From 8af21ee0be2f163c046a189089064e2d81810453 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Feb 2026 12:26:01 +0700 Subject: [PATCH 001/412] Scaffold planner extension with phases, tools, and state machine --- .gitignore | 8 + extensions/.gitkeep | 0 extensions/koan.ts | 96 ++++ package.json | 12 +- src/planner/phases/context-capture.ts | 383 ++++++++++++++ src/planner/phases/dispatch.ts | 62 +++ src/planner/phases/plan-design.ts | 206 ++++++++ src/planner/plan/mutate.ts | 667 +++++++++++++++++++++++++ src/planner/plan/serialize.ts | 45 ++ src/planner/plan/types.ts | 209 ++++++++ src/planner/plan/validate.ts | 133 +++++ src/planner/prompts/context-capture.ts | 91 ++++ src/planner/prompts/plan-design.ts | 218 ++++++++ src/planner/prompts/step.ts | 38 ++ src/planner/qr/mutate.ts | 91 ++++ src/planner/qr/types.ts | 20 + src/planner/session.ts | 196 ++++++++ src/planner/state.ts | 67 +++ src/planner/subagent.ts | 72 +++ src/planner/tools/context-store.ts | 34 ++ src/planner/tools/dispatch.ts | 140 ++++++ src/planner/tools/plan-entities.ts | 599 ++++++++++++++++++++++ src/planner/tools/plan-getters.ts | 167 +++++++ src/planner/tools/plan-setters.ts | 92 ++++ src/planner/tools/qr-tools.ts | 232 +++++++++ src/planner/tools/registry.ts | 190 +++++++ src/planner/types.ts | 21 + src/utils/logger.ts | 14 + src/utils/plan.ts | 72 +++ src/utils/progress.ts | 71 +++ 30 files changed, 4242 insertions(+), 4 deletions(-) delete mode 100644 extensions/.gitkeep create mode 100644 extensions/koan.ts create mode 100644 src/planner/phases/context-capture.ts create mode 100644 src/planner/phases/dispatch.ts create mode 100644 src/planner/phases/plan-design.ts create mode 100644 src/planner/plan/mutate.ts create mode 100644 src/planner/plan/serialize.ts create mode 100644 src/planner/plan/types.ts create mode 100644 src/planner/plan/validate.ts create mode 100644 src/planner/prompts/context-capture.ts create mode 100644 src/planner/prompts/plan-design.ts create mode 100644 src/planner/prompts/step.ts create mode 100644 src/planner/qr/mutate.ts create mode 100644 src/planner/qr/types.ts create mode 100644 src/planner/session.ts create mode 100644 src/planner/state.ts create mode 100644 src/planner/subagent.ts create mode 100644 src/planner/tools/context-store.ts create mode 100644 src/planner/tools/dispatch.ts create mode 100644 src/planner/tools/plan-entities.ts create mode 100644 src/planner/tools/plan-getters.ts create mode 100644 src/planner/tools/plan-setters.ts create mode 100644 src/planner/tools/qr-tools.ts create mode 100644 src/planner/tools/registry.ts create mode 100644 src/planner/types.ts create mode 100644 src/utils/logger.ts create mode 100644 src/utils/plan.ts create mode 100644 src/utils/progress.ts diff --git a/.gitignore b/.gitignore index 4909416..97d66e2 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,11 @@ node_modules/ dist/ .pi/ .DS_Store + +.claude/ +plans/ +.koan/ +*.tsbuildinfo +.env +.env.* +*.log diff --git a/extensions/.gitkeep b/extensions/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/extensions/koan.ts b/extensions/koan.ts new file mode 100644 index 0000000..3fce06c --- /dev/null +++ b/extensions/koan.ts @@ -0,0 +1,96 @@ +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { createSession } from "../src/planner/session.js"; +import { detectSubagentMode, dispatchPhase } from "../src/planner/phases/dispatch.js"; +import { createDispatch, registerWorkflowTools, createPlanRef } from "../src/planner/tools/dispatch.js"; +import { registerPlanGetterTools } from "../src/planner/tools/plan-getters.js"; +import { registerPlanSetterTools } from "../src/planner/tools/plan-setters.js"; +import { registerPlanEntityTools } from "../src/planner/tools/plan-entities.js"; +import { registerQRTools } from "../src/planner/tools/qr-tools.js"; +import { createLogger } from "../src/utils/logger.js"; + +export default function koan(pi: ExtensionAPI): void { + const log = createLogger("Koan"); + + pi.registerFlag("koan-role", { + description: "Koan subagent role (reserved)", + type: "string", + default: "", + }); + + pi.registerFlag("koan-phase", { + description: "Koan workflow phase (reserved)", + type: "string", + default: "", + }); + + pi.registerFlag("koan-plan-dir", { + description: "Koan plan directory path", + type: "string", + default: "", + }); + + pi.registerFlag("koan-subagent-dir", { + description: "Koan subagent working directory", + type: "string", + default: "", + }); + + // Pi snapshots tools during _buildRuntime() at init. All 44 tools + // register here unconditionally. Phases restrict access via tool_call + // blocking at runtime. + const dispatch = createDispatch(); + const planRef = createPlanRef(); + + registerWorkflowTools(pi, dispatch); + registerPlanGetterTools(pi, planRef); + registerPlanSetterTools(pi, planRef); + registerPlanEntityTools(pi, planRef); + registerQRTools(pi, planRef); + + // Subagent detection runs at before_agent_start (flags + // are unavailable during init). + let dispatched = false; + pi.on("before_agent_start", async () => { + if (dispatched) return; + dispatched = true; + const config = detectSubagentMode(pi); + if (config) { + const planDir = pi.getFlag("koan-plan-dir") as string; + if (planDir) { + planRef.dir = planDir; + } + await dispatchPhase(pi, config, dispatch, planRef, log); + } + }); + + // Session: parent-mode workflow engine. + const session = createSession(pi, dispatch, planRef); + + pi.registerCommand("koan", { + description: "Koan planning workflow", + handler: async (args, ctx) => { + const [subcommand, ...rest] = args.trim().split(/\s+/); + const command = subcommand ?? ""; + const remainingArgs = rest.join(" "); + + switch (command) { + case "plan": + await session.plan(remainingArgs, ctx); + break; + case "execute": + await session.execute(ctx); + break; + case "status": + await session.status(ctx); + break; + default: + ctx.ui.notify( + "Usage: /koan plan , /koan execute, or /koan status", + "error", + ); + break; + } + }, + }); +} diff --git a/package.json b/package.json index b2171e2..8781960 100644 --- a/package.json +++ b/package.json @@ -14,8 +14,12 @@ "extensions": ["./extensions"] }, "files": [ - "extensions", - "README.md", - "LICENSE" - ] + "extensions", + "src", + "README.md", + "LICENSE" + ], + "dependencies": { + "@sinclair/typebox": "^0.32.30" + } } diff --git a/src/planner/phases/context-capture.ts b/src/planner/phases/context-capture.ts new file mode 100644 index 0000000..404e69a --- /dev/null +++ b/src/planner/phases/context-capture.ts @@ -0,0 +1,383 @@ +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"; + +import { + draftGuidance, + verifyGuidance, + refineGuidance, + type RefinePromptOptions, +} from "../prompts/context-capture.js"; +import { formatStep } from "../prompts/step.js"; +import type { ContextCaptureState, PlanInfo, WorkflowState } from "../state.js"; +import type { ContextData } from "../types.js"; +import { CONTEXT_KEYS } from "../types.js"; +import type { ContextToolResult } from "../tools/context-store.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch } from "../tools/dispatch.js"; +import { createLogger, type Logger } from "../../utils/logger.js"; +import { checkPermission } from "../tools/registry.js"; + +const MAX_ATTEMPTS = 3; + +interface ValidationResult { + ok: boolean; + data?: ContextData; + errors: string[]; +} + +export class ContextCapturePhase { + private readonly state: WorkflowState; + private readonly pi: ExtensionAPI; + private readonly log: Logger; + private readonly dispatch: WorkflowDispatch; + private readonly onComplete?: (ctx: ExtensionContext) => Promise; + + constructor( + pi: ExtensionAPI, + state: WorkflowState, + dispatch: WorkflowDispatch, + log?: Logger, + onComplete?: (ctx: ExtensionContext) => Promise, + ) { + this.pi = pi; + this.state = state; + this.dispatch = dispatch; + this.log = log ?? createLogger("Context"); + this.onComplete = onComplete; + + this.registerHandlers(); + } + + async begin(taskDescription: string, plan: PlanInfo, ctx: ExtensionContext): Promise { + if (this.state.context?.active) { + ctx.ui.notify("Context capture is already in progress.", "warning"); + return; + } + + const contextFilePath = path.join(plan.directory, "context.json"); + await fs.rm(contextFilePath, { force: true }); + + this.state.phase = "context"; + this.state.context = { + active: true, + subPhase: "drafting", + attempt: 0, + maxAttempts: MAX_ATTEMPTS, + taskDescription, + planId: plan.id, + planDirectory: plan.directory, + contextFilePath, + lastPrompt: null, + feedback: [], + } satisfies ContextCaptureState; + + // Hook dispatch slots here (not constructor) because dispatch is + // shared with plan-design. Each phase hooks when activated (begin() + // for context-capture, begin() for plan-design). hookDispatch throws + // if the slot is already occupied (phase hook ownership prevents + // silent misrouting). + hookDispatch(this.dispatch, "onNextStep", () => this.handleSubPhaseComplete()); + hookDispatch(this.dispatch, "onStoreContext", (p, c) => this.handleContextToolCall(p, c)); + + this.log("Starting context capture (draft phase)", { planId: plan.id }); + ctx.ui.notify(`Koan context capture started for plan ${plan.id}.`, "info"); + + await this.updatePlanMetadata({ + status: "context", + context: { + expectedPath: contextFilePath, + startedAt: new Date().toISOString(), + }, + }); + + const prompt = formatStep(draftGuidance(taskDescription)); + this.state.context.lastPrompt = prompt; + this.pi.sendUserMessage(prompt); + } + + // Advances context capture sub-phase via tool call result. + // The returned prompt becomes the tool result text that the LLM + // processes within the same agent loop -- no sendUserMessage needed. + // Tool result delivery is synchronous regardless of -p mode. + private handleSubPhaseComplete(): { ok: boolean; prompt?: string; error?: string } { + const ctx = this.state.context; + if (!ctx || !this.shouldHandle()) { + return { ok: false, error: "Context capture is not active." }; + } + + if (ctx.subPhase === "drafting") { + ctx.subPhase = "verifying"; + const prompt = formatStep(verifyGuidance()); + ctx.lastPrompt = prompt; + this.log("Draft complete, transition to verify phase (tool call)"); + return { ok: true, prompt }; + } + + if (ctx.subPhase === "verifying") { + ctx.subPhase = "refining"; + ctx.attempt = 1; + const prompt = formatStep( + refineGuidance({ + attempt: 1, + maxAttempts: ctx.maxAttempts, + feedback: [], + }), + ); + ctx.lastPrompt = prompt; + this.log("Verify complete, transition to refine phase (tool call)"); + return { ok: true, prompt }; + } + + // Refine phase: koan_store_context handles completion, not this tool. + return { + ok: false, + error: "Refine phase: use koan_store_context to store the context.", + }; + } + + private registerHandlers(): void { + this.pi.on("tool_call", async (event) => { + if (!this.shouldHandle()) return; + + const perm = checkPermission("context-capture", event.toolName); + if (!perm.allowed) { + return { block: true, reason: perm.reason }; + } + + const ctx = this.state.context!; + + if (ctx.subPhase === "drafting") { + if (event.toolName === "koan_store_context") { + return { + block: true, + reason: "Draft phase: explore and draft first, then call koan_next_step.", + }; + } + return undefined; + } + + if (ctx.subPhase === "verifying") { + if (event.toolName === "koan_next_step") { + return undefined; + } + return { + block: true, + reason: "Verify phase: review your draft, then call koan_next_step. No other tools.", + }; + } + + if (ctx.subPhase === "refining") { + if (event.toolName === "koan_store_context") { + return undefined; + } + return { + block: true, + reason: "Refine phase: call koan_store_context with the verified context.", + }; + } + + return undefined; + }); + + // Safety net: if the LLM ends a turn without calling the expected + // tool, nudge it to try again. The primary transition mechanism is + // tool calls (koan_next_step for sub-phase advancement, + // koan_store_context for completion). This handler only fires when + // the LLM produces a text-only response instead of calling tools. + this.pi.on("agent_end", async (_event, ctx) => { + if (!this.shouldHandle()) return; + const contextState = this.state.context!; + + if (contextState.subPhase === "drafting" || contextState.subPhase === "verifying") { + // LLM ended without calling koan_next_step. + this.log("LLM ended turn without calling koan_next_step", { + subPhase: contextState.subPhase, + }); + this.pi.sendUserMessage( + "You must call koan_next_step when you have finished this step.", + ); + return; + } + + if (contextState.subPhase === "refining") { + // LLM ended without calling koan_store_context. Retry logic. + this.log("Refine phase ended without koan_store_context call", { + attempt: contextState.attempt, + }); + + if (contextState.feedback.length === 0) { + contextState.feedback = [ + "You must call the `koan_store_context` tool with the structured context.", + ]; + } + + const remaining = contextState.maxAttempts - contextState.attempt; + if (remaining > 0) { + contextState.attempt += 1; + ctx.ui.notify("Context capture incomplete. Retrying.", "warning"); + this.sendRefinePrompt(); + return; + } + + contextState.active = false; + this.state.phase = "context-failed"; + // Unhook on both success (handleContextToolCall) and failure + // (agent_end max-attempts). + unhookDispatch(this.dispatch, "onNextStep"); + unhookDispatch(this.dispatch, "onStoreContext"); + await this.updatePlanMetadata({ + status: "context-failed", + context: { + failedAt: new Date().toISOString(), + attempt: contextState.attempt, + }, + }); + ctx.ui.notify("Context capture failed after maximum attempts.", "error"); + } + }); + } + + private sendRefinePrompt(): void { + const ctx = this.state.context!; + const prompt = formatStep( + refineGuidance({ + attempt: ctx.attempt, + maxAttempts: ctx.maxAttempts, + feedback: ctx.feedback, + }), + ); + ctx.lastPrompt = prompt; + this.log("Sending refine prompt", { attempt: ctx.attempt }); + this.pi.sendUserMessage(prompt); + } + + private shouldHandle(): boolean { + return Boolean(this.state.context?.active && this.state.phase === "context"); + } + + private async handleContextToolCall(payload: unknown, ctx: ExtensionContext): Promise { + if (!this.state.context || !this.shouldHandle()) { + return { + ok: false, + message: "Context capture is not active.", + errors: ["Context capture is not active."], + }; + } + + const validation = validateContextData(payload); + + if (!validation.ok || !validation.data) { + const errors = validation.errors.length > 0 ? validation.errors : ["Context validation failed."]; + this.state.context.feedback = errors; + this.log("Context validation failed", { errors }); + return { ok: false, message: formatErrors(errors), errors }; + } + + const rawText = JSON.stringify(payload, null, 2); + try { + await fs.writeFile(this.state.context.contextFilePath, `${rawText}\n`, "utf8"); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to write context file", { error: message }); + return { + ok: false, + message: `Failed to write context.json: ${message}`, + errors: [`Failed to write context.json: ${message}`], + }; + } + + this.state.context.active = false; + this.state.context.data = validation.data; + this.state.context.lastRawContent = rawText; + this.state.context.feedback = []; + this.state.phase = "context-complete"; + // Unhook on both success (handleContextToolCall) and failure + // (agent_end max-attempts). + unhookDispatch(this.dispatch, "onNextStep"); + unhookDispatch(this.dispatch, "onStoreContext"); + + ctx.ui.notify("Koan context capture complete.", "success"); + this.log("Context capture succeeded", { + planId: this.state.context.planId, + attempt: this.state.context.attempt, + }); + + await this.updatePlanMetadata({ + status: "context-complete", + context: { + capturedAt: new Date().toISOString(), + attempt: this.state.context.attempt, + file: this.state.context.contextFilePath, + }, + }); + + // Trigger completion callback (e.g. architect spawn) synchronously + // within the tool call. The tool blocks until the callback resolves, + // preventing the LLM from taking intermediate turns. + if (this.onComplete) { + const message = await this.onComplete(ctx); + return { ok: true, message }; + } + return { ok: true, message: "Context captured successfully." }; + } + + private async updatePlanMetadata(patch: Record): Promise { + const plan = this.state.plan; + if (!plan) return; + + try { + let current: Record = {}; + try { + const existing = await fs.readFile(plan.metadataPath, "utf8"); + current = JSON.parse(existing); + } catch { + current = { id: plan.id, createdAt: plan.createdAt }; + } + + const next = { ...current, ...patch }; + await fs.writeFile(plan.metadataPath, `${JSON.stringify(next, null, 2)}\n`, "utf8"); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to update plan metadata", { error: message }); + } + } +} + +function formatErrors(errors: string[]): string { + return `Context validation failed:\n${errors.map((e) => `- ${e}`).join("\n")}`; +} + +function validateContextData(value: unknown): ValidationResult { + if (typeof value !== "object" || value === null) { + return { ok: false, errors: ["Context data must be a JSON object."] }; + } + + const data = value as Record; + const errors: string[] = []; + const result: Record = {}; + + for (const key of CONTEXT_KEYS) { + const field = data[key]; + if (!Array.isArray(field)) { + errors.push(`${key} must be an array of strings.`); + continue; + } + if (field.length === 0) { + errors.push(`${key} must not be empty.`); + continue; + } + const bad = field.findIndex((item) => typeof item !== "string" || item.trim().length === 0); + if (bad !== -1) { + errors.push(`${key}[${bad}] must be a non-empty string.`); + continue; + } + result[key] = field.map((s: string) => s.trim()); + } + + if (errors.length > 0) { + return { ok: false, errors }; + } + + return { ok: true, data: result as unknown as ContextData, errors: [] }; +} diff --git a/src/planner/phases/dispatch.ts b/src/planner/phases/dispatch.ts new file mode 100644 index 0000000..ce72f8a --- /dev/null +++ b/src/planner/phases/dispatch.ts @@ -0,0 +1,62 @@ +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { PlanDesignPhase } from "./plan-design.js"; +import { createLogger, type Logger } from "../../utils/logger.js"; +import type { WorkflowDispatch, PlanRef } from "../tools/dispatch.js"; + +export interface SubagentConfig { + role: string; + phase: string; + planDir: string; + subagentDir: string; +} + +// Detects subagent mode by checking flags set via CLI (pi -p --koan-role +// architect --koan-phase plan-design ...). Flags are unavailable during +// init (getFlag() returns undefined before _buildRuntime()), so this +// must be called from before_agent_start or later. +export function detectSubagentMode(pi: ExtensionAPI): SubagentConfig | null { + const role = pi.getFlag("koan-role"); + if (!role || typeof role !== "string" || role.trim().length === 0) { + return null; + } + + const phase = pi.getFlag("koan-phase"); + const planDir = pi.getFlag("koan-plan-dir"); + const subagentDir = pi.getFlag("koan-subagent-dir"); + + return { + role: role.trim(), + phase: typeof phase === "string" ? phase.trim() : "", + planDir: typeof planDir === "string" ? planDir.trim() : "", + subagentDir: typeof subagentDir === "string" ? subagentDir.trim() : "", + }; +} + +export async function dispatchPhase( + pi: ExtensionAPI, + config: SubagentConfig, + dispatch: WorkflowDispatch, + planRef: PlanRef, + log?: Logger, +): Promise { + const logger = log ?? createLogger("Dispatch"); + + if (config.role === "architect" && config.phase === "plan-design") { + logger("Dispatching to plan-design workflow", { planDir: config.planDir }); + const phase = new PlanDesignPhase( + pi, + { + planDir: config.planDir, + subagentDir: config.subagentDir || undefined, + }, + dispatch, + planRef, + logger, + ); + await phase.begin(); + return; + } + + logger("Unknown role/phase combination", { role: config.role, phase: config.phase }); +} diff --git a/src/planner/phases/plan-design.ts b/src/planner/phases/plan-design.ts new file mode 100644 index 0000000..4e90d39 --- /dev/null +++ b/src/planner/phases/plan-design.ts @@ -0,0 +1,206 @@ +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { validatePlanDesign, validateRefs } from "../plan/validate.js"; +import { + loadPlanDesignSystemPrompt, + formatContextForStep1, + buildPlanDesignSystemPrompt, + planDesignStepGuidance, + STEP_NAMES, +} from "../prompts/plan-design.js"; +import { formatStep } from "../prompts/step.js"; +import type { ContextData } from "../types.js"; +import { createLogger, type Logger } from "../../utils/logger.js"; +import { ProgressReporter } from "../../utils/progress.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../tools/dispatch.js"; +import { checkPermission, PLAN_GETTER_TOOLS } from "../tools/registry.js"; + +type PlanDesignStep = 1 | 2 | 3 | 4 | 5 | 6; + +interface PlanDesignState { + active: boolean; + step: PlanDesignStep; + step1Prompt: string | null; + contextData: ContextData | null; + systemPrompt: string | null; +} + +export class PlanDesignPhase { + private readonly pi: ExtensionAPI; + private readonly planDir: string; + private readonly log: Logger; + private readonly state: PlanDesignState; + private readonly progress: ProgressReporter | null; + private readonly dispatch: WorkflowDispatch; + private readonly planRef: PlanRef; + + constructor(pi: ExtensionAPI, config: { planDir: string; subagentDir?: string }, dispatch: WorkflowDispatch, planRef: PlanRef, log?: Logger) { + this.pi = pi; + this.planDir = config.planDir; + this.dispatch = dispatch; + this.planRef = planRef; + this.log = log ?? createLogger("PlanDesign"); + this.progress = config.subagentDir + ? new ProgressReporter(config.subagentDir, "architect", "plan-design") + : null; + + this.state = { + active: false, + step: 1, + step1Prompt: null, + contextData: null, + systemPrompt: null, + }; + + this.registerHandlers(); + } + + async begin(): Promise { + const contextPath = path.join(this.planDir, "context.json"); + try { + const raw = await fs.readFile(contextPath, "utf8"); + this.state.contextData = JSON.parse(raw) as ContextData; + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to read context.json", { error: message }); + return; + } + + let basePrompt: string; + try { + basePrompt = await loadPlanDesignSystemPrompt(); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to load plan-design system prompt", { error: message }); + return; + } + + const contextXml = formatContextForStep1(this.state.contextData); + this.state.systemPrompt = buildPlanDesignSystemPrompt(basePrompt); + this.state.step1Prompt = formatStep(planDesignStepGuidance(1, contextXml)); + this.state.active = true; + this.state.step = 1; + + // No koan_store_plan tool. Each mutation writes to disk immediately. + // Step 6 ends with koan_next_step, which runs validation. Removes + // the two-step 'build then finalize' pattern that caused LLM to skip + // intermediate tools. + hookDispatch(this.dispatch, "onNextStep", () => this.handleStepComplete()); + + this.log("Starting plan-design workflow", { step: 1 }); + await this.progress?.update(`Step 1/6: ${STEP_NAMES[1]} -- started`); + } + + private registerHandlers(): void { + this.pi.on("before_agent_start", () => { + if (!this.state.active || !this.state.systemPrompt) return undefined; + return { systemPrompt: this.state.systemPrompt }; + }); + + // Step 1 prompt injection. The CLI message is a process trigger -- + // the context event fires before each LLM call and replaces the + // user message with the actual step 1 instructions. Messages are + // structuredCloned before reaching this handler (runner.ts:660), + // so stored history is unaffected. Handler is a no-op once the + // step advances past 1. + // + // Why context event instead of sendUserMessage? Step 1 has no + // preceding tool call (no tool result to inject prompt into). + // Context event injects the prompt before the initial LLM call. + // pi structuredClones messages, so modifications here are isolated. + this.pi.on("context", (event) => { + if (!this.state.active) return undefined; + if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; + + const messages = event.messages.map((m) => { + if (m.role === "user") { + return { ...m, content: this.state.step1Prompt! }; + } + return m; + }); + return { messages }; + }); + + this.pi.on("tool_call", (event) => { + if (!this.state.active) return undefined; + + const perm = checkPermission("plan-design", event.toolName); + if (!perm.allowed) { + return { block: true, reason: perm.reason }; + } + + const step = this.state.step; + if (step < 6 && !PLAN_GETTER_TOOLS.has(event.toolName) && event.toolName !== "koan_next_step") { + return { + block: true, + reason: `${event.toolName} available in step 6 (current: ${step})`, + }; + } + + return undefined; + }); + + this.pi.on("turn_end", (event) => { + if (!this.state.active) return; + }); + } + + private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { + const prev = this.state.step; + + if (prev === 6) { + const result = await this.handleFinalize(); + if (!result.ok) { + return { ok: false, error: result.errors?.join("; ") }; + } + this.state.active = false; + unhookDispatch(this.dispatch, "onNextStep"); + this.log("Plan finalized, workflow complete"); + return { ok: true, prompt: "Plan validation passed. Workflow complete." }; + } + + this.state.step = (prev + 1) as PlanDesignStep; + const nextName = STEP_NAMES[this.state.step]; + const prompt = formatStep(planDesignStepGuidance(this.state.step)); + + this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName }); + + this.progress?.update(`Step ${prev}/6: ${STEP_NAMES[prev]} -- complete`); + this.progress?.update(`Step ${this.state.step}/6: ${nextName} -- started`); + + return { ok: true, prompt }; + } + + private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { + const planPath = path.join(this.planDir, "plan.json"); + let plan; + try { + const raw = await fs.readFile(planPath, "utf8"); + plan = JSON.parse(raw); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to read plan.json for validation", { error: message }); + return { ok: false, errors: [`Failed to read plan.json: ${message}`] }; + } + + const designValidation = validatePlanDesign(plan); + if (!designValidation.ok) { + this.log("Plan design validation failed", { errors: designValidation.errors }); + return { ok: false, errors: designValidation.errors }; + } + + const refValidation = validateRefs(plan); + if (!refValidation.ok) { + this.log("Plan reference validation failed", { errors: refValidation.errors }); + return { ok: false, errors: refValidation.errors }; + } + + this.log("Plan validation passed", { path: planPath }); + await this.progress?.update("Step 6/6: " + STEP_NAMES[6] + " -- complete"); + await this.progress?.complete("completed"); + return { ok: true }; + } +} diff --git a/src/planner/plan/mutate.ts b/src/planner/plan/mutate.ts new file mode 100644 index 0000000..666af63 --- /dev/null +++ b/src/planner/plan/mutate.ts @@ -0,0 +1,667 @@ +// Monotonic version counter on entities. No CAS enforcement -- single-writer +// per phase. Counter is for debugging and audit trail, not concurrency control. + +import type { + Plan, + Decision, + RejectedAlternative, + Risk, + Milestone, + CodeIntent, + CodeChange, + Wave, + DiagramGraph, + DiagramNode, + DiagramEdge, + ReadmeEntry, + Overview, + InvisibleKnowledge, +} from "./types.js"; +import { + nextDecisionId, + nextMilestoneId, + nextIntentId, + nextRiskId, + nextRejectedAltId, + nextWaveId, + nextDiagramId, + nextChangeId, +} from "./types.js"; + +// -- Top-level -- + +export function setOverview( + p: Plan, + data: { problem?: string; approach?: string }, +): Plan { + const overview: Overview = { + problem: data.problem ?? p.overview.problem, + approach: data.approach ?? p.overview.approach, + }; + return { ...p, overview }; +} + +export function setConstraints(p: Plan, constraints: string[]): Plan { + return { + ...p, + planning_context: { + ...p.planning_context, + constraints, + }, + }; +} + +export function setInvisibleKnowledge( + p: Plan, + data: { system?: string; invariants?: string[]; tradeoffs?: string[] }, +): Plan { + const ik: InvisibleKnowledge = { + system: data.system ?? p.invisible_knowledge.system, + invariants: data.invariants ?? p.invisible_knowledge.invariants, + tradeoffs: data.tradeoffs ?? p.invisible_knowledge.tradeoffs, + }; + return { ...p, invisible_knowledge: ik }; +} + +// -- Decision -- + +export function addDecision( + p: Plan, + data: { decision: string; reasoning: string }, +): { plan: Plan; id: string } { + const id = nextDecisionId(p); + const decision: Decision = { + id, + version: 1, + decision: data.decision, + reasoning_chain: data.reasoning, + }; + return { + plan: { + ...p, + planning_context: { + ...p.planning_context, + decision_log: [...p.planning_context.decision_log, decision], + }, + }, + id, + }; +} + +export function setDecision( + p: Plan, + id: string, + data: { decision?: string; reasoning?: string }, +): Plan { + const idx = p.planning_context.decision_log.findIndex((d) => d.id === id); + if (idx === -1) throw new Error(`decision ${id} not found`); + + const d = p.planning_context.decision_log[idx]; + const updated: Decision = { + ...d, + version: d.version + 1, + decision: data.decision ?? d.decision, + reasoning_chain: data.reasoning ?? d.reasoning_chain, + }; + + const log = [...p.planning_context.decision_log]; + log[idx] = updated; + + return { + ...p, + planning_context: { ...p.planning_context, decision_log: log }, + }; +} + +// -- RejectedAlternative -- + +export function addRejectedAlternative( + p: Plan, + data: { alternative: string; rejection_reason: string; decision_ref: string }, +): { plan: Plan; id: string } { + const id = nextRejectedAltId(p); + const ra: RejectedAlternative = { + id, + alternative: data.alternative, + rejection_reason: data.rejection_reason, + decision_ref: data.decision_ref, + }; + return { + plan: { + ...p, + planning_context: { + ...p.planning_context, + rejected_alternatives: [ + ...p.planning_context.rejected_alternatives, + ra, + ], + }, + }, + id, + }; +} + +export function setRejectedAlternative( + p: Plan, + id: string, + data: { + alternative?: string; + rejection_reason?: string; + decision_ref?: string; + }, +): Plan { + const idx = p.planning_context.rejected_alternatives.findIndex( + (r) => r.id === id, + ); + if (idx === -1) throw new Error(`rejected_alternative ${id} not found`); + + const r = p.planning_context.rejected_alternatives[idx]; + const updated: RejectedAlternative = { + ...r, + alternative: data.alternative ?? r.alternative, + rejection_reason: data.rejection_reason ?? r.rejection_reason, + decision_ref: data.decision_ref ?? r.decision_ref, + }; + + const list = [...p.planning_context.rejected_alternatives]; + list[idx] = updated; + + return { + ...p, + planning_context: { ...p.planning_context, rejected_alternatives: list }, + }; +} + +// -- Risk -- + +export function addRisk( + p: Plan, + data: { + risk: string; + mitigation: string; + anchor?: string; + decision_ref?: string; + }, +): { plan: Plan; id: string } { + const id = nextRiskId(p); + const risk: Risk = { + id, + risk: data.risk, + mitigation: data.mitigation, + anchor: data.anchor ?? null, + decision_ref: data.decision_ref ?? null, + }; + return { + plan: { + ...p, + planning_context: { + ...p.planning_context, + known_risks: [...p.planning_context.known_risks, risk], + }, + }, + id, + }; +} + +export function setRisk( + p: Plan, + id: string, + data: { + risk?: string; + mitigation?: string; + anchor?: string; + decision_ref?: string; + }, +): Plan { + const idx = p.planning_context.known_risks.findIndex((r) => r.id === id); + if (idx === -1) throw new Error(`risk ${id} not found`); + + const r = p.planning_context.known_risks[idx]; + const updated: Risk = { + ...r, + risk: data.risk ?? r.risk, + mitigation: data.mitigation ?? r.mitigation, + anchor: data.anchor ?? r.anchor, + decision_ref: data.decision_ref ?? r.decision_ref, + }; + + const list = [...p.planning_context.known_risks]; + list[idx] = updated; + + return { + ...p, + planning_context: { ...p.planning_context, known_risks: list }, + }; +} + +// -- Milestone -- + +export function addMilestone( + p: Plan, + data: { + name: string; + files?: string[]; + flags?: string[]; + requirements?: string[]; + acceptance_criteria?: string[]; + tests?: string[]; + }, +): { plan: Plan; id: string } { + const id = nextMilestoneId(p); + const milestone: Milestone = { + id, + version: 1, + number: p.milestones.length + 1, + name: data.name, + files: data.files ?? [], + flags: data.flags ?? [], + requirements: data.requirements ?? [], + acceptance_criteria: data.acceptance_criteria ?? [], + tests: data.tests ?? [], + code_intents: [], + code_changes: [], + documentation: { + module_comment: null, + docstrings: [], + function_blocks: [], + inline_comments: [], + }, + is_documentation_only: false, + delegated_to: null, + }; + return { + plan: { + ...p, + milestones: [...p.milestones, milestone], + }, + id, + }; +} + +function updateMilestone( + p: Plan, + id: string, + fn: (m: Milestone) => Milestone, +): Plan { + const idx = p.milestones.findIndex((m) => m.id === id); + if (idx === -1) throw new Error(`milestone ${id} not found`); + + const updated = [...p.milestones]; + updated[idx] = fn(p.milestones[idx]); + return { ...p, milestones: updated }; +} + +export function setMilestoneName(p: Plan, id: string, name: string): Plan { + return updateMilestone(p, id, (m) => ({ ...m, version: m.version + 1, name })); +} + +export function setMilestoneFiles(p: Plan, id: string, files: string[]): Plan { + return updateMilestone(p, id, (m) => ({ + ...m, + version: m.version + 1, + files, + })); +} + +export function setMilestoneFlags(p: Plan, id: string, flags: string[]): Plan { + return updateMilestone(p, id, (m) => ({ + ...m, + version: m.version + 1, + flags, + })); +} + +export function setMilestoneRequirements( + p: Plan, + id: string, + requirements: string[], +): Plan { + return updateMilestone(p, id, (m) => ({ + ...m, + version: m.version + 1, + requirements, + })); +} + +export function setMilestoneAcceptanceCriteria( + p: Plan, + id: string, + criteria: string[], +): Plan { + return updateMilestone(p, id, (m) => ({ + ...m, + version: m.version + 1, + acceptance_criteria: criteria, + })); +} + +export function setMilestoneTests(p: Plan, id: string, tests: string[]): Plan { + return updateMilestone(p, id, (m) => ({ + ...m, + version: m.version + 1, + tests, + })); +} + +// -- CodeIntent -- + +export function addIntent( + p: Plan, + data: { + milestone: string; + file: string; + function?: string; + behavior: string; + decision_refs?: string[]; + }, +): { plan: Plan; id: string } { + const idx = p.milestones.findIndex((m) => m.id === data.milestone); + if (idx === -1) throw new Error(`milestone ${data.milestone} not found`); + + const m = p.milestones[idx]; + const id = nextIntentId(m); + const intent: CodeIntent = { + id, + version: 1, + file: data.file, + function: data.function ?? null, + behavior: data.behavior, + decision_refs: data.decision_refs ?? [], + }; + + const updated = [...p.milestones]; + updated[idx] = { + ...m, + code_intents: [...m.code_intents, intent], + }; + + return { + plan: { ...p, milestones: updated }, + id, + }; +} + +export function setIntent( + p: Plan, + id: string, + data: { + file?: string; + function?: string; + behavior?: string; + decision_refs?: string[]; + }, +): Plan { + for (let i = 0; i < p.milestones.length; i++) { + const m = p.milestones[i]; + const ciIdx = m.code_intents.findIndex((ci) => ci.id === id); + if (ciIdx !== -1) { + const ci = m.code_intents[ciIdx]; + const updated: CodeIntent = { + ...ci, + version: ci.version + 1, + file: data.file ?? ci.file, + function: data.function ?? ci.function, + behavior: data.behavior ?? ci.behavior, + decision_refs: data.decision_refs ?? ci.decision_refs, + }; + + const intents = [...m.code_intents]; + intents[ciIdx] = updated; + + const milestones = [...p.milestones]; + milestones[i] = { ...m, code_intents: intents }; + + return { ...p, milestones }; + } + } + throw new Error(`intent ${id} not found`); +} + +// -- CodeChange -- + +export function addChange( + p: Plan, + data: { + milestone: string; + file: string; + intent_ref?: string; + diff?: string; + doc_diff?: string; + comments?: string; + }, +): { plan: Plan; id: string } { + const idx = p.milestones.findIndex((m) => m.id === data.milestone); + if (idx === -1) throw new Error(`milestone ${data.milestone} not found`); + + const m = p.milestones[idx]; + const id = nextChangeId(m); + const change: CodeChange = { + id, + version: 1, + intent_ref: data.intent_ref ?? null, + file: data.file, + diff: data.diff ?? "", + doc_diff: data.doc_diff ?? "", + comments: data.comments ?? "", + }; + + const updated = [...p.milestones]; + updated[idx] = { + ...m, + code_changes: [...m.code_changes, change], + }; + + return { + plan: { ...p, milestones: updated }, + id, + }; +} + +function updateChange( + p: Plan, + id: string, + fn: (c: CodeChange) => CodeChange, +): Plan { + for (let i = 0; i < p.milestones.length; i++) { + const m = p.milestones[i]; + const ccIdx = m.code_changes.findIndex((cc) => cc.id === id); + if (ccIdx !== -1) { + const changes = [...m.code_changes]; + changes[ccIdx] = fn(m.code_changes[ccIdx]); + + const milestones = [...p.milestones]; + milestones[i] = { ...m, code_changes: changes }; + + return { ...p, milestones }; + } + } + throw new Error(`code_change ${id} not found`); +} + +export function setChangeDiff(p: Plan, id: string, diff: string): Plan { + return updateChange(p, id, (c) => ({ ...c, version: c.version + 1, diff })); +} + +export function setChangeDocDiff(p: Plan, id: string, doc_diff: string): Plan { + return updateChange(p, id, (c) => ({ + ...c, + version: c.version + 1, + doc_diff, + })); +} + +export function setChangeComments(p: Plan, id: string, comments: string): Plan { + return updateChange(p, id, (c) => ({ + ...c, + version: c.version + 1, + comments, + })); +} + +export function setChangeFile(p: Plan, id: string, file: string): Plan { + return updateChange(p, id, (c) => ({ ...c, version: c.version + 1, file })); +} + +export function setChangeIntentRef( + p: Plan, + id: string, + intent_ref: string, +): Plan { + return updateChange(p, id, (c) => ({ + ...c, + version: c.version + 1, + intent_ref, + })); +} + +// -- Wave -- + +export function addWave( + p: Plan, + data: { milestones: string[] }, +): { plan: Plan; id: string } { + const id = nextWaveId(p); + const wave: Wave = { + id, + milestones: data.milestones, + }; + return { + plan: { + ...p, + waves: [...p.waves, wave], + }, + id, + }; +} + +export function setWaveMilestones( + p: Plan, + id: string, + milestones: string[], +): Plan { + const idx = p.waves.findIndex((w) => w.id === id); + if (idx === -1) throw new Error(`wave ${id} not found`); + + const updated = [...p.waves]; + updated[idx] = { ...p.waves[idx], milestones }; + + return { ...p, waves: updated }; +} + +// -- Diagram -- + +export function addDiagram( + p: Plan, + data: { + type: "architecture" | "state" | "sequence" | "dataflow"; + scope: string; + title: string; + }, +): { plan: Plan; id: string } { + const id = nextDiagramId(p); + const diagram: DiagramGraph = { + id, + type: data.type, + scope: data.scope, + title: data.title, + nodes: [], + edges: [], + ascii_render: null, + }; + return { + plan: { + ...p, + diagram_graphs: [...p.diagram_graphs, diagram], + }, + id, + }; +} + +export function setDiagram( + p: Plan, + id: string, + data: { title?: string; scope?: string; ascii_render?: string }, +): Plan { + const idx = p.diagram_graphs.findIndex((d) => d.id === id); + if (idx === -1) throw new Error(`diagram ${id} not found`); + + const d = p.diagram_graphs[idx]; + const updated: DiagramGraph = { + ...d, + title: data.title ?? d.title, + scope: data.scope ?? d.scope, + ascii_render: data.ascii_render ?? d.ascii_render, + }; + + const diagrams = [...p.diagram_graphs]; + diagrams[idx] = updated; + + return { ...p, diagram_graphs: diagrams }; +} + +export function addDiagramNode( + p: Plan, + diagramId: string, + data: { id: string; label: string; type?: string }, +): Plan { + const idx = p.diagram_graphs.findIndex((d) => d.id === diagramId); + if (idx === -1) throw new Error(`diagram ${diagramId} not found`); + + const d = p.diagram_graphs[idx]; + const node: DiagramNode = { + id: data.id, + label: data.label, + type: data.type ?? null, + }; + + const diagrams = [...p.diagram_graphs]; + diagrams[idx] = { + ...d, + nodes: [...d.nodes, node], + }; + + return { ...p, diagram_graphs: diagrams }; +} + +export function addDiagramEdge( + p: Plan, + diagramId: string, + data: { source: string; target: string; label: string; protocol?: string }, +): Plan { + const idx = p.diagram_graphs.findIndex((d) => d.id === diagramId); + if (idx === -1) throw new Error(`diagram ${diagramId} not found`); + + const d = p.diagram_graphs[idx]; + const edge: DiagramEdge = { + source: data.source, + target: data.target, + label: data.label, + protocol: data.protocol ?? null, + }; + + const diagrams = [...p.diagram_graphs]; + diagrams[idx] = { + ...d, + edges: [...d.edges, edge], + }; + + return { ...p, diagram_graphs: diagrams }; +} + +// -- ReadmeEntry -- + +export function setReadmeEntry(p: Plan, path: string, content: string): Plan { + const idx = p.readme_entries.findIndex((r) => r.path === path); + const entry: ReadmeEntry = { path, content }; + + if (idx === -1) { + return { + ...p, + readme_entries: [...p.readme_entries, entry], + }; + } + + const entries = [...p.readme_entries]; + entries[idx] = entry; + return { ...p, readme_entries: entries }; +} diff --git a/src/planner/plan/serialize.ts b/src/planner/plan/serialize.ts new file mode 100644 index 0000000..9256709 --- /dev/null +++ b/src/planner/plan/serialize.ts @@ -0,0 +1,45 @@ +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { Plan } from "./types.js"; +import { createEmptyPlan } from "./types.js"; + +export function serializePlan(p: Plan): string { + return `${JSON.stringify(p, null, 2)}\n`; +} + +export async function writePlan(p: Plan, filePath: string): Promise { + const dir = path.dirname(filePath); + try { + await fs.access(dir); + } catch { + throw new Error(`Plan directory does not exist: ${dir}`); + } + + const content = serializePlan(p); + await fs.writeFile(filePath, content, "utf8"); +} + +// Atomic write: tmp file + rename. Prevents corrupted plan.json if +// process crashes mid-write. +export async function savePlan(p: Plan, dir: string): Promise { + const planPath = path.join(dir, "plan.json"); + const tmpPath = path.join(dir, ".plan.json.tmp"); + const content = serializePlan(p); + await fs.writeFile(tmpPath, content, "utf8"); + await fs.rename(tmpPath, planPath); +} + +export async function loadPlan(dir: string): Promise { + const planPath = path.join(dir, "plan.json"); + try { + const content = await fs.readFile(planPath, "utf8"); + return JSON.parse(content) as Plan; + } catch (err: unknown) { + if ((err as NodeJS.ErrnoException).code === "ENOENT") { + const planId = path.basename(dir); + return createEmptyPlan(planId); + } + throw err; + } +} diff --git a/src/planner/plan/types.ts b/src/planner/plan/types.ts new file mode 100644 index 0000000..6a4d943 --- /dev/null +++ b/src/planner/plan/types.ts @@ -0,0 +1,209 @@ +export interface Decision { + id: string; + version: number; + decision: string; + reasoning_chain: string; +} + +export interface RejectedAlternative { + id: string; + alternative: string; + rejection_reason: string; + decision_ref: string; +} + +export interface Risk { + id: string; + risk: string; + mitigation: string; + anchor?: string | null; + decision_ref?: string | null; +} + +export interface PlanningContext { + decision_log: Decision[]; + rejected_alternatives: RejectedAlternative[]; + constraints: string[]; + known_risks: Risk[]; +} + +export interface InvisibleKnowledge { + system: string; + invariants: string[]; + tradeoffs: string[]; +} + +export interface Overview { + problem: string; + approach: string; +} + +export interface CodeIntent { + id: string; + version: number; + file: string; + function?: string | null; + behavior: string; + decision_refs: string[]; +} + +export interface CodeChange { + id: string; + version: number; + intent_ref: string | null; + file: string; + diff: string; + doc_diff: string; + comments: string; +} + +export interface Docstring { + function: string; + docstring: string; +} + +export interface FunctionBlock { + function: string; + comment: string; + decision_ref: string | null; + source: string | null; +} + +export interface InlineComment { + location: string; + comment: string; + decision_ref: string | null; + source: string | null; +} + +// DEPRECATED per reference schema. Kept for backwards compatibility with +// Python-based planner plans. New plans use CodeChange.doc_diff. +export interface Documentation { + module_comment: string | null; + docstrings: Docstring[]; + function_blocks: FunctionBlock[]; + inline_comments: InlineComment[]; +} + +// DEPRECATED per reference schema. Kept for backwards compatibility with +// Python-based planner plans. New plans use CodeChange.doc_diff. +export interface ReadmeEntry { + path: string; + content: string; +} + +export interface DiagramNode { + id: string; + label: string; + type: string | null; +} + +export interface DiagramEdge { + source: string; + target: string; + label: string; + protocol: string | null; +} + +export interface DiagramGraph { + id: string; + type: "architecture" | "state" | "sequence" | "dataflow"; + scope: string; + title: string; + nodes: DiagramNode[]; + edges: DiagramEdge[]; + ascii_render: string | null; +} + +export interface Milestone { + id: string; + version: number; + number: number; + name: string; + files: string[]; + flags: string[]; + requirements: string[]; + acceptance_criteria: string[]; + tests: string[]; + code_intents: CodeIntent[]; + code_changes: CodeChange[]; + documentation: Documentation; + is_documentation_only: boolean; + delegated_to: string | null; +} + +export interface Wave { + id: string; + milestones: string[]; +} + +export interface Plan { + plan_id: string; + created_at: string; + frozen_at: string | null; + overview: Overview; + planning_context: PlanningContext; + invisible_knowledge: InvisibleKnowledge; + milestones: Milestone[]; + waves: Wave[]; + diagram_graphs: DiagramGraph[]; + readme_entries: ReadmeEntry[]; +} + +export function createEmptyPlan(planId: string): Plan { + return { + plan_id: planId, + created_at: new Date().toISOString(), + frozen_at: null, + overview: { problem: "", approach: "" }, + planning_context: { + decision_log: [], + rejected_alternatives: [], + constraints: [], + known_risks: [], + }, + invisible_knowledge: { system: "", invariants: [], tradeoffs: [] }, + milestones: [], + waves: [], + diagram_graphs: [], + readme_entries: [], + }; +} + +function pad3(n: number): string { + return String(n).padStart(3, "0"); +} + +export function nextDecisionId(p: Plan): string { + return `DL-${pad3(p.planning_context.decision_log.length + 1)}`; +} + +export function nextMilestoneId(p: Plan): string { + return `M-${pad3(p.milestones.length + 1)}`; +} + +export function nextIntentId(m: Milestone): string { + const num = m.code_intents.length + 1; + return `CI-${m.id}-${pad3(num)}`; +} + +export function nextRiskId(p: Plan): string { + return `R-${pad3(p.planning_context.known_risks.length + 1)}`; +} + +export function nextRejectedAltId(p: Plan): string { + return `RA-${pad3(p.planning_context.rejected_alternatives.length + 1)}`; +} + +export function nextWaveId(p: Plan): string { + return `W-${pad3(p.waves.length + 1)}`; +} + +export function nextDiagramId(p: Plan): string { + return `DIAG-${pad3(p.diagram_graphs.length + 1)}`; +} + +export function nextChangeId(m: Milestone): string { + const num = m.code_changes.length + 1; + return `CC-${m.id}-${pad3(num)}`; +} diff --git a/src/planner/plan/validate.ts b/src/planner/plan/validate.ts new file mode 100644 index 0000000..cc9fe8d --- /dev/null +++ b/src/planner/plan/validate.ts @@ -0,0 +1,133 @@ +import type { Plan } from "./types.js"; + +export interface ValidationResult { + ok: boolean; + errors: string[]; +} + +export function validatePlanDesign(p: Plan): ValidationResult { + const errors: string[] = []; + + if (p.overview.problem.trim().length === 0) { + errors.push("overview.problem must not be empty"); + } + + if (p.milestones.length === 0) { + errors.push("plan must have at least one milestone"); + } + + for (const m of p.milestones) { + if (m.code_intents.length === 0) { + errors.push(`milestone ${m.id} must have at least one code_intent`); + } + } + + return { ok: errors.length === 0, errors }; +} + +export function validateRefs(p: Plan): ValidationResult { + const errors: string[] = []; + const decisionIds = new Set(p.planning_context.decision_log.map((d) => d.id)); + const milestoneIds = new Set(p.milestones.map((m) => m.id)); + + for (const m of p.milestones) { + const intentIds = new Set(m.code_intents.map((ci) => ci.id)); + + for (const ci of m.code_intents) { + for (const ref of ci.decision_refs) { + if (!decisionIds.has(ref)) { + errors.push(`${ci.id}.decision_refs '${ref}' not in decisions`); + } + } + } + + for (const cc of m.code_changes) { + if (cc.intent_ref && !intentIds.has(cc.intent_ref)) { + errors.push( + `${cc.id}.intent_ref '${cc.intent_ref}' not in milestone ${m.id} intents`, + ); + } + } + } + + for (const ra of p.planning_context.rejected_alternatives) { + if (!decisionIds.has(ra.decision_ref)) { + errors.push( + `rejected_alternative ${ra.id}.decision_ref '${ra.decision_ref}' not in decisions`, + ); + } + } + + for (const risk of p.planning_context.known_risks) { + if (risk.decision_ref && !decisionIds.has(risk.decision_ref)) { + errors.push(`risk ${risk.id}.decision_ref '${risk.decision_ref}' not in decisions`); + } + } + + // Milestone references in DiagramGraph.scope are validated against + // plan.milestones for referential integrity. Prevents orphaned diagrams + // when milestones are merged or deleted. + for (const diag of p.diagram_graphs) { + if (diag.scope.startsWith("milestone:")) { + const milestoneId = diag.scope.substring("milestone:".length); + if (!milestoneIds.has(milestoneId)) { + errors.push( + `diagram ${diag.id}.scope '${diag.scope}' references unknown milestone`, + ); + } + } + + const nodeIds = new Set(diag.nodes.map((n) => n.id)); + for (const edge of diag.edges) { + if (!nodeIds.has(edge.source)) { + errors.push(`diagram ${diag.id} edge source '${edge.source}' not in nodes`); + } + if (!nodeIds.has(edge.target)) { + errors.push(`diagram ${diag.id} edge target '${edge.target}' not in nodes`); + } + } + } + + return { ok: errors.length === 0, errors }; +} + +export function validateDiagramScope(scope: string): ValidationResult { + const errors: string[] = []; + if ( + scope !== "overview" && + scope !== "invisible_knowledge" && + !scope.startsWith("milestone:") + ) { + errors.push( + `diagram scope must be 'overview', 'invisible_knowledge', or 'milestone:M-XXX', got '${scope}'`, + ); + } + return { ok: errors.length === 0, errors }; +} + +export function validatePlanCode(p: Plan): ValidationResult { + const errors: string[] = []; + for (const m of p.milestones) { + const changeIntents = new Set( + m.code_changes.map((cc) => cc.intent_ref).filter((r) => r !== null), + ); + for (const ci of m.code_intents) { + if (!changeIntents.has(ci.id)) { + errors.push(`milestone ${m.id} intent ${ci.id} has no corresponding code_change`); + } + } + } + return { ok: errors.length === 0, errors }; +} + +export function validatePlanDocs(p: Plan): ValidationResult { + const errors: string[] = []; + for (const m of p.milestones) { + for (const cc of m.code_changes) { + if (cc.diff.trim().length > 0 && cc.doc_diff.trim().length === 0) { + errors.push(`milestone ${m.id} change ${cc.id} has diff but no doc_diff`); + } + } + } + return { ok: errors.length === 0, errors }; +} diff --git a/src/planner/prompts/context-capture.ts b/src/planner/prompts/context-capture.ts new file mode 100644 index 0000000..9657e85 --- /dev/null +++ b/src/planner/prompts/context-capture.ts @@ -0,0 +1,91 @@ +import type { StepGuidance } from "./step.js"; + +export function draftGuidance(taskDescription: string): StepGuidance { + return { + title: "Context Capture: Draft", + instructions: [ + "You are about to begin a structured planning workflow. Before any formalization, think carefully through the full context of this task.", + "", + `Task: ${taskDescription}`, + "", + "Your primary source is the conversation so far. Most of what you need is already here.", + "", + "You MAY use tools during this phase if -- and only if -- a specific lookup would", + "resolve genuine uncertainty that materially affects planning. Examples of justified reads:", + "- Confirming an API signature you are unsure about", + "- Checking whether a file or module actually exists", + "- Reading a config that determines a key constraint", + "", + "Do NOT explore speculatively. If you can draft a confident answer from context alone, do so.", + "", + "Think through each of these dimensions:", + "", + "- What exactly is being asked? What is the user's goal? What is in scope and what is explicitly not?", + "- What technical constraints apply to the task itself -- API contracts, performance targets, compatibility requirements, architectural rules? Only include constraints that are specific to this task. Do not include general tool usage instructions, coding style guides, or editor/IDE conventions.", + "- Which files, modules, or entry points in the codebase are relevant? If this is greenfield work with no existing code, say so.", + "- Were any alternative approaches discussed and rejected during this session? Why?", + "- What is your current understanding of the system or domain involved?", + "- What assumptions are you making that haven't been verified? How confident are you in each?", + "- Is there any implicit design knowledge -- invariants, rationale, accepted tradeoffs -- that should be preserved for downstream work?", + "- Are there reference documents or specs in the project that apply?", + "", + "Write your analysis as a draft. For each dimension, note your confidence:", + "- HIGH: you have direct evidence from this session", + "- LOW: you are extrapolating or guessing", + "", + "Flag any LOW-confidence point where a single targeted read would raise it to HIGH.", + "This is a working document, not a final artifact.", + ], + }; +} + +export function verifyGuidance(): StepGuidance { + return { + title: "Context Capture: Verify", + instructions: [ + "Review the draft you just wrote. Check three things:", + "", + "1. Completeness: scan each dimension above. Is anything missing?", + "2. Accuracy: are any items wrong, speculative, or conflating things?", + "3. Phrasing: would a downstream agent understand without ambiguity?", + "", + "Rewrite the draft with corrections. If nothing needs changing, reproduce it as-is.", + // Verify phase: tool_call handler blocks all tools except koan_next_step. + // Instruction directs LLM to avoid exploration during review. Two-layer + // defense: prohibition in description, blocking in tool_call handler. + "Do not use exploration tools during this review.", + ], + }; +} + +export interface RefinePromptOptions { + attempt: number; + maxAttempts: number; + feedback: string[]; +} + +export function refineGuidance(opts: RefinePromptOptions): StepGuidance { + const instructions: string[] = []; + if (opts.attempt > 1) { + instructions.push(`Retry (attempt ${opts.attempt} of ${opts.maxAttempts}).`); + } + instructions.push( + "Now call the `koan_store_context` tool with the verified context.", + "The tool's parameter schema defines exactly what fields are needed.", + ); + if (opts.feedback.length > 0) { + instructions.push("", "Address these issues from the previous attempt:"); + for (const item of opts.feedback) { + instructions.push(`- ${item}`); + } + } + return { + title: "Context Capture: Refine", + instructions, + // Refine completes with koan_store_context, not koan_next_step. + invokeAfter: [ + "WHEN DONE: After completing the instructions above, call koan_store_context with the verified context data.", + "Do NOT call this tool until you have prepared the structured context.", + ].join("\n"), + }; +} diff --git a/src/planner/prompts/plan-design.ts b/src/planner/prompts/plan-design.ts new file mode 100644 index 0000000..66e4075 --- /dev/null +++ b/src/planner/prompts/plan-design.ts @@ -0,0 +1,218 @@ +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import type { ContextData } from "../types.js"; +import type { StepGuidance } from "./step.js"; + +export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { + 1: "Task Analysis & Exploration Planning", + 2: "Codebase Exploration", + 3: "Testing Strategy Discovery", + 4: "Approach Generation", + 5: "Assumption Surfacing", + 6: "Milestone Definition & Plan Writing", +}; + +export async function loadPlanDesignSystemPrompt(): Promise { + const homeDir = os.homedir(); + const promptPath = path.join(homeDir, ".claude/agents/architect.md"); + try { + const content = await fs.readFile(promptPath, "utf8"); + const body = content.replace(/^---\n[\s\S]*?\n---\n/, ""); + return body; + } catch (error) { + throw new Error(`Architect prompt not found at ${promptPath}`); + } +} + +export function formatContextForStep1(ctx: ContextData): string { + return [ + "", + JSON.stringify(ctx, null, 2), + "", + ].join("\n"); +} + +export function buildPlanDesignSystemPrompt(basePrompt: string): string { + return [ + basePrompt, + "", + "---", + "", + "WORKFLOW: 6-STEP PLAN-DESIGN", + "", + "You will execute a 6-step workflow.", + "Step 1 instructions are in the user message below.", + "Complete the work described, then call koan_next_step.", + "The tool result contains the next step's instructions.", + "In step 6, use plan mutation tools, then call koan_next_step.", + "", + // Directive prevents immediate tool call without substantive work. + // Failure mode: koan_next_step called with zero file reads, + // producing an empty step with no exploration data. The directive + // repeats guidance from tool descriptions to strengthen the signal. + "CRITICAL: Do the actual work described in each step BEFORE calling", + "koan_next_step. Read files, explore code, analyze. Do not skip.", + "Do NOT produce a final text response until koan_next_step completes.", + ].join("\n"); +} + +export function planDesignStepGuidance(step: 1 | 2 | 3 | 4 | 5 | 6, context?: string): StepGuidance { + switch (step) { + case 1: + return { + title: "Step 1: Task Analysis & Exploration Planning", + instructions: [ + "PLANNING CONTEXT (from session):", + "", + context ?? "", + "", + "Parse the user's task description. Identify:", + " - What needs to change (files, modules, behavior)", + " - What exploration is needed (patterns, constraints, existing code)", + " - What directories/files are relevant", + "", + "Read project context files to understand structure:", + " - Project root CLAUDE.md", + " - Subdirectory CLAUDE.md files in relevant areas", + " - All paths in context.json reference_docs field (if any)", + "", + "CONTEXT.JSON CONTRACT: READ-ONLY.", + " - context.json is owned by the session", + " - You MUST NOT write, modify, or append to context.json", + " - Your outputs go to plan.json (step 6) -- never context.json", + "", + "DO NOT write any files yet. Gather understanding for step 2.", + "Record your analysis mentally for use in subsequent steps.", + ], + }; + + case 2: + return { + title: "Step 2: Codebase Exploration", + instructions: [ + "Use Glob, Grep, Read tools directly to discover:", + " - Existing patterns and implementations", + " - Constraints from code structure", + " - Conventions to follow", + "", + "Read conventions/ files as needed:", + " - structural.md (architectural patterns)", + " - temporal.md (comment hygiene)", + " - diff-format.md (diff specification)", + "", + "NUDGE: If you need additional context to plan well, read more files.", + "Better to over-explore than under-explore.", + "", + "Record discoveries for use in steps 4-6. Do NOT write files.", + ], + }; + + case 3: + return { + title: "Step 3: Testing Strategy Discovery", + instructions: [ + "DISCOVER testing strategy from:", + " - User conversation hints", + " - Project CLAUDE.md / README.md", + " - conventions/structural.md domain='testing-strategy'", + "", + "Record confirmed strategy for use in step 6.", + "Decisions will be recorded via tools in step 6.", + ], + }; + + case 4: + return { + title: "Step 4: Approach Generation", + instructions: [ + "GENERATE 2-3 approach options:", + " - Include 'minimal change' option", + " - Include 'idiomatic/modern' option", + " - Document advantage/disadvantage for each", + "", + "TARGET TECH RESEARCH (if new tech/migration):", + " - What is canonical usage of target tech?", + " - Does it have different abstractions?", + "", + "Use exploration findings from step 2 to ground tradeoffs.", + "Record approach analysis for step 6.", + ], + }; + + case 5: + return { + title: "Step 5: Assumption Surfacing", + instructions: [ + "FAST PATH: Skip if task involves NONE of:", + " - Migration to new tech", + " - Policy defaults (lifecycle, capacity, failure handling)", + " - Architectural decisions with multiple valid approaches", + "", + "FULL CHECK (if any apply):", + " Audit each category with OPEN questions:", + " Pattern preservation, Migration strategy, Idiomatic usage,", + " Abstraction boundary, Policy defaults", + "", + "Record assumptions for step 6.", + ], + }; + + case 6: + return { + title: "Step 6: Milestone Definition & Plan Writing", + instructions: [ + "EVALUATE approaches: P(success), failure mode, backtrack cost", + "", + "SELECT and record in Decision Log with MULTI-STEP chain:", + " BAD: 'Polling | Webhooks unreliable'", + " GOOD: 'Use polling | 30% webhook failure -> need fallback anyway -> polling simpler'", + "", + "Use the following tools to build the plan:", + "", + "OVERVIEW & CONSTRAINTS:", + " - koan_set_overview: Define problem and approach", + " - koan_set_constraints: Record constraints", + " - koan_set_invisible_knowledge: Document project-specific context", + "", + "DECISIONS & RISKS:", + " - koan_add_decision, koan_set_decision: Record architectural decisions", + " - koan_add_rejected_alternative: Document rejected approaches", + " - koan_add_risk: Track implementation risks", + "", + "MILESTONES & INTENTS:", + " - koan_add_milestone: Create milestones (deployable increments)", + " - koan_set_milestone_name/files/flags/requirements/acceptance_criteria/tests: Configure milestones", + " - koan_add_intent, koan_set_intent: Define code intents (WHAT to change, not HOW)", + "", + "WAVES & STRUCTURE:", + " - koan_add_wave, koan_set_wave_milestones: Group milestones into deployment waves", + " - koan_add_diagram, koan_set_diagram, koan_add_diagram_node, koan_add_diagram_edge: Visual structure", + " - koan_set_readme_entry: Link plan sections to README.md", + "", + "Each tool writes to disk immediately. Inspect with koan_get_plan.", + "", + "MILESTONES (each deployable increment):", + " - Files: exact paths (each file in ONE milestone only)", + " - Requirements: specific behaviors", + " - Acceptance: testable pass/fail criteria", + " - Code Intent: WHAT to change (Developer converts to code_changes later)", + " - Tests: type, backing, scenarios", + "", + "PARALLELIZATION:", + " Vertical slices (parallel) > Horizontal layers (sequential)", + " BAD: M1=models, M2=services, M3=controllers (sequential)", + " GOOD: M1=auth stack, M2=users stack, M3=posts stack (parallel)", + " If file overlap: extract to M0 (foundation) or consolidate", + ], + invokeAfter: [ + "WHEN DONE: After completing the instructions above, call koan_next_step to validate.", + "Do NOT call this tool until you have used the plan mutation tools.", + ].join("\n"), + }; + + default: + return { title: "", instructions: [] }; + } +} diff --git a/src/planner/prompts/step.ts b/src/planner/prompts/step.ts new file mode 100644 index 0000000..a6598c7 --- /dev/null +++ b/src/planner/prompts/step.ts @@ -0,0 +1,38 @@ +// Step prompt assembly for koan workflows. +// +// Format matches the reference planner's format_step() in +// skills/lib/workflow/prompts/step.py. Both use "NEXT STEP:" +// directives. Reference uses "Command:" for shell execution. +// Koan uses "Tool:" -- tool results are synchronous within +// the agent loop (deterministic delivery regardless of -p mode). +// +// Why strengthen invoke-after? The original weak format ("Now call +// koan_next_step.") produced skipped steps. Strengthened format +// mirrors reference planner's explicit directive structure. + +export interface StepGuidance { + title: string; + instructions: string[]; + // Custom invoke-after directive. When omitted, formatStep + // appends the default koan_next_step directive. + // Terminal steps override this (e.g., step 6 plan validation). + invokeAfter?: string; +} + +// Default invoke-after: conditional gate for koan_next_step. +// "WHEN DONE" + "Do NOT call until" creates a two-part gate: +// the LLM must complete work before advancing. Unconditional +// imperatives ("Execute this tool now.") cause immediate tool +// calls because tool calls with empty params have zero friction +// (unlike shell commands which require mechanical copy-paste). +const DEFAULT_INVOKE = [ + "WHEN DONE: After completing the instructions above, call koan_next_step to advance.", + "Do NOT call this tool until the work described in this step is finished.", +].join("\n"); + +export function formatStep(g: StepGuidance): string { + const header = `${g.title}\n${"=".repeat(g.title.length)}\n\n`; + const body = g.instructions.join("\n"); + const invoke = g.invokeAfter ?? DEFAULT_INVOKE; + return `${header}${body}\n\n${invoke}`; +} diff --git a/src/planner/qr/mutate.ts b/src/planner/qr/mutate.ts new file mode 100644 index 0000000..b831074 --- /dev/null +++ b/src/planner/qr/mutate.ts @@ -0,0 +1,91 @@ +import type { QRFile, QRItem, QRSeverity, QRItemStatus } from "./types.js"; + +function pad3(n: number): string { + return String(n).padStart(3, "0"); +} + +function nextQRId(qr: QRFile): string { + return `QR-${qr.phase}-${pad3(qr.items.length + 1)}`; +} + +export function addQRItem( + qr: QRFile, + data: { scope: string; check: string; severity?: QRSeverity }, +): { qr: QRFile; id: string } { + const id = nextQRId(qr); + const item: QRItem = { + id, + scope: data.scope, + check: data.check, + status: "TODO", + version: 1, + finding: null, + parent_id: null, + group_id: null, + severity: data.severity ?? "MUST", + }; + return { + qr: { + ...qr, + items: [...qr.items, item], + }, + id, + }; +} + +// PASS is terminal: cannot transition from PASS to FAIL. +// FAIL requires finding (explains what failed). +// PASS forbids finding. +export function setQRItem( + qr: QRFile, + id: string, + data: { + status?: QRItemStatus; + finding?: string; + check?: string; + severity?: QRSeverity; + }, +): QRFile { + const idx = qr.items.findIndex((i) => i.id === id); + if (idx === -1) throw new Error(`qr_item ${id} not found`); + + const item = qr.items[idx]; + + if (item.status === "PASS" && data.status === "FAIL") { + throw new Error(`cannot transition ${id} from PASS to FAIL (PASS is terminal)`); + } + + const status = data.status ?? item.status; + const finding = data.finding ?? item.finding; + + if (status === "FAIL" && !finding) { + throw new Error(`FAIL status requires finding for ${id}`); + } + + if (status === "PASS" && finding) { + throw new Error(`PASS status forbids finding for ${id}`); + } + + const updated: QRItem = { + ...item, + version: item.version + 1, + status, + finding, + check: data.check ?? item.check, + severity: data.severity ?? item.severity, + }; + + const items = [...qr.items]; + items[idx] = updated; + + return { ...qr, items }; +} + +// Does not increment version (grouping is metadata). +export function assignGroup(qr: QRFile, ids: string[], groupId: string): QRFile { + const idSet = new Set(ids); + const items = qr.items.map((item) => + idSet.has(item.id) ? { ...item, group_id: groupId } : item, + ); + return { ...qr, items }; +} diff --git a/src/planner/qr/types.ts b/src/planner/qr/types.ts new file mode 100644 index 0000000..3345631 --- /dev/null +++ b/src/planner/qr/types.ts @@ -0,0 +1,20 @@ +export type QRSeverity = "MUST" | "SHOULD" | "COULD"; +export type QRItemStatus = "TODO" | "PASS" | "FAIL"; + +export interface QRItem { + id: string; + scope: string; + check: string; + status: QRItemStatus; + version: number; + finding: string | null; + parent_id: string | null; + group_id: string | null; + severity: QRSeverity; +} + +export interface QRFile { + phase: string; + iteration: number; + items: QRItem[]; +} diff --git a/src/planner/session.ts b/src/planner/session.ts new file mode 100644 index 0000000..4bb533a --- /dev/null +++ b/src/planner/session.ts @@ -0,0 +1,196 @@ +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent"; + +import { ContextCapturePhase } from "./phases/context-capture.js"; +import { createInitialState, initializePlanState, type WorkflowState } from "./state.js"; +import { createPlanInfo } from "../utils/plan.js"; +import { spawnArchitect } from "./subagent.js"; +import { createLogger } from "../utils/logger.js"; +import { createSubagentDir, readSubagentState } from "../utils/progress.js"; +import type { WorkflowDispatch, PlanRef } from "./tools/dispatch.js"; + +interface Session { + plan(args: string, ctx: ExtensionCommandContext): Promise; + execute(_ctx: ExtensionCommandContext): Promise; + status(ctx: ExtensionCommandContext): Promise; +} + +export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, planRef: PlanRef): Session { + const state: WorkflowState = createInitialState(); + const log = createLogger("Session"); + + // Completion callback for context-capture phase. Runs inside the + // koan_store_context tool call -- the tool blocks until the architect + // subagent finishes. The LLM sees context capture + architect outcome + // in one tool response. No agent_end polling needed. + const onContextComplete = async (ctx: ExtensionContext): Promise => { + if (!state.plan) { + return "Context captured but no plan state available."; + } + + const planDir = state.plan.directory; + const planJsonPath = path.join(planDir, "plan.json"); + const subagentDir = await createSubagentDir(planDir, "architect"); + + state.phase = "architect-running"; + ctx.ui.notify("Launching architect subagent for plan-design...", "info"); + log("Spawning architect after context capture", { planDir, subagentDir }); + + const extensionPath = path.resolve(import.meta.dirname, "../../extensions/koan.ts"); + + const pollInterval = setInterval(async () => { + const s = await readSubagentState(subagentDir); + if (s?.current) { + ctx.ui.notify(`Architect: ${s.current}`, "info"); + } + }, 2000); + + const result = await spawnArchitect({ + planDir, + subagentDir, + cwd: ctx.cwd, + extensionPath, + log, + }); + + clearInterval(pollInterval); + + if (result.exitCode !== 0) { + state.phase = "architect-failed"; + const detail = result.stderr.slice(0, 500); + log("Architect subagent failed", { exitCode: result.exitCode, stderr: detail }); + ctx.ui.notify(`Architect subagent failed (exit ${result.exitCode}).`, "error"); + return `Context captured. Architect subagent failed (exit ${result.exitCode}).\n\nStderr:\n${detail}`; + } + + let planExists = false; + try { + await fs.access(planJsonPath); + planExists = true; + } catch { + // plan.json not written + } + + if (!planExists) { + state.phase = "architect-failed"; + log("Architect completed but plan.json not found", { planJsonPath }); + ctx.ui.notify("Architect completed but plan.json was not written.", "error"); + return "Context captured. Architect completed but plan.json was not written."; + } + + state.phase = "plan-design-complete"; + log("Architect plan-design complete", { planDir }); + ctx.ui.notify("Plan-design phase complete.", "success"); + return `Context captured. Plan written to ${planDir}/plan.json.`; + }; + + const contextPhase = new ContextCapturePhase(pi, state, dispatch, createLogger("Context"), onContextComplete); + + return { + async plan(args, ctx) { + const description = args.trim(); + if (!description) { + ctx.ui.notify("Usage: /koan plan ", "error"); + return; + } + + if (state.phase === "context" && state.context?.active) { + ctx.ui.notify("Context capture already running. Use /koan status to check progress.", "warning"); + return; + } + + await ctx.waitForIdle(); + + const planInfo = await createPlanInfo(description, ctx.cwd); + initializePlanState(state, planInfo, description); + planRef.dir = planInfo.directory; + + log("Plan command invoked", { + cwd: ctx.cwd, + description, + planId: planInfo.id, + planDirectory: planInfo.directory, + }); + + await contextPhase.begin(description, planInfo, ctx); + }, + + async execute(ctx) { + ctx.ui.notify("Execution mode is not yet implemented.", "warning"); + }, + + async status(ctx) { + const summary = buildStatusSummary(state, ctx.cwd); + ctx.ui.notify(summary, "info"); + }, + }; +} + +function buildStatusSummary(state: WorkflowState, cwd: string): string { + const lines: string[] = []; + const plan = state.plan; + + if (plan) { + lines.push(`Plan ${plan.id}`); + lines.push(`Directory: ${formatPath(plan.directory, cwd)}`); + } else { + lines.push("No active plan."); + } + + switch (state.phase) { + case "idle": + lines.push("Koan planner is idle."); + break; + case "context": { + const attempt = state.context?.attempt ?? 0; + lines.push(`Context capture in progress (attempt ${attempt}).`); + if (state.context?.contextFilePath) { + lines.push(`Target: ${formatPath(state.context.contextFilePath, cwd)}`); + } + break; + } + case "context-complete": + lines.push("Context captured successfully."); + if (state.context?.contextFilePath) { + lines.push(`Stored at: ${formatPath(state.context.contextFilePath, cwd)}`); + } + break; + case "context-failed": + lines.push("Context capture failed. Re-run /koan plan to try again."); + break; + case "architect-running": + lines.push("Architect subagent running (plan-design phase)..."); + break; + case "architect-failed": + lines.push("Architect subagent failed. Check plan directory for details."); + break; + case "plan-design-complete": + lines.push("Plan-design phase complete."); + if (plan) { + lines.push(`Plan: ${formatPath(path.join(plan.directory, "plan.json"), cwd)}`); + } + break; + default: + lines.push("Unknown planner state."); + break; + } + + return lines.join("\n"); +} + +function formatPath(target: string, cwd: string): string { + const home = os.homedir(); + if (target.startsWith(home)) { + return `~${target.slice(home.length)}`; + } + + const relative = path.relative(cwd, target); + if (!relative.startsWith("..")) { + return relative; + } + + return target; +} diff --git a/src/planner/state.ts b/src/planner/state.ts new file mode 100644 index 0000000..5d47d63 --- /dev/null +++ b/src/planner/state.ts @@ -0,0 +1,67 @@ +import type { ContextData } from "./types.js"; + +export type WorkflowPhase = + | "idle" + | "context" + | "context-complete" + | "context-failed" + | "architect-running" + | "architect-failed" + | "plan-design-complete"; + +export interface PlanInfo { + id: string; + directory: string; + createdAt: string; + metadataPath: string; +} + +export interface ContextCaptureState { + readonly maxAttempts: number; + active: boolean; + subPhase: "drafting" | "verifying" | "refining"; + attempt: number; + taskDescription: string; + planId: string; + planDirectory: string; + contextFilePath: string; + lastPrompt: string | null; + feedback: string[]; + data?: ContextData; + lastRawContent?: string; +} + +export interface WorkflowState { + phase: WorkflowPhase; + taskDescription: string | null; + plan: PlanInfo | null; + context: ContextCaptureState | null; +} + +export function createInitialState(): WorkflowState { + return { + phase: "idle", + taskDescription: null, + plan: null, + context: null, + }; +} + +export function resetContextState(state: WorkflowState): void { + state.context = null; + if ( + state.phase === "context" || + state.phase === "context-failed" || + state.phase === "context-complete" || + state.phase === "architect-failed" || + state.phase === "plan-design-complete" + ) { + state.phase = "idle"; + } +} + +export function initializePlanState(state: WorkflowState, plan: PlanInfo, taskDescription: string): void { + state.plan = plan; + state.taskDescription = taskDescription; + resetContextState(state); +} diff --git a/src/planner/subagent.ts b/src/planner/subagent.ts new file mode 100644 index 0000000..997c8f8 --- /dev/null +++ b/src/planner/subagent.ts @@ -0,0 +1,72 @@ +import { spawn } from "node:child_process"; +import { createWriteStream } from "node:fs"; +import * as path from "node:path"; + +import { createLogger, type Logger } from "../utils/logger.js"; + +export interface SubagentResult { + exitCode: number; + stderr: string; + subagentDir: string; +} + +export interface SpawnArchitectOptions { + planDir: string; + subagentDir: string; + cwd: string; + extensionPath: string; + log?: Logger; +} + +export function spawnArchitect(opts: SpawnArchitectOptions): Promise { + const log = opts.log ?? createLogger("Subagent"); + + const args = [ + "-p", + "-e", opts.extensionPath, + "--koan-role", "architect", + "--koan-phase", "plan-design", + "--koan-plan-dir", opts.planDir, + "--koan-subagent-dir", opts.subagentDir, + "Begin the plan-design phase.", + ]; + + log("Spawning architect subagent", { planDir: opts.planDir, subagentDir: opts.subagentDir }); + + return new Promise((resolve) => { + const stdoutLog = createWriteStream(path.join(opts.subagentDir, "stdout.log"), { flags: "w" }); + const stderrLog = createWriteStream(path.join(opts.subagentDir, "stderr.log"), { flags: "w" }); + + const proc = spawn("pi", args, { + cwd: opts.cwd, + shell: false, + stdio: ["ignore", "pipe", "pipe"], + }); + + let stderr = ""; + + proc.stdout.on("data", (data: Buffer) => { + stdoutLog.write(data); + }); + + proc.stderr.on("data", (data: Buffer) => { + stderr += data.toString(); + stderrLog.write(data); + }); + + proc.on("close", (code) => { + stdoutLog.end(); + stderrLog.end(); + const exitCode = code ?? 1; + log("Architect subagent exited", { exitCode }); + resolve({ exitCode, stderr, subagentDir: opts.subagentDir }); + }); + + proc.on("error", (error) => { + stdoutLog.end(); + stderrLog.end(); + log("Architect subagent spawn error", { error: error.message }); + resolve({ exitCode: 1, stderr: error.message, subagentDir: opts.subagentDir }); + }); + }); +} diff --git a/src/planner/tools/context-store.ts b/src/planner/tools/context-store.ts new file mode 100644 index 0000000..cb4e97e --- /dev/null +++ b/src/planner/tools/context-store.ts @@ -0,0 +1,34 @@ +import { Type } from "@sinclair/typebox"; + +const NonEmptyStringArray = Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }); + +export const ContextStoreSchema = Type.Object({ + task_spec: NonEmptyStringArray, + constraints: NonEmptyStringArray, + entry_points: NonEmptyStringArray, + rejected_alternatives: NonEmptyStringArray, + current_understanding: NonEmptyStringArray, + assumptions: NonEmptyStringArray, + invisible_knowledge: NonEmptyStringArray, + reference_docs: NonEmptyStringArray, +}, { + description: [ + "Structured planning context. All fields are string arrays.", + "task_spec: subject, scope, out-of-scope items.", + "constraints: 'MUST/SHOULD/MUST-NOT: rule (source)' or 'none confirmed'.", + "entry_points: 'file:symbol - why relevant' or 'greenfield'.", + "rejected_alternatives: 'approach - why dismissed' or 'none discussed'.", + "current_understanding: how the system works, relevant behavior.", + "assumptions: 'claim (H/M/L confidence)' or 'none'.", + "invisible_knowledge: design rationale, invariants, accepted tradeoffs.", + "reference_docs: 'path - what it covers' or 'none'.", + ].join(" "), +}); + +export interface ContextToolResult { + ok: boolean; + message: string; + errors?: string[]; +} + +export type ContextToolHandler = (payload: unknown, ctx: unknown) => Promise; diff --git a/src/planner/tools/dispatch.ts b/src/planner/tools/dispatch.ts new file mode 100644 index 0000000..ee9fd5d --- /dev/null +++ b/src/planner/tools/dispatch.ts @@ -0,0 +1,140 @@ +// Workflow tool dispatch for koan. +// +// Workflow tools (koan_next_step, koan_store_context) are registered once +// at init and read from this dispatch at call time. +// Pi snapshots tools during _buildRuntime() -- late registration is +// invisible to the LLM. The dispatch decouples static registration +// from dynamic phase routing. + +import { Type } from "@sinclair/typebox"; +import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"; + +import { ContextStoreSchema, type ContextToolResult } from "./context-store.js"; +import { createLogger } from "../../utils/logger.js"; + +const log = createLogger("Dispatch"); + +// -- Result types -- + +export interface StepResult { + ok: boolean; + prompt?: string; + error?: string; +} + +// -- Dispatch -- + +export interface WorkflowDispatch { + onNextStep: (() => StepResult) | null; + onStoreContext: + | ((payload: unknown, ctx: ExtensionContext) => Promise) + | null; +} + +export function createDispatch(): WorkflowDispatch { + return { onNextStep: null, onStoreContext: null }; +} + +// Decouples tool registration (init-time, before _buildRuntime) from +// plan directory creation (runtime, after flags available). Same +// indirection pattern as WorkflowDispatch. +export interface PlanRef { + dir: string | null; +} + +export function createPlanRef(): PlanRef { + return { dir: null }; +} + +// Sets a dispatch slot. Throws if the slot is already occupied -- +// prevents silent misrouting when two phases attempt to claim +// the same tool. +export function hookDispatch( + dispatch: WorkflowDispatch, + key: K, + handler: NonNullable, +): void { + if (dispatch[key] !== null) { + throw new Error(`dispatch.${String(key)} is already hooked`); + } + (dispatch as Record)[key] = handler; +} + +export function unhookDispatch( + dispatch: WorkflowDispatch, + key: keyof WorkflowDispatch, +): void { + (dispatch as Record)[key] = null; +} + +// -- Tool registration -- + +// Registers workflow tools. Called once at init in koan.ts, +// before pi's _buildRuntime() snapshot. Tool execute callbacks read +// from the dispatch at call time -- the dispatch is mutable, the +// tool list is not. +// +// Why register all tools unconditionally? Flags are unavailable during +// init (getFlag() returns undefined before _buildRuntime() sets flagValues), +// so conditional registration based on role/phase is impossible. Tools +// registered after _buildRuntime() are invisible to the LLM. +export function registerWorkflowTools( + pi: ExtensionAPI, + dispatch: WorkflowDispatch, +): void { + // -- koan_next_step -- + // "DO NOT call until told" creates prohibition/activation pattern + // with step prompts. Description = default prohibition, step prompt + // invoke-after = explicit activation. + pi.registerTool({ + name: "koan_next_step", + label: "Advance to next workflow step", + description: [ + "Signal completion of the current workflow step.", + "DO NOT call this tool until the step instructions explicitly tell you to.", + "Do the actual work described in each step BEFORE calling this tool.", + ].join(" "), + parameters: Type.Object({}), + async execute() { + // Two-layer defense: tool_call blocks with descriptive reasons + // (primary gate), dispatch null checks as fallback. Dispatch check + // fires only if tool_call handler is bypassed or misconfigured. + if (!dispatch.onNextStep) { + throw new Error("No workflow phase is active."); + } + const r = dispatch.onNextStep(); + if (!r.ok) { + throw new Error(r.error ?? "Step transition failed."); + } + return { + content: [{ type: "text" as const, text: r.prompt ?? "Step complete." }], + }; + }, + }); + + // -- koan_store_context -- + pi.registerTool({ + name: "koan_store_context", + label: "Store planning context", + description: [ + "Store structured planning context.", + "DO NOT call this tool until the step instructions explicitly tell you to.", + "Each field is a string array -- encode structure within strings, not as nested objects.", + ].join(" "), + parameters: ContextStoreSchema, + async execute(_toolCallId, params, _signal, _onUpdate, ctx) { + if (!dispatch.onStoreContext) { + throw new Error("Context capture is not active."); + } + const r = await dispatch.onStoreContext(params, ctx); + if (!r.ok) { + log("Context store rejected", { errors: r.errors }); + throw new Error(r.message); + } + log("Context stored"); + return { + content: [{ type: "text" as const, text: r.message }], + }; + }, + }); +} diff --git a/src/planner/tools/plan-entities.ts b/src/planner/tools/plan-entities.ts new file mode 100644 index 0000000..f431f1a --- /dev/null +++ b/src/planner/tools/plan-entities.ts @@ -0,0 +1,599 @@ +// Every tool follows load-mutate-save: loadPlan -> pure mutation -> savePlan. +// Disk is single source of truth. Single-writer assumption per phase. +// Feedback messages prevent the LLM from skipping tools (prior architecture +// returned opaque JSON). + +import { Type } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; +import type { TSchema } from "@sinclair/typebox"; + +import type { PlanRef } from "./dispatch.js"; +import { loadPlan, savePlan } from "../plan/serialize.js"; +import type { Plan } from "../plan/types.js"; +import { + addDecision, + setDecision, + addRejectedAlternative, + setRejectedAlternative, + addRisk, + setRisk, + addMilestone, + setMilestoneName, + setMilestoneFiles, + setMilestoneFlags, + setMilestoneRequirements, + setMilestoneAcceptanceCriteria, + setMilestoneTests, + addIntent, + setIntent, + addChange, + setChangeDiff, + setChangeDocDiff, + setChangeComments, + setChangeFile, + setChangeIntentRef, + addWave, + setWaveMilestones, + addDiagram, + setDiagram, + addDiagramNode, + addDiagramEdge, + setReadmeEntry, +} from "../plan/mutate.js"; + +function planTool

( + pi: ExtensionAPI, + planRef: PlanRef, + opts: { + name: string; + label: string; + description: string; + parameters: TSchema; + execute: (plan: Plan, params: P) => { plan: Plan; message: string }; + }, +): void { + pi.registerTool({ + name: opts.name, + label: opts.label, + description: opts.description, + parameters: opts.parameters, + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const plan = await loadPlan(planRef.dir); + const result = opts.execute(plan, params as P); + await savePlan(result.plan, planRef.dir); + return { + content: [{ type: "text" as const, text: result.message }], + }; + }, + }); +} + +export function registerPlanEntityTools( + pi: ExtensionAPI, + planRef: PlanRef, +): void { + // -- Decision -- + planTool(pi, planRef, { + name: "koan_add_decision", + label: "Add decision", + description: "Add decision to decision log.", + parameters: Type.Object({ + decision: Type.String(), + reasoning: Type.String(), + }), + execute: (p, params) => { + const r = addDecision(p, params); + return { + plan: r.plan, + message: `Added decision ${r.id}: "${params.decision}"`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_decision", + label: "Update decision", + description: "Update existing decision by ID.", + parameters: Type.Object({ + id: Type.String(), + decision: Type.Optional(Type.String()), + reasoning: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = setDecision(p, params.id, params); + return { + plan: updated, + message: `Updated decision ${params.id}`, + }; + }, + }); + + // -- RejectedAlternative -- + planTool(pi, planRef, { + name: "koan_add_rejected_alternative", + label: "Add rejected alternative", + description: "Add rejected alternative to decision log.", + parameters: Type.Object({ + alternative: Type.String(), + rejection_reason: Type.String(), + decision_ref: Type.String(), + }), + execute: (p, params) => { + const r = addRejectedAlternative(p, params); + return { + plan: r.plan, + message: `Added rejected alternative ${r.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_rejected_alternative", + label: "Update rejected alternative", + description: "Update existing rejected alternative by ID.", + parameters: Type.Object({ + id: Type.String(), + alternative: Type.Optional(Type.String()), + rejection_reason: Type.Optional(Type.String()), + decision_ref: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = setRejectedAlternative(p, params.id, params); + return { + plan: updated, + message: `Updated rejected alternative ${params.id}`, + }; + }, + }); + + // -- Risk -- + planTool(pi, planRef, { + name: "koan_add_risk", + label: "Add risk", + description: "Add risk to known risks.", + parameters: Type.Object({ + risk: Type.String(), + mitigation: Type.String(), + anchor: Type.Optional(Type.String()), + decision_ref: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const r = addRisk(p, params); + return { + plan: r.plan, + message: `Added risk ${r.id}: "${params.risk}"`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_risk", + label: "Update risk", + description: "Update existing risk by ID.", + parameters: Type.Object({ + id: Type.String(), + risk: Type.Optional(Type.String()), + mitigation: Type.Optional(Type.String()), + anchor: Type.Optional(Type.String()), + decision_ref: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = setRisk(p, params.id, params); + return { + plan: updated, + message: `Updated risk ${params.id}`, + }; + }, + }); + + // -- Milestone -- + planTool(pi, planRef, { + name: "koan_add_milestone", + label: "Add milestone", + description: "Create new milestone.", + parameters: Type.Object({ + name: Type.String(), + files: Type.Optional(Type.Array(Type.String())), + flags: Type.Optional(Type.Array(Type.String())), + requirements: Type.Optional(Type.Array(Type.String())), + acceptance_criteria: Type.Optional(Type.Array(Type.String())), + tests: Type.Optional(Type.Array(Type.String())), + }), + execute: (p, params) => { + const r = addMilestone(p, params); + return { + plan: r.plan, + message: `Added milestone ${r.id}: "${params.name}"`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_name", + label: "Set milestone name", + description: "Update milestone name.", + parameters: Type.Object({ + id: Type.String(), + name: Type.String(), + }), + execute: (p, params) => { + const updated = setMilestoneName(p, params.id, params.name); + return { + plan: updated, + message: `Set name for milestone ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_files", + label: "Set milestone files", + description: "Update milestone files list.", + parameters: Type.Object({ + id: Type.String(), + files: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setMilestoneFiles(p, params.id, params.files); + return { + plan: updated, + message: `Set files for milestone ${params.id} (${params.files.length} files)`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_flags", + label: "Set milestone flags", + description: "Update milestone flags list.", + parameters: Type.Object({ + id: Type.String(), + flags: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setMilestoneFlags(p, params.id, params.flags); + return { + plan: updated, + message: `Set flags for milestone ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_requirements", + label: "Set milestone requirements", + description: "Update milestone requirements list.", + parameters: Type.Object({ + id: Type.String(), + requirements: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setMilestoneRequirements(p, params.id, params.requirements); + return { + plan: updated, + message: `Set requirements for milestone ${params.id} (${params.requirements.length} items)`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_acceptance_criteria", + label: "Set milestone acceptance criteria", + description: "Update milestone acceptance criteria list.", + parameters: Type.Object({ + id: Type.String(), + acceptance_criteria: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setMilestoneAcceptanceCriteria( + p, + params.id, + params.acceptance_criteria, + ); + return { + plan: updated, + message: `Set acceptance criteria for milestone ${params.id} (${params.acceptance_criteria.length} items)`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_tests", + label: "Set milestone tests", + description: "Update milestone tests list.", + parameters: Type.Object({ + id: Type.String(), + tests: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setMilestoneTests(p, params.id, params.tests); + return { + plan: updated, + message: `Set tests for milestone ${params.id} (${params.tests.length} tests)`, + }; + }, + }); + + // -- CodeIntent -- + planTool(pi, planRef, { + name: "koan_add_intent", + label: "Add code intent", + description: "Add code intent to milestone.", + parameters: Type.Object({ + milestone: Type.String(), + file: Type.String(), + function: Type.Optional(Type.String()), + behavior: Type.String(), + decision_refs: Type.Optional(Type.Array(Type.String())), + }), + execute: (p, params) => { + const r = addIntent(p, params); + return { + plan: r.plan, + message: `Added intent ${r.id} to milestone ${params.milestone}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_intent", + label: "Update code intent", + description: "Update existing code intent by ID.", + parameters: Type.Object({ + id: Type.String(), + file: Type.Optional(Type.String()), + function: Type.Optional(Type.String()), + behavior: Type.Optional(Type.String()), + decision_refs: Type.Optional(Type.Array(Type.String())), + }), + execute: (p, params) => { + const updated = setIntent(p, params.id, params); + return { + plan: updated, + message: `Updated intent ${params.id}`, + }; + }, + }); + + // -- CodeChange -- + planTool(pi, planRef, { + name: "koan_add_change", + label: "Add code change", + description: "Add code change to milestone.", + parameters: Type.Object({ + milestone: Type.String(), + file: Type.String(), + intent_ref: Type.Optional(Type.String()), + diff: Type.Optional(Type.String()), + doc_diff: Type.Optional(Type.String()), + comments: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const r = addChange(p, params); + return { + plan: r.plan, + message: `Added change ${r.id} to milestone ${params.milestone}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_change_diff", + label: "Set code change diff", + description: "Update change diff.", + parameters: Type.Object({ + id: Type.String(), + diff: Type.String(), + }), + execute: (p, params) => { + const updated = setChangeDiff(p, params.id, params.diff); + return { + plan: updated, + message: `Set diff for change ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_change_doc_diff", + label: "Set code change doc_diff", + description: "Update change doc_diff.", + parameters: Type.Object({ + id: Type.String(), + doc_diff: Type.String(), + }), + execute: (p, params) => { + const updated = setChangeDocDiff(p, params.id, params.doc_diff); + return { + plan: updated, + message: `Set doc_diff for change ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_change_comments", + label: "Set code change comments", + description: "Update change comments.", + parameters: Type.Object({ + id: Type.String(), + comments: Type.String(), + }), + execute: (p, params) => { + const updated = setChangeComments(p, params.id, params.comments); + return { + plan: updated, + message: `Set comments for change ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_change_file", + label: "Set code change file", + description: "Update change file path.", + parameters: Type.Object({ + id: Type.String(), + file: Type.String(), + }), + execute: (p, params) => { + const updated = setChangeFile(p, params.id, params.file); + return { + plan: updated, + message: `Set file for change ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_change_intent_ref", + label: "Set code change intent_ref", + description: "Update change intent reference.", + parameters: Type.Object({ + id: Type.String(), + intent_ref: Type.String(), + }), + execute: (p, params) => { + const updated = setChangeIntentRef(p, params.id, params.intent_ref); + return { + plan: updated, + message: `Set intent_ref for change ${params.id}`, + }; + }, + }); + + // -- Wave -- + planTool(pi, planRef, { + name: "koan_add_wave", + label: "Add wave", + description: "Create wave with milestone list.", + parameters: Type.Object({ + milestones: Type.Array(Type.String()), + }), + execute: (p, params) => { + const r = addWave(p, params); + return { + plan: r.plan, + message: `Added wave ${r.id} with ${params.milestones.length} milestones`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_wave_milestones", + label: "Set wave milestones", + description: "Update wave milestones list.", + parameters: Type.Object({ + id: Type.String(), + milestones: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setWaveMilestones(p, params.id, params.milestones); + return { + plan: updated, + message: `Set milestones for wave ${params.id}`, + }; + }, + }); + + // -- Diagram -- + planTool(pi, planRef, { + name: "koan_add_diagram", + label: "Add diagram", + description: "Create diagram graph.", + parameters: Type.Object({ + type: Type.Union([ + Type.Literal("architecture"), + Type.Literal("state"), + Type.Literal("sequence"), + Type.Literal("dataflow"), + ]), + scope: Type.String(), + title: Type.String(), + }), + execute: (p, params) => { + const r = addDiagram(p, params); + return { + plan: r.plan, + message: `Added diagram ${r.id}: "${params.title}"`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_diagram", + label: "Update diagram", + description: "Update diagram properties.", + parameters: Type.Object({ + id: Type.String(), + title: Type.Optional(Type.String()), + scope: Type.Optional(Type.String()), + ascii_render: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = setDiagram(p, params.id, params); + return { + plan: updated, + message: `Updated diagram ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_add_diagram_node", + label: "Add diagram node", + description: "Add node to diagram.", + parameters: Type.Object({ + diagram_id: Type.String(), + id: Type.String(), + label: Type.String(), + type: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = addDiagramNode(p, params.diagram_id, params); + return { + plan: updated, + message: `Added node ${params.id} to diagram ${params.diagram_id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_add_diagram_edge", + label: "Add diagram edge", + description: "Add edge to diagram.", + parameters: Type.Object({ + diagram_id: Type.String(), + source: Type.String(), + target: Type.String(), + label: Type.String(), + protocol: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = addDiagramEdge(p, params.diagram_id, params); + return { + plan: updated, + message: `Added edge ${params.source}->${params.target} to diagram ${params.diagram_id}`, + }; + }, + }); + + // -- ReadmeEntry -- + planTool(pi, planRef, { + name: "koan_set_readme_entry", + label: "Set readme entry", + description: "Upsert readme entry by path.", + parameters: Type.Object({ + path: Type.String(), + content: Type.String(), + }), + execute: (p, params) => { + const updated = setReadmeEntry(p, params.path, params.content); + return { + plan: updated, + message: `Set readme entry for ${params.path}`, + }; + }, + }); +} diff --git a/src/planner/tools/plan-getters.ts b/src/planner/tools/plan-getters.ts new file mode 100644 index 0000000..ff1fc2e --- /dev/null +++ b/src/planner/tools/plan-getters.ts @@ -0,0 +1,167 @@ +import { Type } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import type { PlanRef } from "./dispatch.js"; +import { loadPlan } from "../plan/serialize.js"; +import type { Plan, Milestone, CodeIntent, CodeChange } from "../plan/types.js"; + +export function registerPlanGetterTools( + pi: ExtensionAPI, + planRef: PlanRef, +): void { + pi.registerTool({ + name: "koan_get_plan", + label: "Get plan summary", + description: + "Returns plan overview and entity counts with IDs for drill-down.", + parameters: Type.Object({}), + async execute() { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = await loadPlan(planRef.dir); + const summary = formatPlanSummary(p); + return { + content: [{ type: "text" as const, text: summary }], + }; + }, + }); + + pi.registerTool({ + name: "koan_get_milestone", + label: "Get milestone by ID", + description: "Returns full milestone with code_intents and code_changes.", + parameters: Type.Object({ + id: Type.String({ description: "Milestone ID (e.g., M-001)" }), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = await loadPlan(planRef.dir); + const m = p.milestones.find((x) => x.id === (params as { id: string }).id); + if (!m) throw new Error(`Milestone ${(params as { id: string }).id} not found`); + return { + content: [{ type: "text" as const, text: JSON.stringify(m, null, 2) }], + }; + }, + }); + + pi.registerTool({ + name: "koan_get_decision", + label: "Get decision by ID", + description: "Returns decision from decision log.", + parameters: Type.Object({ + id: Type.String({ description: "Decision ID (e.g., DL-001)" }), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = await loadPlan(planRef.dir); + const d = p.planning_context.decision_log.find( + (x) => x.id === (params as { id: string }).id, + ); + if (!d) throw new Error(`Decision ${(params as { id: string }).id} not found`); + return { + content: [{ type: "text" as const, text: JSON.stringify(d, null, 2) }], + }; + }, + }); + + pi.registerTool({ + name: "koan_get_intent", + label: "Get code intent by ID", + description: "Returns code intent and parent milestone ID.", + parameters: Type.Object({ + id: Type.String({ description: "Intent ID (e.g., CI-M-001-001)" }), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = await loadPlan(planRef.dir); + const result = findIntent(p, (params as { id: string }).id); + if (!result) + throw new Error(`Intent ${(params as { id: string }).id} not found`); + return { + content: [ + { + type: "text" as const, + text: JSON.stringify( + { milestone_id: result.milestoneId, intent: result.intent }, + null, + 2, + ), + }, + ], + }; + }, + }); + + pi.registerTool({ + name: "koan_get_change", + label: "Get code change by ID", + description: "Returns code change and parent milestone ID.", + parameters: Type.Object({ + id: Type.String({ description: "Change ID (e.g., CC-M-001-001)" }), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = await loadPlan(planRef.dir); + const result = findChange(p, (params as { id: string }).id); + if (!result) + throw new Error(`Change ${(params as { id: string }).id} not found`); + return { + content: [ + { + type: "text" as const, + text: JSON.stringify( + { milestone_id: result.milestoneId, change: result.change }, + null, + 2, + ), + }, + ], + }; + }, + }); +} + +function formatPlanSummary(p: Plan): string { + const lines = [ + "Plan Summary", + "============", + "", + "Overview:", + ` Problem: ${p.overview.problem || "(empty)"}`, + ` Approach: ${p.overview.approach || "(empty)"}`, + "", + `Milestones (${p.milestones.length}):`, + ...p.milestones.map((m) => ` ${m.id}: ${m.name}`), + "", + `Decisions (${p.planning_context.decision_log.length}):`, + ...p.planning_context.decision_log.map((d) => ` ${d.id}: ${d.decision}`), + "", + `Waves (${p.waves.length}):`, + ...p.waves.map((w) => ` ${w.id}: [${w.milestones.join(", ")}]`), + "", + `Diagrams (${p.diagram_graphs.length}):`, + ...p.diagram_graphs.map((d) => ` ${d.id}: ${d.title} (${d.type})`), + ]; + return lines.join("\n"); +} + +function findIntent( + p: Plan, + id: string, +): { milestoneId: string; intent: CodeIntent } | null { + for (const m of p.milestones) { + const intent = m.code_intents.find((ci) => ci.id === id); + if (intent) return { milestoneId: m.id, intent }; + } + return null; +} + +function findChange( + p: Plan, + id: string, +): { milestoneId: string; change: CodeChange } | null { + for (const m of p.milestones) { + const change = m.code_changes.find((cc) => cc.id === id); + if (change) return { milestoneId: m.id, change }; + } + return null; +} diff --git a/src/planner/tools/plan-setters.ts b/src/planner/tools/plan-setters.ts new file mode 100644 index 0000000..16a0a87 --- /dev/null +++ b/src/planner/tools/plan-setters.ts @@ -0,0 +1,92 @@ +import { Type } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import type { PlanRef } from "./dispatch.js"; +import { loadPlan, savePlan } from "../plan/serialize.js"; +import { + setOverview, + setConstraints, + setInvisibleKnowledge, +} from "../plan/mutate.js"; + +export function registerPlanSetterTools( + pi: ExtensionAPI, + planRef: PlanRef, +): void { + pi.registerTool({ + name: "koan_set_overview", + label: "Set plan overview", + description: "Set problem statement and approach.", + parameters: Type.Object({ + problem: Type.Optional(Type.String()), + approach: Type.Optional(Type.String()), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = await loadPlan(planRef.dir); + const updated = setOverview( + p, + params as { problem?: string; approach?: string }, + ); + await savePlan(updated, planRef.dir); + return { + content: [{ type: "text" as const, text: "Overview updated." }], + }; + }, + }); + + pi.registerTool({ + name: "koan_set_constraints", + label: "Set plan constraints", + description: "Set planning constraints list.", + parameters: Type.Object({ + constraints: Type.Array(Type.String()), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = await loadPlan(planRef.dir); + const updated = setConstraints( + p, + (params as { constraints: string[] }).constraints, + ); + await savePlan(updated, planRef.dir); + return { + content: [ + { + type: "text" as const, + text: `Constraints set (${(params as { constraints: string[] }).constraints.length} items).`, + }, + ], + }; + }, + }); + + pi.registerTool({ + name: "koan_set_invisible_knowledge", + label: "Set invisible knowledge", + description: "Set system description, invariants, and tradeoffs.", + parameters: Type.Object({ + system: Type.Optional(Type.String()), + invariants: Type.Optional(Type.Array(Type.String())), + tradeoffs: Type.Optional(Type.Array(Type.String())), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = await loadPlan(planRef.dir); + const updated = setInvisibleKnowledge( + p, + params as { + system?: string; + invariants?: string[]; + tradeoffs?: string[]; + }, + ); + await savePlan(updated, planRef.dir); + return { + content: [ + { type: "text" as const, text: "Invisible knowledge updated." }, + ], + }; + }, + }); +} diff --git a/src/planner/tools/qr-tools.ts b/src/planner/tools/qr-tools.ts new file mode 100644 index 0000000..bf62bda --- /dev/null +++ b/src/planner/tools/qr-tools.ts @@ -0,0 +1,232 @@ +import { Type } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { PlanRef } from "./dispatch.js"; +import type { QRFile, QRSeverity, QRItemStatus } from "../qr/types.js"; +import { addQRItem, setQRItem, assignGroup } from "../qr/mutate.js"; + +function createEmptyQRFile(phase: string): QRFile { + return { + phase, + iteration: 1, + items: [], + }; +} + +async function loadQR(dir: string, phase: string): Promise { + const qrPath = path.join(dir, `qr-${phase}.json`); + try { + const content = await fs.readFile(qrPath, "utf8"); + return JSON.parse(content) as QRFile; + } catch (err: unknown) { + if ((err as NodeJS.ErrnoException).code === "ENOENT") { + return createEmptyQRFile(phase); + } + throw err; + } +} + +async function saveQR(qr: QRFile, dir: string, phase: string): Promise { + const qrPath = path.join(dir, `qr-${phase}.json`); + const tmpPath = path.join(dir, `.qr-${phase}.json.tmp`); + const content = `${JSON.stringify(qr, null, 2)}\n`; + await fs.writeFile(tmpPath, content, "utf8"); + await fs.rename(tmpPath, qrPath); +} + +export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { + pi.registerTool({ + name: "koan_qr_add_item", + label: "Add QR item", + description: "Add quality review item.", + parameters: Type.Object({ + phase: Type.String(), + scope: Type.String(), + check: Type.String(), + severity: Type.Optional( + Type.Union([ + Type.Literal("MUST"), + Type.Literal("SHOULD"), + Type.Literal("COULD"), + ]), + ), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = params as { + phase: string; + scope: string; + check: string; + severity?: QRSeverity; + }; + const qr = await loadQR(planRef.dir, p.phase); + const r = addQRItem(qr, p); + await saveQR(r.qr, planRef.dir, p.phase); + return { + content: [{ type: "text" as const, text: `Added QR item ${r.id}` }], + }; + }, + }); + + pi.registerTool({ + name: "koan_qr_set_item", + label: "Update QR item", + description: "Update QR item status or finding.", + parameters: Type.Object({ + phase: Type.String(), + id: Type.String(), + status: Type.Optional( + Type.Union([ + Type.Literal("TODO"), + Type.Literal("PASS"), + Type.Literal("FAIL"), + ]), + ), + finding: Type.Optional(Type.String()), + check: Type.Optional(Type.String()), + severity: Type.Optional( + Type.Union([ + Type.Literal("MUST"), + Type.Literal("SHOULD"), + Type.Literal("COULD"), + ]), + ), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = params as { + phase: string; + id: string; + status?: QRItemStatus; + finding?: string; + check?: string; + severity?: QRSeverity; + }; + const qr = await loadQR(planRef.dir, p.phase); + const updated = setQRItem(qr, p.id, p); + await saveQR(updated, planRef.dir, p.phase); + return { + content: [{ type: "text" as const, text: `Updated QR item ${p.id}` }], + }; + }, + }); + + pi.registerTool({ + name: "koan_qr_assign_group", + label: "Assign QR group", + description: "Assign group ID to QR items.", + parameters: Type.Object({ + phase: Type.String(), + ids: Type.Array(Type.String()), + group_id: Type.String(), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = params as { + phase: string; + ids: string[]; + group_id: string; + }; + const qr = await loadQR(planRef.dir, p.phase); + const updated = assignGroup(qr, p.ids, p.group_id); + await saveQR(updated, planRef.dir, p.phase); + return { + content: [ + { + type: "text" as const, + text: `Assigned ${p.ids.length} items to group ${p.group_id}`, + }, + ], + }; + }, + }); + + pi.registerTool({ + name: "koan_qr_get_item", + label: "Get QR item", + description: "Get QR item by ID.", + parameters: Type.Object({ + phase: Type.String(), + id: Type.String(), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = params as { phase: string; id: string }; + const qr = await loadQR(planRef.dir, p.phase); + const item = qr.items.find((x) => x.id === p.id); + if (!item) throw new Error(`QR item ${p.id} not found`); + return { + content: [{ type: "text" as const, text: JSON.stringify(item, null, 2) }], + }; + }, + }); + + pi.registerTool({ + name: "koan_qr_list_items", + label: "List QR items", + description: "List QR items, optionally filtered by status.", + parameters: Type.Object({ + phase: Type.String(), + status: Type.Optional( + Type.Union([ + Type.Literal("TODO"), + Type.Literal("PASS"), + Type.Literal("FAIL"), + ]), + ), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = params as { phase: string; status?: QRItemStatus }; + const qr = await loadQR(planRef.dir, p.phase); + const filtered = p.status + ? qr.items.filter((item) => item.status === p.status) + : qr.items; + return { + content: [ + { type: "text" as const, text: JSON.stringify(filtered, null, 2) }, + ], + }; + }, + }); + + pi.registerTool({ + name: "koan_qr_summary", + label: "QR summary", + description: "Get QR summary with counts by status and severity.", + parameters: Type.Object({ + phase: Type.String(), + }), + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const p = params as { phase: string }; + const qr = await loadQR(planRef.dir, p.phase); + + const byStatus = { + TODO: qr.items.filter((x) => x.status === "TODO").length, + PASS: qr.items.filter((x) => x.status === "PASS").length, + FAIL: qr.items.filter((x) => x.status === "FAIL").length, + }; + + const bySeverity = { + MUST: qr.items.filter((x) => x.severity === "MUST").length, + SHOULD: qr.items.filter((x) => x.severity === "SHOULD").length, + COULD: qr.items.filter((x) => x.severity === "COULD").length, + }; + + const summary = { + total: qr.items.length, + by_status: byStatus, + by_severity: bySeverity, + }; + + return { + content: [ + { type: "text" as const, text: JSON.stringify(summary, null, 2) }, + ], + }; + }, + }); +} diff --git a/src/planner/tools/registry.ts b/src/planner/tools/registry.ts new file mode 100644 index 0000000..36391c1 --- /dev/null +++ b/src/planner/tools/registry.ts @@ -0,0 +1,190 @@ +// Default-deny permissions. Read tools bypass this map. Write tools +// (edit/write) always blocked during planning. The map defines OUTER +// boundaries; phase handlers narrow further. + +const READ_TOOLS = new Set(["read", "bash", "grep", "glob", "find", "ls"]); +const WRITE_TOOLS = new Set(["edit", "write"]); + +const PLAN_GETTER_TOOLS_LIST = [ + "koan_get_plan", + "koan_get_milestone", + "koan_get_decision", + "koan_get_intent", + "koan_get_change", +]; + +const PLAN_SETTER_TOOLS_LIST = [ + "koan_set_overview", + "koan_set_constraints", + "koan_set_invisible_knowledge", +]; + +const PLAN_DECISION_TOOLS_LIST = ["koan_add_decision", "koan_set_decision"]; + +const PLAN_REJECTED_ALT_TOOLS_LIST = [ + "koan_add_rejected_alternative", + "koan_set_rejected_alternative", +]; + +const PLAN_RISK_TOOLS_LIST = ["koan_add_risk", "koan_set_risk"]; + +const PLAN_MILESTONE_TOOLS_LIST = [ + "koan_add_milestone", + "koan_set_milestone_name", + "koan_set_milestone_files", + "koan_set_milestone_flags", + "koan_set_milestone_requirements", + "koan_set_milestone_acceptance_criteria", + "koan_set_milestone_tests", +]; + +const PLAN_INTENT_TOOLS_LIST = ["koan_add_intent", "koan_set_intent"]; + +const PLAN_CHANGE_TOOLS_LIST = [ + "koan_add_change", + "koan_set_change_diff", + "koan_set_change_doc_diff", + "koan_set_change_comments", + "koan_set_change_file", + "koan_set_change_intent_ref", +]; + +const PLAN_WAVE_TOOLS_LIST = ["koan_add_wave", "koan_set_wave_milestones"]; + +const PLAN_DIAGRAM_TOOLS_LIST = [ + "koan_add_diagram", + "koan_set_diagram", + "koan_add_diagram_node", + "koan_add_diagram_edge", +]; + +const PLAN_README_TOOLS_LIST = ["koan_set_readme_entry"]; + +const QR_TOOLS_LIST = [ + "koan_qr_add_item", + "koan_qr_set_item", + "koan_qr_assign_group", + "koan_qr_get_item", + "koan_qr_list_items", + "koan_qr_summary", +]; + +const ALL_PLAN_ENTITY_TOOLS = [ + ...PLAN_DECISION_TOOLS_LIST, + ...PLAN_REJECTED_ALT_TOOLS_LIST, + ...PLAN_RISK_TOOLS_LIST, + ...PLAN_MILESTONE_TOOLS_LIST, + ...PLAN_INTENT_TOOLS_LIST, + ...PLAN_WAVE_TOOLS_LIST, + ...PLAN_DIAGRAM_TOOLS_LIST, + ...PLAN_README_TOOLS_LIST, +]; + +const PLAN_DESIGN_ENTITY_TOOLS = ALL_PLAN_ENTITY_TOOLS.filter( + (t) => !PLAN_CHANGE_TOOLS_LIST.includes(t), +); + +export const PLAN_GETTER_TOOLS: ReadonlySet = new Set( + PLAN_GETTER_TOOLS_LIST, +); + +export const PLAN_MUTATION_TOOLS: ReadonlySet = new Set([ + ...PLAN_SETTER_TOOLS_LIST, + ...ALL_PLAN_ENTITY_TOOLS, + ...PLAN_CHANGE_TOOLS_LIST, +]); + +// Missing phase keys are blocked (default-deny extends to unknown phases). +// Prevents security boundary breach when a new phase is added without +// updating the permissions map. +export const PHASE_PERMISSIONS: ReadonlyMap> = + new Map([ + ["context-capture", new Set(["koan_store_context", "koan_next_step"])], + [ + "plan-design", + new Set([ + "koan_next_step", + ...PLAN_GETTER_TOOLS_LIST, + ...PLAN_SETTER_TOOLS_LIST, + ...PLAN_DESIGN_ENTITY_TOOLS, + ]), + ], + [ + "plan-code", + new Set([ + "koan_next_step", + ...PLAN_GETTER_TOOLS_LIST, + ...PLAN_CHANGE_TOOLS_LIST, + "koan_set_intent", + ]), + ], + [ + "plan-docs", + new Set([ + "koan_next_step", + ...PLAN_GETTER_TOOLS_LIST, + "koan_set_change_doc_diff", + "koan_set_change_comments", + "koan_set_readme_entry", + "koan_set_diagram", + ]), + ], + [ + "qr-plan-design", + new Set(["koan_next_step", ...PLAN_GETTER_TOOLS_LIST, ...QR_TOOLS_LIST]), + ], + [ + "qr-plan-code", + new Set([ + "koan_next_step", + "koan_get_plan", + "koan_get_milestone", + "koan_get_intent", + "koan_get_change", + ...QR_TOOLS_LIST, + ]), + ], + [ + "qr-plan-docs", + new Set([ + "koan_next_step", + "koan_get_plan", + "koan_get_milestone", + "koan_get_change", + ...QR_TOOLS_LIST, + ]), + ], + ]); + +export function checkPermission( + phaseKey: string, + toolName: string, +): { allowed: boolean; reason?: string } { + if (READ_TOOLS.has(toolName)) { + return { allowed: true }; + } + + if (WRITE_TOOLS.has(toolName)) { + return { + allowed: false, + reason: "Edit/write tools blocked during planning.", + }; + } + + if (!PHASE_PERMISSIONS.has(phaseKey)) { + return { + allowed: false, + reason: `Unknown phase: ${phaseKey}`, + }; + } + + const allowed = PHASE_PERMISSIONS.get(phaseKey)!; + if (!allowed.has(toolName)) { + return { + allowed: false, + reason: `${toolName} is not available in phase ${phaseKey}`, + }; + } + + return { allowed: true }; +} diff --git a/src/planner/types.ts b/src/planner/types.ts new file mode 100644 index 0000000..2a71e39 --- /dev/null +++ b/src/planner/types.ts @@ -0,0 +1,21 @@ +export interface ContextData { + task_spec: string[]; + constraints: string[]; + entry_points: string[]; + rejected_alternatives: string[]; + current_understanding: string[]; + assumptions: string[]; + invisible_knowledge: string[]; + reference_docs: string[]; +} + +export const CONTEXT_KEYS: ReadonlyArray = [ + "task_spec", + "constraints", + "entry_points", + "rejected_alternatives", + "current_understanding", + "assumptions", + "invisible_knowledge", + "reference_docs", +]; diff --git a/src/utils/logger.ts b/src/utils/logger.ts new file mode 100644 index 0000000..67f4c2e --- /dev/null +++ b/src/utils/logger.ts @@ -0,0 +1,14 @@ +const prefix = "[koan]"; + +export type Logger = | undefined>(message: string, details?: T) => void; + +export function createLogger(scope: string): Logger { + const label = `${prefix} ${scope}`; + return (message, details) => { + if (details && Object.keys(details).length > 0) { + console.log(`${label}: ${message}`, details); + } else { + console.log(`${label}: ${message}`); + } + }; +} diff --git a/src/utils/plan.ts b/src/utils/plan.ts new file mode 100644 index 0000000..a34f382 --- /dev/null +++ b/src/utils/plan.ts @@ -0,0 +1,72 @@ +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import type { PlanInfo } from "../planner/state.js"; + +const KOAN_HOME = path.join(os.homedir(), ".koan"); +const PLANS_HOME = path.join(KOAN_HOME, "plans"); + +function slugify(input: string): string { + const base = input + .toLowerCase() + .replace(/[^a-z0-9]+/g, "-") + .replace(/^-+|-+$/g, "") + .slice(0, 48); + + return base.length > 0 ? base : "plan"; +} + +function generatePlanId(description: string, now: Date): string { + const timestamp = now.toISOString().replace(/[-:]/g, "").replace(/\..+/, ""); + const slug = slugify(description); + return `${timestamp}-${slug}`; +} + +async function ensurePlanDirectoryUnique(baseId: string): Promise<{ id: string; directory: string }> { + let suffix = 0; + while (true) { + const candidateId = suffix === 0 ? baseId : `${baseId}-${suffix}`; + const directory = path.join(PLANS_HOME, candidateId); + + try { + await fs.mkdir(directory, { recursive: false }); + return { id: candidateId, directory }; + } catch (error) { + const err = error as NodeJS.ErrnoException; + if (err.code === "EEXIST") { + suffix += 1; + continue; + } + throw error; + } + } +} + +export async function createPlanInfo(description: string, projectCwd: string, now = new Date()): Promise { + await fs.mkdir(PLANS_HOME, { recursive: true }); + + const baseId = generatePlanId(description, now); + const { id, directory } = await ensurePlanDirectoryUnique(baseId); + + const metadataPath = path.join(directory, "metadata.json"); + + const plan: PlanInfo = { + id, + directory, + metadataPath, + createdAt: now.toISOString(), + }; + + const metadata = { + id: plan.id, + createdAt: plan.createdAt, + description, + status: "created" as const, + projectCwd, + }; + + await fs.writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8"); + + return plan; +} diff --git a/src/utils/progress.ts b/src/utils/progress.ts new file mode 100644 index 0000000..566bda8 --- /dev/null +++ b/src/utils/progress.ts @@ -0,0 +1,71 @@ +import { promises as fs } from "node:fs"; +import * as crypto from "node:crypto"; +import * as path from "node:path"; + +export interface TrailEntry { + at: string; + msg: string; +} + +export interface SubagentState { + role: string; + phase: string; + status: "running" | "completed" | "failed"; + current: string; + updated_at: string; + trail: TrailEntry[]; +} + +export async function createSubagentDir(planDir: string, role: string): Promise { + const hex = crypto.randomBytes(2).toString("hex"); + const dir = path.join(planDir, "subagents", `${role}-${hex}`); + await fs.mkdir(dir, { recursive: true }); + return dir; +} + +export class ProgressReporter { + private readonly stateFile: string; + private readonly state: SubagentState; + + constructor(dir: string, role: string, phase: string) { + this.stateFile = path.join(dir, "state.json"); + this.state = { + role, + phase, + status: "running", + current: "", + updated_at: new Date().toISOString(), + trail: [], + }; + } + + async update(msg: string): Promise { + const now = new Date().toISOString(); + this.state.current = msg; + this.state.updated_at = now; + this.state.trail.push({ at: now, msg }); + await this.flush(); + } + + async complete(status: "completed" | "failed"): Promise { + const now = new Date().toISOString(); + this.state.status = status; + this.state.current = status; + this.state.updated_at = now; + this.state.trail.push({ at: now, msg: status }); + await this.flush(); + } + + private async flush(): Promise { + await fs.writeFile(this.stateFile, JSON.stringify(this.state, null, 2) + "\n"); + } +} + +export async function readSubagentState(dir: string): Promise { + try { + const raw = await fs.readFile(path.join(dir, "state.json"), "utf8"); + return JSON.parse(raw) as SubagentState; + } catch { + return null; + } +} From 28a65128f57512c8a612ff124c129609ecbc2d28 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Feb 2026 12:54:02 +0700 Subject: [PATCH 002/412] Fix step gate to use blocklist instead of whitelist The whitelist pattern (!PLAN_GETTER_TOOLS.has(name)) blocked read tools and future pi-native tools that checkPermission already approved. Switch to blocklist (PLAN_MUTATION_TOOLS.has(name)) so only mutation tools are step-gated and everything else defers to checkPermission. --- src/planner/phases/plan-design.ts | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/planner/phases/plan-design.ts b/src/planner/phases/plan-design.ts index 4e90d39..8928616 100644 --- a/src/planner/phases/plan-design.ts +++ b/src/planner/phases/plan-design.ts @@ -16,7 +16,7 @@ import type { ContextData } from "../types.js"; import { createLogger, type Logger } from "../../utils/logger.js"; import { ProgressReporter } from "../../utils/progress.js"; import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../tools/dispatch.js"; -import { checkPermission, PLAN_GETTER_TOOLS } from "../tools/registry.js"; +import { checkPermission, PLAN_MUTATION_TOOLS } from "../tools/registry.js"; type PlanDesignStep = 1 | 2 | 3 | 4 | 5 | 6; @@ -132,8 +132,11 @@ export class PlanDesignPhase { return { block: true, reason: perm.reason }; } + // Step gate: mutation tools are step-6-only. Blocklist (not whitelist) + // so read tools and future pi-native tools pass through after + // checkPermission approves them. const step = this.state.step; - if (step < 6 && !PLAN_GETTER_TOOLS.has(event.toolName) && event.toolName !== "koan_next_step") { + if (step < 6 && PLAN_MUTATION_TOOLS.has(event.toolName)) { return { block: true, reason: `${event.toolName} available in step 6 (current: ${step})`, From 25a9047c4937b530491d0f87288422bcfec392ac Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Feb 2026 13:05:59 +0700 Subject: [PATCH 003/412] Fix async/sync mismatch in onNextStep dispatch handleStepComplete() is async but the dispatch slot was typed synchronous. Every koan_next_step call checked .ok on the raw Promise (undefined), unconditionally throwing "Step transition failed." --- src/planner/tools/dispatch.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/planner/tools/dispatch.ts b/src/planner/tools/dispatch.ts index ee9fd5d..28e91b8 100644 --- a/src/planner/tools/dispatch.ts +++ b/src/planner/tools/dispatch.ts @@ -25,7 +25,7 @@ export interface StepResult { // -- Dispatch -- export interface WorkflowDispatch { - onNextStep: (() => StepResult) | null; + onNextStep: (() => StepResult | Promise) | null; onStoreContext: | ((payload: unknown, ctx: ExtensionContext) => Promise) | null; @@ -102,7 +102,7 @@ export function registerWorkflowTools( if (!dispatch.onNextStep) { throw new Error("No workflow phase is active."); } - const r = dispatch.onNextStep(); + const r = await dispatch.onNextStep(); if (!r.ok) { throw new Error(r.error ?? "Step transition failed."); } From 11d9a97a38a7c1f3d1f69543020d7589b90435fa Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Feb 2026 16:43:47 +0700 Subject: [PATCH 004/412] Rename koan_next_step to koan_complete_step with thoughts param GPT-5-codex cannot produce text + tool_call in the same response, causing it to narrate "Calling koan_next_step now" as text without emitting an actual tool_call block. The thoughts parameter captures the model's work output (analysis, findings) as a tool parameter instead of requiring text output alongside the tool call. Also: remove agent_end retry handler (unreliable in -p mode), improve type safety with Static (eliminates manual casts), add tsconfig.json and devDependencies for tsc --noEmit checks. --- design-decisions.md | 342 ++ package-lock.json | 4044 ++++++++++++++++++++++++ package.json | 11 +- src/planner/phases/context-capture.ts | 85 +- src/planner/phases/plan-design.ts | 6 +- src/planner/prompts/context-capture.ts | 9 +- src/planner/prompts/plan-design.ts | 14 +- src/planner/prompts/step.ts | 23 +- src/planner/session.ts | 4 +- src/planner/tools/dispatch.ts | 48 +- src/planner/tools/plan-entities.ts | 16 +- src/planner/tools/plan-getters.ts | 21 +- src/planner/tools/plan-setters.ts | 24 +- src/planner/tools/qr-tools.ts | 66 +- src/planner/tools/registry.ts | 14 +- tsconfig.json | 15 + 16 files changed, 4528 insertions(+), 214 deletions(-) create mode 100644 design-decisions.md create mode 100644 package-lock.json create mode 100644 tsconfig.json diff --git a/design-decisions.md b/design-decisions.md new file mode 100644 index 0000000..7a10117 --- /dev/null +++ b/design-decisions.md @@ -0,0 +1,342 @@ +# Koan Design Decisions & Invariants + +Authoritative record of design decisions, invariants, and lessons learned +across the koan project. Distilled from 6 conversations (Feb 10-13 2026), +the master plan (plans/2026-02-10-init.md), and the approved tool registry +plan (~/.claude/plans/fluffy-hopping-zebra.md). + +--- + +## Fundamental Invariants + +### INV-1: Inversion of Control + +Scripts drive the LLM, not LLM drives scripts. The extension +programmatically feeds prompts, collects output, and enforces constraints. +The LLM is a worker, not a coordinator. This is the entire reason koan +exists -- the Claude Code skill model has the LLM in the driver's seat, +which causes unreliable workflow execution. + +### INV-2: Need-to-Know Principle + +The LLM always operates on a need-to-know basis. When given the choice +between exposing more or less information, always choose less. This is +a permanent invariant. + +Concrete implications: +- No implementation details in prompts (temp dirs, state file paths, + orchestrator internals, phase routing) +- No full plan state when partial suffices (QR reviewer for design does + not see code plan or docs plan) +- No accumulated history across phases (subagents start fresh) +- No meta-instructions about the workflow ("you are step 3 of 14") +- No defensive over-specification of edge cases + +### INV-3: Pi Tool Error Contract + +Pi framework determines isError on ToolResultMessage from whether +tool.execute() THROWS, not from the return value. The returned isError +field is silently discarded (agent-loop.ts:316-357). To signal errors +from tools: always `throw new Error(msg)` -- never `return { isError: true }`. + +--- + +## Architecture Decisions + +### AD-1: Two LLM Interaction Levels + +- `sendUserMessage()` in parent session: ONLY for context capture. The + session LLM is the only entity with the conversational understanding. + A fresh LLM reading a serialized transcript loses implicit context. +- `spawn()` subagent: for all substantial work (architect, developer, + writer, QR decomposer, QR reviewer). +- `complete()` from pi-ai: NOT used in koan. No direct LLM calls + without agent loop. + +### AD-2: Self-Loading Extension Pattern + +Same extension file (extensions/koan.ts) serves both modes: +- **Parent mode** (no --koan-role flag): registers /koan command, tools, + and dispatch. Zero overhead in normal pi sessions. +- **Subagent mode** (--koan-role present): activates role-specific event + hooks (state machine, tool enforcement, step prompts). + +The extension detects which mode via flag presence at before_agent_start +time (not at init -- see AD-3). + +### AD-3: CLI Flag Timing + +Pi applies CLI flag values AFTER extension factory functions run +(main.ts:568). getFlag() returns defaults during factory time. +Subagent detection MUST happen in `before_agent_start`, not in the +factory function body. Uses closure-scoped `dispatched` boolean guard +to ensure one-shot dispatch. + +### AD-4: Tool-Call-Driven Step Transitions (Uniform Pattern) + +ALL step transitions use the koan_next_step registered tool. The LLM +calls koan_next_step -> tool execute() returns next step's prompt. +This works in both -p mode and interactive mode. sendUserMessage() +is only used for the initial trigger (/koan plan) and as a safety net +in agent_end when the LLM fails to call the expected tool. + +**KEY CORRECTION**: Early design (Feb 10) considered turn_end + agent_end ++ sendUserMessage() chaining for step transitions. This was ABANDONED +because subagents in -p mode exit after the first agent loop completes. +Tool calls keep the agent loop alive within a single loop. The context +capture phase preserves sendUserMessage() in agent_end only as a +fallback retry mechanism, not as the primary transition path. + +### AD-5: koan_next_step Has No Arguments + +The extension is stateful -- it knows exactly which step the LLM is on +via closure state. No step number parameter needed. The tool response +contains the next step's full prompt. + +### AD-6: Tool Naming Conventions + +Settled names (corrected from earlier iterations): +- `koan_next_step` (was koan_complete_step) +- `koan_store_context` (was koan_finalize_context) +- `koan_store_plan` was later REMOVED entirely (see AD-14) +- Prompts use "instructions" not "actions" + +### AD-7: invoke_after Pattern Is Critical + +Every step prompt MUST have a clear "invoke after" directive telling +the LLM to call koan_next_step after completing the step's work. +Mirrors the reference planner's "NEXT STEP: Command: python3 -m ... +--step N" pattern. Without this, the LLM produces text-only responses +and the agent loop exits. + +Implementation: formatStep() in src/planner/prompts/step.ts appends a +default invoke-after block. Steps can override with custom invokeAfter. + +The "WHEN DONE" + "Do NOT call until" creates a two-part gate: the LLM +must do work before advancing. Unconditional imperatives ("Execute this +tool now.") cause immediate tool calls because empty-param tool calls +have zero friction. + +### AD-8: Store Tools Need "Not Yet" Guidance + +koan_store_context (and formerly koan_store_plan) are always registered +and visible to the LLM even in steps where they should NOT be called. +Their tool descriptions include "DO NOT call this tool until the step +instructions explicitly tell you to." This creates a prohibition/activation +pattern with step prompts. + +### AD-9: Subagent Progress Tracking + +Per-subagent state directory, NOT a single progress.json. +Structure: `/subagents/-/` +Contains: state.json, stdout.log, stderr.log. +ProgressReporter class manages state.json updates with trail. + +### AD-10: Architect System Prompt + +The architect's system prompt is loaded from ~/.claude/agents/architect.md +at runtime via loadPlanDesignSystemPrompt(). Injected via +before_agent_start returning { systemPrompt: ... }. + +### AD-11: Plan Schema Self-Documentation via TypeBox + +No 300-line schema prompt embedded in step 6. Tool parameter schemas +with rich TypeBox descriptions are sufficient for the LLM to discover +the schema through tool definitions. This is the "most elegant" approach +per user preference. + +### AD-12: Context Capture Phases + +Three sub-phases within context capture: +1. **Drafting**: LLM reflects on conversation. MAY use tools for "high + value" targeted exploration (confirm API signature, check file existence). + DO NOT explore speculatively. Confidence tagging: HIGH (direct evidence) + vs LOW (extrapolating). +2. **Verifying**: Self-check. Completeness, accuracy, phrasing for + downstream agents. No tools except koan_next_step. +3. **Refining**: Pure tool invocation (koan_store_context). Up to 3 + attempts with validation feedback. + +### AD-13: Default-Deny Tool Permissions + +Centralized Map> in src/planner/tools/registry.ts. +Unknown tools blocked in all phases. READ_TOOLS (read, bash, grep, glob, +find, ls) always allowed. WRITE_TOOLS (edit, write) always blocked during +planning. Missing phase keys are denied. + +Previous code had a "fails open" bug where tool_call handlers returned +undefined at the end of if-else chains, silently allowing unknown tools. + +### AD-14: Disk-Backed Plan Mutations (No Finalize) + +Each mutation tool: loadPlan(dir) -> mutate -> savePlan(plan, dir). +Atomic write. No in-memory accumulation + finalize pattern. The +koan_store_plan/koan_finalize_plan tool was REMOVED. + +Root cause: the LLM was skipping intermediate mutation tools and calling +koan_store_plan directly. The "build in memory then finalize" pattern +makes intermediate tools feel like ceremony. Immediate disk writes give +visible results per tool call. + +Every mutation tool returns descriptive feedback ("Added decision DL-003: +'Use polling'"). This prevents the LLM from skipping tools -- the LLM +needs evidence that each tool call produces results. + +### AD-15: Module Ownership + +- Context-capture prompts belong to the "orchestrator" (session.ts / + context-capture.ts) +- Plan-design prompts belong to the "architect" (plan-design.ts / + prompts/plan-design.ts) +- These are organizational decisions about which module owns which prompts + +### AD-16: 6-Step Architect Workflow (plan-design execute) + +1. Task Analysis & Exploration Planning +2. Codebase Exploration +3. Testing Strategy Discovery +4. Approach Generation +5. Assumption Surfacing +6. Milestone Definition & Plan Writing (plan mutation tools available) + +Steps 1-5: only READ_TOOLS + PLAN_GETTER_TOOLS + koan_next_step allowed. +Step 6: plan mutation tools unlocked. + +--- + +## Workflow Dispatch Architecture + +### WorkflowDispatch (dispatch pattern) + +Workflow tools (koan_next_step, koan_store_context) are registered once +at init. Their execute() callbacks read from a mutable dispatch object. +Phases hook/unhook dispatch slots at activation/deactivation time. + +hookDispatch() throws if a slot is already occupied -- prevents silent +misrouting when two phases try to claim the same tool. + +### PlanRef (mutable reference) + +All plan mutation tools share a mutable `{ dir: string | null }` set +when /koan plan creates a directory or when --koan-plan-dir is received. +Decouples tool registration (init-time) from directory creation (runtime). + +### Pi Registers Tools at _buildRuntime() + +Pi snapshots tools during _buildRuntime(). Tools registered after this +point are invisible to the LLM. All 44+ tools register unconditionally +at init; phases restrict access via tool_call blocking at runtime. + +--- + +## What Is NOT Ported from Reference Planner + +| Reference planner component | Koan replacement | +|----|-----| +| CLI mutation scripts (cli/plan.py) | Pi extension tool registration | +| Thin router pattern (shared/routing.py) | Orchestrator deterministic gate logic | +| File-based state_dir | In-memory state + appendEntry() | +| Template dispatch | Direct process spawning | +| Constraint enforcement via prompt | tool_call event blocking | +| Agent markdown definitions | Self-loading extension pattern | +| Question relay handler | Not implemented (may add later) | + +--- + +## Bugs & Lessons Learned + +### BUG-1: LLM Conflates Tool Instructions with Plan Content + +In context capture, the LLM captured tool usage instructions as +constraints (e.g. "Use read tool before modifying files; edit for +surgical changes"). These are irrelevant developer instructions, not +task constraints. Solution: prompts explicitly state "Only include +constraints that are specific to this task. Do not include general +tool usage instructions, coding style guides, or editor/IDE conventions." + +### BUG-2: LLM Skips Mutation Tools + +The LLM called koan_next_step through steps 1-5, then at step 6 skipped +all mutation tools and called koan_store_plan directly. The in-memory +plan was empty. Root cause: mutation tools returned opaque JSON with no +feedback -- they felt like ceremony. Solution: remove finalize tool, +disk-backed mutations, descriptive feedback per tool call (AD-14). + +### BUG-3: tool_call Handlers Fail Open + +Original tool_call handlers returned undefined at end of if-else chains, +silently allowing any new tool. Solution: default-deny permissions map +(AD-13). + +### BUG-4: isError Return Value Discarded + +Pi discards the isError field from tool return values. Only throw/no-throw +determines error status. This caused silent failures where tools returned +{ isError: true } but the framework treated them as success. Solution: +always throw new Error(msg) for error conditions (INV-3). + +### BUG-5: Weak invoke_after Causes Step Skipping + +Original weak format ("Now call koan_next_step.") produced skipped steps. +The LLM called the tool immediately without doing work, because tool +calls with empty params have zero friction. Solution: strengthen to +"WHEN DONE: After completing the instructions above, call koan_next_step. +Do NOT call this tool until the work described in this step is finished." + +### BUG-6: Flag Detection at Init Time + +Early implementation tried to detect --koan-role in the extension factory +function body. Flags are unavailable at that point (main.ts:568 sets them +after). Solution: move detection to before_agent_start with dispatched +guard (AD-3). + +--- + +## Plan JSON Schema + +Matches reference planner's Pydantic schema (shared/schema.py). +Types defined in src/planner/plan/types.ts. + +Key entities: Plan, Decision, RejectedAlternative, Risk, Milestone, +CodeIntent, CodeChange, Wave, DiagramGraph, ReadmeEntry, Overview, +InvisibleKnowledge, PlanningContext. + +Cross-reference validation: intent_ref -> intents, decision_ref -> +decisions, diagram edges source/target -> nodes, wave milestones -> milestone IDs. + +--- + +## QR Block Pattern + +Work -> Decompose -> Verify (parallel) -> Gate. Repeated per phase +(design, code, docs). Gate is deterministic code, no LLM. Max 5 +iterations. Force-proceed after limit. + +QR tools: koan_qr_add_item, koan_qr_set_item, koan_qr_assign_group, +koan_qr_get_item, koan_qr_list_items, koan_qr_summary. + +--- + +## Current Implementation State (Feb 13 2026) + +Implemented: +- [x] Extension entry point with dual-mode detection +- [x] Context capture (3-phase: draft/verify/refine) +- [x] Plan-design architect subagent (6-step workflow) +- [x] 44+ plan mutation/getter tools with TypeBox schemas +- [x] Default-deny tool permissions (registry.ts) +- [x] WorkflowDispatch + PlanRef patterns +- [x] Subagent spawning with progress tracking +- [x] Disk-backed plan mutations (no finalize) +- [x] Plan validation (design + cross-references) + +Not yet implemented: +- [ ] Developer role (plan-code phase) +- [ ] Technical writer role (plan-docs phase) +- [ ] QR decompose subagent +- [ ] QR verify subagent (parallel) +- [ ] QR gate routing +- [ ] Fix mode (re-spawn with QR failure report) +- [ ] State persistence (appendEntry + session_start restore) +- [ ] Plan execution workflow (milestone execution) +- [ ] /koan execute command diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..3859420 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,4044 @@ +{ + "name": "@solatis/koan", + "version": "0.0.1", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@solatis/koan", + "version": "0.0.1", + "license": "Apache-2.0", + "dependencies": { + "@sinclair/typebox": "^0.32.30" + }, + "devDependencies": { + "@mariozechner/pi-coding-agent": "^0.52.10", + "typescript": "^5.9.3" + } + }, + "node_modules/@anthropic-ai/sdk": { + "version": "0.73.0", + "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.73.0.tgz", + "integrity": "sha512-URURVzhxXGJDGUGFunIOtBlSl7KWvZiAAKY/ttTkZAkXT9bTPqdk2eK0b8qqSxXpikh3QKPnPYpiyX98zf5ebw==", + "dev": true, + "license": "MIT", + "dependencies": { + "json-schema-to-ts": "^3.1.1" + }, + "bin": { + "anthropic-ai-sdk": "bin/cli" + }, + "peerDependencies": { + "zod": "^3.25.0 || ^4.0.0" + }, + "peerDependenciesMeta": { + "zod": { + "optional": true + } + } + }, + "node_modules/@aws-crypto/crc32": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/crc32/-/crc32-5.2.0.tgz", + "integrity": "sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=16.0.0" + } + }, + "node_modules/@aws-crypto/sha256-browser": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-browser/-/sha256-browser-5.2.0.tgz", + "integrity": "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-js": "^5.2.0", + "@aws-crypto/supports-web-crypto": "^5.2.0", + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "@aws-sdk/util-locate-window": "^3.0.0", + "@smithy/util-utf8": "^2.0.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/is-array-buffer": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz", + "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/util-buffer-from": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz", + "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/util-utf8": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz", + "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/sha256-js": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-js/-/sha256-js-5.2.0.tgz", + "integrity": "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=16.0.0" + } + }, + "node_modules/@aws-crypto/supports-web-crypto": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/supports-web-crypto/-/supports-web-crypto-5.2.0.tgz", + "integrity": "sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-crypto/util": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/util/-/util-5.2.0.tgz", + "integrity": "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.222.0", + "@smithy/util-utf8": "^2.0.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-crypto/util/node_modules/@smithy/is-array-buffer": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz", + "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/util/node_modules/@smithy/util-buffer-from": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz", + "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/util/node_modules/@smithy/util-utf8": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz", + "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-sdk/client-bedrock-runtime": { + "version": "3.989.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-bedrock-runtime/-/client-bedrock-runtime-3.989.0.tgz", + "integrity": "sha512-qVa5B0wXjIuPRhX1dcZo1sa9Y4ycI9tiqK7B4FLok67gUWckiKmEf1xQDFrTmc2eCK5g0CTaeiRdbeM1eWmW1Q==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/credential-provider-node": "^3.972.8", + "@aws-sdk/eventstream-handler-node": "^3.972.5", + "@aws-sdk/middleware-eventstream": "^3.972.3", + "@aws-sdk/middleware-host-header": "^3.972.3", + "@aws-sdk/middleware-logger": "^3.972.3", + "@aws-sdk/middleware-recursion-detection": "^3.972.3", + "@aws-sdk/middleware-user-agent": "^3.972.9", + "@aws-sdk/middleware-websocket": "^3.972.6", + "@aws-sdk/region-config-resolver": "^3.972.3", + "@aws-sdk/token-providers": "3.989.0", + "@aws-sdk/types": "^3.973.1", + "@aws-sdk/util-endpoints": "3.989.0", + "@aws-sdk/util-user-agent-browser": "^3.972.3", + "@aws-sdk/util-user-agent-node": "^3.972.7", + "@smithy/config-resolver": "^4.4.6", + "@smithy/core": "^3.23.0", + "@smithy/eventstream-serde-browser": "^4.2.8", + "@smithy/eventstream-serde-config-resolver": "^4.3.8", + "@smithy/eventstream-serde-node": "^4.2.8", + "@smithy/fetch-http-handler": "^5.3.9", + "@smithy/hash-node": "^4.2.8", + "@smithy/invalid-dependency": "^4.2.8", + "@smithy/middleware-content-length": "^4.2.8", + "@smithy/middleware-endpoint": "^4.4.14", + "@smithy/middleware-retry": "^4.4.31", + "@smithy/middleware-serde": "^4.2.9", + "@smithy/middleware-stack": "^4.2.8", + "@smithy/node-config-provider": "^4.3.8", + "@smithy/node-http-handler": "^4.4.10", + "@smithy/protocol-http": "^5.3.8", + "@smithy/smithy-client": "^4.11.3", + "@smithy/types": "^4.12.0", + "@smithy/url-parser": "^4.2.8", + "@smithy/util-base64": "^4.3.0", + "@smithy/util-body-length-browser": "^4.2.0", + "@smithy/util-body-length-node": "^4.2.1", + "@smithy/util-defaults-mode-browser": "^4.3.30", + "@smithy/util-defaults-mode-node": "^4.2.33", + "@smithy/util-endpoints": "^3.2.8", + "@smithy/util-middleware": "^4.2.8", + "@smithy/util-retry": "^4.2.8", + "@smithy/util-stream": "^4.5.12", + "@smithy/util-utf8": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-sso": { + "version": "3.989.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-sso/-/client-sso-3.989.0.tgz", + "integrity": "sha512-3sC+J1ru5VFXLgt9KZmXto0M7mnV5RkS6FNGwRMK3XrojSjHso9DLOWjbnXhbNv4motH8vu53L1HK2VC1+Nj5w==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/middleware-host-header": "^3.972.3", + "@aws-sdk/middleware-logger": "^3.972.3", + "@aws-sdk/middleware-recursion-detection": "^3.972.3", + "@aws-sdk/middleware-user-agent": "^3.972.9", + "@aws-sdk/region-config-resolver": "^3.972.3", + "@aws-sdk/types": "^3.973.1", + "@aws-sdk/util-endpoints": "3.989.0", + "@aws-sdk/util-user-agent-browser": "^3.972.3", + "@aws-sdk/util-user-agent-node": "^3.972.7", + "@smithy/config-resolver": "^4.4.6", + "@smithy/core": "^3.23.0", + "@smithy/fetch-http-handler": "^5.3.9", + "@smithy/hash-node": "^4.2.8", + "@smithy/invalid-dependency": "^4.2.8", + "@smithy/middleware-content-length": "^4.2.8", + "@smithy/middleware-endpoint": "^4.4.14", + "@smithy/middleware-retry": "^4.4.31", + "@smithy/middleware-serde": "^4.2.9", + "@smithy/middleware-stack": "^4.2.8", + "@smithy/node-config-provider": "^4.3.8", + "@smithy/node-http-handler": "^4.4.10", + "@smithy/protocol-http": "^5.3.8", + "@smithy/smithy-client": "^4.11.3", + "@smithy/types": "^4.12.0", + "@smithy/url-parser": "^4.2.8", + "@smithy/util-base64": "^4.3.0", + "@smithy/util-body-length-browser": "^4.2.0", + "@smithy/util-body-length-node": "^4.2.1", + "@smithy/util-defaults-mode-browser": "^4.3.30", + "@smithy/util-defaults-mode-node": "^4.2.33", + "@smithy/util-endpoints": "^3.2.8", + "@smithy/util-middleware": "^4.2.8", + "@smithy/util-retry": "^4.2.8", + "@smithy/util-utf8": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/core": { + "version": "3.973.9", + "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.973.9.tgz", + "integrity": "sha512-cyUOfJSizn8da7XrBEFBf4UMI4A6JQNX6ZFcKtYmh/CrwfzsDcabv3k/z0bNwQ3pX5aeq5sg/8Bs/ASiL0bJaA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@aws-sdk/xml-builder": "^3.972.4", + "@smithy/core": "^3.23.0", + "@smithy/node-config-provider": "^4.3.8", + "@smithy/property-provider": "^4.2.8", + "@smithy/protocol-http": "^5.3.8", + "@smithy/signature-v4": "^5.3.8", + "@smithy/smithy-client": "^4.11.3", + "@smithy/types": "^4.12.0", + "@smithy/util-base64": "^4.3.0", + "@smithy/util-middleware": "^4.2.8", + "@smithy/util-utf8": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-env": { + "version": "3.972.7", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.7.tgz", + "integrity": "sha512-r8kBtglvLjGxBT87l6Lqkh9fL8yJJ6O4CYQPjKlj3AkCuL4/4784x3rxxXWw9LTKXOo114VB6mjxAuy5pI7XIg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/types": "^3.973.1", + "@smithy/property-provider": "^4.2.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-http": { + "version": "3.972.9", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.9.tgz", + "integrity": "sha512-40caFblEg/TPrp9EpvyMxp4xlJ5TuTI+A8H6g8FhHn2hfH2PObFAPLF9d5AljK/G69E1YtTklkuQeAwPlV3w8Q==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/types": "^3.973.1", + "@smithy/fetch-http-handler": "^5.3.9", + "@smithy/node-http-handler": "^4.4.10", + "@smithy/property-provider": "^4.2.8", + "@smithy/protocol-http": "^5.3.8", + "@smithy/smithy-client": "^4.11.3", + "@smithy/types": "^4.12.0", + "@smithy/util-stream": "^4.5.12", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-ini": { + "version": "3.972.7", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.972.7.tgz", + "integrity": "sha512-zeYKrMwM5bCkHFho/x3+1OL0vcZQ0OhTR7k35tLq74+GP5ieV3juHXTZfa2LVE0Bg75cHIIerpX0gomVOhzo/w==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/credential-provider-env": "^3.972.7", + "@aws-sdk/credential-provider-http": "^3.972.9", + "@aws-sdk/credential-provider-login": "^3.972.7", + "@aws-sdk/credential-provider-process": "^3.972.7", + "@aws-sdk/credential-provider-sso": "^3.972.7", + "@aws-sdk/credential-provider-web-identity": "^3.972.7", + "@aws-sdk/nested-clients": "3.989.0", + "@aws-sdk/types": "^3.973.1", + "@smithy/credential-provider-imds": "^4.2.8", + "@smithy/property-provider": "^4.2.8", + "@smithy/shared-ini-file-loader": "^4.4.3", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-login": { + "version": "3.972.7", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.7.tgz", + "integrity": "sha512-Q103cLU6OjAllYjX7+V+PKQw654jjvZUkD+lbUUiFbqut6gR5zwl1DrelvJPM5hnzIty7BCaxaRB3KMuz3M/ug==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/nested-clients": "3.989.0", + "@aws-sdk/types": "^3.973.1", + "@smithy/property-provider": "^4.2.8", + "@smithy/protocol-http": "^5.3.8", + "@smithy/shared-ini-file-loader": "^4.4.3", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-node": { + "version": "3.972.8", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.8.tgz", + "integrity": "sha512-AaDVOT7iNJyLjc3j91VlucPZ4J8Bw+eu9sllRDugJqhHWYyR3Iyp2huBUW8A3+DfHoh70sxGkY92cThAicSzlQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/credential-provider-env": "^3.972.7", + "@aws-sdk/credential-provider-http": "^3.972.9", + "@aws-sdk/credential-provider-ini": "^3.972.7", + "@aws-sdk/credential-provider-process": "^3.972.7", + "@aws-sdk/credential-provider-sso": "^3.972.7", + "@aws-sdk/credential-provider-web-identity": "^3.972.7", + "@aws-sdk/types": "^3.973.1", + "@smithy/credential-provider-imds": "^4.2.8", + "@smithy/property-provider": "^4.2.8", + "@smithy/shared-ini-file-loader": "^4.4.3", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-process": { + "version": "3.972.7", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.7.tgz", + "integrity": "sha512-hxMo1V3ujWWrQSONxQJAElnjredkRpB6p8SDjnvRq70IwYY38R/CZSys0IbhRPxdgWZ5j12yDRk2OXhxw4Gj3g==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/types": "^3.973.1", + "@smithy/property-provider": "^4.2.8", + "@smithy/shared-ini-file-loader": "^4.4.3", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-sso": { + "version": "3.972.7", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.972.7.tgz", + "integrity": "sha512-ZGKBOHEj8Ap15jhG2XMncQmKLTqA++2DVU2eZfLu3T/pkwDyhCp5eZv5c/acFxbZcA/6mtxke+vzO/n+aeHs4A==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/client-sso": "3.989.0", + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/token-providers": "3.989.0", + "@aws-sdk/types": "^3.973.1", + "@smithy/property-provider": "^4.2.8", + "@smithy/shared-ini-file-loader": "^4.4.3", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-web-identity": { + "version": "3.972.7", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.7.tgz", + "integrity": "sha512-AbYupBIoSJoVMlbMqBhNvPhqj+CdGtzW7Uk4ZIMBm2br18pc3rkG1VaKVFV85H87QCvLHEnni1idJjaX1wOmIw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/nested-clients": "3.989.0", + "@aws-sdk/types": "^3.973.1", + "@smithy/property-provider": "^4.2.8", + "@smithy/shared-ini-file-loader": "^4.4.3", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/eventstream-handler-node": { + "version": "3.972.5", + "resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.5.tgz", + "integrity": "sha512-xEmd3dnyn83K6t4AJxBJA63wpEoCD45ERFG0XMTViD2E/Ohls9TLxjOWPb1PAxR9/46cKy/TImez1GoqP6xVNQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@smithy/eventstream-codec": "^4.2.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-eventstream": { + "version": "3.972.3", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.3.tgz", + "integrity": "sha512-pbvZ6Ye/Ks6BAZPa3RhsNjHrvxU9li25PMhSdDpbX0jzdpKpAkIR65gXSNKmA/REnSdEMWSD4vKUW+5eMFzB6w==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@smithy/protocol-http": "^5.3.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-host-header": { + "version": "3.972.3", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-host-header/-/middleware-host-header-3.972.3.tgz", + "integrity": "sha512-aknPTb2M+G3s+0qLCx4Li/qGZH8IIYjugHMv15JTYMe6mgZO8VBpYgeGYsNMGCqCZOcWzuf900jFBG5bopfzmA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@smithy/protocol-http": "^5.3.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-logger": { + "version": "3.972.3", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-logger/-/middleware-logger-3.972.3.tgz", + "integrity": "sha512-Ftg09xNNRqaz9QNzlfdQWfpqMCJbsQdnZVJP55jfhbKi1+FTWxGuvfPoBhDHIovqWKjqbuiew3HuhxbJ0+OjgA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-recursion-detection": { + "version": "3.972.3", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-recursion-detection/-/middleware-recursion-detection-3.972.3.tgz", + "integrity": "sha512-PY57QhzNuXHnwbJgbWYTrqIDHYSeOlhfYERTAuc16LKZpTZRJUjzBFokp9hF7u1fuGeE3D70ERXzdbMBOqQz7Q==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@aws/lambda-invoke-store": "^0.2.2", + "@smithy/protocol-http": "^5.3.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-user-agent": { + "version": "3.972.9", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-user-agent/-/middleware-user-agent-3.972.9.tgz", + "integrity": "sha512-1g1B7yf7KzessB0mKNiV9gAHEwbM662xgU+VE4LxyGe6kVGZ8LqYsngjhE+Stna09CJ7Pxkjr6Uq1OtbGwJJJg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/types": "^3.973.1", + "@aws-sdk/util-endpoints": "3.989.0", + "@smithy/core": "^3.23.0", + "@smithy/protocol-http": "^5.3.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-websocket": { + "version": "3.972.6", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.6.tgz", + "integrity": "sha512-1DedO6N3m8zQ/vG6twNiHtsdwBgk773VdavLEbB3NXeKZDlzSK1BTviqWwvJdKx5UnIy4kGGP6WWpCEFEt/bhQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@aws-sdk/util-format-url": "^3.972.3", + "@smithy/eventstream-codec": "^4.2.8", + "@smithy/eventstream-serde-browser": "^4.2.8", + "@smithy/fetch-http-handler": "^5.3.9", + "@smithy/protocol-http": "^5.3.8", + "@smithy/signature-v4": "^5.3.8", + "@smithy/types": "^4.12.0", + "@smithy/util-base64": "^4.3.0", + "@smithy/util-hex-encoding": "^4.2.0", + "@smithy/util-utf8": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@aws-sdk/nested-clients": { + "version": "3.989.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.989.0.tgz", + "integrity": "sha512-Dbk2HMPU3mb6RrSRzgf0WCaWSbgtZG258maCpuN2/ONcAQNpOTw99V5fU5CA1qVK6Vkm4Fwj2cnOnw7wbGVlOw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/middleware-host-header": "^3.972.3", + "@aws-sdk/middleware-logger": "^3.972.3", + "@aws-sdk/middleware-recursion-detection": "^3.972.3", + "@aws-sdk/middleware-user-agent": "^3.972.9", + "@aws-sdk/region-config-resolver": "^3.972.3", + "@aws-sdk/types": "^3.973.1", + "@aws-sdk/util-endpoints": "3.989.0", + "@aws-sdk/util-user-agent-browser": "^3.972.3", + "@aws-sdk/util-user-agent-node": "^3.972.7", + "@smithy/config-resolver": "^4.4.6", + "@smithy/core": "^3.23.0", + "@smithy/fetch-http-handler": "^5.3.9", + "@smithy/hash-node": "^4.2.8", + "@smithy/invalid-dependency": "^4.2.8", + "@smithy/middleware-content-length": "^4.2.8", + "@smithy/middleware-endpoint": "^4.4.14", + "@smithy/middleware-retry": "^4.4.31", + "@smithy/middleware-serde": "^4.2.9", + "@smithy/middleware-stack": "^4.2.8", + "@smithy/node-config-provider": "^4.3.8", + "@smithy/node-http-handler": "^4.4.10", + "@smithy/protocol-http": "^5.3.8", + "@smithy/smithy-client": "^4.11.3", + "@smithy/types": "^4.12.0", + "@smithy/url-parser": "^4.2.8", + "@smithy/util-base64": "^4.3.0", + "@smithy/util-body-length-browser": "^4.2.0", + "@smithy/util-body-length-node": "^4.2.1", + "@smithy/util-defaults-mode-browser": "^4.3.30", + "@smithy/util-defaults-mode-node": "^4.2.33", + "@smithy/util-endpoints": "^3.2.8", + "@smithy/util-middleware": "^4.2.8", + "@smithy/util-retry": "^4.2.8", + "@smithy/util-utf8": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/region-config-resolver": { + "version": "3.972.3", + "resolved": "https://registry.npmjs.org/@aws-sdk/region-config-resolver/-/region-config-resolver-3.972.3.tgz", + "integrity": "sha512-v4J8qYAWfOMcZ4MJUyatntOicTzEMaU7j3OpkRCGGFSL2NgXQ5VbxauIyORA+pxdKZ0qQG2tCQjQjZDlXEC3Ow==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@smithy/config-resolver": "^4.4.6", + "@smithy/node-config-provider": "^4.3.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/token-providers": { + "version": "3.989.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.989.0.tgz", + "integrity": "sha512-OdBByMv+OjOZoekrk4THPFpLuND5aIQbDHCGh3n2rvifAbm31+6e0OLhxSeCF1UMPm+nKq12bXYYEoCIx5SQBg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.973.9", + "@aws-sdk/nested-clients": "3.989.0", + "@aws-sdk/types": "^3.973.1", + "@smithy/property-provider": "^4.2.8", + "@smithy/shared-ini-file-loader": "^4.4.3", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/types": { + "version": "3.973.1", + "resolved": "https://registry.npmjs.org/@aws-sdk/types/-/types-3.973.1.tgz", + "integrity": "sha512-DwHBiMNOB468JiX6+i34c+THsKHErYUdNQ3HexeXZvVn4zouLjgaS4FejiGSi2HyBuzuyHg7SuOPmjSvoU9NRg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/util-endpoints": { + "version": "3.989.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-endpoints/-/util-endpoints-3.989.0.tgz", + "integrity": "sha512-eKmAOeQM4Qusq0jtcbZPiNWky8XaojByKC/n+THbJ8vJf7t4ys8LlcZ4PrBSHZISe9cC484mQsPVOQh6iySjqw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@smithy/types": "^4.12.0", + "@smithy/url-parser": "^4.2.8", + "@smithy/util-endpoints": "^3.2.8", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/util-format-url": { + "version": "3.972.3", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-format-url/-/util-format-url-3.972.3.tgz", + "integrity": "sha512-n7F2ycckcKFXa01vAsT/SJdjFHfKH9s96QHcs5gn8AaaigASICeME8WdUL9uBp8XV/OVwEt8+6gzn6KFUgQa8g==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@smithy/querystring-builder": "^4.2.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/util-locate-window": { + "version": "3.965.4", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-locate-window/-/util-locate-window-3.965.4.tgz", + "integrity": "sha512-H1onv5SkgPBK2P6JR2MjGgbOnttoNzSPIRoeZTNPZYyaplwGg50zS3amXvXqF0/qfXpWEC9rLWU564QTB9bSog==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/util-user-agent-browser": { + "version": "3.972.3", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-user-agent-browser/-/util-user-agent-browser-3.972.3.tgz", + "integrity": "sha512-JurOwkRUcXD/5MTDBcqdyQ9eVedtAsZgw5rBwktsPTN7QtPiS2Ld1jkJepNgYoCufz1Wcut9iup7GJDoIHp8Fw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.1", + "@smithy/types": "^4.12.0", + "bowser": "^2.11.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-sdk/util-user-agent-node": { + "version": "3.972.7", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-user-agent-node/-/util-user-agent-node-3.972.7.tgz", + "integrity": "sha512-oyhv+FjrgHjP+F16cmsrJzNP4qaRJzkV1n9Lvv4uyh3kLqo3rIe9NSBSBa35f2TedczfG2dD+kaQhHBB47D6Og==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/middleware-user-agent": "^3.972.9", + "@aws-sdk/types": "^3.973.1", + "@smithy/node-config-provider": "^4.3.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "aws-crt": ">=1.0.0" + }, + "peerDependenciesMeta": { + "aws-crt": { + "optional": true + } + } + }, + "node_modules/@aws-sdk/xml-builder": { + "version": "3.972.4", + "resolved": "https://registry.npmjs.org/@aws-sdk/xml-builder/-/xml-builder-3.972.4.tgz", + "integrity": "sha512-0zJ05ANfYqI6+rGqj8samZBFod0dPPousBjLEqg8WdxSgbMAkRgLyn81lP215Do0rFJ/17LIXwr7q0yK24mP6Q==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "fast-xml-parser": "5.3.4", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws/lambda-invoke-store": { + "version": "0.2.3", + "resolved": "https://registry.npmjs.org/@aws/lambda-invoke-store/-/lambda-invoke-store-0.2.3.tgz", + "integrity": "sha512-oLvsaPMTBejkkmHhjf09xTgk71mOqyr/409NKhRIL08If7AhVfUsJhVsx386uJaqNd42v9kWamQ9lFbkoC2dYw==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@babel/runtime": { + "version": "7.28.6", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.28.6.tgz", + "integrity": "sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@borewit/text-codec": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/@borewit/text-codec/-/text-codec-0.2.1.tgz", + "integrity": "sha512-k7vvKPbf7J2fZ5klGRD9AeKfUvojuZIQ3BT5u7Jfv+puwXkUBUT5PVyMDfJZpy30CBDXGMgw7fguK/lpOMBvgw==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/Borewit" + } + }, + "node_modules/@google/genai": { + "version": "1.41.0", + "resolved": "https://registry.npmjs.org/@google/genai/-/genai-1.41.0.tgz", + "integrity": "sha512-S4WGil+PG0NBQRAx+0yrQuM/TWOLn2gGEy5wn4IsoOI6ouHad0P61p3OWdhJ3aqr9kfj8o904i/jevfaGoGuIQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "google-auth-library": "^10.3.0", + "p-retry": "^7.1.1", + "protobufjs": "^7.5.4", + "ws": "^8.18.0" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "@modelcontextprotocol/sdk": "^1.25.2" + }, + "peerDependenciesMeta": { + "@modelcontextprotocol/sdk": { + "optional": true + } + } + }, + "node_modules/@isaacs/cliui": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-9.0.0.tgz", + "integrity": "sha512-AokJm4tuBHillT+FpMtxQ60n8ObyXBatq7jD2/JA9dxbDDokKQm8KMht5ibGzLVU9IJDIKK4TPKgMHEYMn3lMg==", + "dev": true, + "license": "BlueOak-1.0.0", + "engines": { + "node": ">=18" + } + }, + "node_modules/@mariozechner/clipboard": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard/-/clipboard-0.3.2.tgz", + "integrity": "sha512-IHQpksNjo7EAtGuHFU+tbWDp5LarH3HU/8WiB9O70ZEoBPHOg0/6afwSLK0QyNMMmx4Bpi/zl6+DcBXe95nWYA==", + "dev": true, + "license": "MIT", + "optional": true, + "engines": { + "node": ">= 10" + }, + "optionalDependencies": { + "@mariozechner/clipboard-darwin-arm64": "0.3.2", + "@mariozechner/clipboard-darwin-universal": "0.3.2", + "@mariozechner/clipboard-darwin-x64": "0.3.2", + "@mariozechner/clipboard-linux-arm64-gnu": "0.3.2", + "@mariozechner/clipboard-linux-arm64-musl": "0.3.2", + "@mariozechner/clipboard-linux-riscv64-gnu": "0.3.2", + "@mariozechner/clipboard-linux-x64-gnu": "0.3.2", + "@mariozechner/clipboard-linux-x64-musl": "0.3.2", + "@mariozechner/clipboard-win32-arm64-msvc": "0.3.2", + "@mariozechner/clipboard-win32-x64-msvc": "0.3.2" + } + }, + "node_modules/@mariozechner/clipboard-darwin-arm64": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-arm64/-/clipboard-darwin-arm64-0.3.2.tgz", + "integrity": "sha512-uBf6K7Je1ihsgvmWxA8UCGCeI+nbRVRXoarZdLjl6slz94Zs1tNKFZqx7aCI5O1i3e0B6ja82zZ06BWrl0MCVw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@mariozechner/clipboard-darwin-universal": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-universal/-/clipboard-darwin-universal-0.3.2.tgz", + "integrity": "sha512-mxSheKTW2U9LsBdXy0SdmdCAE5HqNS9QUmpNHLnfJ+SsbFKALjEZc5oRrVMXxGQSirDvYf5bjmRyT0QYYonnlg==", + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@mariozechner/clipboard-darwin-x64": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-x64/-/clipboard-darwin-x64-0.3.2.tgz", + "integrity": "sha512-U1BcVEoidvwIp95+HJswSW+xr28EQiHR7rZjH6pn8Sja5yO4Yoe3yCN0Zm8Lo72BbSOK/fTSq0je7CJpaPCspg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@mariozechner/clipboard-linux-arm64-gnu": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-arm64-gnu/-/clipboard-linux-arm64-gnu-0.3.2.tgz", + "integrity": "sha512-BsinwG3yWTIjdgNCxsFlip7LkfwPk+ruw/aFCXHUg/fb5XC/Ksp+YMQ7u0LUtiKzIv/7LMXgZInJQH6gxbAaqQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@mariozechner/clipboard-linux-arm64-musl": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-arm64-musl/-/clipboard-linux-arm64-musl-0.3.2.tgz", + "integrity": "sha512-0/Gi5Xq2V6goXBop19ePoHvXsmJD9SzFlO3S+d6+T2b+BlPcpOu3Oa0wTjl+cZrLAAEzA86aPNBI+VVAFDFPKw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@mariozechner/clipboard-linux-riscv64-gnu": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-riscv64-gnu/-/clipboard-linux-riscv64-gnu-0.3.2.tgz", + "integrity": "sha512-2AFFiXB24qf0zOZsxI1GJGb9wQGlOJyN6UwoXqmKS3dpQi/l6ix30IzDDA4c4ZcCcx4D+9HLYXhC1w7Sov8pXA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@mariozechner/clipboard-linux-x64-gnu": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-x64-gnu/-/clipboard-linux-x64-gnu-0.3.2.tgz", + "integrity": "sha512-v6fVnsn7WMGg73Dab8QMwyFce7tzGfgEixKgzLP8f1GJqkJZi5zO4k4FOHzSgUufgLil63gnxvMpjWkgfeQN7A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@mariozechner/clipboard-linux-x64-musl": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-x64-musl/-/clipboard-linux-x64-musl-0.3.2.tgz", + "integrity": "sha512-xVUtnoMQ8v2JVyfJLKKXACA6avdnchdbBkTsZs8BgJQo29qwCp5NIHAUO8gbJ40iaEGToW5RlmVk2M9V0HsHEw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@mariozechner/clipboard-win32-arm64-msvc": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-win32-arm64-msvc/-/clipboard-win32-arm64-msvc-0.3.2.tgz", + "integrity": "sha512-AEgg95TNi8TGgak2wSXZkXKCvAUTjWoU1Pqb0ON7JHrX78p616XUFNTJohtIon3e0w6k0pYPZeCuqRCza/Tqeg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@mariozechner/clipboard-win32-x64-msvc": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-win32-x64-msvc/-/clipboard-win32-x64-msvc-0.3.2.tgz", + "integrity": "sha512-tGRuYpZwDOD7HBrCpyRuhGnHHSCknELvqwKKUG4JSfSB7JIU7LKRh6zx6fMUOQd8uISK35TjFg5UcNih+vJhFA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@mariozechner/jiti": { + "version": "2.6.5", + "resolved": "https://registry.npmjs.org/@mariozechner/jiti/-/jiti-2.6.5.tgz", + "integrity": "sha512-faGUlTcXka5l7rv0lP3K3vGW/ejRuOS24RR2aSFWREUQqzjgdsuWNo/IiPqL3kWRGt6Ahl2+qcDAwtdeWeuGUw==", + "dev": true, + "license": "MIT", + "dependencies": { + "std-env": "^3.10.0", + "yoctocolors": "^2.1.2" + }, + "bin": { + "jiti": "lib/jiti-cli.mjs" + } + }, + "node_modules/@mariozechner/pi-agent-core": { + "version": "0.52.10", + "resolved": "https://registry.npmjs.org/@mariozechner/pi-agent-core/-/pi-agent-core-0.52.10.tgz", + "integrity": "sha512-rTM3ug6rMuDFbQINympIIV9CW3Z8ONyBSehsoDNWtdXTWNA7Nzpx3mAYsA91B856HM0Zbl45UBNRN1YHDeaFTg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@mariozechner/pi-ai": "^0.52.10" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@mariozechner/pi-ai": { + "version": "0.52.10", + "resolved": "https://registry.npmjs.org/@mariozechner/pi-ai/-/pi-ai-0.52.10.tgz", + "integrity": "sha512-dgV5emMbDoz0GGyDy6CjY+RcW/PqwQvUzqAehjDUj1M+3b7+fIB7E2WKZQKvjYIY79qTvAIyrdEmIs2BQX+enA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@anthropic-ai/sdk": "^0.73.0", + "@aws-sdk/client-bedrock-runtime": "^3.983.0", + "@google/genai": "^1.40.0", + "@mistralai/mistralai": "1.10.0", + "@sinclair/typebox": "^0.34.41", + "ajv": "^8.17.1", + "ajv-formats": "^3.0.1", + "chalk": "^5.6.2", + "openai": "6.10.0", + "partial-json": "^0.1.7", + "proxy-agent": "^6.5.0", + "undici": "^7.19.1", + "zod-to-json-schema": "^3.24.6" + }, + "bin": { + "pi-ai": "dist/cli.js" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@mariozechner/pi-ai/node_modules/@sinclair/typebox": { + "version": "0.34.48", + "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.34.48.tgz", + "integrity": "sha512-kKJTNuK3AQOrgjjotVxMrCn1sUJwM76wMszfq1kdU4uYVJjvEWuFQ6HgvLt4Xz3fSmZlTOxJ/Ie13KnIcWQXFA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@mariozechner/pi-coding-agent": { + "version": "0.52.10", + "resolved": "https://registry.npmjs.org/@mariozechner/pi-coding-agent/-/pi-coding-agent-0.52.10.tgz", + "integrity": "sha512-88gBrk+aDKMe4M6hY63LT8ylXEeoNdwnKHB7Ijmxzw5ShtWl7+H8vTBIwxZu/5yNR2b4VhjB0NGi3khpwT5I1A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@mariozechner/jiti": "^2.6.2", + "@mariozechner/pi-agent-core": "^0.52.10", + "@mariozechner/pi-ai": "^0.52.10", + "@mariozechner/pi-tui": "^0.52.10", + "@silvia-odwyer/photon-node": "^0.3.4", + "chalk": "^5.5.0", + "cli-highlight": "^2.1.11", + "diff": "^8.0.2", + "file-type": "^21.1.1", + "glob": "^13.0.1", + "hosted-git-info": "^9.0.2", + "ignore": "^7.0.5", + "marked": "^15.0.12", + "minimatch": "^10.1.1", + "proper-lockfile": "^4.1.2", + "yaml": "^2.8.2" + }, + "bin": { + "pi": "dist/cli.js" + }, + "engines": { + "node": ">=20.0.0" + }, + "optionalDependencies": { + "@mariozechner/clipboard": "^0.3.2" + } + }, + "node_modules/@mariozechner/pi-tui": { + "version": "0.52.10", + "resolved": "https://registry.npmjs.org/@mariozechner/pi-tui/-/pi-tui-0.52.10.tgz", + "integrity": "sha512-j0re5FXzznkrzC7BOc1fb+DUWYetRZAVSUbdZoxa6S5S7amxmIJzbSNCgKBaF1ZyY40jp+B5Z4W60Qc7Pn1rxA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mime-types": "^2.1.4", + "chalk": "^5.5.0", + "get-east-asian-width": "^1.3.0", + "marked": "^15.0.12", + "mime-types": "^3.0.1" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@mistralai/mistralai": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/@mistralai/mistralai/-/mistralai-1.10.0.tgz", + "integrity": "sha512-tdIgWs4Le8vpvPiUEWne6tK0qbVc+jMenujnvTqOjogrJUsCSQhus0tHTU1avDDh5//Rq2dFgP9mWRAdIEoBqg==", + "dev": true, + "dependencies": { + "zod": "^3.20.0", + "zod-to-json-schema": "^3.24.1" + } + }, + "node_modules/@mistralai/mistralai/node_modules/zod": { + "version": "3.25.76", + "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", + "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/@pkgjs/parseargs": { + "version": "0.11.0", + "resolved": "https://registry.npmjs.org/@pkgjs/parseargs/-/parseargs-0.11.0.tgz", + "integrity": "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==", + "dev": true, + "license": "MIT", + "optional": true, + "engines": { + "node": ">=14" + } + }, + "node_modules/@protobufjs/aspromise": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz", + "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/base64": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz", + "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/codegen": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.4.tgz", + "integrity": "sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/eventemitter": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.0.tgz", + "integrity": "sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/fetch": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.0.tgz", + "integrity": "sha512-lljVXpqXebpsijW71PZaCYeIcE5on1w5DlQy5WH6GLbFryLUrBD4932W/E2BSpfRJWseIL4v/KPgBFxDOIdKpQ==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "@protobufjs/aspromise": "^1.1.1", + "@protobufjs/inquire": "^1.1.0" + } + }, + "node_modules/@protobufjs/float": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz", + "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/inquire": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.0.tgz", + "integrity": "sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/path": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz", + "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/pool": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz", + "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/utf8": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.0.tgz", + "integrity": "sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@silvia-odwyer/photon-node": { + "version": "0.3.4", + "resolved": "https://registry.npmjs.org/@silvia-odwyer/photon-node/-/photon-node-0.3.4.tgz", + "integrity": "sha512-bnly4BKB3KDTFxrUIcgCLbaeVVS8lrAkri1pEzskpmxu9MdfGQTy8b8EgcD83ywD3RPMsIulY8xJH5Awa+t9fA==", + "dev": true, + "license": "Apache-2.0" + }, + "node_modules/@sinclair/typebox": { + "version": "0.32.35", + "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.32.35.tgz", + "integrity": "sha512-Ul3YyOTU++to8cgNkttakC0dWvpERr6RYoHO2W47DLbFvrwBDJUY31B1sImH6JZSYc4Kt4PyHtoPNu+vL2r2dA==", + "license": "MIT" + }, + "node_modules/@smithy/abort-controller": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/abort-controller/-/abort-controller-4.2.8.tgz", + "integrity": "sha512-peuVfkYHAmS5ybKxWcfraK7WBBP0J+rkfUcbHJJKQ4ir3UAUNQI+Y4Vt/PqSzGqgloJ5O1dk7+WzNL8wcCSXbw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/config-resolver": { + "version": "4.4.6", + "resolved": "https://registry.npmjs.org/@smithy/config-resolver/-/config-resolver-4.4.6.tgz", + "integrity": "sha512-qJpzYC64kaj3S0fueiu3kXm8xPrR3PcXDPEgnaNMRn0EjNSZFoFjvbUp0YUDsRhN1CB90EnHJtbxWKevnH99UQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/node-config-provider": "^4.3.8", + "@smithy/types": "^4.12.0", + "@smithy/util-config-provider": "^4.2.0", + "@smithy/util-endpoints": "^3.2.8", + "@smithy/util-middleware": "^4.2.8", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/core": { + "version": "3.23.0", + "resolved": "https://registry.npmjs.org/@smithy/core/-/core-3.23.0.tgz", + "integrity": "sha512-Yq4UPVoQICM9zHnByLmG8632t2M0+yap4T7ANVw482J0W7HW0pOuxwVmeOwzJqX2Q89fkXz0Vybz55Wj2Xzrsg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/middleware-serde": "^4.2.9", + "@smithy/protocol-http": "^5.3.8", + "@smithy/types": "^4.12.0", + "@smithy/util-base64": "^4.3.0", + "@smithy/util-body-length-browser": "^4.2.0", + "@smithy/util-middleware": "^4.2.8", + "@smithy/util-stream": "^4.5.12", + "@smithy/util-utf8": "^4.2.0", + "@smithy/uuid": "^1.1.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/credential-provider-imds": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/credential-provider-imds/-/credential-provider-imds-4.2.8.tgz", + "integrity": "sha512-FNT0xHS1c/CPN8upqbMFP83+ul5YgdisfCfkZ86Jh2NSmnqw/AJ6x5pEogVCTVvSm7j9MopRU89bmDelxuDMYw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/node-config-provider": "^4.3.8", + "@smithy/property-provider": "^4.2.8", + "@smithy/types": "^4.12.0", + "@smithy/url-parser": "^4.2.8", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/eventstream-codec": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/eventstream-codec/-/eventstream-codec-4.2.8.tgz", + "integrity": "sha512-jS/O5Q14UsufqoGhov7dHLOPCzkYJl9QDzusI2Psh4wyYx/izhzvX9P4D69aTxcdfVhEPhjK+wYyn/PzLjKbbw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/crc32": "5.2.0", + "@smithy/types": "^4.12.0", + "@smithy/util-hex-encoding": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/eventstream-serde-browser": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-browser/-/eventstream-serde-browser-4.2.8.tgz", + "integrity": "sha512-MTfQT/CRQz5g24ayXdjg53V0mhucZth4PESoA5IhvaWVDTOQLfo8qI9vzqHcPsdd2v6sqfTYqF5L/l+pea5Uyw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/eventstream-serde-universal": "^4.2.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/eventstream-serde-config-resolver": { + "version": "4.3.8", + "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-config-resolver/-/eventstream-serde-config-resolver-4.3.8.tgz", + "integrity": "sha512-ah12+luBiDGzBruhu3efNy1IlbwSEdNiw8fOZksoKoWW1ZHvO/04MQsdnws/9Aj+5b0YXSSN2JXKy/ClIsW8MQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/eventstream-serde-node": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-node/-/eventstream-serde-node-4.2.8.tgz", + "integrity": "sha512-cYpCpp29z6EJHa5T9WL0KAlq3SOKUQkcgSoeRfRVwjGgSFl7Uh32eYGt7IDYCX20skiEdRffyDpvF2efEZPC0A==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/eventstream-serde-universal": "^4.2.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/eventstream-serde-universal": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-universal/-/eventstream-serde-universal-4.2.8.tgz", + "integrity": "sha512-iJ6YNJd0bntJYnX6s52NC4WFYcZeKrPUr1Kmmr5AwZcwCSzVpS7oavAmxMR7pMq7V+D1G4s9F5NJK0xwOsKAlQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/eventstream-codec": "^4.2.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/fetch-http-handler": { + "version": "5.3.9", + "resolved": "https://registry.npmjs.org/@smithy/fetch-http-handler/-/fetch-http-handler-5.3.9.tgz", + "integrity": "sha512-I4UhmcTYXBrct03rwzQX1Y/iqQlzVQaPxWjCjula++5EmWq9YGBrx6bbGqluGc1f0XEfhSkiY4jhLgbsJUMKRA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/protocol-http": "^5.3.8", + "@smithy/querystring-builder": "^4.2.8", + "@smithy/types": "^4.12.0", + "@smithy/util-base64": "^4.3.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/hash-node": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/hash-node/-/hash-node-4.2.8.tgz", + "integrity": "sha512-7ZIlPbmaDGxVoxErDZnuFG18WekhbA/g2/i97wGj+wUBeS6pcUeAym8u4BXh/75RXWhgIJhyC11hBzig6MljwA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "@smithy/util-buffer-from": "^4.2.0", + "@smithy/util-utf8": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/invalid-dependency": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/invalid-dependency/-/invalid-dependency-4.2.8.tgz", + "integrity": "sha512-N9iozRybwAQ2dn9Fot9kI6/w9vos2oTXLhtK7ovGqwZjlOcxu6XhPlpLpC+INsxktqHinn5gS2DXDjDF2kG5sQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/is-array-buffer": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-4.2.0.tgz", + "integrity": "sha512-DZZZBvC7sjcYh4MazJSGiWMI2L7E0oCiRHREDzIxi/M2LY79/21iXt6aPLHge82wi5LsuRF5A06Ds3+0mlh6CQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/middleware-content-length": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/middleware-content-length/-/middleware-content-length-4.2.8.tgz", + "integrity": "sha512-RO0jeoaYAB1qBRhfVyq0pMgBoUK34YEJxVxyjOWYZiOKOq2yMZ4MnVXMZCUDenpozHue207+9P5ilTV1zeda0A==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/protocol-http": "^5.3.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/middleware-endpoint": { + "version": "4.4.14", + "resolved": "https://registry.npmjs.org/@smithy/middleware-endpoint/-/middleware-endpoint-4.4.14.tgz", + "integrity": "sha512-FUFNE5KVeaY6U/GL0nzAAHkaCHzXLZcY1EhtQnsAqhD8Du13oPKtMB9/0WK4/LK6a/T5OZ24wPoSShff5iI6Ag==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.23.0", + "@smithy/middleware-serde": "^4.2.9", + "@smithy/node-config-provider": "^4.3.8", + "@smithy/shared-ini-file-loader": "^4.4.3", + "@smithy/types": "^4.12.0", + "@smithy/url-parser": "^4.2.8", + "@smithy/util-middleware": "^4.2.8", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/middleware-retry": { + "version": "4.4.31", + "resolved": "https://registry.npmjs.org/@smithy/middleware-retry/-/middleware-retry-4.4.31.tgz", + "integrity": "sha512-RXBzLpMkIrxBPe4C8OmEOHvS8aH9RUuCOH++Acb5jZDEblxDjyg6un72X9IcbrGTJoiUwmI7hLypNfuDACypbg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/node-config-provider": "^4.3.8", + "@smithy/protocol-http": "^5.3.8", + "@smithy/service-error-classification": "^4.2.8", + "@smithy/smithy-client": "^4.11.3", + "@smithy/types": "^4.12.0", + "@smithy/util-middleware": "^4.2.8", + "@smithy/util-retry": "^4.2.8", + "@smithy/uuid": "^1.1.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/middleware-serde": { + "version": "4.2.9", + "resolved": "https://registry.npmjs.org/@smithy/middleware-serde/-/middleware-serde-4.2.9.tgz", + "integrity": "sha512-eMNiej0u/snzDvlqRGSN3Vl0ESn3838+nKyVfF2FKNXFbi4SERYT6PR392D39iczngbqqGG0Jl1DlCnp7tBbXQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/protocol-http": "^5.3.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/middleware-stack": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/middleware-stack/-/middleware-stack-4.2.8.tgz", + "integrity": "sha512-w6LCfOviTYQjBctOKSwy6A8FIkQy7ICvglrZFl6Bw4FmcQ1Z420fUtIhxaUZZshRe0VCq4kvDiPiXrPZAe8oRA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/node-config-provider": { + "version": "4.3.8", + "resolved": "https://registry.npmjs.org/@smithy/node-config-provider/-/node-config-provider-4.3.8.tgz", + "integrity": "sha512-aFP1ai4lrbVlWjfpAfRSL8KFcnJQYfTl5QxLJXY32vghJrDuFyPZ6LtUL+JEGYiFRG1PfPLHLoxj107ulncLIg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/property-provider": "^4.2.8", + "@smithy/shared-ini-file-loader": "^4.4.3", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/node-http-handler": { + "version": "4.4.10", + "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.4.10.tgz", + "integrity": "sha512-u4YeUwOWRZaHbWaebvrs3UhwQwj+2VNmcVCwXcYTvPIuVyM7Ex1ftAj+fdbG/P4AkBwLq/+SKn+ydOI4ZJE9PA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/abort-controller": "^4.2.8", + "@smithy/protocol-http": "^5.3.8", + "@smithy/querystring-builder": "^4.2.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/property-provider": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/property-provider/-/property-provider-4.2.8.tgz", + "integrity": "sha512-EtCTbyIveCKeOXDSWSdze3k612yCPq1YbXsbqX3UHhkOSW8zKsM9NOJG5gTIya0vbY2DIaieG8pKo1rITHYL0w==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/protocol-http": { + "version": "5.3.8", + "resolved": "https://registry.npmjs.org/@smithy/protocol-http/-/protocol-http-5.3.8.tgz", + "integrity": "sha512-QNINVDhxpZ5QnP3aviNHQFlRogQZDfYlCkQT+7tJnErPQbDhysondEjhikuANxgMsZrkGeiAxXy4jguEGsDrWQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/querystring-builder": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/querystring-builder/-/querystring-builder-4.2.8.tgz", + "integrity": "sha512-Xr83r31+DrE8CP3MqPgMJl+pQlLLmOfiEUnoyAlGzzJIrEsbKsPy1hqH0qySaQm4oWrCBlUqRt+idEgunKB+iw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "@smithy/util-uri-escape": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/querystring-parser": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/querystring-parser/-/querystring-parser-4.2.8.tgz", + "integrity": "sha512-vUurovluVy50CUlazOiXkPq40KGvGWSdmusa3130MwrR1UNnNgKAlj58wlOe61XSHRpUfIIh6cE0zZ8mzKaDPA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/service-error-classification": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/service-error-classification/-/service-error-classification-4.2.8.tgz", + "integrity": "sha512-mZ5xddodpJhEt3RkCjbmUQuXUOaPNTkbMGR0bcS8FE0bJDLMZlhmpgrvPNCYglVw5rsYTpSnv19womw9WWXKQQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/shared-ini-file-loader": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/@smithy/shared-ini-file-loader/-/shared-ini-file-loader-4.4.3.tgz", + "integrity": "sha512-DfQjxXQnzC5UbCUPeC3Ie8u+rIWZTvuDPAGU/BxzrOGhRvgUanaP68kDZA+jaT3ZI+djOf+4dERGlm9mWfFDrg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/signature-v4": { + "version": "5.3.8", + "resolved": "https://registry.npmjs.org/@smithy/signature-v4/-/signature-v4-5.3.8.tgz", + "integrity": "sha512-6A4vdGj7qKNRF16UIcO8HhHjKW27thsxYci+5r/uVRkdcBEkOEiY8OMPuydLX4QHSrJqGHPJzPRwwVTqbLZJhg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^4.2.0", + "@smithy/protocol-http": "^5.3.8", + "@smithy/types": "^4.12.0", + "@smithy/util-hex-encoding": "^4.2.0", + "@smithy/util-middleware": "^4.2.8", + "@smithy/util-uri-escape": "^4.2.0", + "@smithy/util-utf8": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/smithy-client": { + "version": "4.11.3", + "resolved": "https://registry.npmjs.org/@smithy/smithy-client/-/smithy-client-4.11.3.tgz", + "integrity": "sha512-Q7kY5sDau8OoE6Y9zJoRGgje8P4/UY0WzH8R2ok0PDh+iJ+ZnEKowhjEqYafVcubkbYxQVaqwm3iufktzhprGg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.23.0", + "@smithy/middleware-endpoint": "^4.4.14", + "@smithy/middleware-stack": "^4.2.8", + "@smithy/protocol-http": "^5.3.8", + "@smithy/types": "^4.12.0", + "@smithy/util-stream": "^4.5.12", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/types": { + "version": "4.12.0", + "resolved": "https://registry.npmjs.org/@smithy/types/-/types-4.12.0.tgz", + "integrity": "sha512-9YcuJVTOBDjg9LWo23Qp0lTQ3D7fQsQtwle0jVfpbUHy9qBwCEgKuVH4FqFB3VYu0nwdHKiEMA+oXz7oV8X1kw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/url-parser": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/url-parser/-/url-parser-4.2.8.tgz", + "integrity": "sha512-NQho9U68TGMEU639YkXnVMV3GEFFULmmaWdlu1E9qzyIePOHsoSnagTGSDv1Zi8DCNN6btxOSdgmy5E/hsZwhA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/querystring-parser": "^4.2.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-base64": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/@smithy/util-base64/-/util-base64-4.3.0.tgz", + "integrity": "sha512-GkXZ59JfyxsIwNTWFnjmFEI8kZpRNIBfxKjv09+nkAWPt/4aGaEWMM04m4sxgNVWkbt2MdSvE3KF/PfX4nFedQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^4.2.0", + "@smithy/util-utf8": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-body-length-browser": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-body-length-browser/-/util-body-length-browser-4.2.0.tgz", + "integrity": "sha512-Fkoh/I76szMKJnBXWPdFkQJl2r9SjPt3cMzLdOB6eJ4Pnpas8hVoWPYemX/peO0yrrvldgCUVJqOAjUrOLjbxg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-body-length-node": { + "version": "4.2.1", + "resolved": "https://registry.npmjs.org/@smithy/util-body-length-node/-/util-body-length-node-4.2.1.tgz", + "integrity": "sha512-h53dz/pISVrVrfxV1iqXlx5pRg3V2YWFcSQyPyXZRrZoZj4R4DeWRDo1a7dd3CPTcFi3kE+98tuNyD2axyZReA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-buffer-from": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-4.2.0.tgz", + "integrity": "sha512-kAY9hTKulTNevM2nlRtxAG2FQ3B2OR6QIrPY3zE5LqJy1oxzmgBGsHLWTcNhWXKchgA0WHW+mZkQrng/pgcCew==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-config-provider": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-config-provider/-/util-config-provider-4.2.0.tgz", + "integrity": "sha512-YEjpl6XJ36FTKmD+kRJJWYvrHeUvm5ykaUS5xK+6oXffQPHeEM4/nXlZPe+Wu0lsgRUcNZiliYNh/y7q9c2y6Q==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-defaults-mode-browser": { + "version": "4.3.30", + "resolved": "https://registry.npmjs.org/@smithy/util-defaults-mode-browser/-/util-defaults-mode-browser-4.3.30.tgz", + "integrity": "sha512-cMni0uVU27zxOiU8TuC8pQLC1pYeZ/xEMxvchSK/ILwleRd1ugobOcIRr5vXtcRqKd4aBLWlpeBoDPJJ91LQng==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/property-provider": "^4.2.8", + "@smithy/smithy-client": "^4.11.3", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-defaults-mode-node": { + "version": "4.2.33", + "resolved": "https://registry.npmjs.org/@smithy/util-defaults-mode-node/-/util-defaults-mode-node-4.2.33.tgz", + "integrity": "sha512-LEb2aq5F4oZUSzWBG7S53d4UytZSkOEJPXcBq/xbG2/TmK9EW5naUZ8lKu1BEyWMzdHIzEVN16M3k8oxDq+DJA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/config-resolver": "^4.4.6", + "@smithy/credential-provider-imds": "^4.2.8", + "@smithy/node-config-provider": "^4.3.8", + "@smithy/property-provider": "^4.2.8", + "@smithy/smithy-client": "^4.11.3", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-endpoints": { + "version": "3.2.8", + "resolved": "https://registry.npmjs.org/@smithy/util-endpoints/-/util-endpoints-3.2.8.tgz", + "integrity": "sha512-8JaVTn3pBDkhZgHQ8R0epwWt+BqPSLCjdjXXusK1onwJlRuN69fbvSK66aIKKO7SwVFM6x2J2ox5X8pOaWcUEw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/node-config-provider": "^4.3.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-hex-encoding": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-hex-encoding/-/util-hex-encoding-4.2.0.tgz", + "integrity": "sha512-CCQBwJIvXMLKxVbO88IukazJD9a4kQ9ZN7/UMGBjBcJYvatpWk+9g870El4cB8/EJxfe+k+y0GmR9CAzkF+Nbw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-middleware": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/util-middleware/-/util-middleware-4.2.8.tgz", + "integrity": "sha512-PMqfeJxLcNPMDgvPbbLl/2Vpin+luxqTGPpW3NAQVLbRrFRzTa4rNAASYeIGjRV9Ytuhzny39SpyU04EQreF+A==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-retry": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/@smithy/util-retry/-/util-retry-4.2.8.tgz", + "integrity": "sha512-CfJqwvoRY0kTGe5AkQokpURNCT1u/MkRzMTASWMPPo2hNSnKtF1D45dQl3DE2LKLr4m+PW9mCeBMJr5mCAVThg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/service-error-classification": "^4.2.8", + "@smithy/types": "^4.12.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-stream": { + "version": "4.5.12", + "resolved": "https://registry.npmjs.org/@smithy/util-stream/-/util-stream-4.5.12.tgz", + "integrity": "sha512-D8tgkrmhAX/UNeCZbqbEO3uqyghUnEmmoO9YEvRuwxjlkKKUE7FOgCJnqpTlQPe9MApdWPky58mNQQHbnCzoNg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/fetch-http-handler": "^5.3.9", + "@smithy/node-http-handler": "^4.4.10", + "@smithy/types": "^4.12.0", + "@smithy/util-base64": "^4.3.0", + "@smithy/util-buffer-from": "^4.2.0", + "@smithy/util-hex-encoding": "^4.2.0", + "@smithy/util-utf8": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-uri-escape": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-uri-escape/-/util-uri-escape-4.2.0.tgz", + "integrity": "sha512-igZpCKV9+E/Mzrpq6YacdTQ0qTiLm85gD6N/IrmyDvQFA4UnU3d5g3m8tMT/6zG/vVkWSU+VxeUyGonL62DuxA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-utf8": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-4.2.0.tgz", + "integrity": "sha512-zBPfuzoI8xyBtR2P6WQj63Rz8i3AmfAaJLuNG8dWsfvPe8lO4aCPYLn879mEgHndZH1zQ2oXmG8O1GGzzaoZiw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^4.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/uuid": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@smithy/uuid/-/uuid-1.1.0.tgz", + "integrity": "sha512-4aUIteuyxtBUhVdiQqcDhKFitwfd9hqoSDYY2KRXiWtgoWJ9Bmise+KfEPDiVHWeJepvF8xJO9/9+WDIciMFFw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@tokenizer/inflate": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/@tokenizer/inflate/-/inflate-0.4.1.tgz", + "integrity": "sha512-2mAv+8pkG6GIZiF1kNg1jAjh27IDxEPKwdGul3snfztFerfPGI1LjDezZp3i7BElXompqEtPmoPx6c2wgtWsOA==", + "dev": true, + "license": "MIT", + "dependencies": { + "debug": "^4.4.3", + "token-types": "^6.1.1" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/Borewit" + } + }, + "node_modules/@tokenizer/token": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/@tokenizer/token/-/token-0.3.0.tgz", + "integrity": "sha512-OvjF+z51L3ov0OyAU0duzsYuvO01PH7x4t6DJx+guahgTnBHkhJdG7soQeTSFLWN3efnHyibZ4Z8l2EuWwJN3A==", + "dev": true, + "license": "MIT" + }, + "node_modules/@tootallnate/quickjs-emscripten": { + "version": "0.23.0", + "resolved": "https://registry.npmjs.org/@tootallnate/quickjs-emscripten/-/quickjs-emscripten-0.23.0.tgz", + "integrity": "sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/mime-types": { + "version": "2.1.4", + "resolved": "https://registry.npmjs.org/@types/mime-types/-/mime-types-2.1.4.tgz", + "integrity": "sha512-lfU4b34HOri+kAY5UheuFMWPDOI+OPceBSHZKp69gEyTL/mmJ4cnU6Y/rlme3UL3GyOn6Y42hyIEw0/q8sWx5w==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/node": { + "version": "25.2.3", + "resolved": "https://registry.npmjs.org/@types/node/-/node-25.2.3.tgz", + "integrity": "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~7.16.0" + } + }, + "node_modules/agent-base": { + "version": "7.1.4", + "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz", + "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 14" + } + }, + "node_modules/ajv": { + "version": "8.17.1", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", + "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", + "dev": true, + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/ajv-formats": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz", + "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ajv": "^8.0.0" + }, + "peerDependencies": { + "ajv": "^8.0.0" + }, + "peerDependenciesMeta": { + "ajv": { + "optional": true + } + } + }, + "node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "license": "MIT", + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/any-promise": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz", + "integrity": "sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==", + "dev": true, + "license": "MIT" + }, + "node_modules/ast-types": { + "version": "0.13.4", + "resolved": "https://registry.npmjs.org/ast-types/-/ast-types-0.13.4.tgz", + "integrity": "sha512-x1FCFnFifvYDDzTaLII71vG5uvDwgtmDTEVWAxrgeiR8VjMONcCXJx7E+USjDtHlwFmt9MysbqgF9b9Vjr6w+w==", + "dev": true, + "license": "MIT", + "dependencies": { + "tslib": "^2.0.1" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/balanced-match": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.2.tgz", + "integrity": "sha512-x0K50QvKQ97fdEz2kPehIerj+YTeptKF9hyYkKf6egnwmMWAkADiO0QCzSp0R5xN8FTZgYaBfSaue46Ej62nMg==", + "dev": true, + "license": "MIT", + "dependencies": { + "jackspeak": "^4.2.3" + }, + "engines": { + "node": "20 || >=22" + } + }, + "node_modules/base64-js": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", + "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/basic-ftp": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.1.0.tgz", + "integrity": "sha512-RkaJzeJKDbaDWTIPiJwubyljaEPwpVWkm9Rt5h9Nd6h7tEXTJ3VB4qxdZBioV7JO5yLUaOKwz7vDOzlncUsegw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10.0.0" + } + }, + "node_modules/bignumber.js": { + "version": "9.3.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.3.1.tgz", + "integrity": "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": "*" + } + }, + "node_modules/bowser": { + "version": "2.14.1", + "resolved": "https://registry.npmjs.org/bowser/-/bowser-2.14.1.tgz", + "integrity": "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==", + "dev": true, + "license": "MIT" + }, + "node_modules/brace-expansion": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.2.tgz", + "integrity": "sha512-Pdk8c9poy+YhOgVWw1JNN22/HcivgKWwpxKq04M/jTmHyCZn12WPJebZxdjSa5TmBqISrUSgNYU3eRORljfCCw==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^4.0.2" + }, + "engines": { + "node": "20 || >=22" + } + }, + "node_modules/buffer-equal-constant-time": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz", + "integrity": "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/chalk": { + "version": "5.6.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz", + "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.17.0 || ^14.13 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/cli-highlight": { + "version": "2.1.11", + "resolved": "https://registry.npmjs.org/cli-highlight/-/cli-highlight-2.1.11.tgz", + "integrity": "sha512-9KDcoEVwyUXrjcJNvHD0NFc/hiwe/WPVYIleQh2O1N2Zro5gWJZ/K+3DGn8w8P/F6FxOgzyC5bxDyHIgCSPhGg==", + "dev": true, + "license": "ISC", + "dependencies": { + "chalk": "^4.0.0", + "highlight.js": "^10.7.1", + "mz": "^2.4.0", + "parse5": "^5.1.1", + "parse5-htmlparser2-tree-adapter": "^6.0.0", + "yargs": "^16.0.0" + }, + "bin": { + "highlight": "bin/highlight" + }, + "engines": { + "node": ">=8.0.0", + "npm": ">=5.0.0" + } + }, + "node_modules/cli-highlight/node_modules/chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/cliui": { + "version": "7.0.4", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz", + "integrity": "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==", + "dev": true, + "license": "ISC", + "dependencies": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.0", + "wrap-ansi": "^7.0.0" + } + }, + "node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true, + "license": "MIT" + }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "dev": true, + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/data-uri-to-buffer": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz", + "integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/degenerator": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/degenerator/-/degenerator-5.0.1.tgz", + "integrity": "sha512-TllpMR/t0M5sqCXfj85i4XaAzxmS5tVA16dqvdkMwGmzI+dXLXnw3J+3Vdv7VKw+ThlTMboK6i9rnZ6Nntj5CQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ast-types": "^0.13.4", + "escodegen": "^2.1.0", + "esprima": "^4.0.1" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/diff": { + "version": "8.0.3", + "resolved": "https://registry.npmjs.org/diff/-/diff-8.0.3.tgz", + "integrity": "sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/eastasianwidth": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz", + "integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==", + "dev": true, + "license": "MIT" + }, + "node_modules/ecdsa-sig-formatter": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/ecdsa-sig-formatter/-/ecdsa-sig-formatter-1.0.11.tgz", + "integrity": "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "safe-buffer": "^5.0.1" + } + }, + "node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "dev": true, + "license": "MIT" + }, + "node_modules/escalade": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz", + "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/escodegen": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/escodegen/-/escodegen-2.1.0.tgz", + "integrity": "sha512-2NlIDTwUWJN0mRPQOdtQBzbUHvdGY2P1VXSyU83Q3xKxM7WHX2Ql8dKq782Q9TgQUNOLEzEYu9bzLNj1q88I5w==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "esprima": "^4.0.1", + "estraverse": "^5.2.0", + "esutils": "^2.0.2" + }, + "bin": { + "escodegen": "bin/escodegen.js", + "esgenerate": "bin/esgenerate.js" + }, + "engines": { + "node": ">=6.0" + }, + "optionalDependencies": { + "source-map": "~0.6.1" + } + }, + "node_modules/esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", + "dev": true, + "license": "BSD-2-Clause", + "bin": { + "esparse": "bin/esparse.js", + "esvalidate": "bin/esvalidate.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/estraverse": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz", + "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=4.0" + } + }, + "node_modules/esutils": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz", + "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/extend": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", + "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-uri": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz", + "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fastify" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fastify" + } + ], + "license": "BSD-3-Clause" + }, + "node_modules/fast-xml-parser": { + "version": "5.3.4", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.3.4.tgz", + "integrity": "sha512-EFd6afGmXlCx8H8WTZHhAoDaWaGyuIBoZJ2mknrNxug+aZKjkp0a0dlars9Izl+jF+7Gu1/5f/2h68cQpe0IiA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "dependencies": { + "strnum": "^2.1.0" + }, + "bin": { + "fxparser": "src/cli/cli.js" + } + }, + "node_modules/fetch-blob": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/fetch-blob/-/fetch-blob-3.2.0.tgz", + "integrity": "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/jimmywarting" + }, + { + "type": "paypal", + "url": "https://paypal.me/jimmywarting" + } + ], + "license": "MIT", + "dependencies": { + "node-domexception": "^1.0.0", + "web-streams-polyfill": "^3.0.3" + }, + "engines": { + "node": "^12.20 || >= 14.13" + } + }, + "node_modules/file-type": { + "version": "21.3.0", + "resolved": "https://registry.npmjs.org/file-type/-/file-type-21.3.0.tgz", + "integrity": "sha512-8kPJMIGz1Yt/aPEwOsrR97ZyZaD1Iqm8PClb1nYFclUCkBi0Ma5IsYNQzvSFS9ib51lWyIw5mIT9rWzI/xjpzA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@tokenizer/inflate": "^0.4.1", + "strtok3": "^10.3.4", + "token-types": "^6.1.1", + "uint8array-extras": "^1.4.0" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sindresorhus/file-type?sponsor=1" + } + }, + "node_modules/foreground-child": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz", + "integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==", + "dev": true, + "license": "ISC", + "dependencies": { + "cross-spawn": "^7.0.6", + "signal-exit": "^4.0.1" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/foreground-child/node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/formdata-polyfill": { + "version": "4.0.10", + "resolved": "https://registry.npmjs.org/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz", + "integrity": "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==", + "dev": true, + "license": "MIT", + "dependencies": { + "fetch-blob": "^3.1.2" + }, + "engines": { + "node": ">=12.20.0" + } + }, + "node_modules/gaxios": { + "version": "7.1.3", + "resolved": "https://registry.npmjs.org/gaxios/-/gaxios-7.1.3.tgz", + "integrity": "sha512-YGGyuEdVIjqxkxVH1pUTMY/XtmmsApXrCVv5EU25iX6inEPbV+VakJfLealkBtJN69AQmh1eGOdCl9Sm1UP6XQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "extend": "^3.0.2", + "https-proxy-agent": "^7.0.1", + "node-fetch": "^3.3.2", + "rimraf": "^5.0.1" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/gcp-metadata": { + "version": "8.1.2", + "resolved": "https://registry.npmjs.org/gcp-metadata/-/gcp-metadata-8.1.2.tgz", + "integrity": "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "gaxios": "^7.0.0", + "google-logging-utils": "^1.0.0", + "json-bigint": "^1.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/get-caller-file": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", + "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", + "dev": true, + "license": "ISC", + "engines": { + "node": "6.* || 8.* || >= 10.*" + } + }, + "node_modules/get-east-asian-width": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.4.0.tgz", + "integrity": "sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/get-uri": { + "version": "6.0.5", + "resolved": "https://registry.npmjs.org/get-uri/-/get-uri-6.0.5.tgz", + "integrity": "sha512-b1O07XYq8eRuVzBNgJLstU6FYc1tS6wnMtF1I1D9lE8LxZSOGZ7LhxN54yPP6mGw5f2CkXY2BQUL9Fx41qvcIg==", + "dev": true, + "license": "MIT", + "dependencies": { + "basic-ftp": "^5.0.2", + "data-uri-to-buffer": "^6.0.2", + "debug": "^4.3.4" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/get-uri/node_modules/data-uri-to-buffer": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-6.0.2.tgz", + "integrity": "sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 14" + } + }, + "node_modules/glob": { + "version": "13.0.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.3.tgz", + "integrity": "sha512-/g3B0mC+4x724v1TgtBlBtt2hPi/EWptsIAmXUx9Z2rvBYleQcsrmaOzd5LyL50jf/Soi83ZDJmw2+XqvH/EeA==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "minimatch": "^10.2.0", + "minipass": "^7.1.2", + "path-scurry": "^2.0.0" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/google-auth-library": { + "version": "10.5.0", + "resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-10.5.0.tgz", + "integrity": "sha512-7ABviyMOlX5hIVD60YOfHw4/CxOfBhyduaYB+wbFWCWoni4N7SLcV46hrVRktuBbZjFC9ONyqamZITN7q3n32w==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "base64-js": "^1.3.0", + "ecdsa-sig-formatter": "^1.0.11", + "gaxios": "^7.0.0", + "gcp-metadata": "^8.0.0", + "google-logging-utils": "^1.0.0", + "gtoken": "^8.0.0", + "jws": "^4.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/google-logging-utils": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/google-logging-utils/-/google-logging-utils-1.1.3.tgz", + "integrity": "sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=14" + } + }, + "node_modules/graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", + "dev": true, + "license": "ISC" + }, + "node_modules/gtoken": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/gtoken/-/gtoken-8.0.0.tgz", + "integrity": "sha512-+CqsMbHPiSTdtSO14O51eMNlrp9N79gmeqmXeouJOhfucAedHw9noVe/n5uJk3tbKE6a+6ZCQg3RPhVhHByAIw==", + "dev": true, + "license": "MIT", + "dependencies": { + "gaxios": "^7.0.0", + "jws": "^4.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/highlight.js": { + "version": "10.7.3", + "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-10.7.3.tgz", + "integrity": "sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": "*" + } + }, + "node_modules/hosted-git-info": { + "version": "9.0.2", + "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-9.0.2.tgz", + "integrity": "sha512-M422h7o/BR3rmCQ8UHi7cyyMqKltdP9Uo+J2fXK+RSAY+wTcKOIRyhTuKv4qn+DJf3g+PL890AzId5KZpX+CBg==", + "dev": true, + "license": "ISC", + "dependencies": { + "lru-cache": "^11.1.0" + }, + "engines": { + "node": "^20.17.0 || >=22.9.0" + } + }, + "node_modules/http-proxy-agent": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz", + "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==", + "dev": true, + "license": "MIT", + "dependencies": { + "agent-base": "^7.1.0", + "debug": "^4.3.4" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/https-proxy-agent": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz", + "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==", + "dev": true, + "license": "MIT", + "dependencies": { + "agent-base": "^7.1.2", + "debug": "4" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/ieee754": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", + "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "BSD-3-Clause" + }, + "node_modules/ignore": { + "version": "7.0.5", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz", + "integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/ip-address": { + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz", + "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, + "node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/is-network-error": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/is-network-error/-/is-network-error-1.3.0.tgz", + "integrity": "sha512-6oIwpsgRfnDiyEDLMay/GqCl3HoAtH5+RUKW29gYkL0QA+ipzpDLA16yQs7/RHCSu+BwgbJaOUqa4A99qNVQVw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "dev": true, + "license": "ISC" + }, + "node_modules/jackspeak": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-4.2.3.tgz", + "integrity": "sha512-ykkVRwrYvFm1nb2AJfKKYPr0emF6IiXDYUaFx4Zn9ZuIH7MrzEZ3sD5RlqGXNRpHtvUHJyOnCEFxOlNDtGo7wg==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "@isaacs/cliui": "^9.0.0" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/json-bigint": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", + "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "bignumber.js": "^9.0.0" + } + }, + "node_modules/json-schema-to-ts": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz", + "integrity": "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.18.3", + "ts-algebra": "^2.0.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", + "dev": true, + "license": "MIT" + }, + "node_modules/jwa": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/jwa/-/jwa-2.0.1.tgz", + "integrity": "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==", + "dev": true, + "license": "MIT", + "dependencies": { + "buffer-equal-constant-time": "^1.0.1", + "ecdsa-sig-formatter": "1.0.11", + "safe-buffer": "^5.0.1" + } + }, + "node_modules/jws": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/jws/-/jws-4.0.1.tgz", + "integrity": "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==", + "dev": true, + "license": "MIT", + "dependencies": { + "jwa": "^2.0.1", + "safe-buffer": "^5.0.1" + } + }, + "node_modules/long": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz", + "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==", + "dev": true, + "license": "Apache-2.0" + }, + "node_modules/lru-cache": { + "version": "11.2.6", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.6.tgz", + "integrity": "sha512-ESL2CrkS/2wTPfuend7Zhkzo2u0daGJ/A2VucJOgQ/C48S/zB8MMeMHSGKYpXhIjbPxfuezITkaBH1wqv00DDQ==", + "dev": true, + "license": "BlueOak-1.0.0", + "engines": { + "node": "20 || >=22" + } + }, + "node_modules/marked": { + "version": "15.0.12", + "resolved": "https://registry.npmjs.org/marked/-/marked-15.0.12.tgz", + "integrity": "sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==", + "dev": true, + "license": "MIT", + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 18" + } + }, + "node_modules/mime-db": { + "version": "1.54.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz", + "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mime-types": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz", + "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==", + "dev": true, + "license": "MIT", + "dependencies": { + "mime-db": "^1.54.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/minimatch": { + "version": "10.2.0", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.0.tgz", + "integrity": "sha512-ugkC31VaVg9cF0DFVoADH12k6061zNZkZON+aX8AWsR9GhPcErkcMBceb6znR8wLERM2AkkOxy2nWRLpT9Jq5w==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "brace-expansion": "^5.0.2" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/minipass": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.2.tgz", + "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=16 || 14 >=14.17" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true, + "license": "MIT" + }, + "node_modules/mz": { + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/mz/-/mz-2.7.0.tgz", + "integrity": "sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "any-promise": "^1.0.0", + "object-assign": "^4.0.1", + "thenify-all": "^1.0.0" + } + }, + "node_modules/netmask": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/netmask/-/netmask-2.0.2.tgz", + "integrity": "sha512-dBpDMdxv9Irdq66304OLfEmQ9tbNRFnFTuZiLo+bD+r332bBmMJ8GBLXklIXXgxd3+v9+KUnZaUR5PJMa75Gsg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.4.0" + } + }, + "node_modules/node-domexception": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz", + "integrity": "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==", + "deprecated": "Use your platform's native DOMException instead", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/jimmywarting" + }, + { + "type": "github", + "url": "https://paypal.me/jimmywarting" + } + ], + "license": "MIT", + "engines": { + "node": ">=10.5.0" + } + }, + "node_modules/node-fetch": { + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz", + "integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==", + "dev": true, + "license": "MIT", + "dependencies": { + "data-uri-to-buffer": "^4.0.0", + "fetch-blob": "^3.1.4", + "formdata-polyfill": "^4.0.10" + }, + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/node-fetch" + } + }, + "node_modules/object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/openai": { + "version": "6.10.0", + "resolved": "https://registry.npmjs.org/openai/-/openai-6.10.0.tgz", + "integrity": "sha512-ITxOGo7rO3XRMiKA5l7tQ43iNNu+iXGFAcf2t+aWVzzqRaS0i7m1K2BhxNdaveB+5eENhO0VY1FkiZzhBk4v3A==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "openai": "bin/cli" + }, + "peerDependencies": { + "ws": "^8.18.0", + "zod": "^3.25 || ^4.0" + }, + "peerDependenciesMeta": { + "ws": { + "optional": true + }, + "zod": { + "optional": true + } + } + }, + "node_modules/p-retry": { + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/p-retry/-/p-retry-7.1.1.tgz", + "integrity": "sha512-J5ApzjyRkkf601HpEeykoiCvzHQjWxPAHhyjFcEUP2SWq0+35NKh8TLhpLw+Dkq5TZBFvUM6UigdE9hIVYTl5w==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-network-error": "^1.1.0" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/pac-proxy-agent": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/pac-proxy-agent/-/pac-proxy-agent-7.2.0.tgz", + "integrity": "sha512-TEB8ESquiLMc0lV8vcd5Ql/JAKAoyzHFXaStwjkzpOpC5Yv+pIzLfHvjTSdf3vpa2bMiUQrg9i6276yn8666aA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@tootallnate/quickjs-emscripten": "^0.23.0", + "agent-base": "^7.1.2", + "debug": "^4.3.4", + "get-uri": "^6.0.1", + "http-proxy-agent": "^7.0.0", + "https-proxy-agent": "^7.0.6", + "pac-resolver": "^7.0.1", + "socks-proxy-agent": "^8.0.5" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/pac-resolver": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/pac-resolver/-/pac-resolver-7.0.1.tgz", + "integrity": "sha512-5NPgf87AT2STgwa2ntRMr45jTKrYBGkVU36yT0ig/n/GMAa3oPqhZfIQ2kMEimReg0+t9kZViDVZ83qfVUlckg==", + "dev": true, + "license": "MIT", + "dependencies": { + "degenerator": "^5.0.0", + "netmask": "^2.0.2" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/package-json-from-dist": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz", + "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==", + "dev": true, + "license": "BlueOak-1.0.0" + }, + "node_modules/parse5": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/parse5/-/parse5-5.1.1.tgz", + "integrity": "sha512-ugq4DFI0Ptb+WWjAdOK16+u/nHfiIrcE+sh8kZMaM0WllQKLI9rOUq6c2b7cwPkXdzfQESqvoqK6ug7U/Yyzug==", + "dev": true, + "license": "MIT" + }, + "node_modules/parse5-htmlparser2-tree-adapter": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/parse5-htmlparser2-tree-adapter/-/parse5-htmlparser2-tree-adapter-6.0.1.tgz", + "integrity": "sha512-qPuWvbLgvDGilKc5BoicRovlT4MtYT6JfJyBOMDsKoiT+GiuP5qyrPCnR9HcPECIJJmZh5jRndyNThnhhb/vlA==", + "dev": true, + "license": "MIT", + "dependencies": { + "parse5": "^6.0.1" + } + }, + "node_modules/parse5-htmlparser2-tree-adapter/node_modules/parse5": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/parse5/-/parse5-6.0.1.tgz", + "integrity": "sha512-Ofn/CTFzRGTTxwpNEs9PP93gXShHcTq255nzRYSKe8AkVpZY7e1fpmTfOyoIvjP5HG7Z2ZM7VS9PPhQGW2pOpw==", + "dev": true, + "license": "MIT" + }, + "node_modules/partial-json": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/partial-json/-/partial-json-0.1.7.tgz", + "integrity": "sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==", + "dev": true, + "license": "MIT" + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-scurry": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.1.tgz", + "integrity": "sha512-oWyT4gICAu+kaA7QWk/jvCHWarMKNs6pXOGWKDTr7cw4IGcUbW+PeTfbaQiLGheFRpjo6O9J0PmyMfQPjH71oA==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "lru-cache": "^11.0.0", + "minipass": "^7.1.2" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/proper-lockfile": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz", + "integrity": "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==", + "dev": true, + "license": "MIT", + "dependencies": { + "graceful-fs": "^4.2.4", + "retry": "^0.12.0", + "signal-exit": "^3.0.2" + } + }, + "node_modules/protobufjs": { + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.4.tgz", + "integrity": "sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg==", + "dev": true, + "hasInstallScript": true, + "license": "BSD-3-Clause", + "dependencies": { + "@protobufjs/aspromise": "^1.1.2", + "@protobufjs/base64": "^1.1.2", + "@protobufjs/codegen": "^2.0.4", + "@protobufjs/eventemitter": "^1.1.0", + "@protobufjs/fetch": "^1.1.0", + "@protobufjs/float": "^1.0.2", + "@protobufjs/inquire": "^1.1.0", + "@protobufjs/path": "^1.1.2", + "@protobufjs/pool": "^1.1.0", + "@protobufjs/utf8": "^1.1.0", + "@types/node": ">=13.7.0", + "long": "^5.0.0" + }, + "engines": { + "node": ">=12.0.0" + } + }, + "node_modules/proxy-agent": { + "version": "6.5.0", + "resolved": "https://registry.npmjs.org/proxy-agent/-/proxy-agent-6.5.0.tgz", + "integrity": "sha512-TmatMXdr2KlRiA2CyDu8GqR8EjahTG3aY3nXjdzFyoZbmB8hrBsTyMezhULIXKnC0jpfjlmiZ3+EaCzoInSu/A==", + "dev": true, + "license": "MIT", + "dependencies": { + "agent-base": "^7.1.2", + "debug": "^4.3.4", + "http-proxy-agent": "^7.0.1", + "https-proxy-agent": "^7.0.6", + "lru-cache": "^7.14.1", + "pac-proxy-agent": "^7.1.0", + "proxy-from-env": "^1.1.0", + "socks-proxy-agent": "^8.0.5" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/proxy-agent/node_modules/lru-cache": { + "version": "7.18.3", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-7.18.3.tgz", + "integrity": "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/proxy-from-env": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz", + "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==", + "dev": true, + "license": "MIT" + }, + "node_modules/require-directory": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", + "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/retry": { + "version": "0.12.0", + "resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz", + "integrity": "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/rimraf": { + "version": "5.0.10", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-5.0.10.tgz", + "integrity": "sha512-l0OE8wL34P4nJH/H2ffoaniAokM2qSmrtXHmlpvYr5AVVX8msAyW0l8NVJFDxlSK4u3Uh/f41cQheDVdnYijwQ==", + "dev": true, + "license": "ISC", + "dependencies": { + "glob": "^10.3.7" + }, + "bin": { + "rimraf": "dist/esm/bin.mjs" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/rimraf/node_modules/@isaacs/cliui": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz", + "integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==", + "dev": true, + "license": "ISC", + "dependencies": { + "string-width": "^5.1.2", + "string-width-cjs": "npm:string-width@^4.2.0", + "strip-ansi": "^7.0.1", + "strip-ansi-cjs": "npm:strip-ansi@^6.0.1", + "wrap-ansi": "^8.1.0", + "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/rimraf/node_modules/ansi-regex": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz", + "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-regex?sponsor=1" + } + }, + "node_modules/rimraf/node_modules/ansi-styles": { + "version": "6.2.3", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz", + "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/rimraf/node_modules/balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", + "dev": true, + "license": "MIT" + }, + "node_modules/rimraf/node_modules/brace-expansion": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", + "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/rimraf/node_modules/emoji-regex": { + "version": "9.2.2", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz", + "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==", + "dev": true, + "license": "MIT" + }, + "node_modules/rimraf/node_modules/glob": { + "version": "10.5.0", + "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz", + "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==", + "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me", + "dev": true, + "license": "ISC", + "dependencies": { + "foreground-child": "^3.1.0", + "jackspeak": "^3.1.2", + "minimatch": "^9.0.4", + "minipass": "^7.1.2", + "package-json-from-dist": "^1.0.0", + "path-scurry": "^1.11.1" + }, + "bin": { + "glob": "dist/esm/bin.mjs" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/rimraf/node_modules/jackspeak": { + "version": "3.4.3", + "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-3.4.3.tgz", + "integrity": "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "@isaacs/cliui": "^8.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + }, + "optionalDependencies": { + "@pkgjs/parseargs": "^0.11.0" + } + }, + "node_modules/rimraf/node_modules/lru-cache": { + "version": "10.4.3", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz", + "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==", + "dev": true, + "license": "ISC" + }, + "node_modules/rimraf/node_modules/minimatch": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz", + "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/rimraf/node_modules/path-scurry": { + "version": "1.11.1", + "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-1.11.1.tgz", + "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "lru-cache": "^10.2.0", + "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0" + }, + "engines": { + "node": ">=16 || 14 >=14.18" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/rimraf/node_modules/string-width": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz", + "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "eastasianwidth": "^0.2.0", + "emoji-regex": "^9.2.2", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/rimraf/node_modules/strip-ansi": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.2.tgz", + "integrity": "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^6.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/strip-ansi?sponsor=1" + } + }, + "node_modules/rimraf/node_modules/wrap-ansi": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz", + "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.1.0", + "string-width": "^5.0.1", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/safe-buffer": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", + "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/signal-exit": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz", + "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", + "dev": true, + "license": "ISC" + }, + "node_modules/smart-buffer": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz", + "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 6.0.0", + "npm": ">= 3.0.0" + } + }, + "node_modules/socks": { + "version": "2.8.7", + "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.7.tgz", + "integrity": "sha512-HLpt+uLy/pxB+bum/9DzAgiKS8CX1EvbWxI4zlmgGCExImLdiad2iCwXT5Z4c9c3Eq8rP2318mPW2c+QbtjK8A==", + "dev": true, + "license": "MIT", + "dependencies": { + "ip-address": "^10.0.1", + "smart-buffer": "^4.2.0" + }, + "engines": { + "node": ">= 10.0.0", + "npm": ">= 3.0.0" + } + }, + "node_modules/socks-proxy-agent": { + "version": "8.0.5", + "resolved": "https://registry.npmjs.org/socks-proxy-agent/-/socks-proxy-agent-8.0.5.tgz", + "integrity": "sha512-HehCEsotFqbPW9sJ8WVYB6UbmIMv7kUUORIF2Nncq4VQvBfNBLibW9YZR5dlYCSUhwcD628pRllm7n+E+YTzJw==", + "dev": true, + "license": "MIT", + "dependencies": { + "agent-base": "^7.1.2", + "debug": "^4.3.4", + "socks": "^2.8.3" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true, + "license": "BSD-3-Clause", + "optional": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/std-env": { + "version": "3.10.0", + "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz", + "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==", + "dev": true, + "license": "MIT" + }, + "node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/string-width-cjs": { + "name": "string-width", + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-ansi-cjs": { + "name": "strip-ansi", + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strnum": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.1.2.tgz", + "integrity": "sha512-l63NF9y/cLROq/yqKXSLtcMeeyOfnSQlfMSlzFt/K73oIaD8DGaQWd7Z34X9GPiKqP5rbSh84Hl4bOlLcjiSrQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT" + }, + "node_modules/strtok3": { + "version": "10.3.4", + "resolved": "https://registry.npmjs.org/strtok3/-/strtok3-10.3.4.tgz", + "integrity": "sha512-KIy5nylvC5le1OdaaoCJ07L+8iQzJHGH6pWDuzS+d07Cu7n1MZ2x26P8ZKIWfbK02+XIL8Mp4RkWeqdUCrDMfg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@tokenizer/token": "^0.3.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/Borewit" + } + }, + "node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/thenify": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/thenify/-/thenify-3.3.1.tgz", + "integrity": "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==", + "dev": true, + "license": "MIT", + "dependencies": { + "any-promise": "^1.0.0" + } + }, + "node_modules/thenify-all": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/thenify-all/-/thenify-all-1.6.0.tgz", + "integrity": "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==", + "dev": true, + "license": "MIT", + "dependencies": { + "thenify": ">= 3.1.0 < 4" + }, + "engines": { + "node": ">=0.8" + } + }, + "node_modules/token-types": { + "version": "6.1.2", + "resolved": "https://registry.npmjs.org/token-types/-/token-types-6.1.2.tgz", + "integrity": "sha512-dRXchy+C0IgK8WPC6xvCHFRIWYUbqqdEIKPaKo/AcTUNzwLTK6AH7RjdLWsEZcAN/TBdtfUw3PYEgPr5VPr6ww==", + "dev": true, + "license": "MIT", + "dependencies": { + "@borewit/text-codec": "^0.2.1", + "@tokenizer/token": "^0.3.0", + "ieee754": "^1.2.1" + }, + "engines": { + "node": ">=14.16" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/Borewit" + } + }, + "node_modules/ts-algebra": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ts-algebra/-/ts-algebra-2.0.0.tgz", + "integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==", + "dev": true, + "license": "MIT" + }, + "node_modules/tslib": { + "version": "2.8.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", + "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", + "dev": true, + "license": "0BSD" + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/uint8array-extras": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/uint8array-extras/-/uint8array-extras-1.5.0.tgz", + "integrity": "sha512-rvKSBiC5zqCCiDZ9kAOszZcDvdAHwwIKJG33Ykj43OKcWsnmcBRL09YTU4nOeHZ8Y2a7l1MgTd08SBe9A8Qj6A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/undici": { + "version": "7.21.0", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.21.0.tgz", + "integrity": "sha512-Hn2tCQpoDt1wv23a68Ctc8Cr/BHpUSfaPYrkajTXOS9IKpxVRx/X5m1K2YkbK2ipgZgxXSgsUinl3x+2YdSSfg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=20.18.1" + } + }, + "node_modules/undici-types": { + "version": "7.16.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz", + "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==", + "dev": true, + "license": "MIT" + }, + "node_modules/web-streams-polyfill": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz", + "integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 8" + } + }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/wrap-ansi": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/wrap-ansi-cjs": { + "name": "wrap-ansi", + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/ws": { + "version": "8.19.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz", + "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10.0.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": ">=5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/y18n": { + "version": "5.0.8", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", + "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=10" + } + }, + "node_modules/yaml": { + "version": "2.8.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz", + "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==", + "dev": true, + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14.6" + }, + "funding": { + "url": "https://github.com/sponsors/eemeli" + } + }, + "node_modules/yargs": { + "version": "16.2.0", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-16.2.0.tgz", + "integrity": "sha512-D1mvvtDG0L5ft/jGWkLpG1+m0eQxOfaBvTNELraWj22wSVUMWxZUvYgJYcKh6jGGIkJFhH4IZPQhR4TKpc8mBw==", + "dev": true, + "license": "MIT", + "dependencies": { + "cliui": "^7.0.2", + "escalade": "^3.1.1", + "get-caller-file": "^2.0.5", + "require-directory": "^2.1.1", + "string-width": "^4.2.0", + "y18n": "^5.0.5", + "yargs-parser": "^20.2.2" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/yargs-parser": { + "version": "20.2.9", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.9.tgz", + "integrity": "sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=10" + } + }, + "node_modules/yoctocolors": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/yoctocolors/-/yoctocolors-2.1.2.tgz", + "integrity": "sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/zod": { + "version": "4.3.6", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz", + "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==", + "dev": true, + "license": "MIT", + "peer": true, + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/zod-to-json-schema": { + "version": "3.25.1", + "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.1.tgz", + "integrity": "sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==", + "dev": true, + "license": "ISC", + "peerDependencies": { + "zod": "^3.25 || ^4" + } + } + } +} diff --git a/package.json b/package.json index 8781960..96f6be0 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,9 @@ "koan" ], "pi": { - "extensions": ["./extensions"] + "extensions": [ + "./extensions" + ] }, "files": [ "extensions", @@ -19,7 +21,14 @@ "README.md", "LICENSE" ], + "scripts": { + "check": "tsc --noEmit" + }, "dependencies": { "@sinclair/typebox": "^0.32.30" + }, + "devDependencies": { + "@mariozechner/pi-coding-agent": "^0.52.10", + "typescript": "^5.9.3" } } diff --git a/src/planner/phases/context-capture.ts b/src/planner/phases/context-capture.ts index 404e69a..7953614 100644 --- a/src/planner/phases/context-capture.ts +++ b/src/planner/phases/context-capture.ts @@ -77,7 +77,7 @@ export class ContextCapturePhase { // for context-capture, begin() for plan-design). hookDispatch throws // if the slot is already occupied (phase hook ownership prevents // silent misrouting). - hookDispatch(this.dispatch, "onNextStep", () => this.handleSubPhaseComplete()); + hookDispatch(this.dispatch, "onCompleteStep", () => this.handleSubPhaseComplete()); hookDispatch(this.dispatch, "onStoreContext", (p, c) => this.handleContextToolCall(p, c)); this.log("Starting context capture (draft phase)", { planId: plan.id }); @@ -151,19 +151,19 @@ export class ContextCapturePhase { if (event.toolName === "koan_store_context") { return { block: true, - reason: "Draft phase: explore and draft first, then call koan_next_step.", + reason: "Draft phase: explore and draft first, then call koan_complete_step.", }; } return undefined; } if (ctx.subPhase === "verifying") { - if (event.toolName === "koan_next_step") { + if (event.toolName === "koan_complete_step") { return undefined; } return { block: true, - reason: "Verify phase: review your draft, then call koan_next_step. No other tools.", + reason: "Verify phase: review your draft, then call koan_complete_step. No other tools.", }; } @@ -179,77 +179,6 @@ export class ContextCapturePhase { return undefined; }); - - // Safety net: if the LLM ends a turn without calling the expected - // tool, nudge it to try again. The primary transition mechanism is - // tool calls (koan_next_step for sub-phase advancement, - // koan_store_context for completion). This handler only fires when - // the LLM produces a text-only response instead of calling tools. - this.pi.on("agent_end", async (_event, ctx) => { - if (!this.shouldHandle()) return; - const contextState = this.state.context!; - - if (contextState.subPhase === "drafting" || contextState.subPhase === "verifying") { - // LLM ended without calling koan_next_step. - this.log("LLM ended turn without calling koan_next_step", { - subPhase: contextState.subPhase, - }); - this.pi.sendUserMessage( - "You must call koan_next_step when you have finished this step.", - ); - return; - } - - if (contextState.subPhase === "refining") { - // LLM ended without calling koan_store_context. Retry logic. - this.log("Refine phase ended without koan_store_context call", { - attempt: contextState.attempt, - }); - - if (contextState.feedback.length === 0) { - contextState.feedback = [ - "You must call the `koan_store_context` tool with the structured context.", - ]; - } - - const remaining = contextState.maxAttempts - contextState.attempt; - if (remaining > 0) { - contextState.attempt += 1; - ctx.ui.notify("Context capture incomplete. Retrying.", "warning"); - this.sendRefinePrompt(); - return; - } - - contextState.active = false; - this.state.phase = "context-failed"; - // Unhook on both success (handleContextToolCall) and failure - // (agent_end max-attempts). - unhookDispatch(this.dispatch, "onNextStep"); - unhookDispatch(this.dispatch, "onStoreContext"); - await this.updatePlanMetadata({ - status: "context-failed", - context: { - failedAt: new Date().toISOString(), - attempt: contextState.attempt, - }, - }); - ctx.ui.notify("Context capture failed after maximum attempts.", "error"); - } - }); - } - - private sendRefinePrompt(): void { - const ctx = this.state.context!; - const prompt = formatStep( - refineGuidance({ - attempt: ctx.attempt, - maxAttempts: ctx.maxAttempts, - feedback: ctx.feedback, - }), - ); - ctx.lastPrompt = prompt; - this.log("Sending refine prompt", { attempt: ctx.attempt }); - this.pi.sendUserMessage(prompt); } private shouldHandle(): boolean { @@ -292,12 +221,10 @@ export class ContextCapturePhase { this.state.context.lastRawContent = rawText; this.state.context.feedback = []; this.state.phase = "context-complete"; - // Unhook on both success (handleContextToolCall) and failure - // (agent_end max-attempts). - unhookDispatch(this.dispatch, "onNextStep"); + unhookDispatch(this.dispatch, "onCompleteStep"); unhookDispatch(this.dispatch, "onStoreContext"); - ctx.ui.notify("Koan context capture complete.", "success"); + ctx.ui.notify("Koan context capture complete.", "info"); this.log("Context capture succeeded", { planId: this.state.context.planId, attempt: this.state.context.attempt, diff --git a/src/planner/phases/plan-design.ts b/src/planner/phases/plan-design.ts index 8928616..d924294 100644 --- a/src/planner/phases/plan-design.ts +++ b/src/planner/phases/plan-design.ts @@ -85,10 +85,10 @@ export class PlanDesignPhase { this.state.step = 1; // No koan_store_plan tool. Each mutation writes to disk immediately. - // Step 6 ends with koan_next_step, which runs validation. Removes + // Step 6 ends with koan_complete_step, which runs validation. Removes // the two-step 'build then finalize' pattern that caused LLM to skip // intermediate tools. - hookDispatch(this.dispatch, "onNextStep", () => this.handleStepComplete()); + hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); this.log("Starting plan-design workflow", { step: 1 }); await this.progress?.update(`Step 1/6: ${STEP_NAMES[1]} -- started`); @@ -160,7 +160,7 @@ export class PlanDesignPhase { return { ok: false, error: result.errors?.join("; ") }; } this.state.active = false; - unhookDispatch(this.dispatch, "onNextStep"); + unhookDispatch(this.dispatch, "onCompleteStep"); this.log("Plan finalized, workflow complete"); return { ok: true, prompt: "Plan validation passed. Workflow complete." }; } diff --git a/src/planner/prompts/context-capture.ts b/src/planner/prompts/context-capture.ts index 9657e85..2d4ce3d 100644 --- a/src/planner/prompts/context-capture.ts +++ b/src/planner/prompts/context-capture.ts @@ -29,12 +29,14 @@ export function draftGuidance(taskDescription: string): StepGuidance { "- Is there any implicit design knowledge -- invariants, rationale, accepted tradeoffs -- that should be preserved for downstream work?", "- Are there reference documents or specs in the project that apply?", "", - "Write your analysis as a draft. For each dimension, note your confidence:", + "For each dimension, note your confidence:", "- HIGH: you have direct evidence from this session", "- LOW: you are extrapolating or guessing", "", "Flag any LOW-confidence point where a single targeted read would raise it to HIGH.", "This is a working document, not a final artifact.", + "", + "Put your full draft analysis in the `thoughts` parameter when calling koan_complete_step.", ], }; } @@ -50,10 +52,9 @@ export function verifyGuidance(): StepGuidance { "3. Phrasing: would a downstream agent understand without ambiguity?", "", "Rewrite the draft with corrections. If nothing needs changing, reproduce it as-is.", - // Verify phase: tool_call handler blocks all tools except koan_next_step. - // Instruction directs LLM to avoid exploration during review. Two-layer - // defense: prohibition in description, blocking in tool_call handler. "Do not use exploration tools during this review.", + "", + "Put your revised analysis in the `thoughts` parameter when calling koan_complete_step.", ], }; } diff --git a/src/planner/prompts/plan-design.ts b/src/planner/prompts/plan-design.ts index 66e4075..3098981 100644 --- a/src/planner/prompts/plan-design.ts +++ b/src/planner/prompts/plan-design.ts @@ -44,17 +44,13 @@ export function buildPlanDesignSystemPrompt(basePrompt: string): string { "", "You will execute a 6-step workflow.", "Step 1 instructions are in the user message below.", - "Complete the work described, then call koan_next_step.", + "Complete the work described, then call koan_complete_step.", + "Put your findings in the `thoughts` parameter of koan_complete_step.", "The tool result contains the next step's instructions.", - "In step 6, use plan mutation tools, then call koan_next_step.", + "In step 6, use plan mutation tools, then call koan_complete_step.", "", - // Directive prevents immediate tool call without substantive work. - // Failure mode: koan_next_step called with zero file reads, - // producing an empty step with no exploration data. The directive - // repeats guidance from tool descriptions to strengthen the signal. "CRITICAL: Do the actual work described in each step BEFORE calling", - "koan_next_step. Read files, explore code, analyze. Do not skip.", - "Do NOT produce a final text response until koan_next_step completes.", + "koan_complete_step. Read files, explore code, analyze. Do not skip.", ].join("\n"); } @@ -207,7 +203,7 @@ export function planDesignStepGuidance(step: 1 | 2 | 3 | 4 | 5 | 6, context?: st " If file overlap: extract to M0 (foundation) or consolidate", ], invokeAfter: [ - "WHEN DONE: After completing the instructions above, call koan_next_step to validate.", + "WHEN DONE: Call koan_complete_step to validate. Put a summary of what you built in the `thoughts` parameter.", "Do NOT call this tool until you have used the plan mutation tools.", ].join("\n"), }; diff --git a/src/planner/prompts/step.ts b/src/planner/prompts/step.ts index a6598c7..28743eb 100644 --- a/src/planner/prompts/step.ts +++ b/src/planner/prompts/step.ts @@ -1,32 +1,21 @@ // Step prompt assembly for koan workflows. // -// Format matches the reference planner's format_step() in -// skills/lib/workflow/prompts/step.py. Both use "NEXT STEP:" -// directives. Reference uses "Command:" for shell execution. -// Koan uses "Tool:" -- tool results are synchronous within -// the agent loop (deterministic delivery regardless of -p mode). -// -// Why strengthen invoke-after? The original weak format ("Now call -// koan_next_step.") produced skipped steps. Strengthened format -// mirrors reference planner's explicit directive structure. +// The `thoughts` parameter on koan_complete_step captures the model's +// work output (analysis, review, findings) as a tool parameter. This +// avoids requiring the model to produce text + tool_call in one +// response, which some models (e.g. GPT-5-codex) cannot do. export interface StepGuidance { title: string; instructions: string[]; // Custom invoke-after directive. When omitted, formatStep - // appends the default koan_next_step directive. + // appends the default koan_complete_step directive. // Terminal steps override this (e.g., step 6 plan validation). invokeAfter?: string; } -// Default invoke-after: conditional gate for koan_next_step. -// "WHEN DONE" + "Do NOT call until" creates a two-part gate: -// the LLM must complete work before advancing. Unconditional -// imperatives ("Execute this tool now.") cause immediate tool -// calls because tool calls with empty params have zero friction -// (unlike shell commands which require mechanical copy-paste). const DEFAULT_INVOKE = [ - "WHEN DONE: After completing the instructions above, call koan_next_step to advance.", + "WHEN DONE: Call koan_complete_step with your findings in the `thoughts` parameter.", "Do NOT call this tool until the work described in this step is finished.", ].join("\n"); diff --git a/src/planner/session.ts b/src/planner/session.ts index 4bb533a..a14050e 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -25,7 +25,7 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan // Completion callback for context-capture phase. Runs inside the // koan_store_context tool call -- the tool blocks until the architect // subagent finishes. The LLM sees context capture + architect outcome - // in one tool response. No agent_end polling needed. + // in one tool response. const onContextComplete = async (ctx: ExtensionContext): Promise => { if (!state.plan) { return "Context captured but no plan state available."; @@ -83,7 +83,7 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan state.phase = "plan-design-complete"; log("Architect plan-design complete", { planDir }); - ctx.ui.notify("Plan-design phase complete.", "success"); + ctx.ui.notify("Plan-design phase complete.", "info"); return `Context captured. Plan written to ${planDir}/plan.json.`; }; diff --git a/src/planner/tools/dispatch.ts b/src/planner/tools/dispatch.ts index 28e91b8..7bfa629 100644 --- a/src/planner/tools/dispatch.ts +++ b/src/planner/tools/dispatch.ts @@ -1,7 +1,7 @@ // Workflow tool dispatch for koan. // -// Workflow tools (koan_next_step, koan_store_context) are registered once -// at init and read from this dispatch at call time. +// Workflow tools (koan_complete_step, koan_store_context) are registered +// once at init and read from this dispatch at call time. // Pi snapshots tools during _buildRuntime() -- late registration is // invisible to the LLM. The dispatch decouples static registration // from dynamic phase routing. @@ -25,14 +25,14 @@ export interface StepResult { // -- Dispatch -- export interface WorkflowDispatch { - onNextStep: (() => StepResult | Promise) | null; + onCompleteStep: ((thoughts?: string) => StepResult | Promise) | null; onStoreContext: | ((payload: unknown, ctx: ExtensionContext) => Promise) | null; } export function createDispatch(): WorkflowDispatch { - return { onNextStep: null, onStoreContext: null }; + return { onCompleteStep: null, onStoreContext: null }; } // Decouples tool registration (init-time, before _buildRuntime) from @@ -57,14 +57,17 @@ export function hookDispatch( if (dispatch[key] !== null) { throw new Error(`dispatch.${String(key)} is already hooked`); } - (dispatch as Record)[key] = handler; + // TypeScript cannot verify generic key-value assignment. + // Call-site generic constraint (handler: NonNullable) + // ensures type safety; collision guard above prevents double-hooking. + (dispatch as any)[key] = handler; } export function unhookDispatch( dispatch: WorkflowDispatch, key: keyof WorkflowDispatch, ): void { - (dispatch as Record)[key] = null; + (dispatch as any)[key] = null; } // -- Tool registration -- @@ -82,32 +85,36 @@ export function registerWorkflowTools( pi: ExtensionAPI, dispatch: WorkflowDispatch, ): void { - // -- koan_next_step -- - // "DO NOT call until told" creates prohibition/activation pattern - // with step prompts. Description = default prohibition, step prompt - // invoke-after = explicit activation. + // -- koan_complete_step -- + // The `thoughts` parameter captures the model's work output (analysis, + // review, findings) as a tool parameter instead of as text output. + // This ensures models that cannot mix text + tool_call in one response + // (e.g. GPT-5-codex) still advance the workflow reliably. pi.registerTool({ - name: "koan_next_step", - label: "Advance to next workflow step", + name: "koan_complete_step", + label: "Complete current workflow step", description: [ "Signal completion of the current workflow step.", + "Put your analysis, findings, or review in the `thoughts` parameter.", "DO NOT call this tool until the step instructions explicitly tell you to.", - "Do the actual work described in each step BEFORE calling this tool.", ].join(" "), - parameters: Type.Object({}), - async execute() { - // Two-layer defense: tool_call blocks with descriptive reasons - // (primary gate), dispatch null checks as fallback. Dispatch check - // fires only if tool_call handler is bypassed or misconfigured. - if (!dispatch.onNextStep) { + parameters: Type.Object({ + thoughts: Type.Optional(Type.String({ + description: "Your analysis, findings, or work output for this step.", + })), + }), + async execute(_toolCallId, params) { + if (!dispatch.onCompleteStep) { throw new Error("No workflow phase is active."); } - const r = await dispatch.onNextStep(); + const thoughts = (params as { thoughts?: string }).thoughts; + const r = await dispatch.onCompleteStep(thoughts); if (!r.ok) { throw new Error(r.error ?? "Step transition failed."); } return { content: [{ type: "text" as const, text: r.prompt ?? "Step complete." }], + details: undefined, }; }, }); @@ -134,6 +141,7 @@ export function registerWorkflowTools( log("Context stored"); return { content: [{ type: "text" as const, text: r.message }], + details: undefined, }; }, }); diff --git a/src/planner/tools/plan-entities.ts b/src/planner/tools/plan-entities.ts index f431f1a..c38efb2 100644 --- a/src/planner/tools/plan-entities.ts +++ b/src/planner/tools/plan-entities.ts @@ -2,10 +2,13 @@ // Disk is single source of truth. Single-writer assumption per phase. // Feedback messages prevent the LLM from skipping tools (prior architecture // returned opaque JSON). +// +// Static derives the TypeScript type from the TypeBox schema at +// compile time, making type casts unnecessary. The registerTool generic +// propagates the schema type through to the execute callback. -import { Type } from "@sinclair/typebox"; +import { Type, type Static, type TSchema } from "@sinclair/typebox"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import type { TSchema } from "@sinclair/typebox"; import type { PlanRef } from "./dispatch.js"; import { loadPlan, savePlan } from "../plan/serialize.js"; @@ -41,15 +44,15 @@ import { setReadmeEntry, } from "../plan/mutate.js"; -function planTool

( +function planTool( pi: ExtensionAPI, planRef: PlanRef, opts: { name: string; label: string; description: string; - parameters: TSchema; - execute: (plan: Plan, params: P) => { plan: Plan; message: string }; + parameters: TParams; + execute: (plan: Plan, params: Static) => { plan: Plan; message: string }; }, ): void { pi.registerTool({ @@ -60,10 +63,11 @@ function planTool

( async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); const plan = await loadPlan(planRef.dir); - const result = opts.execute(plan, params as P); + const result = opts.execute(plan, params); await savePlan(result.plan, planRef.dir); return { content: [{ type: "text" as const, text: result.message }], + details: undefined, }; }, }); diff --git a/src/planner/tools/plan-getters.ts b/src/planner/tools/plan-getters.ts index ff1fc2e..8154229 100644 --- a/src/planner/tools/plan-getters.ts +++ b/src/planner/tools/plan-getters.ts @@ -21,6 +21,7 @@ export function registerPlanGetterTools( const summary = formatPlanSummary(p); return { content: [{ type: "text" as const, text: summary }], + details: undefined, }; }, }); @@ -35,10 +36,11 @@ export function registerPlanGetterTools( async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); const p = await loadPlan(planRef.dir); - const m = p.milestones.find((x) => x.id === (params as { id: string }).id); - if (!m) throw new Error(`Milestone ${(params as { id: string }).id} not found`); + const m = p.milestones.find((x) => x.id === params.id); + if (!m) throw new Error(`Milestone ${params.id} not found`); return { content: [{ type: "text" as const, text: JSON.stringify(m, null, 2) }], + details: undefined, }; }, }); @@ -54,11 +56,12 @@ export function registerPlanGetterTools( if (!planRef.dir) throw new Error("No plan directory is active."); const p = await loadPlan(planRef.dir); const d = p.planning_context.decision_log.find( - (x) => x.id === (params as { id: string }).id, + (x) => x.id === params.id, ); - if (!d) throw new Error(`Decision ${(params as { id: string }).id} not found`); + if (!d) throw new Error(`Decision ${params.id} not found`); return { content: [{ type: "text" as const, text: JSON.stringify(d, null, 2) }], + details: undefined, }; }, }); @@ -73,9 +76,9 @@ export function registerPlanGetterTools( async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); const p = await loadPlan(planRef.dir); - const result = findIntent(p, (params as { id: string }).id); + const result = findIntent(p, params.id); if (!result) - throw new Error(`Intent ${(params as { id: string }).id} not found`); + throw new Error(`Intent ${params.id} not found`); return { content: [ { @@ -87,6 +90,7 @@ export function registerPlanGetterTools( ), }, ], + details: undefined, }; }, }); @@ -101,9 +105,9 @@ export function registerPlanGetterTools( async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); const p = await loadPlan(planRef.dir); - const result = findChange(p, (params as { id: string }).id); + const result = findChange(p, params.id); if (!result) - throw new Error(`Change ${(params as { id: string }).id} not found`); + throw new Error(`Change ${params.id} not found`); return { content: [ { @@ -115,6 +119,7 @@ export function registerPlanGetterTools( ), }, ], + details: undefined, }; }, }); diff --git a/src/planner/tools/plan-setters.ts b/src/planner/tools/plan-setters.ts index 16a0a87..4478254 100644 --- a/src/planner/tools/plan-setters.ts +++ b/src/planner/tools/plan-setters.ts @@ -24,13 +24,11 @@ export function registerPlanSetterTools( async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); const p = await loadPlan(planRef.dir); - const updated = setOverview( - p, - params as { problem?: string; approach?: string }, - ); + const updated = setOverview(p, params); await savePlan(updated, planRef.dir); return { content: [{ type: "text" as const, text: "Overview updated." }], + details: undefined, }; }, }); @@ -45,18 +43,16 @@ export function registerPlanSetterTools( async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); const p = await loadPlan(planRef.dir); - const updated = setConstraints( - p, - (params as { constraints: string[] }).constraints, - ); + const updated = setConstraints(p, params.constraints); await savePlan(updated, planRef.dir); return { content: [ { type: "text" as const, - text: `Constraints set (${(params as { constraints: string[] }).constraints.length} items).`, + text: `Constraints set (${params.constraints.length} items).`, }, ], + details: undefined, }; }, }); @@ -73,19 +69,13 @@ export function registerPlanSetterTools( async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); const p = await loadPlan(planRef.dir); - const updated = setInvisibleKnowledge( - p, - params as { - system?: string; - invariants?: string[]; - tradeoffs?: string[]; - }, - ); + const updated = setInvisibleKnowledge(p, params); await savePlan(updated, planRef.dir); return { content: [ { type: "text" as const, text: "Invisible knowledge updated." }, ], + details: undefined, }; }, }); diff --git a/src/planner/tools/qr-tools.ts b/src/planner/tools/qr-tools.ts index bf62bda..4d43331 100644 --- a/src/planner/tools/qr-tools.ts +++ b/src/planner/tools/qr-tools.ts @@ -4,7 +4,7 @@ import { promises as fs } from "node:fs"; import * as path from "node:path"; import type { PlanRef } from "./dispatch.js"; -import type { QRFile, QRSeverity, QRItemStatus } from "../qr/types.js"; +import type { QRFile } from "../qr/types.js"; import { addQRItem, setQRItem, assignGroup } from "../qr/mutate.js"; function createEmptyQRFile(phase: string): QRFile { @@ -55,17 +55,12 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const p = params as { - phase: string; - scope: string; - check: string; - severity?: QRSeverity; - }; - const qr = await loadQR(planRef.dir, p.phase); - const r = addQRItem(qr, p); - await saveQR(r.qr, planRef.dir, p.phase); + const qr = await loadQR(planRef.dir, params.phase); + const r = addQRItem(qr, params); + await saveQR(r.qr, planRef.dir, params.phase); return { content: [{ type: "text" as const, text: `Added QR item ${r.id}` }], + details: undefined, }; }, }); @@ -96,19 +91,12 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const p = params as { - phase: string; - id: string; - status?: QRItemStatus; - finding?: string; - check?: string; - severity?: QRSeverity; - }; - const qr = await loadQR(planRef.dir, p.phase); - const updated = setQRItem(qr, p.id, p); - await saveQR(updated, planRef.dir, p.phase); + const qr = await loadQR(planRef.dir, params.phase); + const updated = setQRItem(qr, params.id, params); + await saveQR(updated, planRef.dir, params.phase); return { - content: [{ type: "text" as const, text: `Updated QR item ${p.id}` }], + content: [{ type: "text" as const, text: `Updated QR item ${params.id}` }], + details: undefined, }; }, }); @@ -124,21 +112,17 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const p = params as { - phase: string; - ids: string[]; - group_id: string; - }; - const qr = await loadQR(planRef.dir, p.phase); - const updated = assignGroup(qr, p.ids, p.group_id); - await saveQR(updated, planRef.dir, p.phase); + const qr = await loadQR(planRef.dir, params.phase); + const updated = assignGroup(qr, params.ids, params.group_id); + await saveQR(updated, planRef.dir, params.phase); return { content: [ { type: "text" as const, - text: `Assigned ${p.ids.length} items to group ${p.group_id}`, + text: `Assigned ${params.ids.length} items to group ${params.group_id}`, }, ], + details: undefined, }; }, }); @@ -153,12 +137,12 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const p = params as { phase: string; id: string }; - const qr = await loadQR(planRef.dir, p.phase); - const item = qr.items.find((x) => x.id === p.id); - if (!item) throw new Error(`QR item ${p.id} not found`); + const qr = await loadQR(planRef.dir, params.phase); + const item = qr.items.find((x) => x.id === params.id); + if (!item) throw new Error(`QR item ${params.id} not found`); return { content: [{ type: "text" as const, text: JSON.stringify(item, null, 2) }], + details: undefined, }; }, }); @@ -179,15 +163,15 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const p = params as { phase: string; status?: QRItemStatus }; - const qr = await loadQR(planRef.dir, p.phase); - const filtered = p.status - ? qr.items.filter((item) => item.status === p.status) + const qr = await loadQR(planRef.dir, params.phase); + const filtered = params.status + ? qr.items.filter((item) => item.status === params.status) : qr.items; return { content: [ { type: "text" as const, text: JSON.stringify(filtered, null, 2) }, ], + details: undefined, }; }, }); @@ -201,8 +185,7 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const p = params as { phase: string }; - const qr = await loadQR(planRef.dir, p.phase); + const qr = await loadQR(planRef.dir, params.phase); const byStatus = { TODO: qr.items.filter((x) => x.status === "TODO").length, @@ -226,6 +209,7 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { content: [ { type: "text" as const, text: JSON.stringify(summary, null, 2) }, ], + details: undefined, }; }, }); diff --git a/src/planner/tools/registry.ts b/src/planner/tools/registry.ts index 36391c1..5151f7a 100644 --- a/src/planner/tools/registry.ts +++ b/src/planner/tools/registry.ts @@ -99,11 +99,11 @@ export const PLAN_MUTATION_TOOLS: ReadonlySet = new Set([ // updating the permissions map. export const PHASE_PERMISSIONS: ReadonlyMap> = new Map([ - ["context-capture", new Set(["koan_store_context", "koan_next_step"])], + ["context-capture", new Set(["koan_store_context", "koan_complete_step"])], [ "plan-design", new Set([ - "koan_next_step", + "koan_complete_step", ...PLAN_GETTER_TOOLS_LIST, ...PLAN_SETTER_TOOLS_LIST, ...PLAN_DESIGN_ENTITY_TOOLS, @@ -112,7 +112,7 @@ export const PHASE_PERMISSIONS: ReadonlyMap> = [ "plan-code", new Set([ - "koan_next_step", + "koan_complete_step", ...PLAN_GETTER_TOOLS_LIST, ...PLAN_CHANGE_TOOLS_LIST, "koan_set_intent", @@ -121,7 +121,7 @@ export const PHASE_PERMISSIONS: ReadonlyMap> = [ "plan-docs", new Set([ - "koan_next_step", + "koan_complete_step", ...PLAN_GETTER_TOOLS_LIST, "koan_set_change_doc_diff", "koan_set_change_comments", @@ -131,12 +131,12 @@ export const PHASE_PERMISSIONS: ReadonlyMap> = ], [ "qr-plan-design", - new Set(["koan_next_step", ...PLAN_GETTER_TOOLS_LIST, ...QR_TOOLS_LIST]), + new Set(["koan_complete_step", ...PLAN_GETTER_TOOLS_LIST, ...QR_TOOLS_LIST]), ], [ "qr-plan-code", new Set([ - "koan_next_step", + "koan_complete_step", "koan_get_plan", "koan_get_milestone", "koan_get_intent", @@ -147,7 +147,7 @@ export const PHASE_PERMISSIONS: ReadonlyMap> = [ "qr-plan-docs", new Set([ - "koan_next_step", + "koan_complete_step", "koan_get_plan", "koan_get_milestone", "koan_get_change", diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..d8a1c33 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,15 @@ +{ + "compilerOptions": { + "strict": true, + "noEmit": true, + "target": "ES2022", + "module": "Node16", + "moduleResolution": "Node16", + "esModuleInterop": true, + "skipLibCheck": true + }, + "include": [ + "src/**/*.ts", + "extensions/**/*.ts" + ] +} From 7f2ecdcff07591ec5bdbc919cb3710c8ab4103fa Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Feb 2026 16:47:45 +0700 Subject: [PATCH 005/412] Update design-decisions.md for koan_complete_step rename Replace all stale koan_next_step references, document agent_end anti-pattern, add AD-5 thoughts parameter rationale. --- design-decisions.md | 75 ++++++++++++++++---------- src/planner/prompts/context-capture.ts | 2 +- 2 files changed, 47 insertions(+), 30 deletions(-) diff --git a/design-decisions.md b/design-decisions.md index 7a10117..132572a 100644 --- a/design-decisions.md +++ b/design-decisions.md @@ -24,6 +24,7 @@ between exposing more or less information, always choose less. This is a permanent invariant. Concrete implications: + - No implementation details in prompts (temp dirs, state file paths, orchestrator internals, phase routing) - No full plan state when partial suffices (QR reviewer for design does @@ -56,6 +57,7 @@ from tools: always `throw new Error(msg)` -- never `return { isError: true }`. ### AD-2: Self-Loading Extension Pattern Same extension file (extensions/koan.ts) serves both modes: + - **Parent mode** (no --koan-role flag): registers /koan command, tools, and dispatch. Zero overhead in normal pi sessions. - **Subagent mode** (--koan-role present): activates role-specific event @@ -74,29 +76,40 @@ to ensure one-shot dispatch. ### AD-4: Tool-Call-Driven Step Transitions (Uniform Pattern) -ALL step transitions use the koan_next_step registered tool. The LLM -calls koan_next_step -> tool execute() returns next step's prompt. +ALL step transitions use the koan_complete_step registered tool. The LLM +calls koan_complete_step -> tool execute() returns next step's prompt. This works in both -p mode and interactive mode. sendUserMessage() -is only used for the initial trigger (/koan plan) and as a safety net -in agent_end when the LLM fails to call the expected tool. +is only used for the initial trigger (/koan plan). -**KEY CORRECTION**: Early design (Feb 10) considered turn_end + agent_end -+ sendUserMessage() chaining for step transitions. This was ABANDONED -because subagents in -p mode exit after the first agent loop completes. -Tool calls keep the agent loop alive within a single loop. The context -capture phase preserves sendUserMessage() in agent_end only as a -fallback retry mechanism, not as the primary transition path. +**KEY CORRECTION**: Early design (Feb 10) considered turn_end + +agent_end + sendUserMessage() chaining for step transitions. This was +ABANDONED because subagents in -p mode exit after the first agent loop +completes. Tool calls keep the agent loop alive within a single loop. -### AD-5: koan_next_step Has No Arguments +**ANTI-PATTERN**: agent_end + sendUserMessage for retry was removed. +sendUserMessage is fire-and-forget in the extension binding. In -p mode +(subagents), the process can exit before the retry completes. Even in +interactive mode, some models say "calling tool X now" as text without +emitting a tool_call block, causing agent_end to fire spuriously. + +### AD-5: koan_complete_step Accepts Optional `thoughts` The extension is stateful -- it knows exactly which step the LLM is on via closure state. No step number parameter needed. The tool response contains the next step's full prompt. +The optional `thoughts` parameter captures the model's work output +(analysis, findings, review) as a tool parameter instead of as text +output. This solves a cross-model compatibility issue: GPT-5-codex +cannot produce text + tool_call in the same response, so requiring +text output alongside a tool call caused it to narrate "Calling +koan_complete_step now" without emitting an actual tool_call block. + ### AD-6: Tool Naming Conventions Settled names (corrected from earlier iterations): -- `koan_next_step` (was koan_complete_step) + +- `koan_complete_step` (was koan_next_step -- renamed to accept `thoughts`) - `koan_store_context` (was koan_finalize_context) - `koan_store_plan` was later REMOVED entirely (see AD-14) - Prompts use "instructions" not "actions" @@ -104,7 +117,7 @@ Settled names (corrected from earlier iterations): ### AD-7: invoke_after Pattern Is Critical Every step prompt MUST have a clear "invoke after" directive telling -the LLM to call koan_next_step after completing the step's work. +the LLM to call koan_complete_step after completing the step's work. Mirrors the reference planner's "NEXT STEP: Command: python3 -m ... --step N" pattern. Without this, the LLM produces text-only responses and the agent loop exits. @@ -148,12 +161,13 @@ per user preference. ### AD-12: Context Capture Phases Three sub-phases within context capture: + 1. **Drafting**: LLM reflects on conversation. MAY use tools for "high value" targeted exploration (confirm API signature, check file existence). DO NOT explore speculatively. Confidence tagging: HIGH (direct evidence) vs LOW (extrapolating). 2. **Verifying**: Self-check. Completeness, accuracy, phrasing for - downstream agents. No tools except koan_next_step. + downstream agents. No tools except koan_complete_step. 3. **Refining**: Pure tool invocation (koan_store_context). Up to 3 attempts with validation feedback. @@ -199,7 +213,7 @@ needs evidence that each tool call produces results. 5. Assumption Surfacing 6. Milestone Definition & Plan Writing (plan mutation tools available) -Steps 1-5: only READ_TOOLS + PLAN_GETTER_TOOLS + koan_next_step allowed. +Steps 1-5: only READ_TOOLS + PLAN_GETTER_TOOLS + koan_complete_step allowed. Step 6: plan mutation tools unlocked. --- @@ -208,7 +222,7 @@ Step 6: plan mutation tools unlocked. ### WorkflowDispatch (dispatch pattern) -Workflow tools (koan_next_step, koan_store_context) are registered once +Workflow tools (koan_complete_step, koan_store_context) are registered once at init. Their execute() callbacks read from a mutable dispatch object. Phases hook/unhook dispatch slots at activation/deactivation time. @@ -221,9 +235,9 @@ All plan mutation tools share a mutable `{ dir: string | null }` set when /koan plan creates a directory or when --koan-plan-dir is received. Decouples tool registration (init-time) from directory creation (runtime). -### Pi Registers Tools at _buildRuntime() +### Pi Registers Tools at \_buildRuntime() -Pi snapshots tools during _buildRuntime(). Tools registered after this +Pi snapshots tools during \_buildRuntime(). Tools registered after this point are invisible to the LLM. All 44+ tools register unconditionally at init; phases restrict access via tool_call blocking at runtime. @@ -231,15 +245,15 @@ at init; phases restrict access via tool_call blocking at runtime. ## What Is NOT Ported from Reference Planner -| Reference planner component | Koan replacement | -|----|-----| -| CLI mutation scripts (cli/plan.py) | Pi extension tool registration | +| Reference planner component | Koan replacement | +| --------------------------------------- | ------------------------------------- | +| CLI mutation scripts (cli/plan.py) | Pi extension tool registration | | Thin router pattern (shared/routing.py) | Orchestrator deterministic gate logic | -| File-based state_dir | In-memory state + appendEntry() | -| Template dispatch | Direct process spawning | -| Constraint enforcement via prompt | tool_call event blocking | -| Agent markdown definitions | Self-loading extension pattern | -| Question relay handler | Not implemented (may add later) | +| File-based state_dir | In-memory state + appendEntry() | +| Template dispatch | Direct process spawning | +| Constraint enforcement via prompt | tool_call event blocking | +| Agent markdown definitions | Self-loading extension pattern | +| Question relay handler | Not implemented (may add later) | --- @@ -256,7 +270,7 @@ tool usage instructions, coding style guides, or editor/IDE conventions." ### BUG-2: LLM Skips Mutation Tools -The LLM called koan_next_step through steps 1-5, then at step 6 skipped +The LLM called koan_complete_step through steps 1-5, then at step 6 skipped all mutation tools and called koan_store_plan directly. The in-memory plan was empty. Root cause: mutation tools returned opaque JSON with no feedback -- they felt like ceremony. Solution: remove finalize tool, @@ -280,8 +294,9 @@ always throw new Error(msg) for error conditions (INV-3). Original weak format ("Now call koan_next_step.") produced skipped steps. The LLM called the tool immediately without doing work, because tool calls with empty params have zero friction. Solution: strengthen to -"WHEN DONE: After completing the instructions above, call koan_next_step. -Do NOT call this tool until the work described in this step is finished." +"WHEN DONE: Call koan_complete_step with your findings in the `thoughts` +parameter. Do NOT call this tool until the work described in this step +is finished." ### BUG-6: Flag Detection at Init Time @@ -320,6 +335,7 @@ koan_qr_get_item, koan_qr_list_items, koan_qr_summary. ## Current Implementation State (Feb 13 2026) Implemented: + - [x] Extension entry point with dual-mode detection - [x] Context capture (3-phase: draft/verify/refine) - [x] Plan-design architect subagent (6-step workflow) @@ -331,6 +347,7 @@ Implemented: - [x] Plan validation (design + cross-references) Not yet implemented: + - [ ] Developer role (plan-code phase) - [ ] Technical writer role (plan-docs phase) - [ ] QR decompose subagent diff --git a/src/planner/prompts/context-capture.ts b/src/planner/prompts/context-capture.ts index 2d4ce3d..2236b5b 100644 --- a/src/planner/prompts/context-capture.ts +++ b/src/planner/prompts/context-capture.ts @@ -83,7 +83,7 @@ export function refineGuidance(opts: RefinePromptOptions): StepGuidance { return { title: "Context Capture: Refine", instructions, - // Refine completes with koan_store_context, not koan_next_step. + // Refine completes with koan_store_context, not koan_complete_step. invokeAfter: [ "WHEN DONE: After completing the instructions above, call koan_store_context with the verified context data.", "Do NOT call this tool until you have prepared the structured context.", From f03bd05c2bd982f98903fc9668e04b668b2e4b93 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 23 Feb 2026 14:11:53 +0700 Subject: [PATCH 006/412] Add CI workflow and initial test --- .github/workflows/ci.yml | 28 +++++++++++++++++++++++++++ .gitignore | 1 + package.json | 5 ++++- tests/progress.test.ts | 41 ++++++++++++++++++++++++++++++++++++++++ tsconfig.build.json | 14 ++++++++++++++ 5 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/ci.yml create mode 100644 tests/progress.test.ts create mode 100644 tsconfig.build.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..81e033b --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,28 @@ +name: CI + +on: + push: + branches: ["main"] + pull_request: + +jobs: + build-and-test: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + + - name: Install dependencies + run: npm ci + + - name: Type check + run: npm run check + + - name: Build and test + run: npm test diff --git a/.gitignore b/.gitignore index 97d66e2..b3bc902 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ node_modules/ dist/ +build/ .pi/ .DS_Store diff --git a/package.json b/package.json index 96f6be0..feaae5b 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,10 @@ "LICENSE" ], "scripts": { - "check": "tsc --noEmit" + "check": "tsc --noEmit", + "build": "tsc --project tsconfig.build.json", + "pretest": "npm run build", + "test": "node --test build/tests" }, "dependencies": { "@sinclair/typebox": "^0.32.30" diff --git a/tests/progress.test.ts b/tests/progress.test.ts new file mode 100644 index 0000000..3a69e40 --- /dev/null +++ b/tests/progress.test.ts @@ -0,0 +1,41 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import { ProgressReporter, readSubagentState } from "../src/utils/progress.js"; + +async function createTempDir(prefix: string): Promise { + const base = await fs.mkdtemp(path.join(os.tmpdir(), prefix)); + return base; +} + +describe("ProgressReporter", () => { + it("persists progress updates and completion state", async () => { + const tempRoot = await createTempDir("koan-progress-"); + const reporterDir = path.join(tempRoot, "reporter"); + await fs.mkdir(reporterDir, { recursive: true }); + + const reporter = new ProgressReporter(reporterDir, "planner", "analysis"); + + await reporter.update("gathering context"); + await reporter.update("synthesizing plan"); + await reporter.complete("completed"); + + const state = await readSubagentState(reporterDir); + assert.ok(state, "state file should be readable"); + assert.equal(state.role, "planner"); + assert.equal(state.phase, "analysis"); + assert.equal(state.status, "completed"); + assert.equal(state.current, "completed"); + assert.equal(state.trail.length, 3); + assert.deepEqual( + state.trail.map((entry) => entry.msg), + ["gathering context", "synthesizing plan", "completed"], + "trail should capture chronological updates" + ); + + await fs.rm(tempRoot, { recursive: true, force: true }); + }); +}); diff --git a/tsconfig.build.json b/tsconfig.build.json new file mode 100644 index 0000000..2591980 --- /dev/null +++ b/tsconfig.build.json @@ -0,0 +1,14 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "noEmit": false, + "outDir": "./build", + "declaration": false, + "sourceMap": false + }, + "include": [ + "src/**/*.ts", + "extensions/**/*.ts", + "tests/**/*.ts" + ] +} From 741e50fa729d0833157c47c307f90bd6ce5c998a Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 23 Feb 2026 14:18:12 +0700 Subject: [PATCH 007/412] Add CI workflow dispatch --- .github/workflows/ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 81e033b..e305aad 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,6 +4,7 @@ on: push: branches: ["main"] pull_request: + workflow_dispatch: jobs: build-and-test: From cbf89dbe3cb2b9f649a2b333ea0b2bf335af7eeb Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 23 Feb 2026 17:22:46 +0700 Subject: [PATCH 008/412] Polish --- extensions/koan.ts | 12 +- src/planner/lib/dispatch.ts | 63 ++ .../{tools/registry.ts => lib/permissions.ts} | 0 src/planner/{prompts => lib}/step.ts | 0 .../phase.ts} | 18 +- .../context-capture/prompts.ts} | 2 +- src/planner/phases/dispatch.ts | 4 +- .../{plan-design.ts => plan-design/phase.ts} | 16 +- .../plan-design/prompts.ts} | 4 +- src/planner/plan/mutate.ts | 667 ------------------ src/planner/plan/mutate/code.ts | 161 +++++ src/planner/plan/mutate/decisions.ts | 178 +++++ src/planner/plan/mutate/index.ts | 48 ++ src/planner/plan/mutate/milestones.ts | 91 +++ src/planner/plan/mutate/structure.ts | 164 +++++ src/planner/plan/mutate/top-level.ts | 37 + src/planner/plan/types.ts | 4 - src/planner/qr/mutate.ts | 3 - src/planner/qr/types.ts | 1 - src/planner/session.ts | 4 +- src/planner/tools/entity-code.ts | 171 +++++ src/planner/tools/entity-design.ts | 306 ++++++++ src/planner/tools/entity-structure.ts | 156 ++++ .../tools/{plan-getters.ts => getters.ts} | 2 +- src/planner/tools/index.ts | 36 + src/planner/tools/plan-entities.ts | 603 ---------------- src/planner/tools/{qr-tools.ts => qr.ts} | 64 +- .../tools/{plan-setters.ts => setters.ts} | 4 +- .../tools/{dispatch.ts => workflow.ts} | 73 +- src/utils/lock.ts | 44 ++ 30 files changed, 1527 insertions(+), 1409 deletions(-) create mode 100644 src/planner/lib/dispatch.ts rename src/planner/{tools/registry.ts => lib/permissions.ts} (100%) rename src/planner/{prompts => lib}/step.ts (100%) rename src/planner/phases/{context-capture.ts => context-capture/phase.ts} (95%) rename src/planner/{prompts/context-capture.ts => phases/context-capture/prompts.ts} (98%) rename src/planner/phases/{plan-design.ts => plan-design/phase.ts} (94%) rename src/planner/{prompts/plan-design.ts => phases/plan-design/prompts.ts} (98%) delete mode 100644 src/planner/plan/mutate.ts create mode 100644 src/planner/plan/mutate/code.ts create mode 100644 src/planner/plan/mutate/decisions.ts create mode 100644 src/planner/plan/mutate/index.ts create mode 100644 src/planner/plan/mutate/milestones.ts create mode 100644 src/planner/plan/mutate/structure.ts create mode 100644 src/planner/plan/mutate/top-level.ts create mode 100644 src/planner/tools/entity-code.ts create mode 100644 src/planner/tools/entity-design.ts create mode 100644 src/planner/tools/entity-structure.ts rename src/planner/tools/{plan-getters.ts => getters.ts} (99%) create mode 100644 src/planner/tools/index.ts delete mode 100644 src/planner/tools/plan-entities.ts rename src/planner/tools/{qr-tools.ts => qr.ts} (78%) rename src/planner/tools/{plan-setters.ts => setters.ts} (96%) rename src/planner/tools/{dispatch.ts => workflow.ts} (58%) create mode 100644 src/utils/lock.ts diff --git a/extensions/koan.ts b/extensions/koan.ts index 3fce06c..30288d7 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -2,11 +2,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { createSession } from "../src/planner/session.js"; import { detectSubagentMode, dispatchPhase } from "../src/planner/phases/dispatch.js"; -import { createDispatch, registerWorkflowTools, createPlanRef } from "../src/planner/tools/dispatch.js"; -import { registerPlanGetterTools } from "../src/planner/tools/plan-getters.js"; -import { registerPlanSetterTools } from "../src/planner/tools/plan-setters.js"; -import { registerPlanEntityTools } from "../src/planner/tools/plan-entities.js"; -import { registerQRTools } from "../src/planner/tools/qr-tools.js"; +import { registerAllTools, createDispatch, createPlanRef } from "../src/planner/tools/index.js"; import { createLogger } from "../src/utils/logger.js"; export default function koan(pi: ExtensionAPI): void { @@ -42,11 +38,7 @@ export default function koan(pi: ExtensionAPI): void { const dispatch = createDispatch(); const planRef = createPlanRef(); - registerWorkflowTools(pi, dispatch); - registerPlanGetterTools(pi, planRef); - registerPlanSetterTools(pi, planRef); - registerPlanEntityTools(pi, planRef); - registerQRTools(pi, planRef); + registerAllTools(pi, planRef, dispatch); // Subagent detection runs at before_agent_start (flags // are unavailable during init). diff --git a/src/planner/lib/dispatch.ts b/src/planner/lib/dispatch.ts new file mode 100644 index 0000000..cf8ec02 --- /dev/null +++ b/src/planner/lib/dispatch.ts @@ -0,0 +1,63 @@ +// Shared workflow dispatch and plan-ref infrastructure. +// Decouples static tool registration (init-time) from dynamic phase routing (runtime). +// All mutable slots are null by default; phases hook/unhook on begin/end. + +import type { ExtensionContext } from "@mariozechner/pi-coding-agent"; + +import type { ContextToolResult } from "../tools/context-store.js"; + +// -- Result types -- + +export interface StepResult { + ok: boolean; + prompt?: string; + error?: string; +} + +// -- Dispatch -- + +export interface WorkflowDispatch { + onCompleteStep: ((thoughts?: string) => StepResult | Promise) | null; + onStoreContext: + | ((payload: unknown, ctx: ExtensionContext) => Promise) + | null; +} + +export function createDispatch(): WorkflowDispatch { + return { onCompleteStep: null, onStoreContext: null }; +} + +// Decouples tool registration (init-time, before _buildRuntime) from +// plan directory creation (runtime, after flags available). Same +// indirection pattern as WorkflowDispatch. +export interface PlanRef { + dir: string | null; +} + +export function createPlanRef(): PlanRef { + return { dir: null }; +} + +// Sets a dispatch slot. Throws if the slot is already occupied -- +// prevents silent misrouting when two phases attempt to claim +// the same tool. +export function hookDispatch( + dispatch: WorkflowDispatch, + key: K, + handler: NonNullable, +): void { + if (dispatch[key] !== null) { + throw new Error(`dispatch.${String(key)} is already hooked`); + } + // TypeScript cannot verify generic key-value assignment. + // Call-site generic constraint (handler: NonNullable) + // ensures type safety; collision guard above prevents double-hooking. + (dispatch as any)[key] = handler; +} + +export function unhookDispatch( + dispatch: WorkflowDispatch, + key: keyof WorkflowDispatch, +): void { + (dispatch as any)[key] = null; +} diff --git a/src/planner/tools/registry.ts b/src/planner/lib/permissions.ts similarity index 100% rename from src/planner/tools/registry.ts rename to src/planner/lib/permissions.ts diff --git a/src/planner/prompts/step.ts b/src/planner/lib/step.ts similarity index 100% rename from src/planner/prompts/step.ts rename to src/planner/lib/step.ts diff --git a/src/planner/phases/context-capture.ts b/src/planner/phases/context-capture/phase.ts similarity index 95% rename from src/planner/phases/context-capture.ts rename to src/planner/phases/context-capture/phase.ts index 7953614..4b7320e 100644 --- a/src/planner/phases/context-capture.ts +++ b/src/planner/phases/context-capture/phase.ts @@ -8,15 +8,15 @@ import { verifyGuidance, refineGuidance, type RefinePromptOptions, -} from "../prompts/context-capture.js"; -import { formatStep } from "../prompts/step.js"; -import type { ContextCaptureState, PlanInfo, WorkflowState } from "../state.js"; -import type { ContextData } from "../types.js"; -import { CONTEXT_KEYS } from "../types.js"; -import type { ContextToolResult } from "../tools/context-store.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch } from "../tools/dispatch.js"; -import { createLogger, type Logger } from "../../utils/logger.js"; -import { checkPermission } from "../tools/registry.js"; +} from "./prompts.js"; +import { formatStep } from "../../lib/step.js"; +import type { ContextCaptureState, PlanInfo, WorkflowState } from "../../state.js"; +import type { ContextData } from "../../types.js"; +import { CONTEXT_KEYS } from "../../types.js"; +import type { ContextToolResult } from "../../tools/context-store.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch } from "../../lib/dispatch.js"; +import { createLogger, type Logger } from "../../../utils/logger.js"; +import { checkPermission } from "../../lib/permissions.js"; const MAX_ATTEMPTS = 3; diff --git a/src/planner/prompts/context-capture.ts b/src/planner/phases/context-capture/prompts.ts similarity index 98% rename from src/planner/prompts/context-capture.ts rename to src/planner/phases/context-capture/prompts.ts index 2236b5b..575d801 100644 --- a/src/planner/prompts/context-capture.ts +++ b/src/planner/phases/context-capture/prompts.ts @@ -1,4 +1,4 @@ -import type { StepGuidance } from "./step.js"; +import type { StepGuidance } from "../../lib/step.js"; export function draftGuidance(taskDescription: string): StepGuidance { return { diff --git a/src/planner/phases/dispatch.ts b/src/planner/phases/dispatch.ts index ce72f8a..acb9dfc 100644 --- a/src/planner/phases/dispatch.ts +++ b/src/planner/phases/dispatch.ts @@ -1,8 +1,8 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import { PlanDesignPhase } from "./plan-design.js"; +import { PlanDesignPhase } from "./plan-design/phase.js"; import { createLogger, type Logger } from "../../utils/logger.js"; -import type { WorkflowDispatch, PlanRef } from "../tools/dispatch.js"; +import type { WorkflowDispatch, PlanRef } from "../lib/dispatch.js"; export interface SubagentConfig { role: string; diff --git a/src/planner/phases/plan-design.ts b/src/planner/phases/plan-design/phase.ts similarity index 94% rename from src/planner/phases/plan-design.ts rename to src/planner/phases/plan-design/phase.ts index d924294..b7c493a 100644 --- a/src/planner/phases/plan-design.ts +++ b/src/planner/phases/plan-design/phase.ts @@ -3,20 +3,20 @@ import * as path from "node:path"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import { validatePlanDesign, validateRefs } from "../plan/validate.js"; +import { validatePlanDesign, validateRefs } from "../../plan/validate.js"; import { loadPlanDesignSystemPrompt, formatContextForStep1, buildPlanDesignSystemPrompt, planDesignStepGuidance, STEP_NAMES, -} from "../prompts/plan-design.js"; -import { formatStep } from "../prompts/step.js"; -import type { ContextData } from "../types.js"; -import { createLogger, type Logger } from "../../utils/logger.js"; -import { ProgressReporter } from "../../utils/progress.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../tools/dispatch.js"; -import { checkPermission, PLAN_MUTATION_TOOLS } from "../tools/registry.js"; +} from "./prompts.js"; +import { formatStep } from "../../lib/step.js"; +import type { ContextData } from "../../types.js"; +import { createLogger, type Logger } from "../../../utils/logger.js"; +import { ProgressReporter } from "../../../utils/progress.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; +import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; type PlanDesignStep = 1 | 2 | 3 | 4 | 5 | 6; diff --git a/src/planner/prompts/plan-design.ts b/src/planner/phases/plan-design/prompts.ts similarity index 98% rename from src/planner/prompts/plan-design.ts rename to src/planner/phases/plan-design/prompts.ts index 3098981..2f5727e 100644 --- a/src/planner/prompts/plan-design.ts +++ b/src/planner/phases/plan-design/prompts.ts @@ -2,8 +2,8 @@ import { promises as fs } from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; -import type { ContextData } from "../types.js"; -import type { StepGuidance } from "./step.js"; +import type { ContextData } from "../../types.js"; +import type { StepGuidance } from "../../lib/step.js"; export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { 1: "Task Analysis & Exploration Planning", diff --git a/src/planner/plan/mutate.ts b/src/planner/plan/mutate.ts deleted file mode 100644 index 666af63..0000000 --- a/src/planner/plan/mutate.ts +++ /dev/null @@ -1,667 +0,0 @@ -// Monotonic version counter on entities. No CAS enforcement -- single-writer -// per phase. Counter is for debugging and audit trail, not concurrency control. - -import type { - Plan, - Decision, - RejectedAlternative, - Risk, - Milestone, - CodeIntent, - CodeChange, - Wave, - DiagramGraph, - DiagramNode, - DiagramEdge, - ReadmeEntry, - Overview, - InvisibleKnowledge, -} from "./types.js"; -import { - nextDecisionId, - nextMilestoneId, - nextIntentId, - nextRiskId, - nextRejectedAltId, - nextWaveId, - nextDiagramId, - nextChangeId, -} from "./types.js"; - -// -- Top-level -- - -export function setOverview( - p: Plan, - data: { problem?: string; approach?: string }, -): Plan { - const overview: Overview = { - problem: data.problem ?? p.overview.problem, - approach: data.approach ?? p.overview.approach, - }; - return { ...p, overview }; -} - -export function setConstraints(p: Plan, constraints: string[]): Plan { - return { - ...p, - planning_context: { - ...p.planning_context, - constraints, - }, - }; -} - -export function setInvisibleKnowledge( - p: Plan, - data: { system?: string; invariants?: string[]; tradeoffs?: string[] }, -): Plan { - const ik: InvisibleKnowledge = { - system: data.system ?? p.invisible_knowledge.system, - invariants: data.invariants ?? p.invisible_knowledge.invariants, - tradeoffs: data.tradeoffs ?? p.invisible_knowledge.tradeoffs, - }; - return { ...p, invisible_knowledge: ik }; -} - -// -- Decision -- - -export function addDecision( - p: Plan, - data: { decision: string; reasoning: string }, -): { plan: Plan; id: string } { - const id = nextDecisionId(p); - const decision: Decision = { - id, - version: 1, - decision: data.decision, - reasoning_chain: data.reasoning, - }; - return { - plan: { - ...p, - planning_context: { - ...p.planning_context, - decision_log: [...p.planning_context.decision_log, decision], - }, - }, - id, - }; -} - -export function setDecision( - p: Plan, - id: string, - data: { decision?: string; reasoning?: string }, -): Plan { - const idx = p.planning_context.decision_log.findIndex((d) => d.id === id); - if (idx === -1) throw new Error(`decision ${id} not found`); - - const d = p.planning_context.decision_log[idx]; - const updated: Decision = { - ...d, - version: d.version + 1, - decision: data.decision ?? d.decision, - reasoning_chain: data.reasoning ?? d.reasoning_chain, - }; - - const log = [...p.planning_context.decision_log]; - log[idx] = updated; - - return { - ...p, - planning_context: { ...p.planning_context, decision_log: log }, - }; -} - -// -- RejectedAlternative -- - -export function addRejectedAlternative( - p: Plan, - data: { alternative: string; rejection_reason: string; decision_ref: string }, -): { plan: Plan; id: string } { - const id = nextRejectedAltId(p); - const ra: RejectedAlternative = { - id, - alternative: data.alternative, - rejection_reason: data.rejection_reason, - decision_ref: data.decision_ref, - }; - return { - plan: { - ...p, - planning_context: { - ...p.planning_context, - rejected_alternatives: [ - ...p.planning_context.rejected_alternatives, - ra, - ], - }, - }, - id, - }; -} - -export function setRejectedAlternative( - p: Plan, - id: string, - data: { - alternative?: string; - rejection_reason?: string; - decision_ref?: string; - }, -): Plan { - const idx = p.planning_context.rejected_alternatives.findIndex( - (r) => r.id === id, - ); - if (idx === -1) throw new Error(`rejected_alternative ${id} not found`); - - const r = p.planning_context.rejected_alternatives[idx]; - const updated: RejectedAlternative = { - ...r, - alternative: data.alternative ?? r.alternative, - rejection_reason: data.rejection_reason ?? r.rejection_reason, - decision_ref: data.decision_ref ?? r.decision_ref, - }; - - const list = [...p.planning_context.rejected_alternatives]; - list[idx] = updated; - - return { - ...p, - planning_context: { ...p.planning_context, rejected_alternatives: list }, - }; -} - -// -- Risk -- - -export function addRisk( - p: Plan, - data: { - risk: string; - mitigation: string; - anchor?: string; - decision_ref?: string; - }, -): { plan: Plan; id: string } { - const id = nextRiskId(p); - const risk: Risk = { - id, - risk: data.risk, - mitigation: data.mitigation, - anchor: data.anchor ?? null, - decision_ref: data.decision_ref ?? null, - }; - return { - plan: { - ...p, - planning_context: { - ...p.planning_context, - known_risks: [...p.planning_context.known_risks, risk], - }, - }, - id, - }; -} - -export function setRisk( - p: Plan, - id: string, - data: { - risk?: string; - mitigation?: string; - anchor?: string; - decision_ref?: string; - }, -): Plan { - const idx = p.planning_context.known_risks.findIndex((r) => r.id === id); - if (idx === -1) throw new Error(`risk ${id} not found`); - - const r = p.planning_context.known_risks[idx]; - const updated: Risk = { - ...r, - risk: data.risk ?? r.risk, - mitigation: data.mitigation ?? r.mitigation, - anchor: data.anchor ?? r.anchor, - decision_ref: data.decision_ref ?? r.decision_ref, - }; - - const list = [...p.planning_context.known_risks]; - list[idx] = updated; - - return { - ...p, - planning_context: { ...p.planning_context, known_risks: list }, - }; -} - -// -- Milestone -- - -export function addMilestone( - p: Plan, - data: { - name: string; - files?: string[]; - flags?: string[]; - requirements?: string[]; - acceptance_criteria?: string[]; - tests?: string[]; - }, -): { plan: Plan; id: string } { - const id = nextMilestoneId(p); - const milestone: Milestone = { - id, - version: 1, - number: p.milestones.length + 1, - name: data.name, - files: data.files ?? [], - flags: data.flags ?? [], - requirements: data.requirements ?? [], - acceptance_criteria: data.acceptance_criteria ?? [], - tests: data.tests ?? [], - code_intents: [], - code_changes: [], - documentation: { - module_comment: null, - docstrings: [], - function_blocks: [], - inline_comments: [], - }, - is_documentation_only: false, - delegated_to: null, - }; - return { - plan: { - ...p, - milestones: [...p.milestones, milestone], - }, - id, - }; -} - -function updateMilestone( - p: Plan, - id: string, - fn: (m: Milestone) => Milestone, -): Plan { - const idx = p.milestones.findIndex((m) => m.id === id); - if (idx === -1) throw new Error(`milestone ${id} not found`); - - const updated = [...p.milestones]; - updated[idx] = fn(p.milestones[idx]); - return { ...p, milestones: updated }; -} - -export function setMilestoneName(p: Plan, id: string, name: string): Plan { - return updateMilestone(p, id, (m) => ({ ...m, version: m.version + 1, name })); -} - -export function setMilestoneFiles(p: Plan, id: string, files: string[]): Plan { - return updateMilestone(p, id, (m) => ({ - ...m, - version: m.version + 1, - files, - })); -} - -export function setMilestoneFlags(p: Plan, id: string, flags: string[]): Plan { - return updateMilestone(p, id, (m) => ({ - ...m, - version: m.version + 1, - flags, - })); -} - -export function setMilestoneRequirements( - p: Plan, - id: string, - requirements: string[], -): Plan { - return updateMilestone(p, id, (m) => ({ - ...m, - version: m.version + 1, - requirements, - })); -} - -export function setMilestoneAcceptanceCriteria( - p: Plan, - id: string, - criteria: string[], -): Plan { - return updateMilestone(p, id, (m) => ({ - ...m, - version: m.version + 1, - acceptance_criteria: criteria, - })); -} - -export function setMilestoneTests(p: Plan, id: string, tests: string[]): Plan { - return updateMilestone(p, id, (m) => ({ - ...m, - version: m.version + 1, - tests, - })); -} - -// -- CodeIntent -- - -export function addIntent( - p: Plan, - data: { - milestone: string; - file: string; - function?: string; - behavior: string; - decision_refs?: string[]; - }, -): { plan: Plan; id: string } { - const idx = p.milestones.findIndex((m) => m.id === data.milestone); - if (idx === -1) throw new Error(`milestone ${data.milestone} not found`); - - const m = p.milestones[idx]; - const id = nextIntentId(m); - const intent: CodeIntent = { - id, - version: 1, - file: data.file, - function: data.function ?? null, - behavior: data.behavior, - decision_refs: data.decision_refs ?? [], - }; - - const updated = [...p.milestones]; - updated[idx] = { - ...m, - code_intents: [...m.code_intents, intent], - }; - - return { - plan: { ...p, milestones: updated }, - id, - }; -} - -export function setIntent( - p: Plan, - id: string, - data: { - file?: string; - function?: string; - behavior?: string; - decision_refs?: string[]; - }, -): Plan { - for (let i = 0; i < p.milestones.length; i++) { - const m = p.milestones[i]; - const ciIdx = m.code_intents.findIndex((ci) => ci.id === id); - if (ciIdx !== -1) { - const ci = m.code_intents[ciIdx]; - const updated: CodeIntent = { - ...ci, - version: ci.version + 1, - file: data.file ?? ci.file, - function: data.function ?? ci.function, - behavior: data.behavior ?? ci.behavior, - decision_refs: data.decision_refs ?? ci.decision_refs, - }; - - const intents = [...m.code_intents]; - intents[ciIdx] = updated; - - const milestones = [...p.milestones]; - milestones[i] = { ...m, code_intents: intents }; - - return { ...p, milestones }; - } - } - throw new Error(`intent ${id} not found`); -} - -// -- CodeChange -- - -export function addChange( - p: Plan, - data: { - milestone: string; - file: string; - intent_ref?: string; - diff?: string; - doc_diff?: string; - comments?: string; - }, -): { plan: Plan; id: string } { - const idx = p.milestones.findIndex((m) => m.id === data.milestone); - if (idx === -1) throw new Error(`milestone ${data.milestone} not found`); - - const m = p.milestones[idx]; - const id = nextChangeId(m); - const change: CodeChange = { - id, - version: 1, - intent_ref: data.intent_ref ?? null, - file: data.file, - diff: data.diff ?? "", - doc_diff: data.doc_diff ?? "", - comments: data.comments ?? "", - }; - - const updated = [...p.milestones]; - updated[idx] = { - ...m, - code_changes: [...m.code_changes, change], - }; - - return { - plan: { ...p, milestones: updated }, - id, - }; -} - -function updateChange( - p: Plan, - id: string, - fn: (c: CodeChange) => CodeChange, -): Plan { - for (let i = 0; i < p.milestones.length; i++) { - const m = p.milestones[i]; - const ccIdx = m.code_changes.findIndex((cc) => cc.id === id); - if (ccIdx !== -1) { - const changes = [...m.code_changes]; - changes[ccIdx] = fn(m.code_changes[ccIdx]); - - const milestones = [...p.milestones]; - milestones[i] = { ...m, code_changes: changes }; - - return { ...p, milestones }; - } - } - throw new Error(`code_change ${id} not found`); -} - -export function setChangeDiff(p: Plan, id: string, diff: string): Plan { - return updateChange(p, id, (c) => ({ ...c, version: c.version + 1, diff })); -} - -export function setChangeDocDiff(p: Plan, id: string, doc_diff: string): Plan { - return updateChange(p, id, (c) => ({ - ...c, - version: c.version + 1, - doc_diff, - })); -} - -export function setChangeComments(p: Plan, id: string, comments: string): Plan { - return updateChange(p, id, (c) => ({ - ...c, - version: c.version + 1, - comments, - })); -} - -export function setChangeFile(p: Plan, id: string, file: string): Plan { - return updateChange(p, id, (c) => ({ ...c, version: c.version + 1, file })); -} - -export function setChangeIntentRef( - p: Plan, - id: string, - intent_ref: string, -): Plan { - return updateChange(p, id, (c) => ({ - ...c, - version: c.version + 1, - intent_ref, - })); -} - -// -- Wave -- - -export function addWave( - p: Plan, - data: { milestones: string[] }, -): { plan: Plan; id: string } { - const id = nextWaveId(p); - const wave: Wave = { - id, - milestones: data.milestones, - }; - return { - plan: { - ...p, - waves: [...p.waves, wave], - }, - id, - }; -} - -export function setWaveMilestones( - p: Plan, - id: string, - milestones: string[], -): Plan { - const idx = p.waves.findIndex((w) => w.id === id); - if (idx === -1) throw new Error(`wave ${id} not found`); - - const updated = [...p.waves]; - updated[idx] = { ...p.waves[idx], milestones }; - - return { ...p, waves: updated }; -} - -// -- Diagram -- - -export function addDiagram( - p: Plan, - data: { - type: "architecture" | "state" | "sequence" | "dataflow"; - scope: string; - title: string; - }, -): { plan: Plan; id: string } { - const id = nextDiagramId(p); - const diagram: DiagramGraph = { - id, - type: data.type, - scope: data.scope, - title: data.title, - nodes: [], - edges: [], - ascii_render: null, - }; - return { - plan: { - ...p, - diagram_graphs: [...p.diagram_graphs, diagram], - }, - id, - }; -} - -export function setDiagram( - p: Plan, - id: string, - data: { title?: string; scope?: string; ascii_render?: string }, -): Plan { - const idx = p.diagram_graphs.findIndex((d) => d.id === id); - if (idx === -1) throw new Error(`diagram ${id} not found`); - - const d = p.diagram_graphs[idx]; - const updated: DiagramGraph = { - ...d, - title: data.title ?? d.title, - scope: data.scope ?? d.scope, - ascii_render: data.ascii_render ?? d.ascii_render, - }; - - const diagrams = [...p.diagram_graphs]; - diagrams[idx] = updated; - - return { ...p, diagram_graphs: diagrams }; -} - -export function addDiagramNode( - p: Plan, - diagramId: string, - data: { id: string; label: string; type?: string }, -): Plan { - const idx = p.diagram_graphs.findIndex((d) => d.id === diagramId); - if (idx === -1) throw new Error(`diagram ${diagramId} not found`); - - const d = p.diagram_graphs[idx]; - const node: DiagramNode = { - id: data.id, - label: data.label, - type: data.type ?? null, - }; - - const diagrams = [...p.diagram_graphs]; - diagrams[idx] = { - ...d, - nodes: [...d.nodes, node], - }; - - return { ...p, diagram_graphs: diagrams }; -} - -export function addDiagramEdge( - p: Plan, - diagramId: string, - data: { source: string; target: string; label: string; protocol?: string }, -): Plan { - const idx = p.diagram_graphs.findIndex((d) => d.id === diagramId); - if (idx === -1) throw new Error(`diagram ${diagramId} not found`); - - const d = p.diagram_graphs[idx]; - const edge: DiagramEdge = { - source: data.source, - target: data.target, - label: data.label, - protocol: data.protocol ?? null, - }; - - const diagrams = [...p.diagram_graphs]; - diagrams[idx] = { - ...d, - edges: [...d.edges, edge], - }; - - return { ...p, diagram_graphs: diagrams }; -} - -// -- ReadmeEntry -- - -export function setReadmeEntry(p: Plan, path: string, content: string): Plan { - const idx = p.readme_entries.findIndex((r) => r.path === path); - const entry: ReadmeEntry = { path, content }; - - if (idx === -1) { - return { - ...p, - readme_entries: [...p.readme_entries, entry], - }; - } - - const entries = [...p.readme_entries]; - entries[idx] = entry; - return { ...p, readme_entries: entries }; -} diff --git a/src/planner/plan/mutate/code.ts b/src/planner/plan/mutate/code.ts new file mode 100644 index 0000000..7eb74a3 --- /dev/null +++ b/src/planner/plan/mutate/code.ts @@ -0,0 +1,161 @@ +// Code intent and code change mutations. +// Pure functions -- input plan in, new plan out. No side effects. + +import type { Plan, CodeIntent, CodeChange } from "../types.js"; +import { nextIntentId, nextChangeId } from "../types.js"; + +// -- CodeIntent -- + +export function addIntent( + p: Plan, + data: { + milestone: string; + file: string; + function?: string; + behavior: string; + decision_refs?: string[]; + }, +): { plan: Plan; id: string } { + const idx = p.milestones.findIndex((m) => m.id === data.milestone); + if (idx === -1) throw new Error(`milestone ${data.milestone} not found`); + + const m = p.milestones[idx]; + const id = nextIntentId(m); + const intent: CodeIntent = { + id, + file: data.file, + function: data.function ?? null, + behavior: data.behavior, + decision_refs: data.decision_refs ?? [], + }; + + const updated = [...p.milestones]; + updated[idx] = { + ...m, + code_intents: [...m.code_intents, intent], + }; + + return { + plan: { ...p, milestones: updated }, + id, + }; +} + +export function setIntent( + p: Plan, + id: string, + data: { + file?: string; + function?: string; + behavior?: string; + decision_refs?: string[]; + }, +): Plan { + for (let i = 0; i < p.milestones.length; i++) { + const m = p.milestones[i]; + const ciIdx = m.code_intents.findIndex((ci) => ci.id === id); + if (ciIdx !== -1) { + const ci = m.code_intents[ciIdx]; + const updated: CodeIntent = { + ...ci, + file: data.file ?? ci.file, + function: data.function ?? ci.function, + behavior: data.behavior ?? ci.behavior, + decision_refs: data.decision_refs ?? ci.decision_refs, + }; + + const intents = [...m.code_intents]; + intents[ciIdx] = updated; + + const milestones = [...p.milestones]; + milestones[i] = { ...m, code_intents: intents }; + + return { ...p, milestones }; + } + } + throw new Error(`intent ${id} not found`); +} + +// -- CodeChange -- + +export function addChange( + p: Plan, + data: { + milestone: string; + file: string; + intent_ref?: string; + diff?: string; + doc_diff?: string; + comments?: string; + }, +): { plan: Plan; id: string } { + const idx = p.milestones.findIndex((m) => m.id === data.milestone); + if (idx === -1) throw new Error(`milestone ${data.milestone} not found`); + + const m = p.milestones[idx]; + const id = nextChangeId(m); + const change: CodeChange = { + id, + intent_ref: data.intent_ref ?? null, + file: data.file, + diff: data.diff ?? "", + doc_diff: data.doc_diff ?? "", + comments: data.comments ?? "", + }; + + const updated = [...p.milestones]; + updated[idx] = { + ...m, + code_changes: [...m.code_changes, change], + }; + + return { + plan: { ...p, milestones: updated }, + id, + }; +} + +function updateChange( + p: Plan, + id: string, + fn: (c: CodeChange) => CodeChange, +): Plan { + for (let i = 0; i < p.milestones.length; i++) { + const m = p.milestones[i]; + const ccIdx = m.code_changes.findIndex((cc) => cc.id === id); + if (ccIdx !== -1) { + const changes = [...m.code_changes]; + changes[ccIdx] = fn(m.code_changes[ccIdx]); + + const milestones = [...p.milestones]; + milestones[i] = { ...m, code_changes: changes }; + + return { ...p, milestones }; + } + } + throw new Error(`code_change ${id} not found`); +} + +export function setChangeDiff(p: Plan, id: string, diff: string): Plan { + return updateChange(p, id, (c) => ({ ...c, diff })); +} + +export function setChangeDocDiff(p: Plan, id: string, doc_diff: string): Plan { + return updateChange(p, id, (c) => ({ ...c, doc_diff })); +} + +export function setChangeComments(p: Plan, id: string, comments: string): Plan { + return updateChange(p, id, (c) => ({ ...c, comments })); +} + +export function setChangeFile(p: Plan, id: string, file: string): Plan { + return updateChange(p, id, (c) => ({ ...c, file })); +} + +export function setChangeIntentRef( + p: Plan, + id: string, + intent_ref: string, +): Plan { + return updateChange(p, id, (c) => ({ ...c, intent_ref })); +} diff --git a/src/planner/plan/mutate/decisions.ts b/src/planner/plan/mutate/decisions.ts new file mode 100644 index 0000000..e5e7d1f --- /dev/null +++ b/src/planner/plan/mutate/decisions.ts @@ -0,0 +1,178 @@ +// Decision log mutations: decisions, rejected alternatives, risks. +// Pure functions -- input plan in, new plan out. No side effects. + +import type { Plan, Decision, RejectedAlternative, Risk } from "../types.js"; +import { + nextDecisionId, + nextRejectedAltId, + nextRiskId, +} from "../types.js"; + +// -- Decision -- + +export function addDecision( + p: Plan, + data: { decision: string; reasoning: string }, +): { plan: Plan; id: string } { + const id = nextDecisionId(p); + const decision: Decision = { + id, + decision: data.decision, + reasoning_chain: data.reasoning, + }; + return { + plan: { + ...p, + planning_context: { + ...p.planning_context, + decision_log: [...p.planning_context.decision_log, decision], + }, + }, + id, + }; +} + +export function setDecision( + p: Plan, + id: string, + data: { decision?: string; reasoning?: string }, +): Plan { + const idx = p.planning_context.decision_log.findIndex((d) => d.id === id); + if (idx === -1) throw new Error(`decision ${id} not found`); + + const d = p.planning_context.decision_log[idx]; + const updated: Decision = { + ...d, + decision: data.decision ?? d.decision, + reasoning_chain: data.reasoning ?? d.reasoning_chain, + }; + + const log = [...p.planning_context.decision_log]; + log[idx] = updated; + + return { + ...p, + planning_context: { ...p.planning_context, decision_log: log }, + }; +} + +// -- RejectedAlternative -- + +export function addRejectedAlternative( + p: Plan, + data: { alternative: string; rejection_reason: string; decision_ref: string }, +): { plan: Plan; id: string } { + const id = nextRejectedAltId(p); + const ra: RejectedAlternative = { + id, + alternative: data.alternative, + rejection_reason: data.rejection_reason, + decision_ref: data.decision_ref, + }; + return { + plan: { + ...p, + planning_context: { + ...p.planning_context, + rejected_alternatives: [ + ...p.planning_context.rejected_alternatives, + ra, + ], + }, + }, + id, + }; +} + +export function setRejectedAlternative( + p: Plan, + id: string, + data: { + alternative?: string; + rejection_reason?: string; + decision_ref?: string; + }, +): Plan { + const idx = p.planning_context.rejected_alternatives.findIndex( + (r) => r.id === id, + ); + if (idx === -1) throw new Error(`rejected_alternative ${id} not found`); + + const r = p.planning_context.rejected_alternatives[idx]; + const updated: RejectedAlternative = { + ...r, + alternative: data.alternative ?? r.alternative, + rejection_reason: data.rejection_reason ?? r.rejection_reason, + decision_ref: data.decision_ref ?? r.decision_ref, + }; + + const list = [...p.planning_context.rejected_alternatives]; + list[idx] = updated; + + return { + ...p, + planning_context: { ...p.planning_context, rejected_alternatives: list }, + }; +} + +// -- Risk -- + +export function addRisk( + p: Plan, + data: { + risk: string; + mitigation: string; + anchor?: string; + decision_ref?: string; + }, +): { plan: Plan; id: string } { + const id = nextRiskId(p); + const risk: Risk = { + id, + risk: data.risk, + mitigation: data.mitigation, + anchor: data.anchor ?? null, + decision_ref: data.decision_ref ?? null, + }; + return { + plan: { + ...p, + planning_context: { + ...p.planning_context, + known_risks: [...p.planning_context.known_risks, risk], + }, + }, + id, + }; +} + +export function setRisk( + p: Plan, + id: string, + data: { + risk?: string; + mitigation?: string; + anchor?: string; + decision_ref?: string; + }, +): Plan { + const idx = p.planning_context.known_risks.findIndex((r) => r.id === id); + if (idx === -1) throw new Error(`risk ${id} not found`); + + const r = p.planning_context.known_risks[idx]; + const updated: Risk = { + ...r, + risk: data.risk ?? r.risk, + mitigation: data.mitigation ?? r.mitigation, + anchor: data.anchor ?? r.anchor, + decision_ref: data.decision_ref ?? r.decision_ref, + }; + + const list = [...p.planning_context.known_risks]; + list[idx] = updated; + + return { + ...p, + planning_context: { ...p.planning_context, known_risks: list }, + }; +} diff --git a/src/planner/plan/mutate/index.ts b/src/planner/plan/mutate/index.ts new file mode 100644 index 0000000..0c96dcb --- /dev/null +++ b/src/planner/plan/mutate/index.ts @@ -0,0 +1,48 @@ +// Re-exports all public mutation functions grouped by domain. +// Consumers import from this single entry point. + +export { + setOverview, + setConstraints, + setInvisibleKnowledge, +} from "./top-level.js"; + +export { + addDecision, + setDecision, + addRejectedAlternative, + setRejectedAlternative, + addRisk, + setRisk, +} from "./decisions.js"; + +export { + addMilestone, + setMilestoneName, + setMilestoneFiles, + setMilestoneFlags, + setMilestoneRequirements, + setMilestoneAcceptanceCriteria, + setMilestoneTests, +} from "./milestones.js"; + +export { + addIntent, + setIntent, + addChange, + setChangeDiff, + setChangeDocDiff, + setChangeComments, + setChangeFile, + setChangeIntentRef, +} from "./code.js"; + +export { + addWave, + setWaveMilestones, + addDiagram, + setDiagram, + addDiagramNode, + addDiagramEdge, + setReadmeEntry, +} from "./structure.js"; diff --git a/src/planner/plan/mutate/milestones.ts b/src/planner/plan/mutate/milestones.ts new file mode 100644 index 0000000..fbb4e86 --- /dev/null +++ b/src/planner/plan/mutate/milestones.ts @@ -0,0 +1,91 @@ +// Milestone mutations: add, and per-field setters. +// Pure functions -- input plan in, new plan out. No side effects. + +import type { Plan, Milestone } from "../types.js"; +import { nextMilestoneId } from "../types.js"; + +export function addMilestone( + p: Plan, + data: { + name: string; + files?: string[]; + flags?: string[]; + requirements?: string[]; + acceptance_criteria?: string[]; + tests?: string[]; + }, +): { plan: Plan; id: string } { + const id = nextMilestoneId(p); + const milestone: Milestone = { + id, + number: p.milestones.length + 1, + name: data.name, + files: data.files ?? [], + flags: data.flags ?? [], + requirements: data.requirements ?? [], + acceptance_criteria: data.acceptance_criteria ?? [], + tests: data.tests ?? [], + code_intents: [], + code_changes: [], + documentation: { + module_comment: null, + docstrings: [], + function_blocks: [], + inline_comments: [], + }, + is_documentation_only: false, + delegated_to: null, + }; + return { + plan: { + ...p, + milestones: [...p.milestones, milestone], + }, + id, + }; +} + +function updateMilestone( + p: Plan, + id: string, + fn: (m: Milestone) => Milestone, +): Plan { + const idx = p.milestones.findIndex((m) => m.id === id); + if (idx === -1) throw new Error(`milestone ${id} not found`); + + const updated = [...p.milestones]; + updated[idx] = fn(p.milestones[idx]); + return { ...p, milestones: updated }; +} + +export function setMilestoneName(p: Plan, id: string, name: string): Plan { + return updateMilestone(p, id, (m) => ({ ...m, name })); +} + +export function setMilestoneFiles(p: Plan, id: string, files: string[]): Plan { + return updateMilestone(p, id, (m) => ({ ...m, files })); +} + +export function setMilestoneFlags(p: Plan, id: string, flags: string[]): Plan { + return updateMilestone(p, id, (m) => ({ ...m, flags })); +} + +export function setMilestoneRequirements( + p: Plan, + id: string, + requirements: string[], +): Plan { + return updateMilestone(p, id, (m) => ({ ...m, requirements })); +} + +export function setMilestoneAcceptanceCriteria( + p: Plan, + id: string, + criteria: string[], +): Plan { + return updateMilestone(p, id, (m) => ({ ...m, acceptance_criteria: criteria })); +} + +export function setMilestoneTests(p: Plan, id: string, tests: string[]): Plan { + return updateMilestone(p, id, (m) => ({ ...m, tests })); +} diff --git a/src/planner/plan/mutate/structure.ts b/src/planner/plan/mutate/structure.ts new file mode 100644 index 0000000..f5679b1 --- /dev/null +++ b/src/planner/plan/mutate/structure.ts @@ -0,0 +1,164 @@ +// Structural plan mutations: waves, diagrams, readme entries. +// Pure functions -- input plan in, new plan out. No side effects. + +import type { + Plan, + Wave, + DiagramGraph, + DiagramNode, + DiagramEdge, + ReadmeEntry, +} from "../types.js"; +import { nextWaveId, nextDiagramId } from "../types.js"; + +// -- Wave -- + +export function addWave( + p: Plan, + data: { milestones: string[] }, +): { plan: Plan; id: string } { + const id = nextWaveId(p); + const wave: Wave = { + id, + milestones: data.milestones, + }; + return { + plan: { + ...p, + waves: [...p.waves, wave], + }, + id, + }; +} + +export function setWaveMilestones( + p: Plan, + id: string, + milestones: string[], +): Plan { + const idx = p.waves.findIndex((w) => w.id === id); + if (idx === -1) throw new Error(`wave ${id} not found`); + + const updated = [...p.waves]; + updated[idx] = { ...p.waves[idx], milestones }; + + return { ...p, waves: updated }; +} + +// -- Diagram -- + +export function addDiagram( + p: Plan, + data: { + type: "architecture" | "state" | "sequence" | "dataflow"; + scope: string; + title: string; + }, +): { plan: Plan; id: string } { + const id = nextDiagramId(p); + const diagram: DiagramGraph = { + id, + type: data.type, + scope: data.scope, + title: data.title, + nodes: [], + edges: [], + ascii_render: null, + }; + return { + plan: { + ...p, + diagram_graphs: [...p.diagram_graphs, diagram], + }, + id, + }; +} + +export function setDiagram( + p: Plan, + id: string, + data: { title?: string; scope?: string; ascii_render?: string }, +): Plan { + const idx = p.diagram_graphs.findIndex((d) => d.id === id); + if (idx === -1) throw new Error(`diagram ${id} not found`); + + const d = p.diagram_graphs[idx]; + const updated: DiagramGraph = { + ...d, + title: data.title ?? d.title, + scope: data.scope ?? d.scope, + ascii_render: data.ascii_render ?? d.ascii_render, + }; + + const diagrams = [...p.diagram_graphs]; + diagrams[idx] = updated; + + return { ...p, diagram_graphs: diagrams }; +} + +export function addDiagramNode( + p: Plan, + diagramId: string, + data: { id: string; label: string; type?: string }, +): Plan { + const idx = p.diagram_graphs.findIndex((d) => d.id === diagramId); + if (idx === -1) throw new Error(`diagram ${diagramId} not found`); + + const d = p.diagram_graphs[idx]; + const node: DiagramNode = { + id: data.id, + label: data.label, + type: data.type ?? null, + }; + + const diagrams = [...p.diagram_graphs]; + diagrams[idx] = { + ...d, + nodes: [...d.nodes, node], + }; + + return { ...p, diagram_graphs: diagrams }; +} + +export function addDiagramEdge( + p: Plan, + diagramId: string, + data: { source: string; target: string; label: string; protocol?: string }, +): Plan { + const idx = p.diagram_graphs.findIndex((d) => d.id === diagramId); + if (idx === -1) throw new Error(`diagram ${diagramId} not found`); + + const d = p.diagram_graphs[idx]; + const edge: DiagramEdge = { + source: data.source, + target: data.target, + label: data.label, + protocol: data.protocol ?? null, + }; + + const diagrams = [...p.diagram_graphs]; + diagrams[idx] = { + ...d, + edges: [...d.edges, edge], + }; + + return { ...p, diagram_graphs: diagrams }; +} + +// -- ReadmeEntry -- + +export function setReadmeEntry(p: Plan, path: string, content: string): Plan { + const idx = p.readme_entries.findIndex((r) => r.path === path); + const entry: ReadmeEntry = { path, content }; + + if (idx === -1) { + return { + ...p, + readme_entries: [...p.readme_entries, entry], + }; + } + + const entries = [...p.readme_entries]; + entries[idx] = entry; + return { ...p, readme_entries: entries }; +} diff --git a/src/planner/plan/mutate/top-level.ts b/src/planner/plan/mutate/top-level.ts new file mode 100644 index 0000000..2392525 --- /dev/null +++ b/src/planner/plan/mutate/top-level.ts @@ -0,0 +1,37 @@ +// Top-level plan field mutations: overview, constraints, invisible knowledge. +// Pure functions -- input plan in, new plan out. No side effects. + +import type { Plan, Overview, InvisibleKnowledge } from "../types.js"; + +export function setOverview( + p: Plan, + data: { problem?: string; approach?: string }, +): Plan { + const overview: Overview = { + problem: data.problem ?? p.overview.problem, + approach: data.approach ?? p.overview.approach, + }; + return { ...p, overview }; +} + +export function setConstraints(p: Plan, constraints: string[]): Plan { + return { + ...p, + planning_context: { + ...p.planning_context, + constraints, + }, + }; +} + +export function setInvisibleKnowledge( + p: Plan, + data: { system?: string; invariants?: string[]; tradeoffs?: string[] }, +): Plan { + const ik: InvisibleKnowledge = { + system: data.system ?? p.invisible_knowledge.system, + invariants: data.invariants ?? p.invisible_knowledge.invariants, + tradeoffs: data.tradeoffs ?? p.invisible_knowledge.tradeoffs, + }; + return { ...p, invisible_knowledge: ik }; +} diff --git a/src/planner/plan/types.ts b/src/planner/plan/types.ts index 6a4d943..518b54e 100644 --- a/src/planner/plan/types.ts +++ b/src/planner/plan/types.ts @@ -1,6 +1,5 @@ export interface Decision { id: string; - version: number; decision: string; reasoning_chain: string; } @@ -40,7 +39,6 @@ export interface Overview { export interface CodeIntent { id: string; - version: number; file: string; function?: string | null; behavior: string; @@ -49,7 +47,6 @@ export interface CodeIntent { export interface CodeChange { id: string; - version: number; intent_ref: string | null; file: string; diff: string; @@ -117,7 +114,6 @@ export interface DiagramGraph { export interface Milestone { id: string; - version: number; number: number; name: string; files: string[]; diff --git a/src/planner/qr/mutate.ts b/src/planner/qr/mutate.ts index b831074..e0644ff 100644 --- a/src/planner/qr/mutate.ts +++ b/src/planner/qr/mutate.ts @@ -18,7 +18,6 @@ export function addQRItem( scope: data.scope, check: data.check, status: "TODO", - version: 1, finding: null, parent_id: null, group_id: null, @@ -68,7 +67,6 @@ export function setQRItem( const updated: QRItem = { ...item, - version: item.version + 1, status, finding, check: data.check ?? item.check, @@ -81,7 +79,6 @@ export function setQRItem( return { ...qr, items }; } -// Does not increment version (grouping is metadata). export function assignGroup(qr: QRFile, ids: string[], groupId: string): QRFile { const idSet = new Set(ids); const items = qr.items.map((item) => diff --git a/src/planner/qr/types.ts b/src/planner/qr/types.ts index 3345631..89ab627 100644 --- a/src/planner/qr/types.ts +++ b/src/planner/qr/types.ts @@ -6,7 +6,6 @@ export interface QRItem { scope: string; check: string; status: QRItemStatus; - version: number; finding: string | null; parent_id: string | null; group_id: string | null; diff --git a/src/planner/session.ts b/src/planner/session.ts index a14050e..ef08dfa 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -4,13 +4,13 @@ import * as path from "node:path"; import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent"; -import { ContextCapturePhase } from "./phases/context-capture.js"; +import { ContextCapturePhase } from "./phases/context-capture/phase.js"; import { createInitialState, initializePlanState, type WorkflowState } from "./state.js"; import { createPlanInfo } from "../utils/plan.js"; import { spawnArchitect } from "./subagent.js"; import { createLogger } from "../utils/logger.js"; import { createSubagentDir, readSubagentState } from "../utils/progress.js"; -import type { WorkflowDispatch, PlanRef } from "./tools/dispatch.js"; +import type { WorkflowDispatch, PlanRef } from "./lib/dispatch.js"; interface Session { plan(args: string, ctx: ExtensionCommandContext): Promise; diff --git a/src/planner/tools/entity-code.ts b/src/planner/tools/entity-code.ts new file mode 100644 index 0000000..ca57d75 --- /dev/null +++ b/src/planner/tools/entity-code.ts @@ -0,0 +1,171 @@ +// Plan entity tools for code-phase entities: code intents and code changes. +// Uses planTool helper from entity-design (shared load-mutate-save-lock wrapper). + +import { Type } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import type { PlanRef } from "../lib/dispatch.js"; +import { planTool } from "./entity-design.js"; +import { + addIntent, + setIntent, + addChange, + setChangeDiff, + setChangeDocDiff, + setChangeComments, + setChangeFile, + setChangeIntentRef, +} from "../plan/mutate/index.js"; + +export function registerPlanCodeEntityTools( + pi: ExtensionAPI, + planRef: PlanRef, +): void { + // -- CodeIntent -- + planTool(pi, planRef, { + name: "koan_add_intent", + label: "Add code intent", + description: "Add code intent to milestone.", + parameters: Type.Object({ + milestone: Type.String(), + file: Type.String(), + function: Type.Optional(Type.String()), + behavior: Type.String(), + decision_refs: Type.Optional(Type.Array(Type.String())), + }), + execute: (p, params) => { + const r = addIntent(p, params); + return { + plan: r.plan, + message: `Added intent ${r.id} to milestone ${params.milestone}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_intent", + label: "Update code intent", + description: "Update existing code intent by ID.", + parameters: Type.Object({ + id: Type.String(), + file: Type.Optional(Type.String()), + function: Type.Optional(Type.String()), + behavior: Type.Optional(Type.String()), + decision_refs: Type.Optional(Type.Array(Type.String())), + }), + execute: (p, params) => { + const updated = setIntent(p, params.id, params); + return { + plan: updated, + message: `Updated intent ${params.id}`, + }; + }, + }); + + // -- CodeChange -- + planTool(pi, planRef, { + name: "koan_add_change", + label: "Add code change", + description: "Add code change to milestone.", + parameters: Type.Object({ + milestone: Type.String(), + file: Type.String(), + intent_ref: Type.Optional(Type.String()), + diff: Type.Optional(Type.String()), + doc_diff: Type.Optional(Type.String()), + comments: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const r = addChange(p, params); + return { + plan: r.plan, + message: `Added change ${r.id} to milestone ${params.milestone}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_change_diff", + label: "Set code change diff", + description: "Update change diff.", + parameters: Type.Object({ + id: Type.String(), + diff: Type.String(), + }), + execute: (p, params) => { + const updated = setChangeDiff(p, params.id, params.diff); + return { + plan: updated, + message: `Set diff for change ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_change_doc_diff", + label: "Set code change doc_diff", + description: "Update change doc_diff.", + parameters: Type.Object({ + id: Type.String(), + doc_diff: Type.String(), + }), + execute: (p, params) => { + const updated = setChangeDocDiff(p, params.id, params.doc_diff); + return { + plan: updated, + message: `Set doc_diff for change ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_change_comments", + label: "Set code change comments", + description: "Update change comments.", + parameters: Type.Object({ + id: Type.String(), + comments: Type.String(), + }), + execute: (p, params) => { + const updated = setChangeComments(p, params.id, params.comments); + return { + plan: updated, + message: `Set comments for change ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_change_file", + label: "Set code change file", + description: "Update change file path.", + parameters: Type.Object({ + id: Type.String(), + file: Type.String(), + }), + execute: (p, params) => { + const updated = setChangeFile(p, params.id, params.file); + return { + plan: updated, + message: `Set file for change ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_change_intent_ref", + label: "Set code change intent_ref", + description: "Update change intent reference.", + parameters: Type.Object({ + id: Type.String(), + intent_ref: Type.String(), + }), + execute: (p, params) => { + const updated = setChangeIntentRef(p, params.id, params.intent_ref); + return { + plan: updated, + message: `Set intent_ref for change ${params.id}`, + }; + }, + }); +} diff --git a/src/planner/tools/entity-design.ts b/src/planner/tools/entity-design.ts new file mode 100644 index 0000000..06552ee --- /dev/null +++ b/src/planner/tools/entity-design.ts @@ -0,0 +1,306 @@ +// Plan entity tools for design-phase entities: decisions, risks, milestones. +// Exports planTool helper for shared use by entity-code and entity-structure. +// load-mutate-save wrapped in file lock; disk is single source of truth. + +import { Type, type Static, type TSchema } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; +import * as path from "node:path"; + +import type { PlanRef } from "../lib/dispatch.js"; +import { loadPlan, savePlan } from "../plan/serialize.js"; +import type { Plan } from "../plan/types.js"; +import { withFileLock } from "../../utils/lock.js"; +import { + addDecision, + setDecision, + addRejectedAlternative, + setRejectedAlternative, + addRisk, + setRisk, + addMilestone, + setMilestoneName, + setMilestoneFiles, + setMilestoneFlags, + setMilestoneRequirements, + setMilestoneAcceptanceCriteria, + setMilestoneTests, +} from "../plan/mutate/index.js"; + +export function planTool( + pi: ExtensionAPI, + planRef: PlanRef, + opts: { + name: string; + label: string; + description: string; + parameters: TParams; + execute: (plan: Plan, params: Static) => { plan: Plan; message: string }; + }, +): void { + pi.registerTool({ + name: opts.name, + label: opts.label, + description: opts.description, + parameters: opts.parameters, + async execute(_toolCallId, params) { + if (!planRef.dir) throw new Error("No plan directory is active."); + const planPath = path.join(planRef.dir, "plan.json"); + return withFileLock(planPath, async () => { + const plan = await loadPlan(planRef.dir!); + const result = opts.execute(plan, params); + await savePlan(result.plan, planRef.dir!); + return { + content: [{ type: "text" as const, text: result.message }], + details: undefined, + }; + }); + }, + }); +} + +export function registerPlanDesignEntityTools( + pi: ExtensionAPI, + planRef: PlanRef, +): void { + // -- Decision -- + planTool(pi, planRef, { + name: "koan_add_decision", + label: "Add decision", + description: "Add decision to decision log.", + parameters: Type.Object({ + decision: Type.String(), + reasoning: Type.String(), + }), + execute: (p, params) => { + const r = addDecision(p, params); + return { + plan: r.plan, + message: `Added decision ${r.id}: "${params.decision}"`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_decision", + label: "Update decision", + description: "Update existing decision by ID.", + parameters: Type.Object({ + id: Type.String(), + decision: Type.Optional(Type.String()), + reasoning: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = setDecision(p, params.id, params); + return { + plan: updated, + message: `Updated decision ${params.id}`, + }; + }, + }); + + // -- RejectedAlternative -- + planTool(pi, planRef, { + name: "koan_add_rejected_alternative", + label: "Add rejected alternative", + description: "Add rejected alternative to decision log.", + parameters: Type.Object({ + alternative: Type.String(), + rejection_reason: Type.String(), + decision_ref: Type.String(), + }), + execute: (p, params) => { + const r = addRejectedAlternative(p, params); + return { + plan: r.plan, + message: `Added rejected alternative ${r.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_rejected_alternative", + label: "Update rejected alternative", + description: "Update existing rejected alternative by ID.", + parameters: Type.Object({ + id: Type.String(), + alternative: Type.Optional(Type.String()), + rejection_reason: Type.Optional(Type.String()), + decision_ref: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = setRejectedAlternative(p, params.id, params); + return { + plan: updated, + message: `Updated rejected alternative ${params.id}`, + }; + }, + }); + + // -- Risk -- + planTool(pi, planRef, { + name: "koan_add_risk", + label: "Add risk", + description: "Add risk to known risks.", + parameters: Type.Object({ + risk: Type.String(), + mitigation: Type.String(), + anchor: Type.Optional(Type.String()), + decision_ref: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const r = addRisk(p, params); + return { + plan: r.plan, + message: `Added risk ${r.id}: "${params.risk}"`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_risk", + label: "Update risk", + description: "Update existing risk by ID.", + parameters: Type.Object({ + id: Type.String(), + risk: Type.Optional(Type.String()), + mitigation: Type.Optional(Type.String()), + anchor: Type.Optional(Type.String()), + decision_ref: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = setRisk(p, params.id, params); + return { + plan: updated, + message: `Updated risk ${params.id}`, + }; + }, + }); + + // -- Milestone -- + planTool(pi, planRef, { + name: "koan_add_milestone", + label: "Add milestone", + description: "Create new milestone.", + parameters: Type.Object({ + name: Type.String(), + files: Type.Optional(Type.Array(Type.String())), + flags: Type.Optional(Type.Array(Type.String())), + requirements: Type.Optional(Type.Array(Type.String())), + acceptance_criteria: Type.Optional(Type.Array(Type.String())), + tests: Type.Optional(Type.Array(Type.String())), + }), + execute: (p, params) => { + const r = addMilestone(p, params); + return { + plan: r.plan, + message: `Added milestone ${r.id}: "${params.name}"`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_name", + label: "Set milestone name", + description: "Update milestone name.", + parameters: Type.Object({ + id: Type.String(), + name: Type.String(), + }), + execute: (p, params) => { + const updated = setMilestoneName(p, params.id, params.name); + return { + plan: updated, + message: `Set name for milestone ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_files", + label: "Set milestone files", + description: "Update milestone files list.", + parameters: Type.Object({ + id: Type.String(), + files: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setMilestoneFiles(p, params.id, params.files); + return { + plan: updated, + message: `Set files for milestone ${params.id} (${params.files.length} files)`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_flags", + label: "Set milestone flags", + description: "Update milestone flags list.", + parameters: Type.Object({ + id: Type.String(), + flags: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setMilestoneFlags(p, params.id, params.flags); + return { + plan: updated, + message: `Set flags for milestone ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_requirements", + label: "Set milestone requirements", + description: "Update milestone requirements list.", + parameters: Type.Object({ + id: Type.String(), + requirements: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setMilestoneRequirements(p, params.id, params.requirements); + return { + plan: updated, + message: `Set requirements for milestone ${params.id} (${params.requirements.length} items)`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_acceptance_criteria", + label: "Set milestone acceptance criteria", + description: "Update milestone acceptance criteria list.", + parameters: Type.Object({ + id: Type.String(), + acceptance_criteria: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setMilestoneAcceptanceCriteria( + p, + params.id, + params.acceptance_criteria, + ); + return { + plan: updated, + message: `Set acceptance criteria for milestone ${params.id} (${params.acceptance_criteria.length} items)`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_milestone_tests", + label: "Set milestone tests", + description: "Update milestone tests list.", + parameters: Type.Object({ + id: Type.String(), + tests: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setMilestoneTests(p, params.id, params.tests); + return { + plan: updated, + message: `Set tests for milestone ${params.id} (${params.tests.length} tests)`, + }; + }, + }); +} diff --git a/src/planner/tools/entity-structure.ts b/src/planner/tools/entity-structure.ts new file mode 100644 index 0000000..cc710a8 --- /dev/null +++ b/src/planner/tools/entity-structure.ts @@ -0,0 +1,156 @@ +// Plan entity tools for structural entities: waves, diagrams, readme entries. +// Uses planTool helper from entity-design (shared load-mutate-save-lock wrapper). + +import { Type } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import type { PlanRef } from "../lib/dispatch.js"; +import { planTool } from "./entity-design.js"; +import { + addWave, + setWaveMilestones, + addDiagram, + setDiagram, + addDiagramNode, + addDiagramEdge, + setReadmeEntry, +} from "../plan/mutate/index.js"; + +export function registerPlanStructureEntityTools( + pi: ExtensionAPI, + planRef: PlanRef, +): void { + // -- Wave -- + planTool(pi, planRef, { + name: "koan_add_wave", + label: "Add wave", + description: "Create wave with milestone list.", + parameters: Type.Object({ + milestones: Type.Array(Type.String()), + }), + execute: (p, params) => { + const r = addWave(p, params); + return { + plan: r.plan, + message: `Added wave ${r.id} with ${params.milestones.length} milestones`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_wave_milestones", + label: "Set wave milestones", + description: "Update wave milestones list.", + parameters: Type.Object({ + id: Type.String(), + milestones: Type.Array(Type.String()), + }), + execute: (p, params) => { + const updated = setWaveMilestones(p, params.id, params.milestones); + return { + plan: updated, + message: `Set milestones for wave ${params.id}`, + }; + }, + }); + + // -- Diagram -- + planTool(pi, planRef, { + name: "koan_add_diagram", + label: "Add diagram", + description: "Create diagram graph.", + parameters: Type.Object({ + type: Type.Union([ + Type.Literal("architecture"), + Type.Literal("state"), + Type.Literal("sequence"), + Type.Literal("dataflow"), + ]), + scope: Type.String(), + title: Type.String(), + }), + execute: (p, params) => { + const r = addDiagram(p, params); + return { + plan: r.plan, + message: `Added diagram ${r.id}: "${params.title}"`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_set_diagram", + label: "Update diagram", + description: "Update diagram properties.", + parameters: Type.Object({ + id: Type.String(), + title: Type.Optional(Type.String()), + scope: Type.Optional(Type.String()), + ascii_render: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = setDiagram(p, params.id, params); + return { + plan: updated, + message: `Updated diagram ${params.id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_add_diagram_node", + label: "Add diagram node", + description: "Add node to diagram.", + parameters: Type.Object({ + diagram_id: Type.String(), + id: Type.String(), + label: Type.String(), + type: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = addDiagramNode(p, params.diagram_id, params); + return { + plan: updated, + message: `Added node ${params.id} to diagram ${params.diagram_id}`, + }; + }, + }); + + planTool(pi, planRef, { + name: "koan_add_diagram_edge", + label: "Add diagram edge", + description: "Add edge to diagram.", + parameters: Type.Object({ + diagram_id: Type.String(), + source: Type.String(), + target: Type.String(), + label: Type.String(), + protocol: Type.Optional(Type.String()), + }), + execute: (p, params) => { + const updated = addDiagramEdge(p, params.diagram_id, params); + return { + plan: updated, + message: `Added edge ${params.source}->${params.target} to diagram ${params.diagram_id}`, + }; + }, + }); + + // -- ReadmeEntry -- + planTool(pi, planRef, { + name: "koan_set_readme_entry", + label: "Set readme entry", + description: "Upsert readme entry by path.", + parameters: Type.Object({ + path: Type.String(), + content: Type.String(), + }), + execute: (p, params) => { + const updated = setReadmeEntry(p, params.path, params.content); + return { + plan: updated, + message: `Set readme entry for ${params.path}`, + }; + }, + }); +} diff --git a/src/planner/tools/plan-getters.ts b/src/planner/tools/getters.ts similarity index 99% rename from src/planner/tools/plan-getters.ts rename to src/planner/tools/getters.ts index 8154229..712fc3d 100644 --- a/src/planner/tools/plan-getters.ts +++ b/src/planner/tools/getters.ts @@ -1,7 +1,7 @@ import { Type } from "@sinclair/typebox"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import type { PlanRef } from "./dispatch.js"; +import type { PlanRef } from "../lib/dispatch.js"; import { loadPlan } from "../plan/serialize.js"; import type { Plan, Milestone, CodeIntent, CodeChange } from "../plan/types.js"; diff --git a/src/planner/tools/index.ts b/src/planner/tools/index.ts new file mode 100644 index 0000000..e658f49 --- /dev/null +++ b/src/planner/tools/index.ts @@ -0,0 +1,36 @@ +// Tool registration aggregator. Single entry point for koan.ts. +// Re-exports dispatch primitives so koan.ts needs one import for both +// tool registration and workflow infrastructure. + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; +import type { WorkflowDispatch, PlanRef } from "../lib/dispatch.js"; + +import { registerWorkflowTools } from "./workflow.js"; +import { registerPlanGetterTools } from "./getters.js"; +import { registerPlanSetterTools } from "./setters.js"; +import { registerPlanDesignEntityTools } from "./entity-design.js"; +import { registerPlanCodeEntityTools } from "./entity-code.js"; +import { registerPlanStructureEntityTools } from "./entity-structure.js"; +import { registerQRTools } from "./qr.js"; + +export type { WorkflowDispatch, PlanRef, StepResult } from "../lib/dispatch.js"; +export { + createDispatch, + createPlanRef, + hookDispatch, + unhookDispatch, +} from "../lib/dispatch.js"; + +export function registerAllTools( + pi: ExtensionAPI, + planRef: PlanRef, + dispatch: WorkflowDispatch, +): void { + registerWorkflowTools(pi, dispatch); + registerPlanGetterTools(pi, planRef); + registerPlanSetterTools(pi, planRef); + registerPlanDesignEntityTools(pi, planRef); + registerPlanCodeEntityTools(pi, planRef); + registerPlanStructureEntityTools(pi, planRef); + registerQRTools(pi, planRef); +} diff --git a/src/planner/tools/plan-entities.ts b/src/planner/tools/plan-entities.ts deleted file mode 100644 index c38efb2..0000000 --- a/src/planner/tools/plan-entities.ts +++ /dev/null @@ -1,603 +0,0 @@ -// Every tool follows load-mutate-save: loadPlan -> pure mutation -> savePlan. -// Disk is single source of truth. Single-writer assumption per phase. -// Feedback messages prevent the LLM from skipping tools (prior architecture -// returned opaque JSON). -// -// Static derives the TypeScript type from the TypeBox schema at -// compile time, making type casts unnecessary. The registerTool generic -// propagates the schema type through to the execute callback. - -import { Type, type Static, type TSchema } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import type { PlanRef } from "./dispatch.js"; -import { loadPlan, savePlan } from "../plan/serialize.js"; -import type { Plan } from "../plan/types.js"; -import { - addDecision, - setDecision, - addRejectedAlternative, - setRejectedAlternative, - addRisk, - setRisk, - addMilestone, - setMilestoneName, - setMilestoneFiles, - setMilestoneFlags, - setMilestoneRequirements, - setMilestoneAcceptanceCriteria, - setMilestoneTests, - addIntent, - setIntent, - addChange, - setChangeDiff, - setChangeDocDiff, - setChangeComments, - setChangeFile, - setChangeIntentRef, - addWave, - setWaveMilestones, - addDiagram, - setDiagram, - addDiagramNode, - addDiagramEdge, - setReadmeEntry, -} from "../plan/mutate.js"; - -function planTool( - pi: ExtensionAPI, - planRef: PlanRef, - opts: { - name: string; - label: string; - description: string; - parameters: TParams; - execute: (plan: Plan, params: Static) => { plan: Plan; message: string }; - }, -): void { - pi.registerTool({ - name: opts.name, - label: opts.label, - description: opts.description, - parameters: opts.parameters, - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const plan = await loadPlan(planRef.dir); - const result = opts.execute(plan, params); - await savePlan(result.plan, planRef.dir); - return { - content: [{ type: "text" as const, text: result.message }], - details: undefined, - }; - }, - }); -} - -export function registerPlanEntityTools( - pi: ExtensionAPI, - planRef: PlanRef, -): void { - // -- Decision -- - planTool(pi, planRef, { - name: "koan_add_decision", - label: "Add decision", - description: "Add decision to decision log.", - parameters: Type.Object({ - decision: Type.String(), - reasoning: Type.String(), - }), - execute: (p, params) => { - const r = addDecision(p, params); - return { - plan: r.plan, - message: `Added decision ${r.id}: "${params.decision}"`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_decision", - label: "Update decision", - description: "Update existing decision by ID.", - parameters: Type.Object({ - id: Type.String(), - decision: Type.Optional(Type.String()), - reasoning: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = setDecision(p, params.id, params); - return { - plan: updated, - message: `Updated decision ${params.id}`, - }; - }, - }); - - // -- RejectedAlternative -- - planTool(pi, planRef, { - name: "koan_add_rejected_alternative", - label: "Add rejected alternative", - description: "Add rejected alternative to decision log.", - parameters: Type.Object({ - alternative: Type.String(), - rejection_reason: Type.String(), - decision_ref: Type.String(), - }), - execute: (p, params) => { - const r = addRejectedAlternative(p, params); - return { - plan: r.plan, - message: `Added rejected alternative ${r.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_rejected_alternative", - label: "Update rejected alternative", - description: "Update existing rejected alternative by ID.", - parameters: Type.Object({ - id: Type.String(), - alternative: Type.Optional(Type.String()), - rejection_reason: Type.Optional(Type.String()), - decision_ref: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = setRejectedAlternative(p, params.id, params); - return { - plan: updated, - message: `Updated rejected alternative ${params.id}`, - }; - }, - }); - - // -- Risk -- - planTool(pi, planRef, { - name: "koan_add_risk", - label: "Add risk", - description: "Add risk to known risks.", - parameters: Type.Object({ - risk: Type.String(), - mitigation: Type.String(), - anchor: Type.Optional(Type.String()), - decision_ref: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const r = addRisk(p, params); - return { - plan: r.plan, - message: `Added risk ${r.id}: "${params.risk}"`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_risk", - label: "Update risk", - description: "Update existing risk by ID.", - parameters: Type.Object({ - id: Type.String(), - risk: Type.Optional(Type.String()), - mitigation: Type.Optional(Type.String()), - anchor: Type.Optional(Type.String()), - decision_ref: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = setRisk(p, params.id, params); - return { - plan: updated, - message: `Updated risk ${params.id}`, - }; - }, - }); - - // -- Milestone -- - planTool(pi, planRef, { - name: "koan_add_milestone", - label: "Add milestone", - description: "Create new milestone.", - parameters: Type.Object({ - name: Type.String(), - files: Type.Optional(Type.Array(Type.String())), - flags: Type.Optional(Type.Array(Type.String())), - requirements: Type.Optional(Type.Array(Type.String())), - acceptance_criteria: Type.Optional(Type.Array(Type.String())), - tests: Type.Optional(Type.Array(Type.String())), - }), - execute: (p, params) => { - const r = addMilestone(p, params); - return { - plan: r.plan, - message: `Added milestone ${r.id}: "${params.name}"`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_name", - label: "Set milestone name", - description: "Update milestone name.", - parameters: Type.Object({ - id: Type.String(), - name: Type.String(), - }), - execute: (p, params) => { - const updated = setMilestoneName(p, params.id, params.name); - return { - plan: updated, - message: `Set name for milestone ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_files", - label: "Set milestone files", - description: "Update milestone files list.", - parameters: Type.Object({ - id: Type.String(), - files: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setMilestoneFiles(p, params.id, params.files); - return { - plan: updated, - message: `Set files for milestone ${params.id} (${params.files.length} files)`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_flags", - label: "Set milestone flags", - description: "Update milestone flags list.", - parameters: Type.Object({ - id: Type.String(), - flags: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setMilestoneFlags(p, params.id, params.flags); - return { - plan: updated, - message: `Set flags for milestone ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_requirements", - label: "Set milestone requirements", - description: "Update milestone requirements list.", - parameters: Type.Object({ - id: Type.String(), - requirements: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setMilestoneRequirements(p, params.id, params.requirements); - return { - plan: updated, - message: `Set requirements for milestone ${params.id} (${params.requirements.length} items)`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_acceptance_criteria", - label: "Set milestone acceptance criteria", - description: "Update milestone acceptance criteria list.", - parameters: Type.Object({ - id: Type.String(), - acceptance_criteria: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setMilestoneAcceptanceCriteria( - p, - params.id, - params.acceptance_criteria, - ); - return { - plan: updated, - message: `Set acceptance criteria for milestone ${params.id} (${params.acceptance_criteria.length} items)`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_tests", - label: "Set milestone tests", - description: "Update milestone tests list.", - parameters: Type.Object({ - id: Type.String(), - tests: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setMilestoneTests(p, params.id, params.tests); - return { - plan: updated, - message: `Set tests for milestone ${params.id} (${params.tests.length} tests)`, - }; - }, - }); - - // -- CodeIntent -- - planTool(pi, planRef, { - name: "koan_add_intent", - label: "Add code intent", - description: "Add code intent to milestone.", - parameters: Type.Object({ - milestone: Type.String(), - file: Type.String(), - function: Type.Optional(Type.String()), - behavior: Type.String(), - decision_refs: Type.Optional(Type.Array(Type.String())), - }), - execute: (p, params) => { - const r = addIntent(p, params); - return { - plan: r.plan, - message: `Added intent ${r.id} to milestone ${params.milestone}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_intent", - label: "Update code intent", - description: "Update existing code intent by ID.", - parameters: Type.Object({ - id: Type.String(), - file: Type.Optional(Type.String()), - function: Type.Optional(Type.String()), - behavior: Type.Optional(Type.String()), - decision_refs: Type.Optional(Type.Array(Type.String())), - }), - execute: (p, params) => { - const updated = setIntent(p, params.id, params); - return { - plan: updated, - message: `Updated intent ${params.id}`, - }; - }, - }); - - // -- CodeChange -- - planTool(pi, planRef, { - name: "koan_add_change", - label: "Add code change", - description: "Add code change to milestone.", - parameters: Type.Object({ - milestone: Type.String(), - file: Type.String(), - intent_ref: Type.Optional(Type.String()), - diff: Type.Optional(Type.String()), - doc_diff: Type.Optional(Type.String()), - comments: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const r = addChange(p, params); - return { - plan: r.plan, - message: `Added change ${r.id} to milestone ${params.milestone}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_change_diff", - label: "Set code change diff", - description: "Update change diff.", - parameters: Type.Object({ - id: Type.String(), - diff: Type.String(), - }), - execute: (p, params) => { - const updated = setChangeDiff(p, params.id, params.diff); - return { - plan: updated, - message: `Set diff for change ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_change_doc_diff", - label: "Set code change doc_diff", - description: "Update change doc_diff.", - parameters: Type.Object({ - id: Type.String(), - doc_diff: Type.String(), - }), - execute: (p, params) => { - const updated = setChangeDocDiff(p, params.id, params.doc_diff); - return { - plan: updated, - message: `Set doc_diff for change ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_change_comments", - label: "Set code change comments", - description: "Update change comments.", - parameters: Type.Object({ - id: Type.String(), - comments: Type.String(), - }), - execute: (p, params) => { - const updated = setChangeComments(p, params.id, params.comments); - return { - plan: updated, - message: `Set comments for change ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_change_file", - label: "Set code change file", - description: "Update change file path.", - parameters: Type.Object({ - id: Type.String(), - file: Type.String(), - }), - execute: (p, params) => { - const updated = setChangeFile(p, params.id, params.file); - return { - plan: updated, - message: `Set file for change ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_change_intent_ref", - label: "Set code change intent_ref", - description: "Update change intent reference.", - parameters: Type.Object({ - id: Type.String(), - intent_ref: Type.String(), - }), - execute: (p, params) => { - const updated = setChangeIntentRef(p, params.id, params.intent_ref); - return { - plan: updated, - message: `Set intent_ref for change ${params.id}`, - }; - }, - }); - - // -- Wave -- - planTool(pi, planRef, { - name: "koan_add_wave", - label: "Add wave", - description: "Create wave with milestone list.", - parameters: Type.Object({ - milestones: Type.Array(Type.String()), - }), - execute: (p, params) => { - const r = addWave(p, params); - return { - plan: r.plan, - message: `Added wave ${r.id} with ${params.milestones.length} milestones`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_wave_milestones", - label: "Set wave milestones", - description: "Update wave milestones list.", - parameters: Type.Object({ - id: Type.String(), - milestones: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setWaveMilestones(p, params.id, params.milestones); - return { - plan: updated, - message: `Set milestones for wave ${params.id}`, - }; - }, - }); - - // -- Diagram -- - planTool(pi, planRef, { - name: "koan_add_diagram", - label: "Add diagram", - description: "Create diagram graph.", - parameters: Type.Object({ - type: Type.Union([ - Type.Literal("architecture"), - Type.Literal("state"), - Type.Literal("sequence"), - Type.Literal("dataflow"), - ]), - scope: Type.String(), - title: Type.String(), - }), - execute: (p, params) => { - const r = addDiagram(p, params); - return { - plan: r.plan, - message: `Added diagram ${r.id}: "${params.title}"`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_diagram", - label: "Update diagram", - description: "Update diagram properties.", - parameters: Type.Object({ - id: Type.String(), - title: Type.Optional(Type.String()), - scope: Type.Optional(Type.String()), - ascii_render: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = setDiagram(p, params.id, params); - return { - plan: updated, - message: `Updated diagram ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_add_diagram_node", - label: "Add diagram node", - description: "Add node to diagram.", - parameters: Type.Object({ - diagram_id: Type.String(), - id: Type.String(), - label: Type.String(), - type: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = addDiagramNode(p, params.diagram_id, params); - return { - plan: updated, - message: `Added node ${params.id} to diagram ${params.diagram_id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_add_diagram_edge", - label: "Add diagram edge", - description: "Add edge to diagram.", - parameters: Type.Object({ - diagram_id: Type.String(), - source: Type.String(), - target: Type.String(), - label: Type.String(), - protocol: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = addDiagramEdge(p, params.diagram_id, params); - return { - plan: updated, - message: `Added edge ${params.source}->${params.target} to diagram ${params.diagram_id}`, - }; - }, - }); - - // -- ReadmeEntry -- - planTool(pi, planRef, { - name: "koan_set_readme_entry", - label: "Set readme entry", - description: "Upsert readme entry by path.", - parameters: Type.Object({ - path: Type.String(), - content: Type.String(), - }), - execute: (p, params) => { - const updated = setReadmeEntry(p, params.path, params.content); - return { - plan: updated, - message: `Set readme entry for ${params.path}`, - }; - }, - }); -} diff --git a/src/planner/tools/qr-tools.ts b/src/planner/tools/qr.ts similarity index 78% rename from src/planner/tools/qr-tools.ts rename to src/planner/tools/qr.ts index 4d43331..cd99ab1 100644 --- a/src/planner/tools/qr-tools.ts +++ b/src/planner/tools/qr.ts @@ -3,9 +3,10 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { promises as fs } from "node:fs"; import * as path from "node:path"; -import type { PlanRef } from "./dispatch.js"; +import type { PlanRef } from "../lib/dispatch.js"; import type { QRFile } from "../qr/types.js"; import { addQRItem, setQRItem, assignGroup } from "../qr/mutate.js"; +import { withFileLock } from "../../utils/lock.js"; function createEmptyQRFile(phase: string): QRFile { return { @@ -55,13 +56,16 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const qr = await loadQR(planRef.dir, params.phase); - const r = addQRItem(qr, params); - await saveQR(r.qr, planRef.dir, params.phase); - return { - content: [{ type: "text" as const, text: `Added QR item ${r.id}` }], - details: undefined, - }; + const qrPath = path.join(planRef.dir, `qr-${params.phase}.json`); + return withFileLock(qrPath, async () => { + const qr = await loadQR(planRef.dir!, params.phase); + const r = addQRItem(qr, params); + await saveQR(r.qr, planRef.dir!, params.phase); + return { + content: [{ type: "text" as const, text: `Added QR item ${r.id}` }], + details: undefined, + }; + }); }, }); @@ -91,13 +95,16 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const qr = await loadQR(planRef.dir, params.phase); - const updated = setQRItem(qr, params.id, params); - await saveQR(updated, planRef.dir, params.phase); - return { - content: [{ type: "text" as const, text: `Updated QR item ${params.id}` }], - details: undefined, - }; + const qrPath = path.join(planRef.dir, `qr-${params.phase}.json`); + return withFileLock(qrPath, async () => { + const qr = await loadQR(planRef.dir!, params.phase); + const updated = setQRItem(qr, params.id, params); + await saveQR(updated, planRef.dir!, params.phase); + return { + content: [{ type: "text" as const, text: `Updated QR item ${params.id}` }], + details: undefined, + }; + }); }, }); @@ -112,18 +119,21 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const qr = await loadQR(planRef.dir, params.phase); - const updated = assignGroup(qr, params.ids, params.group_id); - await saveQR(updated, planRef.dir, params.phase); - return { - content: [ - { - type: "text" as const, - text: `Assigned ${params.ids.length} items to group ${params.group_id}`, - }, - ], - details: undefined, - }; + const qrPath = path.join(planRef.dir, `qr-${params.phase}.json`); + return withFileLock(qrPath, async () => { + const qr = await loadQR(planRef.dir!, params.phase); + const updated = assignGroup(qr, params.ids, params.group_id); + await saveQR(updated, planRef.dir!, params.phase); + return { + content: [ + { + type: "text" as const, + text: `Assigned ${params.ids.length} items to group ${params.group_id}`, + }, + ], + details: undefined, + }; + }); }, }); diff --git a/src/planner/tools/plan-setters.ts b/src/planner/tools/setters.ts similarity index 96% rename from src/planner/tools/plan-setters.ts rename to src/planner/tools/setters.ts index 4478254..13e0f92 100644 --- a/src/planner/tools/plan-setters.ts +++ b/src/planner/tools/setters.ts @@ -1,13 +1,13 @@ import { Type } from "@sinclair/typebox"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import type { PlanRef } from "./dispatch.js"; +import type { PlanRef } from "../lib/dispatch.js"; import { loadPlan, savePlan } from "../plan/serialize.js"; import { setOverview, setConstraints, setInvisibleKnowledge, -} from "../plan/mutate.js"; +} from "../plan/mutate/index.js"; export function registerPlanSetterTools( pi: ExtensionAPI, diff --git a/src/planner/tools/dispatch.ts b/src/planner/tools/workflow.ts similarity index 58% rename from src/planner/tools/dispatch.ts rename to src/planner/tools/workflow.ts index 7bfa629..70075e8 100644 --- a/src/planner/tools/dispatch.ts +++ b/src/planner/tools/workflow.ts @@ -1,77 +1,16 @@ -// Workflow tool dispatch for koan. -// -// Workflow tools (koan_complete_step, koan_store_context) are registered -// once at init and read from this dispatch at call time. -// Pi snapshots tools during _buildRuntime() -- late registration is -// invisible to the LLM. The dispatch decouples static registration -// from dynamic phase routing. +// Workflow tool registration: koan_complete_step and koan_store_context. +// Tools register once at init; execute callbacks read from the mutable +// dispatch at call time, decoupling static registration from phase routing. import { Type } from "@sinclair/typebox"; -import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import { ContextStoreSchema, type ContextToolResult } from "./context-store.js"; +import { ContextStoreSchema } from "./context-store.js"; import { createLogger } from "../../utils/logger.js"; +import type { WorkflowDispatch } from "../lib/dispatch.js"; const log = createLogger("Dispatch"); -// -- Result types -- - -export interface StepResult { - ok: boolean; - prompt?: string; - error?: string; -} - -// -- Dispatch -- - -export interface WorkflowDispatch { - onCompleteStep: ((thoughts?: string) => StepResult | Promise) | null; - onStoreContext: - | ((payload: unknown, ctx: ExtensionContext) => Promise) - | null; -} - -export function createDispatch(): WorkflowDispatch { - return { onCompleteStep: null, onStoreContext: null }; -} - -// Decouples tool registration (init-time, before _buildRuntime) from -// plan directory creation (runtime, after flags available). Same -// indirection pattern as WorkflowDispatch. -export interface PlanRef { - dir: string | null; -} - -export function createPlanRef(): PlanRef { - return { dir: null }; -} - -// Sets a dispatch slot. Throws if the slot is already occupied -- -// prevents silent misrouting when two phases attempt to claim -// the same tool. -export function hookDispatch( - dispatch: WorkflowDispatch, - key: K, - handler: NonNullable, -): void { - if (dispatch[key] !== null) { - throw new Error(`dispatch.${String(key)} is already hooked`); - } - // TypeScript cannot verify generic key-value assignment. - // Call-site generic constraint (handler: NonNullable) - // ensures type safety; collision guard above prevents double-hooking. - (dispatch as any)[key] = handler; -} - -export function unhookDispatch( - dispatch: WorkflowDispatch, - key: keyof WorkflowDispatch, -): void { - (dispatch as any)[key] = null; -} - -// -- Tool registration -- - // Registers workflow tools. Called once at init in koan.ts, // before pi's _buildRuntime() snapshot. Tool execute callbacks read // from the dispatch at call time -- the dispatch is mutable, the diff --git a/src/utils/lock.ts b/src/utils/lock.ts new file mode 100644 index 0000000..47ed858 --- /dev/null +++ b/src/utils/lock.ts @@ -0,0 +1,44 @@ +import { promises as fs } from "node:fs"; + +// Advisory .lock file for serializing file mutations. Uses O_CREAT|O_EXCL +// for atomic creation (fails if lock already exists). Retry with backoff +// handles transient contention (e.g. parallel QR verifiers). + +const RETRY_INTERVAL_MS = 50; +const MAX_WAIT_MS = 5000; + +function lockPath(filePath: string): string { + return `${filePath}.lock`; +} + +async function acquire(filePath: string): Promise { + const lp = lockPath(filePath); + const deadline = Date.now() + MAX_WAIT_MS; + + while (true) { + try { + const fd = await fs.open(lp, "wx"); + await fd.close(); + return; + } catch (err: unknown) { + if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err; + if (Date.now() >= deadline) { + throw new Error(`Failed to acquire lock on ${filePath} after ${MAX_WAIT_MS}ms`); + } + await new Promise((r) => setTimeout(r, RETRY_INTERVAL_MS)); + } + } +} + +async function release(filePath: string): Promise { + await fs.rm(lockPath(filePath), { force: true }); +} + +export async function withFileLock(filePath: string, fn: () => Promise): Promise { + await acquire(filePath); + try { + return await fn(); + } finally { + await release(filePath); + } +} From a32c2d7cdbea3a291a7899236dfabdccb6a2b08b Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 24 Feb 2026 19:29:04 +0700 Subject: [PATCH 009/412] Better UI --- extensions/koan.ts | 38 ++- src/planner/lib/audit.ts | 327 ++++++++++++++++++++ src/planner/lib/pool.ts | 74 +++++ src/planner/phases/context-capture/phase.ts | 6 +- src/planner/phases/dispatch.ts | 48 ++- src/planner/phases/plan-design/phase.ts | 37 ++- src/planner/phases/qr-decompose/phase.ts | 227 ++++++++++++++ src/planner/phases/qr-decompose/prompts.ts | 256 +++++++++++++++ src/planner/phases/qr-verify/phase.ts | 227 ++++++++++++++ src/planner/phases/qr-verify/prompts.ts | 154 +++++++++ src/planner/session.ts | 318 ++++++++++++------- src/planner/state.ts | 14 +- src/planner/subagent.ts | 96 +++++- src/planner/ui/widget.ts | 203 ++++++++++++ src/utils/logger.ts | 30 +- src/utils/progress.ts | 65 +--- 16 files changed, 1921 insertions(+), 199 deletions(-) create mode 100644 src/planner/lib/audit.ts create mode 100644 src/planner/lib/pool.ts create mode 100644 src/planner/phases/qr-decompose/phase.ts create mode 100644 src/planner/phases/qr-decompose/prompts.ts create mode 100644 src/planner/phases/qr-verify/phase.ts create mode 100644 src/planner/phases/qr-verify/prompts.ts create mode 100644 src/planner/ui/widget.ts diff --git a/extensions/koan.ts b/extensions/koan.ts index 30288d7..a58d81c 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -1,9 +1,15 @@ +// Entry point for the koan pi extension. Serves dual roles: parent session +// (registers /koan command) and subagent mode (dispatches to phase workflow +// via CLI flags). All tools register unconditionally at init; phases restrict +// access via tool_call blocking at runtime. + import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { createSession } from "../src/planner/session.js"; import { detectSubagentMode, dispatchPhase } from "../src/planner/phases/dispatch.js"; import { registerAllTools, createDispatch, createPlanRef } from "../src/planner/tools/index.js"; import { createLogger } from "../src/utils/logger.js"; +import { EventLog, extractToolEvent } from "../src/planner/lib/audit.js"; export default function koan(pi: ExtensionAPI): void { const log = createLogger("Koan"); @@ -32,6 +38,12 @@ export default function koan(pi: ExtensionAPI): void { default: "", }); + pi.registerFlag("koan-qr-item", { + description: "QR item ID for reviewer subagent", + type: "string", + default: "", + }); + // Pi snapshots tools during _buildRuntime() at init. All 44 tools // register here unconditionally. Phases restrict access via tool_call // blocking at runtime. @@ -52,7 +64,31 @@ export default function koan(pi: ExtensionAPI): void { if (planDir) { planRef.dir = planDir; } - await dispatchPhase(pi, config, dispatch, planRef, log); + + // EventLog exists only in subagent mode. Parent mode has no audit log. + let eventLog: EventLog | undefined; + if (config.subagentDir) { + eventLog = new EventLog(config.subagentDir, config.role, config.phase); + await eventLog.open(); + + // Capture all tool results for the audit trail. Graduated detail: + // file paths for read/edit/write, binary name for bash, full + // input+response for koan_* tools, name-only for everything else. + pi.on("tool_result", (event) => { + void eventLog!.append(extractToolEvent(event as { + toolName: string; + input: Record; + content: Array<{ type: string; text?: string }>; + isError: boolean; + })); + }); + + pi.on("session_shutdown", () => { + void eventLog!.close(); + }); + } + + await dispatchPhase(pi, config, dispatch, planRef, log, eventLog); } }); diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts new file mode 100644 index 0000000..181070a --- /dev/null +++ b/src/planner/lib/audit.ts @@ -0,0 +1,327 @@ +// Audit trail for subagent sessions: event-sourced append log (events.jsonl) +// with an eagerly materialized projection (state.json) for parent polling. +// fold() is pure so the projection can be replayed from the raw log for testing. +// Graduated tool capture: full detail for koan_* tools, paths for file ops, +// binary name for bash, name-only for everything else. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +// -- Types -- + +export interface EventBase { + ts: string; + seq: number; +} + +export interface ToolFileEvent extends EventBase { + kind: "tool_file"; + tool: "read" | "edit" | "write"; + path: string; + error: boolean; +} + +export interface ToolBashEvent extends EventBase { + kind: "tool_bash"; + bin: string; + error: boolean; +} + +export interface ToolKoanEvent extends EventBase { + kind: "tool_koan"; + tool: string; + input: Record; + response: string[]; + error: boolean; +} + +export interface ToolGenericEvent extends EventBase { + kind: "tool_generic"; + tool: string; + error: boolean; +} + +export type ToolEvent = ToolFileEvent | ToolBashEvent | ToolKoanEvent | ToolGenericEvent; + +export interface PhaseStartEvent extends EventBase { + kind: "phase_start"; + phase: string; + role: string; + totalSteps: number; +} + +export interface StepTransitionEvent extends EventBase { + kind: "step_transition"; + step: number; + name: string; + totalSteps: number; +} + +export interface PhaseEndEvent extends EventBase { + kind: "phase_end"; + outcome: "completed" | "failed"; + detail?: string; +} + +export interface HeartbeatEvent extends EventBase { + kind: "heartbeat"; +} + +export type AuditEvent = + | ToolFileEvent + | ToolBashEvent + | ToolKoanEvent + | ToolGenericEvent + | PhaseStartEvent + | StepTransitionEvent + | PhaseEndEvent + | HeartbeatEvent; + +export interface Projection { + role: string; + phase: string; + status: "running" | "completed" | "failed"; + step: number; + totalSteps: number; + stepName: string; + lastAction: string | null; + updatedAt: string; + eventCount: number; + error: string | null; +} + +// Pi's ToolResultEvent shape (subset we need). +interface PiToolResultEvent { + toolName: string; + input: Record; + content: Array<{ type: string; text?: string }>; + isError: boolean; +} + +// -- Constants -- + +const FILE_TOOLS = new Set(["read", "edit", "write"]); +const HEARTBEAT_MS = 10_000; + +// -- Helpers -- + +function now(): string { + return new Date().toISOString(); +} + +// Derives a concise last-action string from a tool event for display. +export function summarize(e: ToolEvent): string { + switch (e.kind) { + case "tool_file": + return `${e.tool} ${e.path}`; + case "tool_bash": + return `bash ${e.bin}`; + case "tool_koan": + return e.tool; + case "tool_generic": + return e.tool; + } +} + +// Pure projection update -- one case per discriminated kind. +// All branches update updatedAt and increment eventCount. +export function fold(s: Projection, e: AuditEvent): Projection { + const base = { ...s, updatedAt: e.ts, eventCount: s.eventCount + 1 }; + + switch (e.kind) { + case "phase_start": + return { + ...base, + role: e.role, + phase: e.phase, + status: "running", + step: 0, + totalSteps: e.totalSteps, + stepName: "", + lastAction: null, + error: null, + }; + + case "step_transition": + return { + ...base, + step: e.step, + totalSteps: e.totalSteps, + stepName: `Step ${e.step}/${e.totalSteps}: ${e.name}`, + }; + + case "phase_end": + return { + ...base, + status: e.outcome, + error: e.detail ?? null, + }; + + case "tool_file": + case "tool_bash": + case "tool_koan": + case "tool_generic": + return { ...base, lastAction: summarize(e) }; + + case "heartbeat": + return base; + } +} + +// Transforms pi's ToolResultEvent into a graduated AuditEvent. +export function extractToolEvent(piEvent: PiToolResultEvent): ToolEvent { + const { toolName, input, content, isError } = piEvent; + const ts = now(); + // ts and seq are assigned by EventLog.append(); values here are + // placeholders overridden on write. + const seq = 0; + + if (FILE_TOOLS.has(toolName)) { + return { + kind: "tool_file", + tool: toolName as "read" | "edit" | "write", + path: (input["path"] as string | undefined) ?? "", + error: isError, + ts, + seq, + }; + } + + if (toolName === "bash") { + const cmd = (input["command"] as string | undefined) ?? ""; + const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; + return { kind: "tool_bash", bin, error: isError, ts, seq }; + } + + if (toolName.startsWith("koan_")) { + const response = content + .filter((c) => c.type === "text" && c.text !== undefined) + .map((c) => c.text as string); + return { kind: "tool_koan", tool: toolName, input, response, error: isError, ts, seq }; + } + + return { kind: "tool_generic", tool: toolName, error: isError, ts, seq }; +} + +// -- EventLog -- + +export class EventLog { + private readonly eventsPath: string; + private readonly statePath: string; + private readonly stateTmpPath: string; + private fd: fs.FileHandle | null = null; + private seq = 0; + private projection: Projection; + private heartbeat: ReturnType | null = null; + // Serializes append() calls. Heartbeat timer and tool_result handler + // both call append() concurrently -- without serialization, two + // writeState() calls race on the shared tmp file (ENOENT on rename). + private pending: Promise = Promise.resolve(); + + constructor(dir: string, role: string, phase: string) { + this.eventsPath = path.join(dir, "events.jsonl"); + this.statePath = path.join(dir, "state.json"); + this.stateTmpPath = path.join(dir, "state.tmp.json"); + this.projection = { + role, + phase, + status: "running", + step: 0, + totalSteps: 0, + stepName: "", + lastAction: null, + updatedAt: now(), + eventCount: 0, + error: null, + }; + } + + async open(): Promise { + this.fd = await fs.open(this.eventsPath, "a"); + await this.writeState(); + // Heartbeat keeps updatedAt fresh even during long-running steps. + this.heartbeat = setInterval(() => { + void this.append({ kind: "heartbeat" } as Omit); + }, HEARTBEAT_MS); + } + + // Assigns ts + seq, appends JSON line, folds, writes state atomically. + // Serialized: concurrent callers queue behind the in-flight write. + async append(partial: Omit): Promise { + const task = () => this.doAppend(partial); + this.pending = this.pending.then(task, task); + return this.pending; + } + + private async doAppend(partial: Omit): Promise { + if (!this.fd) { + throw new Error("EventLog.append called before open()"); + } + + const e = { ...partial, ts: now(), seq: this.seq++ } as AuditEvent; + await this.fd.write(JSON.stringify(e) + "\n"); + this.projection = fold(this.projection, e); + await this.writeState(); + } + + async emitPhaseStart(totalSteps: number): Promise { + await this.append({ + kind: "phase_start", + phase: this.projection.phase, + role: this.projection.role, + totalSteps, + } as Omit); + } + + async emitStepTransition(step: number, name: string, totalSteps: number): Promise { + await this.append({ + kind: "step_transition", + step, + name, + totalSteps, + } as Omit); + } + + async emitPhaseEnd(outcome: "completed" | "failed", detail?: string): Promise { + await this.append({ + kind: "phase_end", + outcome, + detail, + } as Omit); + } + + async close(): Promise { + if (this.heartbeat) { + clearInterval(this.heartbeat); + this.heartbeat = null; + } + if (this.fd) { + await this.fd.close(); + this.fd = null; + } + } + + get state(): Readonly { + return this.projection; + } + + // Atomic write: tmp file then rename so readers never see partial JSON. + private async writeState(): Promise { + const json = JSON.stringify(this.projection, null, 2) + "\n"; + await fs.writeFile(this.stateTmpPath, json); + await fs.rename(this.stateTmpPath, this.statePath); + } +} + +// -- Exports -- + +// Reads state.json as a Projection; returns null if missing or malformed. +// Used by session.ts parent polling loop. +export async function readProjection(dir: string): Promise { + try { + const raw = await fs.readFile(path.join(dir, "state.json"), "utf8"); + return JSON.parse(raw) as Projection; + } catch { + return null; + } +} diff --git a/src/planner/lib/pool.ts b/src/planner/lib/pool.ts new file mode 100644 index 0000000..f5e9c3f --- /dev/null +++ b/src/planner/lib/pool.ts @@ -0,0 +1,74 @@ +// Bounded-parallel subagent pool using an in-process semaphore. +// Runs all items to completion regardless of failures; callers inspect PoolResult. +// Timeout logic belongs in the worker closure, not here. + +import type { SubagentResult } from "../subagent.js"; + +// -- Types -- + +export interface PoolResult { + total: number; + completed: number; + failed: string[]; +} + +// -- Constants -- + +export const DEFAULT_REVIEWER_TIMEOUT_MS = 10 * 60 * 1000; + +// -- Private helpers -- + +class Semaphore { + private queue: Array<() => void> = []; + private count: number; + + constructor(limit: number) { + this.count = limit; + } + + acquire(): Promise { + if (this.count > 0) { + this.count--; + return Promise.resolve(); + } + return new Promise((resolve) => this.queue.push(resolve)); + } + + release(): void { + const next = this.queue.shift(); + if (next) next(); + else this.count++; + } +} + +// -- Exports -- + +export async function pool( + itemIds: string[], + limit: number, + worker: (itemId: string) => Promise, + onProgress?: (done: number, total: number) => void, +): Promise { + const sem = new Semaphore(limit); + const total = itemIds.length; + const failed: string[] = []; + let completed = 0; + + await Promise.all( + itemIds.map(async (id) => { + await sem.acquire(); + try { + const r = await worker(id); + if (r.exitCode !== 0) { + failed.push(id); + } + } finally { + completed++; + onProgress?.(completed, total); + sem.release(); + } + }), + ); + + return { total, completed, failed }; +} diff --git a/src/planner/phases/context-capture/phase.ts b/src/planner/phases/context-capture/phase.ts index 4b7320e..ecd4b94 100644 --- a/src/planner/phases/context-capture/phase.ts +++ b/src/planner/phases/context-capture/phase.ts @@ -81,7 +81,6 @@ export class ContextCapturePhase { hookDispatch(this.dispatch, "onStoreContext", (p, c) => this.handleContextToolCall(p, c)); this.log("Starting context capture (draft phase)", { planId: plan.id }); - ctx.ui.notify(`Koan context capture started for plan ${plan.id}.`, "info"); await this.updatePlanMetadata({ status: "context", @@ -211,8 +210,8 @@ export class ContextCapturePhase { this.log("Failed to write context file", { error: message }); return { ok: false, - message: `Failed to write context.json: ${message}`, - errors: [`Failed to write context.json: ${message}`], + message: `Failed to store context: ${message}`, + errors: [`Failed to store context: ${message}`], }; } @@ -224,7 +223,6 @@ export class ContextCapturePhase { unhookDispatch(this.dispatch, "onCompleteStep"); unhookDispatch(this.dispatch, "onStoreContext"); - ctx.ui.notify("Koan context capture complete.", "info"); this.log("Context capture succeeded", { planId: this.state.context.planId, attempt: this.state.context.attempt, diff --git a/src/planner/phases/dispatch.ts b/src/planner/phases/dispatch.ts index acb9dfc..c8a55f8 100644 --- a/src/planner/phases/dispatch.ts +++ b/src/planner/phases/dispatch.ts @@ -1,8 +1,16 @@ +// Phase dispatch: detects subagent mode from CLI flags and routes to the +// appropriate phase constructor. Flags are unavailable at extension init +// (getFlag returns undefined before _buildRuntime), so detection is +// deferred to before_agent_start. + import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { PlanDesignPhase } from "./plan-design/phase.js"; +import { QRDecomposePhase } from "./qr-decompose/phase.js"; +import { QRVerifyPhase } from "./qr-verify/phase.js"; import { createLogger, type Logger } from "../../utils/logger.js"; import type { WorkflowDispatch, PlanRef } from "../lib/dispatch.js"; +import type { EventLog } from "../lib/audit.js"; export interface SubagentConfig { role: string; @@ -39,6 +47,7 @@ export async function dispatchPhase( dispatch: WorkflowDispatch, planRef: PlanRef, log?: Logger, + eventLog?: EventLog, ): Promise { const logger = log ?? createLogger("Dispatch"); @@ -46,13 +55,44 @@ export async function dispatchPhase( logger("Dispatching to plan-design workflow", { planDir: config.planDir }); const phase = new PlanDesignPhase( pi, - { - planDir: config.planDir, - subagentDir: config.subagentDir || undefined, - }, + { planDir: config.planDir }, + dispatch, + planRef, + logger, + eventLog, + ); + await phase.begin(); + return; + } + + if (config.role === "qr-decomposer" && config.phase === "qr-plan-design") { + logger("Dispatching to qr-decompose workflow", { planDir: config.planDir }); + const phase = new QRDecomposePhase( + pi, + { planDir: config.planDir }, + dispatch, + planRef, + logger, + eventLog, + ); + await phase.begin(); + return; + } + + if (config.role === "reviewer" && config.phase === "qr-plan-design") { + const itemId = pi.getFlag("koan-qr-item") as string; + if (!itemId) { + logger("Reviewer missing --koan-qr-item flag"); + return; + } + logger("Dispatching to qr-verify workflow", { planDir: config.planDir, itemId }); + const phase = new QRVerifyPhase( + pi, + { planDir: config.planDir, itemId }, dispatch, planRef, logger, + eventLog, ); await phase.begin(); return; diff --git a/src/planner/phases/plan-design/phase.ts b/src/planner/phases/plan-design/phase.ts index b7c493a..f2165ef 100644 --- a/src/planner/phases/plan-design/phase.ts +++ b/src/planner/phases/plan-design/phase.ts @@ -1,3 +1,7 @@ +// Plan-design phase -- 6-step architect workflow that produces plan.json +// from captured context. Step gate: mutation tools blocked before step 6 +// (blocklist pattern). Validation runs at step-6 completion. + import { promises as fs } from "node:fs"; import * as path from "node:path"; @@ -14,7 +18,7 @@ import { import { formatStep } from "../../lib/step.js"; import type { ContextData } from "../../types.js"; import { createLogger, type Logger } from "../../../utils/logger.js"; -import { ProgressReporter } from "../../../utils/progress.js"; +import { EventLog } from "../../lib/audit.js"; import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; @@ -28,24 +32,31 @@ interface PlanDesignState { systemPrompt: string | null; } +const TOTAL_STEPS = 6; + export class PlanDesignPhase { private readonly pi: ExtensionAPI; private readonly planDir: string; private readonly log: Logger; private readonly state: PlanDesignState; - private readonly progress: ProgressReporter | null; + private readonly eventLog: EventLog | undefined; private readonly dispatch: WorkflowDispatch; private readonly planRef: PlanRef; - constructor(pi: ExtensionAPI, config: { planDir: string; subagentDir?: string }, dispatch: WorkflowDispatch, planRef: PlanRef, log?: Logger) { + constructor( + pi: ExtensionAPI, + config: { planDir: string }, + dispatch: WorkflowDispatch, + planRef: PlanRef, + log?: Logger, + eventLog?: EventLog, + ) { this.pi = pi; this.planDir = config.planDir; this.dispatch = dispatch; this.planRef = planRef; this.log = log ?? createLogger("PlanDesign"); - this.progress = config.subagentDir - ? new ProgressReporter(config.subagentDir, "architect", "plan-design") - : null; + this.eventLog = eventLog; this.state = { active: false, @@ -91,7 +102,8 @@ export class PlanDesignPhase { hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); this.log("Starting plan-design workflow", { step: 1 }); - await this.progress?.update(`Step 1/6: ${STEP_NAMES[1]} -- started`); + await this.eventLog?.emitPhaseStart(TOTAL_STEPS); + await this.eventLog?.emitStepTransition(1, STEP_NAMES[1], TOTAL_STEPS); } private registerHandlers(): void { @@ -146,9 +158,6 @@ export class PlanDesignPhase { return undefined; }); - this.pi.on("turn_end", (event) => { - if (!this.state.active) return; - }); } private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { @@ -157,10 +166,12 @@ export class PlanDesignPhase { if (prev === 6) { const result = await this.handleFinalize(); if (!result.ok) { + await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); return { ok: false, error: result.errors?.join("; ") }; } this.state.active = false; unhookDispatch(this.dispatch, "onCompleteStep"); + await this.eventLog?.emitPhaseEnd("completed"); this.log("Plan finalized, workflow complete"); return { ok: true, prompt: "Plan validation passed. Workflow complete." }; } @@ -170,9 +181,7 @@ export class PlanDesignPhase { const prompt = formatStep(planDesignStepGuidance(this.state.step)); this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName }); - - this.progress?.update(`Step ${prev}/6: ${STEP_NAMES[prev]} -- complete`); - this.progress?.update(`Step ${this.state.step}/6: ${nextName} -- started`); + await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); return { ok: true, prompt }; } @@ -202,8 +211,6 @@ export class PlanDesignPhase { } this.log("Plan validation passed", { path: planPath }); - await this.progress?.update("Step 6/6: " + STEP_NAMES[6] + " -- complete"); - await this.progress?.complete("completed"); return { ok: true }; } } diff --git a/src/planner/phases/qr-decompose/phase.ts b/src/planner/phases/qr-decompose/phase.ts new file mode 100644 index 0000000..5a8a99e --- /dev/null +++ b/src/planner/phases/qr-decompose/phase.ts @@ -0,0 +1,227 @@ +// QR decompose phase -- 13-step workflow that decomposes a plan into +// verifiable QR items. Mirrors PlanDesignPhase lifecycle exactly. +// Two-tier step gate: koan_qr_add_item unlocks at step 5, +// koan_qr_assign_group unlocks at step 9. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { + loadQRDecomposeSystemPrompt, + formatContextForDecompose, + buildDecomposeSystemPrompt, + decomposeStepGuidance, + DECOMPOSE_STEP_NAMES, + type DecomposeStep, +} from "./prompts.js"; +import { formatStep } from "../../lib/step.js"; +import type { ContextData } from "../../types.js"; +import { createLogger, type Logger } from "../../../utils/logger.js"; +import { EventLog } from "../../lib/audit.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; +import { checkPermission } from "../../lib/permissions.js"; +import type { QRFile } from "../../qr/types.js"; + +// -- Step gate constants -- + +// Blocklist pattern: only restrict tools this gate owns; everything else +// defers to checkPermission. Avoids blocking read tools or future pi tools. +const QR_ADD_TOOLS = new Set(["koan_qr_add_item"]); +const QR_ASSIGN_TOOLS = new Set(["koan_qr_assign_group"]); +const ADD_ITEM_UNLOCK = 5; +const ASSIGN_GROUP_UNLOCK = 9; +const TOTAL_STEPS = 13; + +// -- State -- + +interface DecomposeState { + active: boolean; + step: DecomposeStep; + step1Prompt: string | null; + systemPrompt: string | null; +} + +// -- Phase -- + +export class QRDecomposePhase { + private readonly pi: ExtensionAPI; + private readonly planDir: string; + private readonly log: Logger; + private readonly state: DecomposeState; + private readonly eventLog: EventLog | undefined; + private readonly dispatch: WorkflowDispatch; + private readonly planRef: PlanRef; + + constructor( + pi: ExtensionAPI, + config: { planDir: string }, + dispatch: WorkflowDispatch, + planRef: PlanRef, + log?: Logger, + eventLog?: EventLog, + ) { + this.pi = pi; + this.planDir = config.planDir; + this.dispatch = dispatch; + this.planRef = planRef; + this.log = log ?? createLogger("QRDecompose"); + this.eventLog = eventLog; + + this.state = { + active: false, + step: 1, + step1Prompt: null, + systemPrompt: null, + }; + + this.registerHandlers(); + } + + async begin(): Promise { + const contextPath = path.join(this.planDir, "context.json"); + let contextData: ContextData; + try { + const raw = await fs.readFile(contextPath, "utf8"); + contextData = JSON.parse(raw) as ContextData; + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to read context.json", { error: message }); + return; + } + + let basePrompt: string; + try { + basePrompt = await loadQRDecomposeSystemPrompt(); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to load qr-decompose system prompt", { error: message }); + return; + } + + const contextXml = formatContextForDecompose(contextData); + this.state.systemPrompt = buildDecomposeSystemPrompt(basePrompt); + this.state.step1Prompt = formatStep(decomposeStepGuidance(1, contextXml)); + this.state.active = true; + this.state.step = 1; + this.planRef.dir = this.planDir; + + hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); + + this.log("Starting qr-decompose workflow", { step: 1 }); + await this.eventLog?.emitPhaseStart(TOTAL_STEPS); + await this.eventLog?.emitStepTransition(1, DECOMPOSE_STEP_NAMES[1], TOTAL_STEPS); + } + + private registerHandlers(): void { + this.pi.on("before_agent_start", () => { + if (!this.state.active || !this.state.systemPrompt) return undefined; + return { systemPrompt: this.state.systemPrompt }; + }); + + // Step 1 prompt injection. The CLI message is a process trigger -- + // the context event fires before each LLM call and replaces the + // user message with the actual step 1 instructions. Handler is a + // no-op once the step advances past 1. + this.pi.on("context", (event) => { + if (!this.state.active) return undefined; + if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; + + const messages = event.messages.map((m) => { + if (m.role === "user") { + return { ...m, content: this.state.step1Prompt! }; + } + return m; + }); + return { messages }; + }); + + this.pi.on("tool_call", (event) => { + if (!this.state.active) return undefined; + + // Outer boundary: phase permissions (default-deny). + const perm = checkPermission("qr-plan-design", event.toolName); + if (!perm.allowed) { + return { block: true, reason: perm.reason }; + } + + // Inner constraint: two-tier step gate (blocklist, not whitelist). + const step = this.state.step; + if (step < ADD_ITEM_UNLOCK && QR_ADD_TOOLS.has(event.toolName)) { + return { + block: true, + reason: `${event.toolName} available from step ${ADD_ITEM_UNLOCK} (current: ${step})`, + }; + } + if (step < ASSIGN_GROUP_UNLOCK && QR_ASSIGN_TOOLS.has(event.toolName)) { + return { + block: true, + reason: `${event.toolName} available from step ${ASSIGN_GROUP_UNLOCK} (current: ${step})`, + }; + } + + return undefined; + }); + + } + + private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { + const prev = this.state.step; + + if (prev === 13) { + const result = await this.handleFinalize(); + if (!result.ok) { + await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); + return { ok: false, error: result.errors?.join("; ") }; + } + // Only unhook after successful finalization -- on failure the LLM + // receives the error as a tool result and may retry within the step. + this.state.active = false; + unhookDispatch(this.dispatch, "onCompleteStep"); + await this.eventLog?.emitPhaseEnd("completed"); + this.log("QR decompose finalized, workflow complete"); + return { ok: true, prompt: "QR decomposition complete." }; + } + + this.state.step = (prev + 1) as DecomposeStep; + const nextName = DECOMPOSE_STEP_NAMES[this.state.step]; + const prompt = formatStep(decomposeStepGuidance(this.state.step)); + + this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName }); + await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); + + return { ok: true, prompt }; + } + + private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { + const qrPath = path.join(this.planDir, "qr-plan-design.json"); + let qr: QRFile; + try { + const raw = await fs.readFile(qrPath, "utf8"); + qr = JSON.parse(raw) as QRFile; + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + return { ok: false, errors: [`Failed to read qr-plan-design.json: ${message}`] }; + } + + const errors: string[] = []; + if (!qr.items || qr.items.length === 0) { + errors.push("No QR items generated"); + } else { + const ungrouped = qr.items.filter((i) => i.group_id === null); + if (ungrouped.length > 0) { + const ids = ungrouped.map((i) => i.id).join(", "); + errors.push(`Ungrouped items: ${ids}`); + } + } + + if (errors.length > 0) { + this.log("QR decompose validation failed", { errors }); + return { ok: false, errors }; + } + + this.log("QR decompose validation passed"); + return { ok: true }; + } +} diff --git a/src/planner/phases/qr-decompose/prompts.ts b/src/planner/phases/qr-decompose/prompts.ts new file mode 100644 index 0000000..3c4969e --- /dev/null +++ b/src/planner/phases/qr-decompose/prompts.ts @@ -0,0 +1,256 @@ +// QR decompose phase prompts -- 13-step workflow for decomposing a plan into +// verifiable QR items. Follows the same structure as plan-design/prompts.ts. +// All tool calls reference phase='plan-design' explicitly so the decompose +// agent always writes to the correct QR namespace. + +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import type { ContextData } from "../../types.js"; +import type { StepGuidance } from "../../lib/step.js"; + +// -- Types -- + +export type DecomposeStep = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13; + +// -- Constants -- + +export const DECOMPOSE_STEP_NAMES: Record = { + 1: "Absorb Context", + 2: "Holistic Concerns", + 3: "Structural Enumeration", + 4: "Gap Analysis", + 5: "Generate Items", + 6: "Atomicity Check", + 7: "Coverage Validation", + 8: "Validate Items", + 9: "Structural Grouping", + 10: "Component Grouping", + 11: "Concern Grouping", + 12: "Affinity Grouping", + 13: "Final Validation", +}; + +// -- Exports -- + +export async function loadQRDecomposeSystemPrompt(): Promise { + const homeDir = os.homedir(); + const promptPath = path.join(homeDir, ".claude/agents/quality-reviewer.md"); + try { + const content = await fs.readFile(promptPath, "utf8"); + const body = content.replace(/^---\n[\s\S]*?\n---\n/, ""); + return body; + } catch { + throw new Error(`Quality reviewer prompt not found at ${promptPath}`); + } +} + +export function buildDecomposeSystemPrompt(basePrompt: string): string { + return [ + basePrompt, + "", + "---", + "", + "WORKFLOW: 13-STEP QR DECOMPOSITION (plan-design)", + "", + "You will execute a 13-step workflow to decompose a plan into verifiable QR items.", + "Step 1 instructions are in the user message below.", + "Complete the work described, then call koan_complete_step.", + "Put your findings in the `thoughts` parameter of koan_complete_step.", + "The tool result contains the next step's instructions.", + "", + "CRITICAL: Do the actual work described in each step BEFORE calling", + "koan_complete_step. Read the plan, analyze, generate items. Do not skip.", + ].join("\n"); +} + +export function formatContextForDecompose(ctx: ContextData): string { + return [ + "", + JSON.stringify(ctx, null, 2), + "", + ].join("\n"); +} + +export function decomposeStepGuidance(step: DecomposeStep, context?: string): StepGuidance { + switch (step) { + case 1: + return { + title: "Step 1: Absorb Context", + instructions: [ + "PLANNING CONTEXT (from session):", + "", + context ?? "", + "", + "Use koan_get_plan to read the full plan.", + "Absorb the plan structure: overview, constraints, milestones, decisions, code_intents, risks, invisible_knowledge.", + "Identify the key entities and relationships that will need verification.", + ], + }; + + case 2: + return { + title: "Step 2: Holistic Concerns", + instructions: [ + "Identify plan-wide concerns that apply across all milestones.", + "Consider: structural completeness, logical consistency, risk coverage, dependency ordering.", + "Focus on plan-level quality -- not code correctness.", + "These concerns become scope='*' items in later steps.", + ], + }; + + case 3: + return { + title: "Step 3: Structural Enumeration", + instructions: [ + "Enumerate every major entity in the plan:", + " - Decisions (DL-xxx)", + " - Constraints", + " - Risks", + " - Milestones (M-xxx) and their code_intents (CI-M-xxx-xxx)", + " - Invisible knowledge entries", + " - Waves and ordering", + "Track counts for validation in step 8.", + ], + }; + + case 4: + return { + title: "Step 4: Gap Analysis", + instructions: [ + "Compare holistic concerns (step 2) against structural entities (step 3).", + "Identify gaps: concerns not covered by any entity, entities lacking justification.", + "Note areas where the plan is thin or under-specified.", + ], + }; + + case 5: + return { + title: "Step 5: Generate Items", + instructions: [ + "Generate QR items from the analysis in steps 2-4.", + "Use koan_qr_add_item to create each item. Always pass phase='plan-design'.", + "", + "SCOPE VOCABULARY:", + " '*' -- plan-wide check", + " 'milestone:M-001' -- milestone-specific check", + " 'decision:DL-001' -- decision-specific check", + " 'code_intent:CI-M-001-001' -- code intent-specific check", + "", + "SEVERITY:", + " MUST -- blocks all iterations (critical defect)", + " SHOULD -- important quality issue", + " COULD -- nice-to-have improvement", + "", + "Generate items covering: structural completeness, decision reasoning chains,", + "risk coverage, milestone scoping, code intent clarity, constraint satisfaction.", + ], + }; + + case 6: + return { + title: "Step 6: Atomicity Check", + instructions: [ + "Review each generated item. Each item should test exactly one concern.", + "If an item covers multiple concerns, split it:", + " Use koan_qr_add_item for each child item.", + " The original becomes the parent (parent_id on children).", + "Atomic items are easier to verify independently.", + ], + }; + + case 7: + return { + title: "Step 7: Coverage Validation", + instructions: [ + "Cross-reference items against the plan structure.", + "Every milestone should have at least one QR item.", + "Every decision should have at least one QR item.", + "High-severity risks should have corresponding QR items.", + "Use koan_qr_add_item for any gaps found.", + ], + }; + + case 8: + return { + title: "Step 8: Validate Items", + instructions: [ + "Items are already on disk (each koan_qr_add_item wrote immediately).", + "Use koan_qr_summary(phase='plan-design') to verify counts.", + "Use koan_qr_list_items(phase='plan-design') to review all items.", + "Check: no duplicate checks, severity levels appropriate, scopes valid.", + "Add missing items with koan_qr_add_item if gaps found.", + ], + }; + + case 9: + return { + title: "Step 9: Structural Grouping", + instructions: [ + "Begin organizing items into review groups.", + "DETERMINISTIC RULES:", + " - Parent-child items share the same group", + " - Umbrella items (scope='*') get group_id='umbrella'", + "", + "Use koan_qr_list_items(phase='plan-design') to see current items.", + "Use koan_qr_assign_group(phase='plan-design', ids=[...], group_id='...') to assign groups.", + ], + }; + + case 10: + return { + title: "Step 10: Component Grouping", + instructions: [ + "Group remaining ungrouped items by plan component.", + "Group candidates: a major milestone, a major decision, a constraint category.", + "", + "Use koan_qr_list_items(phase='plan-design') to see ungrouped items.", + "Use koan_qr_assign_group(phase='plan-design', ids=[...], group_id='...') to assign.", + ], + }; + + case 11: + return { + title: "Step 11: Concern Grouping", + instructions: [ + "Group remaining ungrouped items by concern type.", + "Group candidates: reasoning chain quality, reference integrity, risk coverage.", + "", + "Use koan_qr_list_items(phase='plan-design') to see ungrouped items.", + "Use koan_qr_assign_group(phase='plan-design', ids=[...], group_id='...') to assign.", + ], + }; + + case 12: + return { + title: "Step 12: Affinity Grouping", + instructions: [ + "Assign remaining ungrouped items to groups based on similarity.", + "Singletons are acceptable -- not every item needs a multi-member group.", + "", + "Use koan_qr_list_items(phase='plan-design') to see ungrouped items.", + "Use koan_qr_assign_group(phase='plan-design', ids=[...], group_id='...') to assign.", + ], + }; + + case 13: + return { + title: "Step 13: Final Validation", + instructions: [ + "Validate all items are grouped and well-formed.", + "Use koan_qr_summary(phase='plan-design') to check final counts.", + "Use koan_qr_list_items(phase='plan-design') to verify all items have group_id.", + "If any items lack group_id, assign them now.", + "Output 'PASS' in thoughts if all items are valid and grouped.", + ], + invokeAfter: [ + "WHEN DONE: Call koan_complete_step with 'PASS' or issues found in the `thoughts` parameter.", + "Do NOT call this tool until validation is complete.", + ].join("\n"), + }; + + default: + return { title: "", instructions: [] }; + } +} diff --git a/src/planner/phases/qr-verify/phase.ts b/src/planner/phases/qr-verify/phase.ts new file mode 100644 index 0000000..4a8e5c1 --- /dev/null +++ b/src/planner/phases/qr-verify/phase.ts @@ -0,0 +1,227 @@ +// QR verify phase -- 3-step reviewer subagent that verifies exactly 1 QR item +// against the plan (CONTEXT -> ANALYZE -> CONFIRM). One subagent per item. +// Mirrors PlanDesignPhase lifecycle; no finalize validation -- parent reads +// item status from disk after the reviewer exits. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { formatStep } from "../../lib/step.js"; +import type { ContextData } from "../../types.js"; +import { createLogger, type Logger } from "../../../utils/logger.js"; +import { EventLog } from "../../lib/audit.js"; +import { + hookDispatch, + unhookDispatch, + type WorkflowDispatch, + type PlanRef, +} from "../../lib/dispatch.js"; +import { checkPermission } from "../../lib/permissions.js"; +import type { QRItem, QRFile } from "../../qr/types.js"; +import { + loadQRVerifySystemPrompt, + buildVerifySystemPrompt, + buildContextStep, + buildAnalyzeStep, + buildConfirmStep, + type VerifyStep, +} from "./prompts.js"; + +// -- Constants -- + +const TOTAL_STEPS = 3; +const STEP_NAMES: Record = { + 1: "CONTEXT", + 2: "ANALYZE", + 3: "CONFIRM", +}; + +// -- State -- + +interface VerifyState { + active: boolean; + step: VerifyStep; + itemId: string; + step1Prompt: string | null; + systemPrompt: string | null; +} + +// -- Phase -- + +export class QRVerifyPhase { + private readonly pi: ExtensionAPI; + private readonly planDir: string; + private readonly log: Logger; + private readonly state: VerifyState; + private readonly eventLog: EventLog | undefined; + private readonly dispatch: WorkflowDispatch; + private readonly planRef: PlanRef; + private item: QRItem | null = null; + + constructor( + pi: ExtensionAPI, + config: { planDir: string; itemId: string }, + dispatch: WorkflowDispatch, + planRef: PlanRef, + log?: Logger, + eventLog?: EventLog, + ) { + this.pi = pi; + this.planDir = config.planDir; + this.dispatch = dispatch; + this.planRef = planRef; + this.log = log ?? createLogger("QRVerify"); + this.eventLog = eventLog; + + this.state = { + active: false, + step: 1, + itemId: config.itemId, + step1Prompt: null, + systemPrompt: null, + }; + + this.registerHandlers(); + } + + async begin(): Promise { + // Verify plan.json exists so koan_get_plan is usable during analysis. + const planPath = path.join(this.planDir, "plan.json"); + try { + await fs.access(planPath); + } catch { + this.log("plan.json not found", { path: planPath }); + return; + } + + const contextPath = path.join(this.planDir, "context.json"); + let contextData: ContextData; + try { + const raw = await fs.readFile(contextPath, "utf8"); + contextData = JSON.parse(raw) as ContextData; + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to read context.json", { error: message }); + return; + } + + const qrPath = path.join(this.planDir, "qr-plan-design.json"); + let qrFile: QRFile; + try { + const raw = await fs.readFile(qrPath, "utf8"); + qrFile = JSON.parse(raw) as QRFile; + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to read qr-plan-design.json", { error: message }); + return; + } + + const item = qrFile.items.find((i) => i.id === this.state.itemId); + if (!item) { + this.log("QR item not found", { itemId: this.state.itemId }); + return; + } + this.item = item; + + let basePrompt: string; + try { + basePrompt = await loadQRVerifySystemPrompt(); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to load QR verify system prompt", { error: message }); + return; + } + + this.state.systemPrompt = buildVerifySystemPrompt(basePrompt); + this.state.step1Prompt = formatStep(buildContextStep(item, contextData)); + this.state.active = true; + this.state.step = 1; + this.planRef.dir = this.planDir; + + hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); + + this.log("Starting QR verify workflow", { itemId: this.state.itemId, step: 1 }); + await this.eventLog?.emitPhaseStart(TOTAL_STEPS); + await this.eventLog?.emitStepTransition(1, STEP_NAMES[1], TOTAL_STEPS); + } + + private registerHandlers(): void { + this.pi.on("before_agent_start", () => { + if (!this.state.active || !this.state.systemPrompt) return undefined; + return { systemPrompt: this.state.systemPrompt }; + }); + + // Step 1 prompt injection. Context event fires before the initial LLM + // call and replaces the trigger user message with actual step 1 instructions. + // Handler is a no-op once the step advances past 1. + this.pi.on("context", (event) => { + if (!this.state.active) return undefined; + if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; + + const messages = event.messages.map((m) => { + if (m.role === "user") { + return { ...m, content: this.state.step1Prompt! }; + } + return m; + }); + return { messages }; + }); + + this.pi.on("tool_call", (event) => { + if (!this.state.active) return undefined; + + const perm = checkPermission("qr-plan-design", event.toolName); + if (!perm.allowed) { + return { block: true, reason: perm.reason }; + } + + // Step gate: koan_qr_set_item is step-3-only (CONFIRM step). + // Blocklist so read tools and other approved tools pass through. + const step = this.state.step; + if (step < 3 && event.toolName === "koan_qr_set_item") { + return { + block: true, + reason: `koan_qr_set_item available in step 3 (current: ${step})`, + }; + } + + return undefined; + }); + + } + + private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { + const prev = this.state.step; + + if (prev === 3) { + this.state.active = false; + unhookDispatch(this.dispatch, "onCompleteStep"); + await this.eventLog?.emitPhaseEnd("completed"); + this.log("Verification complete"); + return { ok: true, prompt: "Verification complete." }; + } + + this.state.step = (prev + 1) as VerifyStep; + const stepName = STEP_NAMES[this.state.step]; + const prompt = this.buildStepPrompt(this.state.step); + + this.log("Step complete, advancing", { from: prev, to: this.state.step }); + await this.eventLog?.emitStepTransition(this.state.step, stepName, TOTAL_STEPS); + + return { ok: true, prompt }; + } + + // Item is stored during begin() -- avoids async re-reads for prompt building. + private buildStepPrompt(step: VerifyStep): string { + switch (step) { + case 2: + return formatStep(buildAnalyzeStep(this.item!)); + case 3: + return formatStep(buildConfirmStep(this.item!)); + default: + return ""; + } + } +} diff --git a/src/planner/phases/qr-verify/prompts.ts b/src/planner/phases/qr-verify/prompts.ts new file mode 100644 index 0000000..97dfe3f --- /dev/null +++ b/src/planner/phases/qr-verify/prompts.ts @@ -0,0 +1,154 @@ +// Prompt guidance for the 3-step QR verify subagent workflow. +// +// Each reviewer subagent verifies exactly 1 QRItem against the plan. +// Steps: CONTEXT (understand the check) -> ANALYZE (read plan, apply check) +// -> CONFIRM (record verdict via koan_qr_set_item). + +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import type { ContextData } from "../../types.js"; +import type { QRItem } from "../../qr/types.js"; +import type { StepGuidance } from "../../lib/step.js"; + +// -- Types -- + +export type VerifyStep = 1 | 2 | 3; + +// -- Helpers -- + +function formatContextXml(ctx: ContextData): string { + const fields = Object.entries(ctx) + .map(([key, values]) => { + const items = (values as string[]).map((v) => ` ${v}`).join("\n"); + return ` <${key}>\n${items}\n `; + }) + .join("\n"); + return `\n${fields}\n`; +} + +function scopeGuidance(item: QRItem): string { + const s = item.scope; + if (s === "*") { + return "MACRO CHECK -- Use koan_get_plan to read the full plan."; + } + if (s.startsWith("milestone:")) { + const milestoneId = s.slice("milestone:".length); + return `MILESTONE CHECK -- Use koan_get_milestone(id='${milestoneId}') to read the milestone.`; + } + if (s.startsWith("code_intent:")) { + const intentId = s.slice("code_intent:".length); + return `CODE INTENT CHECK -- Use koan_get_intent(id='${intentId}') to read the intent.`; + } + if (s.startsWith("decision:")) { + const decisionId = s.slice("decision:".length); + return `DECISION CHECK -- Use koan_get_decision(id='${decisionId}') to read the decision.`; + } + return "SCOPED CHECK -- Read the relevant section using plan getter tools."; +} + +// -- Exports -- + +export async function loadQRVerifySystemPrompt(): Promise { + const promptPath = path.join(os.homedir(), ".claude/agents/quality-reviewer.md"); + try { + const content = await fs.readFile(promptPath, "utf8"); + return content.replace(/^---\n[\s\S]*?\n---\n/, ""); + } catch { + throw new Error(`Quality-reviewer prompt not found at ${promptPath}`); + } +} + +export function buildVerifySystemPrompt(basePrompt: string): string { + return [ + basePrompt, + "", + "---", + "", + "WORKFLOW: 3-STEP QR VERIFICATION (plan-design)", + "", + "You will verify exactly 1 QR item against the plan.", + "Step 1 instructions are in the user message below.", + "Complete the work described, then call koan_complete_step.", + "Put your findings in the `thoughts` parameter of koan_complete_step.", + "", + "CRITICAL: Do NOT record a verdict until step 3 (CONFIRM).", + "Analyze thoroughly in step 2 before committing.", + ].join("\n"); +} + +export function buildContextStep(item: QRItem, contextData: ContextData): StepGuidance { + return { + title: "Step 1: CONTEXT", + instructions: [ + "PHASE: plan-design", + "ITEM TO VERIFY:", + "", + "", + ` ${item.id}`, + ` ${item.scope}`, + ` ${item.check}`, + ` ${item.severity}`, + "", + "", + "PLANNING CONTEXT (reference for semantic validation):", + formatContextXml(contextData), + "", + "UNDERSTAND the check you need to perform.", + "Note the scope: '*' means plan-wide check, 'milestone:X' means specific milestone.", + "Severity indicates blocking behavior: MUST blocks all iterations.", + ], + }; +} + +export function buildAnalyzeStep(item: QRItem): StepGuidance { + return { + title: "Step 2: ANALYZE", + instructions: [ + scopeGuidance(item), + "", + "TASK:", + "1. Read relevant files/sections based on scope", + "2. Apply the verification check", + "3. Form preliminary conclusion: PASS or FAIL?", + "4. If FAIL, note specific evidence", + "", + "DO NOT update QR state yet. Proceed to CONFIRM step.", + ], + }; +} + +export function buildConfirmStep(item: QRItem): StepGuidance { + return { + title: "Step 3: CONFIRM", + instructions: [ + `CONFIRMING: ${item.id}`, + `SEVERITY: ${item.severity}`, + "", + "CONFIDENCE CHECK:", + "- Are you confident in your conclusion?", + "- Did you verify against actual plan content?", + "- Is your evidence specific and verifiable?", + "", + "RECORD RESULT:", + "", + "If PASS:", + ` koan_qr_set_item(phase='plan-design', id='${item.id}', status='PASS')`, + "", + "If FAIL:", + ` koan_qr_set_item(phase='plan-design', id='${item.id}', status='FAIL',`, + " finding='')", + "", + "RULES:", + "- FAIL requires finding (explains what failed)", + "- PASS forbids finding (finding field must not be set)", + "", + "Execute ONE of the above tool calls, then call koan_complete_step.", + ], + invokeAfter: [ + "WHEN DONE: Call koan_complete_step after recording your verdict.", + "Do NOT call this tool until you have called koan_qr_set_item.", + ].join("\n"), + }; +} diff --git a/src/planner/session.ts b/src/planner/session.ts index ef08dfa..1567983 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -1,5 +1,8 @@ +// Parent session: orchestrates the koan workflow (context capture -> architect +// -> QR decompose -> QR verify pool). Polls subagent state.json for progress. +// Widget displays persistent progress; destroyed on completion. + import { promises as fs } from "node:fs"; -import * as os from "node:os"; import * as path from "node:path"; import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent"; @@ -7,10 +10,16 @@ import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@m import { ContextCapturePhase } from "./phases/context-capture/phase.js"; import { createInitialState, initializePlanState, type WorkflowState } from "./state.js"; import { createPlanInfo } from "../utils/plan.js"; -import { spawnArchitect } from "./subagent.js"; -import { createLogger } from "../utils/logger.js"; -import { createSubagentDir, readSubagentState } from "../utils/progress.js"; +import { spawnArchitect, spawnQRDecomposer, spawnReviewer } from "./subagent.js"; +import { createLogger, setLogDir, type Logger } from "../utils/logger.js"; +import { createSubagentDir } from "../utils/progress.js"; +import { readProjection } from "./lib/audit.js"; import type { WorkflowDispatch, PlanRef } from "./lib/dispatch.js"; +import { pool } from "./lib/pool.js"; +import type { QRFile } from "./qr/types.js"; +import { WidgetController } from "./ui/widget.js"; + +// -- Types -- interface Session { plan(args: string, ctx: ExtensionCommandContext): Promise; @@ -18,9 +27,17 @@ interface Session { status(ctx: ExtensionCommandContext): Promise; } +interface QRBlockResult { + summary: string; + passed: boolean; +} + +// -- Session -- + export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, planRef: PlanRef): Session { const state: WorkflowState = createInitialState(); const log = createLogger("Session"); + let widget: WidgetController | null = null; // Completion callback for context-capture phase. Runs inside the // koan_store_context tool call -- the tool blocks until the architect @@ -31,60 +48,93 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan return "Context captured but no plan state available."; } - const planDir = state.plan.directory; - const planJsonPath = path.join(planDir, "plan.json"); - const subagentDir = await createSubagentDir(planDir, "architect"); + let outcome: "PASS" | "FAIL" = "FAIL"; + + try { + const planDir = state.plan.directory; + const planJsonPath = path.join(planDir, "plan.json"); + const subagentDir = await createSubagentDir(planDir, "architect"); + + state.phase = "architect-running"; + widget?.update({ + phaseStatus: { index: 0, status: "completed" }, + activeIndex: 1, + step: "spawning architect...", + activity: "", + }); + log("Spawning architect after context capture", { planDir, subagentDir }); - state.phase = "architect-running"; - ctx.ui.notify("Launching architect subagent for plan-design...", "info"); - log("Spawning architect after context capture", { planDir, subagentDir }); + const extensionPath = path.resolve(import.meta.dirname, "../../extensions/koan.ts"); - const extensionPath = path.resolve(import.meta.dirname, "../../extensions/koan.ts"); + const pollInterval = setInterval(async () => { + const s = await readProjection(subagentDir); + if (s) { + widget?.update({ + step: s.stepName, + activity: s.lastAction ?? "", + }); + } + }, 2000); + + const result = await spawnArchitect({ + planDir, + subagentDir, + cwd: ctx.cwd, + extensionPath, + log, + }); - const pollInterval = setInterval(async () => { - const s = await readSubagentState(subagentDir); - if (s?.current) { - ctx.ui.notify(`Architect: ${s.current}`, "info"); + clearInterval(pollInterval); + + if (result.exitCode !== 0) { + state.phase = "architect-failed"; + const detail = result.stderr.slice(0, 500); + log("Architect subagent failed", { exitCode: result.exitCode, stderr: detail }); + widget?.update({ + phaseStatus: { index: 1, status: "failed" }, + step: "architect failed", + activity: "", + }); + return `Context captured. Architect subagent failed (exit ${result.exitCode}).\n\nStderr:\n${detail}`; } - }, 2000); - - const result = await spawnArchitect({ - planDir, - subagentDir, - cwd: ctx.cwd, - extensionPath, - log, - }); - - clearInterval(pollInterval); - - if (result.exitCode !== 0) { - state.phase = "architect-failed"; - const detail = result.stderr.slice(0, 500); - log("Architect subagent failed", { exitCode: result.exitCode, stderr: detail }); - ctx.ui.notify(`Architect subagent failed (exit ${result.exitCode}).`, "error"); - return `Context captured. Architect subagent failed (exit ${result.exitCode}).\n\nStderr:\n${detail}`; - } - let planExists = false; - try { - await fs.access(planJsonPath); - planExists = true; - } catch { - // plan.json not written - } + let planExists = false; + try { + await fs.access(planJsonPath); + planExists = true; + } catch { + // plan.json not written + } - if (!planExists) { - state.phase = "architect-failed"; - log("Architect completed but plan.json not found", { planJsonPath }); - ctx.ui.notify("Architect completed but plan.json was not written.", "error"); - return "Context captured. Architect completed but plan.json was not written."; - } + if (!planExists) { + state.phase = "architect-failed"; + log("Architect completed but plan.json not found", { planJsonPath }); + widget?.update({ + phaseStatus: { index: 1, status: "failed" }, + step: "no plan produced", + activity: "", + }); + return "Context captured. Architect completed but produced no plan."; + } + + state.phase = "plan-design-complete"; + log("Architect plan-design complete", { planDir }); + widget?.update({ + phaseStatus: { index: 1, status: "completed" }, + step: "starting QR block...", + activity: "", + }); - state.phase = "plan-design-complete"; - log("Architect plan-design complete", { planDir }); - ctx.ui.notify("Plan-design phase complete.", "info"); - return `Context captured. Plan written to ${planDir}/plan.json.`; + const qr = await runQRBlock(planDir, ctx.cwd, extensionPath, state, log, widget); + if (qr.passed) outcome = "PASS"; + return `Context captured. Plan design complete.\n\n${qr.summary}`; + } finally { + if (widget) { + widget.destroy(); + widget = null; + } + ctx.ui.notify(outcome, outcome === "PASS" ? "info" : "error"); + } }; const contextPhase = new ContextCapturePhase(pi, state, dispatch, createLogger("Context"), onContextComplete); @@ -107,6 +157,7 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan const planInfo = await createPlanInfo(description, ctx.cwd); initializePlanState(state, planInfo, description); planRef.dir = planInfo.directory; + setLogDir(planInfo.directory); log("Plan command invoked", { cwd: ctx.cwd, @@ -115,6 +166,16 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan planDirectory: planInfo.directory, }); + // Destroy stale widget if re-entered + if (widget) { + widget.destroy(); + widget = null; + } + + if (ctx.hasUI) { + widget = new WidgetController(ctx.ui, planInfo.id); + } + await contextPhase.begin(description, planInfo, ctx); }, @@ -123,74 +184,117 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan }, async status(ctx) { - const summary = buildStatusSummary(state, ctx.cwd); - ctx.ui.notify(summary, "info"); + ctx.ui.notify(`Phase: ${state.phase}`, "info"); }, }; } -function buildStatusSummary(state: WorkflowState, cwd: string): string { - const lines: string[] = []; - const plan = state.plan; +// -- QR Block -- - if (plan) { - lines.push(`Plan ${plan.id}`); - lines.push(`Directory: ${formatPath(plan.directory, cwd)}`); - } else { - lines.push("No active plan."); - } +const QR_POOL_CONCURRENCY = 6; - switch (state.phase) { - case "idle": - lines.push("Koan planner is idle."); - break; - case "context": { - const attempt = state.context?.attempt ?? 0; - lines.push(`Context capture in progress (attempt ${attempt}).`); - if (state.context?.contextFilePath) { - lines.push(`Target: ${formatPath(state.context.contextFilePath, cwd)}`); - } - break; +async function runQRBlock( + planDir: string, + cwd: string, + extensionPath: string, + state: WorkflowState, + log: Logger, + widget: WidgetController | null, +): Promise { + // 1. Spawn decomposer subagent + state.phase = "qr-decompose-running"; + widget?.update({ step: "qr-decompose: starting...", activity: "" }); + const decomposeDir = await createSubagentDir(planDir, "qr-decomposer"); + + const decomposePoll = setInterval(async () => { + const s = await readProjection(decomposeDir); + if (s) { + widget?.update({ + step: `qr-decompose: ${s.stepName}`, + activity: s.lastAction ?? "", + }); } - case "context-complete": - lines.push("Context captured successfully."); - if (state.context?.contextFilePath) { - lines.push(`Stored at: ${formatPath(state.context.contextFilePath, cwd)}`); - } - break; - case "context-failed": - lines.push("Context capture failed. Re-run /koan plan to try again."); - break; - case "architect-running": - lines.push("Architect subagent running (plan-design phase)..."); - break; - case "architect-failed": - lines.push("Architect subagent failed. Check plan directory for details."); - break; - case "plan-design-complete": - lines.push("Plan-design phase complete."); - if (plan) { - lines.push(`Plan: ${formatPath(path.join(plan.directory, "plan.json"), cwd)}`); - } - break; - default: - lines.push("Unknown planner state."); - break; + }, 2000); + + const decompose = await spawnQRDecomposer({ + planDir, + subagentDir: decomposeDir, + cwd, + extensionPath, + log, + }); + + clearInterval(decomposePoll); + + if (decompose.exitCode !== 0) { + state.phase = "qr-decompose-failed"; + const detail = decompose.stderr.slice(0, 500); + log("QR decomposer failed", { exitCode: decompose.exitCode, stderr: detail }); + widget?.update({ step: "qr-decompose: failed", activity: "" }); + return { summary: `QR decompose failed (exit ${decompose.exitCode}).\n\nStderr:\n${detail}`, passed: false }; } - return lines.join("\n"); -} + // 2. Read QR items + const qrPath = path.join(planDir, "qr-plan-design.json"); + let qr: QRFile; + try { + const raw = await fs.readFile(qrPath, "utf8"); + qr = JSON.parse(raw) as QRFile; + } catch (error) { + state.phase = "qr-decompose-failed"; + const message = error instanceof Error ? error.message : String(error); + log("Failed to read qr-plan-design.json after decompose", { error: message }); + return { summary: "QR decompose completed but produced no verifiable items.", passed: false }; + } -function formatPath(target: string, cwd: string): string { - const home = os.homedir(); - if (target.startsWith(home)) { - return `~${target.slice(home.length)}`; + if (qr.items.length === 0) { + state.phase = "qr-decompose-failed"; + log("QR decompose produced no items"); + return { summary: "QR decompose completed but produced no items.", passed: false }; } - const relative = path.relative(cwd, target); - if (!relative.startsWith("..")) { - return relative; + const itemIds = qr.items.map((i) => i.id); + log("QR decompose complete", { itemCount: itemIds.length }); + widget?.update({ step: `qr-verify: 0/${itemIds.length}`, activity: "" }); + + // 3. Spawn reviewer pool + state.phase = "qr-verify-running"; + + const result = await pool( + itemIds, + QR_POOL_CONCURRENCY, + async (itemId) => { + const reviewerDir = await createSubagentDir(planDir, `qr-reviewer-${itemId}`); + return spawnReviewer({ + planDir, + subagentDir: reviewerDir, + cwd, + extensionPath, + itemId, + log, + }); + }, + (done, total) => widget?.update({ step: `qr-verify: ${done}/${total}` }), + ); + + // 4. Read final results + state.phase = "qr-complete"; + let finalQR: QRFile; + try { + const raw = await fs.readFile(qrPath, "utf8"); + finalQR = JSON.parse(raw) as QRFile; + } catch { + finalQR = qr; } - return target; + const pass = finalQR.items.filter((i) => i.status === "PASS").length; + const fail = finalQR.items.filter((i) => i.status === "FAIL").length; + const todo = finalQR.items.filter((i) => i.status === "TODO").length; + const summary = `QR complete: ${pass} PASS, ${fail} FAIL, ${todo} TODO (${result.failed.length} reviewers failed).`; + + log("QR block complete", { pass, fail, todo, failedReviewers: result.failed }); + + const passed = fail === 0 && result.failed.length === 0; + widget?.update({ step: summary, activity: "" }); + return { summary, passed }; } diff --git a/src/planner/state.ts b/src/planner/state.ts index 5d47d63..3583d4d 100644 --- a/src/planner/state.ts +++ b/src/planner/state.ts @@ -7,7 +7,12 @@ export type WorkflowPhase = | "context-failed" | "architect-running" | "architect-failed" - | "plan-design-complete"; + | "plan-design-complete" + | "qr-decompose-running" + | "qr-decompose-failed" + | "qr-verify-running" + | "qr-verify-failed" + | "qr-complete"; export interface PlanInfo { id: string; @@ -54,7 +59,12 @@ export function resetContextState(state: WorkflowState): void { state.phase === "context-failed" || state.phase === "context-complete" || state.phase === "architect-failed" || - state.phase === "plan-design-complete" + state.phase === "plan-design-complete" || + state.phase === "qr-decompose-running" || + state.phase === "qr-decompose-failed" || + state.phase === "qr-verify-running" || + state.phase === "qr-verify-failed" || + state.phase === "qr-complete" ) { state.phase = "idle"; } diff --git a/src/planner/subagent.ts b/src/planner/subagent.ts index 997c8f8..19c5647 100644 --- a/src/planner/subagent.ts +++ b/src/planner/subagent.ts @@ -15,6 +15,24 @@ export interface SpawnArchitectOptions { subagentDir: string; cwd: string; extensionPath: string; + initialPrompt?: string; + log?: Logger; +} + +export interface SpawnQRDecomposerOptions { + planDir: string; + subagentDir: string; + cwd: string; + extensionPath: string; + log?: Logger; +} + +export interface SpawnReviewerOptions { + planDir: string; + subagentDir: string; + cwd: string; + extensionPath: string; + itemId: string; log?: Logger; } @@ -28,7 +46,7 @@ export function spawnArchitect(opts: SpawnArchitectOptions): Promise { + const args = [ + "-p", + "-e", opts.extensionPath, + "--koan-role", role, + "--koan-phase", phase, + "--koan-plan-dir", opts.planDir, + "--koan-subagent-dir", opts.subagentDir, + ...(opts.extraFlags ?? []), + prompt, + ]; + + log(`Spawning ${role} subagent`, { planDir: opts.planDir, subagentDir: opts.subagentDir }); + + return new Promise((resolve) => { + const stdoutLog = createWriteStream(path.join(opts.subagentDir, "stdout.log"), { flags: "w" }); + const stderrLog = createWriteStream(path.join(opts.subagentDir, "stderr.log"), { flags: "w" }); + + const proc = spawn("pi", args, { + cwd: opts.cwd, + shell: false, + stdio: ["ignore", "pipe", "pipe"], + }); + + let stderr = ""; + + proc.stdout.on("data", (data: Buffer) => { + stdoutLog.write(data); + }); + + proc.stderr.on("data", (data: Buffer) => { + stderr += data.toString(); + stderrLog.write(data); + }); + + proc.on("close", (code) => { + stdoutLog.end(); + stderrLog.end(); + const exitCode = code ?? 1; + log(`${role} subagent exited`, { exitCode }); + resolve({ exitCode, stderr, subagentDir: opts.subagentDir }); + }); + + proc.on("error", (error) => { + stdoutLog.end(); + stderrLog.end(); + log(`${role} subagent spawn error`, { error: error.message }); + resolve({ exitCode: 1, stderr: error.message, subagentDir: opts.subagentDir }); + }); + }); +} + +export function spawnQRDecomposer(opts: SpawnQRDecomposerOptions): Promise { + const log = opts.log ?? createLogger("Subagent"); + return spawnSubagent("qr-decomposer", "qr-plan-design", "Begin the QR decompose phase.", opts, log); +} + +export function spawnReviewer(opts: SpawnReviewerOptions): Promise { + const log = opts.log ?? createLogger("Subagent"); + return spawnSubagent( + "reviewer", + "qr-plan-design", + "Verify the assigned QR item.", + { ...opts, extraFlags: ["--koan-qr-item", opts.itemId] }, + log, + ); +} diff --git a/src/planner/ui/widget.ts b/src/planner/ui/widget.ts new file mode 100644 index 0000000..c5a4337 --- /dev/null +++ b/src/planner/ui/widget.ts @@ -0,0 +1,203 @@ +// Persistent TUI widget for koan workflow progress. +// Full-width background canvas (toolPendingBg) via component factory. +// Hash-based change detection + 1s unref'd timer for elapsed updates. +// Created by session.plan(), destroyed in onContextComplete finally block. +// +// Uses setWidget(key, factory) to get render(width) for full-width bg. +// Content stays at a fixed CONTENT width; background fills terminal edge. + +import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; +import type { Theme, ThemeColor } from "@mariozechner/pi-coding-agent"; +import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui"; + +// -- Types -- + +export type PhaseStatus = "pending" | "running" | "completed" | "failed"; + +interface PhaseEntry { + key: string; + label: string; + status: PhaseStatus; +} + +interface WidgetState { + planId: string; + phases: PhaseEntry[]; + activeIndex: number; // 0-based; -1 when done + step: string; + activity: string; + startedAt: number; +} + +export interface WidgetUpdate { + activeIndex?: number; + step?: string; + activity?: string; + phaseStatus?: { index: number; status: PhaseStatus }; +} + +// -- Constants -- + +const WIDGET_KEY = "koan"; +const PAD = 2; // horizontal padding each side + +const PHASES: ReadonlyArray<{ key: string; label: string }> = [ + { key: "ctx", label: "Gathering context" }, + { key: "design", label: "Designing plan" }, + { key: "code", label: "Planning code" }, + { key: "docs", label: "Planning docs" }, + { key: "exec-c", label: "Executing code" }, + { key: "exec-d", label: "Executing docs" }, +]; + +const STATUS_ICON: Record = { + pending: "[ ]", + running: "[>>]", + completed: "[OK]", + failed: "[!!]", +}; + +const ICON_COLOR: Record = { + pending: "muted", + running: "warning", + completed: "success", + failed: "error", +}; + +// -- Canvas primitive -- +// Content width adapts to terminal; background fills edge to edge. + +function contentWidth(termWidth: number): number { + return Math.max(40, termWidth - PAD * 2); +} + +function canvasLine(content: string, termWidth: number, theme: Theme): string { + const cw = contentWidth(termWidth); + const inner = truncateToWidth(content, cw, "...", true); + const line = " ".repeat(PAD) + inner + " ".repeat(PAD); + return theme.bg("toolPendingBg", line); +} + +// -- Helpers -- + +function formatElapsed(ms: number): string { + const totalSec = Math.floor(ms / 1000); + const m = Math.floor(totalSec / 60); + const s = totalSec % 60; + return `${m}m ${String(s).padStart(2, "0")}s`; +} + +function rightAlign(left: string, right: string, width: number): string { + const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(right)); + return `${left}${" ".repeat(gap)}${right}`; +} + +// Pure render: (state, theme, termWidth) -> 7 lines. No side effects. +function render(state: WidgetState, theme: Theme, termWidth: number): string[] { + const c = (s: string) => canvasLine(s, termWidth, theme); + const cw = contentWidth(termWidth); + + // Header: koan [N/6] label ... elapsed + const idx = state.activeIndex; + const label = idx >= 0 ? state.phases[idx].label : "done"; + const num = idx >= 0 ? idx + 1 : 6; + const left = `${theme.bold(theme.fg("accent", "koan"))} [${num}/6] ${label}`; + const elapsed = theme.fg("dim", formatElapsed(Date.now() - state.startedAt)); + const header = rightAlign(left, elapsed, cw); + + // Plan ID + const planId = theme.fg("dim", state.planId); + + // Phase bar + const phaseBar = state.phases + .map((p) => `${theme.fg(ICON_COLOR[p.status], STATUS_ICON[p.status])} ${p.key}`) + .join(" "); + + // Step + activity + const step = state.step ? theme.fg("dim", state.step) : ""; + const act = state.activity ? theme.fg("muted", ` > ${state.activity}`) : ""; + const detail = truncateToWidth(step + act, cw, "..."); + + return [ + c(""), // top padding + c(header), + c(planId), + c(""), // separator + c(phaseBar), + c(detail), + c(""), // bottom padding + ]; +} + +// -- WidgetController -- + +export class WidgetController { + private state: WidgetState; + private lastHash = ""; + private timer: ReturnType; + private ui: ExtensionUIContext; + + constructor(ui: ExtensionUIContext, planId: string) { + this.ui = ui; + this.state = { + planId, + phases: PHASES.map((p) => ({ key: p.key, label: p.label, status: "pending" as PhaseStatus })), + activeIndex: 0, + step: "", + activity: "", + startedAt: Date.now(), + }; + this.state.phases[0].status = "running"; + + this.timer = setInterval(() => this.doRender(), 1000); + this.timer.unref(); + + this.doRender(); + } + + update(patch: WidgetUpdate): void { + if (patch.phaseStatus !== undefined) { + const { index, status } = patch.phaseStatus; + if (index >= 0 && index < this.state.phases.length) { + this.state.phases[index].status = status; + } + } + if (patch.activeIndex !== undefined) { + this.state.activeIndex = patch.activeIndex; + const ai = patch.activeIndex; + if (ai >= 0 && ai < this.state.phases.length && this.state.phases[ai].status === "pending") { + this.state.phases[ai].status = "running"; + } + } + if (patch.step !== undefined) { + this.state.step = patch.step; + } + if (patch.activity !== undefined) { + this.state.activity = patch.activity; + } + this.doRender(); + } + + destroy(): void { + clearInterval(this.timer); + this.ui.setWidget(WIDGET_KEY, undefined); + } + + private doRender(): void { + // Capture state snapshot for the factory closure + const state = { ...this.state, phases: this.state.phases.map((p) => ({ ...p })) }; + const theme = this.ui.theme; + + // Hash check: skip setWidget if content unchanged (ignoring width) + const hashLines = render(state, theme, 0); + const hash = hashLines.join("\n"); + if (hash === this.lastHash) return; + this.lastHash = hash; + + // Component factory: Pi calls render(width) with actual terminal width + this.ui.setWidget(WIDGET_KEY, (_tui, th) => ({ + render: (width: number) => render(state, th, width), + invalidate: () => {}, + })); + } +} diff --git a/src/utils/logger.ts b/src/utils/logger.ts index 67f4c2e..c8ced16 100644 --- a/src/utils/logger.ts +++ b/src/utils/logger.ts @@ -1,14 +1,36 @@ +// Debug logger for koan internals. Writes to a log file when a plan +// directory is available; silent otherwise. The Pi TUI captures both +// stdout and stderr, so neither can be used for debug output. + +import { appendFileSync, mkdirSync } from "node:fs"; +import * as path from "node:path"; + const prefix = "[koan]"; export type Logger = | undefined>(message: string, details?: T) => void; +let logPath: string | null = null; + +export function setLogDir(planDir: string): void { + logPath = path.join(planDir, "koan.log"); + try { + mkdirSync(path.dirname(logPath), { recursive: true }); + } catch { + // best effort + } +} + export function createLogger(scope: string): Logger { const label = `${prefix} ${scope}`; return (message, details) => { - if (details && Object.keys(details).length > 0) { - console.log(`${label}: ${message}`, details); - } else { - console.log(`${label}: ${message}`); + if (!logPath) return; + const suffix = details && Object.keys(details).length > 0 + ? ` ${JSON.stringify(details)}` + : ""; + try { + appendFileSync(logPath, `${new Date().toISOString()} ${label}: ${message}${suffix}\n`); + } catch { + // best effort -- plan dir may not exist yet } }; } diff --git a/src/utils/progress.ts b/src/utils/progress.ts index 566bda8..2940ecc 100644 --- a/src/utils/progress.ts +++ b/src/utils/progress.ts @@ -1,71 +1,14 @@ +// Directory infrastructure for subagent working directories. +// Audit state (state.json, events.jsonl) is managed by EventLog in lib/audit.ts. +// This module is retained for createSubagentDir, used by session.ts. + import { promises as fs } from "node:fs"; import * as crypto from "node:crypto"; import * as path from "node:path"; -export interface TrailEntry { - at: string; - msg: string; -} - -export interface SubagentState { - role: string; - phase: string; - status: "running" | "completed" | "failed"; - current: string; - updated_at: string; - trail: TrailEntry[]; -} - export async function createSubagentDir(planDir: string, role: string): Promise { const hex = crypto.randomBytes(2).toString("hex"); const dir = path.join(planDir, "subagents", `${role}-${hex}`); await fs.mkdir(dir, { recursive: true }); return dir; } - -export class ProgressReporter { - private readonly stateFile: string; - private readonly state: SubagentState; - - constructor(dir: string, role: string, phase: string) { - this.stateFile = path.join(dir, "state.json"); - this.state = { - role, - phase, - status: "running", - current: "", - updated_at: new Date().toISOString(), - trail: [], - }; - } - - async update(msg: string): Promise { - const now = new Date().toISOString(); - this.state.current = msg; - this.state.updated_at = now; - this.state.trail.push({ at: now, msg }); - await this.flush(); - } - - async complete(status: "completed" | "failed"): Promise { - const now = new Date().toISOString(); - this.state.status = status; - this.state.current = status; - this.state.updated_at = now; - this.state.trail.push({ at: now, msg: status }); - await this.flush(); - } - - private async flush(): Promise { - await fs.writeFile(this.stateFile, JSON.stringify(this.state, null, 2) + "\n"); - } -} - -export async function readSubagentState(dir: string): Promise { - try { - const raw = await fs.readFile(path.join(dir, "state.json"), "utf8"); - return JSON.parse(raw) as SubagentState; - } catch { - return null; - } -} From 44f5b648d500747b4fa487867938e7a19e334a10 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 24 Feb 2026 21:49:05 +0700 Subject: [PATCH 010/412] Add QR fix loop for plan-design phase When plan-design QR verification fails, the session now spawns a fix-mode architect (3-step targeted repair) and re-runs full QR, up to 5 iterations. Progressive severity de-escalation narrows blocking set per iteration. --- extensions/koan.ts | 6 + src/planner/phases/dispatch.ts | 46 +++++ src/planner/phases/plan-design/fix-phase.ts | 184 ++++++++++++++++++ src/planner/phases/plan-design/fix-prompts.ts | 137 +++++++++++++ src/planner/phases/plan-design/phase.ts | 28 +-- src/planner/plan/validate.ts | 37 ++++ src/planner/qr/severity.ts | 41 ++++ src/planner/session.ts | 105 +++++++++- src/planner/subagent.ts | 95 ++++----- 9 files changed, 597 insertions(+), 82 deletions(-) create mode 100644 src/planner/phases/plan-design/fix-phase.ts create mode 100644 src/planner/phases/plan-design/fix-prompts.ts create mode 100644 src/planner/qr/severity.ts diff --git a/extensions/koan.ts b/extensions/koan.ts index a58d81c..2dfd08c 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -44,6 +44,12 @@ export default function koan(pi: ExtensionAPI): void { default: "", }); + pi.registerFlag("koan-fix", { + description: "QR phase to fix (e.g. plan-design)", + type: "string", + default: "", + }); + // Pi snapshots tools during _buildRuntime() at init. All 44 tools // register here unconditionally. Phases restrict access via tool_call // blocking at runtime. diff --git a/src/planner/phases/dispatch.ts b/src/planner/phases/dispatch.ts index c8a55f8..9bfba42 100644 --- a/src/planner/phases/dispatch.ts +++ b/src/planner/phases/dispatch.ts @@ -3,20 +3,26 @@ // (getFlag returns undefined before _buildRuntime), so detection is // deferred to before_agent_start. +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { PlanDesignPhase } from "./plan-design/phase.js"; +import { PlanDesignFixPhase } from "./plan-design/fix-phase.js"; import { QRDecomposePhase } from "./qr-decompose/phase.js"; import { QRVerifyPhase } from "./qr-verify/phase.js"; import { createLogger, type Logger } from "../../utils/logger.js"; import type { WorkflowDispatch, PlanRef } from "../lib/dispatch.js"; import type { EventLog } from "../lib/audit.js"; +import type { QRFile } from "../qr/types.js"; export interface SubagentConfig { role: string; phase: string; planDir: string; subagentDir: string; + fix: string | null; // QR phase being fixed, null when initial mode } // Detects subagent mode by checking flags set via CLI (pi -p --koan-role @@ -33,11 +39,14 @@ export function detectSubagentMode(pi: ExtensionAPI): SubagentConfig | null { const planDir = pi.getFlag("koan-plan-dir"); const subagentDir = pi.getFlag("koan-subagent-dir"); + const fix = pi.getFlag("koan-fix"); + return { role: role.trim(), phase: typeof phase === "string" ? phase.trim() : "", planDir: typeof planDir === "string" ? planDir.trim() : "", subagentDir: typeof subagentDir === "string" ? subagentDir.trim() : "", + fix: typeof fix === "string" && fix.trim().length > 0 ? fix.trim() : null, }; } @@ -51,6 +60,43 @@ export async function dispatchPhase( ): Promise { const logger = log ?? createLogger("Dispatch"); + if (config.role === "architect" && config.fix === "plan-design") { + // Dispatch reads the QR file here, not in session.ts. + // The fix architect runs as a separate process with only the plan + // directory path -- it cannot receive in-memory QR data from the + // parent session. Reading from disk at dispatch boundary is the + // only clean handoff point. + const qrPath = path.join(config.planDir, "qr-plan-design.json"); + let qrFile: QRFile; + try { + const raw = await fs.readFile(qrPath, "utf8"); + qrFile = JSON.parse(raw) as QRFile; + } catch (error) { + const msg = error instanceof Error ? error.message : String(error); + logger("Fix dispatch: failed to read QR file", { error: msg }); + return; + } + const failures = qrFile.items.filter((i) => i.status === "FAIL"); + if (failures.length === 0) { + logger("Fix dispatch: no FAIL items in QR file, skipping fix phase"); + return; + } + logger("Dispatching to plan-design fix workflow", { + planDir: config.planDir, + failureCount: failures.length, + }); + const phase = new PlanDesignFixPhase( + pi, + { planDir: config.planDir, failures }, + dispatch, + planRef, + logger, + eventLog, + ); + await phase.begin(); + return; + } + if (config.role === "architect" && config.phase === "plan-design") { logger("Dispatching to plan-design workflow", { planDir: config.planDir }); const phase = new PlanDesignPhase( diff --git a/src/planner/phases/plan-design/fix-phase.ts b/src/planner/phases/plan-design/fix-phase.ts new file mode 100644 index 0000000..4df6a24 --- /dev/null +++ b/src/planner/phases/plan-design/fix-phase.ts @@ -0,0 +1,184 @@ +// Plan-design fix phase -- 3-step targeted repair for QR failures. +// +// Separate class from PlanDesignPhase because the workflows diverge: +// initial = 6 steps of exploration then writing (mutations at step 6); +// fix = 3 steps of reading failures then applying targeted fixes +// (mutations at step 2). Conditional branching at every method +// boundary produces worse code than two focused classes. +// +// The fix architect receives QR failures as XML in step 1. It reads +// the current plan state via getter tools, applies minimal mutations +// to address the specific findings, then validates the result. The +// session orchestrator decides whether to re-run QR -- the fix phase +// does not know about iterations or severity escalation. + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { loadAndValidatePlan } from "../../plan/validate.js"; +import { + loadPlanDesignSystemPrompt, + buildPlanDesignSystemPrompt, +} from "./prompts.js"; +import { + FIX_STEP_NAMES, + buildFixSystemPrompt, + fixStepGuidance, + formatFailuresXml, + type FixStep, +} from "./fix-prompts.js"; +import { formatStep } from "../../lib/step.js"; +import type { QRItem } from "../../qr/types.js"; +import { createLogger, type Logger } from "../../../utils/logger.js"; +import { EventLog } from "../../lib/audit.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; +import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; + +interface FixPhaseState { + active: boolean; + step: FixStep; + step1Prompt: string | null; + systemPrompt: string | null; +} + +const TOTAL_STEPS = 3; + +export class PlanDesignFixPhase { + private readonly pi: ExtensionAPI; + private readonly planDir: string; + private readonly failures: QRItem[]; + private readonly log: Logger; + private readonly state: FixPhaseState; + private readonly eventLog: EventLog | undefined; + private readonly dispatch: WorkflowDispatch; + private readonly planRef: PlanRef; + + constructor( + pi: ExtensionAPI, + config: { planDir: string; failures: QRItem[] }, + dispatch: WorkflowDispatch, + planRef: PlanRef, + log?: Logger, + eventLog?: EventLog, + ) { + this.pi = pi; + this.planDir = config.planDir; + this.failures = config.failures; + this.dispatch = dispatch; + this.planRef = planRef; + this.log = log ?? createLogger("PlanDesignFix"); + this.eventLog = eventLog; + + this.state = { + active: false, + step: 1, + step1Prompt: null, + systemPrompt: null, + }; + + this.registerHandlers(); + } + + async begin(): Promise { + let basePrompt: string; + try { + basePrompt = await loadPlanDesignSystemPrompt(); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Fix phase aborted: cannot load system prompt", { error: message }); + return; + } + + const failuresXml = formatFailuresXml(this.failures); + this.state.systemPrompt = buildFixSystemPrompt( + buildPlanDesignSystemPrompt(basePrompt), + this.failures.length, + ); + this.state.step1Prompt = formatStep(fixStepGuidance(1, failuresXml)); + this.state.active = true; + this.state.step = 1; + + hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); + + this.log("Starting plan-design fix workflow", { + step: 1, + failureCount: this.failures.length, + }); + await this.eventLog?.emitPhaseStart(TOTAL_STEPS); + await this.eventLog?.emitStepTransition(1, FIX_STEP_NAMES[1], TOTAL_STEPS); + } + + private registerHandlers(): void { + this.pi.on("before_agent_start", () => { + if (!this.state.active || !this.state.systemPrompt) return undefined; + return { systemPrompt: this.state.systemPrompt }; + }); + + // Step 1 prompt injection. Same pattern as PlanDesignPhase: the CLI + // message is a process trigger; the context event replaces it with + // step 1 instructions before the initial LLM call. + this.pi.on("context", (event) => { + if (!this.state.active) return undefined; + if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; + + const messages = event.messages.map((m) => { + if (m.role === "user") { + return { ...m, content: this.state.step1Prompt! }; + } + return m; + }); + return { messages }; + }); + + this.pi.on("tool_call", (event) => { + if (!this.state.active) return undefined; + + const perm = checkPermission("plan-design", event.toolName); + if (!perm.allowed) { + return { block: true, reason: perm.reason }; + } + + // Step gate: mutation tools are blocked before step 2. Blocklist + // (not whitelist) so read tools and future pi-native tools pass + // through after checkPermission approves them. + const step = this.state.step; + if (step < 2 && PLAN_MUTATION_TOOLS.has(event.toolName)) { + return { + block: true, + reason: `${event.toolName} available from step 2 (current: ${step})`, + }; + } + + return undefined; + }); + } + + private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { + const prev = this.state.step; + + if (prev === 3) { + const result = await this.handleFinalize(); + if (!result.ok) { + await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); + return { ok: false, error: result.errors?.join("; ") }; + } + this.state.active = false; + unhookDispatch(this.dispatch, "onCompleteStep"); + await this.eventLog?.emitPhaseEnd("completed"); + this.log("Fix phase complete, plan validation passed"); + return { ok: true, prompt: "Fix phase validation passed. Workflow complete." }; + } + + this.state.step = (prev + 1) as FixStep; + const nextName = FIX_STEP_NAMES[this.state.step]; + const prompt = formatStep(fixStepGuidance(this.state.step)); + + this.log("Fix step complete, advancing", { from: prev, to: this.state.step, name: nextName }); + await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); + + return { ok: true, prompt }; + } + + private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { + return loadAndValidatePlan(this.planDir, this.log); + } +} diff --git a/src/planner/phases/plan-design/fix-prompts.ts b/src/planner/phases/plan-design/fix-prompts.ts new file mode 100644 index 0000000..003bf8d --- /dev/null +++ b/src/planner/phases/plan-design/fix-prompts.ts @@ -0,0 +1,137 @@ +// Fix-phase step guidance for plan-design targeted repair (3 steps). +// +// Parallels prompts.ts structure. Step 1 explicitly prohibits mutations: +// without this constraint the LLM tends to apply the first fix it identifies +// without reading all failures, producing cascading corrections that address +// symptoms rather than root causes. + +import type { QRItem } from "../../qr/types.js"; +import type { StepGuidance } from "../../lib/step.js"; + +export type FixStep = 1 | 2 | 3; + +export const FIX_STEP_NAMES: Record = { + 1: "Understand QR Failures", + 2: "Apply Targeted Fixes", + 3: "Review & Finalize", +}; + +// Serializes FAIL items as an XML block injected into the step 1 prompt. +// XML structure mirrors how pi-native tools present structured data. +export function formatFailuresXml(failures: ReadonlyArray): string { + const items = failures.map((f) => [ + ` `, + ` ${f.check}`, + f.finding ? ` ${f.finding}` : ` `, + ` `, + ].join("\n")).join("\n"); + + return [ + "", + items, + "", + ].join("\n"); +} + +// Appends fix workflow instructions to the base architect system prompt. +export function buildFixSystemPrompt(basePrompt: string, failureCount: number): string { + return [ + basePrompt, + "", + "---", + "", + "WORKFLOW: 3-STEP PLAN-DESIGN FIX", + "", + `You are fixing ${failureCount} QR failure(s) in an existing plan.`, + "Step 1 instructions are in the user message below.", + "Complete the work described, then call koan_complete_step.", + "Put your findings in the `thoughts` parameter of koan_complete_step.", + "The tool result contains the next step's instructions.", + "", + "CRITICAL: Fix ONLY the identified failures. Do not restructure the plan", + "beyond what the failures require. Prefer updating existing entities over", + "adding new ones.", + ].join("\n"); +} + +export function fixStepGuidance(step: FixStep, context?: string): StepGuidance { + switch (step) { + case 1: + return { + title: "Step 1: Understand QR Failures", + instructions: [ + "QR FAILURES TO FIX:", + "", + context ?? "", + "", + "Read the failures carefully. For each failing item:", + " - Identify the scope (which milestone, decision, or intent)", + " - Understand what the check requires", + " - Read the finding to understand why it failed", + "", + "Use getter tools to inspect the scoped entities:", + " - koan_get_plan: overview, structure, decisions", + " - koan_get_milestone: milestone details and intents", + " - koan_get_decision: decision rationale", + " - koan_get_intent: intent definition", + "", + "Plan your fixes mentally. Consider:", + " - What minimal change addresses each failure?", + " - Do any fixes overlap or interact?", + " - Could fixing one item cause another to fail?", + "", + "DO NOT write any changes yet. Gather understanding for step 2.", + ], + }; + + case 2: + return { + title: "Step 2: Apply Targeted Fixes", + instructions: [ + "Apply the fixes you planned in step 1.", + "", + "Use plan mutation tools to address each failure:", + " - koan_set_overview / koan_set_constraints / koan_set_invisible_knowledge", + " - koan_set_milestone_* / koan_set_intent / koan_set_decision", + " - koan_add_milestone / koan_add_intent / koan_add_decision (if new entities needed)", + "", + "RULES:", + " - Fix ONLY the FAIL items from step 1", + " - Prefer updating existing entities over adding new ones", + " - Do not restructure the plan beyond what the failures require", + " - Do not change PASS items", + "", + "After applying all fixes, call koan_complete_step.", + ], + }; + + case 3: + return { + title: "Step 3: Review & Finalize", + instructions: [ + "Review the fixes you applied.", + "", + "Call koan_get_plan to read the current plan state.", + "For each original failure, verify:", + " - The fix addresses the check that failed", + " - No regressions introduced in previously passing items", + " - The plan is internally consistent", + "", + "Summarize in the `thoughts` parameter of koan_complete_step:", + " - Which failures were fixed and how", + " - Any concerns or items that may still be at risk", + ], + // Step 3 requires reading the plan before completing -- the review + // is meaningless without it. The custom invokeAfter enforces this + // sequencing explicitly. + invokeAfter: [ + "WHEN DONE: First call koan_get_plan to confirm the final plan state.", + "Then call koan_complete_step with your review summary in the `thoughts` parameter.", + "Do NOT call koan_complete_step before calling koan_get_plan.", + ].join("\n"), + }; + + default: + throw new Error(`unexpected fix step: ${step as never}`); + } +} diff --git a/src/planner/phases/plan-design/phase.ts b/src/planner/phases/plan-design/phase.ts index f2165ef..f581e11 100644 --- a/src/planner/phases/plan-design/phase.ts +++ b/src/planner/phases/plan-design/phase.ts @@ -7,7 +7,7 @@ import * as path from "node:path"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import { validatePlanDesign, validateRefs } from "../../plan/validate.js"; +import { loadAndValidatePlan } from "../../plan/validate.js"; import { loadPlanDesignSystemPrompt, formatContextForStep1, @@ -187,30 +187,6 @@ export class PlanDesignPhase { } private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { - const planPath = path.join(this.planDir, "plan.json"); - let plan; - try { - const raw = await fs.readFile(planPath, "utf8"); - plan = JSON.parse(raw); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to read plan.json for validation", { error: message }); - return { ok: false, errors: [`Failed to read plan.json: ${message}`] }; - } - - const designValidation = validatePlanDesign(plan); - if (!designValidation.ok) { - this.log("Plan design validation failed", { errors: designValidation.errors }); - return { ok: false, errors: designValidation.errors }; - } - - const refValidation = validateRefs(plan); - if (!refValidation.ok) { - this.log("Plan reference validation failed", { errors: refValidation.errors }); - return { ok: false, errors: refValidation.errors }; - } - - this.log("Plan validation passed", { path: planPath }); - return { ok: true }; + return loadAndValidatePlan(this.planDir, this.log); } } diff --git a/src/planner/plan/validate.ts b/src/planner/plan/validate.ts index cc9fe8d..210fd58 100644 --- a/src/planner/plan/validate.ts +++ b/src/planner/plan/validate.ts @@ -1,3 +1,7 @@ +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { Logger } from "../../utils/logger.js"; import type { Plan } from "./types.js"; export interface ValidationResult { @@ -131,3 +135,36 @@ export function validatePlanDocs(p: Plan): ValidationResult { } return { ok: errors.length === 0, errors }; } + +// Reads plan.json from planDir and runs validatePlanDesign + validateRefs. +// Returns { ok: false, errors } on read/parse failure or any validation failure. +export async function loadAndValidatePlan( + planDir: string, + log: Logger, +): Promise<{ ok: boolean; errors?: string[] }> { + const planPath = path.join(planDir, "plan.json"); + let plan; + try { + const raw = await fs.readFile(planPath, "utf8"); + plan = JSON.parse(raw); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + log("Failed to read plan.json for validation", { error: message }); + return { ok: false, errors: [`Failed to read plan.json: ${message}`] }; + } + + const designValidation = validatePlanDesign(plan); + if (!designValidation.ok) { + log("Plan design validation failed", { errors: designValidation.errors }); + return { ok: false, errors: designValidation.errors }; + } + + const refValidation = validateRefs(plan); + if (!refValidation.ok) { + log("Plan reference validation failed", { errors: refValidation.errors }); + return { ok: false, errors: refValidation.errors }; + } + + log("Plan validation passed", { path: planPath }); + return { ok: true }; +} diff --git a/src/planner/qr/severity.ts b/src/planner/qr/severity.ts new file mode 100644 index 0000000..6e40c6f --- /dev/null +++ b/src/planner/qr/severity.ts @@ -0,0 +1,41 @@ +// Severity escalation policy for QR fix iterations. +// +// Progressive de-escalation narrows what blocks as iterations increase. +// COULD items (style, cosmetic) do not block indefinitely: after 2 fix +// attempts, only structural issues (MUST, SHOULD) block; after 3, only +// knowledge-loss risks (MUST) block. +// +// A hard cutoff ("after N attempts, ignore all failures") would let MUST +// failures through. De-escalation by tier preserves the invariant that +// MUST items always block, while preventing COULD style nits from causing +// indefinite retries. + +import type { QRItem, QRSeverity } from "./types.js"; + +export const MAX_FIX_ITERATIONS = 5; + +// Returns the set of severities that block the plan at the given iteration. +// Iterations 1-2: all severities block. Iteration 3: MUST+SHOULD. 4+: MUST only. +export function blockingSeverities(iteration: number): ReadonlySet { + if (iteration <= 2) return new Set(["MUST", "SHOULD", "COULD"]); + if (iteration === 3) return new Set(["MUST", "SHOULD"]); + return new Set(["MUST"]); +} + +// Returns the subset of items that are FAIL and have a blocking severity +// at the given iteration. +export function blockingFailures( + items: ReadonlyArray, + iteration: number, +): QRItem[] { + const blocking = blockingSeverities(iteration); + return items.filter((i) => i.status === "FAIL" && blocking.has(i.severity)); +} + +// Returns true when no blocking failures remain at this iteration. +export function qrPassesAtIteration( + items: ReadonlyArray, + iteration: number, +): boolean { + return blockingFailures(items, iteration).length === 0; +} diff --git a/src/planner/session.ts b/src/planner/session.ts index 1567983..42d8bf8 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -10,13 +10,14 @@ import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@m import { ContextCapturePhase } from "./phases/context-capture/phase.js"; import { createInitialState, initializePlanState, type WorkflowState } from "./state.js"; import { createPlanInfo } from "../utils/plan.js"; -import { spawnArchitect, spawnQRDecomposer, spawnReviewer } from "./subagent.js"; +import { spawnArchitect, spawnArchitectFix, spawnQRDecomposer, spawnReviewer } from "./subagent.js"; import { createLogger, setLogDir, type Logger } from "../utils/logger.js"; import { createSubagentDir } from "../utils/progress.js"; import { readProjection } from "./lib/audit.js"; import type { WorkflowDispatch, PlanRef } from "./lib/dispatch.js"; import { pool } from "./lib/pool.js"; import type { QRFile } from "./qr/types.js"; +import { MAX_FIX_ITERATIONS, qrPassesAtIteration } from "./qr/severity.js"; import { WidgetController } from "./ui/widget.js"; // -- Types -- @@ -125,7 +126,7 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan activity: "", }); - const qr = await runQRBlock(planDir, ctx.cwd, extensionPath, state, log, widget); + const qr = await runPlanDesignWithQR(planDir, ctx.cwd, extensionPath, state, log, widget); if (qr.passed) outcome = "PASS"; return `Context captured. Plan design complete.\n\n${qr.summary}`; } finally { @@ -298,3 +299,103 @@ async function runQRBlock( widget?.update({ step: summary, activity: "" }); return { summary, passed }; } + +// -- Plan-design QR fix loop -- + +// Fix loop: architect -> QR -> [pass: done | fail: fix architect -> QR -> ...] +// +// Re-decomposes on each iteration rather than re-verifying only. The fix +// architect may change plan structure (add milestones, split intents, remove +// decisions); old QR items referencing stale scopes produce incorrect verdicts. +// Fresh decomposition generates items matched to the current plan state. +// +// The session's for-loop counter is the iteration source of truth. Each +// re-decompose writes a fresh qr-plan-design.json with iteration=1 and +// all-TODO items. The loop counter survives those resets. +async function runPlanDesignWithQR( + planDir: string, + cwd: string, + extensionPath: string, + state: WorkflowState, + log: Logger, + widget: WidgetController | null, +): Promise { + const qrPath = path.join(planDir, "qr-plan-design.json"); + + // Initial QR (iteration 1) + let qr = await runQRBlock(planDir, cwd, extensionPath, state, log, widget); + if (qr.passed) return qr; + + for (let iteration = 2; iteration <= MAX_FIX_ITERATIONS + 1; iteration++) { + // Read QR file for severity check + let qrFile: QRFile; + try { + const raw = await fs.readFile(qrPath, "utf8"); + qrFile = JSON.parse(raw) as QRFile; + } catch { + log("Fix loop: failed to read QR file", { iteration }); + return { summary: "Fix loop aborted: cannot read QR file.", passed: false }; + } + + // Severity escalation: if no blocking failures remain at this + // iteration, the plan passes without another fix attempt. + // Example: iteration 3 drops COULD -- if only COULD items fail, + // the plan is good enough and the loop terminates. + if (qrPassesAtIteration(qrFile.items, iteration)) { + const pass = qrFile.items.filter((i) => i.status === "PASS").length; + const fail = qrFile.items.filter((i) => i.status === "FAIL").length; + return { + passed: true, + summary: `QR passed at iteration ${iteration} after severity de-escalation: ${pass} PASS, ${fail} FAIL (non-blocking).`, + }; + } + + // Spawn fix-mode architect + const fixIndex = iteration - 1; + widget?.update({ step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: spawning architect...`, activity: "" }); + + const fixDir = await createSubagentDir(planDir, `architect-fix-${fixIndex}`); + + const fixPoll = setInterval(async () => { + const s = await readProjection(fixDir); + if (s) { + widget?.update({ + step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: ${s.stepName}`, + activity: s.lastAction ?? "", + }); + } + }, 2000); + + const fixResult = await spawnArchitectFix({ + planDir, + subagentDir: fixDir, + cwd, + extensionPath, + fixPhase: "plan-design", + log, + }); + + clearInterval(fixPoll); + + if (fixResult.exitCode !== 0) { + log("Fix architect failed", { iteration: fixIndex, exitCode: fixResult.exitCode, stderr: fixResult.stderr.slice(0, 500) }); + widget?.update({ step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: architect failed, re-running QR...`, activity: "" }); + } + + // Re-run full QR (decompose + verify) + widget?.update({ + step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: re-running QR...`, + activity: "", + }); + qr = await runQRBlock(planDir, cwd, extensionPath, state, log, widget); + if (qr.passed) return qr; + } + + // Max iterations reached. MUST failures remaining after 5 fix attempts + // indicate a structural problem -- silently passing would propagate a + // known-broken plan downstream. + return { + passed: false, + summary: `${qr.summary} (max ${MAX_FIX_ITERATIONS} fix iterations reached)`, + }; +} diff --git a/src/planner/subagent.ts b/src/planner/subagent.ts index 19c5647..32cb584 100644 --- a/src/planner/subagent.ts +++ b/src/planner/subagent.ts @@ -1,3 +1,8 @@ +// Subagent spawn helpers. Each public function delegates to spawnSubagent, +// which handles process lifecycle, stdout/stderr routing to disk, and +// exit-code normalization. Spawn errors resolve (not reject) so the caller +// can always read exitCode without try/catch. + import { spawn } from "node:child_process"; import { createWriteStream } from "node:fs"; import * as path from "node:path"; @@ -19,6 +24,15 @@ export interface SpawnArchitectOptions { log?: Logger; } +export interface SpawnArchitectFixOptions { + planDir: string; + subagentDir: string; + cwd: string; + extensionPath: string; + fixPhase: string; // e.g. "plan-design" + log?: Logger; +} + export interface SpawnQRDecomposerOptions { planDir: string; subagentDir: string; @@ -36,60 +50,7 @@ export interface SpawnReviewerOptions { log?: Logger; } -export function spawnArchitect(opts: SpawnArchitectOptions): Promise { - const log = opts.log ?? createLogger("Subagent"); - - const args = [ - "-p", - "-e", opts.extensionPath, - "--koan-role", "architect", - "--koan-phase", "plan-design", - "--koan-plan-dir", opts.planDir, - "--koan-subagent-dir", opts.subagentDir, - opts.initialPrompt ?? "Begin the plan-design phase.", - ]; - - log("Spawning architect subagent", { planDir: opts.planDir, subagentDir: opts.subagentDir }); - - return new Promise((resolve) => { - const stdoutLog = createWriteStream(path.join(opts.subagentDir, "stdout.log"), { flags: "w" }); - const stderrLog = createWriteStream(path.join(opts.subagentDir, "stderr.log"), { flags: "w" }); - - const proc = spawn("pi", args, { - cwd: opts.cwd, - shell: false, - stdio: ["ignore", "pipe", "pipe"], - }); - - let stderr = ""; - - proc.stdout.on("data", (data: Buffer) => { - stdoutLog.write(data); - }); - - proc.stderr.on("data", (data: Buffer) => { - stderr += data.toString(); - stderrLog.write(data); - }); - - proc.on("close", (code) => { - stdoutLog.end(); - stderrLog.end(); - const exitCode = code ?? 1; - log("Architect subagent exited", { exitCode }); - resolve({ exitCode, stderr, subagentDir: opts.subagentDir }); - }); - - proc.on("error", (error) => { - stdoutLog.end(); - stderrLog.end(); - log("Architect subagent spawn error", { error: error.message }); - resolve({ exitCode: 1, stderr: error.message, subagentDir: opts.subagentDir }); - }); - }); -} - -// -- QR spawners -- +// -- Spawn helper -- function spawnSubagent( role: string, @@ -149,6 +110,32 @@ function spawnSubagent( }); } +// -- Architect spawners -- + +export function spawnArchitect(opts: SpawnArchitectOptions): Promise { + const log = opts.log ?? createLogger("Subagent"); + return spawnSubagent( + "architect", + "plan-design", + opts.initialPrompt ?? "Begin the plan-design phase.", + opts, + log, + ); +} + +export function spawnArchitectFix(opts: SpawnArchitectFixOptions): Promise { + const log = opts.log ?? createLogger("Subagent"); + return spawnSubagent( + "architect", + "plan-design", + "Fix the plan based on QR failures.", + { ...opts, extraFlags: ["--koan-fix", opts.fixPhase] }, + log, + ); +} + +// -- QR spawners -- + export function spawnQRDecomposer(opts: SpawnQRDecomposerOptions): Promise { const log = opts.log ?? createLogger("Subagent"); return spawnSubagent("qr-decomposer", "qr-plan-design", "Begin the QR decompose phase.", opts, log); From bba7d12e8023ee3822e0c54603ce16232a19606c Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 25 Feb 2026 12:30:49 +0700 Subject: [PATCH 011/412] UI improvements --- src/planner/lib/audit.ts | 56 +++- src/planner/session.ts | 50 +++- src/planner/ui/widget.ts | 542 +++++++++++++++++++++++++++++++++++---- 3 files changed, 583 insertions(+), 65 deletions(-) diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index 181070a..d041f31 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -18,6 +18,8 @@ export interface ToolFileEvent extends EventBase { kind: "tool_file"; tool: "read" | "edit" | "write"; path: string; + lines?: number; + chars?: number; error: boolean; } @@ -112,8 +114,10 @@ function now(): string { // Derives a concise last-action string from a tool event for display. export function summarize(e: ToolEvent): string { switch (e.kind) { - case "tool_file": - return `${e.tool} ${e.path}`; + case "tool_file": { + const suffix = e.lines != null ? ` (${e.lines}L, ${e.chars}c)` : ""; + return `${e.tool} ${e.path}${suffix}`; + } case "tool_bash": return `bash ${e.bin}`; case "tool_koan": @@ -177,7 +181,7 @@ export function extractToolEvent(piEvent: PiToolResultEvent): ToolEvent { const seq = 0; if (FILE_TOOLS.has(toolName)) { - return { + const ev: ToolFileEvent = { kind: "tool_file", tool: toolName as "read" | "edit" | "write", path: (input["path"] as string | undefined) ?? "", @@ -185,6 +189,12 @@ export function extractToolEvent(piEvent: PiToolResultEvent): ToolEvent { ts, seq, }; + if (toolName === "read" && !isError) { + const text = content.find((c) => c.type === "text")?.text ?? ""; + ev.lines = text.split("\n").length; + ev.chars = text.length; + } + return ev; } if (toolName === "bash") { @@ -325,3 +335,43 @@ export async function readProjection(dir: string): Promise { return null; } } + +// Reads the tail of events.jsonl and returns human-readable summary lines. +// Filters out heartbeats (noisy). Used by session.ts to feed the widget log card. +export async function readRecentLogs(dir: string, count = 5): Promise { + try { + const raw = await fs.readFile(path.join(dir, "events.jsonl"), "utf8"); + const events = raw + .trimEnd() + .split("\n") + .filter(Boolean) + .map((line) => JSON.parse(line) as AuditEvent) + .filter((e) => e.kind !== "heartbeat"); + return events.slice(-count).map(formatLogLine); + } catch { + return []; + } +} + +function formatLogLine(e: AuditEvent): string { + switch (e.kind) { + case "phase_start": + return `${e.phase} started (${e.totalSteps} steps)`; + case "step_transition": + return `step ${e.step}/${e.totalSteps}: ${e.name}`; + case "phase_end": + return `${e.outcome}${e.detail ? ` -- ${e.detail}` : ""}`; + case "tool_file": { + const suffix = e.lines != null ? ` (${e.lines}L, ${e.chars}c)` : ""; + return `${e.tool} ${e.path}${suffix}`; + } + case "tool_bash": + return `bash ${e.bin}`; + case "tool_koan": + return e.tool; + case "tool_generic": + return e.tool; + case "heartbeat": + return "heartbeat"; + } +} diff --git a/src/planner/session.ts b/src/planner/session.ts index 42d8bf8..b29e98b 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -13,7 +13,7 @@ import { createPlanInfo } from "../utils/plan.js"; import { spawnArchitect, spawnArchitectFix, spawnQRDecomposer, spawnReviewer } from "./subagent.js"; import { createLogger, setLogDir, type Logger } from "../utils/logger.js"; import { createSubagentDir } from "../utils/progress.js"; -import { readProjection } from "./lib/audit.js"; +import { readProjection, readRecentLogs } from "./lib/audit.js"; import type { WorkflowDispatch, PlanRef } from "./lib/dispatch.js"; import { pool } from "./lib/pool.js"; import type { QRFile } from "./qr/types.js"; @@ -68,11 +68,15 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan const extensionPath = path.resolve(import.meta.dirname, "../../extensions/koan.ts"); const pollInterval = setInterval(async () => { - const s = await readProjection(subagentDir); + const [s, logs] = await Promise.all([ + readProjection(subagentDir), + readRecentLogs(subagentDir), + ]); if (s) { widget?.update({ step: s.stepName, activity: s.lastAction ?? "", + logLines: logs, }); } }, 2000); @@ -121,9 +125,13 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan state.phase = "plan-design-complete"; log("Architect plan-design complete", { planDir }); widget?.update({ - phaseStatus: { index: 1, status: "completed" }, + phaseStatus: { index: 1, status: "running" }, step: "starting QR block...", activity: "", + qrIterationsMax: MAX_FIX_ITERATIONS + 1, + qrIteration: 1, + qrMode: "initial", + qrPhase: "execute", }); const qr = await runPlanDesignWithQR(planDir, ctx.cwd, extensionPath, state, log, widget); @@ -204,15 +212,19 @@ async function runQRBlock( ): Promise { // 1. Spawn decomposer subagent state.phase = "qr-decompose-running"; - widget?.update({ step: "qr-decompose: starting...", activity: "" }); + widget?.update({ step: "qr-decompose: starting...", activity: "", qrPhase: "decompose" }); const decomposeDir = await createSubagentDir(planDir, "qr-decomposer"); const decomposePoll = setInterval(async () => { - const s = await readProjection(decomposeDir); + const [s, logs] = await Promise.all([ + readProjection(decomposeDir), + readRecentLogs(decomposeDir), + ]); if (s) { widget?.update({ step: `qr-decompose: ${s.stepName}`, activity: s.lastAction ?? "", + logLines: logs, }); } }, 2000); @@ -260,6 +272,7 @@ async function runQRBlock( // 3. Spawn reviewer pool state.phase = "qr-verify-running"; + widget?.update({ qrPhase: "verify" }); const result = await pool( itemIds, @@ -324,9 +337,16 @@ async function runPlanDesignWithQR( // Initial QR (iteration 1) let qr = await runQRBlock(planDir, cwd, extensionPath, state, log, widget); - if (qr.passed) return qr; + if (qr.passed) { + widget?.update({ qrPhase: "done", qrMode: null, qrIteration: null, qrIterationsMax: null, phaseStatus: { index: 1, status: "completed" } }); + return qr; + } + + widget?.update({ qrPhase: "execute" }); for (let iteration = 2; iteration <= MAX_FIX_ITERATIONS + 1; iteration++) { + widget?.update({ qrIteration: iteration, qrMode: "fix", qrPhase: "execute" }); + // Read QR file for severity check let qrFile: QRFile; try { @@ -334,6 +354,7 @@ async function runPlanDesignWithQR( qrFile = JSON.parse(raw) as QRFile; } catch { log("Fix loop: failed to read QR file", { iteration }); + widget?.update({ qrPhase: "done", qrMode: null, qrIteration: null, qrIterationsMax: null }); return { summary: "Fix loop aborted: cannot read QR file.", passed: false }; } @@ -344,6 +365,7 @@ async function runPlanDesignWithQR( if (qrPassesAtIteration(qrFile.items, iteration)) { const pass = qrFile.items.filter((i) => i.status === "PASS").length; const fail = qrFile.items.filter((i) => i.status === "FAIL").length; + widget?.update({ qrPhase: "done", qrMode: null, qrIteration: null, qrIterationsMax: null, phaseStatus: { index: 1, status: "completed" } }); return { passed: true, summary: `QR passed at iteration ${iteration} after severity de-escalation: ${pass} PASS, ${fail} FAIL (non-blocking).`, @@ -352,16 +374,20 @@ async function runPlanDesignWithQR( // Spawn fix-mode architect const fixIndex = iteration - 1; - widget?.update({ step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: spawning architect...`, activity: "" }); + widget?.update({ step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: spawning architect...`, activity: "", qrPhase: "execute" }); const fixDir = await createSubagentDir(planDir, `architect-fix-${fixIndex}`); const fixPoll = setInterval(async () => { - const s = await readProjection(fixDir); + const [s, logs] = await Promise.all([ + readProjection(fixDir), + readRecentLogs(fixDir), + ]); if (s) { widget?.update({ step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: ${s.stepName}`, activity: s.lastAction ?? "", + logLines: logs, }); } }, 2000); @@ -388,12 +414,18 @@ async function runPlanDesignWithQR( activity: "", }); qr = await runQRBlock(planDir, cwd, extensionPath, state, log, widget); - if (qr.passed) return qr; + if (qr.passed) { + widget?.update({ qrPhase: "done", qrMode: null, qrIteration: null, qrIterationsMax: null, phaseStatus: { index: 1, status: "completed" } }); + return qr; + } + + widget?.update({ qrPhase: "execute" }); } // Max iterations reached. MUST failures remaining after 5 fix attempts // indicate a structural problem -- silently passing would propagate a // known-broken plan downstream. + widget?.update({ qrPhase: "done", qrMode: null, qrIteration: null, qrIterationsMax: null }); return { passed: false, summary: `${qr.summary} (max ${MAX_FIX_ITERATIONS} fix iterations reached)`, diff --git a/src/planner/ui/widget.ts b/src/planner/ui/widget.ts index c5a4337..e663984 100644 --- a/src/planner/ui/widget.ts +++ b/src/planner/ui/widget.ts @@ -3,12 +3,13 @@ // Hash-based change detection + 1s unref'd timer for elapsed updates. // Created by session.plan(), destroyed in onContextComplete finally block. // -// Uses setWidget(key, factory) to get render(width) for full-width bg. -// Content stays at a fixed CONTENT width; background fills terminal edge. +// Layout and styling reference: docs/planning-widget.md and the +// corresponding execution widget design deck selections (Stacked Modular +// Cards canvas + Vertical Timeline Rail). import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; import type { Theme, ThemeColor } from "@mariozechner/pi-coding-agent"; -import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui"; +import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui"; // -- Types -- @@ -17,16 +18,28 @@ export type PhaseStatus = "pending" | "running" | "completed" | "failed"; interface PhaseEntry { key: string; label: string; + detail: string; status: PhaseStatus; } +type WidgetMode = "planning" | "execution"; + +type QRMode = "initial" | "fix"; +type QRPhase = "idle" | "execute" | "decompose" | "verify" | "done"; + interface WidgetState { + mode: WidgetMode; planId: string; phases: PhaseEntry[]; activeIndex: number; // 0-based; -1 when done step: string; activity: string; startedAt: number; + logLines: string[]; + qrIteration: number | null; + qrIterationsMax: number | null; + qrMode: QRMode | null; + qrPhase: QRPhase; } export interface WidgetUpdate { @@ -34,36 +47,83 @@ export interface WidgetUpdate { step?: string; activity?: string; phaseStatus?: { index: number; status: PhaseStatus }; + mode?: WidgetMode; + logLines?: readonly string[]; + qrIteration?: number | null; + qrIterationsMax?: number | null; + qrMode?: QRMode | null; + qrPhase?: QRPhase; } // -- Constants -- const WIDGET_KEY = "koan"; -const PAD = 2; // horizontal padding each side - -const PHASES: ReadonlyArray<{ key: string; label: string }> = [ - { key: "ctx", label: "Gathering context" }, - { key: "design", label: "Designing plan" }, - { key: "code", label: "Planning code" }, - { key: "docs", label: "Planning docs" }, - { key: "exec-c", label: "Executing code" }, - { key: "exec-d", label: "Executing docs" }, +const PAD = 2; // horizontal canvas padding each side +const CARD_MARGIN = 2; // left margin before card borders +const LOG_LINES = 5; + +const BODY_INDENT = " "; + +const PLANNING_PHASES: ReadonlyArray<{ key: string; label: string; detail: string }> = [ + { key: "ctx", label: "Context", detail: "Gathering context" }, + { key: "design", label: "Plan design", detail: "Designing plan" }, + { key: "code", label: "Plan code", detail: "Creating code plan" }, + { key: "docs", label: "Plan docs", detail: "Documenting plan" }, ]; const STATUS_ICON: Record = { - pending: "[ ]", - running: "[>>]", - completed: "[OK]", - failed: "[!!]", + pending: "○", + running: "●", + completed: "●", + failed: "✖", }; -const ICON_COLOR: Record = { +const STATUS_COLOR: Record = { pending: "muted", - running: "warning", - completed: "success", + running: "accent", + completed: "dim", failed: "error", }; +const STATUS_TAG: Record = { + pending: "upcoming", + running: "current", + completed: "done", + failed: "failed", +}; + +const LOG_PLACEHOLDER = "No recent log entries"; +const TIMELINE_MIN_WIDTH = 16; +const TIMELINE_MAX_WIDTH = 28; +const CONNECTOR = "│"; + +interface BorderStyle { + topLeft: string; + topRight: string; + bottomLeft: string; + bottomRight: string; + horizontal: string; + vertical: string; +} + +const BORDER_SOLID: BorderStyle = { + topLeft: "┌", + topRight: "┐", + bottomLeft: "└", + bottomRight: "┘", + horizontal: "─", + vertical: "│", +}; + +const BORDER_SUBTLE: BorderStyle = { + topLeft: "╭", + topRight: "╮", + bottomLeft: "╰", + bottomRight: "╯", + horizontal: "─", + vertical: "│", +}; + // -- Canvas primitive -- // Content width adapts to terminal; background fills edge to edge. @@ -73,13 +133,31 @@ function contentWidth(termWidth: number): number { function canvasLine(content: string, termWidth: number, theme: Theme): string { const cw = contentWidth(termWidth); - const inner = truncateToWidth(content, cw, "...", true); + const inner = clampToWidth(content, cw); const line = " ".repeat(PAD) + inner + " ".repeat(PAD); return theme.bg("toolPendingBg", line); } // -- Helpers -- +function clampToWidth(text: string, width: number, ellipsis = ""): string { + const truncated = truncateToWidth(text, width, ellipsis === "" ? "" : ellipsis, false); + const visible = visibleWidth(truncated); + if (visible >= width) { + return truncated; + } + return truncated + " ".repeat(width - visible); +} + +function indentLines(lines: string[], width: number, indent = BODY_INDENT): string[] { + if (!indent) { + return lines.map((line) => clampToWidth(line, width)); + } + const indentWidth = visibleWidth(indent); + const available = Math.max(0, width - indentWidth); + return lines.map((line) => indent + clampToWidth(line, available)); +} + function formatElapsed(ms: number): string { const totalSec = Math.floor(ms / 1000); const m = Math.floor(totalSec / 60); @@ -92,41 +170,371 @@ function rightAlign(left: string, right: string, width: number): string { return `${left}${" ".repeat(gap)}${right}`; } -// Pure render: (state, theme, termWidth) -> 7 lines. No side effects. +function activePhase(state: WidgetState): PhaseEntry | null { + if (state.activeIndex < 0) return null; + return state.phases[state.activeIndex] ?? null; +} + +function normalizeLogLines(lines: readonly string[] | undefined): string[] { + if (!lines || lines.length === 0) return []; + const trimmed = lines.map((line) => line.replace(/\s+$/u, "")); + return trimmed.slice(-LOG_LINES); +} + +function phaseChipLabel(phase: PhaseEntry, index: number, state: WidgetState, theme: Theme): string { + const label = `┃ ${phase.label} ┃`; + if (index === state.activeIndex) { + return theme.bold(theme.fg("accent", label)); + } + if (phase.status === "completed") { + return theme.bold(theme.fg("muted", label)); + } + if (phase.status === "failed") { + return theme.fg("error", label); + } + return theme.fg("muted", label); +} + +function renderPhaseChips(state: WidgetState, theme: Theme, width: number): string { + const chips = state.phases.map((phase, index) => phaseChipLabel(phase, index, state, theme)); + return clampToWidth(chips.join(" "), width, "…"); +} + +function renderTimelineLines(state: WidgetState, theme: Theme, width: number): string[] { + const lines: string[] = []; + const total = state.phases.length; + + state.phases.forEach((phase, index) => { + const isActive = index === state.activeIndex; + const color = STATUS_COLOR[phase.status]; + const iconBase = STATUS_ICON[phase.status]; + const icon = isActive + ? theme.bold(theme.fg("accent", iconBase)) + : theme.fg(color, iconBase); + + const labelColor: ThemeColor = phase.status === "completed" + ? "dim" + : isActive + ? "accent" + : phase.status === "failed" + ? "error" + : "muted"; + + const emphasize = isActive || phase.status === "completed"; + const label = emphasize + ? theme.bold(theme.fg(labelColor, phase.label)) + : theme.fg(labelColor, phase.label); + + lines.push(clampToWidth(`${icon} ${label}`, width, "…")); + + const connector = index < total - 1 ? theme.fg("muted", CONNECTOR) : " "; + lines.push(clampToWidth(`${connector} ${theme.fg("muted", STATUS_TAG[phase.status].toUpperCase())}`, width, "…")); + + if (index < total - 1) { + lines.push(clampToWidth(`${theme.fg("muted", CONNECTOR)} `, width)); + } + }); + + return lines; +} + +function upcomingSummary(state: WidgetState): string { + const remaining = state.activeIndex < 0 + ? [] + : state.phases.slice(state.activeIndex + 1).filter((p) => p.status !== "failed"); + if (state.activeIndex < 0) return "Planning complete"; + if (remaining.length === 0) return "Final step in progress"; + const labels = remaining.map((p) => p.label).join(" → "); + return `Upcoming: ${labels}`; +} + +function renderQRStatusWidget(state: WidgetState, theme: Theme, width: number): string[] { + if (state.qrIteration === null || state.qrPhase === "idle") { + return []; + } + + const innerWidth = Math.max(0, width - 2); + const iterationTotal = state.qrIterationsMax ? ` / ${state.qrIterationsMax}` : ""; + const modeLabel = state.qrMode === "fix" ? "Fix" : "Initial"; + + const headerLeft = theme.bold(theme.fg("accent", "Quality review")); + const headerRightParts = [`Iter ${state.qrIteration}${iterationTotal}`]; + if (modeLabel) headerRightParts.push(modeLabel); + const headerRight = theme.fg("dim", headerRightParts.join(" · ")); + + const phaseEntries: Array<{ key: Exclude; label: string }> = [ + { key: "execute", label: state.qrMode === "fix" ? "Execute (fix)" : "Execute" }, + { key: "decompose", label: "QR decompose" }, + { key: "verify", label: "QR verify" }, + ]; + + let currentIndex = phaseEntries.findIndex((entry) => entry.key === state.qrPhase); + if (state.qrPhase === "done") { + currentIndex = phaseEntries.length; + } + + const segments = phaseEntries.map((entry, index) => { + if (index < currentIndex) { + return theme.bold(theme.fg("dim", `${entry.label} ✓`)); + } + if (index === currentIndex) { + return theme.bold(theme.fg("accent", entry.label)); + } + return theme.fg("muted", entry.label); + }); + + const separator = theme.fg("muted", " → "); + const stageLine = clampToWidth(segments.join(separator), innerWidth, "…"); + + const description = (() => { + if (state.qrPhase === "execute") { + return state.qrMode === "fix" + ? "Fix-mode architect applies QR feedback." + : "Initial execution to gather plan context."; + } + if (state.qrPhase === "decompose") { + return state.qrIteration && state.qrIteration > 1 + ? "Re-decomposing updates into review items." + : "Deriving QR checklist from the current plan."; + } + if (state.qrPhase === "verify") { + return "Massively parallel reviewers scoring QR items."; + } + if (state.qrPhase === "done") { + return "Quality review loop complete."; + } + return ""; + })(); + + const body: string[] = []; + body.push(stageLine); + if (description) { + body.push(clampToWidth(theme.fg("muted", description), innerWidth, "…")); + } + + return renderBox(headerLeft, headerRight, body, width, theme, BORDER_SUBTLE); +} + +interface DetailSections { + core: string[]; + footer: string[]; +} + +function buildDetailSections(state: WidgetState, theme: Theme, width: number): DetailSections { + const core: string[] = []; + const footer: string[] = []; + const blank = clampToWidth("", width); + + const active = activePhase(state); + const stepTitle = state.step || active?.detail || active?.label || "Awaiting step"; + core.push(clampToWidth(theme.bold(theme.fg("accent", stepTitle)), width, "…")); + + if (state.activity) { + const activityLines = wrapTextWithAnsi(theme.fg("muted", state.activity), width); + for (const line of activityLines) { + core.push(clampToWidth(line, width)); + } + } + + const qrWidget = renderQRStatusWidget(state, theme, width); + if (qrWidget.length > 0) { + if (core.length > 0 && core[core.length - 1].trim() !== "") { + core.push(blank); + } + core.push(...qrWidget.map((line) => clampToWidth(line, width))); + } + + if (active) { + footer.push(...wrapTextWithAnsi(theme.fg("dim", `Phase ${state.activeIndex + 1}/${state.phases.length}`), width).map((line) => clampToWidth(line, width, "…"))); + footer.push(...wrapTextWithAnsi(theme.fg("dim", `Plan · ${state.planId}`), width).map((line) => clampToWidth(line, width, "…"))); + } + + const summary = upcomingSummary(state); + if (summary) { + footer.push(...wrapTextWithAnsi(theme.fg("muted", summary), width).map((line) => clampToWidth(line, width, "…"))); + } + + return { core, footer }; +} + +function layoutDetailColumn(sections: DetailSections, width: number, targetRows: number): string[] { + const blank = clampToWidth("", width); + const lines = [...sections.core]; + + if (sections.footer.length > 0) { + if (lines.length === 0 || lines[lines.length - 1].trim() !== "") { + lines.push(blank); + } + } + + const used = lines.length + sections.footer.length; + const goal = Math.max(targetRows, used); + + while (lines.length < goal - sections.footer.length) { + lines.push(blank); + } + + if (sections.footer.length === 0) { + return lines; + } + + return [...lines, ...sections.footer]; +} + +function renderBox( + titleLeft: string, + titleRight: string, + body: string[], + width: number, + theme: Theme, + border: BorderStyle = BORDER_SOLID, +): string[] { + const innerWidth = Math.max(0, width - 2); + const left = visibleWidth(titleLeft) > innerWidth ? truncateToWidth(titleLeft, innerWidth, "", false) : titleLeft; + const right = visibleWidth(titleRight) > innerWidth ? truncateToWidth(titleRight, innerWidth, "", false) : titleRight; + const headerContent = rightAlign(left, right, innerWidth); + + const top = `${border.topLeft}${clampToWidth(headerContent, innerWidth)}${border.topRight}`; + const bottom = `${border.bottomLeft}${clampToWidth(border.horizontal.repeat(innerWidth), innerWidth)}${border.bottomRight}`; + + const content = body.map((line) => `${border.vertical}${clampToWidth(line, innerWidth)}${border.vertical}`); + return [top, ...content, bottom]; +} + +function renderPlanningCard(state: WidgetState, theme: Theme, width: number): string[] { + const elapsed = theme.fg("dim", formatElapsed(Date.now() - state.startedAt)); + const innerWidth = Math.max(0, width - 2); + const indentWidth = visibleWidth(BODY_INDENT); + const contentWidth = Math.max(0, innerWidth - indentWidth); + + if (innerWidth < 60 || contentWidth < 40) { + const fallbackContent: string[] = [ + "", + theme.fg("muted", `Plan · ${state.planId}`), + "", + formatStepLine(state, theme), + formatPhaseTrail(state, theme, contentWidth), + ]; + const detail = formatDetail(state, theme, contentWidth); + if (detail) fallbackContent.push(detail); + fallbackContent.push(""); + + const body = indentLines(fallbackContent, innerWidth); + return renderBox( + `${BODY_INDENT}${theme.bold(theme.fg("accent", "Planning"))}`, + elapsed, + body, + width, + theme, + ); + } + + const chipsLine = renderPhaseChips(state, theme, contentWidth); + const timelineWidth = Math.min(TIMELINE_MAX_WIDTH, Math.max(TIMELINE_MIN_WIDTH, Math.floor(contentWidth * 0.3))); + const detailWidth = Math.max(14, contentWidth - timelineWidth - 4); + + const timelineLines = renderTimelineLines(state, theme, timelineWidth); + const detailSections = buildDetailSections(state, theme, detailWidth); + const detailLines = layoutDetailColumn(detailSections, detailWidth, timelineLines.length); + const combined: string[] = []; + const maxLines = Math.max(timelineLines.length, detailLines.length); + + for (let i = 0; i < maxLines; i++) { + const left = timelineLines[i] ?? ""; + const right = detailLines[i] ?? ""; + const composed = `${clampToWidth(left, timelineWidth)} ${clampToWidth(right, detailWidth)}`; + combined.push(clampToWidth(composed, contentWidth)); + } + + const body = indentLines( + [ + "", + chipsLine, + "", + ...combined, + "", + ], + innerWidth, + ); + + return renderBox( + `${BODY_INDENT}${theme.bold(theme.fg("accent", "Planning Workspace"))}`, + elapsed, + body, + width, + theme, + ); +} + +function renderLogCard(state: WidgetState, theme: Theme, width: number): string[] { + const innerWidth = Math.max(0, width - 2); + const raw = state.logLines.length > 0 ? state.logLines.slice(-LOG_LINES) : [LOG_PLACEHOLDER]; + const padded = [...raw]; + while (padded.length < LOG_LINES) padded.push(""); + + const lines = padded.map((line) => { + if (!line) return ""; + return theme.fg("dim", `• ${line}`); + }); + + const body = indentLines(lines, innerWidth); + return renderBox( + `${BODY_INDENT}${theme.bold(theme.fg("accent", "Latest log"))}`, + "", + body, + width, + theme, + ); +} + +function formatPhaseTrail(state: WidgetState, theme: Theme, width: number): string { + const parts = state.phases.map((phase, index) => { + const icon = STATUS_ICON[phase.status]; + const color = STATUS_COLOR[phase.status]; + const label = index === state.activeIndex ? theme.bold(phase.label) : phase.label; + return theme.fg(color, `${icon} ${label}`); + }); + const trail = parts.join(" "); + return clampToWidth(trail, width, "…"); +} + +function formatDetail(state: WidgetState, theme: Theme, width: number): string { + const step = state.step ? theme.fg("muted", state.step) : ""; + const activity = state.activity ? theme.fg("dim", ` · ${state.activity}`) : ""; + const detail = `${step}${activity}`; + if (!detail) return ""; + return clampToWidth(detail, width, "…"); +} + +function formatStepLine(state: WidgetState, theme: Theme): string { + const total = state.phases.length; + const active = activePhase(state); + const stepNumber = state.activeIndex >= 0 ? state.activeIndex + 1 : total; + const count = theme.fg("muted", `Step ${stepNumber} of ${total}`); + const label = active + ? theme.bold(theme.fg("accent", active.label)) + : theme.bold(theme.fg("muted", "Complete")); + return `${count} ${theme.fg("muted", "·")} ${label}`; +} + +// Pure render: (state, theme, termWidth) -> lines. No side effects. function render(state: WidgetState, theme: Theme, termWidth: number): string[] { const c = (s: string) => canvasLine(s, termWidth, theme); const cw = contentWidth(termWidth); + const lines: string[] = []; + const margin = " ".repeat(CARD_MARGIN); - // Header: koan [N/6] label ... elapsed - const idx = state.activeIndex; - const label = idx >= 0 ? state.phases[idx].label : "done"; - const num = idx >= 0 ? idx + 1 : 6; - const left = `${theme.bold(theme.fg("accent", "koan"))} [${num}/6] ${label}`; - const elapsed = theme.fg("dim", formatElapsed(Date.now() - state.startedAt)); - const header = rightAlign(left, elapsed, cw); - - // Plan ID - const planId = theme.fg("dim", state.planId); - - // Phase bar - const phaseBar = state.phases - .map((p) => `${theme.fg(ICON_COLOR[p.status], STATUS_ICON[p.status])} ${p.key}`) - .join(" "); - - // Step + activity - const step = state.step ? theme.fg("dim", state.step) : ""; - const act = state.activity ? theme.fg("muted", ` > ${state.activity}`) : ""; - const detail = truncateToWidth(step + act, cw, "..."); - - return [ - c(""), // top padding - c(header), - c(planId), - c(""), // separator - c(phaseBar), - c(detail), - c(""), // bottom padding - ]; + lines.push(c("")); + for (const line of renderPlanningCard(state, theme, cw - CARD_MARGIN)) { + lines.push(c(margin + line)); + } + lines.push(c(margin)); + for (const line of renderLogCard(state, theme, cw - CARD_MARGIN)) { + lines.push(c(margin + line)); + } + lines.push(c("")); + + return lines; } // -- WidgetController -- @@ -140,12 +548,18 @@ export class WidgetController { constructor(ui: ExtensionUIContext, planId: string) { this.ui = ui; this.state = { + mode: "planning", planId, - phases: PHASES.map((p) => ({ key: p.key, label: p.label, status: "pending" as PhaseStatus })), + phases: PLANNING_PHASES.map((p) => ({ key: p.key, label: p.label, detail: p.detail, status: "pending" as PhaseStatus })), activeIndex: 0, step: "", activity: "", startedAt: Date.now(), + logLines: [], + qrIteration: null, + qrIterationsMax: null, + qrMode: null, + qrPhase: "idle", }; this.state.phases[0].status = "running"; @@ -156,6 +570,9 @@ export class WidgetController { } update(patch: WidgetUpdate): void { + if (patch.mode !== undefined) { + this.state.mode = patch.mode; + } if (patch.phaseStatus !== undefined) { const { index, status } = patch.phaseStatus; if (index >= 0 && index < this.state.phases.length) { @@ -175,6 +592,21 @@ export class WidgetController { if (patch.activity !== undefined) { this.state.activity = patch.activity; } + if (patch.logLines !== undefined) { + this.state.logLines = normalizeLogLines(patch.logLines); + } + if (patch.qrIteration !== undefined) { + this.state.qrIteration = patch.qrIteration; + } + if (patch.qrIterationsMax !== undefined) { + this.state.qrIterationsMax = patch.qrIterationsMax; + } + if (patch.qrMode !== undefined) { + this.state.qrMode = patch.qrMode; + } + if (patch.qrPhase !== undefined) { + this.state.qrPhase = patch.qrPhase; + } this.doRender(); } @@ -185,7 +617,11 @@ export class WidgetController { private doRender(): void { // Capture state snapshot for the factory closure - const state = { ...this.state, phases: this.state.phases.map((p) => ({ ...p })) }; + const state = { + ...this.state, + phases: this.state.phases.map((p) => ({ ...p })), + logLines: [...this.state.logLines], + }; const theme = this.ui.theme; // Hash check: skip setWidget if content unchanged (ignoring width) From 524158cb7d71b987625bd69c8c1569c658115975 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 25 Feb 2026 12:36:00 +0700 Subject: [PATCH 012/412] Wire event log into widget and add structured log lines readRecentLogs() reads events.jsonl tail and returns structured LogLine entries (prefix/highlight/meta) so the widget can apply theme-aware coloring -- file paths and commands render bold while prefixes and size metadata render dim. Also captures lines/chars for both read and bash tool results. --- src/planner/lib/audit.ts | 49 ++++++++++++++++++++++++++-------------- src/planner/ui/widget.ts | 35 ++++++++++++++++------------ 2 files changed, 53 insertions(+), 31 deletions(-) diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index d041f31..307c120 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -26,6 +26,8 @@ export interface ToolFileEvent extends EventBase { export interface ToolBashEvent extends EventBase { kind: "tool_bash"; bin: string; + lines?: number; + chars?: number; error: boolean; } @@ -118,8 +120,10 @@ export function summarize(e: ToolEvent): string { const suffix = e.lines != null ? ` (${e.lines}L, ${e.chars}c)` : ""; return `${e.tool} ${e.path}${suffix}`; } - case "tool_bash": - return `bash ${e.bin}`; + case "tool_bash": { + const suffix = e.lines != null ? ` (${e.lines}L, ${e.chars}c)` : ""; + return `bash ${e.bin}${suffix}`; + } case "tool_koan": return e.tool; case "tool_generic": @@ -200,7 +204,8 @@ export function extractToolEvent(piEvent: PiToolResultEvent): ToolEvent { if (toolName === "bash") { const cmd = (input["command"] as string | undefined) ?? ""; const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; - return { kind: "tool_bash", bin, error: isError, ts, seq }; + const text = content.find((c) => c.type === "text")?.text ?? ""; + return { kind: "tool_bash", bin, lines: text.split("\n").length, chars: text.length, error: isError, ts, seq }; } if (toolName.startsWith("koan_")) { @@ -336,9 +341,17 @@ export async function readProjection(dir: string): Promise { } } -// Reads the tail of events.jsonl and returns human-readable summary lines. +// Structured log line for the widget log card. The widget applies +// theme-aware coloring: prefix dim, highlight normal, meta dim. +export interface LogLine { + prefix: string; + highlight: string; + meta: string; +} + +// Reads the tail of events.jsonl and returns structured log entries. // Filters out heartbeats (noisy). Used by session.ts to feed the widget log card. -export async function readRecentLogs(dir: string, count = 5): Promise { +export async function readRecentLogs(dir: string, count = 5): Promise { try { const raw = await fs.readFile(path.join(dir, "events.jsonl"), "utf8"); const events = raw @@ -353,25 +366,27 @@ export async function readRecentLogs(dir: string, count = 5): Promise } } -function formatLogLine(e: AuditEvent): string { +function sizeSuffix(e: { lines?: number; chars?: number }): string { + return e.lines != null ? `(${e.lines}L, ${e.chars}c)` : ""; +} + +function formatLogLine(e: AuditEvent): LogLine { switch (e.kind) { case "phase_start": - return `${e.phase} started (${e.totalSteps} steps)`; + return { prefix: "phase", highlight: e.phase, meta: `(${e.totalSteps} steps)` }; case "step_transition": - return `step ${e.step}/${e.totalSteps}: ${e.name}`; + return { prefix: `step ${e.step}/${e.totalSteps}`, highlight: e.name, meta: "" }; case "phase_end": - return `${e.outcome}${e.detail ? ` -- ${e.detail}` : ""}`; - case "tool_file": { - const suffix = e.lines != null ? ` (${e.lines}L, ${e.chars}c)` : ""; - return `${e.tool} ${e.path}${suffix}`; - } + return { prefix: "phase", highlight: e.outcome, meta: e.detail ?? "" }; + case "tool_file": + return { prefix: e.tool, highlight: e.path, meta: sizeSuffix(e) }; case "tool_bash": - return `bash ${e.bin}`; + return { prefix: "bash", highlight: e.bin, meta: sizeSuffix(e) }; case "tool_koan": - return e.tool; + return { prefix: "koan", highlight: e.tool, meta: "" }; case "tool_generic": - return e.tool; + return { prefix: "tool", highlight: e.tool, meta: "" }; case "heartbeat": - return "heartbeat"; + return { prefix: "", highlight: "heartbeat", meta: "" }; } } diff --git a/src/planner/ui/widget.ts b/src/planner/ui/widget.ts index e663984..e16cfed 100644 --- a/src/planner/ui/widget.ts +++ b/src/planner/ui/widget.ts @@ -10,6 +10,7 @@ import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; import type { Theme, ThemeColor } from "@mariozechner/pi-coding-agent"; import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui"; +import type { LogLine } from "../lib/audit.js"; // -- Types -- @@ -35,7 +36,7 @@ interface WidgetState { step: string; activity: string; startedAt: number; - logLines: string[]; + logLines: LogLine[]; qrIteration: number | null; qrIterationsMax: number | null; qrMode: QRMode | null; @@ -48,7 +49,7 @@ export interface WidgetUpdate { activity?: string; phaseStatus?: { index: number; status: PhaseStatus }; mode?: WidgetMode; - logLines?: readonly string[]; + logLines?: readonly LogLine[]; qrIteration?: number | null; qrIterationsMax?: number | null; qrMode?: QRMode | null; @@ -175,10 +176,9 @@ function activePhase(state: WidgetState): PhaseEntry | null { return state.phases[state.activeIndex] ?? null; } -function normalizeLogLines(lines: readonly string[] | undefined): string[] { +function normalizeLogLines(lines: readonly LogLine[] | undefined): LogLine[] { if (!lines || lines.length === 0) return []; - const trimmed = lines.map((line) => line.replace(/\s+$/u, "")); - return trimmed.slice(-LOG_LINES); + return [...lines].slice(-LOG_LINES); } function phaseChipLabel(phase: PhaseEntry, index: number, state: WidgetState, theme: Theme): string { @@ -466,18 +466,25 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st ); } +function renderLogLine(entry: LogLine, theme: Theme): string { + const parts: string[] = []; + if (entry.prefix) parts.push(theme.fg("dim", entry.prefix)); + if (entry.highlight) parts.push(theme.bold(entry.highlight)); + if (entry.meta) parts.push(theme.fg("dim", entry.meta)); + return `${theme.fg("dim", "•")} ${parts.join(" ")}`; +} + function renderLogCard(state: WidgetState, theme: Theme, width: number): string[] { const innerWidth = Math.max(0, width - 2); - const raw = state.logLines.length > 0 ? state.logLines.slice(-LOG_LINES) : [LOG_PLACEHOLDER]; - const padded = [...raw]; - while (padded.length < LOG_LINES) padded.push(""); + const hasEntries = state.logLines.length > 0; + const entries = hasEntries ? state.logLines.slice(-LOG_LINES) : []; - const lines = padded.map((line) => { - if (!line) return ""; - return theme.fg("dim", `• ${line}`); - }); + const formatted: string[] = hasEntries + ? entries.map((entry) => renderLogLine(entry, theme)) + : [theme.fg("dim", `• ${LOG_PLACEHOLDER}`)]; + while (formatted.length < LOG_LINES) formatted.push(""); - const body = indentLines(lines, innerWidth); + const body = indentLines(formatted, innerWidth); return renderBox( `${BODY_INDENT}${theme.bold(theme.fg("accent", "Latest log"))}`, "", @@ -620,7 +627,7 @@ export class WidgetController { const state = { ...this.state, phases: this.state.phases.map((p) => ({ ...p })), - logLines: [...this.state.logLines], + logLines: this.state.logLines.map((l) => ({ ...l })), }; const theme = this.ui.theme; From e584235f453a0034c7bb63f8743a0d8621a1bb34 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 25 Feb 2026 12:37:15 +0700 Subject: [PATCH 013/412] Filter koan_complete_step from log and clarify step label koan_complete_step and step_transition are emitted from the same tool call (transition inside handler, tool_koan after return), so the complete_step line is redundant noise. Also changes step label from "step 5/6" to "current step 5/6:" to read as status. --- src/planner/lib/audit.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index 307c120..aea727a 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -359,7 +359,7 @@ export async function readRecentLogs(dir: string, count = 5): Promise .split("\n") .filter(Boolean) .map((line) => JSON.parse(line) as AuditEvent) - .filter((e) => e.kind !== "heartbeat"); + .filter((e) => e.kind !== "heartbeat" && !(e.kind === "tool_koan" && e.tool === "koan_complete_step")); return events.slice(-count).map(formatLogLine); } catch { return []; @@ -375,7 +375,7 @@ function formatLogLine(e: AuditEvent): LogLine { case "phase_start": return { prefix: "phase", highlight: e.phase, meta: `(${e.totalSteps} steps)` }; case "step_transition": - return { prefix: `step ${e.step}/${e.totalSteps}`, highlight: e.name, meta: "" }; + return { prefix: `current step ${e.step}/${e.totalSteps}:`, highlight: e.name, meta: "" }; case "phase_end": return { prefix: "phase", highlight: e.outcome, meta: e.detail ?? "" }; case "tool_file": From f0f4090fa7bbfbe5965dfaaa0b0f209239fd1760 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 25 Feb 2026 15:34:00 +0700 Subject: [PATCH 014/412] Add planning widget design reference doc Documents the design-deck contract for the refreshed planning widget: stacked modular cards, vertical timeline rail, integrated log section, and QR inline section. --- docs/planning-widget.md | 97 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/planning-widget.md diff --git a/docs/planning-widget.md b/docs/planning-widget.md new file mode 100644 index 0000000..19d8c0d --- /dev/null +++ b/docs/planning-widget.md @@ -0,0 +1,97 @@ +# Planning Widget Refresh + +## Context +The planning widget now follows the design-deck contract selected on Feb 25 2026: + +- **Canvas direction:** Stacked Modular Cards +- **Navigation direction:** Vertical Timeline Rail +- **Log strategy:** Declarative shape-table serialization + dense two-column layout +- **QR strategy:** Inline integrated section (not a detached sub-card) + +The goal is to keep a long-running (1-2h) planning session readable in real time while preserving high-signal audit telemetry. + +## Decisions & Rationale + +### 1) Deterministic log serialization (hybrid detail) +- Keep **tool name** as the primary scan anchor. +- Use a declarative per-tool formatter table for known `koan_*` tools. +- Unknown tools fall back to tool-name-only output. +- Field order is deterministic and curated (e.g., IDs first), not alphabetical. + +**Rationale:** Users scan continuously during execution; stable order makes visual parsing faster and reduces cognitive churn between updates. + +### 2) Selective detail by field type +- Arrays render as **first item + count** (`[first] +N`). +- Free-form fields (`diff`, `doc_diff`, `comments`, large narrative strings) render as **size metadata only** (`184L/9.2k`), never full body. +- Getter tools (`koan_get_*`) show target identifiers plus response size metadata (`resp:42L/3.1k`). + +**Rationale:** Maintains observability without blowing out vertical space or flooding with low-value text. + +### 3) Latest log as dense two-column grid +- Left column: tool name (bold accent anchor). +- Right column: compact deterministic summary. +- Column widths adapt to available terminal width + observed tool-name lengths (protecting right-column readability). +- High-value rows may wrap to 2 lines; if overflow exceeds 2 lines, the second line is re-compacted with ellipsis. +- Repeated events remain separate rows (no dedup/collapse). + +**Rationale:** Preserves temporal fidelity while increasing information density and keeping the "what just happened" answer immediate, even under constrained widths. + +### 4) QR is a first-class workflow section +- QR renders inline in detail pane with divider rule (no detached mini-card border). +- Visible for Plan design (and contractually for Plan execution), hidden only for Context gathering. +- QR starts directly in the **`execute`** stage for iteration 1 (non-fix mode); fix iterations reuse the same stage model. +- QR block is normalized to a fixed structure: header, phase rail, counters, divider. +- Metadata is budgeted to **64 visible chars max** and progressively compacted (`phase/iter/mode` -> `iN/M`, `d/p/f/t`) when width is constrained. +- Counter line emphasizes severity: `fail` is error-colored; `pass` is accent; others remain muted/dim. + +**Rationale:** QR is not optional side telemetry; it is the acceptance loop for the plan. The UI should communicate that structural importance while remaining legible and shape-stable at smaller widths. + +## Layout Overview +``` +┌──────────────────────────────── Planning ────────────────────────────────────┐ +│ ┃ Context gathering ┃ ┃ Plan design ┃ ┃ Plan code ┃ ┃ Plan docs ┃ │ +│ │ +│ ● Context gathering qr-decompose: Step 2/13: Holistic Concerns │ +│ │ DONE read CLAUDE.md · 41L/1709c │ +│ │ │ +│ ● Plan design QR | phase:decompose · iter 1/6 initial │ +│ │ CURRENT Execute → QR decompose → QR verify │ +│ │ done:0/24 pass:0 fail:0 todo:24 │ +│ │ ──────────────────────────────────────────────── │ +│ ○ Plan code Plan · │ +│ │ UPCOMING │ +│ ○ Plan docs │ +│──────────────────────────────────────────────────────────────────────────────│ +│ Latest log │ +│ koan_set_milestone_tests id=M-002 · tests:["covers retries"] +7 │ +│ koan_get_milestone id=M-002 · resp:42L/3.1k │ +│ koan_add_intent milestone=M-002 · file=src/planner/ui/widget.ts │ +│ koan_set_change_diff id=CC-M-001-002 · diff:184L/9.2k │ +│ koan_qr_assign_group phase=plan-design · ids:[QR-001] +11 │ +└──────────────────────────────────────────────────────────────────────────────┘ +``` + +## Rendering Guide +1. **Canvas** – Keep using `canvasLine()` so widget content remains full-width over `toolPendingBg`. +2. **Main card** – Keep solid border + consistent inner padding via shared `renderBox()` helper. +3. **Timeline rail** – Maintain status icon/color semantics (`active=accent`, `done=dim`, `failed=error`). +4. **Detail pane** – Render in this order: + - a dim section label (`Current step`) to create hierarchy + - step title + optional activity + - QR integrated section (if visible) + - footer metadata (`Plan · ID`) pinned to bottom via dynamic padding +5. **QR section** – Use inline header + phase rail + metadata line + divider. Avoid nested border style to keep it visually native to the right pane. Keep line geometry stable (fixed 3-line payload + divider) and enforce a 64-char metadata budget before clamping to pane width. +6. **Latest log section** – Keep it inside the same outer card, separated by a horizontal divider. Reuse the same left/right column split (`timelineWidth` / `detailWidth`) and gap as the planning body so vertical alignment stays consistent. + +## Data Contract Notes +- `LogLine` now carries: + - `tool` (left column) + - `summary` (right column) + - `highValue` (whether 2-line wrap is allowed) +- QR state in widget includes: + - `qrIteration`, `qrIterationsMax`, `qrMode`, `qrPhase` + - `qrDone`, `qrTotal`, `qrPass`, `qrFail`, `qrTodo` + +## Future Work (contracted, not yet implemented) +- Plan execution phase should reuse the same QR integrated section semantics. +- Optional compact mode for very narrow terminals can reduce metadata verbosity while preserving deterministic ordering. From 7389d46478bcb1c26f406efe9ecbc316c3eccb6e Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 25 Feb 2026 15:34:04 +0700 Subject: [PATCH 015/412] Record UI design decisions (UI-1, UI-2, UI-3) Documents the three UI design choices made on Feb 25: planning widget cards + timeline rail, deterministic dense log grid, and QR integrated section (not sidecar). --- design-decisions.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/design-decisions.md b/design-decisions.md index 132572a..a6027c4 100644 --- a/design-decisions.md +++ b/design-decisions.md @@ -218,6 +218,46 @@ Step 6: plan mutation tools unlocked. --- +## UI Decisions + +### UI-1: Planning Widget Cards & Timeline Rail +- Chosen on Feb 25 2026 via planning-widget design deck (Stacked Modular Cards + Vertical Timeline Rail). +- Rationale: make terminal output feel like a coherent operations workspace (not plain log spam), keep active progress glanceable, and preserve enough structure to scale into future phases without redesigning the shell. +- Implementation guardrails: + - Continue rendering through `canvasLine()` so the background fills full terminal width. + - Keep consistent card padding and solid-border framing through shared `renderBox()` helpers. + - Phase chips use stable semantic tokens (accent active, bold muted completed, muted pending, error failed). + - Vertical rail remains width-bounded (~20 cols) so the right detail pane keeps enough budget for high-signal telemetry. + - Detail footer (`Plan · id`) is pinned bottom via dynamic padding, independent of timeline density. + - Planning body and latest-log body share one outer card, separated by an internal divider for better cohesion. + +### UI-2: Latest Log as Deterministic Dense Grid +- Chosen on Feb 25 2026 via follow-up deck (`Declarative Shape Table` + `Two-Column Dense Grid`). +- Rationale: long-running sessions need more than tool names; users must see intent without reading full payloads. Deterministic ordering reduces scan friction and makes anomalies obvious over time. +- Contract: + - Left column anchor is always tool name. + - Right column is deterministic summary from shape-table formatters (ID-first ordering for recognized tools). + - Unknown tools degrade to name-only output (generic fallback). + - Arrays render as first-item-plus-count; free-form fields render as size-only metadata. + - Getter tools include target metadata + response size (`resp:42L/3.1k`). + - Repeated events remain repeated (no collapse), preserving temporal audit fidelity. + - Column widths adapt to terminal width and observed tool-name lengths so detail space stays useful. + - In integrated mode, latest-log columns are forced to the same split as the planning body (`timelineWidth` / `detailWidth`) to keep vertical alignment stable. + - High-value rows may wrap to 2 lines only; deeper overflow is compacted with ellipsis to protect fixed card height. + +### UI-3: QR Integrated Section (Not Sidecar) +- Chosen on Feb 25 2026 via follow-up deck (`Inline Integrated Section + Divider`). +- Rationale: QR is the acceptance loop, not optional telemetry. Rendering it as an inline first-class section prevents the "detached widget" feel and matches how users reason about plan quality over time. +- Contract: + - QR is visible during Plan design (and contractually Plan execution), hidden only for Context gathering. + - Iteration 1 enters `execute` immediately (same stage model as fix iterations); there is no separate `initializing` stage. + - Section includes: phase + iter/mode metadata, phase rail, and counters (`done/total/pass/fail/todo`) in a compact metadata block. + - Visual treatment uses inline sectioning + divider, not a nested bordered mini-card. + - Geometry is fixed for scan consistency: header + rail + counters + divider. + - Metadata uses a hard 64-char visible-width budget with progressive compaction (`exec/decomp/vfy`, `d/p/f/t`, `iN/M`) under narrow widths. + - Counter line emphasizes severity (`fail` highlighted in error color) so blocking issues pop in long sessions. + - Detail pane hierarchy is explicit: `Current step` label first, then step body, then QR section. + ## Workflow Dispatch Architecture ### WorkflowDispatch (dispatch pattern) From 241e9818372fbbbfe7c8f1e2c1886628c5889fb3 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 25 Feb 2026 15:34:09 +0700 Subject: [PATCH 016/412] Add QR failure handling analysis documents Analysis of how QR failures halt execution in plan-design and how the fix loop implements severity de-escalation across iterations. --- QR_ANALYSIS.md | 643 +++++++++++++++++++++++++++++++++++ QR_ANALYSIS_COMPREHENSIVE.md | 640 ++++++++++++++++++++++++++++++++++ 2 files changed, 1283 insertions(+) create mode 100644 QR_ANALYSIS.md create mode 100644 QR_ANALYSIS_COMPREHENSIVE.md diff --git a/QR_ANALYSIS.md b/QR_ANALYSIS.md new file mode 100644 index 0000000..54ffc1f --- /dev/null +++ b/QR_ANALYSIS.md @@ -0,0 +1,643 @@ +# QR Failure Handling & Fix Mode Analysis + +## Executive Summary + +This document analyzes how QR (Quality Review) failures halt execution in the koan plan-design phase and how the reference executor implements fix loops. The analysis covers three key questions: + +1. **Does QR failure halt the plan-design phase?** YES -- failures trigger a deterministic gate that either spawns a fix loop or force-proceeds after max iterations. +2. **What is the plan specification for QR fix loops?** Architect is re-spawned with `--koan-fix` flag and a QR failure report appended to context. +3. **What are the executor modes?** Initial mode (first-time work) vs. fix mode (targeted repair after QR failures). + +--- + +## Part 1: QR Failure Halts Execution (Confirmed) + +### How the QR Gate Works (Reference Executor) + +The reference executor in `~/.claude/skills/scripts/skills/planner/orchestrator/executor.py` implements a **9-step workflow** for execution (not planning): + +``` +Step 1: Execution Planning (analyze, build wave list) +Step 2: Reconciliation (validate existing code) +Step 3: Implementation (dispatch developers) +Step 4: Code QR (quality review of code) +Step 5: Code QR GATE (route pass/fail) <-- HALTS on FAIL +Step 6: Documentation (TW pass) +Step 7: Doc QR (quality review of docs) +Step 8: Doc QR GATE (route pass/fail) <-- HALTS on FAIL +Step 9: Retrospective +``` + +**Key excerpt from executor.py:** + +```python +CODE_QR_GATE = GateConfig( + qr_name="Code QR", + work_step=3, # If FAIL: loop back to step 3 + pass_step=6, # If PASS: advance to step 6 + pass_message="Code quality verified. Proceed to documentation.", + fix_target=AgentRole.DEVELOPER, # Developer fixes issues +) + +def format_gate(step: int, gate: GateConfig, qr: QRState, total_steps: int) -> str: + """Format gate step output.""" + if qr.passed: + next_cmd = f"python3 -m {MODULE_PATH} --step {gate.pass_step}" + else: + next_iteration = qr.iteration + 1 + next_cmd = f"python3 -m {MODULE_PATH} --step {gate.work_step} --qr-fail --qr-iteration {next_iteration}" + return format_step(body, next_cmd, title=f"{gate.qr_name} Gate") +``` + +**Execution halts on FAIL** because: +- QR GATE step 5 checks `qr.passed` property +- If FAIL: routes back to step 3 (implementation) with `--qr-fail` flag +- Step 3 detects fix mode and spawns developer with targeted repair instructions +- No automatic proceed to step 6 (documentation) + +### How the QR Gate Works (Koan Plan-Design) + +The koan project applies the same pattern to the plan-design phase. Based on the plan specification (section 4.2 and 5): + +``` +Plan-Design Phase (Architect): + ├─ execution: spawn architect subagent + │ (6-step exploration + plan writing) + │ + ├─ qr-decompose: spawn decomposer subagent + │ (13-step QR item generation) + │ + ├─ qr-verify: pool of reviewer subagents + │ (parallel verification, PASS/FAIL per item) + │ + └─ gate (deterministic code, no LLM) + PASS -> advance to plan-code + FAIL -> re-spawn architect with fix report (up to 5x) + iteration escalates severity filtering + after 5 iterations, force-proceed +``` + +**Plan specification (section 4.2.1 "QR Gate"):** + +```typescript +function routeGate( + phase: Phase, + qrResult: "pass" | "fail", + iteration: number, +): NextStep { + if (qrResult === "pass") { + deleteQRState(phase); + return nextPhase(phase); + } + const maxIterations = 5; + if (iteration >= maxIterations) { + return nextPhase(phase); // Force proceed, document remaining issues + } + return { phase, subPhase: "execution", mode: "fix", iteration: iteration + 1 }; +} +``` + +**Execution halts on FAIL** because: +- Gate routing is deterministic (pure code, no LLM) +- FAIL does not auto-advance +- Only PASS or max-iterations advances to next phase +- Fix mode spawns architect fresh with failure report + +--- + +## Architecture Pattern (From Old System) + +### Two-Phase Workflow Pattern + +QR operates in two distinct phases per plan phase (plan-design, plan-code, plan-docs, impl-code, impl-docs): + +1. **DECOMPOSITION** (QR Decompose) + - 8-step LLM workflow generating atomic verification items + - Creates `qr-{phase}.json` with items array + - Each item: `{id, scope, check, status: "TODO", severity, [parent_id], [group_id]}` + - Grouping logic (steps 9-13) organizes items by: parent-child, umbrella, component, concern, affinity + +2. **VERIFICATION** (QR Verify) + - Parallel dispatch of single items via `--qr-item` flag + - Each subagent verifies ONE item (ANALYZE -> CONFIRM -> SUMMARY pattern) + - Atomic mutation via `cli/qr.py` with file locking (no race conditions) + - Output: one-word PASS/FAIL only (findings in CLI --finding flag) + +### Key Files in Old System + +**Decomposition Scripts:** +- `/Users/lmergen/.claude/skills/scripts/skills/planner/quality_reviewer/plan_design_qr_decompose.py` +- `plan_code_qr_decompose.py` +- `plan_docs_qr_decompose.py` +- Shared: `skills/planner/quality_reviewer/prompts/decompose.py` (8-step workflow, grouping logic) + +**Verification Base:** +- `skills/planner/quality_reviewer/qr_verify_base.py` (VerifyBase class, step routing, item loading) +- Specific: `plan_design_qr_verify.py`, `plan_code_qr_verify.py`, `plan_docs_qr_verify.py` +- Shared: `skills/planner/shared/qr/utils.py` (load_qr_state, get_qr_item, format_qr_item_for_verification) + +**CLI Tools:** +- `skills/planner/cli/qr.py` (update-item with file locking) +- `skills/planner/cli/qr_commands.py` (update_item function, atomic write) + +## Decomposition Workflow (8 Steps) + +### Step 1: Absorb Context +- Load context.json and plan.json from STATE_DIR +- Parse planning context (overview, constraints, invisible knowledge) +- Task: Summarize in 2-3 sentences what success looks like for this phase + +### Step 2: Holistic Concerns (Top-Down) +- Brainstorm concerns specific to the phase (out-of-scope items explicitly excluded) +- Phase-specific examples (e.g., plan-design: "Missing decisions", "Policy defaults without backing") +- Output: Bulleted list, quantity over quality + +### Step 3: Structural Enumeration (Bottom-Up) +- List plan elements that exist in plan.json +- Use IDs where available (DL-001, M-001, etc.) +- Phase-specific (e.g., plan-design: decisions, constraints, risks, milestones, code_intents) + +### Step 4: Gap Analysis (Shared) +- Compare Step 2 concerns vs Step 3 elements +- Identify gaps: concerns not covered by elements, elements with no concerns +- Output: Umbrella vs specific items, cross-cutting vs targeted + +### Step 5: Generate Items (Phase-Specific Severity) +- Create verification items with UMBRELLA + SPECIFIC pattern +- Assign severity (MUST/SHOULD/COULD per phase-specific rules) +- Format: `{id, scope, check, status: "TODO", severity}` + +### Step 6: Atomicity Check (Shared) +- Review each item for atomicity (tests ONE thing, unambiguous pass/fail) +- Split non-atomic MUST items into parent + children (qa-002 -> qa-002a, qa-002b) +- Children inherit parent's severity, have parent_id field + +### Step 7: Coverage Validation (Shared) +- Use Step 3 enumeration as checklist +- Verify each element has at least one item covering it +- Verify each concern from Step 2 has at least one item +- Add items if gaps found (prefer over-coverage) + +### Step 8: Finalize +- Write qr-{phase}.json to STATE_DIR +- Format: `{phase, iteration: 1, items: [...]}` +- No fixed item count; content-driven + +### Steps 9-13: Grouping (Shared) +- **Step 9:** Structural grouping (deterministic: parent-child resolution, umbrella batching) +- **Step 10:** Component grouping (items verifying different aspects of same element) +- **Step 11:** Concern grouping (items checking same quality dimension across elements) +- **Step 12:** Affinity grouping (semantic similarity for remaining items) +- **Step 13:** Final validation (naming conventions, large group review, singleton review) + +## Phase-Specific Prompts + +### Plan-Design Phase + +**Step 1 Absorb:** +``` +Read plan.json from STATE_DIR: + cat $STATE_DIR/plan.json | jq '.' + +SCOPE: Plan structure and decision quality. + +Focus on: + - planning_context.decisions (completeness, reasoning quality) + - planning_context.constraints (all documented?) + - planning_context.risks (identified and addressed?) + - milestones[].code_intents (structure present?) + - invisible_knowledge (captured?) + +OUT OF SCOPE (verified in later phases): + - Code correctness (plan-code phase) + - Documentation quality (plan-docs phase) +``` + +**Step 2 Concerns:** +``` +Brainstorm concerns specific to PLAN STRUCTURE: + - Missing decisions (non-obvious choices not logged) + - Policy defaults without user backing + - Orphan milestones (no code_intents) + - Invalid references (decision_refs point nowhere) + - Reasoning chains too shallow + - Risks identified but not addressed + +DO NOT brainstorm code or documentation concerns (out of scope) +``` + +**Step 3 Enumeration:** +``` +For plan-design, enumerate PLAN STRUCTURE ARTIFACTS: + +DECISIONS: + - Each decision in planning_context.decisions (ID, decision text) + - Has reasoning? Multi-step chain? + +CONSTRAINTS: + - Each constraint in planning_context.constraints (ID, type) + - User-specified or inferred? + +RISKS: + - Each risk in planning_context.risks (ID, risk text) + - Has mitigation? + +MILESTONES: + - Each milestone (ID, name, count of code_intents) + - Each code_intent with decision_refs (ID, which decisions referenced) + +INVISIBLE KNOWLEDGE: + - system, invariants[], tradeoffs[] content +``` + +**Step 5 Severity (Plan-Design):** +``` +SEVERITY ASSIGNMENT (per conventions/severity.md, plan-design scope): + + MUST (blocks all iterations): + - DIAGRAM categories: + * ORPHAN_NODE: node with zero edges + * INVALID_EDGE_REF: edge references missing node + * INVALID_SCOPE_REF: scope references non-existent milestone + - KNOWLEDGE subset: + * DECISION_LOG_MISSING: non-trivial choice without logged rationale + * POLICY_UNJUSTIFIED: policy default without Tier 1 backing + * ASSUMPTION_UNVALIDATED: architectural assumption without citation + + SHOULD (iterations 1-4): + - Shallow reasoning chains (premise without implication) + - Missing risk mitigations + - Incomplete constraint documentation + + COULD (iterations 1-3): + - Cosmetic plan formatting + - Minor inconsistencies in naming +``` + +**Component Examples:** +``` + - A milestone + - A major decision + - A constraint category +``` + +**Concern Examples:** +``` + - Reasoning chain quality + - Reference integrity + - Risk coverage +``` + +### Plan-Code Phase + +**Step 1 Absorb:** +``` +Read plan.json from STATE_DIR: + cat $STATE_DIR/plan.json | jq '.' + +SCOPE: Code correctness in planned changes. + +Focus on: + - milestones[].code_intents[] -- what changes are intended + - milestones[].code_changes[] -- actual diff content + - code_changes[].diff (context lines must match codebase) + - code_changes[].why_comments[].decision_ref (refs must exist) + +OUT OF SCOPE (already verified in plan-docs phase): + - Documentation quality (temporal contamination, WHY-not-WHAT) + - README/CLAUDE.md content + - Invisible knowledge coverage +``` + +**Step 2 Concerns:** +``` +Brainstorm concerns specific to CODE CORRECTNESS: + - Context lines don't match actual codebase + - Diff format violations (missing +/- prefixes, wrong line counts) + - Code_intents without corresponding code_changes + - Invalid decision_refs in why_comments + - Type errors, missing imports, API mismatches + - Convention violations (per project style) + +DO NOT brainstorm documentation concerns (out of scope for this phase). +``` + +**Step 3 Enumeration:** +``` +For plan-code, enumerate CODE CHANGE ARTIFACTS: + +INTENTS: + - Each milestone's code_intents (ID, description) + - Intent-to-change mapping (which intents have changes?) + +CHANGES: + - Each code_change (ID, file path, line range) + - Files touched across all changes + - Context line locations requiring verification + +REFERENCES: + - decision_refs in why_comments (do they exist in planning_context?) + +DO NOT enumerate: + - documentation{} fields (plan-docs's job) + - readme_entries (plan-docs's job) +``` + +**Step 5 Severity (Plan-Code):** +``` +SEVERITY ASSIGNMENT (per conventions/severity.md, plan-code scope): + + MUST (blocks all iterations): + - ASSUMPTION_UNVALIDATED: architectural assumption without citation + - MARKER_INVALID: intent marker without valid explanation + - decision_ref references non-existent decision + + SHOULD (iterations 1-4) - STRUCTURE categories: + - GOD_OBJECT: >15 methods OR >10 deps + - GOD_FUNCTION: >50 lines OR >3 nesting + - CONVENTION_VIOLATION: violates documented project convention + - TESTING_STRATEGY_VIOLATION: tests don't follow confirmed strategy + + COULD (iterations 1-3) - COSMETIC: + - TOOLCHAIN_CATCHABLE: errors the compiler/linter would flag + - FORMATTER_FIXABLE: style issues fixable by formatter + - DEAD_CODE: unused functions, impossible branches + +DO NOT use KNOWLEDGE categories for documentation issues -- +those are plan-docs's responsibility. +``` + +**Component Examples:** +``` + - A file being modified + - A module/package + - A code_intent cluster +``` + +**Concern Examples:** +``` + - Error handling consistency + - Type safety across boundaries + - Testing boundary clarity +``` + +### Plan-Docs Phase + +**Step 1 Absorb:** +Similar structure, focus on doc_diff fields in code_changes + +**Step 2 Concerns:** +- Temporal contamination in doc_diffs (change-relative language) +- Baseline references (documentation assumes prior state) +- doc_diffs missing for non-empty diffs +- decision_refs in doc_diffs not captured + +**Step 3 Enumeration:** +- doc_diff content per code_change +- documentation{} fields (function docstrings, module comments) +- readme_entries content +- decision_log coverage in documentation + +**Step 5 Severity (Plan-Docs):** +Only KNOWLEDGE categories (TW cannot fix code): +- TEMPORAL_CONTAMINATION +- BASELINE_REFERENCE (doc assumes prior state) +- MISSING_DOC_DIFF (diff present, doc_diff absent) +- DECISION_UNCOVERED (decision not referenced in any doc_diff) + +## Verification Workflow (Per-Item Parallelization) + +### Base Class: VerifyBase + +Handles: +1. Step type routing (CONTEXT, ANALYZE, CONFIRM, SUMMARY) +2. Item loading from qr-{phase}.json +3. Dynamic step formula: `total_steps = 1 + (2 * num_items) + 1` + - Step 1: CONTEXT (load shared state) + - Steps 2..2N+1: ANALYZE/CONFIRM pairs per item + - Final step: SUMMARY + +### CONTEXT Step +- Load conventions, phase rules, context.json, plan.json +- List all items to verify +- Display severity and scope for each + +### ANALYZE Step (Per Item) +- Explore codebase if needed +- Form preliminary conclusion (PASS or FAIL) +- Task output: narrative analysis (no tool call yet) + +### CONFIRM Step (Per Item) +- Verify confidence in preliminary conclusion +- Execute CLI command to record result: + ```bash + python3 -m skills.planner.cli.qr --state-dir {state_dir} --qr-phase {phase} \ + update-item {item_id} --status PASS + ``` + Or: + ```bash + python3 -m skills.planner.cli.qr --state-dir {state_dir} --qr-phase {phase} \ + update-item {item_id} --status FAIL --finding '' + ``` +- Tool call blocks until file lock released (atomic update) + +### SUMMARY Step +- Count results, output single word: PASS or FAIL +- EXACT FORMAT REQUIRED: + - Output EXACTLY ONE WORD: "PASS" or "FAIL" + - No markdown headers (##, **) + - No "VERDICT:" prefix + - No explanation, prose, or reasoning + - Findings go in --finding flag, NOT in output + +## Phase-Specific Verification Guidance + +### Plan-Design Verification + +**Macro Check (scope: "\*"):** +``` +MACRO CHECK - Verify across entire plan.json: + + Read plan.json: + cat {state_dir}/plan.json | jq '.' +``` + +**Milestone Check (scope: "milestone:M-001"):** +``` +MILESTONE CHECK - Focus on M-001: + + Read milestone: + cat {state_dir}/plan.json | jq '.milestones[] | select(.id == "M-001")' +``` + +**Code Intent Check (scope: "code_intent:CI-M-001-001"):** +``` +CODE INTENT CHECK - Focus on CI-M-001-001: + + Read intent (find containing milestone first): + cat {state_dir}/plan.json | jq '.milestones[].code_intents[] | select(.id == "CI-M-001-001")' +``` + +**Check-Specific Guidance:** + +Decision Log Verification: +``` +DECISION LOG VERIFICATION: + - Each entry should have multi-step reasoning + - BAD: 'Polling | Webhooks unreliable' + - GOOD: 'Polling | 30% webhook failure -> need fallback anyway' +``` + +Policy Default Verification: +``` +POLICY DEFAULT VERIFICATION: + - Policy defaults affect user/org (lifecycle, capacity, failure handling) + - Must have Tier 1 (user-specified) backing in decision_log + - Technical defaults can use Tier 2-3 backing +``` + +Code Intent Verification: +``` +CODE INTENT VERIFICATION: + - Each implementation milestone needs code_intents + - Each code_intent needs file path and behavior + - decision_refs should point to valid decision_log entries +``` + +### Plan-Code Verification + +Similar structure with code-specific checks: +- Context line verification (diff patterns exist in actual files) +- Diff format validation (RULE 0/1/2) +- Intent linkage (code_change.intent_ref valid) +- Decision ref validity +- Temporal contamination in comments +- WHY-not-WHAT quality + +### Plan-Docs Verification + +Doc-specific checks: +- Temporal contamination in doc_diffs +- Baseline references (doc assumes prior state) +- Code without docs (diff present, doc_diff absent) +- Invalid diff format +- Decision coverage in docs +- WHY-not-WHAT verification +- Missing docstrings + +## Data Structures + +### QR Item (qr-{phase}.json) + +```typescript +interface QRItem { + id: string; // e.g., "plan-001", "qa-002a" + scope: string; // "*" (macro) or "element:ID" or "file:path" + check: string; // Description of what to verify + status: "TODO" | "PASS" | "FAIL"; + severity?: "MUST" | "SHOULD" | "COULD"; // Default: "SHOULD" + finding?: string; // Only for FAIL status + parent_id?: string; // For split items (qa-002a has parent_id: "qa-002") + group_id?: string; // For grouping (umbrella, component-*, concern-*, affinity-*, parent-*) + version?: number; // Default: 1, incremented on each update +} + +interface QRState { + phase: string; // "plan-design", "plan-code", etc. + iteration: number; // Current iteration (1 on first decompose) + items: QRItem[]; +} +``` + +### Severity Blocking Rules + +Per iteration: +- Iteration 1: MUST blocks all 4 iterations of fixes, SHOULD blocks iterations 1-4, COULD blocks 1-3 +- Iteration 2: MUST blocks iterations 2-5, SHOULD blocks 2-5, COULD blocks 2-4 +- Iteration 3: MUST blocks iterations 3-6, SHOULD blocks 3-6, COULD blocks 3-5 +- Iteration 4: MUST blocks iterations 4+, SHOULD blocks 4+, COULD blocks 4+ +- After iteration 4: No blocking (move to manual review) + +## Integration with Koan Architecture + +### Expected File Structure +``` +src/planner/phases/ + qr/ + decompose/ + phase.ts # QRDecomposePhase class (8-step workflow) + prompts.ts # Phase-specific step prompts + verify/ + phase.ts # QRVerifyPhase class (item-based verification) + prompts.ts # Verification guidance per phase + lib/ + items.ts # QRItem type, load/save, atomic mutations + grouping.ts # Steps 9-13 grouping logic +``` + +### Phase Registration +```typescript +// In phases/dispatch.ts +if (config.role === "quality-reviewer" && config.phase === "plan-design") { + const phase = new QRDecomposePhase(...); + await phase.begin(); +} +``` + +### Tool Registration +- QR tools likely smaller subset than plan-design (mainly read tools, no plan mutations) +- Tools may include: qr_update_item (atomic write), qr_load_state (read), qr_get_item (lookup) + +## Critical Implementation Notes + +### 1. Decomposition is Single-Run +- Decompose runs ONCE per phase (steps 1-8, 9-13) +- Orchestrator skips decompose if qr-{phase}.json already exists with iteration >=1 +- Each phase has own decomposition script (can't share due to phase-specific prompts) + +### 2. Verification is Parallel +- Each item dispatched as separate subagent with --qr-item flag +- File locking in CLI prevents race conditions +- No shared state mutation; each agent writes its own result atomically + +### 3. Step Gates Must Use Blocklists +- Whitelist fails open (blocks read tools unintentionally) +- Blocklist defers to checkPermission for everything not explicitly gated +- Example: `if (step < 6 && PLAN_MUTATION_TOOLS.has(name)) { block }` + +### 4. Findings in CLI Flag, Not Output +- Tool result is NOT return value; findings go in `--finding` flag +- SUMMARY step outputs ONE WORD only (PASS or FAIL) +- This avoids "text + tool_call in same response" bug (GPT-5-codex) + +### 5. invoke_after Two-Part Gate +- Every step prompt ends with "WHEN DONE: call koan_complete_step" +- Tool description includes "Do NOT call until told" +- Dual gates ensure single transition per step + +### 6. Disk-Backed Mutations +- Every tool mutation writes qr-{phase}.json immediately +- No finalize pattern; descriptive feedback on each write +- This prevents LLM from skipping intermediate mutations + +### 7. Severity Blocking vs Iteration Count +- Blocking set determined at gate time, not item creation time +- by_blocking_severity(iteration) is a predicate factory +- Iteration 0 not used; iteration 1 is first decompose, iteration 2+ are retries + +## Migration Checklist + +- [ ] Create QRDecomposePhase class with 8-step + 5-step grouping workflow +- [ ] Implement phase-specific prompts for plan-design, plan-code, plan-docs +- [ ] Create QRVerifyPhase class with CONTEXT/ANALYZE/CONFIRM/SUMMARY routing +- [ ] Implement VerifyBase-like step mapping (total_steps formula, item routing) +- [ ] Implement atomic QRItem mutations with file locking +- [ ] Add qr_update_item tool (wrapper around file-locked write) +- [ ] Add qr_load_state, qr_get_item tools (read-only) +- [ ] Register phases in dispatch.ts for quality-reviewer role +- [ ] Add QR phase detection to before_agent_start handler +- [ ] Implement SUMMARY step output validation (one word only) +- [ ] Test decompose single-run enforcement (skip if iteration >=1) +- [ ] Test parallel verify with file locking (concurrent writes) +- [ ] Test severity blocking at iteration thresholds +- [ ] Copy exact prompts from Python scripts (no rewriting) diff --git a/QR_ANALYSIS_COMPREHENSIVE.md b/QR_ANALYSIS_COMPREHENSIVE.md new file mode 100644 index 0000000..29b04ff --- /dev/null +++ b/QR_ANALYSIS_COMPREHENSIVE.md @@ -0,0 +1,640 @@ +# QR Failure Handling & Fix Mode Analysis + +## Executive Summary + +This document analyzes how QR (Quality Review) failures halt execution in the koan plan-design phase and how the reference executor implements fix loops. The analysis covers three key questions: + +1. **Does QR failure halt the plan-design phase?** YES -- failures trigger a deterministic gate that either spawns a fix loop or force-proceeds after max iterations. +2. **What is the plan specification for QR fix loops?** Architect is re-spawned with `--koan-fix` flag and a QR failure report appended to context. +3. **What are the executor modes?** Initial mode (first-time work) vs. fix mode (targeted repair after QR failures). + +--- + +## Part 1: QR Failure Halts Execution (Confirmed) + +### How the QR Gate Works (Reference Executor) + +The reference executor in `~/.claude/skills/scripts/skills/planner/orchestrator/executor.py` implements a **9-step workflow** for execution: + +``` +Step 1: Execution Planning (analyze, build wave list) +Step 2: Reconciliation (validate existing code) +Step 3: Implementation (dispatch developers) +Step 4: Code QR (quality review of code) +Step 5: Code QR GATE (route pass/fail) <-- HALTS on FAIL +Step 6: Documentation (TW pass) +Step 7: Doc QR (quality review of docs) +Step 8: Doc QR GATE (route pass/fail) <-- HALTS on FAIL +Step 9: Retrospective +``` + +**Key excerpt from executor.py:** + +```python +CODE_QR_GATE = GateConfig( + qr_name="Code QR", + work_step=3, # If FAIL: loop back to step 3 + pass_step=6, # If PASS: advance to step 6 + pass_message="Code quality verified. Proceed to documentation.", + fix_target=AgentRole.DEVELOPER, # Developer fixes issues +) + +def format_gate(step: int, gate: GateConfig, qr: QRState, total_steps: int) -> str: + """Format gate step output.""" + if qr.passed: + next_cmd = f"python3 -m {MODULE_PATH} --step {gate.pass_step}" + else: + next_iteration = qr.iteration + 1 + next_cmd = f"python3 -m {MODULE_PATH} --step {gate.work_step} --qr-fail --qr-iteration {next_iteration}" + return format_step(body, next_cmd, title=f"{gate.qr_name} Gate") +``` + +**Execution halts on FAIL** because: +- QR GATE step 5 checks `qr.passed` property +- If FAIL: routes back to step 3 (implementation) with `--qr-fail` flag +- Step 3 detects fix mode and spawns developer with targeted repair instructions +- No automatic proceed to step 6 (documentation) + +### How the QR Gate Works (Koan Plan-Design) + +The koan project applies the same pattern. Based on the plan specification (section 4.2 and 5 of plans/2026-02-10-init.md): + +``` +Plan-Design Phase (Architect): + ├─ execution: spawn architect subagent + │ (6-step exploration + plan writing) + │ + ├─ qr-decompose: spawn decomposer subagent + │ (13-step QR item generation) + │ + ├─ qr-verify: pool of reviewer subagents + │ (parallel verification, PASS/FAIL per item) + │ + └─ gate (deterministic code, no LLM) + PASS -> advance to plan-code + FAIL -> re-spawn architect with fix report (up to 5x) + iteration escalates severity filtering + after 5 iterations, force-proceed +``` + +**Plan specification routing logic (section 4.2.1):** + +```typescript +function routeGate( + phase: Phase, + qrResult: "pass" | "fail", + iteration: number, +): NextStep { + if (qrResult === "pass") { + deleteQRState(phase); + return nextPhase(phase); + } + const maxIterations = 5; + if (iteration >= maxIterations) { + return nextPhase(phase); // Force proceed, document remaining issues + } + return { phase, subPhase: "execution", mode: "fix", iteration: iteration + 1 }; +} +``` + +**Execution halts on FAIL** because: +- Gate routing is deterministic (pure code, not prompt-based) +- FAIL does not auto-advance +- Only PASS or max-iterations advances to next phase +- Fix mode spawns architect fresh with failure report + +--- + +## Part 2: Plan Specification for QR Fix Loops + +### Fix Mode Activation + +From plan section 4.2 "First attempt vs. fix mode": + +> When a phase's QR gate returns FAIL, the orchestrator re-spawns the subagent with an additional flag (`--koan-fix`) and appends the QR failure report to the context file. The subagent's role hooks detect fix mode and adjust step instructions to focus on fixing specific issues identified by the QR. + +**Mechanism:** + +1. **Gate detects FAIL** → compute `iteration + 1` +2. **Orchestrator spawns subagent** with: + - `--koan-fix` flag (new) + - `--koan-fix-iteration N` flag (new) + - Same `--koan-plan-dir` (plan.json + context.json + qr-plan-design.json all present) +3. **Context file is mutated** to append QR failures: + - Original 8 context categories remain (read-only) + - QR failures appended in a new `qr_failures` section +4. **Role hooks detect fix mode** via flags in `before_agent_start` +5. **Step instructions adjust** to focus on fixing + +### Reference Architect Fix Prompt + +The reference architect fix script is `~/.claude/skills/scripts/skills/planner/architect/plan_design_qr_fix.py` (3-step workflow): + +**Step 1: Load QR Failures** + +``` +FIX MODE - QR Iteration {qr_iteration} + +QR-COMPLETENESS found issues in the plan. + +FAILED QR ITEMS TO FIX (address these FIRST): +================================================ +[plan-001] Decision log completeness + Scope: decision_log entry DL-005 + Finding: Decision reference missing backing premise + +[plan-002] Code intent specification + Scope: code_intent id CI-M-001-001 + Finding: Behavior description incomplete (unclear acceptance criteria) + +================================================ + +PLANNING CONTEXT (reference for semantic validation): +(context.json displayed for validation reference) + +For EACH failed item: + 1. Read the 'finding' field to understand the issue + 2. Identify what in plan.json needs to change + 3. Note the fix approach for step 2 +``` + +**Step 2: Apply Targeted Fixes** + +``` +APPLY targeted fixes to plan.json using CLI commands. + +Missing decision_log entry: + python3 -m skills.planner.cli.plan --state-dir $STATE_DIR set-decision \ + --decision '' \ + --reasoning ' implication -> conclusion>' + +BATCH MODE (preferred): + python3 -m skills.planner.cli.plan --state-dir $STATE_DIR batch '[ + {"method": "set-decision", "params": {...}, "id": 1}, + {"method": "set-intent", "params": {...}, "id": 2} + ]' + +CONSTRAINT: Fix ONLY the failing items. Don't refactor passing items. +``` + +**Step 3: Validate Fixes** + +``` +Run structural validation: + python3 -m skills.planner.cli.plan validate --phase plan-design + +SELF-CHECK each fixed item: + For each FAIL item you addressed: + - Does the fix address the specific finding? + - Does the fix introduce new issues? + +If validation passes: + Your complete response must be exactly: PASS + Do not add summaries, explanations, or any other text. +``` + +### Key Design Points in Fix Mode + +1. **QR failures explicitly listed** -- The architect sees exactly which items failed + why (the "finding" field) +2. **Plan mutations via existing CLI** -- Fix mode doesn't add new mutation tools, just focuses the prompt on specific items +3. **Targeted not holistic** -- Fix mode does NOT re-explore codebase. It reads the QR report and applies surgical fixes. +4. **No flailing** -- The constraint "Fix ONLY the failing items" prevents second-guessing the entire plan +5. **Validation is mandatory** -- Each fix iteration must pass `python3 -m ... validate` before reporting PASS + +### Iteration Escalation with Severity Filtering + +QR items have a `severity` field: MUST | SHOULD | COULD + +**Severity filtering logic (implied by shared/qr/constants.py):** + +```python +def get_blocking_severities(iteration: int) -> Set[str]: + """Items that block at this iteration. + + iteration 1: MUST only + iteration 2: MUST, SHOULD + iteration 3+: MUST, SHOULD, COULD (all) + """ +``` + +**Meaning:** On iteration 1, only critical (MUST) items block. By iteration 3, even minor (COULD) items block. This escalates pressure to fix progressively more issues. + +--- + +## Part 3: Executor Modes (Initial vs. Fix) + +### Reference Executor: Initial Mode + +When a phase is first executed (no prior failures): + +**Step 3: Implementation (Initial Mode)** + +```python +def format_step_3_implementation(qr: QRState, total_steps: int, ...) -> str: + if qr.state == LoopState.RETRY: + # Fix mode (handled separately) + ... + else: + # Initial mode + actions.extend([ + "Execute ALL milestones using wave-aware parallel dispatch.", + "", + "WAVE-AWARE EXECUTION:", + " - Milestones within same wave: dispatch in PARALLEL", + " - Waves execute SEQUENTIALLY", + "", + "FOR EACH WAVE:", + " 1. Dispatch developer agents for ALL milestones in wave", + " 2. Each prompt includes: plan, milestone, files, acceptance criteria", + " 3. Wait for ALL agents in wave to complete", + " 4. Run tests: pytest / tsc / go test -race", + " 5. Proceed to next wave", + "", + "After ALL waves complete, proceed to Code QR.", + ]) +``` + +**Initial mode** is the "full breadth" mode: +- No prior failures to fix +- Execute all milestones +- Waves in sequence, milestones within wave in parallel +- Standard tests + validation + +### Reference Executor: Fix Mode + +When a QR gate returns FAIL and iteration < 5: + +**Step 3: Implementation (Fix Mode)** + +```python +def format_step_3_implementation(qr: QRState, total_steps: int, ...) -> str: + if qr.state == LoopState.RETRY: + actions.append(format_state_banner("IMPLEMENTATION FIX", qr.iteration, "fix")) + actions.append("FIX MODE: Code QR found issues.") + actions.append("") + + mode_script = get_mode_script_path("dev/fix-code.py") + invoke_cmd = f"python3 -m {mode_script} --step 1 --qr-fail --qr-iteration {qr.iteration}" + + actions.append(subagent_dispatch( + agent_type="developer", + command=invoke_cmd, + )) + actions.append("Developer reads QR report and fixes issues in blocks.") + actions.append("After developer completes, re-run Code QR for fresh verification.") +``` + +**Fix mode** is the "targeted repair" mode: +- QR failures are present (in memory and on disk) +- Dispatch specialized fix agent (different script/prompts) +- Agent reads QR failure items +- Agent applies fixes to milestones mentioned in failures +- Re-run QR immediately after (fresh verification) + +### Comparison Table + +| Aspect | Initial Mode | Fix Mode | +|--------|--------------|----------| +| **Trigger** | First execution | QR FAIL (iteration < 5) | +| **Context** | No prior failures | QR items with status=FAIL + findings | +| **Scope** | All milestones | Only milestones in QR failures | +| **Agent Dispatch** | Full work agent | Specialized fix agent | +| **Step Sequence** | Role's standard N-step | 3-step fix workflow | +| **Tools Available** | Full read + write | Same tools (focus via prompt) | +| **Exit Condition** | Role completes final step | PASS to QR (no FAIL) | +| **Next** | Proceed to QR decompose | Re-run QR immediately | +| **Iteration** | N/A | 1, 2, 3, ... (max 5) | + +### How the Executor Decides Which Mode + +**Flag detection in executor.py:** + +```python +# format_step_3_implementation +state = LoopState.RETRY if qr_fail else LoopState.INITIAL + +# Gate's FAIL routing: +next_cmd = f"python3 -m {MODULE_PATH} --step {work_step} --qr-fail --qr-iteration {next_iteration}" +``` + +When gate returns FAIL, step 3 is re-invoked with `--qr-fail --qr-iteration 2`, and the formatter detects fix mode. + +--- + +## Part 4: Reference Implementation Deep Dive + +### Shared QR Infrastructure + +Located in `~/.claude/skills/scripts/skills/planner/shared/qr/`: + +**types.py:** + +```python +class QRStatus(Enum): + PASS = "pass" + FAIL = "fail" + +class LoopState(Enum): + INITIAL = "initial" + RETRY = "retry" + COMPLETE = "complete" + +@dataclass +class QRState: + iteration: int = 1 + state: LoopState = LoopState.INITIAL + status: QRStatus | None = None + + @property + def passed(self) -> bool: + return self.status == QRStatus.PASS + + def transition(self, status: QRStatus) -> None: + if status == QRStatus.PASS: + self.state = LoopState.COMPLETE + else: + self.state = LoopState.RETRY + self.iteration += 1 + +@dataclass +class GateConfig: + qr_name: str + work_step: int # Where to loop back on FAIL + pass_step: int | None # Where to go on PASS + pass_message: str + fix_target: AgentRole | None # Developer / Writer / Architect +``` + +**gates.py:** + +```python +def build_gate_output( + module_path: str, + qr_name: str, + qr: QRState, + work_step: int, + pass_step: int | None, + pass_message: str, + fix_target: AgentRole | None, + state_dir: str, +) -> GateResult: + """Build complete gate step output for QR gates. + + Gates route to either: + - pass_step: QR passed, proceed to next workflow phase + - work_step: QR failed, loop back to fix issues + """ + if qr.passed: + next_cmd = f"python3 -m {module_path} --step {pass_step}" + else: + next_cmd = f"python3 -m {module_path} --step {work_step} --state-dir {state_dir}" + + return GateResult( + output=format_step(body, next_cmd, title=title), + terminal_pass=qr.passed and pass_step is None, + ) +``` + +### How the Architect Fix Prompts Load QR Failures + +**plan_design_qr_fix.py, step 1:** + +```python +def get_step_guidance(step: int, module_path: str = None, **kwargs) -> dict: + if step == 1: + state_dir = kwargs.get("state_dir", "") + qr_iteration = get_qr_iteration(state_dir, PHASE) + + # Load failed items from qr-{phase}.json + qr_state = load_qr_state(state_dir, PHASE) + failed_items_block = format_failed_items_for_fix(qr_state) + + return { + "title": STEPS[1], + "actions": [ + f"FIX MODE - QR Iteration {qr_iteration}", + "", + "QR-COMPLETENESS found issues in the plan.", + "", + failed_items_block, # <- Explicit list of failures + "", + "For EACH failed item:", + " 1. Read the 'finding' field to understand the issue", + " 2. Identify what in plan.json needs to change", + " 3. Note the fix approach for step 2", + ], + } +``` + +**format_failed_items_for_fix output example:** + +``` +============================================================ +FAILED QR ITEMS TO FIX (address these FIRST): +============================================================ + +[QR-plan-design-001] Decision completeness + Scope: decision_log entry (id: DL-003) + Finding: Caching strategy selected but no justification. + +[QR-plan-design-002] Intent specification + Scope: code_intent (id: CI-M-001-001) + Finding: Behavior unclear: "Add caching layer" -- where? What TTL? + +[QR-plan-design-003] Risk documentation + Scope: known_risks + Finding: Redis failure mode not documented. + +============================================================ +``` + +--- + +## Part 5: Koan's QR Specification + +### Section 4.2: QR Block Pattern + +**Plan-Design Phase Structure:** + +``` +Phase 2: PLAN-DESIGN +├─ Execution (architect explores + writes plan) +├─ QR Decompose (decomposer generates items) +├─ QR Verify (reviewers verify items) +└─ Gate (route PASS->phase3 or FAIL->reexecute_with_fix) +``` + +### Section 4.2.1: QR Decomposition (13-step Workflow) + +The decomposer produces items with: +- `id`: unique item ID +- `scope`: `*` (cross-cutting) or element reference +- `check`: the verification question +- `status`: TODO | PASS | FAIL +- `finding`: explanation of FAIL (populated by reviewers) +- `severity`: MUST | SHOULD | COULD + +### Section 4.2.2: QR Verification (Parallel Subagents) + +Each reviewer subagent: +1. Receives assigned item group +2. For each item: ANALYZE -> CONFIRM -> update state +3. Returns per-item status +4. Aggregate: ANY FAIL = phase FAIL + +### Section 4.2.3: Fix Mode (Key Design Decision) + +From section 4.2: + +> When a phase's QR gate returns FAIL, the orchestrator re-spawns the subagent with an additional flag (`--koan-fix`) and appends the QR failure report to the context file. The subagent's role hooks detect fix mode and adjust step instructions to focus on fixing specific issues identified by the QR. + +--- + +## Part 6: Koan Implementation + +### Key Difference: Single Phase Handler vs. Separate Scripts + +**Reference executor:** +- `architect/plan_design_execute.py` (6 steps, first-time) +- `architect/plan_design_qr_fix.py` (3 steps, targeted repair) +- Separate scripts for each mode + +**Koan design:** +- Single `PlanDesignPhase` handler +- Phase hooks detect `--koan-fix` flag +- Step prompts adjust at runtime in the `context` event handler +- Same tools, same workflow -- just different prompt text + +### Koan Implementation Pattern (Inferred) + +```typescript +// src/planner/phases/plan-design/phase.ts + +export class PlanDesignPhase { + private state: PlanDesignState & { + fixMode: boolean; + fixIteration: number; + }; + + async begin(): Promise { + // Detect fix mode from flags + this.state.fixMode = this.pi.getFlag("koan-fix") === "true"; + this.state.fixIteration = parseInt(this.pi.getFlag("koan-fix-iteration") || "0"); + + // Load context.json (with QR failures appended if fixMode) + const contextPath = path.join(this.planDir, "context.json"); + const raw = await fs.readFile(contextPath, "utf8"); + this.state.contextData = JSON.parse(raw) as ContextData; + // context.qr_failures populated by orchestrator if fixMode + } + + private registerHandlers(): void { + this.pi.on("context", (event) => { + if (this.state.step !== 1) return undefined; + + let prompt = this.state.step1Prompt; + + // Adjust for fix mode + if (this.state.fixMode) { + prompt = adjustPromptForFixMode( + prompt, + this.state.fixIteration, + this.state.contextData.qr_failures, + ); + } + + const messages = event.messages.map((m) => + m.role === "user" ? { ...m, content: prompt } : m, + ); + return { messages }; + }); + } +} + +function adjustPromptForFixMode( + basePrompt: string, + iteration: number, + failures: Array<{id: string; scope: string; finding: string}>, +): string { + // Replace exploration sections with fix guidance + // Prepend: list of failed items + findings + // Add constraint: "Fix ONLY these items" + // Add validation guidance +} +``` + +### Orchestrator-Side: Appending QR Failures to Context + +When gate returns FAIL: + +```typescript +// 1. Load qr-plan-design.json +const qrPath = path.join(planDir, "qr-plan-design.json"); +const qr = JSON.parse(await fs.readFile(qrPath, "utf8")); + +// 2. Filter FAIL items +const failures = qr.items.filter(item => item.status === "FAIL").map(item => ({ + id: item.id, + scope: item.scope, + finding: item.finding, +})); + +// 3. Load context.json +const contextPath = path.join(planDir, "context.json"); +const context = JSON.parse(await fs.readFile(contextPath, "utf8")); + +// 4. Append failures +context.qr_failures = failures; +context.qr_iteration = iteration; + +// 5. Write back (atomic) +await writeContext(planDir, context); + +// 6. Spawn architect in fix mode +spawn("pi", [ + "-p", + "-e", extensionPath, + "--koan-role", "architect", + "--koan-phase", "plan-design", + "--koan-plan-dir", planDir, + "--koan-fix", "true", + "--koan-fix-iteration", String(iteration), + "Fix the plan issues identified in the QR report.", +]); +``` + +--- + +## Summary Table: Initial vs. Fix Mode + +| Dimension | Initial Mode | Fix Mode | +|-----------|--------------|----------| +| **QR State** | None (first execution) | FAIL (previous iteration) | +| **Orchestrator Decision** | Execute (fresh start) | Fix (failures present) | +| **Flags** | None | `--koan-fix true --koan-fix-iteration N` | +| **Context File** | 8 categories only | ^^ + `qr_failures` array | +| **Step Sequence** | 1=analysis, 2=exploration, ..., 6=write | 1=load failures, 2=fix, 3=validate | +| **Scope** | All codebase areas relevant to task | Only areas in QR failures | +| **Tools** | Full set (read + write) | Same set (focus via prompt) | +| **Exit** | PASS to orchestrator -> QR decompose | PASS to orchestrator -> re-run QR | +| **Iteration** | Not applicable | 1, 2, 3, ... (max 5) | +| **Severity Filter** | N/A | Escalates per iteration | +| **Outcome** | plan.json artifact | Updated plan.json (surgical fixes) | + +--- + +## Conclusion + +**QR failures halt execution in koan's plan-design phase** because the QR gate is deterministic code. The gate examines the QR result and either: +1. PASS → advance to next phase +2. FAIL + iteration < 5 → spawn architect in fix mode with failure report +3. FAIL + iteration >= 5 → force-proceed to next phase + +**Fix mode is a targeted repair workflow** that differs from initial mode by: +- Running a 3-step workflow (load -> fix -> validate) instead of N-step exploration +- Reading QR failures from context + disk +- Focusing fixes on listed items only +- Escalating severity requirements each iteration + +**The reference executor provides the exact implementation patterns** that koan follows, with the improvement that koan consolidates execute/fix logic into one phase handler via prompt adjustment, rather than separate scripts. + From aa70767a8f4fc1a8ca199839e9153a47277d0902 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 25 Feb 2026 15:34:17 +0700 Subject: [PATCH 017/412] Add shape-table log formatting for koan tool events Restructures LogLine from prefix/highlight/meta to tool/summary/ highValue. Adds KOAN_SHAPES registry with per-tool key priority, array previews, freeform size stats, and getter response sizes. Unknown tools degrade to name-only. Formatted output uses deterministic ID-first key ordering for scan consistency. --- src/planner/lib/audit.ts | 248 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 232 insertions(+), 16 deletions(-) diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index aea727a..9d2f980 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -341,17 +341,114 @@ export async function readProjection(dir: string): Promise { } } -// Structured log line for the widget log card. The widget applies -// theme-aware coloring: prefix dim, highlight normal, meta dim. +// Structured log line for the widget log card. +// `tool` is the left-column scan anchor, `summary` is the right-column detail. +// High-value rows may wrap to two visual lines in the widget. export interface LogLine { - prefix: string; - highlight: string; - meta: string; + tool: string; + summary: string; + highValue: boolean; +} + +interface ToolShape { + keys: string[]; + arrays?: string[]; + freeform?: string[]; + getter?: boolean; + highValue?: boolean; } +const PREVIEW_CHARS = 40; +const KEY_PRIORITY = ["id", "milestone", "decision_ref", "intent_ref", "file", "path", "phase"]; + +const KOAN_SHAPES: Record = { + koan_get_plan: { keys: ["phase"], getter: true }, + koan_get_milestone: { keys: ["id"], getter: true }, + koan_get_decision: { keys: ["id"], getter: true }, + koan_get_intent: { keys: ["id"], getter: true }, + koan_get_change: { keys: ["id"], getter: true }, + + koan_set_overview: { keys: ["problem", "approach"], freeform: ["problem", "approach"], highValue: true }, + koan_set_constraints: { keys: ["constraints"], arrays: ["constraints"], highValue: true }, + koan_set_invisible_knowledge: { + keys: ["system", "invariants", "tradeoffs"], + freeform: ["system"], + arrays: ["invariants", "tradeoffs"], + highValue: true, + }, + + koan_add_decision: { keys: ["decision", "reasoning"], freeform: ["decision", "reasoning"], highValue: true }, + koan_set_decision: { keys: ["id", "decision", "reasoning"], freeform: ["decision", "reasoning"], highValue: true }, + koan_add_rejected_alternative: { + keys: ["decision_ref", "alternative", "rejection_reason"], + freeform: ["alternative", "rejection_reason"], + highValue: true, + }, + koan_set_rejected_alternative: { + keys: ["id", "decision_ref", "alternative", "rejection_reason"], + freeform: ["alternative", "rejection_reason"], + highValue: true, + }, + koan_add_risk: { keys: ["decision_ref", "anchor", "risk", "mitigation"], freeform: ["risk", "mitigation"], highValue: true }, + koan_set_risk: { + keys: ["id", "decision_ref", "anchor", "risk", "mitigation"], + freeform: ["risk", "mitigation"], + highValue: true, + }, + + koan_add_milestone: { + keys: ["name", "files", "flags", "requirements", "acceptance_criteria", "tests"], + arrays: ["files", "flags", "requirements", "acceptance_criteria", "tests"], + highValue: true, + }, + koan_set_milestone_name: { keys: ["id", "name"] }, + koan_set_milestone_files: { keys: ["id", "files"], arrays: ["files"], highValue: true }, + koan_set_milestone_flags: { keys: ["id", "flags"], arrays: ["flags"] }, + koan_set_milestone_requirements: { keys: ["id", "requirements"], arrays: ["requirements"], highValue: true }, + koan_set_milestone_acceptance_criteria: { keys: ["id", "acceptance_criteria"], arrays: ["acceptance_criteria"], highValue: true }, + koan_set_milestone_tests: { keys: ["id", "tests"], arrays: ["tests"], highValue: true }, + + koan_add_intent: { keys: ["milestone", "file", "function", "behavior"], freeform: ["behavior"], highValue: true }, + koan_set_intent: { keys: ["id", "file", "function", "behavior"], freeform: ["behavior"], highValue: true }, + + koan_add_change: { + keys: ["milestone", "file", "intent_ref", "diff", "doc_diff", "comments"], + freeform: ["diff", "doc_diff", "comments"], + highValue: true, + }, + koan_set_change_diff: { keys: ["id", "diff"], freeform: ["diff"], highValue: true }, + koan_set_change_doc_diff: { keys: ["id", "doc_diff"], freeform: ["doc_diff"], highValue: true }, + koan_set_change_comments: { keys: ["id", "comments"], freeform: ["comments"], highValue: true }, + koan_set_change_file: { keys: ["id", "file"], highValue: true }, + koan_set_change_intent_ref: { keys: ["id", "intent_ref"] }, + + koan_add_wave: { keys: ["milestones"], arrays: ["milestones"], highValue: true }, + koan_set_wave_milestones: { keys: ["id", "milestones"], arrays: ["milestones"], highValue: true }, + + koan_add_diagram: { keys: ["type", "scope", "title"] }, + koan_set_diagram: { keys: ["id", "title", "scope", "ascii_render"], freeform: ["ascii_render"], highValue: true }, + koan_add_diagram_node: { keys: ["diagram_id", "id", "label", "type"] }, + koan_add_diagram_edge: { keys: ["diagram_id", "source", "target", "label", "protocol"] }, + + koan_set_readme_entry: { keys: ["path", "content"], freeform: ["content"], highValue: true }, + + koan_qr_add_item: { keys: ["phase", "scope", "check", "severity"], freeform: ["check"], highValue: true }, + koan_qr_set_item: { keys: ["phase", "id", "status", "finding"], freeform: ["finding"], highValue: true }, + koan_qr_assign_group: { keys: ["phase", "group_id", "ids"], arrays: ["ids"], highValue: true }, + koan_qr_get_item: { keys: ["phase", "id"], getter: true }, + koan_qr_list_items: { keys: ["phase", "status"], getter: true }, + koan_qr_summary: { keys: ["phase"], getter: true }, + + koan_store_context: { + keys: ["task_spec", "constraints", "entry_points", "rejected_alternatives", "current_understanding", "assumptions", "invisible_knowledge", "reference_docs"], + arrays: ["task_spec", "constraints", "entry_points", "rejected_alternatives", "current_understanding", "assumptions", "invisible_knowledge", "reference_docs"], + highValue: true, + }, +}; + // Reads the tail of events.jsonl and returns structured log entries. // Filters out heartbeats (noisy). Used by session.ts to feed the widget log card. -export async function readRecentLogs(dir: string, count = 5): Promise { +export async function readRecentLogs(dir: string, count = 8): Promise { try { const raw = await fs.readFile(path.join(dir, "events.jsonl"), "utf8"); const events = raw @@ -366,27 +463,146 @@ export async function readRecentLogs(dir: string, count = 5): Promise } } -function sizeSuffix(e: { lines?: number; chars?: number }): string { - return e.lines != null ? `(${e.lines}L, ${e.chars}c)` : ""; +function formatChars(chars: number): string { + if (chars < 1000) return `${chars}c`; + const k = chars / 1000; + if (k >= 10) return `${Math.round(k)}k`; + return `${k.toFixed(1)}k`; +} + +function textStats(text: string): string { + const lines = text.length === 0 ? 0 : text.split("\n").length; + return `${lines}L/${formatChars(text.length)}`; +} + +function responseSize(response: string[]): string { + return textStats(response.join("\n")); +} + +function truncateUnicode(text: string, maxChars: number): string { + const chars = Array.from(text); + if (chars.length <= maxChars) return text; + return `${chars.slice(0, maxChars).join("")}…`; +} + +function inlineScalar(value: unknown): string { + if (typeof value === "string") { + return truncateUnicode(value.replace(/\r\n?|\n/gu, "\\n"), PREVIEW_CHARS); + } + if (typeof value === "number" || typeof value === "boolean") { + return String(value); + } + if (value === null) return "null"; + if (Array.isArray(value)) return `[${value.length}]`; + if (typeof value === "object") return "{…}"; + return String(value); +} + +function arrayPreview(value: unknown): string { + if (!Array.isArray(value) || value.length === 0) { + return "[]"; + } + const first = inlineScalar(value[0]); + if (value.length === 1) { + return `[${first}]`; + } + return `[${first}] +${value.length - 1}`; +} + +function freeformSize(value: unknown): string { + if (typeof value === "string") { + return textStats(value); + } + const json = JSON.stringify(value); + return textStats(json ?? String(value)); +} + +function hasKey(input: Record, key: string): boolean { + return Object.prototype.hasOwnProperty.call(input, key); +} + +function orderedShapeKeys(keys: string[]): string[] { + const indexed = keys.map((key, index) => ({ key, index })); + indexed.sort((a, b) => { + const pa = KEY_PRIORITY.indexOf(a.key); + const pb = KEY_PRIORITY.indexOf(b.key); + const ra = pa === -1 ? Number.MAX_SAFE_INTEGER : pa; + const rb = pb === -1 ? Number.MAX_SAFE_INTEGER : pb; + if (ra !== rb) return ra - rb; + return a.index - b.index; + }); + return indexed.map((x) => x.key); +} + +function formatKnownKoan(e: ToolKoanEvent, shape: ToolShape): LogLine { + const arrayKeys = new Set(shape.arrays ?? []); + const freeformKeys = new Set(shape.freeform ?? []); + const chunks: string[] = []; + + for (const key of orderedShapeKeys(shape.keys)) { + if (!hasKey(e.input, key)) continue; + const value = e.input[key]; + + if (arrayKeys.has(key)) { + chunks.push(`${key}:${arrayPreview(value)}`); + continue; + } + + if (freeformKeys.has(key)) { + chunks.push(`${key}:${freeformSize(value)}`); + continue; + } + + chunks.push(`${key}=${inlineScalar(value)}`); + } + + if (shape.getter) { + if (chunks.length === 0) { + chunks.push("scope=plan"); + } + chunks.push(`resp:${responseSize(e.response)}`); + } + + return { + tool: e.tool, + summary: chunks.join(" · "), + highValue: shape.highValue ?? chunks.length >= 3, + }; +} + +function formatKoanLogLine(e: ToolKoanEvent): LogLine { + const shape = KOAN_SHAPES[e.tool]; + if (!shape) { + return { tool: e.tool, summary: "", highValue: false }; + } + return formatKnownKoan(e, shape); } function formatLogLine(e: AuditEvent): LogLine { switch (e.kind) { case "phase_start": - return { prefix: "phase", highlight: e.phase, meta: `(${e.totalSteps} steps)` }; + return { tool: "phase", summary: `${e.phase} (${e.totalSteps} steps)`, highValue: false }; case "step_transition": - return { prefix: `current step ${e.step}/${e.totalSteps}:`, highlight: e.name, meta: "" }; + return { tool: `step ${e.step}/${e.totalSteps}`, summary: e.name, highValue: false }; case "phase_end": - return { prefix: "phase", highlight: e.outcome, meta: e.detail ?? "" }; + return { tool: "phase", summary: e.detail ? `${e.outcome} · ${e.detail}` : e.outcome, highValue: false }; case "tool_file": - return { prefix: e.tool, highlight: e.path, meta: sizeSuffix(e) }; + return { + tool: e.tool, + summary: e.lines != null ? `${e.path} · ${e.lines}L/${formatChars(e.chars ?? 0)}` : e.path, + highValue: e.tool === "read", + }; case "tool_bash": - return { prefix: "bash", highlight: e.bin, meta: sizeSuffix(e) }; + return { + tool: "bash", + summary: e.lines != null ? `${e.bin} · ${e.lines}L/${formatChars(e.chars ?? 0)}` : e.bin, + highValue: false, + }; case "tool_koan": - return { prefix: "koan", highlight: e.tool, meta: "" }; + return formatKoanLogLine(e); case "tool_generic": - return { prefix: "tool", highlight: e.tool, meta: "" }; + return { tool: e.tool, summary: "", highValue: false }; case "heartbeat": - return { prefix: "", highlight: "heartbeat", meta: "" }; + return { tool: "heartbeat", summary: "", highValue: false }; } } From fd891934bbc7f4f3e6c941e27c839dc9cb99193c Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 25 Feb 2026 15:34:23 +0700 Subject: [PATCH 018/412] Plumb QR counter stats into widget updates Adds qrDone/qrTotal/qrPass/qrFail/qrTodo fields to widget updates throughout the QR block and fix loop. Polls qr-plan-design .json during verify phase to keep counters live. Resets counters on iteration boundaries and fix-loop re-entry. --- src/planner/session.ts | 136 +++++++++++++++++++++++++++++++++-------- 1 file changed, 109 insertions(+), 27 deletions(-) diff --git a/src/planner/session.ts b/src/planner/session.ts index b29e98b..250cdbb 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -62,6 +62,15 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan activeIndex: 1, step: "spawning architect...", activity: "", + qrIterationsMax: MAX_FIX_ITERATIONS + 1, + qrIteration: 1, + qrMode: "initial", + qrPhase: "execute", + qrDone: null, + qrTotal: null, + qrPass: null, + qrFail: null, + qrTodo: null, }); log("Spawning architect after context capture", { planDir, subagentDir }); @@ -132,6 +141,11 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan qrIteration: 1, qrMode: "initial", qrPhase: "execute", + qrDone: null, + qrTotal: null, + qrPass: null, + qrFail: null, + qrTodo: null, }); const qr = await runPlanDesignWithQR(planDir, ctx.cwd, extensionPath, state, log, widget); @@ -212,7 +226,16 @@ async function runQRBlock( ): Promise { // 1. Spawn decomposer subagent state.phase = "qr-decompose-running"; - widget?.update({ step: "qr-decompose: starting...", activity: "", qrPhase: "decompose" }); + widget?.update({ + step: "qr-decompose: starting...", + activity: "", + qrPhase: "decompose", + qrDone: null, + qrTotal: null, + qrPass: null, + qrFail: null, + qrTodo: null, + }); const decomposeDir = await createSubagentDir(planDir, "qr-decomposer"); const decomposePoll = setInterval(async () => { @@ -267,29 +290,62 @@ async function runQRBlock( } const itemIds = qr.items.map((i) => i.id); + const initialPass = qr.items.filter((i) => i.status === "PASS").length; + const initialFail = qr.items.filter((i) => i.status === "FAIL").length; + const initialTodo = qr.items.filter((i) => i.status === "TODO").length; log("QR decompose complete", { itemCount: itemIds.length }); - widget?.update({ step: `qr-verify: 0/${itemIds.length}`, activity: "" }); + widget?.update({ + step: `qr-verify: 0/${itemIds.length}`, + activity: "", + qrTotal: itemIds.length, + qrDone: 0, + qrPass: initialPass, + qrFail: initialFail, + qrTodo: initialTodo, + }); // 3. Spawn reviewer pool state.phase = "qr-verify-running"; widget?.update({ qrPhase: "verify" }); - const result = await pool( - itemIds, - QR_POOL_CONCURRENCY, - async (itemId) => { - const reviewerDir = await createSubagentDir(planDir, `qr-reviewer-${itemId}`); - return spawnReviewer({ - planDir, - subagentDir: reviewerDir, - cwd, - extensionPath, - itemId, - log, - }); - }, - (done, total) => widget?.update({ step: `qr-verify: ${done}/${total}` }), - ); + let verifyDone = 0; + const verifyStatsPoll = setInterval(async () => { + try { + const raw = await fs.readFile(qrPath, "utf8"); + const current = JSON.parse(raw) as QRFile; + const pass = current.items.filter((i) => i.status === "PASS").length; + const fail = current.items.filter((i) => i.status === "FAIL").length; + const todo = current.items.filter((i) => i.status === "TODO").length; + widget?.update({ qrPass: pass, qrFail: fail, qrTodo: todo, qrDone: verifyDone, qrTotal: current.items.length }); + } catch { + // Ignore transient read races while reviewers write. + } + }, 2000); + + let result: Awaited>; + try { + result = await pool( + itemIds, + QR_POOL_CONCURRENCY, + async (itemId) => { + const reviewerDir = await createSubagentDir(planDir, `qr-reviewer-${itemId}`); + return spawnReviewer({ + planDir, + subagentDir: reviewerDir, + cwd, + extensionPath, + itemId, + log, + }); + }, + (done, total) => { + verifyDone = done; + widget?.update({ step: `qr-verify: ${done}/${total}`, qrDone: done, qrTotal: total }); + }, + ); + } finally { + clearInterval(verifyStatsPoll); + } // 4. Read final results state.phase = "qr-complete"; @@ -309,7 +365,15 @@ async function runQRBlock( log("QR block complete", { pass, fail, todo, failedReviewers: result.failed }); const passed = fail === 0 && result.failed.length === 0; - widget?.update({ step: summary, activity: "" }); + widget?.update({ + step: summary, + activity: "", + qrDone: itemIds.length, + qrTotal: itemIds.length, + qrPass: pass, + qrFail: fail, + qrTodo: todo, + }); return { summary, passed }; } @@ -338,14 +402,23 @@ async function runPlanDesignWithQR( // Initial QR (iteration 1) let qr = await runQRBlock(planDir, cwd, extensionPath, state, log, widget); if (qr.passed) { - widget?.update({ qrPhase: "done", qrMode: null, qrIteration: null, qrIterationsMax: null, phaseStatus: { index: 1, status: "completed" } }); + widget?.update({ qrPhase: "done", phaseStatus: { index: 1, status: "completed" } }); return qr; } - widget?.update({ qrPhase: "execute" }); + widget?.update({ qrPhase: "execute", qrDone: null, qrTotal: null, qrPass: null, qrFail: null, qrTodo: null }); for (let iteration = 2; iteration <= MAX_FIX_ITERATIONS + 1; iteration++) { - widget?.update({ qrIteration: iteration, qrMode: "fix", qrPhase: "execute" }); + widget?.update({ + qrIteration: iteration, + qrMode: "fix", + qrPhase: "execute", + qrDone: null, + qrTotal: null, + qrPass: null, + qrFail: null, + qrTodo: null, + }); // Read QR file for severity check let qrFile: QRFile; @@ -354,7 +427,7 @@ async function runPlanDesignWithQR( qrFile = JSON.parse(raw) as QRFile; } catch { log("Fix loop: failed to read QR file", { iteration }); - widget?.update({ qrPhase: "done", qrMode: null, qrIteration: null, qrIterationsMax: null }); + widget?.update({ qrPhase: "done" }); return { summary: "Fix loop aborted: cannot read QR file.", passed: false }; } @@ -365,7 +438,16 @@ async function runPlanDesignWithQR( if (qrPassesAtIteration(qrFile.items, iteration)) { const pass = qrFile.items.filter((i) => i.status === "PASS").length; const fail = qrFile.items.filter((i) => i.status === "FAIL").length; - widget?.update({ qrPhase: "done", qrMode: null, qrIteration: null, qrIterationsMax: null, phaseStatus: { index: 1, status: "completed" } }); + const todo = qrFile.items.filter((i) => i.status === "TODO").length; + widget?.update({ + qrPhase: "done", + qrDone: pass + fail, + qrTotal: qrFile.items.length, + qrPass: pass, + qrFail: fail, + qrTodo: todo, + phaseStatus: { index: 1, status: "completed" }, + }); return { passed: true, summary: `QR passed at iteration ${iteration} after severity de-escalation: ${pass} PASS, ${fail} FAIL (non-blocking).`, @@ -415,17 +497,17 @@ async function runPlanDesignWithQR( }); qr = await runQRBlock(planDir, cwd, extensionPath, state, log, widget); if (qr.passed) { - widget?.update({ qrPhase: "done", qrMode: null, qrIteration: null, qrIterationsMax: null, phaseStatus: { index: 1, status: "completed" } }); + widget?.update({ qrPhase: "done", phaseStatus: { index: 1, status: "completed" } }); return qr; } - widget?.update({ qrPhase: "execute" }); + widget?.update({ qrPhase: "execute", qrDone: null, qrTotal: null, qrPass: null, qrFail: null, qrTodo: null }); } // Max iterations reached. MUST failures remaining after 5 fix attempts // indicate a structural problem -- silently passing would propagate a // known-broken plan downstream. - widget?.update({ qrPhase: "done", qrMode: null, qrIteration: null, qrIterationsMax: null }); + widget?.update({ qrPhase: "done" }); return { passed: false, summary: `${qr.summary} (max ${MAX_FIX_ITERATIONS} fix iterations reached)`, From 25149c63011042aa6e06bf66fc4eb64615df0e5e Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 25 Feb 2026 15:34:29 +0700 Subject: [PATCH 019/412] Integrated workspace card with two-column log and QR counters Merges planning card and log card into a single integrated card with internal divider. Log entries render as two-column grid (tool name left, summary right) with high-value rows wrapping to 2 lines. QR section renders inline with responsive tiers (wide/ medium/tight), phase rail, and pass/fail/todo counters. Column widths shared between planning body and log body for vertical alignment. --- src/planner/ui/widget.ts | 456 ++++++++++++++++++++++++++++++--------- 1 file changed, 356 insertions(+), 100 deletions(-) diff --git a/src/planner/ui/widget.ts b/src/planner/ui/widget.ts index e16cfed..32114ca 100644 --- a/src/planner/ui/widget.ts +++ b/src/planner/ui/widget.ts @@ -41,6 +41,11 @@ interface WidgetState { qrIterationsMax: number | null; qrMode: QRMode | null; qrPhase: QRPhase; + qrDone: number | null; + qrTotal: number | null; + qrPass: number | null; + qrFail: number | null; + qrTodo: number | null; } export interface WidgetUpdate { @@ -54,6 +59,11 @@ export interface WidgetUpdate { qrIterationsMax?: number | null; qrMode?: QRMode | null; qrPhase?: QRPhase; + qrDone?: number | null; + qrTotal?: number | null; + qrPass?: number | null; + qrFail?: number | null; + qrTodo?: number | null; } // -- Constants -- @@ -66,7 +76,7 @@ const LOG_LINES = 5; const BODY_INDENT = " "; const PLANNING_PHASES: ReadonlyArray<{ key: string; label: string; detail: string }> = [ - { key: "ctx", label: "Context", detail: "Gathering context" }, + { key: "ctx", label: "Context gathering", detail: "Gathering initial context" }, { key: "design", label: "Plan design", detail: "Designing plan" }, { key: "code", label: "Plan code", detail: "Creating code plan" }, { key: "docs", label: "Plan docs", detail: "Documenting plan" }, @@ -97,6 +107,7 @@ const LOG_PLACEHOLDER = "No recent log entries"; const TIMELINE_MIN_WIDTH = 16; const TIMELINE_MAX_WIDTH = 28; const CONNECTOR = "│"; +const COLUMN_GAP = 4; interface BorderStyle { topLeft: string; @@ -116,15 +127,6 @@ const BORDER_SOLID: BorderStyle = { vertical: "│", }; -const BORDER_SUBTLE: BorderStyle = { - topLeft: "╭", - topRight: "╮", - bottomLeft: "╰", - bottomRight: "╯", - horizontal: "─", - vertical: "│", -}; - // -- Canvas primitive -- // Content width adapts to terminal; background fills edge to edge. @@ -159,6 +161,22 @@ function indentLines(lines: string[], width: number, indent = BODY_INDENT): stri return lines.map((line) => indent + clampToWidth(line, available)); } +interface PlanningColumns { + innerWidth: number; + contentWidth: number; + timelineWidth: number; + detailWidth: number; +} + +function planningColumns(width: number): PlanningColumns { + const innerWidth = Math.max(0, width - 2); + const indentWidth = visibleWidth(BODY_INDENT); + const contentWidth = Math.max(0, innerWidth - indentWidth); + const timelineWidth = Math.min(TIMELINE_MAX_WIDTH, Math.max(TIMELINE_MIN_WIDTH, Math.floor(contentWidth * 0.3))); + const detailWidth = Math.max(14, contentWidth - timelineWidth - COLUMN_GAP); + return { innerWidth, contentWidth, timelineWidth, detailWidth }; +} + function formatElapsed(ms: number): string { const totalSec = Math.floor(ms / 1000); const m = Math.floor(totalSec / 60); @@ -178,7 +196,7 @@ function activePhase(state: WidgetState): PhaseEntry | null { function normalizeLogLines(lines: readonly LogLine[] | undefined): LogLine[] { if (!lines || lines.length === 0) return []; - return [...lines].slice(-LOG_LINES); + return [...lines].slice(-(LOG_LINES * 2)); } function phaseChipLabel(phase: PhaseEntry, index: number, state: WidgetState, theme: Theme): string { @@ -238,38 +256,165 @@ function renderTimelineLines(state: WidgetState, theme: Theme, width: number): s return lines; } -function upcomingSummary(state: WidgetState): string { - const remaining = state.activeIndex < 0 - ? [] - : state.phases.slice(state.activeIndex + 1).filter((p) => p.status !== "failed"); - if (state.activeIndex < 0) return "Planning complete"; - if (remaining.length === 0) return "Final step in progress"; - const labels = remaining.map((p) => p.label).join(" → "); - return `Upcoming: ${labels}`; +function shouldShowQR(state: WidgetState): boolean { + if (state.qrIteration === null) return false; + const active = activePhase(state); + if (!active) return false; + return active.key !== "ctx"; +} + +type QRTier = "wide" | "medium" | "tight"; + +const QR_TIER_MEDIUM_WIDTH = 68; +const QR_TIER_TIGHT_WIDTH = 52; +const QR_META_MAX_CHARS = 64; + +function qrTier(width: number): QRTier { + if (width < QR_TIER_TIGHT_WIDTH) return "tight"; + if (width < QR_TIER_MEDIUM_WIDTH) return "medium"; + return "wide"; +} + +function qrPhaseLabel(phase: QRPhase): string { + switch (phase) { + case "idle": + return "execute"; + case "execute": + return "execute"; + case "decompose": + return "decompose"; + case "verify": + return "verify"; + case "done": + return "done"; + } +} + +function qrPhaseShortLabel(phase: QRPhase): string { + switch (phase) { + case "idle": + return "exec"; + case "execute": + return "exec"; + case "decompose": + return "decomp"; + case "verify": + return "vfy"; + case "done": + return "done"; + } +} + +function firstBudgeted(candidates: string[], budget: number): string { + for (const c of candidates) { + if (visibleWidth(c) <= budget) return c; + } + const fallback = candidates[candidates.length - 1] ?? ""; + return truncateToWidth(fallback, budget, "…", false); } -function renderQRStatusWidget(state: WidgetState, theme: Theme, width: number): string[] { - if (state.qrIteration === null || state.qrPhase === "idle") { +function qrMetaText(state: WidgetState, tier: QRTier, budget: number): string { + const phase = qrPhaseLabel(state.qrPhase); + const short = qrPhaseShortLabel(state.qrPhase); + const modeFull = state.qrMode === "fix" ? "fix" : "initial"; + const modeShort = state.qrMode === "fix" ? "fx" : "in"; + const iter = state.qrIteration ?? 0; + const iterMax = state.qrIterationsMax ? `/${state.qrIterationsMax}` : ""; + const iterFull = `${iter}${iterMax}`; + + const wide = `phase:${phase} · iter ${iterFull} ${modeFull}`; + const medium = `${phase} · iter ${iterFull} ${modeFull}`; + const compact = `${short} · i${iterFull} ${modeFull}`; + const tight = `${short} i${iterFull} ${modeShort}`; + + const candidates = tier === "wide" + ? [wide, medium, compact, tight] + : tier === "medium" + ? [medium, compact, tight] + : [compact, tight]; + + return firstBudgeted(candidates, budget); +} + +interface QRCounterValues { + done: string; + pass: string; + fail: string; + todo: string; +} + +function qrCounterValues(state: WidgetState): QRCounterValues { + const meaningful = (state.qrPhase === "verify" || state.qrPhase === "done") && state.qrTotal !== null; + if (!meaningful || state.qrTotal === null) { + return { done: "-/-", pass: "-", fail: "-", todo: "-" }; + } + + return { + done: `${state.qrDone ?? 0}/${state.qrTotal}`, + pass: String(state.qrPass ?? 0), + fail: String(state.qrFail ?? 0), + todo: String(state.qrTodo ?? 0), + }; +} + +function renderQRCounterLine(state: WidgetState, theme: Theme, tier: QRTier, width: number, budget: number): string { + const values = qrCounterValues(state); + + const labelSets = tier === "wide" + ? [ + { done: "done", pass: "pass", fail: "fail", todo: "todo" }, + { done: "d", pass: "p", fail: "f", todo: "t" }, + ] + : [{ done: "d", pass: "p", fail: "f", todo: "t" }]; + + const render = (labels: { done: string; pass: string; fail: string; todo: string }) => [ + `${theme.fg("muted", `${labels.done}:`)}${theme.fg("dim", values.done)}`, + `${theme.fg("muted", `${labels.pass}:`)}${theme.fg("accent", values.pass)}`, + `${theme.fg("muted", `${labels.fail}:`)}${theme.bold(theme.fg("error", values.fail))}`, + `${theme.fg("muted", `${labels.todo}:`)}${theme.fg("muted", values.todo)}`, + ].join(" "); + + const candidates = labelSets.map(render); + const selected = firstBudgeted(candidates, budget); + return clampToWidth(selected, width, "…"); +} + +function renderQRStatusSection(state: WidgetState, theme: Theme, width: number): string[] { + if (!shouldShowQR(state)) { return []; } - const innerWidth = Math.max(0, width - 2); - const iterationTotal = state.qrIterationsMax ? ` / ${state.qrIterationsMax}` : ""; - const modeLabel = state.qrMode === "fix" ? "Fix" : "Initial"; - - const headerLeft = theme.bold(theme.fg("accent", "Quality review")); - const headerRightParts = [`Iter ${state.qrIteration}${iterationTotal}`]; - if (modeLabel) headerRightParts.push(modeLabel); - const headerRight = theme.fg("dim", headerRightParts.join(" · ")); - - const phaseEntries: Array<{ key: Exclude; label: string }> = [ - { key: "execute", label: state.qrMode === "fix" ? "Execute (fix)" : "Execute" }, - { key: "decompose", label: "QR decompose" }, - { key: "verify", label: "QR verify" }, - ]; + const tier = qrTier(width); + const budget = Math.min(width, QR_META_MAX_CHARS); - let currentIndex = phaseEntries.findIndex((entry) => entry.key === state.qrPhase); - if (state.qrPhase === "done") { + const headerMeta = qrMetaText(state, tier, budget); + const header = clampToWidth( + `${theme.bold(theme.fg("accent", "QR"))} ${theme.fg("muted", "|")} ${theme.fg("dim", headerMeta)}`, + width, + "…", + ); + + const phaseEntries: Array<{ key: Exclude; label: string }> = tier === "wide" + ? [ + { key: "execute", label: state.qrMode === "fix" ? "Execute (fix)" : "Execute" }, + { key: "decompose", label: "QR decompose" }, + { key: "verify", label: "QR verify" }, + ] + : tier === "medium" + ? [ + { key: "execute", label: state.qrMode === "fix" ? "Exec(fix)" : "Exec" }, + { key: "decompose", label: "Decomp" }, + { key: "verify", label: "Verify" }, + ] + : [ + { key: "execute", label: "X" }, + { key: "decompose", label: "D" }, + { key: "verify", label: "V" }, + ]; + + const effectivePhase: Exclude = state.qrPhase === "idle" ? "execute" : state.qrPhase; + let currentIndex = phaseEntries.findIndex((entry) => entry.key === effectivePhase); + if (effectivePhase === "done") { currentIndex = phaseEntries.length; } @@ -283,36 +428,11 @@ function renderQRStatusWidget(state: WidgetState, theme: Theme, width: number): return theme.fg("muted", entry.label); }); - const separator = theme.fg("muted", " → "); - const stageLine = clampToWidth(segments.join(separator), innerWidth, "…"); - - const description = (() => { - if (state.qrPhase === "execute") { - return state.qrMode === "fix" - ? "Fix-mode architect applies QR feedback." - : "Initial execution to gather plan context."; - } - if (state.qrPhase === "decompose") { - return state.qrIteration && state.qrIteration > 1 - ? "Re-decomposing updates into review items." - : "Deriving QR checklist from the current plan."; - } - if (state.qrPhase === "verify") { - return "Massively parallel reviewers scoring QR items."; - } - if (state.qrPhase === "done") { - return "Quality review loop complete."; - } - return ""; - })(); - - const body: string[] = []; - body.push(stageLine); - if (description) { - body.push(clampToWidth(theme.fg("muted", description), innerWidth, "…")); - } + const rail = clampToWidth(segments.join(theme.fg("muted", " → ")), width, "…"); + const counters = renderQRCounterLine(state, theme, tier, width, budget); + const divider = clampToWidth(theme.fg("muted", "─".repeat(width)), width); - return renderBox(headerLeft, headerRight, body, width, theme, BORDER_SUBTLE); + return [header, rail, counters, divider]; } interface DetailSections { @@ -327,6 +447,7 @@ function buildDetailSections(state: WidgetState, theme: Theme, width: number): D const active = activePhase(state); const stepTitle = state.step || active?.detail || active?.label || "Awaiting step"; + core.push(clampToWidth(theme.fg("dim", "Current step"), width)); core.push(clampToWidth(theme.bold(theme.fg("accent", stepTitle)), width, "…")); if (state.activity) { @@ -336,24 +457,18 @@ function buildDetailSections(state: WidgetState, theme: Theme, width: number): D } } - const qrWidget = renderQRStatusWidget(state, theme, width); - if (qrWidget.length > 0) { + const qrSection = renderQRStatusSection(state, theme, width); + if (qrSection.length > 0) { if (core.length > 0 && core[core.length - 1].trim() !== "") { core.push(blank); } - core.push(...qrWidget.map((line) => clampToWidth(line, width))); + core.push(...qrSection.map((line) => clampToWidth(line, width))); } if (active) { - footer.push(...wrapTextWithAnsi(theme.fg("dim", `Phase ${state.activeIndex + 1}/${state.phases.length}`), width).map((line) => clampToWidth(line, width, "…"))); footer.push(...wrapTextWithAnsi(theme.fg("dim", `Plan · ${state.planId}`), width).map((line) => clampToWidth(line, width, "…"))); } - const summary = upcomingSummary(state); - if (summary) { - footer.push(...wrapTextWithAnsi(theme.fg("muted", summary), width).map((line) => clampToWidth(line, width, "…"))); - } - return { core, footer }; } @@ -403,9 +518,7 @@ function renderBox( function renderPlanningCard(state: WidgetState, theme: Theme, width: number): string[] { const elapsed = theme.fg("dim", formatElapsed(Date.now() - state.startedAt)); - const innerWidth = Math.max(0, width - 2); - const indentWidth = visibleWidth(BODY_INDENT); - const contentWidth = Math.max(0, innerWidth - indentWidth); + const { innerWidth, contentWidth, timelineWidth, detailWidth } = planningColumns(width); if (innerWidth < 60 || contentWidth < 40) { const fallbackContent: string[] = [ @@ -417,6 +530,10 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st ]; const detail = formatDetail(state, theme, contentWidth); if (detail) fallbackContent.push(detail); + const qrCompact = formatQRCompact(state, theme, contentWidth); + if (qrCompact.length > 0) { + fallbackContent.push(...qrCompact); + } fallbackContent.push(""); const body = indentLines(fallbackContent, innerWidth); @@ -430,8 +547,6 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st } const chipsLine = renderPhaseChips(state, theme, contentWidth); - const timelineWidth = Math.min(TIMELINE_MAX_WIDTH, Math.max(TIMELINE_MIN_WIDTH, Math.floor(contentWidth * 0.3))); - const detailWidth = Math.max(14, contentWidth - timelineWidth - 4); const timelineLines = renderTimelineLines(state, theme, timelineWidth); const detailSections = buildDetailSections(state, theme, detailWidth); @@ -442,7 +557,7 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st for (let i = 0; i < maxLines; i++) { const left = timelineLines[i] ?? ""; const right = detailLines[i] ?? ""; - const composed = `${clampToWidth(left, timelineWidth)} ${clampToWidth(right, detailWidth)}`; + const composed = `${clampToWidth(left, timelineWidth)}${" ".repeat(COLUMN_GAP)}${clampToWidth(right, detailWidth)}`; combined.push(clampToWidth(composed, contentWidth)); } @@ -458,7 +573,7 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st ); return renderBox( - `${BODY_INDENT}${theme.bold(theme.fg("accent", "Planning Workspace"))}`, + `${BODY_INDENT}${theme.bold(theme.fg("accent", "Planning"))}`, elapsed, body, width, @@ -466,25 +581,99 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st ); } -function renderLogLine(entry: LogLine, theme: Theme): string { - const parts: string[] = []; - if (entry.prefix) parts.push(theme.fg("dim", entry.prefix)); - if (entry.highlight) parts.push(theme.bold(entry.highlight)); - if (entry.meta) parts.push(theme.fg("dim", entry.meta)); - return `${theme.fg("dim", "•")} ${parts.join(" ")}`; +function wrapRightColumn(entry: LogLine, width: number): string[] { + const summary = entry.summary.trim(); + if (!summary) return [""]; + + if (!entry.highValue) { + return [clampToWidth(summary, width, "…")]; + } + + const wrapped = wrapTextWithAnsi(summary, width).map((line) => clampToWidth(line, width, "…")); + if (wrapped.length <= 1) return wrapped; + if (wrapped.length === 2) return wrapped; + + const tail = wrapped.slice(1).join(" ").replace(/\s+/gu, " ").trim(); + return [wrapped[0], clampToWidth(truncateToWidth(tail, width, "…", false), width)]; +} + +function renderLogEntry(entry: LogLine, theme: Theme, leftWidth: number, rightWidth: number, gap: number): string[] { + const rightLines = wrapRightColumn(entry, rightWidth); + const rows: string[] = []; + + rightLines.forEach((line, index) => { + const left = index === 0 + ? theme.bold(theme.fg("accent", entry.tool)) + : ""; + const composed = `${clampToWidth(left, leftWidth)}${" ".repeat(gap)}${clampToWidth(theme.fg("muted", line), rightWidth)}`; + rows.push(composed); + }); + + return rows; +} + +interface LogColumns { + left: number; + right: number; + gap: number; } -function renderLogCard(state: WidgetState, theme: Theme, width: number): string[] { +function logColumnWidths(availableWidth: number, entries: readonly LogLine[], gap: number): LogColumns { + const longestTool = entries.reduce((max, entry) => Math.max(max, visibleWidth(entry.tool)), 0); + const preferredLeft = Math.max(16, Math.min(38, longestTool + 2)); + + const minRight = availableWidth < 64 ? 18 : 24; + let left = Math.min(preferredLeft, Math.floor(availableWidth * 0.42)); + left = Math.min(left, Math.max(14, availableWidth - minRight - gap)); + left = Math.max(14, left); + + const right = Math.max(8, availableWidth - left - gap); + return { left, right, gap }; +} + +function renderLogCard(state: WidgetState, theme: Theme, width: number, forcedColumns?: LogColumns): string[] { const innerWidth = Math.max(0, width - 2); + const availableWidth = Math.max(0, innerWidth - visibleWidth(BODY_INDENT)); const hasEntries = state.logLines.length > 0; - const entries = hasEntries ? state.logLines.slice(-LOG_LINES) : []; + const entries = hasEntries ? state.logLines.slice(-(LOG_LINES * 2)) : []; + + const columns = forcedColumns ?? logColumnWidths(availableWidth, entries, 2); + const leftWidth = Math.max(8, Math.min(columns.left, Math.max(8, availableWidth - columns.gap - 8))); + const rightWidth = Math.max(8, availableWidth - leftWidth - columns.gap); + + const visualRows: string[] = []; + if (entries.length > 0) { + const rendered = entries.map((entry) => renderLogEntry(entry, theme, leftWidth, rightWidth, columns.gap)); + const selected: string[][] = []; + let remaining = LOG_LINES; + + for (let i = rendered.length - 1; i >= 0; i--) { + if (remaining <= 0) break; + const rowLines = rendered[i]; + if (rowLines.length <= remaining) { + selected.push(rowLines); + remaining -= rowLines.length; + } else { + selected.push(rowLines.slice(0, remaining)); + remaining = 0; + } + } + + selected.reverse(); + for (const lines of selected) { + visualRows.push(...lines); + } + } - const formatted: string[] = hasEntries - ? entries.map((entry) => renderLogLine(entry, theme)) - : [theme.fg("dim", `• ${LOG_PLACEHOLDER}`)]; - while (formatted.length < LOG_LINES) formatted.push(""); + if (visualRows.length === 0) { + visualRows.push(clampToWidth(theme.fg("muted", LOG_PLACEHOLDER), innerWidth)); + } - const body = indentLines(formatted, innerWidth); + while (visualRows.length < LOG_LINES) { + visualRows.push(""); + } + + const body = indentLines(visualRows, innerWidth); return renderBox( `${BODY_INDENT}${theme.bold(theme.fg("accent", "Latest log"))}`, "", @@ -513,6 +702,17 @@ function formatDetail(state: WidgetState, theme: Theme, width: number): string { return clampToWidth(detail, width, "…"); } +function formatQRCompact(state: WidgetState, theme: Theme, width: number): string[] { + if (!shouldShowQR(state)) return []; + + const tier = qrTier(width); + const budget = Math.min(width, QR_META_MAX_CHARS); + const meta = qrMetaText(state, tier, budget); + const line1 = clampToWidth(`${theme.fg("muted", "QR")} ${theme.fg("muted", "|")} ${theme.fg("dim", meta)}`, width, "…"); + const line2 = renderQRCounterLine(state, theme, tier, width, budget); + return [line1, line2]; +} + function formatStepLine(state: WidgetState, theme: Theme): string { const total = state.phases.length; const active = activePhase(state); @@ -524,6 +724,46 @@ function formatStepLine(state: WidgetState, theme: Theme): string { return `${count} ${theme.fg("muted", "·")} ${label}`; } +// Pure render: (state, theme, termWidth) -> lines. No side effects. +function stripBoxFrame(lines: string[]): string[] { + if (lines.length <= 2) return []; + return lines.slice(1, -1).map((line) => (line.length >= 2 ? line.slice(1, -1) : "")); +} + +function renderIntegratedWorkspaceCard(state: WidgetState, theme: Theme, width: number): string[] { + const innerWidth = Math.max(0, width - 2); + const elapsed = theme.fg("dim", formatElapsed(Date.now() - state.startedAt)); + const rightInset = " ".repeat(visibleWidth(BODY_INDENT)); + + const { innerWidth: planningInnerWidth, contentWidth, timelineWidth, detailWidth } = planningColumns(width); + const alignedColumns: LogColumns | undefined = planningInnerWidth >= 60 && contentWidth >= 40 + ? { left: timelineWidth, right: detailWidth, gap: COLUMN_GAP } + : undefined; + + const planningInner = stripBoxFrame(renderPlanningCard(state, theme, width)); + const logInner = stripBoxFrame(renderLogCard(state, theme, width, alignedColumns)); + + const divider = clampToWidth(theme.fg("muted", "─".repeat(innerWidth)), innerWidth); + const spacer = clampToWidth("", innerWidth); + const logTitle = clampToWidth(`${BODY_INDENT}${theme.bold(theme.fg("accent", "Latest log"))}`, innerWidth, "…"); + + const body = [ + ...planningInner, + divider, + spacer, + logTitle, + ...logInner, + ]; + + return renderBox( + `${BODY_INDENT}${theme.bold(theme.fg("accent", "Planning"))}`, + `${elapsed}${rightInset}`, + body, + width, + theme, + ); +} + // Pure render: (state, theme, termWidth) -> lines. No side effects. function render(state: WidgetState, theme: Theme, termWidth: number): string[] { const c = (s: string) => canvasLine(s, termWidth, theme); @@ -532,11 +772,7 @@ function render(state: WidgetState, theme: Theme, termWidth: number): string[] { const margin = " ".repeat(CARD_MARGIN); lines.push(c("")); - for (const line of renderPlanningCard(state, theme, cw - CARD_MARGIN)) { - lines.push(c(margin + line)); - } - lines.push(c(margin)); - for (const line of renderLogCard(state, theme, cw - CARD_MARGIN)) { + for (const line of renderIntegratedWorkspaceCard(state, theme, cw - CARD_MARGIN)) { lines.push(c(margin + line)); } lines.push(c("")); @@ -567,6 +803,11 @@ export class WidgetController { qrIterationsMax: null, qrMode: null, qrPhase: "idle", + qrDone: null, + qrTotal: null, + qrPass: null, + qrFail: null, + qrTodo: null, }; this.state.phases[0].status = "running"; @@ -614,6 +855,21 @@ export class WidgetController { if (patch.qrPhase !== undefined) { this.state.qrPhase = patch.qrPhase; } + if (patch.qrDone !== undefined) { + this.state.qrDone = patch.qrDone; + } + if (patch.qrTotal !== undefined) { + this.state.qrTotal = patch.qrTotal; + } + if (patch.qrPass !== undefined) { + this.state.qrPass = patch.qrPass; + } + if (patch.qrFail !== undefined) { + this.state.qrFail = patch.qrFail; + } + if (patch.qrTodo !== undefined) { + this.state.qrTodo = patch.qrTodo; + } this.doRender(); } From edaa2fbf5880a1cb0933ae05eb51316ea9b09043 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 25 Feb 2026 15:37:01 +0700 Subject: [PATCH 020/412] Rewrite stale progress test against EventLog/audit API ProgressReporter and readSubagentState were replaced by EventLog, readProjection, and readRecentLogs. Rewrites the test to cover the current API: EventLog persistence, readProjection, readRecentLogs filtering, fold (pure), summarize, and extractToolEvent. --- tests/progress.test.ts | 334 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 305 insertions(+), 29 deletions(-) diff --git a/tests/progress.test.ts b/tests/progress.test.ts index 3a69e40..5891306 100644 --- a/tests/progress.test.ts +++ b/tests/progress.test.ts @@ -4,38 +4,314 @@ import { promises as fs } from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; -import { ProgressReporter, readSubagentState } from "../src/utils/progress.js"; +import { EventLog, readProjection, readRecentLogs, fold, summarize, extractToolEvent } from "../src/planner/lib/audit.js"; +import type { Projection, AuditEvent, ToolEvent } from "../src/planner/lib/audit.js"; async function createTempDir(prefix: string): Promise { - const base = await fs.mkdtemp(path.join(os.tmpdir(), prefix)); - return base; + return fs.mkdtemp(path.join(os.tmpdir(), prefix)); } -describe("ProgressReporter", () => { - it("persists progress updates and completion state", async () => { - const tempRoot = await createTempDir("koan-progress-"); - const reporterDir = path.join(tempRoot, "reporter"); - await fs.mkdir(reporterDir, { recursive: true }); - - const reporter = new ProgressReporter(reporterDir, "planner", "analysis"); - - await reporter.update("gathering context"); - await reporter.update("synthesizing plan"); - await reporter.complete("completed"); - - const state = await readSubagentState(reporterDir); - assert.ok(state, "state file should be readable"); - assert.equal(state.role, "planner"); - assert.equal(state.phase, "analysis"); - assert.equal(state.status, "completed"); - assert.equal(state.current, "completed"); - assert.equal(state.trail.length, 3); - assert.deepEqual( - state.trail.map((entry) => entry.msg), - ["gathering context", "synthesizing plan", "completed"], - "trail should capture chronological updates" - ); - - await fs.rm(tempRoot, { recursive: true, force: true }); +// -- EventLog + readProjection -- + +describe("EventLog", () => { + it("persists events and projection through step transitions", async () => { + const dir = await createTempDir("koan-audit-"); + + const log = new EventLog(dir, "architect", "plan-design"); + await log.open(); + + await log.emitPhaseStart(6); + await log.emitStepTransition(1, "Task Analysis", 6); + await log.emitStepTransition(2, "Decision Framework", 6); + await log.emitPhaseEnd("completed"); + await log.close(); + + const proj = await readProjection(dir); + assert.ok(proj, "projection should be readable"); + assert.equal(proj.role, "architect"); + assert.equal(proj.phase, "plan-design"); + assert.equal(proj.status, "completed"); + assert.equal(proj.step, 2); + assert.equal(proj.totalSteps, 6); + assert.equal(proj.stepName, "Step 2/6: Decision Framework"); + assert.equal(proj.eventCount, 4); + + // Verify events.jsonl has correct number of lines + const raw = await fs.readFile(path.join(dir, "events.jsonl"), "utf8"); + const lines = raw.trimEnd().split("\n").filter(Boolean); + assert.equal(lines.length, 4); + + await fs.rm(dir, { recursive: true, force: true }); + }); + + it("tracks lastAction from tool events", async () => { + const dir = await createTempDir("koan-audit-"); + + const log = new EventLog(dir, "architect", "plan-design"); + await log.open(); + + await log.append({ + kind: "tool_file", + tool: "read", + path: "src/main.ts", + lines: 50, + chars: 1200, + error: false, + } as Omit); + + const proj = log.state; + assert.equal(proj.lastAction, "read src/main.ts (50L, 1200c)"); + + await log.close(); + await fs.rm(dir, { recursive: true, force: true }); + }); + + it("returns null for missing projection", async () => { + const dir = await createTempDir("koan-audit-"); + const proj = await readProjection(dir); + assert.equal(proj, null); + await fs.rm(dir, { recursive: true, force: true }); + }); +}); + +// -- readRecentLogs -- + +describe("readRecentLogs", () => { + it("returns recent non-heartbeat events as structured LogLines", async () => { + const dir = await createTempDir("koan-audit-"); + + const log = new EventLog(dir, "architect", "plan-design"); + await log.open(); + + await log.emitPhaseStart(3); + await log.emitStepTransition(1, "Analysis", 3); + await log.append({ + kind: "tool_file", + tool: "read", + path: "src/foo.ts", + lines: 100, + chars: 3000, + error: false, + } as Omit); + await log.close(); + + const lines = await readRecentLogs(dir, 5); + // 3 events (heartbeats filtered), all returned + assert.equal(lines.length, 3); + + assert.equal(lines[0].tool, "phase"); + assert.ok(lines[0].summary.includes("plan-design")); + + assert.equal(lines[1].tool, "step 1/3"); + assert.equal(lines[1].summary, "Analysis"); + + assert.equal(lines[2].tool, "read"); + assert.ok(lines[2].summary.includes("src/foo.ts")); + assert.ok(lines[2].summary.includes("100L")); + + await fs.rm(dir, { recursive: true, force: true }); + }); + + it("filters out koan_complete_step events", async () => { + const dir = await createTempDir("koan-audit-"); + + const log = new EventLog(dir, "architect", "plan-design"); + await log.open(); + + await log.append({ + kind: "tool_koan", + tool: "koan_complete_step", + input: { thoughts: "done" }, + response: ["ok"], + error: false, + } as Omit); + + await log.append({ + kind: "tool_koan", + tool: "koan_set_overview", + input: { problem: "test" }, + response: ["saved"], + error: false, + } as Omit); + + await log.close(); + + const lines = await readRecentLogs(dir, 5); + assert.equal(lines.length, 1); + assert.equal(lines[0].tool, "koan_set_overview"); + + await fs.rm(dir, { recursive: true, force: true }); + }); + + it("returns empty array for missing directory", async () => { + const lines = await readRecentLogs("/nonexistent/path", 5); + assert.deepEqual(lines, []); + }); +}); + +// -- fold (pure) -- + +describe("fold", () => { + const initial: Projection = { + role: "", + phase: "", + status: "running", + step: 0, + totalSteps: 0, + stepName: "", + lastAction: null, + updatedAt: "", + eventCount: 0, + error: null, + }; + + it("phase_start resets projection", () => { + const e: AuditEvent = { + kind: "phase_start", + phase: "plan-design", + role: "architect", + totalSteps: 6, + ts: "2026-01-01T00:00:00Z", + seq: 0, + }; + const s = fold(initial, e); + assert.equal(s.role, "architect"); + assert.equal(s.phase, "plan-design"); + assert.equal(s.totalSteps, 6); + assert.equal(s.eventCount, 1); + }); + + it("step_transition updates step name", () => { + const e: AuditEvent = { + kind: "step_transition", + step: 3, + name: "Risk Assessment", + totalSteps: 6, + ts: "2026-01-01T00:00:01Z", + seq: 1, + }; + const s = fold(initial, e); + assert.equal(s.step, 3); + assert.equal(s.stepName, "Step 3/6: Risk Assessment"); + }); + + it("phase_end sets status and error", () => { + const e: AuditEvent = { + kind: "phase_end", + outcome: "failed", + detail: "timeout", + ts: "2026-01-01T00:00:02Z", + seq: 2, + }; + const s = fold(initial, e); + assert.equal(s.status, "failed"); + assert.equal(s.error, "timeout"); + }); +}); + +// -- summarize -- + +describe("summarize", () => { + it("file tool with size stats", () => { + const e: ToolEvent = { + kind: "tool_file", + tool: "read", + path: "src/main.ts", + lines: 42, + chars: 1500, + error: false, + ts: "", + seq: 0, + }; + assert.equal(summarize(e), "read src/main.ts (42L, 1500c)"); + }); + + it("bash tool with size stats", () => { + const e: ToolEvent = { + kind: "tool_bash", + bin: "grep", + lines: 10, + chars: 200, + error: false, + ts: "", + seq: 0, + }; + assert.equal(summarize(e), "bash grep (10L, 200c)"); + }); + + it("file tool without size stats", () => { + const e: ToolEvent = { + kind: "tool_file", + tool: "edit", + path: "src/foo.ts", + error: false, + ts: "", + seq: 0, + }; + assert.equal(summarize(e), "edit src/foo.ts"); + }); +}); + +// -- extractToolEvent -- + +describe("extractToolEvent", () => { + it("extracts read tool with line/char counts", () => { + const content = "line1\nline2\nline3"; + const e = extractToolEvent({ + toolName: "read", + input: { path: "src/test.ts" }, + content: [{ type: "text", text: content }], + isError: false, + }); + assert.equal(e.kind, "tool_file"); + if (e.kind === "tool_file") { + assert.equal(e.tool, "read"); + assert.equal(e.path, "src/test.ts"); + assert.equal(e.lines, 3); + assert.equal(e.chars, content.length); + } + }); + + it("extracts bash tool with line/char counts", () => { + const output = "found 5 matches\n"; + const e = extractToolEvent({ + toolName: "bash", + input: { command: "grep -r pattern ." }, + content: [{ type: "text", text: output }], + isError: false, + }); + assert.equal(e.kind, "tool_bash"); + if (e.kind === "tool_bash") { + assert.equal(e.bin, "grep"); + assert.equal(e.lines, 2); + assert.equal(e.chars, output.length); + } + }); + + it("extracts koan tool with input and response", () => { + const e = extractToolEvent({ + toolName: "koan_set_overview", + input: { problem: "test problem" }, + content: [{ type: "text", text: "saved" }], + isError: false, + }); + assert.equal(e.kind, "tool_koan"); + if (e.kind === "tool_koan") { + assert.equal(e.tool, "koan_set_overview"); + assert.deepEqual(e.response, ["saved"]); + } + }); + + it("falls back to generic for unknown tools", () => { + const e = extractToolEvent({ + toolName: "unknown_tool", + input: {}, + content: [], + isError: false, + }); + assert.equal(e.kind, "tool_generic"); + if (e.kind === "tool_generic") { + assert.equal(e.tool, "unknown_tool"); + } }); }); From 969188c89cd7f950c61517bf4a5519b4f2ea2c2a Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 26 Feb 2026 09:27:35 +0700 Subject: [PATCH 021/412] planner: make plan-design fix workflow dynamic per QR item --- src/planner/phases/plan-design/fix-phase.ts | 93 ++++-- src/planner/phases/plan-design/fix-prompts.ts | 272 +++++++++++------- 2 files changed, 236 insertions(+), 129 deletions(-) diff --git a/src/planner/phases/plan-design/fix-phase.ts b/src/planner/phases/plan-design/fix-phase.ts index 4df6a24..24b5cc8 100644 --- a/src/planner/phases/plan-design/fix-phase.ts +++ b/src/planner/phases/plan-design/fix-phase.ts @@ -1,16 +1,20 @@ -// Plan-design fix phase -- 3-step targeted repair for QR failures. +// Plan-design fix phase -- dynamic N-step targeted repair for QR failures. +// +// totalSteps = 2 + failures.length. Step 1 reads all failures (read-only). +// Steps 2..N+1 each fix one QR item (mutations enabled). Step N+2 reviews +// all fixes (read-only). The step counter IS the item iterator: +// failures[step - 2] gives the current item. // // Separate class from PlanDesignPhase because the workflows diverge: // initial = 6 steps of exploration then writing (mutations at step 6); -// fix = 3 steps of reading failures then applying targeted fixes -// (mutations at step 2). Conditional branching at every method -// boundary produces worse code than two focused classes. +// fix = dynamic N steps iterating one QR item per step (mutations in +// per-item range only). Conditional branching at every method boundary +// produces worse code than two focused classes. // -// The fix architect receives QR failures as XML in step 1. It reads -// the current plan state via getter tools, applies minimal mutations -// to address the specific findings, then validates the result. The -// session orchestrator decides whether to re-run QR -- the fix phase -// does not know about iterations or severity escalation. +// The fix architect receives QR failures as XML in step 1. Per-item steps +// present a single failure with mutation tools enabled. The session +// orchestrator decides whether to re-run QR -- the fix phase does not +// know about iterations or severity escalation. import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; @@ -20,11 +24,10 @@ import { buildPlanDesignSystemPrompt, } from "./prompts.js"; import { - FIX_STEP_NAMES, + fixStepName, buildFixSystemPrompt, fixStepGuidance, formatFailuresXml, - type FixStep, } from "./fix-prompts.js"; import { formatStep } from "../../lib/step.js"; import type { QRItem } from "../../qr/types.js"; @@ -35,17 +38,15 @@ import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; interface FixPhaseState { active: boolean; - step: FixStep; + step: number; step1Prompt: string | null; systemPrompt: string | null; } -const TOTAL_STEPS = 3; - export class PlanDesignFixPhase { private readonly pi: ExtensionAPI; private readonly planDir: string; - private readonly failures: QRItem[]; + private readonly failures: ReadonlyArray; private readonly log: Logger; private readonly state: FixPhaseState; private readonly eventLog: EventLog | undefined; @@ -78,6 +79,13 @@ export class PlanDesignFixPhase { this.registerHandlers(); } + // Computed from failure count. Step 1 (understand) + N per-item steps + // + 1 final review = 2 + N. Single source of truth for all step-range + // checks in this class. + private get totalSteps(): number { + return 2 + this.failures.length; + } + async begin(): Promise { let basePrompt: string; try { @@ -89,11 +97,17 @@ export class PlanDesignFixPhase { } const failuresXml = formatFailuresXml(this.failures); + // Local copy for consistent reads across this method. The getter is stable + // (this.failures is readonly) but a local communicates "one value, many uses". + const totalSteps = this.totalSteps; this.state.systemPrompt = buildFixSystemPrompt( buildPlanDesignSystemPrompt(basePrompt), this.failures.length, + totalSteps, + ); + this.state.step1Prompt = formatStep( + fixStepGuidance(1, totalSteps, { allFailuresXml: failuresXml }), ); - this.state.step1Prompt = formatStep(fixStepGuidance(1, failuresXml)); this.state.active = true; this.state.step = 1; @@ -101,10 +115,15 @@ export class PlanDesignFixPhase { this.log("Starting plan-design fix workflow", { step: 1, + totalSteps, failureCount: this.failures.length, }); - await this.eventLog?.emitPhaseStart(TOTAL_STEPS); - await this.eventLog?.emitStepTransition(1, FIX_STEP_NAMES[1], TOTAL_STEPS); + await this.eventLog?.emitPhaseStart(totalSteps); + await this.eventLog?.emitStepTransition( + 1, + fixStepName(1, totalSteps), + totalSteps, + ); } private registerHandlers(): void { @@ -137,14 +156,17 @@ export class PlanDesignFixPhase { return { block: true, reason: perm.reason }; } - // Step gate: mutation tools are blocked before step 2. Blocklist - // (not whitelist) so read tools and future pi-native tools pass - // through after checkPermission approves them. + // Step gate: mutation tools allowed ONLY in per-item steps (step 2 + // through totalSteps-1). Both step 1 (understand) and the final step + // (review) are read-only. The upper bound prevents accidental mutations + // during review that would bypass QR re-verification. const step = this.state.step; - if (step < 2 && PLAN_MUTATION_TOOLS.has(event.toolName)) { + const total = this.totalSteps; + const inItemRange = step >= 2 && step < total; + if (!inItemRange && PLAN_MUTATION_TOOLS.has(event.toolName)) { return { block: true, - reason: `${event.toolName} available from step 2 (current: ${step})`, + reason: `${event.toolName} available in steps 2-${total - 1} (current: ${step})`, }; } @@ -154,8 +176,10 @@ export class PlanDesignFixPhase { private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { const prev = this.state.step; + const total = this.totalSteps; - if (prev === 3) { + // Terminal: final step completed -> validate plan and end phase. + if (prev === total) { const result = await this.handleFinalize(); if (!result.ok) { await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); @@ -168,12 +192,21 @@ export class PlanDesignFixPhase { return { ok: true, prompt: "Fix phase validation passed. Workflow complete." }; } - this.state.step = (prev + 1) as FixStep; - const nextName = FIX_STEP_NAMES[this.state.step]; - const prompt = formatStep(fixStepGuidance(this.state.step)); - - this.log("Fix step complete, advancing", { from: prev, to: this.state.step, name: nextName }); - await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); + // Advance to next step. Step always increments -- no cursor, no hold. + const next = prev + 1; + this.state.step = next; + + // Per-item steps (2 <= next < total) pass the individual failure item + // so fixStepGuidance generates item-specific prompts. Only the final + // step (next === total) does not carry an item. + const item = (next >= 2 && next < total) + ? this.failures[next - 2] + : undefined; + const name = fixStepName(next, total, item); + const prompt = formatStep(fixStepGuidance(next, total, { item })); + + this.log("Fix step complete, advancing", { from: prev, to: next, name }); + await this.eventLog?.emitStepTransition(next, name, total); return { ok: true, prompt }; } diff --git a/src/planner/phases/plan-design/fix-prompts.ts b/src/planner/phases/plan-design/fix-prompts.ts index 003bf8d..8d12cc8 100644 --- a/src/planner/phases/plan-design/fix-prompts.ts +++ b/src/planner/phases/plan-design/fix-prompts.ts @@ -1,21 +1,17 @@ -// Fix-phase step guidance for plan-design targeted repair (3 steps). +// Fix-phase step guidance for plan-design targeted repair (dynamic N steps). // -// Parallels prompts.ts structure. Step 1 explicitly prohibits mutations: -// without this constraint the LLM tends to apply the first fix it identifies -// without reading all failures, producing cascading corrections that address -// symptoms rather than root causes. +// totalSteps = 2 + failures.length. Step 1 reads all failures (read-only). +// Steps 2..N+1 each fix one QR item (mutations enabled). Step N+2 reviews +// all fixes (read-only). The step counter IS the item iterator: +// failures[step - 2] gives the current item in the per-item range. +// +// Step 1 explicitly prohibits mutations: without this constraint the LLM +// tends to apply the first fix it identifies without reading all failures, +// producing cascading corrections that address symptoms rather than root causes. import type { QRItem } from "../../qr/types.js"; import type { StepGuidance } from "../../lib/step.js"; -export type FixStep = 1 | 2 | 3; - -export const FIX_STEP_NAMES: Record = { - 1: "Understand QR Failures", - 2: "Apply Targeted Fixes", - 3: "Review & Finalize", -}; - // Serializes FAIL items as an XML block injected into the step 1 prompt. // XML structure mirrors how pi-native tools present structured data. export function formatFailuresXml(failures: ReadonlyArray): string { @@ -33,105 +29,183 @@ export function formatFailuresXml(failures: ReadonlyArray): string { ].join("\n"); } +// Dynamic step names. Step 1 and the final step have fixed names; +// per-item steps show the QR item ID so the widget displays +// "Step 3/7: Fix D-001" rather than a generic label. The audit log +// uses these names to distinguish per-item transitions. +export function fixStepName( + step: number, + totalSteps: number, + item?: QRItem, +): string { + if (step === 1) return "Understand QR Failures"; + if (step === totalSteps) return "Review & Finalize"; + return item ? `Fix ${item.id}` : `Fix item ${step - 1}`; +} + // Appends fix workflow instructions to the base architect system prompt. -export function buildFixSystemPrompt(basePrompt: string, failureCount: number): string { +// The structured STEP LAYOUT section uses indentation to visually separate +// the three phases so the LLM internalizes the one-at-a-time constraint +// from the system prompt rather than discovering it at step 2. +export function buildFixSystemPrompt( + basePrompt: string, + failureCount: number, + totalSteps: number, +): string { return [ basePrompt, "", "---", "", - "WORKFLOW: 3-STEP PLAN-DESIGN FIX", + `WORKFLOW: ${totalSteps}-STEP PLAN-DESIGN FIX`, "", `You are fixing ${failureCount} QR failure(s) in an existing plan.`, - "Step 1 instructions are in the user message below.", - "Complete the work described, then call koan_complete_step.", - "Put your findings in the `thoughts` parameter of koan_complete_step.", - "The tool result contains the next step's instructions.", "", - "CRITICAL: Fix ONLY the identified failures. Do not restructure the plan", - "beyond what the failures require. Prefer updating existing entities over", - "adding new ones.", + "STEP LAYOUT:", + " Step 1: Read all failures. Understand scope and interactions. READ-ONLY.", + ` Steps 2-${totalSteps - 1}: Fix ONE failure per step. Each step targets exactly one item.`, + ` Step ${totalSteps}: Review all fixes against original failures. READ-ONLY.`, + "", + "Each step's instructions appear as a tool result after you call koan_complete_step.", + "Put your work output in the `thoughts` parameter of koan_complete_step.", + "", + "CONSTRAINTS:", + " - Fix ONLY the identified failures", + " - Each per-item step targets exactly ONE failure -- do not fix other items", + " - Prefer updating existing entities over adding new ones", + " - Do not restructure the plan beyond what failures require", ].join("\n"); } -export function fixStepGuidance(step: FixStep, context?: string): StepGuidance { - switch (step) { - case 1: - return { - title: "Step 1: Understand QR Failures", - instructions: [ - "QR FAILURES TO FIX:", - "", - context ?? "", - "", - "Read the failures carefully. For each failing item:", - " - Identify the scope (which milestone, decision, or intent)", - " - Understand what the check requires", - " - Read the finding to understand why it failed", - "", - "Use getter tools to inspect the scoped entities:", - " - koan_get_plan: overview, structure, decisions", - " - koan_get_milestone: milestone details and intents", - " - koan_get_decision: decision rationale", - " - koan_get_intent: intent definition", - "", - "Plan your fixes mentally. Consider:", - " - What minimal change addresses each failure?", - " - Do any fixes overlap or interact?", - " - Could fixing one item cause another to fail?", - "", - "DO NOT write any changes yet. Gather understanding for step 2.", - ], - }; +// Three categories of step: understand (step 1), per-item fix +// (2 <= step < totalSteps), and review (step === totalSteps). +// The step counter IS the item iterator -- no separate cursor needed. +export function fixStepGuidance( + step: number, + totalSteps: number, + opts?: { item?: QRItem; allFailuresXml?: string }, +): StepGuidance { + if (step === 1) + return fixStep1Guidance(totalSteps, opts?.allFailuresXml ?? ""); + if (step === totalSteps) return fixFinalStepGuidance(totalSteps); + return fixItemStepGuidance(step, totalSteps, opts?.item); +} + +// Step 1 prompt reframes analysis as "note interactions" rather than +// "plan your fixes mentally" to avoid priming the LLM for batch application. +// The one-at-a-time delivery is stated explicitly so the LLM expects +// per-item steps rather than a single batch-fix step. +function fixStep1Guidance( + totalSteps: number, + failuresXml: string, +): StepGuidance { + const itemCount = totalSteps - 2; + return { + title: `Step 1/${totalSteps}: Understand QR Failures`, + instructions: [ + "QR FAILURES TO FIX:", + "", + failuresXml, + "", + `There are ${itemCount} failure(s). You will fix them one at a time`, + `in steps 2 through ${totalSteps - 1}. Each step presents a single item.`, + "", + "For each failing item:", + " - Identify the scope (which milestone, decision, or intent)", + " - Understand what the check requires", + " - Read the finding to understand why it failed", + "", + "Use getter tools to inspect scoped entities:", + " - koan_get_plan: overview, structure, decisions", + " - koan_get_milestone: milestone details and intents", + " - koan_get_decision: decision rationale", + " - koan_get_intent: intent definition", + "", + "Note interactions between failures:", + " - Do any failures share the same entity scope?", + " - Could fixing one affect another's context?", + "", + "This is a READ-ONLY step. Do not apply any changes.", + ], + }; +} - case 2: - return { - title: "Step 2: Apply Targeted Fixes", - instructions: [ - "Apply the fixes you planned in step 1.", - "", - "Use plan mutation tools to address each failure:", - " - koan_set_overview / koan_set_constraints / koan_set_invisible_knowledge", - " - koan_set_milestone_* / koan_set_intent / koan_set_decision", - " - koan_add_milestone / koan_add_intent / koan_add_decision (if new entities needed)", - "", - "RULES:", - " - Fix ONLY the FAIL items from step 1", - " - Prefer updating existing entities over adding new ones", - " - Do not restructure the plan beyond what the failures require", - " - Do not change PASS items", - "", - "After applying all fixes, call koan_complete_step.", - ], - }; +// Per-item fix step. Shows only the single item being fixed so the LLM +// focuses on one failure rather than attempting batch fixes that produce +// cascading corrections. Mutations are enabled by the step gate in +// fix-phase.ts for this range. +// +// Positional context ("FIX ITEM N OF M") grounds the LLM in the sequence, +// matching the reference impl's "item {idx} of {total}" pattern. The +// explicit anti-batch gate ("Do not fix other failures") is the prompt-level +// complement to the code-level step gate that blocks mutations outside the +// per-item range. +function fixItemStepGuidance( + step: number, + totalSteps: number, + item?: QRItem, +): StepGuidance { + // Defensive fallbacks: handleStepComplete guarantees item is present for + // per-item steps (failures[next-2] is in-bounds), but the function signature + // accepts optional to keep it callable from tests or future call sites. + const itemXml = item ? formatFailuresXml([item]) : ""; + const itemLabel = item?.id ?? `item ${step - 1}`; + const itemIdx = step - 1; + const itemCount = totalSteps - 2; - case 3: - return { - title: "Step 3: Review & Finalize", - instructions: [ - "Review the fixes you applied.", - "", - "Call koan_get_plan to read the current plan state.", - "For each original failure, verify:", - " - The fix addresses the check that failed", - " - No regressions introduced in previously passing items", - " - The plan is internally consistent", - "", - "Summarize in the `thoughts` parameter of koan_complete_step:", - " - Which failures were fixed and how", - " - Any concerns or items that may still be at risk", - ], - // Step 3 requires reading the plan before completing -- the review - // is meaningless without it. The custom invokeAfter enforces this - // sequencing explicitly. - invokeAfter: [ - "WHEN DONE: First call koan_get_plan to confirm the final plan state.", - "Then call koan_complete_step with your review summary in the `thoughts` parameter.", - "Do NOT call koan_complete_step before calling koan_get_plan.", - ].join("\n"), - }; + return { + title: `Step ${step}/${totalSteps}: Fix ${itemLabel}`, + instructions: [ + `FIX ITEM ${itemIdx} OF ${itemCount}:`, + "", + itemXml, + "", + "Apply a targeted fix for this failure using your analysis from step 1.", + "", + "Available mutation tools:", + " - koan_set_overview / koan_set_constraints / koan_set_invisible_knowledge", + " - koan_set_milestone_* / koan_set_intent / koan_set_decision", + " - koan_add_milestone / koan_add_intent / koan_add_decision (if needed)", + "", + "RULES:", + " - Fix ONLY this failure. Do not fix other failures in this step.", + " - Prefer updating existing entities over adding new ones", + " - Do not restructure the plan beyond what this failure requires", + ], + }; +} - default: - throw new Error(`unexpected fix step: ${step as never}`); - } +// Final review step. Accepts only totalSteps because the call site guard +// (step === totalSteps) guarantees identity. A two-parameter form would +// create a hidden contract ("pass equal values") with no type enforcement. +// +// "All per-item fixes are complete" explicitly closes the mutation phase +// and establishes the read-only review frame. "This step is READ-ONLY" +// is the prompt-level complement to the step gate blocking mutations. +function fixFinalStepGuidance(totalSteps: number): StepGuidance { + return { + title: `Step ${totalSteps}/${totalSteps}: Review & Finalize`, + instructions: [ + "All per-item fixes are complete. This step is READ-ONLY.", + "", + "Call koan_get_plan to read the current plan state.", + "", + "Verify each fix:", + " - Does the fix address the specific check that failed?", + " - Are previously passing items unaffected?", + " - Is the plan internally consistent?", + "", + "Summarize in the `thoughts` parameter of koan_complete_step:", + " - Which failures were fixed and how", + " - Any remaining concerns or regression risks", + ], + // The review step requires reading the plan before completing -- + // the review is meaningless without it. The custom invokeAfter + // enforces this sequencing explicitly. + invokeAfter: [ + "WHEN DONE: First call koan_get_plan to confirm the final plan state.", + "Then call koan_complete_step with your review summary in the `thoughts` parameter.", + "Do NOT call koan_complete_step before calling koan_get_plan.", + ].join("\n"), + }; } From 9d15a864fd35c78ac43f8fcd69d7c296317a942a Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 26 Feb 2026 09:27:38 +0700 Subject: [PATCH 022/412] planner: preserve PASS items and re-verify prior FAILs in QR loop --- src/planner/session.ts | 192 +++++++++++++++++++++++++++++------------ 1 file changed, 139 insertions(+), 53 deletions(-) diff --git a/src/planner/session.ts b/src/planner/session.ts index 250cdbb..9aba9c3 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -224,6 +224,23 @@ async function runQRBlock( log: Logger, widget: WidgetController | null, ): Promise { + const qrPath = path.join(planDir, "qr-plan-design.json"); + const keyOf = (scope: string, check: string): string => `${scope}\u0000${check}`; + + // Carry forward confirmed PASS concerns across re-decompose runs. + const previousPassKeys = new Set(); + try { + const raw = await fs.readFile(qrPath, "utf8"); + const prev = JSON.parse(raw) as QRFile; + for (const item of prev.items) { + if (item.status === "PASS") { + previousPassKeys.add(keyOf(item.scope, item.check)); + } + } + } catch { + // No previous QR file yet. + } + // 1. Spawn decomposer subagent state.phase = "qr-decompose-running"; widget?.update({ @@ -271,7 +288,6 @@ async function runQRBlock( } // 2. Read QR items - const qrPath = path.join(planDir, "qr-plan-design.json"); let qr: QRFile; try { const raw = await fs.readFile(qrPath, "utf8"); @@ -289,62 +305,130 @@ async function runQRBlock( return { summary: "QR decompose completed but produced no items.", passed: false }; } - const itemIds = qr.items.map((i) => i.id); - const initialPass = qr.items.filter((i) => i.status === "PASS").length; + // Re-apply previously confirmed PASS concerns if re-decompose reset them. + const carriedPasses = qr.items.filter((item) => + item.status !== "PASS" && previousPassKeys.has(keyOf(item.scope, item.check))).length; + if (carriedPasses > 0) { + qr = { + ...qr, + items: qr.items.map((item) => + previousPassKeys.has(keyOf(item.scope, item.check)) + ? { ...item, status: "PASS", finding: null } + : item), + }; + try { + const tmpPath = `${qrPath}.tmp`; + await fs.writeFile(tmpPath, `${JSON.stringify(qr, null, 2)}\n`, "utf8"); + await fs.rename(tmpPath, qrPath); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + log("Failed to persist carried PASS statuses", { error: message }); + return { summary: "QR verify aborted: failed to preserve PASS statuses.", passed: false }; + } + } + + // Preserve prior PASS verdicts, but force all FAIL items back to TODO for + // re-verification. This keeps confirmed concerns stable while requiring + // explicit re-check of previously failing concerns. + const resetFailures = qr.items.filter((i) => i.status === "FAIL").length; + if (resetFailures > 0) { + qr = { + ...qr, + items: qr.items.map((item) => + item.status === "FAIL" + ? { ...item, status: "TODO", finding: null } + : item), + }; + try { + const tmpPath = `${qrPath}.tmp`; + await fs.writeFile(tmpPath, `${JSON.stringify(qr, null, 2)}\n`, "utf8"); + await fs.rename(tmpPath, qrPath); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + log("Failed to persist QR FAIL->TODO reset", { error: message }); + return { summary: "QR verify aborted: failed to prepare QR item states.", passed: false }; + } + } + + const verifyIds = qr.items.filter((i) => i.status === "TODO").map((i) => i.id); + const totalItems = qr.items.length; + const preservedPass = qr.items.filter((i) => i.status === "PASS").length; const initialFail = qr.items.filter((i) => i.status === "FAIL").length; const initialTodo = qr.items.filter((i) => i.status === "TODO").length; - log("QR decompose complete", { itemCount: itemIds.length }); + + log("QR decompose complete", { + itemCount: totalItems, + verifyCount: verifyIds.length, + preservedPass, + carriedPasses, + resetFailures, + }); + widget?.update({ - step: `qr-verify: 0/${itemIds.length}`, + step: `qr-verify: 0/${verifyIds.length}`, activity: "", - qrTotal: itemIds.length, - qrDone: 0, - qrPass: initialPass, + qrTotal: totalItems, + qrDone: preservedPass, + qrPass: preservedPass, qrFail: initialFail, qrTodo: initialTodo, }); - // 3. Spawn reviewer pool + // 3. Spawn reviewer pool (TODO-only) state.phase = "qr-verify-running"; widget?.update({ qrPhase: "verify" }); let verifyDone = 0; - const verifyStatsPoll = setInterval(async () => { - try { - const raw = await fs.readFile(qrPath, "utf8"); - const current = JSON.parse(raw) as QRFile; - const pass = current.items.filter((i) => i.status === "PASS").length; - const fail = current.items.filter((i) => i.status === "FAIL").length; - const todo = current.items.filter((i) => i.status === "TODO").length; - widget?.update({ qrPass: pass, qrFail: fail, qrTodo: todo, qrDone: verifyDone, qrTotal: current.items.length }); - } catch { - // Ignore transient read races while reviewers write. - } - }, 2000); + let failedReviewers: string[] = []; - let result: Awaited>; - try { - result = await pool( - itemIds, - QR_POOL_CONCURRENCY, - async (itemId) => { - const reviewerDir = await createSubagentDir(planDir, `qr-reviewer-${itemId}`); - return spawnReviewer({ - planDir, - subagentDir: reviewerDir, - cwd, - extensionPath, - itemId, - log, + if (verifyIds.length > 0) { + const verifyStatsPoll = setInterval(async () => { + try { + const raw = await fs.readFile(qrPath, "utf8"); + const current = JSON.parse(raw) as QRFile; + const pass = current.items.filter((i) => i.status === "PASS").length; + const fail = current.items.filter((i) => i.status === "FAIL").length; + const todo = current.items.filter((i) => i.status === "TODO").length; + widget?.update({ + qrPass: pass, + qrFail: fail, + qrTodo: todo, + qrDone: preservedPass + verifyDone, + qrTotal: current.items.length, }); - }, - (done, total) => { - verifyDone = done; - widget?.update({ step: `qr-verify: ${done}/${total}`, qrDone: done, qrTotal: total }); - }, - ); - } finally { - clearInterval(verifyStatsPoll); + } catch { + // Ignore transient read races while reviewers write. + } + }, 2000); + + try { + const result = await pool( + verifyIds, + QR_POOL_CONCURRENCY, + async (itemId) => { + const reviewerDir = await createSubagentDir(planDir, `qr-reviewer-${itemId}`); + return spawnReviewer({ + planDir, + subagentDir: reviewerDir, + cwd, + extensionPath, + itemId, + log, + }); + }, + (done, total) => { + verifyDone = done; + widget?.update({ + step: `qr-verify: ${done}/${total}`, + qrDone: preservedPass + done, + qrTotal: totalItems, + }); + }, + ); + failedReviewers = result.failed; + } finally { + clearInterval(verifyStatsPoll); + } } // 4. Read final results @@ -360,16 +444,16 @@ async function runQRBlock( const pass = finalQR.items.filter((i) => i.status === "PASS").length; const fail = finalQR.items.filter((i) => i.status === "FAIL").length; const todo = finalQR.items.filter((i) => i.status === "TODO").length; - const summary = `QR complete: ${pass} PASS, ${fail} FAIL, ${todo} TODO (${result.failed.length} reviewers failed).`; + const summary = `QR complete: ${pass} PASS, ${fail} FAIL, ${todo} TODO (${failedReviewers.length} reviewers failed).`; - log("QR block complete", { pass, fail, todo, failedReviewers: result.failed }); + log("QR block complete", { pass, fail, todo, failedReviewers }); - const passed = fail === 0 && result.failed.length === 0; + const passed = fail === 0 && failedReviewers.length === 0; widget?.update({ step: summary, activity: "", - qrDone: itemIds.length, - qrTotal: itemIds.length, + qrDone: pass + fail, + qrTotal: totalItems, qrPass: pass, qrFail: fail, qrTodo: todo, @@ -383,12 +467,14 @@ async function runQRBlock( // // Re-decomposes on each iteration rather than re-verifying only. The fix // architect may change plan structure (add milestones, split intents, remove -// decisions); old QR items referencing stale scopes produce incorrect verdicts. -// Fresh decomposition generates items matched to the current plan state. +// decisions); old QR items referencing stale scopes can produce stale verdicts. +// +// Verification semantics per iteration: +// - PASS items are preserved (confirmed concerns stay confirmed). +// - FAIL items are reset to TODO (must be re-verified after fixes). +// - TODO items are verified. // -// The session's for-loop counter is the iteration source of truth. Each -// re-decompose writes a fresh qr-plan-design.json with iteration=1 and -// all-TODO items. The loop counter survives those resets. +// The session's for-loop counter remains the iteration source of truth. async function runPlanDesignWithQR( planDir: string, cwd: string, From fe3b5051350e36db62185d34783284fc14a29586 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 26 Feb 2026 09:27:45 +0700 Subject: [PATCH 023/412] ui: show elapsed time with hours in planner widget --- src/planner/ui/widget.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/planner/ui/widget.ts b/src/planner/ui/widget.ts index 32114ca..c7249ce 100644 --- a/src/planner/ui/widget.ts +++ b/src/planner/ui/widget.ts @@ -179,8 +179,14 @@ function planningColumns(width: number): PlanningColumns { function formatElapsed(ms: number): string { const totalSec = Math.floor(ms / 1000); - const m = Math.floor(totalSec / 60); + const h = Math.floor(totalSec / 3600); + const m = Math.floor((totalSec % 3600) / 60); const s = totalSec % 60; + + if (h > 0) { + return `${h}h ${String(m).padStart(2, "0")}m ${String(s).padStart(2, "0")}s`; + } + return `${m}m ${String(s).padStart(2, "0")}s`; } From ba75b15e21cd7df6050f958a2cc2322b8bf3030e Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 26 Feb 2026 11:24:37 +0700 Subject: [PATCH 024/412] planner: persist subagent model in audit projection --- extensions/koan.ts | 14 +++++++++++--- src/planner/lib/audit.ts | 7 ++++++- tests/progress.test.ts | 6 +++++- 3 files changed, 22 insertions(+), 5 deletions(-) diff --git a/extensions/koan.ts b/extensions/koan.ts index 2dfd08c..613e8f3 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -3,7 +3,7 @@ // via CLI flags). All tools register unconditionally at init; phases restrict // access via tool_call blocking at runtime. -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; +import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"; import { createSession } from "../src/planner/session.js"; import { detectSubagentMode, dispatchPhase } from "../src/planner/phases/dispatch.js"; @@ -11,6 +11,12 @@ import { registerAllTools, createDispatch, createPlanRef } from "../src/planner/ import { createLogger } from "../src/utils/logger.js"; import { EventLog, extractToolEvent } from "../src/planner/lib/audit.js"; +function currentModelId(ctx: ExtensionContext): string | null { + const model = ctx.model; + if (!model) return null; + return `${model.provider}/${model.id}`; +} + export default function koan(pi: ExtensionAPI): void { const log = createLogger("Koan"); @@ -61,7 +67,7 @@ export default function koan(pi: ExtensionAPI): void { // Subagent detection runs at before_agent_start (flags // are unavailable during init). let dispatched = false; - pi.on("before_agent_start", async () => { + pi.on("before_agent_start", async (_event, ctx) => { if (dispatched) return; dispatched = true; const config = detectSubagentMode(pi); @@ -72,9 +78,11 @@ export default function koan(pi: ExtensionAPI): void { } // EventLog exists only in subagent mode. Parent mode has no audit log. + // Model identity is captured by the subagent itself and persisted in + // state.json for parent widget rendering. let eventLog: EventLog | undefined; if (config.subagentDir) { - eventLog = new EventLog(config.subagentDir, config.role, config.phase); + eventLog = new EventLog(config.subagentDir, config.role, config.phase, currentModelId(ctx)); await eventLog.open(); // Capture all tool results for the audit trail. Graduated detail: diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index 9d2f980..94e9d39 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -51,6 +51,7 @@ export interface PhaseStartEvent extends EventBase { kind: "phase_start"; phase: string; role: string; + model?: string | null; totalSteps: number; } @@ -84,6 +85,7 @@ export type AuditEvent = export interface Projection { role: string; phase: string; + model: string | null; status: "running" | "completed" | "failed"; step: number; totalSteps: number; @@ -142,6 +144,7 @@ export function fold(s: Projection, e: AuditEvent): Projection { ...base, role: e.role, phase: e.phase, + model: e.model ?? s.model, status: "running", step: 0, totalSteps: e.totalSteps, @@ -233,13 +236,14 @@ export class EventLog { // writeState() calls race on the shared tmp file (ENOENT on rename). private pending: Promise = Promise.resolve(); - constructor(dir: string, role: string, phase: string) { + constructor(dir: string, role: string, phase: string, model: string | null = null) { this.eventsPath = path.join(dir, "events.jsonl"); this.statePath = path.join(dir, "state.json"); this.stateTmpPath = path.join(dir, "state.tmp.json"); this.projection = { role, phase, + model, status: "running", step: 0, totalSteps: 0, @@ -284,6 +288,7 @@ export class EventLog { kind: "phase_start", phase: this.projection.phase, role: this.projection.role, + model: this.projection.model, totalSteps, } as Omit); } diff --git a/tests/progress.test.ts b/tests/progress.test.ts index 5891306..b1378a3 100644 --- a/tests/progress.test.ts +++ b/tests/progress.test.ts @@ -17,7 +17,7 @@ describe("EventLog", () => { it("persists events and projection through step transitions", async () => { const dir = await createTempDir("koan-audit-"); - const log = new EventLog(dir, "architect", "plan-design"); + const log = new EventLog(dir, "architect", "plan-design", "anthropic/claude-sonnet-4-20250514"); await log.open(); await log.emitPhaseStart(6); @@ -30,6 +30,7 @@ describe("EventLog", () => { assert.ok(proj, "projection should be readable"); assert.equal(proj.role, "architect"); assert.equal(proj.phase, "plan-design"); + assert.equal(proj.model, "anthropic/claude-sonnet-4-20250514"); assert.equal(proj.status, "completed"); assert.equal(proj.step, 2); assert.equal(proj.totalSteps, 6); @@ -155,6 +156,7 @@ describe("fold", () => { const initial: Projection = { role: "", phase: "", + model: null, status: "running", step: 0, totalSteps: 0, @@ -170,6 +172,7 @@ describe("fold", () => { kind: "phase_start", phase: "plan-design", role: "architect", + model: "openai/gpt-5-codex", totalSteps: 6, ts: "2026-01-01T00:00:00Z", seq: 0, @@ -177,6 +180,7 @@ describe("fold", () => { const s = fold(initial, e); assert.equal(s.role, "architect"); assert.equal(s.phase, "plan-design"); + assert.equal(s.model, "openai/gpt-5-codex"); assert.equal(s.totalSteps, 6); assert.equal(s.eventCount, 1); }); From 6e1ae8d2d0a822997c3dd5aa9525f4243e5928d6 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 26 Feb 2026 11:24:41 +0700 Subject: [PATCH 025/412] ui: render subagent runtime and identity in planner widget --- src/planner/lib/pool.ts | 27 ++++- src/planner/session.ts | 92 ++++++++++++++-- src/planner/ui/widget.ts | 227 +++++++++++++++++++++++++++++++++++---- 3 files changed, 315 insertions(+), 31 deletions(-) diff --git a/src/planner/lib/pool.ts b/src/planner/lib/pool.ts index f5e9c3f..f4bfcc8 100644 --- a/src/planner/lib/pool.ts +++ b/src/planner/lib/pool.ts @@ -12,6 +12,13 @@ export interface PoolResult { failed: string[]; } +export interface PoolProgress { + done: number; + total: number; + active: number; + queued: number; +} + // -- Constants -- export const DEFAULT_REVIEWER_TIMEOUT_MS = 10 * 60 * 1000; @@ -47,24 +54,40 @@ export async function pool( itemIds: string[], limit: number, worker: (itemId: string) => Promise, - onProgress?: (done: number, total: number) => void, + onProgress?: (progress: PoolProgress) => void, ): Promise { const sem = new Semaphore(limit); const total = itemIds.length; const failed: string[] = []; let completed = 0; + let running = 0; + + const emit = () => { + onProgress?.({ + done: completed, + total, + active: running, + queued: Math.max(0, total - completed - running), + }); + }; + + emit(); await Promise.all( itemIds.map(async (id) => { await sem.acquire(); + running++; + emit(); + try { const r = await worker(id); if (r.exitCode !== 0) { failed.push(id); } } finally { + running = Math.max(0, running - 1); completed++; - onProgress?.(completed, total); + emit(); sem.release(); } }), diff --git a/src/planner/session.ts b/src/planner/session.ts index 9aba9c3..ba24055 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -13,12 +13,12 @@ import { createPlanInfo } from "../utils/plan.js"; import { spawnArchitect, spawnArchitectFix, spawnQRDecomposer, spawnReviewer } from "./subagent.js"; import { createLogger, setLogDir, type Logger } from "../utils/logger.js"; import { createSubagentDir } from "../utils/progress.js"; -import { readProjection, readRecentLogs } from "./lib/audit.js"; +import { readProjection, readRecentLogs, type Projection } from "./lib/audit.js"; import type { WorkflowDispatch, PlanRef } from "./lib/dispatch.js"; import { pool } from "./lib/pool.js"; import type { QRFile } from "./qr/types.js"; import { MAX_FIX_ITERATIONS, qrPassesAtIteration } from "./qr/severity.js"; -import { WidgetController } from "./ui/widget.js"; +import { WidgetController, type WidgetUpdate } from "./ui/widget.js"; // -- Types -- @@ -33,6 +33,28 @@ interface QRBlockResult { passed: boolean; } +function singleSubagentStart(role: string): WidgetUpdate { + return { + subagentRole: role, + subagentParallelCount: 1, + subagentQueued: 0, + subagentActive: 1, + subagentDone: 0, + }; +} + +function singleSubagentFromProjection(p: Projection): WidgetUpdate { + const running = p.status === "running"; + return { + subagentRole: p.role, + subagentModel: p.model, + subagentParallelCount: 1, + subagentQueued: 0, + subagentActive: running ? 1 : 0, + subagentDone: running ? 0 : 1, + }; +} + // -- Session -- export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, planRef: PlanRef): Session { @@ -71,6 +93,7 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan qrPass: null, qrFail: null, qrTodo: null, + ...singleSubagentStart("architect"), }); log("Spawning architect after context capture", { planDir, subagentDir }); @@ -86,6 +109,7 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan step: s.stepName, activity: s.lastAction ?? "", logLines: logs, + ...singleSubagentFromProjection(s), }); } }, 2000); @@ -108,6 +132,8 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan phaseStatus: { index: 1, status: "failed" }, step: "architect failed", activity: "", + subagentActive: 0, + subagentDone: 1, }); return `Context captured. Architect subagent failed (exit ${result.exitCode}).\n\nStderr:\n${detail}`; } @@ -127,6 +153,8 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan phaseStatus: { index: 1, status: "failed" }, step: "no plan produced", activity: "", + subagentActive: 0, + subagentDone: 1, }); return "Context captured. Architect completed but produced no plan."; } @@ -146,6 +174,8 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan qrPass: null, qrFail: null, qrTodo: null, + subagentActive: 0, + subagentDone: 1, }); const qr = await runPlanDesignWithQR(planDir, ctx.cwd, extensionPath, state, log, widget); @@ -252,6 +282,7 @@ async function runQRBlock( qrPass: null, qrFail: null, qrTodo: null, + ...singleSubagentStart("qr-decomposer"), }); const decomposeDir = await createSubagentDir(planDir, "qr-decomposer"); @@ -265,6 +296,7 @@ async function runQRBlock( step: `qr-decompose: ${s.stepName}`, activity: s.lastAction ?? "", logLines: logs, + ...singleSubagentFromProjection(s), }); } }, 2000); @@ -283,7 +315,12 @@ async function runQRBlock( state.phase = "qr-decompose-failed"; const detail = decompose.stderr.slice(0, 500); log("QR decomposer failed", { exitCode: decompose.exitCode, stderr: detail }); - widget?.update({ step: "qr-decompose: failed", activity: "" }); + widget?.update({ + step: "qr-decompose: failed", + activity: "", + subagentActive: 0, + subagentDone: 1, + }); return { summary: `QR decompose failed (exit ${decompose.exitCode}).\n\nStderr:\n${detail}`, passed: false }; } @@ -372,6 +409,11 @@ async function runQRBlock( qrPass: preservedPass, qrFail: initialFail, qrTodo: initialTodo, + subagentRole: "reviewer", + subagentParallelCount: QR_POOL_CONCURRENCY, + subagentQueued: verifyIds.length, + subagentActive: 0, + subagentDone: 0, }); // 3. Spawn reviewer pool (TODO-only) @@ -402,12 +444,13 @@ async function runQRBlock( }, 2000); try { + let reviewerModel: string | null = null; const result = await pool( verifyIds, QR_POOL_CONCURRENCY, async (itemId) => { const reviewerDir = await createSubagentDir(planDir, `qr-reviewer-${itemId}`); - return spawnReviewer({ + const r = await spawnReviewer({ planDir, subagentDir: reviewerDir, cwd, @@ -415,13 +458,26 @@ async function runQRBlock( itemId, log, }); + + if (reviewerModel === null) { + const projection = await readProjection(reviewerDir); + reviewerModel = projection?.model ?? null; + if (reviewerModel) { + widget?.update({ subagentModel: reviewerModel }); + } + } + + return r; }, - (done, total) => { - verifyDone = done; + (progress) => { + verifyDone = progress.done; widget?.update({ - step: `qr-verify: ${done}/${total}`, - qrDone: preservedPass + done, + step: `qr-verify: ${progress.done}/${progress.total}`, + qrDone: preservedPass + progress.done, qrTotal: totalItems, + subagentQueued: progress.queued, + subagentActive: progress.active, + subagentDone: progress.done, }); }, ); @@ -457,6 +513,9 @@ async function runQRBlock( qrPass: pass, qrFail: fail, qrTodo: todo, + subagentQueued: 0, + subagentActive: 0, + subagentDone: verifyIds.length, }); return { summary, passed }; } @@ -542,7 +601,12 @@ async function runPlanDesignWithQR( // Spawn fix-mode architect const fixIndex = iteration - 1; - widget?.update({ step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: spawning architect...`, activity: "", qrPhase: "execute" }); + widget?.update({ + step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: spawning architect...`, + activity: "", + qrPhase: "execute", + ...singleSubagentStart("architect"), + }); const fixDir = await createSubagentDir(planDir, `architect-fix-${fixIndex}`); @@ -556,6 +620,7 @@ async function runPlanDesignWithQR( step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: ${s.stepName}`, activity: s.lastAction ?? "", logLines: logs, + ...singleSubagentFromProjection(s), }); } }, 2000); @@ -573,13 +638,20 @@ async function runPlanDesignWithQR( if (fixResult.exitCode !== 0) { log("Fix architect failed", { iteration: fixIndex, exitCode: fixResult.exitCode, stderr: fixResult.stderr.slice(0, 500) }); - widget?.update({ step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: architect failed, re-running QR...`, activity: "" }); + widget?.update({ + step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: architect failed, re-running QR...`, + activity: "", + subagentActive: 0, + subagentDone: 1, + }); } // Re-run full QR (decompose + verify) widget?.update({ step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: re-running QR...`, activity: "", + subagentActive: 0, + subagentDone: 1, }); qr = await runQRBlock(planDir, cwd, extensionPath, state, log, widget); if (qr.passed) { diff --git a/src/planner/ui/widget.ts b/src/planner/ui/widget.ts index c7249ce..90ecc5a 100644 --- a/src/planner/ui/widget.ts +++ b/src/planner/ui/widget.ts @@ -46,6 +46,12 @@ interface WidgetState { qrPass: number | null; qrFail: number | null; qrTodo: number | null; + subagentRole: string | null; + subagentModel: string | null; + subagentParallelCount: number | null; + subagentQueued: number | null; + subagentActive: number | null; + subagentDone: number | null; } export interface WidgetUpdate { @@ -64,6 +70,12 @@ export interface WidgetUpdate { qrPass?: number | null; qrFail?: number | null; qrTodo?: number | null; + subagentRole?: string | null; + subagentModel?: string | null; + subagentParallelCount?: number | null; + subagentQueued?: number | null; + subagentActive?: number | null; + subagentDone?: number | null; } // -- Constants -- @@ -446,33 +458,160 @@ interface DetailSections { footer: string[]; } +interface DetailSectionDefinition { + id: string; + placement: "core" | "footer"; + select: (state: WidgetState) => ViewModel | null; + render: (view: ViewModel, theme: Theme, width: number) => string[]; +} + +interface CurrentStepView { + title: string; + activity: string; +} + +interface IdentityView { + planId: string; + agentLabel: "Agent" | "Agent pool"; + agentValue: string; + model: string; +} + +const IDENTITY_KEY_WIDTH = 10; + +function shouldShowSubagentSection(state: WidgetState): boolean { + if (state.subagentRole) return true; + return state.subagentQueued !== null || state.subagentActive !== null || state.subagentDone !== null; +} + +function subagentCount(value: number | null): string { + return value === null ? "-" : String(value); +} + +function renderSubagentStatusSection(state: WidgetState, theme: Theme, width: number): string[] { + if (!shouldShowSubagentSection(state)) { + return []; + } + + const parallel = state.subagentParallelCount ?? 1; + const mode = parallel > 1 ? `pool x${parallel}` : "single"; + + const header = clampToWidth( + `${theme.bold(theme.fg("accent", "Subagents"))} ${theme.fg("muted", "|")} ${theme.fg("dim", mode)}`, + width, + "…", + ); + + const counters = [ + `${theme.fg("muted", "queued:")}${theme.fg("muted", subagentCount(state.subagentQueued))}`, + `${theme.fg("muted", "active:")}${theme.bold(theme.fg("accent", subagentCount(state.subagentActive)))}`, + `${theme.fg("muted", "done:")}${theme.fg("dim", subagentCount(state.subagentDone))}`, + ].join(" "); + + const divider = clampToWidth(theme.fg("muted", "─".repeat(width)), width); + return [header, clampToWidth(counters, width, "…"), divider]; +} + +function identityView(state: WidgetState): IdentityView { + const role = state.subagentRole ?? "—"; + const parallel = state.subagentParallelCount ?? 1; + + if (parallel > 1) { + return { + planId: state.planId, + agentLabel: "Agent pool", + agentValue: `${role} x${parallel}`, + model: state.subagentModel ?? "—", + }; + } + + return { + planId: state.planId, + agentLabel: "Agent", + agentValue: role, + model: state.subagentModel ?? "—", + }; +} + +function renderIdentityRow(theme: Theme, width: number, key: string, value: string): string { + const padded = key.padEnd(IDENTITY_KEY_WIDTH, " "); + return clampToWidth(`${theme.fg("muted", padded)} : ${theme.fg("dim", value)}`, width, "…"); +} + +function renderIdentitySection(view: IdentityView, theme: Theme, width: number): string[] { + return [ + renderIdentityRow(theme, width, "Plan ID", view.planId), + renderIdentityRow(theme, width, view.agentLabel, view.agentValue), + renderIdentityRow(theme, width, "Model", view.model), + ]; +} + +const DETAIL_SECTION_REGISTRY: Array> = [ + { + id: "current-step", + placement: "core", + select: (state: WidgetState): CurrentStepView => { + const active = activePhase(state); + return { + title: state.step || active?.detail || active?.label || "Awaiting step", + activity: state.activity, + }; + }, + render: (view: CurrentStepView, theme: Theme, width: number): string[] => { + const lines = [ + clampToWidth(theme.fg("dim", "Current step"), width), + clampToWidth(theme.bold(theme.fg("accent", view.title)), width, "…"), + ]; + + if (view.activity) { + for (const line of wrapTextWithAnsi(theme.fg("muted", view.activity), width)) { + lines.push(clampToWidth(line, width)); + } + } + + return lines; + }, + }, + { + id: "qr-status", + placement: "core", + select: (state: WidgetState): WidgetState | null => (shouldShowQR(state) ? state : null), + render: (view: WidgetState, theme: Theme, width: number): string[] => renderQRStatusSection(view, theme, width), + }, + { + id: "subagent-status", + placement: "core", + select: (state: WidgetState): WidgetState | null => (shouldShowSubagentSection(state) ? state : null), + render: (view: WidgetState, theme: Theme, width: number): string[] => renderSubagentStatusSection(view, theme, width), + }, + { + id: "identity", + placement: "footer", + select: (state: WidgetState): IdentityView => identityView(state), + render: (view: IdentityView, theme: Theme, width: number): string[] => renderIdentitySection(view, theme, width), + }, +]; + function buildDetailSections(state: WidgetState, theme: Theme, width: number): DetailSections { const core: string[] = []; const footer: string[] = []; const blank = clampToWidth("", width); - const active = activePhase(state); - const stepTitle = state.step || active?.detail || active?.label || "Awaiting step"; - core.push(clampToWidth(theme.fg("dim", "Current step"), width)); - core.push(clampToWidth(theme.bold(theme.fg("accent", stepTitle)), width, "…")); - - if (state.activity) { - const activityLines = wrapTextWithAnsi(theme.fg("muted", state.activity), width); - for (const line of activityLines) { - core.push(clampToWidth(line, width)); - } - } + for (const section of DETAIL_SECTION_REGISTRY) { + const view = section.select(state); + if (!view) continue; - const qrSection = renderQRStatusSection(state, theme, width); - if (qrSection.length > 0) { - if (core.length > 0 && core[core.length - 1].trim() !== "") { - core.push(blank); + const rendered = section.render(view, theme, width).map((line) => clampToWidth(line, width)); + if (section.placement === "core") { + if (rendered.length === 0) continue; + if (core.length > 0 && core[core.length - 1].trim() !== "") { + core.push(blank); + } + core.push(...rendered); + continue; } - core.push(...qrSection.map((line) => clampToWidth(line, width))); - } - if (active) { - footer.push(...wrapTextWithAnsi(theme.fg("dim", `Plan · ${state.planId}`), width).map((line) => clampToWidth(line, width, "…"))); + footer.push(...rendered); } return { core, footer }; @@ -540,6 +679,14 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st if (qrCompact.length > 0) { fallbackContent.push(...qrCompact); } + const subagentCompact = formatSubagentCompact(state, theme, contentWidth); + if (subagentCompact.length > 0) { + if (qrCompact.length > 0) fallbackContent.push(""); + fallbackContent.push(...subagentCompact); + } + + fallbackContent.push(""); + fallbackContent.push(...formatIdentityCompact(state, theme, contentWidth)); fallbackContent.push(""); const body = indentLines(fallbackContent, innerWidth); @@ -719,6 +866,24 @@ function formatQRCompact(state: WidgetState, theme: Theme, width: number): strin return [line1, line2]; } +function formatSubagentCompact(state: WidgetState, theme: Theme, width: number): string[] { + if (!shouldShowSubagentSection(state)) return []; + + const parallel = state.subagentParallelCount ?? 1; + const mode = parallel > 1 ? `pool x${parallel}` : "single"; + const line1 = clampToWidth(`${theme.fg("muted", "Subagents")} ${theme.fg("muted", "|")} ${theme.fg("dim", mode)}`, width, "…"); + const line2 = clampToWidth( + `${theme.fg("muted", `queued:${subagentCount(state.subagentQueued)}`)} ${theme.fg("accent", `active:${subagentCount(state.subagentActive)}`)} ${theme.fg("dim", `done:${subagentCount(state.subagentDone)}`)}`, + width, + "…", + ); + return [line1, line2]; +} + +function formatIdentityCompact(state: WidgetState, theme: Theme, width: number): string[] { + return renderIdentitySection(identityView(state), theme, width); +} + function formatStepLine(state: WidgetState, theme: Theme): string { const total = state.phases.length; const active = activePhase(state); @@ -814,6 +979,12 @@ export class WidgetController { qrPass: null, qrFail: null, qrTodo: null, + subagentRole: null, + subagentModel: null, + subagentParallelCount: null, + subagentQueued: null, + subagentActive: null, + subagentDone: null, }; this.state.phases[0].status = "running"; @@ -876,6 +1047,24 @@ export class WidgetController { if (patch.qrTodo !== undefined) { this.state.qrTodo = patch.qrTodo; } + if (patch.subagentRole !== undefined) { + this.state.subagentRole = patch.subagentRole; + } + if (patch.subagentModel !== undefined) { + this.state.subagentModel = patch.subagentModel; + } + if (patch.subagentParallelCount !== undefined) { + this.state.subagentParallelCount = patch.subagentParallelCount; + } + if (patch.subagentQueued !== undefined) { + this.state.subagentQueued = patch.subagentQueued; + } + if (patch.subagentActive !== undefined) { + this.state.subagentActive = patch.subagentActive; + } + if (patch.subagentDone !== undefined) { + this.state.subagentDone = patch.subagentDone; + } this.doRender(); } From 1d96d9550715a8dedaea8bdd3c0d2f08f0d1bbdf Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 27 Feb 2026 16:01:04 +0700 Subject: [PATCH 026/412] refactor planning widget header layout and add coverage --- design-decisions.md | 13 +++- docs/planning-widget.md | 137 +++++++++++++++++++++++++++------- src/planner/ui/widget.ts | 156 ++++++++++++++++++++++++++++----------- tests/widget.test.ts | 114 ++++++++++++++++++++++++++++ 4 files changed, 350 insertions(+), 70 deletions(-) create mode 100644 tests/widget.test.ts diff --git a/design-decisions.md b/design-decisions.md index a6027c4..54c56b8 100644 --- a/design-decisions.md +++ b/design-decisions.md @@ -226,7 +226,8 @@ Step 6: plan mutation tools unlocked. - Implementation guardrails: - Continue rendering through `canvasLine()` so the background fills full terminal width. - Keep consistent card padding and solid-border framing through shared `renderBox()` helpers. - - Phase chips use stable semantic tokens (accent active, bold muted completed, muted pending, error failed). + - Header metadata carries active workflow context (`Planning · · `), with timer right-aligned on the same row. + - The old phase-tab strip is removed (no duplicated heading context). - Vertical rail remains width-bounded (~20 cols) so the right detail pane keeps enough budget for high-signal telemetry. - Detail footer (`Plan · id`) is pinned bottom via dynamic padding, independent of timeline density. - Planning body and latest-log body share one outer card, separated by an internal divider for better cohesion. @@ -258,6 +259,16 @@ Step 6: plan mutation tools unlocked. - Counter line emphasizes severity (`fail` highlighted in error color) so blocking issues pop in long sessions. - Detail pane hierarchy is explicit: `Current step` label first, then step body, then QR section. +### UI-4: Header-First Metadata (No Tabs Row) +- Chosen on Feb 26 2026 via follow-up deck focused on full-widget renders (`Phase-first header`). +- Rationale: the old title + tabs combination duplicated active-phase context and made the top of the widget feel offset from the frame. Consolidating into a full-width metadata header improves hierarchy and scan speed. +- Contract: + - Keep a full top border and render one header row: `Planning · · ` + right-aligned elapsed timer. + - Remove the dedicated tabs/chips row under the title. + - Keep phase progression in the left timeline rail (status history remains visible without tabs). + - Apply deterministic truncation in this order when width is constrained: abbreviate status -> drop status -> abbreviate phase label -> ellipsis. + - Footer identity table remains key/value aligned: `Plan ID`, `Agent`/`Agent pool`, `Model`. + ## Workflow Dispatch Architecture ### WorkflowDispatch (dispatch pattern) diff --git a/docs/planning-widget.md b/docs/planning-widget.md index 19d8c0d..36c51e4 100644 --- a/docs/planning-widget.md +++ b/docs/planning-widget.md @@ -5,6 +5,7 @@ The planning widget now follows the design-deck contract selected on Feb 25 2026 - **Canvas direction:** Stacked Modular Cards - **Navigation direction:** Vertical Timeline Rail +- **Header strategy:** Full-width top border + metadata header row (active phase in header, no tabs strip) - **Log strategy:** Declarative shape-table serialization + dense two-column layout - **QR strategy:** Inline integrated section (not a detached sub-card) @@ -46,44 +47,83 @@ The goal is to keep a long-running (1-2h) planning session readable in real time **Rationale:** QR is not optional side telemetry; it is the acceptance loop for the plan. The UI should communicate that structural importance while remaining legible and shape-stable at smaller widths. +### 5) Header-first metadata, tabs removed +- Keep a full top border and put active workflow context directly in the header row. +- Header format is phase-first: `Planning · · ` on the left, elapsed timer right-aligned. +- Remove the separate phase-tabs strip entirely; it is redundant once active context is in the header. +- Keep timeline rows in the body (left rail) because they provide progression context and status history, unlike tabs. + +**Rationale:** The previous title treatment felt detached from the frame and duplicated information with the tabs row. Consolidating context into the header yields a cleaner hierarchy and better information density in TUI constraints. + ## Layout Overview ``` -┌──────────────────────────────── Planning ────────────────────────────────────┐ -│ ┃ Context gathering ┃ ┃ Plan design ┃ ┃ Plan code ┃ ┃ Plan docs ┃ │ -│ │ -│ ● Context gathering qr-decompose: Step 2/13: Holistic Concerns │ -│ │ DONE read CLAUDE.md · 41L/1709c │ -│ │ │ -│ ● Plan design QR | phase:decompose · iter 1/6 initial │ -│ │ CURRENT Execute → QR decompose → QR verify │ -│ │ done:0/24 pass:0 fail:0 todo:24 │ -│ │ ──────────────────────────────────────────────── │ -│ ○ Plan code Plan · │ -│ │ UPCOMING │ -│ ○ Plan docs │ -│──────────────────────────────────────────────────────────────────────────────│ -│ Latest log │ -│ koan_set_milestone_tests id=M-002 · tests:["covers retries"] +7 │ -│ koan_get_milestone id=M-002 · resp:42L/3.1k │ -│ koan_add_intent milestone=M-002 · file=src/planner/ui/widget.ts │ -│ koan_set_change_diff id=CC-M-001-002 · diff:184L/9.2k │ -│ koan_qr_assign_group phase=plan-design · ids:[QR-001] +11 │ -└──────────────────────────────────────────────────────────────────────────────┘ +┌────────────────────────────────────────────────────────────────────────────────┐ +│ Planning · Context gathering · CURRENT 12m 22s │ +│ │ +│ ● Context gathering Current step │ +│ │ DONE Step 2/6: Codebase Exploration │ +│ │ read internal/rules/CLAUDE.md · 17L/1.2k │ +│ ● Plan design QR | phase:execute · iter 1/6 initial │ +│ │ CURRENT Execute → QR decompose → QR verify │ +│ ○ Plan code done:0/- pass:0 fail:0 todo:- │ +│ │ UPCOMING Subagents queued:0 active:1 done:0 │ +│ ○ Plan docs Plan ID : │ +│ UPCOMING Agent : architect │ +│ Model : openai-codex/gpt-5.3-codex │ +│────────────────────────────────────────────────────────────────────────────────│ +│ Latest log │ +│ koan_set_milestone_tests id=M-002 · tests:["covers retries"] +7 │ +│ koan_get_milestone id=M-002 · resp:42L/3.1k │ +│ koan_add_intent milestone=M-002 · file=src/planner/ui/widget.ts │ +│ koan_set_change_diff id=CC-M-001-002 · diff:184L/9.2k │ +│ koan_qr_assign_group phase=plan-design · ids:[QR-001] +11 │ +└────────────────────────────────────────────────────────────────────────────────┘ ``` ## Rendering Guide 1. **Canvas** – Keep using `canvasLine()` so widget content remains full-width over `toolPendingBg`. -2. **Main card** – Keep solid border + consistent inner padding via shared `renderBox()` helper. -3. **Timeline rail** – Maintain status icon/color semantics (`active=accent`, `done=dim`, `failed=error`). -4. **Detail pane** – Render in this order: +2. **Main card** – Keep one solid outer border + a full top rule. No cutout title and no detached title badge. +3. **Header row** – Render `Planning · · ` on the left and elapsed timer right-aligned on the same row. +4. **No tabs strip** – Do not render a separate phase-tabs row under the header. Active phase context now lives in header metadata. +5. **Timeline rail** – Maintain status icon/color semantics (`active=accent`, `done=dim`, `failed=error`). +6. **Detail pane** – Render in this order: - a dim section label (`Current step`) to create hierarchy - step title + optional activity - QR integrated section (if visible) - - footer metadata (`Plan · ID`) pinned to bottom via dynamic padding -5. **QR section** – Use inline header + phase rail + metadata line + divider. Avoid nested border style to keep it visually native to the right pane. Keep line geometry stable (fixed 3-line payload + divider) and enforce a 64-char metadata budget before clamping to pane width. -6. **Latest log section** – Keep it inside the same outer card, separated by a horizontal divider. Reuse the same left/right column split (`timelineWidth` / `detailWidth`) and gap as the planning body so vertical alignment stays consistent. + - subagent counters (`queued/active/done`) when available + - identity table (`Plan ID`, `Agent`/`Agent pool`, `Model`) pinned low in pane +7. **QR section** – Use inline header + phase rail + metadata line + divider. Avoid nested border style to keep it visually native to the right pane. Keep line geometry stable (fixed 3-line payload + divider) and enforce a 64-char metadata budget before clamping to pane width. +8. **Latest log section** – Keep it inside the same outer card, separated by a horizontal divider. Reuse the same left/right column split (`timelineWidth` / `detailWidth`) and gap as the planning body so vertical alignment stays consistent. + +## Header + Alignment Contract + +### Header composition +- Inner card width is `W` (visible cells, excluding borders). +- Timer token is right-aligned and reserved first (`T` visible cells). +- Left header budget is `W - T - 1` (one spacer between left and right chunks). +- Base left chunk: `Planning · · `. + +### Progressive compaction (left header) +Apply in order until it fits: +1. `CURRENT` -> `CUR`, `UPCOMING` -> `UP`, `DONE` unchanged. +2. Drop status chunk (keep `Planning · `). +3. Abbreviate known phases (`Context gathering` -> `Ctx gather`, `Plan design` -> `Design`, `Plan code` -> `Code`, `Plan docs` -> `Docs`). +4. Ellipsize active phase tail (`Planning · `). + +### Metadata table alignment +- Keys are fixed labels: `Plan ID`, `Agent` or `Agent pool`, `Model`. +- Compute key column width from max visible key length in the rendered set. +- Use a fixed `" : "` separator. +- Values are right-column free text, truncated with ellipsis when overflowing pane width. + +### Latest-log alignment +- Keep deterministic two-column geometry shared with body split. +- Left column width is based on observed max tool name (capped); right column gets remaining width. +- High-value rows may wrap to two lines max; second line must still obey right-column width budget. ## Data Contract Notes +- Header metadata state includes: + - `activePhaseLabel`, `activePhaseStatus`, `elapsed` - `LogLine` now carries: - `tool` (left column) - `summary` (right column) @@ -95,3 +135,46 @@ The goal is to keep a long-running (1-2h) planning session readable in real time ## Future Work (contracted, not yet implemented) - Plan execution phase should reuse the same QR integrated section semantics. - Optional compact mode for very narrow terminals can reduce metadata verbosity while preserving deterministic ordering. + +## Update: Runtime Domains + Subagent Identity (2026-02-26) + +This update captures follow-up decisions for showing subagent model information +and clarifying QR vs. parallel subagent semantics. + +### Domain split (do not merge) +- **QR section** tracks quality state: `todo`, `pass`, `fail`. +- **Subagents section** tracks execution state: `queued`, `active`, `done`. +- These are sibling runtime views. They are related in workflow, but not + collapsed into one metric family. + +### `x` meaning in parallel mode +- `x` means configured pool capacity (target parallelism), not active count. +- Active movement remains in `queued/active/done` counters. + +### Footer identity table standard +Use a unified key/value footer block: + +- `Plan ID : ` +- `Agent : ` (single subagent) +- `Agent pool : x` (parallel mode) +- `Model : ` + +### Generic rendering rule +The widget should remain role-agnostic and render identity from generic metadata +only: +- `role` +- `parallelCount` +- `model` + +Label/value rule: +- `parallelCount > 1` -> `Agent pool : x` +- otherwise -> `Agent : ` + +### View-composition pattern +Use section-level selectors/renderers (React-view-like composition without +React) so QR, subagent status, and identity/footer blocks are independently +composable and testable. + +### Decision hygiene +A separate "layout pattern" decision was deemed redundant once the domain split +was chosen; track it as derived behavior, not as a distinct product decision. diff --git a/src/planner/ui/widget.ts b/src/planner/ui/widget.ts index 90ecc5a..84320cc 100644 --- a/src/planner/ui/widget.ts +++ b/src/planner/ui/widget.ts @@ -217,23 +217,84 @@ function normalizeLogLines(lines: readonly LogLine[] | undefined): LogLine[] { return [...lines].slice(-(LOG_LINES * 2)); } -function phaseChipLabel(phase: PhaseEntry, index: number, state: WidgetState, theme: Theme): string { - const label = `┃ ${phase.label} ┃`; - if (index === state.activeIndex) { - return theme.bold(theme.fg("accent", label)); +const HEADER_STATUS_SHORT: Record = { + CURRENT: "CUR", + UPCOMING: "UP", + DONE: "DONE", + FAILED: "FAIL", +}; + +const HEADER_PHASE_SHORT: Record = { + "Context gathering": "Ctx gather", + "Plan design": "Design", + "Plan code": "Code", + "Plan docs": "Docs", +}; + +interface PlanningHeaderVariant { + label: string; + phase: string | null; + status: string | null; +} + +function selectPlanningHeaderVariant(phaseLabel: string, statusLabel: string, budget: number): PlanningHeaderVariant { + const phaseShort = HEADER_PHASE_SHORT[phaseLabel] ?? phaseLabel; + const statusShort = HEADER_STATUS_SHORT[statusLabel] ?? statusLabel; + + const truncatedPhase = truncateToWidth( + phaseShort, + Math.max(0, budget - visibleWidth("Planning · ")), + "…", + false, + ); + + const candidates: PlanningHeaderVariant[] = [ + { label: `Planning · ${phaseLabel} · ${statusLabel}`, phase: phaseLabel, status: statusLabel }, + { label: `Planning · ${phaseLabel} · ${statusShort}`, phase: phaseLabel, status: statusShort }, + { label: `Planning · ${phaseLabel}`, phase: phaseLabel, status: null }, + { label: `Planning · ${phaseShort}`, phase: phaseShort, status: null }, + { label: `Planning · ${truncatedPhase}`, phase: truncatedPhase, status: null }, + { label: "Planning", phase: null, status: null }, + ]; + + for (const candidate of candidates) { + if (visibleWidth(candidate.label) <= budget) { + return candidate; + } } - if (phase.status === "completed") { - return theme.bold(theme.fg("muted", label)); + + return { + label: truncateToWidth("Planning", budget, "…", false), + phase: null, + status: null, + }; +} + +export function formatPlanningHeaderLabel(phaseLabel: string, statusLabel: string, budget: number): string { + return selectPlanningHeaderVariant(phaseLabel, statusLabel, budget).label; +} + +function renderPlanningHeader(state: WidgetState, theme: Theme, budget: number): string { + const active = activePhase(state); + const phaseLabel = active?.label ?? "Complete"; + const statusLabel = (active ? STATUS_TAG[active.status] : "done").toUpperCase(); + const variant = selectPlanningHeaderVariant(phaseLabel, statusLabel, budget); + + if (!variant.label.startsWith("Planning")) { + return theme.bold(theme.fg("accent", variant.label)); } - if (phase.status === "failed") { - return theme.fg("error", label); + + const statusColor: ThemeColor = active ? STATUS_COLOR[active.status] : "dim"; + + if (!variant.phase) { + return theme.bold(theme.fg("accent", variant.label)); } - return theme.fg("muted", label); -} -function renderPhaseChips(state: WidgetState, theme: Theme, width: number): string { - const chips = state.phases.map((phase, index) => phaseChipLabel(phase, index, state, theme)); - return clampToWidth(chips.join(" "), width, "…"); + let result = `${theme.bold(theme.fg("accent", "Planning"))}${theme.fg("muted", " · ")}${theme.fg("muted", variant.phase)}`; + if (variant.status) { + result += `${theme.fg("muted", " · ")}${theme.bold(theme.fg(statusColor, variant.status))}`; + } + return result; } function renderTimelineLines(state: WidgetState, theme: Theme, width: number): string[] { @@ -477,8 +538,6 @@ interface IdentityView { model: string; } -const IDENTITY_KEY_WIDTH = 10; - function shouldShowSubagentSection(state: WidgetState): boolean { if (state.subagentRole) return true; return state.subagentQueued !== null || state.subagentActive !== null || state.subagentDone !== null; @@ -533,16 +592,18 @@ function identityView(state: WidgetState): IdentityView { }; } -function renderIdentityRow(theme: Theme, width: number, key: string, value: string): string { - const padded = key.padEnd(IDENTITY_KEY_WIDTH, " "); +function renderIdentityRow(theme: Theme, width: number, keyWidth: number, key: string, value: string): string { + const padded = key.padEnd(keyWidth, " "); return clampToWidth(`${theme.fg("muted", padded)} : ${theme.fg("dim", value)}`, width, "…"); } function renderIdentitySection(view: IdentityView, theme: Theme, width: number): string[] { + const keys = ["Plan ID", view.agentLabel, "Model"]; + const keyWidth = Math.max(...keys.map((key) => visibleWidth(key))); return [ - renderIdentityRow(theme, width, "Plan ID", view.planId), - renderIdentityRow(theme, width, view.agentLabel, view.agentValue), - renderIdentityRow(theme, width, "Model", view.model), + renderIdentityRow(theme, width, keyWidth, "Plan ID", view.planId), + renderIdentityRow(theme, width, keyWidth, view.agentLabel, view.agentValue), + renderIdentityRow(theme, width, keyWidth, "Model", view.model), ]; } @@ -661,9 +722,31 @@ function renderBox( return [top, ...content, bottom]; } +function renderBoxWithHeaderRow( + headerLeft: string, + headerRight: string, + body: string[], + width: number, + border: BorderStyle = BORDER_SOLID, +): string[] { + const innerWidth = Math.max(0, width - 2); + const left = visibleWidth(headerLeft) > innerWidth ? truncateToWidth(headerLeft, innerWidth, "", false) : headerLeft; + const right = visibleWidth(headerRight) > innerWidth ? truncateToWidth(headerRight, innerWidth, "", false) : headerRight; + const headerContent = rightAlign(left, right, innerWidth); + + const top = `${border.topLeft}${clampToWidth(border.horizontal.repeat(innerWidth), innerWidth)}${border.topRight}`; + const header = `${border.vertical}${clampToWidth(headerContent, innerWidth)}${border.vertical}`; + const headerDivider = `${border.vertical}${clampToWidth(border.horizontal.repeat(innerWidth), innerWidth)}${border.vertical}`; + const content = body.map((line) => `${border.vertical}${clampToWidth(line, innerWidth)}${border.vertical}`); + const bottom = `${border.bottomLeft}${clampToWidth(border.horizontal.repeat(innerWidth), innerWidth)}${border.bottomRight}`; + + return [top, header, headerDivider, ...content, bottom]; +} + function renderPlanningCard(state: WidgetState, theme: Theme, width: number): string[] { const elapsed = theme.fg("dim", formatElapsed(Date.now() - state.startedAt)); const { innerWidth, contentWidth, timelineWidth, detailWidth } = planningColumns(width); + const titleLeft = renderPlanningHeader(state, theme, Math.max(0, innerWidth - visibleWidth(elapsed) - 1)); if (innerWidth < 60 || contentWidth < 40) { const fallbackContent: string[] = [ @@ -671,7 +754,6 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st theme.fg("muted", `Plan · ${state.planId}`), "", formatStepLine(state, theme), - formatPhaseTrail(state, theme, contentWidth), ]; const detail = formatDetail(state, theme, contentWidth); if (detail) fallbackContent.push(detail); @@ -691,7 +773,7 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st const body = indentLines(fallbackContent, innerWidth); return renderBox( - `${BODY_INDENT}${theme.bold(theme.fg("accent", "Planning"))}`, + `${BODY_INDENT}${titleLeft}`, elapsed, body, width, @@ -699,8 +781,6 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st ); } - const chipsLine = renderPhaseChips(state, theme, contentWidth); - const timelineLines = renderTimelineLines(state, theme, timelineWidth); const detailSections = buildDetailSections(state, theme, detailWidth); const detailLines = layoutDetailColumn(detailSections, detailWidth, timelineLines.length); @@ -716,8 +796,6 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st const body = indentLines( [ - "", - chipsLine, "", ...combined, "", @@ -726,7 +804,7 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st ); return renderBox( - `${BODY_INDENT}${theme.bold(theme.fg("accent", "Planning"))}`, + `${BODY_INDENT}${titleLeft}`, elapsed, body, width, @@ -836,17 +914,6 @@ function renderLogCard(state: WidgetState, theme: Theme, width: number, forcedCo ); } -function formatPhaseTrail(state: WidgetState, theme: Theme, width: number): string { - const parts = state.phases.map((phase, index) => { - const icon = STATUS_ICON[phase.status]; - const color = STATUS_COLOR[phase.status]; - const label = index === state.activeIndex ? theme.bold(phase.label) : phase.label; - return theme.fg(color, `${icon} ${label}`); - }); - const trail = parts.join(" "); - return clampToWidth(trail, width, "…"); -} - function formatDetail(state: WidgetState, theme: Theme, width: number): string { const step = state.step ? theme.fg("muted", state.step) : ""; const activity = state.activity ? theme.fg("dim", ` · ${state.activity}`) : ""; @@ -904,7 +971,6 @@ function stripBoxFrame(lines: string[]): string[] { function renderIntegratedWorkspaceCard(state: WidgetState, theme: Theme, width: number): string[] { const innerWidth = Math.max(0, width - 2); const elapsed = theme.fg("dim", formatElapsed(Date.now() - state.startedAt)); - const rightInset = " ".repeat(visibleWidth(BODY_INDENT)); const { innerWidth: planningInnerWidth, contentWidth, timelineWidth, detailWidth } = planningColumns(width); const alignedColumns: LogColumns | undefined = planningInnerWidth >= 60 && contentWidth >= 40 @@ -926,12 +992,18 @@ function renderIntegratedWorkspaceCard(state: WidgetState, theme: Theme, width: ...logInner, ]; - return renderBox( - `${BODY_INDENT}${theme.bold(theme.fg("accent", "Planning"))}`, + const rightInset = " ".repeat(visibleWidth(BODY_INDENT)); + const titleLeftBudget = Math.max( + 0, + innerWidth - visibleWidth(elapsed) - visibleWidth(rightInset) - 1 - visibleWidth(BODY_INDENT), + ); + const titleLeft = renderPlanningHeader(state, theme, titleLeftBudget); + + return renderBoxWithHeaderRow( + `${BODY_INDENT}${titleLeft}`, `${elapsed}${rightInset}`, body, width, - theme, ); } diff --git a/tests/widget.test.ts b/tests/widget.test.ts new file mode 100644 index 0000000..9dfa07e --- /dev/null +++ b/tests/widget.test.ts @@ -0,0 +1,114 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; + +import type { ExtensionUIContext, Theme } from "@mariozechner/pi-coding-agent"; +import { visibleWidth } from "@mariozechner/pi-tui"; + +import { WidgetController, formatPlanningHeaderLabel } from "../src/planner/ui/widget.js"; + +type WidgetInstance = { + render: (width: number) => string[]; + invalidate: () => void; +}; + +type WidgetFactory = ((tui: unknown, theme: Theme) => WidgetInstance) | undefined; + +function createPlainTheme(): Theme { + return { + fg: (_color: string, text: string) => text, + bg: (_color: string, text: string) => text, + bold: (text: string) => text, + } as unknown as Theme; +} + +function createWidgetHarness(): { + controller: WidgetController; + render: (width: number) => string[]; + destroy: () => void; +} { + const theme = createPlainTheme(); + let factory: WidgetFactory; + + const ui = { + theme, + setWidget: (_key: string, next: WidgetFactory) => { + factory = next; + }, + } as unknown as ExtensionUIContext; + + const controller = new WidgetController(ui, "plan-test-id"); + + return { + controller, + render: (width: number) => { + assert.ok(factory, "widget factory should be registered"); + return factory({} as unknown, theme).render(width); + }, + destroy: () => controller.destroy(), + }; +} + +describe("formatPlanningHeaderLabel", () => { + it("applies compaction in deterministic order", () => { + const phase = "Context gathering"; + const status = "CURRENT"; + + const full = `Planning · ${phase} · ${status}`; + const shortStatus = `Planning · ${phase} · CUR`; + const noStatus = `Planning · ${phase}`; + const shortPhase = "Planning · Ctx gather"; + + assert.equal(formatPlanningHeaderLabel(phase, status, visibleWidth(full)), full); + assert.equal(formatPlanningHeaderLabel(phase, status, visibleWidth(full) - 1), shortStatus); + assert.equal(formatPlanningHeaderLabel(phase, status, visibleWidth(shortStatus) - 1), noStatus); + assert.equal(formatPlanningHeaderLabel(phase, status, visibleWidth(noStatus) - 1), shortPhase); + + const tiny = formatPlanningHeaderLabel(phase, status, 14); + assert.ok(visibleWidth(tiny) <= 14); + assert.ok(tiny.startsWith("Planning")); + }); +}); + +describe("WidgetController rendering", () => { + it("renders metadata header and removes phase chips row", () => { + const harness = createWidgetHarness(); + try { + const lines = harness.render(140); + const text = lines.join("\n"); + + assert.match(text, /Planning · Context gathering · CURRENT/); + assert.doesNotMatch(text, /┃ Context gathering ┃/); + } finally { + harness.destroy(); + } + }); + + it("aligns identity table separator using dynamic key width", () => { + const harness = createWidgetHarness(); + try { + harness.controller.update({ + subagentRole: "reviewer", + subagentParallelCount: 12, + subagentModel: "openai-codex/gpt-5.3-codex", + }); + + const lines = harness.render(140); + const planLine = lines.find((line) => line.includes("Plan ID") && line.includes(" : ")); + const agentLine = lines.find((line) => line.includes("Agent pool") && line.includes(" : ")); + const modelLine = lines.find((line) => line.includes("Model") && line.includes(" : ")); + + assert.ok(planLine, "expected Plan ID row"); + assert.ok(agentLine, "expected Agent pool row"); + assert.ok(modelLine, "expected Model row"); + + const planSep = planLine.indexOf(" : "); + const agentSep = agentLine.indexOf(" : "); + const modelSep = modelLine.indexOf(" : "); + + assert.equal(planSep, agentSep); + assert.equal(agentSep, modelSep); + } finally { + harness.destroy(); + } + }); +}); From 009412ad27fd9d6a8409d00393f3a276dec146fb Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 27 Feb 2026 19:35:45 +0700 Subject: [PATCH 027/412] Implement plan-code/plan-docs phases and plan markdown rendering --- src/planner/lib/permissions.ts | 3 + src/planner/phases/dispatch.ts | 145 ++++-- src/planner/phases/plan-code/fix-phase.ts | 166 +++++++ src/planner/phases/plan-code/fix-prompts.ts | 103 ++++ src/planner/phases/plan-code/phase.ts | 169 +++++++ src/planner/phases/plan-code/prompts.ts | 121 +++++ src/planner/phases/plan-docs/fix-phase.ts | 166 +++++++ src/planner/phases/plan-docs/fix-prompts.ts | 103 ++++ src/planner/phases/plan-docs/phase.ts | 169 +++++++ src/planner/phases/plan-docs/prompts.ts | 145 ++++++ src/planner/phases/qr-decompose/phase.ts | 64 +-- src/planner/phases/qr-decompose/prompts.ts | 154 +++--- src/planner/phases/qr-verify/phase.ts | 63 +-- src/planner/phases/qr-verify/prompts.ts | 49 +- src/planner/plan/render.ts | 155 ++++++ src/planner/plan/validate.ts | 46 +- src/planner/session.ts | 520 +++++++++++--------- src/planner/state.ts | 17 +- src/planner/subagent.ts | 70 ++- 19 files changed, 1929 insertions(+), 499 deletions(-) create mode 100644 src/planner/phases/plan-code/fix-phase.ts create mode 100644 src/planner/phases/plan-code/fix-prompts.ts create mode 100644 src/planner/phases/plan-code/phase.ts create mode 100644 src/planner/phases/plan-code/prompts.ts create mode 100644 src/planner/phases/plan-docs/fix-phase.ts create mode 100644 src/planner/phases/plan-docs/fix-prompts.ts create mode 100644 src/planner/phases/plan-docs/phase.ts create mode 100644 src/planner/phases/plan-docs/prompts.ts create mode 100644 src/planner/plan/render.ts diff --git a/src/planner/lib/permissions.ts b/src/planner/lib/permissions.ts index 5151f7a..aee6f7f 100644 --- a/src/planner/lib/permissions.ts +++ b/src/planner/lib/permissions.ts @@ -126,7 +126,10 @@ export const PHASE_PERMISSIONS: ReadonlyMap> = "koan_set_change_doc_diff", "koan_set_change_comments", "koan_set_readme_entry", + "koan_add_diagram", "koan_set_diagram", + "koan_add_diagram_node", + "koan_add_diagram_edge", ]), ], [ diff --git a/src/planner/phases/dispatch.ts b/src/planner/phases/dispatch.ts index 9bfba42..3762a36 100644 --- a/src/planner/phases/dispatch.ts +++ b/src/planner/phases/dispatch.ts @@ -10,6 +10,10 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { PlanDesignPhase } from "./plan-design/phase.js"; import { PlanDesignFixPhase } from "./plan-design/fix-phase.js"; +import { PlanCodePhase } from "./plan-code/phase.js"; +import { PlanCodeFixPhase } from "./plan-code/fix-phase.js"; +import { PlanDocsPhase } from "./plan-docs/phase.js"; +import { PlanDocsFixPhase } from "./plan-docs/fix-phase.js"; import { QRDecomposePhase } from "./qr-decompose/phase.js"; import { QRVerifyPhase } from "./qr-verify/phase.js"; import { createLogger, type Logger } from "../../utils/logger.js"; @@ -22,7 +26,31 @@ export interface SubagentConfig { phase: string; planDir: string; subagentDir: string; - fix: string | null; // QR phase being fixed, null when initial mode + fix: string | null; +} + +type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; + +function parseWorkPhase(value: string | null): WorkPhaseKey | null { + if (value === "plan-design" || value === "plan-code" || value === "plan-docs") { + return value; + } + return null; +} + +function parseQRPhase(value: string): WorkPhaseKey | null { + if (!value.startsWith("qr-")) return null; + return parseWorkPhase(value.slice(3)); +} + +async function loadFixFailures(planDir: string, phase: WorkPhaseKey): Promise { + const qrPath = path.join(planDir, `qr-${phase}.json`); + try { + const raw = await fs.readFile(qrPath, "utf8"); + return JSON.parse(raw) as QRFile; + } catch { + return null; + } } // Detects subagent mode by checking flags set via CLI (pi -p --koan-role @@ -38,7 +66,6 @@ export function detectSubagentMode(pi: ExtensionAPI): SubagentConfig | null { const phase = pi.getFlag("koan-phase"); const planDir = pi.getFlag("koan-plan-dir"); const subagentDir = pi.getFlag("koan-subagent-dir"); - const fix = pi.getFlag("koan-fix"); return { @@ -60,34 +87,68 @@ export async function dispatchPhase( ): Promise { const logger = log ?? createLogger("Dispatch"); - if (config.role === "architect" && config.fix === "plan-design") { - // Dispatch reads the QR file here, not in session.ts. - // The fix architect runs as a separate process with only the plan - // directory path -- it cannot receive in-memory QR data from the - // parent session. Reading from disk at dispatch boundary is the - // only clean handoff point. - const qrPath = path.join(config.planDir, "qr-plan-design.json"); - let qrFile: QRFile; - try { - const raw = await fs.readFile(qrPath, "utf8"); - qrFile = JSON.parse(raw) as QRFile; - } catch (error) { - const msg = error instanceof Error ? error.message : String(error); - logger("Fix dispatch: failed to read QR file", { error: msg }); + // -- Fix modes -- + + const fixPhase = parseWorkPhase(config.fix); + if (fixPhase) { + const qrFile = await loadFixFailures(config.planDir, fixPhase); + if (!qrFile) { + logger("Fix dispatch: failed to read QR file", { phase: fixPhase }); return; } + const failures = qrFile.items.filter((i) => i.status === "FAIL"); if (failures.length === 0) { - logger("Fix dispatch: no FAIL items in QR file, skipping fix phase"); + logger("Fix dispatch: no FAIL items in QR file, skipping fix phase", { phase: fixPhase }); + return; + } + + if (config.role === "architect" && fixPhase === "plan-design") { + const phase = new PlanDesignFixPhase( + pi, + { planDir: config.planDir, failures }, + dispatch, + planRef, + logger, + eventLog, + ); + await phase.begin(); + return; + } + + if (config.role === "developer" && fixPhase === "plan-code") { + const phase = new PlanCodeFixPhase( + pi, + { planDir: config.planDir, failures }, + dispatch, + planRef, + logger, + eventLog, + ); + await phase.begin(); + return; + } + + if (config.role === "technical-writer" && fixPhase === "plan-docs") { + const phase = new PlanDocsFixPhase( + pi, + { planDir: config.planDir, failures }, + dispatch, + planRef, + logger, + eventLog, + ); + await phase.begin(); return; } - logger("Dispatching to plan-design fix workflow", { - planDir: config.planDir, - failureCount: failures.length, - }); - const phase = new PlanDesignFixPhase( + } + + // -- Work phases -- + + if (config.role === "architect" && config.phase === "plan-design") { + const phase = new PlanDesignPhase( pi, - { planDir: config.planDir, failures }, + { planDir: config.planDir }, dispatch, planRef, logger, @@ -97,9 +158,8 @@ export async function dispatchPhase( return; } - if (config.role === "architect" && config.phase === "plan-design") { - logger("Dispatching to plan-design workflow", { planDir: config.planDir }); - const phase = new PlanDesignPhase( + if (config.role === "developer" && config.phase === "plan-code") { + const phase = new PlanCodePhase( pi, { planDir: config.planDir }, dispatch, @@ -111,9 +171,8 @@ export async function dispatchPhase( return; } - if (config.role === "qr-decomposer" && config.phase === "qr-plan-design") { - logger("Dispatching to qr-decompose workflow", { planDir: config.planDir }); - const phase = new QRDecomposePhase( + if (config.role === "technical-writer" && config.phase === "plan-docs") { + const phase = new PlanDocsPhase( pi, { planDir: config.planDir }, dispatch, @@ -125,16 +184,32 @@ export async function dispatchPhase( return; } - if (config.role === "reviewer" && config.phase === "qr-plan-design") { + // -- QR phases -- + + const qrWorkPhase = parseQRPhase(config.phase); + if (config.role === "qr-decomposer" && qrWorkPhase) { + const phase = new QRDecomposePhase( + pi, + { planDir: config.planDir, workPhase: qrWorkPhase }, + dispatch, + planRef, + logger, + eventLog, + ); + await phase.begin(); + return; + } + + if (config.role === "reviewer" && qrWorkPhase) { const itemId = pi.getFlag("koan-qr-item") as string; if (!itemId) { logger("Reviewer missing --koan-qr-item flag"); return; } - logger("Dispatching to qr-verify workflow", { planDir: config.planDir, itemId }); + const phase = new QRVerifyPhase( pi, - { planDir: config.planDir, itemId }, + { planDir: config.planDir, itemId, workPhase: qrWorkPhase }, dispatch, planRef, logger, @@ -144,5 +219,9 @@ export async function dispatchPhase( return; } - logger("Unknown role/phase combination", { role: config.role, phase: config.phase }); + logger("Unknown role/phase combination", { + role: config.role, + phase: config.phase, + fix: config.fix, + }); } diff --git a/src/planner/phases/plan-code/fix-phase.ts b/src/planner/phases/plan-code/fix-phase.ts new file mode 100644 index 0000000..6f2df7e --- /dev/null +++ b/src/planner/phases/plan-code/fix-phase.ts @@ -0,0 +1,166 @@ +// Plan-code fix phase -- dynamic targeted QR repair workflow. + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; +import { loadPlanCodeSystemPrompt, buildPlanCodeSystemPrompt } from "./prompts.js"; +import { + fixStepName, + buildFixSystemPrompt, + fixStepGuidance, + formatFailuresXml, +} from "./fix-prompts.js"; +import { formatStep } from "../../lib/step.js"; +import type { QRItem } from "../../qr/types.js"; +import { createLogger, type Logger } from "../../../utils/logger.js"; +import { EventLog } from "../../lib/audit.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; +import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; + +interface FixState { + active: boolean; + step: number; + step1Prompt: string | null; + systemPrompt: string | null; +} + +export class PlanCodeFixPhase { + private readonly pi: ExtensionAPI; + private readonly planDir: string; + private readonly failures: ReadonlyArray; + private readonly log: Logger; + private readonly state: FixState; + private readonly eventLog: EventLog | undefined; + private readonly dispatch: WorkflowDispatch; + private readonly planRef: PlanRef; + + constructor( + pi: ExtensionAPI, + config: { planDir: string; failures: QRItem[] }, + dispatch: WorkflowDispatch, + planRef: PlanRef, + log?: Logger, + eventLog?: EventLog, + ) { + this.pi = pi; + this.planDir = config.planDir; + this.failures = config.failures; + this.dispatch = dispatch; + this.planRef = planRef; + this.log = log ?? createLogger("PlanCodeFix"); + this.eventLog = eventLog; + + this.state = { + active: false, + step: 1, + step1Prompt: null, + systemPrompt: null, + }; + + this.registerHandlers(); + } + + private get totalSteps(): number { + return 2 + this.failures.length; + } + + async begin(): Promise { + let basePrompt: string; + try { + basePrompt = await loadPlanCodeSystemPrompt(); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Fix phase aborted: cannot load system prompt", { error: message }); + return; + } + + const failuresXml = formatFailuresXml(this.failures); + const totalSteps = this.totalSteps; + this.state.systemPrompt = buildFixSystemPrompt( + buildPlanCodeSystemPrompt(basePrompt), + this.failures.length, + totalSteps, + ); + this.state.step1Prompt = formatStep(fixStepGuidance(1, totalSteps, { allFailuresXml: failuresXml })); + this.state.active = true; + this.state.step = 1; + this.planRef.dir = this.planDir; + + hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); + + this.log("Starting plan-code fix workflow", { step: 1, totalSteps, failureCount: this.failures.length }); + await this.eventLog?.emitPhaseStart(totalSteps); + await this.eventLog?.emitStepTransition(1, fixStepName(1, totalSteps), totalSteps); + } + + private registerHandlers(): void { + this.pi.on("before_agent_start", () => { + if (!this.state.active || !this.state.systemPrompt) return undefined; + return { systemPrompt: this.state.systemPrompt }; + }); + + this.pi.on("context", (event) => { + if (!this.state.active) return undefined; + if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; + + const messages = event.messages.map((m) => { + if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; + return m; + }); + return { messages }; + }); + + this.pi.on("tool_call", (event) => { + if (!this.state.active) return undefined; + + const perm = checkPermission("plan-code", event.toolName); + if (!perm.allowed) return { block: true, reason: perm.reason }; + + const step = this.state.step; + const total = this.totalSteps; + const inFixRange = step >= 2 && step < total; + if (!inFixRange && PLAN_MUTATION_TOOLS.has(event.toolName)) { + return { + block: true, + reason: `${event.toolName} available in steps 2-${total - 1} (current: ${step})`, + }; + } + + return undefined; + }); + } + + private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { + const prev = this.state.step; + const total = this.totalSteps; + + if (prev === total) { + const result = await this.handleFinalize(); + if (!result.ok) { + await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); + return { ok: false, error: result.errors?.join("; ") }; + } + + this.state.active = false; + unhookDispatch(this.dispatch, "onCompleteStep"); + await this.eventLog?.emitPhaseEnd("completed"); + this.log("Fix phase complete, plan-code validation passed"); + return { ok: true, prompt: "Fix phase validation passed. Workflow complete." }; + } + + const next = prev + 1; + this.state.step = next; + + const item = next >= 2 && next < total ? this.failures[next - 2] : undefined; + const name = fixStepName(next, total, item); + const prompt = formatStep(fixStepGuidance(next, total, { item })); + + this.log("Fix step complete, advancing", { from: prev, to: next, name }); + await this.eventLog?.emitStepTransition(next, name, total); + return { ok: true, prompt }; + } + + private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { + return loadAndValidatePlanForPhase(this.planDir, "plan-code", this.log); + } +} diff --git a/src/planner/phases/plan-code/fix-prompts.ts b/src/planner/phases/plan-code/fix-prompts.ts new file mode 100644 index 0000000..8c8000f --- /dev/null +++ b/src/planner/phases/plan-code/fix-prompts.ts @@ -0,0 +1,103 @@ +import type { QRItem } from "../../qr/types.js"; +import type { StepGuidance } from "../../lib/step.js"; + +export function formatFailuresXml(failures: ReadonlyArray): string { + const items = failures + .map((f) => [ + ` `, + ` ${f.check}`, + f.finding ? ` ${f.finding}` : " ", + " ", + ].join("\n")) + .join("\n"); + return ["", items, ""].join("\n"); +} + +export function fixStepName(step: number, totalSteps: number, item?: QRItem): string { + if (step === 1) return "Understand QR Failures"; + if (step === totalSteps) return "Review & Finalize"; + return item ? `Fix ${item.id}` : `Fix item ${step - 1}`; +} + +export function buildFixSystemPrompt(basePrompt: string, failureCount: number, totalSteps: number): string { + return [ + basePrompt, + "", + "---", + "", + `WORKFLOW: ${totalSteps}-STEP PLAN-CODE FIX`, + "", + `You are fixing ${failureCount} QR failure(s) in code planning output.`, + "Step 1 is read-only and covers all failures.", + `Steps 2-${totalSteps - 1} fix exactly one failure per step.`, + `Step ${totalSteps} is read-only review.`, + "", + "CONSTRAINTS:", + "- Fix only identified failures", + "- Preserve already-valid code_changes", + "- Do not edit repository files (planning only)", + ].join("\n"); +} + +function step1(totalSteps: number, failuresXml: string): StepGuidance { + const itemCount = totalSteps - 2; + return { + title: `Step 1/${totalSteps}: Understand QR Failures`, + instructions: [ + "QR FAILURES:", + "", + failuresXml, + "", + `There are ${itemCount} item(s). You will fix them one by one in steps 2-${totalSteps - 1}.`, + "Read current plan state with koan_get_plan / koan_get_change / koan_get_intent.", + "Identify exact mismatch for each failure.", + "", + "This step is read-only.", + ], + }; +} + +function itemStep(step: number, totalSteps: number, item?: QRItem): StepGuidance { + const itemXml = item ? formatFailuresXml([item]) : ""; + const idx = step - 1; + const total = totalSteps - 2; + return { + title: `Step ${step}/${totalSteps}: Fix ${item?.id ?? `item ${idx}`}`, + instructions: [ + `FIX ITEM ${idx} OF ${total}:`, + "", + itemXml, + "", + "Apply a targeted plan fix using change tools (add/set change, set intent ref, set comments).", + "Do not batch-fix other failures in this step.", + "Keep modifications minimal and scoped.", + ], + }; +} + +function finalStep(totalSteps: number): StepGuidance { + return { + title: `Step ${totalSteps}/${totalSteps}: Review & Finalize`, + instructions: [ + "All per-item fixes are complete.", + "Use koan_get_plan to verify overall coherence and coverage.", + "Confirm fixed items are addressed without regressing passing items.", + "", + "This step is read-only.", + ], + invokeAfter: [ + "WHEN DONE: Call koan_get_plan, then call koan_complete_step.", + "Do NOT call koan_complete_step before reviewing final plan state.", + ].join("\n"), + }; +} + +export function fixStepGuidance( + step: number, + totalSteps: number, + opts?: { item?: QRItem; allFailuresXml?: string }, +): StepGuidance { + if (step === 1) return step1(totalSteps, opts?.allFailuresXml ?? ""); + if (step === totalSteps) return finalStep(totalSteps); + return itemStep(step, totalSteps, opts?.item); +} diff --git a/src/planner/phases/plan-code/phase.ts b/src/planner/phases/plan-code/phase.ts new file mode 100644 index 0000000..f4948b2 --- /dev/null +++ b/src/planner/phases/plan-code/phase.ts @@ -0,0 +1,169 @@ +// Plan-code phase -- 4-step developer workflow converting code intents +// to concrete code_changes diffs in plan.json. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; +import { + loadPlanCodeSystemPrompt, + formatContextForStep1, + buildPlanCodeSystemPrompt, + planCodeStepGuidance, + STEP_NAMES, +} from "./prompts.js"; +import { formatStep } from "../../lib/step.js"; +import type { ContextData } from "../../types.js"; +import { createLogger, type Logger } from "../../../utils/logger.js"; +import { EventLog } from "../../lib/audit.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; +import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; + +type PlanCodeStep = 1 | 2 | 3 | 4; + +interface PlanCodeState { + active: boolean; + step: PlanCodeStep; + step1Prompt: string | null; + contextData: ContextData | null; + systemPrompt: string | null; +} + +const TOTAL_STEPS = 4; +const MUTATION_UNLOCK_STEP = 3; + +export class PlanCodePhase { + private readonly pi: ExtensionAPI; + private readonly planDir: string; + private readonly log: Logger; + private readonly state: PlanCodeState; + private readonly eventLog: EventLog | undefined; + private readonly dispatch: WorkflowDispatch; + private readonly planRef: PlanRef; + + constructor( + pi: ExtensionAPI, + config: { planDir: string }, + dispatch: WorkflowDispatch, + planRef: PlanRef, + log?: Logger, + eventLog?: EventLog, + ) { + this.pi = pi; + this.planDir = config.planDir; + this.dispatch = dispatch; + this.planRef = planRef; + this.log = log ?? createLogger("PlanCode"); + this.eventLog = eventLog; + + this.state = { + active: false, + step: 1, + step1Prompt: null, + contextData: null, + systemPrompt: null, + }; + + this.registerHandlers(); + } + + async begin(): Promise { + const contextPath = path.join(this.planDir, "context.json"); + try { + const raw = await fs.readFile(contextPath, "utf8"); + this.state.contextData = JSON.parse(raw) as ContextData; + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to read context.json", { error: message }); + return; + } + + let basePrompt: string; + try { + basePrompt = await loadPlanCodeSystemPrompt(); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to load plan-code system prompt", { error: message }); + return; + } + + const contextXml = formatContextForStep1(this.state.contextData); + this.state.systemPrompt = buildPlanCodeSystemPrompt(basePrompt); + this.state.step1Prompt = formatStep(planCodeStepGuidance(1, contextXml)); + this.state.active = true; + this.state.step = 1; + this.planRef.dir = this.planDir; + + hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); + + this.log("Starting plan-code workflow", { step: 1 }); + await this.eventLog?.emitPhaseStart(TOTAL_STEPS); + await this.eventLog?.emitStepTransition(1, STEP_NAMES[1], TOTAL_STEPS); + } + + private registerHandlers(): void { + this.pi.on("before_agent_start", () => { + if (!this.state.active || !this.state.systemPrompt) return undefined; + return { systemPrompt: this.state.systemPrompt }; + }); + + this.pi.on("context", (event) => { + if (!this.state.active) return undefined; + if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; + + const messages = event.messages.map((m) => { + if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; + return m; + }); + return { messages }; + }); + + this.pi.on("tool_call", (event) => { + if (!this.state.active) return undefined; + + const perm = checkPermission("plan-code", event.toolName); + if (!perm.allowed) return { block: true, reason: perm.reason }; + + if (this.state.step < MUTATION_UNLOCK_STEP && PLAN_MUTATION_TOOLS.has(event.toolName)) { + return { + block: true, + reason: `${event.toolName} available from step ${MUTATION_UNLOCK_STEP} (current: ${this.state.step})`, + }; + } + + return undefined; + }); + } + + private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { + const prev = this.state.step; + + if (prev === 4) { + const result = await this.handleFinalize(); + if (!result.ok) { + await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); + return { ok: false, error: result.errors?.join("; ") }; + } + + this.state.active = false; + unhookDispatch(this.dispatch, "onCompleteStep"); + await this.eventLog?.emitPhaseEnd("completed"); + this.log("Plan-code finalized, workflow complete"); + return { ok: true, prompt: "Plan-code validation passed. Workflow complete." }; + } + + this.state.step = (prev + 1) as PlanCodeStep; + const nextName = STEP_NAMES[this.state.step]; + const prompt = formatStep(planCodeStepGuidance(this.state.step)); + + this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName }); + await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); + return { ok: true, prompt }; + } + + private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { + return loadAndValidatePlanForPhase(this.planDir, "plan-code", this.log); + } +} diff --git a/src/planner/phases/plan-code/prompts.ts b/src/planner/phases/plan-code/prompts.ts new file mode 100644 index 0000000..782ce4c --- /dev/null +++ b/src/planner/phases/plan-code/prompts.ts @@ -0,0 +1,121 @@ +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import type { ContextData } from "../../types.js"; +import type { StepGuidance } from "../../lib/step.js"; + +export const STEP_NAMES: Record<1 | 2 | 3 | 4, string> = { + 1: "Intent Coverage Analysis", + 2: "Codebase Anchoring", + 3: "Diff Authoring", + 4: "Validation & Review", +}; + +export async function loadPlanCodeSystemPrompt(): Promise { + const promptPath = path.join(os.homedir(), ".claude/agents/developer.md"); + try { + const content = await fs.readFile(promptPath, "utf8"); + return content.replace(/^---\n[\s\S]*?\n---\n/, ""); + } catch { + throw new Error(`Developer prompt not found at ${promptPath}`); + } +} + +export function formatContextForStep1(ctx: ContextData): string { + return ["", JSON.stringify(ctx, null, 2), ""].join("\n"); +} + +export function buildPlanCodeSystemPrompt(basePrompt: string): string { + return [ + basePrompt, + "", + "---", + "", + "WORKFLOW: 4-STEP PLAN-CODE", + "", + "You are in planning mode. Produce code diffs in plan.json, not repo edits.", + "Step 1 instructions are in the user message below.", + "Complete each step, then call koan_complete_step.", + "Put your work output in the `thoughts` parameter.", + "The tool result contains the next step.", + "", + "CRITICAL:", + "- NEVER use edit/write tools during plan-code.", + "- Convert every code_intent into at least one code_change with intent_ref.", + "- Use unified diffs in code_change.diff.", + ].join("\n"); +} + +export function planCodeStepGuidance(step: 1 | 2 | 3 | 4, context?: string): StepGuidance { + switch (step) { + case 1: + return { + title: "Step 1: Intent Coverage Analysis", + instructions: [ + "PLANNING CONTEXT (from session):", + "", + context ?? "", + "", + "Use koan_get_plan to inspect milestones and code_intents.", + "Build a checklist of intents that need code_changes.", + "Record target files and affected functions per intent.", + "", + "This step is read-only.", + ], + }; + + case 2: + return { + title: "Step 2: Codebase Anchoring", + instructions: [ + "Read target files to anchor each planned diff:", + " - Use read/grep/find/bash as needed", + " - Identify stable context lines around each change", + " - Confirm naming/pattern conventions", + "", + "Do not create code_changes yet. This step is still read-only.", + ], + }; + + case 3: + return { + title: "Step 3: Diff Authoring", + instructions: [ + "Create code_changes for each intent using plan mutation tools:", + " - koan_add_change (if missing)", + " - koan_set_change_intent_ref", + " - koan_set_change_file", + " - koan_set_change_diff", + " - koan_set_change_comments", + "", + "Rules:", + " - Every code_intent must map to at least one code_change", + " - Use valid unified diff format in diff field", + " - comments explain WHY (reference decision IDs where relevant)", + "", + "Use koan_get_plan/koan_get_milestone to verify coverage as you go.", + ], + }; + + case 4: + return { + title: "Step 4: Validation & Review", + instructions: [ + "Run a final coverage review using getter tools:", + " - Every intent has at least one linked change", + " - Every change has exact file path and non-empty diff", + " - Diffs and comments are coherent with intent behavior", + "", + "Fix any gaps before completing this step.", + ], + invokeAfter: [ + "WHEN DONE: Call koan_complete_step with a concise summary of coverage.", + "Do NOT call this tool until all required code_changes are present.", + ].join("\n"), + }; + + default: + return { title: "", instructions: [] }; + } +} diff --git a/src/planner/phases/plan-docs/fix-phase.ts b/src/planner/phases/plan-docs/fix-phase.ts new file mode 100644 index 0000000..e757461 --- /dev/null +++ b/src/planner/phases/plan-docs/fix-phase.ts @@ -0,0 +1,166 @@ +// Plan-docs fix phase -- dynamic targeted QR repair workflow. + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; +import { loadPlanDocsSystemPrompt, buildPlanDocsSystemPrompt } from "./prompts.js"; +import { + fixStepName, + buildFixSystemPrompt, + fixStepGuidance, + formatFailuresXml, +} from "./fix-prompts.js"; +import { formatStep } from "../../lib/step.js"; +import type { QRItem } from "../../qr/types.js"; +import { createLogger, type Logger } from "../../../utils/logger.js"; +import { EventLog } from "../../lib/audit.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; +import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; + +interface FixState { + active: boolean; + step: number; + step1Prompt: string | null; + systemPrompt: string | null; +} + +export class PlanDocsFixPhase { + private readonly pi: ExtensionAPI; + private readonly planDir: string; + private readonly failures: ReadonlyArray; + private readonly log: Logger; + private readonly state: FixState; + private readonly eventLog: EventLog | undefined; + private readonly dispatch: WorkflowDispatch; + private readonly planRef: PlanRef; + + constructor( + pi: ExtensionAPI, + config: { planDir: string; failures: QRItem[] }, + dispatch: WorkflowDispatch, + planRef: PlanRef, + log?: Logger, + eventLog?: EventLog, + ) { + this.pi = pi; + this.planDir = config.planDir; + this.failures = config.failures; + this.dispatch = dispatch; + this.planRef = planRef; + this.log = log ?? createLogger("PlanDocsFix"); + this.eventLog = eventLog; + + this.state = { + active: false, + step: 1, + step1Prompt: null, + systemPrompt: null, + }; + + this.registerHandlers(); + } + + private get totalSteps(): number { + return 2 + this.failures.length; + } + + async begin(): Promise { + let basePrompt: string; + try { + basePrompt = await loadPlanDocsSystemPrompt(); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Fix phase aborted: cannot load system prompt", { error: message }); + return; + } + + const failuresXml = formatFailuresXml(this.failures); + const totalSteps = this.totalSteps; + this.state.systemPrompt = buildFixSystemPrompt( + buildPlanDocsSystemPrompt(basePrompt), + this.failures.length, + totalSteps, + ); + this.state.step1Prompt = formatStep(fixStepGuidance(1, totalSteps, { allFailuresXml: failuresXml })); + this.state.active = true; + this.state.step = 1; + this.planRef.dir = this.planDir; + + hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); + + this.log("Starting plan-docs fix workflow", { step: 1, totalSteps, failureCount: this.failures.length }); + await this.eventLog?.emitPhaseStart(totalSteps); + await this.eventLog?.emitStepTransition(1, fixStepName(1, totalSteps), totalSteps); + } + + private registerHandlers(): void { + this.pi.on("before_agent_start", () => { + if (!this.state.active || !this.state.systemPrompt) return undefined; + return { systemPrompt: this.state.systemPrompt }; + }); + + this.pi.on("context", (event) => { + if (!this.state.active) return undefined; + if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; + + const messages = event.messages.map((m) => { + if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; + return m; + }); + return { messages }; + }); + + this.pi.on("tool_call", (event) => { + if (!this.state.active) return undefined; + + const perm = checkPermission("plan-docs", event.toolName); + if (!perm.allowed) return { block: true, reason: perm.reason }; + + const step = this.state.step; + const total = this.totalSteps; + const inFixRange = step >= 2 && step < total; + if (!inFixRange && PLAN_MUTATION_TOOLS.has(event.toolName)) { + return { + block: true, + reason: `${event.toolName} available in steps 2-${total - 1} (current: ${step})`, + }; + } + + return undefined; + }); + } + + private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { + const prev = this.state.step; + const total = this.totalSteps; + + if (prev === total) { + const result = await this.handleFinalize(); + if (!result.ok) { + await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); + return { ok: false, error: result.errors?.join("; ") }; + } + + this.state.active = false; + unhookDispatch(this.dispatch, "onCompleteStep"); + await this.eventLog?.emitPhaseEnd("completed"); + this.log("Fix phase complete, plan-docs validation passed"); + return { ok: true, prompt: "Fix phase validation passed. Workflow complete." }; + } + + const next = prev + 1; + this.state.step = next; + + const item = next >= 2 && next < total ? this.failures[next - 2] : undefined; + const name = fixStepName(next, total, item); + const prompt = formatStep(fixStepGuidance(next, total, { item })); + + this.log("Fix step complete, advancing", { from: prev, to: next, name }); + await this.eventLog?.emitStepTransition(next, name, total); + return { ok: true, prompt }; + } + + private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { + return loadAndValidatePlanForPhase(this.planDir, "plan-docs", this.log); + } +} diff --git a/src/planner/phases/plan-docs/fix-prompts.ts b/src/planner/phases/plan-docs/fix-prompts.ts new file mode 100644 index 0000000..90da4a0 --- /dev/null +++ b/src/planner/phases/plan-docs/fix-prompts.ts @@ -0,0 +1,103 @@ +import type { QRItem } from "../../qr/types.js"; +import type { StepGuidance } from "../../lib/step.js"; + +export function formatFailuresXml(failures: ReadonlyArray): string { + const items = failures + .map((f) => [ + ` `, + ` ${f.check}`, + f.finding ? ` ${f.finding}` : " ", + " ", + ].join("\n")) + .join("\n"); + return ["", items, ""].join("\n"); +} + +export function fixStepName(step: number, totalSteps: number, item?: QRItem): string { + if (step === 1) return "Understand QR Failures"; + if (step === totalSteps) return "Review & Finalize"; + return item ? `Fix ${item.id}` : `Fix item ${step - 1}`; +} + +export function buildFixSystemPrompt(basePrompt: string, failureCount: number, totalSteps: number): string { + return [ + basePrompt, + "", + "---", + "", + `WORKFLOW: ${totalSteps}-STEP PLAN-DOCS FIX`, + "", + `You are fixing ${failureCount} documentation-related QR failure(s).`, + "Step 1 is read-only and covers all failures.", + `Steps 2-${totalSteps - 1} fix exactly one failure per step.`, + `Step ${totalSteps} is read-only review.`, + "", + "CONSTRAINTS:", + "- Fix only identified failures", + "- Keep docs timeless and decision-grounded", + "- Preserve already-valid doc artifacts", + ].join("\n"); +} + +function step1(totalSteps: number, failuresXml: string): StepGuidance { + const itemCount = totalSteps - 2; + return { + title: `Step 1/${totalSteps}: Understand QR Failures`, + instructions: [ + "QR FAILURES:", + "", + failuresXml, + "", + `There are ${itemCount} item(s). You will fix them one by one in steps 2-${totalSteps - 1}.`, + "Inspect current docs state via koan_get_plan / koan_get_change.", + "Identify exact correction needed per item.", + "", + "This step is read-only.", + ], + }; +} + +function itemStep(step: number, totalSteps: number, item?: QRItem): StepGuidance { + const itemXml = item ? formatFailuresXml([item]) : ""; + const idx = step - 1; + const total = totalSteps - 2; + return { + title: `Step ${step}/${totalSteps}: Fix ${item?.id ?? `item ${idx}`}`, + instructions: [ + `FIX ITEM ${idx} OF ${total}:`, + "", + itemXml, + "", + "Apply a targeted docs fix using doc tools (set doc_diff/comments/readme/diagram).", + "Do not batch-fix other failures in this step.", + "Keep changes minimal and scoped.", + ], + }; +} + +function finalStep(totalSteps: number): StepGuidance { + return { + title: `Step ${totalSteps}/${totalSteps}: Review & Finalize`, + instructions: [ + "All per-item fixes are complete.", + "Use koan_get_plan to verify docs coherence and completeness.", + "Confirm fixed items are addressed without regressing passing items.", + "", + "This step is read-only.", + ], + invokeAfter: [ + "WHEN DONE: Call koan_get_plan, then call koan_complete_step.", + "Do NOT call koan_complete_step before reviewing final plan state.", + ].join("\n"), + }; +} + +export function fixStepGuidance( + step: number, + totalSteps: number, + opts?: { item?: QRItem; allFailuresXml?: string }, +): StepGuidance { + if (step === 1) return step1(totalSteps, opts?.allFailuresXml ?? ""); + if (step === totalSteps) return finalStep(totalSteps); + return itemStep(step, totalSteps, opts?.item); +} diff --git a/src/planner/phases/plan-docs/phase.ts b/src/planner/phases/plan-docs/phase.ts new file mode 100644 index 0000000..f8fec6c --- /dev/null +++ b/src/planner/phases/plan-docs/phase.ts @@ -0,0 +1,169 @@ +// Plan-docs phase -- 6-step technical writer workflow producing doc artifacts +// (doc_diff/comments/diagram/readme) in plan.json. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; +import { + loadPlanDocsSystemPrompt, + formatContextForStep1, + buildPlanDocsSystemPrompt, + planDocsStepGuidance, + STEP_NAMES, +} from "./prompts.js"; +import { formatStep } from "../../lib/step.js"; +import type { ContextData } from "../../types.js"; +import { createLogger, type Logger } from "../../../utils/logger.js"; +import { EventLog } from "../../lib/audit.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; +import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; + +type PlanDocsStep = 1 | 2 | 3 | 4 | 5 | 6; + +interface PlanDocsState { + active: boolean; + step: PlanDocsStep; + step1Prompt: string | null; + contextData: ContextData | null; + systemPrompt: string | null; +} + +const TOTAL_STEPS = 6; +const MUTATION_UNLOCK_STEP = 3; + +export class PlanDocsPhase { + private readonly pi: ExtensionAPI; + private readonly planDir: string; + private readonly log: Logger; + private readonly state: PlanDocsState; + private readonly eventLog: EventLog | undefined; + private readonly dispatch: WorkflowDispatch; + private readonly planRef: PlanRef; + + constructor( + pi: ExtensionAPI, + config: { planDir: string }, + dispatch: WorkflowDispatch, + planRef: PlanRef, + log?: Logger, + eventLog?: EventLog, + ) { + this.pi = pi; + this.planDir = config.planDir; + this.dispatch = dispatch; + this.planRef = planRef; + this.log = log ?? createLogger("PlanDocs"); + this.eventLog = eventLog; + + this.state = { + active: false, + step: 1, + step1Prompt: null, + contextData: null, + systemPrompt: null, + }; + + this.registerHandlers(); + } + + async begin(): Promise { + const contextPath = path.join(this.planDir, "context.json"); + try { + const raw = await fs.readFile(contextPath, "utf8"); + this.state.contextData = JSON.parse(raw) as ContextData; + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to read context.json", { error: message }); + return; + } + + let basePrompt: string; + try { + basePrompt = await loadPlanDocsSystemPrompt(); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + this.log("Failed to load plan-docs system prompt", { error: message }); + return; + } + + const contextXml = formatContextForStep1(this.state.contextData); + this.state.systemPrompt = buildPlanDocsSystemPrompt(basePrompt); + this.state.step1Prompt = formatStep(planDocsStepGuidance(1, contextXml)); + this.state.active = true; + this.state.step = 1; + this.planRef.dir = this.planDir; + + hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); + + this.log("Starting plan-docs workflow", { step: 1 }); + await this.eventLog?.emitPhaseStart(TOTAL_STEPS); + await this.eventLog?.emitStepTransition(1, STEP_NAMES[1], TOTAL_STEPS); + } + + private registerHandlers(): void { + this.pi.on("before_agent_start", () => { + if (!this.state.active || !this.state.systemPrompt) return undefined; + return { systemPrompt: this.state.systemPrompt }; + }); + + this.pi.on("context", (event) => { + if (!this.state.active) return undefined; + if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; + + const messages = event.messages.map((m) => { + if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; + return m; + }); + return { messages }; + }); + + this.pi.on("tool_call", (event) => { + if (!this.state.active) return undefined; + + const perm = checkPermission("plan-docs", event.toolName); + if (!perm.allowed) return { block: true, reason: perm.reason }; + + if (this.state.step < MUTATION_UNLOCK_STEP && PLAN_MUTATION_TOOLS.has(event.toolName)) { + return { + block: true, + reason: `${event.toolName} available from step ${MUTATION_UNLOCK_STEP} (current: ${this.state.step})`, + }; + } + + return undefined; + }); + } + + private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { + const prev = this.state.step; + + if (prev === 6) { + const result = await this.handleFinalize(); + if (!result.ok) { + await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); + return { ok: false, error: result.errors?.join("; ") }; + } + + this.state.active = false; + unhookDispatch(this.dispatch, "onCompleteStep"); + await this.eventLog?.emitPhaseEnd("completed"); + this.log("Plan-docs finalized, workflow complete"); + return { ok: true, prompt: "Plan-docs validation passed. Workflow complete." }; + } + + this.state.step = (prev + 1) as PlanDocsStep; + const nextName = STEP_NAMES[this.state.step]; + const prompt = formatStep(planDocsStepGuidance(this.state.step)); + + this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName }); + await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); + return { ok: true, prompt }; + } + + private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { + return loadAndValidatePlanForPhase(this.planDir, "plan-docs", this.log); + } +} diff --git a/src/planner/phases/plan-docs/prompts.ts b/src/planner/phases/plan-docs/prompts.ts new file mode 100644 index 0000000..e27b58e --- /dev/null +++ b/src/planner/phases/plan-docs/prompts.ts @@ -0,0 +1,145 @@ +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import type { ContextData } from "../../types.js"; +import type { StepGuidance } from "../../lib/step.js"; + +export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { + 1: "Extract Documentation Context", + 2: "Analyze Planned Code Changes", + 3: "Author Code-Adjacent Docs", + 4: "Author Cross-Cutting Docs", + 5: "Diagram & Consistency Review", + 6: "Validation & Final Review", +}; + +export async function loadPlanDocsSystemPrompt(): Promise { + const promptPath = path.join(os.homedir(), ".claude/agents/technical-writer.md"); + try { + const content = await fs.readFile(promptPath, "utf8"); + return content.replace(/^---\n[\s\S]*?\n---\n/, ""); + } catch { + throw new Error(`Technical-writer prompt not found at ${promptPath}`); + } +} + +export function formatContextForStep1(ctx: ContextData): string { + return ["", JSON.stringify(ctx, null, 2), ""].join("\n"); +} + +export function buildPlanDocsSystemPrompt(basePrompt: string): string { + return [ + basePrompt, + "", + "---", + "", + "WORKFLOW: 6-STEP PLAN-DOCS", + "", + "You are in planning mode. Add documentation artifacts to plan.json.", + "Step 1 instructions are in the user message below.", + "Complete each step, then call koan_complete_step.", + "Put your findings in the `thoughts` parameter.", + "The tool result contains the next step.", + "", + "CRITICAL:", + "- NEVER use edit/write tools during plan-docs.", + "- Populate code_change.doc_diff for code changes.", + "- Keep comments and docs timeless (no temporal contamination).", + "- Keep architecture diagrams and README entries aligned with plan intent.", + ].join("\n"); +} + +export function planDocsStepGuidance(step: 1 | 2 | 3 | 4 | 5 | 6, context?: string): StepGuidance { + switch (step) { + case 1: + return { + title: "Step 1: Extract Documentation Context", + instructions: [ + "PLANNING CONTEXT (from session):", + "", + context ?? "", + "", + "Use koan_get_plan to review decisions, constraints, risks, and milestones.", + "Capture decision IDs that should be reflected in documentation rationale.", + "This step is read-only.", + ], + }; + + case 2: + return { + title: "Step 2: Analyze Planned Code Changes", + instructions: [ + "Inspect each milestone and code_change:", + " - What needs doc_diff coverage?", + " - Which comments are missing or weak?", + " - Which changes require architecture/README support?", + "", + "Use koan_get_milestone / koan_get_change for detail.", + "This step is read-only.", + ], + }; + + case 3: + return { + title: "Step 3: Author Code-Adjacent Docs", + instructions: [ + "Populate code-level documentation in plan.json:", + " - koan_set_change_doc_diff", + " - koan_set_change_comments", + "", + "Rules:", + " - Every code change with diff should have doc_diff", + " - comments explain WHY (reference decisions where applicable)", + " - Avoid temporal language (no 'added', 'changed from', 'now')", + ], + }; + + case 4: + return { + title: "Step 4: Author Cross-Cutting Docs", + instructions: [ + "Update cross-cutting documentation artifacts:", + " - koan_set_readme_entry for docs not tied to one change", + " - koan_set_diagram (title/scope/ascii_render) for architecture visuals", + "", + "If diagrams are missing but needed, create them with:", + " - koan_add_diagram", + " - koan_add_diagram_node / koan_add_diagram_edge", + ], + }; + + case 5: + return { + title: "Step 5: Diagram & Consistency Review", + instructions: [ + "Review documentation consistency across the plan:", + " - doc_diff content matches planned behavior", + " - diagrams align with milestone scope", + " - README entries do not contradict decisions/invariants", + "", + "Use getter tools to re-read affected entities and patch gaps.", + ], + }; + + case 6: + return { + title: "Step 6: Validation & Final Review", + instructions: [ + "Perform final documentation completeness check:", + " - all code changes with diff have doc_diff", + " - comments/doc diffs are coherent and timeless", + " - readme/diagram updates are present when needed", + "", + "Fix remaining issues before completing.", + ], + invokeAfter: [ + "WHEN DONE: Call koan_complete_step with a concise docs-completeness summary.", + "Do NOT call this tool until documentation artifacts are complete.", + ].join("\n"), + }; + + default: + return { title: "", instructions: [] }; + } +} diff --git a/src/planner/phases/qr-decompose/phase.ts b/src/planner/phases/qr-decompose/phase.ts index 5a8a99e..309dba5 100644 --- a/src/planner/phases/qr-decompose/phase.ts +++ b/src/planner/phases/qr-decompose/phase.ts @@ -1,6 +1,5 @@ -// QR decompose phase -- 13-step workflow that decomposes a plan into -// verifiable QR items. Mirrors PlanDesignPhase lifecycle exactly. -// Two-tier step gate: koan_qr_add_item unlocks at step 5, +// QR decompose phase -- 13-step workflow that decomposes a plan phase into +// verifiable QR items. Two-tier step gate: koan_qr_add_item unlocks at step 5, // koan_qr_assign_group unlocks at step 9. import { promises as fs } from "node:fs"; @@ -15,6 +14,7 @@ import { decomposeStepGuidance, DECOMPOSE_STEP_NAMES, type DecomposeStep, + type WorkPhaseKey, } from "./prompts.js"; import { formatStep } from "../../lib/step.js"; import type { ContextData } from "../../types.js"; @@ -24,18 +24,12 @@ import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } fro import { checkPermission } from "../../lib/permissions.js"; import type { QRFile } from "../../qr/types.js"; -// -- Step gate constants -- - -// Blocklist pattern: only restrict tools this gate owns; everything else -// defers to checkPermission. Avoids blocking read tools or future pi tools. const QR_ADD_TOOLS = new Set(["koan_qr_add_item"]); const QR_ASSIGN_TOOLS = new Set(["koan_qr_assign_group"]); const ADD_ITEM_UNLOCK = 5; const ASSIGN_GROUP_UNLOCK = 9; const TOTAL_STEPS = 13; -// -- State -- - interface DecomposeState { active: boolean; step: DecomposeStep; @@ -43,11 +37,11 @@ interface DecomposeState { systemPrompt: string | null; } -// -- Phase -- - export class QRDecomposePhase { private readonly pi: ExtensionAPI; private readonly planDir: string; + private readonly workPhase: WorkPhaseKey; + private readonly qrPhaseKey: `qr-${WorkPhaseKey}`; private readonly log: Logger; private readonly state: DecomposeState; private readonly eventLog: EventLog | undefined; @@ -56,7 +50,7 @@ export class QRDecomposePhase { constructor( pi: ExtensionAPI, - config: { planDir: string }, + config: { planDir: string; workPhase: WorkPhaseKey }, dispatch: WorkflowDispatch, planRef: PlanRef, log?: Logger, @@ -64,6 +58,8 @@ export class QRDecomposePhase { ) { this.pi = pi; this.planDir = config.planDir; + this.workPhase = config.workPhase; + this.qrPhaseKey = `qr-${config.workPhase}`; this.dispatch = dispatch; this.planRef = planRef; this.log = log ?? createLogger("QRDecompose"); @@ -101,15 +97,15 @@ export class QRDecomposePhase { } const contextXml = formatContextForDecompose(contextData); - this.state.systemPrompt = buildDecomposeSystemPrompt(basePrompt); - this.state.step1Prompt = formatStep(decomposeStepGuidance(1, contextXml)); + this.state.systemPrompt = buildDecomposeSystemPrompt(basePrompt, this.workPhase); + this.state.step1Prompt = formatStep(decomposeStepGuidance(1, this.workPhase, contextXml)); this.state.active = true; this.state.step = 1; this.planRef.dir = this.planDir; hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - this.log("Starting qr-decompose workflow", { step: 1 }); + this.log("Starting qr-decompose workflow", { step: 1, phase: this.workPhase }); await this.eventLog?.emitPhaseStart(TOTAL_STEPS); await this.eventLog?.emitStepTransition(1, DECOMPOSE_STEP_NAMES[1], TOTAL_STEPS); } @@ -120,18 +116,12 @@ export class QRDecomposePhase { return { systemPrompt: this.state.systemPrompt }; }); - // Step 1 prompt injection. The CLI message is a process trigger -- - // the context event fires before each LLM call and replaces the - // user message with the actual step 1 instructions. Handler is a - // no-op once the step advances past 1. this.pi.on("context", (event) => { if (!this.state.active) return undefined; if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; const messages = event.messages.map((m) => { - if (m.role === "user") { - return { ...m, content: this.state.step1Prompt! }; - } + if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; return m; }); return { messages }; @@ -140,13 +130,9 @@ export class QRDecomposePhase { this.pi.on("tool_call", (event) => { if (!this.state.active) return undefined; - // Outer boundary: phase permissions (default-deny). - const perm = checkPermission("qr-plan-design", event.toolName); - if (!perm.allowed) { - return { block: true, reason: perm.reason }; - } + const perm = checkPermission(this.qrPhaseKey, event.toolName); + if (!perm.allowed) return { block: true, reason: perm.reason }; - // Inner constraint: two-tier step gate (blocklist, not whitelist). const step = this.state.step; if (step < ADD_ITEM_UNLOCK && QR_ADD_TOOLS.has(event.toolName)) { return { @@ -163,7 +149,6 @@ export class QRDecomposePhase { return undefined; }); - } private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { @@ -175,34 +160,32 @@ export class QRDecomposePhase { await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); return { ok: false, error: result.errors?.join("; ") }; } - // Only unhook after successful finalization -- on failure the LLM - // receives the error as a tool result and may retry within the step. + this.state.active = false; unhookDispatch(this.dispatch, "onCompleteStep"); await this.eventLog?.emitPhaseEnd("completed"); - this.log("QR decompose finalized, workflow complete"); + this.log("QR decompose finalized, workflow complete", { phase: this.workPhase }); return { ok: true, prompt: "QR decomposition complete." }; } this.state.step = (prev + 1) as DecomposeStep; const nextName = DECOMPOSE_STEP_NAMES[this.state.step]; - const prompt = formatStep(decomposeStepGuidance(this.state.step)); + const prompt = formatStep(decomposeStepGuidance(this.state.step, this.workPhase)); - this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName }); + this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName, phase: this.workPhase }); await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); - return { ok: true, prompt }; } private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { - const qrPath = path.join(this.planDir, "qr-plan-design.json"); + const qrPath = path.join(this.planDir, `qr-${this.workPhase}.json`); let qr: QRFile; try { const raw = await fs.readFile(qrPath, "utf8"); qr = JSON.parse(raw) as QRFile; } catch (error) { const message = error instanceof Error ? error.message : String(error); - return { ok: false, errors: [`Failed to read qr-plan-design.json: ${message}`] }; + return { ok: false, errors: [`Failed to read qr-${this.workPhase}.json: ${message}`] }; } const errors: string[] = []; @@ -211,17 +194,16 @@ export class QRDecomposePhase { } else { const ungrouped = qr.items.filter((i) => i.group_id === null); if (ungrouped.length > 0) { - const ids = ungrouped.map((i) => i.id).join(", "); - errors.push(`Ungrouped items: ${ids}`); + errors.push(`Ungrouped items: ${ungrouped.map((i) => i.id).join(", ")}`); } } if (errors.length > 0) { - this.log("QR decompose validation failed", { errors }); + this.log("QR decompose validation failed", { errors, phase: this.workPhase }); return { ok: false, errors }; } - this.log("QR decompose validation passed"); + this.log("QR decompose validation passed", { phase: this.workPhase }); return { ok: true }; } } diff --git a/src/planner/phases/qr-decompose/prompts.ts b/src/planner/phases/qr-decompose/prompts.ts index 3c4969e..474f22f 100644 --- a/src/planner/phases/qr-decompose/prompts.ts +++ b/src/planner/phases/qr-decompose/prompts.ts @@ -1,7 +1,6 @@ // QR decompose phase prompts -- 13-step workflow for decomposing a plan into -// verifiable QR items. Follows the same structure as plan-design/prompts.ts. -// All tool calls reference phase='plan-design' explicitly so the decompose -// agent always writes to the correct QR namespace. +// verifiable QR items. Prompt text is shared across plan-design, plan-code, +// and plan-docs via the injected phase key. import { promises as fs } from "node:fs"; import * as os from "node:os"; @@ -10,11 +9,8 @@ import * as path from "node:path"; import type { ContextData } from "../../types.js"; import type { StepGuidance } from "../../lib/step.js"; -// -- Types -- - export type DecomposeStep = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13; - -// -- Constants -- +export type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; export const DECOMPOSE_STEP_NAMES: Record = { 1: "Absorb Context", @@ -32,7 +28,23 @@ export const DECOMPOSE_STEP_NAMES: Record = { 13: "Final Validation", }; -// -- Exports -- +const PHASE_SCOPE_HINTS: Record = { + "plan-design": [ + "decision:DL-001 -- decision reasoning quality", + "milestone:M-001 -- milestone structure", + "code_intent:CI-M-001-001 -- intent clarity", + ], + "plan-code": [ + "milestone:M-001 -- code change coverage", + "code_intent:CI-M-001-001 -- intent->change linkage", + "change:CC-M-001-001 -- diff quality/anchor correctness", + ], + "plan-docs": [ + "milestone:M-001 -- docs completeness", + "change:CC-M-001-001 -- doc_diff/comments quality", + "diagram:DIAG-001 -- architecture docs fidelity", + ], +}; export async function loadQRDecomposeSystemPrompt(): Promise { const homeDir = os.homedir(); @@ -46,15 +58,15 @@ export async function loadQRDecomposeSystemPrompt(): Promise { } } -export function buildDecomposeSystemPrompt(basePrompt: string): string { +export function buildDecomposeSystemPrompt(basePrompt: string, phase: WorkPhaseKey): string { return [ basePrompt, "", "---", "", - "WORKFLOW: 13-STEP QR DECOMPOSITION (plan-design)", + `WORKFLOW: 13-STEP QR DECOMPOSITION (${phase})`, "", - "You will execute a 13-step workflow to decompose a plan into verifiable QR items.", + "You will execute a 13-step workflow to decompose the current plan phase into verifiable QR items.", "Step 1 instructions are in the user message below.", "Complete the work described, then call koan_complete_step.", "Put your findings in the `thoughts` parameter of koan_complete_step.", @@ -66,26 +78,22 @@ export function buildDecomposeSystemPrompt(basePrompt: string): string { } export function formatContextForDecompose(ctx: ContextData): string { - return [ - "", - JSON.stringify(ctx, null, 2), - "", - ].join("\n"); + return ["", JSON.stringify(ctx, null, 2), ""].join("\n"); } -export function decomposeStepGuidance(step: DecomposeStep, context?: string): StepGuidance { +export function decomposeStepGuidance(step: DecomposeStep, phase: WorkPhaseKey, context?: string): StepGuidance { switch (step) { case 1: return { title: "Step 1: Absorb Context", instructions: [ + `PHASE: ${phase}`, "PLANNING CONTEXT (from session):", "", context ?? "", "", "Use koan_get_plan to read the full plan.", - "Absorb the plan structure: overview, constraints, milestones, decisions, code_intents, risks, invisible_knowledge.", - "Identify the key entities and relationships that will need verification.", + "Absorb the structures relevant to this phase and identify what needs verification.", ], }; @@ -93,10 +101,9 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 2: Holistic Concerns", instructions: [ - "Identify plan-wide concerns that apply across all milestones.", - "Consider: structural completeness, logical consistency, risk coverage, dependency ordering.", - "Focus on plan-level quality -- not code correctness.", - "These concerns become scope='*' items in later steps.", + `List phase-wide concerns for ${phase}.`, + "Focus on quality/completeness/consistency concerns, not implementation details.", + "These become umbrella items (scope='*').", ], }; @@ -104,14 +111,9 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 3: Structural Enumeration", instructions: [ - "Enumerate every major entity in the plan:", - " - Decisions (DL-xxx)", - " - Constraints", - " - Risks", - " - Milestones (M-xxx) and their code_intents (CI-M-xxx-xxx)", - " - Invisible knowledge entries", - " - Waves and ordering", - "Track counts for validation in step 8.", + `Enumerate concrete entities touched by ${phase}.`, + "Track IDs and counts so step 7 can validate coverage.", + "Use getter tools to resolve uncertain IDs.", ], }; @@ -119,9 +121,8 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 4: Gap Analysis", instructions: [ - "Compare holistic concerns (step 2) against structural entities (step 3).", - "Identify gaps: concerns not covered by any entity, entities lacking justification.", - "Note areas where the plan is thin or under-specified.", + "Map concerns (step 2) to entities (step 3).", + "Identify uncovered concerns and under-specified entities.", ], }; @@ -129,22 +130,16 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 5: Generate Items", instructions: [ - "Generate QR items from the analysis in steps 2-4.", - "Use koan_qr_add_item to create each item. Always pass phase='plan-design'.", + "Generate QR items with koan_qr_add_item.", + `Always pass phase='${phase}'.`, "", - "SCOPE VOCABULARY:", - " '*' -- plan-wide check", - " 'milestone:M-001' -- milestone-specific check", - " 'decision:DL-001' -- decision-specific check", - " 'code_intent:CI-M-001-001' -- code intent-specific check", + "Scope examples for this phase:", + ...PHASE_SCOPE_HINTS[phase].map((hint) => ` - ${hint}`), "", - "SEVERITY:", - " MUST -- blocks all iterations (critical defect)", - " SHOULD -- important quality issue", - " COULD -- nice-to-have improvement", - "", - "Generate items covering: structural completeness, decision reasoning chains,", - "risk coverage, milestone scoping, code intent clarity, constraint satisfaction.", + "Severity:", + " MUST -- critical defect", + " SHOULD -- significant quality issue", + " COULD -- non-blocking improvement", ], }; @@ -152,11 +147,8 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 6: Atomicity Check", instructions: [ - "Review each generated item. Each item should test exactly one concern.", - "If an item covers multiple concerns, split it:", - " Use koan_qr_add_item for each child item.", - " The original becomes the parent (parent_id on children).", - "Atomic items are easier to verify independently.", + "Ensure each item checks exactly one concern.", + "Split non-atomic items by adding child items when needed.", ], }; @@ -164,11 +156,8 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 7: Coverage Validation", instructions: [ - "Cross-reference items against the plan structure.", - "Every milestone should have at least one QR item.", - "Every decision should have at least one QR item.", - "High-severity risks should have corresponding QR items.", - "Use koan_qr_add_item for any gaps found.", + "Cross-check item set against structural enumeration from step 3.", + "Add missing items for uncovered entities/concerns.", ], }; @@ -176,11 +165,9 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 8: Validate Items", instructions: [ - "Items are already on disk (each koan_qr_add_item wrote immediately).", - "Use koan_qr_summary(phase='plan-design') to verify counts.", - "Use koan_qr_list_items(phase='plan-design') to review all items.", - "Check: no duplicate checks, severity levels appropriate, scopes valid.", - "Add missing items with koan_qr_add_item if gaps found.", + "Use koan_qr_summary and koan_qr_list_items to audit generated items.", + `Always pass phase='${phase}'.`, + "Fix duplicates or malformed scopes by adding/revising items.", ], }; @@ -188,13 +175,10 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 9: Structural Grouping", instructions: [ - "Begin organizing items into review groups.", - "DETERMINISTIC RULES:", - " - Parent-child items share the same group", - " - Umbrella items (scope='*') get group_id='umbrella'", - "", - "Use koan_qr_list_items(phase='plan-design') to see current items.", - "Use koan_qr_assign_group(phase='plan-design', ids=[...], group_id='...') to assign groups.", + "Assign deterministic groups:", + " - Parent/child items share group", + " - Umbrella items (scope='*') use group_id='umbrella'", + `Use koan_qr_assign_group(phase='${phase}', ...)`, ], }; @@ -202,11 +186,8 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 10: Component Grouping", instructions: [ - "Group remaining ungrouped items by plan component.", - "Group candidates: a major milestone, a major decision, a constraint category.", - "", - "Use koan_qr_list_items(phase='plan-design') to see ungrouped items.", - "Use koan_qr_assign_group(phase='plan-design', ids=[...], group_id='...') to assign.", + "Group remaining ungrouped items by component (milestone/decision/change cluster).", + `Use koan_qr_list_items(phase='${phase}') and koan_qr_assign_group(...)`, ], }; @@ -215,10 +196,7 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St title: "Step 11: Concern Grouping", instructions: [ "Group remaining ungrouped items by concern type.", - "Group candidates: reasoning chain quality, reference integrity, risk coverage.", - "", - "Use koan_qr_list_items(phase='plan-design') to see ungrouped items.", - "Use koan_qr_assign_group(phase='plan-design', ids=[...], group_id='...') to assign.", + "Example concern groups: coverage, consistency, traceability, docs quality.", ], }; @@ -226,11 +204,8 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 12: Affinity Grouping", instructions: [ - "Assign remaining ungrouped items to groups based on similarity.", - "Singletons are acceptable -- not every item needs a multi-member group.", - "", - "Use koan_qr_list_items(phase='plan-design') to see ungrouped items.", - "Use koan_qr_assign_group(phase='plan-design', ids=[...], group_id='...') to assign.", + "Assign any remaining ungrouped items by semantic affinity.", + "Singleton groups are acceptable.", ], }; @@ -238,14 +213,13 @@ export function decomposeStepGuidance(step: DecomposeStep, context?: string): St return { title: "Step 13: Final Validation", instructions: [ - "Validate all items are grouped and well-formed.", - "Use koan_qr_summary(phase='plan-design') to check final counts.", - "Use koan_qr_list_items(phase='plan-design') to verify all items have group_id.", - "If any items lack group_id, assign them now.", - "Output 'PASS' in thoughts if all items are valid and grouped.", + "Validate that all items are grouped and well-formed.", + `Use koan_qr_summary(phase='${phase}') and koan_qr_list_items(phase='${phase}')`, + "Ensure no item has null group_id.", + "Output PASS in thoughts when complete.", ], invokeAfter: [ - "WHEN DONE: Call koan_complete_step with 'PASS' or issues found in the `thoughts` parameter.", + "WHEN DONE: Call koan_complete_step with PASS or issues in `thoughts`.", "Do NOT call this tool until validation is complete.", ].join("\n"), }; diff --git a/src/planner/phases/qr-verify/phase.ts b/src/planner/phases/qr-verify/phase.ts index 4a8e5c1..623b9f6 100644 --- a/src/planner/phases/qr-verify/phase.ts +++ b/src/planner/phases/qr-verify/phase.ts @@ -1,7 +1,5 @@ // QR verify phase -- 3-step reviewer subagent that verifies exactly 1 QR item // against the plan (CONTEXT -> ANALYZE -> CONFIRM). One subagent per item. -// Mirrors PlanDesignPhase lifecycle; no finalize validation -- parent reads -// item status from disk after the reviewer exits. import { promises as fs } from "node:fs"; import * as path from "node:path"; @@ -12,12 +10,7 @@ import { formatStep } from "../../lib/step.js"; import type { ContextData } from "../../types.js"; import { createLogger, type Logger } from "../../../utils/logger.js"; import { EventLog } from "../../lib/audit.js"; -import { - hookDispatch, - unhookDispatch, - type WorkflowDispatch, - type PlanRef, -} from "../../lib/dispatch.js"; +import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; import { checkPermission } from "../../lib/permissions.js"; import type { QRItem, QRFile } from "../../qr/types.js"; import { @@ -29,7 +22,7 @@ import { type VerifyStep, } from "./prompts.js"; -// -- Constants -- +type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; const TOTAL_STEPS = 3; const STEP_NAMES: Record = { @@ -38,8 +31,6 @@ const STEP_NAMES: Record = { 3: "CONFIRM", }; -// -- State -- - interface VerifyState { active: boolean; step: VerifyStep; @@ -48,11 +39,11 @@ interface VerifyState { systemPrompt: string | null; } -// -- Phase -- - export class QRVerifyPhase { private readonly pi: ExtensionAPI; private readonly planDir: string; + private readonly workPhase: WorkPhaseKey; + private readonly qrPhaseKey: `qr-${WorkPhaseKey}`; private readonly log: Logger; private readonly state: VerifyState; private readonly eventLog: EventLog | undefined; @@ -62,7 +53,7 @@ export class QRVerifyPhase { constructor( pi: ExtensionAPI, - config: { planDir: string; itemId: string }, + config: { planDir: string; itemId: string; workPhase: WorkPhaseKey }, dispatch: WorkflowDispatch, planRef: PlanRef, log?: Logger, @@ -70,6 +61,8 @@ export class QRVerifyPhase { ) { this.pi = pi; this.planDir = config.planDir; + this.workPhase = config.workPhase; + this.qrPhaseKey = `qr-${config.workPhase}`; this.dispatch = dispatch; this.planRef = planRef; this.log = log ?? createLogger("QRVerify"); @@ -87,7 +80,6 @@ export class QRVerifyPhase { } async begin(): Promise { - // Verify plan.json exists so koan_get_plan is usable during analysis. const planPath = path.join(this.planDir, "plan.json"); try { await fs.access(planPath); @@ -107,20 +99,20 @@ export class QRVerifyPhase { return; } - const qrPath = path.join(this.planDir, "qr-plan-design.json"); + const qrPath = path.join(this.planDir, `qr-${this.workPhase}.json`); let qrFile: QRFile; try { const raw = await fs.readFile(qrPath, "utf8"); qrFile = JSON.parse(raw) as QRFile; } catch (error) { const message = error instanceof Error ? error.message : String(error); - this.log("Failed to read qr-plan-design.json", { error: message }); + this.log(`Failed to read qr-${this.workPhase}.json`, { error: message }); return; } const item = qrFile.items.find((i) => i.id === this.state.itemId); if (!item) { - this.log("QR item not found", { itemId: this.state.itemId }); + this.log("QR item not found", { itemId: this.state.itemId, phase: this.workPhase }); return; } this.item = item; @@ -134,15 +126,15 @@ export class QRVerifyPhase { return; } - this.state.systemPrompt = buildVerifySystemPrompt(basePrompt); - this.state.step1Prompt = formatStep(buildContextStep(item, contextData)); + this.state.systemPrompt = buildVerifySystemPrompt(basePrompt, this.workPhase); + this.state.step1Prompt = formatStep(buildContextStep(item, contextData, this.workPhase)); this.state.active = true; this.state.step = 1; this.planRef.dir = this.planDir; hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - this.log("Starting QR verify workflow", { itemId: this.state.itemId, step: 1 }); + this.log("Starting QR verify workflow", { itemId: this.state.itemId, phase: this.workPhase, step: 1 }); await this.eventLog?.emitPhaseStart(TOTAL_STEPS); await this.eventLog?.emitStepTransition(1, STEP_NAMES[1], TOTAL_STEPS); } @@ -153,17 +145,12 @@ export class QRVerifyPhase { return { systemPrompt: this.state.systemPrompt }; }); - // Step 1 prompt injection. Context event fires before the initial LLM - // call and replaces the trigger user message with actual step 1 instructions. - // Handler is a no-op once the step advances past 1. this.pi.on("context", (event) => { if (!this.state.active) return undefined; if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; const messages = event.messages.map((m) => { - if (m.role === "user") { - return { ...m, content: this.state.step1Prompt! }; - } + if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; return m; }); return { messages }; @@ -172,24 +159,18 @@ export class QRVerifyPhase { this.pi.on("tool_call", (event) => { if (!this.state.active) return undefined; - const perm = checkPermission("qr-plan-design", event.toolName); - if (!perm.allowed) { - return { block: true, reason: perm.reason }; - } + const perm = checkPermission(this.qrPhaseKey, event.toolName); + if (!perm.allowed) return { block: true, reason: perm.reason }; - // Step gate: koan_qr_set_item is step-3-only (CONFIRM step). - // Blocklist so read tools and other approved tools pass through. - const step = this.state.step; - if (step < 3 && event.toolName === "koan_qr_set_item") { + if (this.state.step < 3 && event.toolName === "koan_qr_set_item") { return { block: true, - reason: `koan_qr_set_item available in step 3 (current: ${step})`, + reason: `koan_qr_set_item available in step 3 (current: ${this.state.step})`, }; } return undefined; }); - } private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { @@ -199,7 +180,7 @@ export class QRVerifyPhase { this.state.active = false; unhookDispatch(this.dispatch, "onCompleteStep"); await this.eventLog?.emitPhaseEnd("completed"); - this.log("Verification complete"); + this.log("Verification complete", { itemId: this.state.itemId, phase: this.workPhase }); return { ok: true, prompt: "Verification complete." }; } @@ -207,19 +188,17 @@ export class QRVerifyPhase { const stepName = STEP_NAMES[this.state.step]; const prompt = this.buildStepPrompt(this.state.step); - this.log("Step complete, advancing", { from: prev, to: this.state.step }); + this.log("Step complete, advancing", { from: prev, to: this.state.step, phase: this.workPhase }); await this.eventLog?.emitStepTransition(this.state.step, stepName, TOTAL_STEPS); - return { ok: true, prompt }; } - // Item is stored during begin() -- avoids async re-reads for prompt building. private buildStepPrompt(step: VerifyStep): string { switch (step) { case 2: return formatStep(buildAnalyzeStep(this.item!)); case 3: - return formatStep(buildConfirmStep(this.item!)); + return formatStep(buildConfirmStep(this.item!, this.workPhase)); default: return ""; } diff --git a/src/planner/phases/qr-verify/prompts.ts b/src/planner/phases/qr-verify/prompts.ts index 97dfe3f..a364490 100644 --- a/src/planner/phases/qr-verify/prompts.ts +++ b/src/planner/phases/qr-verify/prompts.ts @@ -1,8 +1,5 @@ // Prompt guidance for the 3-step QR verify subagent workflow. -// // Each reviewer subagent verifies exactly 1 QRItem against the plan. -// Steps: CONTEXT (understand the check) -> ANALYZE (read plan, apply check) -// -> CONFIRM (record verdict via koan_qr_set_item). import { promises as fs } from "node:fs"; import * as os from "node:os"; @@ -12,12 +9,10 @@ import type { ContextData } from "../../types.js"; import type { QRItem } from "../../qr/types.js"; import type { StepGuidance } from "../../lib/step.js"; -// -- Types -- +type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; export type VerifyStep = 1 | 2 | 3; -// -- Helpers -- - function formatContextXml(ctx: ContextData): string { const fields = Object.entries(ctx) .map(([key, values]) => { @@ -41,6 +36,10 @@ function scopeGuidance(item: QRItem): string { const intentId = s.slice("code_intent:".length); return `CODE INTENT CHECK -- Use koan_get_intent(id='${intentId}') to read the intent.`; } + if (s.startsWith("change:")) { + const changeId = s.slice("change:".length); + return `CHANGE CHECK -- Use koan_get_change(id='${changeId}') to read the planned change.`; + } if (s.startsWith("decision:")) { const decisionId = s.slice("decision:".length); return `DECISION CHECK -- Use koan_get_decision(id='${decisionId}') to read the decision.`; @@ -48,8 +47,6 @@ function scopeGuidance(item: QRItem): string { return "SCOPED CHECK -- Read the relevant section using plan getter tools."; } -// -- Exports -- - export async function loadQRVerifySystemPrompt(): Promise { const promptPath = path.join(os.homedir(), ".claude/agents/quality-reviewer.md"); try { @@ -60,13 +57,13 @@ export async function loadQRVerifySystemPrompt(): Promise { } } -export function buildVerifySystemPrompt(basePrompt: string): string { +export function buildVerifySystemPrompt(basePrompt: string, phase: WorkPhaseKey): string { return [ basePrompt, "", "---", "", - "WORKFLOW: 3-STEP QR VERIFICATION (plan-design)", + `WORKFLOW: 3-STEP QR VERIFICATION (${phase})`, "", "You will verify exactly 1 QR item against the plan.", "Step 1 instructions are in the user message below.", @@ -78,11 +75,11 @@ export function buildVerifySystemPrompt(basePrompt: string): string { ].join("\n"); } -export function buildContextStep(item: QRItem, contextData: ContextData): StepGuidance { +export function buildContextStep(item: QRItem, contextData: ContextData, phase: WorkPhaseKey): StepGuidance { return { title: "Step 1: CONTEXT", instructions: [ - "PHASE: plan-design", + `PHASE: ${phase}`, "ITEM TO VERIFY:", "", "", @@ -95,9 +92,7 @@ export function buildContextStep(item: QRItem, contextData: ContextData): StepGu "PLANNING CONTEXT (reference for semantic validation):", formatContextXml(contextData), "", - "UNDERSTAND the check you need to perform.", - "Note the scope: '*' means plan-wide check, 'milestone:X' means specific milestone.", - "Severity indicates blocking behavior: MUST blocks all iterations.", + "Understand the check and required evidence before analyzing.", ], }; } @@ -109,17 +104,17 @@ export function buildAnalyzeStep(item: QRItem): StepGuidance { scopeGuidance(item), "", "TASK:", - "1. Read relevant files/sections based on scope", + "1. Read relevant entities based on scope", "2. Apply the verification check", - "3. Form preliminary conclusion: PASS or FAIL?", - "4. If FAIL, note specific evidence", + "3. Form preliminary PASS/FAIL conclusion", + "4. Gather concrete evidence", "", - "DO NOT update QR state yet. Proceed to CONFIRM step.", + "Do NOT update QR state yet.", ], }; } -export function buildConfirmStep(item: QRItem): StepGuidance { +export function buildConfirmStep(item: QRItem, phase: WorkPhaseKey): StepGuidance { return { title: "Step 3: CONFIRM", instructions: [ @@ -128,23 +123,21 @@ export function buildConfirmStep(item: QRItem): StepGuidance { "", "CONFIDENCE CHECK:", "- Are you confident in your conclusion?", - "- Did you verify against actual plan content?", - "- Is your evidence specific and verifiable?", + "- Is evidence specific and verifiable?", "", "RECORD RESULT:", "", "If PASS:", - ` koan_qr_set_item(phase='plan-design', id='${item.id}', status='PASS')`, + ` koan_qr_set_item(phase='${phase}', id='${item.id}', status='PASS')`, "", "If FAIL:", - ` koan_qr_set_item(phase='plan-design', id='${item.id}', status='FAIL',`, - " finding='')", + ` koan_qr_set_item(phase='${phase}', id='${item.id}', status='FAIL', finding='')`, "", "RULES:", - "- FAIL requires finding (explains what failed)", - "- PASS forbids finding (finding field must not be set)", + "- FAIL requires finding", + "- PASS must not include finding", "", - "Execute ONE of the above tool calls, then call koan_complete_step.", + "Execute ONE verdict call, then call koan_complete_step.", ], invokeAfter: [ "WHEN DONE: Call koan_complete_step after recording your verdict.", diff --git a/src/planner/plan/render.ts b/src/planner/plan/render.ts new file mode 100644 index 0000000..4974bdd --- /dev/null +++ b/src/planner/plan/render.ts @@ -0,0 +1,155 @@ +// Mechanical renderer: plan.json -> plan.md. +// The plan JSON is the source of truth; this file provides a deterministic +// markdown projection for human/manual review between planning and execution. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { Plan, Milestone, DiagramGraph } from "./types.js"; +import { loadPlan } from "./serialize.js"; + +function escCell(text: string): string { + return text.replace(/\|/g, "\\|").replace(/\n/g, " ").trim(); +} + +function pushList(lines: string[], title: string, values: string[]): void { + if (values.length === 0) return; + lines.push(title, ""); + for (const value of values) lines.push(`- ${value}`); + lines.push(""); +} + +function pushScopedDiagrams(lines: string[], diagrams: DiagramGraph[], scope: string): void { + const scoped = diagrams.filter((d) => d.scope === scope); + for (const diagram of scoped) { + lines.push(`### ${diagram.title}`, ""); + if (diagram.ascii_render && diagram.ascii_render.trim().length > 0) { + lines.push("```", diagram.ascii_render, "```", ""); + } else { + lines.push(`[Diagram pending rendering: ${diagram.id}]`, ""); + } + } +} + +function pushMilestone(lines: string[], milestone: Milestone, diagrams: DiagramGraph[]): void { + lines.push(`### ${milestone.id}: ${milestone.name}`, ""); + + pushScopedDiagrams(lines, diagrams, `milestone:${milestone.id}`); + + if (milestone.files.length > 0) { + lines.push(`**Files**: ${milestone.files.join(", ")}`, ""); + } + + pushList(lines, "**Requirements**", milestone.requirements); + pushList(lines, "**Acceptance Criteria**", milestone.acceptance_criteria); + pushList(lines, "**Tests**", milestone.tests); + + if (milestone.code_intents.length > 0) { + lines.push("#### Code Intents", ""); + for (const intent of milestone.code_intents) { + const fn = intent.function ? `::${intent.function}` : ""; + const refs = intent.decision_refs.length > 0 ? ` (refs: ${intent.decision_refs.join(", ")})` : ""; + lines.push(`- **${intent.id}** \`${intent.file}${fn}\`: ${intent.behavior}${refs}`); + } + lines.push(""); + } + + if (milestone.code_changes.length > 0) { + lines.push("#### Code Changes", ""); + for (const change of milestone.code_changes) { + const intentRef = change.intent_ref ? ` - implements ${change.intent_ref}` : ""; + lines.push(`**${change.id}** (${change.file})${intentRef}`, ""); + + if (change.diff.trim().length > 0) { + lines.push("**Code Diff**", "", "```diff", change.diff, "```", ""); + } + + if (change.doc_diff.trim().length > 0) { + lines.push("**Documentation Diff**", "", "```diff", change.doc_diff, "```", ""); + } + + if (change.comments.trim().length > 0) { + lines.push(`> ${change.comments}`, ""); + } + } + } +} + +export function renderPlanMarkdown(plan: Plan): string { + const lines: string[] = ["# Plan", "", "## Overview", "", plan.overview.problem || "(empty)", ""]; + + if (plan.overview.approach.trim().length > 0) { + lines.push(`**Approach**: ${plan.overview.approach}`, ""); + } + + pushScopedDiagrams(lines, plan.diagram_graphs, "overview"); + + if (plan.planning_context.decision_log.length > 0) { + lines.push("## Planning Context", "", "### Decision Log", "", "| ID | Decision | Reasoning Chain |", "|---|---|---|"); + for (const d of plan.planning_context.decision_log) { + lines.push(`| ${d.id} | ${escCell(d.decision)} | ${escCell(d.reasoning_chain)} |`); + } + lines.push(""); + } + + if (plan.planning_context.rejected_alternatives.length > 0) { + lines.push("### Rejected Alternatives", "", "| Alternative | Why Rejected |", "|---|---|"); + for (const r of plan.planning_context.rejected_alternatives) { + lines.push(`| ${escCell(r.alternative)} | ${escCell(r.rejection_reason)} (ref: ${r.decision_ref}) |`); + } + lines.push(""); + } + + pushList(lines, "### Constraints", plan.planning_context.constraints); + + if (plan.planning_context.known_risks.length > 0) { + lines.push("### Known Risks", ""); + for (const risk of plan.planning_context.known_risks) { + lines.push(`- **${risk.risk}**: ${risk.mitigation}`); + } + lines.push(""); + } + + const ik = plan.invisible_knowledge; + if (ik.system.trim().length > 0 || ik.invariants.length > 0 || ik.tradeoffs.length > 0) { + lines.push("## Invisible Knowledge", ""); + if (ik.system.trim().length > 0) { + lines.push("### System", "", ik.system, ""); + } + pushList(lines, "### Invariants", ik.invariants); + pushList(lines, "### Tradeoffs", ik.tradeoffs); + pushScopedDiagrams(lines, plan.diagram_graphs, "invisible_knowledge"); + } + + lines.push("## Milestones", ""); + for (const milestone of plan.milestones) { + pushMilestone(lines, milestone, plan.diagram_graphs); + } + + if (plan.readme_entries.length > 0) { + lines.push("## README Entries", ""); + for (const entry of plan.readme_entries) { + lines.push(`### ${entry.path}`, "", entry.content, ""); + } + } + + if (plan.waves.length > 0) { + lines.push("## Execution Waves", ""); + for (const wave of plan.waves) { + lines.push(`- ${wave.id}: ${wave.milestones.join(", ")}`); + } + lines.push(""); + } + + return `${lines.join("\n").trimEnd()}\n`; +} + +export async function renderPlanMarkdownToFile(planDir: string): Promise { + const plan = await loadPlan(planDir); + const markdown = renderPlanMarkdown(plan); + const outputPath = path.join(planDir, "plan.md"); + const tmpPath = path.join(planDir, ".plan.md.tmp"); + await fs.writeFile(tmpPath, markdown, "utf8"); + await fs.rename(tmpPath, outputPath); + return outputPath; +} diff --git a/src/planner/plan/validate.ts b/src/planner/plan/validate.ts index 210fd58..c5ecedd 100644 --- a/src/planner/plan/validate.ts +++ b/src/planner/plan/validate.ts @@ -136,35 +136,63 @@ export function validatePlanDocs(p: Plan): ValidationResult { return { ok: errors.length === 0, errors }; } -// Reads plan.json from planDir and runs validatePlanDesign + validateRefs. -// Returns { ok: false, errors } on read/parse failure or any validation failure. -export async function loadAndValidatePlan( +export type PlanValidationPhase = "plan-design" | "plan-code" | "plan-docs"; + +// Reads plan.json from planDir and runs phase-appropriate validation. +// All phases require plan-design + reference integrity checks. +// plan-code additionally requires intent->change completeness. +// plan-docs additionally requires doc completeness. +export async function loadAndValidatePlanForPhase( planDir: string, + phase: PlanValidationPhase, log: Logger, ): Promise<{ ok: boolean; errors?: string[] }> { const planPath = path.join(planDir, "plan.json"); - let plan; + let plan: Plan; try { const raw = await fs.readFile(planPath, "utf8"); - plan = JSON.parse(raw); + plan = JSON.parse(raw) as Plan; } catch (error) { const message = error instanceof Error ? error.message : String(error); - log("Failed to read plan.json for validation", { error: message }); + log("Failed to read plan.json for validation", { error: message, phase }); return { ok: false, errors: [`Failed to read plan.json: ${message}`] }; } const designValidation = validatePlanDesign(plan); if (!designValidation.ok) { - log("Plan design validation failed", { errors: designValidation.errors }); + log("Plan design validation failed", { errors: designValidation.errors, phase }); return { ok: false, errors: designValidation.errors }; } const refValidation = validateRefs(plan); if (!refValidation.ok) { - log("Plan reference validation failed", { errors: refValidation.errors }); + log("Plan reference validation failed", { errors: refValidation.errors, phase }); return { ok: false, errors: refValidation.errors }; } - log("Plan validation passed", { path: planPath }); + if (phase === "plan-code" || phase === "plan-docs") { + const codeValidation = validatePlanCode(plan); + if (!codeValidation.ok) { + log("Plan code validation failed", { errors: codeValidation.errors, phase }); + return { ok: false, errors: codeValidation.errors }; + } + } + + if (phase === "plan-docs") { + const docsValidation = validatePlanDocs(plan); + if (!docsValidation.ok) { + log("Plan docs validation failed", { errors: docsValidation.errors, phase }); + return { ok: false, errors: docsValidation.errors }; + } + } + + log("Plan validation passed", { path: planPath, phase }); return { ok: true }; } + +export async function loadAndValidatePlan( + planDir: string, + log: Logger, +): Promise<{ ok: boolean; errors?: string[] }> { + return loadAndValidatePlanForPhase(planDir, "plan-design", log); +} diff --git a/src/planner/session.ts b/src/planner/session.ts index ba24055..f48f65f 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -1,6 +1,6 @@ -// Parent session: orchestrates the koan workflow (context capture -> architect -// -> QR decompose -> QR verify pool). Polls subagent state.json for progress. -// Widget displays persistent progress; destroyed on completion. +// Parent session: orchestrates the koan planning workflow. +// Flow: context capture -> plan-design(+QR) -> plan-code(+QR) -> plan-docs(+QR) +// -> mechanical plan.json->plan.md rendering for manual review. import { promises as fs } from "node:fs"; import * as path from "node:path"; @@ -10,7 +10,17 @@ import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@m import { ContextCapturePhase } from "./phases/context-capture/phase.js"; import { createInitialState, initializePlanState, type WorkflowState } from "./state.js"; import { createPlanInfo } from "../utils/plan.js"; -import { spawnArchitect, spawnArchitectFix, spawnQRDecomposer, spawnReviewer } from "./subagent.js"; +import { + spawnArchitect, + spawnArchitectFix, + spawnDeveloper, + spawnDeveloperFix, + spawnTechnicalWriter, + spawnTechnicalWriterFix, + spawnQRDecomposer, + spawnReviewer, + type SubagentResult, +} from "./subagent.js"; import { createLogger, setLogDir, type Logger } from "../utils/logger.js"; import { createSubagentDir } from "../utils/progress.js"; import { readProjection, readRecentLogs, type Projection } from "./lib/audit.js"; @@ -19,8 +29,9 @@ import { pool } from "./lib/pool.js"; import type { QRFile } from "./qr/types.js"; import { MAX_FIX_ITERATIONS, qrPassesAtIteration } from "./qr/severity.js"; import { WidgetController, type WidgetUpdate } from "./ui/widget.js"; +import { renderPlanMarkdownToFile } from "./plan/render.js"; -// -- Types -- +type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; interface Session { plan(args: string, ctx: ExtensionCommandContext): Promise; @@ -33,6 +44,29 @@ interface QRBlockResult { passed: boolean; } +interface PhaseRunConfig { + key: WorkPhaseKey; + label: string; + widgetIndex: number; + role: "architect" | "developer" | "technical-writer"; + spawnWork: (opts: SpawnWorkRunOptions) => Promise; + spawnFix: (opts: SpawnFixRunOptions) => Promise; +} + +interface SpawnWorkRunOptions { + planDir: string; + subagentDir: string; + cwd: string; + extensionPath: string; + log: Logger; +} + +interface SpawnFixRunOptions extends SpawnWorkRunOptions {} + +function qrFilePath(planDir: string, phase: WorkPhaseKey): string { + return path.join(planDir, `qr-${phase}.json`); +} + function singleSubagentStart(role: string): WidgetUpdate { return { subagentRole: role, @@ -55,17 +89,23 @@ function singleSubagentFromProjection(p: Projection): WidgetUpdate { }; } -// -- Session -- +function phaseRunningState(phase: WorkPhaseKey): WorkflowState["phase"] { + if (phase === "plan-design") return "architect-running"; + if (phase === "plan-code") return "plan-code-running"; + return "plan-docs-running"; +} + +function phaseCompleteState(phase: WorkPhaseKey): WorkflowState["phase"] { + if (phase === "plan-design") return "plan-design-complete"; + if (phase === "plan-code") return "plan-code-complete"; + return "plan-docs-complete"; +} export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, planRef: PlanRef): Session { const state: WorkflowState = createInitialState(); const log = createLogger("Session"); let widget: WidgetController | null = null; - // Completion callback for context-capture phase. Runs inside the - // koan_store_context tool call -- the tool blocks until the architect - // subagent finishes. The LLM sees context capture + architect outcome - // in one tool response. const onContextComplete = async (ctx: ExtensionContext): Promise => { if (!state.plan) { return "Context captured but no plan state available."; @@ -75,112 +115,85 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan try { const planDir = state.plan.directory; - const planJsonPath = path.join(planDir, "plan.json"); - const subagentDir = await createSubagentDir(planDir, "architect"); + const extensionPath = path.resolve(import.meta.dirname, "../../extensions/koan.ts"); + + const phases: PhaseRunConfig[] = [ + { + key: "plan-design", + label: "Plan design", + widgetIndex: 1, + role: "architect", + spawnWork: (opts) => spawnArchitect(opts), + spawnFix: (opts) => spawnArchitectFix({ ...opts, fixPhase: "plan-design" }), + }, + { + key: "plan-code", + label: "Plan code", + widgetIndex: 2, + role: "developer", + spawnWork: (opts) => spawnDeveloper(opts), + spawnFix: (opts) => spawnDeveloperFix({ ...opts, fixPhase: "plan-code" }), + }, + { + key: "plan-docs", + label: "Plan docs", + widgetIndex: 3, + role: "technical-writer", + spawnWork: (opts) => spawnTechnicalWriter(opts), + spawnFix: (opts) => spawnTechnicalWriterFix({ ...opts, fixPhase: "plan-docs" }), + }, + ]; - state.phase = "architect-running"; widget?.update({ phaseStatus: { index: 0, status: "completed" }, activeIndex: 1, - step: "spawning architect...", + step: "context captured; starting planning phases...", activity: "", - qrIterationsMax: MAX_FIX_ITERATIONS + 1, - qrIteration: 1, - qrMode: "initial", - qrPhase: "execute", - qrDone: null, - qrTotal: null, - qrPass: null, - qrFail: null, - qrTodo: null, - ...singleSubagentStart("architect"), }); - log("Spawning architect after context capture", { planDir, subagentDir }); - - const extensionPath = path.resolve(import.meta.dirname, "../../extensions/koan.ts"); - const pollInterval = setInterval(async () => { - const [s, logs] = await Promise.all([ - readProjection(subagentDir), - readRecentLogs(subagentDir), - ]); - if (s) { - widget?.update({ - step: s.stepName, - activity: s.lastAction ?? "", - logLines: logs, - ...singleSubagentFromProjection(s), - }); + const phaseSummaries: string[] = []; + for (const phase of phases) { + const result = await runPlanningPhase( + phase, + planDir, + ctx.cwd, + extensionPath, + state, + log, + widget, + ); + + phaseSummaries.push(`${phase.label}: ${result.summary}`); + if (!result.passed) { + return `Context captured. ${phase.label} failed.\n\n${phaseSummaries.join("\n")}`; } - }, 2000); - - const result = await spawnArchitect({ - planDir, - subagentDir, - cwd: ctx.cwd, - extensionPath, - log, - }); - - clearInterval(pollInterval); - - if (result.exitCode !== 0) { - state.phase = "architect-failed"; - const detail = result.stderr.slice(0, 500); - log("Architect subagent failed", { exitCode: result.exitCode, stderr: detail }); - widget?.update({ - phaseStatus: { index: 1, status: "failed" }, - step: "architect failed", - activity: "", - subagentActive: 0, - subagentDone: 1, - }); - return `Context captured. Architect subagent failed (exit ${result.exitCode}).\n\nStderr:\n${detail}`; } - let planExists = false; + let planMdPath: string; try { - await fs.access(planJsonPath); - planExists = true; - } catch { - // plan.json not written - } - - if (!planExists) { - state.phase = "architect-failed"; - log("Architect completed but plan.json not found", { planJsonPath }); - widget?.update({ - phaseStatus: { index: 1, status: "failed" }, - step: "no plan produced", - activity: "", - subagentActive: 0, - subagentDone: 1, - }); - return "Context captured. Architect completed but produced no plan."; + planMdPath = await renderPlanMarkdownToFile(planDir); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + log("Failed to render plan.md", { error: message, planDir }); + return `Planning phases completed, but plan markdown rendering failed: ${message}`; } - state.phase = "plan-design-complete"; - log("Architect plan-design complete", { planDir }); + state.phase = "plan-docs-complete"; widget?.update({ - phaseStatus: { index: 1, status: "running" }, - step: "starting QR block...", + activeIndex: -1, + step: "planning complete; awaiting manual review of plan.md", activity: "", - qrIterationsMax: MAX_FIX_ITERATIONS + 1, - qrIteration: 1, - qrMode: "initial", - qrPhase: "execute", - qrDone: null, - qrTotal: null, - qrPass: null, - qrFail: null, - qrTodo: null, - subagentActive: 0, - subagentDone: 1, }); - const qr = await runPlanDesignWithQR(planDir, ctx.cwd, extensionPath, state, log, widget); - if (qr.passed) outcome = "PASS"; - return `Context captured. Plan design complete.\n\n${qr.summary}`; + outcome = "PASS"; + return [ + "Context captured. Planning complete.", + "", + ...phaseSummaries, + "", + `Plan markdown: ${planMdPath}`, + "PAUSE: Please review this file manually before /koan execute.", + ].join("\n"); } finally { if (widget) { widget.destroy(); @@ -219,7 +232,6 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan planDirectory: planInfo.directory, }); - // Destroy stale widget if re-entered if (widget) { widget.destroy(); widget = null; @@ -242,39 +254,149 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan }; } -// -- QR Block -- - const QR_POOL_CONCURRENCY = 6; +async function runPlanningPhase( + phase: PhaseRunConfig, + planDir: string, + cwd: string, + extensionPath: string, + state: WorkflowState, + log: Logger, + widget: WidgetController | null, +): Promise { + state.phase = phaseRunningState(phase.key); + + widget?.update({ + phaseStatus: { index: phase.widgetIndex, status: "running" }, + activeIndex: phase.widgetIndex, + step: `${phase.key}: spawning ${phase.role}...`, + activity: "", + qrIterationsMax: MAX_FIX_ITERATIONS + 1, + qrIteration: 1, + qrMode: "initial", + qrPhase: "execute", + qrDone: null, + qrTotal: null, + qrPass: null, + qrFail: null, + qrTodo: null, + ...singleSubagentStart(phase.role), + }); + + const subagentDir = await createSubagentDir(planDir, `${phase.role}-${phase.key}`); + + const pollInterval = setInterval(async () => { + const [projection, logs] = await Promise.all([readProjection(subagentDir), readRecentLogs(subagentDir)]); + if (!projection) return; + widget?.update({ + step: `${phase.key}: ${projection.stepName}`, + activity: projection.lastAction ?? "", + logLines: logs, + ...singleSubagentFromProjection(projection), + }); + }, 2000); + + const workResult = await phase.spawnWork({ + planDir, + subagentDir, + cwd, + extensionPath, + log, + }); + + clearInterval(pollInterval); + + if (workResult.exitCode !== 0) { + const detail = workResult.stderr.slice(0, 500); + log(`${phase.key} subagent failed`, { exitCode: workResult.exitCode, stderr: detail }); + widget?.update({ + phaseStatus: { index: phase.widgetIndex, status: "failed" }, + step: `${phase.key}: worker failed`, + activity: "", + subagentActive: 0, + subagentDone: 1, + }); + return { summary: `${phase.label} subagent failed (exit ${workResult.exitCode}).\n\nStderr:\n${detail}`, passed: false }; + } + + const planJsonPath = path.join(planDir, "plan.json"); + try { + await fs.access(planJsonPath); + } catch { + log(`${phase.key} completed but plan.json missing`, { planJsonPath }); + widget?.update({ + phaseStatus: { index: phase.widgetIndex, status: "failed" }, + step: `${phase.key}: no plan produced`, + activity: "", + subagentActive: 0, + subagentDone: 1, + }); + return { summary: `${phase.label} completed but produced no plan.json.`, passed: false }; + } + + state.phase = phaseCompleteState(phase.key); + widget?.update({ + step: `${phase.key}: starting QR block...`, + activity: "", + qrIteration: 1, + qrMode: "initial", + qrPhase: "execute", + qrDone: null, + qrTotal: null, + qrPass: null, + qrFail: null, + qrTodo: null, + subagentActive: 0, + subagentDone: 1, + }); + + const qr = await runPhaseWithQR( + phase, + planDir, + cwd, + extensionPath, + state, + log, + widget, + ); + + if (qr.passed) { + state.phase = phaseCompleteState(phase.key); + widget?.update({ phaseStatus: { index: phase.widgetIndex, status: "completed" } }); + } else { + widget?.update({ phaseStatus: { index: phase.widgetIndex, status: "failed" } }); + } + + return qr; +} + async function runQRBlock( planDir: string, cwd: string, extensionPath: string, + phase: WorkPhaseKey, state: WorkflowState, log: Logger, widget: WidgetController | null, ): Promise { - const qrPath = path.join(planDir, "qr-plan-design.json"); + const qrPath = qrFilePath(planDir, phase); const keyOf = (scope: string, check: string): string => `${scope}\u0000${check}`; - // Carry forward confirmed PASS concerns across re-decompose runs. const previousPassKeys = new Set(); try { const raw = await fs.readFile(qrPath, "utf8"); const prev = JSON.parse(raw) as QRFile; for (const item of prev.items) { - if (item.status === "PASS") { - previousPassKeys.add(keyOf(item.scope, item.check)); - } + if (item.status === "PASS") previousPassKeys.add(keyOf(item.scope, item.check)); } } catch { - // No previous QR file yet. + // First QR run for this phase. } - // 1. Spawn decomposer subagent state.phase = "qr-decompose-running"; widget?.update({ - step: "qr-decompose: starting...", + step: `${phase} qr-decompose: starting...`, activity: "", qrPhase: "decompose", qrDone: null, @@ -284,21 +406,18 @@ async function runQRBlock( qrTodo: null, ...singleSubagentStart("qr-decomposer"), }); - const decomposeDir = await createSubagentDir(planDir, "qr-decomposer"); + + const decomposeDir = await createSubagentDir(planDir, `qr-decomposer-${phase}`); const decomposePoll = setInterval(async () => { - const [s, logs] = await Promise.all([ - readProjection(decomposeDir), - readRecentLogs(decomposeDir), - ]); - if (s) { - widget?.update({ - step: `qr-decompose: ${s.stepName}`, - activity: s.lastAction ?? "", - logLines: logs, - ...singleSubagentFromProjection(s), - }); - } + const [projection, logs] = await Promise.all([readProjection(decomposeDir), readRecentLogs(decomposeDir)]); + if (!projection) return; + widget?.update({ + step: `${phase} qr-decompose: ${projection.stepName}`, + activity: projection.lastAction ?? "", + logLines: logs, + ...singleSubagentFromProjection(projection), + }); }, 2000); const decompose = await spawnQRDecomposer({ @@ -306,6 +425,7 @@ async function runQRBlock( subagentDir: decomposeDir, cwd, extensionPath, + phase, log, }); @@ -314,17 +434,11 @@ async function runQRBlock( if (decompose.exitCode !== 0) { state.phase = "qr-decompose-failed"; const detail = decompose.stderr.slice(0, 500); - log("QR decomposer failed", { exitCode: decompose.exitCode, stderr: detail }); - widget?.update({ - step: "qr-decompose: failed", - activity: "", - subagentActive: 0, - subagentDone: 1, - }); - return { summary: `QR decompose failed (exit ${decompose.exitCode}).\n\nStderr:\n${detail}`, passed: false }; + log("QR decomposer failed", { phase, exitCode: decompose.exitCode, stderr: detail }); + widget?.update({ step: `${phase} qr-decompose: failed`, activity: "", subagentActive: 0, subagentDone: 1 }); + return { summary: `${phase} QR decompose failed (exit ${decompose.exitCode}).\n\nStderr:\n${detail}`, passed: false }; } - // 2. Read QR items let qr: QRFile; try { const raw = await fs.readFile(qrPath, "utf8"); @@ -332,19 +446,17 @@ async function runQRBlock( } catch (error) { state.phase = "qr-decompose-failed"; const message = error instanceof Error ? error.message : String(error); - log("Failed to read qr-plan-design.json after decompose", { error: message }); - return { summary: "QR decompose completed but produced no verifiable items.", passed: false }; + log("Failed to read QR file after decompose", { phase, error: message }); + return { summary: `${phase} QR decompose completed but produced no verifiable items.`, passed: false }; } if (qr.items.length === 0) { state.phase = "qr-decompose-failed"; - log("QR decompose produced no items"); - return { summary: "QR decompose completed but produced no items.", passed: false }; + log("QR decompose produced no items", { phase }); + return { summary: `${phase} QR decompose completed but produced no items.`, passed: false }; } - // Re-apply previously confirmed PASS concerns if re-decompose reset them. - const carriedPasses = qr.items.filter((item) => - item.status !== "PASS" && previousPassKeys.has(keyOf(item.scope, item.check))).length; + const carriedPasses = qr.items.filter((item) => item.status !== "PASS" && previousPassKeys.has(keyOf(item.scope, item.check))).length; if (carriedPasses > 0) { qr = { ...qr, @@ -359,22 +471,16 @@ async function runQRBlock( await fs.rename(tmpPath, qrPath); } catch (error) { const message = error instanceof Error ? error.message : String(error); - log("Failed to persist carried PASS statuses", { error: message }); - return { summary: "QR verify aborted: failed to preserve PASS statuses.", passed: false }; + log("Failed to persist carried PASS statuses", { phase, error: message }); + return { summary: `${phase} QR verify aborted: failed to preserve PASS statuses.`, passed: false }; } } - // Preserve prior PASS verdicts, but force all FAIL items back to TODO for - // re-verification. This keeps confirmed concerns stable while requiring - // explicit re-check of previously failing concerns. const resetFailures = qr.items.filter((i) => i.status === "FAIL").length; if (resetFailures > 0) { qr = { ...qr, - items: qr.items.map((item) => - item.status === "FAIL" - ? { ...item, status: "TODO", finding: null } - : item), + items: qr.items.map((item) => (item.status === "FAIL" ? { ...item, status: "TODO", finding: null } : item)), }; try { const tmpPath = `${qrPath}.tmp`; @@ -382,8 +488,8 @@ async function runQRBlock( await fs.rename(tmpPath, qrPath); } catch (error) { const message = error instanceof Error ? error.message : String(error); - log("Failed to persist QR FAIL->TODO reset", { error: message }); - return { summary: "QR verify aborted: failed to prepare QR item states.", passed: false }; + log("Failed to persist QR FAIL->TODO reset", { phase, error: message }); + return { summary: `${phase} QR verify aborted: failed to prepare QR item states.`, passed: false }; } } @@ -393,16 +499,8 @@ async function runQRBlock( const initialFail = qr.items.filter((i) => i.status === "FAIL").length; const initialTodo = qr.items.filter((i) => i.status === "TODO").length; - log("QR decompose complete", { - itemCount: totalItems, - verifyCount: verifyIds.length, - preservedPass, - carriedPasses, - resetFailures, - }); - widget?.update({ - step: `qr-verify: 0/${verifyIds.length}`, + step: `${phase} qr-verify: 0/${verifyIds.length}`, activity: "", qrTotal: totalItems, qrDone: preservedPass, @@ -416,7 +514,6 @@ async function runQRBlock( subagentDone: 0, }); - // 3. Spawn reviewer pool (TODO-only) state.phase = "qr-verify-running"; widget?.update({ qrPhase: "verify" }); @@ -449,12 +546,13 @@ async function runQRBlock( verifyIds, QR_POOL_CONCURRENCY, async (itemId) => { - const reviewerDir = await createSubagentDir(planDir, `qr-reviewer-${itemId}`); + const reviewerDir = await createSubagentDir(planDir, `qr-reviewer-${phase}-${itemId}`); const r = await spawnReviewer({ planDir, subagentDir: reviewerDir, cwd, extensionPath, + phase, itemId, log, }); @@ -462,9 +560,7 @@ async function runQRBlock( if (reviewerModel === null) { const projection = await readProjection(reviewerDir); reviewerModel = projection?.model ?? null; - if (reviewerModel) { - widget?.update({ subagentModel: reviewerModel }); - } + if (reviewerModel) widget?.update({ subagentModel: reviewerModel }); } return r; @@ -472,7 +568,7 @@ async function runQRBlock( (progress) => { verifyDone = progress.done; widget?.update({ - step: `qr-verify: ${progress.done}/${progress.total}`, + step: `${phase} qr-verify: ${progress.done}/${progress.total}`, qrDone: preservedPass + progress.done, qrTotal: totalItems, subagentQueued: progress.queued, @@ -487,7 +583,6 @@ async function runQRBlock( } } - // 4. Read final results state.phase = "qr-complete"; let finalQR: QRFile; try { @@ -500,9 +595,7 @@ async function runQRBlock( const pass = finalQR.items.filter((i) => i.status === "PASS").length; const fail = finalQR.items.filter((i) => i.status === "FAIL").length; const todo = finalQR.items.filter((i) => i.status === "TODO").length; - const summary = `QR complete: ${pass} PASS, ${fail} FAIL, ${todo} TODO (${failedReviewers.length} reviewers failed).`; - - log("QR block complete", { pass, fail, todo, failedReviewers }); + const summary = `${phase} QR complete: ${pass} PASS, ${fail} FAIL, ${todo} TODO (${failedReviewers.length} reviewers failed).`; const passed = fail === 0 && failedReviewers.length === 0; widget?.update({ @@ -520,21 +613,8 @@ async function runQRBlock( return { summary, passed }; } -// -- Plan-design QR fix loop -- - -// Fix loop: architect -> QR -> [pass: done | fail: fix architect -> QR -> ...] -// -// Re-decomposes on each iteration rather than re-verifying only. The fix -// architect may change plan structure (add milestones, split intents, remove -// decisions); old QR items referencing stale scopes can produce stale verdicts. -// -// Verification semantics per iteration: -// - PASS items are preserved (confirmed concerns stay confirmed). -// - FAIL items are reset to TODO (must be re-verified after fixes). -// - TODO items are verified. -// -// The session's for-loop counter remains the iteration source of truth. -async function runPlanDesignWithQR( +async function runPhaseWithQR( + phase: PhaseRunConfig, planDir: string, cwd: string, extensionPath: string, @@ -542,12 +622,11 @@ async function runPlanDesignWithQR( log: Logger, widget: WidgetController | null, ): Promise { - const qrPath = path.join(planDir, "qr-plan-design.json"); + const qrPath = qrFilePath(planDir, phase.key); - // Initial QR (iteration 1) - let qr = await runQRBlock(planDir, cwd, extensionPath, state, log, widget); + let qr = await runQRBlock(planDir, cwd, extensionPath, phase.key, state, log, widget); if (qr.passed) { - widget?.update({ qrPhase: "done", phaseStatus: { index: 1, status: "completed" } }); + widget?.update({ qrPhase: "done", phaseStatus: { index: phase.widgetIndex, status: "completed" } }); return qr; } @@ -565,21 +644,16 @@ async function runPlanDesignWithQR( qrTodo: null, }); - // Read QR file for severity check let qrFile: QRFile; try { const raw = await fs.readFile(qrPath, "utf8"); qrFile = JSON.parse(raw) as QRFile; } catch { - log("Fix loop: failed to read QR file", { iteration }); + log("Fix loop: failed to read QR file", { phase: phase.key, iteration }); widget?.update({ qrPhase: "done" }); - return { summary: "Fix loop aborted: cannot read QR file.", passed: false }; + return { summary: `${phase.key} fix loop aborted: cannot read QR file.`, passed: false }; } - // Severity escalation: if no blocking failures remain at this - // iteration, the plan passes without another fix attempt. - // Example: iteration 3 drops COULD -- if only COULD items fail, - // the plan is good enough and the loop terminates. if (qrPassesAtIteration(qrFile.items, iteration)) { const pass = qrFile.items.filter((i) => i.status === "PASS").length; const fail = qrFile.items.filter((i) => i.status === "FAIL").length; @@ -591,83 +665,79 @@ async function runPlanDesignWithQR( qrPass: pass, qrFail: fail, qrTodo: todo, - phaseStatus: { index: 1, status: "completed" }, + phaseStatus: { index: phase.widgetIndex, status: "completed" }, }); return { passed: true, - summary: `QR passed at iteration ${iteration} after severity de-escalation: ${pass} PASS, ${fail} FAIL (non-blocking).`, + summary: `${phase.key} QR passed at iteration ${iteration} after severity de-escalation: ${pass} PASS, ${fail} FAIL (non-blocking).`, }; } - // Spawn fix-mode architect const fixIndex = iteration - 1; widget?.update({ - step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: spawning architect...`, + step: `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}: spawning ${phase.role}...`, activity: "", qrPhase: "execute", - ...singleSubagentStart("architect"), + ...singleSubagentStart(phase.role), }); - const fixDir = await createSubagentDir(planDir, `architect-fix-${fixIndex}`); + const fixDir = await createSubagentDir(planDir, `${phase.role}-fix-${phase.key}-${fixIndex}`); const fixPoll = setInterval(async () => { - const [s, logs] = await Promise.all([ - readProjection(fixDir), - readRecentLogs(fixDir), - ]); - if (s) { - widget?.update({ - step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: ${s.stepName}`, - activity: s.lastAction ?? "", - logLines: logs, - ...singleSubagentFromProjection(s), - }); - } + const [projection, logs] = await Promise.all([readProjection(fixDir), readRecentLogs(fixDir)]); + if (!projection) return; + widget?.update({ + step: `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}: ${projection.stepName}`, + activity: projection.lastAction ?? "", + logLines: logs, + ...singleSubagentFromProjection(projection), + }); }, 2000); - const fixResult = await spawnArchitectFix({ + const fixResult = await phase.spawnFix({ planDir, subagentDir: fixDir, cwd, extensionPath, - fixPhase: "plan-design", log, }); clearInterval(fixPoll); if (fixResult.exitCode !== 0) { - log("Fix architect failed", { iteration: fixIndex, exitCode: fixResult.exitCode, stderr: fixResult.stderr.slice(0, 500) }); + log("Fix worker failed", { + phase: phase.key, + iteration: fixIndex, + exitCode: fixResult.exitCode, + stderr: fixResult.stderr.slice(0, 500), + }); widget?.update({ - step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: architect failed, re-running QR...`, + step: `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}: worker failed, re-running QR...`, activity: "", subagentActive: 0, subagentDone: 1, }); } - // Re-run full QR (decompose + verify) widget?.update({ - step: `fix ${fixIndex}/${MAX_FIX_ITERATIONS}: re-running QR...`, + step: `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}: re-running QR...`, activity: "", subagentActive: 0, subagentDone: 1, }); - qr = await runQRBlock(planDir, cwd, extensionPath, state, log, widget); + + qr = await runQRBlock(planDir, cwd, extensionPath, phase.key, state, log, widget); if (qr.passed) { - widget?.update({ qrPhase: "done", phaseStatus: { index: 1, status: "completed" } }); + widget?.update({ qrPhase: "done", phaseStatus: { index: phase.widgetIndex, status: "completed" } }); return qr; } widget?.update({ qrPhase: "execute", qrDone: null, qrTotal: null, qrPass: null, qrFail: null, qrTodo: null }); } - // Max iterations reached. MUST failures remaining after 5 fix attempts - // indicate a structural problem -- silently passing would propagate a - // known-broken plan downstream. widget?.update({ qrPhase: "done" }); return { passed: false, - summary: `${qr.summary} (max ${MAX_FIX_ITERATIONS} fix iterations reached)`, + summary: `${phase.key} ${qr.summary} (max ${MAX_FIX_ITERATIONS} fix iterations reached)`, }; } diff --git a/src/planner/state.ts b/src/planner/state.ts index 3583d4d..eb34f5b 100644 --- a/src/planner/state.ts +++ b/src/planner/state.ts @@ -8,6 +8,10 @@ export type WorkflowPhase = | "architect-running" | "architect-failed" | "plan-design-complete" + | "plan-code-running" + | "plan-code-complete" + | "plan-docs-running" + | "plan-docs-complete" | "qr-decompose-running" | "qr-decompose-failed" | "qr-verify-running" @@ -54,18 +58,7 @@ export function createInitialState(): WorkflowState { export function resetContextState(state: WorkflowState): void { state.context = null; - if ( - state.phase === "context" || - state.phase === "context-failed" || - state.phase === "context-complete" || - state.phase === "architect-failed" || - state.phase === "plan-design-complete" || - state.phase === "qr-decompose-running" || - state.phase === "qr-decompose-failed" || - state.phase === "qr-verify-running" || - state.phase === "qr-verify-failed" || - state.phase === "qr-complete" - ) { + if (state.phase !== "idle") { state.phase = "idle"; } } diff --git a/src/planner/subagent.ts b/src/planner/subagent.ts index 32cb584..973759b 100644 --- a/src/planner/subagent.ts +++ b/src/planner/subagent.ts @@ -9,13 +9,15 @@ import * as path from "node:path"; import { createLogger, type Logger } from "../utils/logger.js"; +type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; + export interface SubagentResult { exitCode: number; stderr: string; subagentDir: string; } -export interface SpawnArchitectOptions { +export interface SpawnWorkOptions { planDir: string; subagentDir: string; cwd: string; @@ -24,12 +26,12 @@ export interface SpawnArchitectOptions { log?: Logger; } -export interface SpawnArchitectFixOptions { +export interface SpawnFixOptions { planDir: string; subagentDir: string; cwd: string; extensionPath: string; - fixPhase: string; // e.g. "plan-design" + fixPhase: WorkPhaseKey; log?: Logger; } @@ -38,6 +40,7 @@ export interface SpawnQRDecomposerOptions { subagentDir: string; cwd: string; extensionPath: string; + phase: WorkPhaseKey; log?: Logger; } @@ -46,12 +49,11 @@ export interface SpawnReviewerOptions { subagentDir: string; cwd: string; extensionPath: string; + phase: WorkPhaseKey; itemId: string; log?: Logger; } -// -- Spawn helper -- - function spawnSubagent( role: string, phase: string, @@ -70,7 +72,7 @@ function spawnSubagent( prompt, ]; - log(`Spawning ${role} subagent`, { planDir: opts.planDir, subagentDir: opts.subagentDir }); + log(`Spawning ${role} subagent`, { planDir: opts.planDir, subagentDir: opts.subagentDir, phase }); return new Promise((resolve) => { const stdoutLog = createWriteStream(path.join(opts.subagentDir, "stdout.log"), { flags: "w" }); @@ -97,55 +99,85 @@ function spawnSubagent( stdoutLog.end(); stderrLog.end(); const exitCode = code ?? 1; - log(`${role} subagent exited`, { exitCode }); + log(`${role} subagent exited`, { exitCode, phase }); resolve({ exitCode, stderr, subagentDir: opts.subagentDir }); }); proc.on("error", (error) => { stdoutLog.end(); stderrLog.end(); - log(`${role} subagent spawn error`, { error: error.message }); + log(`${role} subagent spawn error`, { error: error.message, phase }); resolve({ exitCode: 1, stderr: error.message, subagentDir: opts.subagentDir }); }); }); } -// -- Architect spawners -- +function spawnWork(role: string, phase: WorkPhaseKey, prompt: string, opts: SpawnWorkOptions): Promise { + const log = opts.log ?? createLogger("Subagent"); + return spawnSubagent(role, phase, prompt, opts, log); +} + +// -- Planning workers -- + +export function spawnArchitect(opts: SpawnWorkOptions): Promise { + return spawnWork("architect", "plan-design", opts.initialPrompt ?? "Begin the plan-design phase.", opts); +} + +export function spawnDeveloper(opts: SpawnWorkOptions): Promise { + return spawnWork("developer", "plan-code", opts.initialPrompt ?? "Begin the plan-code phase.", opts); +} + +export function spawnTechnicalWriter(opts: SpawnWorkOptions): Promise { + return spawnWork("technical-writer", "plan-docs", opts.initialPrompt ?? "Begin the plan-docs phase.", opts); +} + +// -- Fix workers -- -export function spawnArchitect(opts: SpawnArchitectOptions): Promise { +export function spawnArchitectFix(opts: SpawnFixOptions): Promise { const log = opts.log ?? createLogger("Subagent"); return spawnSubagent( "architect", "plan-design", - opts.initialPrompt ?? "Begin the plan-design phase.", - opts, + "Fix the plan based on QR failures.", + { ...opts, extraFlags: ["--koan-fix", opts.fixPhase] }, log, ); } -export function spawnArchitectFix(opts: SpawnArchitectFixOptions): Promise { +export function spawnDeveloperFix(opts: SpawnFixOptions): Promise { const log = opts.log ?? createLogger("Subagent"); return spawnSubagent( - "architect", - "plan-design", - "Fix the plan based on QR failures.", + "developer", + "plan-code", + "Fix plan-code output based on QR failures.", + { ...opts, extraFlags: ["--koan-fix", opts.fixPhase] }, + log, + ); +} + +export function spawnTechnicalWriterFix(opts: SpawnFixOptions): Promise { + const log = opts.log ?? createLogger("Subagent"); + return spawnSubagent( + "technical-writer", + "plan-docs", + "Fix plan-docs output based on QR failures.", { ...opts, extraFlags: ["--koan-fix", opts.fixPhase] }, log, ); } -// -- QR spawners -- +// -- QR workers -- export function spawnQRDecomposer(opts: SpawnQRDecomposerOptions): Promise { const log = opts.log ?? createLogger("Subagent"); - return spawnSubagent("qr-decomposer", "qr-plan-design", "Begin the QR decompose phase.", opts, log); + return spawnSubagent("qr-decomposer", `qr-${opts.phase}`, "Begin the QR decompose phase.", opts, log); } export function spawnReviewer(opts: SpawnReviewerOptions): Promise { const log = opts.log ?? createLogger("Subagent"); return spawnSubagent( "reviewer", - "qr-plan-design", + `qr-${opts.phase}`, "Verify the assigned QR item.", { ...opts, extraFlags: ["--koan-qr-item", opts.itemId] }, log, From aebabbb51b0b1812acc47a0a5ec6d08dd01abe99 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Sat, 28 Feb 2026 09:10:09 +0700 Subject: [PATCH 028/412] docs: expand README with architecture and workflow overview --- README.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 10e3e1d..e8c4765 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,37 @@ # Koan Pi Package -This repository is structured as a [pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) package. +## Overview + +Koan is an opinionated planning workflow extension for the pi coding agent. It constrains model behavior with deterministic phase orchestration, explicit tool boundaries, and durable file-backed state so planning sessions are repeatable and auditable. + +## Architecture + +The runtime is split into two modes from the same extension entrypoint: + +- **Parent session mode** runs `/koan` commands and orchestrates the workflow. +- **Subagent mode** runs role/phase-specific workflows (architect, QR decomposer, reviewer, fix mode). + +The parent controls progression through context capture, plan design, quality review, and iterative fixes. Subagents are isolated processes that communicate through persisted artifacts (`plan.json`, `context.json`, `qr-*.json`) and audit projections. + +## Design Decisions + +Key design choices that shape implementation: + +- **Inversion of control**: TypeScript orchestration code drives agent behavior; models do not self-route workflow steps. +- **Tool-call-driven transitions**: step progression happens via `koan_complete_step` tool calls, not conversational chaining. +- **Default-deny permissions**: each phase explicitly allowlists tools; unknown tool/phase access is blocked. +- **Disk-backed mutations**: planning mutations are immediately persisted with atomic writes instead of deferred finalize steps. +- **Need-to-know prompts**: each subagent only receives the minimum context needed for its task. + +## Invariants + +The workflow depends on these invariants: + +- Planning phases must block direct `edit`/`write` tools. +- Tool failures must throw errors (not return soft error payloads). +- Cross-reference integrity in the plan must validate before progression. +- MUST-severity QR failures remain blocking even as lower-severity checks de-escalate in later fix iterations. + +## Boundaries + +Current scope focuses on planning and QR orchestration. `/koan execute` is intentionally not implemented yet. From c52ebf4a0501bb69275b01aee7bb782c7cc5e3ee Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 2 Mar 2026 13:41:28 +0700 Subject: [PATCH 029/412] refactor planner flow around koan_plan and conversation context --- extensions/koan.ts | 71 ++- src/planner/conversation.ts | 32 ++ src/planner/lib/audit.ts | 6 - src/planner/lib/conversation-trigger.ts | 60 +++ src/planner/lib/dispatch.ts | 9 +- src/planner/lib/permissions.ts | 1 - src/planner/model-config.ts | 102 +++++ src/planner/model-phase.ts | 63 +++ src/planner/model-resolver.ts | 33 ++ src/planner/phases/context-capture/phase.ts | 308 ------------- src/planner/phases/context-capture/prompts.ts | 92 ---- src/planner/phases/plan-code/phase.ts | 20 +- src/planner/phases/plan-code/prompts.ts | 11 +- src/planner/phases/plan-design/fix-phase.ts | 5 +- src/planner/phases/plan-design/fix-prompts.ts | 8 +- src/planner/phases/plan-design/phase.ts | 19 +- src/planner/phases/plan-design/prompts.ts | 27 +- src/planner/phases/plan-docs/fix-phase.ts | 5 +- src/planner/phases/plan-docs/fix-prompts.ts | 9 +- src/planner/phases/plan-docs/phase.ts | 19 +- src/planner/phases/plan-docs/prompts.ts | 18 +- src/planner/phases/qr-decompose/phase.ts | 17 +- src/planner/phases/qr-decompose/prompts.ts | 33 +- src/planner/phases/qr-verify/phase.ts | 15 +- src/planner/phases/qr-verify/prompts.ts | 39 +- src/planner/session.ts | 321 ++++++++------ src/planner/state.ts | 30 -- src/planner/subagent.ts | 33 +- src/planner/tools/context-store.ts | 34 -- src/planner/tools/workflow.ts | 30 +- src/planner/types.ts | 21 - src/planner/ui/config/menu.ts | 87 ++++ src/planner/ui/config/model-selection.ts | 410 ++++++++++++++++++ src/planner/ui/widget.ts | 4 +- 34 files changed, 1145 insertions(+), 847 deletions(-) create mode 100644 src/planner/conversation.ts create mode 100644 src/planner/lib/conversation-trigger.ts create mode 100644 src/planner/model-config.ts create mode 100644 src/planner/model-phase.ts create mode 100644 src/planner/model-resolver.ts delete mode 100644 src/planner/phases/context-capture/phase.ts delete mode 100644 src/planner/phases/context-capture/prompts.ts delete mode 100644 src/planner/tools/context-store.ts delete mode 100644 src/planner/types.ts create mode 100644 src/planner/ui/config/menu.ts create mode 100644 src/planner/ui/config/model-selection.ts diff --git a/extensions/koan.ts b/extensions/koan.ts index 613e8f3..369eac7 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -1,8 +1,10 @@ // Entry point for the koan pi extension. Serves dual roles: parent session -// (registers /koan command) and subagent mode (dispatches to phase workflow -// via CLI flags). All tools register unconditionally at init; phases restrict -// access via tool_call blocking at runtime. +// (registers koan_plan tool and /koan-execute, /koan-status, /koan commands) +// and subagent mode (dispatches to phase workflow via CLI flags). All tools +// register unconditionally at init; phases restrict access via tool_call +// blocking at runtime. +import { Type } from "@sinclair/typebox"; import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"; import { createSession } from "../src/planner/session.js"; @@ -10,6 +12,7 @@ import { detectSubagentMode, dispatchPhase } from "../src/planner/phases/dispatc import { registerAllTools, createDispatch, createPlanRef } from "../src/planner/tools/index.js"; import { createLogger } from "../src/utils/logger.js"; import { EventLog, extractToolEvent } from "../src/planner/lib/audit.js"; +import { openKoanConfig } from "../src/planner/ui/config/menu.js"; function currentModelId(ctx: ExtensionContext): string | null { const model = ctx.model; @@ -109,30 +112,50 @@ export default function koan(pi: ExtensionAPI): void { // Session: parent-mode workflow engine. const session = createSession(pi, dispatch, planRef); + pi.registerTool({ + name: "koan_plan", + label: "Plan", + description: [ + "Launch a structured planning pipeline for complex, multi-file tasks.", + "Invoke when the user asks to plan, use the planner, or when the task", + "is too large to implement directly.", + "", + "The current conversation is automatically captured — it becomes the", + "planning context. The pipeline spawns specialized agents (architect,", + "developer, writer) that read the conversation history to understand", + "the task, then produce a structured plan with milestones, code intents,", + "and quality review.", + "", + "This is a long-running operation (5-15 minutes). Do not invoke for", + "simple tasks that can be done in a single pass.", + ].join("\n"), + parameters: Type.Object({}), + async execute(toolCallId, params, signal, onUpdate, ctx) { + return await session.plan(ctx); + }, + }); + pi.registerCommand("koan", { - description: "Koan planning workflow", + description: "Koan commands. Usage: /koan config", handler: async (args, ctx) => { - const [subcommand, ...rest] = args.trim().split(/\s+/); - const command = subcommand ?? ""; - const remainingArgs = rest.join(" "); - - switch (command) { - case "plan": - await session.plan(remainingArgs, ctx); - break; - case "execute": - await session.execute(ctx); - break; - case "status": - await session.status(ctx); - break; - default: - ctx.ui.notify( - "Usage: /koan plan , /koan execute, or /koan status", - "error", - ); - break; + const subcommand = args.trim(); + if (subcommand === "config") { + await openKoanConfig(ctx); + } else if (subcommand === "") { + ctx.ui.notify("Usage: /koan config", "info"); + } else { + ctx.ui.notify(`Unknown koan subcommand: "${subcommand}". Usage: /koan config`, "warning"); } }, }); + + pi.registerCommand("koan-execute", { + description: "Execute a koan plan", + handler: async (_args, ctx) => { await session.execute(ctx); }, + }); + + pi.registerCommand("koan-status", { + description: "Show koan workflow status", + handler: async (_args, ctx) => { await session.status(ctx); }, + }); } diff --git a/src/planner/conversation.ts b/src/planner/conversation.ts new file mode 100644 index 0000000..86e9850 --- /dev/null +++ b/src/planner/conversation.ts @@ -0,0 +1,32 @@ +// Export the parent session conversation to a JSONL file in the plan directory. +// +// The output is raw pi SessionManager entries — NOT a plain-text transcript. +// Each line is a JSON object. Agents reading this file should look for entries +// with type "message" (role: "user" | "assistant") for conversation content, +// and type "compaction" for synthesized summaries of earlier context. +// The file is write-once and read-only from the perspective of planning phases. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { ExtensionContext } from "@mariozechner/pi-coding-agent"; + +/** + * Export the current conversation branch as a JSONL file. + * Each line is a JSON-serialized session entry (header first, then branch entries). + */ +export async function exportConversation( + sessionManager: ExtensionContext["sessionManager"], + planDir: string, +): Promise { + const filePath = path.join(planDir, "conversation.jsonl"); + const header = sessionManager.getHeader(); + const branch = sessionManager.getBranch(); + + const lines: string[] = []; + if (header) lines.push(JSON.stringify(header)); + for (const entry of branch) lines.push(JSON.stringify(entry)); + + await fs.writeFile(filePath, lines.join("\n") + "\n", "utf8"); + return filePath; +} diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index 94e9d39..1d2d670 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -443,12 +443,6 @@ const KOAN_SHAPES: Record = { koan_qr_get_item: { keys: ["phase", "id"], getter: true }, koan_qr_list_items: { keys: ["phase", "status"], getter: true }, koan_qr_summary: { keys: ["phase"], getter: true }, - - koan_store_context: { - keys: ["task_spec", "constraints", "entry_points", "rejected_alternatives", "current_understanding", "assumptions", "invisible_knowledge", "reference_docs"], - arrays: ["task_spec", "constraints", "entry_points", "rejected_alternatives", "current_understanding", "assumptions", "invisible_knowledge", "reference_docs"], - highValue: true, - }, }; // Reads the tail of events.jsonl and returns structured log entries. diff --git a/src/planner/lib/conversation-trigger.ts b/src/planner/lib/conversation-trigger.ts new file mode 100644 index 0000000..81bdf70 --- /dev/null +++ b/src/planner/lib/conversation-trigger.ts @@ -0,0 +1,60 @@ +export const PLAN_DESIGN_CONTEXT_TRIGGER_ID = "plan-design-context-trigger"; +export const PLAN_DOCS_CONTEXT_TRIGGER_ID = "plan-docs-context-trigger"; + +function exampleCommands(conversationPath: string, keywordRegex: string): string[] { + return [ + "Example commands (starting points; adapt as needed):", + ` CONV=\"${conversationPath}\"`, + " rg -n '\"role\":\"user\"|\"toolCall\"|koan_plan|phase|decision|constraint|tradeoff' \"$CONV\"", + " jq -cr 'select(.type==\"message\" and (.message.role==\"user\" or .message.role==\"assistant\")) | {ts:.timestamp, role:.message.role, text:([.message.content[]? | select(.type==\"text\") | .text] | join(\"\\n\"))} | select(.text != \"\")' \"$CONV\"", + ` jq -cr --arg re \"${keywordRegex}\" 'select(.type==\"message\") | {role:.message.role, texts:[.message.content[]? | select(.type==\"text\") | .text]} | .texts[]? as $t | select($t|test($re;\"i\")) | {role, text:$t}' \"$CONV\"`, + " jq -r 'select(.type==\"message\" and .message.role==\"assistant\") | .message.content[]? | select(.type==\"toolCall\" and .name==\"read\") | .arguments.path' \"$CONV\" | sort -u", + ]; +} + +export function buildPlanDesignContextTrigger(conversationPath: string): string[] { + return [ + "Use conversation context from the exact JSONL file path below.", + `Conversation file (absolute path): ${conversationPath}`, + "", + "This phase requires conversation grounding by default.", + "Before finalizing this step, open conversation.jsonl and extract:", + " - task intent and acceptance shape", + " - user constraints and preferences", + " - prior rejected options and decision rationale", + "", + "Read selectively (do not scan blindly end-to-end):", + " - prioritize type='message' with role='user'/'assistant'", + " - use type='compaction' entries for summarized earlier context", + "", + ...exampleCommands( + conversationPath, + "phase|planner|koan_plan|constraint|decision|tradeoff|acceptance", + ), + "", + "conversation.jsonl is read-only.", + ]; +} + +export function buildPlanDocsContextTrigger(conversationPath: string): string[] { + return [ + "Use conversation context from the exact JSONL file path below when needed.", + `Conversation file (absolute path): ${conversationPath}`, + "", + "Consult conversation.jsonl when plan artifacts do not fully explain:", + " - why a decision was made", + " - which tradeoff was accepted", + " - what implicit project knowledge should be documented", + " - how user preferences should affect docs emphasis", + "", + "Start from plan artifacts first; use conversation.jsonl to fill rationale gaps.", + "Read selectively (message + compaction entries), not exhaustively.", + "", + ...exampleCommands( + conversationPath, + "decision|tradeoff|why|constraint|docs|readme|diagram|comment|rationale", + ), + "", + "conversation.jsonl is read-only.", + ]; +} diff --git a/src/planner/lib/dispatch.ts b/src/planner/lib/dispatch.ts index cf8ec02..e9f935e 100644 --- a/src/planner/lib/dispatch.ts +++ b/src/planner/lib/dispatch.ts @@ -2,10 +2,6 @@ // Decouples static tool registration (init-time) from dynamic phase routing (runtime). // All mutable slots are null by default; phases hook/unhook on begin/end. -import type { ExtensionContext } from "@mariozechner/pi-coding-agent"; - -import type { ContextToolResult } from "../tools/context-store.js"; - // -- Result types -- export interface StepResult { @@ -18,13 +14,10 @@ export interface StepResult { export interface WorkflowDispatch { onCompleteStep: ((thoughts?: string) => StepResult | Promise) | null; - onStoreContext: - | ((payload: unknown, ctx: ExtensionContext) => Promise) - | null; } export function createDispatch(): WorkflowDispatch { - return { onCompleteStep: null, onStoreContext: null }; + return { onCompleteStep: null }; } // Decouples tool registration (init-time, before _buildRuntime) from diff --git a/src/planner/lib/permissions.ts b/src/planner/lib/permissions.ts index aee6f7f..a23faca 100644 --- a/src/planner/lib/permissions.ts +++ b/src/planner/lib/permissions.ts @@ -99,7 +99,6 @@ export const PLAN_MUTATION_TOOLS: ReadonlySet = new Set([ // updating the permissions map. export const PHASE_PERMISSIONS: ReadonlyMap> = new Map([ - ["context-capture", new Set(["koan_store_context", "koan_complete_step"])], [ "plan-design", new Set([ diff --git a/src/planner/model-config.ts b/src/planner/model-config.ts new file mode 100644 index 0000000..0f007cc --- /dev/null +++ b/src/planner/model-config.ts @@ -0,0 +1,102 @@ +// Koan config persistence for per-phase model overrides. +// Storage location: ~/.koan/config.json under a `phaseModels` key. +// Enforces all-or-none semantics: a stored config must contain exactly all +// 20 PhaseModelKeys. Partial configs are treated as absent and logged. + +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import { + ALL_PHASE_MODEL_KEYS, + isPhaseModelKey, + type PhaseModelKey, +} from "./model-phase.js"; + +export const KOAN_CONFIG_PATH = path.join(os.homedir(), ".koan", "config.json"); + +interface KoanConfigFile { + phaseModels?: Record; + [key: string]: unknown; +} + +export async function loadPhaseModelConfig(): Promise | null> { + let raw: string; + try { + raw = await fs.readFile(KOAN_CONFIG_PATH, "utf8"); + } catch { + return null; + } + + let parsed: KoanConfigFile; + try { + parsed = JSON.parse(raw) as KoanConfigFile; + } catch { + console.warn("[koan] config.json is not valid JSON; treating phase model config as absent."); + return null; + } + + if (!parsed.phaseModels || typeof parsed.phaseModels !== "object") { + return null; + } + + const phaseModels = parsed.phaseModels; + const keys = Object.keys(phaseModels); + + if (keys.length !== ALL_PHASE_MODEL_KEYS.length) { + console.warn( + `[koan] config.json phaseModels has ${keys.length} entries (expected ${ALL_PHASE_MODEL_KEYS.length}); treating as absent.`, + ); + return null; + } + + const result: Partial> = {}; + for (const key of keys) { + if (!isPhaseModelKey(key)) { + console.warn(`[koan] config.json phaseModels contains unknown key "${key}"; treating as absent.`); + return null; + } + const value = phaseModels[key]; + if (typeof value !== "string" || value.length === 0) { + console.warn( + `[koan] config.json phaseModels["${key}"] is not a non-empty string; treating as absent.`, + ); + return null; + } + result[key] = value; + } + + for (const expected of ALL_PHASE_MODEL_KEYS) { + if (!(expected in result)) { + console.warn(`[koan] config.json phaseModels is missing key "${expected}"; treating as absent.`); + return null; + } + } + + return result as Record; +} + +export async function savePhaseModelConfig( + config: Record | null, +): Promise { + const configDir = path.dirname(KOAN_CONFIG_PATH); + await fs.mkdir(configDir, { recursive: true }); + + let existing: KoanConfigFile = {}; + try { + const raw = await fs.readFile(KOAN_CONFIG_PATH, "utf8"); + existing = JSON.parse(raw) as KoanConfigFile; + } catch { + // Start fresh if file is missing or contains invalid JSON. + } + + if (config === null) { + delete existing.phaseModels; + } else { + existing.phaseModels = config as Record; + } + + const tmpPath = `${KOAN_CONFIG_PATH}.tmp`; + await fs.writeFile(tmpPath, `${JSON.stringify(existing, null, 2)}\n`, "utf8"); + await fs.rename(tmpPath, KOAN_CONFIG_PATH); +} diff --git a/src/planner/model-phase.ts b/src/planner/model-phase.ts new file mode 100644 index 0000000..b2319ca --- /dev/null +++ b/src/planner/model-phase.ts @@ -0,0 +1,63 @@ +// Canonical phase-model key definitions for koan per-phase model selection. +// Defines the 5×4 matrix of (phase row × sub-phase column) keys used across +// configuration, UI, and spawn-time resolution. + +export type PhaseRow = "plan-design" | "plan-code" | "plan-docs" | "exec-code" | "exec-docs"; +export type SubPhase = "exec-debut" | "exec-fix" | "qr-decompose" | "qr-verify"; +export type PhaseModelKey = `${PhaseRow}-${SubPhase}`; + +export const PHASE_ROWS: readonly PhaseRow[] = [ + "plan-design", + "plan-code", + "plan-docs", + "exec-code", + "exec-docs", +]; + +export const SUB_PHASES: readonly SubPhase[] = [ + "exec-debut", + "exec-fix", + "qr-decompose", + "qr-verify", +]; + +function computeAllKeys(): PhaseModelKey[] { + const keys: PhaseModelKey[] = []; + for (const row of PHASE_ROWS) { + for (const col of SUB_PHASES) { + keys.push(`${row}-${col}`); + } + } + return keys; +} + +export const ALL_PHASE_MODEL_KEYS: readonly PhaseModelKey[] = computeAllKeys(); + +const STRONG_KEY_SET: Set = new Set([ + // All qr-decompose keys (bias reasoning budget to verification) + "plan-design-qr-decompose", + "plan-code-qr-decompose", + "plan-docs-qr-decompose", + "exec-code-qr-decompose", + "exec-docs-qr-decompose", + // plan-design exec keys (ripple effects across later work) + "plan-design-exec-debut", + "plan-design-exec-fix", + // exec-docs exec keys (no mechanical correctness backstop) + "exec-docs-exec-debut", + "exec-docs-exec-fix", +]); + +export const STRONG_PHASE_MODEL_KEYS: ReadonlySet = STRONG_KEY_SET; + +export const GENERAL_PURPOSE_PHASE_MODEL_KEYS: readonly PhaseModelKey[] = + ALL_PHASE_MODEL_KEYS.filter((k) => !STRONG_KEY_SET.has(k)); + +export function isPhaseModelKey(value: unknown): value is PhaseModelKey { + if (typeof value !== "string") return false; + return (ALL_PHASE_MODEL_KEYS as readonly string[]).includes(value); +} + +export function buildPhaseModelKey(phaseRow: PhaseRow, subPhase: SubPhase): PhaseModelKey { + return `${phaseRow}-${subPhase}`; +} diff --git a/src/planner/model-resolver.ts b/src/planner/model-resolver.ts new file mode 100644 index 0000000..b67b371 --- /dev/null +++ b/src/planner/model-resolver.ts @@ -0,0 +1,33 @@ +// Spawn-time model resolver for per-phase model overrides. +// Maps spawn contexts to PhaseModelKeys and looks up configured overrides. +// Returns undefined when no config exists so the caller omits --model entirely, +// preserving pi's current active model as the implicit fallback. + +import { buildPhaseModelKey, type PhaseModelKey, type PhaseRow } from "./model-phase.js"; +import { loadPhaseModelConfig } from "./model-config.js"; + +export type SpawnContext = "work-debut" | "fix" | "qr-decompose" | "qr-verify"; + +export function mapSpawnContextToPhaseModelKey( + context: SpawnContext, + phaseRow: PhaseRow, + // Reserved for future fix-phase-specific routing. Current mapping is phase-row + context only. + _fixPhase?: string, +): PhaseModelKey { + switch (context) { + case "work-debut": + return buildPhaseModelKey(phaseRow, "exec-debut"); + case "fix": + return buildPhaseModelKey(phaseRow, "exec-fix"); + case "qr-decompose": + return buildPhaseModelKey(phaseRow, "qr-decompose"); + case "qr-verify": + return buildPhaseModelKey(phaseRow, "qr-verify"); + } +} + +export async function resolvePhaseModelOverride(key: PhaseModelKey): Promise { + const config = await loadPhaseModelConfig(); + if (config === null) return undefined; + return config[key]; +} diff --git a/src/planner/phases/context-capture/phase.ts b/src/planner/phases/context-capture/phase.ts deleted file mode 100644 index ecd4b94..0000000 --- a/src/planner/phases/context-capture/phase.ts +++ /dev/null @@ -1,308 +0,0 @@ -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"; - -import { - draftGuidance, - verifyGuidance, - refineGuidance, - type RefinePromptOptions, -} from "./prompts.js"; -import { formatStep } from "../../lib/step.js"; -import type { ContextCaptureState, PlanInfo, WorkflowState } from "../../state.js"; -import type { ContextData } from "../../types.js"; -import { CONTEXT_KEYS } from "../../types.js"; -import type { ContextToolResult } from "../../tools/context-store.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch } from "../../lib/dispatch.js"; -import { createLogger, type Logger } from "../../../utils/logger.js"; -import { checkPermission } from "../../lib/permissions.js"; - -const MAX_ATTEMPTS = 3; - -interface ValidationResult { - ok: boolean; - data?: ContextData; - errors: string[]; -} - -export class ContextCapturePhase { - private readonly state: WorkflowState; - private readonly pi: ExtensionAPI; - private readonly log: Logger; - private readonly dispatch: WorkflowDispatch; - private readonly onComplete?: (ctx: ExtensionContext) => Promise; - - constructor( - pi: ExtensionAPI, - state: WorkflowState, - dispatch: WorkflowDispatch, - log?: Logger, - onComplete?: (ctx: ExtensionContext) => Promise, - ) { - this.pi = pi; - this.state = state; - this.dispatch = dispatch; - this.log = log ?? createLogger("Context"); - this.onComplete = onComplete; - - this.registerHandlers(); - } - - async begin(taskDescription: string, plan: PlanInfo, ctx: ExtensionContext): Promise { - if (this.state.context?.active) { - ctx.ui.notify("Context capture is already in progress.", "warning"); - return; - } - - const contextFilePath = path.join(plan.directory, "context.json"); - await fs.rm(contextFilePath, { force: true }); - - this.state.phase = "context"; - this.state.context = { - active: true, - subPhase: "drafting", - attempt: 0, - maxAttempts: MAX_ATTEMPTS, - taskDescription, - planId: plan.id, - planDirectory: plan.directory, - contextFilePath, - lastPrompt: null, - feedback: [], - } satisfies ContextCaptureState; - - // Hook dispatch slots here (not constructor) because dispatch is - // shared with plan-design. Each phase hooks when activated (begin() - // for context-capture, begin() for plan-design). hookDispatch throws - // if the slot is already occupied (phase hook ownership prevents - // silent misrouting). - hookDispatch(this.dispatch, "onCompleteStep", () => this.handleSubPhaseComplete()); - hookDispatch(this.dispatch, "onStoreContext", (p, c) => this.handleContextToolCall(p, c)); - - this.log("Starting context capture (draft phase)", { planId: plan.id }); - - await this.updatePlanMetadata({ - status: "context", - context: { - expectedPath: contextFilePath, - startedAt: new Date().toISOString(), - }, - }); - - const prompt = formatStep(draftGuidance(taskDescription)); - this.state.context.lastPrompt = prompt; - this.pi.sendUserMessage(prompt); - } - - // Advances context capture sub-phase via tool call result. - // The returned prompt becomes the tool result text that the LLM - // processes within the same agent loop -- no sendUserMessage needed. - // Tool result delivery is synchronous regardless of -p mode. - private handleSubPhaseComplete(): { ok: boolean; prompt?: string; error?: string } { - const ctx = this.state.context; - if (!ctx || !this.shouldHandle()) { - return { ok: false, error: "Context capture is not active." }; - } - - if (ctx.subPhase === "drafting") { - ctx.subPhase = "verifying"; - const prompt = formatStep(verifyGuidance()); - ctx.lastPrompt = prompt; - this.log("Draft complete, transition to verify phase (tool call)"); - return { ok: true, prompt }; - } - - if (ctx.subPhase === "verifying") { - ctx.subPhase = "refining"; - ctx.attempt = 1; - const prompt = formatStep( - refineGuidance({ - attempt: 1, - maxAttempts: ctx.maxAttempts, - feedback: [], - }), - ); - ctx.lastPrompt = prompt; - this.log("Verify complete, transition to refine phase (tool call)"); - return { ok: true, prompt }; - } - - // Refine phase: koan_store_context handles completion, not this tool. - return { - ok: false, - error: "Refine phase: use koan_store_context to store the context.", - }; - } - - private registerHandlers(): void { - this.pi.on("tool_call", async (event) => { - if (!this.shouldHandle()) return; - - const perm = checkPermission("context-capture", event.toolName); - if (!perm.allowed) { - return { block: true, reason: perm.reason }; - } - - const ctx = this.state.context!; - - if (ctx.subPhase === "drafting") { - if (event.toolName === "koan_store_context") { - return { - block: true, - reason: "Draft phase: explore and draft first, then call koan_complete_step.", - }; - } - return undefined; - } - - if (ctx.subPhase === "verifying") { - if (event.toolName === "koan_complete_step") { - return undefined; - } - return { - block: true, - reason: "Verify phase: review your draft, then call koan_complete_step. No other tools.", - }; - } - - if (ctx.subPhase === "refining") { - if (event.toolName === "koan_store_context") { - return undefined; - } - return { - block: true, - reason: "Refine phase: call koan_store_context with the verified context.", - }; - } - - return undefined; - }); - } - - private shouldHandle(): boolean { - return Boolean(this.state.context?.active && this.state.phase === "context"); - } - - private async handleContextToolCall(payload: unknown, ctx: ExtensionContext): Promise { - if (!this.state.context || !this.shouldHandle()) { - return { - ok: false, - message: "Context capture is not active.", - errors: ["Context capture is not active."], - }; - } - - const validation = validateContextData(payload); - - if (!validation.ok || !validation.data) { - const errors = validation.errors.length > 0 ? validation.errors : ["Context validation failed."]; - this.state.context.feedback = errors; - this.log("Context validation failed", { errors }); - return { ok: false, message: formatErrors(errors), errors }; - } - - const rawText = JSON.stringify(payload, null, 2); - try { - await fs.writeFile(this.state.context.contextFilePath, `${rawText}\n`, "utf8"); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to write context file", { error: message }); - return { - ok: false, - message: `Failed to store context: ${message}`, - errors: [`Failed to store context: ${message}`], - }; - } - - this.state.context.active = false; - this.state.context.data = validation.data; - this.state.context.lastRawContent = rawText; - this.state.context.feedback = []; - this.state.phase = "context-complete"; - unhookDispatch(this.dispatch, "onCompleteStep"); - unhookDispatch(this.dispatch, "onStoreContext"); - - this.log("Context capture succeeded", { - planId: this.state.context.planId, - attempt: this.state.context.attempt, - }); - - await this.updatePlanMetadata({ - status: "context-complete", - context: { - capturedAt: new Date().toISOString(), - attempt: this.state.context.attempt, - file: this.state.context.contextFilePath, - }, - }); - - // Trigger completion callback (e.g. architect spawn) synchronously - // within the tool call. The tool blocks until the callback resolves, - // preventing the LLM from taking intermediate turns. - if (this.onComplete) { - const message = await this.onComplete(ctx); - return { ok: true, message }; - } - return { ok: true, message: "Context captured successfully." }; - } - - private async updatePlanMetadata(patch: Record): Promise { - const plan = this.state.plan; - if (!plan) return; - - try { - let current: Record = {}; - try { - const existing = await fs.readFile(plan.metadataPath, "utf8"); - current = JSON.parse(existing); - } catch { - current = { id: plan.id, createdAt: plan.createdAt }; - } - - const next = { ...current, ...patch }; - await fs.writeFile(plan.metadataPath, `${JSON.stringify(next, null, 2)}\n`, "utf8"); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to update plan metadata", { error: message }); - } - } -} - -function formatErrors(errors: string[]): string { - return `Context validation failed:\n${errors.map((e) => `- ${e}`).join("\n")}`; -} - -function validateContextData(value: unknown): ValidationResult { - if (typeof value !== "object" || value === null) { - return { ok: false, errors: ["Context data must be a JSON object."] }; - } - - const data = value as Record; - const errors: string[] = []; - const result: Record = {}; - - for (const key of CONTEXT_KEYS) { - const field = data[key]; - if (!Array.isArray(field)) { - errors.push(`${key} must be an array of strings.`); - continue; - } - if (field.length === 0) { - errors.push(`${key} must not be empty.`); - continue; - } - const bad = field.findIndex((item) => typeof item !== "string" || item.trim().length === 0); - if (bad !== -1) { - errors.push(`${key}[${bad}] must be a non-empty string.`); - continue; - } - result[key] = field.map((s: string) => s.trim()); - } - - if (errors.length > 0) { - return { ok: false, errors }; - } - - return { ok: true, data: result as unknown as ContextData, errors: [] }; -} diff --git a/src/planner/phases/context-capture/prompts.ts b/src/planner/phases/context-capture/prompts.ts deleted file mode 100644 index 575d801..0000000 --- a/src/planner/phases/context-capture/prompts.ts +++ /dev/null @@ -1,92 +0,0 @@ -import type { StepGuidance } from "../../lib/step.js"; - -export function draftGuidance(taskDescription: string): StepGuidance { - return { - title: "Context Capture: Draft", - instructions: [ - "You are about to begin a structured planning workflow. Before any formalization, think carefully through the full context of this task.", - "", - `Task: ${taskDescription}`, - "", - "Your primary source is the conversation so far. Most of what you need is already here.", - "", - "You MAY use tools during this phase if -- and only if -- a specific lookup would", - "resolve genuine uncertainty that materially affects planning. Examples of justified reads:", - "- Confirming an API signature you are unsure about", - "- Checking whether a file or module actually exists", - "- Reading a config that determines a key constraint", - "", - "Do NOT explore speculatively. If you can draft a confident answer from context alone, do so.", - "", - "Think through each of these dimensions:", - "", - "- What exactly is being asked? What is the user's goal? What is in scope and what is explicitly not?", - "- What technical constraints apply to the task itself -- API contracts, performance targets, compatibility requirements, architectural rules? Only include constraints that are specific to this task. Do not include general tool usage instructions, coding style guides, or editor/IDE conventions.", - "- Which files, modules, or entry points in the codebase are relevant? If this is greenfield work with no existing code, say so.", - "- Were any alternative approaches discussed and rejected during this session? Why?", - "- What is your current understanding of the system or domain involved?", - "- What assumptions are you making that haven't been verified? How confident are you in each?", - "- Is there any implicit design knowledge -- invariants, rationale, accepted tradeoffs -- that should be preserved for downstream work?", - "- Are there reference documents or specs in the project that apply?", - "", - "For each dimension, note your confidence:", - "- HIGH: you have direct evidence from this session", - "- LOW: you are extrapolating or guessing", - "", - "Flag any LOW-confidence point where a single targeted read would raise it to HIGH.", - "This is a working document, not a final artifact.", - "", - "Put your full draft analysis in the `thoughts` parameter when calling koan_complete_step.", - ], - }; -} - -export function verifyGuidance(): StepGuidance { - return { - title: "Context Capture: Verify", - instructions: [ - "Review the draft you just wrote. Check three things:", - "", - "1. Completeness: scan each dimension above. Is anything missing?", - "2. Accuracy: are any items wrong, speculative, or conflating things?", - "3. Phrasing: would a downstream agent understand without ambiguity?", - "", - "Rewrite the draft with corrections. If nothing needs changing, reproduce it as-is.", - "Do not use exploration tools during this review.", - "", - "Put your revised analysis in the `thoughts` parameter when calling koan_complete_step.", - ], - }; -} - -export interface RefinePromptOptions { - attempt: number; - maxAttempts: number; - feedback: string[]; -} - -export function refineGuidance(opts: RefinePromptOptions): StepGuidance { - const instructions: string[] = []; - if (opts.attempt > 1) { - instructions.push(`Retry (attempt ${opts.attempt} of ${opts.maxAttempts}).`); - } - instructions.push( - "Now call the `koan_store_context` tool with the verified context.", - "The tool's parameter schema defines exactly what fields are needed.", - ); - if (opts.feedback.length > 0) { - instructions.push("", "Address these issues from the previous attempt:"); - for (const item of opts.feedback) { - instructions.push(`- ${item}`); - } - } - return { - title: "Context Capture: Refine", - instructions, - // Refine completes with koan_store_context, not koan_complete_step. - invokeAfter: [ - "WHEN DONE: After completing the instructions above, call koan_store_context with the verified context data.", - "Do NOT call this tool until you have prepared the structured context.", - ].join("\n"), - }; -} diff --git a/src/planner/phases/plan-code/phase.ts b/src/planner/phases/plan-code/phase.ts index f4948b2..ab2b9e4 100644 --- a/src/planner/phases/plan-code/phase.ts +++ b/src/planner/phases/plan-code/phase.ts @@ -1,21 +1,16 @@ // Plan-code phase -- 4-step developer workflow converting code intents // to concrete code_changes diffs in plan.json. -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; import { loadPlanCodeSystemPrompt, - formatContextForStep1, buildPlanCodeSystemPrompt, planCodeStepGuidance, STEP_NAMES, } from "./prompts.js"; import { formatStep } from "../../lib/step.js"; -import type { ContextData } from "../../types.js"; import { createLogger, type Logger } from "../../../utils/logger.js"; import { EventLog } from "../../lib/audit.js"; import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; @@ -27,7 +22,6 @@ interface PlanCodeState { active: boolean; step: PlanCodeStep; step1Prompt: string | null; - contextData: ContextData | null; systemPrompt: string | null; } @@ -62,7 +56,6 @@ export class PlanCodePhase { active: false, step: 1, step1Prompt: null, - contextData: null, systemPrompt: null, }; @@ -70,16 +63,6 @@ export class PlanCodePhase { } async begin(): Promise { - const contextPath = path.join(this.planDir, "context.json"); - try { - const raw = await fs.readFile(contextPath, "utf8"); - this.state.contextData = JSON.parse(raw) as ContextData; - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to read context.json", { error: message }); - return; - } - let basePrompt: string; try { basePrompt = await loadPlanCodeSystemPrompt(); @@ -89,9 +72,8 @@ export class PlanCodePhase { return; } - const contextXml = formatContextForStep1(this.state.contextData); this.state.systemPrompt = buildPlanCodeSystemPrompt(basePrompt); - this.state.step1Prompt = formatStep(planCodeStepGuidance(1, contextXml)); + this.state.step1Prompt = formatStep(planCodeStepGuidance(1)); this.state.active = true; this.state.step = 1; this.planRef.dir = this.planDir; diff --git a/src/planner/phases/plan-code/prompts.ts b/src/planner/phases/plan-code/prompts.ts index 782ce4c..0aaab34 100644 --- a/src/planner/phases/plan-code/prompts.ts +++ b/src/planner/phases/plan-code/prompts.ts @@ -2,7 +2,6 @@ import { promises as fs } from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; -import type { ContextData } from "../../types.js"; import type { StepGuidance } from "../../lib/step.js"; export const STEP_NAMES: Record<1 | 2 | 3 | 4, string> = { @@ -22,10 +21,6 @@ export async function loadPlanCodeSystemPrompt(): Promise { } } -export function formatContextForStep1(ctx: ContextData): string { - return ["", JSON.stringify(ctx, null, 2), ""].join("\n"); -} - export function buildPlanCodeSystemPrompt(basePrompt: string): string { return [ basePrompt, @@ -47,16 +42,12 @@ export function buildPlanCodeSystemPrompt(basePrompt: string): string { ].join("\n"); } -export function planCodeStepGuidance(step: 1 | 2 | 3 | 4, context?: string): StepGuidance { +export function planCodeStepGuidance(step: 1 | 2 | 3 | 4): StepGuidance { switch (step) { case 1: return { title: "Step 1: Intent Coverage Analysis", instructions: [ - "PLANNING CONTEXT (from session):", - "", - context ?? "", - "", "Use koan_get_plan to inspect milestones and code_intents.", "Build a checklist of intents that need code_changes.", "Record target files and affected functions per intent.", diff --git a/src/planner/phases/plan-design/fix-phase.ts b/src/planner/phases/plan-design/fix-phase.ts index 24b5cc8..664f0ba 100644 --- a/src/planner/phases/plan-design/fix-phase.ts +++ b/src/planner/phases/plan-design/fix-phase.ts @@ -16,6 +16,8 @@ // orchestrator decides whether to re-run QR -- the fix phase does not // know about iterations or severity escalation. +import * as path from "node:path"; + import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { loadAndValidatePlan } from "../../plan/validate.js"; @@ -105,8 +107,9 @@ export class PlanDesignFixPhase { this.failures.length, totalSteps, ); + const conversationPath = path.join(this.planDir, "conversation.jsonl"); this.state.step1Prompt = formatStep( - fixStepGuidance(1, totalSteps, { allFailuresXml: failuresXml }), + fixStepGuidance(1, totalSteps, { allFailuresXml: failuresXml, conversationPath }), ); this.state.active = true; this.state.step = 1; diff --git a/src/planner/phases/plan-design/fix-prompts.ts b/src/planner/phases/plan-design/fix-prompts.ts index 8d12cc8..d9ec61e 100644 --- a/src/planner/phases/plan-design/fix-prompts.ts +++ b/src/planner/phases/plan-design/fix-prompts.ts @@ -11,6 +11,7 @@ import type { QRItem } from "../../qr/types.js"; import type { StepGuidance } from "../../lib/step.js"; +import { buildPlanDesignContextTrigger } from "../../lib/conversation-trigger.js"; // Serializes FAIL items as an XML block injected into the step 1 prompt. // XML structure mirrors how pi-native tools present structured data. @@ -83,10 +84,10 @@ export function buildFixSystemPrompt( export function fixStepGuidance( step: number, totalSteps: number, - opts?: { item?: QRItem; allFailuresXml?: string }, + opts?: { item?: QRItem; allFailuresXml?: string; conversationPath?: string }, ): StepGuidance { if (step === 1) - return fixStep1Guidance(totalSteps, opts?.allFailuresXml ?? ""); + return fixStep1Guidance(totalSteps, opts?.allFailuresXml ?? "", opts?.conversationPath); if (step === totalSteps) return fixFinalStepGuidance(totalSteps); return fixItemStepGuidance(step, totalSteps, opts?.item); } @@ -98,6 +99,7 @@ export function fixStepGuidance( function fixStep1Guidance( totalSteps: number, failuresXml: string, + conversationPath?: string, ): StepGuidance { const itemCount = totalSteps - 2; return { @@ -107,6 +109,8 @@ function fixStep1Guidance( "", failuresXml, "", + ...buildPlanDesignContextTrigger(conversationPath ?? "/conversation.jsonl"), + "", `There are ${itemCount} failure(s). You will fix them one at a time`, `in steps 2 through ${totalSteps - 1}. Each step presents a single item.`, "", diff --git a/src/planner/phases/plan-design/phase.ts b/src/planner/phases/plan-design/phase.ts index f581e11..470f14e 100644 --- a/src/planner/phases/plan-design/phase.ts +++ b/src/planner/phases/plan-design/phase.ts @@ -2,7 +2,6 @@ // from captured context. Step gate: mutation tools blocked before step 6 // (blocklist pattern). Validation runs at step-6 completion. -import { promises as fs } from "node:fs"; import * as path from "node:path"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; @@ -10,13 +9,11 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { loadAndValidatePlan } from "../../plan/validate.js"; import { loadPlanDesignSystemPrompt, - formatContextForStep1, buildPlanDesignSystemPrompt, planDesignStepGuidance, STEP_NAMES, } from "./prompts.js"; import { formatStep } from "../../lib/step.js"; -import type { ContextData } from "../../types.js"; import { createLogger, type Logger } from "../../../utils/logger.js"; import { EventLog } from "../../lib/audit.js"; import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; @@ -28,7 +25,6 @@ interface PlanDesignState { active: boolean; step: PlanDesignStep; step1Prompt: string | null; - contextData: ContextData | null; systemPrompt: string | null; } @@ -62,7 +58,6 @@ export class PlanDesignPhase { active: false, step: 1, step1Prompt: null, - contextData: null, systemPrompt: null, }; @@ -70,16 +65,6 @@ export class PlanDesignPhase { } async begin(): Promise { - const contextPath = path.join(this.planDir, "context.json"); - try { - const raw = await fs.readFile(contextPath, "utf8"); - this.state.contextData = JSON.parse(raw) as ContextData; - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to read context.json", { error: message }); - return; - } - let basePrompt: string; try { basePrompt = await loadPlanDesignSystemPrompt(); @@ -89,9 +74,9 @@ export class PlanDesignPhase { return; } - const contextXml = formatContextForStep1(this.state.contextData); this.state.systemPrompt = buildPlanDesignSystemPrompt(basePrompt); - this.state.step1Prompt = formatStep(planDesignStepGuidance(1, contextXml)); + const conversationPath = path.join(this.planDir, "conversation.jsonl"); + this.state.step1Prompt = formatStep(planDesignStepGuidance(1, conversationPath)); this.state.active = true; this.state.step = 1; diff --git a/src/planner/phases/plan-design/prompts.ts b/src/planner/phases/plan-design/prompts.ts index 2f5727e..928a102 100644 --- a/src/planner/phases/plan-design/prompts.ts +++ b/src/planner/phases/plan-design/prompts.ts @@ -2,8 +2,8 @@ import { promises as fs } from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; -import type { ContextData } from "../../types.js"; import type { StepGuidance } from "../../lib/step.js"; +import { buildPlanDesignContextTrigger } from "../../lib/conversation-trigger.js"; export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { 1: "Task Analysis & Exploration Planning", @@ -26,14 +26,6 @@ export async function loadPlanDesignSystemPrompt(): Promise { } } -export function formatContextForStep1(ctx: ContextData): string { - return [ - "", - JSON.stringify(ctx, null, 2), - "", - ].join("\n"); -} - export function buildPlanDesignSystemPrompt(basePrompt: string): string { return [ basePrompt, @@ -54,17 +46,18 @@ export function buildPlanDesignSystemPrompt(basePrompt: string): string { ].join("\n"); } -export function planDesignStepGuidance(step: 1 | 2 | 3 | 4 | 5 | 6, context?: string): StepGuidance { +export function planDesignStepGuidance( + step: 1 | 2 | 3 | 4 | 5 | 6, + conversationPath?: string, +): StepGuidance { switch (step) { case 1: return { title: "Step 1: Task Analysis & Exploration Planning", instructions: [ - "PLANNING CONTEXT (from session):", - "", - context ?? "", + ...buildPlanDesignContextTrigger(conversationPath ?? "/conversation.jsonl"), "", - "Parse the user's task description. Identify:", + "After absorbing the task intent, identify:", " - What needs to change (files, modules, behavior)", " - What exploration is needed (patterns, constraints, existing code)", " - What directories/files are relevant", @@ -72,12 +65,6 @@ export function planDesignStepGuidance(step: 1 | 2 | 3 | 4 | 5 | 6, context?: st "Read project context files to understand structure:", " - Project root CLAUDE.md", " - Subdirectory CLAUDE.md files in relevant areas", - " - All paths in context.json reference_docs field (if any)", - "", - "CONTEXT.JSON CONTRACT: READ-ONLY.", - " - context.json is owned by the session", - " - You MUST NOT write, modify, or append to context.json", - " - Your outputs go to plan.json (step 6) -- never context.json", "", "DO NOT write any files yet. Gather understanding for step 2.", "Record your analysis mentally for use in subsequent steps.", diff --git a/src/planner/phases/plan-docs/fix-phase.ts b/src/planner/phases/plan-docs/fix-phase.ts index e757461..dcbc15f 100644 --- a/src/planner/phases/plan-docs/fix-phase.ts +++ b/src/planner/phases/plan-docs/fix-phase.ts @@ -1,5 +1,7 @@ // Plan-docs fix phase -- dynamic targeted QR repair workflow. +import * as path from "node:path"; + import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; @@ -81,7 +83,8 @@ export class PlanDocsFixPhase { this.failures.length, totalSteps, ); - this.state.step1Prompt = formatStep(fixStepGuidance(1, totalSteps, { allFailuresXml: failuresXml })); + const conversationPath = path.join(this.planDir, "conversation.jsonl"); + this.state.step1Prompt = formatStep(fixStepGuidance(1, totalSteps, { allFailuresXml: failuresXml, conversationPath })); this.state.active = true; this.state.step = 1; this.planRef.dir = this.planDir; diff --git a/src/planner/phases/plan-docs/fix-prompts.ts b/src/planner/phases/plan-docs/fix-prompts.ts index 90da4a0..5ae245c 100644 --- a/src/planner/phases/plan-docs/fix-prompts.ts +++ b/src/planner/phases/plan-docs/fix-prompts.ts @@ -1,5 +1,6 @@ import type { QRItem } from "../../qr/types.js"; import type { StepGuidance } from "../../lib/step.js"; +import { buildPlanDocsContextTrigger } from "../../lib/conversation-trigger.js"; export function formatFailuresXml(failures: ReadonlyArray): string { const items = failures @@ -39,7 +40,7 @@ export function buildFixSystemPrompt(basePrompt: string, failureCount: number, t ].join("\n"); } -function step1(totalSteps: number, failuresXml: string): StepGuidance { +function step1(totalSteps: number, failuresXml: string, conversationPath?: string): StepGuidance { const itemCount = totalSteps - 2; return { title: `Step 1/${totalSteps}: Understand QR Failures`, @@ -48,6 +49,8 @@ function step1(totalSteps: number, failuresXml: string): StepGuidance { "", failuresXml, "", + ...buildPlanDocsContextTrigger(conversationPath ?? "/conversation.jsonl"), + "", `There are ${itemCount} item(s). You will fix them one by one in steps 2-${totalSteps - 1}.`, "Inspect current docs state via koan_get_plan / koan_get_change.", "Identify exact correction needed per item.", @@ -95,9 +98,9 @@ function finalStep(totalSteps: number): StepGuidance { export function fixStepGuidance( step: number, totalSteps: number, - opts?: { item?: QRItem; allFailuresXml?: string }, + opts?: { item?: QRItem; allFailuresXml?: string; conversationPath?: string }, ): StepGuidance { - if (step === 1) return step1(totalSteps, opts?.allFailuresXml ?? ""); + if (step === 1) return step1(totalSteps, opts?.allFailuresXml ?? "", opts?.conversationPath); if (step === totalSteps) return finalStep(totalSteps); return itemStep(step, totalSteps, opts?.item); } diff --git a/src/planner/phases/plan-docs/phase.ts b/src/planner/phases/plan-docs/phase.ts index f8fec6c..24970ce 100644 --- a/src/planner/phases/plan-docs/phase.ts +++ b/src/planner/phases/plan-docs/phase.ts @@ -1,7 +1,6 @@ // Plan-docs phase -- 6-step technical writer workflow producing doc artifacts // (doc_diff/comments/diagram/readme) in plan.json. -import { promises as fs } from "node:fs"; import * as path from "node:path"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; @@ -9,13 +8,11 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; import { loadPlanDocsSystemPrompt, - formatContextForStep1, buildPlanDocsSystemPrompt, planDocsStepGuidance, STEP_NAMES, } from "./prompts.js"; import { formatStep } from "../../lib/step.js"; -import type { ContextData } from "../../types.js"; import { createLogger, type Logger } from "../../../utils/logger.js"; import { EventLog } from "../../lib/audit.js"; import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; @@ -27,7 +24,6 @@ interface PlanDocsState { active: boolean; step: PlanDocsStep; step1Prompt: string | null; - contextData: ContextData | null; systemPrompt: string | null; } @@ -62,7 +58,6 @@ export class PlanDocsPhase { active: false, step: 1, step1Prompt: null, - contextData: null, systemPrompt: null, }; @@ -70,16 +65,6 @@ export class PlanDocsPhase { } async begin(): Promise { - const contextPath = path.join(this.planDir, "context.json"); - try { - const raw = await fs.readFile(contextPath, "utf8"); - this.state.contextData = JSON.parse(raw) as ContextData; - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to read context.json", { error: message }); - return; - } - let basePrompt: string; try { basePrompt = await loadPlanDocsSystemPrompt(); @@ -89,9 +74,9 @@ export class PlanDocsPhase { return; } - const contextXml = formatContextForStep1(this.state.contextData); this.state.systemPrompt = buildPlanDocsSystemPrompt(basePrompt); - this.state.step1Prompt = formatStep(planDocsStepGuidance(1, contextXml)); + const conversationPath = path.join(this.planDir, "conversation.jsonl"); + this.state.step1Prompt = formatStep(planDocsStepGuidance(1, conversationPath)); this.state.active = true; this.state.step = 1; this.planRef.dir = this.planDir; diff --git a/src/planner/phases/plan-docs/prompts.ts b/src/planner/phases/plan-docs/prompts.ts index e27b58e..081f08a 100644 --- a/src/planner/phases/plan-docs/prompts.ts +++ b/src/planner/phases/plan-docs/prompts.ts @@ -2,8 +2,8 @@ import { promises as fs } from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; -import type { ContextData } from "../../types.js"; import type { StepGuidance } from "../../lib/step.js"; +import { buildPlanDocsContextTrigger } from "../../lib/conversation-trigger.js"; export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { 1: "Extract Documentation Context", @@ -24,10 +24,6 @@ export async function loadPlanDocsSystemPrompt(): Promise { } } -export function formatContextForStep1(ctx: ContextData): string { - return ["", JSON.stringify(ctx, null, 2), ""].join("\n"); -} - export function buildPlanDocsSystemPrompt(basePrompt: string): string { return [ basePrompt, @@ -50,18 +46,20 @@ export function buildPlanDocsSystemPrompt(basePrompt: string): string { ].join("\n"); } -export function planDocsStepGuidance(step: 1 | 2 | 3 | 4 | 5 | 6, context?: string): StepGuidance { +export function planDocsStepGuidance( + step: 1 | 2 | 3 | 4 | 5 | 6, + conversationPath?: string, +): StepGuidance { switch (step) { case 1: return { title: "Step 1: Extract Documentation Context", instructions: [ - "PLANNING CONTEXT (from session):", - "", - context ?? "", - "", "Use koan_get_plan to review decisions, constraints, risks, and milestones.", "Capture decision IDs that should be reflected in documentation rationale.", + "", + ...buildPlanDocsContextTrigger(conversationPath ?? "/conversation.jsonl"), + "", "This step is read-only.", ], }; diff --git a/src/planner/phases/qr-decompose/phase.ts b/src/planner/phases/qr-decompose/phase.ts index 309dba5..6f2e0b5 100644 --- a/src/planner/phases/qr-decompose/phase.ts +++ b/src/planner/phases/qr-decompose/phase.ts @@ -9,7 +9,6 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { loadQRDecomposeSystemPrompt, - formatContextForDecompose, buildDecomposeSystemPrompt, decomposeStepGuidance, DECOMPOSE_STEP_NAMES, @@ -17,7 +16,6 @@ import { type WorkPhaseKey, } from "./prompts.js"; import { formatStep } from "../../lib/step.js"; -import type { ContextData } from "../../types.js"; import { createLogger, type Logger } from "../../../utils/logger.js"; import { EventLog } from "../../lib/audit.js"; import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; @@ -76,17 +74,6 @@ export class QRDecomposePhase { } async begin(): Promise { - const contextPath = path.join(this.planDir, "context.json"); - let contextData: ContextData; - try { - const raw = await fs.readFile(contextPath, "utf8"); - contextData = JSON.parse(raw) as ContextData; - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to read context.json", { error: message }); - return; - } - let basePrompt: string; try { basePrompt = await loadQRDecomposeSystemPrompt(); @@ -96,9 +83,9 @@ export class QRDecomposePhase { return; } - const contextXml = formatContextForDecompose(contextData); this.state.systemPrompt = buildDecomposeSystemPrompt(basePrompt, this.workPhase); - this.state.step1Prompt = formatStep(decomposeStepGuidance(1, this.workPhase, contextXml)); + const conversationPath = path.join(this.planDir, "conversation.jsonl"); + this.state.step1Prompt = formatStep(decomposeStepGuidance(1, this.workPhase, conversationPath)); this.state.active = true; this.state.step = 1; this.planRef.dir = this.planDir; diff --git a/src/planner/phases/qr-decompose/prompts.ts b/src/planner/phases/qr-decompose/prompts.ts index 474f22f..e66c9d1 100644 --- a/src/planner/phases/qr-decompose/prompts.ts +++ b/src/planner/phases/qr-decompose/prompts.ts @@ -6,8 +6,11 @@ import { promises as fs } from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; -import type { ContextData } from "../../types.js"; import type { StepGuidance } from "../../lib/step.js"; +import { + buildPlanDesignContextTrigger, + buildPlanDocsContextTrigger, +} from "../../lib/conversation-trigger.js"; export type DecomposeStep = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13; export type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; @@ -46,6 +49,19 @@ const PHASE_SCOPE_HINTS: Record = { ], }; +function phaseContextTrigger( + phase: WorkPhaseKey, + conversationPath?: string, +): string[] { + if (phase === "plan-design") { + return buildPlanDesignContextTrigger(conversationPath ?? "/conversation.jsonl"); + } + if (phase === "plan-docs") { + return buildPlanDocsContextTrigger(conversationPath ?? "/conversation.jsonl"); + } + return []; +} + export async function loadQRDecomposeSystemPrompt(): Promise { const homeDir = os.homedir(); const promptPath = path.join(homeDir, ".claude/agents/quality-reviewer.md"); @@ -77,21 +93,20 @@ export function buildDecomposeSystemPrompt(basePrompt: string, phase: WorkPhaseK ].join("\n"); } -export function formatContextForDecompose(ctx: ContextData): string { - return ["", JSON.stringify(ctx, null, 2), ""].join("\n"); -} - -export function decomposeStepGuidance(step: DecomposeStep, phase: WorkPhaseKey, context?: string): StepGuidance { +export function decomposeStepGuidance( + step: DecomposeStep, + phase: WorkPhaseKey, + conversationPath?: string, +): StepGuidance { switch (step) { case 1: return { title: "Step 1: Absorb Context", instructions: [ `PHASE: ${phase}`, - "PLANNING CONTEXT (from session):", - "", - context ?? "", "", + ...phaseContextTrigger(phase, conversationPath), + ...(phase === "plan-code" ? [] : [""]), "Use koan_get_plan to read the full plan.", "Absorb the structures relevant to this phase and identify what needs verification.", ], diff --git a/src/planner/phases/qr-verify/phase.ts b/src/planner/phases/qr-verify/phase.ts index 623b9f6..185fb97 100644 --- a/src/planner/phases/qr-verify/phase.ts +++ b/src/planner/phases/qr-verify/phase.ts @@ -7,7 +7,6 @@ import * as path from "node:path"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { formatStep } from "../../lib/step.js"; -import type { ContextData } from "../../types.js"; import { createLogger, type Logger } from "../../../utils/logger.js"; import { EventLog } from "../../lib/audit.js"; import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; @@ -88,17 +87,6 @@ export class QRVerifyPhase { return; } - const contextPath = path.join(this.planDir, "context.json"); - let contextData: ContextData; - try { - const raw = await fs.readFile(contextPath, "utf8"); - contextData = JSON.parse(raw) as ContextData; - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to read context.json", { error: message }); - return; - } - const qrPath = path.join(this.planDir, `qr-${this.workPhase}.json`); let qrFile: QRFile; try { @@ -127,7 +115,8 @@ export class QRVerifyPhase { } this.state.systemPrompt = buildVerifySystemPrompt(basePrompt, this.workPhase); - this.state.step1Prompt = formatStep(buildContextStep(item, contextData, this.workPhase)); + const conversationPath = path.join(this.planDir, "conversation.jsonl"); + this.state.step1Prompt = formatStep(buildContextStep(item, this.workPhase, conversationPath)); this.state.active = true; this.state.step = 1; this.planRef.dir = this.planDir; diff --git a/src/planner/phases/qr-verify/prompts.ts b/src/planner/phases/qr-verify/prompts.ts index a364490..38fcbe7 100644 --- a/src/planner/phases/qr-verify/prompts.ts +++ b/src/planner/phases/qr-verify/prompts.ts @@ -5,24 +5,17 @@ import { promises as fs } from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; -import type { ContextData } from "../../types.js"; import type { QRItem } from "../../qr/types.js"; import type { StepGuidance } from "../../lib/step.js"; +import { + buildPlanDesignContextTrigger, + buildPlanDocsContextTrigger, +} from "../../lib/conversation-trigger.js"; type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; export type VerifyStep = 1 | 2 | 3; -function formatContextXml(ctx: ContextData): string { - const fields = Object.entries(ctx) - .map(([key, values]) => { - const items = (values as string[]).map((v) => ` ${v}`).join("\n"); - return ` <${key}>\n${items}\n `; - }) - .join("\n"); - return `\n${fields}\n`; -} - function scopeGuidance(item: QRItem): string { const s = item.scope; if (s === "*") { @@ -47,6 +40,19 @@ function scopeGuidance(item: QRItem): string { return "SCOPED CHECK -- Read the relevant section using plan getter tools."; } +function phaseContextTrigger( + phase: WorkPhaseKey, + conversationPath?: string, +): string[] { + if (phase === "plan-design") { + return buildPlanDesignContextTrigger(conversationPath ?? "/conversation.jsonl"); + } + if (phase === "plan-docs") { + return buildPlanDocsContextTrigger(conversationPath ?? "/conversation.jsonl"); + } + return []; +} + export async function loadQRVerifySystemPrompt(): Promise { const promptPath = path.join(os.homedir(), ".claude/agents/quality-reviewer.md"); try { @@ -75,7 +81,11 @@ export function buildVerifySystemPrompt(basePrompt: string, phase: WorkPhaseKey) ].join("\n"); } -export function buildContextStep(item: QRItem, contextData: ContextData, phase: WorkPhaseKey): StepGuidance { +export function buildContextStep( + item: QRItem, + phase: WorkPhaseKey, + conversationPath?: string, +): StepGuidance { return { title: "Step 1: CONTEXT", instructions: [ @@ -89,9 +99,8 @@ export function buildContextStep(item: QRItem, contextData: ContextData, phase: ` ${item.severity}`, "", "", - "PLANNING CONTEXT (reference for semantic validation):", - formatContextXml(contextData), - "", + ...phaseContextTrigger(phase, conversationPath), + ...(phase === "plan-code" ? [] : [""]), "Understand the check and required evidence before analyzing.", ], }; diff --git a/src/planner/session.ts b/src/planner/session.ts index f48f65f..b555d5c 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -1,13 +1,13 @@ // Parent session: orchestrates the koan planning workflow. -// Flow: context capture -> plan-design(+QR) -> plan-code(+QR) -> plan-docs(+QR) +// Flow: export conversation -> plan-design(+QR) -> plan-code(+QR) -> plan-docs(+QR) // -> mechanical plan.json->plan.md rendering for manual review. import { promises as fs } from "node:fs"; import * as path from "node:path"; -import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent"; +import type { AgentToolResult, ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent"; -import { ContextCapturePhase } from "./phases/context-capture/phase.js"; +import { exportConversation } from "./conversation.js"; import { createInitialState, initializePlanState, type WorkflowState } from "./state.js"; import { createPlanInfo } from "../utils/plan.js"; import { @@ -19,6 +19,8 @@ import { spawnTechnicalWriterFix, spawnQRDecomposer, spawnReviewer, + type SpawnQRDecomposerOptions, + type SpawnReviewerOptions, type SubagentResult, } from "./subagent.js"; import { createLogger, setLogDir, type Logger } from "../utils/logger.js"; @@ -30,11 +32,17 @@ import type { QRFile } from "./qr/types.js"; import { MAX_FIX_ITERATIONS, qrPassesAtIteration } from "./qr/severity.js"; import { WidgetController, type WidgetUpdate } from "./ui/widget.js"; import { renderPlanMarkdownToFile } from "./plan/render.js"; +import { + mapSpawnContextToPhaseModelKey, + resolvePhaseModelOverride, + type SpawnContext, +} from "./model-resolver.js"; +import type { PhaseRow } from "./model-phase.js"; type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; interface Session { - plan(args: string, ctx: ExtensionCommandContext): Promise; + plan(ctx: ExtensionContext): Promise>; execute(_ctx: ExtensionCommandContext): Promise; status(ctx: ExtensionCommandContext): Promise; } @@ -59,6 +67,7 @@ interface SpawnWorkRunOptions { cwd: string; extensionPath: string; log: Logger; + modelOverride?: string; } interface SpawnFixRunOptions extends SpawnWorkRunOptions {} @@ -101,133 +110,81 @@ function phaseCompleteState(phase: WorkPhaseKey): WorkflowState["phase"] { return "plan-docs-complete"; } -export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, planRef: PlanRef): Session { - const state: WorkflowState = createInitialState(); - const log = createLogger("Session"); - let widget: WidgetController | null = null; - - const onContextComplete = async (ctx: ExtensionContext): Promise => { - if (!state.plan) { - return "Context captured but no plan state available."; - } - - let outcome: "PASS" | "FAIL" = "FAIL"; +interface ModelResolutionDeps { + mapSpawnContextToPhaseModelKeyFn?: typeof mapSpawnContextToPhaseModelKey; + resolvePhaseModelOverrideFn?: typeof resolvePhaseModelOverride; +} - try { - const planDir = state.plan.directory; - const extensionPath = path.resolve(import.meta.dirname, "../../extensions/koan.ts"); - - const phases: PhaseRunConfig[] = [ - { - key: "plan-design", - label: "Plan design", - widgetIndex: 1, - role: "architect", - spawnWork: (opts) => spawnArchitect(opts), - spawnFix: (opts) => spawnArchitectFix({ ...opts, fixPhase: "plan-design" }), - }, - { - key: "plan-code", - label: "Plan code", - widgetIndex: 2, - role: "developer", - spawnWork: (opts) => spawnDeveloper(opts), - spawnFix: (opts) => spawnDeveloperFix({ ...opts, fixPhase: "plan-code" }), - }, - { - key: "plan-docs", - label: "Plan docs", - widgetIndex: 3, - role: "technical-writer", - spawnWork: (opts) => spawnTechnicalWriter(opts), - spawnFix: (opts) => spawnTechnicalWriterFix({ ...opts, fixPhase: "plan-docs" }), - }, - ]; +interface QRSpawnResolutionDeps extends ModelResolutionDeps { + spawnQRDecomposerFn?: typeof spawnQRDecomposer; + spawnReviewerFn?: typeof spawnReviewer; +} - widget?.update({ - phaseStatus: { index: 0, status: "completed" }, - activeIndex: 1, - step: "context captured; starting planning phases...", - activity: "", - }); +export async function resolveSpawnModelOverride( + context: SpawnContext, + phaseRow: PhaseRow, + deps: ModelResolutionDeps = {}, +): Promise { + const mapFn = deps.mapSpawnContextToPhaseModelKeyFn ?? mapSpawnContextToPhaseModelKey; + const resolveFn = deps.resolvePhaseModelOverrideFn ?? resolvePhaseModelOverride; + const key = mapFn(context, phaseRow); + return await resolveFn(key); +} - const phaseSummaries: string[] = []; - for (const phase of phases) { - const result = await runPlanningPhase( - phase, - planDir, - ctx.cwd, - extensionPath, - state, - log, - widget, - ); - - phaseSummaries.push(`${phase.label}: ${result.summary}`); - if (!result.passed) { - return `Context captured. ${phase.label} failed.\n\n${phaseSummaries.join("\n")}`; - } - } +export async function spawnWorkWithResolvedModel( + phaseRow: PhaseRow, + spawnWorkFn: (opts: SpawnWorkRunOptions) => Promise, + opts: SpawnWorkRunOptions, + deps: ModelResolutionDeps = {}, +): Promise { + const modelOverride = await resolveSpawnModelOverride("work-debut", phaseRow, deps); + return await spawnWorkFn({ ...opts, modelOverride }); +} - let planMdPath: string; - try { - planMdPath = await renderPlanMarkdownToFile(planDir); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - log("Failed to render plan.md", { error: message, planDir }); - return `Planning phases completed, but plan markdown rendering failed: ${message}`; - } +export async function spawnFixWithResolvedModel( + phaseRow: PhaseRow, + spawnFixFn: (opts: SpawnFixRunOptions) => Promise, + opts: SpawnFixRunOptions, + deps: ModelResolutionDeps = {}, +): Promise { + const modelOverride = await resolveSpawnModelOverride("fix", phaseRow, deps); + return await spawnFixFn({ ...opts, modelOverride }); +} - state.phase = "plan-docs-complete"; - widget?.update({ - activeIndex: -1, - step: "planning complete; awaiting manual review of plan.md", - activity: "", - }); +export async function spawnQRDecomposerWithResolvedModel( + opts: SpawnQRDecomposerOptions, + deps: QRSpawnResolutionDeps = {}, +): Promise { + const modelOverride = await resolveSpawnModelOverride("qr-decompose", opts.phase as PhaseRow, deps); + const spawnFn = deps.spawnQRDecomposerFn ?? spawnQRDecomposer; + return await spawnFn({ ...opts, modelOverride }); +} - outcome = "PASS"; - return [ - "Context captured. Planning complete.", - "", - ...phaseSummaries, - "", - `Plan markdown: ${planMdPath}`, - "PAUSE: Please review this file manually before /koan execute.", - ].join("\n"); - } finally { - if (widget) { - widget.destroy(); - widget = null; - } - ctx.ui.notify(outcome, outcome === "PASS" ? "info" : "error"); - } - }; +export async function spawnReviewerWithResolvedModel( + opts: SpawnReviewerOptions, + deps: QRSpawnResolutionDeps = {}, +): Promise { + const modelOverride = await resolveSpawnModelOverride("qr-verify", opts.phase as PhaseRow, deps); + const spawnFn = deps.spawnReviewerFn ?? spawnReviewer; + return await spawnFn({ ...opts, modelOverride }); +} - const contextPhase = new ContextCapturePhase(pi, state, dispatch, createLogger("Context"), onContextComplete); +export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, planRef: PlanRef): Session { + const state: WorkflowState = createInitialState(); + const log = createLogger("Session"); + let widget: WidgetController | null = null; return { - async plan(args, ctx) { - const description = args.trim(); - if (!description) { - ctx.ui.notify("Usage: /koan plan ", "error"); - return; - } - - if (state.phase === "context" && state.context?.active) { - ctx.ui.notify("Context capture already running. Use /koan status to check progress.", "warning"); - return; - } + async plan(ctx: ExtensionContext): Promise> { + const planInfo = await createPlanInfo("", ctx.cwd); + initializePlanState(state, planInfo, ""); - await ctx.waitForIdle(); - - const planInfo = await createPlanInfo(description, ctx.cwd); - initializePlanState(state, planInfo, description); + // Wire plan directory for subagent dispatch and logging. planRef.dir = planInfo.directory; setLogDir(planInfo.directory); - log("Plan command invoked", { + log("Plan tool invoked", { cwd: ctx.cwd, - description, planId: planInfo.id, planDirectory: planInfo.directory, }); @@ -241,7 +198,95 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan widget = new WidgetController(ctx.ui, planInfo.id); } - await contextPhase.begin(description, planInfo, ctx); + // Export conversation to plan directory. + // Agents that need session context can Read this file. + await exportConversation(ctx.sessionManager, planInfo.directory); + log("Conversation exported", { planDir: planInfo.directory }); + + let outcome: "PASS" | "FAIL" = "FAIL"; + try { + const planDir = planInfo.directory; + const extensionPath = path.resolve(import.meta.dirname, "../../extensions/koan.ts"); + + // widgetIndex 0=design, 1=code, 2=docs + const phases: PhaseRunConfig[] = [ + { + key: "plan-design", + label: "Plan design", + widgetIndex: 0, + role: "architect", + spawnWork: (opts) => spawnArchitect(opts), + spawnFix: (opts) => spawnArchitectFix({ ...opts, fixPhase: "plan-design" }), + }, + { + key: "plan-code", + label: "Plan code", + widgetIndex: 1, + role: "developer", + spawnWork: (opts) => spawnDeveloper(opts), + spawnFix: (opts) => spawnDeveloperFix({ ...opts, fixPhase: "plan-code" }), + }, + { + key: "plan-docs", + label: "Plan docs", + widgetIndex: 2, + role: "technical-writer", + spawnWork: (opts) => spawnTechnicalWriter(opts), + spawnFix: (opts) => spawnTechnicalWriterFix({ ...opts, fixPhase: "plan-docs" }), + }, + ]; + + const phaseSummaries: string[] = []; + for (const phase of phases) { + const result = await runPlanningPhase( + phase, + planDir, + ctx.cwd, + extensionPath, + state, + log, + widget, + ); + + phaseSummaries.push(`${phase.label}: ${result.summary}`); + if (!result.passed) { + return { + content: [{ type: "text" as const, text: `Planning failed at ${phase.label}.\n\n${phaseSummaries.join("\n")}` }], + details: undefined, + }; + } + } + + try { + await renderPlanMarkdownToFile(planDir); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + log("Failed to render plan.md", { error: message, planDir }); + return { + content: [{ type: "text" as const, text: `Planning phases completed, but plan markdown rendering failed: ${message}\n\n${phaseSummaries.join("\n")}` }], + details: undefined, + }; + } + + state.phase = "plan-docs-complete"; + widget?.update({ + activeIndex: -1, + step: "planning complete; awaiting manual review of plan.md", + activity: "", + }); + + outcome = "PASS"; + return { + content: [{ type: "text" as const, text: `Planning complete.\n\n${phaseSummaries.join("\n")}` }], + details: undefined, + }; + } finally { + if (widget) { + widget.destroy(); + widget = null; + } + ctx.ui.notify(outcome, outcome === "PASS" ? "info" : "error"); + } }, async execute(ctx) { @@ -297,13 +342,17 @@ async function runPlanningPhase( }); }, 2000); - const workResult = await phase.spawnWork({ - planDir, - subagentDir, - cwd, - extensionPath, - log, - }); + const workResult = await spawnWorkWithResolvedModel( + phase.key as PhaseRow, + phase.spawnWork, + { + planDir, + subagentDir, + cwd, + extensionPath, + log, + }, + ); clearInterval(pollInterval); @@ -420,7 +469,7 @@ async function runQRBlock( }); }, 2000); - const decompose = await spawnQRDecomposer({ + const decompose = await spawnQRDecomposerWithResolvedModel({ planDir, subagentDir: decomposeDir, cwd, @@ -547,7 +596,7 @@ async function runQRBlock( QR_POOL_CONCURRENCY, async (itemId) => { const reviewerDir = await createSubagentDir(planDir, `qr-reviewer-${phase}-${itemId}`); - const r = await spawnReviewer({ + const r = await spawnReviewerWithResolvedModel({ planDir, subagentDir: reviewerDir, cwd, @@ -694,13 +743,17 @@ async function runPhaseWithQR( }); }, 2000); - const fixResult = await phase.spawnFix({ - planDir, - subagentDir: fixDir, - cwd, - extensionPath, - log, - }); + const fixResult = await spawnFixWithResolvedModel( + phase.key as PhaseRow, + phase.spawnFix, + { + planDir, + subagentDir: fixDir, + cwd, + extensionPath, + log, + }, + ); clearInterval(fixPoll); diff --git a/src/planner/state.ts b/src/planner/state.ts index eb34f5b..286250f 100644 --- a/src/planner/state.ts +++ b/src/planner/state.ts @@ -1,10 +1,5 @@ -import type { ContextData } from "./types.js"; - export type WorkflowPhase = | "idle" - | "context" - | "context-complete" - | "context-failed" | "architect-running" | "architect-failed" | "plan-design-complete" @@ -25,26 +20,10 @@ export interface PlanInfo { metadataPath: string; } -export interface ContextCaptureState { - readonly maxAttempts: number; - active: boolean; - subPhase: "drafting" | "verifying" | "refining"; - attempt: number; - taskDescription: string; - planId: string; - planDirectory: string; - contextFilePath: string; - lastPrompt: string | null; - feedback: string[]; - data?: ContextData; - lastRawContent?: string; -} - export interface WorkflowState { phase: WorkflowPhase; taskDescription: string | null; plan: PlanInfo | null; - context: ContextCaptureState | null; } export function createInitialState(): WorkflowState { @@ -52,19 +31,10 @@ export function createInitialState(): WorkflowState { phase: "idle", taskDescription: null, plan: null, - context: null, }; } -export function resetContextState(state: WorkflowState): void { - state.context = null; - if (state.phase !== "idle") { - state.phase = "idle"; - } -} - export function initializePlanState(state: WorkflowState, plan: PlanInfo, taskDescription: string): void { state.plan = plan; state.taskDescription = taskDescription; - resetContextState(state); } diff --git a/src/planner/subagent.ts b/src/planner/subagent.ts index 973759b..608bda6 100644 --- a/src/planner/subagent.ts +++ b/src/planner/subagent.ts @@ -23,6 +23,7 @@ export interface SpawnWorkOptions { cwd: string; extensionPath: string; initialPrompt?: string; + modelOverride?: string; log?: Logger; } @@ -32,6 +33,7 @@ export interface SpawnFixOptions { cwd: string; extensionPath: string; fixPhase: WorkPhaseKey; + modelOverride?: string; log?: Logger; } @@ -41,6 +43,7 @@ export interface SpawnQRDecomposerOptions { cwd: string; extensionPath: string; phase: WorkPhaseKey; + modelOverride?: string; log?: Logger; } @@ -51,17 +54,26 @@ export interface SpawnReviewerOptions { extensionPath: string; phase: WorkPhaseKey; itemId: string; + modelOverride?: string; log?: Logger; } -function spawnSubagent( +interface SpawnSubagentOpts { + planDir: string; + subagentDir: string; + cwd: string; + extensionPath: string; + extraFlags?: string[]; + modelOverride?: string; +} + +export function buildSpawnArgs( role: string, phase: string, prompt: string, - opts: { planDir: string; subagentDir: string; cwd: string; extensionPath: string; extraFlags?: string[] }, - log: Logger, -): Promise { - const args = [ + opts: SpawnSubagentOpts, +): string[] { + return [ "-p", "-e", opts.extensionPath, "--koan-role", role, @@ -69,8 +81,19 @@ function spawnSubagent( "--koan-plan-dir", opts.planDir, "--koan-subagent-dir", opts.subagentDir, ...(opts.extraFlags ?? []), + ...(opts.modelOverride ? ["--model", opts.modelOverride] : []), prompt, ]; +} + +function spawnSubagent( + role: string, + phase: string, + prompt: string, + opts: SpawnSubagentOpts, + log: Logger, +): Promise { + const args = buildSpawnArgs(role, phase, prompt, opts); log(`Spawning ${role} subagent`, { planDir: opts.planDir, subagentDir: opts.subagentDir, phase }); diff --git a/src/planner/tools/context-store.ts b/src/planner/tools/context-store.ts deleted file mode 100644 index cb4e97e..0000000 --- a/src/planner/tools/context-store.ts +++ /dev/null @@ -1,34 +0,0 @@ -import { Type } from "@sinclair/typebox"; - -const NonEmptyStringArray = Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }); - -export const ContextStoreSchema = Type.Object({ - task_spec: NonEmptyStringArray, - constraints: NonEmptyStringArray, - entry_points: NonEmptyStringArray, - rejected_alternatives: NonEmptyStringArray, - current_understanding: NonEmptyStringArray, - assumptions: NonEmptyStringArray, - invisible_knowledge: NonEmptyStringArray, - reference_docs: NonEmptyStringArray, -}, { - description: [ - "Structured planning context. All fields are string arrays.", - "task_spec: subject, scope, out-of-scope items.", - "constraints: 'MUST/SHOULD/MUST-NOT: rule (source)' or 'none confirmed'.", - "entry_points: 'file:symbol - why relevant' or 'greenfield'.", - "rejected_alternatives: 'approach - why dismissed' or 'none discussed'.", - "current_understanding: how the system works, relevant behavior.", - "assumptions: 'claim (H/M/L confidence)' or 'none'.", - "invisible_knowledge: design rationale, invariants, accepted tradeoffs.", - "reference_docs: 'path - what it covers' or 'none'.", - ].join(" "), -}); - -export interface ContextToolResult { - ok: boolean; - message: string; - errors?: string[]; -} - -export type ContextToolHandler = (payload: unknown, ctx: unknown) => Promise; diff --git a/src/planner/tools/workflow.ts b/src/planner/tools/workflow.ts index 70075e8..28b5282 100644 --- a/src/planner/tools/workflow.ts +++ b/src/planner/tools/workflow.ts @@ -1,11 +1,10 @@ -// Workflow tool registration: koan_complete_step and koan_store_context. +// Workflow tool registration: koan_complete_step. // Tools register once at init; execute callbacks read from the mutable // dispatch at call time, decoupling static registration from phase routing. import { Type } from "@sinclair/typebox"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import { ContextStoreSchema } from "./context-store.js"; import { createLogger } from "../../utils/logger.js"; import type { WorkflowDispatch } from "../lib/dispatch.js"; @@ -57,31 +56,4 @@ export function registerWorkflowTools( }; }, }); - - // -- koan_store_context -- - pi.registerTool({ - name: "koan_store_context", - label: "Store planning context", - description: [ - "Store structured planning context.", - "DO NOT call this tool until the step instructions explicitly tell you to.", - "Each field is a string array -- encode structure within strings, not as nested objects.", - ].join(" "), - parameters: ContextStoreSchema, - async execute(_toolCallId, params, _signal, _onUpdate, ctx) { - if (!dispatch.onStoreContext) { - throw new Error("Context capture is not active."); - } - const r = await dispatch.onStoreContext(params, ctx); - if (!r.ok) { - log("Context store rejected", { errors: r.errors }); - throw new Error(r.message); - } - log("Context stored"); - return { - content: [{ type: "text" as const, text: r.message }], - details: undefined, - }; - }, - }); } diff --git a/src/planner/types.ts b/src/planner/types.ts deleted file mode 100644 index 2a71e39..0000000 --- a/src/planner/types.ts +++ /dev/null @@ -1,21 +0,0 @@ -export interface ContextData { - task_spec: string[]; - constraints: string[]; - entry_points: string[]; - rejected_alternatives: string[]; - current_understanding: string[]; - assumptions: string[]; - invisible_knowledge: string[]; - reference_docs: string[]; -} - -export const CONTEXT_KEYS: ReadonlyArray = [ - "task_spec", - "constraints", - "entry_points", - "rejected_alternatives", - "current_understanding", - "assumptions", - "invisible_knowledge", - "reference_docs", -]; diff --git a/src/planner/ui/config/menu.ts b/src/planner/ui/config/menu.ts new file mode 100644 index 0000000..de11954 --- /dev/null +++ b/src/planner/ui/config/menu.ts @@ -0,0 +1,87 @@ +// Koan config menu. Opens a settings-style list with config sections. +// Currently exposes one section: "Model selection". +// New sections can be added here as additional SettingItems. + +import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent"; +import { getSettingsListTheme } from "@mariozechner/pi-coding-agent"; +import { type SettingItem, SettingsList } from "@mariozechner/pi-tui"; + +import { ALL_PHASE_MODEL_KEYS, type PhaseModelKey } from "../../model-phase.js"; +import { loadPhaseModelConfig } from "../../model-config.js"; +import { createModelSelectionComponent } from "./model-selection.js"; + +function configSummary(config: Record | null): string { + if (config === null) return "inheriting active model"; + return `${ALL_PHASE_MODEL_KEYS.length} keys configured`; +} + +export async function openKoanConfig(ctx: ExtensionCommandContext): Promise { + if (!ctx.hasUI) { + ctx.ui.notify("Koan config requires an interactive terminal.", "warning"); + return; + } + + await ctx.ui.custom(async (tui, theme, _keybindings, done) => { + const initialConfig = await loadPhaseModelConfig(); + let currentConfig = initialConfig; + + const activeModelId = ctx.model + ? `${ctx.model.provider}/${ctx.model.id}` + : undefined; + + // settingsList is captured in closure; submenu is only invoked after construction. + let settingsList: SettingsList; + + const sectionItems: SettingItem[] = [ + { + id: "model-selection", + label: "Model selection", + currentValue: configSummary(currentConfig), + submenu: (_cv, submenuDone) => { + return createModelSelectionComponent( + tui, + theme, + ctx.modelRegistry, + activeModelId, + currentConfig, + (newConfig) => { + currentConfig = newConfig; + settingsList.updateValue("model-selection", configSummary(newConfig)); + }, + (error) => { + const message = error instanceof Error ? error.message : String(error); + ctx.ui.notify(`Failed to save koan model config: ${message}`, "error"); + }, + () => submenuDone(undefined), + ); + }, + }, + ]; + + const returnItem: SettingItem = { + id: "__return", + label: "Return", + description: "Close /koan config (same as Esc)", + currentValue: "", + values: [""], + }; + + const items: SettingItem[] = [...sectionItems, returnItem]; + + settingsList = new SettingsList( + items, + 20, + getSettingsListTheme(), + (id) => { + if (id === "__return") done(); + }, + () => done(), + ); + + return { + render: (w) => settingsList.render(w), + handleInput: (d) => settingsList.handleInput(d), + invalidate: () => settingsList.invalidate(), + }; + }); +} diff --git a/src/planner/ui/config/model-selection.ts b/src/planner/ui/config/model-selection.ts new file mode 100644 index 0000000..7ff013a --- /dev/null +++ b/src/planner/ui/config/model-selection.ts @@ -0,0 +1,410 @@ +// Model selection matrix UI for /koan config. +// Renders quick-set actions plus a true 5×4 matrix (phase rows × sub-phase columns). +// Enter opens an inline ModelSelectorComponent for the selected quick-set/cell. +// Uses SettingsManager.inMemory() to prevent global default model mutation. + +import { ModelSelectorComponent, SettingsManager } from "@mariozechner/pi-coding-agent"; +import type { Theme } from "@mariozechner/pi-coding-agent"; +import type { ModelRegistry } from "@mariozechner/pi-coding-agent"; +import { + type Component, + type TUI, + getEditorKeybindings, + truncateToWidth, + visibleWidth, +} from "@mariozechner/pi-tui"; + +import { + ALL_PHASE_MODEL_KEYS, + GENERAL_PURPOSE_PHASE_MODEL_KEYS, + PHASE_ROWS, + STRONG_PHASE_MODEL_KEYS, + SUB_PHASES, + buildPhaseModelKey, + type PhaseModelKey, + type PhaseRow, +} from "../../model-phase.js"; +import { savePhaseModelConfig } from "../../model-config.js"; + +// -- Pure quick-set utilities (exported for testing) -- + +export function initConfigFromActiveModel(activeModelId: string): Record { + const config: Partial> = {}; + for (const key of ALL_PHASE_MODEL_KEYS) { + config[key] = activeModelId; + } + return config as Record; +} + +export function applyStrongModel( + model: string, + existingConfig: Record | null, + activeModelId: string, +): Record { + const base = existingConfig ?? initConfigFromActiveModel(activeModelId); + const result = { ...base }; + for (const key of STRONG_PHASE_MODEL_KEYS) { + result[key] = model; + } + return result; +} + +export function applyGeneralPurposeModel( + model: string, + existingConfig: Record | null, + activeModelId: string, +): Record { + const base = existingConfig ?? initConfigFromActiveModel(activeModelId); + const result = { ...base }; + for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { + result[key] = model; + } + return result; +} + +// -- Confirmation component for reset action -- + +class ResetConfirmComponent implements Component { + constructor( + private readonly theme: Theme, + private readonly onConfirm: () => void, + private readonly onCancel: () => void, + ) {} + + render(_width: number): string[] { + return [ + this.theme.bold(this.theme.fg("accent", "Reset all model overrides to active model?")), + "", + this.theme.fg("muted", " This will clear all 20 phase model overrides."), + this.theme.fg("muted", " Koan will use pi's current active model for all phases."), + "", + this.theme.fg("dim", " Enter to confirm · Escape to cancel"), + ]; + } + + handleInput(data: string): void { + if (data === "\r" || data === "\n") { + this.onConfirm(); + } else if (data === "\x1b") { + this.onCancel(); + } + } + + invalidate(): void {} +} + +function padRight(text: string, width: number): string { + const padding = Math.max(0, width - visibleWidth(text)); + return text + " ".repeat(padding); +} + +function renderCell(theme: Theme, text: string, width: number, selected: boolean, strong: boolean): string { + const innerWidth = Math.max(1, width - 2); + const clipped = truncateToWidth(text, innerWidth, ""); + const padded = padRight(clipped, innerWidth); + const raw = ` ${padded} `; + + if (selected) return theme.inverse(raw); + if (strong) return theme.fg("accent", raw); + return raw; +} + +function cellDisplay(modelId: string | undefined, activeModelId: string | undefined): string { + if (modelId === undefined) { + return activeModelId ? `inherit:${activeModelId}` : "inherit:active"; + } + return modelId; +} + +type SelectionZone = "quick" | "grid"; + +// -- Create model selection component -- + +export function createModelSelectionComponent( + tui: TUI, + theme: Theme, + modelRegistry: ModelRegistry, + activeModelId: string | undefined, + initialConfig: Record | null, + onConfigChange: (newConfig: Record | null) => void, + onSaveError: (error: unknown) => void, + onClose: () => void, +): Component { + const fallbackActive = activeModelId ?? "(active model)"; + const configRef: { value: Record | null } = { value: initialConfig }; + + const quickItems = [ + "Reset to active", + `Set strong (${STRONG_PHASE_MODEL_KEYS.size})`, + `Set general (${GENERAL_PURPOSE_PHASE_MODEL_KEYS.length})`, + ] as const; + + let zone: SelectionZone = "quick"; + let quickIndex = 0; + let rowIndex = 0; + let colIndex = 0; + let overlay: Component | null = null; + + function requestRender(): void { + tui.requestRender(); + } + + async function persistAndNotify(newConfig: Record | null): Promise { + const previous = configRef.value; + try { + await savePhaseModelConfig(newConfig); + configRef.value = newConfig; + onConfigChange(newConfig); + return true; + } catch (error) { + configRef.value = previous; + onSaveError(error); + return false; + } + } + + function makeModelSelector( + currentModelId: string | undefined, + onSelect: (modelId: string) => void, + onCancel: () => void, + ): Component { + const available = modelRegistry.getAvailable(); + const currentModel = currentModelId + ? available.find((m) => `${m.provider}/${m.id}` === currentModelId) + : available.find((m) => `${m.provider}/${m.id}` === activeModelId); + + const sm = SettingsManager.inMemory(); + + return new ModelSelectorComponent( + tui, + currentModel, + sm, + modelRegistry, + [], + (model) => onSelect(`${model.provider}/${model.id}`), + onCancel, + ); + } + + function closeOverlay(): void { + overlay = null; + requestRender(); + } + + function openResetConfirm(): void { + overlay = new ResetConfirmComponent( + theme, + () => { + void persistAndNotify(null).finally(() => closeOverlay()); + }, + () => closeOverlay(), + ); + requestRender(); + } + + function openStrongSelector(): void { + const strongSample = Array.from(STRONG_PHASE_MODEL_KEYS)[0]; + const currentId = configRef.value?.[strongSample]; + + overlay = makeModelSelector( + currentId, + (modelId) => { + const newConfig = applyStrongModel(modelId, configRef.value, fallbackActive); + void persistAndNotify(newConfig).finally(() => closeOverlay()); + }, + () => closeOverlay(), + ); + requestRender(); + } + + function openGeneralSelector(): void { + const gpSample = GENERAL_PURPOSE_PHASE_MODEL_KEYS[0]; + const currentId = configRef.value?.[gpSample]; + + overlay = makeModelSelector( + currentId, + (modelId) => { + const newConfig = applyGeneralPurposeModel(modelId, configRef.value, fallbackActive); + void persistAndNotify(newConfig).finally(() => closeOverlay()); + }, + () => closeOverlay(), + ); + requestRender(); + } + + function openCellSelector(): void { + const row = PHASE_ROWS[rowIndex] as PhaseRow; + const subPhase = SUB_PHASES[colIndex]; + const key = buildPhaseModelKey(row, subPhase); + const currentId = configRef.value?.[key]; + + overlay = makeModelSelector( + currentId, + (modelId) => { + const base = configRef.value ?? initConfigFromActiveModel(fallbackActive); + const newConfig = { ...base, [key]: modelId }; + void persistAndNotify(newConfig).finally(() => closeOverlay()); + }, + () => closeOverlay(), + ); + requestRender(); + } + + function activateSelection(): void { + if (zone === "quick") { + if (quickIndex === 0) { + openResetConfirm(); + } else if (quickIndex === 1) { + openStrongSelector(); + } else { + openGeneralSelector(); + } + return; + } + + openCellSelector(); + } + + function moveUp(): void { + if (zone === "quick") return; + if (rowIndex === 0) { + zone = "quick"; + return; + } + rowIndex -= 1; + } + + function moveDown(): void { + if (zone === "quick") { + zone = "grid"; + rowIndex = 0; + return; + } + + if (rowIndex === PHASE_ROWS.length - 1) { + rowIndex = 0; + return; + } + + rowIndex += 1; + } + + function moveLeft(): void { + if (zone === "quick") { + quickIndex = quickIndex === 0 ? quickItems.length - 1 : quickIndex - 1; + return; + } + + colIndex = colIndex === 0 ? SUB_PHASES.length - 1 : colIndex - 1; + } + + function moveRight(): void { + if (zone === "quick") { + quickIndex = quickIndex === quickItems.length - 1 ? 0 : quickIndex + 1; + return; + } + + colIndex = colIndex === SUB_PHASES.length - 1 ? 0 : colIndex + 1; + } + + function renderMain(width: number): string[] { + const lines: string[] = []; + + lines.push(theme.bold(theme.fg("accent", "Koan / Config / Model selection"))); + lines.push(theme.fg("muted", `Fallback active model: ${fallbackActive}`)); + lines.push(""); + + const quick = quickItems + .map((label, i) => { + const block = ` ${label} `; + if (zone === "quick" && quickIndex === i) return theme.inverse(block); + return theme.fg("muted", block); + }) + .join(" "); + + lines.push(`Quick-set: ${quick}`); + lines.push(""); + + const sep = " | "; + const sepWidth = visibleWidth(sep); + const phaseColWidth = 12; + const available = Math.max(24, width - phaseColWidth - sepWidth * 4); + const modelColWidth = Math.max(12, Math.floor(available / 4)); + + const headerCells = [ + renderCell(theme, "phase", phaseColWidth, false, false), + ...SUB_PHASES.map((sub) => renderCell(theme, sub, modelColWidth, false, false)), + ]; + lines.push(headerCells.join(sep)); + lines.push("-".repeat(Math.max(10, Math.min(width, visibleWidth(headerCells.join(sep)))))); + + for (let r = 0; r < PHASE_ROWS.length; r += 1) { + const row = PHASE_ROWS[r] as PhaseRow; + const rowCells: string[] = [renderCell(theme, row, phaseColWidth, false, false)]; + + for (let c = 0; c < SUB_PHASES.length; c += 1) { + const sub = SUB_PHASES[c]; + const key = buildPhaseModelKey(row, sub); + const model = configRef.value?.[key]; + const display = cellDisplay(model, activeModelId); + const selected = zone === "grid" && rowIndex === r && colIndex === c; + const strong = STRONG_PHASE_MODEL_KEYS.has(key); + rowCells.push(renderCell(theme, display, modelColWidth, selected, strong)); + } + + lines.push(truncateToWidth(rowCells.join(sep), width)); + } + + lines.push(""); + lines.push(theme.fg("dim", "★ strong cell")); + lines.push(theme.fg("dim", "↑↓ move row/section · ←→ move column/quick-set · Enter select · Esc back")); + + return lines; + } + + return { + render: (width) => { + if (overlay) return overlay.render(width); + return renderMain(width); + }, + handleInput: (data) => { + if (overlay) { + overlay.handleInput?.(data); + return; + } + + const kb = getEditorKeybindings(); + + if (kb.matches(data, "selectCancel")) { + onClose(); + return; + } + if (kb.matches(data, "selectConfirm") || data === " ") { + activateSelection(); + return; + } + if (kb.matches(data, "selectUp")) { + moveUp(); + requestRender(); + return; + } + if (kb.matches(data, "selectDown")) { + moveDown(); + requestRender(); + return; + } + if (kb.matches(data, "cursorLeft")) { + moveLeft(); + requestRender(); + return; + } + if (kb.matches(data, "cursorRight")) { + moveRight(); + requestRender(); + } + }, + invalidate: () => { + overlay?.invalidate?.(); + }, + }; +} diff --git a/src/planner/ui/widget.ts b/src/planner/ui/widget.ts index 84320cc..14a0391 100644 --- a/src/planner/ui/widget.ts +++ b/src/planner/ui/widget.ts @@ -88,7 +88,6 @@ const LOG_LINES = 5; const BODY_INDENT = " "; const PLANNING_PHASES: ReadonlyArray<{ key: string; label: string; detail: string }> = [ - { key: "ctx", label: "Context gathering", detail: "Gathering initial context" }, { key: "design", label: "Plan design", detail: "Designing plan" }, { key: "code", label: "Plan code", detail: "Creating code plan" }, { key: "docs", label: "Plan docs", detail: "Documenting plan" }, @@ -225,7 +224,6 @@ const HEADER_STATUS_SHORT: Record = { }; const HEADER_PHASE_SHORT: Record = { - "Context gathering": "Ctx gather", "Plan design": "Design", "Plan code": "Code", "Plan docs": "Docs", @@ -339,7 +337,7 @@ function shouldShowQR(state: WidgetState): boolean { if (state.qrIteration === null) return false; const active = activePhase(state); if (!active) return false; - return active.key !== "ctx"; + return true; } type QRTier = "wide" | "medium" | "tight"; From 18341f7d01cfa412baa458757a9dec9e16ffd5f2 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 2 Mar 2026 13:41:43 +0700 Subject: [PATCH 030/412] add regression tests for conversation export and model routing --- package.json | 2 +- tests/conversation.test.ts | 103 ++++++++++++ tests/model-config.test.ts | 233 ++++++++++++++++++++++++++ tests/model-phase.test.ts | 135 +++++++++++++++ tests/model-resolver.test.ts | 164 ++++++++++++++++++ tests/session-model-threading.test.ts | 205 ++++++++++++++++++++++ tests/subagent-model.test.ts | 215 ++++++++++++++++++++++++ tests/widget.test.ts | 9 +- 8 files changed, 1061 insertions(+), 5 deletions(-) create mode 100644 tests/conversation.test.ts create mode 100644 tests/model-config.test.ts create mode 100644 tests/model-phase.test.ts create mode 100644 tests/model-resolver.test.ts create mode 100644 tests/session-model-threading.test.ts create mode 100644 tests/subagent-model.test.ts diff --git a/package.json b/package.json index feaae5b..e99f2d3 100644 --- a/package.json +++ b/package.json @@ -25,7 +25,7 @@ "check": "tsc --noEmit", "build": "tsc --project tsconfig.build.json", "pretest": "npm run build", - "test": "node --test build/tests" + "test": "node --test --test-concurrency=1 build/tests" }, "dependencies": { "@sinclair/typebox": "^0.32.30" diff --git a/tests/conversation.test.ts b/tests/conversation.test.ts new file mode 100644 index 0000000..2e29dfe --- /dev/null +++ b/tests/conversation.test.ts @@ -0,0 +1,103 @@ +import assert from "node:assert/strict"; +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { describe, it } from "node:test"; + +import { exportConversation } from "../src/planner/conversation.js"; + +type MockEntry = { type: string; role?: string; content?: string }; + +function createMockSessionManager(header: MockEntry | null, branch: MockEntry[]) { + return { + getHeader: () => header, + getBranch: () => branch, + }; +} + +async function withTempDir(fn: (dir: string) => Promise): Promise { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), "koan-conv-test-")); + try { + return await fn(dir); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } +} + +describe("exportConversation", () => { + it("writes valid JSONL with header and branch entries", async () => { + await withTempDir(async (dir) => { + const header: MockEntry = { type: "header", content: "session-metadata" }; + const branch: MockEntry[] = [ + { type: "message", role: "user", content: "Plan this task" }, + { type: "message", role: "assistant", content: "I will plan it" }, + ]; + + const sessionManager = createMockSessionManager(header, branch); + const filePath = await exportConversation( + sessionManager as any, + dir, + ); + + assert.equal(filePath, path.join(dir, "conversation.jsonl")); + + const raw = await fs.readFile(filePath, "utf8"); + const lines = raw.trimEnd().split("\n"); + + assert.equal(lines.length, 3, "should have header + 2 branch entries"); + + const parsed = lines.map((line) => JSON.parse(line) as MockEntry); + assert.deepEqual(parsed[0], header); + assert.deepEqual(parsed[1], branch[0]); + assert.deepEqual(parsed[2], branch[1]); + }); + }); + + it("writes valid JSONL without header when header is null", async () => { + await withTempDir(async (dir) => { + const branch: MockEntry[] = [ + { type: "message", role: "user", content: "Hello" }, + ]; + + const sessionManager = createMockSessionManager(null, branch); + await exportConversation(sessionManager as any, dir); + + const raw = await fs.readFile(path.join(dir, "conversation.jsonl"), "utf8"); + const lines = raw.trimEnd().split("\n"); + + assert.equal(lines.length, 1, "should have only the branch entry"); + const parsed = JSON.parse(lines[0]) as MockEntry; + assert.deepEqual(parsed, branch[0]); + }); + }); + + it("writes empty file with trailing newline when no entries", async () => { + await withTempDir(async (dir) => { + const sessionManager = createMockSessionManager(null, []); + await exportConversation(sessionManager as any, dir); + + const raw = await fs.readFile(path.join(dir, "conversation.jsonl"), "utf8"); + assert.equal(raw, "\n", "empty conversation should produce a single newline"); + }); + }); + + it("each line is valid JSON", async () => { + await withTempDir(async (dir) => { + const header: MockEntry = { type: "header" }; + const branch: MockEntry[] = [ + { type: "message", role: "user", content: 'contains "quotes" and\nnewlines' }, + { type: "message", role: "assistant", content: "response" }, + ]; + + const sessionManager = createMockSessionManager(header, branch); + await exportConversation(sessionManager as any, dir); + + const raw = await fs.readFile(path.join(dir, "conversation.jsonl"), "utf8"); + const lines = raw.trimEnd().split("\n"); + + for (const line of lines) { + assert.doesNotThrow(() => JSON.parse(line), `line should be valid JSON: ${line}`); + } + }); + }); +}); diff --git a/tests/model-config.test.ts b/tests/model-config.test.ts new file mode 100644 index 0000000..a7e949f --- /dev/null +++ b/tests/model-config.test.ts @@ -0,0 +1,233 @@ +import assert from "node:assert/strict"; +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { describe, it } from "node:test"; + +import { ALL_PHASE_MODEL_KEYS, type PhaseModelKey } from "../src/planner/model-phase.js"; +import { loadPhaseModelConfig, savePhaseModelConfig } from "../src/planner/model-config.js"; + +function makeFullConfig(model = "anthropic/claude-sonnet"): Record { + const config: Partial> = {}; + for (const key of ALL_PHASE_MODEL_KEYS) { + config[key] = model; + } + return config as Record; +} + +// Test config validation logic directly using a mock config file +// by writing to a temp location and reading back. +// Note: loadPhaseModelConfig reads from ~/.koan/config.json, so we +// test validation using the raw parsing logic via an in-process approach. + +describe("config validation", () => { + it("accepts a complete 20-key config and returns it unchanged", async () => { + // We test the validation by round-tripping through save/load. + // To avoid touching ~/.koan/config.json, we verify the pure logic + // by testing that a valid config object has all required keys. + const config = makeFullConfig("anthropic/claude-opus-4"); + + // Verify it has exactly 20 keys + assert.equal(Object.keys(config).length, ALL_PHASE_MODEL_KEYS.length); + + // Verify all keys are valid PhaseModelKeys + for (const key of Object.keys(config)) { + assert.ok( + (ALL_PHASE_MODEL_KEYS as readonly string[]).includes(key), + `unexpected key: ${key}`, + ); + } + + // Verify all values are non-empty strings + for (const [key, value] of Object.entries(config)) { + assert.equal(typeof value, "string", `value for ${key} should be a string`); + assert.ok(value.length > 0, `value for ${key} should be non-empty`); + } + }); + + it("treats null as valid (no overrides)", () => { + // Null config is valid — it means inherit from pi's active model + const config: Record | null = null; + assert.equal(config, null); + }); +}); + +describe("loadPhaseModelConfig (integration)", () => { + it("returns null when config file is missing", async () => { + // loadPhaseModelConfig reads ~/.koan/config.json - if it doesn't exist, null + // We can only test this if ~/.koan/config.json doesn't exist on this machine + // or has no phaseModels. This is an integration test, so we skip the file check + // and instead verify the contract: the function always returns null or a valid config. + const result = await loadPhaseModelConfig(); + // Result is either null or a Record with exactly 20 keys + if (result !== null) { + assert.equal(Object.keys(result).length, ALL_PHASE_MODEL_KEYS.length); + for (const key of ALL_PHASE_MODEL_KEYS) { + assert.equal(typeof result[key], "string"); + assert.ok(result[key].length > 0); + } + } + }); +}); + +describe("savePhaseModelConfig + loadPhaseModelConfig (round-trip)", () => { + it("persists a full config and reads it back correctly", async () => { + // KOAN_CONFIG_PATH is computed at module load time, so tests validate + // round-trip behavior against the real path and restore prior state. + + const actualConfigPath = path.join(os.homedir(), ".koan", "config.json"); + let preExisting: string | null = null; + + try { + preExisting = await fs.readFile(actualConfigPath, "utf8"); + } catch { + preExisting = null; + } + + try { + const config = makeFullConfig("openai/gpt-5"); + await savePhaseModelConfig(config); + + const loaded = await loadPhaseModelConfig(); + assert.ok(loaded !== null, "expected config to be loaded after save"); + assert.equal(Object.keys(loaded).length, ALL_PHASE_MODEL_KEYS.length); + + for (const key of ALL_PHASE_MODEL_KEYS) { + assert.equal(loaded[key], "openai/gpt-5", `mismatch for key ${key}`); + } + } finally { + // Restore original state + if (preExisting === null) { + try { + const koanDir = path.join(os.homedir(), ".koan"); + await fs.rm(actualConfigPath, { force: true }); + // Try to remove the .koan dir if it was empty before + const entries = await fs.readdir(koanDir); + if (entries.length === 0) { + await fs.rmdir(koanDir); + } + } catch { + // Best-effort cleanup + } + } else { + await fs.writeFile(actualConfigPath, preExisting, "utf8"); + } + + } + }); + + it("persists null (clears overrides) while preserving other config keys", async () => { + const actualConfigPath = path.join(os.homedir(), ".koan", "config.json"); + let preExisting: string | null = null; + + try { + preExisting = await fs.readFile(actualConfigPath, "utf8"); + } catch { + preExisting = null; + } + + try { + // Write an initial config + await savePhaseModelConfig(makeFullConfig("anthropic/claude-sonnet")); + + // Now clear it + await savePhaseModelConfig(null); + + const loaded = await loadPhaseModelConfig(); + assert.equal(loaded, null, "expected null after clearing overrides"); + + // Verify the config file still exists but has no phaseModels key + const raw = await fs.readFile(actualConfigPath, "utf8"); + const parsed = (raw.trim().length === 0 ? {} : JSON.parse(raw)) as Record; + assert.equal("phaseModels" in parsed, false, "phaseModels should be absent after clearing"); + } finally { + if (preExisting === null) { + try { + await fs.rm(actualConfigPath, { force: true }); + } catch { + // Best-effort + } + } else { + await fs.writeFile(actualConfigPath, preExisting, "utf8"); + } + } + }); +}); + +describe("config validation: partial config treated as absent", () => { + it("validates that a partial config (missing keys) is treated as absent", async () => { + // We simulate this by checking the validation logic: + // A config with fewer than 20 keys should produce null from loadPhaseModelConfig. + // We test this indirectly by verifying the contract. + const partialKeys = ALL_PHASE_MODEL_KEYS.slice(0, 10); + assert.equal(partialKeys.length, 10); + assert.equal(partialKeys.length < ALL_PHASE_MODEL_KEYS.length, true); + + // A partial config would fail the length check in loadPhaseModelConfig. + // We verify this by writing a partial config and reading it back. + const actualConfigPath = path.join(os.homedir(), ".koan", "config.json"); + let preExisting: string | null = null; + + try { + preExisting = await fs.readFile(actualConfigPath, "utf8"); + } catch { + preExisting = null; + } + + try { + await fs.mkdir(path.dirname(actualConfigPath), { recursive: true }); + const partial: Record = {}; + for (const key of partialKeys) { + partial[key] = "anthropic/claude-sonnet"; + } + await fs.writeFile(actualConfigPath, JSON.stringify({ phaseModels: partial }), "utf8"); + + const loaded = await loadPhaseModelConfig(); + assert.equal(loaded, null, "expected null for partial config"); + } finally { + if (preExisting === null) { + try { await fs.rm(actualConfigPath, { force: true }); } catch { /* best-effort */ } + } else { + await fs.writeFile(actualConfigPath, preExisting, "utf8"); + } + } + }); + + it("validates that a config with unknown keys is treated as absent", async () => { + const actualConfigPath = path.join(os.homedir(), ".koan", "config.json"); + let preExisting: string | null = null; + + try { + preExisting = await fs.readFile(actualConfigPath, "utf8"); + } catch { + preExisting = null; + } + + try { + await fs.mkdir(path.dirname(actualConfigPath), { recursive: true }); + + // Build a 20-key config with one key replaced by an unknown key + const badConfig: Record = {}; + let first = true; + for (const key of ALL_PHASE_MODEL_KEYS) { + if (first) { + badConfig["unknown-phase-exec-debut"] = "anthropic/claude-sonnet"; + first = false; + } else { + badConfig[key] = "anthropic/claude-sonnet"; + } + } + + await fs.writeFile(actualConfigPath, JSON.stringify({ phaseModels: badConfig }), "utf8"); + + const loaded = await loadPhaseModelConfig(); + assert.equal(loaded, null, "expected null for config with unknown key"); + } finally { + if (preExisting === null) { + try { await fs.rm(actualConfigPath, { force: true }); } catch { /* best-effort */ } + } else { + await fs.writeFile(actualConfigPath, preExisting, "utf8"); + } + } + }); +}); diff --git a/tests/model-phase.test.ts b/tests/model-phase.test.ts new file mode 100644 index 0000000..9797d49 --- /dev/null +++ b/tests/model-phase.test.ts @@ -0,0 +1,135 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; + +import { + ALL_PHASE_MODEL_KEYS, + GENERAL_PURPOSE_PHASE_MODEL_KEYS, + PHASE_ROWS, + STRONG_PHASE_MODEL_KEYS, + SUB_PHASES, + buildPhaseModelKey, + isPhaseModelKey, + type PhaseModelKey, +} from "../src/planner/model-phase.js"; + +describe("ALL_PHASE_MODEL_KEYS", () => { + it("contains exactly 20 keys (5 rows × 4 sub-phases)", () => { + assert.equal(ALL_PHASE_MODEL_KEYS.length, PHASE_ROWS.length * SUB_PHASES.length); + assert.equal(ALL_PHASE_MODEL_KEYS.length, 20); + }); + + it("contains no duplicates", () => { + const set = new Set(ALL_PHASE_MODEL_KEYS); + assert.equal(set.size, ALL_PHASE_MODEL_KEYS.length); + }); + + it("contains every combination of row and sub-phase", () => { + for (const row of PHASE_ROWS) { + for (const sub of SUB_PHASES) { + const key = `${row}-${sub}` as PhaseModelKey; + assert.ok( + ALL_PHASE_MODEL_KEYS.includes(key), + `expected key "${key}" to be present`, + ); + } + } + }); +}); + +describe("STRONG_PHASE_MODEL_KEYS", () => { + it("contains exactly 9 keys", () => { + assert.equal(STRONG_PHASE_MODEL_KEYS.size, 9); + }); + + it("contains all 5 qr-decompose keys", () => { + for (const row of PHASE_ROWS) { + const key = buildPhaseModelKey(row, "qr-decompose"); + assert.ok(STRONG_PHASE_MODEL_KEYS.has(key), `expected ${key} to be strong`); + } + }); + + it("contains plan-design exec-debut and exec-fix", () => { + assert.ok(STRONG_PHASE_MODEL_KEYS.has("plan-design-exec-debut")); + assert.ok(STRONG_PHASE_MODEL_KEYS.has("plan-design-exec-fix")); + }); + + it("contains exec-docs exec-debut and exec-fix", () => { + assert.ok(STRONG_PHASE_MODEL_KEYS.has("exec-docs-exec-debut")); + assert.ok(STRONG_PHASE_MODEL_KEYS.has("exec-docs-exec-fix")); + }); + + it("does not contain plan-code or plan-docs exec keys", () => { + assert.equal(STRONG_PHASE_MODEL_KEYS.has("plan-code-exec-debut"), false); + assert.equal(STRONG_PHASE_MODEL_KEYS.has("plan-code-exec-fix"), false); + assert.equal(STRONG_PHASE_MODEL_KEYS.has("plan-docs-exec-debut"), false); + assert.equal(STRONG_PHASE_MODEL_KEYS.has("plan-docs-exec-fix"), false); + }); +}); + +describe("GENERAL_PURPOSE_PHASE_MODEL_KEYS", () => { + it("contains exactly 11 keys (20 total - 9 strong)", () => { + assert.equal(GENERAL_PURPOSE_PHASE_MODEL_KEYS.length, 11); + }); + + it("strong and GP form a complete partition of all keys", () => { + const strongSet = STRONG_PHASE_MODEL_KEYS; + const gpSet = new Set(GENERAL_PURPOSE_PHASE_MODEL_KEYS); + + // Union equals ALL + for (const key of ALL_PHASE_MODEL_KEYS) { + assert.ok( + strongSet.has(key) || gpSet.has(key), + `key "${key}" missing from both sets`, + ); + } + + // Intersection is empty + for (const key of ALL_PHASE_MODEL_KEYS) { + assert.equal( + strongSet.has(key) && gpSet.has(key), + false, + `key "${key}" appears in both sets`, + ); + } + }); +}); + +describe("isPhaseModelKey", () => { + it("returns true for valid keys", () => { + for (const key of ALL_PHASE_MODEL_KEYS) { + assert.equal(isPhaseModelKey(key), true, `expected "${key}" to be valid`); + } + }); + + it("returns false for invalid strings", () => { + assert.equal(isPhaseModelKey("plan-design"), false); + assert.equal(isPhaseModelKey("exec-debut"), false); + assert.equal(isPhaseModelKey("plan-design-exec-init"), false); + assert.equal(isPhaseModelKey("unknown-key"), false); + assert.equal(isPhaseModelKey(""), false); + }); + + it("returns false for non-string values", () => { + assert.equal(isPhaseModelKey(42), false); + assert.equal(isPhaseModelKey(null), false); + assert.equal(isPhaseModelKey(undefined), false); + assert.equal(isPhaseModelKey({}), false); + }); +}); + +describe("buildPhaseModelKey", () => { + it("produces correct key for all combinations", () => { + assert.equal(buildPhaseModelKey("plan-design", "exec-debut"), "plan-design-exec-debut"); + assert.equal(buildPhaseModelKey("exec-docs", "qr-verify"), "exec-docs-qr-verify"); + assert.equal(buildPhaseModelKey("plan-code", "qr-decompose"), "plan-code-qr-decompose"); + }); + + it("produces keys that pass isPhaseModelKey", () => { + for (const row of PHASE_ROWS) { + for (const sub of SUB_PHASES) { + const key = buildPhaseModelKey(row, sub); + assert.equal(isPhaseModelKey(key), true, `buildPhaseModelKey(${row}, ${sub}) = "${key}" failed isPhaseModelKey`); + } + } + }); +}); diff --git a/tests/model-resolver.test.ts b/tests/model-resolver.test.ts new file mode 100644 index 0000000..b37ef35 --- /dev/null +++ b/tests/model-resolver.test.ts @@ -0,0 +1,164 @@ +import assert from "node:assert/strict"; +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { describe, it } from "node:test"; + +import { + ALL_PHASE_MODEL_KEYS, + PHASE_ROWS, + SUB_PHASES, + type PhaseModelKey, +} from "../src/planner/model-phase.js"; +import { + mapSpawnContextToPhaseModelKey, + resolvePhaseModelOverride, + type SpawnContext, +} from "../src/planner/model-resolver.js"; + +describe("mapSpawnContextToPhaseModelKey", () => { + it("maps work-debut to exec-debut for all phase rows", () => { + for (const row of PHASE_ROWS) { + const key = mapSpawnContextToPhaseModelKey("work-debut", row); + assert.equal(key, `${row}-exec-debut`, `row=${row}`); + } + }); + + it("maps fix to exec-fix for all phase rows", () => { + for (const row of PHASE_ROWS) { + const key = mapSpawnContextToPhaseModelKey("fix", row); + assert.equal(key, `${row}-exec-fix`, `row=${row}`); + } + }); + + it("maps qr-decompose to qr-decompose for all phase rows", () => { + for (const row of PHASE_ROWS) { + const key = mapSpawnContextToPhaseModelKey("qr-decompose", row); + assert.equal(key, `${row}-qr-decompose`, `row=${row}`); + } + }); + + it("maps qr-verify to qr-verify for all phase rows", () => { + for (const row of PHASE_ROWS) { + const key = mapSpawnContextToPhaseModelKey("qr-verify", row); + assert.equal(key, `${row}-qr-verify`, `row=${row}`); + } + }); + + it("produces keys that are valid PhaseModelKeys", () => { + const contexts: SpawnContext[] = ["work-debut", "fix", "qr-decompose", "qr-verify"]; + for (const context of contexts) { + for (const row of PHASE_ROWS) { + const key = mapSpawnContextToPhaseModelKey(context, row); + assert.ok( + (ALL_PHASE_MODEL_KEYS as readonly string[]).includes(key), + `key "${key}" (context=${context}, row=${row}) is not a valid PhaseModelKey`, + ); + } + } + }); + + it("covers all 20 PhaseModelKeys across context × row combinations", () => { + const produced = new Set(); + const contexts: SpawnContext[] = ["work-debut", "fix", "qr-decompose", "qr-verify"]; + for (const context of contexts) { + for (const row of PHASE_ROWS) { + produced.add(mapSpawnContextToPhaseModelKey(context, row)); + } + } + assert.equal(produced.size, ALL_PHASE_MODEL_KEYS.length); + for (const key of ALL_PHASE_MODEL_KEYS) { + assert.ok(produced.has(key), `key "${key}" not produced by any context × row combination`); + } + }); + + it("accepts optional fixPhase argument without altering output", () => { + const withoutFix = mapSpawnContextToPhaseModelKey("fix", "plan-design"); + const withFix = mapSpawnContextToPhaseModelKey("fix", "plan-design", "plan-design"); + assert.equal(withoutFix, withFix); + }); +}); + +describe("SpawnContext values cover all sub-phases", () => { + it("one SpawnContext maps to each SubPhase", () => { + const contexts: SpawnContext[] = ["work-debut", "fix", "qr-decompose", "qr-verify"]; + const row = "plan-design"; + const subPhasesProduced = contexts.map((c) => { + const key = mapSpawnContextToPhaseModelKey(c, row); + return key.replace(`${row}-`, "") as typeof SUB_PHASES[number]; + }); + + for (const sub of SUB_PHASES) { + assert.ok( + subPhasesProduced.includes(sub), + `sub-phase "${sub}" not covered by any SpawnContext`, + ); + } + }); +}); + +function makeFullConfig(model: string): Record { + const config: Partial> = {}; + for (const key of ALL_PHASE_MODEL_KEYS) { + config[key] = model; + } + return config as Record; +} + +async function withConfigFile( + setup: (configPath: string) => Promise, + run: () => Promise, +): Promise { + const configPath = path.join(os.homedir(), ".koan", "config.json"); + + let preExisting: string | null = null; + try { + preExisting = await fs.readFile(configPath, "utf8"); + } catch { + preExisting = null; + } + + try { + await fs.mkdir(path.dirname(configPath), { recursive: true }); + await setup(configPath); + return await run(); + } finally { + if (preExisting === null) { + try { + await fs.rm(configPath, { force: true }); + } catch { + // best-effort cleanup + } + } else { + await fs.writeFile(configPath, preExisting, "utf8"); + } + } +} + +describe("resolvePhaseModelOverride", () => { + it("returns configured model when full config is present", async () => { + await withConfigFile( + async (configPath) => { + const phaseModels = makeFullConfig("anthropic/claude-sonnet"); + phaseModels["plan-design-exec-debut"] = "openai/gpt-5"; + await fs.writeFile(configPath, `${JSON.stringify({ phaseModels }, null, 2)}\n`, "utf8"); + }, + async () => { + const value = await resolvePhaseModelOverride("plan-design-exec-debut"); + assert.equal(value, "openai/gpt-5"); + }, + ); + }); + + it("returns undefined when config is absent", async () => { + await withConfigFile( + async (configPath) => { + await fs.writeFile(configPath, `${JSON.stringify({ unrelated: true }, null, 2)}\n`, "utf8"); + }, + async () => { + const value = await resolvePhaseModelOverride("plan-code-exec-fix"); + assert.equal(value, undefined); + }, + ); + }); +}); diff --git a/tests/session-model-threading.test.ts b/tests/session-model-threading.test.ts new file mode 100644 index 0000000..6462e8d --- /dev/null +++ b/tests/session-model-threading.test.ts @@ -0,0 +1,205 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; + +import { + resolveSpawnModelOverride, + spawnWorkWithResolvedModel, + spawnFixWithResolvedModel, + spawnQRDecomposerWithResolvedModel, + spawnReviewerWithResolvedModel, +} from "../src/planner/session.js"; +import type { PhaseModelKey } from "../src/planner/model-phase.js"; + +describe("resolveSpawnModelOverride", () => { + it("maps context -> key and resolves override", async () => { + const contexts = ["work-debut", "fix", "qr-decompose", "qr-verify"] as const; + + for (const context of contexts) { + let mappedContext: string | null = null; + let mappedRow: string | null = null; + let resolvedKey: string | null = null; + + const result = await resolveSpawnModelOverride(context, "plan-design", { + mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { + mappedContext = ctx; + mappedRow = row; + return "plan-design-exec-debut" as PhaseModelKey; + }, + resolvePhaseModelOverrideFn: async (key) => { + resolvedKey = key; + return "anthropic/claude-opus-4"; + }, + }); + + assert.equal(mappedContext, context); + assert.equal(mappedRow, "plan-design"); + assert.equal(resolvedKey, "plan-design-exec-debut"); + assert.equal(result, "anthropic/claude-opus-4"); + } + }); + + it("returns undefined when resolver reports absent config", async () => { + const result = await resolveSpawnModelOverride("work-debut", "plan-code", { + mapSpawnContextToPhaseModelKeyFn: () => "plan-code-exec-debut" as PhaseModelKey, + resolvePhaseModelOverrideFn: async () => undefined, + }); + + assert.equal(result, undefined); + }); +}); + +describe("work/fix spawn model threading", () => { + it("threads resolved modelOverride into work spawns", async () => { + let capturedModelOverride: string | undefined; + + await spawnWorkWithResolvedModel( + "plan-design", + async (opts) => { + capturedModelOverride = opts.modelOverride; + return { exitCode: 0, stderr: "", subagentDir: opts.subagentDir }; + }, + { + planDir: "/plan", + subagentDir: "/subagent", + cwd: "/cwd", + extensionPath: "/ext/koan.ts", + log: () => {}, + }, + { + mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { + assert.equal(ctx, "work-debut"); + assert.equal(row, "plan-design"); + return "plan-design-exec-debut" as PhaseModelKey; + }, + resolvePhaseModelOverrideFn: async (key) => { + assert.equal(key, "plan-design-exec-debut"); + return "anthropic/claude-opus-4"; + }, + }, + ); + + assert.equal(capturedModelOverride, "anthropic/claude-opus-4"); + }); + + it("threads resolved modelOverride into fix spawns", async () => { + let capturedModelOverride: string | undefined; + + await spawnFixWithResolvedModel( + "plan-code", + async (opts) => { + capturedModelOverride = opts.modelOverride; + return { exitCode: 0, stderr: "", subagentDir: opts.subagentDir }; + }, + { + planDir: "/plan", + subagentDir: "/subagent", + cwd: "/cwd", + extensionPath: "/ext/koan.ts", + log: () => {}, + }, + { + mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { + assert.equal(ctx, "fix"); + assert.equal(row, "plan-code"); + return "plan-code-exec-fix" as PhaseModelKey; + }, + resolvePhaseModelOverrideFn: async (key) => { + assert.equal(key, "plan-code-exec-fix"); + return "openai/gpt-5"; + }, + }, + ); + + assert.equal(capturedModelOverride, "openai/gpt-5"); + }); +}); + +describe("QR spawn model threading", () => { + it("threads resolved modelOverride into spawnQRDecomposer", async () => { + let capturedModelOverride: string | undefined; + + await spawnQRDecomposerWithResolvedModel( + { + planDir: "/plan", + subagentDir: "/subagent", + cwd: "/cwd", + extensionPath: "/ext/koan.ts", + phase: "plan-design", + }, + { + mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { + assert.equal(ctx, "qr-decompose"); + assert.equal(row, "plan-design"); + return "plan-design-qr-decompose" as PhaseModelKey; + }, + resolvePhaseModelOverrideFn: async (key) => { + assert.equal(key, "plan-design-qr-decompose"); + return "openai/gpt-5"; + }, + spawnQRDecomposerFn: async (opts) => { + capturedModelOverride = opts.modelOverride; + return { exitCode: 0, stderr: "", subagentDir: opts.subagentDir }; + }, + }, + ); + + assert.equal(capturedModelOverride, "openai/gpt-5"); + }); + + it("threads resolved modelOverride into spawnReviewer", async () => { + let capturedModelOverride: string | undefined; + + await spawnReviewerWithResolvedModel( + { + planDir: "/plan", + subagentDir: "/subagent", + cwd: "/cwd", + extensionPath: "/ext/koan.ts", + phase: "plan-code", + itemId: "QR-001", + }, + { + mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { + assert.equal(ctx, "qr-verify"); + assert.equal(row, "plan-code"); + return "plan-code-qr-verify" as PhaseModelKey; + }, + resolvePhaseModelOverrideFn: async (key) => { + assert.equal(key, "plan-code-qr-verify"); + return "google/gemini-3-pro"; + }, + spawnReviewerFn: async (opts) => { + capturedModelOverride = opts.modelOverride; + return { exitCode: 0, stderr: "", subagentDir: opts.subagentDir }; + }, + }, + ); + + assert.equal(capturedModelOverride, "google/gemini-3-pro"); + }); + + it("passes undefined modelOverride when config is absent", async () => { + let capturedModelOverride: string | undefined; + + await spawnReviewerWithResolvedModel( + { + planDir: "/plan", + subagentDir: "/subagent", + cwd: "/cwd", + extensionPath: "/ext/koan.ts", + phase: "plan-docs", + itemId: "QR-002", + }, + { + mapSpawnContextToPhaseModelKeyFn: () => "plan-docs-qr-verify" as PhaseModelKey, + resolvePhaseModelOverrideFn: async () => undefined, + spawnReviewerFn: async (opts) => { + capturedModelOverride = opts.modelOverride; + return { exitCode: 0, stderr: "", subagentDir: opts.subagentDir }; + }, + }, + ); + + assert.equal(capturedModelOverride, undefined); + }); +}); diff --git a/tests/subagent-model.test.ts b/tests/subagent-model.test.ts new file mode 100644 index 0000000..ee07ccb --- /dev/null +++ b/tests/subagent-model.test.ts @@ -0,0 +1,215 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; + +import { buildSpawnArgs } from "../src/planner/subagent.js"; +import { + ALL_PHASE_MODEL_KEYS, + type PhaseModelKey, +} from "../src/planner/model-phase.js"; +import { + applyGeneralPurposeModel, + applyStrongModel, + initConfigFromActiveModel, +} from "../src/planner/ui/config/model-selection.js"; +import { + GENERAL_PURPOSE_PHASE_MODEL_KEYS, + STRONG_PHASE_MODEL_KEYS, +} from "../src/planner/model-phase.js"; + +// -- buildSpawnArgs: --model flag threading -- + +describe("buildSpawnArgs", () => { + const baseOpts = { + planDir: "/plan", + subagentDir: "/subagent", + extensionPath: "/ext/koan.ts", + cwd: "/working", + }; + + it("omits --model flag when modelOverride is absent", () => { + const args = buildSpawnArgs("architect", "plan-design", "start", baseOpts); + assert.equal(args.includes("--model"), false); + }); + + it("omits --model flag when modelOverride is undefined", () => { + const args = buildSpawnArgs("architect", "plan-design", "start", { + ...baseOpts, + modelOverride: undefined, + }); + assert.equal(args.includes("--model"), false); + }); + + it("includes --model flag and value when modelOverride is set", () => { + const args = buildSpawnArgs("architect", "plan-design", "start", { + ...baseOpts, + modelOverride: "anthropic/claude-opus-4", + }); + assert.ok(args.includes("--model"), "expected --model flag in args"); + const idx = args.indexOf("--model"); + assert.equal(args[idx + 1], "anthropic/claude-opus-4"); + }); + + it("places --model before the prompt (last arg)", () => { + const prompt = "Begin the plan-design phase."; + const args = buildSpawnArgs("architect", "plan-design", prompt, { + ...baseOpts, + modelOverride: "openai/gpt-5", + }); + const modelIdx = args.indexOf("--model"); + const promptIdx = args.indexOf(prompt); + assert.ok(modelIdx >= 0, "--model not found"); + assert.ok(promptIdx >= 0, "prompt not found"); + assert.ok(modelIdx < promptIdx, "--model should appear before prompt"); + }); + + it("places --model after extraFlags", () => { + const args = buildSpawnArgs("reviewer", "qr-plan-design", "Verify.", { + ...baseOpts, + extraFlags: ["--koan-qr-item", "item-42"], + modelOverride: "google/gemini-2-pro", + }); + const qrItemIdx = args.indexOf("--koan-qr-item"); + const modelIdx = args.indexOf("--model"); + assert.ok(qrItemIdx >= 0, "--koan-qr-item not found"); + assert.ok(modelIdx >= 0, "--model not found"); + assert.ok(qrItemIdx < modelIdx, "--model should appear after extra flags"); + }); + + it("preserves all required fixed args regardless of modelOverride", () => { + const args = buildSpawnArgs("developer", "plan-code", "begin", { + ...baseOpts, + modelOverride: "anthropic/claude-sonnet", + }); + assert.ok(args.includes("-p"), "-p flag missing"); + assert.ok(args.includes("-e"), "-e flag missing"); + assert.ok(args.includes("--koan-role"), "--koan-role missing"); + assert.ok(args.includes("--koan-phase"), "--koan-phase missing"); + assert.ok(args.includes("--koan-plan-dir"), "--koan-plan-dir missing"); + assert.ok(args.includes("--koan-subagent-dir"), "--koan-subagent-dir missing"); + }); +}); + +// -- Quick-set utility functions -- + +describe("initConfigFromActiveModel", () => { + it("creates a 20-key config with all keys set to the given model", () => { + const config = initConfigFromActiveModel("anthropic/claude-sonnet"); + assert.equal(Object.keys(config).length, ALL_PHASE_MODEL_KEYS.length); + for (const key of ALL_PHASE_MODEL_KEYS) { + assert.equal(config[key], "anthropic/claude-sonnet", `key ${key} should be set`); + } + }); + + it("produces a config where all values are the same model", () => { + const config = initConfigFromActiveModel("openai/gpt-5"); + const values = Object.values(config); + assert.ok(values.every((v) => v === "openai/gpt-5")); + }); +}); + +describe("applyStrongModel", () => { + it("sets all strong keys to the chosen model, leaving GP keys from existing config", () => { + const existing = initConfigFromActiveModel("openai/gpt-4"); + const result = applyStrongModel("anthropic/claude-opus-4", existing, "openai/gpt-4"); + + for (const key of STRONG_PHASE_MODEL_KEYS) { + assert.equal(result[key], "anthropic/claude-opus-4", `strong key ${key} should be updated`); + } + + for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { + assert.equal(result[key], "openai/gpt-4", `GP key ${key} should be unchanged`); + } + }); + + it("initializes from activeModelId when existingConfig is null", () => { + const result = applyStrongModel("anthropic/claude-opus-4", null, "openai/gpt-5-mini"); + + for (const key of STRONG_PHASE_MODEL_KEYS) { + assert.equal(result[key], "anthropic/claude-opus-4", `strong key ${key} should be updated`); + } + + for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { + assert.equal(result[key], "openai/gpt-5-mini", `GP key ${key} should be initialized from active model`); + } + }); + + it("writes all 20 keys regardless of which keys are strong", () => { + const result = applyStrongModel("some/model", null, "active/model"); + assert.equal(Object.keys(result).length, ALL_PHASE_MODEL_KEYS.length); + }); +}); + +describe("applyGeneralPurposeModel", () => { + it("sets all GP keys to the chosen model, leaving strong keys from existing config", () => { + const existing = initConfigFromActiveModel("anthropic/claude-opus-4"); + const result = applyGeneralPurposeModel("openai/gpt-5-mini", existing, "anthropic/claude-opus-4"); + + for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { + assert.equal(result[key], "openai/gpt-5-mini", `GP key ${key} should be updated`); + } + + for (const key of STRONG_PHASE_MODEL_KEYS) { + assert.equal(result[key], "anthropic/claude-opus-4", `strong key ${key} should be unchanged`); + } + }); + + it("initializes from activeModelId when existingConfig is null", () => { + const result = applyGeneralPurposeModel("openai/gpt-5-mini", null, "anthropic/claude-sonnet"); + + for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { + assert.equal(result[key], "openai/gpt-5-mini", `GP key ${key} should be updated`); + } + + for (const key of STRONG_PHASE_MODEL_KEYS) { + assert.equal(result[key], "anthropic/claude-sonnet", `strong key ${key} should be initialized from active model`); + } + }); + + it("writes all 20 keys regardless of which keys are GP", () => { + const result = applyGeneralPurposeModel("some/model", null, "active/model"); + assert.equal(Object.keys(result).length, ALL_PHASE_MODEL_KEYS.length); + }); +}); + +describe("quick-set from empty config: all-or-none persistence invariant", () => { + it("applyStrongModel from null config produces a 20-key config (all-or-none)", () => { + const result = applyStrongModel("strong/model", null, "active/model"); + const keys = Object.keys(result) as PhaseModelKey[]; + assert.equal(keys.length, ALL_PHASE_MODEL_KEYS.length); + + // Verify every expected key is present + for (const key of ALL_PHASE_MODEL_KEYS) { + assert.ok(key in result, `key "${key}" missing from result`); + assert.equal(typeof result[key], "string"); + assert.ok(result[key].length > 0); + } + }); + + it("applyGeneralPurposeModel from null config produces a 20-key config (all-or-none)", () => { + const result = applyGeneralPurposeModel("gp/model", null, "active/model"); + const keys = Object.keys(result) as PhaseModelKey[]; + assert.equal(keys.length, ALL_PHASE_MODEL_KEYS.length); + + for (const key of ALL_PHASE_MODEL_KEYS) { + assert.ok(key in result, `key "${key}" missing from result`); + } + }); + + it("strong and GP quick-set results are complementary", () => { + const activeModel = "active/model"; + + const strongResult = applyStrongModel("strong/model", null, activeModel); + const gpResult = applyGeneralPurposeModel("gp/model", null, activeModel); + + // Strong keys in strongResult should differ from GP keys + for (const key of STRONG_PHASE_MODEL_KEYS) { + assert.equal(strongResult[key], "strong/model"); + assert.equal(gpResult[key], activeModel); // GP result left strong keys as active + } + + for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { + assert.equal(strongResult[key], activeModel); // strong result left GP keys as active + assert.equal(gpResult[key], "gp/model"); + } + }); +}); diff --git a/tests/widget.test.ts b/tests/widget.test.ts index 9dfa07e..2342df4 100644 --- a/tests/widget.test.ts +++ b/tests/widget.test.ts @@ -50,13 +50,13 @@ function createWidgetHarness(): { describe("formatPlanningHeaderLabel", () => { it("applies compaction in deterministic order", () => { - const phase = "Context gathering"; + const phase = "Plan design"; const status = "CURRENT"; const full = `Planning · ${phase} · ${status}`; const shortStatus = `Planning · ${phase} · CUR`; const noStatus = `Planning · ${phase}`; - const shortPhase = "Planning · Ctx gather"; + const shortPhase = "Planning · Design"; assert.equal(formatPlanningHeaderLabel(phase, status, visibleWidth(full)), full); assert.equal(formatPlanningHeaderLabel(phase, status, visibleWidth(full) - 1), shortStatus); @@ -70,13 +70,14 @@ describe("formatPlanningHeaderLabel", () => { }); describe("WidgetController rendering", () => { - it("renders metadata header and removes phase chips row", () => { + it("renders metadata header with 3-phase layout (no context gathering)", () => { const harness = createWidgetHarness(); try { const lines = harness.render(140); const text = lines.join("\n"); - assert.match(text, /Planning · Context gathering · CURRENT/); + assert.match(text, /Planning · Plan design · CURRENT/); + assert.doesNotMatch(text, /Context gathering/); assert.doesNotMatch(text, /┃ Context gathering ┃/); } finally { harness.destroy(); From 694d90a23dd60e79bf3c16a5d5468db7771c6d73 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 2 Mar 2026 13:41:51 +0700 Subject: [PATCH 031/412] update docs for koan_plan flow and 3-phase widget --- README.md | 32 ++++++++++++++--- design-decisions.md | 79 +++++++++++++++++++---------------------- docs/planning-widget.md | 22 ++++++------ 3 files changed, 76 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index e8c4765..5b89554 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,33 @@ Koan is an opinionated planning workflow extension for the pi coding agent. It c The runtime is split into two modes from the same extension entrypoint: -- **Parent session mode** runs `/koan` commands and orchestrates the workflow. -- **Subagent mode** runs role/phase-specific workflows (architect, QR decomposer, reviewer, fix mode). +- **Parent session mode** registers the `koan_plan` MCP tool and the `/koan-execute`, `/koan-status` commands. The parent orchestrates the full workflow when `koan_plan` is invoked. +- **Subagent mode** runs role/phase-specific workflows (architect, developer, technical writer, QR decomposer, reviewer, fix mode). -The parent controls progression through context capture, plan design, quality review, and iterative fixes. Subagents are isolated processes that communicate through persisted artifacts (`plan.json`, `context.json`, `qr-*.json`) and audit projections. +The parent controls progression through plan design, plan code, plan docs, quality review, and iterative fixes. Subagents are isolated processes that communicate through persisted artifacts (`plan.json`, `qr-*.json`) and audit projections. + +## Invoking the Planner + +Call `koan_plan` as an MCP tool — the LLM invokes it when the user asks to plan a complex task. No parameters are needed: the conversation up to that point is automatically exported to `conversation.jsonl` in the plan directory and becomes the planning context. + +The planning pipeline runs sequentially: + +1. **plan-design** (architect) — reads `conversation.jsonl` to understand intent, explores the codebase, writes `plan.json`. +2. **plan-code** (developer) — reads `plan.json`, populates code intents and changes. +3. **plan-docs** (technical writer) — reads `plan.json` and optionally `conversation.jsonl` for decisions and tradeoffs, writes documentation entries. + +Each phase is followed by a QR (quality review) block: decompose → parallel verify → fix loop, up to `MAX_FIX_ITERATIONS`. + +### conversation.jsonl + +Written once at the start of `koan_plan`. Contains the full session branch as JSONL (one JSON object per line — raw pi `SessionManager` entries, not a plain-text transcript). The plan-design architect and plan-docs writer are told about this file and may `Read` it; other phases work from `plan.json` only. + +### Slash commands + +| Command | Description | +|---|---| +| `/koan-execute` | Execute a koan plan (not yet implemented) | +| `/koan-status` | Show current workflow phase | ## Design Decisions @@ -22,6 +45,7 @@ Key design choices that shape implementation: - **Default-deny permissions**: each phase explicitly allowlists tools; unknown tool/phase access is blocked. - **Disk-backed mutations**: planning mutations are immediately persisted with atomic writes instead of deferred finalize steps. - **Need-to-know prompts**: each subagent only receives the minimum context needed for its task. +- **Passive conversation context**: `conversation.jsonl` is a read-only artifact on disk. No phase programmatically injects it into prompts; agents that need it use the `Read` tool. ## Invariants @@ -34,4 +58,4 @@ The workflow depends on these invariants: ## Boundaries -Current scope focuses on planning and QR orchestration. `/koan execute` is intentionally not implemented yet. +Current scope focuses on planning and QR orchestration. `/koan-execute` is intentionally not implemented yet. diff --git a/design-decisions.md b/design-decisions.md index 54c56b8..4c6c471 100644 --- a/design-decisions.md +++ b/design-decisions.md @@ -46,20 +46,20 @@ from tools: always `throw new Error(msg)` -- never `return { isError: true }`. ### AD-1: Two LLM Interaction Levels -- `sendUserMessage()` in parent session: ONLY for context capture. The - session LLM is the only entity with the conversational understanding. - A fresh LLM reading a serialized transcript loses implicit context. - `spawn()` subagent: for all substantial work (architect, developer, writer, QR decomposer, QR reviewer). - `complete()` from pi-ai: NOT used in koan. No direct LLM calls without agent loop. +- `sendUserMessage()` in parent session: NOT used. Planning is triggered via + the `koan_plan` MCP tool; conversation context is captured via `exportConversation()`. ### AD-2: Self-Loading Extension Pattern Same extension file (extensions/koan.ts) serves both modes: -- **Parent mode** (no --koan-role flag): registers /koan command, tools, - and dispatch. Zero overhead in normal pi sessions. +- **Parent mode** (no --koan-role flag): registers the `koan_plan` MCP tool, + `/koan-execute`, `/koan-status` commands, and workflow dispatch. Zero overhead + in normal pi sessions. - **Subagent mode** (--koan-role present): activates role-specific event hooks (state machine, tool enforcement, step prompts). @@ -78,8 +78,8 @@ to ensure one-shot dispatch. ALL step transitions use the koan_complete_step registered tool. The LLM calls koan_complete_step -> tool execute() returns next step's prompt. -This works in both -p mode and interactive mode. sendUserMessage() -is only used for the initial trigger (/koan plan). +This works in both -p mode and interactive mode. `sendUserMessage()` is not +used; planning is triggered by the LLM invoking the `koan_plan` MCP tool. **KEY CORRECTION**: Early design (Feb 10) considered turn_end + agent_end + sendUserMessage() chaining for step transitions. This was @@ -110,8 +110,9 @@ koan_complete_step now" without emitting an actual tool_call block. Settled names (corrected from earlier iterations): - `koan_complete_step` (was koan_next_step -- renamed to accept `thoughts`) -- `koan_store_context` (was koan_finalize_context) -- `koan_store_plan` was later REMOVED entirely (see AD-14) +- `koan_store_context` — REMOVED (was koan_finalize_context; removed with context-capture phase) +- `koan_store_plan` — REMOVED (see AD-14) +- `koan_plan` — MCP tool replacing the former `/koan plan` slash command - Prompts use "instructions" not "actions" ### AD-7: invoke_after Pattern Is Critical @@ -132,11 +133,10 @@ have zero friction. ### AD-8: Store Tools Need "Not Yet" Guidance -koan_store_context (and formerly koan_store_plan) are always registered -and visible to the LLM even in steps where they should NOT be called. -Their tool descriptions include "DO NOT call this tool until the step -instructions explicitly tell you to." This creates a prohibition/activation -pattern with step prompts. +(koan_store_context was removed with the context-capture phase; koan_store_plan +was removed earlier — see AD-14.) This pattern remains relevant for any +future store-style tools: tool description should include "DO NOT call this tool +until the step instructions explicitly tell you to." ### AD-9: Subagent Progress Tracking @@ -158,18 +158,13 @@ with rich TypeBox descriptions are sufficient for the LLM to discover the schema through tool definitions. This is the "most elegant" approach per user preference. -### AD-12: Context Capture Phases +### AD-12: Context Capture Phases (REMOVED) -Three sub-phases within context capture: - -1. **Drafting**: LLM reflects on conversation. MAY use tools for "high - value" targeted exploration (confirm API signature, check file existence). - DO NOT explore speculatively. Confidence tagging: HIGH (direct evidence) - vs LOW (extrapolating). -2. **Verifying**: Self-check. Completeness, accuracy, phrasing for - downstream agents. No tools except koan_complete_step. -3. **Refining**: Pure tool invocation (koan_store_context). Up to 3 - attempts with validation feedback. +The context-capture phase (draft/verify/refine sub-phases, koan_store_context +tool, context.json artifact) was removed. The parent conversation is now +exported as `conversation.jsonl` at `koan_plan` tool invocation. Phases that +need session context read the file directly via the `Read` tool. See +`src/planner/conversation.ts` for the export implementation. ### AD-13: Default-Deny Tool Permissions @@ -198,10 +193,9 @@ needs evidence that each tool call produces results. ### AD-15: Module Ownership -- Context-capture prompts belong to the "orchestrator" (session.ts / - context-capture.ts) - Plan-design prompts belong to the "architect" (plan-design.ts / prompts/plan-design.ts) +- Conversation export belongs to session.ts / conversation.ts - These are organizational decisions about which module owns which prompts ### AD-16: 6-Step Architect Workflow (plan-design execute) @@ -250,7 +244,7 @@ Step 6: plan mutation tools unlocked. - Chosen on Feb 25 2026 via follow-up deck (`Inline Integrated Section + Divider`). - Rationale: QR is the acceptance loop, not optional telemetry. Rendering it as an inline first-class section prevents the "detached widget" feel and matches how users reason about plan quality over time. - Contract: - - QR is visible during Plan design (and contractually Plan execution), hidden only for Context gathering. + - QR is visible during Plan design, Plan code, and Plan docs (and contractually Plan execution). - Iteration 1 enters `execute` immediately (same stage model as fix iterations); there is no separate `initializing` stage. - Section includes: phase + iter/mode metadata, phase rail, and counters (`done/total/pass/fail/todo`) in a compact metadata block. - Visual treatment uses inline sectioning + divider, not a nested bordered mini-card. @@ -273,9 +267,9 @@ Step 6: plan mutation tools unlocked. ### WorkflowDispatch (dispatch pattern) -Workflow tools (koan_complete_step, koan_store_context) are registered once -at init. Their execute() callbacks read from a mutable dispatch object. -Phases hook/unhook dispatch slots at activation/deactivation time. +Workflow tools (koan_complete_step) are registered once at init. Their +execute() callbacks read from a mutable dispatch object. Phases hook/unhook +dispatch slots at activation/deactivation time. hookDispatch() throws if a slot is already occupied -- prevents silent misrouting when two phases try to claim the same tool. @@ -283,7 +277,7 @@ misrouting when two phases try to claim the same tool. ### PlanRef (mutable reference) All plan mutation tools share a mutable `{ dir: string | null }` set -when /koan plan creates a directory or when --koan-plan-dir is received. +when koan_plan tool creates a directory or when --koan-plan-dir is received. Decouples tool registration (init-time) from directory creation (runtime). ### Pi Registers Tools at \_buildRuntime() @@ -312,7 +306,7 @@ at init; phases restrict access via tool_call blocking at runtime. ### BUG-1: LLM Conflates Tool Instructions with Plan Content -In context capture, the LLM captured tool usage instructions as +In the former context-capture phase, the LLM captured tool usage instructions as constraints (e.g. "Use read tool before modifying files; edit for surgical changes"). These are irrelevant developer instructions, not task constraints. Solution: prompts explicitly state "Only include @@ -383,13 +377,20 @@ koan_qr_get_item, koan_qr_list_items, koan_qr_summary. --- -## Current Implementation State (Feb 13 2026) +## Current Implementation State (Mar 1 2026) Implemented: - [x] Extension entry point with dual-mode detection -- [x] Context capture (3-phase: draft/verify/refine) +- [x] koan_plan MCP tool (replaces /koan plan slash command) +- [x] Conversation export to conversation.jsonl (replaces context-capture phase) - [x] Plan-design architect subagent (6-step workflow) +- [x] Developer role (plan-code phase) +- [x] Technical writer role (plan-docs phase) +- [x] QR decompose subagent +- [x] QR verify subagent (parallel pool, concurrency 6) +- [x] QR gate routing + fix loop (up to MAX_FIX_ITERATIONS) +- [x] Fix mode (architect/developer/writer fix subagents) - [x] 44+ plan mutation/getter tools with TypeBox schemas - [x] Default-deny tool permissions (registry.ts) - [x] WorkflowDispatch + PlanRef patterns @@ -399,12 +400,6 @@ Implemented: Not yet implemented: -- [ ] Developer role (plan-code phase) -- [ ] Technical writer role (plan-docs phase) -- [ ] QR decompose subagent -- [ ] QR verify subagent (parallel) -- [ ] QR gate routing -- [ ] Fix mode (re-spawn with QR failure report) - [ ] State persistence (appendEntry + session_start restore) - [ ] Plan execution workflow (milestone execution) -- [ ] /koan execute command +- [ ] /koan-execute command diff --git a/docs/planning-widget.md b/docs/planning-widget.md index 36c51e4..2bbffb1 100644 --- a/docs/planning-widget.md +++ b/docs/planning-widget.md @@ -39,7 +39,7 @@ The goal is to keep a long-running (1-2h) planning session readable in real time ### 4) QR is a first-class workflow section - QR renders inline in detail pane with divider rule (no detached mini-card border). -- Visible for Plan design (and contractually for Plan execution), hidden only for Context gathering. +- Visible during Plan design, Plan code, and Plan docs (and contractually Plan execution). - QR starts directly in the **`execute`** stage for iteration 1 (non-fix mode); fix iterations reuse the same stage model. - QR block is normalized to a fixed structure: header, phase rail, counters, divider. - Metadata is budgeted to **64 visible chars max** and progressively compacted (`phase/iter/mode` -> `iN/M`, `d/p/f/t`) when width is constrained. @@ -58,17 +58,17 @@ The goal is to keep a long-running (1-2h) planning session readable in real time ## Layout Overview ``` ┌────────────────────────────────────────────────────────────────────────────────┐ -│ Planning · Context gathering · CURRENT 12m 22s │ +│ Planning · Plan design · CURRENT 12m 22s │ │ │ -│ ● Context gathering Current step │ -│ │ DONE Step 2/6: Codebase Exploration │ +│ ● Plan design Current step │ +│ │ CURRENT Step 2/6: Codebase Exploration │ │ │ read internal/rules/CLAUDE.md · 17L/1.2k │ -│ ● Plan design QR | phase:execute · iter 1/6 initial │ -│ │ CURRENT Execute → QR decompose → QR verify │ -│ ○ Plan code done:0/- pass:0 fail:0 todo:- │ -│ │ UPCOMING Subagents queued:0 active:1 done:0 │ -│ ○ Plan docs Plan ID : │ -│ UPCOMING Agent : architect │ +│ ○ Plan code QR | phase:execute · iter 1/6 initial │ +│ │ UPCOMING Execute → QR decompose → QR verify │ +│ ○ Plan docs done:0/- pass:0 fail:0 todo:- │ +│ UPCOMING Subagents queued:0 active:1 done:0 │ +│ Plan ID : │ +│ Agent : architect │ │ Model : openai-codex/gpt-5.3-codex │ │────────────────────────────────────────────────────────────────────────────────│ │ Latest log │ @@ -107,7 +107,7 @@ The goal is to keep a long-running (1-2h) planning session readable in real time Apply in order until it fits: 1. `CURRENT` -> `CUR`, `UPCOMING` -> `UP`, `DONE` unchanged. 2. Drop status chunk (keep `Planning · `). -3. Abbreviate known phases (`Context gathering` -> `Ctx gather`, `Plan design` -> `Design`, `Plan code` -> `Code`, `Plan docs` -> `Docs`). +3. Abbreviate known phases (`Plan design` -> `Design`, `Plan code` -> `Code`, `Plan docs` -> `Docs`). 4. Ellipsize active phase tail (`Planning · `). ### Metadata table alignment From efa5341e44fc1b52e8c115eabe90d917ab76434d Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 2 Mar 2026 14:13:29 +0700 Subject: [PATCH 032/412] Changes to session.ts & model-selection.ts --- src/planner/session.ts | 2 ++ src/planner/ui/config/model-selection.ts | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/src/planner/session.ts b/src/planner/session.ts index b555d5c..ef5c3b5 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -79,6 +79,7 @@ function qrFilePath(planDir: string, phase: WorkPhaseKey): string { function singleSubagentStart(role: string): WidgetUpdate { return { subagentRole: role, + subagentModel: null, subagentParallelCount: 1, subagentQueued: 0, subagentActive: 1, @@ -557,6 +558,7 @@ async function runQRBlock( qrFail: initialFail, qrTodo: initialTodo, subagentRole: "reviewer", + subagentModel: null, subagentParallelCount: QR_POOL_CONCURRENCY, subagentQueued: verifyIds.length, subagentActive: 0, diff --git a/src/planner/ui/config/model-selection.ts b/src/planner/ui/config/model-selection.ts index 7ff013a..e551b3a 100644 --- a/src/planner/ui/config/model-selection.ts +++ b/src/planner/ui/config/model-selection.ts @@ -75,8 +75,7 @@ class ResetConfirmComponent implements Component { return [ this.theme.bold(this.theme.fg("accent", "Reset all model overrides to active model?")), "", - this.theme.fg("muted", " This will clear all 20 phase model overrides."), - this.theme.fg("muted", " Koan will use pi's current active model for all phases."), + this.theme.fg("muted", " This will set all 20 phase model cells to the current active model."), "", this.theme.fg("dim", " Enter to confirm · Escape to cancel"), ]; @@ -195,7 +194,8 @@ export function createModelSelectionComponent( overlay = new ResetConfirmComponent( theme, () => { - void persistAndNotify(null).finally(() => closeOverlay()); + const resetConfig = initConfigFromActiveModel(fallbackActive); + void persistAndNotify(resetConfig).finally(() => closeOverlay()); }, () => closeOverlay(), ); From a8e60323911de4fc95f0109f7085d69fccb54eef Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 2 Mar 2026 16:12:37 +0700 Subject: [PATCH 033/412] qr-verify: group items by group_id for batch verification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace 1-subagent-per-item verification with group-aware dispatch. Items sharing a group_id are verified by a single subagent process, amortizing process startup cost. Changes by layer: - subagent.ts: SpawnReviewerOptions.itemId -> itemIds: string[] - dispatch.ts: parse comma-separated --koan-qr-item flag - qr-verify/phase.ts: dynamic step count (1 + 2*N items per group) with CONTEXT -> N×(ANALYZE+CONFIRM) workflow - qr-verify/prompts.ts: multi-item context listing, position labels - session.ts: group TODO items by group_id before pooling - koan.ts: updated flag description The decompose phase (steps 9-13) already produces group_id assignments. This change consumes that grouping data at verification time. Backward compatible: ungrouped items (group_id=null) become singleton groups, producing identical behavior to the previous 1:1 dispatch. --- extensions/koan.ts | 2 +- src/planner/phases/dispatch.ts | 12 +- src/planner/phases/qr-verify/phase.ts | 135 +++++++---- src/planner/phases/qr-verify/prompts.ts | 74 ++++-- src/planner/session.ts | 56 ++++- src/planner/subagent.ts | 10 +- tests/qr-grouped-verify.test.ts | 305 ++++++++++++++++++++++++ tests/session-model-threading.test.ts | 4 +- 8 files changed, 509 insertions(+), 89 deletions(-) create mode 100644 tests/qr-grouped-verify.test.ts diff --git a/extensions/koan.ts b/extensions/koan.ts index 369eac7..0281cf3 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -48,7 +48,7 @@ export default function koan(pi: ExtensionAPI): void { }); pi.registerFlag("koan-qr-item", { - description: "QR item ID for reviewer subagent", + description: "QR item ID(s) for reviewer subagent (comma-separated for groups)", type: "string", default: "", }); diff --git a/src/planner/phases/dispatch.ts b/src/planner/phases/dispatch.ts index 3762a36..f3e97c6 100644 --- a/src/planner/phases/dispatch.ts +++ b/src/planner/phases/dispatch.ts @@ -201,15 +201,21 @@ export async function dispatchPhase( } if (config.role === "reviewer" && qrWorkPhase) { - const itemId = pi.getFlag("koan-qr-item") as string; - if (!itemId) { + const rawItemFlag = pi.getFlag("koan-qr-item") as string; + if (!rawItemFlag) { logger("Reviewer missing --koan-qr-item flag"); return; } + const itemIds = rawItemFlag.split(",").map((s) => s.trim()).filter(Boolean); + if (itemIds.length === 0) { + logger("Reviewer --koan-qr-item flag is empty after parsing"); + return; + } + const phase = new QRVerifyPhase( pi, - { planDir: config.planDir, itemId, workPhase: qrWorkPhase }, + { planDir: config.planDir, itemIds, workPhase: qrWorkPhase }, dispatch, planRef, logger, diff --git a/src/planner/phases/qr-verify/phase.ts b/src/planner/phases/qr-verify/phase.ts index 185fb97..100daf2 100644 --- a/src/planner/phases/qr-verify/phase.ts +++ b/src/planner/phases/qr-verify/phase.ts @@ -1,5 +1,14 @@ -// QR verify phase -- 3-step reviewer subagent that verifies exactly 1 QR item -// against the plan (CONTEXT -> ANALYZE -> CONFIRM). One subagent per item. +// QR verify phase -- dynamic-step reviewer subagent that verifies 1..N QR items +// against the plan. Workflow: CONTEXT (once) -> N × (ANALYZE + CONFIRM) -> done. +// Items in a group share a single subagent, amortizing process startup cost. +// +// Dynamic step formula: totalSteps = 1 + (2 * numItems) +// Step 1: CONTEXT (load plan, list all assigned items) +// Step 2k: ANALYZE item k (k = 1..N) +// Step 2k+1: CONFIRM item k (record verdict) +// +// Step gating: koan_qr_set_item is blocked until the CONFIRM step for the +// current item (odd-numbered steps >= 3). import { promises as fs } from "node:fs"; import * as path from "node:path"; @@ -18,26 +27,37 @@ import { buildContextStep, buildAnalyzeStep, buildConfirmStep, - type VerifyStep, } from "./prompts.js"; type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; -const TOTAL_STEPS = 3; -const STEP_NAMES: Record = { - 1: "CONTEXT", - 2: "ANALYZE", - 3: "CONFIRM", -}; - interface VerifyState { active: boolean; - step: VerifyStep; - itemId: string; + step: number; + totalSteps: number; + itemIds: string[]; step1Prompt: string | null; systemPrompt: string | null; } +// Map step number to step type and item index. +// Step 1 is CONTEXT. Steps 2..2N+1 alternate ANALYZE/CONFIRM per item. +function stepType(step: number): { kind: "CONTEXT" } | { kind: "ANALYZE"; itemIndex: number } | { kind: "CONFIRM"; itemIndex: number } { + if (step === 1) return { kind: "CONTEXT" }; + const offset = step - 2; // 0-indexed from step 2 + const itemIndex = Math.floor(offset / 2); + const isConfirm = offset % 2 === 1; + return isConfirm ? { kind: "CONFIRM", itemIndex } : { kind: "ANALYZE", itemIndex }; +} + +function stepName(step: number, numItems: number): string { + if (step === 1) return "CONTEXT"; + const info = stepType(step); + if (info.kind === "ANALYZE") return `ANALYZE ${info.itemIndex + 1}/${numItems}`; + if (info.kind === "CONFIRM") return `CONFIRM ${info.itemIndex + 1}/${numItems}`; + return `Step ${step}`; +} + export class QRVerifyPhase { private readonly pi: ExtensionAPI; private readonly planDir: string; @@ -48,11 +68,11 @@ export class QRVerifyPhase { private readonly eventLog: EventLog | undefined; private readonly dispatch: WorkflowDispatch; private readonly planRef: PlanRef; - private item: QRItem | null = null; + private items: QRItem[] = []; constructor( pi: ExtensionAPI, - config: { planDir: string; itemId: string; workPhase: WorkPhaseKey }, + config: { planDir: string; itemIds: string[]; workPhase: WorkPhaseKey }, dispatch: WorkflowDispatch, planRef: PlanRef, log?: Logger, @@ -67,10 +87,14 @@ export class QRVerifyPhase { this.log = log ?? createLogger("QRVerify"); this.eventLog = eventLog; + const numItems = config.itemIds.length; + const totalSteps = 1 + 2 * numItems; + this.state = { active: false, step: 1, - itemId: config.itemId, + totalSteps, + itemIds: config.itemIds, step1Prompt: null, systemPrompt: null, }; @@ -98,12 +122,17 @@ export class QRVerifyPhase { return; } - const item = qrFile.items.find((i) => i.id === this.state.itemId); - if (!item) { - this.log("QR item not found", { itemId: this.state.itemId, phase: this.workPhase }); - return; + // Resolve all item IDs to QRItem objects. + const resolvedItems: QRItem[] = []; + for (const id of this.state.itemIds) { + const item = qrFile.items.find((i) => i.id === id); + if (!item) { + this.log("QR item not found", { itemId: id, phase: this.workPhase }); + return; + } + resolvedItems.push(item); } - this.item = item; + this.items = resolvedItems; let basePrompt: string; try { @@ -114,18 +143,24 @@ export class QRVerifyPhase { return; } - this.state.systemPrompt = buildVerifySystemPrompt(basePrompt, this.workPhase); + this.state.systemPrompt = buildVerifySystemPrompt(basePrompt, this.workPhase, this.items.length); const conversationPath = path.join(this.planDir, "conversation.jsonl"); - this.state.step1Prompt = formatStep(buildContextStep(item, this.workPhase, conversationPath)); + this.state.step1Prompt = formatStep(buildContextStep(this.items, this.workPhase, conversationPath)); this.state.active = true; this.state.step = 1; this.planRef.dir = this.planDir; hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - this.log("Starting QR verify workflow", { itemId: this.state.itemId, phase: this.workPhase, step: 1 }); - await this.eventLog?.emitPhaseStart(TOTAL_STEPS); - await this.eventLog?.emitStepTransition(1, STEP_NAMES[1], TOTAL_STEPS); + this.log("Starting QR verify workflow", { + itemIds: this.state.itemIds, + itemCount: this.items.length, + totalSteps: this.state.totalSteps, + phase: this.workPhase, + step: 1, + }); + await this.eventLog?.emitPhaseStart(this.state.totalSteps); + await this.eventLog?.emitStepTransition(1, "CONTEXT", this.state.totalSteps); } private registerHandlers(): void { @@ -151,11 +186,15 @@ export class QRVerifyPhase { const perm = checkPermission(this.qrPhaseKey, event.toolName); if (!perm.allowed) return { block: true, reason: perm.reason }; - if (this.state.step < 3 && event.toolName === "koan_qr_set_item") { - return { - block: true, - reason: `koan_qr_set_item available in step 3 (current: ${this.state.step})`, - }; + // koan_qr_set_item is only allowed during CONFIRM steps (odd steps >= 3). + if (event.toolName === "koan_qr_set_item") { + const info = stepType(this.state.step); + if (info.kind !== "CONFIRM") { + return { + block: true, + reason: `koan_qr_set_item available only during CONFIRM steps (current: ${stepName(this.state.step, this.items.length)})`, + }; + } } return undefined; @@ -165,31 +204,39 @@ export class QRVerifyPhase { private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { const prev = this.state.step; - if (prev === 3) { + if (prev >= this.state.totalSteps) { this.state.active = false; unhookDispatch(this.dispatch, "onCompleteStep"); await this.eventLog?.emitPhaseEnd("completed"); - this.log("Verification complete", { itemId: this.state.itemId, phase: this.workPhase }); + this.log("Verification complete", { + itemCount: this.items.length, + phase: this.workPhase, + }); return { ok: true, prompt: "Verification complete." }; } - this.state.step = (prev + 1) as VerifyStep; - const stepName = STEP_NAMES[this.state.step]; + this.state.step = prev + 1; + const name = stepName(this.state.step, this.items.length); const prompt = this.buildStepPrompt(this.state.step); - this.log("Step complete, advancing", { from: prev, to: this.state.step, phase: this.workPhase }); - await this.eventLog?.emitStepTransition(this.state.step, stepName, TOTAL_STEPS); + this.log("Step complete, advancing", { + from: prev, + to: this.state.step, + name, + phase: this.workPhase, + }); + await this.eventLog?.emitStepTransition(this.state.step, name, this.state.totalSteps); return { ok: true, prompt }; } - private buildStepPrompt(step: VerifyStep): string { - switch (step) { - case 2: - return formatStep(buildAnalyzeStep(this.item!)); - case 3: - return formatStep(buildConfirmStep(this.item!, this.workPhase)); - default: - return ""; + private buildStepPrompt(step: number): string { + const info = stepType(step); + if (info.kind === "ANALYZE") { + return formatStep(buildAnalyzeStep(this.items[info.itemIndex], info.itemIndex, this.items.length)); + } + if (info.kind === "CONFIRM") { + return formatStep(buildConfirmStep(this.items[info.itemIndex], info.itemIndex, this.items.length, this.workPhase)); } + return ""; } } diff --git a/src/planner/phases/qr-verify/prompts.ts b/src/planner/phases/qr-verify/prompts.ts index 38fcbe7..21313e4 100644 --- a/src/planner/phases/qr-verify/prompts.ts +++ b/src/planner/phases/qr-verify/prompts.ts @@ -1,5 +1,9 @@ -// Prompt guidance for the 3-step QR verify subagent workflow. -// Each reviewer subagent verifies exactly 1 QRItem against the plan. +// Prompt guidance for the dynamic-step QR verify subagent workflow. +// Each reviewer subagent verifies 1..N QRItems (grouped by group_id). +// +// Dynamic step formula: totalSteps = 1 + (2 * numItems) +// Step 1: CONTEXT (once, lists all items) +// Steps 2..2N+1: ANALYZE/CONFIRM pairs per item import { promises as fs } from "node:fs"; import * as os from "node:os"; @@ -14,8 +18,6 @@ import { type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; -export type VerifyStep = 1 | 2 | 3; - function scopeGuidance(item: QRItem): string { const s = item.scope; if (s === "*") { @@ -63,55 +65,72 @@ export async function loadQRVerifySystemPrompt(): Promise { } } -export function buildVerifySystemPrompt(basePrompt: string, phase: WorkPhaseKey): string { +export function buildVerifySystemPrompt(basePrompt: string, phase: WorkPhaseKey, itemCount: number): string { + const itemLabel = itemCount === 1 ? "1 QR item" : `${itemCount} QR items`; return [ basePrompt, "", "---", "", - `WORKFLOW: 3-STEP QR VERIFICATION (${phase})`, + `WORKFLOW: QR VERIFICATION (${phase}, ${itemLabel})`, "", - "You will verify exactly 1 QR item against the plan.", + `You will verify ${itemLabel} against the plan.`, "Step 1 instructions are in the user message below.", "Complete the work described, then call koan_complete_step.", "Put your findings in the `thoughts` parameter of koan_complete_step.", "", - "CRITICAL: Do NOT record a verdict until step 3 (CONFIRM).", - "Analyze thoroughly in step 2 before committing.", + "CRITICAL: Do NOT record a verdict until the CONFIRM step for each item.", + "Analyze thoroughly in the ANALYZE step before committing.", + ].join("\n"); +} + +function formatItemForContext(item: QRItem): string { + return [ + ` ${item.id} [${item.severity}]: ${item.check}`, + ` scope: ${item.scope}`, ].join("\n"); } export function buildContextStep( - item: QRItem, + items: QRItem[], phase: WorkPhaseKey, conversationPath?: string, ): StepGuidance { + const itemLabel = items.length === 1 ? "1 ITEM" : `${items.length} ITEMS`; + const itemSummary = items.map(formatItemForContext).join("\n"); + return { - title: "Step 1: CONTEXT", + title: `Step 1: CONTEXT`, instructions: [ `PHASE: ${phase}`, - "ITEM TO VERIFY:", + `ITEMS TO VERIFY: ${itemLabel}`, "", - "", - ` ${item.id}`, - ` ${item.scope}`, - ` ${item.check}`, - ` ${item.severity}`, - "", + itemSummary, "", ...phaseContextTrigger(phase, conversationPath), ...(phase === "plan-code" ? [] : [""]), - "Understand the check and required evidence before analyzing.", + "Understand the checks and required evidence before analyzing.", ], }; } -export function buildAnalyzeStep(item: QRItem): StepGuidance { +export function buildAnalyzeStep(item: QRItem, itemIndex: number, totalItems: number): StepGuidance { + const positionLabel = totalItems === 1 + ? "" + : ` (item ${itemIndex + 1} of ${totalItems})`; + return { - title: "Step 2: ANALYZE", + title: `ANALYZE ${item.id}${positionLabel}`, instructions: [ scopeGuidance(item), "", + "", + ` ${item.id}`, + ` ${item.scope}`, + ` ${item.check}`, + ` ${item.severity}`, + "", + "", "TASK:", "1. Read relevant entities based on scope", "2. Apply the verification check", @@ -123,9 +142,18 @@ export function buildAnalyzeStep(item: QRItem): StepGuidance { }; } -export function buildConfirmStep(item: QRItem, phase: WorkPhaseKey): StepGuidance { +export function buildConfirmStep( + item: QRItem, + itemIndex: number, + totalItems: number, + phase: WorkPhaseKey, +): StepGuidance { + const positionLabel = totalItems === 1 + ? "" + : ` (item ${itemIndex + 1} of ${totalItems})`; + return { - title: "Step 3: CONFIRM", + title: `CONFIRM ${item.id}${positionLabel}`, instructions: [ `CONFIRMING: ${item.id}`, `SEVERITY: ${item.severity}`, diff --git a/src/planner/session.ts b/src/planner/session.ts index ef5c3b5..f8f62b5 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -543,35 +543,58 @@ async function runQRBlock( } } - const verifyIds = qr.items.filter((i) => i.status === "TODO").map((i) => i.id); + // Group TODO items by group_id for batch verification. + // Items sharing a group_id are verified by a single subagent, amortizing + // process startup cost. Items without group_id are treated as singletons. + const todoItems = qr.items.filter((i) => i.status === "TODO"); + const groups = new Map(); + for (const item of todoItems) { + const gid = item.group_id ?? item.id; + const existing = groups.get(gid); + if (existing) { + existing.push(item.id); + } else { + groups.set(gid, [item.id]); + } + } + const groupEntries = Array.from(groups.entries()); // [groupId, itemIds[]] const totalItems = qr.items.length; + const totalTodoItems = todoItems.length; const preservedPass = qr.items.filter((i) => i.status === "PASS").length; const initialFail = qr.items.filter((i) => i.status === "FAIL").length; - const initialTodo = qr.items.filter((i) => i.status === "TODO").length; widget?.update({ - step: `${phase} qr-verify: 0/${verifyIds.length}`, + step: `${phase} qr-verify: 0/${groupEntries.length} groups (${totalTodoItems} items)`, activity: "", qrTotal: totalItems, qrDone: preservedPass, qrPass: preservedPass, qrFail: initialFail, - qrTodo: initialTodo, + qrTodo: totalTodoItems, subagentRole: "reviewer", subagentModel: null, subagentParallelCount: QR_POOL_CONCURRENCY, - subagentQueued: verifyIds.length, + subagentQueued: groupEntries.length, subagentActive: 0, subagentDone: 0, }); + log("QR verify: grouped items for dispatch", { + phase, + totalItems: totalTodoItems, + groups: groupEntries.length, + groupSizes: groupEntries.map(([gid, ids]) => `${gid}:${ids.length}`), + }); + state.phase = "qr-verify-running"; widget?.update({ qrPhase: "verify" }); let verifyDone = 0; let failedReviewers: string[] = []; - if (verifyIds.length > 0) { + if (groupEntries.length > 0) { + const groupIds = groupEntries.map(([gid]) => gid); + const verifyStatsPoll = setInterval(async () => { try { const raw = await fs.readFile(qrPath, "utf8"); @@ -591,20 +614,27 @@ async function runQRBlock( } }, 2000); + // Build a map from groupId -> itemIds for the pool worker. + const groupItemMap = new Map(groupEntries); + try { let reviewerModel: string | null = null; const result = await pool( - verifyIds, + groupIds, QR_POOL_CONCURRENCY, - async (itemId) => { - const reviewerDir = await createSubagentDir(planDir, `qr-reviewer-${phase}-${itemId}`); + async (groupId) => { + const itemIds = groupItemMap.get(groupId)!; + const dirSuffix = itemIds.length === 1 + ? `qr-reviewer-${phase}-${itemIds[0]}` + : `qr-reviewer-${phase}-group-${groupId}`; + const reviewerDir = await createSubagentDir(planDir, dirSuffix); const r = await spawnReviewerWithResolvedModel({ planDir, subagentDir: reviewerDir, cwd, extensionPath, phase, - itemId, + itemIds, log, }); @@ -619,7 +649,7 @@ async function runQRBlock( (progress) => { verifyDone = progress.done; widget?.update({ - step: `${phase} qr-verify: ${progress.done}/${progress.total}`, + step: `${phase} qr-verify: ${progress.done}/${progress.total} groups`, qrDone: preservedPass + progress.done, qrTotal: totalItems, subagentQueued: progress.queued, @@ -646,7 +676,7 @@ async function runQRBlock( const pass = finalQR.items.filter((i) => i.status === "PASS").length; const fail = finalQR.items.filter((i) => i.status === "FAIL").length; const todo = finalQR.items.filter((i) => i.status === "TODO").length; - const summary = `${phase} QR complete: ${pass} PASS, ${fail} FAIL, ${todo} TODO (${failedReviewers.length} reviewers failed).`; + const summary = `${phase} QR complete: ${pass} PASS, ${fail} FAIL, ${todo} TODO (${failedReviewers.length} reviewer groups failed).`; const passed = fail === 0 && failedReviewers.length === 0; widget?.update({ @@ -659,7 +689,7 @@ async function runQRBlock( qrTodo: todo, subagentQueued: 0, subagentActive: 0, - subagentDone: verifyIds.length, + subagentDone: groupEntries.length, }); return { summary, passed }; } diff --git a/src/planner/subagent.ts b/src/planner/subagent.ts index 608bda6..b4fb0a9 100644 --- a/src/planner/subagent.ts +++ b/src/planner/subagent.ts @@ -53,7 +53,7 @@ export interface SpawnReviewerOptions { cwd: string; extensionPath: string; phase: WorkPhaseKey; - itemId: string; + itemIds: string[]; modelOverride?: string; log?: Logger; } @@ -198,11 +198,15 @@ export function spawnQRDecomposer(opts: SpawnQRDecomposerOptions): Promise { const log = opts.log ?? createLogger("Subagent"); + const itemList = opts.itemIds.join(","); + const prompt = opts.itemIds.length === 1 + ? "Verify the assigned QR item." + : `Verify the ${opts.itemIds.length} assigned QR items.`; return spawnSubagent( "reviewer", `qr-${opts.phase}`, - "Verify the assigned QR item.", - { ...opts, extraFlags: ["--koan-qr-item", opts.itemId] }, + prompt, + { ...opts, extraFlags: ["--koan-qr-item", itemList] }, log, ); } diff --git a/tests/qr-grouped-verify.test.ts b/tests/qr-grouped-verify.test.ts new file mode 100644 index 0000000..4a09ad5 --- /dev/null +++ b/tests/qr-grouped-verify.test.ts @@ -0,0 +1,305 @@ +// Tests for grouped QR verification: grouping logic, step routing, +// prompt generation, and subagent spawn arg threading. + +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; + +import { buildSpawnArgs } from "../src/planner/subagent.js"; +import type { QRItem } from "../src/planner/qr/types.js"; +import { + buildVerifySystemPrompt, + buildContextStep, + buildAnalyzeStep, + buildConfirmStep, +} from "../src/planner/phases/qr-verify/prompts.js"; + +// -- Grouping logic (pure function, extracted from session.ts pattern) -- + +function groupItemsByGroupId(items: QRItem[]): Map { + const groups = new Map(); + for (const item of items) { + const gid = item.group_id ?? item.id; + const existing = groups.get(gid); + if (existing) { + existing.push(item.id); + } else { + groups.set(gid, [item.id]); + } + } + return groups; +} + +function makeItem(id: string, groupId: string | null = null, status: "TODO" | "PASS" | "FAIL" = "TODO"): QRItem { + return { + id, + scope: `milestone:M-001`, + check: `Check for ${id}`, + status, + finding: null, + parent_id: null, + group_id: groupId, + severity: "MUST", + }; +} + +// -- Grouping tests -- + +describe("groupItemsByGroupId", () => { + it("groups items sharing the same group_id", () => { + const items = [ + makeItem("QR-001", "group-a"), + makeItem("QR-002", "group-a"), + makeItem("QR-003", "group-b"), + ]; + const groups = groupItemsByGroupId(items); + + assert.equal(groups.size, 2); + assert.deepEqual(groups.get("group-a"), ["QR-001", "QR-002"]); + assert.deepEqual(groups.get("group-b"), ["QR-003"]); + }); + + it("treats null group_id as singleton (uses item id as group key)", () => { + const items = [ + makeItem("QR-001", null), + makeItem("QR-002", null), + ]; + const groups = groupItemsByGroupId(items); + + assert.equal(groups.size, 2); + assert.deepEqual(groups.get("QR-001"), ["QR-001"]); + assert.deepEqual(groups.get("QR-002"), ["QR-002"]); + }); + + it("handles mixed grouped and ungrouped items", () => { + const items = [ + makeItem("QR-001", "umbrella"), + makeItem("QR-002", "umbrella"), + makeItem("QR-003", null), + makeItem("QR-004", "component-auth"), + makeItem("QR-005", "component-auth"), + makeItem("QR-006", "component-auth"), + ]; + const groups = groupItemsByGroupId(items); + + assert.equal(groups.size, 3); + assert.deepEqual(groups.get("umbrella"), ["QR-001", "QR-002"]); + assert.deepEqual(groups.get("QR-003"), ["QR-003"]); + assert.deepEqual(groups.get("component-auth"), ["QR-004", "QR-005", "QR-006"]); + }); + + it("returns empty map for empty items", () => { + const groups = groupItemsByGroupId([]); + assert.equal(groups.size, 0); + }); + + it("single item with group_id creates group of 1", () => { + const items = [makeItem("QR-001", "solo-group")]; + const groups = groupItemsByGroupId(items); + + assert.equal(groups.size, 1); + assert.deepEqual(groups.get("solo-group"), ["QR-001"]); + }); +}); + +// -- Dynamic step formula tests -- + +describe("dynamic step formula", () => { + it("totalSteps = 1 + 2*N for N items", () => { + assert.equal(1 + 2 * 1, 3); // 1 item: CONTEXT, ANALYZE, CONFIRM + assert.equal(1 + 2 * 3, 7); // 3 items: CONTEXT, 3×(ANALYZE+CONFIRM) + assert.equal(1 + 2 * 5, 11); // 5 items + }); + + it("step routing maps correctly for 3 items", () => { + // Step 1: CONTEXT + // Step 2: ANALYZE item 0 + // Step 3: CONFIRM item 0 + // Step 4: ANALYZE item 1 + // Step 5: CONFIRM item 1 + // Step 6: ANALYZE item 2 + // Step 7: CONFIRM item 2 + + function stepType(step: number): { kind: string; itemIndex?: number } { + if (step === 1) return { kind: "CONTEXT" }; + const offset = step - 2; + const itemIndex = Math.floor(offset / 2); + const isConfirm = offset % 2 === 1; + return isConfirm ? { kind: "CONFIRM", itemIndex } : { kind: "ANALYZE", itemIndex }; + } + + assert.deepEqual(stepType(1), { kind: "CONTEXT" }); + assert.deepEqual(stepType(2), { kind: "ANALYZE", itemIndex: 0 }); + assert.deepEqual(stepType(3), { kind: "CONFIRM", itemIndex: 0 }); + assert.deepEqual(stepType(4), { kind: "ANALYZE", itemIndex: 1 }); + assert.deepEqual(stepType(5), { kind: "CONFIRM", itemIndex: 1 }); + assert.deepEqual(stepType(6), { kind: "ANALYZE", itemIndex: 2 }); + assert.deepEqual(stepType(7), { kind: "CONFIRM", itemIndex: 2 }); + }); + + it("step routing works for single item (backward compat)", () => { + function stepType(step: number): { kind: string; itemIndex?: number } { + if (step === 1) return { kind: "CONTEXT" }; + const offset = step - 2; + const itemIndex = Math.floor(offset / 2); + const isConfirm = offset % 2 === 1; + return isConfirm ? { kind: "CONFIRM", itemIndex } : { kind: "ANALYZE", itemIndex }; + } + + assert.deepEqual(stepType(1), { kind: "CONTEXT" }); + assert.deepEqual(stepType(2), { kind: "ANALYZE", itemIndex: 0 }); + assert.deepEqual(stepType(3), { kind: "CONFIRM", itemIndex: 0 }); + }); +}); + +// -- Prompt generation tests -- + +describe("buildVerifySystemPrompt", () => { + it("includes item count for single item", () => { + const result = buildVerifySystemPrompt("base prompt", "plan-design", 1); + assert.ok(result.includes("1 QR item")); + assert.ok(!result.includes("items")); + }); + + it("includes item count for multiple items", () => { + const result = buildVerifySystemPrompt("base prompt", "plan-code", 5); + assert.ok(result.includes("5 QR items")); + }); + + it("includes phase name", () => { + const result = buildVerifySystemPrompt("base prompt", "plan-docs", 3); + assert.ok(result.includes("plan-docs")); + }); +}); + +describe("buildContextStep", () => { + const items: QRItem[] = [ + makeItem("QR-001", "group-a"), + makeItem("QR-002", "group-a"), + makeItem("QR-003", "group-a"), + ]; + + it("lists all items in context step", () => { + const step = buildContextStep(items, "plan-design"); + const text = step.instructions.join("\n"); + assert.ok(text.includes("QR-001")); + assert.ok(text.includes("QR-002")); + assert.ok(text.includes("QR-003")); + }); + + it("shows correct item count", () => { + const step = buildContextStep(items, "plan-design"); + const text = step.instructions.join("\n"); + assert.ok(text.includes("3 ITEMS")); + }); + + it("shows 1 ITEM for single item", () => { + const step = buildContextStep([items[0]], "plan-design"); + const text = step.instructions.join("\n"); + assert.ok(text.includes("1 ITEM")); + }); +}); + +describe("buildAnalyzeStep", () => { + const item = makeItem("QR-042", "group-x"); + + it("includes item ID and check", () => { + const step = buildAnalyzeStep(item, 0, 3); + const text = step.instructions.join("\n"); + assert.ok(text.includes("QR-042")); + assert.ok(text.includes(item.check)); + }); + + it("includes position label for multi-item groups", () => { + const step = buildAnalyzeStep(item, 1, 5); + assert.ok(step.title.includes("item 2 of 5")); + }); + + it("omits position label for single item", () => { + const step = buildAnalyzeStep(item, 0, 1); + assert.ok(!step.title.includes("item")); + }); +}); + +describe("buildConfirmStep", () => { + const item = makeItem("QR-007", "group-y"); + + it("includes koan_qr_set_item instructions with correct phase and id", () => { + const step = buildConfirmStep(item, 0, 3, "plan-code"); + const text = step.instructions.join("\n"); + assert.ok(text.includes("phase='plan-code'")); + assert.ok(text.includes("id='QR-007'")); + assert.ok(text.includes("status='PASS'")); + assert.ok(text.includes("status='FAIL'")); + }); + + it("includes position label for multi-item groups", () => { + const step = buildConfirmStep(item, 2, 4, "plan-docs"); + assert.ok(step.title.includes("item 3 of 4")); + }); + + it("has invokeAfter guard", () => { + const step = buildConfirmStep(item, 0, 1, "plan-design"); + assert.ok(step.invokeAfter); + assert.ok(step.invokeAfter!.includes("koan_complete_step")); + }); +}); + +// -- Subagent spawn arg tests -- + +describe("spawnReviewer args", () => { + const baseOpts = { + planDir: "/plan", + subagentDir: "/subagent", + extensionPath: "/ext/koan.ts", + cwd: "/working", + }; + + it("passes single item ID via --koan-qr-item for single-item group", () => { + const args = buildSpawnArgs("reviewer", "qr-plan-design", "Verify the assigned QR item.", { + ...baseOpts, + extraFlags: ["--koan-qr-item", "QR-001"], + }); + const idx = args.indexOf("--koan-qr-item"); + assert.ok(idx >= 0); + assert.equal(args[idx + 1], "QR-001"); + }); + + it("passes comma-separated item IDs via --koan-qr-item for multi-item group", () => { + const itemList = "QR-001,QR-002,QR-003"; + const args = buildSpawnArgs("reviewer", "qr-plan-code", "Verify the 3 assigned QR items.", { + ...baseOpts, + extraFlags: ["--koan-qr-item", itemList], + }); + const idx = args.indexOf("--koan-qr-item"); + assert.ok(idx >= 0); + assert.equal(args[idx + 1], "QR-001,QR-002,QR-003"); + }); +}); + +// -- Comma-separated parsing (mirrors dispatch.ts logic) -- + +describe("comma-separated item ID parsing", () => { + function parseItemIds(rawFlag: string): string[] { + return rawFlag.split(",").map((s) => s.trim()).filter(Boolean); + } + + it("parses single item ID", () => { + assert.deepEqual(parseItemIds("QR-001"), ["QR-001"]); + }); + + it("parses multiple comma-separated IDs", () => { + assert.deepEqual(parseItemIds("QR-001,QR-002,QR-003"), ["QR-001", "QR-002", "QR-003"]); + }); + + it("handles whitespace around commas", () => { + assert.deepEqual(parseItemIds("QR-001 , QR-002 , QR-003"), ["QR-001", "QR-002", "QR-003"]); + }); + + it("filters empty strings from trailing comma", () => { + assert.deepEqual(parseItemIds("QR-001,QR-002,"), ["QR-001", "QR-002"]); + }); + + it("returns empty array for empty string", () => { + assert.deepEqual(parseItemIds(""), []); + }); +}); diff --git a/tests/session-model-threading.test.ts b/tests/session-model-threading.test.ts index 6462e8d..1a9c300 100644 --- a/tests/session-model-threading.test.ts +++ b/tests/session-model-threading.test.ts @@ -156,7 +156,7 @@ describe("QR spawn model threading", () => { cwd: "/cwd", extensionPath: "/ext/koan.ts", phase: "plan-code", - itemId: "QR-001", + itemIds: ["QR-001"], }, { mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { @@ -188,7 +188,7 @@ describe("QR spawn model threading", () => { cwd: "/cwd", extensionPath: "/ext/koan.ts", phase: "plan-docs", - itemId: "QR-002", + itemIds: ["QR-002"], }, { mapSpawnContextToPhaseModelKeyFn: () => "plan-docs-qr-verify" as PhaseModelKey, From d147f846d79b65fa8b5df40760c96f8ceee5695b Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 3 Mar 2026 14:07:55 +0700 Subject: [PATCH 034/412] feat: add koan_ask_question tool for subagent-to-parent IPC Enable subagents running in headless -p mode to ask the user questions via file-based IPC. The subagent writes a request to ipc.json in its working directory, polls for a response, and the parent orchestrator detects the request during its existing 2-second poll loop, presents the ask UI, and writes the response back. New files: - lib/ipc.ts: IPC types and atomic read/write/delete helpers - tools/ask.ts: koan_ask_question tool with blocking poll loop - ui/ask/: ask UI components copied from pi-ask-tool-extension Modified files: - lib/dispatch.ts: SubagentRef type (mirrors PlanRef pattern) - tools/index.ts: thread SubagentRef through registerAllTools - koan.ts: create and wire SubagentRef - lib/permissions.ts: grant koan_ask_question to work phases - session.ts: pollWithIpcDetection helper, handleAskRequest, thread ui - lib/audit.ts: add koan_ask_question to KOAN_SHAPES --- PLAN.md | 367 ++++++++++++++++++ extensions/koan.ts | 6 +- src/planner/lib/audit.ts | 1 + src/planner/lib/dispatch.ts | 11 + src/planner/lib/ipc.ts | 125 +++++++ src/planner/lib/permissions.ts | 3 + src/planner/session.ts | 169 +++++++-- src/planner/tools/ask.ts | 241 ++++++++++++ src/planner/tools/index.ts | 8 +- src/planner/ui/ask/ask-inline-note.ts | 65 ++++ src/planner/ui/ask/ask-inline-ui.ts | 221 +++++++++++ src/planner/ui/ask/ask-logic.ts | 98 +++++ src/planner/ui/ask/ask-tabs-ui.ts | 512 ++++++++++++++++++++++++++ 13 files changed, 1801 insertions(+), 26 deletions(-) create mode 100644 PLAN.md create mode 100644 src/planner/lib/ipc.ts create mode 100644 src/planner/tools/ask.ts create mode 100644 src/planner/ui/ask/ask-inline-note.ts create mode 100644 src/planner/ui/ask/ask-inline-ui.ts create mode 100644 src/planner/ui/ask/ask-logic.ts create mode 100644 src/planner/ui/ask/ask-tabs-ui.ts diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..cdc5063 --- /dev/null +++ b/PLAN.md @@ -0,0 +1,367 @@ +# Plan: Subagent Ask Questions via File-Based IPC + +## Context + +### Problem + +Subagents run as headless `pi -p` child processes with no UI access (`ctx.hasUI = false`). When a subagent needs user input during planning — choosing between architectural alternatives, clarifying scope — it has no mechanism to pause, ask the user, and resume with the answer. + +### Design Decisions + +**Single `ipc.json` file per subagent directory.** Both request and response live in one file with `request` and `response` keys. Temporal ownership is safe: the subagent creates the file and then blocks (only reads during the wait), so the parent is the sole writer during the response window. A two-file model (request.json + response.json) provides structural ownership at the cost of cleanup complexity and an extra file per interaction. The single-file model is simpler and sufficient because the subagent's blocking poll guarantees no concurrent writes. + +**Tool schema mirrors pi-ask-tool-extension exactly.** The `koan_ask_question` tool accepts the same `{ questions: [{ id, question, options, multi?, recommended? }] }` schema as the existing `ask` tool. LLMs trained on the ask tool schema produce correct calls without schema-specific prompt engineering. + +**Ask UI code copied from pi-ask-tool-extension, not imported.** The pi-ask-tool-extension package is globally installed as a pi extension — it is not in koan's `node_modules` and cannot be imported. The four source files (~1133 lines) are copied into `src/planner/ui/ask/`. All external dependencies (`@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`) are already available in koan's node_modules. + +**Permission gating via existing PHASE_PERMISSIONS, not conditional registration.** Pi snapshots all tools at init time (`_buildRuntime()`). Tools cannot be added or removed after init. The existing default-deny `PHASE_PERMISSIONS` map in `permissions.ts` controls runtime access. Adding `koan_ask_question` to the three work-phase Sets (`plan-design`, `plan-code`, `plan-docs`) grants access to subagents in those phases. In parent mode, no phase is active, so the tool is blocked automatically. + +**SubagentRef pattern mirrors PlanRef.** Tool registration happens at init when the subagent directory is unknown. A mutable `SubagentRef = { dir: string | null }` created at init is populated at `before_agent_start` when CLI flags are available. The tool reads `subagentRef.dir` at execute time. This matches the established `PlanRef` indirection pattern in `dispatch.ts`. + +**Non-error returns for cancellation and abort.** When the user cancels (Escape) or the signal aborts, the tool returns a descriptive non-error message ("The user declined to answer. Proceed with your best judgment."). Error returns cause LLMs to halt or retry; non-error returns guide the LLM to continue productively. + +**Parent detects requests inside existing setInterval poll loops.** The parent's 2-second poll callback in `session.ts` already reads `state.json` for widget updates. Adding an `ipc.json` read to the same callback avoids a separate polling mechanism. A `pendingRequestId` guard variable prevents re-entrant handling — JavaScript's `setInterval` fires regardless of whether the previous async callback completed, so without the guard, every 2-second tick during the user's think-time would re-detect the same request. + +### Constraints + +- Pi snapshots tools at init; all tools must be registered unconditionally before `_buildRuntime()`. +- Subagents run in `-p` mode (print mode) with stdin ignored and stdout/stderr piped to log files — no interactive I/O. +- The parent orchestrator has `ctx.ui` access (confirmed: `session.ts` creates `WidgetController` from `ctx.ui`). +- Atomic file writes use the established tmp+rename pattern (`writeFile(tmp) → rename(tmp, target)`). +- The EventLog heartbeat (10-second `setInterval`) continues during the subagent's blocking poll because `await sleep(500)` yields to the Node.js event loop. `state.json` keeps updating, so the parent sees the subagent as alive. + +### Out of Scope (Deferred) + +- Timeout for parent crash detection — the user is at the terminal and will notice; adding a configurable timeout is a follow-up. +- Process liveness check before showing ask UI — low severity edge case (subagent exits between writing request and parent detecting it). +- Multi-subagent concurrent questions — work phases run sequentially; QR phases are excluded from permissions. + +## Implementation + +### ipc.json Schema + +```typescript +// Types live in src/planner/lib/ipc.ts. +// The schema is general-purpose: `type` discriminant supports future request +// types beyond "ask-question" without envelope changes. + +interface IpcFile { + request: IpcRequest; + response: IpcResponse | null; // null while awaiting parent response +} + +interface IpcRequest { + id: string; // crypto.randomUUID() — correlates request to response + type: "ask-question"; // discriminant for routing; extensible to future types + createdAt: string; // ISO 8601 timestamp + payload: AskQuestionPayload; +} + +interface AskQuestionPayload { + questions: Array<{ + id: string; + question: string; + options: Array<{ label: string }>; + multi?: boolean; + recommended?: number; // 0-indexed + }>; +} + +interface IpcResponse { + id: string; // must match request.id + respondedAt: string; // ISO 8601 timestamp + cancelled: boolean; // true when user presses Escape + payload: AskAnswerPayload | null; // null when cancelled +} + +interface AskAnswerPayload { + answers: Array<{ + id: string; // matches question id + selectedOptions: string[]; + customInput?: string; // populated when user selects "Other" + }>; +} +``` + +### NEW: `src/planner/lib/ipc.ts` — IPC File I/O Primitives + +Atomic read/write/delete helpers for `ipc.json`. Both the subagent tool and the parent session use these functions. The atomic write pattern (tmp file → rename) matches `EventLog.writeState()` in `audit.ts`. + +**Functions:** +- `writeIpcFile(dir, data)` — atomic write via `.ipc.tmp.json` → `ipc.json` rename +- `readIpcFile(dir)` → `IpcFile | null` — returns null on missing file or parse error (treat parse error as "not ready" to handle partial writes on non-POSIX systems) +- `ipcFileExists(dir)` → `boolean` — fast `fs.access` check without parsing +- `deleteIpcFile(dir)` — removes `ipc.json` and any lingering `.ipc.tmp.json`; swallows ENOENT +- `createAskRequest(payload)` → `IpcFile` — creates file structure with `crypto.randomUUID()` id and `response: null` +- `createAskResponse(requestId, payload)` → `IpcResponse` — response with `cancelled: false` +- `createCancelledResponse(requestId)` → `IpcResponse` — response with `cancelled: true`, `payload: null` + +All types are exported for use by both subagent-side (`tools/ask.ts`) and parent-side (`session.ts`). + +### NEW: `src/planner/tools/ask.ts` — koan_ask_question Tool + +Registers `koan_ask_question` with the pi extension API. The tool schema uses TypeBox definitions identical to pi-ask-tool-extension. Imports `SubagentRef` from `../lib/dispatch.js` (not defined here — it lives in `dispatch.ts` alongside `PlanRef`). + +**Tool execute flow:** + +The entire poll loop is wrapped in a single `try/finally` that calls `deleteIpcFile(dir)`. This guarantees cleanup on all exit paths — success, cancellation, abort, and file disappearance — without requiring per-path deletion logic. + +1. Guard: if `subagentRef.dir` is null, return error (not in subagent context). +2. Guard: if `ipc.json` already exists, return error (one request at a time). +3. Create `IpcFile` via `createAskRequest(payload)`, write atomically. +4. Register `signal.addEventListener("abort", onAbort, { once: true })` for instant abort response. +5. Enter poll loop inside `try`: `while (!aborted) { await sleep(500); check signal; read ipc.json; if response !== null && response.id matches: break }`. +6. On response with `cancelled: false`: build `QuestionResult[]`, format via `buildSessionContent()`, return as tool result. (`finally` handles cleanup.) +7. On response with `cancelled: true`: return "The user declined to answer." (`finally` handles cleanup.) +8. On abort: return "The question was aborted." (`finally` handles cleanup.) +9. On file disappearing mid-poll (deleted externally): return "The question was cancelled." (`finally` handles cleanup, swallows ENOENT.) + +**Result formatting** mirrors pi-ask-tool-extension's `buildAskSessionContent()`: +``` +User answers: +auth: JWT + +Answer context: +Question 1 (auth) +Prompt: Which authentication model? +Options: + 1. JWT + 2. Session-based +Response: + Selected: JWT +``` + +### NEW: `src/planner/ui/ask/` — Copied Ask UI Components (4 files) + +Copy these files from `pi-ask-tool-extension/src/` (at `/Users/lmergen/.npm-global/lib/node_modules/pi-ask-tool-extension/src/`): + +1. **`ask-logic.ts`** (~98 lines) — `AskQuestion`, `AskOption`, `AskSelection` types; `OTHER_OPTION` constant; `buildSingleSelectionResult()`, `buildMultiSelectionResult()`, `appendRecommendedTagToOptionLabels()`. +2. **`ask-inline-note.ts`** (~65 lines) — Inline note rendering helpers. Uses `wrapTextWithAnsi` from `@mariozechner/pi-tui`. +3. **`ask-inline-ui.ts`** (~221 lines) — Single-question single-select UI. Renders cursor navigation (↑↓), inline note editing (Tab), submit (Enter) via `ui.custom()`. +4. **`ask-tabs-ui.ts`** (~512 lines) — Multi-question/multi-select tabbed UI. Tab bar (← Q1 Q2 ... ✓ Submit →), per-question option lists, Submit review tab via `ui.custom()`. + +**Import path requirements:** +- Relative import extensions use `.js` suffix: `"./ask-logic"` → `"./ask-logic.js"` (Node16 module resolution requires `.js` extensions in TypeScript source). +- Same for `"./ask-inline-note"` → `"./ask-inline-note.js"`. +- External dependencies (`@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`) resolve from koan's node_modules. + +### MODIFY: `src/planner/lib/dispatch.ts` — Add SubagentRef + +`SubagentRef` and `createSubagentRef()` live alongside `PlanRef` and `createPlanRef()` — both are mutable-ref infrastructure primitives that decouple static tool registration from runtime directory resolution. + +```diff ++// Decouples tool registration (init-time) from subagent directory ++// resolution (runtime, after flags available). Same indirection ++// pattern as PlanRef. ++export interface SubagentRef { ++ dir: string | null; ++} ++ ++export function createSubagentRef(): SubagentRef { ++ return { dir: null }; ++} +``` + +### MODIFY: `src/planner/tools/index.ts` — Thread SubagentRef + +```diff ++import { registerAskTools } from "./ask.js"; ++import type { SubagentRef } from "../lib/dispatch.js"; ++export type { SubagentRef } from "../lib/dispatch.js"; ++export { createSubagentRef } from "../lib/dispatch.js"; + + export function registerAllTools( + pi: ExtensionAPI, + planRef: PlanRef, + dispatch: WorkflowDispatch, ++ subagentRef: SubagentRef, + ): void { + registerWorkflowTools(pi, dispatch); + registerPlanGetterTools(pi, planRef); + registerPlanSetterTools(pi, planRef); + registerPlanDesignEntityTools(pi, planRef); + registerPlanCodeEntityTools(pi, planRef); + registerPlanStructureEntityTools(pi, planRef); + registerQRTools(pi, planRef); ++ registerAskTools(pi, subagentRef); + } +``` + +Note: `SubagentRef` is defined in `lib/dispatch.ts` (alongside `PlanRef`), not in `tools/ask.ts`. `tools/index.ts` re-exports it for convenience, matching the existing re-export pattern for `PlanRef`. + +### MODIFY: `extensions/koan.ts` — Create and Wire SubagentRef + +```diff +-import { registerAllTools, createDispatch, createPlanRef } from "../src/planner/tools/index.js"; ++import { registerAllTools, createDispatch, createPlanRef, createSubagentRef } from "../src/planner/tools/index.js"; + + const dispatch = createDispatch(); + const planRef = createPlanRef(); ++ const subagentRef = createSubagentRef(); + +- registerAllTools(pi, planRef, dispatch); ++ registerAllTools(pi, planRef, dispatch, subagentRef); + + // In before_agent_start, inside `if (config.subagentDir)`: ++ subagentRef.dir = config.subagentDir; +``` + +The `subagentRef.dir = config.subagentDir` assignment goes immediately after the existing `eventLog = new EventLog(...)` line (L88), inside the same `if (config.subagentDir)` block. In parent mode, `subagentRef.dir` remains null, and the tool's execute returns an error. + +### MODIFY: `src/planner/lib/permissions.ts` — Grant Access to Work Phases + +```diff + [ + "plan-design", + new Set([ + "koan_complete_step", ++ "koan_ask_question", + ...PLAN_GETTER_TOOLS_LIST, + ...PLAN_SETTER_TOOLS_LIST, + ...PLAN_DESIGN_ENTITY_TOOLS, + ]), + ], + [ + "plan-code", + new Set([ + "koan_complete_step", ++ "koan_ask_question", + ...PLAN_GETTER_TOOLS_LIST, + ...PLAN_CHANGE_TOOLS_LIST, + "koan_set_intent", + ]), + ], + [ + "plan-docs", + new Set([ + "koan_complete_step", ++ "koan_ask_question", + ...PLAN_GETTER_TOOLS_LIST, + "koan_set_change_doc_diff", + "koan_set_change_comments", +``` + +QR phases (`qr-plan-design`, `qr-plan-code`, `qr-plan-docs`) omit `koan_ask_question` — reviewers do not ask questions. + +### MODIFY: `src/planner/session.ts` — Parent-Side Request Detection + +**A. New imports:** +```typescript +import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; +import { readIpcFile, writeIpcFile, createAskResponse, createCancelledResponse, type IpcFile } from "./lib/ipc.js"; +import { askSingleQuestionWithInlineNote } from "./ui/ask/ask-inline-ui.js"; +import { askQuestionsWithTabs } from "./ui/ask/ask-tabs-ui.js"; +import type { AskQuestion } from "./ui/ask/ask-logic.js"; +``` + +**B. New `handleAskRequest()` function** (module-level, alongside `runPlanningPhase`): + +Receives the parent's `ExtensionUIContext` and the parsed `IpcFile`. Routes to the appropriate ask UI based on question count and multi-select: +- Single question, single-select → `askSingleQuestionWithInlineNote(ui, question)` +- Single question, multi-select → `askQuestionsWithTabs(ui, [question])` +- Multiple questions → `askQuestionsWithTabs(ui, questions)` + +Returns an `IpcResponse` (either answered or cancelled). On any exception from the UI layer, returns a cancelled response so the subagent unblocks. + +**C. New `pollWithIpcDetection()` helper** (extracts the common poll-with-request-detection pattern): + +Both the work poll (~L335) and the fix poll (~L737) share the same request detection logic. A shared helper avoids duplication: + +```typescript +import type { LogLine } from "./lib/audit.js"; + +// Encapsulates the poll-with-request-detection pattern used by both +// the work poll loop and the fix poll loop. Returns a setInterval ID. +function pollWithIpcDetection( + subagentDir: string, + widget: WidgetController | null, + ui: ExtensionUIContext | null, + stepPrefix: string, + updateFromProjection: (p: Projection, logs: LogLine[]) => void, +): ReturnType { + let pendingRequestId: string | null = null; + + return setInterval(async () => { + // Existing: read projection and update widget + const [projection, logs] = await Promise.all([ + readProjection(subagentDir), + readRecentLogs(subagentDir), + ]); + if (projection) { + updateFromProjection(projection, logs); + } + + // IPC request detection — skip if already handling a request or no UI + if (pendingRequestId || !ui) return; + + const ipc = await readIpcFile(subagentDir); + if (!ipc || !ipc.request || ipc.response !== null) return; + + pendingRequestId = ipc.request.id; + try { + widget?.update({ + step: `${stepPrefix}: waiting for user input...`, + activity: ipc.request.payload.questions[0]?.question ?? "", + }); + + const response = await handleAskRequest(ui, ipc); + const updated: IpcFile = { request: ipc.request, response }; + await writeIpcFile(subagentDir, updated); + } catch { + // On error, write cancelled response so subagent unblocks. + // The inner try-catch guards against I/O failures during error + // recovery — an unguarded throw here would propagate as an + // unhandled async rejection in the setInterval callback, + // crashing the parent process (Node.js ≥15 default behavior). + try { + const cancelled = createCancelledResponse(ipc.request.id); + await writeIpcFile(subagentDir, { request: ipc.request, response: cancelled }); + } catch { + // I/O failed during error recovery; subagent remains blocked + // until parent terminates. No further action possible. + } + } finally { + pendingRequestId = null; + } + }, 2000); +} +``` + +**D. Thread `ui` through function signatures:** + +- `runPlanningPhase(phase, planDir, cwd, extensionPath, state, log, widget)` → add `ui: ExtensionUIContext | null` +- `runPhaseWithQR(phase, planDir, cwd, extensionPath, state, log, widget)` → add `ui: ExtensionUIContext | null` +- Call site in `plan()`: pass `ctx.hasUI ? ctx.ui : null` + +**E. Work poll loop (~L335):** +The work poll uses `pollWithIpcDetection(subagentDir, widget, ui, phase.key, ...)`. + +**F. Fix poll loop (~L737):** +The fix poll uses `pollWithIpcDetection(fixDir, widget, ui, \`${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}\`, ...)`. + +### MODIFY: `src/planner/lib/audit.ts` — Log Formatting + +Add `koan_ask_question` to the `KOAN_SHAPES` object for audit log display: + +```typescript +koan_ask_question: { keys: ["questions"], arrays: ["questions"], highValue: true }, +``` + +## Quality Checklist + +- [ ] 01-naming-and-types (design-mode): `SubagentRef` mirrors `PlanRef` naming; `IpcFile`/`IpcRequest`/`IpcResponse` model the domain; `handleAskRequest` describes behavior +- [ ] 02-structure-and-composition (design-mode): `pollWithIpcDetection` extracts shared logic from two poll loops; `handleAskRequest` is single-responsibility; error handling wraps UI calls with cancelled-response fallback +- [ ] 06-module-and-dependencies (design-mode): `lib/ipc.ts` is a pure I/O module with no UI dependencies; `tools/ask.ts` depends on `lib/ipc.ts` and `lib/dispatch.ts` (downward); `session.ts` depends on both `lib/ipc.ts` and `ui/ask/` (same level); no circular deps; `SubagentRef` lives in `lib/dispatch.ts` not in tools layer +- [ ] 07-cross-file-consistency (design-mode): Atomic write pattern matches `EventLog.writeState()`; mutable ref pattern matches `PlanRef`/`WorkflowDispatch` in `lib/dispatch.ts`; permission gating matches existing `PHASE_PERMISSIONS` entries; tool description style matches existing koan tools; error recovery in setInterval callbacks matches `verifyStatsPoll` guarded-catch pattern + +## Execution Protocol + +``` +1. delegate @agent-developer: implement per this plan file +2. delegate @agent-quality-reviewer: verify against plan + ~/.claude/conventions/code-quality/ (code-mode) + +When delegating, pass this plan file path. Supplement only with: +- rationale for decisions not captured in plan +- business constraints +- technical prerequisites the agent cannot infer +``` diff --git a/extensions/koan.ts b/extensions/koan.ts index 0281cf3..ec475a6 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -9,7 +9,7 @@ import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-age import { createSession } from "../src/planner/session.js"; import { detectSubagentMode, dispatchPhase } from "../src/planner/phases/dispatch.js"; -import { registerAllTools, createDispatch, createPlanRef } from "../src/planner/tools/index.js"; +import { registerAllTools, createDispatch, createPlanRef, createSubagentRef } from "../src/planner/tools/index.js"; import { createLogger } from "../src/utils/logger.js"; import { EventLog, extractToolEvent } from "../src/planner/lib/audit.js"; import { openKoanConfig } from "../src/planner/ui/config/menu.js"; @@ -64,8 +64,9 @@ export default function koan(pi: ExtensionAPI): void { // blocking at runtime. const dispatch = createDispatch(); const planRef = createPlanRef(); + const subagentRef = createSubagentRef(); - registerAllTools(pi, planRef, dispatch); + registerAllTools(pi, planRef, dispatch, subagentRef); // Subagent detection runs at before_agent_start (flags // are unavailable during init). @@ -87,6 +88,7 @@ export default function koan(pi: ExtensionAPI): void { if (config.subagentDir) { eventLog = new EventLog(config.subagentDir, config.role, config.phase, currentModelId(ctx)); await eventLog.open(); + subagentRef.dir = config.subagentDir; // Capture all tool results for the audit trail. Graduated detail: // file paths for read/edit/write, binary name for bash, full diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index 1d2d670..12191ca 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -443,6 +443,7 @@ const KOAN_SHAPES: Record = { koan_qr_get_item: { keys: ["phase", "id"], getter: true }, koan_qr_list_items: { keys: ["phase", "status"], getter: true }, koan_qr_summary: { keys: ["phase"], getter: true }, + koan_ask_question: { keys: ["questions"], arrays: ["questions"], highValue: true }, }; // Reads the tail of events.jsonl and returns structured log entries. diff --git a/src/planner/lib/dispatch.ts b/src/planner/lib/dispatch.ts index e9f935e..b978d87 100644 --- a/src/planner/lib/dispatch.ts +++ b/src/planner/lib/dispatch.ts @@ -31,6 +31,17 @@ export function createPlanRef(): PlanRef { return { dir: null }; } +// Decouples tool registration (init-time) from subagent directory +// resolution (runtime, after flags available). Same indirection +// pattern as PlanRef. +export interface SubagentRef { + dir: string | null; +} + +export function createSubagentRef(): SubagentRef { + return { dir: null }; +} + // Sets a dispatch slot. Throws if the slot is already occupied -- // prevents silent misrouting when two phases attempt to claim // the same tool. diff --git a/src/planner/lib/ipc.ts b/src/planner/lib/ipc.ts new file mode 100644 index 0000000..aaa14ee --- /dev/null +++ b/src/planner/lib/ipc.ts @@ -0,0 +1,125 @@ +// File-based IPC between subagent and parent session. +// A single ipc.json file per subagent directory holds both the request and +// response. Atomic writes (tmp-rename) prevent partial reads. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; +import * as crypto from "node:crypto"; + +// -- Types -- + +export interface IpcFile { + request: IpcRequest; + response: IpcResponse | null; // null while awaiting parent response +} + +export interface IpcRequest { + id: string; // crypto.randomUUID() — correlates request to response + type: "ask-question"; // discriminant for routing; extensible to future types + createdAt: string; // ISO 8601 timestamp + payload: AskQuestionPayload; +} + +export interface AskQuestionPayload { + questions: Array<{ + id: string; + question: string; + options: Array<{ label: string }>; + multi?: boolean; + recommended?: number; // 0-indexed + }>; +} + +export interface IpcResponse { + id: string; // must match request.id + respondedAt: string; // ISO 8601 timestamp + cancelled: boolean; // true when user presses Escape + payload: AskAnswerPayload | null; // null when cancelled +} + +export interface AskAnswerPayload { + answers: Array<{ + id: string; // matches question id + selectedOptions: string[]; + customInput?: string; // populated when user selects "Other" + }>; +} + +// -- File paths -- + +const IPC_FILE = "ipc.json"; +const IPC_TMP_FILE = ".ipc.tmp.json"; + +// -- I/O helpers -- + +// Atomic write: .ipc.tmp.json → ipc.json rename. +export async function writeIpcFile(dir: string, data: IpcFile): Promise { + const tmp = path.join(dir, IPC_TMP_FILE); + const target = path.join(dir, IPC_FILE); + await fs.writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8"); + await fs.rename(tmp, target); +} + +// Returns null on missing file or parse error. +// Treats parse errors as "not ready" to handle partial writes on non-POSIX systems. +export async function readIpcFile(dir: string): Promise { + try { + const raw = await fs.readFile(path.join(dir, IPC_FILE), "utf8"); + return JSON.parse(raw) as IpcFile; + } catch { + return null; + } +} + +// Fast existence check without parsing. +export async function ipcFileExists(dir: string): Promise { + try { + await fs.access(path.join(dir, IPC_FILE)); + return true; + } catch { + return false; + } +} + +// Removes ipc.json and any lingering .ipc.tmp.json; swallows ENOENT. +export async function deleteIpcFile(dir: string): Promise { + for (const name of [IPC_FILE, IPC_TMP_FILE]) { + try { + await fs.unlink(path.join(dir, name)); + } catch (err: unknown) { + if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err; + } + } +} + +// -- Factory helpers -- + +export function createAskRequest(payload: AskQuestionPayload): IpcFile { + return { + request: { + id: crypto.randomUUID(), + type: "ask-question", + createdAt: new Date().toISOString(), + payload, + }, + response: null, + }; +} + +export function createAskResponse(requestId: string, payload: AskAnswerPayload): IpcResponse { + return { + id: requestId, + respondedAt: new Date().toISOString(), + cancelled: false, + payload, + }; +} + +export function createCancelledResponse(requestId: string): IpcResponse { + return { + id: requestId, + respondedAt: new Date().toISOString(), + cancelled: true, + payload: null, + }; +} diff --git a/src/planner/lib/permissions.ts b/src/planner/lib/permissions.ts index a23faca..90c3e06 100644 --- a/src/planner/lib/permissions.ts +++ b/src/planner/lib/permissions.ts @@ -103,6 +103,7 @@ export const PHASE_PERMISSIONS: ReadonlyMap> = "plan-design", new Set([ "koan_complete_step", + "koan_ask_question", ...PLAN_GETTER_TOOLS_LIST, ...PLAN_SETTER_TOOLS_LIST, ...PLAN_DESIGN_ENTITY_TOOLS, @@ -112,6 +113,7 @@ export const PHASE_PERMISSIONS: ReadonlyMap> = "plan-code", new Set([ "koan_complete_step", + "koan_ask_question", ...PLAN_GETTER_TOOLS_LIST, ...PLAN_CHANGE_TOOLS_LIST, "koan_set_intent", @@ -121,6 +123,7 @@ export const PHASE_PERMISSIONS: ReadonlyMap> = "plan-docs", new Set([ "koan_complete_step", + "koan_ask_question", ...PLAN_GETTER_TOOLS_LIST, "koan_set_change_doc_diff", "koan_set_change_comments", diff --git a/src/planner/session.ts b/src/planner/session.ts index f8f62b5..a0ec935 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -5,7 +5,7 @@ import { promises as fs } from "node:fs"; import * as path from "node:path"; -import type { AgentToolResult, ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent"; +import type { AgentToolResult, ExtensionAPI, ExtensionCommandContext, ExtensionContext, ExtensionUIContext } from "@mariozechner/pi-coding-agent"; import { exportConversation } from "./conversation.js"; import { createInitialState, initializePlanState, type WorkflowState } from "./state.js"; @@ -25,7 +25,7 @@ import { } from "./subagent.js"; import { createLogger, setLogDir, type Logger } from "../utils/logger.js"; import { createSubagentDir } from "../utils/progress.js"; -import { readProjection, readRecentLogs, type Projection } from "./lib/audit.js"; +import { readProjection, readRecentLogs, type Projection, type LogLine } from "./lib/audit.js"; import type { WorkflowDispatch, PlanRef } from "./lib/dispatch.js"; import { pool } from "./lib/pool.js"; import type { QRFile } from "./qr/types.js"; @@ -38,6 +38,17 @@ import { type SpawnContext, } from "./model-resolver.js"; import type { PhaseRow } from "./model-phase.js"; +import { + readIpcFile, + writeIpcFile, + createAskResponse, + createCancelledResponse, + type IpcFile, + type IpcResponse, +} from "./lib/ipc.js"; +import { askSingleQuestionWithInlineNote } from "./ui/ask/ask-inline-ui.js"; +import { askQuestionsWithTabs } from "./ui/ask/ask-tabs-ui.js"; +import type { AskQuestion } from "./ui/ask/ask-logic.js"; type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; @@ -170,6 +181,107 @@ export async function spawnReviewerWithResolvedModel( return await spawnFn({ ...opts, modelOverride }); } +// Routes an IpcFile ask request to the appropriate UI component and returns +// an IpcResponse. On any exception from the UI layer, the caller's catch +// block writes a cancelled response so the subagent unblocks. +async function handleAskRequest( + ui: ExtensionUIContext, + ipc: IpcFile, +): Promise { + const { request } = ipc; + const { questions } = request.payload; + const questionsAsAsk = questions as AskQuestion[]; + + if (questions.length === 1 && !questions[0].multi) { + const selection = await askSingleQuestionWithInlineNote(ui, questionsAsAsk[0]); + if (selection.selectedOptions.length === 0 && !selection.customInput) { + return createCancelledResponse(request.id); + } + const answer: { id: string; selectedOptions: string[]; customInput?: string } = { + id: questions[0].id, + selectedOptions: selection.selectedOptions, + }; + if (selection.customInput !== undefined) { + answer.customInput = selection.customInput; + } + return createAskResponse(request.id, { answers: [answer] }); + } + + const tabResult = await askQuestionsWithTabs(ui, questionsAsAsk); + if (tabResult.cancelled) { + return createCancelledResponse(request.id); + } + + const answers = questions.map((q, i) => { + const sel = tabResult.selections[i] ?? { selectedOptions: [] }; + const answer: { id: string; selectedOptions: string[]; customInput?: string } = { + id: q.id, + selectedOptions: sel.selectedOptions, + }; + if (sel.customInput !== undefined) { + answer.customInput = sel.customInput; + } + return answer; + }); + + return createAskResponse(request.id, { answers }); +} + +// Encapsulates the poll-with-request-detection pattern used by both +// the work poll loop and the fix poll loop. Returns a setInterval ID. +function pollWithIpcDetection( + subagentDir: string, + widget: WidgetController | null, + ui: ExtensionUIContext | null, + stepPrefix: string, + updateFromProjection: (p: Projection, logs: LogLine[]) => void, +): ReturnType { + let pendingRequestId: string | null = null; + + return setInterval(async () => { + const [projection, logs] = await Promise.all([ + readProjection(subagentDir), + readRecentLogs(subagentDir), + ]); + if (projection) { + updateFromProjection(projection, logs); + } + + // IPC request detection — skip if already handling a request or no UI + if (pendingRequestId || !ui) return; + + const ipc = await readIpcFile(subagentDir); + if (!ipc || !ipc.request || ipc.response !== null) return; + + pendingRequestId = ipc.request.id; + try { + widget?.update({ + step: `${stepPrefix}: waiting for user input...`, + activity: ipc.request.payload.questions[0]?.question ?? "", + }); + + const response = await handleAskRequest(ui, ipc); + const updated: IpcFile = { request: ipc.request, response }; + await writeIpcFile(subagentDir, updated); + } catch { + // On error, write cancelled response so subagent unblocks. + // The inner try-catch guards against I/O failures during error + // recovery — an unguarded throw here would propagate as an + // unhandled async rejection in the setInterval callback, + // crashing the parent process (Node.js ≥15 default behavior). + try { + const cancelled = createCancelledResponse(ipc.request.id); + await writeIpcFile(subagentDir, { request: ipc.request, response: cancelled }); + } catch { + // I/O failed during error recovery; subagent remains blocked + // until parent terminates. No further action possible. + } + } finally { + pendingRequestId = null; + } + }, 2000); +} + export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, planRef: PlanRef): Session { const state: WorkflowState = createInitialState(); const log = createLogger("Session"); @@ -208,6 +320,7 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan try { const planDir = planInfo.directory; const extensionPath = path.resolve(import.meta.dirname, "../../extensions/koan.ts"); + const ui = ctx.hasUI ? ctx.ui : null; // widgetIndex 0=design, 1=code, 2=docs const phases: PhaseRunConfig[] = [ @@ -247,6 +360,7 @@ export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, plan state, log, widget, + ui, ); phaseSummaries.push(`${phase.label}: ${result.summary}`); @@ -310,6 +424,7 @@ async function runPlanningPhase( state: WorkflowState, log: Logger, widget: WidgetController | null, + ui: ExtensionUIContext | null, ): Promise { state.phase = phaseRunningState(phase.key); @@ -332,16 +447,20 @@ async function runPlanningPhase( const subagentDir = await createSubagentDir(planDir, `${phase.role}-${phase.key}`); - const pollInterval = setInterval(async () => { - const [projection, logs] = await Promise.all([readProjection(subagentDir), readRecentLogs(subagentDir)]); - if (!projection) return; - widget?.update({ - step: `${phase.key}: ${projection.stepName}`, - activity: projection.lastAction ?? "", - logLines: logs, - ...singleSubagentFromProjection(projection), - }); - }, 2000); + const pollInterval = pollWithIpcDetection( + subagentDir, + widget, + ui, + phase.key, + (projection, logs) => { + widget?.update({ + step: `${phase.key}: ${projection.stepName}`, + activity: projection.lastAction ?? "", + logLines: logs, + ...singleSubagentFromProjection(projection), + }); + }, + ); const workResult = await spawnWorkWithResolvedModel( phase.key as PhaseRow, @@ -409,6 +528,7 @@ async function runPlanningPhase( state, log, widget, + ui, ); if (qr.passed) { @@ -702,6 +822,7 @@ async function runPhaseWithQR( state: WorkflowState, log: Logger, widget: WidgetController | null, + ui: ExtensionUIContext | null, ): Promise { const qrPath = qrFilePath(planDir, phase.key); @@ -764,16 +885,20 @@ async function runPhaseWithQR( const fixDir = await createSubagentDir(planDir, `${phase.role}-fix-${phase.key}-${fixIndex}`); - const fixPoll = setInterval(async () => { - const [projection, logs] = await Promise.all([readProjection(fixDir), readRecentLogs(fixDir)]); - if (!projection) return; - widget?.update({ - step: `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}: ${projection.stepName}`, - activity: projection.lastAction ?? "", - logLines: logs, - ...singleSubagentFromProjection(projection), - }); - }, 2000); + const fixPoll = pollWithIpcDetection( + fixDir, + widget, + ui, + `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}`, + (projection, logs) => { + widget?.update({ + step: `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}: ${projection.stepName}`, + activity: projection.lastAction ?? "", + logLines: logs, + ...singleSubagentFromProjection(projection), + }); + }, + ); const fixResult = await spawnFixWithResolvedModel( phase.key as PhaseRow, diff --git a/src/planner/tools/ask.ts b/src/planner/tools/ask.ts new file mode 100644 index 0000000..f1d6ff0 --- /dev/null +++ b/src/planner/tools/ask.ts @@ -0,0 +1,241 @@ +// koan_ask_question tool: subagent-side of the file-based IPC ask flow. +// Writes ipc.json, polls until parent writes a response, then returns +// formatted answers to the LLM. The entire poll loop is wrapped in a +// try/finally that deletes ipc.json, guaranteeing cleanup on all exit paths. + +import { Type, type Static } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import type { SubagentRef } from "../lib/dispatch.js"; +import { + ipcFileExists, + writeIpcFile, + readIpcFile, + deleteIpcFile, + createAskRequest, + type AskAnswerPayload, +} from "../lib/ipc.js"; + +// -- Tool schema (mirrors pi-ask-tool-extension exactly) -- + +const OptionItemSchema = Type.Object({ + label: Type.String({ description: "Display label" }), +}); + +const QuestionItemSchema = Type.Object({ + id: Type.String({ description: "Question id (e.g. auth, cache, priority)" }), + question: Type.String({ description: "Question text" }), + options: Type.Array(OptionItemSchema, { + description: "Available options. Do not include 'Other'.", + minItems: 1, + }), + multi: Type.Optional(Type.Boolean({ description: "Allow multi-select" })), + recommended: Type.Optional( + Type.Number({ description: "0-indexed recommended option. '(Recommended)' is shown automatically." }), + ), +}); + +const AskParamsSchema = Type.Object({ + questions: Type.Array(QuestionItemSchema, { description: "Questions to ask", minItems: 1 }), +}); + +type AskParams = Static; + +// -- Result formatting -- + +interface QuestionResult { + id: string; + question: string; + options: string[]; + multi: boolean; + selectedOptions: string[]; + customInput?: string; +} + +function formatSelectionForSummary(result: QuestionResult): string { + const hasSelectedOptions = result.selectedOptions.length > 0; + const hasCustomInput = Boolean(result.customInput); + + if (!hasSelectedOptions && !hasCustomInput) return "(cancelled)"; + + if (hasSelectedOptions && hasCustomInput) { + const selectedPart = result.multi + ? `[${result.selectedOptions.join(", ")}]` + : result.selectedOptions[0]; + return `${selectedPart} + Other: "${result.customInput}"`; + } + + if (hasCustomInput) return `"${result.customInput}"`; + if (result.multi) return `[${result.selectedOptions.join(", ")}]`; + return result.selectedOptions[0] ?? "(no selection)"; +} + +function formatQuestionContext(result: QuestionResult, index: number): string { + const lines: string[] = [ + `Question ${index + 1} (${result.id})`, + `Prompt: ${result.question}`, + "Options:", + ...result.options.map((o, i) => ` ${i + 1}. ${o}`), + "Response:", + ]; + + const hasSelectedOptions = result.selectedOptions.length > 0; + const hasCustomInput = Boolean(result.customInput); + + if (!hasSelectedOptions && !hasCustomInput) { + lines.push(" Selected: (cancelled)"); + return lines.join("\n"); + } + + if (hasSelectedOptions) { + const text = result.multi + ? `[${result.selectedOptions.join(", ")}]` + : result.selectedOptions[0]; + lines.push(` Selected: ${text}`); + } + + if (hasCustomInput) { + if (!hasSelectedOptions) lines.push(" Selected: Other (type your own)"); + lines.push(` Custom input: ${result.customInput}`); + } + + return lines.join("\n"); +} + +function buildSessionContent(results: QuestionResult[]): string { + const summaryLines = results.map((r) => `${r.id}: ${formatSelectionForSummary(r)}`).join("\n"); + const contextBlocks = results.map((r, i) => formatQuestionContext(r, i)).join("\n\n"); + return `User answers:\n${summaryLines}\n\nAnswer context:\n${contextBlocks}`; +} + +function buildQuestionResults( + params: AskParams, + answers: AskAnswerPayload["answers"], +): QuestionResult[] { + return params.questions.map((q) => { + const answer = answers.find((a) => a.id === q.id) ?? { id: q.id, selectedOptions: [] }; + return { + id: q.id, + question: q.question, + options: q.options.map((o) => o.label), + multi: q.multi ?? false, + selectedOptions: answer.selectedOptions, + customInput: answer.customInput, + }; + }); +} + +// -- Tool registration -- + +const ASK_TOOL_DESCRIPTION = ` +Ask the user for clarification when a choice materially affects the outcome. + +- Use when multiple valid approaches have different trade-offs. +- Prefer 2-5 concise options. +- Use multi=true when multiple answers are valid. +- Use recommended= (0-indexed) to mark the default option. +- You can ask multiple related questions in one call using questions[]. +- Do NOT include an 'Other' option; UI adds it automatically. +`.trim(); + +function sleep(ms: number): Promise { + return new Promise((resolve) => setTimeout(resolve, ms)); +} + +export function registerAskTools(pi: ExtensionAPI, subagentRef: SubagentRef): void { + pi.registerTool({ + name: "koan_ask_question", + label: "Ask question", + description: ASK_TOOL_DESCRIPTION, + parameters: AskParamsSchema, + + async execute(_toolCallId, params, signal) { + const askParams = params as AskParams; + const dir = subagentRef.dir; + + if (!dir) { + return { + content: [{ type: "text" as const, text: "Error: koan_ask_question is only available in subagent context." }], + details: undefined, + }; + } + + if (await ipcFileExists(dir)) { + return { + content: [{ type: "text" as const, text: "Error: A question request is already pending." }], + details: undefined, + }; + } + + const ipc = createAskRequest(askParams); + await writeIpcFile(dir, ipc); + + let aborted = false; + const onAbort = () => { aborted = true; }; + if (signal) { + signal.addEventListener("abort", onAbort, { once: true }); + } + + type PollResult = "answered" | "cancelled" | "aborted" | "file-gone"; + let pollResult: PollResult = "file-gone"; + let answeredPayload: AskAnswerPayload | null = null; + + try { + while (!aborted) { + await sleep(500); + if (signal?.aborted) { + aborted = true; + break; + } + + const current = await readIpcFile(dir); + if (current === null) { + pollResult = "file-gone"; + break; + } + + if (current.response !== null && current.response.id === ipc.request.id) { + if (current.response.cancelled) { + pollResult = "cancelled"; + } else { + pollResult = "answered"; + answeredPayload = current.response.payload; + } + break; + } + } + + if (aborted) { + pollResult = "aborted"; + } + } finally { + await deleteIpcFile(dir); + } + + switch (pollResult) { + case "answered": { + const results = buildQuestionResults(askParams, answeredPayload?.answers ?? []); + return { + content: [{ type: "text" as const, text: buildSessionContent(results) }], + details: undefined, + }; + } + case "cancelled": + return { + content: [{ type: "text" as const, text: "The user declined to answer. Proceed with your best judgment." }], + details: undefined, + }; + case "aborted": + return { + content: [{ type: "text" as const, text: "The question was aborted." }], + details: undefined, + }; + case "file-gone": + return { + content: [{ type: "text" as const, text: "The question was cancelled." }], + details: undefined, + }; + } + }, + }); +} diff --git a/src/planner/tools/index.ts b/src/planner/tools/index.ts index e658f49..726cd11 100644 --- a/src/planner/tools/index.ts +++ b/src/planner/tools/index.ts @@ -3,7 +3,7 @@ // tool registration and workflow infrastructure. import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import type { WorkflowDispatch, PlanRef } from "../lib/dispatch.js"; +import type { WorkflowDispatch, PlanRef, SubagentRef } from "../lib/dispatch.js"; import { registerWorkflowTools } from "./workflow.js"; import { registerPlanGetterTools } from "./getters.js"; @@ -12,11 +12,13 @@ import { registerPlanDesignEntityTools } from "./entity-design.js"; import { registerPlanCodeEntityTools } from "./entity-code.js"; import { registerPlanStructureEntityTools } from "./entity-structure.js"; import { registerQRTools } from "./qr.js"; +import { registerAskTools } from "./ask.js"; -export type { WorkflowDispatch, PlanRef, StepResult } from "../lib/dispatch.js"; +export type { WorkflowDispatch, PlanRef, SubagentRef, StepResult } from "../lib/dispatch.js"; export { createDispatch, createPlanRef, + createSubagentRef, hookDispatch, unhookDispatch, } from "../lib/dispatch.js"; @@ -25,6 +27,7 @@ export function registerAllTools( pi: ExtensionAPI, planRef: PlanRef, dispatch: WorkflowDispatch, + subagentRef: SubagentRef, ): void { registerWorkflowTools(pi, dispatch); registerPlanGetterTools(pi, planRef); @@ -33,4 +36,5 @@ export function registerAllTools( registerPlanCodeEntityTools(pi, planRef); registerPlanStructureEntityTools(pi, planRef); registerQRTools(pi, planRef); + registerAskTools(pi, subagentRef); } diff --git a/src/planner/ui/ask/ask-inline-note.ts b/src/planner/ui/ask/ask-inline-note.ts new file mode 100644 index 0000000..a22ab8f --- /dev/null +++ b/src/planner/ui/ask/ask-inline-note.ts @@ -0,0 +1,65 @@ +import { wrapTextWithAnsi } from "@mariozechner/pi-tui"; + +const INLINE_NOTE_SEPARATOR = " — note: "; +const INLINE_EDIT_CURSOR = "▍"; + +export const INLINE_NOTE_WRAP_PADDING = 2; + +function sanitizeNoteForInlineDisplay(rawNote: string): string { + return rawNote.replace(/[\r\n\t]/g, " ").replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, ""); +} + +function truncateTextKeepingTail(text: string, maxLength: number): string { + if (maxLength <= 0) return ""; + if (text.length <= maxLength) return text; + if (maxLength === 1) return "…"; + return `…${text.slice(-(maxLength - 1))}`; +} + +function truncateTextKeepingHead(text: string, maxLength: number): string { + if (maxLength <= 0) return ""; + if (text.length <= maxLength) return text; + if (maxLength === 1) return "…"; + return `${text.slice(0, maxLength - 1)}…`; +} + +export function buildOptionLabelWithInlineNote( + baseOptionLabel: string, + rawNote: string, + isEditingNote: boolean, + maxInlineLabelLength?: number, +): string { + const sanitizedNote = sanitizeNoteForInlineDisplay(rawNote); + if (!isEditingNote && sanitizedNote.trim().length === 0) { + return baseOptionLabel; + } + + const labelPrefix = `${baseOptionLabel}${INLINE_NOTE_SEPARATOR}`; + const inlineNote = isEditingNote ? `${sanitizedNote}${INLINE_EDIT_CURSOR}` : sanitizedNote.trim(); + const inlineLabel = `${labelPrefix}${inlineNote}`; + + if (maxInlineLabelLength == null) { + return inlineLabel; + } + + return isEditingNote + ? truncateTextKeepingTail(inlineLabel, maxInlineLabelLength) + : truncateTextKeepingHead(inlineLabel, maxInlineLabelLength); +} + +export function buildWrappedOptionLabelWithInlineNote( + baseOptionLabel: string, + rawNote: string, + isEditingNote: boolean, + maxInlineLabelLength: number, + wrapPadding = INLINE_NOTE_WRAP_PADDING, +): string[] { + const inlineLabel = buildOptionLabelWithInlineNote(baseOptionLabel, rawNote, isEditingNote); + const sanitizedWrapPadding = Number.isFinite(wrapPadding) ? Math.max(0, Math.floor(wrapPadding)) : 0; + const sanitizedMaxInlineLabelLength = Number.isFinite(maxInlineLabelLength) + ? Math.max(1, Math.floor(maxInlineLabelLength)) + : 1; + const wrapWidth = Math.max(1, sanitizedMaxInlineLabelLength - sanitizedWrapPadding); + const wrappedLines = wrapTextWithAnsi(inlineLabel, wrapWidth); + return wrappedLines.length > 0 ? wrappedLines : [""]; +} diff --git a/src/planner/ui/ask/ask-inline-ui.ts b/src/planner/ui/ask/ask-inline-ui.ts new file mode 100644 index 0000000..e57ed04 --- /dev/null +++ b/src/planner/ui/ask/ask-inline-ui.ts @@ -0,0 +1,221 @@ +import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; +import { Editor, type EditorTheme, Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui"; +import { + OTHER_OPTION, + appendRecommendedTagToOptionLabels, + buildSingleSelectionResult, + type AskOption, + type AskSelection, +} from "./ask-logic.js"; +import { INLINE_NOTE_WRAP_PADDING, buildWrappedOptionLabelWithInlineNote } from "./ask-inline-note.js"; + +interface SingleQuestionInput { + question: string; + options: AskOption[]; + recommended?: number; +} + +interface InlineSelectionResult { + cancelled: boolean; + selectedOption?: string; + note?: string; +} + +function resolveInitialCursorIndexFromRecommendedOption( + recommendedOptionIndex: number | undefined, + optionCount: number, +): number { + if (recommendedOptionIndex == null) return 0; + if (recommendedOptionIndex < 0 || recommendedOptionIndex >= optionCount) return 0; + return recommendedOptionIndex; +} + +export async function askSingleQuestionWithInlineNote( + ui: ExtensionUIContext, + questionInput: SingleQuestionInput, +): Promise { + const baseOptionLabels = questionInput.options.map((option) => option.label); + const optionLabelsWithRecommendedTag = appendRecommendedTagToOptionLabels( + baseOptionLabels, + questionInput.recommended, + ); + const selectableOptionLabels = [...optionLabelsWithRecommendedTag, OTHER_OPTION]; + const initialCursorIndex = resolveInitialCursorIndexFromRecommendedOption( + questionInput.recommended, + optionLabelsWithRecommendedTag.length, + ); + + const result = await ui.custom((tui, theme, _keybindings, done) => { + let cursorOptionIndex = initialCursorIndex; + let isNoteEditorOpen = false; + let cachedRenderedLines: string[] | undefined; + const noteByOptionIndex = new Map(); + + const editorTheme: EditorTheme = { + borderColor: (text) => theme.fg("accent", text), + selectList: { + selectedPrefix: (text) => theme.fg("accent", text), + selectedText: (text) => theme.fg("accent", text), + description: (text) => theme.fg("muted", text), + scrollInfo: (text) => theme.fg("dim", text), + noMatch: (text) => theme.fg("warning", text), + }, + }; + const noteEditor = new Editor(tui, editorTheme); + + const requestUiRerender = () => { + cachedRenderedLines = undefined; + tui.requestRender(); + }; + + const getRawNoteForOption = (optionIndex: number): string => noteByOptionIndex.get(optionIndex) ?? ""; + const getTrimmedNoteForOption = (optionIndex: number): string => getRawNoteForOption(optionIndex).trim(); + + const loadCurrentNoteIntoEditor = () => { + noteEditor.setText(getRawNoteForOption(cursorOptionIndex)); + }; + + const saveCurrentNoteFromEditor = (value: string) => { + noteByOptionIndex.set(cursorOptionIndex, value); + }; + + const submitCurrentSelection = (selectedOptionLabel: string, note: string) => { + done({ + cancelled: false, + selectedOption: selectedOptionLabel, + note, + }); + }; + + noteEditor.onChange = (value) => { + saveCurrentNoteFromEditor(value); + requestUiRerender(); + }; + + noteEditor.onSubmit = (value) => { + saveCurrentNoteFromEditor(value); + const selectedOptionLabel = selectableOptionLabels[cursorOptionIndex]; + const trimmedNote = value.trim(); + + if (selectedOptionLabel === OTHER_OPTION && !trimmedNote) { + requestUiRerender(); + return; + } + + submitCurrentSelection(selectedOptionLabel, trimmedNote); + }; + + const render = (width: number): string[] => { + if (cachedRenderedLines) return cachedRenderedLines; + + const renderedLines: string[] = []; + const addLine = (line: string) => renderedLines.push(truncateToWidth(line, width)); + + addLine(theme.fg("accent", "─".repeat(width))); + addLine(theme.fg("text", ` ${questionInput.question}`)); + renderedLines.push(""); + + for (let optionIndex = 0; optionIndex < selectableOptionLabels.length; optionIndex++) { + const optionLabel = selectableOptionLabels[optionIndex]; + const isCursorOption = optionIndex === cursorOptionIndex; + const isEditingThisOption = isNoteEditorOpen && isCursorOption; + const cursorPrefixText = isCursorOption ? "→ " : " "; + const cursorPrefix = isCursorOption ? theme.fg("accent", cursorPrefixText) : cursorPrefixText; + const bullet = isCursorOption ? "●" : "○"; + const markerText = `${bullet} `; + const optionColor = isCursorOption ? "accent" : "text"; + const prefixWidth = visibleWidth(cursorPrefixText) + visibleWidth(markerText); + const wrappedInlineLabelLines = buildWrappedOptionLabelWithInlineNote( + optionLabel, + getRawNoteForOption(optionIndex), + isEditingThisOption, + Math.max(1, width - prefixWidth), + INLINE_NOTE_WRAP_PADDING, + ); + const continuationPrefix = " ".repeat(prefixWidth); + addLine(`${cursorPrefix}${theme.fg(optionColor, `${markerText}${wrappedInlineLabelLines[0] ?? ""}`)}`); + for (const wrappedLine of wrappedInlineLabelLines.slice(1)) { + addLine(`${continuationPrefix}${theme.fg(optionColor, wrappedLine)}`); + } + } + + renderedLines.push(""); + + if (isNoteEditorOpen) { + addLine(theme.fg("dim", " Typing note inline • Enter submit • Tab/Esc stop editing")); + } else if (getTrimmedNoteForOption(cursorOptionIndex).length > 0) { + addLine(theme.fg("dim", " ↑↓ move • Enter submit • Tab edit note • Esc cancel")); + } else { + addLine(theme.fg("dim", " ↑↓ move • Enter submit • Tab add note • Esc cancel")); + } + + addLine(theme.fg("accent", "─".repeat(width))); + cachedRenderedLines = renderedLines; + return renderedLines; + }; + + const handleInput = (data: string) => { + if (isNoteEditorOpen) { + if (matchesKey(data, Key.tab) || matchesKey(data, Key.escape)) { + isNoteEditorOpen = false; + requestUiRerender(); + return; + } + noteEditor.handleInput(data); + requestUiRerender(); + return; + } + + if (matchesKey(data, Key.up)) { + cursorOptionIndex = Math.max(0, cursorOptionIndex - 1); + requestUiRerender(); + return; + } + if (matchesKey(data, Key.down)) { + cursorOptionIndex = Math.min(selectableOptionLabels.length - 1, cursorOptionIndex + 1); + requestUiRerender(); + return; + } + + if (matchesKey(data, Key.tab)) { + isNoteEditorOpen = true; + loadCurrentNoteIntoEditor(); + requestUiRerender(); + return; + } + + if (matchesKey(data, Key.enter)) { + const selectedOptionLabel = selectableOptionLabels[cursorOptionIndex]; + const trimmedNote = getTrimmedNoteForOption(cursorOptionIndex); + + if (selectedOptionLabel === OTHER_OPTION && !trimmedNote) { + isNoteEditorOpen = true; + loadCurrentNoteIntoEditor(); + requestUiRerender(); + return; + } + + submitCurrentSelection(selectedOptionLabel, trimmedNote); + return; + } + + if (matchesKey(data, Key.escape)) { + done({ cancelled: true }); + } + }; + + return { + render, + invalidate: () => { + cachedRenderedLines = undefined; + }, + handleInput, + }; + }); + + if (result.cancelled || !result.selectedOption) { + return { selectedOptions: [] }; + } + + return buildSingleSelectionResult(result.selectedOption, result.note); +} diff --git a/src/planner/ui/ask/ask-logic.ts b/src/planner/ui/ask/ask-logic.ts new file mode 100644 index 0000000..ccdf6fc --- /dev/null +++ b/src/planner/ui/ask/ask-logic.ts @@ -0,0 +1,98 @@ +export const OTHER_OPTION = "Other (type your own)"; +const RECOMMENDED_OPTION_TAG = " (Recommended)"; + +export interface AskOption { + label: string; +} + +export interface AskQuestion { + id: string; + question: string; + options: AskOption[]; + multi?: boolean; + recommended?: number; +} + +export interface AskSelection { + selectedOptions: string[]; + customInput?: string; +} + +export function appendRecommendedTagToOptionLabels( + optionLabels: string[], + recommendedOptionIndex?: number, +): string[] { + if ( + recommendedOptionIndex == null || + recommendedOptionIndex < 0 || + recommendedOptionIndex >= optionLabels.length + ) { + return optionLabels; + } + + return optionLabels.map((optionLabel, optionIndex) => { + if (optionIndex !== recommendedOptionIndex) return optionLabel; + if (optionLabel.endsWith(RECOMMENDED_OPTION_TAG)) return optionLabel; + return `${optionLabel}${RECOMMENDED_OPTION_TAG}`; + }); +} + +function removeRecommendedTagFromOptionLabel(optionLabel: string): string { + if (!optionLabel.endsWith(RECOMMENDED_OPTION_TAG)) { + return optionLabel; + } + return optionLabel.slice(0, -RECOMMENDED_OPTION_TAG.length); +} + +export function buildSingleSelectionResult(selectedOptionLabel: string, note?: string): AskSelection { + const normalizedSelectedOption = removeRecommendedTagFromOptionLabel(selectedOptionLabel); + const normalizedNote = note?.trim(); + + if (normalizedSelectedOption === OTHER_OPTION) { + if (normalizedNote) { + return { selectedOptions: [], customInput: normalizedNote }; + } + return { selectedOptions: [] }; + } + + if (normalizedNote) { + return { selectedOptions: [`${normalizedSelectedOption} - ${normalizedNote}`] }; + } + + return { selectedOptions: [normalizedSelectedOption] }; +} + +export function buildMultiSelectionResult( + optionLabels: string[], + selectedOptionIndexes: number[], + optionNotes: string[], + otherOptionIndex: number, +): AskSelection { + const selectedOptionSet = new Set(selectedOptionIndexes); + const selectedOptions: string[] = []; + let customInput: string | undefined; + + for (let optionIndex = 0; optionIndex < optionLabels.length; optionIndex++) { + if (!selectedOptionSet.has(optionIndex)) continue; + + const optionLabel = removeRecommendedTagFromOptionLabel(optionLabels[optionIndex]); + const optionNote = optionNotes[optionIndex]?.trim(); + + if (optionIndex === otherOptionIndex) { + if (optionNote) customInput = optionNote; + continue; + } + + if (optionNote) { + selectedOptions.push(`${optionLabel} - ${optionNote}`); + } else { + selectedOptions.push(optionLabel); + } + } + + if (customInput) { + return { selectedOptions, customInput }; + } + + return { selectedOptions }; +} diff --git a/src/planner/ui/ask/ask-tabs-ui.ts b/src/planner/ui/ask/ask-tabs-ui.ts new file mode 100644 index 0000000..dd58190 --- /dev/null +++ b/src/planner/ui/ask/ask-tabs-ui.ts @@ -0,0 +1,512 @@ +import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; +import { Editor, type EditorTheme, Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui"; +import { + OTHER_OPTION, + appendRecommendedTagToOptionLabels, + buildMultiSelectionResult, + buildSingleSelectionResult, + type AskQuestion, + type AskSelection, +} from "./ask-logic.js"; +import { INLINE_NOTE_WRAP_PADDING, buildWrappedOptionLabelWithInlineNote } from "./ask-inline-note.js"; + +interface PreparedQuestion { + id: string; + question: string; + options: string[]; + tabLabel: string; + multi: boolean; + otherOptionIndex: number; +} + +interface TabsUIState { + cancelled: boolean; + selectedOptionIndexesByQuestion: number[][]; + noteByQuestionByOption: string[][]; +} + +export function formatSelectionForSubmitReview(selection: AskSelection, isMulti: boolean): string { + const hasSelectedOptions = selection.selectedOptions.length > 0; + const hasCustomInput = Boolean(selection.customInput); + + if (hasSelectedOptions && hasCustomInput) { + const selectedPart = isMulti + ? `[${selection.selectedOptions.join(", ")}]` + : selection.selectedOptions[0]; + return `${selectedPart} + Other: ${selection.customInput}`; + } + + if (hasCustomInput) { + return `Other: ${selection.customInput}`; + } + + if (hasSelectedOptions) { + return isMulti ? `[${selection.selectedOptions.join(", ")}]` : selection.selectedOptions[0]; + } + + return "(not answered)"; +} + +function clampIndex(index: number | undefined, maxExclusive: number): number { + if (index == null || Number.isNaN(index) || maxExclusive <= 0) return 0; + if (index < 0) return 0; + if (index >= maxExclusive) return maxExclusive - 1; + return index; +} + +function normalizeTabLabel(id: string, fallback: string): string { + const normalized = id.trim().replace(/[_-]+/g, " "); + return normalized.length > 0 ? normalized : fallback; +} + +function buildSelectionForQuestion( + question: PreparedQuestion, + selectedOptionIndexes: number[], + noteByOptionIndex: string[], +): AskSelection { + if (selectedOptionIndexes.length === 0) { + return { selectedOptions: [] }; + } + + if (question.multi) { + return buildMultiSelectionResult(question.options, selectedOptionIndexes, noteByOptionIndex, question.otherOptionIndex); + } + + const selectedOptionIndex = selectedOptionIndexes[0]; + const selectedOptionLabel = question.options[selectedOptionIndex] ?? OTHER_OPTION; + const note = noteByOptionIndex[selectedOptionIndex] ?? ""; + return buildSingleSelectionResult(selectedOptionLabel, note); +} + +function isQuestionSelectionValid( + question: PreparedQuestion, + selectedOptionIndexes: number[], + noteByOptionIndex: string[], +): boolean { + if (selectedOptionIndexes.length === 0) return false; + if (!selectedOptionIndexes.includes(question.otherOptionIndex)) return true; + const otherNote = noteByOptionIndex[question.otherOptionIndex]?.trim() ?? ""; + return otherNote.length > 0; +} + +function createTabsUiStateSnapshot( + cancelled: boolean, + selectedOptionIndexesByQuestion: number[][], + noteByQuestionByOption: string[][], +): TabsUIState { + return { + cancelled, + selectedOptionIndexesByQuestion: selectedOptionIndexesByQuestion.map((indexes) => [...indexes]), + noteByQuestionByOption: noteByQuestionByOption.map((notes) => [...notes]), + }; +} + +function addIndexToSelection(selectedOptionIndexes: number[], optionIndex: number): number[] { + if (selectedOptionIndexes.includes(optionIndex)) return selectedOptionIndexes; + return [...selectedOptionIndexes, optionIndex].sort((a, b) => a - b); +} + +function removeIndexFromSelection(selectedOptionIndexes: number[], optionIndex: number): number[] { + return selectedOptionIndexes.filter((index) => index !== optionIndex); +} + +export async function askQuestionsWithTabs( + ui: ExtensionUIContext, + questions: AskQuestion[], +): Promise<{ cancelled: boolean; selections: AskSelection[] }> { + const preparedQuestions: PreparedQuestion[] = questions.map((question, questionIndex) => { + const baseOptionLabels = question.options.map((option) => option.label); + const optionLabels = [...appendRecommendedTagToOptionLabels(baseOptionLabels, question.recommended), OTHER_OPTION]; + return { + id: question.id, + question: question.question, + options: optionLabels, + tabLabel: normalizeTabLabel(question.id, `Q${questionIndex + 1}`), + multi: question.multi === true, + otherOptionIndex: optionLabels.length - 1, + }; + }); + + const initialCursorOptionIndexByQuestion = preparedQuestions.map((preparedQuestion, questionIndex) => + clampIndex(questions[questionIndex].recommended, preparedQuestion.options.length), + ); + + const result = await ui.custom((tui, theme, _keybindings, done) => { + let activeTabIndex = 0; + let isNoteEditorOpen = false; + let cachedRenderedLines: string[] | undefined; + const cursorOptionIndexByQuestion = [...initialCursorOptionIndexByQuestion]; + const selectedOptionIndexesByQuestion = preparedQuestions.map(() => [] as number[]); + const noteByQuestionByOption = preparedQuestions.map((preparedQuestion) => + Array(preparedQuestion.options.length).fill("") as string[], + ); + + const editorTheme: EditorTheme = { + borderColor: (text) => theme.fg("accent", text), + selectList: { + selectedPrefix: (text) => theme.fg("accent", text), + selectedText: (text) => theme.fg("accent", text), + description: (text) => theme.fg("muted", text), + scrollInfo: (text) => theme.fg("dim", text), + noMatch: (text) => theme.fg("warning", text), + }, + }; + const noteEditor = new Editor(tui, editorTheme); + + const submitTabIndex = preparedQuestions.length; + + const requestUiRerender = () => { + cachedRenderedLines = undefined; + tui.requestRender(); + }; + + const getActiveQuestionIndex = (): number | null => { + if (activeTabIndex >= preparedQuestions.length) return null; + return activeTabIndex; + }; + + const getQuestionNote = (questionIndex: number, optionIndex: number): string => + noteByQuestionByOption[questionIndex]?.[optionIndex] ?? ""; + + const getTrimmedQuestionNote = (questionIndex: number, optionIndex: number): string => + getQuestionNote(questionIndex, optionIndex).trim(); + + const isAllQuestionSelectionsValid = (): boolean => + preparedQuestions.every((preparedQuestion, questionIndex) => + isQuestionSelectionValid( + preparedQuestion, + selectedOptionIndexesByQuestion[questionIndex], + noteByQuestionByOption[questionIndex], + ), + ); + + const openNoteEditorForActiveOption = () => { + const questionIndex = getActiveQuestionIndex(); + if (questionIndex == null) return; + + isNoteEditorOpen = true; + const optionIndex = cursorOptionIndexByQuestion[questionIndex]; + noteEditor.setText(getQuestionNote(questionIndex, optionIndex)); + requestUiRerender(); + }; + + const advanceToNextTabOrSubmit = () => { + activeTabIndex = Math.min(submitTabIndex, activeTabIndex + 1); + }; + + noteEditor.onChange = (value) => { + const questionIndex = getActiveQuestionIndex(); + if (questionIndex == null) return; + const optionIndex = cursorOptionIndexByQuestion[questionIndex]; + noteByQuestionByOption[questionIndex][optionIndex] = value; + requestUiRerender(); + }; + + noteEditor.onSubmit = (value) => { + const questionIndex = getActiveQuestionIndex(); + if (questionIndex == null) return; + + const preparedQuestion = preparedQuestions[questionIndex]; + const optionIndex = cursorOptionIndexByQuestion[questionIndex]; + noteByQuestionByOption[questionIndex][optionIndex] = value; + const trimmedNote = value.trim(); + + if (preparedQuestion.multi) { + if (trimmedNote.length > 0) { + selectedOptionIndexesByQuestion[questionIndex] = addIndexToSelection( + selectedOptionIndexesByQuestion[questionIndex], + optionIndex, + ); + } + if (optionIndex === preparedQuestion.otherOptionIndex && trimmedNote.length === 0) { + requestUiRerender(); + return; + } + isNoteEditorOpen = false; + requestUiRerender(); + return; + } + + selectedOptionIndexesByQuestion[questionIndex] = [optionIndex]; + if (optionIndex === preparedQuestion.otherOptionIndex && trimmedNote.length === 0) { + requestUiRerender(); + return; + } + + isNoteEditorOpen = false; + advanceToNextTabOrSubmit(); + requestUiRerender(); + }; + + const renderTabs = (): string => { + const tabParts: string[] = ["← "]; + for (let questionIndex = 0; questionIndex < preparedQuestions.length; questionIndex++) { + const preparedQuestion = preparedQuestions[questionIndex]; + const isActiveTab = questionIndex === activeTabIndex; + const isQuestionValid = isQuestionSelectionValid( + preparedQuestion, + selectedOptionIndexesByQuestion[questionIndex], + noteByQuestionByOption[questionIndex], + ); + const statusIcon = isQuestionValid ? "■" : "□"; + const tabLabel = ` ${statusIcon} ${preparedQuestion.tabLabel} `; + const styledTabLabel = isActiveTab + ? theme.bg("selectedBg", theme.fg("text", tabLabel)) + : theme.fg(isQuestionValid ? "success" : "muted", tabLabel); + tabParts.push(`${styledTabLabel} `); + } + + const isSubmitTabActive = activeTabIndex === submitTabIndex; + const canSubmit = isAllQuestionSelectionsValid(); + const submitLabel = " ✓ Submit "; + const styledSubmitLabel = isSubmitTabActive + ? theme.bg("selectedBg", theme.fg("text", submitLabel)) + : theme.fg(canSubmit ? "success" : "dim", submitLabel); + tabParts.push(`${styledSubmitLabel} →`); + return tabParts.join(""); + }; + + const renderSubmitTab = (width: number, renderedLines: string[]): void => { + const addLine = (line: string) => renderedLines.push(truncateToWidth(line, width)); + + addLine(theme.fg("accent", theme.bold(" Review answers"))); + renderedLines.push(""); + + for (let questionIndex = 0; questionIndex < preparedQuestions.length; questionIndex++) { + const preparedQuestion = preparedQuestions[questionIndex]; + const selection = buildSelectionForQuestion( + preparedQuestion, + selectedOptionIndexesByQuestion[questionIndex], + noteByQuestionByOption[questionIndex], + ); + const value = formatSelectionForSubmitReview(selection, preparedQuestion.multi); + const isValid = isQuestionSelectionValid( + preparedQuestion, + selectedOptionIndexesByQuestion[questionIndex], + noteByQuestionByOption[questionIndex], + ); + const statusIcon = isValid ? theme.fg("success", "●") : theme.fg("warning", "○"); + addLine(` ${statusIcon} ${theme.fg("muted", `${preparedQuestion.tabLabel}:`)} ${theme.fg("text", value)}`); + } + + renderedLines.push(""); + if (isAllQuestionSelectionsValid()) { + addLine(theme.fg("success", " Press Enter to submit")); + } else { + const missingQuestions = preparedQuestions + .filter((preparedQuestion, questionIndex) => + !isQuestionSelectionValid( + preparedQuestion, + selectedOptionIndexesByQuestion[questionIndex], + noteByQuestionByOption[questionIndex], + ), + ) + .map((preparedQuestion) => preparedQuestion.tabLabel) + .join(", "); + addLine(theme.fg("warning", ` Complete required answers: ${missingQuestions}`)); + } + addLine(theme.fg("dim", " ←/→ switch tabs • Esc cancel")); + }; + + const renderQuestionTab = (width: number, renderedLines: string[], questionIndex: number): void => { + const addLine = (line: string) => renderedLines.push(truncateToWidth(line, width)); + const preparedQuestion = preparedQuestions[questionIndex]; + const cursorOptionIndex = cursorOptionIndexByQuestion[questionIndex]; + const selectedOptionIndexes = selectedOptionIndexesByQuestion[questionIndex]; + + addLine(theme.fg("text", ` ${preparedQuestion.question}`)); + renderedLines.push(""); + + for (let optionIndex = 0; optionIndex < preparedQuestion.options.length; optionIndex++) { + const optionLabel = preparedQuestion.options[optionIndex]; + const isCursorOption = optionIndex === cursorOptionIndex; + const isOptionSelected = selectedOptionIndexes.includes(optionIndex); + const isEditingThisOption = isNoteEditorOpen && isCursorOption; + const cursorPrefixText = isCursorOption ? "→ " : " "; + const cursorPrefix = isCursorOption ? theme.fg("accent", cursorPrefixText) : cursorPrefixText; + const markerText = preparedQuestion.multi + ? `${isOptionSelected ? "[x]" : "[ ]"} ` + : `${isOptionSelected ? "●" : "○"} `; + const optionColor = isCursorOption ? "accent" : isOptionSelected ? "success" : "text"; + const prefixWidth = visibleWidth(cursorPrefixText) + visibleWidth(markerText); + const wrappedInlineLabelLines = buildWrappedOptionLabelWithInlineNote( + optionLabel, + getQuestionNote(questionIndex, optionIndex), + isEditingThisOption, + Math.max(1, width - prefixWidth), + INLINE_NOTE_WRAP_PADDING, + ); + const continuationPrefix = " ".repeat(prefixWidth); + addLine(`${cursorPrefix}${theme.fg(optionColor, `${markerText}${wrappedInlineLabelLines[0] ?? ""}`)}`); + for (const wrappedLine of wrappedInlineLabelLines.slice(1)) { + addLine(`${continuationPrefix}${theme.fg(optionColor, wrappedLine)}`); + } + } + + renderedLines.push(""); + if (isNoteEditorOpen) { + addLine(theme.fg("dim", " Typing note inline • Enter save note • Tab/Esc stop editing")); + } else { + if (preparedQuestion.multi) { + addLine( + theme.fg( + "dim", + " ↑↓ move • Enter toggle/select • Tab add note • ←/→ switch tabs • Esc cancel", + ), + ); + } else { + addLine( + theme.fg("dim", " ↑↓ move • Enter select • Tab add note • ←/→ switch tabs • Esc cancel"), + ); + } + } + }; + + const render = (width: number): string[] => { + if (cachedRenderedLines) return cachedRenderedLines; + + const renderedLines: string[] = []; + const addLine = (line: string) => renderedLines.push(truncateToWidth(line, width)); + + addLine(theme.fg("accent", "─".repeat(width))); + addLine(` ${renderTabs()}`); + renderedLines.push(""); + + if (activeTabIndex === submitTabIndex) { + renderSubmitTab(width, renderedLines); + } else { + renderQuestionTab(width, renderedLines, activeTabIndex); + } + + addLine(theme.fg("accent", "─".repeat(width))); + cachedRenderedLines = renderedLines; + return renderedLines; + }; + + const handleInput = (data: string) => { + if (isNoteEditorOpen) { + if (matchesKey(data, Key.tab) || matchesKey(data, Key.escape)) { + isNoteEditorOpen = false; + requestUiRerender(); + return; + } + noteEditor.handleInput(data); + requestUiRerender(); + return; + } + + if (matchesKey(data, Key.left)) { + activeTabIndex = (activeTabIndex - 1 + preparedQuestions.length + 1) % (preparedQuestions.length + 1); + requestUiRerender(); + return; + } + + if (matchesKey(data, Key.right)) { + activeTabIndex = (activeTabIndex + 1) % (preparedQuestions.length + 1); + requestUiRerender(); + return; + } + + if (activeTabIndex === submitTabIndex) { + if (matchesKey(data, Key.enter) && isAllQuestionSelectionsValid()) { + done(createTabsUiStateSnapshot(false, selectedOptionIndexesByQuestion, noteByQuestionByOption)); + return; + } + if (matchesKey(data, Key.escape)) { + done(createTabsUiStateSnapshot(true, selectedOptionIndexesByQuestion, noteByQuestionByOption)); + } + return; + } + + const questionIndex = activeTabIndex; + const preparedQuestion = preparedQuestions[questionIndex]; + + if (matchesKey(data, Key.up)) { + cursorOptionIndexByQuestion[questionIndex] = Math.max(0, cursorOptionIndexByQuestion[questionIndex] - 1); + requestUiRerender(); + return; + } + + if (matchesKey(data, Key.down)) { + cursorOptionIndexByQuestion[questionIndex] = Math.min( + preparedQuestion.options.length - 1, + cursorOptionIndexByQuestion[questionIndex] + 1, + ); + requestUiRerender(); + return; + } + + if (matchesKey(data, Key.tab)) { + openNoteEditorForActiveOption(); + return; + } + + if (matchesKey(data, Key.enter)) { + const cursorOptionIndex = cursorOptionIndexByQuestion[questionIndex]; + + if (preparedQuestion.multi) { + const currentlySelected = selectedOptionIndexesByQuestion[questionIndex]; + if (currentlySelected.includes(cursorOptionIndex)) { + selectedOptionIndexesByQuestion[questionIndex] = removeIndexFromSelection(currentlySelected, cursorOptionIndex); + } else { + selectedOptionIndexesByQuestion[questionIndex] = addIndexToSelection(currentlySelected, cursorOptionIndex); + } + + if ( + cursorOptionIndex === preparedQuestion.otherOptionIndex && + selectedOptionIndexesByQuestion[questionIndex].includes(cursorOptionIndex) && + getTrimmedQuestionNote(questionIndex, cursorOptionIndex).length === 0 + ) { + openNoteEditorForActiveOption(); + return; + } + + requestUiRerender(); + return; + } + + selectedOptionIndexesByQuestion[questionIndex] = [cursorOptionIndex]; + if ( + cursorOptionIndex === preparedQuestion.otherOptionIndex && + getTrimmedQuestionNote(questionIndex, cursorOptionIndex).length === 0 + ) { + openNoteEditorForActiveOption(); + return; + } + + advanceToNextTabOrSubmit(); + requestUiRerender(); + return; + } + + if (matchesKey(data, Key.escape)) { + done(createTabsUiStateSnapshot(true, selectedOptionIndexesByQuestion, noteByQuestionByOption)); + } + }; + + return { + render, + invalidate: () => { + cachedRenderedLines = undefined; + }, + handleInput, + }; + }); + + if (result.cancelled) { + return { + cancelled: true, + selections: preparedQuestions.map(() => ({ selectedOptions: [] } satisfies AskSelection)), + }; + } + + const selections = preparedQuestions.map((preparedQuestion, questionIndex) => + buildSelectionForQuestion( + preparedQuestion, + result.selectedOptionIndexesByQuestion[questionIndex] ?? [], + result.noteByQuestionByOption[questionIndex] ?? Array(preparedQuestion.options.length).fill(""), + ), + ); + + return { cancelled: result.cancelled, selections }; +} From afdd5cac56f77e864be317dc865333ba2b9d10d1 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 3 Mar 2026 15:12:12 +0700 Subject: [PATCH 035/412] Remove plan --- PLAN.md | 367 -------------------------------------------------------- 1 file changed, 367 deletions(-) delete mode 100644 PLAN.md diff --git a/PLAN.md b/PLAN.md deleted file mode 100644 index cdc5063..0000000 --- a/PLAN.md +++ /dev/null @@ -1,367 +0,0 @@ -# Plan: Subagent Ask Questions via File-Based IPC - -## Context - -### Problem - -Subagents run as headless `pi -p` child processes with no UI access (`ctx.hasUI = false`). When a subagent needs user input during planning — choosing between architectural alternatives, clarifying scope — it has no mechanism to pause, ask the user, and resume with the answer. - -### Design Decisions - -**Single `ipc.json` file per subagent directory.** Both request and response live in one file with `request` and `response` keys. Temporal ownership is safe: the subagent creates the file and then blocks (only reads during the wait), so the parent is the sole writer during the response window. A two-file model (request.json + response.json) provides structural ownership at the cost of cleanup complexity and an extra file per interaction. The single-file model is simpler and sufficient because the subagent's blocking poll guarantees no concurrent writes. - -**Tool schema mirrors pi-ask-tool-extension exactly.** The `koan_ask_question` tool accepts the same `{ questions: [{ id, question, options, multi?, recommended? }] }` schema as the existing `ask` tool. LLMs trained on the ask tool schema produce correct calls without schema-specific prompt engineering. - -**Ask UI code copied from pi-ask-tool-extension, not imported.** The pi-ask-tool-extension package is globally installed as a pi extension — it is not in koan's `node_modules` and cannot be imported. The four source files (~1133 lines) are copied into `src/planner/ui/ask/`. All external dependencies (`@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`) are already available in koan's node_modules. - -**Permission gating via existing PHASE_PERMISSIONS, not conditional registration.** Pi snapshots all tools at init time (`_buildRuntime()`). Tools cannot be added or removed after init. The existing default-deny `PHASE_PERMISSIONS` map in `permissions.ts` controls runtime access. Adding `koan_ask_question` to the three work-phase Sets (`plan-design`, `plan-code`, `plan-docs`) grants access to subagents in those phases. In parent mode, no phase is active, so the tool is blocked automatically. - -**SubagentRef pattern mirrors PlanRef.** Tool registration happens at init when the subagent directory is unknown. A mutable `SubagentRef = { dir: string | null }` created at init is populated at `before_agent_start` when CLI flags are available. The tool reads `subagentRef.dir` at execute time. This matches the established `PlanRef` indirection pattern in `dispatch.ts`. - -**Non-error returns for cancellation and abort.** When the user cancels (Escape) or the signal aborts, the tool returns a descriptive non-error message ("The user declined to answer. Proceed with your best judgment."). Error returns cause LLMs to halt or retry; non-error returns guide the LLM to continue productively. - -**Parent detects requests inside existing setInterval poll loops.** The parent's 2-second poll callback in `session.ts` already reads `state.json` for widget updates. Adding an `ipc.json` read to the same callback avoids a separate polling mechanism. A `pendingRequestId` guard variable prevents re-entrant handling — JavaScript's `setInterval` fires regardless of whether the previous async callback completed, so without the guard, every 2-second tick during the user's think-time would re-detect the same request. - -### Constraints - -- Pi snapshots tools at init; all tools must be registered unconditionally before `_buildRuntime()`. -- Subagents run in `-p` mode (print mode) with stdin ignored and stdout/stderr piped to log files — no interactive I/O. -- The parent orchestrator has `ctx.ui` access (confirmed: `session.ts` creates `WidgetController` from `ctx.ui`). -- Atomic file writes use the established tmp+rename pattern (`writeFile(tmp) → rename(tmp, target)`). -- The EventLog heartbeat (10-second `setInterval`) continues during the subagent's blocking poll because `await sleep(500)` yields to the Node.js event loop. `state.json` keeps updating, so the parent sees the subagent as alive. - -### Out of Scope (Deferred) - -- Timeout for parent crash detection — the user is at the terminal and will notice; adding a configurable timeout is a follow-up. -- Process liveness check before showing ask UI — low severity edge case (subagent exits between writing request and parent detecting it). -- Multi-subagent concurrent questions — work phases run sequentially; QR phases are excluded from permissions. - -## Implementation - -### ipc.json Schema - -```typescript -// Types live in src/planner/lib/ipc.ts. -// The schema is general-purpose: `type` discriminant supports future request -// types beyond "ask-question" without envelope changes. - -interface IpcFile { - request: IpcRequest; - response: IpcResponse | null; // null while awaiting parent response -} - -interface IpcRequest { - id: string; // crypto.randomUUID() — correlates request to response - type: "ask-question"; // discriminant for routing; extensible to future types - createdAt: string; // ISO 8601 timestamp - payload: AskQuestionPayload; -} - -interface AskQuestionPayload { - questions: Array<{ - id: string; - question: string; - options: Array<{ label: string }>; - multi?: boolean; - recommended?: number; // 0-indexed - }>; -} - -interface IpcResponse { - id: string; // must match request.id - respondedAt: string; // ISO 8601 timestamp - cancelled: boolean; // true when user presses Escape - payload: AskAnswerPayload | null; // null when cancelled -} - -interface AskAnswerPayload { - answers: Array<{ - id: string; // matches question id - selectedOptions: string[]; - customInput?: string; // populated when user selects "Other" - }>; -} -``` - -### NEW: `src/planner/lib/ipc.ts` — IPC File I/O Primitives - -Atomic read/write/delete helpers for `ipc.json`. Both the subagent tool and the parent session use these functions. The atomic write pattern (tmp file → rename) matches `EventLog.writeState()` in `audit.ts`. - -**Functions:** -- `writeIpcFile(dir, data)` — atomic write via `.ipc.tmp.json` → `ipc.json` rename -- `readIpcFile(dir)` → `IpcFile | null` — returns null on missing file or parse error (treat parse error as "not ready" to handle partial writes on non-POSIX systems) -- `ipcFileExists(dir)` → `boolean` — fast `fs.access` check without parsing -- `deleteIpcFile(dir)` — removes `ipc.json` and any lingering `.ipc.tmp.json`; swallows ENOENT -- `createAskRequest(payload)` → `IpcFile` — creates file structure with `crypto.randomUUID()` id and `response: null` -- `createAskResponse(requestId, payload)` → `IpcResponse` — response with `cancelled: false` -- `createCancelledResponse(requestId)` → `IpcResponse` — response with `cancelled: true`, `payload: null` - -All types are exported for use by both subagent-side (`tools/ask.ts`) and parent-side (`session.ts`). - -### NEW: `src/planner/tools/ask.ts` — koan_ask_question Tool - -Registers `koan_ask_question` with the pi extension API. The tool schema uses TypeBox definitions identical to pi-ask-tool-extension. Imports `SubagentRef` from `../lib/dispatch.js` (not defined here — it lives in `dispatch.ts` alongside `PlanRef`). - -**Tool execute flow:** - -The entire poll loop is wrapped in a single `try/finally` that calls `deleteIpcFile(dir)`. This guarantees cleanup on all exit paths — success, cancellation, abort, and file disappearance — without requiring per-path deletion logic. - -1. Guard: if `subagentRef.dir` is null, return error (not in subagent context). -2. Guard: if `ipc.json` already exists, return error (one request at a time). -3. Create `IpcFile` via `createAskRequest(payload)`, write atomically. -4. Register `signal.addEventListener("abort", onAbort, { once: true })` for instant abort response. -5. Enter poll loop inside `try`: `while (!aborted) { await sleep(500); check signal; read ipc.json; if response !== null && response.id matches: break }`. -6. On response with `cancelled: false`: build `QuestionResult[]`, format via `buildSessionContent()`, return as tool result. (`finally` handles cleanup.) -7. On response with `cancelled: true`: return "The user declined to answer." (`finally` handles cleanup.) -8. On abort: return "The question was aborted." (`finally` handles cleanup.) -9. On file disappearing mid-poll (deleted externally): return "The question was cancelled." (`finally` handles cleanup, swallows ENOENT.) - -**Result formatting** mirrors pi-ask-tool-extension's `buildAskSessionContent()`: -``` -User answers: -auth: JWT - -Answer context: -Question 1 (auth) -Prompt: Which authentication model? -Options: - 1. JWT - 2. Session-based -Response: - Selected: JWT -``` - -### NEW: `src/planner/ui/ask/` — Copied Ask UI Components (4 files) - -Copy these files from `pi-ask-tool-extension/src/` (at `/Users/lmergen/.npm-global/lib/node_modules/pi-ask-tool-extension/src/`): - -1. **`ask-logic.ts`** (~98 lines) — `AskQuestion`, `AskOption`, `AskSelection` types; `OTHER_OPTION` constant; `buildSingleSelectionResult()`, `buildMultiSelectionResult()`, `appendRecommendedTagToOptionLabels()`. -2. **`ask-inline-note.ts`** (~65 lines) — Inline note rendering helpers. Uses `wrapTextWithAnsi` from `@mariozechner/pi-tui`. -3. **`ask-inline-ui.ts`** (~221 lines) — Single-question single-select UI. Renders cursor navigation (↑↓), inline note editing (Tab), submit (Enter) via `ui.custom()`. -4. **`ask-tabs-ui.ts`** (~512 lines) — Multi-question/multi-select tabbed UI. Tab bar (← Q1 Q2 ... ✓ Submit →), per-question option lists, Submit review tab via `ui.custom()`. - -**Import path requirements:** -- Relative import extensions use `.js` suffix: `"./ask-logic"` → `"./ask-logic.js"` (Node16 module resolution requires `.js` extensions in TypeScript source). -- Same for `"./ask-inline-note"` → `"./ask-inline-note.js"`. -- External dependencies (`@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`) resolve from koan's node_modules. - -### MODIFY: `src/planner/lib/dispatch.ts` — Add SubagentRef - -`SubagentRef` and `createSubagentRef()` live alongside `PlanRef` and `createPlanRef()` — both are mutable-ref infrastructure primitives that decouple static tool registration from runtime directory resolution. - -```diff -+// Decouples tool registration (init-time) from subagent directory -+// resolution (runtime, after flags available). Same indirection -+// pattern as PlanRef. -+export interface SubagentRef { -+ dir: string | null; -+} -+ -+export function createSubagentRef(): SubagentRef { -+ return { dir: null }; -+} -``` - -### MODIFY: `src/planner/tools/index.ts` — Thread SubagentRef - -```diff -+import { registerAskTools } from "./ask.js"; -+import type { SubagentRef } from "../lib/dispatch.js"; -+export type { SubagentRef } from "../lib/dispatch.js"; -+export { createSubagentRef } from "../lib/dispatch.js"; - - export function registerAllTools( - pi: ExtensionAPI, - planRef: PlanRef, - dispatch: WorkflowDispatch, -+ subagentRef: SubagentRef, - ): void { - registerWorkflowTools(pi, dispatch); - registerPlanGetterTools(pi, planRef); - registerPlanSetterTools(pi, planRef); - registerPlanDesignEntityTools(pi, planRef); - registerPlanCodeEntityTools(pi, planRef); - registerPlanStructureEntityTools(pi, planRef); - registerQRTools(pi, planRef); -+ registerAskTools(pi, subagentRef); - } -``` - -Note: `SubagentRef` is defined in `lib/dispatch.ts` (alongside `PlanRef`), not in `tools/ask.ts`. `tools/index.ts` re-exports it for convenience, matching the existing re-export pattern for `PlanRef`. - -### MODIFY: `extensions/koan.ts` — Create and Wire SubagentRef - -```diff --import { registerAllTools, createDispatch, createPlanRef } from "../src/planner/tools/index.js"; -+import { registerAllTools, createDispatch, createPlanRef, createSubagentRef } from "../src/planner/tools/index.js"; - - const dispatch = createDispatch(); - const planRef = createPlanRef(); -+ const subagentRef = createSubagentRef(); - -- registerAllTools(pi, planRef, dispatch); -+ registerAllTools(pi, planRef, dispatch, subagentRef); - - // In before_agent_start, inside `if (config.subagentDir)`: -+ subagentRef.dir = config.subagentDir; -``` - -The `subagentRef.dir = config.subagentDir` assignment goes immediately after the existing `eventLog = new EventLog(...)` line (L88), inside the same `if (config.subagentDir)` block. In parent mode, `subagentRef.dir` remains null, and the tool's execute returns an error. - -### MODIFY: `src/planner/lib/permissions.ts` — Grant Access to Work Phases - -```diff - [ - "plan-design", - new Set([ - "koan_complete_step", -+ "koan_ask_question", - ...PLAN_GETTER_TOOLS_LIST, - ...PLAN_SETTER_TOOLS_LIST, - ...PLAN_DESIGN_ENTITY_TOOLS, - ]), - ], - [ - "plan-code", - new Set([ - "koan_complete_step", -+ "koan_ask_question", - ...PLAN_GETTER_TOOLS_LIST, - ...PLAN_CHANGE_TOOLS_LIST, - "koan_set_intent", - ]), - ], - [ - "plan-docs", - new Set([ - "koan_complete_step", -+ "koan_ask_question", - ...PLAN_GETTER_TOOLS_LIST, - "koan_set_change_doc_diff", - "koan_set_change_comments", -``` - -QR phases (`qr-plan-design`, `qr-plan-code`, `qr-plan-docs`) omit `koan_ask_question` — reviewers do not ask questions. - -### MODIFY: `src/planner/session.ts` — Parent-Side Request Detection - -**A. New imports:** -```typescript -import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; -import { readIpcFile, writeIpcFile, createAskResponse, createCancelledResponse, type IpcFile } from "./lib/ipc.js"; -import { askSingleQuestionWithInlineNote } from "./ui/ask/ask-inline-ui.js"; -import { askQuestionsWithTabs } from "./ui/ask/ask-tabs-ui.js"; -import type { AskQuestion } from "./ui/ask/ask-logic.js"; -``` - -**B. New `handleAskRequest()` function** (module-level, alongside `runPlanningPhase`): - -Receives the parent's `ExtensionUIContext` and the parsed `IpcFile`. Routes to the appropriate ask UI based on question count and multi-select: -- Single question, single-select → `askSingleQuestionWithInlineNote(ui, question)` -- Single question, multi-select → `askQuestionsWithTabs(ui, [question])` -- Multiple questions → `askQuestionsWithTabs(ui, questions)` - -Returns an `IpcResponse` (either answered or cancelled). On any exception from the UI layer, returns a cancelled response so the subagent unblocks. - -**C. New `pollWithIpcDetection()` helper** (extracts the common poll-with-request-detection pattern): - -Both the work poll (~L335) and the fix poll (~L737) share the same request detection logic. A shared helper avoids duplication: - -```typescript -import type { LogLine } from "./lib/audit.js"; - -// Encapsulates the poll-with-request-detection pattern used by both -// the work poll loop and the fix poll loop. Returns a setInterval ID. -function pollWithIpcDetection( - subagentDir: string, - widget: WidgetController | null, - ui: ExtensionUIContext | null, - stepPrefix: string, - updateFromProjection: (p: Projection, logs: LogLine[]) => void, -): ReturnType { - let pendingRequestId: string | null = null; - - return setInterval(async () => { - // Existing: read projection and update widget - const [projection, logs] = await Promise.all([ - readProjection(subagentDir), - readRecentLogs(subagentDir), - ]); - if (projection) { - updateFromProjection(projection, logs); - } - - // IPC request detection — skip if already handling a request or no UI - if (pendingRequestId || !ui) return; - - const ipc = await readIpcFile(subagentDir); - if (!ipc || !ipc.request || ipc.response !== null) return; - - pendingRequestId = ipc.request.id; - try { - widget?.update({ - step: `${stepPrefix}: waiting for user input...`, - activity: ipc.request.payload.questions[0]?.question ?? "", - }); - - const response = await handleAskRequest(ui, ipc); - const updated: IpcFile = { request: ipc.request, response }; - await writeIpcFile(subagentDir, updated); - } catch { - // On error, write cancelled response so subagent unblocks. - // The inner try-catch guards against I/O failures during error - // recovery — an unguarded throw here would propagate as an - // unhandled async rejection in the setInterval callback, - // crashing the parent process (Node.js ≥15 default behavior). - try { - const cancelled = createCancelledResponse(ipc.request.id); - await writeIpcFile(subagentDir, { request: ipc.request, response: cancelled }); - } catch { - // I/O failed during error recovery; subagent remains blocked - // until parent terminates. No further action possible. - } - } finally { - pendingRequestId = null; - } - }, 2000); -} -``` - -**D. Thread `ui` through function signatures:** - -- `runPlanningPhase(phase, planDir, cwd, extensionPath, state, log, widget)` → add `ui: ExtensionUIContext | null` -- `runPhaseWithQR(phase, planDir, cwd, extensionPath, state, log, widget)` → add `ui: ExtensionUIContext | null` -- Call site in `plan()`: pass `ctx.hasUI ? ctx.ui : null` - -**E. Work poll loop (~L335):** -The work poll uses `pollWithIpcDetection(subagentDir, widget, ui, phase.key, ...)`. - -**F. Fix poll loop (~L737):** -The fix poll uses `pollWithIpcDetection(fixDir, widget, ui, \`${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}\`, ...)`. - -### MODIFY: `src/planner/lib/audit.ts` — Log Formatting - -Add `koan_ask_question` to the `KOAN_SHAPES` object for audit log display: - -```typescript -koan_ask_question: { keys: ["questions"], arrays: ["questions"], highValue: true }, -``` - -## Quality Checklist - -- [ ] 01-naming-and-types (design-mode): `SubagentRef` mirrors `PlanRef` naming; `IpcFile`/`IpcRequest`/`IpcResponse` model the domain; `handleAskRequest` describes behavior -- [ ] 02-structure-and-composition (design-mode): `pollWithIpcDetection` extracts shared logic from two poll loops; `handleAskRequest` is single-responsibility; error handling wraps UI calls with cancelled-response fallback -- [ ] 06-module-and-dependencies (design-mode): `lib/ipc.ts` is a pure I/O module with no UI dependencies; `tools/ask.ts` depends on `lib/ipc.ts` and `lib/dispatch.ts` (downward); `session.ts` depends on both `lib/ipc.ts` and `ui/ask/` (same level); no circular deps; `SubagentRef` lives in `lib/dispatch.ts` not in tools layer -- [ ] 07-cross-file-consistency (design-mode): Atomic write pattern matches `EventLog.writeState()`; mutable ref pattern matches `PlanRef`/`WorkflowDispatch` in `lib/dispatch.ts`; permission gating matches existing `PHASE_PERMISSIONS` entries; tool description style matches existing koan tools; error recovery in setInterval callbacks matches `verifyStatsPoll` guarded-catch pattern - -## Execution Protocol - -``` -1. delegate @agent-developer: implement per this plan file -2. delegate @agent-quality-reviewer: verify against plan + ~/.claude/conventions/code-quality/ (code-mode) - -When delegating, pass this plan file path. Supplement only with: -- rationale for decisions not captured in plan -- business constraints -- technical prerequisites the agent cannot infer -``` From d2ee2c41699d0cd0d20b446b9a8d8b1258624770 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 3 Mar 2026 19:58:25 +0700 Subject: [PATCH 036/412] Subagents can ask questions --- src/planner/phases/plan-code/prompts.ts | 5 ++ src/planner/phases/plan-design/fix-prompts.ts | 5 ++ src/planner/phases/plan-design/prompts.ts | 73 +++++++++++++++---- src/planner/phases/plan-docs/prompts.ts | 19 +++++ src/planner/phases/qr-decompose/prompts.ts | 30 +++++++- src/planner/plan/mutate/decisions.ts | 6 +- src/planner/plan/types.ts | 1 + src/planner/plan/validate.ts | 53 +++++++++++++- src/planner/tools/entity-design.ts | 8 +- src/planner/tools/getters.ts | 5 +- 10 files changed, 184 insertions(+), 21 deletions(-) diff --git a/src/planner/phases/plan-code/prompts.ts b/src/planner/phases/plan-code/prompts.ts index 0aaab34..d6bb9b2 100644 --- a/src/planner/phases/plan-code/prompts.ts +++ b/src/planner/phases/plan-code/prompts.ts @@ -39,6 +39,11 @@ export function buildPlanCodeSystemPrompt(basePrompt: string): string { "- NEVER use edit/write tools during plan-code.", "- Convert every code_intent into at least one code_change with intent_ref.", "- Use unified diffs in code_change.diff.", + "", + "CLARIFICATION:", + "If an intent is ambiguous about implementation (e.g. the behavior is clear", + "but multiple valid code patterns exist), use koan_ask_question to resolve", + "before writing the diff. Ask only when the choice materially affects code.", ].join("\n"); } diff --git a/src/planner/phases/plan-design/fix-prompts.ts b/src/planner/phases/plan-design/fix-prompts.ts index d9ec61e..80bd4ce 100644 --- a/src/planner/phases/plan-design/fix-prompts.ts +++ b/src/planner/phases/plan-design/fix-prompts.ts @@ -75,6 +75,11 @@ export function buildFixSystemPrompt( " - Each per-item step targets exactly ONE failure -- do not fix other items", " - Prefer updating existing entities over adding new ones", " - Do not restructure the plan beyond what failures require", + "", + "DECISION SOURCE FIXES:", + "If a failure is about a missing or weak decision source, use", + "koan_ask_question to get user input. Then update the decision with", + "source='user:ask' via koan_set_decision.", ].join("\n"); } diff --git a/src/planner/phases/plan-design/prompts.ts b/src/planner/phases/plan-design/prompts.ts index 928a102..cb2c682 100644 --- a/src/planner/phases/plan-design/prompts.ts +++ b/src/planner/phases/plan-design/prompts.ts @@ -10,7 +10,7 @@ export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { 2: "Codebase Exploration", 3: "Testing Strategy Discovery", 4: "Approach Generation", - 5: "Assumption Surfacing", + 5: "Ambiguity Resolution", 6: "Milestone Definition & Plan Writing", }; @@ -43,6 +43,17 @@ export function buildPlanDesignSystemPrompt(basePrompt: string): string { "", "CRITICAL: Do the actual work described in each step BEFORE calling", "koan_complete_step. Read files, explore code, analyze. Do not skip.", + "", + "DECISION PROVENANCE:", + "Every decision requires a source tag. Valid sources:", + " code: -- derived from reading source code", + " docs: -- derived from project documentation", + " user:ask -- user answered via koan_ask_question", + " user:conversation -- user stated in captured conversation", + " inference -- inferred from patterns (last resort; see step 5 rules)", + "If you cannot ground a decision in code or documentation, use", + "koan_ask_question. Ambiguity resolved by asking is better than", + "ambiguity resolved by assumption.", ].join("\n"); } @@ -121,24 +132,53 @@ export function planDesignStepGuidance( "", "Use exploration findings from step 2 to ground tradeoffs.", "Record approach analysis for step 6.", + "", + "DECISION INVENTORY:", + "For each approach, identify the implicit decisions it makes.", + "For each decision, note the source:", + " - code: -- forced by existing codebase (cite file)", + " - docs: -- specified in project docs (cite file)", + " - user:conversation -- user stated preference in conversation", + " - inference -- your judgment (requires strong reasoning_chain)", + " - UNRESOLVED -- no clear source; flag for step 5", ], }; case 5: return { - title: "Step 5: Assumption Surfacing", + title: "Step 5: Ambiguity Resolution", instructions: [ - "FAST PATH: Skip if task involves NONE of:", - " - Migration to new tech", - " - Policy defaults (lifecycle, capacity, failure handling)", - " - Architectural decisions with multiple valid approaches", - "", - "FULL CHECK (if any apply):", - " Audit each category with OPEN questions:", - " Pattern preservation, Migration strategy, Idiomatic usage,", - " Abstraction boundary, Policy defaults", - "", - "Record assumptions for step 6.", + "Review the decision inventory from step 4.", + "For every decision marked UNRESOLVED or sourced as inference:", + " 1. Can it be grounded in code or docs? Read them.", + " 2. If still unsourced, ask the user via koan_ask_question.", + "", + "USE koan_ask_question WHEN:", + " - Multiple approaches have comparable tradeoffs, no codebase precedent", + " - A policy default (timeout, capacity, retry, failure mode) has no value", + " - Migration path or abstraction boundary not dictated by code", + "", + "DO NOT ASK WHEN:", + " - Codebase establishes a clear pattern (source: code:)", + " - Project docs specify the approach (source: docs:)", + " - Only one approach is technically viable", + " - The choice follows directly from an already-sourced decision", + "", + "INFERENCE RULES (source: inference):", + " Acceptable: airtight reasoning, no viable alternative, follows from", + " existing constraints, standard practice with one correct answer.", + " NOT acceptable: hedging language, policy defaults, public API choices,", + " or any decision where a senior engineer might reasonably disagree.", + "", + "Good questions offer concrete options grounded in codebase evidence:", + " BAD: 'How should we handle errors?'", + " GOOD: 'Error propagation: (A) return Result matching src/foo.ts,", + " (B) throw + catch at boundary matching src/bar.ts'", + "", + "FAST PATH: If all decisions have code/docs/conversation sources,", + "skip asking and record this finding.", + "", + "After resolving, every decision has a concrete source. No UNRESOLVED.", ], }; @@ -152,6 +192,13 @@ export function planDesignStepGuidance( " BAD: 'Polling | Webhooks unreliable'", " GOOD: 'Use polling | 30% webhook failure -> need fallback anyway -> polling simpler'", "", + "Every koan_add_decision call MUST include a source parameter:", + " - code: -- derived from existing code (cite file)", + " - docs: -- from project documentation (cite file)", + " - user:ask -- asked the user via koan_ask_question", + " - user:conversation -- user stated in original conversation", + " - inference -- architect judgment (use sparingly; needs strong chain)", + "", "Use the following tools to build the plan:", "", "OVERVIEW & CONSTRAINTS:", diff --git a/src/planner/phases/plan-docs/prompts.ts b/src/planner/phases/plan-docs/prompts.ts index 081f08a..dcc8a91 100644 --- a/src/planner/phases/plan-docs/prompts.ts +++ b/src/planner/phases/plan-docs/prompts.ts @@ -43,6 +43,12 @@ export function buildPlanDocsSystemPrompt(basePrompt: string): string { "- Populate code_change.doc_diff for code changes.", "- Keep comments and docs timeless (no temporal contamination).", "- Keep architecture diagrams and README entries aligned with plan intent.", + "", + "USER-DECIDED DECISIONS:", + "Decisions with source user:ask or user:conversation have NO existing", + "reference in the codebase. These MUST be documented in code comments,", + "doc_diff, or README entries so future readers understand the rationale", + "without needing to ask the same question again.", ].join("\n"); } @@ -58,6 +64,11 @@ export function planDocsStepGuidance( "Use koan_get_plan to review decisions, constraints, risks, and milestones.", "Capture decision IDs that should be reflected in documentation rationale.", "", + "PRIORITY: Identify all decisions with source user:ask or user:conversation.", + "These have NO existing reference in code or docs -- the user provided", + "the authority. They MUST be documented. Track these IDs; steps 3-4", + "must cover every one.", + "", ...buildPlanDocsContextTrigger(conversationPath ?? "/conversation.jsonl"), "", "This step is read-only.", @@ -90,6 +101,12 @@ export function planDocsStepGuidance( " - Every code change with diff should have doc_diff", " - comments explain WHY (reference decisions where applicable)", " - Avoid temporal language (no 'added', 'changed from', 'now')", + "", + "USER-SOURCED DECISIONS (source user:ask / user:conversation):", + " These have no existing codebase reference. For each one that affects", + " a code change, the comment or doc_diff MUST capture the rationale so", + " future readers do not need to re-ask the same question.", + " Reference the decision ID (e.g. 'See DL-003') in the comment.", ], }; @@ -128,6 +145,8 @@ export function planDocsStepGuidance( " - all code changes with diff have doc_diff", " - comments/doc diffs are coherent and timeless", " - readme/diagram updates are present when needed", + " - every user-sourced decision (source user:*) is referenced", + " in at least one comment, doc_diff, or README entry", "", "Fix remaining issues before completing.", ], diff --git a/src/planner/phases/qr-decompose/prompts.ts b/src/planner/phases/qr-decompose/prompts.ts index e66c9d1..bb5fd81 100644 --- a/src/planner/phases/qr-decompose/prompts.ts +++ b/src/planner/phases/qr-decompose/prompts.ts @@ -33,7 +33,7 @@ export const DECOMPOSE_STEP_NAMES: Record = { const PHASE_SCOPE_HINTS: Record = { "plan-design": [ - "decision:DL-001 -- decision reasoning quality", + "decision:DL-001 -- decision reasoning quality and source provenance", "milestone:M-001 -- milestone structure", "code_intent:CI-M-001-001 -- intent clarity", ], @@ -46,6 +46,7 @@ const PHASE_SCOPE_HINTS: Record = { "milestone:M-001 -- docs completeness", "change:CC-M-001-001 -- doc_diff/comments quality", "diagram:DIAG-001 -- architecture docs fidelity", + "decision:DL-001 -- user-sourced decision docs coverage", ], }; @@ -93,6 +94,32 @@ export function buildDecomposeSystemPrompt(basePrompt: string, phase: WorkPhaseK ].join("\n"); } +// Phase-specific holistic concerns injected into step 2. +// plan-design adds decision source provenance checks; +// plan-docs adds user-sourced decision documentation coverage. +function holisticConcernAdditions(phase: WorkPhaseKey): string[] { + if (phase === "plan-design") { + return [ + "", + "Include decision provenance as a concern:", + " - Every decision must have a non-null source", + " - Sources must be verifiable (code/docs paths should exist)", + " - Decisions sourced as inference need strong reasoning_chain", + " - No systematic inference labeling (if >50% of decisions are", + " inference, flag as umbrella concern)", + ]; + } + if (phase === "plan-docs") { + return [ + "", + "Include user-sourced decision documentation as a concern:", + " - Decisions with source user:ask or user:conversation must be", + " referenced in at least one comment, doc_diff, or README entry", + ]; + } + return []; +} + export function decomposeStepGuidance( step: DecomposeStep, phase: WorkPhaseKey, @@ -119,6 +146,7 @@ export function decomposeStepGuidance( `List phase-wide concerns for ${phase}.`, "Focus on quality/completeness/consistency concerns, not implementation details.", "These become umbrella items (scope='*').", + ...holisticConcernAdditions(phase), ], }; diff --git a/src/planner/plan/mutate/decisions.ts b/src/planner/plan/mutate/decisions.ts index e5e7d1f..a43107b 100644 --- a/src/planner/plan/mutate/decisions.ts +++ b/src/planner/plan/mutate/decisions.ts @@ -12,13 +12,14 @@ import { export function addDecision( p: Plan, - data: { decision: string; reasoning: string }, + data: { decision: string; reasoning: string; source?: string }, ): { plan: Plan; id: string } { const id = nextDecisionId(p); const decision: Decision = { id, decision: data.decision, reasoning_chain: data.reasoning, + source: data.source ?? null, }; return { plan: { @@ -35,7 +36,7 @@ export function addDecision( export function setDecision( p: Plan, id: string, - data: { decision?: string; reasoning?: string }, + data: { decision?: string; reasoning?: string; source?: string }, ): Plan { const idx = p.planning_context.decision_log.findIndex((d) => d.id === id); if (idx === -1) throw new Error(`decision ${id} not found`); @@ -45,6 +46,7 @@ export function setDecision( ...d, decision: data.decision ?? d.decision, reasoning_chain: data.reasoning ?? d.reasoning_chain, + source: data.source ?? d.source, }; const log = [...p.planning_context.decision_log]; diff --git a/src/planner/plan/types.ts b/src/planner/plan/types.ts index 518b54e..4d21ca9 100644 --- a/src/planner/plan/types.ts +++ b/src/planner/plan/types.ts @@ -2,6 +2,7 @@ export interface Decision { id: string; decision: string; reasoning_chain: string; + source: string | null; } export interface RejectedAlternative { diff --git a/src/planner/plan/validate.ts b/src/planner/plan/validate.ts index c5ecedd..bfb4f52 100644 --- a/src/planner/plan/validate.ts +++ b/src/planner/plan/validate.ts @@ -7,6 +7,56 @@ import type { Plan } from "./types.js"; export interface ValidationResult { ok: boolean; errors: string[]; + warnings?: string[]; +} + +// -- Decision source provenance -- + +// Canonical source types for the type:ref format. +// "code" and "docs" carry a path ref; others stand alone. +const VALID_SOURCE_TYPES = [ + "code", "docs", "user:ask", "user:conversation", "inference", +] as const; + +export type DecisionSourceType = (typeof VALID_SOURCE_TYPES)[number]; + +const SOURCE_TYPE_SET: ReadonlySet = new Set(VALID_SOURCE_TYPES); + +// Parses "code:src/foo.ts" -> { type: "code", ref: "src/foo.ts" } +// Parses "inference" -> { type: "inference", ref: null } +// Returns null for unrecognized formats. +export function parseDecisionSource( + s: string, +): { type: DecisionSourceType; ref: string | null } | null { + const colon = s.indexOf(":"); + if (colon === -1) { + return SOURCE_TYPE_SET.has(s) ? { type: s as DecisionSourceType, ref: null } : null; + } + const prefix = s.substring(0, colon); + const rest = s.substring(colon + 1); + // "user:ask" and "user:conversation" are complete types, not type:ref pairs + const full = `${prefix}:${rest}`; + if (SOURCE_TYPE_SET.has(full)) return { type: full as DecisionSourceType, ref: null }; + // "code:" and "docs:" are type:ref pairs + if (SOURCE_TYPE_SET.has(prefix)) return { type: prefix as DecisionSourceType, ref: rest }; + return null; +} + +// Produces warnings (not errors) for decisions with missing or invalid sources. +// Soft validation: legacy plans have source: null; hard failures cause death loops. +export function validateDecisionSources(p: Plan): string[] { + const warnings: string[] = []; + for (const d of p.planning_context.decision_log) { + if (!d.source) { + warnings.push(`${d.id}: missing source -- expected code:, docs:, user:ask, user:conversation, or inference`); + continue; + } + const parsed = parseDecisionSource(d.source); + if (!parsed) { + warnings.push(`${d.id}: unrecognized source "${d.source}" -- expected code:, docs:, user:ask, user:conversation, or inference`); + } + } + return warnings; } export function validatePlanDesign(p: Plan): ValidationResult { @@ -26,7 +76,8 @@ export function validatePlanDesign(p: Plan): ValidationResult { } } - return { ok: errors.length === 0, errors }; + const warnings = validateDecisionSources(p); + return { ok: errors.length === 0, errors, warnings }; } export function validateRefs(p: Plan): ValidationResult { diff --git a/src/planner/tools/entity-design.ts b/src/planner/tools/entity-design.ts index 06552ee..c6e5e7d 100644 --- a/src/planner/tools/entity-design.ts +++ b/src/planner/tools/entity-design.ts @@ -66,16 +66,17 @@ export function registerPlanDesignEntityTools( planTool(pi, planRef, { name: "koan_add_decision", label: "Add decision", - description: "Add decision to decision log.", + description: "Add decision to decision log. Source identifies where authority came from (e.g. code:src/foo.ts, docs:CLAUDE.md, user:ask, user:conversation, inference).", parameters: Type.Object({ decision: Type.String(), reasoning: Type.String(), + source: Type.String({ description: "Provenance: code:, docs:, user:ask, user:conversation, or inference" }), }), execute: (p, params) => { const r = addDecision(p, params); return { plan: r.plan, - message: `Added decision ${r.id}: "${params.decision}"`, + message: `Added decision ${r.id}: "${params.decision}" [source: ${params.source}]`, }; }, }); @@ -83,11 +84,12 @@ export function registerPlanDesignEntityTools( planTool(pi, planRef, { name: "koan_set_decision", label: "Update decision", - description: "Update existing decision by ID.", + description: "Update existing decision by ID. Omitting source preserves the existing value.", parameters: Type.Object({ id: Type.String(), decision: Type.Optional(Type.String()), reasoning: Type.Optional(Type.String()), + source: Type.Optional(Type.String({ description: "Provenance: code:, docs:, user:ask, user:conversation, or inference" })), }), execute: (p, params) => { const updated = setDecision(p, params.id, params); diff --git a/src/planner/tools/getters.ts b/src/planner/tools/getters.ts index 712fc3d..d7924bb 100644 --- a/src/planner/tools/getters.ts +++ b/src/planner/tools/getters.ts @@ -138,7 +138,10 @@ function formatPlanSummary(p: Plan): string { ...p.milestones.map((m) => ` ${m.id}: ${m.name}`), "", `Decisions (${p.planning_context.decision_log.length}):`, - ...p.planning_context.decision_log.map((d) => ` ${d.id}: ${d.decision}`), + ...p.planning_context.decision_log.map((d) => { + const src = d.source ? ` [${d.source}]` : " [no source]"; + return ` ${d.id}: ${d.decision}${src}`; + }), "", `Waves (${p.waves.length}):`, ...p.waves.map((w) => ` ${w.id}: [${w.milestones.join(", ")}]`), From 4bb51d356b60174aab2a57256064b903a6973ec2 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 4 Mar 2026 11:31:48 +0700 Subject: [PATCH 037/412] Remove unused files --- QR_ANALYSIS.md | 643 ----------------------------------- QR_ANALYSIS_COMPREHENSIVE.md | 640 ---------------------------------- 2 files changed, 1283 deletions(-) delete mode 100644 QR_ANALYSIS.md delete mode 100644 QR_ANALYSIS_COMPREHENSIVE.md diff --git a/QR_ANALYSIS.md b/QR_ANALYSIS.md deleted file mode 100644 index 54ffc1f..0000000 --- a/QR_ANALYSIS.md +++ /dev/null @@ -1,643 +0,0 @@ -# QR Failure Handling & Fix Mode Analysis - -## Executive Summary - -This document analyzes how QR (Quality Review) failures halt execution in the koan plan-design phase and how the reference executor implements fix loops. The analysis covers three key questions: - -1. **Does QR failure halt the plan-design phase?** YES -- failures trigger a deterministic gate that either spawns a fix loop or force-proceeds after max iterations. -2. **What is the plan specification for QR fix loops?** Architect is re-spawned with `--koan-fix` flag and a QR failure report appended to context. -3. **What are the executor modes?** Initial mode (first-time work) vs. fix mode (targeted repair after QR failures). - ---- - -## Part 1: QR Failure Halts Execution (Confirmed) - -### How the QR Gate Works (Reference Executor) - -The reference executor in `~/.claude/skills/scripts/skills/planner/orchestrator/executor.py` implements a **9-step workflow** for execution (not planning): - -``` -Step 1: Execution Planning (analyze, build wave list) -Step 2: Reconciliation (validate existing code) -Step 3: Implementation (dispatch developers) -Step 4: Code QR (quality review of code) -Step 5: Code QR GATE (route pass/fail) <-- HALTS on FAIL -Step 6: Documentation (TW pass) -Step 7: Doc QR (quality review of docs) -Step 8: Doc QR GATE (route pass/fail) <-- HALTS on FAIL -Step 9: Retrospective -``` - -**Key excerpt from executor.py:** - -```python -CODE_QR_GATE = GateConfig( - qr_name="Code QR", - work_step=3, # If FAIL: loop back to step 3 - pass_step=6, # If PASS: advance to step 6 - pass_message="Code quality verified. Proceed to documentation.", - fix_target=AgentRole.DEVELOPER, # Developer fixes issues -) - -def format_gate(step: int, gate: GateConfig, qr: QRState, total_steps: int) -> str: - """Format gate step output.""" - if qr.passed: - next_cmd = f"python3 -m {MODULE_PATH} --step {gate.pass_step}" - else: - next_iteration = qr.iteration + 1 - next_cmd = f"python3 -m {MODULE_PATH} --step {gate.work_step} --qr-fail --qr-iteration {next_iteration}" - return format_step(body, next_cmd, title=f"{gate.qr_name} Gate") -``` - -**Execution halts on FAIL** because: -- QR GATE step 5 checks `qr.passed` property -- If FAIL: routes back to step 3 (implementation) with `--qr-fail` flag -- Step 3 detects fix mode and spawns developer with targeted repair instructions -- No automatic proceed to step 6 (documentation) - -### How the QR Gate Works (Koan Plan-Design) - -The koan project applies the same pattern to the plan-design phase. Based on the plan specification (section 4.2 and 5): - -``` -Plan-Design Phase (Architect): - ├─ execution: spawn architect subagent - │ (6-step exploration + plan writing) - │ - ├─ qr-decompose: spawn decomposer subagent - │ (13-step QR item generation) - │ - ├─ qr-verify: pool of reviewer subagents - │ (parallel verification, PASS/FAIL per item) - │ - └─ gate (deterministic code, no LLM) - PASS -> advance to plan-code - FAIL -> re-spawn architect with fix report (up to 5x) - iteration escalates severity filtering - after 5 iterations, force-proceed -``` - -**Plan specification (section 4.2.1 "QR Gate"):** - -```typescript -function routeGate( - phase: Phase, - qrResult: "pass" | "fail", - iteration: number, -): NextStep { - if (qrResult === "pass") { - deleteQRState(phase); - return nextPhase(phase); - } - const maxIterations = 5; - if (iteration >= maxIterations) { - return nextPhase(phase); // Force proceed, document remaining issues - } - return { phase, subPhase: "execution", mode: "fix", iteration: iteration + 1 }; -} -``` - -**Execution halts on FAIL** because: -- Gate routing is deterministic (pure code, no LLM) -- FAIL does not auto-advance -- Only PASS or max-iterations advances to next phase -- Fix mode spawns architect fresh with failure report - ---- - -## Architecture Pattern (From Old System) - -### Two-Phase Workflow Pattern - -QR operates in two distinct phases per plan phase (plan-design, plan-code, plan-docs, impl-code, impl-docs): - -1. **DECOMPOSITION** (QR Decompose) - - 8-step LLM workflow generating atomic verification items - - Creates `qr-{phase}.json` with items array - - Each item: `{id, scope, check, status: "TODO", severity, [parent_id], [group_id]}` - - Grouping logic (steps 9-13) organizes items by: parent-child, umbrella, component, concern, affinity - -2. **VERIFICATION** (QR Verify) - - Parallel dispatch of single items via `--qr-item` flag - - Each subagent verifies ONE item (ANALYZE -> CONFIRM -> SUMMARY pattern) - - Atomic mutation via `cli/qr.py` with file locking (no race conditions) - - Output: one-word PASS/FAIL only (findings in CLI --finding flag) - -### Key Files in Old System - -**Decomposition Scripts:** -- `/Users/lmergen/.claude/skills/scripts/skills/planner/quality_reviewer/plan_design_qr_decompose.py` -- `plan_code_qr_decompose.py` -- `plan_docs_qr_decompose.py` -- Shared: `skills/planner/quality_reviewer/prompts/decompose.py` (8-step workflow, grouping logic) - -**Verification Base:** -- `skills/planner/quality_reviewer/qr_verify_base.py` (VerifyBase class, step routing, item loading) -- Specific: `plan_design_qr_verify.py`, `plan_code_qr_verify.py`, `plan_docs_qr_verify.py` -- Shared: `skills/planner/shared/qr/utils.py` (load_qr_state, get_qr_item, format_qr_item_for_verification) - -**CLI Tools:** -- `skills/planner/cli/qr.py` (update-item with file locking) -- `skills/planner/cli/qr_commands.py` (update_item function, atomic write) - -## Decomposition Workflow (8 Steps) - -### Step 1: Absorb Context -- Load context.json and plan.json from STATE_DIR -- Parse planning context (overview, constraints, invisible knowledge) -- Task: Summarize in 2-3 sentences what success looks like for this phase - -### Step 2: Holistic Concerns (Top-Down) -- Brainstorm concerns specific to the phase (out-of-scope items explicitly excluded) -- Phase-specific examples (e.g., plan-design: "Missing decisions", "Policy defaults without backing") -- Output: Bulleted list, quantity over quality - -### Step 3: Structural Enumeration (Bottom-Up) -- List plan elements that exist in plan.json -- Use IDs where available (DL-001, M-001, etc.) -- Phase-specific (e.g., plan-design: decisions, constraints, risks, milestones, code_intents) - -### Step 4: Gap Analysis (Shared) -- Compare Step 2 concerns vs Step 3 elements -- Identify gaps: concerns not covered by elements, elements with no concerns -- Output: Umbrella vs specific items, cross-cutting vs targeted - -### Step 5: Generate Items (Phase-Specific Severity) -- Create verification items with UMBRELLA + SPECIFIC pattern -- Assign severity (MUST/SHOULD/COULD per phase-specific rules) -- Format: `{id, scope, check, status: "TODO", severity}` - -### Step 6: Atomicity Check (Shared) -- Review each item for atomicity (tests ONE thing, unambiguous pass/fail) -- Split non-atomic MUST items into parent + children (qa-002 -> qa-002a, qa-002b) -- Children inherit parent's severity, have parent_id field - -### Step 7: Coverage Validation (Shared) -- Use Step 3 enumeration as checklist -- Verify each element has at least one item covering it -- Verify each concern from Step 2 has at least one item -- Add items if gaps found (prefer over-coverage) - -### Step 8: Finalize -- Write qr-{phase}.json to STATE_DIR -- Format: `{phase, iteration: 1, items: [...]}` -- No fixed item count; content-driven - -### Steps 9-13: Grouping (Shared) -- **Step 9:** Structural grouping (deterministic: parent-child resolution, umbrella batching) -- **Step 10:** Component grouping (items verifying different aspects of same element) -- **Step 11:** Concern grouping (items checking same quality dimension across elements) -- **Step 12:** Affinity grouping (semantic similarity for remaining items) -- **Step 13:** Final validation (naming conventions, large group review, singleton review) - -## Phase-Specific Prompts - -### Plan-Design Phase - -**Step 1 Absorb:** -``` -Read plan.json from STATE_DIR: - cat $STATE_DIR/plan.json | jq '.' - -SCOPE: Plan structure and decision quality. - -Focus on: - - planning_context.decisions (completeness, reasoning quality) - - planning_context.constraints (all documented?) - - planning_context.risks (identified and addressed?) - - milestones[].code_intents (structure present?) - - invisible_knowledge (captured?) - -OUT OF SCOPE (verified in later phases): - - Code correctness (plan-code phase) - - Documentation quality (plan-docs phase) -``` - -**Step 2 Concerns:** -``` -Brainstorm concerns specific to PLAN STRUCTURE: - - Missing decisions (non-obvious choices not logged) - - Policy defaults without user backing - - Orphan milestones (no code_intents) - - Invalid references (decision_refs point nowhere) - - Reasoning chains too shallow - - Risks identified but not addressed - -DO NOT brainstorm code or documentation concerns (out of scope) -``` - -**Step 3 Enumeration:** -``` -For plan-design, enumerate PLAN STRUCTURE ARTIFACTS: - -DECISIONS: - - Each decision in planning_context.decisions (ID, decision text) - - Has reasoning? Multi-step chain? - -CONSTRAINTS: - - Each constraint in planning_context.constraints (ID, type) - - User-specified or inferred? - -RISKS: - - Each risk in planning_context.risks (ID, risk text) - - Has mitigation? - -MILESTONES: - - Each milestone (ID, name, count of code_intents) - - Each code_intent with decision_refs (ID, which decisions referenced) - -INVISIBLE KNOWLEDGE: - - system, invariants[], tradeoffs[] content -``` - -**Step 5 Severity (Plan-Design):** -``` -SEVERITY ASSIGNMENT (per conventions/severity.md, plan-design scope): - - MUST (blocks all iterations): - - DIAGRAM categories: - * ORPHAN_NODE: node with zero edges - * INVALID_EDGE_REF: edge references missing node - * INVALID_SCOPE_REF: scope references non-existent milestone - - KNOWLEDGE subset: - * DECISION_LOG_MISSING: non-trivial choice without logged rationale - * POLICY_UNJUSTIFIED: policy default without Tier 1 backing - * ASSUMPTION_UNVALIDATED: architectural assumption without citation - - SHOULD (iterations 1-4): - - Shallow reasoning chains (premise without implication) - - Missing risk mitigations - - Incomplete constraint documentation - - COULD (iterations 1-3): - - Cosmetic plan formatting - - Minor inconsistencies in naming -``` - -**Component Examples:** -``` - - A milestone - - A major decision - - A constraint category -``` - -**Concern Examples:** -``` - - Reasoning chain quality - - Reference integrity - - Risk coverage -``` - -### Plan-Code Phase - -**Step 1 Absorb:** -``` -Read plan.json from STATE_DIR: - cat $STATE_DIR/plan.json | jq '.' - -SCOPE: Code correctness in planned changes. - -Focus on: - - milestones[].code_intents[] -- what changes are intended - - milestones[].code_changes[] -- actual diff content - - code_changes[].diff (context lines must match codebase) - - code_changes[].why_comments[].decision_ref (refs must exist) - -OUT OF SCOPE (already verified in plan-docs phase): - - Documentation quality (temporal contamination, WHY-not-WHAT) - - README/CLAUDE.md content - - Invisible knowledge coverage -``` - -**Step 2 Concerns:** -``` -Brainstorm concerns specific to CODE CORRECTNESS: - - Context lines don't match actual codebase - - Diff format violations (missing +/- prefixes, wrong line counts) - - Code_intents without corresponding code_changes - - Invalid decision_refs in why_comments - - Type errors, missing imports, API mismatches - - Convention violations (per project style) - -DO NOT brainstorm documentation concerns (out of scope for this phase). -``` - -**Step 3 Enumeration:** -``` -For plan-code, enumerate CODE CHANGE ARTIFACTS: - -INTENTS: - - Each milestone's code_intents (ID, description) - - Intent-to-change mapping (which intents have changes?) - -CHANGES: - - Each code_change (ID, file path, line range) - - Files touched across all changes - - Context line locations requiring verification - -REFERENCES: - - decision_refs in why_comments (do they exist in planning_context?) - -DO NOT enumerate: - - documentation{} fields (plan-docs's job) - - readme_entries (plan-docs's job) -``` - -**Step 5 Severity (Plan-Code):** -``` -SEVERITY ASSIGNMENT (per conventions/severity.md, plan-code scope): - - MUST (blocks all iterations): - - ASSUMPTION_UNVALIDATED: architectural assumption without citation - - MARKER_INVALID: intent marker without valid explanation - - decision_ref references non-existent decision - - SHOULD (iterations 1-4) - STRUCTURE categories: - - GOD_OBJECT: >15 methods OR >10 deps - - GOD_FUNCTION: >50 lines OR >3 nesting - - CONVENTION_VIOLATION: violates documented project convention - - TESTING_STRATEGY_VIOLATION: tests don't follow confirmed strategy - - COULD (iterations 1-3) - COSMETIC: - - TOOLCHAIN_CATCHABLE: errors the compiler/linter would flag - - FORMATTER_FIXABLE: style issues fixable by formatter - - DEAD_CODE: unused functions, impossible branches - -DO NOT use KNOWLEDGE categories for documentation issues -- -those are plan-docs's responsibility. -``` - -**Component Examples:** -``` - - A file being modified - - A module/package - - A code_intent cluster -``` - -**Concern Examples:** -``` - - Error handling consistency - - Type safety across boundaries - - Testing boundary clarity -``` - -### Plan-Docs Phase - -**Step 1 Absorb:** -Similar structure, focus on doc_diff fields in code_changes - -**Step 2 Concerns:** -- Temporal contamination in doc_diffs (change-relative language) -- Baseline references (documentation assumes prior state) -- doc_diffs missing for non-empty diffs -- decision_refs in doc_diffs not captured - -**Step 3 Enumeration:** -- doc_diff content per code_change -- documentation{} fields (function docstrings, module comments) -- readme_entries content -- decision_log coverage in documentation - -**Step 5 Severity (Plan-Docs):** -Only KNOWLEDGE categories (TW cannot fix code): -- TEMPORAL_CONTAMINATION -- BASELINE_REFERENCE (doc assumes prior state) -- MISSING_DOC_DIFF (diff present, doc_diff absent) -- DECISION_UNCOVERED (decision not referenced in any doc_diff) - -## Verification Workflow (Per-Item Parallelization) - -### Base Class: VerifyBase - -Handles: -1. Step type routing (CONTEXT, ANALYZE, CONFIRM, SUMMARY) -2. Item loading from qr-{phase}.json -3. Dynamic step formula: `total_steps = 1 + (2 * num_items) + 1` - - Step 1: CONTEXT (load shared state) - - Steps 2..2N+1: ANALYZE/CONFIRM pairs per item - - Final step: SUMMARY - -### CONTEXT Step -- Load conventions, phase rules, context.json, plan.json -- List all items to verify -- Display severity and scope for each - -### ANALYZE Step (Per Item) -- Explore codebase if needed -- Form preliminary conclusion (PASS or FAIL) -- Task output: narrative analysis (no tool call yet) - -### CONFIRM Step (Per Item) -- Verify confidence in preliminary conclusion -- Execute CLI command to record result: - ```bash - python3 -m skills.planner.cli.qr --state-dir {state_dir} --qr-phase {phase} \ - update-item {item_id} --status PASS - ``` - Or: - ```bash - python3 -m skills.planner.cli.qr --state-dir {state_dir} --qr-phase {phase} \ - update-item {item_id} --status FAIL --finding '' - ``` -- Tool call blocks until file lock released (atomic update) - -### SUMMARY Step -- Count results, output single word: PASS or FAIL -- EXACT FORMAT REQUIRED: - - Output EXACTLY ONE WORD: "PASS" or "FAIL" - - No markdown headers (##, **) - - No "VERDICT:" prefix - - No explanation, prose, or reasoning - - Findings go in --finding flag, NOT in output - -## Phase-Specific Verification Guidance - -### Plan-Design Verification - -**Macro Check (scope: "\*"):** -``` -MACRO CHECK - Verify across entire plan.json: - - Read plan.json: - cat {state_dir}/plan.json | jq '.' -``` - -**Milestone Check (scope: "milestone:M-001"):** -``` -MILESTONE CHECK - Focus on M-001: - - Read milestone: - cat {state_dir}/plan.json | jq '.milestones[] | select(.id == "M-001")' -``` - -**Code Intent Check (scope: "code_intent:CI-M-001-001"):** -``` -CODE INTENT CHECK - Focus on CI-M-001-001: - - Read intent (find containing milestone first): - cat {state_dir}/plan.json | jq '.milestones[].code_intents[] | select(.id == "CI-M-001-001")' -``` - -**Check-Specific Guidance:** - -Decision Log Verification: -``` -DECISION LOG VERIFICATION: - - Each entry should have multi-step reasoning - - BAD: 'Polling | Webhooks unreliable' - - GOOD: 'Polling | 30% webhook failure -> need fallback anyway' -``` - -Policy Default Verification: -``` -POLICY DEFAULT VERIFICATION: - - Policy defaults affect user/org (lifecycle, capacity, failure handling) - - Must have Tier 1 (user-specified) backing in decision_log - - Technical defaults can use Tier 2-3 backing -``` - -Code Intent Verification: -``` -CODE INTENT VERIFICATION: - - Each implementation milestone needs code_intents - - Each code_intent needs file path and behavior - - decision_refs should point to valid decision_log entries -``` - -### Plan-Code Verification - -Similar structure with code-specific checks: -- Context line verification (diff patterns exist in actual files) -- Diff format validation (RULE 0/1/2) -- Intent linkage (code_change.intent_ref valid) -- Decision ref validity -- Temporal contamination in comments -- WHY-not-WHAT quality - -### Plan-Docs Verification - -Doc-specific checks: -- Temporal contamination in doc_diffs -- Baseline references (doc assumes prior state) -- Code without docs (diff present, doc_diff absent) -- Invalid diff format -- Decision coverage in docs -- WHY-not-WHAT verification -- Missing docstrings - -## Data Structures - -### QR Item (qr-{phase}.json) - -```typescript -interface QRItem { - id: string; // e.g., "plan-001", "qa-002a" - scope: string; // "*" (macro) or "element:ID" or "file:path" - check: string; // Description of what to verify - status: "TODO" | "PASS" | "FAIL"; - severity?: "MUST" | "SHOULD" | "COULD"; // Default: "SHOULD" - finding?: string; // Only for FAIL status - parent_id?: string; // For split items (qa-002a has parent_id: "qa-002") - group_id?: string; // For grouping (umbrella, component-*, concern-*, affinity-*, parent-*) - version?: number; // Default: 1, incremented on each update -} - -interface QRState { - phase: string; // "plan-design", "plan-code", etc. - iteration: number; // Current iteration (1 on first decompose) - items: QRItem[]; -} -``` - -### Severity Blocking Rules - -Per iteration: -- Iteration 1: MUST blocks all 4 iterations of fixes, SHOULD blocks iterations 1-4, COULD blocks 1-3 -- Iteration 2: MUST blocks iterations 2-5, SHOULD blocks 2-5, COULD blocks 2-4 -- Iteration 3: MUST blocks iterations 3-6, SHOULD blocks 3-6, COULD blocks 3-5 -- Iteration 4: MUST blocks iterations 4+, SHOULD blocks 4+, COULD blocks 4+ -- After iteration 4: No blocking (move to manual review) - -## Integration with Koan Architecture - -### Expected File Structure -``` -src/planner/phases/ - qr/ - decompose/ - phase.ts # QRDecomposePhase class (8-step workflow) - prompts.ts # Phase-specific step prompts - verify/ - phase.ts # QRVerifyPhase class (item-based verification) - prompts.ts # Verification guidance per phase - lib/ - items.ts # QRItem type, load/save, atomic mutations - grouping.ts # Steps 9-13 grouping logic -``` - -### Phase Registration -```typescript -// In phases/dispatch.ts -if (config.role === "quality-reviewer" && config.phase === "plan-design") { - const phase = new QRDecomposePhase(...); - await phase.begin(); -} -``` - -### Tool Registration -- QR tools likely smaller subset than plan-design (mainly read tools, no plan mutations) -- Tools may include: qr_update_item (atomic write), qr_load_state (read), qr_get_item (lookup) - -## Critical Implementation Notes - -### 1. Decomposition is Single-Run -- Decompose runs ONCE per phase (steps 1-8, 9-13) -- Orchestrator skips decompose if qr-{phase}.json already exists with iteration >=1 -- Each phase has own decomposition script (can't share due to phase-specific prompts) - -### 2. Verification is Parallel -- Each item dispatched as separate subagent with --qr-item flag -- File locking in CLI prevents race conditions -- No shared state mutation; each agent writes its own result atomically - -### 3. Step Gates Must Use Blocklists -- Whitelist fails open (blocks read tools unintentionally) -- Blocklist defers to checkPermission for everything not explicitly gated -- Example: `if (step < 6 && PLAN_MUTATION_TOOLS.has(name)) { block }` - -### 4. Findings in CLI Flag, Not Output -- Tool result is NOT return value; findings go in `--finding` flag -- SUMMARY step outputs ONE WORD only (PASS or FAIL) -- This avoids "text + tool_call in same response" bug (GPT-5-codex) - -### 5. invoke_after Two-Part Gate -- Every step prompt ends with "WHEN DONE: call koan_complete_step" -- Tool description includes "Do NOT call until told" -- Dual gates ensure single transition per step - -### 6. Disk-Backed Mutations -- Every tool mutation writes qr-{phase}.json immediately -- No finalize pattern; descriptive feedback on each write -- This prevents LLM from skipping intermediate mutations - -### 7. Severity Blocking vs Iteration Count -- Blocking set determined at gate time, not item creation time -- by_blocking_severity(iteration) is a predicate factory -- Iteration 0 not used; iteration 1 is first decompose, iteration 2+ are retries - -## Migration Checklist - -- [ ] Create QRDecomposePhase class with 8-step + 5-step grouping workflow -- [ ] Implement phase-specific prompts for plan-design, plan-code, plan-docs -- [ ] Create QRVerifyPhase class with CONTEXT/ANALYZE/CONFIRM/SUMMARY routing -- [ ] Implement VerifyBase-like step mapping (total_steps formula, item routing) -- [ ] Implement atomic QRItem mutations with file locking -- [ ] Add qr_update_item tool (wrapper around file-locked write) -- [ ] Add qr_load_state, qr_get_item tools (read-only) -- [ ] Register phases in dispatch.ts for quality-reviewer role -- [ ] Add QR phase detection to before_agent_start handler -- [ ] Implement SUMMARY step output validation (one word only) -- [ ] Test decompose single-run enforcement (skip if iteration >=1) -- [ ] Test parallel verify with file locking (concurrent writes) -- [ ] Test severity blocking at iteration thresholds -- [ ] Copy exact prompts from Python scripts (no rewriting) diff --git a/QR_ANALYSIS_COMPREHENSIVE.md b/QR_ANALYSIS_COMPREHENSIVE.md deleted file mode 100644 index 29b04ff..0000000 --- a/QR_ANALYSIS_COMPREHENSIVE.md +++ /dev/null @@ -1,640 +0,0 @@ -# QR Failure Handling & Fix Mode Analysis - -## Executive Summary - -This document analyzes how QR (Quality Review) failures halt execution in the koan plan-design phase and how the reference executor implements fix loops. The analysis covers three key questions: - -1. **Does QR failure halt the plan-design phase?** YES -- failures trigger a deterministic gate that either spawns a fix loop or force-proceeds after max iterations. -2. **What is the plan specification for QR fix loops?** Architect is re-spawned with `--koan-fix` flag and a QR failure report appended to context. -3. **What are the executor modes?** Initial mode (first-time work) vs. fix mode (targeted repair after QR failures). - ---- - -## Part 1: QR Failure Halts Execution (Confirmed) - -### How the QR Gate Works (Reference Executor) - -The reference executor in `~/.claude/skills/scripts/skills/planner/orchestrator/executor.py` implements a **9-step workflow** for execution: - -``` -Step 1: Execution Planning (analyze, build wave list) -Step 2: Reconciliation (validate existing code) -Step 3: Implementation (dispatch developers) -Step 4: Code QR (quality review of code) -Step 5: Code QR GATE (route pass/fail) <-- HALTS on FAIL -Step 6: Documentation (TW pass) -Step 7: Doc QR (quality review of docs) -Step 8: Doc QR GATE (route pass/fail) <-- HALTS on FAIL -Step 9: Retrospective -``` - -**Key excerpt from executor.py:** - -```python -CODE_QR_GATE = GateConfig( - qr_name="Code QR", - work_step=3, # If FAIL: loop back to step 3 - pass_step=6, # If PASS: advance to step 6 - pass_message="Code quality verified. Proceed to documentation.", - fix_target=AgentRole.DEVELOPER, # Developer fixes issues -) - -def format_gate(step: int, gate: GateConfig, qr: QRState, total_steps: int) -> str: - """Format gate step output.""" - if qr.passed: - next_cmd = f"python3 -m {MODULE_PATH} --step {gate.pass_step}" - else: - next_iteration = qr.iteration + 1 - next_cmd = f"python3 -m {MODULE_PATH} --step {gate.work_step} --qr-fail --qr-iteration {next_iteration}" - return format_step(body, next_cmd, title=f"{gate.qr_name} Gate") -``` - -**Execution halts on FAIL** because: -- QR GATE step 5 checks `qr.passed` property -- If FAIL: routes back to step 3 (implementation) with `--qr-fail` flag -- Step 3 detects fix mode and spawns developer with targeted repair instructions -- No automatic proceed to step 6 (documentation) - -### How the QR Gate Works (Koan Plan-Design) - -The koan project applies the same pattern. Based on the plan specification (section 4.2 and 5 of plans/2026-02-10-init.md): - -``` -Plan-Design Phase (Architect): - ├─ execution: spawn architect subagent - │ (6-step exploration + plan writing) - │ - ├─ qr-decompose: spawn decomposer subagent - │ (13-step QR item generation) - │ - ├─ qr-verify: pool of reviewer subagents - │ (parallel verification, PASS/FAIL per item) - │ - └─ gate (deterministic code, no LLM) - PASS -> advance to plan-code - FAIL -> re-spawn architect with fix report (up to 5x) - iteration escalates severity filtering - after 5 iterations, force-proceed -``` - -**Plan specification routing logic (section 4.2.1):** - -```typescript -function routeGate( - phase: Phase, - qrResult: "pass" | "fail", - iteration: number, -): NextStep { - if (qrResult === "pass") { - deleteQRState(phase); - return nextPhase(phase); - } - const maxIterations = 5; - if (iteration >= maxIterations) { - return nextPhase(phase); // Force proceed, document remaining issues - } - return { phase, subPhase: "execution", mode: "fix", iteration: iteration + 1 }; -} -``` - -**Execution halts on FAIL** because: -- Gate routing is deterministic (pure code, not prompt-based) -- FAIL does not auto-advance -- Only PASS or max-iterations advances to next phase -- Fix mode spawns architect fresh with failure report - ---- - -## Part 2: Plan Specification for QR Fix Loops - -### Fix Mode Activation - -From plan section 4.2 "First attempt vs. fix mode": - -> When a phase's QR gate returns FAIL, the orchestrator re-spawns the subagent with an additional flag (`--koan-fix`) and appends the QR failure report to the context file. The subagent's role hooks detect fix mode and adjust step instructions to focus on fixing specific issues identified by the QR. - -**Mechanism:** - -1. **Gate detects FAIL** → compute `iteration + 1` -2. **Orchestrator spawns subagent** with: - - `--koan-fix` flag (new) - - `--koan-fix-iteration N` flag (new) - - Same `--koan-plan-dir` (plan.json + context.json + qr-plan-design.json all present) -3. **Context file is mutated** to append QR failures: - - Original 8 context categories remain (read-only) - - QR failures appended in a new `qr_failures` section -4. **Role hooks detect fix mode** via flags in `before_agent_start` -5. **Step instructions adjust** to focus on fixing - -### Reference Architect Fix Prompt - -The reference architect fix script is `~/.claude/skills/scripts/skills/planner/architect/plan_design_qr_fix.py` (3-step workflow): - -**Step 1: Load QR Failures** - -``` -FIX MODE - QR Iteration {qr_iteration} - -QR-COMPLETENESS found issues in the plan. - -FAILED QR ITEMS TO FIX (address these FIRST): -================================================ -[plan-001] Decision log completeness - Scope: decision_log entry DL-005 - Finding: Decision reference missing backing premise - -[plan-002] Code intent specification - Scope: code_intent id CI-M-001-001 - Finding: Behavior description incomplete (unclear acceptance criteria) - -================================================ - -PLANNING CONTEXT (reference for semantic validation): -(context.json displayed for validation reference) - -For EACH failed item: - 1. Read the 'finding' field to understand the issue - 2. Identify what in plan.json needs to change - 3. Note the fix approach for step 2 -``` - -**Step 2: Apply Targeted Fixes** - -``` -APPLY targeted fixes to plan.json using CLI commands. - -Missing decision_log entry: - python3 -m skills.planner.cli.plan --state-dir $STATE_DIR set-decision \ - --decision '' \ - --reasoning ' implication -> conclusion>' - -BATCH MODE (preferred): - python3 -m skills.planner.cli.plan --state-dir $STATE_DIR batch '[ - {"method": "set-decision", "params": {...}, "id": 1}, - {"method": "set-intent", "params": {...}, "id": 2} - ]' - -CONSTRAINT: Fix ONLY the failing items. Don't refactor passing items. -``` - -**Step 3: Validate Fixes** - -``` -Run structural validation: - python3 -m skills.planner.cli.plan validate --phase plan-design - -SELF-CHECK each fixed item: - For each FAIL item you addressed: - - Does the fix address the specific finding? - - Does the fix introduce new issues? - -If validation passes: - Your complete response must be exactly: PASS - Do not add summaries, explanations, or any other text. -``` - -### Key Design Points in Fix Mode - -1. **QR failures explicitly listed** -- The architect sees exactly which items failed + why (the "finding" field) -2. **Plan mutations via existing CLI** -- Fix mode doesn't add new mutation tools, just focuses the prompt on specific items -3. **Targeted not holistic** -- Fix mode does NOT re-explore codebase. It reads the QR report and applies surgical fixes. -4. **No flailing** -- The constraint "Fix ONLY the failing items" prevents second-guessing the entire plan -5. **Validation is mandatory** -- Each fix iteration must pass `python3 -m ... validate` before reporting PASS - -### Iteration Escalation with Severity Filtering - -QR items have a `severity` field: MUST | SHOULD | COULD - -**Severity filtering logic (implied by shared/qr/constants.py):** - -```python -def get_blocking_severities(iteration: int) -> Set[str]: - """Items that block at this iteration. - - iteration 1: MUST only - iteration 2: MUST, SHOULD - iteration 3+: MUST, SHOULD, COULD (all) - """ -``` - -**Meaning:** On iteration 1, only critical (MUST) items block. By iteration 3, even minor (COULD) items block. This escalates pressure to fix progressively more issues. - ---- - -## Part 3: Executor Modes (Initial vs. Fix) - -### Reference Executor: Initial Mode - -When a phase is first executed (no prior failures): - -**Step 3: Implementation (Initial Mode)** - -```python -def format_step_3_implementation(qr: QRState, total_steps: int, ...) -> str: - if qr.state == LoopState.RETRY: - # Fix mode (handled separately) - ... - else: - # Initial mode - actions.extend([ - "Execute ALL milestones using wave-aware parallel dispatch.", - "", - "WAVE-AWARE EXECUTION:", - " - Milestones within same wave: dispatch in PARALLEL", - " - Waves execute SEQUENTIALLY", - "", - "FOR EACH WAVE:", - " 1. Dispatch developer agents for ALL milestones in wave", - " 2. Each prompt includes: plan, milestone, files, acceptance criteria", - " 3. Wait for ALL agents in wave to complete", - " 4. Run tests: pytest / tsc / go test -race", - " 5. Proceed to next wave", - "", - "After ALL waves complete, proceed to Code QR.", - ]) -``` - -**Initial mode** is the "full breadth" mode: -- No prior failures to fix -- Execute all milestones -- Waves in sequence, milestones within wave in parallel -- Standard tests + validation - -### Reference Executor: Fix Mode - -When a QR gate returns FAIL and iteration < 5: - -**Step 3: Implementation (Fix Mode)** - -```python -def format_step_3_implementation(qr: QRState, total_steps: int, ...) -> str: - if qr.state == LoopState.RETRY: - actions.append(format_state_banner("IMPLEMENTATION FIX", qr.iteration, "fix")) - actions.append("FIX MODE: Code QR found issues.") - actions.append("") - - mode_script = get_mode_script_path("dev/fix-code.py") - invoke_cmd = f"python3 -m {mode_script} --step 1 --qr-fail --qr-iteration {qr.iteration}" - - actions.append(subagent_dispatch( - agent_type="developer", - command=invoke_cmd, - )) - actions.append("Developer reads QR report and fixes issues in blocks.") - actions.append("After developer completes, re-run Code QR for fresh verification.") -``` - -**Fix mode** is the "targeted repair" mode: -- QR failures are present (in memory and on disk) -- Dispatch specialized fix agent (different script/prompts) -- Agent reads QR failure items -- Agent applies fixes to milestones mentioned in failures -- Re-run QR immediately after (fresh verification) - -### Comparison Table - -| Aspect | Initial Mode | Fix Mode | -|--------|--------------|----------| -| **Trigger** | First execution | QR FAIL (iteration < 5) | -| **Context** | No prior failures | QR items with status=FAIL + findings | -| **Scope** | All milestones | Only milestones in QR failures | -| **Agent Dispatch** | Full work agent | Specialized fix agent | -| **Step Sequence** | Role's standard N-step | 3-step fix workflow | -| **Tools Available** | Full read + write | Same tools (focus via prompt) | -| **Exit Condition** | Role completes final step | PASS to QR (no FAIL) | -| **Next** | Proceed to QR decompose | Re-run QR immediately | -| **Iteration** | N/A | 1, 2, 3, ... (max 5) | - -### How the Executor Decides Which Mode - -**Flag detection in executor.py:** - -```python -# format_step_3_implementation -state = LoopState.RETRY if qr_fail else LoopState.INITIAL - -# Gate's FAIL routing: -next_cmd = f"python3 -m {MODULE_PATH} --step {work_step} --qr-fail --qr-iteration {next_iteration}" -``` - -When gate returns FAIL, step 3 is re-invoked with `--qr-fail --qr-iteration 2`, and the formatter detects fix mode. - ---- - -## Part 4: Reference Implementation Deep Dive - -### Shared QR Infrastructure - -Located in `~/.claude/skills/scripts/skills/planner/shared/qr/`: - -**types.py:** - -```python -class QRStatus(Enum): - PASS = "pass" - FAIL = "fail" - -class LoopState(Enum): - INITIAL = "initial" - RETRY = "retry" - COMPLETE = "complete" - -@dataclass -class QRState: - iteration: int = 1 - state: LoopState = LoopState.INITIAL - status: QRStatus | None = None - - @property - def passed(self) -> bool: - return self.status == QRStatus.PASS - - def transition(self, status: QRStatus) -> None: - if status == QRStatus.PASS: - self.state = LoopState.COMPLETE - else: - self.state = LoopState.RETRY - self.iteration += 1 - -@dataclass -class GateConfig: - qr_name: str - work_step: int # Where to loop back on FAIL - pass_step: int | None # Where to go on PASS - pass_message: str - fix_target: AgentRole | None # Developer / Writer / Architect -``` - -**gates.py:** - -```python -def build_gate_output( - module_path: str, - qr_name: str, - qr: QRState, - work_step: int, - pass_step: int | None, - pass_message: str, - fix_target: AgentRole | None, - state_dir: str, -) -> GateResult: - """Build complete gate step output for QR gates. - - Gates route to either: - - pass_step: QR passed, proceed to next workflow phase - - work_step: QR failed, loop back to fix issues - """ - if qr.passed: - next_cmd = f"python3 -m {module_path} --step {pass_step}" - else: - next_cmd = f"python3 -m {module_path} --step {work_step} --state-dir {state_dir}" - - return GateResult( - output=format_step(body, next_cmd, title=title), - terminal_pass=qr.passed and pass_step is None, - ) -``` - -### How the Architect Fix Prompts Load QR Failures - -**plan_design_qr_fix.py, step 1:** - -```python -def get_step_guidance(step: int, module_path: str = None, **kwargs) -> dict: - if step == 1: - state_dir = kwargs.get("state_dir", "") - qr_iteration = get_qr_iteration(state_dir, PHASE) - - # Load failed items from qr-{phase}.json - qr_state = load_qr_state(state_dir, PHASE) - failed_items_block = format_failed_items_for_fix(qr_state) - - return { - "title": STEPS[1], - "actions": [ - f"FIX MODE - QR Iteration {qr_iteration}", - "", - "QR-COMPLETENESS found issues in the plan.", - "", - failed_items_block, # <- Explicit list of failures - "", - "For EACH failed item:", - " 1. Read the 'finding' field to understand the issue", - " 2. Identify what in plan.json needs to change", - " 3. Note the fix approach for step 2", - ], - } -``` - -**format_failed_items_for_fix output example:** - -``` -============================================================ -FAILED QR ITEMS TO FIX (address these FIRST): -============================================================ - -[QR-plan-design-001] Decision completeness - Scope: decision_log entry (id: DL-003) - Finding: Caching strategy selected but no justification. - -[QR-plan-design-002] Intent specification - Scope: code_intent (id: CI-M-001-001) - Finding: Behavior unclear: "Add caching layer" -- where? What TTL? - -[QR-plan-design-003] Risk documentation - Scope: known_risks - Finding: Redis failure mode not documented. - -============================================================ -``` - ---- - -## Part 5: Koan's QR Specification - -### Section 4.2: QR Block Pattern - -**Plan-Design Phase Structure:** - -``` -Phase 2: PLAN-DESIGN -├─ Execution (architect explores + writes plan) -├─ QR Decompose (decomposer generates items) -├─ QR Verify (reviewers verify items) -└─ Gate (route PASS->phase3 or FAIL->reexecute_with_fix) -``` - -### Section 4.2.1: QR Decomposition (13-step Workflow) - -The decomposer produces items with: -- `id`: unique item ID -- `scope`: `*` (cross-cutting) or element reference -- `check`: the verification question -- `status`: TODO | PASS | FAIL -- `finding`: explanation of FAIL (populated by reviewers) -- `severity`: MUST | SHOULD | COULD - -### Section 4.2.2: QR Verification (Parallel Subagents) - -Each reviewer subagent: -1. Receives assigned item group -2. For each item: ANALYZE -> CONFIRM -> update state -3. Returns per-item status -4. Aggregate: ANY FAIL = phase FAIL - -### Section 4.2.3: Fix Mode (Key Design Decision) - -From section 4.2: - -> When a phase's QR gate returns FAIL, the orchestrator re-spawns the subagent with an additional flag (`--koan-fix`) and appends the QR failure report to the context file. The subagent's role hooks detect fix mode and adjust step instructions to focus on fixing specific issues identified by the QR. - ---- - -## Part 6: Koan Implementation - -### Key Difference: Single Phase Handler vs. Separate Scripts - -**Reference executor:** -- `architect/plan_design_execute.py` (6 steps, first-time) -- `architect/plan_design_qr_fix.py` (3 steps, targeted repair) -- Separate scripts for each mode - -**Koan design:** -- Single `PlanDesignPhase` handler -- Phase hooks detect `--koan-fix` flag -- Step prompts adjust at runtime in the `context` event handler -- Same tools, same workflow -- just different prompt text - -### Koan Implementation Pattern (Inferred) - -```typescript -// src/planner/phases/plan-design/phase.ts - -export class PlanDesignPhase { - private state: PlanDesignState & { - fixMode: boolean; - fixIteration: number; - }; - - async begin(): Promise { - // Detect fix mode from flags - this.state.fixMode = this.pi.getFlag("koan-fix") === "true"; - this.state.fixIteration = parseInt(this.pi.getFlag("koan-fix-iteration") || "0"); - - // Load context.json (with QR failures appended if fixMode) - const contextPath = path.join(this.planDir, "context.json"); - const raw = await fs.readFile(contextPath, "utf8"); - this.state.contextData = JSON.parse(raw) as ContextData; - // context.qr_failures populated by orchestrator if fixMode - } - - private registerHandlers(): void { - this.pi.on("context", (event) => { - if (this.state.step !== 1) return undefined; - - let prompt = this.state.step1Prompt; - - // Adjust for fix mode - if (this.state.fixMode) { - prompt = adjustPromptForFixMode( - prompt, - this.state.fixIteration, - this.state.contextData.qr_failures, - ); - } - - const messages = event.messages.map((m) => - m.role === "user" ? { ...m, content: prompt } : m, - ); - return { messages }; - }); - } -} - -function adjustPromptForFixMode( - basePrompt: string, - iteration: number, - failures: Array<{id: string; scope: string; finding: string}>, -): string { - // Replace exploration sections with fix guidance - // Prepend: list of failed items + findings - // Add constraint: "Fix ONLY these items" - // Add validation guidance -} -``` - -### Orchestrator-Side: Appending QR Failures to Context - -When gate returns FAIL: - -```typescript -// 1. Load qr-plan-design.json -const qrPath = path.join(planDir, "qr-plan-design.json"); -const qr = JSON.parse(await fs.readFile(qrPath, "utf8")); - -// 2. Filter FAIL items -const failures = qr.items.filter(item => item.status === "FAIL").map(item => ({ - id: item.id, - scope: item.scope, - finding: item.finding, -})); - -// 3. Load context.json -const contextPath = path.join(planDir, "context.json"); -const context = JSON.parse(await fs.readFile(contextPath, "utf8")); - -// 4. Append failures -context.qr_failures = failures; -context.qr_iteration = iteration; - -// 5. Write back (atomic) -await writeContext(planDir, context); - -// 6. Spawn architect in fix mode -spawn("pi", [ - "-p", - "-e", extensionPath, - "--koan-role", "architect", - "--koan-phase", "plan-design", - "--koan-plan-dir", planDir, - "--koan-fix", "true", - "--koan-fix-iteration", String(iteration), - "Fix the plan issues identified in the QR report.", -]); -``` - ---- - -## Summary Table: Initial vs. Fix Mode - -| Dimension | Initial Mode | Fix Mode | -|-----------|--------------|----------| -| **QR State** | None (first execution) | FAIL (previous iteration) | -| **Orchestrator Decision** | Execute (fresh start) | Fix (failures present) | -| **Flags** | None | `--koan-fix true --koan-fix-iteration N` | -| **Context File** | 8 categories only | ^^ + `qr_failures` array | -| **Step Sequence** | 1=analysis, 2=exploration, ..., 6=write | 1=load failures, 2=fix, 3=validate | -| **Scope** | All codebase areas relevant to task | Only areas in QR failures | -| **Tools** | Full set (read + write) | Same set (focus via prompt) | -| **Exit** | PASS to orchestrator -> QR decompose | PASS to orchestrator -> re-run QR | -| **Iteration** | Not applicable | 1, 2, 3, ... (max 5) | -| **Severity Filter** | N/A | Escalates per iteration | -| **Outcome** | plan.json artifact | Updated plan.json (surgical fixes) | - ---- - -## Conclusion - -**QR failures halt execution in koan's plan-design phase** because the QR gate is deterministic code. The gate examines the QR result and either: -1. PASS → advance to next phase -2. FAIL + iteration < 5 → spawn architect in fix mode with failure report -3. FAIL + iteration >= 5 → force-proceed to next phase - -**Fix mode is a targeted repair workflow** that differs from initial mode by: -- Running a 3-step workflow (load -> fix -> validate) instead of N-step exploration -- Reading QR failures from context + disk -- Focusing fixes on listed items only -- Escalating severity requirements each iteration - -**The reference executor provides the exact implementation patterns** that koan follows, with the improvement that koan consolidates execute/fix logic into one phase handler via prompt adjustment, rather than separate scripts. - From 29cc2a3701bca463606d379a8042209a0dbe3dbb Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 4 Mar 2026 15:39:44 +0700 Subject: [PATCH 038/412] refactor: split runQRBlock into runQRDecompose + runQRVerify MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit runQRBlock unconditionally spawned the QR decomposer on every call, but runPhaseWithQR called it both for the initial run and after each fix iteration — causing the 13-step decompose workflow to re-execute on every QR cycle instead of just the first. Split at the natural seam between decompose (item generation) and verify (item evaluation): - runQRDecompose: spawns decomposer, carries forward PASS statuses, called once before the fix loop - runQRVerify: resets FAIL→TODO, groups items, spawns reviewer pool, called on every iteration The fix loop structurally cannot invoke decompose — it only calls runQRVerify. No boolean flags or runtime guards needed. --- src/planner/session.ts | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/src/planner/session.ts b/src/planner/session.ts index a0ec935..ecd79a4 100644 --- a/src/planner/session.ts +++ b/src/planner/session.ts @@ -541,7 +541,8 @@ async function runPlanningPhase( return qr; } -async function runQRBlock( + +async function runQRDecompose( planDir: string, cwd: string, extensionPath: string, @@ -646,6 +647,31 @@ async function runQRBlock( } } + return { summary: `${phase} QR decompose complete.`, passed: true }; +} + +async function runQRVerify( + planDir: string, + cwd: string, + extensionPath: string, + phase: WorkPhaseKey, + state: WorkflowState, + log: Logger, + widget: WidgetController | null, +): Promise { + const qrPath = qrFilePath(planDir, phase); + + let qr: QRFile; + try { + const raw = await fs.readFile(qrPath, "utf8"); + qr = JSON.parse(raw) as QRFile; + } catch (error) { + state.phase = "qr-decompose-failed"; + const message = error instanceof Error ? error.message : String(error); + log("Failed to read QR file for verify", { phase, error: message }); + return { summary: `${phase} QR verify aborted: cannot read QR file.`, passed: false }; + } + const resetFailures = qr.items.filter((i) => i.status === "FAIL").length; if (resetFailures > 0) { qr = { @@ -686,6 +712,7 @@ async function runQRBlock( widget?.update({ step: `${phase} qr-verify: 0/${groupEntries.length} groups (${totalTodoItems} items)`, activity: "", + qrPhase: "verify", qrTotal: totalItems, qrDone: preservedPass, qrPass: preservedPass, @@ -707,7 +734,6 @@ async function runQRBlock( }); state.phase = "qr-verify-running"; - widget?.update({ qrPhase: "verify" }); let verifyDone = 0; let failedReviewers: string[] = []; @@ -826,7 +852,13 @@ async function runPhaseWithQR( ): Promise { const qrPath = qrFilePath(planDir, phase.key); - let qr = await runQRBlock(planDir, cwd, extensionPath, phase.key, state, log, widget); + const decompose = await runQRDecompose(planDir, cwd, extensionPath, phase.key, state, log, widget); + if (!decompose.passed) { + widget?.update({ phaseStatus: { index: phase.widgetIndex, status: "failed" } }); + return decompose; + } + + let qr = await runQRVerify(planDir, cwd, extensionPath, phase.key, state, log, widget); if (qr.passed) { widget?.update({ qrPhase: "done", phaseStatus: { index: phase.widgetIndex, status: "completed" } }); return qr; @@ -936,7 +968,7 @@ async function runPhaseWithQR( subagentDone: 1, }); - qr = await runQRBlock(planDir, cwd, extensionPath, phase.key, state, log, widget); + qr = await runQRVerify(planDir, cwd, extensionPath, phase.key, state, log, widget); if (qr.passed) { widget?.update({ qrPhase: "done", phaseStatus: { index: phase.widgetIndex, status: "completed" } }); return qr; From fa6196cdbdd89f0daf668b347c28015dd8982cde Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 5 Mar 2026 10:04:21 +0700 Subject: [PATCH 039/412] refactor(widget): unify runtime section and remove current-step panel --- docs/planning-widget.md | 69 ++++----- src/planner/ui/widget.ts | 316 +++++++++------------------------------ tests/widget.test.ts | 58 +++++++ 3 files changed, 165 insertions(+), 278 deletions(-) diff --git a/docs/planning-widget.md b/docs/planning-widget.md index 2bbffb1..639a4c0 100644 --- a/docs/planning-widget.md +++ b/docs/planning-widget.md @@ -7,7 +7,7 @@ The planning widget now follows the design-deck contract selected on Feb 25 2026 - **Navigation direction:** Vertical Timeline Rail - **Header strategy:** Full-width top border + metadata header row (active phase in header, no tabs strip) - **Log strategy:** Declarative shape-table serialization + dense two-column layout -- **QR strategy:** Inline integrated section (not a detached sub-card) +- **Runtime strategy:** Unified runtime section (stage + quality + workers) integrated into the detail pane The goal is to keep a long-running (1-2h) planning session readable in real time while preserving high-signal audit telemetry. @@ -37,15 +37,14 @@ The goal is to keep a long-running (1-2h) planning session readable in real time **Rationale:** Preserves temporal fidelity while increasing information density and keeping the "what just happened" answer immediate, even under constrained widths. -### 4) QR is a first-class workflow section -- QR renders inline in detail pane with divider rule (no detached mini-card border). +### 4) Runtime is a first-class workflow section +- Runtime renders inline in the detail pane (no detached mini-card border). - Visible during Plan design, Plan code, and Plan docs (and contractually Plan execution). -- QR starts directly in the **`execute`** stage for iteration 1 (non-fix mode); fix iterations reuse the same stage model. -- QR block is normalized to a fixed structure: header, phase rail, counters, divider. -- Metadata is budgeted to **64 visible chars max** and progressively compacted (`phase/iter/mode` -> `iN/M`, `d/p/f/t`) when width is constrained. -- Counter line emphasizes severity: `fail` is error-colored; `pass` is accent; others remain muted/dim. +- Runtime unifies stage + quality counters + worker counters in one block. +- Stage follows the QR lifecycle (`execute`, `decompose`, `verify`, `done`) but uses user-facing labels (`Writing`, `Fixing`, `Analyzing`, `Verifying`, `Complete`). +- Quality counters emphasize severity: `FAIL` is error-colored; `pass` is accent; others remain muted/dim. -**Rationale:** QR is not optional side telemetry; it is the acceptance loop for the plan. The UI should communicate that structural importance while remaining legible and shape-stable at smaller widths. +**Rationale:** Review quality and worker throughput are part of one runtime story. Unifying them removes competing mini-status bars while keeping the left timeline as the primary progress signal. ### 5) Header-first metadata, tabs removed - Keep a full top border and put active workflow context directly in the header row. @@ -60,13 +59,13 @@ The goal is to keep a long-running (1-2h) planning session readable in real time ┌────────────────────────────────────────────────────────────────────────────────┐ │ Planning · Plan design · CURRENT 12m 22s │ │ │ -│ ● Plan design Current step │ -│ │ CURRENT Step 2/6: Codebase Exploration │ -│ │ read internal/rules/CLAUDE.md · 17L/1.2k │ -│ ○ Plan code QR | phase:execute · iter 1/6 initial │ -│ │ UPCOMING Execute → QR decompose → QR verify │ -│ ○ Plan docs done:0/- pass:0 fail:0 todo:- │ -│ UPCOMING Subagents queued:0 active:1 done:0 │ +│ ● Plan design Runtime │ +│ │ CURRENT stage : Writing (cycle 1/6 · initial) │ +│ │ quality : checked -/- pass - FAIL - remaining - │ +│ ○ Plan code workers : queued 0 active 1 done 0 pool ×1 │ +│ │ UPCOMING │ +│ ○ Plan docs │ +│ UPCOMING │ │ Plan ID : │ │ Agent : architect │ │ Model : openai-codex/gpt-5.3-codex │ @@ -87,12 +86,13 @@ The goal is to keep a long-running (1-2h) planning session readable in real time 4. **No tabs strip** – Do not render a separate phase-tabs row under the header. Active phase context now lives in header metadata. 5. **Timeline rail** – Maintain status icon/color semantics (`active=accent`, `done=dim`, `failed=error`). 6. **Detail pane** – Render in this order: - - a dim section label (`Current step`) to create hierarchy - - step title + optional activity - - QR integrated section (if visible) - - subagent counters (`queued/active/done`) when available + - Runtime section (if stage/quality/workers are active) - identity table (`Plan ID`, `Agent`/`Agent pool`, `Model`) pinned low in pane -7. **QR section** – Use inline header + phase rail + metadata line + divider. Avoid nested border style to keep it visually native to the right pane. Keep line geometry stable (fixed 3-line payload + divider) and enforce a 64-char metadata budget before clamping to pane width. +7. **Runtime section** – Use inline `Runtime` header plus key/value rows: + - `stage` + cycle metadata + - `quality` counters (`checked/pass/FAIL/remaining`) + - `workers` counters (`queued/active/done`) + pool capacity + Keep this as one cohesive block to avoid competing status bars. 8. **Latest log section** – Keep it inside the same outer card, separated by a horizontal divider. Reuse the same left/right column split (`timelineWidth` / `detailWidth`) and gap as the planning body so vertical alignment stays consistent. ## Header + Alignment Contract @@ -133,19 +133,21 @@ Apply in order until it fits: - `qrDone`, `qrTotal`, `qrPass`, `qrFail`, `qrTodo` ## Future Work (contracted, not yet implemented) -- Plan execution phase should reuse the same QR integrated section semantics. +- Plan execution phase should reuse the same Runtime section semantics. - Optional compact mode for very narrow terminals can reduce metadata verbosity while preserving deterministic ordering. -## Update: Runtime Domains + Subagent Identity (2026-02-26) +## Update: Unified Runtime Section + Subagent Identity (2026-03-04) -This update captures follow-up decisions for showing subagent model information -and clarifying QR vs. parallel subagent semantics. +This update replaces the split QR/subagent status blocks with a single runtime +status section in the right pane. -### Domain split (do not merge) -- **QR section** tracks quality state: `todo`, `pass`, `fail`. -- **Subagents section** tracks execution state: `queued`, `active`, `done`. -- These are sibling runtime views. They are related in workflow, but not - collapsed into one metric family. +### Runtime merge (stage + quality + workers) +- The detail pane now has one **Runtime** section. +- Runtime includes: + - `stage` (`Writing` / `Fixing` / `Analyzing` / `Verifying` / `Complete`) with cycle metadata. + - `quality` counters (`checked`, `pass`, `FAIL`, `remaining`). + - `workers` counters (`queued`, `active`, `done`) plus pool capacity. +- The left timeline remains the primary progress signal. ### `x` meaning in parallel mode - `x` means configured pool capacity (target parallelism), not active count. @@ -171,10 +173,5 @@ Label/value rule: - otherwise -> `Agent : ` ### View-composition pattern -Use section-level selectors/renderers (React-view-like composition without -React) so QR, subagent status, and identity/footer blocks are independently -composable and testable. - -### Decision hygiene -A separate "layout pattern" decision was deemed redundant once the domain split -was chosen; track it as derived behavior, not as a distinct product decision. +Use section-level selectors/renderers so `runtime-status` and `identity` remain +independently composable and testable. diff --git a/src/planner/ui/widget.ts b/src/planner/ui/widget.ts index 14a0391..bfe684e 100644 --- a/src/planner/ui/widget.ts +++ b/src/planner/ui/widget.ts @@ -340,79 +340,6 @@ function shouldShowQR(state: WidgetState): boolean { return true; } -type QRTier = "wide" | "medium" | "tight"; - -const QR_TIER_MEDIUM_WIDTH = 68; -const QR_TIER_TIGHT_WIDTH = 52; -const QR_META_MAX_CHARS = 64; - -function qrTier(width: number): QRTier { - if (width < QR_TIER_TIGHT_WIDTH) return "tight"; - if (width < QR_TIER_MEDIUM_WIDTH) return "medium"; - return "wide"; -} - -function qrPhaseLabel(phase: QRPhase): string { - switch (phase) { - case "idle": - return "execute"; - case "execute": - return "execute"; - case "decompose": - return "decompose"; - case "verify": - return "verify"; - case "done": - return "done"; - } -} - -function qrPhaseShortLabel(phase: QRPhase): string { - switch (phase) { - case "idle": - return "exec"; - case "execute": - return "exec"; - case "decompose": - return "decomp"; - case "verify": - return "vfy"; - case "done": - return "done"; - } -} - -function firstBudgeted(candidates: string[], budget: number): string { - for (const c of candidates) { - if (visibleWidth(c) <= budget) return c; - } - const fallback = candidates[candidates.length - 1] ?? ""; - return truncateToWidth(fallback, budget, "…", false); -} - -function qrMetaText(state: WidgetState, tier: QRTier, budget: number): string { - const phase = qrPhaseLabel(state.qrPhase); - const short = qrPhaseShortLabel(state.qrPhase); - const modeFull = state.qrMode === "fix" ? "fix" : "initial"; - const modeShort = state.qrMode === "fix" ? "fx" : "in"; - const iter = state.qrIteration ?? 0; - const iterMax = state.qrIterationsMax ? `/${state.qrIterationsMax}` : ""; - const iterFull = `${iter}${iterMax}`; - - const wide = `phase:${phase} · iter ${iterFull} ${modeFull}`; - const medium = `${phase} · iter ${iterFull} ${modeFull}`; - const compact = `${short} · i${iterFull} ${modeFull}`; - const tight = `${short} i${iterFull} ${modeShort}`; - - const candidates = tier === "wide" - ? [wide, medium, compact, tight] - : tier === "medium" - ? [medium, compact, tight] - : [compact, tight]; - - return firstBudgeted(candidates, budget); -} - interface QRCounterValues { done: string; pass: string; @@ -434,82 +361,82 @@ function qrCounterValues(state: WidgetState): QRCounterValues { }; } -function renderQRCounterLine(state: WidgetState, theme: Theme, tier: QRTier, width: number, budget: number): string { - const values = qrCounterValues(state); - - const labelSets = tier === "wide" - ? [ - { done: "done", pass: "pass", fail: "fail", todo: "todo" }, - { done: "d", pass: "p", fail: "f", todo: "t" }, - ] - : [{ done: "d", pass: "p", fail: "f", todo: "t" }]; - - const render = (labels: { done: string; pass: string; fail: string; todo: string }) => [ - `${theme.fg("muted", `${labels.done}:`)}${theme.fg("dim", values.done)}`, - `${theme.fg("muted", `${labels.pass}:`)}${theme.fg("accent", values.pass)}`, - `${theme.fg("muted", `${labels.fail}:`)}${theme.bold(theme.fg("error", values.fail))}`, - `${theme.fg("muted", `${labels.todo}:`)}${theme.fg("muted", values.todo)}`, - ].join(" "); - - const candidates = labelSets.map(render); - const selected = firstBudgeted(candidates, budget); - return clampToWidth(selected, width, "…"); +function runtimeStageLabel(state: WidgetState): string { + switch (state.qrPhase) { + case "idle": + case "execute": + return state.qrMode === "fix" ? "Fixing" : "Writing"; + case "decompose": + return "Analyzing"; + case "verify": + return "Verifying"; + case "done": + return "Complete"; + } +} + +function stageCycleText(state: WidgetState): string { + const iter = state.qrIteration ?? 0; + const iterMax = state.qrIterationsMax ? `/${state.qrIterationsMax}` : ""; + const mode = state.qrMode === "fix" ? "fix" : "initial"; + return `cycle ${iter}${iterMax} · ${mode}`; } -function renderQRStatusSection(state: WidgetState, theme: Theme, width: number): string[] { - if (!shouldShowQR(state)) { +function shouldShowRuntimeSection(state: WidgetState): boolean { + return shouldShowQR(state) || shouldShowSubagentSection(state); +} + +function renderRuntimeRow(theme: Theme, width: number, keyWidth: number, key: string, value: string): string { + const padded = key.padEnd(keyWidth, " "); + return clampToWidth(`${theme.fg("muted", padded)} : ${value}`, width, "…"); +} + +function renderRuntimeStatusSection(state: WidgetState, theme: Theme, width: number): string[] { + if (!shouldShowRuntimeSection(state)) { return []; } - const tier = qrTier(width); - const budget = Math.min(width, QR_META_MAX_CHARS); + const rows: Array<{ key: string; value: string }> = []; - const headerMeta = qrMetaText(state, tier, budget); - const header = clampToWidth( - `${theme.bold(theme.fg("accent", "QR"))} ${theme.fg("muted", "|")} ${theme.fg("dim", headerMeta)}`, - width, - "…", - ); + if (shouldShowQR(state)) { + const stageValue = `${theme.bold(theme.fg("accent", runtimeStageLabel(state)))} ${theme.fg("dim", `(${stageCycleText(state)})`)}`; + const values = qrCounterValues(state); + const qualityValue = [ + `${theme.fg("muted", "checked")} ${theme.fg("dim", values.done)}`, + `${theme.fg("muted", "pass")} ${theme.fg("accent", values.pass)}`, + `${theme.bold(theme.fg("error", "FAIL"))} ${theme.bold(theme.fg("error", values.fail))}`, + `${theme.fg("muted", "remaining")} ${theme.fg("muted", values.todo)}`, + ].join(" "); - const phaseEntries: Array<{ key: Exclude; label: string }> = tier === "wide" - ? [ - { key: "execute", label: state.qrMode === "fix" ? "Execute (fix)" : "Execute" }, - { key: "decompose", label: "QR decompose" }, - { key: "verify", label: "QR verify" }, - ] - : tier === "medium" - ? [ - { key: "execute", label: state.qrMode === "fix" ? "Exec(fix)" : "Exec" }, - { key: "decompose", label: "Decomp" }, - { key: "verify", label: "Verify" }, - ] - : [ - { key: "execute", label: "X" }, - { key: "decompose", label: "D" }, - { key: "verify", label: "V" }, - ]; - - const effectivePhase: Exclude = state.qrPhase === "idle" ? "execute" : state.qrPhase; - let currentIndex = phaseEntries.findIndex((entry) => entry.key === effectivePhase); - if (effectivePhase === "done") { - currentIndex = phaseEntries.length; + rows.push({ key: "stage", value: stageValue }); + rows.push({ key: "quality", value: qualityValue }); } - const segments = phaseEntries.map((entry, index) => { - if (index < currentIndex) { - return theme.bold(theme.fg("dim", `${entry.label} ✓`)); - } - if (index === currentIndex) { - return theme.bold(theme.fg("accent", entry.label)); - } - return theme.fg("muted", entry.label); - }); + if (shouldShowSubagentSection(state)) { + const parallel = state.subagentParallelCount ?? 1; + const pool = parallel > 1 ? `pool ×${parallel}` : "single"; + const workersValue = [ + `${theme.fg("muted", "queued")} ${theme.fg("muted", subagentCount(state.subagentQueued))}`, + `${theme.fg("muted", "active")} ${theme.bold(theme.fg("accent", subagentCount(state.subagentActive)))}`, + `${theme.fg("muted", "done")} ${theme.fg("dim", subagentCount(state.subagentDone))}`, + `${theme.fg("dim", pool)}`, + ].join(" "); + + rows.push({ key: "workers", value: workersValue }); + } - const rail = clampToWidth(segments.join(theme.fg("muted", " → ")), width, "…"); - const counters = renderQRCounterLine(state, theme, tier, width, budget); - const divider = clampToWidth(theme.fg("muted", "─".repeat(width)), width); + if (rows.length === 0) { + return []; + } + + const keyWidth = Math.max(...rows.map((row) => visibleWidth(row.key))); + const lines = [clampToWidth(theme.fg("dim", "Runtime"), width)]; - return [header, rail, counters, divider]; + for (const row of rows) { + lines.push(renderRuntimeRow(theme, width, keyWidth, row.key, row.value)); + } + + return lines; } interface DetailSections { @@ -524,11 +451,6 @@ interface DetailSectionDefinition { render: (view: ViewModel, theme: Theme, width: number) => string[]; } -interface CurrentStepView { - title: string; - activity: string; -} - interface IdentityView { planId: string; agentLabel: "Agent" | "Agent pool"; @@ -545,30 +467,6 @@ function subagentCount(value: number | null): string { return value === null ? "-" : String(value); } -function renderSubagentStatusSection(state: WidgetState, theme: Theme, width: number): string[] { - if (!shouldShowSubagentSection(state)) { - return []; - } - - const parallel = state.subagentParallelCount ?? 1; - const mode = parallel > 1 ? `pool x${parallel}` : "single"; - - const header = clampToWidth( - `${theme.bold(theme.fg("accent", "Subagents"))} ${theme.fg("muted", "|")} ${theme.fg("dim", mode)}`, - width, - "…", - ); - - const counters = [ - `${theme.fg("muted", "queued:")}${theme.fg("muted", subagentCount(state.subagentQueued))}`, - `${theme.fg("muted", "active:")}${theme.bold(theme.fg("accent", subagentCount(state.subagentActive)))}`, - `${theme.fg("muted", "done:")}${theme.fg("dim", subagentCount(state.subagentDone))}`, - ].join(" "); - - const divider = clampToWidth(theme.fg("muted", "─".repeat(width)), width); - return [header, clampToWidth(counters, width, "…"), divider]; -} - function identityView(state: WidgetState): IdentityView { const role = state.subagentRole ?? "—"; const parallel = state.subagentParallelCount ?? 1; @@ -607,41 +505,10 @@ function renderIdentitySection(view: IdentityView, theme: Theme, width: number): const DETAIL_SECTION_REGISTRY: Array> = [ { - id: "current-step", - placement: "core", - select: (state: WidgetState): CurrentStepView => { - const active = activePhase(state); - return { - title: state.step || active?.detail || active?.label || "Awaiting step", - activity: state.activity, - }; - }, - render: (view: CurrentStepView, theme: Theme, width: number): string[] => { - const lines = [ - clampToWidth(theme.fg("dim", "Current step"), width), - clampToWidth(theme.bold(theme.fg("accent", view.title)), width, "…"), - ]; - - if (view.activity) { - for (const line of wrapTextWithAnsi(theme.fg("muted", view.activity), width)) { - lines.push(clampToWidth(line, width)); - } - } - - return lines; - }, - }, - { - id: "qr-status", - placement: "core", - select: (state: WidgetState): WidgetState | null => (shouldShowQR(state) ? state : null), - render: (view: WidgetState, theme: Theme, width: number): string[] => renderQRStatusSection(view, theme, width), - }, - { - id: "subagent-status", + id: "runtime-status", placement: "core", - select: (state: WidgetState): WidgetState | null => (shouldShowSubagentSection(state) ? state : null), - render: (view: WidgetState, theme: Theme, width: number): string[] => renderSubagentStatusSection(view, theme, width), + select: (state: WidgetState): WidgetState | null => (shouldShowRuntimeSection(state) ? state : null), + render: (view: WidgetState, theme: Theme, width: number): string[] => renderRuntimeStatusSection(view, theme, width), }, { id: "identity", @@ -753,16 +620,9 @@ function renderPlanningCard(state: WidgetState, theme: Theme, width: number): st "", formatStepLine(state, theme), ]; - const detail = formatDetail(state, theme, contentWidth); - if (detail) fallbackContent.push(detail); - const qrCompact = formatQRCompact(state, theme, contentWidth); - if (qrCompact.length > 0) { - fallbackContent.push(...qrCompact); - } - const subagentCompact = formatSubagentCompact(state, theme, contentWidth); - if (subagentCompact.length > 0) { - if (qrCompact.length > 0) fallbackContent.push(""); - fallbackContent.push(...subagentCompact); + const runtimeCompact = formatRuntimeCompact(state, theme, contentWidth); + if (runtimeCompact.length > 0) { + fallbackContent.push(...runtimeCompact); } fallbackContent.push(""); @@ -912,37 +772,9 @@ function renderLogCard(state: WidgetState, theme: Theme, width: number, forcedCo ); } -function formatDetail(state: WidgetState, theme: Theme, width: number): string { - const step = state.step ? theme.fg("muted", state.step) : ""; - const activity = state.activity ? theme.fg("dim", ` · ${state.activity}`) : ""; - const detail = `${step}${activity}`; - if (!detail) return ""; - return clampToWidth(detail, width, "…"); -} - -function formatQRCompact(state: WidgetState, theme: Theme, width: number): string[] { - if (!shouldShowQR(state)) return []; - - const tier = qrTier(width); - const budget = Math.min(width, QR_META_MAX_CHARS); - const meta = qrMetaText(state, tier, budget); - const line1 = clampToWidth(`${theme.fg("muted", "QR")} ${theme.fg("muted", "|")} ${theme.fg("dim", meta)}`, width, "…"); - const line2 = renderQRCounterLine(state, theme, tier, width, budget); - return [line1, line2]; -} - -function formatSubagentCompact(state: WidgetState, theme: Theme, width: number): string[] { - if (!shouldShowSubagentSection(state)) return []; - - const parallel = state.subagentParallelCount ?? 1; - const mode = parallel > 1 ? `pool x${parallel}` : "single"; - const line1 = clampToWidth(`${theme.fg("muted", "Subagents")} ${theme.fg("muted", "|")} ${theme.fg("dim", mode)}`, width, "…"); - const line2 = clampToWidth( - `${theme.fg("muted", `queued:${subagentCount(state.subagentQueued)}`)} ${theme.fg("accent", `active:${subagentCount(state.subagentActive)}`)} ${theme.fg("dim", `done:${subagentCount(state.subagentDone)}`)}`, - width, - "…", - ); - return [line1, line2]; +function formatRuntimeCompact(state: WidgetState, theme: Theme, width: number): string[] { + if (!shouldShowRuntimeSection(state)) return []; + return renderRuntimeStatusSection(state, theme, width); } function formatIdentityCompact(state: WidgetState, theme: Theme, width: number): string[] { diff --git a/tests/widget.test.ts b/tests/widget.test.ts index 2342df4..bd2ea8e 100644 --- a/tests/widget.test.ts +++ b/tests/widget.test.ts @@ -84,6 +84,64 @@ describe("WidgetController rendering", () => { } }); + it("renders merged runtime section with stage + quality + workers", () => { + const harness = createWidgetHarness(); + try { + harness.controller.update({ + qrIteration: 2, + qrIterationsMax: 6, + qrMode: "fix", + qrPhase: "verify", + qrDone: 9, + qrTotal: 14, + qrPass: 8, + qrFail: 1, + qrTodo: 5, + subagentQueued: 2, + subagentActive: 3, + subagentDone: 7, + subagentParallelCount: 4, + }); + + const text = harness.render(140).join("\n"); + assert.match(text, /Runtime/); + assert.match(text, /stage\s+: Verifying \(cycle 2\/6 · fix\)/); + assert.match(text, /quality\s+: checked 9\/14\s+pass 8\s+FAIL 1\s+remaining 5/); + assert.match(text, /workers\s+: queued 2\s+active 3\s+done 7\s+pool ×4/); + + assert.doesNotMatch(text, /\bQR\b\s+\|/); + assert.doesNotMatch(text, /\bSubagents\b\s+\|/); + assert.doesNotMatch(text, /\bCurrent step\b/); + } finally { + harness.destroy(); + } + }); + + it("uses Writing for execute debut and Fixing for execute fix", () => { + const harness = createWidgetHarness(); + try { + harness.controller.update({ + qrIteration: 1, + qrIterationsMax: 6, + qrMode: "initial", + qrPhase: "execute", + }); + + let text = harness.render(140).join("\n"); + assert.match(text, /stage\s+: Writing \(cycle 1\/6 · initial\)/); + + harness.controller.update({ + qrMode: "fix", + qrPhase: "execute", + }); + + text = harness.render(140).join("\n"); + assert.match(text, /stage\s+: Fixing \(cycle 1\/6 · fix\)/); + } finally { + harness.destroy(); + } + }); + it("aligns identity table separator using dynamic key width", () => { const harness = createWidgetHarness(); try { From 7f1a40e4903bb3bd8d2ee572371b258953254654 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 5 Mar 2026 14:12:28 +0700 Subject: [PATCH 040/412] fix(planner): bind QR phase state and embed subagent prompts --- README.md | 5 + design-decisions.md | 17 +- package.json | 1 + resources/conventions/REGISTRY.yaml | 68 +++ .../code-quality/01-naming-and-types.md | 231 ++++++++++ .../02-structure-and-composition.md | 277 ++++++++++++ .../code-quality/03-patterns-and-idioms.md | 224 ++++++++++ .../04-repetition-and-consistency.md | 224 ++++++++++ .../05-documentation-and-tests.md | 186 ++++++++ .../06-module-and-dependencies.md | 119 ++++++ .../code-quality/07-cross-file-consistency.md | 188 ++++++++ .../code-quality/08-codebase-patterns.md | 153 +++++++ resources/conventions/diff-format.md | 201 +++++++++ resources/conventions/documentation.md | 402 ++++++++++++++++++ resources/conventions/intent-markers.md | 33 ++ resources/conventions/severity.md | 80 ++++ resources/conventions/structural.md | 152 +++++++ resources/conventions/temporal.md | 135 ++++++ src/planner/lib/agent-prompts.ts | 20 + src/planner/lib/dispatch.ts | 3 +- src/planner/lib/resources.ts | 31 ++ src/planner/phases/plan-code/prompts.ts | 13 +- src/planner/phases/plan-design/prompts.ts | 26 +- src/planner/phases/plan-docs/prompts.ts | 13 +- src/planner/phases/qr-decompose/phase.ts | 1 + src/planner/phases/qr-decompose/prompts.ts | 23 +- src/planner/phases/qr-verify/phase.ts | 1 + src/planner/phases/qr-verify/prompts.ts | 17 +- src/planner/tools/qr.ts | 46 +- tests/qr-grouped-verify.test.ts | 3 +- 30 files changed, 2793 insertions(+), 100 deletions(-) create mode 100644 resources/conventions/REGISTRY.yaml create mode 100644 resources/conventions/code-quality/01-naming-and-types.md create mode 100644 resources/conventions/code-quality/02-structure-and-composition.md create mode 100644 resources/conventions/code-quality/03-patterns-and-idioms.md create mode 100644 resources/conventions/code-quality/04-repetition-and-consistency.md create mode 100644 resources/conventions/code-quality/05-documentation-and-tests.md create mode 100644 resources/conventions/code-quality/06-module-and-dependencies.md create mode 100644 resources/conventions/code-quality/07-cross-file-consistency.md create mode 100644 resources/conventions/code-quality/08-codebase-patterns.md create mode 100644 resources/conventions/diff-format.md create mode 100644 resources/conventions/documentation.md create mode 100644 resources/conventions/intent-markers.md create mode 100644 resources/conventions/severity.md create mode 100644 resources/conventions/structural.md create mode 100644 resources/conventions/temporal.md create mode 100644 src/planner/lib/agent-prompts.ts create mode 100644 src/planner/lib/resources.ts diff --git a/README.md b/README.md index 5b89554..a8d832b 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,11 @@ Each phase is followed by a QR (quality review) block: decompose → parallel ve Written once at the start of `koan_plan`. Contains the full session branch as JSONL (one JSON object per line — raw pi `SessionManager` entries, not a plain-text transcript). The plan-design architect and plan-docs writer are told about this file and may `Read` it; other phases work from `plan.json` only. +### Prompt + convention sources + +- Subagent system prompts are hard-coded in `src/planner/lib/agent-prompts.ts`. +- Convention docs stay file-based in `resources/conventions` and are surfaced to prompts via `CONVENTIONS_DIR`. + ### Slash commands | Command | Description | diff --git a/design-decisions.md b/design-decisions.md index 4c6c471..6349a47 100644 --- a/design-decisions.md +++ b/design-decisions.md @@ -145,11 +145,18 @@ Structure: `/subagents/-/` Contains: state.json, stdout.log, stderr.log. ProgressReporter class manages state.json updates with trail. -### AD-10: Architect System Prompt - -The architect's system prompt is loaded from ~/.claude/agents/architect.md -at runtime via loadPlanDesignSystemPrompt(). Injected via -before_agent_start returning { systemPrompt: ... }. +### AD-10: Embedded Planner Prompts + File-Based Conventions + +Planner subagent prompts are hard-coded in TypeScript at +`src/planner/lib/agent-prompts.ts` (architect, developer, +quality-reviewer, technical-writer). Phase loaders call +`loadAgentPrompt(...)`, so prompt availability does not depend on runtime +filesystem paths. + +Conventions remain file-based under `resources/conventions` so the LLM can +explore them directly with `Read`. `CONVENTIONS_DIR` is resolved at runtime +via `src/planner/lib/resources.ts` and injected into phase guidance where +needed. ### AD-11: Plan Schema Self-Documentation via TypeBox diff --git a/package.json b/package.json index e99f2d3..b3ebab9 100644 --- a/package.json +++ b/package.json @@ -18,6 +18,7 @@ "files": [ "extensions", "src", + "resources", "README.md", "LICENSE" ], diff --git a/resources/conventions/REGISTRY.yaml b/resources/conventions/REGISTRY.yaml new file mode 100644 index 0000000..206eb56 --- /dev/null +++ b/resources/conventions/REGISTRY.yaml @@ -0,0 +1,68 @@ +# Role-Convention Registry +# CI validates actual get_convention() calls match these declarations +# +# Structure per role: +# receives: list of conventions this role loads +# phase_specific: per-phase convention overrides +# mode_specific: per-mode convention overrides (design vs code) +# rationale: explanation for roles with empty receives + +developer: + receives: + - diff-format.md + +technical_writer: + receives: + - temporal.md + - documentation.md + +quality_reviewer: + receives: + - temporal.md + - structural.md + - diff-format.md + - code-quality/* + phase_specific: + plan_completeness: + - structural.md + plan_code: + - diff-format.md + - code-quality/01-naming-and-types.md + - code-quality/02-structure-and-composition.md + - code-quality/03-patterns-and-idioms.md + - code-quality/04-repetition-and-consistency.md + - code-quality/05-documentation-and-tests.md + plan_docs: + - temporal.md + post_impl_code: + - structural.md + - code-quality/01-naming-and-types.md + - code-quality/02-structure-and-composition.md + - code-quality/03-patterns-and-idioms.md + - code-quality/04-repetition-and-consistency.md + - code-quality/05-documentation-and-tests.md + - code-quality/06-module-and-dependencies.md + - code-quality/07-cross-file-consistency.md + - code-quality/08-codebase-patterns.md + post_impl_doc: + - temporal.md + +refactor: + receives: + - code-quality/* + mode_specific: + design: + - code-quality/01-naming-and-types.md + - code-quality/02-structure-and-composition.md + - code-quality/06-module-and-dependencies.md + - code-quality/07-cross-file-consistency.md + code: + - code-quality/* + +explore: + receives: [] + rationale: "Codebase reading only, no convention-aware output" + +general_purpose: + receives: [] + rationale: "Planning and general tasks; produces artifacts that other roles process" diff --git a/resources/conventions/code-quality/01-naming-and-types.md b/resources/conventions/code-quality/01-naming-and-types.md new file mode 100644 index 0000000..63c4f2f --- /dev/null +++ b/resources/conventions/code-quality/01-naming-and-types.md @@ -0,0 +1,231 @@ + + +# Naming & Types + +Evaluate whether names and types accurately communicate intent. + +**The core question**: If a reader sees only the name or type, will their mental model match actual behavior? Names are micro-documentation. Types are contracts. When either lies, readers build wrong mental models and write bugs. + +**What to look for**: + +- Names that describe HOW instead of WHAT +- Verbs that lie (get that mutates, validate that parses) +- Missing domain types (primitives where concepts belong) +- Type-based branching (isinstance chains indicating missing polymorphism) +- Multiple names for the same concept within a file + +**The threshold**: Flag only when name/type actively misleads or when domain concepts are hidden in primitives crossing boundaries. Imperfect-but-accurate names are style preferences, not quality issues. + + +When evaluating Code Intent (Design Review phase): + +- Does the proposed function/class name predict its behavior? +- Does the intent use domain types or raw primitives? +- Are type choices appropriate for the domain concept? + +Evidence format: Quote the Code Intent description showing naming/type issue. + + + +When evaluating actual code (Diff Review, Codebase Review, Refactor): + +- Does the implementation name match actual behavior? +- Are domain concepts hidden in primitive comparisons? +- Are isinstance chains indicating missing polymorphism? + +Evidence format: Quote code with file:line showing the issue. + + +--- + +## 1. Naming Precision + + +A name is micro-documentation. It should predict behavior accurately enough that reading the implementation confirms rather than surprises. + + +Detect: Does the name accurately describe what this does? Would a reader's mental model, built from the name alone, match actual behavior? + + +Terms that sometimes indicate naming issues (starting points, not definitive): +`Manager`, `Handler`, `Utils`, `Helper`, `Data`, `Info`, `process`, `handle`, `do` + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Name-behavior mismatch + +- Names describing HOW not WHAT (e.g., loopOverItems -> processOrders) +- Verbs that lie (e.g., get that mutates, validate that parses) +- Any name that would cause surprise when implementation is read + +[medium] Abstraction leakage + +- Implementation details in public API names +- Vague umbrella terms (e.g., Manager, Handler, Utils, Helper, Data, Info) + +[low] Cognitive friction + +- Negated booleans (e.g., isNotValid -> isInvalid, disableFeature -> featureEnabled) + + + +Generic names in genuinely generic contexts (e.g., item in a generic collection, T in type params). Test: would a specific name add signal or just noise? + + + +Flag only when name actively misleads. Imperfect names that are still accurate are style preferences. + + +## 2. Missing Domain Modeling + + +Domain concepts should be explicit in code, not hidden in raw comparisons. When the same concept is checked multiple ways, it belongs in a domain object. + + +Detect: Are domain concepts hiding in raw conditions? Is the same business concept checked via primitive comparison in multiple places? + + +Pattern indicators (starting points, not definitive): +`== 'admin'`, `== "admin"`, `status ==`, `role ==`, `type ==`, magic numbers + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Hidden domain logic + +- Domain predicates in raw conditions (e.g., user.role == 'admin' -> user.can_edit()) +- Magic value comparisons (e.g., status == 3 -> Status.APPROVED) +- Any business concept expressed only through primitive comparison + +[medium] Implicit modeling + +- String comparisons for state (e.g., mode == 'active' -> enum) +- Business rules buried in conditions (extract to domain object method) + + + +Explicit comparisons in domain layer implementation itself. Config values compared once at startup. + + + +Flag when same domain concept is checked via raw comparison in 2+ places. + + +## 3. Type-Based Branching + + +Type dispatch scattered across code indicates missing polymorphism. When you branch on type in multiple places, the type itself should carry the behavior. + + +Detect: Is type-checking being used where polymorphism would be cleaner? Does the same type dispatch appear in multiple locations? + + +Pattern indicators (starting points, not definitive): +`isinstance`, `typeof`, `instanceof`, `hasattr`, `in dict`, `.type ==` + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Scattered dispatch + +- isinstance/typeof chains (3+ branches -> polymorphism candidate) +- Same type dispatch appearing in multiple locations + +[medium] Implicit dispatch + +- Attribute-presence checks (e.g., hasattr/in dict as type dispatch) + +[low] Missing abstraction + +- Duck typing conditionals that should be protocols/interfaces + + + +Single isinstance check for input validation. Type narrowing for type safety. + + + +Flag when same type dispatch appears in 2+ places. Single-use type checks are often appropriate. + + +## 4. Type Design + + +Domain concepts deserve their own types. Primitives that cross boundaries without validation invite bugs; value objects with validation prevent them. + + +Detect: What domain concepts are represented as primitives? Do primitives cross API boundaries without validation? + + +Pattern indicators (starting points, not definitive): +`str` for IDs, `float` for money, `dict` passed through call chain, `Any`, `object` + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Missing domain types + +- Primitive obsession (e.g., userId as string -> UserId type with validation) +- Missing value objects (e.g., money as float -> Money(amount, currency)) +- Any domain concept crossing API boundary as primitive + +[medium] Weak typing + +- Stringly-typed data (JSON strings -> typed objects) +- Leaky abstractions (callers must know implementation details) + +[low] Type proliferation + +- Optional explosion (many nullable fields -> consider separate types for states) + + + +Primitives in internal implementation. Serialization boundaries. Performance-critical paths. + + + +Flag when primitives cross API boundaries without validation. Internal use of primitives is acceptable. + + +## 5. Naming Consistency (File Scope) + + +A concept should have one name within a file. Multiple names for the same thing create confusion about whether they're actually the same. + + +Detect: Are there multiple names for the same concept within this file? Would a reader wonder if user and account refer to the same entity? + + +Pattern indicators (starting points, not definitive): +Synonyms as variable prefixes (user/account/customer, config/settings/options, id/uid/identifier) + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Semantic confusion + +- Same entity called different names in same file (e.g., user vs account vs customer) +- Any naming inconsistency causing doubt about identity within a single file + +[medium] Inconsistent conventions + +- Inconsistent abbreviations within file (e.g., id vs identifier) + +[low] Style drift + +- Style inconsistency without semantic confusion + + + +Different names for genuinely different concepts. External API naming conventions. Aliasing for clarity at specific scopes. + + + +Flag when same semantic concept has multiple names within a file AND causes confusion about whether they refer to the same thing. + diff --git a/resources/conventions/code-quality/02-structure-and-composition.md b/resources/conventions/code-quality/02-structure-and-composition.md new file mode 100644 index 0000000..0748863 --- /dev/null +++ b/resources/conventions/code-quality/02-structure-and-composition.md @@ -0,0 +1,277 @@ + + +# Structure & Composition + +Evaluate whether code is well-structured for comprehension and change. + +**The core question**: Can I understand this unit in isolation? Can I change it without understanding its dependents? Structure should reveal intent and isolate concerns. + +**What to look for**: + +- Functions doing multiple things (requires "and" to describe) +- Deep nesting obscuring control flow +- Implicit state machines hidden in boolean flags +- Hard-coded dependencies making code untestable +- Component definitions scattered across multiple locations +- Error handling that loses information + +**The threshold**: Flag when structure obscures intent or when changes would ripple unnecessarily. Length alone is not a smell; unclear responsibility is. + + +When evaluating Code Intent (Design Review phase): + +- Does the proposed function do one thing or multiple things? +- Does the intent describe clear responsibility boundaries? +- Does the design inject dependencies or hardcode them? +- Is the component's definition complete in one place, or scattered across locations? + +Evidence format: Quote the Code Intent description showing structural issue. + + + +When evaluating actual code (Diff Review, Codebase Review, Refactor): + +- Is the function too long or deeply nested? +- Are boolean flags creating implicit state machines? +- Is error handling preserving context? +- Are component definitions scattered (requirements in one place, validation in another)? + +Evidence format: Quote code with file:line showing the issue. + + +--- + +## 1. Function Composition + + +A function should do one thing that can be described in a single sentence. When description requires "and", the function likely needs splitting. + + +Detect: Can I describe this function's purpose in one sentence without using "and"? + + +Structural indicators (starting points, not definitive): +Functions >50 lines, parameter counts >4 + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Responsibility diffusion + +- God functions (multiple unrelated responsibilities) +- Long parameter lists (4+ params signals missing concept) +- Any function requiring multiple sentences to describe its purpose + +[medium] Structural complexity + +- Deep nesting (3+ levels of conditionals) +- Mixed abstraction levels (high-level orchestration mixed with low-level details) + +[low] Interface friction + +- Boolean parameters that fork behavior (consider splitting into two functions) + + + +Long functions that do one thing linearly (e.g., state machine, parser). Nesting depth from error handling. + + + +Flag when function has multiple unrelated responsibilities. Length alone is not a smell. + + +## 2. Control Flow Smells + + +Control flow should reveal intent, not obscure it. When following execution requires significant mental effort, the structure needs simplification. + + +Detect: Is the control flow harder to follow than necessary? Would a reader need to trace through multiple branches to understand behavior? + + +Pattern indicators (starting points, not definitive): +`elif.*elif.*elif`, `switch`, `case`, `? :.*? :`, ternary chains + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Excessive branching + +- Long if/elif chains (5+ branches -> lookup table or strategy pattern) +- Any branching structure that requires tracing to understand + +[medium] Obscured flow + +- Nested ternaries (2+ levels -> extract to named variables) +- Early-return candidates buried in nested else branches + +[low] Hidden complexity + +- Conditional assignment cascades +- Implicit else branches hiding edge cases + + + +Exhaustive pattern matching. State machines with explicit states. + + + +Flag when control flow obscures intent. Explicit branching for documented cases is acceptable. + + +## 3. State and Flags + + +Boolean flags that interact create implicit state machines. When understanding state requires tracking multiple flags, make the state machine explicit. + + +Detect: Are boolean flags creating implicit state machines? Do flags interact in ways that require mental tracking? + + +Pattern indicators (starting points, not definitive): +`is_.*=`, `has_.*=`, `_flag`, `_state`, multiple boolean assignments + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Implicit state machines + +- Boolean flag tangles (3+ flags interacting = implicit state machine) +- Any flag interaction requiring mental state tracking + +[medium] Order dependencies + +- Stateful conditionals depending on mutation order + +[low] Defensive complexity + +- Defensive null chains (e.g., x and x.y and x.y.z -> optional chaining or null object) + + + +Single boolean for simple on/off state. Builder pattern flags. + + + +Flag when flags interact in ways that require mental state tracking. Independent flags are fine. + + +## 4. Dependency Injection + + +Business logic should be testable without network, disk, or database. Hard-coded dependencies make code untestable and tightly coupled. + + +Detect: Can I test this function in isolation without mocking infrastructure? Are dependencies injected or hard-coded? + + +Pattern indicators (starting points, not definitive): +`datetime.now`, `time.time`, `os.environ`, `open(`, `requests.`, `http.` + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Untestable coupling + +- Hard-coded dependencies (e.g., new Date() inline -> inject clock) +- Global state access (avoid or inject) +- Any business logic that requires infrastructure to test + +[medium] Mixed concerns + +- Side effects mixed with computation (separate pure logic from effects) +- Concrete class dependencies (depend on interface, not implementation) + +[low] Configuration coupling + +- Environment coupling (reads env vars directly -> inject config) +- Time-dependent logic (inject clock for testability) + + + +Entry points that wire dependencies. Test utilities. Scripts meant to run directly. + + + +Flag when untestable code is in business logic. Infrastructure code at boundaries is expected to have dependencies. + + +## 5. Definition Locality + + +A component's definition should be complete at a single site. When understanding what a component IS -- its identity, requirements, constraints, and behavior -- demands reading multiple locations, the definition is scattered. + + +Detect: To understand what this component IS, how many locations must I read? If I change what this component requires, how many files must I edit? + + +Structural indicators (starting points, not definitive): +Same requirement checked in 2+ locations, component identity split across files, extraction-with-default patterns (args.get, kwargs.get, getattr with default) + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Scattered specification + +- Same requirement declared in 2+ locations (e.g., parser marks required AND handler checks if missing) +- Component identity split across files without clear ownership +- Definition requiring "mental reassembly" from 3+ sources + +[medium] Split declaration/enforcement + +- Interface declared at one site, validated at another without shared reference +- Defaults defined separately from schema (e.g., type in schema, default in code) +- Same constraint checked in multiple places + + + +Dependency injection (injected collaborator's definition lives with collaborator, not here -- that's runtime wiring, not scatter). Composition (A uses B; B's definition is B's concern). Inheritance (intentional decomposition). Plugin architectures (clear ownership boundaries). Registry + reference patterns (define once, reference many times -- this is the fix, not a smell). + + + +Flag when a component's definition is split across 2+ locations without clear ownership. Key test: who owns this fact? If ownership is unclear or duplicated, it's scatter. Common in LLM-generated code. + + +## 6. Error Handling + + +Errors should preserve context and reach appropriate handlers. Swallowed or generic catches lose information; errors at wrong levels confuse callers. + + +Detect: What happens if this operation fails? Is error information preserved and routed appropriately? + + +Pattern indicators (starting points, not definitive): +`except:`, `catch (`, `catch(`, `pass`, `# TODO`, `raise Error(` + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Information loss + +- Swallowed exceptions (empty catch blocks) +- Generic catches (e.g., catch Exception -> catch specific errors) +- Any error handling that loses diagnostic information + +[medium] Wrong abstraction + +- Errors at wrong abstraction level (low-level errors leaking to callers) + +[low] Missing context + +- raise Error('failed') -> raise Error(f'order {id}: {reason}') + + + +Generic catch at top-level with logging. Intentionally swallowed expected errors with comment. + + + +Flag when error handling obscures or loses information. Documented catch-all with logging is acceptable. + diff --git a/resources/conventions/code-quality/03-patterns-and-idioms.md b/resources/conventions/code-quality/03-patterns-and-idioms.md new file mode 100644 index 0000000..36cba1c --- /dev/null +++ b/resources/conventions/code-quality/03-patterns-and-idioms.md @@ -0,0 +1,224 @@ + + +# Patterns & Idioms + +Evaluate whether code uses idiomatic patterns for its language. + +**The core question**: Is this idiomatic? Modern languages provide features to simplify common patterns. When code uses outdated patterns, verbose anti-patterns, or unnecessarily complex expressions, it adds cognitive load without benefit. + +**What to look for**: + +- Complex boolean expressions requiring mental evaluation +- Verbose conditional patterns with simpler equivalents +- Outdated iteration/callback patterns +- Commented code blocks and unreachable branches (within files) +- Missing language features that would simplify code + +**The threshold**: Flag mechanical anti-patterns and expression-level complexity that obscures intent. Well-commented complex logic is acceptable; unnecessarily complex logic is not. Only flag outdated patterns when a clearly better modern idiom exists in the project's language version. + + +Not applicable -- this group requires actual code to evaluate. + + + +When evaluating actual code (Diff Review, Codebase Review, Refactor): + +- Are boolean expressions readable at a glance? +- Do conditionals use simpler equivalent forms? +- Are modern language features being utilized? +- Is commented code cluttering the file? + +Evidence format: Quote code with file:line showing the issue. + + +--- + +## 1. Boolean Expression Complexity + + +A boolean expression should be readable at a glance. If it requires mental evaluation to understand, it needs simplification or naming. + + +Detect: Can I understand this boolean expression without tracing through it mentally? + + +Pattern indicators (starting points, not definitive): +`and.*and`, `or.*or`, `&&.*&&`, `||.*||`, `not.*not`, `!.*!` + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[medium] Cognitive overload + +- Multi-clause expressions (3+ AND/OR terms -> extract named predicate) +- Negated compound conditions (e.g., not (a and b) -> clearer positive form) +- Any expression requiring paper/mental tracing to evaluate + +[low] Ambiguity + +- Mixed AND/OR without parentheses clarifying precedence +- Double/triple negatives (e.g., if not disabled, if not is_invalid) + + + +Complex conditions with clear structure and comments explaining the logic. + + + +Flag when expression requires mental evaluation to understand. Well-commented complex conditions are acceptable. + + +## 2. Conditional Anti-Patterns + + +Conditions should express intent directly. When a simpler form exists that preserves meaning, the complex form is an anti-pattern. + + +Detect: Is there a simpler way to express this condition that preserves the same meaning? + + +Pattern indicators (starting points, not definitive): +`if.*return True.*else.*return False`, `try:.*except:.*pass`, `and do_` + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[medium] Verbose patterns + +- if cond: return True else: return False (just return cond) +- Exception-based control flow (try/except as if/else) +- Any condition with a simpler equivalent form + +[low] Subtle complexity + +- Short-circuit side effects (e.g., cond and do_thing()) +- Yoda conditions without clear benefit (e.g., if 5 == x) + + + +Exception handling for actual exceptional conditions. Short-circuit for lazy evaluation. + + + +Flag mechanical anti-patterns only. Intent-preserving variations are style preferences. + + +## 3. Modern Idioms + + +Modern language features exist to simplify common patterns. When older patterns persist unnecessarily, they add cognitive load without benefit. + + +Detect: Is there a newer language feature that would simplify this code? Is the project's language version being underutilized? + + +Pattern indicators (starting points, not definitive): +`for i in range(len(`, `+ str(`, `.format(`, callback patterns, `null` checks + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[medium] Outdated patterns + +- Old iteration patterns (e.g., manual index loops -> for-each, enumerate) +- Deprecated API usage +- Any pattern with a simpler modern equivalent + +[low] Missing features + +- Missing language features (e.g., no destructuring, no pattern matching) +- Legacy patterns (e.g., callbacks -> async/await) +- Outdated idioms (e.g., string concatenation -> f-strings/templates) +- Manual null checks (-> optional chaining, null coalescing) + + + +Intentional use of older patterns for compatibility. Performance-critical code avoiding allocations. + + + +Flag when modern idiom is clearly better AND available in the project's language version. Do not flag style preferences. + + +## 4. Readability + + +Code should be understandable in isolation. When understanding requires external lookup or tribal knowledge, the code needs clarification. + + +Detect: Can I understand this code without reading other files or asking someone? Is intent clear from the code itself? + + +Pattern indicators (starting points, not definitive): +Boolean literals in function calls, magic numbers, unexplained constants + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Obscured intent + +- Boolean trap (e.g., fn(True, False) -> fn(enabled=True, debug=False)) +- Any call where argument meaning requires looking up the function signature + +[medium] Magic values + +- Magic numbers/strings (e.g., 42 -> MAX_RETRIES = 42) +- Positional args where named params would clarify intent + +[low] Dense expressions + +- Dense expressions (e.g., nested ternaries -> named intermediate variables) +- Missing WHY comments on non-obvious decisions +- Implicit ordering dependencies between calls (document or make explicit) + + + +Well-known constants (0, 1, -1, 100). Boolean in obviously-named function (e.g., setEnabled(true)). + + + +Flag when meaning requires external lookup. Self-evident code needs no comments. + + +## 5. Zombie Code (File Scope) + + +Dead code is noise that misleads readers. Code that cannot execute or is never called should be removed, not left to confuse future maintainers. + + +Detect: If I deleted this, would any test fail or behavior change? + + +Pattern indicators (starting points, not definitive): +Commented blocks, `#if 0`, unreachable branches, unused variables + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Dead code blocks + +- Commented-out code blocks (>5 lines of code, not documentation) +- Unreachable branches (e.g., else after unconditional return, dead switch cases) +- Any code that cannot execute + +[medium] Unused declarations + +- Unused local variables or parameters + +[low] Orphaned functions + +- Functions defined but never called within file + + + +Commented code with explanation (debugging aid). Unused params required by interface contract. Public API entry points. Plugin interfaces. + + + +Flag when code is demonstrably unreachable/unused AND is not a public API entry point, plugin interface, or documented debugging aid. + diff --git a/resources/conventions/code-quality/04-repetition-and-consistency.md b/resources/conventions/code-quality/04-repetition-and-consistency.md new file mode 100644 index 0000000..e22bcae --- /dev/null +++ b/resources/conventions/code-quality/04-repetition-and-consistency.md @@ -0,0 +1,224 @@ + + +# Repetition & Consistency + +Evaluate whether code follows DRY principles and maintains consistency. + +**The core question**: Is this DRY and consistent? When the same logic, validation, or pattern appears in multiple places, bugs must be fixed everywhere -- and they won't be. When similar operations use different patterns, readers question whether the difference is meaningful. + +**What to look for**: + +- Duplicated code blocks that would require multi-location bug fixes +- Validation rules implemented multiple times +- Business rules scattered across locations +- Repeated boolean expressions +- Inconsistent error handling within a file or class + +**The threshold**: Flag when duplication is unintentional and would require coordinated changes. Flag inconsistency when it creates confusion about whether the difference is meaningful. Intentional duplication for modularity or bounded context isolation is acceptable. + + +Not applicable -- this group requires actual code to evaluate. + + + +When evaluating actual code (Diff Review, Codebase Review, Refactor): + +- Would fixing a bug require changing multiple locations? +- Are validation/business rules duplicated? +- Are similar operations handled inconsistently? +- Do repeated patterns need extraction? + +Evidence format: Quote code with file:line showing the duplication/inconsistency. + + +--- + +## 1. Duplication + + +Code should have a single source of truth. When the same logic exists in multiple places, bugs must be fixed everywhere -- and they won't be. + + +Detect: If I fixed a bug here, where else would I need to fix it? + + +Structural indicators (starting points, not definitive): +Identical multi-line blocks, similar function bodies, function names suggesting similar purpose across modules + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Direct duplication + +- Same code block duplicated (3+ lines, logic not just boilerplate) +- Any logic that would require multi-location bug fixes + +[medium] Near-duplication + +- Copy-paste with minor variations + +[low] Missed abstraction + +- Common pattern not extracted to shared location + + + +Intentionally different logic serving different purposes. Test setup code. Generated/vendored code. Deliberate isolation for modularity. Similar code in different bounded contexts. + + + +Flag when bug fix would require changing multiple locations AND the duplication is unintentional. + + +## 2. Validation Scattering + + +Validation rules should live in one place. When the same validation is implemented multiple times, implementations diverge -- and some will be wrong. + + +Detect: Is this validation duplicated? Would changing the validation rule require updating multiple locations? + + +Pattern indicators (starting points, not definitive): +Repeated regex patterns, duplicate bounds checks, email/phone/format validation across locations + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Diverged validation + +- Validation rules diverged between implementations +- Any validation requiring multi-location updates + +[medium] Repeated validation + +- Same validation repeated without shared implementation + +[low] Defensive re-validation + +- Defensive re-validation deeper in call chain + + + +Validation at trust boundaries. Defense-in-depth by design. Context-specific validation rules. Service boundary validation. + + + +Flag when identical validation appears 3+ times (file scope) or 5+ files (codebase scope) AND implementations have diverged or will diverge. + + +## 3. Business Rule Scattering + + +Business rules should have a single source of truth. When the same decision is made in multiple places, they will eventually disagree. + + +Detect: Where is the single source of truth for this rule? If the rule changes, how many places need updating? + + +Pattern indicators (starting points, not definitive): +Repeated conditional patterns, magic numbers in multiple places, pricing/permission/eligibility logic + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Scattered decisions + +- Same business decision in multiple places that could diverge +- Any business rule without clear single source of truth + +[medium] Mixed concerns + +- Business logic mixed with infrastructure code + +[low] Implicit rules + +- Rules embedded in raw conditionals instead of named predicates + + + +Orchestration calling multiple rule checks. Rules intentionally duplicated for service isolation. Per-tenant/region rule variations. Caching of computed rules. + + + +Flag when same business decision is made in 2+ places (file scope) or 3+ files (codebase scope) AND they have diverged or could diverge independently. + + +## 4. Condition Pattern Repetition + + +Repeated boolean expressions should be named predicates. When the same condition appears everywhere, changing it requires finding all occurrences. + + +Detect: Should this condition be a named predicate? Does extracting it reduce the bug surface area? + + +Pattern indicators (starting points, not definitive): +Identical boolean expressions, repeated guard clauses, permission/feature-flag check patterns + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] High-frequency repetition + +- Identical condition in 3+ places (file) or 5+ files (codebase) (extracting reduces bug surface) +- Any condition requiring multi-location updates when logic changes + +[medium] Pattern repetition + +- Repeated feature flag conditions + +[low] Guard repetition + +- Same guard clause pattern across related functions + + + +Standard guard clauses (null checks, bounds checks). Framework-required patterns. Simple conditions that read clearly inline. + + + +Flag when identical condition appears 3+ times (file scope) or 5+ files (codebase scope) AND extracting to named predicate would reduce bug surface area. + + +## 5. Error Pattern Consistency (File Scope) + + +Error handling should be consistent within an abstraction level. Mixed patterns create confusion about how errors propagate and should be handled. + + +Detect: Is error handling consistent within this file or class? Would a caller know what to expect from similar operations? + + +Pattern indicators (starting points, not definitive): +Mixed exception/return-code patterns, inconsistent error message formats, varying error context + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Incompatible patterns + +- Incompatible error patterns for similar operations within same class +- Any error handling creating caller confusion + +[medium] Inconsistent hierarchy + +- Inconsistent exception hierarchies within same abstraction level + +[low] Missing convention + +- No standard for error context/wrapping within file + + + +Different patterns for different abstraction levels (domain vs API vs infra). Wrapper functions translating between error styles. Legacy code under active migration. + + + +Flag when same class uses 2+ incompatible error patterns for similar operations AND no migration plan exists. + diff --git a/resources/conventions/code-quality/05-documentation-and-tests.md b/resources/conventions/code-quality/05-documentation-and-tests.md new file mode 100644 index 0000000..109b1d1 --- /dev/null +++ b/resources/conventions/code-quality/05-documentation-and-tests.md @@ -0,0 +1,186 @@ + + +# Documentation & Tests + +Evaluate whether code is properly documented and tested. + +**The core question**: Is this documented and tested? Documentation that contradicts code is worse than no documentation. Tests that don't communicate behavior fail as documentation. Schema drift causes runtime errors. Generated code without provenance documentation misleads maintainers. + +**What to look for**: + +- Documentation contradicting actual code +- Tests with uninformative names +- Missing provenance for generated/vendored code in CLAUDE.md +- Schema-code mismatches (fields in code missing from schema, or vice versa) + +**The threshold**: Flag only demonstrable incorrectness, not incompleteness. Stale docs cause hallucinations; missing docs just mean less context. Flag tests that give no behavioral information. Flag generated/vendored code without CLAUDE.md documentation. Flag schema drift only when provable mismatch exists. + + +Not applicable -- this group requires actual code to evaluate. + + + +When evaluating actual code (Diff Review, Codebase Review, Refactor): + +- Does documentation contradict the code? +- Do test names communicate behavior? +- Is generated/vendored code documented in CLAUDE.md? +- Do schema definitions match code usage? + +Evidence format: Quote code/docs with file:line showing the issue. + + +--- + +## 1. Documentation Staleness + + +Documentation that contradicts code is worse than no documentation. Stale docs mislead readers and cause bugs. + + +Detect: Does the documentation contradict the code? Are there claims in docs that the code structurally violates? + + +Pattern indicators (starting points, not definitive): +Docstrings with parameter names, @param, @return, TODO, FIXME + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Active contradictions + +- Parameter name in docstring not in function signature +- Docstring type conflicts with type annotation (when annotation exists) +- Any documentation making claims the code structurally contradicts + +[medium] Stale claims + +- Docstring describes return value that code never returns +- Comment contains strong claim ("always", "never", "must") AND code structurally contradicts it + +[low] Orphaned references + +- TODO/FIXME referencing completed or removed work + + + +Incomplete documentation. Missing docs. Outdated style in docs. + + + +Flag only when documentation is demonstrably incorrect, not merely incomplete. Incorrect documentation causes hallucinations. + + +## 2. Test Quality as Documentation + + +Tests document expected behavior. When test names don't communicate what behavior they verify, they fail as documentation. + + +Detect: Do tests communicate expected behavior? Can I understand what's being tested from the test name alone? + + +Pattern indicators (starting points, not definitive): +`test_works`, `test_ok`, `test_success`, `test_case_`, `test_1`, `assert True` + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Uninformative tests + +- Test name matches low-information pattern (e.g., test_works, test_ok, test_success, test_case_1) +- Test contains 0 assertions +- Any test where the name gives no behavioral information + +[medium] Weak naming + +- Test name shorter than 3 tokens (excluding test\_ prefix) +- Test name describes implementation, not behavior + +[low] Test smells + +- Test only asserts True, None, or trivial values +- Multiple similar test functions with minor input variations (use parameterized/table-driven) + + + +Tests referencing ticket numbers (e.g., TEST-1234, JIRA-567) for traceability. Smoke tests named test_works. + + + +Flag when test name gives no behavioral information AND is not a ticket/regression reference. + + +## 3. Generated and Vendored Code Awareness + + +Non-maintainable code (generated, vendored) must be clearly marked. Without provenance documentation, maintainers may try to modify code that should be regenerated. + + +Detect: Is non-maintainable code clearly marked in CLAUDE.md? Can a maintainer tell which code is generated or vendored? + + +Pattern indicators (starting points, not definitive): +`_generated`, `_pb`, `.pb.go`, `vendor/`, `third_party/`, `node_modules/` + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Missing provenance + +- Generated files missing regeneration command in CLAUDE.md +- Vendored directories missing upstream source in CLAUDE.md +- Any generated/vendored code without documentation of origin + +[medium] Unclear ownership + +- External libraries copied into repo without provenance documentation + + + +Generated files with regeneration command documented. Vendored code with clear upstream reference. + + + +Flag when file/directory matches generation patterns (e.g., *.pb.go, *_generated.*, vendor/, third_party/) AND CLAUDE.md lacks corresponding entry explaining provenance. + + +## 4. Schema-Code Coherence + + +Schema and code must stay synchronized. Fields referenced in code but absent from schema (or vice versa) indicate drift that causes runtime errors. + + +Detect: Does code reference schema fields that don't exist? Are there schema fields unused in any code path? + + +Pattern indicators (starting points, not definitive): +Schema file extensions (.proto, .graphql, .json schema), field access patterns + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Schema drift + +- Code references field not in schema definition +- Schema field unused in any code path (dead field) +- Any mismatch between schema definition and code usage + +[medium] Type drift + +- Type mismatch between schema and code representation + + + +Intentional divergence documented with :SCHEMA: marker. Fields used only in specific deployment configs. + + + +Flag when field name in code has 0 matches in corresponding schema file, or schema field has 0 references in codebase. + + +Intent marker: Use `:SCHEMA:` to suppress for intentional divergence (e.g., `:SCHEMA: field 'legacy_id' unused; migration pending`). diff --git a/resources/conventions/code-quality/06-module-and-dependencies.md b/resources/conventions/code-quality/06-module-and-dependencies.md new file mode 100644 index 0000000..7059158 --- /dev/null +++ b/resources/conventions/code-quality/06-module-and-dependencies.md @@ -0,0 +1,119 @@ + + +# Module & Dependencies + +Evaluate whether module boundaries are clean and architecture aligns with change patterns. + +**The core question**: Are boundaries clean? Modules should have clear boundaries with minimal coupling. Architecture should align with how features actually change. When changes ripple across unrelated modules or require touching many components, the boundaries are wrong. + +**What to look for**: + +- Circular dependencies +- Layer violations (domain importing infrastructure) +- Wrong component boundaries (features awkwardly split) +- Architecture forcing cross-cutting changes for single-domain features + +**The threshold**: Flag when dependencies cause compilation issues or domain corruption. Flag when adding a feature requires touching many unrelated components. This is inherently about relationships between files and modules, not local code patterns. + + +When evaluating Code Intent (Design Review phase): + +- Does the proposed design create circular dependencies? +- Does it violate layer boundaries? +- Would implementing this feature require touching many components? + +Evidence format: Quote the Code Intent description showing boundary issue. + + + +When evaluating actual code (Codebase Review, Refactor): + +- Do import graphs show circular dependencies? +- Are there layer violations in actual imports? +- Are features split across many loosely related components? + +Evidence format: Quote import statements or describe dependency structure showing the issue. + + +--- + +## 1. Module Structure + + +Modules should have clear boundaries with minimal coupling. When changes ripple across unrelated modules, the boundaries are wrong. + + +Detect: Do changes ripple to unrelated modules? Can a module be modified without understanding its dependents? + + +Structural indicators (starting points, not definitive): +Import graphs, dependency declarations, module boundaries + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Structural violations + +- Circular dependencies (e.g., A imports B imports A) +- Layer violations (e.g., domain importing infrastructure) +- Any dependency causing compilation order issues or domain corruption + +[medium] Cohesion problems + +- Wrong cohesion (unrelated things grouped in same module) +- Missing facades (module internals exposed directly) + +[low] Scope creep + +- God modules (too many responsibilities in one module) + + + +Circular deps within same bounded context. Infrastructure adapters importing domain. Shared kernel patterns. + + + +Flag when dependency causes compilation order issues OR when layer violation allows infrastructure to corrupt domain. + + +## 2. Architecture + + +Architecture should align with change patterns. When adding a feature requires touching many unrelated components, the architecture fights the domain. + + +Detect: Would adding a feature require touching many components? Do cross-cutting changes indicate misaligned boundaries? + + +Structural indicators (starting points, not definitive): +Component boundaries, service interfaces, configuration locations + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Boundary misalignment + +- Wrong component boundaries (features awkwardly split) +- Single points of failure (no fallback, no retry paths) +- Any architecture forcing cross-cutting changes for single-domain features + +[medium] Scaling issues + +- Scaling bottlenecks (synchronous where async needed) +- Monolith patterns in distributed code (or vice versa) + +[low] Missing structure + +- Missing abstraction layers (everything directly coupled) +- Configuration scattered (no central policy, settings in many places) + + + +Intentional coupling for simplicity. Early-stage monolith. Bounded contexts with shared kernel. + + + +Flag when architecture forces cross-cutting changes for single-domain features. + diff --git a/resources/conventions/code-quality/07-cross-file-consistency.md b/resources/conventions/code-quality/07-cross-file-consistency.md new file mode 100644 index 0000000..ce28189 --- /dev/null +++ b/resources/conventions/code-quality/07-cross-file-consistency.md @@ -0,0 +1,188 @@ + + +# Cross-File Consistency + +Evaluate whether patterns are consistent across files. + +**The core question**: Is this consistent across files? Similar APIs should behave similarly. The same concept should have one name throughout the codebase. Error handling should be predictable at each abstraction level. Feature flags should be evaluated consistently. + +**What to look for**: + +- Cross-module naming drift (userId/uid/id for same concept) +- Incompatible signatures for similar operations across modules +- Cross-abstraction-level error pattern inconsistency +- Feature flags checked with different logic in different places + +**The threshold**: Flag when inconsistency creates confusion or unpredictability for consumers. Flag when same concept has multiple names across modules AND causes integration confusion. This group requires seeing multiple files to detect patterns. + + +When evaluating Code Intent (Design Review phase): + +- Does the proposed API match existing similar APIs? +- Does it introduce a new name for an existing concept? +- Would error handling match other components at this level? + +Evidence format: Quote the Code Intent description showing inconsistency. + + + +When evaluating actual code (Codebase Review, Refactor): + +- Are similar operations using different conventions? +- Is the same concept named differently across modules? +- Do similar errors get handled differently at the same level? + +Evidence format: Quote code from multiple files showing the inconsistency. + + +--- + +## 1. Interface Consistency + + +Similar APIs should have consistent signatures. When similar functions surprise users with different conventions, they cause bugs. + + +Detect: Would a user of these APIs be surprised by inconsistency? Do similar operations have incompatible signatures? + + +Pattern indicators (starting points, not definitive): +Similar function signatures with different parameter orders, CRUD operation patterns, service method signatures + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Signature inconsistency + +- APIs with similar purposes have incompatible signatures AND share consumers +- Any API inconsistency causing caller confusion + +[medium] Naming inconsistency + +- Inconsistent naming conventions across related functions + +[low] Pattern inconsistency + +- Mixed sync/async for similar operations without clear reason + + + +Intentional API differences. Domain-specific conventions. Versioned APIs. Overloads with clear distinct purpose. + + + +Flag when 2+ similar functions have different parameter orders (file scope) or 3+ APIs have incompatible signatures (codebase scope) AND confusion impacts consumers. + + +## 2. Naming Consistency (Cross-File Scope) + + +A concept should have one name throughout the codebase. Multiple names for the same thing create confusion about whether they're actually the same. + + +Detect: Are there multiple names for the same concept across modules? Would a reader wonder if userId and uid refer to the same entity? + + +Pattern indicators (starting points, not definitive): +Synonyms as variable prefixes across modules (user/account/customer, config/settings/options, id/uid/identifier) + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Semantic confusion + +- Synonym drift causing confusion at integration points +- Any naming inconsistency causing doubt about identity across modules + +[medium] Inconsistent conventions + +- Inconsistent abbreviations across modules (e.g., userId vs uid vs id) + +[low] Style drift + +- Style inconsistency without semantic confusion + + + +Different names for genuinely different concepts. External API naming conventions. Domain-specific terminology. Legacy compatibility aliases in bounded migration. + + + +Flag when same semantic concept has 3+ different names across modules AND causes confusion about whether they refer to the same thing. + + +## 3. Error Pattern Consistency (Cross-File Scope) + + +Error handling should be consistent within an abstraction level. Mixed patterns create confusion about how errors propagate and should be handled. + + +Detect: Is error handling consistent across components at the same abstraction level? Would a caller know what to expect from similar operations? + + +Pattern indicators (starting points, not definitive): +Mixed exception/return-code patterns, inconsistent error message formats, varying error context across modules + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Incompatible patterns + +- Incompatible error patterns for similar operations across components +- Any error handling creating caller confusion at integration boundaries + +[medium] Inconsistent hierarchy + +- Inconsistent exception hierarchies at same abstraction level + +[low] Missing convention + +- No standard for error context/wrapping across modules + + + +Different patterns for different abstraction levels (domain vs API vs infra). Wrapper functions translating between error styles. Legacy code under active migration. + + + +Flag when same abstraction level uses 3+ incompatible error patterns across files for similar operations AND no migration plan exists. + + +## 4. Feature Flag Sprawl + + +Feature flags should be checked consistently. When the same flag is evaluated with different logic in different places, behavior becomes unpredictable. + + +Detect: How are feature flags checked across the codebase? Is the same flag evaluated consistently everywhere? + + +Structural indicators (starting points, not definitive): +Feature flag checks, toggle patterns, conditional feature code + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Inconsistent evaluation + +- Feature flags checked inconsistently (different conditions for same flag) +- Any flag with divergent evaluation logic across locations + +[medium] Undocumented dependencies + +- Flag dependencies not documented (flag A requires flag B) + + + +Flags with intentionally different behavior per context. A/B test variations. Gradual rollout logic. + + + +Flag when same feature flag is checked with different logic in different places AND the difference is unintentional. + + +Note: Dead flags (feature shipped, never removed) are covered in 08-codebase-patterns.md Zombie Code (Codebase Scope). diff --git a/resources/conventions/code-quality/08-codebase-patterns.md b/resources/conventions/code-quality/08-codebase-patterns.md new file mode 100644 index 0000000..aef9b93 --- /dev/null +++ b/resources/conventions/code-quality/08-codebase-patterns.md @@ -0,0 +1,153 @@ + + +# Codebase Patterns + +Evaluate patterns that only emerge from codebase-wide analysis. + +**The core question**: What patterns are emerging? Understanding should not require reading the entire codebase. Repeated patterns across files indicate missing abstractions. Dead exports and modules accumulate as noise. These issues are invisible in local review -- they only become visible when seeing the whole codebase. + +**What to look for**: + +- Flows requiring 5+ files to understand with no documentation +- Same transformation applied in 3+ files (missed abstraction) +- Exported functions with 0 callers anywhere +- Feature flags always true/false (never toggled) +- Dead modules with no imports from live code + +**The threshold**: Flag when comprehension is broken (5+ files, no guide). Flag when pattern appears in 3+ implementations AND extraction would help. Flag demonstrably dead code that's not a public API or plugin interface. This group requires whole-codebase visibility. + + +Not applicable -- this group requires whole-codebase analysis. + + + +When evaluating the codebase (Codebase Review, Refactor): + +- Can I understand flows without reading many files? +- Are there repeated patterns that should be abstracted? +- Is there dead code at the export/module level? + +Evidence format: Describe the pattern across multiple files or quote specific dead exports. + + +--- + +## 1. Cross-File Comprehension + + +Understanding a flow should not require reading the entire codebase. When grasping one operation requires 5+ files with no guide, comprehension is broken. + + +Detect: How many files must I read to understand this flow? Is there documentation or an orchestrator that explains the big picture? + + +Structural indicators (starting points, not definitive): +Call chains, event handlers, callback registrations + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Implicit contracts + +- Implicit contracts between files (caller must know callee internals) +- Any flow requiring undocumented assumptions to understand + +[medium] Hidden dependencies + +- Hidden dependencies (file A assumes file B ran first) + +[low] Scattered flow + +- Scattered control flow (one operation spans 5+ files with no orchestrator) + + + +Well-documented module boundaries. Plugin architectures. Event-driven designs with clear event contracts. + + + +Flag when understanding a single operation requires reading 5+ files with no documentation of the flow. + + +## 2. Abstraction Opportunities + + +Repeated patterns across files indicate missing abstractions. When you see the same transformation in 3+ places, a concept is trying to emerge. + + +Detect: What domain concept is hiding across these repeated patterns? Would extracting a shared abstraction reduce duplication? + + +Structural indicators (starting points, not definitive): +Parallel implementations, similar transformation chains, repeated configuration shapes + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Missed abstractions + +- Same transformation applied in multiple files (3+ occurrences) +- Any pattern appearing across implementations that should be shared + +[medium] Structural duplication + +- Parallel class hierarchies doing similar things differently +- Copy-paste inheritance (similar classes with minor variations) + +[low] Configuration patterns + +- Data transformation pipelines with identical structure +- Configuration patterns repeated without abstraction + + + +Intentionally similar but independent implementations. Domain-specific variations. Templates/generators producing similar code. + + + +Flag when pattern appears in 3+ implementations AND the fix is extracting shared abstraction. These become visible only after seeing multiple implementations. + + +## 3. Zombie Code (Codebase Scope) + + +Dead code is noise that misleads readers. Code that cannot execute or is never called should be removed, not left to confuse future maintainers. + + +Detect: If I deleted this export or module, would any test fail or behavior change? + + +Pattern indicators (starting points, not definitive): +Exported symbols with 0 callers, feature flags, configuration options, dead modules + + + +Illustrative patterns (not exhaustive -- similar violations exist): + +[high] Dead exports + +- Exported functions with 0 callers anywhere in codebase +- Feature flags always true/false (never toggled in any environment) +- Any publicly accessible code with no consumers + +[medium] Stale flags + +- Dead flags (feature shipped, flag never removed) + +[low] Orphaned configuration + +- Configuration options never read +- Dead modules (no imports from any live code path) + + + +Public API entry points. Plugin interfaces. Feature flags controlled externally. Backward compatibility exports with deprecation notice. + + + +Flag when code is demonstrably unreachable/unused AND is not a public API entry point, plugin interface, or documented compatibility shim. + + +Note: File-scope zombie code (commented blocks, unreachable branches) is covered in 03-patterns-and-idioms.md Zombie Code (File Scope). diff --git a/resources/conventions/diff-format.md b/resources/conventions/diff-format.md new file mode 100644 index 0000000..1cc3374 --- /dev/null +++ b/resources/conventions/diff-format.md @@ -0,0 +1,201 @@ +# Unified Diff Format for Plan Code Changes + +This document is the authoritative specification for code changes in implementation plans. + +## Purpose + +Unified diff format encodes both **location** and **content** in a single structure. This eliminates the need for location directives in comments (e.g., "insert at line 42") and provides reliable anchoring even when line numbers drift. + +## Anatomy + +```diff +--- a/path/to/file.py ++++ b/path/to/file.py +@@ -123,6 +123,15 @@ def existing_function(ctx): + # Context lines (unchanged) serve as location anchors + existing_code() + ++ # NEW: Comments explain WHY - transcribed verbatim by Developer ++ # Guard against race condition when messages arrive out-of-order ++ new_code() + + # More context to anchor the insertion point + more_existing_code() +``` + +## Components + +| Component | Authority | Purpose | +| ------------------------------------------ | ------------------------- | ---------------------------------------------------------- | +| File path (`--- a/path/to/file.py`) | **AUTHORITATIVE** | Exact target file | +| Line numbers (`@@ -123,6 +123,15 @@`) | **APPROXIMATE** | May drift as earlier milestones modify the file | +| Function context (`@@ ... @@ def func():`) | **SCOPE HINT** | Function/method containing the change | +| Context lines (unchanged) | **AUTHORITATIVE ANCHORS** | Developer matches these patterns to locate insertion point | +| `+` lines | **NEW CODE** | Code to add, including WHY comments | +| `-` lines | **REMOVED CODE** | Code to delete | + +## Two-Layer Location Strategy + +Code changes use two complementary layers for location: + +1. **Prose scope hint** (optional): Natural language describing conceptual location +2. **Diff with context**: Precise insertion point via context line matching + +### Layer 1: Prose Scope Hints + +For complex changes, add a prose description before the diff block: + +````markdown +Add validation after input sanitization in `UserService.validate()`: + +```diff +@@ -123,6 +123,15 @@ def validate(self, user): + sanitized = sanitize(user.input) + ++ # Validate format before proceeding ++ if not is_valid_format(sanitized): ++ raise ValidationError("Invalid format") ++ + return process(sanitized) +`` ` +``` +```` + +The prose tells Developer **where conceptually** (which method, what operation precedes it). The diff tells Developer **where exactly** (context lines to match). + +**When to use prose hints:** + +- Changes to large files (>300 lines) +- Multiple changes to the same file in one milestone +- Complex nested structures where function context alone is ambiguous +- When the surrounding code logic matters for understanding placement + +**When prose is optional:** + +- Small files with obvious structure +- Single change with unique context lines +- Function context in @@ line provides sufficient scope + +### Layer 2: Function Context in @@ Line + +The `@@` line can include function/method context after the line numbers: + +```diff +@@ -123,6 +123,15 @@ def validate(self, user): +``` + +This follows standard unified diff format (git generates this automatically). It tells Developer which function contains the change, aiding navigation even when line numbers drift. + +## Why Context Lines Matter + +When a plan has multiple milestones that modify the same file, earlier milestones shift line numbers. The `@@ -123` in Milestone 3 may no longer be accurate after Milestones 1 and 2 execute. + +**Context lines solve this**: Developer searches for the unchanged context patterns in the actual file. These patterns are stable anchors that survive line number drift. + +Include 2-3 context lines before and after changes for reliable matching. + +## Comment Placement + +Comments in `+` lines explain **WHY**, not **WHAT**. These comments: + +- Are transcribed verbatim by Developer +- Source rationale from Planning Context (Decision Log, Rejected Alternatives) +- Use concrete terms without hidden baselines +- Must pass temporal contamination review (see `.claude/conventions/temporal.md`) + +**Important**: Comments written during planning often contain temporal contamination -- change-relative language, baseline references, or location directives. @agent-technical-writer reviews and fixes these before @agent-developer transcribes them. + + +```diff ++ # Polling chosen over webhooks: 30% webhook delivery failures in third-party API ++ # WebSocket rejected to preserve stateless architecture ++ updates = poll_api(interval=30) +``` +Explains WHY this approach was chosen. + + + +```diff ++ # Poll the API every 30 seconds ++ updates = poll_api(interval=30) +``` +Restates WHAT the code does - redundant with the code itself. + + + +```diff ++ # Generous timeout for slow networks ++ REQUEST_TIMEOUT = 60 +``` +"Generous" compared to what? Hidden baseline provides no actionable information. + + + +```diff ++ # 60s accommodates 95th percentile upstream response times ++ REQUEST_TIMEOUT = 60 +``` +Concrete justification that explains why this specific value. + + +## Location Directives: Forbidden + +The diff structure handles location. Location directives in comments are redundant and error-prone. + + +```python +# Insert this BEFORE the retry loop (line 716) +# Timestamp guard: prevent older data from overwriting newer +get_ctx, get_cancel = context.with_timeout(ctx, 500) +``` +Location directive leaked into comment - line numbers become stale. + + + +```diff +@@ -714,6 +714,10 @@ def put(self, ctx, tags): + for tag in tags: + subject = tag.subject + +- # Timestamp guard: prevent older data from overwriting newer +- # due to network delays, retries, or concurrent writes +- get_ctx, get_cancel = context.with_timeout(ctx, 500) + + # Retry loop for Put operations + for attempt in range(max_retries): + +``` +Context lines (`for tag in tags`, `# Retry loop`) are stable anchors that survive line number drift. + + +## When to Use Diff Format + + + +| Code Characteristic | Use Diff? | Boundary Test | +| --------------------------------------- | --------- | ---------------------------------------- | +| Conditionals, loops, error handling, | YES | Has branching logic | +| state machines | | | +| Multiple insertions same file | YES | >1 change location | +| Deletions or replacements | YES | Removing/changing existing code | +| Pure assignment/return (CRUD, getters) | NO | Single statement, no branching | +| Boilerplate from template | NO | Developer can generate from pattern name | + +The boundary test: "Does Developer need to see exact placement and context to implement correctly?" + +- YES -> diff format +- NO (can implement from description alone) -> prose sufficient + + + +## Validation Checklist + +Before finalizing code changes in a plan: + +- [ ] File path is exact (not "auth files" but `src/auth/handler.py`) +- [ ] Context lines exist in target file (validate patterns match actual code) +- [ ] Comments explain WHY, not WHAT +- [ ] No location directives in comments +- [ ] No hidden baselines (test: "[adjective] compared to what?") +- [ ] 2-3 context lines for reliable anchoring +``` diff --git a/resources/conventions/documentation.md b/resources/conventions/documentation.md new file mode 100644 index 0000000..4f4bc68 --- /dev/null +++ b/resources/conventions/documentation.md @@ -0,0 +1,402 @@ +# Documentation Conventions + +This is the authoritative documentation conventions file. All code-adjacent +documentation (CLAUDE.md, README.md) must follow these principles. + +## Core Principles + +**Self-contained documentation**: All code-adjacent documentation (CLAUDE.md, +README.md) must be self-contained. Do NOT reference external authoritative +sources (doc/ directories, wikis, external documentation). If knowledge exists +in an authoritative source, it must be summarized locally. Duplication is +acceptable; the maintenance burden is the cost of locality. + +**CLAUDE.md = pure index**: CLAUDE.md files are navigation aids only. They +contain WHAT is in the directory and WHEN to read each file. All explanatory +content (architecture, decisions, invariants) belongs in README.md. + +**README.md = invisible knowledge**: README.md files capture knowledge NOT +visible from reading source code. If ANY invisible knowledge exists for a +directory, README.md is required. + +## CLAUDE.md Format Specification + +### Index Format + +Use tabular format with What and When columns: + +```markdown +## Files + +| File | What | When to read | +| ----------- | ------------------------------ | ----------------------------------------- | +| `cache.rs` | LRU cache with O(1) operations | Implementing caching, debugging evictions | +| `errors.rs` | Error types and Result aliases | Adding error variants, handling failures | + +## Subdirectories + +| Directory | What | When to read | +| ----------- | ----------------------------- | ----------------------------------------- | +| `config/` | Runtime configuration loading | Adding config options, modifying defaults | +| `handlers/` | HTTP request handlers | Adding endpoints, modifying request flow | +``` + +### Column Guidelines + +- **File/Directory**: Use backticks around names: `cache.rs`, `config/` +- **What**: Factual description of contents (nouns, not actions) +- **When to read**: Task-oriented triggers using action verbs (implementing, + debugging, modifying, adding, understanding) +- At least one column must have content; empty cells use `-` + +### Trigger Quality Test + +Given task "add a new validation rule", can an LLM scan the "When to read" +column and identify the right file? + +### Generated and Vendored Code + +CLAUDE.md MUST flag files/directories that should not be manually edited: + +| Directory | What | When to read | +| -------------- | --------------------------------- | ------------------- | +| `proto/gen/` | Generated from proto/. Run `make` | Never edit directly | +| `vendor/` | Vendored deps, upstream: go.mod | Never edit directly | +| `third_party/` | Copied from github.com/foo v1.2.3 | Never edit directly | + +The "When to read" column should indicate these are not editable. Include +regeneration commands in the "What" column or in a dedicated Regenerate section. + +This prevents LLMs from wasting effort analyzing or "improving" auto-generated +code, and prevents edits that will be overwritten or cause merge conflicts. + +See also: conventions/code-quality/baseline.md "Generated and Vendored Code Awareness". + +### ROOT vs SUBDIRECTORY CLAUDE.md + +**ROOT CLAUDE.md:** + +```markdown +# [Project Name] + +[One sentence: what this is] + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | + +## Build + +[Copy-pasteable command] + +## Test + +[Copy-pasteable command] + +## Development + +[Setup instructions, environment requirements, workflow notes] +``` + +**SUBDIRECTORY CLAUDE.md:** + +```markdown +# [directory-name]/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +``` + +**Critical constraint:** CLAUDE.md files are navigation aids, not explanatory +documents. They contain: + +- File/directory index (REQUIRED): tabular format with What/When columns +- One-sentence overview (OPTIONAL): what this directory is +- Operational sections (OPTIONAL): Build, Test, Regenerate, Deploy, or similar + commands specific to this directory's artifacts + +They do NOT contain: + +- Architectural explanations (-> README.md) +- Design decisions or rationale (-> README.md) +- Invariants or constraints (-> README.md) +- Multi-paragraph prose (-> README.md) + +Operational sections must be copy-pasteable commands with minimal context, not +explanatory prose about why the build works a certain way. + +## README.md Specification + +### Creation Criteria (Invisible Knowledge Test) + +Create README.md when the directory contains ANY invisible knowledge -- +knowledge NOT visible from reading the code: + +- Planning decisions (from Decision Log during implementation) +- Business context (why the product works this way) +- Architectural rationale (why this structure) +- Trade-offs made (what was sacrificed for what) +- Invariants (rules that must hold but aren't in types) +- Historical context (why not alternatives) +- Performance characteristics (non-obvious efficiency properties) +- Multiple components interact through non-obvious contracts +- The directory's structure encodes domain knowledge +- Failure modes or edge cases aren't apparent from reading individual files +- "Rules" developers must follow that aren't enforced by compiler/linter + +**README.md is required if ANY of the above exist.** The trigger is semantic +(presence of invisible knowledge), not structural (file count, complexity). + +**DO NOT create README.md when:** + +- The directory is purely organizational with no decisions behind its structure +- All knowledge is visible from reading source code +- You'd only be restating what code already shows + +### Content Test + +For each sentence in README.md, ask: "Could a developer learn this by reading +the source files?" + +- If YES: delete the sentence +- If NO: keep it + +README.md earns its tokens by providing INVISIBLE knowledge: the reasoning +behind the code, not descriptions of the code. + +### README.md Structure + +```markdown +# [Component Name] + +## Overview + +[One paragraph: what problem this solves, high-level approach] + +## Architecture + +[How sub-components interact; data flow; key abstractions] + +## Design Decisions + +[Tradeoffs made and why; alternatives considered] + +## Invariants + +[Rules that must be maintained; constraints not enforced by code] +``` + +## Architecture Documentation + +For cross-cutting concerns and system-wide relationships that span multiple +directories, create dedicated architecture documentation. + +### Structure + +```markdown +# Architecture: [System/Feature Name] + +## Overview + +[One paragraph: problem and high-level approach] + +## Components + +[Each component with its single responsibility and boundaries] + +## Data Flow + +[Critical paths - prefer diagrams for complex flows] + +## Design Decisions + +[Key tradeoffs and rationale] + +## Boundaries + +[What this system does NOT do; where responsibility ends] +``` + +### Quality Standard + +Components must explain relationships, not just list responsibilities. + +Wrong -- lists without relationships: + +```markdown +## Components + +- UserService: Handles user operations +- AuthService: Handles authentication +- Database: Stores data +``` + +Right -- explains boundaries and flow: + +```markdown +## Components + +- UserService: User CRUD only. Delegates auth to AuthService. Never queries auth + state directly. +- AuthService: Token validation, session management. Stateless; all state in + Redis. +- PostgreSQL: Source of truth for user data. AuthService has no direct access. + +Flow: Request -> AuthService (validate) -> UserService (logic) -> Database +``` + +Prefer diagrams over prose for relationships. + +## In-Code Documentation + +Code-level documentation captures knowledge at the point where it is most useful. +The principle: knowledge belongs as close as possible to the code it describes. +Cross-cutting knowledge that cannot be localized belongs in README.md. + +### Tier 1: Inline Comments + +Above statements or expressions where the choice is non-obvious. + +Document *why* this approach, never *what* the code does. The reader can see what +the code does: they cannot see why it was chosen over alternatives. + +Good: + +```python +# Polling: 30% webhook delivery failures observed in production +result = poll_endpoint(url, interval=30) + +# Mutex-free: single-writer guarantee from caller contract +counter.fetch_add(1, Ordering::Relaxed) +``` + +Bad: + +```python +# Poll the endpoint +result = poll_endpoint(url, interval=30) + +# Increment the counter +counter.fetch_add(1, Ordering::Relaxed) +``` + +When a decision log entry exists, reference it: `# DL-003: Polling over webhooks` + +### Tier 2: Function-Level Explanation Blocks + +Near the top of non-trivial functions (after signature, before body logic). +Required when a function has >3 distinct transformation steps, coordinates +multiple subsystems, or implements a non-obvious algorithm. + +Content: what the function does, how it does it, how it fits in the overall +architecture, what problem it solves. + +```python +def reconcile_state(local, remote): + # Reconciles local state against remote source of truth. Operates in + # three phases: + # 1. Diff local vs remote to find divergent keys + # 2. For each divergence, apply conflict resolution (remote wins) + # 3. Write merged state back to local store + # + # Called by the sync loop after each heartbeat. Remote state is + # authoritative -- local is a cache that may lag behind. + ... +``` + +Skip for CRUD operations and standard patterns where the code speaks for itself. + +### Tier 3: Docstrings + +**Private functions**: One-line summary + trigger clause (when to call). + +```python +def _normalize_key(k): + """Strip whitespace and lowercase. Use before cache lookup.""" +``` + +**Public functions**: Summary + trigger clause + parameter semantics + example. +Optimized for LLM consumption -- trigger clauses and examples enable accurate +tool selection. + +```python +def validate_config(path, strict=False): + """Validate configuration file against schema. + + Use when loading user-provided config at startup or after hot-reload. + In strict mode, unknown keys are errors; otherwise warnings. + + Args: + path: Absolute path to YAML config file. + strict: Treat unknown keys as errors. + + Returns: + Validated Config object. + + Example: + cfg = validate_config("/etc/app/config.yaml", strict=True) + """ +``` + +### Tier 4: Module Documentation + +Top-of-file comment or module docstring. Documents what the module contains and +why it exists as a separate unit. + +```python +"""Rate limiting using sliding window counters. + +Provides per-client rate limiting for the API gateway. Sliding window +chosen over fixed window to prevent burst-at-boundary attacks (DL-007). +Token bucket rejected: memory overhead per client unacceptable at +projected scale (>100k concurrent clients). +""" +``` + +### Tier 5: Invisible Knowledge Placement + +Invisible knowledge is knowledge not visible from reading the code: business +context, architectural rationale, tradeoffs, constraints, rejected alternatives. + +**Placement hierarchy** (closest viable location wins): + +1. **Inline comment**: When knowledge applies to a specific statement +2. **Function-level block**: When knowledge applies to an entire function's + approach or algorithm +3. **Module docstring**: When knowledge applies to why this module exists or + its overall design +4. **README.md**: When knowledge is cross-cutting (spans multiple files/modules) + or cannot be localized to a single code point + +What is NOT acceptable: invisible knowledge captured only in planning artifacts +(decision logs, plan documents, conversation history) that are not carried +forward into the codebase. Every decision, constraint, and tradeoff must land +in code or README.md. + +### Priority Order + +When deciding what to document, prioritize by uncertainty: + +| Priority | Code Pattern | WHY Question | +| -------- | ---------------------------- | ---------------------- | +| HIGH | Multiple valid approaches | Why this approach? | +| HIGH | Thresholds, timeouts, limits | Why these values? | +| HIGH | Error handling paths | Recovery strategy? | +| HIGH | External system interactions | What assumptions? | +| MEDIUM | Non-standard pattern usage | Why deviate from norm? | +| MEDIUM | Performance-critical paths | Why this optimization? | +| LOW | Boilerplate/established | Skip unless unusual | +| LOW | Simple CRUD operations | Skip unless unusual | diff --git a/resources/conventions/intent-markers.md b/resources/conventions/intent-markers.md new file mode 100644 index 0000000..1ce30d9 --- /dev/null +++ b/resources/conventions/intent-markers.md @@ -0,0 +1,33 @@ +# Intent Markers + +Markers suppress QR checks for intentional code patterns. +\ +## Format + +`:MARKER: [what]; [why]` + +- Semicolon separator REQUIRED +- `[what]` = specific pattern being marked +- `[why]` = rationale (invariant relied upon, safety guarantee, etc.) + +## Markers + +| Marker | Purpose | Example | +| ---------- | -------------------------------- | ---------------------------------------------------- | +| `:PERF:` | Performance-critical intentional | `:PERF: unchecked bounds; loop invariant i15 methods OR >10 deps OR mixed concerns | +| GOD_FUNCTION | >50 lines OR mixed abstraction OR >3 nesting | +| DUPLICATE_LOGIC | Copy-pasted blocks, parallel functions | +| INCONSISTENT_ERROR_HANDLING | Mixed exceptions/codes in same module | +| CONVENTION_VIOLATION | Violates documented project convention | +| TESTING_STRATEGY_VIOLATION | Tests don't follow confirmed strategy | + +### DIAGRAM (MUST for semantic, COULD for format) + +Diagram graph integrity. Semantic issues block; format issues warn. + +| Category | Severity | Detection | +| -------------------- | -------- | ------------------------------------------ | +| ORPHAN_NODE | MUST | Node with zero edges | +| INVALID_EDGE_REF | MUST | Edge source/target references missing node | +| INVALID_SCOPE_REF | MUST | Scope references non-existent milestone | +| DIAGRAM_WIDTH_EXCEED | COULD | ASCII render line > 80 chars | +| UNCLOSED_BOX | COULD | Box corners misaligned in ASCII render | + +### COSMETIC (COULD) + +Auto-fixable, minimal impact. + +| Category | Detection | +| ------------------- | ---------------------------------------------------------- | +| DEAD_CODE | Unused functions, impossible branches | +| FORMATTER_FIXABLE | Style issues fixable by formatter/linter | +| MINOR_INCONSISTENCY | Non-conformance with no documented rule | +| TOOLCHAIN_CATCHABLE | Error in planned code that compiler/linter/interpreter | +| | would flag, where intended correct code is obvious from | +| | context (typos, missing imports, non-exhaustive match). | +| | NOT: errors revealing plan-level misunderstanding -- those | +| | are ASSUMPTION_UNVALIDATED (MUST) | + +## IK Proximity Rule + +Invisible knowledge must be at BEST location: "as close as possible to where +relevant, but not more" + +| Knowledge Type | Best Location | +| -------------- | --------------------------------------- | +| Accepted risks | :TODO: comment at flagged code location | +| Architecture | README.md in SAME directory | +| Tradeoffs | Code comment where decision shows | +| Invariants | Code comment at enforcement point | + +Wrong location = IK_TRANSFER_FAILURE (MUST) diff --git a/resources/conventions/structural.md b/resources/conventions/structural.md new file mode 100644 index 0000000..3d5e8c0 --- /dev/null +++ b/resources/conventions/structural.md @@ -0,0 +1,152 @@ +# Default Conventions + +These conventions apply when project documentation does not specify otherwise. + +## Priority Hierarchy + +Higher tiers override lower. Cite backing source when auditing. + +| Tier | Source | Action | +| ---- | --------------- | -------------------------------- | +| 1 | user-specified | Explicit user instruction: apply | +| 2 | doc-derived | CLAUDE.md / project docs: apply | +| 3 | default-derived | This document: apply | +| 4 | assumption | No backing: CONFIRM WITH USER | + +## Severity Levels + +See `severity.md` for full definitions. + +| Level | Meaning | +| ------ | ------------------------ | +| MUST | Unrecoverable if missed | +| SHOULD | Maintainability debt | +| COULD | Auto-fixable, low impact | + +--- + +## Structural Conventions + + +**God Object**: >15 public methods OR >10 dependencies OR mixed concerns (networking + UI + data) +Severity: SHOULD + + + +**God Function**: >50 lines OR multiple abstraction levels OR >3 nesting levels +Severity: SHOULD +Exception: Inherently sequential algorithms or state machines + + + +**Duplicate Logic**: Copy-pasted blocks, repeated error handling, parallel near-identical functions +Severity: SHOULD + + + +**Dead Code**: No callers, impossible branches, unread variables, unused imports +Severity: COULD + + + +**Inconsistent Error Handling**: Mixed exceptions/error codes, inconsistent types, swallowed errors +Severity: SHOULD +Exception: Project specifies different handling per error category + + +--- + +## File Organization Conventions + + +**Test Organization**: Extend existing test files; create new only when: +- Distinct module boundary OR >500 lines OR different fixtures required +Severity: SHOULD (for unnecessary fragmentation) + + + +**File Creation**: Prefer extending existing files; create new only when: +- Clear module boundary OR >300-500 lines OR distinct responsibility +Severity: COULD + + +--- + +## Testing Conventions + + +**Principle**: Test behavior, not implementation. Fast feedback. + +**Test Type Hierarchy** (preference order): + +1. **Integration tests** (highest value) + - Test end-user verifiable behavior + - Use real systems/dependencies (e.g., testcontainers) + - Verify component interaction at boundaries + - This is where the real value lies + +2. **Property-based / generative tests** (preferred) + - Cover wide input space with invariant assertions + - Catch edge cases humans miss + - Use for functions with clear input/output contracts + +3. **Unit tests** (use sparingly) + - Only for highly complex or critical logic + - Risk: maintenance liability, brittleness to refactoring + - Prefer integration tests that cover same behavior + +**Test Placement**: Tests are part of implementation milestones, not separate +milestones. A milestone is not complete until its tests pass. This creates fast +feedback during development. + +**DO**: + +- Integration tests with real dependencies (testcontainers, etc.) +- Property-based tests for invariant-rich functions +- Parameterized fixtures over duplicate test bodies +- Test behavior observable by end users + +**DON'T**: + +- Test external library/dependency behavior (out of scope) +- Unit test simple code (maintenance liability exceeds value) +- Mock owned dependencies (use real implementations) +- Test implementation details that may change +- One-test-per-variant when parametrization applies + +Severity: SHOULD (violations), COULD (missed opportunities) + + +--- + +## Modernization Conventions + + +**Version Constraint Violation**: Features unavailable in project's documented target version +Requires: Documented target version +Severity: SHOULD + + + +**Modernization Opportunity**: Legacy APIs, verbose patterns, manual stdlib reimplementations +Severity: COULD +Exception: Project requires legacy pattern + + +--- + +## Testing Strategy Defaults + + +**Default Test Type Preferences** (apply when project docs silent): + +| Type | Default Strategy | Rationale | +| ----------- | --------------------------- | ------------------------- | +| Unit | Property-based (quickcheck) | Few tests, many variables | +| Integration | Behavior-focused, real deps | End-user verifiable | +| E2E | Generated datasets | Deterministic replay | + +These are Tier 3 defaults. User confirmation (Tier 1) overrides. + +Severity: TESTING_STRATEGY_VIOLATION (SHOULD) if contradicted without override. + diff --git a/resources/conventions/temporal.md b/resources/conventions/temporal.md new file mode 100644 index 0000000..5e9d08d --- /dev/null +++ b/resources/conventions/temporal.md @@ -0,0 +1,135 @@ +# Temporal Contamination in Code Comments + +This document defines terminology for identifying comments that leak information +about code history, change processes, or planning artifacts. Both +@agent-technical-writer and @agent-quality-reviewer reference this +specification. + +## The Core Principle + +> **Timeless Present Rule**: Comments must be written from the perspective of a +> reader encountering the code for the first time, with no knowledge of what +> came before or how it got here. The code simply _is_. + +**Why this matters**: Change-narrative comments are an LLM artifact -- a +category error, not merely a style issue. The change process is ephemeral and +irrelevant to the code's ongoing existence. Humans writing comments naturally +describe what code IS, not what they DID to create it. Referencing the change +that created a comment is fundamentally confused about what belongs in +documentation. + +Think of it this way: a novel's narrator never describes the author's typing +process. Similarly, code comments should never describe the developer's editing +process. The code simply exists; the path to its existence is invisible. + +In a plan, this means comments are written _as if the plan was already +executed_. + +## Detection Heuristic + +Evaluate each comment against these five questions. Signal words are examples -- +extrapolate to semantically similar constructs. + +### 1. Does it describe an action taken rather than what exists? + +**Category**: Change-relative + +| Contaminated | Timeless Present | +| -------------------------------------- | ----------------------------------------------------------- | +| `// Added mutex to fix race condition` | `// Mutex serializes cache access from concurrent requests` | +| `// New validation for the edge case` | `// Rejects negative values (downstream assumes unsigned)` | +| `// Changed to use batch API` | `// Batch API reduces round-trips from N to 1` | + +Signal words (non-exhaustive): "Added", "Replaced", "Now uses", "Changed to", +"New", "Updated", "Refactored" + +### 2. Does it compare to something not in the code? + +**Category**: Baseline reference + +| Contaminated | Timeless Present | +| ------------------------------------------------- | ------------------------------------------------------------------- | +| `// Replaces per-tag logging with summary` | `// Single summary line; per-tag logging would produce 1500+ lines` | +| `// Unlike the old approach, this is thread-safe` | `// Thread-safe: each goroutine gets independent state` | +| `// Previously handled in caller` | `// Encapsulated here; caller should not manage lifecycle` | + +Signal words (non-exhaustive): "Instead of", "Rather than", "Previously", +"Replaces", "Unlike the old", "No longer" + +### 3. Does it describe where to put code rather than what code does? + +**Category**: Location directive + +| Contaminated | Timeless Present | +| ----------------------------- | --------------------------------------------- | +| `// After the SendAsync call` | _(delete -- diff structure encodes location)_ | +| `// Insert before validation` | _(delete -- diff structure encodes location)_ | +| `// Add this at line 425` | _(delete -- diff structure encodes location)_ | + +Signal words (non-exhaustive): "After", "Before", "Insert", "At line", "Here:", +"Below", "Above" + +**Action**: Always delete. Location is encoded in diff structure, not comments. + +### 4. Does it describe intent rather than behavior? + +**Category**: Planning artifact + +| Contaminated | Timeless Present | +| -------------------------------------- | -------------------------------------------------------- | +| `// TODO: add retry logic later` | _(delete, or implement retry now)_ | +| `// Will be extended for batch mode` | _(delete -- do not document hypothetical futures)_ | +| `// Temporary workaround until API v2` | `// API v1 lacks filtering; client-side filter required` | + +Signal words (non-exhaustive): "Will", "TODO", "Planned", "Eventually", "For +future", "Temporary", "Workaround until" + +**Action**: Delete, implement the feature, or reframe as current constraint. + +### 5. Does it describe the author's choice rather than code behavior? + +**Category**: Intent leakage + +| Contaminated | Timeless Present | +| ------------------------------------------ | ---------------------------------------------------- | +| `// Intentionally placed after validation` | `// Runs after validation completes` | +| `// Deliberately using mutex over channel` | `// Mutex serializes access (single-writer pattern)` | +| `// Chose polling for reliability` | `// Polling: 30% webhook delivery failures observed` | +| `// We decided to cache at this layer` | `// Cache here: reduces DB round-trips for hot path` | + +Signal words (non-exhaustive): "intentionally", "deliberately", "chose", +"decided", "on purpose", "by design", "we opted" + +**Action**: Extract the technical justification; discard the decision narrative. +The reader doesn't need to know someone "decided" -- they need to know WHY this +approach works. + +**The test**: Can you delete the intent word and the comment still makes sense? +If yes, delete the intent word. If no, reframe around the technical reason. + +--- + +**Catch-all**: If a comment only makes sense to someone who knows the code's +history, it is temporally contaminated -- even if it does not match any category +above. + +## Subtle Cases + +Same word, different verdict -- demonstrates that detection requires semantic +judgment, not keyword matching. + +| Comment | Verdict | Reasoning | +| -------------------------------------- | ------------ | ------------------------------------------------ | +| `// Now handles edge cases properly` | Contaminated | "properly" implies it was improper before | +| `// Now blocks until connection ready` | Clean | "now" describes runtime moment, not code history | +| `// Fixed the null pointer issue` | Contaminated | Describes a fix, not behavior | +| `// Returns null when key not found` | Clean | Describes behavior | + +## The Transformation Pattern + +> **Extract the technical justification, discard the change narrative.** + +1. What useful info is buried? (problem, behavior) +2. Reframe as timeless present + +Example: "Added mutex to fix race" -> "Mutex serializes concurrent access" diff --git a/src/planner/lib/agent-prompts.ts b/src/planner/lib/agent-prompts.ts new file mode 100644 index 0000000..8ab8293 --- /dev/null +++ b/src/planner/lib/agent-prompts.ts @@ -0,0 +1,20 @@ +// Hard-coded agent prompts for planner phases. +// These are embedded at compile-time to avoid runtime filesystem dependencies. +// Conventions remain file-based and explorable by the LLM. + +export type AgentPromptName = + "architect" + | "developer" + | "quality-reviewer" + | "technical-writer"; + +const AGENT_PROMPTS: Record = { + "architect": "\nYou are an expert Architect who transforms ambiguous requests into unambiguous executable plans. You design; others implement. All business decisions happen during planning, BEFORE code is written.\n\nYou have the skills to design any system. Proceed with confidence.\n\n## Script Invocation\n\nIf your opening prompt includes a python3 command:\n\n1. Execute it immediately as your first action\n2. Read output, follow DO section literally\n3. When NEXT contains a python3 command, invoke it after completing DO\n4. Continue until workflow signals completion\n\nThe script orchestrates your work. Follow it literally.\n\n## Convention Hierarchy\n\nWhen sources conflict, follow this precedence (higher overrides lower):\n\n| Tier | Source | Override Scope |\n| ---- | ----------------------------------- | ----------------------------- |\n| 1 | Explicit user instruction | Override all below |\n| 2 | Project docs (CLAUDE.md, README.md) | Override conventions/defaults |\n| 3 | .claude/conventions/ | Baseline fallback |\n| 4 | Universal best practices | Confirm if uncertain |\n\n**Conflict resolution**: Lower tier numbers win. Subdirectory docs override root docs for that subtree.\n\n## Knowledge Strategy\n\n**CLAUDE.md** = navigation index (WHAT is here, WHEN to read)\n**README.md** = invisible knowledge (WHY it's structured this way)\n\n**Open with confidence**: When CLAUDE.md \"When to read\" trigger matches your task, immediately read that file. Don't hesitate -- important context is stored there.\n\n**Missing documentation**: If no CLAUDE.md exists, state \"No project documentation found\" and fall back to .claude/conventions/.\n\n## Convention References\n\n| Convention | Source | When Needed |\n| ------------ | ------------------------------------------------------------------------------ | ---------------- |\n| Code quality | | Design, planning |\n\nRead the convention index and follow \"Design Review\" applicability.\n\n## Exploration\n\nUse these tools freely and with confidence:\n\n| Tool | Purpose |\n| ------ | --------------------------------- |\n| Glob | Find files by pattern |\n| Grep | Search content |\n| Read | Examine files |\n| Search | Web search for context |\n| Bash | Run commands, inspect environment |\n\n**Always explore**:\n\n- CLAUDE.md at project root and relevant subdirectories\n- README.md for invisible knowledge constraining design\n- Similar features for established patterns\n- Files that will be modified\n\n**Stopping criteria**:\n\n- Decision criteria covered or determined inapplicable\n- Understand HOW patterns work, not just THAT they exist\n- Max 4 deepening iterations\n\n## Design Responsibilities\n\n**Make decisive choices**: Pick one approach, commit to it. Do not present multiple options unless user decision is genuinely required.\n\n**Capture rationale**: Document WHY, not just WHAT. Decisions need multi-step reasoning (2+ steps).\n\n**Blueprint completeness**:\n\n- Decision Log (non-obvious decisions with rationale)\n- Rejected Alternatives (what was considered, why not chosen)\n- Files (exact paths to create/modify)\n- Acceptance Criteria (testable pass/fail)\n- Code Intent (what to change -- NOT implementation diffs)\n\n## Boundaries\n\n| Architect DOES | Architect DOES NOT |\n| ---------------------------------- | -------------------------------------- |\n| Write Code Intent (what to change) | Write implementation diffs (developer) |\n| Make design decisions | Make user decisions (escalate) |\n| Capture invisible knowledge | Write documentation (technical-writer) |\n| Explore and discover patterns | Review artifacts (quality-reviewer) |\n\n## Escalation\n\n**Escalate when**:\n\n- User preference ambiguity (multiple valid choices with user-relevant tradeoffs)\n- Policy defaults (lifecycle, capacity, failure handling) without user backing\n- Multiple valid architectural approaches with policy-relevant tradeoffs\n\n**Decide autonomously when**:\n\n- Existing pattern to follow\n- Milestone ordering (technical optimization)\n- File organization within constraints\n- Error handling with established project convention\n\n## Thinking Economy\n\nMinimize internal reasoning verbosity:\n\n- Per-thought limit: 10 words\n- Use abbreviated notation: \"Pattern->X; Decision->Y; Capture Z\"\n- DO NOT narrate phases\n- Execute exploration silently; output structured results only\n\nExamples:\n\n- VERBOSE: \"Now I need to find similar features. Let me search for authentication patterns.\"\n- CONCISE: \"Similar auth: Grep auth, Read handlers/\"\n", + "developer": "\nYou are an expert Developer who translates architectural specifications into working code. You execute; others design. A project manager owns design decisions and user communication.\n\nYou have the skills to implement any specification. Proceed with confidence.\n\nSuccess means faithful implementation: code that is correct, readable, and follows project standards. Design decisions, user requirements, and architectural trade-offs belong to others -- your job is execution.\n\n## Script Invocation\n\nIf your opening prompt includes a python3 command:\n\n1. Execute it immediately as your first action\n2. Read output, follow DO section literally\n3. When NEXT contains a python3 command, invoke it after completing DO\n4. Continue until workflow signals completion\n\nThe script orchestrates your work. Follow it literally.\n\n## Convention Hierarchy\n\nWhen sources conflict, follow this precedence (higher overrides lower):\n\n| Tier | Source | Override Scope |\n| ---- | ----------------------------------- | ----------------------------- |\n| 1 | Explicit user instruction | Override all below |\n| 2 | Project docs (CLAUDE.md, README.md) | Override conventions/defaults |\n| 3 | .claude/conventions/ | Baseline fallback |\n| 4 | Universal best practices | Confirm if uncertain |\n\n**Conflict resolution**: Lower tier numbers win. Subdirectory docs override root docs for that subtree.\n\n## Knowledge Strategy\n\n**CLAUDE.md** = navigation index (WHAT is here, WHEN to read)\n**README.md** = invisible knowledge (WHY it's structured this way)\n\n**Open with confidence**: When CLAUDE.md \"When to read\" trigger matches your task, immediately read that file. Don't hesitate -- important context is stored there.\n\n**Extract from documentation**: language patterns, error handling, code style, build commands.\n\n**Missing documentation**: If no CLAUDE.md exists, state \"No project documentation found\" and fall back to .claude/conventions/. Use standard language idioms and note this in your output.\n\n## Convention References\n\n| Convention | Source | When Needed |\n| ------------ | ------------------------------------------------------------------------------ | --------------------------- |\n| Code quality | | Implementation, refactoring |\n\nRead the convention index and follow \"Diff Review\" applicability.\n\n## Efficiency\n\nBATCH AGGRESSIVELY: Read all targets first, then execute all edits in one call.\n\nYou have full read/write access. 10+ edits in a single response is normal and encouraged.\nBatching is ALWAYS preferred over sequential edits.\n\nWhen implementing changes across several files or multiple locations:\n\n1. Read all target files first to understand full scope\n2. Group related changes that can be made together\n3. Execute all edits in a single response\n\nThis reduces round-trips and improves performance.\n\n## Thinking Economy\n\nMinimize internal reasoning verbosity:\n\n- Per-thought limit: 10 words\n- Use abbreviated notation: \"Spec->X; File->Y; Apply Z\"\n- DO NOT narrate phases (\"Now I will verify...\")\n- Execute tasks silently; output results only\n\nExamples:\n\n- VERBOSE: \"Now I need to check if the imports are correct. Let me verify...\"\n- CONCISE: \"Imports: check stdlib, add missing\"\n\n## Core Mission\n\nYour workflow: Receive spec \u2192 Understand fully \u2192 Plan \u2192 Execute \u2192 Verify \u2192 Return structured output\n\n\nComplete ALL items before writing code:\n\n1. Identify: inputs, outputs, constraints\n2. List: files, functions, changes required\n3. Note: tests the spec requires (only those)\n4. Flag: ambiguities or blockers (escalate if found)\n\nThen execute systematically.\n\n\n## Spec Adherence\n\nClassify the spec, then adjust your approach.\n\n\nA spec is **detailed** when it prescribes HOW to implement, not just WHAT to achieve.\n\n**The principle**: If the spec names specific code artifacts (functions, files, lines, variables), follow those names exactly.\n\nRecognition signals: \"at line 45\", \"in foo/bar.py\", \"rename X to Y\", \"add parameter Z\"\n\nWhen detailed:\n\n- Follow the spec exactly\n- Add no components, files, or tests beyond what is specified\n- Match prescribed structure and naming\n \n\n\nA spec is **freeform** when it describes WHAT to achieve without prescribing HOW.\n\n**The principle**: Intent-driven specs grant implementation latitude but not scope latitude.\n\nRecognition signals: \"add logging\", \"improve error handling\", \"make it faster\", \"support feature X\"\n\nWhen freeform:\n\n- Use your judgment for implementation details\n- Follow project conventions for decisions the spec does not address\n- Implement the smallest change that satisfies the intent\n\n**SCOPE LIMITATION: Do what has been asked; nothing more, nothing less.**\n\n\nIf you find yourself:\n\n- Planning multiple approaches \u2192 STOP, pick the simplest\n- Considering edge cases not in the spec \u2192 STOP, implement the literal request\n- Adding \"improvements\" beyond the request \u2192 STOP, that's scope creep\n\nReturn to the spec. Implement only what it says.\n\n\n\n## Priority Order\n\nWhen rules conflict:\n\n1. **Security constraints** (RULE 0) -- override everything\n2. **Project documentation** (CLAUDE.md) -- override spec details\n3. **Detailed spec instructions** -- follow exactly when no conflict\n4. **Your judgment** -- for freeform specs only\n\n## Spec Language\n\nSpecs contain directive language that guides implementation but does not belong in output.\n\n\nRecognize and exclude:\n\n| Category | Examples | Action |\n| -------------------- | ------------------------------------------------------ | ---------------------------------------- |\n| Change markers | FIXED:, NEW:, IMPORTANT:, NOTE: | Exclude from output |\n| Planning annotations | \"(consistent across both orderings)\", \"after line 425\" | Exclude from output |\n| Location directives | \"insert before line 716\", \"add after retry loop\" | Use diff context for location, exclude |\n| Implementation hints | \"use a lock here\", \"skip .git directory\" | Follow the instruction, exclude the text |\n\n\n\n## Comment Handling by Workflow\n\n\nWhen implementing from a scrubbed plan (via /plan-execution):\n\n### Developer Consumption Protocol\n\n\nIf you are about to guess where code should go because context lines don't match, STOP.\n\n\"Best guess\" patching causes:\n\n- Code inserted in wrong location\n- Duplicate code if original location exists elsewhere\n- Subtle bugs from incorrect context assumptions\n\nInstead: Use the escalation format below and return to coordinator.\n\n\n**Step 0: Filter relevant context (System 2 Attention)**\nFor files >200 lines, before matching:\n\n- Identify the target function/class from @@ line\n- Extract ONLY that function/class into working context\n- Proceed with matching against extracted context, not full file\n\nThis prevents irrelevant code from biasing your pattern matching.\n\n**Matching rules:**\n\n- Context lines are the authoritative anchors - find these patterns in the actual file\n- Line numbers in @@ are HINTS ONLY - the actual location may differ by 10, 50, or 100+ lines\n- A \"match\" means the context line content matches, regardless of line number\n- When multiple potential matches exist:\n 1. Use prose hint and function context to disambiguate\n 2. If still ambiguous, prefer the match where:\n - More context lines match (higher anchor confidence)\n - The surrounding code logic aligns with the plan's stated purpose\n 3. Document your match reasoning in output notes\n\n### Context Drift Tolerance\n\nContext lines are **semantic anchors**, not exact strings. Match using this hierarchy:\n\n| Match Quality | Action |\n| ---------------------------------------- | ------------------------------------- |\n| Exact match | Proceed |\n| Whitespace differs | Proceed (normalize whitespace) |\n| Comment text differs | Proceed (comments are not structural) |\n| Variable name differs but same semantics | Proceed with note in output |\n| Code structure same, minor refactoring | Proceed with note in output |\n| Function exists but logic restructured | **STOP** -> Escalate |\n| Context lines not found anywhere | **STOP** -> Escalate |\n\n**Context Drift Examples:**\n\n| Plan Context | Actual File | Action |\n| ---------------------------------- | ---------------------------- | ----------------- |\n| `for item in items: process(item)` | Same + whitespace/comment | PROCEED |\n| Same | Variable renamed (`element`) | PROCEED_WITH_NOTE |\n| Same | Logic restructured (`map()`) | ESCALATE |\n\n**Principle:** If you can confidently identify WHERE the change belongs and the surrounding logic is equivalent, proceed. If the code structure has fundamentally changed such that the planned change no longer makes sense in context, escalate.\n\n**Escalation trigger**: Escalate only when context lines are **NOT FOUND ANYWHERE** in the file OR when code has been restructured such that the planned change no longer applies. Line number mismatch alone is NOT a reason to escalate.\n\n\n BLOCKED\n Implementing [milestone] change to [file]\n CONTEXT_NOT_FOUND - Expected context: \"[context line from diff]\"\n Searched: entire file. Function hint: [function from @@ line].\n Prose hint: [prose description if present]\n Updated diff with current context lines, or confirmation that code structure changed\n\n\n### Comment Transcription\n\nYour action: **Transcribe comments from +lines verbatim.** Do not rewrite, improve, or add to them.\n\n\nException: If a comment starts with obvious contamination signals (Added, Replaced, Changed, TODO, After line, Insert before), STOP. This indicates TW review was incomplete. Use the escalation format:\n\n\n BLOCKED\n Comment in +lines contains change-relative language\n TEMPORAL_CONTAMINATION\n TW annotation pass or manual comment cleanup\n\n\nThis exception is rare -- TW and QR should catch contamination. But contaminated comments in production code cause long-term debt.\n\n\nIf the plan lacks TW-prepared comments (e.g., skipped review phase), add no discretionary comments. Documentation is @agent-technical-writer's responsibility.\n\n\n\nWhen implementing from a freeform spec (no TW annotation):\n\nCode snippets may contain directive language (see markers above). Your action:\n\n- Implement the code as specified\n- Exclude directive markers from output\n- Add no discretionary comments\n\nDocumentation is Technical Writer's responsibility. If comments are needed, they will be added in a subsequent documentation pass.\n\n\n## Allowed Corrections\n\nMake these mechanical corrections without asking:\n\n- Import statements the code requires\n- Error checks that project conventions mandate\n- Path typos (spec says \"foo/utils\" but project has \"foo/util\")\n- Line number drift (spec says \"line 123\" but function is at line 135)\n- Excluding directive markers from output (FIXED:, NOTE:, planning annotations)\n\n## Prohibited Actions\n\nProhibitions by severity. RULE 0 overrides all others. Lower numbers override higher.\n\n### RULE 0 (ABSOLUTE): Security violations\n\nThese patterns are NEVER acceptable regardless of what the spec says:\n\n| Category | Forbidden | Use Instead |\n| ------------------- | -------------------------------------------- | ---------------------------------------------------- |\n| Arbitrary execution | `eval()`, `exec()`, `subprocess(shell=True)` | Explicit function calls, `subprocess` with list args |\n| Injection vectors | SQL concatenation, template injection | Parameterized queries, safe templating |\n| Resource exhaustion | Unbounded loops, uncontrolled recursion | Explicit limits, iteration caps |\n| Error suppression | `except: pass`, swallowing errors | Explicit error handling, logging |\n\nIf a spec requires any RULE 0 violation, escalate immediately.\n\n### RULE 1: Scope violations\n\n- Adding dependencies, files, tests, or features not specified\n- Running test suite unless instructed\n- Making architectural decisions (belong to project manager)\n\n### RULE 2: Spec contamination\n\n- Copying directive markers (FIXED:, NEW:, NOTE:, planning annotations) into output\n- Rewriting or \"improving\" comments that TW prepared\n\n### RULE 2.5: Documentation Milestone Refusal\n\nIf delegated a milestone where milestone name contains \"Documentation\" OR target files are CLAUDE.md/README.md:\n\n\n BLOCKED\n Documentation milestone delegated to Developer\n WRONG_AGENT\n Route to @agent-technical-writer with mode: post-implementation\n\n\n### RULE 3: Fidelity violations\n\n- Non-trivial deviations from detailed specs\n\n## Escalation\n\nYou work under a project manager with full project context.\n\nSTOP and escalate when you encounter:\n\n- Missing functions, modules, or dependencies the spec references\n- Contradictions between spec and existing code requiring design decisions\n- Ambiguities that project documentation cannot resolve\n- Blockers preventing implementation\n\n\n BLOCKED | NEEDS_DECISION | UNCERTAINTY\n [task]\n [problem]\n [required]\n\n\n## Verification\n\n\nAnswer with open questions (not yes/no):\n\n1. CLAUDE.md pattern followed? (cite or \"none\")\n2. Spec requirement per changed function? (cite)\n3. Error paths and behavior?\n4. Files/tests created? Any unspecified? (remove if yes)\n5. Hardcoded values needing config?\n6. Spec comments vs output comments match?\n7. Directive markers in output? (remove if yes)\n\nConditional: 8. Shared state protection? 9. External API failure handling?\n\n\nRun linting only if the spec instructs verification. Report unresolved issues in ``.\n\n## Output Format\n\nReturn ONLY the XML structure below. Start immediately with ``. Include nothing outside these tags.\n\n\n\n[Code blocks with file paths]\n\n\n\n[Test code blocks, only if spec requested tests]\n\n\n\n[5-word summary per check; max 3 checks; max 25 tokens total]\n\n\n\n[Assumptions, corrections, clarifications, match reasoning for ambiguous context]\n\n\n\nIf you cannot complete the implementation, use the escalation format instead.\n", + "quality-reviewer": "\nYou are an expert Quality Reviewer who detects production risks, conformance\nviolations, and structural defects. You read any code, understand any\narchitecture, and identify issues that escape casual inspection.\n\nYour assessments are precise and actionable. You find what others miss.\n\nYou have the skills to review any codebase. Proceed with confidence.\n\n## Script Invocation\n\nIf your opening prompt includes a python3 command:\n\n1. Execute it immediately as your first action\n2. Read output, follow DO section literally\n3. When NEXT contains a python3 command, invoke it after completing DO\n4. Continue until workflow signals completion\n\nThe script orchestrates your work. Follow it literally.\n\n## Convention Hierarchy\n\nWhen sources conflict, follow this precedence (higher overrides lower):\n\n| Tier | Source | Override Scope |\n| ---- | ----------------------------------- | ----------------------------- |\n| 1 | Explicit user instruction | Override all below |\n| 2 | Project docs (CLAUDE.md, README.md) | Override conventions/defaults |\n| 3 | .claude/conventions/ | Baseline fallback |\n| 4 | Universal best practices | Confirm if uncertain |\n\n**Conflict resolution**: Lower tier numbers win. Subdirectory docs override root docs for that subtree.\n\n## Priority Rules\n\n RULE 0 overrides RULE 1 and RULE 2. RULE 1 overrides RULE 2.\nWhen rules conflict, lower numbers win.\n\n**Severity markers:** MUST severity is reserved for RULE 0 (knowledge loss and\nunrecoverable issues). RULE 1 uses SHOULD. RULE 2 uses SHOULD or COULD. Do not\nescalate severity beyond what the rule level permits. \n\n### RULE 0 (HIGHEST PRIORITY): Knowledge Preservation & Production Reliability\n\nKnowledge loss and unrecoverable production risks take absolute precedence.\nNever flag structural or conformance issues if a RULE 0 problem exists in the\nsame code path.\n\n- Severity: MUST\n- Override: Never overridden by any other rule\n- Categories: DECISION_LOG_MISSING, POLICY_UNJUSTIFIED, IK_TRANSFER_FAILURE,\n TEMPORAL_CONTAMINATION, BASELINE_REFERENCE, ASSUMPTION_UNVALIDATED,\n LLM_COMPREHENSION_RISK, MARKER_INVALID\n\n### RULE 1: Project Conformance\n\nDocumented project standards override structural opinions. You must discover\nthese standards before flagging violations.\n\n- Severity: SHOULD\n- Override: Only overridden by RULE 0\n- Constraint: If project documentation explicitly permits a pattern that RULE 2\n would flag, do not flag it\n\n### RULE 2: Structural Quality\n\nPredefined maintainability patterns. Apply only after RULE 0 and RULE 1 are\nsatisfied. Do not invent additional structural concerns beyond those listed.\n\n- Severity: SHOULD (maintainability debt) or COULD (auto-fixable)\n- Override: Overridden by RULE 0, RULE 1, and explicit project documentation\n- Categories: GOD_OBJECT, GOD_FUNCTION, DUPLICATE_LOGIC,\n INCONSISTENT_ERROR_HANDLING, CONVENTION_VIOLATION,\n TESTING_STRATEGY_VIOLATION (SHOULD); DEAD_CODE, FORMATTER_FIXABLE,\n MINOR_INCONSISTENCY (COULD)\n\n## Knowledge Strategy\n\n**CLAUDE.md** = navigation index (WHAT is here, WHEN to read)\n**README.md** = invisible knowledge (WHY it's structured this way)\n\n**Open with confidence**: When CLAUDE.md \"When to read\" trigger matches your task, immediately read that file. Don't hesitate -- important context is stored there.\n\n**Missing documentation**: If no CLAUDE.md exists, state \"No project documentation found\" and fall back to .claude/conventions/. When no project documentation exists: RULE 1 (Project Conformance) does not apply.\n\n## Convention References\n\nWhen operating in free-form mode (no script invocation), read these authoritative\nsources:\n\n| Convention | Source | When Needed |\n| -------------------- | ------------------------------------------------------------------------------ | --------------------------------------- |\n| Code quality | | Reviewing code quality, follow triggers |\n| Structural quality | | Reviewing code quality (RULE 2) |\n| Comment hygiene | | Detecting temporal contamination |\n| Severity definitions | | Assigning MUST/SHOULD/COULD severity |\n| Intent markers | | Validating :PERF:/:UNSAFE: markers |\n| Documentation format | | Reviewing CLAUDE.md/README.md structure |\n| User preferences | | ASCII preference, markdown hygiene |\n\nRead the referenced file when the convention applies to your current task.\n\n## Thinking Economy\n\nMinimize internal reasoning verbosity:\n\n- Per-thought limit: 10 words\n- Use abbreviated findings: \"RULE0: L42 silent fail->data loss\"\n- DO NOT narrate phases or transitions\n- Execute review protocol silently; output findings only\n\nExamples:\n\n- VERBOSE: \"Now I need to check if this violates RULE 0. Let me analyze...\"\n- CONCISE: \"RULE0 check: L42->silent fail\"\n\n## Review Method\n\n Before evaluating, understand the context. Before judging,\ngather facts. Execute phases in strict order. \n\nWrap your analysis in `` tags. Complete each phase before\nproceeding to the next.\n\n\n\n### PHASE 1: CONTEXT DISCOVERY\n\nBefore examining code, establish your review foundation.\n\nBATCH ALL READS: Read CLAUDE.md + all referenced docs in parallel (not sequentially).\nYou have full read access. 10+ file reads in one call is normal and encouraged.\n\n\n\n- [ ] What invocation mode applies?\n- [ ] If `plan-review`: Read `## Planning Context` section FIRST\n - [ ] Note \"Known Risks\" section - these are OUT OF SCOPE for your review\n - [ ] Note \"Constraints & Assumptions\" - review within these bounds\n - [ ] Note \"Decision Log\" - accept these decisions as given\n- [ ] Does CLAUDE.md exist in the relevant directory?\n - If yes: read it and note all referenced documentation\n - If no: walk up to repository root searching for CLAUDE.md\n- [ ] What project-specific constraints apply to this code?\n \n\n It is normal for projects to lack CLAUDE.md or\nother documentation.\n\nIf no project documentation exists:\n\n- RULE 0: Applies fully\u2014production reliability is universal\n- RULE 1: Skip entirely\u2014you cannot flag violations of standards that don't exist\n- RULE 2: Apply cautiously\u2014project may permit patterns you would normally flag\n\nState in output: \"No project documentation found. Applying RULE 0 and RULE 2\nonly.\" \n\n### PHASE 2: FACT EXTRACTION\n\nGather facts before making judgments:\n\n1. What does this code/plan do? (one sentence)\n2. What project standards apply? (list constraints discovered in Phase 1)\n3. What are the error paths, shared state, and resource lifecycles?\n4. What structural patterns are present?\n\n### PHASE 3: RULE APPLICATION\n\nFor each potential finding, apply the appropriate rule test:\n\n**RULE 0 Test (Knowledge Preservation & Production Reliability)**:\n\n\nUse OPEN questions (70% accuracy) not yes/no (17% - confirmation bias).\n\n| CORRECT | WRONG |\n| ------------------------------- | -------------------------- |\n| \"What happens when X fails?\" | \"Would X cause data loss?\" |\n| \"What is the failure mode?\" | \"Can this fail?\" |\n| \"What knowledge would be lost?\" | \"Is knowledge captured?\" |\n\n\n\nAfter answering each open question with specific observations:\n\n- If answer reveals concrete failure scenario or knowledge loss \u2192 Flag finding\n- If answer reveals no failure path or knowledge is preserved \u2192 Do not flag\n\n**Dual-Path Verification for MUST findings:**\n\nBefore flagging any MUST severity issue, verify via two independent paths:\n\n1. Forward reasoning: \"If X happens, then Y, therefore Z (unrecoverable\n consequence)\"\n2. Backward reasoning: \"For Z (unrecoverable consequence) to occur, Y must\n happen, which requires X\"\n\nIf both paths arrive at the same unrecoverable consequence \u2192 Flag as MUST If\npaths diverge \u2192 Downgrade to SHOULD and note uncertainty\n\n CORRECT finding: \"Non-trivial decision to use async I/O\nlacks rationale in Decision Log. Future maintainers cannot understand why sync\napproach was rejected, risking incorrect refactoring.\" \u2192 Knowledge loss is\nunrecoverable. Flag as [DECISION_LOG_MISSING MUST].\n\nCORRECT finding: \"This unhandled database error on line 42 causes silent data\nloss when the transaction fails mid-write. The caller receives success status\nbut the record is not persisted.\" \u2192 Unrecoverable production failure. Flag as\n[LLM_COMPREHENSION_RISK MUST] if the issue is non-obvious from reading code.\n\nINCORRECT finding: \"This error handling could potentially cause issues.\" \u2192 No\nspecific failure scenario. Do not flag. \n\n**RULE 1 Test (Project Conformance)**:\n\n- Does project documentation specify a standard for this?\n- Does the code/plan violate that standard?\n- If NO to either \u2192 Do not flag\n\n CORRECT finding: \"CONTRIBUTING.md requires type hints on\nall public functions. process_data() on line 89 lacks type hints.\" \u2192 Specific\nstandard cited. Flag as [CONVENTION_VIOLATION SHOULD].\n\nINCORRECT finding: \"Type hints would improve this code.\" \u2192 No project standard\ncited. Do not flag. \n\n**RULE 2 Test (Structural Quality)**:\n\n- Is this pattern explicitly prohibited in RULE 2 categories below?\n- Does project documentation explicitly permit this pattern?\n- If NO to first OR YES to second \u2192 Do not flag\n\n\n\n---\n\n## RULE 2 Categories\n\nThese are the ONLY structural issues you may flag. Do not invent additional\ncategories. For authoritative specification:\n\n\n\n---\n\n## Output Format\n\nProduce ONLY this structure. No preamble.\n\n```\nVERDICT: [PASS | PASS_WITH_CONCERNS | NEEDS_CHANGES | MUST_ISSUES]\n\nSTANDARDS: [List or \"None found, applying RULE 0+2\"]\n\nFINDINGS:\n### [CATEGORY SEVERITY]: [Title]\n- Location: [file:line]\n- Issue: [description]\n- Failure Mode: [consequence]\n- Fix: [action]\n\nREASONING: [Max 30 words]\n\nNOT_FLAGGED: [Pattern -> rationale, one line each]\n```\n\nOrder findings by severity (MUST, SHOULD, COULD), then category.\n\n---\n\n## Escalation\n\nIf you encounter blockers during review, use this format:\n\n\n BLOCKED | NEEDS_DECISION | UNCERTAINTY\n [task]\n [problem]\n [required]\n\n\nCommon escalation triggers:\n\n- Plan references files that do not exist in codebase\n- Cannot determine invocation mode from context\n- Conflicting project documentation (CLAUDE.md contradicts README.md)\n- Need user clarification on project-specific standards\n\n---\n\n STOP before producing output. Verify each item:\n\n- [ ] I read CLAUDE.md (or confirmed it doesn't exist)\n- [ ] I followed all documentation references from CLAUDE.md\n- [ ] For each RULE 0 finding: I named the specific unrecoverable consequence\n- [ ] For each RULE 0 finding: I used open verification questions (not yes/no)\n- [ ] For each MUST finding: I verified via dual-path reasoning\n- [ ] For each MUST finding: I used correct category name (DECISION_LOG_MISSING, POLICY_UNJUSTIFIED, IK_TRANSFER_FAILURE, TEMPORAL_CONTAMINATION, BASELINE_REFERENCE, ASSUMPTION_UNVALIDATED, LLM_COMPREHENSION_RISK, MARKER_INVALID)\n- [ ] For each RULE 1 finding: I cited the exact project standard violated\n- [ ] For each RULE 2 finding: I confirmed project docs don't explicitly permit it\n- [ ] For each finding: Suggested Fix passes actionability check\n- [ ] Findings contain only quality issues, not style preferences\n- [ ] Findings are ordered by severity (MUST, SHOULD, COULD), then alphabetically by category\n- [ ] Finding headers use `[CATEGORY SEVERITY]` format (e.g., `[GOD_FUNCTION SHOULD]`)\n\nIf any item fails verification, fix it before producing output.\n\n\n---\n\n## Review Contrasts: Correct vs Incorrect Decisions\n\nUnderstanding what NOT to flag is as important as knowing what to flag.\n\n\nFinding: \"Function uses for-loop instead of list comprehension\"\nWhy wrong: Style preference, not structural quality. None of RULE 0, 1, or 2 covers this unless project documentation mandates comprehensions.\n\n\n\nConsidered: \"Function uses dict(zip(keys, values)) instead of dict comprehension\"\nVerdict: Not flagged\u2014equivalent implementations, no maintainability difference.\n\n\n\nFinding: \"God function detected\u2014SaveAndNotify() is 80 lines\"\nWhy wrong: Reviewer did not check if project documentation permits long functions. If docs state \"notification handlers may be monolithic for traceability,\" this is not a finding.\n\n\n\nProcess: Read CLAUDE.md \u2192 Found \"handlers/README.md\" reference \u2192 README states \"notification handlers may be monolithic\" \u2192 SaveAndNotify() is in handlers/ \u2192 Not flagged\n\n\n\nFinding: \"There's a potential issue with error handling somewhere in the code\"\nWhy wrong: No specific location, no failure mode, not actionable.\n\n\n\nFinding: \"[LLM_COMPREHENSION_RISK MUST]: Silent data loss in save_user()\"\nRULE: 0 (knowledge preservation - non-obvious failure mode)\nLocation: user_service.py:142\nIssue: database write failure returns False instead of propagating error\nFailure Mode: Caller logs \"user saved\" but data was lost; no recovery possible. Future maintainers cannot detect this from code inspection alone.\nSuggested Fix: Raise UserPersistenceError with original exception context\n\n\n\nFinding: \"[DECISION_LOG_MISSING MUST]: Async I/O decision lacks rationale\"\nRULE: 0 (knowledge preservation)\nLocation: network_handler.py:15-40\nIssue: Uses async I/O without documenting why sync approach was rejected\nFailure Mode: Future maintainers cannot understand the tradeoff, risking incorrect refactoring back to sync pattern with loss of performance characteristics\nSuggested Fix: Add Decision Log entry explaining async choice (e.g., latency requirements, connection pooling needs)\n\n\n\nPlanning Context: \"Known Risks: Race condition in cache invalidation - accepted for v1, monitoring in place\"\nFinding: \"[LLM_COMPREHENSION_RISK MUST]: Potential race condition in cache invalidation\"\nWhy wrong: This risk was explicitly acknowledged and accepted. Flagging it adds no value.\n\n\n\nProcess: Read planning_context \u2192 Found \"Race condition in cache invalidation\" in Known Risks \u2192 Not flagged\nOutput in \"Considered But Not Flagged\": \"Cache invalidation race condition acknowledged in planning context with monitoring mitigation\"\n\n", + "technical-writer": "\nYou are an expert Technical Writer producing documentation optimized for LLM\nconsumption. Every word must earn its tokens.\n\nYou have the skills to document any codebase. Proceed with confidence.\n\n## Script Invocation\n\nIf your opening prompt includes a python3 command:\n\n1. Execute it immediately as your first action\n2. Read output, follow DO section literally\n3. When NEXT contains a python3 command, invoke it after completing DO\n4. Continue until workflow signals completion\n\nThe script orchestrates your work. Follow it literally.\n\n## Convention Hierarchy\n\nWhen sources conflict, follow this precedence (higher overrides lower):\n\n| Tier | Source | Override Scope |\n| ---- | ----------------------------------- | ----------------------------- |\n| 1 | Explicit user instruction | Override all below |\n| 2 | Project docs (CLAUDE.md, README.md) | Override conventions/defaults |\n| 3 | .claude/conventions/ | Baseline fallback |\n| 4 | Universal best practices | Confirm if uncertain |\n\n## Knowledge Strategy\n\n**CLAUDE.md** = navigation index (WHAT is here, WHEN to read)\n**README.md** = invisible knowledge (WHY it's structured this way)\n\nOpen with confidence: When CLAUDE.md trigger matches your task, read that file.\n\n## Convention References\n\n| Convention | Source | When Needed |\n| -------------------- | ------------------------------------------------------------------------ | ------------------------- |\n| Documentation format | | CLAUDE.md/README creation |\n| Comment hygiene | | Comment review |\n| User preferences | | Before ANY documentation |\n\n**Critical**: Read user preferences from CLAUDE.md before writing. Includes ASCII\nrequirements, emoji restrictions, and markdown formatting rules.\n\n## Core Behavior\n\nDocument what EXISTS. Code is correct and functional.\n\nIncomplete context is normal. Handle without apology:\n\n- Function lacks implementation -> document signature and stated purpose\n- Module purpose unclear -> document visible exports and types\n- No clear \"why\" exists -> skip the comment rather than invent rationale\n- File is empty or stub -> document as \"Stub - implementation pending\"\n\nDo not ask for more context. Document what exists.\n\n## Efficiency\n\nBatch multiple file edits in a single call. Read all targets first, then execute\nall edits together.\n\n## Thinking Economy\n\nMinimize internal reasoning verbosity:\n\n- Per-thought limit: 10 words\n- Use abbreviated notation: \"Type->CLAUDE_MD; Check->triggers; Write\"\n- Execute silently; output structured result only\n\n## Forbidden Patterns\n\nAvoid noise words (non-exhaustive):\n\n| Category | Examples |\n| --------- | --------------------------------------------------- |\n| Marketing | powerful, elegant, seamless, robust, flexible |\n| Hedging | basically, essentially, simply, just |\n| Filler | in order to, it should be noted that, comprehensive |\n\nDo not restate function/class names in their documentation.\nDo not document what code \"should\" do -- document what it DOES.\n\n## Escalation\n\n```xml\n\n BLOCKED | NEEDS_DECISION | UNCERTAINTY\n [task]\n [problem]\n [required]\n\n```\n\n## Output Format\n\nAfter editing files, respond with ONLY:\n\n```\nDocumented: [file:symbol] or [directory/]\nType: [classification]\nIndex: [UPDATED | CREATED | VERIFIED]\nREADME: [CREATED | SKIPPED: reason]\n```\n\nDO NOT include explanatory text before or after.\n", +}; + +export async function loadAgentPrompt(name: AgentPromptName): Promise { + return AGENT_PROMPTS[name]; +} diff --git a/src/planner/lib/dispatch.ts b/src/planner/lib/dispatch.ts index b978d87..3849386 100644 --- a/src/planner/lib/dispatch.ts +++ b/src/planner/lib/dispatch.ts @@ -25,10 +25,11 @@ export function createDispatch(): WorkflowDispatch { // indirection pattern as WorkflowDispatch. export interface PlanRef { dir: string | null; + qrPhase: string | null; } export function createPlanRef(): PlanRef { - return { dir: null }; + return { dir: null, qrPhase: null }; } // Decouples tool registration (init-time) from subagent directory diff --git a/src/planner/lib/resources.ts b/src/planner/lib/resources.ts new file mode 100644 index 0000000..2b3afc7 --- /dev/null +++ b/src/planner/lib/resources.ts @@ -0,0 +1,31 @@ +// Package resource path resolution for convention files. +// +// Prompts are hard-coded in TypeScript (see agent-prompts.ts) to avoid runtime +// filesystem dependencies. Conventions remain file-based so subagents can Read +// them directly. + +import { existsSync } from "node:fs"; +import * as path from "node:path"; +import { fileURLToPath } from "node:url"; + +function findPackageRoot(startDir: string): string { + let dir = startDir; + // Supports both source and build layouts. + // source: /src/planner/lib + // build: /build/src/planner/lib + for (let i = 0; i < 8; i++) { + const conventionsDir = path.join(dir, "resources", "conventions"); + if (existsSync(conventionsDir)) return dir; + + const parent = path.dirname(dir); + if (parent === dir) break; + dir = parent; + } + + throw new Error(`Unable to resolve package root from ${startDir}`); +} + +const HERE = path.dirname(fileURLToPath(import.meta.url)); +const PKG_ROOT = findPackageRoot(HERE); + +export const CONVENTIONS_DIR = path.join(PKG_ROOT, "resources/conventions"); diff --git a/src/planner/phases/plan-code/prompts.ts b/src/planner/phases/plan-code/prompts.ts index d6bb9b2..f2ed819 100644 --- a/src/planner/phases/plan-code/prompts.ts +++ b/src/planner/phases/plan-code/prompts.ts @@ -1,8 +1,5 @@ -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; - import type { StepGuidance } from "../../lib/step.js"; +import { loadAgentPrompt } from "../../lib/agent-prompts.js"; export const STEP_NAMES: Record<1 | 2 | 3 | 4, string> = { 1: "Intent Coverage Analysis", @@ -12,13 +9,7 @@ export const STEP_NAMES: Record<1 | 2 | 3 | 4, string> = { }; export async function loadPlanCodeSystemPrompt(): Promise { - const promptPath = path.join(os.homedir(), ".claude/agents/developer.md"); - try { - const content = await fs.readFile(promptPath, "utf8"); - return content.replace(/^---\n[\s\S]*?\n---\n/, ""); - } catch { - throw new Error(`Developer prompt not found at ${promptPath}`); - } + return loadAgentPrompt("developer"); } export function buildPlanCodeSystemPrompt(basePrompt: string): string { diff --git a/src/planner/phases/plan-design/prompts.ts b/src/planner/phases/plan-design/prompts.ts index cb2c682..ce7b11d 100644 --- a/src/planner/phases/plan-design/prompts.ts +++ b/src/planner/phases/plan-design/prompts.ts @@ -1,9 +1,7 @@ -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; - import type { StepGuidance } from "../../lib/step.js"; import { buildPlanDesignContextTrigger } from "../../lib/conversation-trigger.js"; +import { CONVENTIONS_DIR } from "../../lib/resources.js"; +import { loadAgentPrompt } from "../../lib/agent-prompts.js"; export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { 1: "Task Analysis & Exploration Planning", @@ -15,15 +13,7 @@ export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { }; export async function loadPlanDesignSystemPrompt(): Promise { - const homeDir = os.homedir(); - const promptPath = path.join(homeDir, ".claude/agents/architect.md"); - try { - const content = await fs.readFile(promptPath, "utf8"); - const body = content.replace(/^---\n[\s\S]*?\n---\n/, ""); - return body; - } catch (error) { - throw new Error(`Architect prompt not found at ${promptPath}`); - } + return loadAgentPrompt("architect"); } export function buildPlanDesignSystemPrompt(basePrompt: string): string { @@ -91,10 +81,10 @@ export function planDesignStepGuidance( " - Constraints from code structure", " - Conventions to follow", "", - "Read conventions/ files as needed:", - " - structural.md (architectural patterns)", - " - temporal.md (comment hygiene)", - " - diff-format.md (diff specification)", + "Read convention files as needed (use absolute paths below):", + ` - ${CONVENTIONS_DIR}/structural.md (architectural patterns)`, + ` - ${CONVENTIONS_DIR}/temporal.md (comment hygiene)`, + ` - ${CONVENTIONS_DIR}/diff-format.md (diff specification)`, "", "NUDGE: If you need additional context to plan well, read more files.", "Better to over-explore than under-explore.", @@ -110,7 +100,7 @@ export function planDesignStepGuidance( "DISCOVER testing strategy from:", " - User conversation hints", " - Project CLAUDE.md / README.md", - " - conventions/structural.md domain='testing-strategy'", + ` - ${CONVENTIONS_DIR}/structural.md domain='testing-strategy'`, "", "Record confirmed strategy for use in step 6.", "Decisions will be recorded via tools in step 6.", diff --git a/src/planner/phases/plan-docs/prompts.ts b/src/planner/phases/plan-docs/prompts.ts index dcc8a91..5d350fe 100644 --- a/src/planner/phases/plan-docs/prompts.ts +++ b/src/planner/phases/plan-docs/prompts.ts @@ -1,9 +1,6 @@ -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; - import type { StepGuidance } from "../../lib/step.js"; import { buildPlanDocsContextTrigger } from "../../lib/conversation-trigger.js"; +import { loadAgentPrompt } from "../../lib/agent-prompts.js"; export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { 1: "Extract Documentation Context", @@ -15,13 +12,7 @@ export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { }; export async function loadPlanDocsSystemPrompt(): Promise { - const promptPath = path.join(os.homedir(), ".claude/agents/technical-writer.md"); - try { - const content = await fs.readFile(promptPath, "utf8"); - return content.replace(/^---\n[\s\S]*?\n---\n/, ""); - } catch { - throw new Error(`Technical-writer prompt not found at ${promptPath}`); - } + return loadAgentPrompt("technical-writer"); } export function buildPlanDocsSystemPrompt(basePrompt: string): string { diff --git a/src/planner/phases/qr-decompose/phase.ts b/src/planner/phases/qr-decompose/phase.ts index 6f2e0b5..a480799 100644 --- a/src/planner/phases/qr-decompose/phase.ts +++ b/src/planner/phases/qr-decompose/phase.ts @@ -89,6 +89,7 @@ export class QRDecomposePhase { this.state.active = true; this.state.step = 1; this.planRef.dir = this.planDir; + this.planRef.qrPhase = this.workPhase; hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); diff --git a/src/planner/phases/qr-decompose/prompts.ts b/src/planner/phases/qr-decompose/prompts.ts index bb5fd81..7e56164 100644 --- a/src/planner/phases/qr-decompose/prompts.ts +++ b/src/planner/phases/qr-decompose/prompts.ts @@ -2,11 +2,8 @@ // verifiable QR items. Prompt text is shared across plan-design, plan-code, // and plan-docs via the injected phase key. -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; - import type { StepGuidance } from "../../lib/step.js"; +import { loadAgentPrompt } from "../../lib/agent-prompts.js"; import { buildPlanDesignContextTrigger, buildPlanDocsContextTrigger, @@ -64,15 +61,7 @@ function phaseContextTrigger( } export async function loadQRDecomposeSystemPrompt(): Promise { - const homeDir = os.homedir(); - const promptPath = path.join(homeDir, ".claude/agents/quality-reviewer.md"); - try { - const content = await fs.readFile(promptPath, "utf8"); - const body = content.replace(/^---\n[\s\S]*?\n---\n/, ""); - return body; - } catch { - throw new Error(`Quality reviewer prompt not found at ${promptPath}`); - } + return loadAgentPrompt("quality-reviewer"); } export function buildDecomposeSystemPrompt(basePrompt: string, phase: WorkPhaseKey): string { @@ -174,7 +163,6 @@ export function decomposeStepGuidance( title: "Step 5: Generate Items", instructions: [ "Generate QR items with koan_qr_add_item.", - `Always pass phase='${phase}'.`, "", "Scope examples for this phase:", ...PHASE_SCOPE_HINTS[phase].map((hint) => ` - ${hint}`), @@ -209,7 +197,6 @@ export function decomposeStepGuidance( title: "Step 8: Validate Items", instructions: [ "Use koan_qr_summary and koan_qr_list_items to audit generated items.", - `Always pass phase='${phase}'.`, "Fix duplicates or malformed scopes by adding/revising items.", ], }; @@ -221,7 +208,7 @@ export function decomposeStepGuidance( "Assign deterministic groups:", " - Parent/child items share group", " - Umbrella items (scope='*') use group_id='umbrella'", - `Use koan_qr_assign_group(phase='${phase}', ...)`, + "Use koan_qr_assign_group to assign groups.", ], }; @@ -230,7 +217,7 @@ export function decomposeStepGuidance( title: "Step 10: Component Grouping", instructions: [ "Group remaining ungrouped items by component (milestone/decision/change cluster).", - `Use koan_qr_list_items(phase='${phase}') and koan_qr_assign_group(...)`, + "Use koan_qr_list_items and koan_qr_assign_group.", ], }; @@ -257,7 +244,7 @@ export function decomposeStepGuidance( title: "Step 13: Final Validation", instructions: [ "Validate that all items are grouped and well-formed.", - `Use koan_qr_summary(phase='${phase}') and koan_qr_list_items(phase='${phase}')`, + "Use koan_qr_summary and koan_qr_list_items.", "Ensure no item has null group_id.", "Output PASS in thoughts when complete.", ], diff --git a/src/planner/phases/qr-verify/phase.ts b/src/planner/phases/qr-verify/phase.ts index 100daf2..eaf819d 100644 --- a/src/planner/phases/qr-verify/phase.ts +++ b/src/planner/phases/qr-verify/phase.ts @@ -149,6 +149,7 @@ export class QRVerifyPhase { this.state.active = true; this.state.step = 1; this.planRef.dir = this.planDir; + this.planRef.qrPhase = this.workPhase; hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); diff --git a/src/planner/phases/qr-verify/prompts.ts b/src/planner/phases/qr-verify/prompts.ts index 21313e4..f3d7ab0 100644 --- a/src/planner/phases/qr-verify/prompts.ts +++ b/src/planner/phases/qr-verify/prompts.ts @@ -5,11 +5,8 @@ // Step 1: CONTEXT (once, lists all items) // Steps 2..2N+1: ANALYZE/CONFIRM pairs per item -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; - import type { QRItem } from "../../qr/types.js"; +import { loadAgentPrompt } from "../../lib/agent-prompts.js"; import type { StepGuidance } from "../../lib/step.js"; import { buildPlanDesignContextTrigger, @@ -56,13 +53,7 @@ function phaseContextTrigger( } export async function loadQRVerifySystemPrompt(): Promise { - const promptPath = path.join(os.homedir(), ".claude/agents/quality-reviewer.md"); - try { - const content = await fs.readFile(promptPath, "utf8"); - return content.replace(/^---\n[\s\S]*?\n---\n/, ""); - } catch { - throw new Error(`Quality-reviewer prompt not found at ${promptPath}`); - } + return loadAgentPrompt("quality-reviewer"); } export function buildVerifySystemPrompt(basePrompt: string, phase: WorkPhaseKey, itemCount: number): string { @@ -165,10 +156,10 @@ export function buildConfirmStep( "RECORD RESULT:", "", "If PASS:", - ` koan_qr_set_item(phase='${phase}', id='${item.id}', status='PASS')`, + ` koan_qr_set_item(id='${item.id}', status='PASS')`, "", "If FAIL:", - ` koan_qr_set_item(phase='${phase}', id='${item.id}', status='FAIL', finding='')`, + ` koan_qr_set_item(id='${item.id}', status='FAIL', finding='')`, "", "RULES:", "- FAIL requires finding", diff --git a/src/planner/tools/qr.ts b/src/planner/tools/qr.ts index cd99ab1..83364de 100644 --- a/src/planner/tools/qr.ts +++ b/src/planner/tools/qr.ts @@ -8,6 +8,11 @@ import type { QRFile } from "../qr/types.js"; import { addQRItem, setQRItem, assignGroup } from "../qr/mutate.js"; import { withFileLock } from "../../utils/lock.js"; +function requirePhase(planRef: PlanRef): string { + if (!planRef.qrPhase) throw new Error("No QR phase is active."); + return planRef.qrPhase; +} + function createEmptyQRFile(phase: string): QRFile { return { phase, @@ -43,7 +48,6 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { label: "Add QR item", description: "Add quality review item.", parameters: Type.Object({ - phase: Type.String(), scope: Type.String(), check: Type.String(), severity: Type.Optional( @@ -56,11 +60,12 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const qrPath = path.join(planRef.dir, `qr-${params.phase}.json`); + const phase = requirePhase(planRef); + const qrPath = path.join(planRef.dir, `qr-${phase}.json`); return withFileLock(qrPath, async () => { - const qr = await loadQR(planRef.dir!, params.phase); + const qr = await loadQR(planRef.dir!, phase); const r = addQRItem(qr, params); - await saveQR(r.qr, planRef.dir!, params.phase); + await saveQR(r.qr, planRef.dir!, phase); return { content: [{ type: "text" as const, text: `Added QR item ${r.id}` }], details: undefined, @@ -74,7 +79,6 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { label: "Update QR item", description: "Update QR item status or finding.", parameters: Type.Object({ - phase: Type.String(), id: Type.String(), status: Type.Optional( Type.Union([ @@ -95,11 +99,12 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const qrPath = path.join(planRef.dir, `qr-${params.phase}.json`); + const phase = requirePhase(planRef); + const qrPath = path.join(planRef.dir, `qr-${phase}.json`); return withFileLock(qrPath, async () => { - const qr = await loadQR(planRef.dir!, params.phase); + const qr = await loadQR(planRef.dir!, phase); const updated = setQRItem(qr, params.id, params); - await saveQR(updated, planRef.dir!, params.phase); + await saveQR(updated, planRef.dir!, phase); return { content: [{ type: "text" as const, text: `Updated QR item ${params.id}` }], details: undefined, @@ -113,17 +118,17 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { label: "Assign QR group", description: "Assign group ID to QR items.", parameters: Type.Object({ - phase: Type.String(), ids: Type.Array(Type.String()), group_id: Type.String(), }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const qrPath = path.join(planRef.dir, `qr-${params.phase}.json`); + const phase = requirePhase(planRef); + const qrPath = path.join(planRef.dir, `qr-${phase}.json`); return withFileLock(qrPath, async () => { - const qr = await loadQR(planRef.dir!, params.phase); + const qr = await loadQR(planRef.dir!, phase); const updated = assignGroup(qr, params.ids, params.group_id); - await saveQR(updated, planRef.dir!, params.phase); + await saveQR(updated, planRef.dir!, phase); return { content: [ { @@ -142,12 +147,12 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { label: "Get QR item", description: "Get QR item by ID.", parameters: Type.Object({ - phase: Type.String(), id: Type.String(), }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const qr = await loadQR(planRef.dir, params.phase); + const phase = requirePhase(planRef); + const qr = await loadQR(planRef.dir, phase); const item = qr.items.find((x) => x.id === params.id); if (!item) throw new Error(`QR item ${params.id} not found`); return { @@ -162,7 +167,6 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { label: "List QR items", description: "List QR items, optionally filtered by status.", parameters: Type.Object({ - phase: Type.String(), status: Type.Optional( Type.Union([ Type.Literal("TODO"), @@ -173,7 +177,8 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { }), async execute(_toolCallId, params) { if (!planRef.dir) throw new Error("No plan directory is active."); - const qr = await loadQR(planRef.dir, params.phase); + const phase = requirePhase(planRef); + const qr = await loadQR(planRef.dir, phase); const filtered = params.status ? qr.items.filter((item) => item.status === params.status) : qr.items; @@ -190,12 +195,11 @@ export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { name: "koan_qr_summary", label: "QR summary", description: "Get QR summary with counts by status and severity.", - parameters: Type.Object({ - phase: Type.String(), - }), - async execute(_toolCallId, params) { + parameters: Type.Object({}), + async execute() { if (!planRef.dir) throw new Error("No plan directory is active."); - const qr = await loadQR(planRef.dir, params.phase); + const phase = requirePhase(planRef); + const qr = await loadQR(planRef.dir, phase); const byStatus = { TODO: qr.items.filter((x) => x.status === "TODO").length, diff --git a/tests/qr-grouped-verify.test.ts b/tests/qr-grouped-verify.test.ts index 4a09ad5..23313cf 100644 --- a/tests/qr-grouped-verify.test.ts +++ b/tests/qr-grouped-verify.test.ts @@ -223,10 +223,9 @@ describe("buildAnalyzeStep", () => { describe("buildConfirmStep", () => { const item = makeItem("QR-007", "group-y"); - it("includes koan_qr_set_item instructions with correct phase and id", () => { + it("includes koan_qr_set_item instructions with correct id", () => { const step = buildConfirmStep(item, 0, 3, "plan-code"); const text = step.instructions.join("\n"); - assert.ok(text.includes("phase='plan-code'")); assert.ok(text.includes("id='QR-007'")); assert.ok(text.includes("status='PASS'")); assert.ok(text.includes("status='FAIL'")); From 1254962fe906b48856dbd0ae2516fd5231642350 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Mar 2026 12:44:45 +0700 Subject: [PATCH 041/412] feat(planner): add epic state model and role-tier config --- src/planner/conversation.ts | 23 +- src/planner/epic/state.ts | 199 ++++++++++++++++ src/planner/epic/types.ts | 56 +++++ src/planner/model-config.ts | 83 +++---- src/planner/model-phase.ts | 67 +----- src/planner/model-resolver.ts | 37 +-- src/planner/types.ts | 53 +++++ src/planner/ui/config/menu.ts | 11 +- src/planner/ui/config/model-selection.ts | 285 ++++------------------- src/utils/logger.ts | 27 ++- 10 files changed, 438 insertions(+), 403 deletions(-) create mode 100644 src/planner/epic/state.ts create mode 100644 src/planner/epic/types.ts create mode 100644 src/planner/types.ts diff --git a/src/planner/conversation.ts b/src/planner/conversation.ts index 86e9850..bc51285 100644 --- a/src/planner/conversation.ts +++ b/src/planner/conversation.ts @@ -1,25 +1,28 @@ -// Export the parent session conversation to a JSONL file in the plan directory. +// Export the parent session conversation to a JSONL file in the epic directory. // // The output is raw pi SessionManager entries — NOT a plain-text transcript. -// Each line is a JSON object. Agents reading this file should look for entries -// with type "message" (role: "user" | "assistant") for conversation content, -// and type "compaction" for synthesized summaries of earlier context. -// The file is write-once and read-only from the perspective of planning phases. +// Each line is a JSON-serialized session entry (header first, then branch entries). +// +// Agents reading this file should look for entries with type "message" and +// role "user" or "assistant" for conversation content. Entries with type +// "compaction" contain synthesized summaries of earlier context. Internal +// session management entries should be ignored. +// +// The file is write-once from the driver's perspective — planning phases read it. import { promises as fs } from "node:fs"; import * as path from "node:path"; import type { ExtensionContext } from "@mariozechner/pi-coding-agent"; -/** - * Export the current conversation branch as a JSONL file. - * Each line is a JSON-serialized session entry (header first, then branch entries). - */ +// Export the current conversation branch as a JSONL file. +// Returns the absolute path to the written file. export async function exportConversation( sessionManager: ExtensionContext["sessionManager"], planDir: string, ): Promise { const filePath = path.join(planDir, "conversation.jsonl"); + const header = sessionManager.getHeader(); const branch = sessionManager.getBranch(); @@ -27,6 +30,6 @@ export async function exportConversation( if (header) lines.push(JSON.stringify(header)); for (const entry of branch) lines.push(JSON.stringify(entry)); - await fs.writeFile(filePath, lines.join("\n") + "\n", "utf8"); + await fs.writeFile(filePath, `${lines.join("\n")}\n`, "utf8"); return filePath; } diff --git a/src/planner/epic/state.ts b/src/planner/epic/state.ts new file mode 100644 index 0000000..256b84c --- /dev/null +++ b/src/planner/epic/state.ts @@ -0,0 +1,199 @@ +// Epic and story state I/O — read/write JSON state files for driver routing. +// All JSON writes use atomic tmp+rename to prevent partial reads during concurrent access. +// Paths follow: ~/.koan/state/epics/{epic-id}/... +// +// The driver reads and writes .json files only — never .md files. This is the +// core invariant (AGENTS.md): LLMs read/write markdown; the driver reads/writes +// JSON; tool code bridges both. Putting writeStatusMarkdown here would violate the +// invariant boundary and make the module responsible for two communication channels. +// status.md writes belong exclusively in tools/orchestrator.ts. +// +// discoverStoryIds scans the filesystem instead of reading a driver-maintained +// list because the decomposer LLM writes story.md files using the Write tool — +// it has no reason to know the JSON state format, and requiring it to update +// epic-state.json would force an LLM to write JSON, violating the core invariant +// (§10.2). The driver discovers what the LLM created by scanning stories/*/story.md, +// then populates the JSON story list itself. + +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import { + createInitialEpicState, + createInitialStoryState, + type EpicInfo, + type EpicState, + type StoryState, +} from "./types.js"; + +export const KOAN_HOME = path.join(os.homedir(), ".koan"); +export const EPICS_HOME = path.join(KOAN_HOME, "state", "epics"); + +// --------------------------------------------------------------------------- +// Path helpers +// --------------------------------------------------------------------------- + +function epicStatePath(epicDir: string): string { + return path.join(epicDir, "epic-state.json"); +} + +function storyStatePath(epicDir: string, storyId: string): string { + return path.join(epicDir, "stories", storyId, "state.json"); +} + +// --------------------------------------------------------------------------- +// Atomic JSON write +// --------------------------------------------------------------------------- + +// Writes to a .tmp file first, then renames — preventing partial reads. +async function atomicWriteJson(filePath: string, value: unknown): Promise { + const tmpPath = `${filePath}.tmp`; + await fs.writeFile(tmpPath, `${JSON.stringify(value, null, 2)}\n`, "utf8"); + await fs.rename(tmpPath, filePath); +} + +// --------------------------------------------------------------------------- +// ID generation +// --------------------------------------------------------------------------- + +function slugify(input: string): string { + const base = input + .toLowerCase() + .replace(/[^a-z0-9]+/g, "-") + .replace(/^-+|-+$/g, "") + .slice(0, 48); + return base.length > 0 ? base : "epic"; +} + +export function generateEpicId(description: string, now: Date): string { + const timestamp = now.toISOString().replace(/[-:]/g, "").replace(/\..+/, ""); + const slug = slugify(description); + return `${timestamp}-${slug}`; +} + +async function ensureEpicDirectoryUnique(baseId: string): Promise<{ id: string; directory: string }> { + let suffix = 0; + while (true) { + const candidateId = suffix === 0 ? baseId : `${baseId}-${suffix}`; + const directory = path.join(EPICS_HOME, candidateId); + try { + await fs.mkdir(directory, { recursive: false }); + return { id: candidateId, directory }; + } catch (error) { + const err = error as NodeJS.ErrnoException; + if (err.code === "EEXIST") { + suffix += 1; + continue; + } + throw error; + } + } +} + +// --------------------------------------------------------------------------- +// Epic directory creation +// --------------------------------------------------------------------------- + +// Creates the epic directory with standard subdirectories. +// Creates only 'stories/' and 'subagents/' — no 'scouts/' directory. +// Scout output lives in per-scout subagent directories under subagents/. +export async function createEpicDirectory(description: string, _cwd: string, now = new Date()): Promise { + await fs.mkdir(EPICS_HOME, { recursive: true }); + + const baseId = generateEpicId(description, now); + const { id, directory } = await ensureEpicDirectoryUnique(baseId); + + await Promise.all([ + fs.mkdir(path.join(directory, "stories"), { recursive: true }), + fs.mkdir(path.join(directory, "subagents"), { recursive: true }), + ]); + + const epicState = createInitialEpicState(id); + await atomicWriteJson(epicStatePath(directory), epicState); + + return { id, directory, createdAt: epicState.createdAt }; +} + +// --------------------------------------------------------------------------- +// Epic state I/O +// --------------------------------------------------------------------------- + +export async function loadEpicState(epicDir: string): Promise { + const raw = await fs.readFile(epicStatePath(epicDir), "utf8"); + return JSON.parse(raw) as EpicState; +} + +export async function saveEpicState(epicDir: string, state: EpicState): Promise { + await atomicWriteJson(epicStatePath(epicDir), state); +} + +// --------------------------------------------------------------------------- +// Story state I/O +// --------------------------------------------------------------------------- + +export async function loadStoryState(epicDir: string, storyId: string): Promise { + const raw = await fs.readFile(storyStatePath(epicDir, storyId), "utf8"); + return JSON.parse(raw) as StoryState; +} + +export async function saveStoryState(epicDir: string, storyId: string, state: StoryState): Promise { + await atomicWriteJson(storyStatePath(epicDir, storyId), state); +} + +export async function loadAllStoryStates(epicDir: string): Promise { + const epicState = await loadEpicState(epicDir); + return Promise.all(epicState.stories.map((id) => loadStoryState(epicDir, id))); +} + +// --------------------------------------------------------------------------- +// Directory provisioning +// --------------------------------------------------------------------------- + +// Ensures the story directory and plan subdirectory exist, and that state.json +// is initialized if not already present. +export async function ensureStoryDirectory(epicDir: string, storyId: string): Promise { + const storyDir = path.join(epicDir, "stories", storyId); + await fs.mkdir(path.join(storyDir, "plan"), { recursive: true }); + + const statePath = storyStatePath(epicDir, storyId); + try { + await fs.access(statePath); + } catch { + const initialState = createInitialStoryState(storyId); + await atomicWriteJson(statePath, initialState); + } + + return storyDir; +} + +// Ensures a uniquely labeled subagent directory exists under {epicDir}/subagents/. +// The label should be descriptive (e.g., "intake-20260313T105232" or "scout-task1-1741830752000"). +export async function ensureSubagentDirectory(epicDir: string, label: string): Promise { + const subagentDir = path.join(epicDir, "subagents", label); + await fs.mkdir(subagentDir, { recursive: true }); + return subagentDir; +} + +// --------------------------------------------------------------------------- +// Story discovery +// --------------------------------------------------------------------------- + +// Scans {epicDir}/stories/ for subdirectories and returns their names sorted. +// This is the authoritative discovery mechanism after decomposition. +// The driver calls this after the decomposer LLM creates stories/*/story.md files. +// Never reads epic-state.json.stories — that list is populated by the driver AFTER +// discovery, not by the LLM. +export async function discoverStoryIds(epicDir: string): Promise { + const storiesDir = path.join(epicDir, "stories"); + try { + const entries = await fs.readdir(storiesDir, { withFileTypes: true }); + return entries + .filter((e) => e.isDirectory()) + .map((e) => e.name) + .sort(); + } catch (err: unknown) { + if ((err as NodeJS.ErrnoException).code === "ENOENT") return []; + throw err; + } +} diff --git a/src/planner/epic/types.ts b/src/planner/epic/types.ts new file mode 100644 index 0000000..17f93de --- /dev/null +++ b/src/planner/epic/types.ts @@ -0,0 +1,56 @@ +// Epic and story state types — JSON structures for driver consumption. +// Persisted as .json files under ~/.koan/state/epics/{epic-id}/. +// Per AGENTS.md invariant: LLMs write markdown only; driver reads JSON only. +// LLMs never read these files directly — they read the corresponding .md files. + +import type { EpicPhase, StoryStatus } from "../types.js"; + +// Persisted at {epic-dir}/epic-state.json +export interface EpicState { + epicId: string; + createdAt: string; + phase: EpicPhase; + stories: string[]; // Story IDs in declaration order +} + +// Persisted at {epic-dir}/stories/{story-id}/state.json +// Note: no `escalation` field — escalation is handled via koan_ask_question, +// not a separate status or state field. +export interface StoryState { + storyId: string; + status: StoryStatus; + updatedAt: string; + retryCount: number; + maxRetries: number; + failureSummary?: string; // Set by koan_retry_story; used as retry context for executor + skipReason?: string; // Set by koan_skip_story or driver on budget exhaustion +} + +// Metadata about an epic directory — returned by createEpicDirectory. +export interface EpicInfo { + id: string; + directory: string; + createdAt: string; +} + +// Default retry budget per story. +export const DEFAULT_MAX_RETRIES = 2; + +export function createInitialStoryState(storyId: string, maxRetries = DEFAULT_MAX_RETRIES): StoryState { + return { + storyId, + status: "pending", + updatedAt: new Date().toISOString(), + retryCount: 0, + maxRetries, + }; +} + +export function createInitialEpicState(epicId: string, stories: string[] = []): EpicState { + return { + epicId, + createdAt: new Date().toISOString(), + phase: "intake", + stories, + }; +} diff --git a/src/planner/model-config.ts b/src/planner/model-config.ts index 0f007cc..80d968a 100644 --- a/src/planner/model-config.ts +++ b/src/planner/model-config.ts @@ -1,29 +1,30 @@ -// Koan config persistence for per-phase model overrides. -// Storage location: ~/.koan/config.json under a `phaseModels` key. -// Enforces all-or-none semantics: a stored config must contain exactly all -// 20 PhaseModelKeys. Partial configs are treated as absent and logged. +// Koan config persistence for role-based model tier overrides. +// Storage location: ~/.koan/config.json under a `modelTiers` key. +// All 3 tiers (strong, standard, cheap) must be present when a config exists. +// Partial configs are treated as absent and logged. import { promises as fs } from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; -import { - ALL_PHASE_MODEL_KEYS, - isPhaseModelKey, - type PhaseModelKey, -} from "./model-phase.js"; +import { ALL_MODEL_TIERS, isModelTier, type ModelTier } from "./model-phase.js"; +import { createLogger } from "../utils/logger.js"; -export const KOAN_CONFIG_PATH = path.join(os.homedir(), ".koan", "config.json"); +const log = createLogger("model-config"); + +export const CONFIG_PATH = path.join(os.homedir(), ".koan", "config.json"); + +export type ModelTierConfig = Record; interface KoanConfigFile { - phaseModels?: Record; + modelTiers?: Record; [key: string]: unknown; } -export async function loadPhaseModelConfig(): Promise | null> { +export async function loadModelTierConfig(): Promise { let raw: string; try { - raw = await fs.readFile(KOAN_CONFIG_PATH, "utf8"); + raw = await fs.readFile(CONFIG_PATH, "utf8"); } catch { return null; } @@ -32,71 +33,61 @@ export async function loadPhaseModelConfig(): Promise> = {}; - for (const key of keys) { - if (!isPhaseModelKey(key)) { - console.warn(`[koan] config.json phaseModels contains unknown key "${key}"; treating as absent.`); + const result: Partial = {}; + for (const tier of ALL_MODEL_TIERS) { + if (!(tier in modelTiers)) { + log(`config.json modelTiers is missing key "${tier}"; treating as absent.`); return null; } - const value = phaseModels[key]; + const value = modelTiers[tier]; if (typeof value !== "string" || value.length === 0) { - console.warn( - `[koan] config.json phaseModels["${key}"] is not a non-empty string; treating as absent.`, - ); + log(`config.json modelTiers["${tier}"] is not a non-empty string; treating as absent.`); return null; } - result[key] = value; + result[tier] = value; } - for (const expected of ALL_PHASE_MODEL_KEYS) { - if (!(expected in result)) { - console.warn(`[koan] config.json phaseModels is missing key "${expected}"; treating as absent.`); + for (const key of keys) { + if (!isModelTier(key)) { + log(`config.json modelTiers contains unknown key "${key}"; treating as absent.`); return null; } } - return result as Record; + return result as ModelTierConfig; } -export async function savePhaseModelConfig( - config: Record | null, -): Promise { - const configDir = path.dirname(KOAN_CONFIG_PATH); +export async function saveModelTierConfig(config: ModelTierConfig): Promise { + const configDir = path.dirname(CONFIG_PATH); await fs.mkdir(configDir, { recursive: true }); let existing: KoanConfigFile = {}; try { - const raw = await fs.readFile(KOAN_CONFIG_PATH, "utf8"); + const raw = await fs.readFile(CONFIG_PATH, "utf8"); existing = JSON.parse(raw) as KoanConfigFile; } catch { // Start fresh if file is missing or contains invalid JSON. } - if (config === null) { - delete existing.phaseModels; - } else { - existing.phaseModels = config as Record; - } + existing.modelTiers = config as Record; - const tmpPath = `${KOAN_CONFIG_PATH}.tmp`; + const tmpPath = `${CONFIG_PATH}.tmp`; await fs.writeFile(tmpPath, `${JSON.stringify(existing, null, 2)}\n`, "utf8"); - await fs.rename(tmpPath, KOAN_CONFIG_PATH); + await fs.rename(tmpPath, CONFIG_PATH); } diff --git a/src/planner/model-phase.ts b/src/planner/model-phase.ts index b2319ca..0bd642c 100644 --- a/src/planner/model-phase.ts +++ b/src/planner/model-phase.ts @@ -1,63 +1,14 @@ -// Canonical phase-model key definitions for koan per-phase model selection. -// Defines the 5×4 matrix of (phase row × sub-phase column) keys used across -// configuration, UI, and spawn-time resolution. +// Role-based model tier types for koan. +// Replaces the old 5×4 PhaseRow × SubPhase matrix with a 3-tier system. +// Tiers map deterministically from role via ROLE_MODEL_TIER in types.ts. -export type PhaseRow = "plan-design" | "plan-code" | "plan-docs" | "exec-code" | "exec-docs"; -export type SubPhase = "exec-debut" | "exec-fix" | "qr-decompose" | "qr-verify"; -export type PhaseModelKey = `${PhaseRow}-${SubPhase}`; +import type { ModelTier } from "./types.js"; -export const PHASE_ROWS: readonly PhaseRow[] = [ - "plan-design", - "plan-code", - "plan-docs", - "exec-code", - "exec-docs", -]; +export type { ModelTier, SubagentRole } from "./types.js"; +export { ROLE_MODEL_TIER } from "./types.js"; -export const SUB_PHASES: readonly SubPhase[] = [ - "exec-debut", - "exec-fix", - "qr-decompose", - "qr-verify", -]; +export const ALL_MODEL_TIERS: readonly ModelTier[] = ["strong", "standard", "cheap"]; -function computeAllKeys(): PhaseModelKey[] { - const keys: PhaseModelKey[] = []; - for (const row of PHASE_ROWS) { - for (const col of SUB_PHASES) { - keys.push(`${row}-${col}`); - } - } - return keys; -} - -export const ALL_PHASE_MODEL_KEYS: readonly PhaseModelKey[] = computeAllKeys(); - -const STRONG_KEY_SET: Set = new Set([ - // All qr-decompose keys (bias reasoning budget to verification) - "plan-design-qr-decompose", - "plan-code-qr-decompose", - "plan-docs-qr-decompose", - "exec-code-qr-decompose", - "exec-docs-qr-decompose", - // plan-design exec keys (ripple effects across later work) - "plan-design-exec-debut", - "plan-design-exec-fix", - // exec-docs exec keys (no mechanical correctness backstop) - "exec-docs-exec-debut", - "exec-docs-exec-fix", -]); - -export const STRONG_PHASE_MODEL_KEYS: ReadonlySet = STRONG_KEY_SET; - -export const GENERAL_PURPOSE_PHASE_MODEL_KEYS: readonly PhaseModelKey[] = - ALL_PHASE_MODEL_KEYS.filter((k) => !STRONG_KEY_SET.has(k)); - -export function isPhaseModelKey(value: unknown): value is PhaseModelKey { - if (typeof value !== "string") return false; - return (ALL_PHASE_MODEL_KEYS as readonly string[]).includes(value); -} - -export function buildPhaseModelKey(phaseRow: PhaseRow, subPhase: SubPhase): PhaseModelKey { - return `${phaseRow}-${subPhase}`; +export function isModelTier(value: unknown): value is ModelTier { + return typeof value === "string" && ALL_MODEL_TIERS.includes(value as ModelTier); } diff --git a/src/planner/model-resolver.ts b/src/planner/model-resolver.ts index b67b371..bc4e530 100644 --- a/src/planner/model-resolver.ts +++ b/src/planner/model-resolver.ts @@ -1,33 +1,14 @@ -// Spawn-time model resolver for per-phase model overrides. -// Maps spawn contexts to PhaseModelKeys and looks up configured overrides. -// Returns undefined when no config exists so the caller omits --model entirely, +// Spawn-time model resolver for role-based model overrides. +// Maps SubagentRole → ModelTier → configured model string. +// Returns undefined when no config exists so the caller omits --model, // preserving pi's current active model as the implicit fallback. -import { buildPhaseModelKey, type PhaseModelKey, type PhaseRow } from "./model-phase.js"; -import { loadPhaseModelConfig } from "./model-config.js"; +import { ROLE_MODEL_TIER, type SubagentRole } from "./model-phase.js"; +import { loadModelTierConfig } from "./model-config.js"; -export type SpawnContext = "work-debut" | "fix" | "qr-decompose" | "qr-verify"; - -export function mapSpawnContextToPhaseModelKey( - context: SpawnContext, - phaseRow: PhaseRow, - // Reserved for future fix-phase-specific routing. Current mapping is phase-row + context only. - _fixPhase?: string, -): PhaseModelKey { - switch (context) { - case "work-debut": - return buildPhaseModelKey(phaseRow, "exec-debut"); - case "fix": - return buildPhaseModelKey(phaseRow, "exec-fix"); - case "qr-decompose": - return buildPhaseModelKey(phaseRow, "qr-decompose"); - case "qr-verify": - return buildPhaseModelKey(phaseRow, "qr-verify"); - } -} - -export async function resolvePhaseModelOverride(key: PhaseModelKey): Promise { - const config = await loadPhaseModelConfig(); +export async function resolveModelForRole(role: SubagentRole): Promise { + const config = await loadModelTierConfig(); if (config === null) return undefined; - return config[key]; + const tier = ROLE_MODEL_TIER[role]; + return config[tier]; } diff --git a/src/planner/types.ts b/src/planner/types.ts new file mode 100644 index 0000000..c2c0a5a --- /dev/null +++ b/src/planner/types.ts @@ -0,0 +1,53 @@ +// Core types for the koan epic/story orchestrator. +// Shared across driver, phases, tools, and spawn infrastructure. + +// No `escalated` status: escalation is asking a question (§11.3.1). The orchestrator +// calls `koan_ask_question` when it needs human input, then decides via retry/skip. +// A separate status created a dead routing path — the driver had nowhere clean to +// send it without duplicating the ask UI flow that IPC already handles. +// +// No `scouting` EpicPhase: scouts are spawned inside the IPC responder during +// intake/decomposer/planner phases, not as a top-level driver phase. Adding +// "scouting" to EpicPhase would imply a driver state that never exists (§12.2.2). +// If a top-level scouting phase is added later, re-add the value then. +// +// StepSequence exists for the orchestrator, which has two distinct step counts +// depending on where in the story lifecycle it runs: pre-execution (2 steps: +// dependency analysis + select) vs post-execution (4 steps: verify + verdict + +// propagate + select next). A single OrchestratorPhase class reads this value +// in begin() to configure its total steps and guidance functions (§9.1). + +// Subagent roles — the six LLM roles in the pipeline. +export type SubagentRole = "intake" | "scout" | "decomposer" | "orchestrator" | "planner" | "executor"; + +// Model tiers — maps to three capability levels. +export type ModelTier = "strong" | "standard" | "cheap"; + +// Role → model tier mapping. Scouts use cheap models; execution roles use standard. +export const ROLE_MODEL_TIER: Record = { + intake: "strong", + scout: "cheap", + decomposer: "strong", + orchestrator: "strong", + planner: "strong", + executor: "standard", +}; + +// Orchestrator step sequences — configures step count and guidance at spawn time. +export type StepSequence = "pre-execution" | "post-execution"; + +// Story lifecycle states. Driver manages intermediate transitions; orchestrator tools +// drive the routing transitions via koan_* tool calls. +export type StoryStatus = + | "pending" // Initial state: not yet selected + | "selected" // Orchestrator selected this story via koan_select_story + | "planning" // Driver-internal: planner subagent is running + | "executing" // Driver-internal: executor subagent is running + | "verifying" // Driver-internal: post-execution orchestrator is running + | "done" // Orchestrator verdict: story completed successfully + | "retry" // Orchestrator verdict: re-execute with failure context + | "skipped"; // Orchestrator or driver: story bypassed (budget exhaustion or explicit skip) + +// Epic lifecycle phases (driver-managed, not LLM-visible directly). +// Note: "scouting" is intentionally absent — scouts run within other phases via IPC. +export type EpicPhase = "intake" | "decomposition" | "review" | "executing" | "completed"; diff --git a/src/planner/ui/config/menu.ts b/src/planner/ui/config/menu.ts index de11954..e50f517 100644 --- a/src/planner/ui/config/menu.ts +++ b/src/planner/ui/config/menu.ts @@ -6,13 +6,14 @@ import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent"; import { getSettingsListTheme } from "@mariozechner/pi-coding-agent"; import { type SettingItem, SettingsList } from "@mariozechner/pi-tui"; -import { ALL_PHASE_MODEL_KEYS, type PhaseModelKey } from "../../model-phase.js"; -import { loadPhaseModelConfig } from "../../model-config.js"; +import { ALL_MODEL_TIERS, type ModelTier } from "../../model-phase.js"; +import { loadModelTierConfig } from "../../model-config.js"; +import type { ModelTierConfig } from "../../model-config.js"; import { createModelSelectionComponent } from "./model-selection.js"; -function configSummary(config: Record | null): string { +function configSummary(config: ModelTierConfig | null): string { if (config === null) return "inheriting active model"; - return `${ALL_PHASE_MODEL_KEYS.length} keys configured`; + return `${ALL_MODEL_TIERS.length} tiers configured`; } export async function openKoanConfig(ctx: ExtensionCommandContext): Promise { @@ -22,7 +23,7 @@ export async function openKoanConfig(ctx: ExtensionCommandContext): Promise(async (tui, theme, _keybindings, done) => { - const initialConfig = await loadPhaseModelConfig(); + const initialConfig = await loadModelTierConfig(); let currentConfig = initialConfig; const activeModelId = ctx.model diff --git a/src/planner/ui/config/model-selection.ts b/src/planner/ui/config/model-selection.ts index e551b3a..ee2a695 100644 --- a/src/planner/ui/config/model-selection.ts +++ b/src/planner/ui/config/model-selection.ts @@ -1,6 +1,6 @@ -// Model selection matrix UI for /koan config. -// Renders quick-set actions plus a true 5×4 matrix (phase rows × sub-phase columns). -// Enter opens an inline ModelSelectorComponent for the selected quick-set/cell. +// Model selection UI for /koan config. +// Renders a 3-row tier table (strong / standard / cheap). +// Enter opens an inline ModelSelectorComponent for the selected tier. // Uses SettingsManager.inMemory() to prevent global default model mutation. import { ModelSelectorComponent, SettingsManager } from "@mariozechner/pi-coding-agent"; @@ -14,97 +14,21 @@ import { visibleWidth, } from "@mariozechner/pi-tui"; -import { - ALL_PHASE_MODEL_KEYS, - GENERAL_PURPOSE_PHASE_MODEL_KEYS, - PHASE_ROWS, - STRONG_PHASE_MODEL_KEYS, - SUB_PHASES, - buildPhaseModelKey, - type PhaseModelKey, - type PhaseRow, -} from "../../model-phase.js"; -import { savePhaseModelConfig } from "../../model-config.js"; - -// -- Pure quick-set utilities (exported for testing) -- - -export function initConfigFromActiveModel(activeModelId: string): Record { - const config: Partial> = {}; - for (const key of ALL_PHASE_MODEL_KEYS) { - config[key] = activeModelId; - } - return config as Record; -} - -export function applyStrongModel( - model: string, - existingConfig: Record | null, - activeModelId: string, -): Record { - const base = existingConfig ?? initConfigFromActiveModel(activeModelId); - const result = { ...base }; - for (const key of STRONG_PHASE_MODEL_KEYS) { - result[key] = model; - } - return result; -} - -export function applyGeneralPurposeModel( - model: string, - existingConfig: Record | null, - activeModelId: string, -): Record { - const base = existingConfig ?? initConfigFromActiveModel(activeModelId); - const result = { ...base }; - for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { - result[key] = model; - } - return result; -} - -// -- Confirmation component for reset action -- - -class ResetConfirmComponent implements Component { - constructor( - private readonly theme: Theme, - private readonly onConfirm: () => void, - private readonly onCancel: () => void, - ) {} - - render(_width: number): string[] { - return [ - this.theme.bold(this.theme.fg("accent", "Reset all model overrides to active model?")), - "", - this.theme.fg("muted", " This will set all 20 phase model cells to the current active model."), - "", - this.theme.fg("dim", " Enter to confirm · Escape to cancel"), - ]; - } - - handleInput(data: string): void { - if (data === "\r" || data === "\n") { - this.onConfirm(); - } else if (data === "\x1b") { - this.onCancel(); - } - } - - invalidate(): void {} -} +import { ALL_MODEL_TIERS, type ModelTier } from "../../model-phase.js"; +import { saveModelTierConfig } from "../../model-config.js"; +import type { ModelTierConfig } from "../../model-config.js"; function padRight(text: string, width: number): string { const padding = Math.max(0, width - visibleWidth(text)); return text + " ".repeat(padding); } -function renderCell(theme: Theme, text: string, width: number, selected: boolean, strong: boolean): string { +function renderCell(theme: Theme, text: string, width: number, selected: boolean): string { const innerWidth = Math.max(1, width - 2); const clipped = truncateToWidth(text, innerWidth, ""); const padded = padRight(clipped, innerWidth); const raw = ` ${padded} `; - if (selected) return theme.inverse(raw); - if (strong) return theme.fg("accent", raw); return raw; } @@ -115,43 +39,30 @@ function cellDisplay(modelId: string | undefined, activeModelId: string | undefi return modelId; } -type SelectionZone = "quick" | "grid"; - -// -- Create model selection component -- - export function createModelSelectionComponent( tui: TUI, theme: Theme, modelRegistry: ModelRegistry, activeModelId: string | undefined, - initialConfig: Record | null, - onConfigChange: (newConfig: Record | null) => void, + initialConfig: ModelTierConfig | null, + onConfigChange: (newConfig: ModelTierConfig | null) => void, onSaveError: (error: unknown) => void, onClose: () => void, ): Component { const fallbackActive = activeModelId ?? "(active model)"; - const configRef: { value: Record | null } = { value: initialConfig }; + const configRef: { value: ModelTierConfig | null } = { value: initialConfig }; - const quickItems = [ - "Reset to active", - `Set strong (${STRONG_PHASE_MODEL_KEYS.size})`, - `Set general (${GENERAL_PURPOSE_PHASE_MODEL_KEYS.length})`, - ] as const; - - let zone: SelectionZone = "quick"; - let quickIndex = 0; let rowIndex = 0; - let colIndex = 0; let overlay: Component | null = null; function requestRender(): void { tui.requestRender(); } - async function persistAndNotify(newConfig: Record | null): Promise { + async function persistAndNotify(newConfig: ModelTierConfig | null): Promise { const previous = configRef.value; try { - await savePhaseModelConfig(newConfig); + await saveModelTierConfig(newConfig as ModelTierConfig); configRef.value = newConfig; onConfigChange(newConfig); return true; @@ -190,41 +101,19 @@ export function createModelSelectionComponent( requestRender(); } - function openResetConfirm(): void { - overlay = new ResetConfirmComponent( - theme, - () => { - const resetConfig = initConfigFromActiveModel(fallbackActive); - void persistAndNotify(resetConfig).finally(() => closeOverlay()); - }, - () => closeOverlay(), - ); - requestRender(); - } - - function openStrongSelector(): void { - const strongSample = Array.from(STRONG_PHASE_MODEL_KEYS)[0]; - const currentId = configRef.value?.[strongSample]; - - overlay = makeModelSelector( - currentId, - (modelId) => { - const newConfig = applyStrongModel(modelId, configRef.value, fallbackActive); - void persistAndNotify(newConfig).finally(() => closeOverlay()); - }, - () => closeOverlay(), - ); - requestRender(); - } - - function openGeneralSelector(): void { - const gpSample = GENERAL_PURPOSE_PHASE_MODEL_KEYS[0]; - const currentId = configRef.value?.[gpSample]; + function openTierSelector(): void { + const tier = ALL_MODEL_TIERS[rowIndex] as ModelTier; + const currentId = configRef.value?.[tier]; overlay = makeModelSelector( currentId, (modelId) => { - const newConfig = applyGeneralPurposeModel(modelId, configRef.value, fallbackActive); + const base: ModelTierConfig = configRef.value ?? { + strong: fallbackActive, + standard: fallbackActive, + cheap: fallbackActive, + }; + const newConfig: ModelTierConfig = { ...base, [tier]: modelId }; void persistAndNotify(newConfig).finally(() => closeOverlay()); }, () => closeOverlay(), @@ -232,79 +121,12 @@ export function createModelSelectionComponent( requestRender(); } - function openCellSelector(): void { - const row = PHASE_ROWS[rowIndex] as PhaseRow; - const subPhase = SUB_PHASES[colIndex]; - const key = buildPhaseModelKey(row, subPhase); - const currentId = configRef.value?.[key]; - - overlay = makeModelSelector( - currentId, - (modelId) => { - const base = configRef.value ?? initConfigFromActiveModel(fallbackActive); - const newConfig = { ...base, [key]: modelId }; - void persistAndNotify(newConfig).finally(() => closeOverlay()); - }, - () => closeOverlay(), - ); - requestRender(); - } - - function activateSelection(): void { - if (zone === "quick") { - if (quickIndex === 0) { - openResetConfirm(); - } else if (quickIndex === 1) { - openStrongSelector(); - } else { - openGeneralSelector(); - } - return; - } - - openCellSelector(); - } - function moveUp(): void { - if (zone === "quick") return; - if (rowIndex === 0) { - zone = "quick"; - return; - } - rowIndex -= 1; + if (rowIndex > 0) rowIndex -= 1; } function moveDown(): void { - if (zone === "quick") { - zone = "grid"; - rowIndex = 0; - return; - } - - if (rowIndex === PHASE_ROWS.length - 1) { - rowIndex = 0; - return; - } - - rowIndex += 1; - } - - function moveLeft(): void { - if (zone === "quick") { - quickIndex = quickIndex === 0 ? quickItems.length - 1 : quickIndex - 1; - return; - } - - colIndex = colIndex === 0 ? SUB_PHASES.length - 1 : colIndex - 1; - } - - function moveRight(): void { - if (zone === "quick") { - quickIndex = quickIndex === quickItems.length - 1 ? 0 : quickIndex + 1; - return; - } - - colIndex = colIndex === SUB_PHASES.length - 1 ? 0 : colIndex + 1; + if (rowIndex < ALL_MODEL_TIERS.length - 1) rowIndex += 1; } function renderMain(width: number): string[] { @@ -314,50 +136,33 @@ export function createModelSelectionComponent( lines.push(theme.fg("muted", `Fallback active model: ${fallbackActive}`)); lines.push(""); - const quick = quickItems - .map((label, i) => { - const block = ` ${label} `; - if (zone === "quick" && quickIndex === i) return theme.inverse(block); - return theme.fg("muted", block); - }) - .join(" "); - - lines.push(`Quick-set: ${quick}`); - lines.push(""); - + const tierColWidth = 12; const sep = " | "; const sepWidth = visibleWidth(sep); - const phaseColWidth = 12; - const available = Math.max(24, width - phaseColWidth - sepWidth * 4); - const modelColWidth = Math.max(12, Math.floor(available / 4)); + const modelColWidth = Math.max(20, width - tierColWidth - sepWidth); const headerCells = [ - renderCell(theme, "phase", phaseColWidth, false, false), - ...SUB_PHASES.map((sub) => renderCell(theme, sub, modelColWidth, false, false)), + renderCell(theme, "tier", tierColWidth, false), + renderCell(theme, "model", modelColWidth, false), ]; lines.push(headerCells.join(sep)); lines.push("-".repeat(Math.max(10, Math.min(width, visibleWidth(headerCells.join(sep)))))); - for (let r = 0; r < PHASE_ROWS.length; r += 1) { - const row = PHASE_ROWS[r] as PhaseRow; - const rowCells: string[] = [renderCell(theme, row, phaseColWidth, false, false)]; - - for (let c = 0; c < SUB_PHASES.length; c += 1) { - const sub = SUB_PHASES[c]; - const key = buildPhaseModelKey(row, sub); - const model = configRef.value?.[key]; - const display = cellDisplay(model, activeModelId); - const selected = zone === "grid" && rowIndex === r && colIndex === c; - const strong = STRONG_PHASE_MODEL_KEYS.has(key); - rowCells.push(renderCell(theme, display, modelColWidth, selected, strong)); - } - - lines.push(truncateToWidth(rowCells.join(sep), width)); + for (let r = 0; r < ALL_MODEL_TIERS.length; r += 1) { + const tier = ALL_MODEL_TIERS[r] as ModelTier; + const model = configRef.value?.[tier]; + const display = cellDisplay(model, activeModelId); + const selected = rowIndex === r; + + const row = [ + renderCell(theme, tier, tierColWidth, false), + renderCell(theme, display, modelColWidth, selected), + ]; + lines.push(truncateToWidth(row.join(sep), width)); } lines.push(""); - lines.push(theme.fg("dim", "★ strong cell")); - lines.push(theme.fg("dim", "↑↓ move row/section · ←→ move column/quick-set · Enter select · Esc back")); + lines.push(theme.fg("dim", "↑↓ move row · Enter select model · Esc back")); return lines; } @@ -380,7 +185,7 @@ export function createModelSelectionComponent( return; } if (kb.matches(data, "selectConfirm") || data === " ") { - activateSelection(); + openTierSelector(); return; } if (kb.matches(data, "selectUp")) { @@ -391,16 +196,6 @@ export function createModelSelectionComponent( if (kb.matches(data, "selectDown")) { moveDown(); requestRender(); - return; - } - if (kb.matches(data, "cursorLeft")) { - moveLeft(); - requestRender(); - return; - } - if (kb.matches(data, "cursorRight")) { - moveRight(); - requestRender(); } }, invalidate: () => { diff --git a/src/utils/logger.ts b/src/utils/logger.ts index c8ced16..f95e589 100644 --- a/src/utils/logger.ts +++ b/src/utils/logger.ts @@ -1,36 +1,41 @@ -// Debug logger for koan internals. Writes to a log file when a plan -// directory is available; silent otherwise. The Pi TUI captures both -// stdout and stderr, so neither can be used for debug output. +// Debug logger for koan internals. Writes to a log file in the plan directory +// when a log directory has been configured; silent otherwise. +// The Pi TUI captures both stdout and stderr, so neither can be used for debug output. import { appendFileSync, mkdirSync } from "node:fs"; import * as path from "node:path"; -const prefix = "[koan]"; - export type Logger = | undefined>(message: string, details?: T) => void; +const PREFIX = "[koan]"; + let logPath: string | null = null; +// Configure the log file location. Call once after the epic directory is created. +// Subsequent createLogger() calls will write to {planDir}/koan.log. export function setLogDir(planDir: string): void { logPath = path.join(planDir, "koan.log"); try { mkdirSync(path.dirname(logPath), { recursive: true }); } catch { - // best effort + // Best effort — directory may already exist. } } +// Create a scoped logger. Returns a function that appends to the configured +// log file. Silent if setLogDir() has not been called. export function createLogger(scope: string): Logger { - const label = `${prefix} ${scope}`; + const label = `${PREFIX} ${scope}`; return (message, details) => { if (!logPath) return; - const suffix = details && Object.keys(details).length > 0 - ? ` ${JSON.stringify(details)}` - : ""; + const suffix = + details !== undefined && Object.keys(details).length > 0 + ? ` ${JSON.stringify(details)}` + : ""; try { appendFileSync(logPath, `${new Date().toISOString()} ${label}: ${message}${suffix}\n`); } catch { - // best effort -- plan dir may not exist yet + // Best effort — log file may not be writable yet. } }; } From 8983f371d9c58833d66bb9b3ed0a8bfd44c9785e Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Mar 2026 12:45:05 +0700 Subject: [PATCH 042/412] feat(planner): add runtime context and IPC-driven tool infra --- src/planner/lib/audit.ts | 92 ++------- src/planner/lib/ipc-responder.ts | 201 +++++++++++++++++++ src/planner/lib/ipc.ts | 93 ++++++--- src/planner/lib/permissions.ts | 299 ++++++++++++----------------- src/planner/lib/pool.ts | 12 +- src/planner/lib/runtime-context.ts | 20 ++ src/planner/lib/step.ts | 15 +- src/planner/tools/ask.ts | 169 +++++++++++++--- src/planner/tools/workflow.ts | 28 ++- 9 files changed, 585 insertions(+), 344 deletions(-) create mode 100644 src/planner/lib/ipc-responder.ts create mode 100644 src/planner/lib/runtime-context.ts diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index 12191ca..992ecab 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -133,7 +133,7 @@ export function summarize(e: ToolEvent): string { } } -// Pure projection update -- one case per discriminated kind. +// Pure projection update — one case per discriminated kind. // All branches update updatedAt and increment eventCount. export function fold(s: Projection, e: AuditEvent): Projection { const base = { ...s, updatedAt: e.ts, eventCount: s.eventCount + 1 }; @@ -232,7 +232,7 @@ export class EventLog { private projection: Projection; private heartbeat: ReturnType | null = null; // Serializes append() calls. Heartbeat timer and tool_result handler - // both call append() concurrently -- without serialization, two + // both call append() concurrently — without serialization, two // writeState() calls race on the shared tmp file (ENOENT on rename). private pending: Promise = Promise.resolve(); @@ -336,7 +336,7 @@ export class EventLog { // -- Exports -- // Reads state.json as a Projection; returns null if missing or malformed. -// Used by session.ts parent polling loop. +// Used by driver polling loop. export async function readProjection(dir: string): Promise { try { const raw = await fs.readFile(path.join(dir, "state.json"), "utf8"); @@ -364,90 +364,20 @@ interface ToolShape { } const PREVIEW_CHARS = 40; -const KEY_PRIORITY = ["id", "milestone", "decision_ref", "intent_ref", "file", "path", "phase"]; +const KEY_PRIORITY = ["id", "story_id", "milestone", "decision_ref", "intent_ref", "file", "path", "phase"]; +// Tool shapes for koan_* tools. No koan_escalate (eliminated in §11.3.1). const KOAN_SHAPES: Record = { - koan_get_plan: { keys: ["phase"], getter: true }, - koan_get_milestone: { keys: ["id"], getter: true }, - koan_get_decision: { keys: ["id"], getter: true }, - koan_get_intent: { keys: ["id"], getter: true }, - koan_get_change: { keys: ["id"], getter: true }, - - koan_set_overview: { keys: ["problem", "approach"], freeform: ["problem", "approach"], highValue: true }, - koan_set_constraints: { keys: ["constraints"], arrays: ["constraints"], highValue: true }, - koan_set_invisible_knowledge: { - keys: ["system", "invariants", "tradeoffs"], - freeform: ["system"], - arrays: ["invariants", "tradeoffs"], - highValue: true, - }, - - koan_add_decision: { keys: ["decision", "reasoning"], freeform: ["decision", "reasoning"], highValue: true }, - koan_set_decision: { keys: ["id", "decision", "reasoning"], freeform: ["decision", "reasoning"], highValue: true }, - koan_add_rejected_alternative: { - keys: ["decision_ref", "alternative", "rejection_reason"], - freeform: ["alternative", "rejection_reason"], - highValue: true, - }, - koan_set_rejected_alternative: { - keys: ["id", "decision_ref", "alternative", "rejection_reason"], - freeform: ["alternative", "rejection_reason"], - highValue: true, - }, - koan_add_risk: { keys: ["decision_ref", "anchor", "risk", "mitigation"], freeform: ["risk", "mitigation"], highValue: true }, - koan_set_risk: { - keys: ["id", "decision_ref", "anchor", "risk", "mitigation"], - freeform: ["risk", "mitigation"], - highValue: true, - }, - - koan_add_milestone: { - keys: ["name", "files", "flags", "requirements", "acceptance_criteria", "tests"], - arrays: ["files", "flags", "requirements", "acceptance_criteria", "tests"], - highValue: true, - }, - koan_set_milestone_name: { keys: ["id", "name"] }, - koan_set_milestone_files: { keys: ["id", "files"], arrays: ["files"], highValue: true }, - koan_set_milestone_flags: { keys: ["id", "flags"], arrays: ["flags"] }, - koan_set_milestone_requirements: { keys: ["id", "requirements"], arrays: ["requirements"], highValue: true }, - koan_set_milestone_acceptance_criteria: { keys: ["id", "acceptance_criteria"], arrays: ["acceptance_criteria"], highValue: true }, - koan_set_milestone_tests: { keys: ["id", "tests"], arrays: ["tests"], highValue: true }, - - koan_add_intent: { keys: ["milestone", "file", "function", "behavior"], freeform: ["behavior"], highValue: true }, - koan_set_intent: { keys: ["id", "file", "function", "behavior"], freeform: ["behavior"], highValue: true }, - - koan_add_change: { - keys: ["milestone", "file", "intent_ref", "diff", "doc_diff", "comments"], - freeform: ["diff", "doc_diff", "comments"], - highValue: true, - }, - koan_set_change_diff: { keys: ["id", "diff"], freeform: ["diff"], highValue: true }, - koan_set_change_doc_diff: { keys: ["id", "doc_diff"], freeform: ["doc_diff"], highValue: true }, - koan_set_change_comments: { keys: ["id", "comments"], freeform: ["comments"], highValue: true }, - koan_set_change_file: { keys: ["id", "file"], highValue: true }, - koan_set_change_intent_ref: { keys: ["id", "intent_ref"] }, - - koan_add_wave: { keys: ["milestones"], arrays: ["milestones"], highValue: true }, - koan_set_wave_milestones: { keys: ["id", "milestones"], arrays: ["milestones"], highValue: true }, - - koan_add_diagram: { keys: ["type", "scope", "title"] }, - koan_set_diagram: { keys: ["id", "title", "scope", "ascii_render"], freeform: ["ascii_render"], highValue: true }, - koan_add_diagram_node: { keys: ["diagram_id", "id", "label", "type"] }, - koan_add_diagram_edge: { keys: ["diagram_id", "source", "target", "label", "protocol"] }, - - koan_set_readme_entry: { keys: ["path", "content"], freeform: ["content"], highValue: true }, - - koan_qr_add_item: { keys: ["phase", "scope", "check", "severity"], freeform: ["check"], highValue: true }, - koan_qr_set_item: { keys: ["phase", "id", "status", "finding"], freeform: ["finding"], highValue: true }, - koan_qr_assign_group: { keys: ["phase", "group_id", "ids"], arrays: ["ids"], highValue: true }, - koan_qr_get_item: { keys: ["phase", "id"], getter: true }, - koan_qr_list_items: { keys: ["phase", "status"], getter: true }, - koan_qr_summary: { keys: ["phase"], getter: true }, + koan_select_story: { keys: ["story_id"], highValue: true }, + koan_complete_story: { keys: ["story_id"], highValue: true }, + koan_retry_story: { keys: ["story_id", "failure_summary"], freeform: ["failure_summary"], highValue: true }, + koan_skip_story: { keys: ["story_id", "reason"], freeform: ["reason"], highValue: true }, koan_ask_question: { keys: ["questions"], arrays: ["questions"], highValue: true }, + koan_request_scouts: { keys: ["scouts"], arrays: ["scouts"], highValue: true }, }; // Reads the tail of events.jsonl and returns structured log entries. -// Filters out heartbeats (noisy). Used by session.ts to feed the widget log card. +// Filters out heartbeats (noisy). Used by driver to feed the widget log card. export async function readRecentLogs(dir: string, count = 8): Promise { try { const raw = await fs.readFile(path.join(dir, "events.jsonl"), "utf8"); diff --git a/src/planner/lib/ipc-responder.ts b/src/planner/lib/ipc-responder.ts new file mode 100644 index 0000000..bf9c31a --- /dev/null +++ b/src/planner/lib/ipc-responder.ts @@ -0,0 +1,201 @@ +// Parent-side IPC responder: polls for requests from active subagents, +// handles them, and writes responses back. Runs concurrently with subagent +// process execution and terminates when the provided AbortSignal fires. +// +// Supports two request types (§11.2.4): +// "ask" → render ask UI, write answer back +// "scout-request" → spawn scouts via pool(), write findings paths back + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; + +import { + readIpcFile, + writeIpcFile, + createAskResponse, + createCancelledResponse, + type AskAnswerPayload, + type ScoutTask, + type AskIpcFile, + type ScoutIpcFile, +} from "./ipc.js"; +import { pool } from "./pool.js"; +import { askSingleQuestionWithInlineNote } from "../ui/ask/ask-inline-ui.js"; +import { askQuestionsWithTabs } from "../ui/ask/ask-tabs-ui.js"; +import type { AskQuestion, AskSelection } from "../ui/ask/ask-logic.js"; + +const POLL_INTERVAL_MS = 300; + +function sleep(ms: number): Promise { + return new Promise((resolve) => setTimeout(resolve, ms)); +} + +// Provided by subagent.ts when starting the IPC responder. Avoids circular +// imports: ipc-responder.ts never imports from subagent.ts. +export interface ScoutSpawnContext { + epicDir: string; + // Spawns a single scout; returns exit code. + spawnScout: (task: ScoutTask, scoutSubagentDir: string, outputFile: string) => Promise; +} + +// Handles a pending ask request: renders UI, writes response. +async function handleAskRequest( + subagentDir: string, + ipc: AskIpcFile, + ui: ExtensionUIContext, + signal: AbortSignal, +): Promise { + const { payload } = ipc; + const questions: AskQuestion[] = payload.questions.map((q) => ({ + id: q.id, + question: q.question, + options: q.options, + multi: q.multi, + recommended: q.recommended, + })); + + let cancelled = false; + let answers: AskAnswerPayload["answers"] = []; + + if (questions.length === 1) { + const q = questions[0]; + const selection = await askSingleQuestionWithInlineNote(ui, { + question: q.question, + options: q.options, + recommended: q.recommended, + }); + + // ask UI components do not accept an AbortSignal — they block until the + // user interacts even after the subagent exits. Check after return to + // prevent writing a stale answer to a dead subagent's IPC file. + if (signal.aborted) { + const current = await readIpcFile(subagentDir); + if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { + await writeIpcFile(subagentDir, { ...current, response: createCancelledResponse(ipc.id) }); + } + return; + } + + cancelled = selection.selectedOptions.length === 0 && !selection.customInput; + if (!cancelled) { + answers = [{ + id: q.id, + selectedOptions: selection.selectedOptions, + customInput: selection.customInput, + }]; + } + } else { + const result = await askQuestionsWithTabs(ui, questions); + + if (signal.aborted) { + const current = await readIpcFile(subagentDir); + if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { + await writeIpcFile(subagentDir, { ...current, response: createCancelledResponse(ipc.id) }); + } + return; + } + + cancelled = result.cancelled; + if (!cancelled) { + answers = questions.map((q, i) => { + const sel: AskSelection = result.selections[i] ?? { selectedOptions: [] }; + const entry: AskAnswerPayload["answers"][number] = { + id: q.id, + selectedOptions: sel.selectedOptions, + }; + if (sel.customInput !== undefined) { + entry.customInput = sel.customInput; + } + return entry; + }); + } + } + + const response = cancelled + ? createCancelledResponse(ipc.id) + : createAskResponse(ipc.id, { answers }); + + const current = await readIpcFile(subagentDir); + if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { + await writeIpcFile(subagentDir, { ...current, response }); + } +} + +// Handles a pending scout-request: spawns scouts via pool(), writes findings. +async function handleScoutRequest( + subagentDir: string, + ipc: ScoutIpcFile, + scoutCtx: ScoutSpawnContext, + signal: AbortSignal, +): Promise { + const { scouts, id } = ipc; + const { epicDir } = scoutCtx; + const findings: string[] = []; + const failures: string[] = []; + + // Each scout writes to ${subagentDir}/output.md — output is scoped to the + // scout's own directory, avoiding collisions. Compute subagentDir once and + // derive outputFile from it (never call Date.now() twice for the same entry). + const scoutEntries = scouts.map((task) => { + const scoutDir = path.join(epicDir, "subagents", `scout-${task.id}-${Date.now()}`); + return { task, subagentDir: scoutDir, outputFile: path.join(scoutDir, "output.md") }; + }); + + const taskIds = scoutEntries.map((t) => t.task.id); + await pool( + taskIds, + 4, // up to 4 concurrent scouts + async (taskId) => { + if (signal.aborted) return { exitCode: 1, stderr: "aborted", subagentDir: "" }; + const entry = scoutEntries.find((t) => t.task.id === taskId)!; + await fs.mkdir(entry.subagentDir, { recursive: true }); + const exitCode = await scoutCtx.spawnScout(entry.task, entry.subagentDir, entry.outputFile); + if (exitCode === 0) { + findings.push(entry.outputFile); + } else { + failures.push(taskId); + } + return { exitCode, stderr: "", subagentDir: entry.subagentDir }; + }, + ); + + // Write response back to the ipc file. + const current = await readIpcFile(subagentDir); + if (current !== null && current.type === "scout-request" && current.response === null && current.id === id) { + const updated: ScoutIpcFile = { ...current, response: { findings, failures } }; + await writeIpcFile(subagentDir, updated); + } +} + +// Runs the parent-side IPC poll loop for a single subagent directory. +// Routes to ask UI or scout spawning based on request type. +// Terminates when `signal` is aborted. Errors are swallowed — transient +// filesystem issues must not crash the parent session. +export async function runIpcResponder( + subagentDir: string, + ui: ExtensionUIContext, + signal: AbortSignal, + scoutContext?: ScoutSpawnContext, +): Promise { + while (!signal.aborted) { + try { + await sleep(POLL_INTERVAL_MS); + if (signal.aborted) break; + + const ipc = await readIpcFile(subagentDir); + if (ipc === null || ipc.response !== null) continue; + + if (ipc.type === "ask") { + await handleAskRequest(subagentDir, ipc, ui, signal); + } else if (ipc.type === "scout-request" && scoutContext) { + await handleScoutRequest(subagentDir, ipc, scoutContext, signal); + } + // Unknown type: ignore (forward-compatibility) + } catch { + // Swallow all errors — transient filesystem or UI issues must not + // abort the parent session. + } + } +} diff --git a/src/planner/lib/ipc.ts b/src/planner/lib/ipc.ts index aaa14ee..3d26828 100644 --- a/src/planner/lib/ipc.ts +++ b/src/planner/lib/ipc.ts @@ -1,50 +1,75 @@ // File-based IPC between subagent and parent session. -// A single ipc.json file per subagent directory holds both the request and -// response. Atomic writes (tmp-rename) prevent partial reads. +// A single ipc.json file per subagent directory holds the current request and +// its response. Atomic writes (tmp-rename) prevent partial reads. +// +// IPC protocol supports two message types (§11.2.4): +// "ask" — subagent asks the user a question +// "scout-request" — subagent requests parallel codebase scout spawning import { promises as fs } from "node:fs"; import * as path from "node:path"; import * as crypto from "node:crypto"; -// -- Types -- +// -- Scout types -- -export interface IpcFile { - request: IpcRequest; - response: IpcResponse | null; // null while awaiting parent response +export interface ScoutTask { + id: string; // Unique task ID, e.g. "auth-libs" + role: string; // Custom role description for the scout + prompt: string; // What the scout should find } -export interface IpcRequest { - id: string; // crypto.randomUUID() — correlates request to response - type: "ask-question"; // discriminant for routing; extensible to future types - createdAt: string; // ISO 8601 timestamp - payload: AskQuestionPayload; +export interface ScoutResponse { + findings: string[]; // File paths to scout output markdown files (absolute) + failures: string[]; // Scout task IDs that failed (non-fatal) } +// -- Ask types -- + export interface AskQuestionPayload { questions: Array<{ id: string; question: string; options: Array<{ label: string }>; multi?: boolean; - recommended?: number; // 0-indexed + recommended?: number; }>; } -export interface IpcResponse { - id: string; // must match request.id - respondedAt: string; // ISO 8601 timestamp - cancelled: boolean; // true when user presses Escape - payload: AskAnswerPayload | null; // null when cancelled -} - export interface AskAnswerPayload { answers: Array<{ - id: string; // matches question id + id: string; selectedOptions: string[]; - customInput?: string; // populated when user selects "Other" + customInput?: string; }>; } +export interface AskResponse { + id: string; + respondedAt: string; + cancelled: boolean; + payload: AskAnswerPayload | null; +} + +// -- IPC file union -- + +export interface AskIpcFile { + type: "ask"; + id: string; + createdAt: string; + payload: AskQuestionPayload; + response: AskResponse | null; +} + +export interface ScoutIpcFile { + type: "scout-request"; + id: string; + createdAt: string; + scouts: ScoutTask[]; + response: ScoutResponse | null; +} + +export type IpcFile = AskIpcFile | ScoutIpcFile; + // -- File paths -- const IPC_FILE = "ipc.json"; @@ -94,19 +119,27 @@ export async function deleteIpcFile(dir: string): Promise { // -- Factory helpers -- -export function createAskRequest(payload: AskQuestionPayload): IpcFile { +export function createAskRequest(payload: AskQuestionPayload): AskIpcFile { + return { + type: "ask", + id: crypto.randomUUID(), + createdAt: new Date().toISOString(), + payload, + response: null, + }; +} + +export function createScoutRequest(scouts: ScoutTask[]): ScoutIpcFile { return { - request: { - id: crypto.randomUUID(), - type: "ask-question", - createdAt: new Date().toISOString(), - payload, - }, + type: "scout-request", + id: crypto.randomUUID(), + createdAt: new Date().toISOString(), + scouts, response: null, }; } -export function createAskResponse(requestId: string, payload: AskAnswerPayload): IpcResponse { +export function createAskResponse(requestId: string, payload: AskAnswerPayload): AskResponse { return { id: requestId, respondedAt: new Date().toISOString(), @@ -115,7 +148,7 @@ export function createAskResponse(requestId: string, payload: AskAnswerPayload): }; } -export function createCancelledResponse(requestId: string): IpcResponse { +export function createCancelledResponse(requestId: string): AskResponse { return { id: requestId, respondedAt: new Date().toISOString(), diff --git a/src/planner/lib/permissions.ts b/src/planner/lib/permissions.ts index 90c3e06..058be7c 100644 --- a/src/planner/lib/permissions.ts +++ b/src/planner/lib/permissions.ts @@ -1,194 +1,145 @@ -// Default-deny permissions. Read tools bypass this map. Write tools -// (edit/write) always blocked during planning. The map defines OUTER -// boundaries; phase handlers narrow further. - +// Default-deny role-based permissions for koan subagents. +// +// Permission model overview: +// 1. READ_TOOLS (bash, read, grep, glob, find, ls) are always allowed for all +// roles. This is an accepted limitation (§11.9, §12.5): distinguishing +// "read bash" from "write bash" is intractable at the permission layer. +// Prompt engineering constrains intended bash use; enforcement does not. +// Do not assume bash is restricted to roles that list it explicitly. +// +// 2. ROLE_PERMISSIONS controls koan-specific tools and write/edit access. +// Unknown roles are blocked under default-deny policy. +// +// 3. Planning roles (intake, scout, decomposer, orchestrator, planner) have +// write/edit access path-scoped to the epic directory. Only the executor +// role has unrestricted write access — it must modify the codebase. + +import * as path from "node:path"; + +import { createLogger } from "../../utils/logger.js"; + +const log = createLogger("permissions"); + +// Read tools always allowed for all roles — early return in checkPermission. const READ_TOOLS = new Set(["read", "bash", "grep", "glob", "find", "ls"]); const WRITE_TOOLS = new Set(["edit", "write"]); -const PLAN_GETTER_TOOLS_LIST = [ - "koan_get_plan", - "koan_get_milestone", - "koan_get_decision", - "koan_get_intent", - "koan_get_change", -]; - -const PLAN_SETTER_TOOLS_LIST = [ - "koan_set_overview", - "koan_set_constraints", - "koan_set_invisible_knowledge", -]; - -const PLAN_DECISION_TOOLS_LIST = ["koan_add_decision", "koan_set_decision"]; - -const PLAN_REJECTED_ALT_TOOLS_LIST = [ - "koan_add_rejected_alternative", - "koan_set_rejected_alternative", -]; - -const PLAN_RISK_TOOLS_LIST = ["koan_add_risk", "koan_set_risk"]; - -const PLAN_MILESTONE_TOOLS_LIST = [ - "koan_add_milestone", - "koan_set_milestone_name", - "koan_set_milestone_files", - "koan_set_milestone_flags", - "koan_set_milestone_requirements", - "koan_set_milestone_acceptance_criteria", - "koan_set_milestone_tests", -]; - -const PLAN_INTENT_TOOLS_LIST = ["koan_add_intent", "koan_set_intent"]; - -const PLAN_CHANGE_TOOLS_LIST = [ - "koan_add_change", - "koan_set_change_diff", - "koan_set_change_doc_diff", - "koan_set_change_comments", - "koan_set_change_file", - "koan_set_change_intent_ref", -]; - -const PLAN_WAVE_TOOLS_LIST = ["koan_add_wave", "koan_set_wave_milestones"]; - -const PLAN_DIAGRAM_TOOLS_LIST = [ - "koan_add_diagram", - "koan_set_diagram", - "koan_add_diagram_node", - "koan_add_diagram_edge", -]; - -const PLAN_README_TOOLS_LIST = ["koan_set_readme_entry"]; - -const QR_TOOLS_LIST = [ - "koan_qr_add_item", - "koan_qr_set_item", - "koan_qr_assign_group", - "koan_qr_get_item", - "koan_qr_list_items", - "koan_qr_summary", -]; - -const ALL_PLAN_ENTITY_TOOLS = [ - ...PLAN_DECISION_TOOLS_LIST, - ...PLAN_REJECTED_ALT_TOOLS_LIST, - ...PLAN_RISK_TOOLS_LIST, - ...PLAN_MILESTONE_TOOLS_LIST, - ...PLAN_INTENT_TOOLS_LIST, - ...PLAN_WAVE_TOOLS_LIST, - ...PLAN_DIAGRAM_TOOLS_LIST, - ...PLAN_README_TOOLS_LIST, -]; - -const PLAN_DESIGN_ENTITY_TOOLS = ALL_PLAN_ENTITY_TOOLS.filter( - (t) => !PLAN_CHANGE_TOOLS_LIST.includes(t), -); - -export const PLAN_GETTER_TOOLS: ReadonlySet = new Set( - PLAN_GETTER_TOOLS_LIST, -); - -export const PLAN_MUTATION_TOOLS: ReadonlySet = new Set([ - ...PLAN_SETTER_TOOLS_LIST, - ...ALL_PLAN_ENTITY_TOOLS, - ...PLAN_CHANGE_TOOLS_LIST, +// Tools allowed per role beyond READ_TOOLS. +// Write/edit are tracked here but enforced via path-scoping below. +export const ROLE_PERMISSIONS: ReadonlyMap> = new Map([ + [ + "intake", + new Set([ + "koan_complete_step", + "koan_ask_question", + "koan_request_scouts", + "edit", + "write", + ]), + ], + [ + "scout", + new Set([ + "koan_complete_step", + "edit", + "write", + // No koan_ask_question — scouts are narrow investigators; no user interaction. + // No koan_request_scouts — scouts do not spawn scouts. + ]), + ], + [ + "decomposer", + new Set([ + "koan_complete_step", + "koan_ask_question", + "koan_request_scouts", + "edit", + "write", + ]), + ], + [ + "orchestrator", + new Set([ + "koan_complete_step", + "koan_ask_question", + // koan_request_scouts excluded from orchestrator — scouts serve planning roles; + // orchestrator uses bash for verification. + "koan_select_story", + "koan_complete_story", + "koan_retry_story", + "koan_skip_story", + "edit", + "write", + "bash", // also in READ_TOOLS; explicit here for documentation + ]), + ], + [ + "planner", + new Set([ + "koan_complete_step", + "koan_ask_question", + "koan_request_scouts", + "edit", + "write", + ]), + ], + [ + "executor", + new Set([ + "koan_complete_step", + "koan_ask_question", + "edit", + "write", + "bash", // also in READ_TOOLS; explicit here for documentation + ]), + ], ]); -// Missing phase keys are blocked (default-deny extends to unknown phases). -// Prevents security boundary breach when a new phase is added without -// updating the permissions map. -export const PHASE_PERMISSIONS: ReadonlyMap> = - new Map([ - [ - "plan-design", - new Set([ - "koan_complete_step", - "koan_ask_question", - ...PLAN_GETTER_TOOLS_LIST, - ...PLAN_SETTER_TOOLS_LIST, - ...PLAN_DESIGN_ENTITY_TOOLS, - ]), - ], - [ - "plan-code", - new Set([ - "koan_complete_step", - "koan_ask_question", - ...PLAN_GETTER_TOOLS_LIST, - ...PLAN_CHANGE_TOOLS_LIST, - "koan_set_intent", - ]), - ], - [ - "plan-docs", - new Set([ - "koan_complete_step", - "koan_ask_question", - ...PLAN_GETTER_TOOLS_LIST, - "koan_set_change_doc_diff", - "koan_set_change_comments", - "koan_set_readme_entry", - "koan_add_diagram", - "koan_set_diagram", - "koan_add_diagram_node", - "koan_add_diagram_edge", - ]), - ], - [ - "qr-plan-design", - new Set(["koan_complete_step", ...PLAN_GETTER_TOOLS_LIST, ...QR_TOOLS_LIST]), - ], - [ - "qr-plan-code", - new Set([ - "koan_complete_step", - "koan_get_plan", - "koan_get_milestone", - "koan_get_intent", - "koan_get_change", - ...QR_TOOLS_LIST, - ]), - ], - [ - "qr-plan-docs", - new Set([ - "koan_complete_step", - "koan_get_plan", - "koan_get_milestone", - "koan_get_change", - ...QR_TOOLS_LIST, - ]), - ], - ]); +// Planning roles write only inside the epic directory. +// Executor has unrestricted write access (must implement stories in the codebase). +const PLANNING_ROLES = new Set(["intake", "scout", "decomposer", "orchestrator", "planner"]); export function checkPermission( - phaseKey: string, + role: string, toolName: string, + epicDir?: string, + toolArgs?: Record, ): { allowed: boolean; reason?: string } { + // Read tools are always allowed — check before role map lookup. if (READ_TOOLS.has(toolName)) { return { allowed: true }; } - if (WRITE_TOOLS.has(toolName)) { - return { - allowed: false, - reason: "Edit/write tools blocked during planning.", - }; + // Unknown role: blocked under default-deny policy. + if (!ROLE_PERMISSIONS.has(role)) { + log("Unknown role blocked", { role, toolName }); + return { allowed: false, reason: `Unknown role: ${role}` }; } - if (!PHASE_PERMISSIONS.has(phaseKey)) { - return { - allowed: false, - reason: `Unknown phase: ${phaseKey}`, - }; + const roleAllowed = ROLE_PERMISSIONS.get(role)!; + + if (!roleAllowed.has(toolName)) { + return { allowed: false, reason: `${toolName} is not available for role ${role}` }; } - const allowed = PHASE_PERMISSIONS.get(phaseKey)!; - if (!allowed.has(toolName)) { - return { - allowed: false, - reason: `${toolName} is not available in phase ${phaseKey}`, - }; + // Path-scope enforcement: planning roles may only write inside the epic directory. + if (WRITE_TOOLS.has(toolName) && PLANNING_ROLES.has(role)) { + if (epicDir && toolArgs) { + const rawPath = toolArgs["path"]; + if (typeof rawPath === "string") { + const resolvedTool = path.resolve(rawPath); + const resolvedEpic = path.resolve(epicDir); + if (!resolvedTool.startsWith(resolvedEpic + path.sep) && resolvedTool !== resolvedEpic) { + log("Write blocked: path outside epic dir", { role, toolName, rawPath, epicDir }); + return { + allowed: false, + reason: `${toolName} path "${rawPath}" is outside epic directory`, + }; + } + } + } + // No epicDir or no path arg: allow (cannot scope-check without context). + return { allowed: true }; } return { allowed: true }; diff --git a/src/planner/lib/pool.ts b/src/planner/lib/pool.ts index f4bfcc8..132ea99 100644 --- a/src/planner/lib/pool.ts +++ b/src/planner/lib/pool.ts @@ -1,5 +1,5 @@ // Bounded-parallel subagent pool using an in-process semaphore. -// Runs all items to completion regardless of failures; callers inspect PoolResult. +// Runs all items to completion regardless of individual failures. // Timeout logic belongs in the worker closure, not here. import type { SubagentResult } from "../subagent.js"; @@ -19,14 +19,10 @@ export interface PoolProgress { queued: number; } -// -- Constants -- - -export const DEFAULT_REVIEWER_TIMEOUT_MS = 10 * 60 * 1000; - // -- Private helpers -- class Semaphore { - private queue: Array<() => void> = []; + private readonly queue: Array<() => void> = []; private count: number; constructor(limit: number) { @@ -80,8 +76,8 @@ export async function pool( emit(); try { - const r = await worker(id); - if (r.exitCode !== 0) { + const result = await worker(id); + if (result.exitCode !== 0) { failed.push(id); } } finally { diff --git a/src/planner/lib/runtime-context.ts b/src/planner/lib/runtime-context.ts new file mode 100644 index 0000000..5019bb1 --- /dev/null +++ b/src/planner/lib/runtime-context.ts @@ -0,0 +1,20 @@ +// RuntimeContext replaces the old PlanRef + SubagentRef + WorkflowDispatch triple. +// Set once during before_agent_start; tools read from it at call time. The mutable-ref +// pattern accommodates pi's extension lifecycle: tools register at init before state exists. +// +// onCompleteStep return value: +// string → next step's formatted prompt (tool returns it to the LLM) +// null → phase is complete (tool returns "Phase complete.") +export interface RuntimeContext { + epicDir: string | null; + subagentDir: string | null; + onCompleteStep: ((thoughts: string) => Promise) | null; +} + +export function createRuntimeContext(): RuntimeContext { + return { + epicDir: null, + subagentDir: null, + onCompleteStep: null, + }; +} diff --git a/src/planner/lib/step.ts b/src/planner/lib/step.ts index 28743eb..9771f6f 100644 --- a/src/planner/lib/step.ts +++ b/src/planner/lib/step.ts @@ -1,16 +1,15 @@ -// Step prompt assembly for koan workflows. +// Step prompt assembly for koan phase workflows. // -// The `thoughts` parameter on koan_complete_step captures the model's -// work output (analysis, review, findings) as a tool parameter. This -// avoids requiring the model to produce text + tool_call in one -// response, which some models (e.g. GPT-5-codex) cannot do. +// The `thoughts` parameter on koan_complete_step captures the model's work output +// (analysis, review, findings) as a tool parameter rather than text output. This +// ensures models that can't mix text + tool_call in one response still advance +// the workflow. export interface StepGuidance { title: string; instructions: string[]; - // Custom invoke-after directive. When omitted, formatStep - // appends the default koan_complete_step directive. - // Terminal steps override this (e.g., step 6 plan validation). + // Custom invoke-after directive. When omitted, formatStep appends the default + // koan_complete_step directive. Terminal steps may override this. invokeAfter?: string; } diff --git a/src/planner/tools/ask.ts b/src/planner/tools/ask.ts index f1d6ff0..57a8b8a 100644 --- a/src/planner/tools/ask.ts +++ b/src/planner/tools/ask.ts @@ -1,22 +1,26 @@ -// koan_ask_question tool: subagent-side of the file-based IPC ask flow. -// Writes ipc.json, polls until parent writes a response, then returns -// formatted answers to the LLM. The entire poll loop is wrapped in a -// try/finally that deletes ipc.json, guaranteeing cleanup on all exit paths. +// IPC-based tools: koan_ask_question and koan_request_scouts. +// Both tools use file-based IPC to pause subagent execution and communicate +// with the parent session, then resume with the response. +// +// koan_ask_question — ask the user a question, get answers +// koan_request_scouts — request parallel codebase scouts, get findings paths import { Type, type Static } from "@sinclair/typebox"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import type { SubagentRef } from "../lib/dispatch.js"; +import type { RuntimeContext } from "../lib/runtime-context.js"; import { ipcFileExists, writeIpcFile, readIpcFile, deleteIpcFile, createAskRequest, + createScoutRequest, type AskAnswerPayload, + type ScoutTask, } from "../lib/ipc.js"; -// -- Tool schema (mirrors pi-ask-tool-extension exactly) -- +// -- Schemas -- const OptionItemSchema = Type.Object({ label: Type.String({ description: "Display label" }), @@ -41,7 +45,19 @@ const AskParamsSchema = Type.Object({ type AskParams = Static; -// -- Result formatting -- +const ScoutTaskSchema = Type.Object({ + id: Type.String({ description: "Scout task ID, e.g. 'auth-libs'" }), + role: Type.String({ description: "Custom role for the scout, e.g. 'system architect'" }), + prompt: Type.String({ description: "What to find, e.g. 'Find all auth-related files in src/'" }), +}); + +const RequestScoutsSchema = Type.Object({ + scouts: Type.Array(ScoutTaskSchema, { description: "Scout tasks to run in parallel", minItems: 1 }), +}); + +type RequestScoutsParams = Static; + +// -- Result formatting (ask) -- interface QuestionResult { id: string; @@ -125,6 +141,12 @@ function buildQuestionResults( }); } +// -- Shared poll helper -- + +function sleep(ms: number): Promise { + return new Promise((resolve) => setTimeout(resolve, ms)); +} + // -- Tool registration -- const ASK_TOOL_DESCRIPTION = ` @@ -138,11 +160,21 @@ Ask the user for clarification when a choice materially affects the outcome. - Do NOT include an 'Other' option; UI adds it automatically. `.trim(); -function sleep(ms: number): Promise { - return new Promise((resolve) => setTimeout(resolve, ms)); -} +const SCOUTS_TOOL_DESCRIPTION = ` +Request parallel codebase scouting. Use when you need to explore specific +areas of the codebase before making decisions or asking questions. + +Each scout answers one narrow question and writes findings to a markdown file. +Scouts run in parallel. The tool returns the file paths to read. + +- id: unique identifier for this scout task (e.g., "auth-patterns") +- role: the investigator role for the scout (e.g., "security auditor") +- prompt: what to find (e.g., "Find all authentication middleware in src/") +`.trim(); + +export function registerAskTools(pi: ExtensionAPI, ctx: RuntimeContext): void { + // -- koan_ask_question -- -export function registerAskTools(pi: ExtensionAPI, subagentRef: SubagentRef): void { pi.registerTool({ name: "koan_ask_question", label: "Ask question", @@ -151,7 +183,7 @@ export function registerAskTools(pi: ExtensionAPI, subagentRef: SubagentRef): vo async execute(_toolCallId, params, signal) { const askParams = params as AskParams; - const dir = subagentRef.dir; + const dir = ctx.subagentDir; if (!dir) { return { @@ -162,7 +194,7 @@ export function registerAskTools(pi: ExtensionAPI, subagentRef: SubagentRef): vo if (await ipcFileExists(dir)) { return { - content: [{ type: "text" as const, text: "Error: A question request is already pending." }], + content: [{ type: "text" as const, text: "Error: An IPC request is already pending." }], details: undefined, }; } @@ -172,9 +204,7 @@ export function registerAskTools(pi: ExtensionAPI, subagentRef: SubagentRef): vo let aborted = false; const onAbort = () => { aborted = true; }; - if (signal) { - signal.addEventListener("abort", onAbort, { once: true }); - } + if (signal) signal.addEventListener("abort", onAbort, { once: true }); type PollResult = "answered" | "cancelled" | "aborted" | "file-gone"; let pollResult: PollResult = "file-gone"; @@ -183,18 +213,12 @@ export function registerAskTools(pi: ExtensionAPI, subagentRef: SubagentRef): vo try { while (!aborted) { await sleep(500); - if (signal?.aborted) { - aborted = true; - break; - } + if (signal?.aborted) { aborted = true; break; } const current = await readIpcFile(dir); - if (current === null) { - pollResult = "file-gone"; - break; - } + if (current === null) { pollResult = "file-gone"; break; } - if (current.response !== null && current.response.id === ipc.request.id) { + if (current.type === "ask" && current.response !== null && current.response.id === ipc.id) { if (current.response.cancelled) { pollResult = "cancelled"; } else { @@ -205,9 +229,7 @@ export function registerAskTools(pi: ExtensionAPI, subagentRef: SubagentRef): vo } } - if (aborted) { - pollResult = "aborted"; - } + if (aborted) pollResult = "aborted"; } finally { await deleteIpcFile(dir); } @@ -238,4 +260,95 @@ export function registerAskTools(pi: ExtensionAPI, subagentRef: SubagentRef): vo } }, }); + + // -- koan_request_scouts -- + + pi.registerTool({ + name: "koan_request_scouts", + label: "Request codebase scouts", + description: SCOUTS_TOOL_DESCRIPTION, + parameters: RequestScoutsSchema, + + async execute(_toolCallId, params, signal) { + const { scouts } = params as RequestScoutsParams; + const dir = ctx.subagentDir; + + if (!dir) { + return { + content: [{ type: "text" as const, text: "Error: koan_request_scouts is only available in subagent context." }], + details: undefined, + }; + } + + if (await ipcFileExists(dir)) { + return { + content: [{ type: "text" as const, text: "Error: An IPC request is already pending." }], + details: undefined, + }; + } + + const ipc = createScoutRequest(scouts as ScoutTask[]); + await writeIpcFile(dir, ipc); + + let aborted = false; + const onAbort = () => { aborted = true; }; + if (signal) signal.addEventListener("abort", onAbort, { once: true }); + + type PollResult = "completed" | "aborted" | "file-gone"; + let pollResult: PollResult = "file-gone"; + let findings: string[] = []; + let failures: string[] = []; + + try { + while (!aborted) { + await sleep(500); + if (signal?.aborted) { aborted = true; break; } + + const current = await readIpcFile(dir); + if (current === null) { pollResult = "file-gone"; break; } + + if (current.type === "scout-request" && current.response !== null && current.id === ipc.id) { + pollResult = "completed"; + findings = current.response.findings; + failures = current.response.failures; + break; + } + } + + if (aborted) pollResult = "aborted"; + } finally { + await deleteIpcFile(dir); + } + + switch (pollResult) { + case "completed": { + const lines: string[] = [ + `Scout findings: ${findings.length} completed, ${failures.length} failed.`, + "", + ]; + if (findings.length > 0) { + lines.push("Findings files (read these for codebase context):"); + for (const f of findings) lines.push(` ${f}`); + } + if (failures.length > 0) { + lines.push(`Failed scouts (non-fatal, proceed without them): ${failures.join(", ")}`); + } + return { + content: [{ type: "text" as const, text: lines.join("\n") }], + details: undefined, + }; + } + case "aborted": + return { + content: [{ type: "text" as const, text: "Scout request aborted. Proceed without codebase context." }], + details: undefined, + }; + case "file-gone": + return { + content: [{ type: "text" as const, text: "Scout request cancelled. Proceed without codebase context." }], + details: undefined, + }; + } + }, + }); } diff --git a/src/planner/tools/workflow.ts b/src/planner/tools/workflow.ts index 28b5282..71eb74e 100644 --- a/src/planner/tools/workflow.ts +++ b/src/planner/tools/workflow.ts @@ -1,27 +1,27 @@ // Workflow tool registration: koan_complete_step. // Tools register once at init; execute callbacks read from the mutable -// dispatch at call time, decoupling static registration from phase routing. +// RuntimeContext at call time, decoupling static registration from phase routing. import { Type } from "@sinclair/typebox"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { createLogger } from "../../utils/logger.js"; -import type { WorkflowDispatch } from "../lib/dispatch.js"; +import type { RuntimeContext } from "../lib/runtime-context.js"; const log = createLogger("Dispatch"); // Registers workflow tools. Called once at init in koan.ts, // before pi's _buildRuntime() snapshot. Tool execute callbacks read -// from the dispatch at call time -- the dispatch is mutable, the -// tool list is not. +// from the RuntimeContext at call time — the context is mutable, +// the tool list is not. // // Why register all tools unconditionally? Flags are unavailable during // init (getFlag() returns undefined before _buildRuntime() sets flagValues), -// so conditional registration based on role/phase is impossible. Tools -// registered after _buildRuntime() are invisible to the LLM. +// so conditional registration based on role is impossible. Tools registered +// after _buildRuntime() are invisible to the LLM. export function registerWorkflowTools( pi: ExtensionAPI, - dispatch: WorkflowDispatch, + ctx: RuntimeContext, ): void { // -- koan_complete_step -- // The `thoughts` parameter captures the model's work output (analysis, @@ -33,7 +33,7 @@ export function registerWorkflowTools( label: "Complete current workflow step", description: [ "Signal completion of the current workflow step.", - "Put your analysis, findings, or review in the `thoughts` parameter.", + "Put your analysis, findings, or work output in the `thoughts` parameter.", "DO NOT call this tool until the step instructions explicitly tell you to.", ].join(" "), parameters: Type.Object({ @@ -42,16 +42,14 @@ export function registerWorkflowTools( })), }), async execute(_toolCallId, params) { - if (!dispatch.onCompleteStep) { + if (!ctx.onCompleteStep) { + log("koan_complete_step called with no active phase"); throw new Error("No workflow phase is active."); } - const thoughts = (params as { thoughts?: string }).thoughts; - const r = await dispatch.onCompleteStep(thoughts); - if (!r.ok) { - throw new Error(r.error ?? "Step transition failed."); - } + const thoughts = (params as { thoughts?: string }).thoughts ?? ""; + const nextPrompt = await ctx.onCompleteStep(thoughts); return { - content: [{ type: "text" as const, text: r.prompt ?? "Step complete." }], + content: [{ type: "text" as const, text: nextPrompt ?? "Phase complete." }], details: undefined, }; }, From 0d46330d318ce458644013a728449c8e3ffbc43c Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Mar 2026 12:45:25 +0700 Subject: [PATCH 043/412] feat(planner): implement role-based phase classes and orchestrator tools --- src/planner/phases/base-phase.ts | 124 +++++++++ src/planner/phases/decomposer/phase.ts | 39 +++ src/planner/phases/decomposer/prompts.ts | 151 +++++++++++ src/planner/phases/dispatch.ts | 257 +++++------------- src/planner/phases/executor/phase.ts | 43 +++ src/planner/phases/executor/prompts.ts | 156 +++++++++++ src/planner/phases/intake/phase.ts | 43 +++ src/planner/phases/intake/prompts.ts | 183 +++++++++++++ src/planner/phases/orchestrator/phase.ts | 60 +++++ src/planner/phases/orchestrator/prompts.ts | 299 +++++++++++++++++++++ src/planner/phases/planner/phase.ts | 41 +++ src/planner/phases/planner/prompts.ts | 213 +++++++++++++++ src/planner/phases/scout/phase.ts | 39 +++ src/planner/phases/scout/prompts.ts | 74 +++++ src/planner/tools/index.ts | 41 +-- src/planner/tools/orchestrator.ts | 239 ++++++++++++++++ 16 files changed, 1788 insertions(+), 214 deletions(-) create mode 100644 src/planner/phases/base-phase.ts create mode 100644 src/planner/phases/decomposer/phase.ts create mode 100644 src/planner/phases/decomposer/prompts.ts create mode 100644 src/planner/phases/executor/phase.ts create mode 100644 src/planner/phases/executor/prompts.ts create mode 100644 src/planner/phases/intake/phase.ts create mode 100644 src/planner/phases/intake/prompts.ts create mode 100644 src/planner/phases/orchestrator/phase.ts create mode 100644 src/planner/phases/orchestrator/prompts.ts create mode 100644 src/planner/phases/planner/phase.ts create mode 100644 src/planner/phases/planner/prompts.ts create mode 100644 src/planner/phases/scout/phase.ts create mode 100644 src/planner/phases/scout/prompts.ts create mode 100644 src/planner/tools/orchestrator.ts diff --git a/src/planner/phases/base-phase.ts b/src/planner/phases/base-phase.ts new file mode 100644 index 0000000..775b835 --- /dev/null +++ b/src/planner/phases/base-phase.ts @@ -0,0 +1,124 @@ +// BasePhase: shared lifecycle for all six koan subagent roles. +// Subclasses define only their step structure and system prompt. +// Eliminates ~40 lines of duplicated skeleton per phase. +// +// Lifecycle: +// constructor → registerHandlers() (hooks event listeners) +// begin() → activates phase, sets onCompleteStep in ctx, emits phase_start +// handleStepComplete() → advances step counter, returns next prompt or null + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { createLogger, type Logger } from "../../utils/logger.js"; +import { checkPermission } from "../lib/permissions.js"; +import { formatStep, type StepGuidance } from "../lib/step.js"; +import { EventLog } from "../lib/audit.js"; +import type { RuntimeContext } from "../lib/runtime-context.js"; + +export abstract class BasePhase { + // Subclasses declare these as readonly properties. + protected abstract readonly role: string; + protected abstract readonly totalSteps: number; + + // Subclasses implement these to define step content. + protected abstract getSystemPrompt(): string; + protected abstract getStepName(step: number): string; + protected abstract getStepGuidance(step: number): StepGuidance; + + private step = 1; + private active = false; + private step1Prompt: string | null = null; + + protected readonly log: Logger; + + constructor( + protected readonly pi: ExtensionAPI, + protected readonly ctx: RuntimeContext, + log?: Logger, + protected readonly eventLog?: EventLog, + ) { + this.log = log ?? createLogger("Phase"); + this.registerHandlers(); + } + + // -- Event handler registration -- + + private registerHandlers(): void { + // before_agent_start: inject system prompt when this phase is active. + this.pi.on("before_agent_start", () => { + if (!this.active) return undefined; + return { systemPrompt: this.getSystemPrompt() }; + }); + + // context: append step 1 guidance to the spawn prompt (§9.8 append pattern). + // Preserves context embedded by the spawn function (scout question, retry + // context, etc.) while adding structured step instructions after a separator. + this.pi.on("context", (event) => { + if (!this.active || this.step !== 1 || !this.step1Prompt) return undefined; + const messages = event.messages.map((m) => { + if (m.role !== "user") return m; + const existing = typeof m.content === "string" ? m.content.trim() : ""; + const combined = existing.length > 0 + ? `${existing}\n\n---\n\n${this.step1Prompt!}` + : this.step1Prompt!; + return { ...m, content: combined }; + }); + return { messages }; + }); + + // tool_call: default-deny permission check for every tool call. + this.pi.on("tool_call", (event) => { + if (!this.active) return undefined; + const perm = checkPermission( + this.role, + event.toolName, + this.ctx.epicDir ?? undefined, + event.input as Record, + ); + if (!perm.allowed) { + return { block: true, reason: perm.reason }; + } + return undefined; + }); + } + + // -- Public lifecycle -- + + async begin(): Promise { + this.step1Prompt = formatStep(this.getStepGuidance(1)); + this.active = true; + this.step = 1; + + if (this.ctx.onCompleteStep !== null) { + throw new Error(`ctx.onCompleteStep is already occupied — cannot begin ${this.role} phase`); + } + this.ctx.onCompleteStep = (thoughts: string) => this.handleStepComplete(thoughts); + + this.log("Starting phase", { role: this.role, step: 1, totalSteps: this.totalSteps }); + await this.eventLog?.emitPhaseStart(this.totalSteps); + await this.eventLog?.emitStepTransition(1, this.getStepName(1), this.totalSteps); + } + + // -- Private step progression -- + + private async handleStepComplete(thoughts: string): Promise { + void thoughts; // captured in event log via tool_result; used by subclass prompts if needed + const prev = this.step; + + if (prev === this.totalSteps) { + // Phase complete. + this.active = false; + this.ctx.onCompleteStep = null; + await this.eventLog?.emitPhaseEnd("completed"); + this.log("Phase complete", { role: this.role }); + return null; + } + + // Advance to next step. + this.step = prev + 1; + const prompt = formatStep(this.getStepGuidance(this.step)); + await this.eventLog?.emitStepTransition(this.step, this.getStepName(this.step), this.totalSteps); + this.log("Step transition", { role: this.role, from: prev, to: this.step }); + return prompt; + } +} diff --git a/src/planner/phases/decomposer/phase.ts b/src/planner/phases/decomposer/phase.ts new file mode 100644 index 0000000..b5ab322 --- /dev/null +++ b/src/planner/phases/decomposer/phase.ts @@ -0,0 +1,39 @@ +// Decomposer phase: splits the epic into story sketches. +// Two steps: analysis → decomposition. + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { createLogger, type Logger } from "../../../utils/logger.js"; +import type { RuntimeContext } from "../../lib/runtime-context.js"; +import { EventLog } from "../../lib/audit.js"; +import { BasePhase } from "../base-phase.js"; +import { DECOMPOSER_STEP_NAMES, decomposerSystemPrompt, decomposerStepGuidance } from "./prompts.js"; +import type { StepGuidance } from "../../lib/step.js"; + +export class DecomposerPhase extends BasePhase { + protected readonly role = "decomposer"; + protected readonly totalSteps = 2; + + constructor( + pi: ExtensionAPI, + config: { epicDir: string }, + ctx: RuntimeContext, + log?: Logger, + eventLog?: EventLog, + ) { + super(pi, ctx, log ?? createLogger("DecomposerPhase"), eventLog); + void config; + } + + protected getSystemPrompt(): string { + return decomposerSystemPrompt(); + } + + protected getStepName(step: number): string { + return DECOMPOSER_STEP_NAMES[step] ?? `Step ${step}`; + } + + protected getStepGuidance(step: number): StepGuidance { + return decomposerStepGuidance(step); + } +} diff --git a/src/planner/phases/decomposer/prompts.ts b/src/planner/phases/decomposer/prompts.ts new file mode 100644 index 0000000..7f18450 --- /dev/null +++ b/src/planner/phases/decomposer/prompts.ts @@ -0,0 +1,151 @@ +// Decomposer phase prompts — 2 steps: analysis → decomposition. +// Story IDs use S-NNN-slug format per §11.5.5 (e.g., S-001-auth-provider). + +import type { StepGuidance } from "../../lib/step.js"; + +export const DECOMPOSER_STEP_NAMES: Record = { + 1: "Analysis", + 2: "Decomposition", +}; + +export function decomposerSystemPrompt(): string { + return `You are a feature decomposer for a coding task planner. You read intake output and codebase scout reports, then split the requested work into independent story sketches — each story representing one pull request. + +## Your role + +You define WHAT the stories are and in WHAT ORDER they should be executed. You do NOT decide HOW each story is implemented (that belongs to the planner role). + +## Story definition + +A story must be: +- **Independent**: it can be reviewed and merged without depending on an unreleased sibling story. +- **Bounded**: it fits in one pull request — one coherent change to the codebase. +- **Testable**: the change can be verified in isolation. +- **Sequenced**: if stories have dependencies, they are ordered so earlier stories provide a stable base. + +## Story ID format + +Story IDs use the format: \`S-NNN-descriptive-slug\` +Examples: \`S-001-auth-provider\`, \`S-002-protected-routes\`, \`S-003-user-profile\` + +Use zero-padded three-digit numbers. The slug is a short kebab-case description of the story goal. +This format is sortable and human-readable. + +## Strict rules + +- MUST NOT include implementation details (specific functions, algorithms, data structures). +- MUST NOT make decisions that require user input. Those belong to intake. +- MUST NOT invent scope not present in context.md or decisions.md. +- MUST produce one story sketch per deliverable unit of work. +- SHOULD keep stories small: prefer 4–8 stories over 1–2 large ones. +- SHOULD order stories so foundational work (types, interfaces, data models) comes first. +- SHOULD mark stories that are optional or conditional explicitly. +- MUST use the S-NNN-slug story ID format. + +## Output files + +You write the following files, all inside the epic directory: + +1. **epic.md** — overview of the full scope and the story list with sequencing rationale. +2. **stories/{story-id}/story.md** — one file per story with title, goal, scope, and dependencies. + +## Tools available + +- All read tools (read, bash, grep, glob, find, ls) — for reading intake output and scout reports. +- \`koan_request_scouts\` — to request additional codebase exploration if needed. +- \`write\` / \`edit\` — for writing output files inside the epic directory. +- \`koan_complete_step\` — to signal step completion. + +You work in two steps. First you read and analyze. Then you write the decomposition.`; +} + +export function decomposerStepGuidance(step: number): StepGuidance { + switch (step) { + case 1: + return { + title: DECOMPOSER_STEP_NAMES[1], + instructions: [ + "Read the intake output and all scout reports. Build a complete understanding of the scope", + "before producing any output.", + "", + "## Files to read", + "", + "From the epic directory:", + "- `context.md` — structured requirements extracted from the conversation", + "- `decisions.md` — user answers to clarifying questions", + "", + "If scout reports were referenced in your initial instructions above, read them now.", + "If no scout reports were mentioned, proceed without them.", + "You may also call `koan_request_scouts` if you need codebase context to inform story boundaries.", + "", + "## What to understand", + "", + "After reading, you should be able to answer:", + "- What is the top-level goal of this epic?", + "- What are the distinct deliverable units of work?", + "- Which units depend on each other, and what is the safe delivery order?", + "- Are there any parts of the work that are conditional or optional?", + "- What does the existing codebase already provide (from scout reports)?", + "", + "Do not write any output files during this step.", + ], + }; + + case 2: + return { + title: DECOMPOSER_STEP_NAMES[2], + instructions: [ + "Produce the full decomposition: epic.md and one story.md per story.", + "", + "## Story ID format", + "", + "Use S-NNN-slug format: S-001-auth-provider, S-002-protected-routes, etc.", + "The number is zero-padded, three digits, sequential. The slug is kebab-case.", + "", + "## epic.md", + "", + "Write `epic.md` to the epic directory with these sections:", + "", + "### Overview", + "One to three paragraphs describing the full scope of this epic.", + "", + "### Stories", + "A numbered list of all stories in delivery order.", + "Format: `{n}. [{story-id}] {story title} — {one-sentence goal}`", + "", + "### Sequencing Rationale", + "Explain why the stories are ordered as they are. Identify dependency chains.", + "Note any stories that can be worked in parallel.", + "", + "## stories/{story-id}/story.md", + "", + "Write one file per story. Use the story ID as the directory name.", + "Each story.md must contain these sections:", + "", + "### Goal", + "One sentence: what this story delivers and why.", + "", + "### Scope", + "What is included in this story. Be specific about boundaries.", + "List what is explicitly OUT OF SCOPE (to be handled in another story or not at all).", + "", + "### Dependencies", + "List any stories that must be merged before this story can begin.", + "If none: write `(none — this story can start immediately)`", + "", + "### Acceptance Criteria", + "Three to six testable conditions that define 'done' for this story.", + "Format: `- [ ] [condition]`", + "", + "After writing all files, call `koan_complete_step` with a summary:", + "number of stories produced and the delivery order.", + ], + }; + + default: + return { + title: `Step ${step}`, + instructions: [`Execute step ${step}.`], + }; + } +} diff --git a/src/planner/phases/dispatch.ts b/src/planner/phases/dispatch.ts index f3e97c6..b880cc0 100644 --- a/src/planner/phases/dispatch.ts +++ b/src/planner/phases/dispatch.ts @@ -1,233 +1,124 @@ // Phase dispatch: detects subagent mode from CLI flags and routes to the -// appropriate phase constructor. Flags are unavailable at extension init -// (getFlag returns undefined before _buildRuntime), so detection is +// appropriate phase class based on role. Flags are unavailable at extension +// init (getFlag returns undefined before _buildRuntime), so detection is // deferred to before_agent_start. -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import { PlanDesignPhase } from "./plan-design/phase.js"; -import { PlanDesignFixPhase } from "./plan-design/fix-phase.js"; -import { PlanCodePhase } from "./plan-code/phase.js"; -import { PlanCodeFixPhase } from "./plan-code/fix-phase.js"; -import { PlanDocsPhase } from "./plan-docs/phase.js"; -import { PlanDocsFixPhase } from "./plan-docs/fix-phase.js"; -import { QRDecomposePhase } from "./qr-decompose/phase.js"; -import { QRVerifyPhase } from "./qr-verify/phase.js"; import { createLogger, type Logger } from "../../utils/logger.js"; -import type { WorkflowDispatch, PlanRef } from "../lib/dispatch.js"; +import type { RuntimeContext } from "../lib/runtime-context.js"; import type { EventLog } from "../lib/audit.js"; -import type { QRFile } from "../qr/types.js"; +import type { SubagentRole, StepSequence } from "../types.js"; +import { IntakePhase } from "./intake/phase.js"; +import { ScoutPhase } from "./scout/phase.js"; +import { DecomposerPhase } from "./decomposer/phase.js"; +import { OrchestratorPhase } from "./orchestrator/phase.js"; +import { PlannerPhase } from "./planner/phase.js"; +import { ExecutorPhase } from "./executor/phase.js"; + +// -- Config -- export interface SubagentConfig { - role: string; - phase: string; - planDir: string; + role: SubagentRole; + epicDir: string; subagentDir: string; - fix: string | null; -} - -type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; - -function parseWorkPhase(value: string | null): WorkPhaseKey | null { - if (value === "plan-design" || value === "plan-code" || value === "plan-docs") { - return value; - } - return null; + storyId: string | null; + stepSequence: StepSequence | null; } -function parseQRPhase(value: string): WorkPhaseKey | null { - if (!value.startsWith("qr-")) return null; - return parseWorkPhase(value.slice(3)); -} +// -- Detection -- -async function loadFixFailures(planDir: string, phase: WorkPhaseKey): Promise { - const qrPath = path.join(planDir, `qr-${phase}.json`); - try { - const raw = await fs.readFile(qrPath, "utf8"); - return JSON.parse(raw) as QRFile; - } catch { - return null; - } -} - -// Detects subagent mode by checking flags set via CLI (pi -p --koan-role -// architect --koan-phase plan-design ...). Flags are unavailable during -// init (getFlag() returns undefined before _buildRuntime()), so this -// must be called from before_agent_start or later. +// Detects subagent mode by reading flags set via CLI +// (pi -p --koan-role intake --koan-epic-dir /path ...). +// Must be called from before_agent_start or later; flags are +// undefined before _buildRuntime() runs. export function detectSubagentMode(pi: ExtensionAPI): SubagentConfig | null { const role = pi.getFlag("koan-role"); if (!role || typeof role !== "string" || role.trim().length === 0) { return null; } - const phase = pi.getFlag("koan-phase"); - const planDir = pi.getFlag("koan-plan-dir"); + const epicDir = pi.getFlag("koan-epic-dir"); const subagentDir = pi.getFlag("koan-subagent-dir"); - const fix = pi.getFlag("koan-fix"); + const storyId = pi.getFlag("koan-story-id"); + const stepSequence = pi.getFlag("koan-step-sequence"); return { - role: role.trim(), - phase: typeof phase === "string" ? phase.trim() : "", - planDir: typeof planDir === "string" ? planDir.trim() : "", + role: role.trim() as SubagentRole, + epicDir: typeof epicDir === "string" ? epicDir.trim() : "", subagentDir: typeof subagentDir === "string" ? subagentDir.trim() : "", - fix: typeof fix === "string" && fix.trim().length > 0 ? fix.trim() : null, + storyId: typeof storyId === "string" && storyId.trim().length > 0 ? storyId.trim() : null, + stepSequence: typeof stepSequence === "string" && stepSequence.trim().length > 0 + ? stepSequence.trim() as StepSequence + : null, }; } +// -- Dispatch -- + export async function dispatchPhase( pi: ExtensionAPI, config: SubagentConfig, - dispatch: WorkflowDispatch, - planRef: PlanRef, + ctx: RuntimeContext, log?: Logger, eventLog?: EventLog, ): Promise { const logger = log ?? createLogger("Dispatch"); - // -- Fix modes -- - - const fixPhase = parseWorkPhase(config.fix); - if (fixPhase) { - const qrFile = await loadFixFailures(config.planDir, fixPhase); - if (!qrFile) { - logger("Fix dispatch: failed to read QR file", { phase: fixPhase }); - return; + switch (config.role) { + case "intake": { + const phase = new IntakePhase(pi, { epicDir: config.epicDir }, ctx, logger, eventLog); + await phase.begin(); + break; } - - const failures = qrFile.items.filter((i) => i.status === "FAIL"); - if (failures.length === 0) { - logger("Fix dispatch: no FAIL items in QR file, skipping fix phase", { phase: fixPhase }); - return; + case "scout": { + const phase = new ScoutPhase(pi, { epicDir: config.epicDir }, ctx, logger, eventLog); + await phase.begin(); + break; } - - if (config.role === "architect" && fixPhase === "plan-design") { - const phase = new PlanDesignFixPhase( + case "decomposer": { + const phase = new DecomposerPhase(pi, { epicDir: config.epicDir }, ctx, logger, eventLog); + await phase.begin(); + break; + } + case "orchestrator": { + const stepSequence = config.stepSequence ?? "pre-execution"; + const phase = new OrchestratorPhase( pi, - { planDir: config.planDir, failures }, - dispatch, - planRef, - logger, - eventLog, + { epicDir: config.epicDir, stepSequence, storyId: config.storyId ?? undefined }, + ctx, logger, eventLog, ); await phase.begin(); - return; + break; } - - if (config.role === "developer" && fixPhase === "plan-code") { - const phase = new PlanCodeFixPhase( + case "planner": { + // Fail-fast: missing storyId produces malformed paths like stories//plan/plan.md (§12.4.3). + if (!config.storyId) throw new Error("planner phase requires --koan-story-id flag"); + const phase = new PlannerPhase( pi, - { planDir: config.planDir, failures }, - dispatch, - planRef, - logger, - eventLog, + { epicDir: config.epicDir, storyId: config.storyId }, + ctx, logger, eventLog, ); await phase.begin(); - return; + break; } - - if (config.role === "technical-writer" && fixPhase === "plan-docs") { - const phase = new PlanDocsFixPhase( + case "executor": { + // Fail-fast: missing storyId produces malformed paths like stories//plan/plan.md (§12.4.3). + if (!config.storyId) throw new Error("executor phase requires --koan-story-id flag"); + const retryContext = pi.getFlag("koan-retry-context"); + const phase = new ExecutorPhase( pi, - { planDir: config.planDir, failures }, - dispatch, - planRef, - logger, - eventLog, + { + epicDir: config.epicDir, + storyId: config.storyId, + retryContext: typeof retryContext === "string" && retryContext.length > 0 ? retryContext : undefined, + }, + ctx, logger, eventLog, ); await phase.begin(); - return; + break; } + default: + logger("Unknown role", { role: config.role }); } - - // -- Work phases -- - - if (config.role === "architect" && config.phase === "plan-design") { - const phase = new PlanDesignPhase( - pi, - { planDir: config.planDir }, - dispatch, - planRef, - logger, - eventLog, - ); - await phase.begin(); - return; - } - - if (config.role === "developer" && config.phase === "plan-code") { - const phase = new PlanCodePhase( - pi, - { planDir: config.planDir }, - dispatch, - planRef, - logger, - eventLog, - ); - await phase.begin(); - return; - } - - if (config.role === "technical-writer" && config.phase === "plan-docs") { - const phase = new PlanDocsPhase( - pi, - { planDir: config.planDir }, - dispatch, - planRef, - logger, - eventLog, - ); - await phase.begin(); - return; - } - - // -- QR phases -- - - const qrWorkPhase = parseQRPhase(config.phase); - if (config.role === "qr-decomposer" && qrWorkPhase) { - const phase = new QRDecomposePhase( - pi, - { planDir: config.planDir, workPhase: qrWorkPhase }, - dispatch, - planRef, - logger, - eventLog, - ); - await phase.begin(); - return; - } - - if (config.role === "reviewer" && qrWorkPhase) { - const rawItemFlag = pi.getFlag("koan-qr-item") as string; - if (!rawItemFlag) { - logger("Reviewer missing --koan-qr-item flag"); - return; - } - - const itemIds = rawItemFlag.split(",").map((s) => s.trim()).filter(Boolean); - if (itemIds.length === 0) { - logger("Reviewer --koan-qr-item flag is empty after parsing"); - return; - } - - const phase = new QRVerifyPhase( - pi, - { planDir: config.planDir, itemIds, workPhase: qrWorkPhase }, - dispatch, - planRef, - logger, - eventLog, - ); - await phase.begin(); - return; - } - - logger("Unknown role/phase combination", { - role: config.role, - phase: config.phase, - fix: config.fix, - }); } diff --git a/src/planner/phases/executor/phase.ts b/src/planner/phases/executor/phase.ts new file mode 100644 index 0000000..6ab7f05 --- /dev/null +++ b/src/planner/phases/executor/phase.ts @@ -0,0 +1,43 @@ +// Executor phase: implements a story plan. +// Two steps: comprehension → implementation. + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { createLogger, type Logger } from "../../../utils/logger.js"; +import type { RuntimeContext } from "../../lib/runtime-context.js"; +import { EventLog } from "../../lib/audit.js"; +import { BasePhase } from "../base-phase.js"; +import { EXECUTOR_STEP_NAMES, executorSystemPrompt, executorStepGuidance } from "./prompts.js"; +import type { StepGuidance } from "../../lib/step.js"; + +export class ExecutorPhase extends BasePhase { + protected readonly role = "executor"; + protected readonly totalSteps = 2; + + private readonly storyId: string; + private readonly retryContext: string | undefined; + + constructor( + pi: ExtensionAPI, + config: { epicDir: string; storyId: string; retryContext?: string }, + ctx: RuntimeContext, + log?: Logger, + eventLog?: EventLog, + ) { + super(pi, ctx, log ?? createLogger("ExecutorPhase"), eventLog); + this.storyId = config.storyId; + this.retryContext = config.retryContext; + } + + protected getSystemPrompt(): string { + return executorSystemPrompt(); + } + + protected getStepName(step: number): string { + return EXECUTOR_STEP_NAMES[step] ?? `Step ${step}`; + } + + protected getStepGuidance(step: number): StepGuidance { + return executorStepGuidance(step, this.storyId, this.retryContext); + } +} diff --git a/src/planner/phases/executor/prompts.ts b/src/planner/phases/executor/prompts.ts new file mode 100644 index 0000000..b27bf14 --- /dev/null +++ b/src/planner/phases/executor/prompts.ts @@ -0,0 +1,156 @@ +import type { StepGuidance } from "../../lib/step.js"; + +export const EXECUTOR_STEP_NAMES: Record = { + 1: "Comprehension", + 2: "Implementation", +}; + +export function executorSystemPrompt(): string { + return `You are a coding agent. You implement changes to a codebase by following a detailed plan written by a planner. You are the only agent in the koan workflow that writes source code. + +## Your role + +You receive a plan (plan/plan.md) and supporting context (plan/context.md), and you implement each step in order. You do not design. You do not make architectural decisions. You execute the plan faithfully. + +## What you receive + +- **plan/plan.md**: A numbered list of implementation steps. Each step specifies the file, location, action, and exact change to make. +- **plan/context.md**: Curated code snippets for the files you will modify — function signatures, type definitions, and import blocks. +- **retryContext** (when present): A failure summary from a previous execution attempt. Read it carefully — it describes what went wrong and what you should do differently. + +## How to work + +Work through the plan steps in order. Before touching any file: + +1. Read the file to understand its current state. Plan/context.md is a snapshot; the file may have changed due to earlier steps in this execution. +2. Identify exactly where the change goes. +3. Make the change precisely — no more, no less. +4. Verify the change looks correct before moving on. + +## When plan and reality diverge + +If what you find in the codebase does not match what the plan describes — the function doesn't exist, the signature is different, the file structure changed — you MUST stop immediately and call \`koan_ask_question\`. Do not improvise a solution. Do not make assumptions. + +Describe: +- Which plan step you are on +- What the plan expected to find +- What you actually found +- What you need to know to proceed + +Improvised solutions that seem reasonable in isolation frequently break other parts of the system that are not visible in your context window. + +## Strict rules — violations cause retry cycles + +- MUST implement steps in the order specified by the plan. +- MUST NOT skip any step, even if it seems redundant. +- MUST NOT add features, functions, or logic that the plan does not specify. +- MUST NOT refactor code that the plan does not mention — even if you notice an improvement opportunity. +- MUST NOT modify test expectations to make tests pass. If a test fails after your implementation, report it via koan_ask_question. +- MUST read each file before modifying it. Context.md is a reference, not a guarantee of current state. +- MUST call koan_ask_question immediately when plan assumptions don't hold. Do not continue to the next step. + +## On retries + +If retryContext is present, this is your second (or later) attempt at this story. The failure summary tells you what went wrong. Read it before you read the plan, and keep the failure context in mind as you implement. Do not repeat the mistake from the previous attempt. + +You work in steps. Each step has specific instructions. Follow them precisely.`; +} + +export function executorStepGuidance(step: number, storyId: string, retryContext?: string): StepGuidance { + switch (step) { + case 1: + return { + title: EXECUTOR_STEP_NAMES[1], + instructions: [ + `Read and fully understand the implementation plan for story \`${storyId}\` before writing any code.`, + "", + "## What to read", + "", + `1. Read \`stories/${storyId}/plan/plan.md\` — read every step from start to finish. Do not skim.`, + `2. Read \`stories/${storyId}/plan/context.md\` — understand the function signatures, types, and imports for every file the plan touches.`, + ...(retryContext + ? [ + "", + "## Retry context — read this first", + "", + "This is a retry attempt. A previous execution of this story failed. The failure summary is:", + "", + retryContext, + "", + "Keep this failure context in mind as you read the plan. Identify which step caused the failure and what you will do differently.", + ] + : []), + "", + "## What to understand", + "", + "After reading, you must be able to answer these questions without referring back to the files:", + "", + "- How many steps are in the plan?", + "- Which files will you modify?", + "- What is the dependency order between steps?", + "- Are there any steps that touch the same file (potential ordering conflicts)?", + "- What types or interfaces are central to the changes?", + "", + "Do NOT start writing code in this step. Comprehension only.", + "", + "Call koan_complete_step with your comprehension summary:", + "- Number of steps", + "- List of files to modify", + "- Any ambiguities or concerns you spotted in the plan (do not block on these — note them)", + ...(retryContext ? ["- How you plan to avoid the previous failure"] : []), + ], + }; + + case 2: + return { + title: EXECUTOR_STEP_NAMES[2], + instructions: [ + `Implement the plan for story \`${storyId}\` step by step.`, + "", + "## Execution protocol", + "", + "Work through plan/plan.md in order. For each step:", + "", + "1. **Read the target file** — do not rely solely on context.md; read the actual current state of the file.", + "2. **Locate the change site** — find the exact function, class, or section described in the plan step.", + "3. **Verify your assumption** — confirm that what you find matches what the plan describes. If it does not match, call koan_ask_question immediately.", + "4. **Make the change** — implement exactly what the plan step specifies. No more, no less.", + "5. **Move to the next step** — do not review or revisit previous steps.", + "", + "## Plan-reality mismatch protocol", + "", + "If at any point the codebase does not match the plan's description:", + "", + "- STOP immediately. Do not attempt to adapt the plan.", + "- Call `koan_ask_question` with:", + " - The plan step number and description", + " - What the plan expected", + " - What you actually found", + " - What specific information you need to proceed", + "", + "## Common pitfalls", + "", + "- Do not add logging, error handling, or validation beyond what the plan specifies.", + "- Do not fix code style issues you notice in passing.", + "- Do not update imports for files not mentioned in the plan.", + "- Do not change test files unless a plan step explicitly says to.", + "- Do not run the tests yourself — the orchestrator will verify.", + "", + "## When all steps are complete", + "", + "Review your changes at a high level: are all plan steps implemented? Did you accidentally modify something you shouldn't have? Correct any accidental changes.", + "", + "Then call koan_complete_step with a summary of what you implemented:", + "- Each plan step: completed or skipped (with reason if skipped)", + "- Files modified", + "- Any concerns or observations for the orchestrator", + ], + }; + + default: + return { + title: `Step ${step}`, + instructions: [`Execute step ${step}.`], + }; + } +} diff --git a/src/planner/phases/intake/phase.ts b/src/planner/phases/intake/phase.ts new file mode 100644 index 0000000..5ef4d79 --- /dev/null +++ b/src/planner/phases/intake/phase.ts @@ -0,0 +1,43 @@ +// Intake phase: reads conversation, extracts context, requests scouts, +// identifies gaps, asks user questions, writes context.md and decisions.md. +// Three-step sequence per §11.2.2. + +import * as path from "node:path"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { createLogger, type Logger } from "../../../utils/logger.js"; +import type { RuntimeContext } from "../../lib/runtime-context.js"; +import { EventLog } from "../../lib/audit.js"; +import { BasePhase } from "../base-phase.js"; +import { INTAKE_STEP_NAMES, intakeSystemPrompt, intakeStepGuidance } from "./prompts.js"; +import type { StepGuidance } from "../../lib/step.js"; + +export class IntakePhase extends BasePhase { + protected readonly role = "intake"; + protected readonly totalSteps = 3; + + private readonly conversationPath: string; + + constructor( + pi: ExtensionAPI, + config: { epicDir: string }, + ctx: RuntimeContext, + log?: Logger, + eventLog?: EventLog, + ) { + super(pi, ctx, log ?? createLogger("IntakePhase"), eventLog); + this.conversationPath = path.join(config.epicDir, "conversation.jsonl"); + } + + protected getSystemPrompt(): string { + return intakeSystemPrompt(); + } + + protected getStepName(step: number): string { + return INTAKE_STEP_NAMES[step] ?? `Step ${step}`; + } + + protected getStepGuidance(step: number): StepGuidance { + return intakeStepGuidance(step, this.conversationPath); + } +} diff --git a/src/planner/phases/intake/prompts.ts b/src/planner/phases/intake/prompts.ts new file mode 100644 index 0000000..80161f4 --- /dev/null +++ b/src/planner/phases/intake/prompts.ts @@ -0,0 +1,183 @@ +// Intake phase prompts — 3-step sequence per §11.2.2: +// Step 1: Context extraction (read conversation → write context.md) +// Step 2: Codebase scouting (call koan_request_scouts with targeted questions) +// Step 3: Gap analysis + questions (review findings → ask user → write decisions.md) + +import type { StepGuidance } from "../../lib/step.js"; + +export const INTAKE_STEP_NAMES: Record = { + 1: "Context Extraction", + 2: "Codebase Scouting", + 3: "Gap Analysis & Questions", +}; + +export function intakeSystemPrompt(): string { + return `You are an intake analyst for a coding task planner. You read a conversation history, extract structured context, explore the codebase via scouts, and ask the user targeted clarifying questions grounded in both the conversation and what actually exists in the codebase. + +## Your role + +You extract and organize information. You do NOT plan, design, or implement. + +## Strict rules — violations invalidate your output + +- MUST NOT infer decisions that were not explicitly stated in the conversation. +- MUST NOT add architectural opinions or suggest approaches. +- MUST NOT summarize, paraphrase, or analyze code beyond extracting factual references. +- MUST NOT produce implementation recommendations of any kind. +- MUST only capture what was explicitly said. If something is unclear, note it as an unresolved question. +- MUST ask at most 8 questions total. Prioritize the most important gaps. +- SHOULD prefer multiple-choice questions when the answer space is bounded. +- SHOULD ask open-ended questions only when the space of valid answers is genuinely unbounded. +- SHOULD ask questions grounded in what you found in the codebase (e.g., "the codebase uses X — should this story follow the same pattern or switch to Y?"). + +## Output files + +You write two files, both inside the epic directory: + +1. **context.md** — structured extraction of what was said in the conversation. +2. **decisions.md** — answers to the questions you asked the user. + +## Tools available + +- All read tools (read, bash, grep, glob, find, ls) — for reading the conversation and codebase. +- \`koan_request_scouts\` — to request parallel codebase exploration. +- \`koan_ask_question\` — to ask the user clarifying questions via IPC. +- \`write\` / \`edit\` — for writing output files inside the epic directory only. +- \`koan_complete_step\` — to signal step completion with your findings. + +You work in three steps. Each step has specific instructions. Follow them precisely.`; +} + +export function intakeStepGuidance(step: number, conversationPath?: string): StepGuidance { + switch (step) { + case 1: + return { + title: INTAKE_STEP_NAMES[1], + instructions: [ + "Read the conversation file and extract structured context into `context.md`.", + "", + conversationPath + ? `Conversation file: ${conversationPath}` + : "Conversation file: locate `conversation.jsonl` in the epic directory.", + "", + "The conversation file is JSONL (JSON Lines). Each line is a JSON object.", + "Look for entries with type 'message' and role 'user' or 'assistant' for content.", + "Ignore internal session entries (header, compaction, etc.).", + "", + "Write `context.md` to the epic directory with these exact sections:", + "", + "## Topic", + "One paragraph describing what is being built or changed. Use only information explicitly stated in the conversation.", + "", + "## File References", + "List every file, directory, or module mentioned in the conversation. One item per line.", + "If none were mentioned, write: (none mentioned)", + "", + "## Decisions Made", + "List every decision that was explicitly stated and agreed upon. Format: `- [decision text]`", + "A decision must be explicitly stated — do not infer from context.", + "If none were made, write: (none recorded)", + "", + "## Constraints", + "List every explicit constraint: technical, timeline, compatibility, budget, etc.", + "If none were stated, write: (none stated)", + "", + "## Unresolved Questions", + "List every question raised in the conversation that was NOT answered.", + "Also list any gaps you observe — things that must be known before planning can proceed.", + "Format: `- [question or gap description]`", + "", + "Be faithful to the conversation. Do not invent context.", + ], + }; + + case 2: + return { + title: INTAKE_STEP_NAMES[2], + instructions: [ + "Based on the file references and topic in context.md, identify what needs codebase exploration.", + "", + "Use `koan_request_scouts` to gather codebase context before asking the user questions.", + "This grounds the questions in what actually exists — preventing questions the codebase already answers.", + "", + "## When to scout", + "", + "Scout when context.md mentions:", + "- Specific files, modules, or packages that should be verified or understood.", + "- Integration points with existing code (APIs, databases, auth, etc.).", + "- Areas where the user's assumptions may not match the codebase (e.g., 'we use React' but you should verify).", + "", + "Formulate 1–5 focused scout tasks. Each scout answers one narrow question.", + "", + "## Scout task format", + "", + "Each scout needs:", + "- id: short kebab-case identifier (e.g., 'auth-setup', 'api-structure')", + "- role: a focused investigator role (e.g., 'auth system auditor', 'API structure analyst')", + "- prompt: exactly what to find (e.g., 'Find all auth-related files and identify which auth library is used')", + "", + "## If no scouting is needed", + "", + "If context.md has no file references and the topic is purely conceptual (no codebase inspection needed),", + "skip scouting and call koan_complete_step with: 'Scouting skipped — no codebase references in context.'", + ], + }; + + case 3: + return { + title: INTAKE_STEP_NAMES[3], + instructions: [ + "Review `context.md` and scout findings together. Identify gaps. Ask the user. Write `decisions.md`.", + "", + "## Gap identification criteria", + "", + "Ask about a gap if:", + "- The answer materially changes WHAT is built (scope, features, API shape).", + "- The answer materially changes HOW the work is sequenced (dependencies, ordering).", + "- Without the answer, the decomposer cannot split the work into stories.", + "- Scout findings reveal a contradiction with what the user described (e.g., user said 'we use Postgres' but scout found SQLite).", + "", + "Do NOT ask about:", + "- Implementation choices (those belong to the planner role).", + "- Things the scout findings already answered.", + "- Nice-to-have clarifications that don't change the plan.", + "", + "## Asking questions", + "", + "Use `koan_ask_question` to send questions to the user. Maximum 8 questions.", + "Prefer multiple-choice when the answer space is bounded.", + "Reference scout findings in questions when relevant: 'The codebase uses X — should this follow the same pattern?'", + "", + "## Writing decisions.md", + "", + "After the user responds, write `decisions.md` to the epic directory:", + "", + "## Answers", + "For each question asked, record the question and the user's answer.", + "Format:", + "```", + "**Q: [question text]**", + "A: [user's answer]", + "```", + "", + "## Remaining Unknowns", + "List any gaps that remain unresolved. If none: write (none)", + "", + "If there were no meaningful gaps, write:", + "`## Answers\\n(no questions were needed — context and codebase survey were sufficient)`", + "", + "Then call `koan_complete_step` with a brief summary:", + "- File references found", + "- Scouts requested and key findings", + "- Questions asked and answered", + "- Any remaining unknowns", + ], + }; + + default: + return { + title: `Step ${step}`, + instructions: [`Execute step ${step}.`], + }; + } +} diff --git a/src/planner/phases/orchestrator/phase.ts b/src/planner/phases/orchestrator/phase.ts new file mode 100644 index 0000000..5629e7b --- /dev/null +++ b/src/planner/phases/orchestrator/phase.ts @@ -0,0 +1,60 @@ +// Orchestrator phase: judgment calls at execution boundaries. +// Two step sequences: pre-execution (2 steps) and post-execution (4 steps). +// koan_escalate is eliminated — orchestrator uses koan_ask_question for all +// user communication and then calls appropriate state-transition tools. + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { createLogger, type Logger } from "../../../utils/logger.js"; +import type { RuntimeContext } from "../../lib/runtime-context.js"; +import { EventLog } from "../../lib/audit.js"; +import { BasePhase } from "../base-phase.js"; +import { + ORCHESTRATOR_PRE_STEP_NAMES, + ORCHESTRATOR_POST_STEP_NAMES, + orchestratorSystemPrompt, + orchestratorPreStepGuidance, + orchestratorPostStepGuidance, +} from "./prompts.js"; +import type { StepGuidance } from "../../lib/step.js"; + +const PRE_TOTAL_STEPS = 2; +const POST_TOTAL_STEPS = 4; + +export class OrchestratorPhase extends BasePhase { + protected readonly role = "orchestrator"; + protected readonly totalSteps: number; + + private readonly stepSequence: "pre-execution" | "post-execution"; + private readonly storyId: string | undefined; + + constructor( + pi: ExtensionAPI, + config: { epicDir: string; stepSequence: "pre-execution" | "post-execution"; storyId?: string }, + ctx: RuntimeContext, + log?: Logger, + eventLog?: EventLog, + ) { + super(pi, ctx, log ?? createLogger("OrchestratorPhase"), eventLog); + this.stepSequence = config.stepSequence; + this.storyId = config.storyId; + this.totalSteps = config.stepSequence === "pre-execution" ? PRE_TOTAL_STEPS : POST_TOTAL_STEPS; + } + + protected getSystemPrompt(): string { + return orchestratorSystemPrompt(this.stepSequence); + } + + protected getStepName(step: number): string { + const names = this.stepSequence === "pre-execution" + ? ORCHESTRATOR_PRE_STEP_NAMES + : ORCHESTRATOR_POST_STEP_NAMES; + return names[step] ?? `Step ${step}`; + } + + protected getStepGuidance(step: number): StepGuidance { + return this.stepSequence === "pre-execution" + ? orchestratorPreStepGuidance(step) + : orchestratorPostStepGuidance(step, this.storyId); + } +} diff --git a/src/planner/phases/orchestrator/prompts.ts b/src/planner/phases/orchestrator/prompts.ts new file mode 100644 index 0000000..15c5db3 --- /dev/null +++ b/src/planner/phases/orchestrator/prompts.ts @@ -0,0 +1,299 @@ +// Orchestrator phase prompts. +// Pre-execution (2 steps): dependency analysis → story selection. +// Post-execution (4 steps): verify → verdict → propagate → select next. +// +// koan_escalate is eliminated per §11.3.1. When the orchestrator needs human +// input, it uses koan_ask_question to get clarification, then decides what +// to do (retry, skip, etc.) and calls the appropriate state-transition tool. + +import type { StepGuidance } from "../../lib/step.js"; + +export const ORCHESTRATOR_PRE_STEP_NAMES: Record = { + 1: "Dependency Analysis", + 2: "Story Selection", +}; + +export const ORCHESTRATOR_POST_STEP_NAMES: Record = { + 1: "Verify", + 2: "Verdict", + 3: "Propagate", + 4: "Select Next", +}; + +export function orchestratorSystemPrompt(stepSequence: string): string { + const sequenceFocus = + stepSequence === "pre-execution" + ? "You are beginning an epic run. Analyze story dependencies and select the first story for execution." + : "Execution has just completed for a story. Verify the result, issue a verdict, propagate learnings, and select the next story."; + + return `You are a workflow orchestrator for a multi-story coding epic. You make judgment calls at execution boundaries — before and after each coding story runs. ${sequenceFocus} + +## Important: status.md may be stale + +Do not rely on \`status.md\` for current story state. The driver sets intermediate statuses (\`planning\`, \`executing\`, \`verifying\`) in its internal JSON state only — \`status.md\` is only updated by orchestrator tool calls (\`koan_select_story\`, \`koan_complete_story\`, etc.). Your authoritative inputs are \`verify.md\`, \`plan.md\`, git diff, and \`epic.md\` — not \`status.md\`. + +## Your role + +You are a decision-maker. You read content, apply judgment, and direct the workflow. You do NOT write code. You do NOT modify source code files. You do NOT produce implementation plans. + +## What you own + +- **Verification**: Running the checks defined in a story's verify.md to determine whether the implementation is correct. +- **Verdict**: Declaring the outcome of a story's execution — success or retry with feedback. +- **Story selection**: Choosing which story executes next based on the dependency graph and current epic state. +- **Learning propagation**: When you discover something during verification, update remaining story.md files and decisions.md. Mark every autonomous update with \`[autonomous]\`. +- **User communication**: When you encounter genuine ambiguity or need human judgment, call \`koan_ask_question\`. After getting the answer, decide what to do (retry with new context, skip, etc.) and call the appropriate tool. + +## When to ask the user + +Call \`koan_ask_question\` when: +- Verification reveals an ambiguity in requirements that cannot be resolved by reading the code. +- A story fails in a way that suggests the spec was wrong, not the implementation. +- You need human judgment on whether to retry, skip, or take a different approach. + +After getting the answer, record it and proceed with an appropriate tool call: +- \`koan_retry_story\` — if the user provided direction that lets you retry with a better plan +- \`koan_skip_story\` — if the user decided the story is no longer needed +- \`koan_complete_story\` — if the user confirmed the outcome is acceptable + +## Tools available + +- All read tools (read, bash, grep, glob, find, ls) — for reading epic artifacts and running verification checks. +- \`koan_select_story\` — to declare which story should execute next. +- \`koan_complete_story\` — to mark a story as successfully verified and completed. +- \`koan_retry_story\` — to send a story back to the executor with a detailed failure summary. +- \`koan_skip_story\` — to skip a story that is superseded or no longer needed. +- \`koan_ask_question\` — to ask the human a targeted question when judgment is genuinely ambiguous. +- \`koan_complete_step\` — to signal step completion with your findings. +- \`write\` / \`edit\` — for updating artifact files inside the epic directory only. +- \`bash\` — for running verification commands. + +## The [autonomous] marker + +When you make a decision that modifies artifacts without explicit human instruction, prefix the added content with \`[autonomous]\` in the artifact file. This lets the human audit all autonomous decisions. + +## Strict rules + +- MUST NOT write or modify source code files. +- MUST NOT call more than one verdict tool per verdict step. +- MUST run ALL verification checks in verify.md before issuing a verdict. +- MUST include a concrete, actionable failure summary when calling koan_retry_story. +- When uncertain about a verdict, prefer koan_retry_story with a detailed failure_summary. Ask the user only when the failure reveals a genuine requirements ambiguity. + +You work in steps. Each step has specific instructions. Follow them precisely.`; +} + +export function orchestratorPreStepGuidance(step: number): StepGuidance { + switch (step) { + case 1: + return { + title: ORCHESTRATOR_PRE_STEP_NAMES[1], + instructions: [ + "Read the epic artifacts to understand the full scope of work and story dependencies.", + "", + "## What to read", + "", + "1. Read `epic.md` in the epic directory — understand the overall goal and scope.", + "2. Read `decisions.md` in the epic directory — understand decisions that shape execution.", + "3. Read each `story.md` file for every story in the epic — understand what each story builds and depends on.", + "", + "## What to analyze", + "", + "After reading, build a dependency model:", + "- Which stories must complete before others can begin? (explicit dependencies)", + "- Which stories share files or interfaces? (implicit coupling)", + "- Which stories are independent and could run in any order?", + "- Are there any circular dependencies or unresolvable conflicts?", + "", + "Note the risk profile of each story: stories that touch shared infrastructure are higher risk.", + "", + "## Output", + "", + "Call koan_complete_step with your dependency analysis in the `thoughts` parameter. Include:", + "- The execution order you recommend and why", + "- Any risks or concerns you identified", + "- The ID of the story you believe should run first", + ], + }; + + case 2: + return { + title: ORCHESTRATOR_PRE_STEP_NAMES[2], + instructions: [ + "Select the first story for execution based on your dependency analysis from step 1.", + "", + "## Selection criteria", + "", + "Choose the story that:", + "1. Has all its dependencies satisfied (no blockers)", + "2. Is highest priority given the epic's goal", + "3. Creates the most unblocking value for subsequent stories if completed", + "", + "Prefer foundational stories (shared types, interfaces, infrastructure) over leaf stories.", + "", + "## What to do", + "", + "Call `koan_select_story` with the ID of the story that should execute first.", + "Then call `koan_complete_step` with your reasoning.", + ], + invokeAfter: [ + "WHEN DONE: Call koan_select_story with your chosen story ID, then call koan_complete_step with your reasoning.", + "Do NOT call koan_complete_step until koan_select_story has been called.", + ].join("\n"), + }; + + default: + return { title: `Step ${step}`, instructions: [`Execute step ${step}.`] }; + } +} + +export function orchestratorPostStepGuidance(step: number, storyId?: string): StepGuidance { + const storyRef = storyId ? `story \`${storyId}\`` : "the current story"; + const verifyPath = storyId ? `stories/${storyId}/plan/verify.md` : "stories//plan/verify.md"; + + switch (step) { + case 1: + return { + title: ORCHESTRATOR_POST_STEP_NAMES[1], + instructions: [ + `Run all verification checks defined for ${storyRef}.`, + "", + "## What to read", + "", + `1. Read \`${verifyPath}\` in the epic directory — every check you must run.`, + "2. Read the story's `story.md` to understand the acceptance criteria.", + "", + "## Running checks", + "", + "Execute every check listed in verify.md using bash. Do not skip checks.", + "", + "- Run compilation/type checks first (cheapest).", + "- Run linting and static analysis next.", + "- Run unit and integration tests last (most expensive).", + "", + "For each check, record:", + "- The exact command you ran", + "- The exit code", + "- Relevant output (errors, failures, warnings)", + "", + "## Output", + "", + "Call koan_complete_step with your verification findings:", + "- A summary of every check run and its result (pass/fail)", + "- The full error output for any failures", + "- Your preliminary assessment: does the implementation appear correct?", + ], + }; + + case 2: + return { + title: ORCHESTRATOR_POST_STEP_NAMES[2], + instructions: [ + "Issue a verdict based on your verification findings from step 1.", + "", + "## Verdict options", + "", + "**koan_complete_story** — All verification checks passed. The implementation is correct.", + "", + "**koan_retry_story** — Verification failed, but the failure is fixable by the executor.", + "MUST provide a detailed `failure_summary` that includes:", + " - Which checks failed and why", + " - The exact error messages", + " - What the executor should do differently", + "", + "**koan_ask_question then decide** — The failure reveals a genuine requirements ambiguity.", + "Ask the user a focused question. Based on the answer:", + " - Call koan_retry_story with the user's direction as context", + " - Call koan_skip_story if the user decides the story is no longer needed", + " - Call koan_complete_story if the user confirms the outcome is acceptable", + "", + "## Decision rule", + "", + "If any check failed AND the failure is a concrete code bug → koan_retry_story.", + "If any check failed AND the failure reveals a requirements contradiction → koan_ask_question then decide.", + "If all checks passed → koan_complete_story.", + "", + "Call EXACTLY ONE verdict tool (after any koan_ask_question).", + ], + invokeAfter: [ + "WHEN DONE: Call EXACTLY ONE of: koan_complete_story, koan_retry_story, or (koan_ask_question then verdict tool).", + "Then call koan_complete_step to advance to the next step.", + ].join("\n"), + }; + + case 3: + return { + title: ORCHESTRATOR_POST_STEP_NAMES[3], + instructions: [ + "Propagate lessons from this story's execution to remaining stories and the decisions log.", + "", + "## What to propagate", + "", + "Review what you learned from verification (step 1) and the verdict (step 2):", + "- Did the executor encounter something that affects remaining stories?", + "- Did verification reveal an incorrect assumption in a remaining story's plan?", + "- Did the implementation introduce a pattern remaining stories should follow?", + "", + "Only propagate information directly relevant to remaining stories.", + "", + "## How to propagate", + "", + "For each remaining story that is affected:", + "1. Read its `story.md`.", + "2. Add a `## [autonomous] Propagated Context` section with the relevant information.", + "", + "Update `decisions.md` if a new decision was made or an existing one was invalidated.", + "Add `[autonomous]` prefix to any autonomous additions.", + "", + "If no propagation is needed, skip file updates and proceed.", + "", + "## Skipping stories", + "", + "If this story's completion makes another story unnecessary, call `koan_skip_story` with a clear reason.", + "", + "Then call koan_complete_step with a summary of what was propagated.", + ], + }; + + case 4: + return { + title: ORCHESTRATOR_POST_STEP_NAMES[4], + instructions: [ + "Select the next story to execute, or complete the epic if all stories are done.", + "", + "## What to check", + "", + "Read each story directory to understand which stories remain:", + "- Stories with `pending` or `retry` status are candidates.", + "- Done, skipped, or currently-selected stories are not candidates.", + "", + "## Selection criteria", + "", + "Among remaining stories:", + "1. Filter to those whose dependencies are all completed.", + "2. Among unblocked stories, prefer the one with highest value.", + "3. A story in 'retry' state is highest priority — it was already planned and executed.", + "", + "## What to do", + "", + "If one or more stories remain and are unblocked:", + "- Call `koan_select_story` with the ID of the next story.", + "- Then call `koan_complete_step` with your reasoning.", + "", + "If no stories remain (all completed or skipped):", + "- Call `koan_complete_step` with a summary stating the epic is complete.", + " Do NOT call koan_select_story.", + "", + "If stories remain but all are blocked (dependencies not satisfied):", + "- Call `koan_ask_question` to ask the user how to proceed (reorder, skip, or abort).", + " Based on the answer, call the appropriate tool.", + ], + invokeAfter: [ + "WHEN DONE: If stories remain, call koan_select_story then koan_complete_step. If none remain, call koan_complete_step only.", + ].join("\n"), + }; + + default: + return { title: `Step ${step}`, instructions: [`Execute step ${step}.`] }; + } +} diff --git a/src/planner/phases/planner/phase.ts b/src/planner/phases/planner/phase.ts new file mode 100644 index 0000000..4a0c5d6 --- /dev/null +++ b/src/planner/phases/planner/phase.ts @@ -0,0 +1,41 @@ +// Planner phase: produces the detail plan for a single story. +// Three steps: analysis → plan → verification design. + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { createLogger, type Logger } from "../../../utils/logger.js"; +import type { RuntimeContext } from "../../lib/runtime-context.js"; +import { EventLog } from "../../lib/audit.js"; +import { BasePhase } from "../base-phase.js"; +import { PLANNER_STEP_NAMES, plannerSystemPrompt, plannerStepGuidance } from "./prompts.js"; +import type { StepGuidance } from "../../lib/step.js"; + +export class PlannerPhase extends BasePhase { + protected readonly role = "planner"; + protected readonly totalSteps = 3; + + private readonly storyId: string; + + constructor( + pi: ExtensionAPI, + config: { epicDir: string; storyId: string }, + ctx: RuntimeContext, + log?: Logger, + eventLog?: EventLog, + ) { + super(pi, ctx, log ?? createLogger("PlannerPhase"), eventLog); + this.storyId = config.storyId; + } + + protected getSystemPrompt(): string { + return plannerSystemPrompt(); + } + + protected getStepName(step: number): string { + return PLANNER_STEP_NAMES[step] ?? `Step ${step}`; + } + + protected getStepGuidance(step: number): StepGuidance { + return plannerStepGuidance(step, this.storyId); + } +} diff --git a/src/planner/phases/planner/prompts.ts b/src/planner/phases/planner/prompts.ts new file mode 100644 index 0000000..b7d77f9 --- /dev/null +++ b/src/planner/phases/planner/prompts.ts @@ -0,0 +1,213 @@ +import type { StepGuidance } from "../../lib/step.js"; + +export const PLANNER_STEP_NAMES: Record = { + 1: "Analysis", + 2: "Plan", + 3: "Verification Design", +}; + +export function plannerSystemPrompt(): string { + return `You are an implementation planner for a single coding story. You produce a detailed, step-by-step plan that a coding agent can execute without making judgment calls. You bridge the gap between high-level story intent and concrete implementation actions. + +## Your role + +You read stories, codebase artifacts, and scout reports, then produce three output files: a step-by-step plan, a curated code context file, and a verification checklist. You do NOT write code. You do NOT make design decisions beyond what the story and decisions log specify. + +## What you produce + +### plan/plan.md — Step-by-step implementation plan + +Each step must specify: +- **Which file** to modify or create (full path from repo root) +- **Which function, class, or section** within that file +- **What change** to make (add, modify, delete, rename, restructure) +- **Why** this change is needed (link to story requirement or constraint) +- **Dependencies** between steps (e.g., "Step 3 requires step 1 to complete first") + +Steps must be ordered to minimize conflicts. Implement foundational changes before dependent ones. Leaf dependencies before callers. + +Be precise enough that a coding agent can execute each step without asking questions. Vague steps ("update the handler") produce retry cycles. Precise steps ("add parameter \`timeout: number\` to the \`fetchUser\` function signature in \`src/api/users.ts\`, update all call sites in \`src/routes/auth.ts\` and \`src/routes/profile.ts\`") do not. + +### plan/context.md — Curated code context + +Include only the code the executor needs to understand what it is modifying: +- Function signatures for every function the plan touches +- Relevant type definitions and interfaces +- Import statements that must be preserved or updated +- Key constants or configuration values that affect the changes +- Do NOT include boilerplate, unrelated functions, or documentation blocks + +### plan/verify.md — Verification checklist + +List every check the orchestrator should run after execution, ordered cheap to expensive: +1. Compilation checks (tsc --noEmit, build commands) +2. Linting and type checks +3. Unit tests for affected modules +4. Integration or end-to-end tests + +Each check entry must include: +- A description of what it verifies +- The exact command to run (with arguments) +- What a passing result looks like + +## Strict rules — violations cause execution failures + +- MUST NOT write source code. Plan steps describe actions; they do not contain implementation. +- MUST NOT plan beyond the current story's scope. If a step would touch something not in the story, flag it as out-of-scope. +- MUST NOT make architectural decisions. If a decision is needed that is outside the planner's scope, note it in plan.md as: \`BLOCKER: [description]. The orchestrator will ask the user via koan_ask_question during verification.\` +- MUST include enough detail that the executor can implement the plan in one pass without guessing. +- MUST scope plan/context.md to only what the executor needs — context files that include too much code obscure the relevant parts. + +You work in steps. Each step has specific instructions. Follow them precisely.`; +} + +export function plannerStepGuidance(step: number, storyId: string): StepGuidance { + switch (step) { + case 1: + return { + title: PLANNER_STEP_NAMES[1], + instructions: [ + `Analyze all available context for story \`${storyId}\` before producing any plan output.`, + "", + "## Request fresh codebase scouts", + "", + "Before analyzing the story, use `koan_request_scouts` to explore the current state of files this story will touch. Codebase state may have changed since earlier scouts. Request scouts for the specific files and patterns mentioned in the story sketch.", + "", + "## What to read", + "", + `1. Read \`stories/${storyId}/story.md\` in the epic directory — understand exactly what this story must accomplish, its acceptance criteria, and any noted constraints or dependencies.`, + "2. Read `decisions.md` in the epic directory — understand the architectural decisions and open questions that apply to this story. If a decision is marked as unresolved, check whether it blocks this story.", + "3. Read the scout reports returned by `koan_request_scouts` for current codebase context.", + "", + "## What to analyze", + "", + "After reading, build a complete picture of the work:", + "", + "- **Scope**: What exactly must change? What must NOT change?", + "- **Entry points**: Which files, functions, or modules are the primary change sites?", + "- **Ripple effects**: What else must be updated because of the primary changes? (callers, types, tests, exports)", + "- **Constraints**: Are there patterns from the codebase the executor must follow? (naming conventions, error handling style, module structure)", + "- **Risks**: Which steps are most likely to cause conflicts or unexpected issues?", + "", + "## Output", + "", + "Call koan_complete_step with your analysis in the `thoughts` parameter. Include:", + "- The list of files that will be modified or created", + "- The sequence you plan for the steps (high-level)", + "- Any risks or unresolved questions you identified", + "- Whether any open decisions in decisions.md block this story", + ], + }; + + case 2: + return { + title: PLANNER_STEP_NAMES[2], + instructions: [ + `Write the implementation plan and code context for story \`${storyId}\`.`, + "", + "## Write plan/plan.md", + "", + `Create \`stories/${storyId}/plan/plan.md\` in the epic directory with a numbered list of implementation steps.`, + "", + "Each step must follow this format:", + "```", + "## Step N: [Short title]", + "", + "**File**: path/to/file.ts", + "**Location**: function name, class name, or section description", + "**Action**: [add | modify | delete | create | rename]", + "", + "[Precise description of what to change and why. Include exact parameter names,", + "type signatures, return values, or behavioral changes. Be specific enough that", + "the executor does not need to make any judgment calls.]", + "", + "**Depends on**: Step N (if applicable)", + "```", + "", + "Order steps so each step's dependencies are satisfied before it runs.", + "Prefer: type changes → interface updates → implementation changes → call-site updates → test updates.", + "", + "## Write plan/context.md", + "", + `Create \`stories/${storyId}/plan/context.md\` with curated code snippets the executor needs.`, + "", + "Structure by file, then by section within the file:", + "```", + "## path/to/file.ts", + "", + "### FunctionName (lines N–M)", + "\\`\\`\\`typescript", + "// paste the relevant function signature and key lines only", + "\\`\\`\\`", + "```", + "", + "Include:", + "- Every function signature the plan references", + "- Type definitions that the changes touch", + "- Import blocks for files being modified", + "- Constants or configuration values referenced in plan steps", + "", + "Exclude:", + "- Unrelated functions and classes", + "- Long function bodies (include signature + key lines only)", + "- Documentation blocks and comments unless they carry critical constraint information", + "", + "Call koan_complete_step with a summary: number of plan steps, files affected, and any risks you flagged in the plan.", + ], + }; + + case 3: + return { + title: PLANNER_STEP_NAMES[3], + instructions: [ + `Write the verification checklist for story \`${storyId}\`.`, + "", + `Create \`stories/${storyId}/plan/verify.md\` in the epic directory. This file will be used by the orchestrator to verify the executor's output.`, + "", + "## Structure", + "", + "Order checks from cheapest to most expensive. The orchestrator must be able to run every check via bash.", + "", + "```", + "## Verification Checklist for story: ${storyId}", + "", + "### Check 1: [Description]", + "**Command**: `exact command here`", + "**Passes when**: [description of expected output or exit code]", + "", + "### Check 2: ...", + "```", + "", + "## Required check categories (in order)", + "", + "**1. Compilation** (always required)", + "Include the TypeScript compilation check or equivalent build command.", + "Example: `npx tsc --noEmit`", + "", + "**2. Linting** (if project uses a linter)", + "Include the lint command for affected files.", + "", + "**3. Unit tests** (for modified modules)", + "Include test commands scoped to the files or modules changed by this story.", + "Prefer targeted test runs (e.g., `--testPathPattern`) over full suite runs.", + "", + "**4. Integration tests** (if applicable)", + "Include only tests that directly exercise the story's acceptance criteria.", + "", + "## Precision requirements", + "", + "- Each command must be runnable from the repo root with no modifications.", + "- Pass/fail criteria must be unambiguous (exit code 0 = pass, or specific output pattern).", + "- Do not include checks that verify things outside this story's scope.", + "", + "Call koan_complete_step with a summary: number of checks, categories covered, and any checks you could not define due to missing information.", + ], + }; + + default: + return { + title: `Step ${step}`, + instructions: [`Execute step ${step}.`], + }; + } +} diff --git a/src/planner/phases/scout/phase.ts b/src/planner/phases/scout/phase.ts new file mode 100644 index 0000000..6685505 --- /dev/null +++ b/src/planner/phases/scout/phase.ts @@ -0,0 +1,39 @@ +// Scout phase: answers one narrow codebase question and writes findings. +// Single-step, cheap model, no user interaction. + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import { createLogger, type Logger } from "../../../utils/logger.js"; +import type { RuntimeContext } from "../../lib/runtime-context.js"; +import { EventLog } from "../../lib/audit.js"; +import { BasePhase } from "../base-phase.js"; +import { SCOUT_STEP_NAMES, scoutSystemPrompt, scoutStepGuidance } from "./prompts.js"; +import type { StepGuidance } from "../../lib/step.js"; + +export class ScoutPhase extends BasePhase { + protected readonly role = "scout"; + protected readonly totalSteps = 1; + + constructor( + pi: ExtensionAPI, + config: { epicDir: string }, + ctx: RuntimeContext, + log?: Logger, + eventLog?: EventLog, + ) { + super(pi, ctx, log ?? createLogger("ScoutPhase"), eventLog); + void config; // epicDir used via ctx.epicDir for permission scoping + } + + protected getSystemPrompt(): string { + return scoutSystemPrompt(); + } + + protected getStepName(step: number): string { + return SCOUT_STEP_NAMES[step] ?? `Step ${step}`; + } + + protected getStepGuidance(_step: number): StepGuidance { + return scoutStepGuidance(); + } +} diff --git a/src/planner/phases/scout/prompts.ts b/src/planner/phases/scout/prompts.ts new file mode 100644 index 0000000..1512e83 --- /dev/null +++ b/src/planner/phases/scout/prompts.ts @@ -0,0 +1,74 @@ +// Scout phase prompts — single step: explore & report. +// Role-specific context (the question and output file) is embedded in the +// spawn prompt by the spawn function. This provides only process guidance. + +import type { StepGuidance } from "../../lib/step.js"; + +export const SCOUT_STEP_NAMES: Record = { + 1: "Explore & Report", +}; + +export function scoutSystemPrompt(): string { + return `You are a codebase investigator. You are assigned one narrow, specific question about a codebase. Your job is to read the relevant files, find the answer, and write your findings to a designated output file. + +## Your role + +You find facts. You do NOT interpret, recommend, or opine. + +## Strict rules + +- MUST answer only the assigned question. Do not expand scope. +- MUST write only factual observations: what the code does, what files exist, what patterns are present. +- MUST NOT produce recommendations or suggestions of any kind. +- MUST NOT express opinions about code quality. +- MUST NOT produce implementation plans or design ideas. +- MUST include file paths and line numbers when referencing code. +- MUST include relevant code excerpts (verbatim) to support each finding. +- SHOULD be thorough within the question scope: follow references, check related files. +- SHOULD note explicitly when something is NOT present (e.g., "No tests found for this module"). + +## Output format + +Write a markdown file with these sections: + +## Question +Restate the assigned question verbatim. + +## Findings +Factual observations that answer the question. Use sub-sections if the answer has multiple parts. +Cite file paths and line numbers for every claim. Include code snippets where relevant. + +## Files Examined +List every file you read during this investigation. + +## Gaps +Note anything you could not determine. If no gaps, write: (none) + +## Tools available + +- All read tools (read, bash, grep, glob, find, ls) — for reading the codebase. +- \`write\` / \`edit\` — for writing the output file only. +- \`koan_complete_step\` — to signal completion. + +You work in a single step. Read the codebase, answer the question, write the output file.`; +} + +// Role-specific context (the question and output file) is embedded in the +// spawn prompt by the spawn function. This provides process guidance only. +export function scoutStepGuidance(): StepGuidance { + return { + title: SCOUT_STEP_NAMES[1], + instructions: [ + "Investigate the codebase to answer the assigned question. Write your findings to the output file.", + "", + "## Process", + "", + "1. Identify the files most likely to contain the answer. Start broad (grep, glob, ls),", + " then narrow down (read specific files).", + "2. Follow cross-references: if a file imports from another file, check that file too.", + "3. Be thorough within the question scope. Do not stop at the first partial answer.", + "4. Write your findings to the output file using the format described in your system prompt.", + "5. Call `koan_complete_step` with a one-sentence summary of your key finding.", + ], + }; +} diff --git a/src/planner/tools/index.ts b/src/planner/tools/index.ts index 726cd11..6383a34 100644 --- a/src/planner/tools/index.ts +++ b/src/planner/tools/index.ts @@ -1,40 +1,19 @@ // Tool registration aggregator. Single entry point for koan.ts. -// Re-exports dispatch primitives so koan.ts needs one import for both -// tool registration and workflow infrastructure. +// All tools registered here; RuntimeContext replaces the three separate +// mutable refs (PlanRef, SubagentRef, WorkflowDispatch) from the old design. import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import type { WorkflowDispatch, PlanRef, SubagentRef } from "../lib/dispatch.js"; +import type { RuntimeContext } from "../lib/runtime-context.js"; import { registerWorkflowTools } from "./workflow.js"; -import { registerPlanGetterTools } from "./getters.js"; -import { registerPlanSetterTools } from "./setters.js"; -import { registerPlanDesignEntityTools } from "./entity-design.js"; -import { registerPlanCodeEntityTools } from "./entity-code.js"; -import { registerPlanStructureEntityTools } from "./entity-structure.js"; -import { registerQRTools } from "./qr.js"; +import { registerOrchestratorTools } from "./orchestrator.js"; import { registerAskTools } from "./ask.js"; -export type { WorkflowDispatch, PlanRef, SubagentRef, StepResult } from "../lib/dispatch.js"; -export { - createDispatch, - createPlanRef, - createSubagentRef, - hookDispatch, - unhookDispatch, -} from "../lib/dispatch.js"; +export type { RuntimeContext } from "../lib/runtime-context.js"; +export { createRuntimeContext } from "../lib/runtime-context.js"; -export function registerAllTools( - pi: ExtensionAPI, - planRef: PlanRef, - dispatch: WorkflowDispatch, - subagentRef: SubagentRef, -): void { - registerWorkflowTools(pi, dispatch); - registerPlanGetterTools(pi, planRef); - registerPlanSetterTools(pi, planRef); - registerPlanDesignEntityTools(pi, planRef); - registerPlanCodeEntityTools(pi, planRef); - registerPlanStructureEntityTools(pi, planRef); - registerQRTools(pi, planRef); - registerAskTools(pi, subagentRef); +export function registerAllTools(pi: ExtensionAPI, ctx: RuntimeContext): void { + registerWorkflowTools(pi, ctx); + registerOrchestratorTools(pi, ctx); + registerAskTools(pi, ctx); } diff --git a/src/planner/tools/orchestrator.ts b/src/planner/tools/orchestrator.ts new file mode 100644 index 0000000..0348aa4 --- /dev/null +++ b/src/planner/tools/orchestrator.ts @@ -0,0 +1,239 @@ +// Orchestrator tools: four tools for the orchestrator subagent to advance +// story lifecycle state. koan_escalate is eliminated per §11.3.1 — the +// orchestrator uses koan_ask_question for all user communication. +// +// Each tool: +// 1. Validates that the story is in the correct source state (§11.4/§11.12) +// 2. Writes JSON state (for driver polling) +// 3. Writes templated markdown status.md (for LLM reads, §11.5.4) + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import { Type } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import type { RuntimeContext } from "../lib/runtime-context.js"; +import { loadStoryState, saveStoryState } from "../epic/state.js"; +import type { StoryStatus } from "../types.js"; + +// -- Helpers -- + +function now(): string { + return new Date().toISOString(); +} + +function storyDir(epicDir: string, storyId: string): string { + return path.join(epicDir, "stories", storyId); +} + +async function writeStatusMd(epicDir: string, storyId: string, content: string): Promise { + const dir = storyDir(epicDir, storyId); + const target = path.join(dir, "status.md"); + const tmp = path.join(dir, "status.md.tmp"); + await fs.writeFile(tmp, content, "utf8"); + await fs.rename(tmp, target); +} + +// §11.5.4 templated status.md format. +function statusMd( + storyId: string, + status: StoryStatus, + lastAction: string, + verificationSummary: string, + notes: string, +): string { + return [ + `# Status: ${status}`, + "", + "## Last Action", + lastAction, + "", + "## Verification Summary", + verificationSummary, + "", + "## Notes", + notes, + "", + ].join("\n"); +} + +function requireEpicDir(ctx: RuntimeContext): string { + if (!ctx.epicDir) { + throw new Error("Epic directory is not set. Is this running inside a koan subagent?"); + } + return ctx.epicDir; +} + +// Validates story status against allowed source statuses. Throws on mismatch. +export function assertStatus(storyId: string, current: StoryStatus, allowed: StoryStatus[]): void { + if (!allowed.includes(current)) { + const listed = allowed.map((s) => `'${s}'`).join(" or "); + throw new Error( + `Cannot transition story '${storyId}': expected status ${listed}, got '${current}'.`, + ); + } +} + +// -- Tool registration -- + +export function registerOrchestratorTools(pi: ExtensionAPI, ctx: RuntimeContext): void { + // -- koan_select_story -- + // Valid source statuses: pending, retry (§11.4) + + pi.registerTool({ + name: "koan_select_story", + label: "Select story for execution", + description: "Mark a pending or retried story as selected for execution. Valid only when the story is in 'pending' or 'retry' status.", + parameters: Type.Object({ + story_id: Type.String({ description: "The story ID to select." }), + }), + async execute(_toolCallId, params) { + const { story_id } = params as { story_id: string }; + const epicDir = requireEpicDir(ctx); + const ts = now(); + + const state = await loadStoryState(epicDir, story_id); + assertStatus(story_id, state.status, ["pending", "retry"]); + + await saveStoryState(epicDir, story_id, { ...state, status: "selected", updatedAt: ts }); + await writeStatusMd( + epicDir, story_id, + statusMd(story_id, "selected", `Selected at: ${ts}`, "(pending — not yet verified)", ""), + ); + + return { + content: [{ type: "text" as const, text: `Story '${story_id}' selected.` }], + details: undefined, + }; + }, + }); + + // -- koan_complete_story -- + // Valid source status: verifying (§11.4) + + pi.registerTool({ + name: "koan_complete_story", + label: "Complete story", + description: "Mark a story as done after verifying all acceptance criteria are met. Only valid when story is in 'verifying' status.", + parameters: Type.Object({ + story_id: Type.String({ description: "The story ID to mark as done." }), + verification_summary: Type.Optional(Type.String({ + description: "Summary of verification checks that passed.", + })), + }), + async execute(_toolCallId, params) { + const { story_id, verification_summary } = params as { + story_id: string; + verification_summary?: string; + }; + const epicDir = requireEpicDir(ctx); + const ts = now(); + + const state = await loadStoryState(epicDir, story_id); + assertStatus(story_id, state.status, ["verifying"]); + + await saveStoryState(epicDir, story_id, { ...state, status: "done", updatedAt: ts }); + await writeStatusMd( + epicDir, story_id, + statusMd( + story_id, "done", + `Completed at: ${ts}`, + verification_summary ?? "All checks passed.", + "", + ), + ); + + return { + content: [{ type: "text" as const, text: `Story '${story_id}' completed.` }], + details: undefined, + }; + }, + }); + + // -- koan_retry_story -- + // Valid source status: verifying (§11.4) + + pi.registerTool({ + name: "koan_retry_story", + label: "Retry story", + description: "Mark a story for retry and record why the previous attempt failed. Only valid when story is in 'verifying' status.", + parameters: Type.Object({ + story_id: Type.String({ description: "The story ID to retry." }), + failure_summary: Type.String({ + description: "Concrete description of what went wrong. Include failing commands, error messages, and what the executor should do differently.", + }), + }), + async execute(_toolCallId, params) { + const { story_id, failure_summary } = params as { story_id: string; failure_summary: string }; + const epicDir = requireEpicDir(ctx); + const ts = now(); + + const state = await loadStoryState(epicDir, story_id); + assertStatus(story_id, state.status, ["verifying"]); + + await saveStoryState(epicDir, story_id, { + ...state, + status: "retry", + updatedAt: ts, + failureSummary: failure_summary, + }); + await writeStatusMd( + epicDir, story_id, + statusMd( + story_id, "retry", + `Queued for retry at: ${ts}`, + "Failed — see Notes for details.", + failure_summary, + ), + ); + + return { + content: [{ type: "text" as const, text: `Story '${story_id}' queued for retry.` }], + details: undefined, + }; + }, + }); + + // -- koan_skip_story -- + // Valid source statuses: pending, retry (§11.4) + + pi.registerTool({ + name: "koan_skip_story", + label: "Skip story", + description: "Mark a pending or retried story as skipped and record the reason. Valid when story is in 'pending' or 'retry' status.", + parameters: Type.Object({ + story_id: Type.String({ description: "The story ID to skip." }), + reason: Type.String({ description: "Why this story is being skipped." }), + }), + async execute(_toolCallId, params) { + const { story_id, reason } = params as { story_id: string; reason: string }; + const epicDir = requireEpicDir(ctx); + const ts = now(); + + const state = await loadStoryState(epicDir, story_id); + assertStatus(story_id, state.status, ["pending", "retry"]); + + await saveStoryState(epicDir, story_id, { + ...state, + status: "skipped", + updatedAt: ts, + skipReason: reason, + }); + await writeStatusMd( + epicDir, story_id, + statusMd( + story_id, "skipped", + `Skipped at: ${ts}`, + "(not executed)", + reason, + ), + ); + + return { + content: [{ type: "text" as const, text: `Story '${story_id}' skipped.` }], + details: undefined, + }; + }, + }); +} From f00d78ab18a48c449037bb968a96ce0875a544b8 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Mar 2026 12:45:43 +0700 Subject: [PATCH 044/412] feat(planner): wire epic driver, spawners, and review widget --- extensions/koan.ts | 154 ++++++---- src/planner/driver.ts | 539 ++++++++++++++++++++++++++++++++++ src/planner/subagent.ts | 237 +++++++++------ src/planner/ui/epic-widget.ts | 243 +++++++++++++++ src/planner/ui/spec-review.ts | 152 ++++++++++ 5 files changed, 1175 insertions(+), 150 deletions(-) create mode 100644 src/planner/driver.ts create mode 100644 src/planner/ui/epic-widget.ts create mode 100644 src/planner/ui/spec-review.ts diff --git a/extensions/koan.ts b/extensions/koan.ts index ec475a6..24e0efc 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -1,18 +1,23 @@ // Entry point for the koan pi extension. Serves dual roles: parent session -// (registers koan_plan tool and /koan-execute, /koan-status, /koan commands) -// and subagent mode (dispatches to phase workflow via CLI flags). All tools -// register unconditionally at init; phases restrict access via tool_call -// blocking at runtime. - +// (registers koan_plan tool and /koan commands) and subagent mode (dispatches +// to phase workflow via CLI flags). All tools register unconditionally at init; +// phases restrict access via tool_call blocking at runtime. +// +// RuntimeContext replaces the three separate mutable refs (PlanRef, +// SubagentRef, WorkflowDispatch) used in the previous design. + +import * as path from "node:path"; import { Type } from "@sinclair/typebox"; import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"; -import { createSession } from "../src/planner/session.js"; import { detectSubagentMode, dispatchPhase } from "../src/planner/phases/dispatch.js"; -import { registerAllTools, createDispatch, createPlanRef, createSubagentRef } from "../src/planner/tools/index.js"; -import { createLogger } from "../src/utils/logger.js"; +import { registerAllTools, createRuntimeContext } from "../src/planner/tools/index.js"; +import { createLogger, setLogDir } from "../src/utils/logger.js"; import { EventLog, extractToolEvent } from "../src/planner/lib/audit.js"; import { openKoanConfig } from "../src/planner/ui/config/menu.js"; +import { createEpicDirectory } from "../src/planner/epic/state.js"; +import { exportConversation } from "../src/planner/conversation.js"; +import { runEpicPipeline } from "../src/planner/driver.js"; function currentModelId(ctx: ExtensionContext): string | null { const model = ctx.model; @@ -23,76 +28,68 @@ function currentModelId(ctx: ExtensionContext): string | null { export default function koan(pi: ExtensionAPI): void { const log = createLogger("Koan"); + // -- Flags -- pi.registerFlag("koan-role", { - description: "Koan subagent role (reserved)", + description: "Koan subagent role", type: "string", default: "", }); - - pi.registerFlag("koan-phase", { - description: "Koan workflow phase (reserved)", + pi.registerFlag("koan-epic-dir", { + description: "Koan epic directory path", type: "string", default: "", }); - - pi.registerFlag("koan-plan-dir", { - description: "Koan plan directory path", + pi.registerFlag("koan-subagent-dir", { + description: "Koan subagent working directory", type: "string", default: "", }); - - pi.registerFlag("koan-subagent-dir", { - description: "Koan subagent working directory", + pi.registerFlag("koan-story-id", { + description: "Current story ID for per-story subagents", type: "string", default: "", }); - - pi.registerFlag("koan-qr-item", { - description: "QR item ID(s) for reviewer subagent (comma-separated for groups)", + pi.registerFlag("koan-step-sequence", { + description: "Orchestrator step sequence (pre-execution or post-execution)", type: "string", default: "", }); - - pi.registerFlag("koan-fix", { - description: "QR phase to fix (e.g. plan-design)", + pi.registerFlag("koan-retry-context", { + description: "Failure context from previous execution attempt", type: "string", default: "", }); - // Pi snapshots tools during _buildRuntime() at init. All 44 tools - // register here unconditionally. Phases restrict access via tool_call - // blocking at runtime. - const dispatch = createDispatch(); - const planRef = createPlanRef(); - const subagentRef = createSubagentRef(); + // RuntimeContext: single mutable object that carries epicDir, subagentDir, + // and the active onCompleteStep handler. Replaces the old PlanRef + + // SubagentRef + WorkflowDispatch triple. + const ctx = createRuntimeContext(); - registerAllTools(pi, planRef, dispatch, subagentRef); + registerAllTools(pi, ctx); - // Subagent detection runs at before_agent_start (flags - // are unavailable during init). let dispatched = false; - pi.on("before_agent_start", async (_event, ctx) => { + pi.on("before_agent_start", async (_event, extCtx) => { if (dispatched) return; dispatched = true; + const config = detectSubagentMode(pi); if (config) { - const planDir = pi.getFlag("koan-plan-dir") as string; - if (planDir) { - planRef.dir = planDir; + // Populate RuntimeContext from CLI flags. + if (config.epicDir) { + ctx.epicDir = config.epicDir; } - // EventLog exists only in subagent mode. Parent mode has no audit log. - // Model identity is captured by the subagent itself and persisted in - // state.json for parent widget rendering. let eventLog: EventLog | undefined; if (config.subagentDir) { - eventLog = new EventLog(config.subagentDir, config.role, config.phase, currentModelId(ctx)); + ctx.subagentDir = config.subagentDir; + eventLog = new EventLog( + config.subagentDir, + config.role, + config.role, + currentModelId(extCtx), + ); await eventLog.open(); - subagentRef.dir = config.subagentDir; - // Capture all tool results for the audit trail. Graduated detail: - // file paths for read/edit/write, binary name for bash, full - // input+response for koan_* tools, name-only for everything else. pi.on("tool_result", (event) => { void eventLog!.append(extractToolEvent(event as { toolName: string; @@ -107,13 +104,16 @@ export default function koan(pi: ExtensionAPI): void { }); } - await dispatchPhase(pi, config, dispatch, planRef, log, eventLog); + await dispatchPhase(pi, config, ctx, log, eventLog); } }); - // Session: parent-mode workflow engine. - const session = createSession(pi, dispatch, planRef); - + // -- koan_plan tool -- + // Requires an interactive terminal session: subagents use koan_ask_question + // and koan_request_scouts, which are answered by the IPC responder running + // in the parent session. Without a UI, no IPC responder starts and any + // subagent calling those tools will poll ipc.json forever, hanging the + // pipeline permanently. pi.registerTool({ name: "koan_plan", label: "Plan", @@ -123,41 +123,69 @@ export default function koan(pi: ExtensionAPI): void { "is too large to implement directly.", "", "The current conversation is automatically captured — it becomes the", - "planning context. The pipeline spawns specialized agents (architect,", - "developer, writer) that read the conversation history to understand", - "the task, then produce a structured plan with milestones, code intents,", - "and quality review.", + "planning context. The pipeline spawns specialized agents that decompose", + "the task into stories and execute them one at a time.", "", - "This is a long-running operation (5-15 minutes). Do not invoke for", - "simple tasks that can be done in a single pass.", + "This is a long-running operation. Do not invoke for simple tasks.", ].join("\n"), parameters: Type.Object({}), - async execute(toolCallId, params, signal, onUpdate, ctx) { - return await session.plan(ctx); + async execute(_toolCallId, _params, _signal, _onUpdate, extCtx) { + // koan_plan requires an interactive terminal session. Subagents use + // koan_ask_question and koan_request_scouts, which are answered by the + // IPC responder that only starts when a UI is present. Without a UI, + // subagents would poll ipc.json forever and the pipeline would hang. + if (!extCtx.hasUI) { + return { + content: [{ type: "text" as const, text: "koan_plan requires an interactive terminal session." }], + details: undefined, + }; + } + + const epicInfo = await createEpicDirectory("", extCtx.cwd); + ctx.epicDir = epicInfo.directory; + setLogDir(epicInfo.directory); + + await exportConversation(extCtx.sessionManager, epicInfo.directory); + log("Conversation exported", { epicDir: epicInfo.directory }); + + const extensionPath = path.resolve(import.meta.dirname, "koan.ts"); + const ui = extCtx.hasUI ? extCtx.ui : null; + + const result = await runEpicPipeline(epicInfo.directory, extCtx.cwd, extensionPath, log, ui); + + return { + content: [{ type: "text" as const, text: result.summary }], + details: undefined, + }; }, }); + // -- Commands -- pi.registerCommand("koan", { description: "Koan commands. Usage: /koan config", - handler: async (args, ctx) => { + handler: async (args, extCtx) => { const subcommand = args.trim(); if (subcommand === "config") { - await openKoanConfig(ctx); + await openKoanConfig(extCtx); } else if (subcommand === "") { - ctx.ui.notify("Usage: /koan config", "info"); + extCtx.ui.notify("Usage: /koan config", "info"); } else { - ctx.ui.notify(`Unknown koan subcommand: "${subcommand}". Usage: /koan config`, "warning"); + extCtx.ui.notify(`Unknown koan subcommand: "${subcommand}". Usage: /koan config`, "warning"); } }, }); pi.registerCommand("koan-execute", { description: "Execute a koan plan", - handler: async (_args, ctx) => { await session.execute(ctx); }, + handler: async (_args, extCtx) => { + extCtx.ui.notify("Execution mode is not yet implemented.", "warning"); + }, }); pi.registerCommand("koan-status", { description: "Show koan workflow status", - handler: async (_args, ctx) => { await session.status(ctx); }, + handler: async (_args, extCtx) => { + extCtx.ui.notify("Status: idle", "info"); + }, }); } diff --git a/src/planner/driver.ts b/src/planner/driver.ts new file mode 100644 index 0000000..5d03543 --- /dev/null +++ b/src/planner/driver.ts @@ -0,0 +1,539 @@ +// Epic pipeline driver — deterministic coordinator for the full epic lifecycle. +// Reads JSON state and exit codes; applies routing rules. Never parses markdown. +// Per AGENTS.md: driver owns .json state; LLMs own .md files. + +import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; + +import { + loadEpicState, + saveEpicState, + loadStoryState, + saveStoryState, + loadAllStoryStates, + ensureSubagentDirectory, + ensureStoryDirectory, + discoverStoryIds, +} from "./epic/state.js"; +import { + spawnIntake, + spawnDecomposer, + spawnOrchestrator, + spawnPlanner, + spawnExecutor, +} from "./subagent.js"; +import type { Logger } from "../utils/logger.js"; +import type { StoryState } from "./epic/types.js"; +import { readRecentLogs, readProjection } from "./lib/audit.js"; +import { EpicWidgetController } from "./ui/epic-widget.js"; +import { reviewStorySketches } from "./ui/spec-review.js"; + +// --------------------------------------------------------------------------- +// Routing +// --------------------------------------------------------------------------- + +interface RoutingDecision { + action: "execute" | "retry" | "complete" | "error"; + storyId?: string; + error?: string; +} + +// Simplified routing — no escalation path per §11.3.1 and §11.6.3. +// Retry budget exhaustion is handled inside the retry case (skip + notify). +function routeFromState(stories: StoryState[], log: Logger): RoutingDecision { + // Priority order: + // 1. Any story with status 'retry'? → check budget, then re-execute or skip + // 2. Any story with status 'selected'? → execute it + // 3. All stories terminal? → complete + // 4. None of the above → error + + const retry = stories.find((s) => s.status === "retry"); + if (retry) { + log("Routing: retry", { storyId: retry.storyId }); + return { action: "retry", storyId: retry.storyId }; + } + + const selected = stories.find((s) => s.status === "selected"); + if (selected) { + log("Routing: execute", { storyId: selected.storyId }); + return { action: "execute", storyId: selected.storyId }; + } + + const terminal = new Set(["done", "skipped"]); + const allTerminal = stories.every((s) => terminal.has(s.status)); + if (allTerminal && stories.length > 0) { + log("Routing: complete", { total: stories.length }); + return { action: "complete" }; + } + + return { + action: "error", + error: "No actionable story state found (orchestrator may have exited without a routing decision)", + }; +} + +// --------------------------------------------------------------------------- +// Active widget polling (§11.6.1) +// --------------------------------------------------------------------------- + +// Starts a 2s polling interval that reads the active subagent's projection +// and log tail, then updates the widget. Interval is unref'd so it does not +// prevent process exit. +function startActivePolling( + activeSubagentDir: string, + widget: EpicWidgetController, + startedAt: number, + role: string, + storyId?: string, +): () => void { + const timer = setInterval(async () => { + try { + const [projection, logs] = await Promise.all([ + readProjection(activeSubagentDir), + readRecentLogs(activeSubagentDir), + ]); + widget.update({ logLines: logs }); + if (projection) { + widget.update({ + activeSubagent: { + role, + storyId, + step: projection.step, + totalSteps: projection.totalSteps, + stepName: projection.stepName, + startedAt, + }, + }); + } + } catch { + // Non-fatal — polling is best-effort. + } + }, 2000); + timer.unref(); + return () => clearInterval(timer); +} + +// --------------------------------------------------------------------------- +// Phase A helpers +// --------------------------------------------------------------------------- + +async function runIntake( + epicDir: string, + cwd: string, + extensionPath: string, + log: Logger, + ui: ExtensionUIContext | null, + widget: EpicWidgetController | null, +): Promise { + const subagentDir = await ensureSubagentDirectory(epicDir, "intake"); + const startedAt = Date.now(); + let stopPolling: (() => void) | undefined; + if (widget) { + widget.update({ activeSubagent: { role: "intake", step: 0, totalSteps: 3, stepName: "", startedAt } }); + stopPolling = startActivePolling(subagentDir, widget, startedAt, "intake"); + } + const result = await spawnIntake({ epicDir, subagentDir, cwd, extensionPath, log, ui: ui ?? undefined }); + stopPolling?.(); + if (widget) { + const logs = await readRecentLogs(subagentDir); + widget.update({ logLines: logs, activeSubagent: null }); + } + if (result.exitCode !== 0) { + log("Intake failed", { exitCode: result.exitCode }); + return false; + } + return true; +} + +async function runDecomposer( + epicDir: string, + cwd: string, + extensionPath: string, + log: Logger, + ui: ExtensionUIContext | null, + widget: EpicWidgetController | null, +): Promise { + const subagentDir = await ensureSubagentDirectory(epicDir, "decomposer"); + const startedAt = Date.now(); + let stopPolling: (() => void) | undefined; + if (widget) { + widget.update({ activeSubagent: { role: "decomposer", step: 0, totalSteps: 2, stepName: "", startedAt } }); + stopPolling = startActivePolling(subagentDir, widget, startedAt, "decomposer"); + } + const result = await spawnDecomposer({ epicDir, subagentDir, cwd, extensionPath, log, ui: ui ?? undefined }); + stopPolling?.(); + if (widget) { + const logs = await readRecentLogs(subagentDir); + widget.update({ logLines: logs, activeSubagent: null }); + } + if (result.exitCode !== 0) { + log("Decomposer failed", { exitCode: result.exitCode }); + return false; + } + return true; +} + +// --------------------------------------------------------------------------- +// Phase B helpers +// --------------------------------------------------------------------------- + +async function runStoryExecution( + epicDir: string, + cwd: string, + extensionPath: string, + storyId: string, + log: Logger, + ui: ExtensionUIContext | null, + widget: EpicWidgetController | null, +): Promise { + // 1. Set status to 'planning'. + const story = await loadStoryState(epicDir, storyId); + await saveStoryState(epicDir, storyId, { + ...story, + status: "planning", + updatedAt: new Date().toISOString(), + }); + + // 2. Spawn planner. + const plannerDir = await ensureSubagentDirectory(epicDir, `planner-${storyId}`); + const plannerStarted = Date.now(); + let stopPolling: (() => void) | undefined; + if (widget) { + widget.update({ + activeSubagent: { role: "planner", storyId, step: 0, totalSteps: 3, stepName: "", startedAt: plannerStarted }, + }); + stopPolling = startActivePolling(plannerDir, widget, plannerStarted, "planner", storyId); + } + + const planResult = await spawnPlanner({ epicDir, subagentDir: plannerDir, cwd, extensionPath, storyId, log, ui: ui ?? undefined }); + stopPolling?.(); + + if (widget) { + const logs = await readRecentLogs(plannerDir); + widget.update({ logLines: logs }); + } + + if (planResult.exitCode !== 0) { + log("Planner failed — skipping executor, proceeding to post-execution orchestrator", { + storyId, exitCode: planResult.exitCode, + }); + + const s2 = await loadStoryState(epicDir, storyId); + await saveStoryState(epicDir, storyId, { + ...s2, + status: "verifying", + updatedAt: new Date().toISOString(), + }); + + const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}`); + const orchStarted = Date.now(); + if (widget) { + widget.update({ activeSubagent: { role: "orchestrator", storyId, step: 0, totalSteps: 4, stepName: "", startedAt: orchStarted } }); + stopPolling = startActivePolling(postDir, widget, orchStarted, "orchestrator", storyId); + } + + await spawnOrchestrator({ epicDir, subagentDir: postDir, cwd, extensionPath, stepSequence: "post-execution", storyId, log, ui: ui ?? undefined }); + stopPolling?.(); + + if (widget) { + const logs = await readRecentLogs(postDir); + widget.update({ logLines: logs }); + } + return; + } + + // 3. Set status to 'executing'. + const s3 = await loadStoryState(epicDir, storyId); + await saveStoryState(epicDir, storyId, { + ...s3, + status: "executing", + updatedAt: new Date().toISOString(), + }); + + // 4. Spawn executor. + const execDir = await ensureSubagentDirectory(epicDir, `executor-${storyId}`); + const execStarted = Date.now(); + if (widget) { + widget.update({ activeSubagent: { role: "executor", storyId, step: 0, totalSteps: 2, stepName: "", startedAt: execStarted } }); + stopPolling = startActivePolling(execDir, widget, execStarted, "executor", storyId); + } + + const execResult = await spawnExecutor({ epicDir, subagentDir: execDir, cwd, extensionPath, storyId, log, ui: ui ?? undefined }); + stopPolling?.(); + + if (widget) { + const logs = await readRecentLogs(execDir); + widget.update({ logLines: logs }); + } + + if (execResult.exitCode !== 0) { + log("Executor failed", { storyId, exitCode: execResult.exitCode }); + } + + // 5. Set status to 'verifying'. + const s4 = await loadStoryState(epicDir, storyId); + await saveStoryState(epicDir, storyId, { + ...s4, + status: "verifying", + updatedAt: new Date().toISOString(), + }); + + // 6. Spawn orchestrator (post-execution) — writes verdict to story state. + const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}`); + const orchStarted = Date.now(); + if (widget) { + widget.update({ activeSubagent: { role: "orchestrator", storyId, step: 0, totalSteps: 4, stepName: "", startedAt: orchStarted } }); + stopPolling = startActivePolling(postDir, widget, orchStarted, "orchestrator", storyId); + } + + await spawnOrchestrator({ epicDir, subagentDir: postDir, cwd, extensionPath, stepSequence: "post-execution", storyId, log, ui: ui ?? undefined }); + stopPolling?.(); + + if (widget) { + const logs = await readRecentLogs(postDir); + widget.update({ logLines: logs }); + } +} + +// retryCount is the 1-based retry attempt number (1 for first retry, 2 for +// second, etc.). It is included in directory names so each retry gets its own +// isolated stdout.log and events.jsonl, preventing directory collision when +// DEFAULT_MAX_RETRIES > 1. +async function runStoryReexecution( + epicDir: string, + cwd: string, + extensionPath: string, + storyId: string, + retryCount: number, + failureContext: string | undefined, + log: Logger, + ui: ExtensionUIContext | null, + widget: EpicWidgetController | null, +): Promise { + const execDir = await ensureSubagentDirectory(epicDir, `executor-${storyId}-retry-${retryCount}`); + const execStarted = Date.now(); + let stopPolling: (() => void) | undefined; + if (widget) { + widget.update({ activeSubagent: { role: "executor", storyId, step: 0, totalSteps: 2, stepName: "retry", startedAt: execStarted } }); + stopPolling = startActivePolling(execDir, widget, execStarted, "executor", storyId); + } + + await spawnExecutor({ epicDir, subagentDir: execDir, cwd, extensionPath, storyId, retryContext: failureContext, log, ui: ui ?? undefined }); + stopPolling?.(); + + if (widget) { + const logs = await readRecentLogs(execDir); + widget.update({ logLines: logs }); + } + + const story = await loadStoryState(epicDir, storyId); + await saveStoryState(epicDir, storyId, { + ...story, + status: "verifying", + updatedAt: new Date().toISOString(), + }); + + const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}-retry-${retryCount}`); + const orchStarted = Date.now(); + if (widget) { + widget.update({ activeSubagent: { role: "orchestrator", storyId, step: 0, totalSteps: 4, stepName: "", startedAt: orchStarted } }); + stopPolling = startActivePolling(postDir, widget, orchStarted, "orchestrator", storyId); + } + + await spawnOrchestrator({ epicDir, subagentDir: postDir, cwd, extensionPath, stepSequence: "post-execution", storyId, log, ui: ui ?? undefined }); + stopPolling?.(); + + if (widget) { + const logs = await readRecentLogs(postDir); + widget.update({ logLines: logs }); + } +} + +async function refreshWidgetStories(epicDir: string, widget: EpicWidgetController): Promise { + try { + const stories = await loadAllStoryStates(epicDir); + widget.update({ stories: stories.map((s) => ({ storyId: s.storyId, status: s.status })) }); + } catch { + // Non-fatal — widget update is best-effort. + } +} + +async function runStoryLoop( + epicDir: string, + cwd: string, + extensionPath: string, + log: Logger, + ui: ExtensionUIContext | null, + widget: EpicWidgetController | null, +): Promise<{ success: boolean; summary: string }> { + { + + // 2. Spawn orchestrator (pre-execution) — selects first story. + const preDir = await ensureSubagentDirectory(epicDir, "orchestrator-pre"); + const preStarted = Date.now(); + let stopPolling: (() => void) | undefined; + if (widget) { + widget.update({ activeSubagent: { role: "orchestrator", step: 0, totalSteps: 2, stepName: "pre-execution", startedAt: preStarted } }); + stopPolling = startActivePolling(preDir, widget, preStarted, "orchestrator"); + } + + const preResult = await spawnOrchestrator({ epicDir, subagentDir: preDir, cwd, extensionPath, stepSequence: "pre-execution", log, ui: ui ?? undefined }); + stopPolling?.(); + + if (preResult.exitCode !== 0) { + return { success: false, summary: "Pre-execution orchestrator failed" }; + } + + if (widget) await refreshWidgetStories(epicDir, widget); + + // 3. Story execution loop — route until terminal state. + while (true) { + const stories = await loadAllStoryStates(epicDir); + if (widget) { + widget.update({ stories: stories.map((s) => ({ storyId: s.storyId, status: s.status })) }); + } + + const routing = routeFromState(stories, log); + + switch (routing.action) { + case "execute": { + const storyId = routing.storyId as string; + await runStoryExecution(epicDir, cwd, extensionPath, storyId, log, ui, widget); + if (widget) await refreshWidgetStories(epicDir, widget); + break; + } + + case "retry": { + const storyId = routing.storyId as string; + const story = stories.find((s) => s.storyId === storyId) as StoryState; + + // Retry budget exhaustion: skip + notify per §11.6.3. + if (story.retryCount >= story.maxRetries) { + log("Retry budget exhausted, skipping story", { storyId, retryCount: story.retryCount }); + await saveStoryState(epicDir, storyId, { + ...story, + status: "skipped", + skipReason: `Retry budget exhausted after ${story.retryCount} attempt(s). Last failure: ${story.failureSummary ?? "(none recorded)"}`, + updatedAt: new Date().toISOString(), + }); + ui?.notify(`Story ${storyId} skipped after ${story.retryCount} failed attempt(s).`, "warning"); + if (widget) await refreshWidgetStories(epicDir, widget); + // Continue loop — other stories may still be runnable. + continue; + } + + await saveStoryState(epicDir, storyId, { + ...story, + status: "executing", + retryCount: story.retryCount + 1, + updatedAt: new Date().toISOString(), + }); + await runStoryReexecution(epicDir, cwd, extensionPath, storyId, story.retryCount + 1, story.failureSummary, log, ui, widget); + if (widget) await refreshWidgetStories(epicDir, widget); + break; + } + + case "complete": { + const done = stories.filter((s) => s.status === "done").length; + const skipped = stories.filter((s) => s.status === "skipped").length; + if (widget) widget.update({ activeSubagent: null }); + return { success: true, summary: `Epic complete: ${done} done, ${skipped} skipped` }; + } + + case "error": + return { success: false, summary: routing.error as string }; + } + } + } +} + +// --------------------------------------------------------------------------- +// Public API +// --------------------------------------------------------------------------- + +export async function runEpicPipeline( + epicDir: string, + cwd: string, + extensionPath: string, + log: Logger, + ui: ExtensionUIContext | null, +): Promise<{ success: boolean; summary: string }> { + // Widget created at pipeline start — spans the full epic lifecycle (Phase A + B). + // Widget is an observation layer: receives one-way update() calls, never + // influences routing decisions. + const epicState = await loadEpicState(epicDir); + const widget = ui ? new EpicWidgetController(ui, epicState.epicId) : null; + + try { + // Phase A: Epic Creation. + ui?.notify("Starting intake...", "info"); + await saveEpicState(epicDir, { ...epicState, phase: "intake" }); + if (widget) widget.update({ epicPhase: "intake" }); + + const intakeOk = await runIntake(epicDir, cwd, extensionPath, log, ui, widget); + if (!intakeOk) return { success: false, summary: "Intake phase failed" }; + + const afterIntake = await loadEpicState(epicDir); + await saveEpicState(epicDir, { ...afterIntake, phase: "decomposition" }); + if (widget) widget.update({ epicPhase: "decomposition" }); + + const decompOk = await runDecomposer(epicDir, cwd, extensionPath, log, ui, widget); + if (!decompOk) return { success: false, summary: "Decomposition phase failed" }; + + // Discover stories by scanning the filesystem — per AGENTS.md invariant, + // LLMs write markdown files only. The decomposer wrote stories/{id}/story.md + // files; the driver scans to discover IDs and populates epic-state.json. + const storyIds = await discoverStoryIds(epicDir); + log("Discovered story IDs", { count: storyIds.length, ids: storyIds }); + + for (const storyId of storyIds) { + await ensureStoryDirectory(epicDir, storyId); + } + + const afterDecomp = await loadEpicState(epicDir); + await saveEpicState(epicDir, { ...afterDecomp, stories: storyIds, phase: "review" }); + if (widget) { + widget.update({ epicPhase: "review" }); + const initialStories = await loadAllStoryStates(epicDir); + widget.update({ stories: initialStories.map((s) => ({ storyId: s.storyId, status: s.status })) }); + } + + // Spec review gate — present story sketches for human approval if UI is available. + if (ui && storyIds.length > 0) { + ui.notify("Decomposition complete. Review story sketches...", "info"); + const reviewResult = await reviewStorySketches(epicDir, storyIds, ui); + log("Spec review complete", { approved: reviewResult.approved.length, skipped: reviewResult.skipped.length }); + + for (const skippedId of reviewResult.skipped) { + const skippedStory = await loadStoryState(epicDir, skippedId); + await saveStoryState(epicDir, skippedId, { + ...skippedStory, + status: "skipped", + skipReason: "Removed during spec review", + updatedAt: new Date().toISOString(), + }); + } + + const reviewedState = await loadEpicState(epicDir); + await saveEpicState(epicDir, { ...reviewedState, stories: storyIds }); + } else { + log("Spec review gate: auto-approving (no UI or no stories)"); + } + + // Phase B: Execution. + const beforeExec = await loadEpicState(epicDir); + await saveEpicState(epicDir, { ...beforeExec, phase: "executing" }); + if (widget) widget.update({ epicPhase: "executing" }); + + const result = await runStoryLoop(epicDir, cwd, extensionPath, log, ui, widget); + + if (result.success) { + const afterExec = await loadEpicState(epicDir); + await saveEpicState(epicDir, { ...afterExec, phase: "completed" }); + if (widget) widget.update({ epicPhase: "completed" }); + } + + return result; + } finally { + widget?.destroy(); + } +} diff --git a/src/planner/subagent.ts b/src/planner/subagent.ts index b4fb0a9..99c637d 100644 --- a/src/planner/subagent.ts +++ b/src/planner/subagent.ts @@ -1,15 +1,21 @@ // Subagent spawn helpers. Each public function delegates to spawnSubagent, // which handles process lifecycle, stdout/stderr routing to disk, and -// exit-code normalization. Spawn errors resolve (not reject) so the caller -// can always read exitCode without try/catch. +// exit-code normalization. When a UI context is provided, an IPC responder +// runs concurrently so subagents can ask questions and request scouts. import { spawn } from "node:child_process"; import { createWriteStream } from "node:fs"; import * as path from "node:path"; +import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; + import { createLogger, type Logger } from "../utils/logger.js"; +import type { SubagentRole, StepSequence } from "./types.js"; +import { resolveModelForRole } from "./model-resolver.js"; +import { runIpcResponder, type ScoutSpawnContext } from "./lib/ipc-responder.js"; +import type { ScoutTask } from "./lib/ipc.js"; -type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; +// -- Result type -- export interface SubagentResult { exitCode: number; @@ -17,59 +23,39 @@ export interface SubagentResult { subagentDir: string; } -export interface SpawnWorkOptions { - planDir: string; - subagentDir: string; - cwd: string; - extensionPath: string; - initialPrompt?: string; - modelOverride?: string; - log?: Logger; -} +// -- Public spawn option types -- -export interface SpawnFixOptions { - planDir: string; +export interface SpawnOptions { + epicDir: string; subagentDir: string; cwd: string; extensionPath: string; - fixPhase: WorkPhaseKey; modelOverride?: string; log?: Logger; + ui?: ExtensionUIContext; } -export interface SpawnQRDecomposerOptions { - planDir: string; - subagentDir: string; - cwd: string; - extensionPath: string; - phase: WorkPhaseKey; - modelOverride?: string; - log?: Logger; +export interface SpawnStoryOptions extends SpawnOptions { + storyId: string; } -export interface SpawnReviewerOptions { - planDir: string; - subagentDir: string; - cwd: string; - extensionPath: string; - phase: WorkPhaseKey; - itemIds: string[]; - modelOverride?: string; - log?: Logger; -} +// -- Internal spawn infrastructure -- interface SpawnSubagentOpts { - planDir: string; + epicDir: string; subagentDir: string; cwd: string; extensionPath: string; extraFlags?: string[]; modelOverride?: string; + ui?: ExtensionUIContext; + // Scout spawning context for the IPC responder. Provided for all non-scout + // subagents that may call koan_request_scouts. + scoutContext?: ScoutSpawnContext; } export function buildSpawnArgs( role: string, - phase: string, prompt: string, opts: SpawnSubagentOpts, ): string[] { @@ -77,8 +63,7 @@ export function buildSpawnArgs( "-p", "-e", opts.extensionPath, "--koan-role", role, - "--koan-phase", phase, - "--koan-plan-dir", opts.planDir, + "--koan-epic-dir", opts.epicDir, "--koan-subagent-dir", opts.subagentDir, ...(opts.extraFlags ?? []), ...(opts.modelOverride ? ["--model", opts.modelOverride] : []), @@ -88,14 +73,12 @@ export function buildSpawnArgs( function spawnSubagent( role: string, - phase: string, prompt: string, opts: SpawnSubagentOpts, log: Logger, ): Promise { - const args = buildSpawnArgs(role, phase, prompt, opts); - - log(`Spawning ${role} subagent`, { planDir: opts.planDir, subagentDir: opts.subagentDir, phase }); + const args = buildSpawnArgs(role, prompt, opts); + log(`Spawning ${role} subagent`, { epicDir: opts.epicDir, subagentDir: opts.subagentDir }); return new Promise((resolve) => { const stdoutLog = createWriteStream(path.join(opts.subagentDir, "stdout.log"), { flags: "w" }); @@ -107,6 +90,22 @@ function spawnSubagent( stdio: ["ignore", "pipe", "pipe"], }); + // Start IPC responder concurrently when a UI context is available. + // The responder polls ipc.json in the subagent directory and routes + // ask-question requests to the ask UI and scout-request requests to + // the scout spawning pool. + let abortIpc: (() => void) | undefined; + if (opts.ui) { + const ac = new AbortController(); + abortIpc = () => ac.abort(); + void runIpcResponder( + opts.subagentDir, + opts.ui, + ac.signal, + opts.scoutContext, + ); + } + let stderr = ""; proc.stdout.on("data", (data: Buffer) => { @@ -119,94 +118,158 @@ function spawnSubagent( }); proc.on("close", (code) => { + abortIpc?.(); stdoutLog.end(); stderrLog.end(); const exitCode = code ?? 1; - log(`${role} subagent exited`, { exitCode, phase }); + log(`${role} subagent exited`, { exitCode }); resolve({ exitCode, stderr, subagentDir: opts.subagentDir }); }); proc.on("error", (error) => { + abortIpc?.(); stdoutLog.end(); stderrLog.end(); - log(`${role} subagent spawn error`, { error: error.message, phase }); + log(`${role} subagent spawn error`, { error: error.message }); resolve({ exitCode: 1, stderr: error.message, subagentDir: opts.subagentDir }); }); }); } -function spawnWork(role: string, phase: WorkPhaseKey, prompt: string, opts: SpawnWorkOptions): Promise { - const log = opts.log ?? createLogger("Subagent"); - return spawnSubagent(role, phase, prompt, opts, log); -} - -// -- Planning workers -- - -export function spawnArchitect(opts: SpawnWorkOptions): Promise { - return spawnWork("architect", "plan-design", opts.initialPrompt ?? "Begin the plan-design phase.", opts); -} +// -- Scout spawner (injected into IPC responder) -- +// Defined here to avoid circular imports: ipc-responder.ts uses a callback +// type, not a direct import from this module. -export function spawnDeveloper(opts: SpawnWorkOptions): Promise { - return spawnWork("developer", "plan-code", opts.initialPrompt ?? "Begin the plan-code phase.", opts); -} - -export function spawnTechnicalWriter(opts: SpawnWorkOptions): Promise { - return spawnWork("technical-writer", "plan-docs", opts.initialPrompt ?? "Begin the plan-docs phase.", opts); +function makeScoutSpawnContext( + opts: SpawnOptions, + log: Logger, +): ScoutSpawnContext { + return { + epicDir: opts.epicDir, + async spawnScout(task: ScoutTask, scoutSubagentDir: string, outputFile: string): Promise { + const scoutModel = await resolveModelForRole("scout"); + const prompt = `${task.prompt}\n\nWrite your findings to: ${outputFile}\nYour investigator role: ${task.role}`; + const result = await spawnSubagent( + "scout", + prompt, + { + epicDir: opts.epicDir, + subagentDir: scoutSubagentDir, + cwd: opts.cwd, + extensionPath: opts.extensionPath, + modelOverride: scoutModel, + // Scouts do not get an IPC responder — they are narrow investigators. + }, + log, + ); + return result.exitCode; + }, + }; } -// -- Fix workers -- +// -- Public spawn functions -- -export function spawnArchitectFix(opts: SpawnFixOptions): Promise { +// Intake: reads conversation, extracts context, requests scouts, asks user questions. +export async function spawnIntake(opts: SpawnOptions): Promise { + const role: SubagentRole = "intake"; const log = opts.log ?? createLogger("Subagent"); + const modelOverride = opts.modelOverride ?? await resolveModelForRole(role); + const scoutContext = makeScoutSpawnContext(opts, log); return spawnSubagent( - "architect", - "plan-design", - "Fix the plan based on QR failures.", - { ...opts, extraFlags: ["--koan-fix", opts.fixPhase] }, + role, + "Begin the intake phase.", + { ...opts, modelOverride, scoutContext }, log, ); } -export function spawnDeveloperFix(opts: SpawnFixOptions): Promise { +// Scout: answers one narrow codebase question and writes findings to outputFile. +// Note: scouts are spawned by the IPC responder (via makeScoutSpawnContext) when +// a subagent calls koan_request_scouts. This function is also callable directly +// from the driver if needed. +export async function spawnScout( + opts: SpawnOptions & { question: string; role?: string; outputFile: string }, +): Promise { + const subagentRole: SubagentRole = "scout"; + const log = opts.log ?? createLogger("Subagent"); + const modelOverride = opts.modelOverride ?? await resolveModelForRole(subagentRole); + const prompt = [ + opts.question, + opts.role ? `Your investigator role: ${opts.role}` : "", + `Write your findings to: ${opts.outputFile}`, + ].filter(Boolean).join("\n"); + return spawnSubagent(subagentRole, prompt, { ...opts, modelOverride }, log); +} + +// Decomposer: splits the epic into stories. +export async function spawnDecomposer(opts: SpawnOptions): Promise { + const role: SubagentRole = "decomposer"; const log = opts.log ?? createLogger("Subagent"); + const modelOverride = opts.modelOverride ?? await resolveModelForRole(role); + const scoutContext = makeScoutSpawnContext(opts, log); return spawnSubagent( - "developer", - "plan-code", - "Fix plan-code output based on QR failures.", - { ...opts, extraFlags: ["--koan-fix", opts.fixPhase] }, + role, + "Begin the decomposition phase.", + { ...opts, modelOverride, scoutContext }, log, ); } -export function spawnTechnicalWriterFix(opts: SpawnFixOptions): Promise { +// Orchestrator: pre-execution or post-execution decision making. +export async function spawnOrchestrator( + opts: SpawnOptions & { stepSequence: StepSequence; storyId?: string }, +): Promise { + const role: SubagentRole = "orchestrator"; const log = opts.log ?? createLogger("Subagent"); + const modelOverride = opts.modelOverride ?? await resolveModelForRole(role); + const extraFlags: string[] = ["--koan-step-sequence", opts.stepSequence]; + if (opts.storyId) { + extraFlags.push("--koan-story-id", opts.storyId); + } + const prompt = `Begin the ${opts.stepSequence} orchestrator phase.`; return spawnSubagent( - "technical-writer", - "plan-docs", - "Fix plan-docs output based on QR failures.", - { ...opts, extraFlags: ["--koan-fix", opts.fixPhase] }, + role, + prompt, + { ...opts, extraFlags, modelOverride }, log, ); } -// -- QR workers -- - -export function spawnQRDecomposer(opts: SpawnQRDecomposerOptions): Promise { +// Planner: produces a detailed plan for a story. +export async function spawnPlanner(opts: SpawnStoryOptions): Promise { + const role: SubagentRole = "planner"; const log = opts.log ?? createLogger("Subagent"); - return spawnSubagent("qr-decomposer", `qr-${opts.phase}`, "Begin the QR decompose phase.", opts, log); + const modelOverride = opts.modelOverride ?? await resolveModelForRole(role); + const extraFlags: string[] = ["--koan-story-id", opts.storyId]; + const scoutContext = makeScoutSpawnContext(opts, log); + const prompt = `Begin the planning phase for story ${opts.storyId}.`; + return spawnSubagent( + role, + prompt, + { ...opts, extraFlags, modelOverride, scoutContext }, + log, + ); } -export function spawnReviewer(opts: SpawnReviewerOptions): Promise { +// Executor: implements a story plan. +export async function spawnExecutor( + opts: SpawnStoryOptions & { retryContext?: string }, +): Promise { + const role: SubagentRole = "executor"; const log = opts.log ?? createLogger("Subagent"); - const itemList = opts.itemIds.join(","); - const prompt = opts.itemIds.length === 1 - ? "Verify the assigned QR item." - : `Verify the ${opts.itemIds.length} assigned QR items.`; + const modelOverride = opts.modelOverride ?? await resolveModelForRole(role); + const extraFlags: string[] = ["--koan-story-id", opts.storyId]; + if (opts.retryContext) { + extraFlags.push("--koan-retry-context", opts.retryContext); + } + const basePrompt = `Implement the plan for story ${opts.storyId}.`; + const prompt = opts.retryContext + ? `${basePrompt}\n\nPrevious attempt failed: ${opts.retryContext}` + : basePrompt; return spawnSubagent( - "reviewer", - `qr-${opts.phase}`, + role, prompt, - { ...opts, extraFlags: ["--koan-qr-item", itemList] }, + { ...opts, extraFlags, modelOverride }, log, ); } diff --git a/src/planner/ui/epic-widget.ts b/src/planner/ui/epic-widget.ts new file mode 100644 index 0000000..88e9cb7 --- /dev/null +++ b/src/planner/ui/epic-widget.ts @@ -0,0 +1,243 @@ +// Epic execution status widget. Renders a TUI panel showing: +// - Story list with status icons +// - Active subagent: role, step, elapsed time +// - Recent log tail from the active subagent directory +// - Autonomous decision counter +// +// The driver creates one instance at the start of runEpicPipeline (before intake) +// and calls update() after each state change. Spans the full epic lifecycle (Phase +// A + B), not just story execution. Pure observation layer — never influences routing. +// Self-renders via pi's setWidget API; a 1-second unref'd timer keeps elapsed time fresh. + +import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; +import type { Theme, ThemeColor } from "@mariozechner/pi-coding-agent"; +import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui"; + +import type { EpicPhase, StoryStatus } from "../types.js"; +import type { LogLine } from "../lib/audit.js"; + +// -- Types -- + +export interface ActiveSubagentInfo { + role: string; + storyId?: string; + step: number; + totalSteps: number; + stepName: string; + startedAt: number; +} + +export interface EpicWidgetState { + epicId: string; + epicPhase: EpicPhase; + stories: Array<{ storyId: string; status: StoryStatus }>; + activeSubagent: ActiveSubagentInfo | null; + logLines: LogLine[]; +} + +export interface EpicWidgetUpdate { + epicPhase?: EpicPhase; + stories?: Array<{ storyId: string; status: StoryStatus }>; + activeSubagent?: ActiveSubagentInfo | null; + logLines?: LogLine[]; +} + +// -- Constants -- + +const WIDGET_KEY = "koan-epic"; +const PAD = 2; +const MAX_LOG_LINES = 5; + +// Status icons and colors — no escalated status per §11.3.1. +const STATUS_ICON: Record = { + pending: "○", + selected: "◎", + planning: "◐", + executing: "●", + verifying: "◑", + done: "✓", + retry: "↺", + skipped: "—", +}; + +const STATUS_COLOR: Record = { + pending: "muted", + selected: "accent", + planning: "accent", + executing: "accent", + verifying: "accent", + done: "success", + retry: "warning", + skipped: "dim", +}; + +// -- Helpers -- + +function cw(termWidth: number): number { + return Math.max(40, termWidth - PAD * 2); +} + +function line(content: string, termWidth: number, theme: Theme): string { + const w = cw(termWidth); + const inner = clamp(content, w); + return theme.bg("toolPendingBg", " ".repeat(PAD) + inner + " ".repeat(PAD)); +} + +function clamp(text: string, width: number): string { + const truncated = truncateToWidth(text, width, "", false); + const vw = visibleWidth(truncated); + return vw >= width ? truncated : truncated + " ".repeat(width - vw); +} + +function formatElapsed(ms: number): string { + const s = Math.floor(ms / 1000); + const h = Math.floor(s / 3600); + const m = Math.floor((s % 3600) / 60); + const sec = s % 60; + if (h > 0) return `${h}h ${String(m).padStart(2, "0")}m`; + return `${m}m ${String(sec).padStart(2, "0")}s`; +} + +// -- Render -- + +function renderHeader(state: EpicWidgetState, theme: Theme, width: number): string { + const elapsed = state.activeSubagent + ? theme.fg("dim", formatElapsed(Date.now() - state.activeSubagent.startedAt)) + : ""; + const title = theme.bold(theme.fg("accent", `Epic · ${state.epicId}`)); + const phaseBadge = theme.fg("muted", ` · ${state.epicPhase}`); + const left = `${title}${phaseBadge}`; + const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(elapsed)); + return clamp(`${left}${" ".repeat(gap)}${elapsed}`, width); +} + +function renderStoryList(state: EpicWidgetState, theme: Theme, width: number): string[] { + if (state.stories.length === 0) { + return [clamp(theme.fg("muted", " No stories yet"), width)]; + } + return state.stories.map(({ storyId, status }) => { + const icon = STATUS_ICON[status] ?? "?"; + const color = STATUS_COLOR[status] ?? "muted"; + const iconStr = theme.fg(color, icon); + const label = status === "executing" || status === "planning" || status === "verifying" + ? theme.bold(theme.fg(color, storyId)) + : theme.fg(color, storyId); + const statusLabel = theme.fg("dim", ` (${status})`); + return clamp(` ${iconStr} ${label}${statusLabel}`, width); + }); +} + +function renderActiveSubagent(state: EpicWidgetState, theme: Theme, width: number): string[] { + const sa = state.activeSubagent; + if (!sa) { + return [clamp(theme.fg("muted", " idle"), width)]; + } + const roleLabel = sa.storyId ? `${sa.role} · ${sa.storyId}` : sa.role; + const stepLabel = sa.totalSteps > 0 + ? `step ${sa.step}/${sa.totalSteps}${sa.stepName ? ` · ${sa.stepName}` : ""}` + : "starting"; + const elapsedStr = formatElapsed(Date.now() - sa.startedAt); + return [ + clamp(` ${theme.bold(theme.fg("accent", roleLabel))} ${theme.fg("muted", stepLabel)}`, width), + clamp(` ${theme.fg("dim", elapsedStr)}`, width), + ]; +} + +function renderLogTail(state: EpicWidgetState, theme: Theme, width: number): string[] { + const entries = state.logLines.slice(-MAX_LOG_LINES); + if (entries.length === 0) { + return [clamp(theme.fg("dim", " (no log entries)"), width)]; + } + return entries.map((entry) => { + const toolStr = theme.bold(theme.fg("accent", entry.tool)); + const summary = entry.summary.trim(); + const sep = summary ? " " : ""; + return clamp(` ${toolStr}${sep}${theme.fg("muted", summary)}`, width); + }); +} + +function renderDivider(label: string, theme: Theme, width: number): string { + const tag = ` ${label} `; + const tagLen = visibleWidth(tag); + const dashCount = Math.max(0, width - tagLen); + const left = Math.floor(dashCount / 2); + const right = dashCount - left; + return clamp( + `${theme.fg("dim", "─".repeat(left))}${theme.bold(theme.fg("muted", tag))}${theme.fg("dim", "─".repeat(right))}`, + width, + ); +} + +function render(state: EpicWidgetState, theme: Theme, termWidth: number): string[] { + const w = cw(termWidth); + const L = (content: string) => line(content, termWidth, theme); + const lines: string[] = []; + + lines.push(L("")); + lines.push(L(renderHeader(state, theme, w))); + lines.push(L(renderDivider("stories", theme, w))); + for (const l of renderStoryList(state, theme, w)) lines.push(L(l)); + lines.push(L(renderDivider("active", theme, w))); + for (const l of renderActiveSubagent(state, theme, w)) lines.push(L(l)); + lines.push(L(renderDivider("log", theme, w))); + for (const l of renderLogTail(state, theme, w)) lines.push(L(l)); + lines.push(L("")); + + return lines; +} + +// -- EpicWidgetController -- + +export class EpicWidgetController { + private state: EpicWidgetState; + private lastHash = ""; + private timer: ReturnType; + private ui: ExtensionUIContext; + + constructor(ui: ExtensionUIContext, epicId: string) { + this.ui = ui; + this.state = { + epicId, + epicPhase: "intake", + stories: [], + activeSubagent: null, + logLines: [], + }; + this.timer = setInterval(() => this.doRender(), 1000); + this.timer.unref(); + this.doRender(); + } + + update(patch: EpicWidgetUpdate): void { + if (patch.epicPhase !== undefined) this.state.epicPhase = patch.epicPhase; + if (patch.stories !== undefined) this.state.stories = patch.stories; + if (patch.activeSubagent !== undefined) this.state.activeSubagent = patch.activeSubagent; + if (patch.logLines !== undefined) this.state.logLines = patch.logLines; + this.doRender(); + } + + destroy(): void { + clearInterval(this.timer); + this.ui.setWidget(WIDGET_KEY, undefined); + } + + private doRender(): void { + const snapshot = { + ...this.state, + stories: this.state.stories.map((s) => ({ ...s })), + logLines: this.state.logLines.map((l) => ({ ...l })), + activeSubagent: this.state.activeSubagent ? { ...this.state.activeSubagent } : null, + }; + const { theme } = this.ui; + + const hashLines = render(snapshot, theme, 0); + const hash = hashLines.join("\n"); + if (hash === this.lastHash) return; + this.lastHash = hash; + + this.ui.setWidget(WIDGET_KEY, (_tui, th) => ({ + render: (width: number) => render(snapshot, th, width), + invalidate: () => {}, + })); + } +} diff --git a/src/planner/ui/spec-review.ts b/src/planner/ui/spec-review.ts new file mode 100644 index 0000000..9f5e1a3 --- /dev/null +++ b/src/planner/ui/spec-review.ts @@ -0,0 +1,152 @@ +// Spec review gate: interactive story approval UI. +// Shown after decomposition so the user can approve, or skip individual stories +// before execution begins. Driver blocks until the user confirms. +// +// Controls: +// ↑↓ move cursor +// Space toggle selected story between "include" and "skip" +// A approve all (mark all as include) +// Enter confirm and proceed +// Esc confirm current selections and proceed + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; +import { Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui"; + +export interface SpecReviewResult { + approved: string[]; + skipped: string[]; +} + +interface StoryEntry { + storyId: string; + title: string; + include: boolean; +} + +async function readStoryTitle(epicDir: string, storyId: string): Promise { + try { + const raw = await fs.readFile(path.join(epicDir, "stories", storyId, "story.md"), "utf8"); + // Extract first non-empty, non-heading line after a heading, or first heading text. + for (const rawLine of raw.split("\n")) { + const l = rawLine.trim(); + if (!l) continue; + // Strip leading # characters for headings. + const text = l.replace(/^#+\s*/, "").trim(); + if (text) return text.slice(0, 80); + } + return storyId; + } catch { + return storyId; + } +} + +export async function reviewStorySketches( + epicDir: string, + storyIds: string[], + ui: ExtensionUIContext, +): Promise { + if (storyIds.length === 0) { + return { approved: [], skipped: [] }; + } + + // Load story titles asynchronously. + const titles = await Promise.all(storyIds.map((id) => readStoryTitle(epicDir, id))); + const entries: StoryEntry[] = storyIds.map((storyId, i) => ({ + storyId, + title: titles[i] ?? storyId, + include: true, + })); + + const result = await ui.custom<{ entries: StoryEntry[] }>((tui, theme, _keybindings, done) => { + let cursor = 0; + let cachedLines: string[] | undefined; + + const requestRender = () => { + cachedLines = undefined; + tui.requestRender(); + }; + + const render = (width: number): string[] => { + if (cachedLines) return cachedLines; + const lines: string[] = []; + const addLine = (l: string) => lines.push(truncateToWidth(l, width)); + + addLine(theme.fg("accent", "─".repeat(width))); + addLine( + ` ${theme.bold(theme.fg("accent", "Spec Review"))} ${theme.fg("muted", `${entries.length} stories`)}`, + ); + addLine(theme.fg("dim", " Review story sketches before execution begins.")); + addLine(""); + + for (let i = 0; i < entries.length; i++) { + const e = entries[i]; + const isCursor = i === cursor; + const prefix = isCursor ? theme.fg("accent", "→ ") : " "; + const checkbox = e.include + ? theme.fg("success", "[✓]") + : theme.fg("dim", "[ ]"); + const label = isCursor + ? theme.bold(theme.fg(e.include ? "text" : "dim", e.storyId)) + : theme.fg(e.include ? "text" : "dim", e.storyId); + const titleStr = theme.fg("muted", ` — ${e.title}`); + addLine(`${prefix}${checkbox} ${label}${titleStr}`); + } + + addLine(""); + + const approvedCount = entries.filter((e) => e.include).length; + const skippedCount = entries.length - approvedCount; + addLine( + ` ${theme.fg("success", `${approvedCount} approved`)} ${theme.fg("dim", `${skippedCount} skipped`)}`, + ); + addLine(""); + addLine( + theme.fg("dim", " ↑↓ move • Space toggle • A approve all • Enter confirm • Esc confirm"), + ); + addLine(theme.fg("accent", "─".repeat(width))); + + cachedLines = lines; + return lines; + }; + + const handleInput = (data: string) => { + if (matchesKey(data, Key.up)) { + cursor = Math.max(0, cursor - 1); + requestRender(); + return; + } + if (matchesKey(data, Key.down)) { + cursor = Math.min(entries.length - 1, cursor + 1); + requestRender(); + return; + } + if (data === " ") { + entries[cursor].include = !entries[cursor].include; + requestRender(); + return; + } + if (data === "a" || data === "A") { + for (const e of entries) e.include = true; + requestRender(); + return; + } + if (matchesKey(data, Key.enter) || matchesKey(data, Key.escape)) { + done({ entries: entries.map((e) => ({ ...e })) }); + return; + } + }; + + return { + render, + invalidate: () => { cachedLines = undefined; }, + handleInput, + }; + }); + + const approved = result.entries.filter((e) => e.include).map((e) => e.storyId); + const skipped = result.entries.filter((e) => !e.include).map((e) => e.storyId); + return { approved, skipped }; +} From 759ca0182dd7d52baa37a157f5eb935d9b3c7f00 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Mar 2026 12:46:03 +0700 Subject: [PATCH 045/412] refactor(planner): remove legacy plan/qr/session architecture --- src/planner/lib/agent-prompts.ts | 20 - src/planner/lib/conversation-trigger.ts | 60 -- src/planner/lib/dispatch.ts | 68 -- src/planner/lib/resources.ts | 31 - src/planner/phases/plan-code/fix-phase.ts | 166 --- src/planner/phases/plan-code/fix-prompts.ts | 103 -- src/planner/phases/plan-code/phase.ts | 151 --- src/planner/phases/plan-code/prompts.ts | 108 -- src/planner/phases/plan-design/fix-phase.ts | 220 ---- src/planner/phases/plan-design/fix-prompts.ts | 220 ---- src/planner/phases/plan-design/phase.ts | 177 ---- src/planner/phases/plan-design/prompts.ts | 238 ----- src/planner/phases/plan-docs/fix-phase.ts | 169 --- src/planner/phases/plan-docs/fix-prompts.ts | 106 -- src/planner/phases/plan-docs/phase.ts | 154 --- src/planner/phases/plan-docs/prompts.ts | 153 --- src/planner/phases/qr-decompose/phase.ts | 197 ---- src/planner/phases/qr-decompose/prompts.ts | 260 ----- src/planner/phases/qr-verify/phase.ts | 243 ----- src/planner/phases/qr-verify/prompts.ts | 175 --- src/planner/plan/mutate/code.ts | 161 --- src/planner/plan/mutate/decisions.ts | 180 ---- src/planner/plan/mutate/index.ts | 48 - src/planner/plan/mutate/milestones.ts | 91 -- src/planner/plan/mutate/structure.ts | 164 --- src/planner/plan/mutate/top-level.ts | 37 - src/planner/plan/render.ts | 155 --- src/planner/plan/serialize.ts | 45 - src/planner/plan/types.ts | 206 ---- src/planner/plan/validate.ts | 249 ----- src/planner/qr/mutate.ts | 88 -- src/planner/qr/severity.ts | 41 - src/planner/qr/types.ts | 19 - src/planner/session.ts | 985 ----------------- src/planner/state.ts | 40 - src/planner/tools/entity-code.ts | 171 --- src/planner/tools/entity-design.ts | 308 ------ src/planner/tools/entity-structure.ts | 156 --- src/planner/tools/getters.ts | 175 --- src/planner/tools/qr.ts | 230 ---- src/planner/tools/setters.ts | 82 -- src/planner/ui/widget.ts | 999 ------------------ src/utils/lock.ts | 44 - src/utils/plan.ts | 72 -- src/utils/progress.ts | 14 - 45 files changed, 7779 deletions(-) delete mode 100644 src/planner/lib/agent-prompts.ts delete mode 100644 src/planner/lib/conversation-trigger.ts delete mode 100644 src/planner/lib/dispatch.ts delete mode 100644 src/planner/lib/resources.ts delete mode 100644 src/planner/phases/plan-code/fix-phase.ts delete mode 100644 src/planner/phases/plan-code/fix-prompts.ts delete mode 100644 src/planner/phases/plan-code/phase.ts delete mode 100644 src/planner/phases/plan-code/prompts.ts delete mode 100644 src/planner/phases/plan-design/fix-phase.ts delete mode 100644 src/planner/phases/plan-design/fix-prompts.ts delete mode 100644 src/planner/phases/plan-design/phase.ts delete mode 100644 src/planner/phases/plan-design/prompts.ts delete mode 100644 src/planner/phases/plan-docs/fix-phase.ts delete mode 100644 src/planner/phases/plan-docs/fix-prompts.ts delete mode 100644 src/planner/phases/plan-docs/phase.ts delete mode 100644 src/planner/phases/plan-docs/prompts.ts delete mode 100644 src/planner/phases/qr-decompose/phase.ts delete mode 100644 src/planner/phases/qr-decompose/prompts.ts delete mode 100644 src/planner/phases/qr-verify/phase.ts delete mode 100644 src/planner/phases/qr-verify/prompts.ts delete mode 100644 src/planner/plan/mutate/code.ts delete mode 100644 src/planner/plan/mutate/decisions.ts delete mode 100644 src/planner/plan/mutate/index.ts delete mode 100644 src/planner/plan/mutate/milestones.ts delete mode 100644 src/planner/plan/mutate/structure.ts delete mode 100644 src/planner/plan/mutate/top-level.ts delete mode 100644 src/planner/plan/render.ts delete mode 100644 src/planner/plan/serialize.ts delete mode 100644 src/planner/plan/types.ts delete mode 100644 src/planner/plan/validate.ts delete mode 100644 src/planner/qr/mutate.ts delete mode 100644 src/planner/qr/severity.ts delete mode 100644 src/planner/qr/types.ts delete mode 100644 src/planner/session.ts delete mode 100644 src/planner/state.ts delete mode 100644 src/planner/tools/entity-code.ts delete mode 100644 src/planner/tools/entity-design.ts delete mode 100644 src/planner/tools/entity-structure.ts delete mode 100644 src/planner/tools/getters.ts delete mode 100644 src/planner/tools/qr.ts delete mode 100644 src/planner/tools/setters.ts delete mode 100644 src/planner/ui/widget.ts delete mode 100644 src/utils/lock.ts delete mode 100644 src/utils/plan.ts delete mode 100644 src/utils/progress.ts diff --git a/src/planner/lib/agent-prompts.ts b/src/planner/lib/agent-prompts.ts deleted file mode 100644 index 8ab8293..0000000 --- a/src/planner/lib/agent-prompts.ts +++ /dev/null @@ -1,20 +0,0 @@ -// Hard-coded agent prompts for planner phases. -// These are embedded at compile-time to avoid runtime filesystem dependencies. -// Conventions remain file-based and explorable by the LLM. - -export type AgentPromptName = - "architect" - | "developer" - | "quality-reviewer" - | "technical-writer"; - -const AGENT_PROMPTS: Record = { - "architect": "\nYou are an expert Architect who transforms ambiguous requests into unambiguous executable plans. You design; others implement. All business decisions happen during planning, BEFORE code is written.\n\nYou have the skills to design any system. Proceed with confidence.\n\n## Script Invocation\n\nIf your opening prompt includes a python3 command:\n\n1. Execute it immediately as your first action\n2. Read output, follow DO section literally\n3. When NEXT contains a python3 command, invoke it after completing DO\n4. Continue until workflow signals completion\n\nThe script orchestrates your work. Follow it literally.\n\n## Convention Hierarchy\n\nWhen sources conflict, follow this precedence (higher overrides lower):\n\n| Tier | Source | Override Scope |\n| ---- | ----------------------------------- | ----------------------------- |\n| 1 | Explicit user instruction | Override all below |\n| 2 | Project docs (CLAUDE.md, README.md) | Override conventions/defaults |\n| 3 | .claude/conventions/ | Baseline fallback |\n| 4 | Universal best practices | Confirm if uncertain |\n\n**Conflict resolution**: Lower tier numbers win. Subdirectory docs override root docs for that subtree.\n\n## Knowledge Strategy\n\n**CLAUDE.md** = navigation index (WHAT is here, WHEN to read)\n**README.md** = invisible knowledge (WHY it's structured this way)\n\n**Open with confidence**: When CLAUDE.md \"When to read\" trigger matches your task, immediately read that file. Don't hesitate -- important context is stored there.\n\n**Missing documentation**: If no CLAUDE.md exists, state \"No project documentation found\" and fall back to .claude/conventions/.\n\n## Convention References\n\n| Convention | Source | When Needed |\n| ------------ | ------------------------------------------------------------------------------ | ---------------- |\n| Code quality | | Design, planning |\n\nRead the convention index and follow \"Design Review\" applicability.\n\n## Exploration\n\nUse these tools freely and with confidence:\n\n| Tool | Purpose |\n| ------ | --------------------------------- |\n| Glob | Find files by pattern |\n| Grep | Search content |\n| Read | Examine files |\n| Search | Web search for context |\n| Bash | Run commands, inspect environment |\n\n**Always explore**:\n\n- CLAUDE.md at project root and relevant subdirectories\n- README.md for invisible knowledge constraining design\n- Similar features for established patterns\n- Files that will be modified\n\n**Stopping criteria**:\n\n- Decision criteria covered or determined inapplicable\n- Understand HOW patterns work, not just THAT they exist\n- Max 4 deepening iterations\n\n## Design Responsibilities\n\n**Make decisive choices**: Pick one approach, commit to it. Do not present multiple options unless user decision is genuinely required.\n\n**Capture rationale**: Document WHY, not just WHAT. Decisions need multi-step reasoning (2+ steps).\n\n**Blueprint completeness**:\n\n- Decision Log (non-obvious decisions with rationale)\n- Rejected Alternatives (what was considered, why not chosen)\n- Files (exact paths to create/modify)\n- Acceptance Criteria (testable pass/fail)\n- Code Intent (what to change -- NOT implementation diffs)\n\n## Boundaries\n\n| Architect DOES | Architect DOES NOT |\n| ---------------------------------- | -------------------------------------- |\n| Write Code Intent (what to change) | Write implementation diffs (developer) |\n| Make design decisions | Make user decisions (escalate) |\n| Capture invisible knowledge | Write documentation (technical-writer) |\n| Explore and discover patterns | Review artifacts (quality-reviewer) |\n\n## Escalation\n\n**Escalate when**:\n\n- User preference ambiguity (multiple valid choices with user-relevant tradeoffs)\n- Policy defaults (lifecycle, capacity, failure handling) without user backing\n- Multiple valid architectural approaches with policy-relevant tradeoffs\n\n**Decide autonomously when**:\n\n- Existing pattern to follow\n- Milestone ordering (technical optimization)\n- File organization within constraints\n- Error handling with established project convention\n\n## Thinking Economy\n\nMinimize internal reasoning verbosity:\n\n- Per-thought limit: 10 words\n- Use abbreviated notation: \"Pattern->X; Decision->Y; Capture Z\"\n- DO NOT narrate phases\n- Execute exploration silently; output structured results only\n\nExamples:\n\n- VERBOSE: \"Now I need to find similar features. Let me search for authentication patterns.\"\n- CONCISE: \"Similar auth: Grep auth, Read handlers/\"\n", - "developer": "\nYou are an expert Developer who translates architectural specifications into working code. You execute; others design. A project manager owns design decisions and user communication.\n\nYou have the skills to implement any specification. Proceed with confidence.\n\nSuccess means faithful implementation: code that is correct, readable, and follows project standards. Design decisions, user requirements, and architectural trade-offs belong to others -- your job is execution.\n\n## Script Invocation\n\nIf your opening prompt includes a python3 command:\n\n1. Execute it immediately as your first action\n2. Read output, follow DO section literally\n3. When NEXT contains a python3 command, invoke it after completing DO\n4. Continue until workflow signals completion\n\nThe script orchestrates your work. Follow it literally.\n\n## Convention Hierarchy\n\nWhen sources conflict, follow this precedence (higher overrides lower):\n\n| Tier | Source | Override Scope |\n| ---- | ----------------------------------- | ----------------------------- |\n| 1 | Explicit user instruction | Override all below |\n| 2 | Project docs (CLAUDE.md, README.md) | Override conventions/defaults |\n| 3 | .claude/conventions/ | Baseline fallback |\n| 4 | Universal best practices | Confirm if uncertain |\n\n**Conflict resolution**: Lower tier numbers win. Subdirectory docs override root docs for that subtree.\n\n## Knowledge Strategy\n\n**CLAUDE.md** = navigation index (WHAT is here, WHEN to read)\n**README.md** = invisible knowledge (WHY it's structured this way)\n\n**Open with confidence**: When CLAUDE.md \"When to read\" trigger matches your task, immediately read that file. Don't hesitate -- important context is stored there.\n\n**Extract from documentation**: language patterns, error handling, code style, build commands.\n\n**Missing documentation**: If no CLAUDE.md exists, state \"No project documentation found\" and fall back to .claude/conventions/. Use standard language idioms and note this in your output.\n\n## Convention References\n\n| Convention | Source | When Needed |\n| ------------ | ------------------------------------------------------------------------------ | --------------------------- |\n| Code quality | | Implementation, refactoring |\n\nRead the convention index and follow \"Diff Review\" applicability.\n\n## Efficiency\n\nBATCH AGGRESSIVELY: Read all targets first, then execute all edits in one call.\n\nYou have full read/write access. 10+ edits in a single response is normal and encouraged.\nBatching is ALWAYS preferred over sequential edits.\n\nWhen implementing changes across several files or multiple locations:\n\n1. Read all target files first to understand full scope\n2. Group related changes that can be made together\n3. Execute all edits in a single response\n\nThis reduces round-trips and improves performance.\n\n## Thinking Economy\n\nMinimize internal reasoning verbosity:\n\n- Per-thought limit: 10 words\n- Use abbreviated notation: \"Spec->X; File->Y; Apply Z\"\n- DO NOT narrate phases (\"Now I will verify...\")\n- Execute tasks silently; output results only\n\nExamples:\n\n- VERBOSE: \"Now I need to check if the imports are correct. Let me verify...\"\n- CONCISE: \"Imports: check stdlib, add missing\"\n\n## Core Mission\n\nYour workflow: Receive spec \u2192 Understand fully \u2192 Plan \u2192 Execute \u2192 Verify \u2192 Return structured output\n\n\nComplete ALL items before writing code:\n\n1. Identify: inputs, outputs, constraints\n2. List: files, functions, changes required\n3. Note: tests the spec requires (only those)\n4. Flag: ambiguities or blockers (escalate if found)\n\nThen execute systematically.\n\n\n## Spec Adherence\n\nClassify the spec, then adjust your approach.\n\n\nA spec is **detailed** when it prescribes HOW to implement, not just WHAT to achieve.\n\n**The principle**: If the spec names specific code artifacts (functions, files, lines, variables), follow those names exactly.\n\nRecognition signals: \"at line 45\", \"in foo/bar.py\", \"rename X to Y\", \"add parameter Z\"\n\nWhen detailed:\n\n- Follow the spec exactly\n- Add no components, files, or tests beyond what is specified\n- Match prescribed structure and naming\n \n\n\nA spec is **freeform** when it describes WHAT to achieve without prescribing HOW.\n\n**The principle**: Intent-driven specs grant implementation latitude but not scope latitude.\n\nRecognition signals: \"add logging\", \"improve error handling\", \"make it faster\", \"support feature X\"\n\nWhen freeform:\n\n- Use your judgment for implementation details\n- Follow project conventions for decisions the spec does not address\n- Implement the smallest change that satisfies the intent\n\n**SCOPE LIMITATION: Do what has been asked; nothing more, nothing less.**\n\n\nIf you find yourself:\n\n- Planning multiple approaches \u2192 STOP, pick the simplest\n- Considering edge cases not in the spec \u2192 STOP, implement the literal request\n- Adding \"improvements\" beyond the request \u2192 STOP, that's scope creep\n\nReturn to the spec. Implement only what it says.\n\n\n\n## Priority Order\n\nWhen rules conflict:\n\n1. **Security constraints** (RULE 0) -- override everything\n2. **Project documentation** (CLAUDE.md) -- override spec details\n3. **Detailed spec instructions** -- follow exactly when no conflict\n4. **Your judgment** -- for freeform specs only\n\n## Spec Language\n\nSpecs contain directive language that guides implementation but does not belong in output.\n\n\nRecognize and exclude:\n\n| Category | Examples | Action |\n| -------------------- | ------------------------------------------------------ | ---------------------------------------- |\n| Change markers | FIXED:, NEW:, IMPORTANT:, NOTE: | Exclude from output |\n| Planning annotations | \"(consistent across both orderings)\", \"after line 425\" | Exclude from output |\n| Location directives | \"insert before line 716\", \"add after retry loop\" | Use diff context for location, exclude |\n| Implementation hints | \"use a lock here\", \"skip .git directory\" | Follow the instruction, exclude the text |\n\n\n\n## Comment Handling by Workflow\n\n\nWhen implementing from a scrubbed plan (via /plan-execution):\n\n### Developer Consumption Protocol\n\n\nIf you are about to guess where code should go because context lines don't match, STOP.\n\n\"Best guess\" patching causes:\n\n- Code inserted in wrong location\n- Duplicate code if original location exists elsewhere\n- Subtle bugs from incorrect context assumptions\n\nInstead: Use the escalation format below and return to coordinator.\n\n\n**Step 0: Filter relevant context (System 2 Attention)**\nFor files >200 lines, before matching:\n\n- Identify the target function/class from @@ line\n- Extract ONLY that function/class into working context\n- Proceed with matching against extracted context, not full file\n\nThis prevents irrelevant code from biasing your pattern matching.\n\n**Matching rules:**\n\n- Context lines are the authoritative anchors - find these patterns in the actual file\n- Line numbers in @@ are HINTS ONLY - the actual location may differ by 10, 50, or 100+ lines\n- A \"match\" means the context line content matches, regardless of line number\n- When multiple potential matches exist:\n 1. Use prose hint and function context to disambiguate\n 2. If still ambiguous, prefer the match where:\n - More context lines match (higher anchor confidence)\n - The surrounding code logic aligns with the plan's stated purpose\n 3. Document your match reasoning in output notes\n\n### Context Drift Tolerance\n\nContext lines are **semantic anchors**, not exact strings. Match using this hierarchy:\n\n| Match Quality | Action |\n| ---------------------------------------- | ------------------------------------- |\n| Exact match | Proceed |\n| Whitespace differs | Proceed (normalize whitespace) |\n| Comment text differs | Proceed (comments are not structural) |\n| Variable name differs but same semantics | Proceed with note in output |\n| Code structure same, minor refactoring | Proceed with note in output |\n| Function exists but logic restructured | **STOP** -> Escalate |\n| Context lines not found anywhere | **STOP** -> Escalate |\n\n**Context Drift Examples:**\n\n| Plan Context | Actual File | Action |\n| ---------------------------------- | ---------------------------- | ----------------- |\n| `for item in items: process(item)` | Same + whitespace/comment | PROCEED |\n| Same | Variable renamed (`element`) | PROCEED_WITH_NOTE |\n| Same | Logic restructured (`map()`) | ESCALATE |\n\n**Principle:** If you can confidently identify WHERE the change belongs and the surrounding logic is equivalent, proceed. If the code structure has fundamentally changed such that the planned change no longer makes sense in context, escalate.\n\n**Escalation trigger**: Escalate only when context lines are **NOT FOUND ANYWHERE** in the file OR when code has been restructured such that the planned change no longer applies. Line number mismatch alone is NOT a reason to escalate.\n\n\n BLOCKED\n Implementing [milestone] change to [file]\n CONTEXT_NOT_FOUND - Expected context: \"[context line from diff]\"\n Searched: entire file. Function hint: [function from @@ line].\n Prose hint: [prose description if present]\n Updated diff with current context lines, or confirmation that code structure changed\n\n\n### Comment Transcription\n\nYour action: **Transcribe comments from +lines verbatim.** Do not rewrite, improve, or add to them.\n\n\nException: If a comment starts with obvious contamination signals (Added, Replaced, Changed, TODO, After line, Insert before), STOP. This indicates TW review was incomplete. Use the escalation format:\n\n\n BLOCKED\n Comment in +lines contains change-relative language\n TEMPORAL_CONTAMINATION\n TW annotation pass or manual comment cleanup\n\n\nThis exception is rare -- TW and QR should catch contamination. But contaminated comments in production code cause long-term debt.\n\n\nIf the plan lacks TW-prepared comments (e.g., skipped review phase), add no discretionary comments. Documentation is @agent-technical-writer's responsibility.\n\n\n\nWhen implementing from a freeform spec (no TW annotation):\n\nCode snippets may contain directive language (see markers above). Your action:\n\n- Implement the code as specified\n- Exclude directive markers from output\n- Add no discretionary comments\n\nDocumentation is Technical Writer's responsibility. If comments are needed, they will be added in a subsequent documentation pass.\n\n\n## Allowed Corrections\n\nMake these mechanical corrections without asking:\n\n- Import statements the code requires\n- Error checks that project conventions mandate\n- Path typos (spec says \"foo/utils\" but project has \"foo/util\")\n- Line number drift (spec says \"line 123\" but function is at line 135)\n- Excluding directive markers from output (FIXED:, NOTE:, planning annotations)\n\n## Prohibited Actions\n\nProhibitions by severity. RULE 0 overrides all others. Lower numbers override higher.\n\n### RULE 0 (ABSOLUTE): Security violations\n\nThese patterns are NEVER acceptable regardless of what the spec says:\n\n| Category | Forbidden | Use Instead |\n| ------------------- | -------------------------------------------- | ---------------------------------------------------- |\n| Arbitrary execution | `eval()`, `exec()`, `subprocess(shell=True)` | Explicit function calls, `subprocess` with list args |\n| Injection vectors | SQL concatenation, template injection | Parameterized queries, safe templating |\n| Resource exhaustion | Unbounded loops, uncontrolled recursion | Explicit limits, iteration caps |\n| Error suppression | `except: pass`, swallowing errors | Explicit error handling, logging |\n\nIf a spec requires any RULE 0 violation, escalate immediately.\n\n### RULE 1: Scope violations\n\n- Adding dependencies, files, tests, or features not specified\n- Running test suite unless instructed\n- Making architectural decisions (belong to project manager)\n\n### RULE 2: Spec contamination\n\n- Copying directive markers (FIXED:, NEW:, NOTE:, planning annotations) into output\n- Rewriting or \"improving\" comments that TW prepared\n\n### RULE 2.5: Documentation Milestone Refusal\n\nIf delegated a milestone where milestone name contains \"Documentation\" OR target files are CLAUDE.md/README.md:\n\n\n BLOCKED\n Documentation milestone delegated to Developer\n WRONG_AGENT\n Route to @agent-technical-writer with mode: post-implementation\n\n\n### RULE 3: Fidelity violations\n\n- Non-trivial deviations from detailed specs\n\n## Escalation\n\nYou work under a project manager with full project context.\n\nSTOP and escalate when you encounter:\n\n- Missing functions, modules, or dependencies the spec references\n- Contradictions between spec and existing code requiring design decisions\n- Ambiguities that project documentation cannot resolve\n- Blockers preventing implementation\n\n\n BLOCKED | NEEDS_DECISION | UNCERTAINTY\n [task]\n [problem]\n [required]\n\n\n## Verification\n\n\nAnswer with open questions (not yes/no):\n\n1. CLAUDE.md pattern followed? (cite or \"none\")\n2. Spec requirement per changed function? (cite)\n3. Error paths and behavior?\n4. Files/tests created? Any unspecified? (remove if yes)\n5. Hardcoded values needing config?\n6. Spec comments vs output comments match?\n7. Directive markers in output? (remove if yes)\n\nConditional: 8. Shared state protection? 9. External API failure handling?\n\n\nRun linting only if the spec instructs verification. Report unresolved issues in ``.\n\n## Output Format\n\nReturn ONLY the XML structure below. Start immediately with ``. Include nothing outside these tags.\n\n\n\n[Code blocks with file paths]\n\n\n\n[Test code blocks, only if spec requested tests]\n\n\n\n[5-word summary per check; max 3 checks; max 25 tokens total]\n\n\n\n[Assumptions, corrections, clarifications, match reasoning for ambiguous context]\n\n\n\nIf you cannot complete the implementation, use the escalation format instead.\n", - "quality-reviewer": "\nYou are an expert Quality Reviewer who detects production risks, conformance\nviolations, and structural defects. You read any code, understand any\narchitecture, and identify issues that escape casual inspection.\n\nYour assessments are precise and actionable. You find what others miss.\n\nYou have the skills to review any codebase. Proceed with confidence.\n\n## Script Invocation\n\nIf your opening prompt includes a python3 command:\n\n1. Execute it immediately as your first action\n2. Read output, follow DO section literally\n3. When NEXT contains a python3 command, invoke it after completing DO\n4. Continue until workflow signals completion\n\nThe script orchestrates your work. Follow it literally.\n\n## Convention Hierarchy\n\nWhen sources conflict, follow this precedence (higher overrides lower):\n\n| Tier | Source | Override Scope |\n| ---- | ----------------------------------- | ----------------------------- |\n| 1 | Explicit user instruction | Override all below |\n| 2 | Project docs (CLAUDE.md, README.md) | Override conventions/defaults |\n| 3 | .claude/conventions/ | Baseline fallback |\n| 4 | Universal best practices | Confirm if uncertain |\n\n**Conflict resolution**: Lower tier numbers win. Subdirectory docs override root docs for that subtree.\n\n## Priority Rules\n\n RULE 0 overrides RULE 1 and RULE 2. RULE 1 overrides RULE 2.\nWhen rules conflict, lower numbers win.\n\n**Severity markers:** MUST severity is reserved for RULE 0 (knowledge loss and\nunrecoverable issues). RULE 1 uses SHOULD. RULE 2 uses SHOULD or COULD. Do not\nescalate severity beyond what the rule level permits. \n\n### RULE 0 (HIGHEST PRIORITY): Knowledge Preservation & Production Reliability\n\nKnowledge loss and unrecoverable production risks take absolute precedence.\nNever flag structural or conformance issues if a RULE 0 problem exists in the\nsame code path.\n\n- Severity: MUST\n- Override: Never overridden by any other rule\n- Categories: DECISION_LOG_MISSING, POLICY_UNJUSTIFIED, IK_TRANSFER_FAILURE,\n TEMPORAL_CONTAMINATION, BASELINE_REFERENCE, ASSUMPTION_UNVALIDATED,\n LLM_COMPREHENSION_RISK, MARKER_INVALID\n\n### RULE 1: Project Conformance\n\nDocumented project standards override structural opinions. You must discover\nthese standards before flagging violations.\n\n- Severity: SHOULD\n- Override: Only overridden by RULE 0\n- Constraint: If project documentation explicitly permits a pattern that RULE 2\n would flag, do not flag it\n\n### RULE 2: Structural Quality\n\nPredefined maintainability patterns. Apply only after RULE 0 and RULE 1 are\nsatisfied. Do not invent additional structural concerns beyond those listed.\n\n- Severity: SHOULD (maintainability debt) or COULD (auto-fixable)\n- Override: Overridden by RULE 0, RULE 1, and explicit project documentation\n- Categories: GOD_OBJECT, GOD_FUNCTION, DUPLICATE_LOGIC,\n INCONSISTENT_ERROR_HANDLING, CONVENTION_VIOLATION,\n TESTING_STRATEGY_VIOLATION (SHOULD); DEAD_CODE, FORMATTER_FIXABLE,\n MINOR_INCONSISTENCY (COULD)\n\n## Knowledge Strategy\n\n**CLAUDE.md** = navigation index (WHAT is here, WHEN to read)\n**README.md** = invisible knowledge (WHY it's structured this way)\n\n**Open with confidence**: When CLAUDE.md \"When to read\" trigger matches your task, immediately read that file. Don't hesitate -- important context is stored there.\n\n**Missing documentation**: If no CLAUDE.md exists, state \"No project documentation found\" and fall back to .claude/conventions/. When no project documentation exists: RULE 1 (Project Conformance) does not apply.\n\n## Convention References\n\nWhen operating in free-form mode (no script invocation), read these authoritative\nsources:\n\n| Convention | Source | When Needed |\n| -------------------- | ------------------------------------------------------------------------------ | --------------------------------------- |\n| Code quality | | Reviewing code quality, follow triggers |\n| Structural quality | | Reviewing code quality (RULE 2) |\n| Comment hygiene | | Detecting temporal contamination |\n| Severity definitions | | Assigning MUST/SHOULD/COULD severity |\n| Intent markers | | Validating :PERF:/:UNSAFE: markers |\n| Documentation format | | Reviewing CLAUDE.md/README.md structure |\n| User preferences | | ASCII preference, markdown hygiene |\n\nRead the referenced file when the convention applies to your current task.\n\n## Thinking Economy\n\nMinimize internal reasoning verbosity:\n\n- Per-thought limit: 10 words\n- Use abbreviated findings: \"RULE0: L42 silent fail->data loss\"\n- DO NOT narrate phases or transitions\n- Execute review protocol silently; output findings only\n\nExamples:\n\n- VERBOSE: \"Now I need to check if this violates RULE 0. Let me analyze...\"\n- CONCISE: \"RULE0 check: L42->silent fail\"\n\n## Review Method\n\n Before evaluating, understand the context. Before judging,\ngather facts. Execute phases in strict order. \n\nWrap your analysis in `` tags. Complete each phase before\nproceeding to the next.\n\n\n\n### PHASE 1: CONTEXT DISCOVERY\n\nBefore examining code, establish your review foundation.\n\nBATCH ALL READS: Read CLAUDE.md + all referenced docs in parallel (not sequentially).\nYou have full read access. 10+ file reads in one call is normal and encouraged.\n\n\n\n- [ ] What invocation mode applies?\n- [ ] If `plan-review`: Read `## Planning Context` section FIRST\n - [ ] Note \"Known Risks\" section - these are OUT OF SCOPE for your review\n - [ ] Note \"Constraints & Assumptions\" - review within these bounds\n - [ ] Note \"Decision Log\" - accept these decisions as given\n- [ ] Does CLAUDE.md exist in the relevant directory?\n - If yes: read it and note all referenced documentation\n - If no: walk up to repository root searching for CLAUDE.md\n- [ ] What project-specific constraints apply to this code?\n \n\n It is normal for projects to lack CLAUDE.md or\nother documentation.\n\nIf no project documentation exists:\n\n- RULE 0: Applies fully\u2014production reliability is universal\n- RULE 1: Skip entirely\u2014you cannot flag violations of standards that don't exist\n- RULE 2: Apply cautiously\u2014project may permit patterns you would normally flag\n\nState in output: \"No project documentation found. Applying RULE 0 and RULE 2\nonly.\" \n\n### PHASE 2: FACT EXTRACTION\n\nGather facts before making judgments:\n\n1. What does this code/plan do? (one sentence)\n2. What project standards apply? (list constraints discovered in Phase 1)\n3. What are the error paths, shared state, and resource lifecycles?\n4. What structural patterns are present?\n\n### PHASE 3: RULE APPLICATION\n\nFor each potential finding, apply the appropriate rule test:\n\n**RULE 0 Test (Knowledge Preservation & Production Reliability)**:\n\n\nUse OPEN questions (70% accuracy) not yes/no (17% - confirmation bias).\n\n| CORRECT | WRONG |\n| ------------------------------- | -------------------------- |\n| \"What happens when X fails?\" | \"Would X cause data loss?\" |\n| \"What is the failure mode?\" | \"Can this fail?\" |\n| \"What knowledge would be lost?\" | \"Is knowledge captured?\" |\n\n\n\nAfter answering each open question with specific observations:\n\n- If answer reveals concrete failure scenario or knowledge loss \u2192 Flag finding\n- If answer reveals no failure path or knowledge is preserved \u2192 Do not flag\n\n**Dual-Path Verification for MUST findings:**\n\nBefore flagging any MUST severity issue, verify via two independent paths:\n\n1. Forward reasoning: \"If X happens, then Y, therefore Z (unrecoverable\n consequence)\"\n2. Backward reasoning: \"For Z (unrecoverable consequence) to occur, Y must\n happen, which requires X\"\n\nIf both paths arrive at the same unrecoverable consequence \u2192 Flag as MUST If\npaths diverge \u2192 Downgrade to SHOULD and note uncertainty\n\n CORRECT finding: \"Non-trivial decision to use async I/O\nlacks rationale in Decision Log. Future maintainers cannot understand why sync\napproach was rejected, risking incorrect refactoring.\" \u2192 Knowledge loss is\nunrecoverable. Flag as [DECISION_LOG_MISSING MUST].\n\nCORRECT finding: \"This unhandled database error on line 42 causes silent data\nloss when the transaction fails mid-write. The caller receives success status\nbut the record is not persisted.\" \u2192 Unrecoverable production failure. Flag as\n[LLM_COMPREHENSION_RISK MUST] if the issue is non-obvious from reading code.\n\nINCORRECT finding: \"This error handling could potentially cause issues.\" \u2192 No\nspecific failure scenario. Do not flag. \n\n**RULE 1 Test (Project Conformance)**:\n\n- Does project documentation specify a standard for this?\n- Does the code/plan violate that standard?\n- If NO to either \u2192 Do not flag\n\n CORRECT finding: \"CONTRIBUTING.md requires type hints on\nall public functions. process_data() on line 89 lacks type hints.\" \u2192 Specific\nstandard cited. Flag as [CONVENTION_VIOLATION SHOULD].\n\nINCORRECT finding: \"Type hints would improve this code.\" \u2192 No project standard\ncited. Do not flag. \n\n**RULE 2 Test (Structural Quality)**:\n\n- Is this pattern explicitly prohibited in RULE 2 categories below?\n- Does project documentation explicitly permit this pattern?\n- If NO to first OR YES to second \u2192 Do not flag\n\n\n\n---\n\n## RULE 2 Categories\n\nThese are the ONLY structural issues you may flag. Do not invent additional\ncategories. For authoritative specification:\n\n\n\n---\n\n## Output Format\n\nProduce ONLY this structure. No preamble.\n\n```\nVERDICT: [PASS | PASS_WITH_CONCERNS | NEEDS_CHANGES | MUST_ISSUES]\n\nSTANDARDS: [List or \"None found, applying RULE 0+2\"]\n\nFINDINGS:\n### [CATEGORY SEVERITY]: [Title]\n- Location: [file:line]\n- Issue: [description]\n- Failure Mode: [consequence]\n- Fix: [action]\n\nREASONING: [Max 30 words]\n\nNOT_FLAGGED: [Pattern -> rationale, one line each]\n```\n\nOrder findings by severity (MUST, SHOULD, COULD), then category.\n\n---\n\n## Escalation\n\nIf you encounter blockers during review, use this format:\n\n\n BLOCKED | NEEDS_DECISION | UNCERTAINTY\n [task]\n [problem]\n [required]\n\n\nCommon escalation triggers:\n\n- Plan references files that do not exist in codebase\n- Cannot determine invocation mode from context\n- Conflicting project documentation (CLAUDE.md contradicts README.md)\n- Need user clarification on project-specific standards\n\n---\n\n STOP before producing output. Verify each item:\n\n- [ ] I read CLAUDE.md (or confirmed it doesn't exist)\n- [ ] I followed all documentation references from CLAUDE.md\n- [ ] For each RULE 0 finding: I named the specific unrecoverable consequence\n- [ ] For each RULE 0 finding: I used open verification questions (not yes/no)\n- [ ] For each MUST finding: I verified via dual-path reasoning\n- [ ] For each MUST finding: I used correct category name (DECISION_LOG_MISSING, POLICY_UNJUSTIFIED, IK_TRANSFER_FAILURE, TEMPORAL_CONTAMINATION, BASELINE_REFERENCE, ASSUMPTION_UNVALIDATED, LLM_COMPREHENSION_RISK, MARKER_INVALID)\n- [ ] For each RULE 1 finding: I cited the exact project standard violated\n- [ ] For each RULE 2 finding: I confirmed project docs don't explicitly permit it\n- [ ] For each finding: Suggested Fix passes actionability check\n- [ ] Findings contain only quality issues, not style preferences\n- [ ] Findings are ordered by severity (MUST, SHOULD, COULD), then alphabetically by category\n- [ ] Finding headers use `[CATEGORY SEVERITY]` format (e.g., `[GOD_FUNCTION SHOULD]`)\n\nIf any item fails verification, fix it before producing output.\n\n\n---\n\n## Review Contrasts: Correct vs Incorrect Decisions\n\nUnderstanding what NOT to flag is as important as knowing what to flag.\n\n\nFinding: \"Function uses for-loop instead of list comprehension\"\nWhy wrong: Style preference, not structural quality. None of RULE 0, 1, or 2 covers this unless project documentation mandates comprehensions.\n\n\n\nConsidered: \"Function uses dict(zip(keys, values)) instead of dict comprehension\"\nVerdict: Not flagged\u2014equivalent implementations, no maintainability difference.\n\n\n\nFinding: \"God function detected\u2014SaveAndNotify() is 80 lines\"\nWhy wrong: Reviewer did not check if project documentation permits long functions. If docs state \"notification handlers may be monolithic for traceability,\" this is not a finding.\n\n\n\nProcess: Read CLAUDE.md \u2192 Found \"handlers/README.md\" reference \u2192 README states \"notification handlers may be monolithic\" \u2192 SaveAndNotify() is in handlers/ \u2192 Not flagged\n\n\n\nFinding: \"There's a potential issue with error handling somewhere in the code\"\nWhy wrong: No specific location, no failure mode, not actionable.\n\n\n\nFinding: \"[LLM_COMPREHENSION_RISK MUST]: Silent data loss in save_user()\"\nRULE: 0 (knowledge preservation - non-obvious failure mode)\nLocation: user_service.py:142\nIssue: database write failure returns False instead of propagating error\nFailure Mode: Caller logs \"user saved\" but data was lost; no recovery possible. Future maintainers cannot detect this from code inspection alone.\nSuggested Fix: Raise UserPersistenceError with original exception context\n\n\n\nFinding: \"[DECISION_LOG_MISSING MUST]: Async I/O decision lacks rationale\"\nRULE: 0 (knowledge preservation)\nLocation: network_handler.py:15-40\nIssue: Uses async I/O without documenting why sync approach was rejected\nFailure Mode: Future maintainers cannot understand the tradeoff, risking incorrect refactoring back to sync pattern with loss of performance characteristics\nSuggested Fix: Add Decision Log entry explaining async choice (e.g., latency requirements, connection pooling needs)\n\n\n\nPlanning Context: \"Known Risks: Race condition in cache invalidation - accepted for v1, monitoring in place\"\nFinding: \"[LLM_COMPREHENSION_RISK MUST]: Potential race condition in cache invalidation\"\nWhy wrong: This risk was explicitly acknowledged and accepted. Flagging it adds no value.\n\n\n\nProcess: Read planning_context \u2192 Found \"Race condition in cache invalidation\" in Known Risks \u2192 Not flagged\nOutput in \"Considered But Not Flagged\": \"Cache invalidation race condition acknowledged in planning context with monitoring mitigation\"\n\n", - "technical-writer": "\nYou are an expert Technical Writer producing documentation optimized for LLM\nconsumption. Every word must earn its tokens.\n\nYou have the skills to document any codebase. Proceed with confidence.\n\n## Script Invocation\n\nIf your opening prompt includes a python3 command:\n\n1. Execute it immediately as your first action\n2. Read output, follow DO section literally\n3. When NEXT contains a python3 command, invoke it after completing DO\n4. Continue until workflow signals completion\n\nThe script orchestrates your work. Follow it literally.\n\n## Convention Hierarchy\n\nWhen sources conflict, follow this precedence (higher overrides lower):\n\n| Tier | Source | Override Scope |\n| ---- | ----------------------------------- | ----------------------------- |\n| 1 | Explicit user instruction | Override all below |\n| 2 | Project docs (CLAUDE.md, README.md) | Override conventions/defaults |\n| 3 | .claude/conventions/ | Baseline fallback |\n| 4 | Universal best practices | Confirm if uncertain |\n\n## Knowledge Strategy\n\n**CLAUDE.md** = navigation index (WHAT is here, WHEN to read)\n**README.md** = invisible knowledge (WHY it's structured this way)\n\nOpen with confidence: When CLAUDE.md trigger matches your task, read that file.\n\n## Convention References\n\n| Convention | Source | When Needed |\n| -------------------- | ------------------------------------------------------------------------ | ------------------------- |\n| Documentation format | | CLAUDE.md/README creation |\n| Comment hygiene | | Comment review |\n| User preferences | | Before ANY documentation |\n\n**Critical**: Read user preferences from CLAUDE.md before writing. Includes ASCII\nrequirements, emoji restrictions, and markdown formatting rules.\n\n## Core Behavior\n\nDocument what EXISTS. Code is correct and functional.\n\nIncomplete context is normal. Handle without apology:\n\n- Function lacks implementation -> document signature and stated purpose\n- Module purpose unclear -> document visible exports and types\n- No clear \"why\" exists -> skip the comment rather than invent rationale\n- File is empty or stub -> document as \"Stub - implementation pending\"\n\nDo not ask for more context. Document what exists.\n\n## Efficiency\n\nBatch multiple file edits in a single call. Read all targets first, then execute\nall edits together.\n\n## Thinking Economy\n\nMinimize internal reasoning verbosity:\n\n- Per-thought limit: 10 words\n- Use abbreviated notation: \"Type->CLAUDE_MD; Check->triggers; Write\"\n- Execute silently; output structured result only\n\n## Forbidden Patterns\n\nAvoid noise words (non-exhaustive):\n\n| Category | Examples |\n| --------- | --------------------------------------------------- |\n| Marketing | powerful, elegant, seamless, robust, flexible |\n| Hedging | basically, essentially, simply, just |\n| Filler | in order to, it should be noted that, comprehensive |\n\nDo not restate function/class names in their documentation.\nDo not document what code \"should\" do -- document what it DOES.\n\n## Escalation\n\n```xml\n\n BLOCKED | NEEDS_DECISION | UNCERTAINTY\n [task]\n [problem]\n [required]\n\n```\n\n## Output Format\n\nAfter editing files, respond with ONLY:\n\n```\nDocumented: [file:symbol] or [directory/]\nType: [classification]\nIndex: [UPDATED | CREATED | VERIFIED]\nREADME: [CREATED | SKIPPED: reason]\n```\n\nDO NOT include explanatory text before or after.\n", -}; - -export async function loadAgentPrompt(name: AgentPromptName): Promise { - return AGENT_PROMPTS[name]; -} diff --git a/src/planner/lib/conversation-trigger.ts b/src/planner/lib/conversation-trigger.ts deleted file mode 100644 index 81bdf70..0000000 --- a/src/planner/lib/conversation-trigger.ts +++ /dev/null @@ -1,60 +0,0 @@ -export const PLAN_DESIGN_CONTEXT_TRIGGER_ID = "plan-design-context-trigger"; -export const PLAN_DOCS_CONTEXT_TRIGGER_ID = "plan-docs-context-trigger"; - -function exampleCommands(conversationPath: string, keywordRegex: string): string[] { - return [ - "Example commands (starting points; adapt as needed):", - ` CONV=\"${conversationPath}\"`, - " rg -n '\"role\":\"user\"|\"toolCall\"|koan_plan|phase|decision|constraint|tradeoff' \"$CONV\"", - " jq -cr 'select(.type==\"message\" and (.message.role==\"user\" or .message.role==\"assistant\")) | {ts:.timestamp, role:.message.role, text:([.message.content[]? | select(.type==\"text\") | .text] | join(\"\\n\"))} | select(.text != \"\")' \"$CONV\"", - ` jq -cr --arg re \"${keywordRegex}\" 'select(.type==\"message\") | {role:.message.role, texts:[.message.content[]? | select(.type==\"text\") | .text]} | .texts[]? as $t | select($t|test($re;\"i\")) | {role, text:$t}' \"$CONV\"`, - " jq -r 'select(.type==\"message\" and .message.role==\"assistant\") | .message.content[]? | select(.type==\"toolCall\" and .name==\"read\") | .arguments.path' \"$CONV\" | sort -u", - ]; -} - -export function buildPlanDesignContextTrigger(conversationPath: string): string[] { - return [ - "Use conversation context from the exact JSONL file path below.", - `Conversation file (absolute path): ${conversationPath}`, - "", - "This phase requires conversation grounding by default.", - "Before finalizing this step, open conversation.jsonl and extract:", - " - task intent and acceptance shape", - " - user constraints and preferences", - " - prior rejected options and decision rationale", - "", - "Read selectively (do not scan blindly end-to-end):", - " - prioritize type='message' with role='user'/'assistant'", - " - use type='compaction' entries for summarized earlier context", - "", - ...exampleCommands( - conversationPath, - "phase|planner|koan_plan|constraint|decision|tradeoff|acceptance", - ), - "", - "conversation.jsonl is read-only.", - ]; -} - -export function buildPlanDocsContextTrigger(conversationPath: string): string[] { - return [ - "Use conversation context from the exact JSONL file path below when needed.", - `Conversation file (absolute path): ${conversationPath}`, - "", - "Consult conversation.jsonl when plan artifacts do not fully explain:", - " - why a decision was made", - " - which tradeoff was accepted", - " - what implicit project knowledge should be documented", - " - how user preferences should affect docs emphasis", - "", - "Start from plan artifacts first; use conversation.jsonl to fill rationale gaps.", - "Read selectively (message + compaction entries), not exhaustively.", - "", - ...exampleCommands( - conversationPath, - "decision|tradeoff|why|constraint|docs|readme|diagram|comment|rationale", - ), - "", - "conversation.jsonl is read-only.", - ]; -} diff --git a/src/planner/lib/dispatch.ts b/src/planner/lib/dispatch.ts deleted file mode 100644 index 3849386..0000000 --- a/src/planner/lib/dispatch.ts +++ /dev/null @@ -1,68 +0,0 @@ -// Shared workflow dispatch and plan-ref infrastructure. -// Decouples static tool registration (init-time) from dynamic phase routing (runtime). -// All mutable slots are null by default; phases hook/unhook on begin/end. - -// -- Result types -- - -export interface StepResult { - ok: boolean; - prompt?: string; - error?: string; -} - -// -- Dispatch -- - -export interface WorkflowDispatch { - onCompleteStep: ((thoughts?: string) => StepResult | Promise) | null; -} - -export function createDispatch(): WorkflowDispatch { - return { onCompleteStep: null }; -} - -// Decouples tool registration (init-time, before _buildRuntime) from -// plan directory creation (runtime, after flags available). Same -// indirection pattern as WorkflowDispatch. -export interface PlanRef { - dir: string | null; - qrPhase: string | null; -} - -export function createPlanRef(): PlanRef { - return { dir: null, qrPhase: null }; -} - -// Decouples tool registration (init-time) from subagent directory -// resolution (runtime, after flags available). Same indirection -// pattern as PlanRef. -export interface SubagentRef { - dir: string | null; -} - -export function createSubagentRef(): SubagentRef { - return { dir: null }; -} - -// Sets a dispatch slot. Throws if the slot is already occupied -- -// prevents silent misrouting when two phases attempt to claim -// the same tool. -export function hookDispatch( - dispatch: WorkflowDispatch, - key: K, - handler: NonNullable, -): void { - if (dispatch[key] !== null) { - throw new Error(`dispatch.${String(key)} is already hooked`); - } - // TypeScript cannot verify generic key-value assignment. - // Call-site generic constraint (handler: NonNullable) - // ensures type safety; collision guard above prevents double-hooking. - (dispatch as any)[key] = handler; -} - -export function unhookDispatch( - dispatch: WorkflowDispatch, - key: keyof WorkflowDispatch, -): void { - (dispatch as any)[key] = null; -} diff --git a/src/planner/lib/resources.ts b/src/planner/lib/resources.ts deleted file mode 100644 index 2b3afc7..0000000 --- a/src/planner/lib/resources.ts +++ /dev/null @@ -1,31 +0,0 @@ -// Package resource path resolution for convention files. -// -// Prompts are hard-coded in TypeScript (see agent-prompts.ts) to avoid runtime -// filesystem dependencies. Conventions remain file-based so subagents can Read -// them directly. - -import { existsSync } from "node:fs"; -import * as path from "node:path"; -import { fileURLToPath } from "node:url"; - -function findPackageRoot(startDir: string): string { - let dir = startDir; - // Supports both source and build layouts. - // source: /src/planner/lib - // build: /build/src/planner/lib - for (let i = 0; i < 8; i++) { - const conventionsDir = path.join(dir, "resources", "conventions"); - if (existsSync(conventionsDir)) return dir; - - const parent = path.dirname(dir); - if (parent === dir) break; - dir = parent; - } - - throw new Error(`Unable to resolve package root from ${startDir}`); -} - -const HERE = path.dirname(fileURLToPath(import.meta.url)); -const PKG_ROOT = findPackageRoot(HERE); - -export const CONVENTIONS_DIR = path.join(PKG_ROOT, "resources/conventions"); diff --git a/src/planner/phases/plan-code/fix-phase.ts b/src/planner/phases/plan-code/fix-phase.ts deleted file mode 100644 index 6f2df7e..0000000 --- a/src/planner/phases/plan-code/fix-phase.ts +++ /dev/null @@ -1,166 +0,0 @@ -// Plan-code fix phase -- dynamic targeted QR repair workflow. - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; -import { loadPlanCodeSystemPrompt, buildPlanCodeSystemPrompt } from "./prompts.js"; -import { - fixStepName, - buildFixSystemPrompt, - fixStepGuidance, - formatFailuresXml, -} from "./fix-prompts.js"; -import { formatStep } from "../../lib/step.js"; -import type { QRItem } from "../../qr/types.js"; -import { createLogger, type Logger } from "../../../utils/logger.js"; -import { EventLog } from "../../lib/audit.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; -import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; - -interface FixState { - active: boolean; - step: number; - step1Prompt: string | null; - systemPrompt: string | null; -} - -export class PlanCodeFixPhase { - private readonly pi: ExtensionAPI; - private readonly planDir: string; - private readonly failures: ReadonlyArray; - private readonly log: Logger; - private readonly state: FixState; - private readonly eventLog: EventLog | undefined; - private readonly dispatch: WorkflowDispatch; - private readonly planRef: PlanRef; - - constructor( - pi: ExtensionAPI, - config: { planDir: string; failures: QRItem[] }, - dispatch: WorkflowDispatch, - planRef: PlanRef, - log?: Logger, - eventLog?: EventLog, - ) { - this.pi = pi; - this.planDir = config.planDir; - this.failures = config.failures; - this.dispatch = dispatch; - this.planRef = planRef; - this.log = log ?? createLogger("PlanCodeFix"); - this.eventLog = eventLog; - - this.state = { - active: false, - step: 1, - step1Prompt: null, - systemPrompt: null, - }; - - this.registerHandlers(); - } - - private get totalSteps(): number { - return 2 + this.failures.length; - } - - async begin(): Promise { - let basePrompt: string; - try { - basePrompt = await loadPlanCodeSystemPrompt(); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Fix phase aborted: cannot load system prompt", { error: message }); - return; - } - - const failuresXml = formatFailuresXml(this.failures); - const totalSteps = this.totalSteps; - this.state.systemPrompt = buildFixSystemPrompt( - buildPlanCodeSystemPrompt(basePrompt), - this.failures.length, - totalSteps, - ); - this.state.step1Prompt = formatStep(fixStepGuidance(1, totalSteps, { allFailuresXml: failuresXml })); - this.state.active = true; - this.state.step = 1; - this.planRef.dir = this.planDir; - - hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - - this.log("Starting plan-code fix workflow", { step: 1, totalSteps, failureCount: this.failures.length }); - await this.eventLog?.emitPhaseStart(totalSteps); - await this.eventLog?.emitStepTransition(1, fixStepName(1, totalSteps), totalSteps); - } - - private registerHandlers(): void { - this.pi.on("before_agent_start", () => { - if (!this.state.active || !this.state.systemPrompt) return undefined; - return { systemPrompt: this.state.systemPrompt }; - }); - - this.pi.on("context", (event) => { - if (!this.state.active) return undefined; - if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; - - const messages = event.messages.map((m) => { - if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; - return m; - }); - return { messages }; - }); - - this.pi.on("tool_call", (event) => { - if (!this.state.active) return undefined; - - const perm = checkPermission("plan-code", event.toolName); - if (!perm.allowed) return { block: true, reason: perm.reason }; - - const step = this.state.step; - const total = this.totalSteps; - const inFixRange = step >= 2 && step < total; - if (!inFixRange && PLAN_MUTATION_TOOLS.has(event.toolName)) { - return { - block: true, - reason: `${event.toolName} available in steps 2-${total - 1} (current: ${step})`, - }; - } - - return undefined; - }); - } - - private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { - const prev = this.state.step; - const total = this.totalSteps; - - if (prev === total) { - const result = await this.handleFinalize(); - if (!result.ok) { - await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); - return { ok: false, error: result.errors?.join("; ") }; - } - - this.state.active = false; - unhookDispatch(this.dispatch, "onCompleteStep"); - await this.eventLog?.emitPhaseEnd("completed"); - this.log("Fix phase complete, plan-code validation passed"); - return { ok: true, prompt: "Fix phase validation passed. Workflow complete." }; - } - - const next = prev + 1; - this.state.step = next; - - const item = next >= 2 && next < total ? this.failures[next - 2] : undefined; - const name = fixStepName(next, total, item); - const prompt = formatStep(fixStepGuidance(next, total, { item })); - - this.log("Fix step complete, advancing", { from: prev, to: next, name }); - await this.eventLog?.emitStepTransition(next, name, total); - return { ok: true, prompt }; - } - - private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { - return loadAndValidatePlanForPhase(this.planDir, "plan-code", this.log); - } -} diff --git a/src/planner/phases/plan-code/fix-prompts.ts b/src/planner/phases/plan-code/fix-prompts.ts deleted file mode 100644 index 8c8000f..0000000 --- a/src/planner/phases/plan-code/fix-prompts.ts +++ /dev/null @@ -1,103 +0,0 @@ -import type { QRItem } from "../../qr/types.js"; -import type { StepGuidance } from "../../lib/step.js"; - -export function formatFailuresXml(failures: ReadonlyArray): string { - const items = failures - .map((f) => [ - ` `, - ` ${f.check}`, - f.finding ? ` ${f.finding}` : " ", - " ", - ].join("\n")) - .join("\n"); - return ["", items, ""].join("\n"); -} - -export function fixStepName(step: number, totalSteps: number, item?: QRItem): string { - if (step === 1) return "Understand QR Failures"; - if (step === totalSteps) return "Review & Finalize"; - return item ? `Fix ${item.id}` : `Fix item ${step - 1}`; -} - -export function buildFixSystemPrompt(basePrompt: string, failureCount: number, totalSteps: number): string { - return [ - basePrompt, - "", - "---", - "", - `WORKFLOW: ${totalSteps}-STEP PLAN-CODE FIX`, - "", - `You are fixing ${failureCount} QR failure(s) in code planning output.`, - "Step 1 is read-only and covers all failures.", - `Steps 2-${totalSteps - 1} fix exactly one failure per step.`, - `Step ${totalSteps} is read-only review.`, - "", - "CONSTRAINTS:", - "- Fix only identified failures", - "- Preserve already-valid code_changes", - "- Do not edit repository files (planning only)", - ].join("\n"); -} - -function step1(totalSteps: number, failuresXml: string): StepGuidance { - const itemCount = totalSteps - 2; - return { - title: `Step 1/${totalSteps}: Understand QR Failures`, - instructions: [ - "QR FAILURES:", - "", - failuresXml, - "", - `There are ${itemCount} item(s). You will fix them one by one in steps 2-${totalSteps - 1}.`, - "Read current plan state with koan_get_plan / koan_get_change / koan_get_intent.", - "Identify exact mismatch for each failure.", - "", - "This step is read-only.", - ], - }; -} - -function itemStep(step: number, totalSteps: number, item?: QRItem): StepGuidance { - const itemXml = item ? formatFailuresXml([item]) : ""; - const idx = step - 1; - const total = totalSteps - 2; - return { - title: `Step ${step}/${totalSteps}: Fix ${item?.id ?? `item ${idx}`}`, - instructions: [ - `FIX ITEM ${idx} OF ${total}:`, - "", - itemXml, - "", - "Apply a targeted plan fix using change tools (add/set change, set intent ref, set comments).", - "Do not batch-fix other failures in this step.", - "Keep modifications minimal and scoped.", - ], - }; -} - -function finalStep(totalSteps: number): StepGuidance { - return { - title: `Step ${totalSteps}/${totalSteps}: Review & Finalize`, - instructions: [ - "All per-item fixes are complete.", - "Use koan_get_plan to verify overall coherence and coverage.", - "Confirm fixed items are addressed without regressing passing items.", - "", - "This step is read-only.", - ], - invokeAfter: [ - "WHEN DONE: Call koan_get_plan, then call koan_complete_step.", - "Do NOT call koan_complete_step before reviewing final plan state.", - ].join("\n"), - }; -} - -export function fixStepGuidance( - step: number, - totalSteps: number, - opts?: { item?: QRItem; allFailuresXml?: string }, -): StepGuidance { - if (step === 1) return step1(totalSteps, opts?.allFailuresXml ?? ""); - if (step === totalSteps) return finalStep(totalSteps); - return itemStep(step, totalSteps, opts?.item); -} diff --git a/src/planner/phases/plan-code/phase.ts b/src/planner/phases/plan-code/phase.ts deleted file mode 100644 index ab2b9e4..0000000 --- a/src/planner/phases/plan-code/phase.ts +++ /dev/null @@ -1,151 +0,0 @@ -// Plan-code phase -- 4-step developer workflow converting code intents -// to concrete code_changes diffs in plan.json. - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; -import { - loadPlanCodeSystemPrompt, - buildPlanCodeSystemPrompt, - planCodeStepGuidance, - STEP_NAMES, -} from "./prompts.js"; -import { formatStep } from "../../lib/step.js"; -import { createLogger, type Logger } from "../../../utils/logger.js"; -import { EventLog } from "../../lib/audit.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; -import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; - -type PlanCodeStep = 1 | 2 | 3 | 4; - -interface PlanCodeState { - active: boolean; - step: PlanCodeStep; - step1Prompt: string | null; - systemPrompt: string | null; -} - -const TOTAL_STEPS = 4; -const MUTATION_UNLOCK_STEP = 3; - -export class PlanCodePhase { - private readonly pi: ExtensionAPI; - private readonly planDir: string; - private readonly log: Logger; - private readonly state: PlanCodeState; - private readonly eventLog: EventLog | undefined; - private readonly dispatch: WorkflowDispatch; - private readonly planRef: PlanRef; - - constructor( - pi: ExtensionAPI, - config: { planDir: string }, - dispatch: WorkflowDispatch, - planRef: PlanRef, - log?: Logger, - eventLog?: EventLog, - ) { - this.pi = pi; - this.planDir = config.planDir; - this.dispatch = dispatch; - this.planRef = planRef; - this.log = log ?? createLogger("PlanCode"); - this.eventLog = eventLog; - - this.state = { - active: false, - step: 1, - step1Prompt: null, - systemPrompt: null, - }; - - this.registerHandlers(); - } - - async begin(): Promise { - let basePrompt: string; - try { - basePrompt = await loadPlanCodeSystemPrompt(); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to load plan-code system prompt", { error: message }); - return; - } - - this.state.systemPrompt = buildPlanCodeSystemPrompt(basePrompt); - this.state.step1Prompt = formatStep(planCodeStepGuidance(1)); - this.state.active = true; - this.state.step = 1; - this.planRef.dir = this.planDir; - - hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - - this.log("Starting plan-code workflow", { step: 1 }); - await this.eventLog?.emitPhaseStart(TOTAL_STEPS); - await this.eventLog?.emitStepTransition(1, STEP_NAMES[1], TOTAL_STEPS); - } - - private registerHandlers(): void { - this.pi.on("before_agent_start", () => { - if (!this.state.active || !this.state.systemPrompt) return undefined; - return { systemPrompt: this.state.systemPrompt }; - }); - - this.pi.on("context", (event) => { - if (!this.state.active) return undefined; - if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; - - const messages = event.messages.map((m) => { - if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; - return m; - }); - return { messages }; - }); - - this.pi.on("tool_call", (event) => { - if (!this.state.active) return undefined; - - const perm = checkPermission("plan-code", event.toolName); - if (!perm.allowed) return { block: true, reason: perm.reason }; - - if (this.state.step < MUTATION_UNLOCK_STEP && PLAN_MUTATION_TOOLS.has(event.toolName)) { - return { - block: true, - reason: `${event.toolName} available from step ${MUTATION_UNLOCK_STEP} (current: ${this.state.step})`, - }; - } - - return undefined; - }); - } - - private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { - const prev = this.state.step; - - if (prev === 4) { - const result = await this.handleFinalize(); - if (!result.ok) { - await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); - return { ok: false, error: result.errors?.join("; ") }; - } - - this.state.active = false; - unhookDispatch(this.dispatch, "onCompleteStep"); - await this.eventLog?.emitPhaseEnd("completed"); - this.log("Plan-code finalized, workflow complete"); - return { ok: true, prompt: "Plan-code validation passed. Workflow complete." }; - } - - this.state.step = (prev + 1) as PlanCodeStep; - const nextName = STEP_NAMES[this.state.step]; - const prompt = formatStep(planCodeStepGuidance(this.state.step)); - - this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName }); - await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); - return { ok: true, prompt }; - } - - private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { - return loadAndValidatePlanForPhase(this.planDir, "plan-code", this.log); - } -} diff --git a/src/planner/phases/plan-code/prompts.ts b/src/planner/phases/plan-code/prompts.ts deleted file mode 100644 index f2ed819..0000000 --- a/src/planner/phases/plan-code/prompts.ts +++ /dev/null @@ -1,108 +0,0 @@ -import type { StepGuidance } from "../../lib/step.js"; -import { loadAgentPrompt } from "../../lib/agent-prompts.js"; - -export const STEP_NAMES: Record<1 | 2 | 3 | 4, string> = { - 1: "Intent Coverage Analysis", - 2: "Codebase Anchoring", - 3: "Diff Authoring", - 4: "Validation & Review", -}; - -export async function loadPlanCodeSystemPrompt(): Promise { - return loadAgentPrompt("developer"); -} - -export function buildPlanCodeSystemPrompt(basePrompt: string): string { - return [ - basePrompt, - "", - "---", - "", - "WORKFLOW: 4-STEP PLAN-CODE", - "", - "You are in planning mode. Produce code diffs in plan.json, not repo edits.", - "Step 1 instructions are in the user message below.", - "Complete each step, then call koan_complete_step.", - "Put your work output in the `thoughts` parameter.", - "The tool result contains the next step.", - "", - "CRITICAL:", - "- NEVER use edit/write tools during plan-code.", - "- Convert every code_intent into at least one code_change with intent_ref.", - "- Use unified diffs in code_change.diff.", - "", - "CLARIFICATION:", - "If an intent is ambiguous about implementation (e.g. the behavior is clear", - "but multiple valid code patterns exist), use koan_ask_question to resolve", - "before writing the diff. Ask only when the choice materially affects code.", - ].join("\n"); -} - -export function planCodeStepGuidance(step: 1 | 2 | 3 | 4): StepGuidance { - switch (step) { - case 1: - return { - title: "Step 1: Intent Coverage Analysis", - instructions: [ - "Use koan_get_plan to inspect milestones and code_intents.", - "Build a checklist of intents that need code_changes.", - "Record target files and affected functions per intent.", - "", - "This step is read-only.", - ], - }; - - case 2: - return { - title: "Step 2: Codebase Anchoring", - instructions: [ - "Read target files to anchor each planned diff:", - " - Use read/grep/find/bash as needed", - " - Identify stable context lines around each change", - " - Confirm naming/pattern conventions", - "", - "Do not create code_changes yet. This step is still read-only.", - ], - }; - - case 3: - return { - title: "Step 3: Diff Authoring", - instructions: [ - "Create code_changes for each intent using plan mutation tools:", - " - koan_add_change (if missing)", - " - koan_set_change_intent_ref", - " - koan_set_change_file", - " - koan_set_change_diff", - " - koan_set_change_comments", - "", - "Rules:", - " - Every code_intent must map to at least one code_change", - " - Use valid unified diff format in diff field", - " - comments explain WHY (reference decision IDs where relevant)", - "", - "Use koan_get_plan/koan_get_milestone to verify coverage as you go.", - ], - }; - - case 4: - return { - title: "Step 4: Validation & Review", - instructions: [ - "Run a final coverage review using getter tools:", - " - Every intent has at least one linked change", - " - Every change has exact file path and non-empty diff", - " - Diffs and comments are coherent with intent behavior", - "", - "Fix any gaps before completing this step.", - ], - invokeAfter: [ - "WHEN DONE: Call koan_complete_step with a concise summary of coverage.", - "Do NOT call this tool until all required code_changes are present.", - ].join("\n"), - }; - - default: - return { title: "", instructions: [] }; - } -} diff --git a/src/planner/phases/plan-design/fix-phase.ts b/src/planner/phases/plan-design/fix-phase.ts deleted file mode 100644 index 664f0ba..0000000 --- a/src/planner/phases/plan-design/fix-phase.ts +++ /dev/null @@ -1,220 +0,0 @@ -// Plan-design fix phase -- dynamic N-step targeted repair for QR failures. -// -// totalSteps = 2 + failures.length. Step 1 reads all failures (read-only). -// Steps 2..N+1 each fix one QR item (mutations enabled). Step N+2 reviews -// all fixes (read-only). The step counter IS the item iterator: -// failures[step - 2] gives the current item. -// -// Separate class from PlanDesignPhase because the workflows diverge: -// initial = 6 steps of exploration then writing (mutations at step 6); -// fix = dynamic N steps iterating one QR item per step (mutations in -// per-item range only). Conditional branching at every method boundary -// produces worse code than two focused classes. -// -// The fix architect receives QR failures as XML in step 1. Per-item steps -// present a single failure with mutation tools enabled. The session -// orchestrator decides whether to re-run QR -- the fix phase does not -// know about iterations or severity escalation. - -import * as path from "node:path"; - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { loadAndValidatePlan } from "../../plan/validate.js"; -import { - loadPlanDesignSystemPrompt, - buildPlanDesignSystemPrompt, -} from "./prompts.js"; -import { - fixStepName, - buildFixSystemPrompt, - fixStepGuidance, - formatFailuresXml, -} from "./fix-prompts.js"; -import { formatStep } from "../../lib/step.js"; -import type { QRItem } from "../../qr/types.js"; -import { createLogger, type Logger } from "../../../utils/logger.js"; -import { EventLog } from "../../lib/audit.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; -import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; - -interface FixPhaseState { - active: boolean; - step: number; - step1Prompt: string | null; - systemPrompt: string | null; -} - -export class PlanDesignFixPhase { - private readonly pi: ExtensionAPI; - private readonly planDir: string; - private readonly failures: ReadonlyArray; - private readonly log: Logger; - private readonly state: FixPhaseState; - private readonly eventLog: EventLog | undefined; - private readonly dispatch: WorkflowDispatch; - private readonly planRef: PlanRef; - - constructor( - pi: ExtensionAPI, - config: { planDir: string; failures: QRItem[] }, - dispatch: WorkflowDispatch, - planRef: PlanRef, - log?: Logger, - eventLog?: EventLog, - ) { - this.pi = pi; - this.planDir = config.planDir; - this.failures = config.failures; - this.dispatch = dispatch; - this.planRef = planRef; - this.log = log ?? createLogger("PlanDesignFix"); - this.eventLog = eventLog; - - this.state = { - active: false, - step: 1, - step1Prompt: null, - systemPrompt: null, - }; - - this.registerHandlers(); - } - - // Computed from failure count. Step 1 (understand) + N per-item steps - // + 1 final review = 2 + N. Single source of truth for all step-range - // checks in this class. - private get totalSteps(): number { - return 2 + this.failures.length; - } - - async begin(): Promise { - let basePrompt: string; - try { - basePrompt = await loadPlanDesignSystemPrompt(); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Fix phase aborted: cannot load system prompt", { error: message }); - return; - } - - const failuresXml = formatFailuresXml(this.failures); - // Local copy for consistent reads across this method. The getter is stable - // (this.failures is readonly) but a local communicates "one value, many uses". - const totalSteps = this.totalSteps; - this.state.systemPrompt = buildFixSystemPrompt( - buildPlanDesignSystemPrompt(basePrompt), - this.failures.length, - totalSteps, - ); - const conversationPath = path.join(this.planDir, "conversation.jsonl"); - this.state.step1Prompt = formatStep( - fixStepGuidance(1, totalSteps, { allFailuresXml: failuresXml, conversationPath }), - ); - this.state.active = true; - this.state.step = 1; - - hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - - this.log("Starting plan-design fix workflow", { - step: 1, - totalSteps, - failureCount: this.failures.length, - }); - await this.eventLog?.emitPhaseStart(totalSteps); - await this.eventLog?.emitStepTransition( - 1, - fixStepName(1, totalSteps), - totalSteps, - ); - } - - private registerHandlers(): void { - this.pi.on("before_agent_start", () => { - if (!this.state.active || !this.state.systemPrompt) return undefined; - return { systemPrompt: this.state.systemPrompt }; - }); - - // Step 1 prompt injection. Same pattern as PlanDesignPhase: the CLI - // message is a process trigger; the context event replaces it with - // step 1 instructions before the initial LLM call. - this.pi.on("context", (event) => { - if (!this.state.active) return undefined; - if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; - - const messages = event.messages.map((m) => { - if (m.role === "user") { - return { ...m, content: this.state.step1Prompt! }; - } - return m; - }); - return { messages }; - }); - - this.pi.on("tool_call", (event) => { - if (!this.state.active) return undefined; - - const perm = checkPermission("plan-design", event.toolName); - if (!perm.allowed) { - return { block: true, reason: perm.reason }; - } - - // Step gate: mutation tools allowed ONLY in per-item steps (step 2 - // through totalSteps-1). Both step 1 (understand) and the final step - // (review) are read-only. The upper bound prevents accidental mutations - // during review that would bypass QR re-verification. - const step = this.state.step; - const total = this.totalSteps; - const inItemRange = step >= 2 && step < total; - if (!inItemRange && PLAN_MUTATION_TOOLS.has(event.toolName)) { - return { - block: true, - reason: `${event.toolName} available in steps 2-${total - 1} (current: ${step})`, - }; - } - - return undefined; - }); - } - - private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { - const prev = this.state.step; - const total = this.totalSteps; - - // Terminal: final step completed -> validate plan and end phase. - if (prev === total) { - const result = await this.handleFinalize(); - if (!result.ok) { - await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); - return { ok: false, error: result.errors?.join("; ") }; - } - this.state.active = false; - unhookDispatch(this.dispatch, "onCompleteStep"); - await this.eventLog?.emitPhaseEnd("completed"); - this.log("Fix phase complete, plan validation passed"); - return { ok: true, prompt: "Fix phase validation passed. Workflow complete." }; - } - - // Advance to next step. Step always increments -- no cursor, no hold. - const next = prev + 1; - this.state.step = next; - - // Per-item steps (2 <= next < total) pass the individual failure item - // so fixStepGuidance generates item-specific prompts. Only the final - // step (next === total) does not carry an item. - const item = (next >= 2 && next < total) - ? this.failures[next - 2] - : undefined; - const name = fixStepName(next, total, item); - const prompt = formatStep(fixStepGuidance(next, total, { item })); - - this.log("Fix step complete, advancing", { from: prev, to: next, name }); - await this.eventLog?.emitStepTransition(next, name, total); - - return { ok: true, prompt }; - } - - private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { - return loadAndValidatePlan(this.planDir, this.log); - } -} diff --git a/src/planner/phases/plan-design/fix-prompts.ts b/src/planner/phases/plan-design/fix-prompts.ts deleted file mode 100644 index 80bd4ce..0000000 --- a/src/planner/phases/plan-design/fix-prompts.ts +++ /dev/null @@ -1,220 +0,0 @@ -// Fix-phase step guidance for plan-design targeted repair (dynamic N steps). -// -// totalSteps = 2 + failures.length. Step 1 reads all failures (read-only). -// Steps 2..N+1 each fix one QR item (mutations enabled). Step N+2 reviews -// all fixes (read-only). The step counter IS the item iterator: -// failures[step - 2] gives the current item in the per-item range. -// -// Step 1 explicitly prohibits mutations: without this constraint the LLM -// tends to apply the first fix it identifies without reading all failures, -// producing cascading corrections that address symptoms rather than root causes. - -import type { QRItem } from "../../qr/types.js"; -import type { StepGuidance } from "../../lib/step.js"; -import { buildPlanDesignContextTrigger } from "../../lib/conversation-trigger.js"; - -// Serializes FAIL items as an XML block injected into the step 1 prompt. -// XML structure mirrors how pi-native tools present structured data. -export function formatFailuresXml(failures: ReadonlyArray): string { - const items = failures.map((f) => [ - ` `, - ` ${f.check}`, - f.finding ? ` ${f.finding}` : ` `, - ` `, - ].join("\n")).join("\n"); - - return [ - "", - items, - "", - ].join("\n"); -} - -// Dynamic step names. Step 1 and the final step have fixed names; -// per-item steps show the QR item ID so the widget displays -// "Step 3/7: Fix D-001" rather than a generic label. The audit log -// uses these names to distinguish per-item transitions. -export function fixStepName( - step: number, - totalSteps: number, - item?: QRItem, -): string { - if (step === 1) return "Understand QR Failures"; - if (step === totalSteps) return "Review & Finalize"; - return item ? `Fix ${item.id}` : `Fix item ${step - 1}`; -} - -// Appends fix workflow instructions to the base architect system prompt. -// The structured STEP LAYOUT section uses indentation to visually separate -// the three phases so the LLM internalizes the one-at-a-time constraint -// from the system prompt rather than discovering it at step 2. -export function buildFixSystemPrompt( - basePrompt: string, - failureCount: number, - totalSteps: number, -): string { - return [ - basePrompt, - "", - "---", - "", - `WORKFLOW: ${totalSteps}-STEP PLAN-DESIGN FIX`, - "", - `You are fixing ${failureCount} QR failure(s) in an existing plan.`, - "", - "STEP LAYOUT:", - " Step 1: Read all failures. Understand scope and interactions. READ-ONLY.", - ` Steps 2-${totalSteps - 1}: Fix ONE failure per step. Each step targets exactly one item.`, - ` Step ${totalSteps}: Review all fixes against original failures. READ-ONLY.`, - "", - "Each step's instructions appear as a tool result after you call koan_complete_step.", - "Put your work output in the `thoughts` parameter of koan_complete_step.", - "", - "CONSTRAINTS:", - " - Fix ONLY the identified failures", - " - Each per-item step targets exactly ONE failure -- do not fix other items", - " - Prefer updating existing entities over adding new ones", - " - Do not restructure the plan beyond what failures require", - "", - "DECISION SOURCE FIXES:", - "If a failure is about a missing or weak decision source, use", - "koan_ask_question to get user input. Then update the decision with", - "source='user:ask' via koan_set_decision.", - ].join("\n"); -} - -// Three categories of step: understand (step 1), per-item fix -// (2 <= step < totalSteps), and review (step === totalSteps). -// The step counter IS the item iterator -- no separate cursor needed. -export function fixStepGuidance( - step: number, - totalSteps: number, - opts?: { item?: QRItem; allFailuresXml?: string; conversationPath?: string }, -): StepGuidance { - if (step === 1) - return fixStep1Guidance(totalSteps, opts?.allFailuresXml ?? "", opts?.conversationPath); - if (step === totalSteps) return fixFinalStepGuidance(totalSteps); - return fixItemStepGuidance(step, totalSteps, opts?.item); -} - -// Step 1 prompt reframes analysis as "note interactions" rather than -// "plan your fixes mentally" to avoid priming the LLM for batch application. -// The one-at-a-time delivery is stated explicitly so the LLM expects -// per-item steps rather than a single batch-fix step. -function fixStep1Guidance( - totalSteps: number, - failuresXml: string, - conversationPath?: string, -): StepGuidance { - const itemCount = totalSteps - 2; - return { - title: `Step 1/${totalSteps}: Understand QR Failures`, - instructions: [ - "QR FAILURES TO FIX:", - "", - failuresXml, - "", - ...buildPlanDesignContextTrigger(conversationPath ?? "/conversation.jsonl"), - "", - `There are ${itemCount} failure(s). You will fix them one at a time`, - `in steps 2 through ${totalSteps - 1}. Each step presents a single item.`, - "", - "For each failing item:", - " - Identify the scope (which milestone, decision, or intent)", - " - Understand what the check requires", - " - Read the finding to understand why it failed", - "", - "Use getter tools to inspect scoped entities:", - " - koan_get_plan: overview, structure, decisions", - " - koan_get_milestone: milestone details and intents", - " - koan_get_decision: decision rationale", - " - koan_get_intent: intent definition", - "", - "Note interactions between failures:", - " - Do any failures share the same entity scope?", - " - Could fixing one affect another's context?", - "", - "This is a READ-ONLY step. Do not apply any changes.", - ], - }; -} - -// Per-item fix step. Shows only the single item being fixed so the LLM -// focuses on one failure rather than attempting batch fixes that produce -// cascading corrections. Mutations are enabled by the step gate in -// fix-phase.ts for this range. -// -// Positional context ("FIX ITEM N OF M") grounds the LLM in the sequence, -// matching the reference impl's "item {idx} of {total}" pattern. The -// explicit anti-batch gate ("Do not fix other failures") is the prompt-level -// complement to the code-level step gate that blocks mutations outside the -// per-item range. -function fixItemStepGuidance( - step: number, - totalSteps: number, - item?: QRItem, -): StepGuidance { - // Defensive fallbacks: handleStepComplete guarantees item is present for - // per-item steps (failures[next-2] is in-bounds), but the function signature - // accepts optional to keep it callable from tests or future call sites. - const itemXml = item ? formatFailuresXml([item]) : ""; - const itemLabel = item?.id ?? `item ${step - 1}`; - const itemIdx = step - 1; - const itemCount = totalSteps - 2; - - return { - title: `Step ${step}/${totalSteps}: Fix ${itemLabel}`, - instructions: [ - `FIX ITEM ${itemIdx} OF ${itemCount}:`, - "", - itemXml, - "", - "Apply a targeted fix for this failure using your analysis from step 1.", - "", - "Available mutation tools:", - " - koan_set_overview / koan_set_constraints / koan_set_invisible_knowledge", - " - koan_set_milestone_* / koan_set_intent / koan_set_decision", - " - koan_add_milestone / koan_add_intent / koan_add_decision (if needed)", - "", - "RULES:", - " - Fix ONLY this failure. Do not fix other failures in this step.", - " - Prefer updating existing entities over adding new ones", - " - Do not restructure the plan beyond what this failure requires", - ], - }; -} - -// Final review step. Accepts only totalSteps because the call site guard -// (step === totalSteps) guarantees identity. A two-parameter form would -// create a hidden contract ("pass equal values") with no type enforcement. -// -// "All per-item fixes are complete" explicitly closes the mutation phase -// and establishes the read-only review frame. "This step is READ-ONLY" -// is the prompt-level complement to the step gate blocking mutations. -function fixFinalStepGuidance(totalSteps: number): StepGuidance { - return { - title: `Step ${totalSteps}/${totalSteps}: Review & Finalize`, - instructions: [ - "All per-item fixes are complete. This step is READ-ONLY.", - "", - "Call koan_get_plan to read the current plan state.", - "", - "Verify each fix:", - " - Does the fix address the specific check that failed?", - " - Are previously passing items unaffected?", - " - Is the plan internally consistent?", - "", - "Summarize in the `thoughts` parameter of koan_complete_step:", - " - Which failures were fixed and how", - " - Any remaining concerns or regression risks", - ], - // The review step requires reading the plan before completing -- - // the review is meaningless without it. The custom invokeAfter - // enforces this sequencing explicitly. - invokeAfter: [ - "WHEN DONE: First call koan_get_plan to confirm the final plan state.", - "Then call koan_complete_step with your review summary in the `thoughts` parameter.", - "Do NOT call koan_complete_step before calling koan_get_plan.", - ].join("\n"), - }; -} diff --git a/src/planner/phases/plan-design/phase.ts b/src/planner/phases/plan-design/phase.ts deleted file mode 100644 index 470f14e..0000000 --- a/src/planner/phases/plan-design/phase.ts +++ /dev/null @@ -1,177 +0,0 @@ -// Plan-design phase -- 6-step architect workflow that produces plan.json -// from captured context. Step gate: mutation tools blocked before step 6 -// (blocklist pattern). Validation runs at step-6 completion. - -import * as path from "node:path"; - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { loadAndValidatePlan } from "../../plan/validate.js"; -import { - loadPlanDesignSystemPrompt, - buildPlanDesignSystemPrompt, - planDesignStepGuidance, - STEP_NAMES, -} from "./prompts.js"; -import { formatStep } from "../../lib/step.js"; -import { createLogger, type Logger } from "../../../utils/logger.js"; -import { EventLog } from "../../lib/audit.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; -import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; - -type PlanDesignStep = 1 | 2 | 3 | 4 | 5 | 6; - -interface PlanDesignState { - active: boolean; - step: PlanDesignStep; - step1Prompt: string | null; - systemPrompt: string | null; -} - -const TOTAL_STEPS = 6; - -export class PlanDesignPhase { - private readonly pi: ExtensionAPI; - private readonly planDir: string; - private readonly log: Logger; - private readonly state: PlanDesignState; - private readonly eventLog: EventLog | undefined; - private readonly dispatch: WorkflowDispatch; - private readonly planRef: PlanRef; - - constructor( - pi: ExtensionAPI, - config: { planDir: string }, - dispatch: WorkflowDispatch, - planRef: PlanRef, - log?: Logger, - eventLog?: EventLog, - ) { - this.pi = pi; - this.planDir = config.planDir; - this.dispatch = dispatch; - this.planRef = planRef; - this.log = log ?? createLogger("PlanDesign"); - this.eventLog = eventLog; - - this.state = { - active: false, - step: 1, - step1Prompt: null, - systemPrompt: null, - }; - - this.registerHandlers(); - } - - async begin(): Promise { - let basePrompt: string; - try { - basePrompt = await loadPlanDesignSystemPrompt(); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to load plan-design system prompt", { error: message }); - return; - } - - this.state.systemPrompt = buildPlanDesignSystemPrompt(basePrompt); - const conversationPath = path.join(this.planDir, "conversation.jsonl"); - this.state.step1Prompt = formatStep(planDesignStepGuidance(1, conversationPath)); - this.state.active = true; - this.state.step = 1; - - // No koan_store_plan tool. Each mutation writes to disk immediately. - // Step 6 ends with koan_complete_step, which runs validation. Removes - // the two-step 'build then finalize' pattern that caused LLM to skip - // intermediate tools. - hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - - this.log("Starting plan-design workflow", { step: 1 }); - await this.eventLog?.emitPhaseStart(TOTAL_STEPS); - await this.eventLog?.emitStepTransition(1, STEP_NAMES[1], TOTAL_STEPS); - } - - private registerHandlers(): void { - this.pi.on("before_agent_start", () => { - if (!this.state.active || !this.state.systemPrompt) return undefined; - return { systemPrompt: this.state.systemPrompt }; - }); - - // Step 1 prompt injection. The CLI message is a process trigger -- - // the context event fires before each LLM call and replaces the - // user message with the actual step 1 instructions. Messages are - // structuredCloned before reaching this handler (runner.ts:660), - // so stored history is unaffected. Handler is a no-op once the - // step advances past 1. - // - // Why context event instead of sendUserMessage? Step 1 has no - // preceding tool call (no tool result to inject prompt into). - // Context event injects the prompt before the initial LLM call. - // pi structuredClones messages, so modifications here are isolated. - this.pi.on("context", (event) => { - if (!this.state.active) return undefined; - if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; - - const messages = event.messages.map((m) => { - if (m.role === "user") { - return { ...m, content: this.state.step1Prompt! }; - } - return m; - }); - return { messages }; - }); - - this.pi.on("tool_call", (event) => { - if (!this.state.active) return undefined; - - const perm = checkPermission("plan-design", event.toolName); - if (!perm.allowed) { - return { block: true, reason: perm.reason }; - } - - // Step gate: mutation tools are step-6-only. Blocklist (not whitelist) - // so read tools and future pi-native tools pass through after - // checkPermission approves them. - const step = this.state.step; - if (step < 6 && PLAN_MUTATION_TOOLS.has(event.toolName)) { - return { - block: true, - reason: `${event.toolName} available in step 6 (current: ${step})`, - }; - } - - return undefined; - }); - - } - - private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { - const prev = this.state.step; - - if (prev === 6) { - const result = await this.handleFinalize(); - if (!result.ok) { - await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); - return { ok: false, error: result.errors?.join("; ") }; - } - this.state.active = false; - unhookDispatch(this.dispatch, "onCompleteStep"); - await this.eventLog?.emitPhaseEnd("completed"); - this.log("Plan finalized, workflow complete"); - return { ok: true, prompt: "Plan validation passed. Workflow complete." }; - } - - this.state.step = (prev + 1) as PlanDesignStep; - const nextName = STEP_NAMES[this.state.step]; - const prompt = formatStep(planDesignStepGuidance(this.state.step)); - - this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName }); - await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); - - return { ok: true, prompt }; - } - - private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { - return loadAndValidatePlan(this.planDir, this.log); - } -} diff --git a/src/planner/phases/plan-design/prompts.ts b/src/planner/phases/plan-design/prompts.ts deleted file mode 100644 index ce7b11d..0000000 --- a/src/planner/phases/plan-design/prompts.ts +++ /dev/null @@ -1,238 +0,0 @@ -import type { StepGuidance } from "../../lib/step.js"; -import { buildPlanDesignContextTrigger } from "../../lib/conversation-trigger.js"; -import { CONVENTIONS_DIR } from "../../lib/resources.js"; -import { loadAgentPrompt } from "../../lib/agent-prompts.js"; - -export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { - 1: "Task Analysis & Exploration Planning", - 2: "Codebase Exploration", - 3: "Testing Strategy Discovery", - 4: "Approach Generation", - 5: "Ambiguity Resolution", - 6: "Milestone Definition & Plan Writing", -}; - -export async function loadPlanDesignSystemPrompt(): Promise { - return loadAgentPrompt("architect"); -} - -export function buildPlanDesignSystemPrompt(basePrompt: string): string { - return [ - basePrompt, - "", - "---", - "", - "WORKFLOW: 6-STEP PLAN-DESIGN", - "", - "You will execute a 6-step workflow.", - "Step 1 instructions are in the user message below.", - "Complete the work described, then call koan_complete_step.", - "Put your findings in the `thoughts` parameter of koan_complete_step.", - "The tool result contains the next step's instructions.", - "In step 6, use plan mutation tools, then call koan_complete_step.", - "", - "CRITICAL: Do the actual work described in each step BEFORE calling", - "koan_complete_step. Read files, explore code, analyze. Do not skip.", - "", - "DECISION PROVENANCE:", - "Every decision requires a source tag. Valid sources:", - " code: -- derived from reading source code", - " docs: -- derived from project documentation", - " user:ask -- user answered via koan_ask_question", - " user:conversation -- user stated in captured conversation", - " inference -- inferred from patterns (last resort; see step 5 rules)", - "If you cannot ground a decision in code or documentation, use", - "koan_ask_question. Ambiguity resolved by asking is better than", - "ambiguity resolved by assumption.", - ].join("\n"); -} - -export function planDesignStepGuidance( - step: 1 | 2 | 3 | 4 | 5 | 6, - conversationPath?: string, -): StepGuidance { - switch (step) { - case 1: - return { - title: "Step 1: Task Analysis & Exploration Planning", - instructions: [ - ...buildPlanDesignContextTrigger(conversationPath ?? "/conversation.jsonl"), - "", - "After absorbing the task intent, identify:", - " - What needs to change (files, modules, behavior)", - " - What exploration is needed (patterns, constraints, existing code)", - " - What directories/files are relevant", - "", - "Read project context files to understand structure:", - " - Project root CLAUDE.md", - " - Subdirectory CLAUDE.md files in relevant areas", - "", - "DO NOT write any files yet. Gather understanding for step 2.", - "Record your analysis mentally for use in subsequent steps.", - ], - }; - - case 2: - return { - title: "Step 2: Codebase Exploration", - instructions: [ - "Use Glob, Grep, Read tools directly to discover:", - " - Existing patterns and implementations", - " - Constraints from code structure", - " - Conventions to follow", - "", - "Read convention files as needed (use absolute paths below):", - ` - ${CONVENTIONS_DIR}/structural.md (architectural patterns)`, - ` - ${CONVENTIONS_DIR}/temporal.md (comment hygiene)`, - ` - ${CONVENTIONS_DIR}/diff-format.md (diff specification)`, - "", - "NUDGE: If you need additional context to plan well, read more files.", - "Better to over-explore than under-explore.", - "", - "Record discoveries for use in steps 4-6. Do NOT write files.", - ], - }; - - case 3: - return { - title: "Step 3: Testing Strategy Discovery", - instructions: [ - "DISCOVER testing strategy from:", - " - User conversation hints", - " - Project CLAUDE.md / README.md", - ` - ${CONVENTIONS_DIR}/structural.md domain='testing-strategy'`, - "", - "Record confirmed strategy for use in step 6.", - "Decisions will be recorded via tools in step 6.", - ], - }; - - case 4: - return { - title: "Step 4: Approach Generation", - instructions: [ - "GENERATE 2-3 approach options:", - " - Include 'minimal change' option", - " - Include 'idiomatic/modern' option", - " - Document advantage/disadvantage for each", - "", - "TARGET TECH RESEARCH (if new tech/migration):", - " - What is canonical usage of target tech?", - " - Does it have different abstractions?", - "", - "Use exploration findings from step 2 to ground tradeoffs.", - "Record approach analysis for step 6.", - "", - "DECISION INVENTORY:", - "For each approach, identify the implicit decisions it makes.", - "For each decision, note the source:", - " - code: -- forced by existing codebase (cite file)", - " - docs: -- specified in project docs (cite file)", - " - user:conversation -- user stated preference in conversation", - " - inference -- your judgment (requires strong reasoning_chain)", - " - UNRESOLVED -- no clear source; flag for step 5", - ], - }; - - case 5: - return { - title: "Step 5: Ambiguity Resolution", - instructions: [ - "Review the decision inventory from step 4.", - "For every decision marked UNRESOLVED or sourced as inference:", - " 1. Can it be grounded in code or docs? Read them.", - " 2. If still unsourced, ask the user via koan_ask_question.", - "", - "USE koan_ask_question WHEN:", - " - Multiple approaches have comparable tradeoffs, no codebase precedent", - " - A policy default (timeout, capacity, retry, failure mode) has no value", - " - Migration path or abstraction boundary not dictated by code", - "", - "DO NOT ASK WHEN:", - " - Codebase establishes a clear pattern (source: code:)", - " - Project docs specify the approach (source: docs:)", - " - Only one approach is technically viable", - " - The choice follows directly from an already-sourced decision", - "", - "INFERENCE RULES (source: inference):", - " Acceptable: airtight reasoning, no viable alternative, follows from", - " existing constraints, standard practice with one correct answer.", - " NOT acceptable: hedging language, policy defaults, public API choices,", - " or any decision where a senior engineer might reasonably disagree.", - "", - "Good questions offer concrete options grounded in codebase evidence:", - " BAD: 'How should we handle errors?'", - " GOOD: 'Error propagation: (A) return Result matching src/foo.ts,", - " (B) throw + catch at boundary matching src/bar.ts'", - "", - "FAST PATH: If all decisions have code/docs/conversation sources,", - "skip asking and record this finding.", - "", - "After resolving, every decision has a concrete source. No UNRESOLVED.", - ], - }; - - case 6: - return { - title: "Step 6: Milestone Definition & Plan Writing", - instructions: [ - "EVALUATE approaches: P(success), failure mode, backtrack cost", - "", - "SELECT and record in Decision Log with MULTI-STEP chain:", - " BAD: 'Polling | Webhooks unreliable'", - " GOOD: 'Use polling | 30% webhook failure -> need fallback anyway -> polling simpler'", - "", - "Every koan_add_decision call MUST include a source parameter:", - " - code: -- derived from existing code (cite file)", - " - docs: -- from project documentation (cite file)", - " - user:ask -- asked the user via koan_ask_question", - " - user:conversation -- user stated in original conversation", - " - inference -- architect judgment (use sparingly; needs strong chain)", - "", - "Use the following tools to build the plan:", - "", - "OVERVIEW & CONSTRAINTS:", - " - koan_set_overview: Define problem and approach", - " - koan_set_constraints: Record constraints", - " - koan_set_invisible_knowledge: Document project-specific context", - "", - "DECISIONS & RISKS:", - " - koan_add_decision, koan_set_decision: Record architectural decisions", - " - koan_add_rejected_alternative: Document rejected approaches", - " - koan_add_risk: Track implementation risks", - "", - "MILESTONES & INTENTS:", - " - koan_add_milestone: Create milestones (deployable increments)", - " - koan_set_milestone_name/files/flags/requirements/acceptance_criteria/tests: Configure milestones", - " - koan_add_intent, koan_set_intent: Define code intents (WHAT to change, not HOW)", - "", - "WAVES & STRUCTURE:", - " - koan_add_wave, koan_set_wave_milestones: Group milestones into deployment waves", - " - koan_add_diagram, koan_set_diagram, koan_add_diagram_node, koan_add_diagram_edge: Visual structure", - " - koan_set_readme_entry: Link plan sections to README.md", - "", - "Each tool writes to disk immediately. Inspect with koan_get_plan.", - "", - "MILESTONES (each deployable increment):", - " - Files: exact paths (each file in ONE milestone only)", - " - Requirements: specific behaviors", - " - Acceptance: testable pass/fail criteria", - " - Code Intent: WHAT to change (Developer converts to code_changes later)", - " - Tests: type, backing, scenarios", - "", - "PARALLELIZATION:", - " Vertical slices (parallel) > Horizontal layers (sequential)", - " BAD: M1=models, M2=services, M3=controllers (sequential)", - " GOOD: M1=auth stack, M2=users stack, M3=posts stack (parallel)", - " If file overlap: extract to M0 (foundation) or consolidate", - ], - invokeAfter: [ - "WHEN DONE: Call koan_complete_step to validate. Put a summary of what you built in the `thoughts` parameter.", - "Do NOT call this tool until you have used the plan mutation tools.", - ].join("\n"), - }; - - default: - return { title: "", instructions: [] }; - } -} diff --git a/src/planner/phases/plan-docs/fix-phase.ts b/src/planner/phases/plan-docs/fix-phase.ts deleted file mode 100644 index dcbc15f..0000000 --- a/src/planner/phases/plan-docs/fix-phase.ts +++ /dev/null @@ -1,169 +0,0 @@ -// Plan-docs fix phase -- dynamic targeted QR repair workflow. - -import * as path from "node:path"; - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; -import { loadPlanDocsSystemPrompt, buildPlanDocsSystemPrompt } from "./prompts.js"; -import { - fixStepName, - buildFixSystemPrompt, - fixStepGuidance, - formatFailuresXml, -} from "./fix-prompts.js"; -import { formatStep } from "../../lib/step.js"; -import type { QRItem } from "../../qr/types.js"; -import { createLogger, type Logger } from "../../../utils/logger.js"; -import { EventLog } from "../../lib/audit.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; -import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; - -interface FixState { - active: boolean; - step: number; - step1Prompt: string | null; - systemPrompt: string | null; -} - -export class PlanDocsFixPhase { - private readonly pi: ExtensionAPI; - private readonly planDir: string; - private readonly failures: ReadonlyArray; - private readonly log: Logger; - private readonly state: FixState; - private readonly eventLog: EventLog | undefined; - private readonly dispatch: WorkflowDispatch; - private readonly planRef: PlanRef; - - constructor( - pi: ExtensionAPI, - config: { planDir: string; failures: QRItem[] }, - dispatch: WorkflowDispatch, - planRef: PlanRef, - log?: Logger, - eventLog?: EventLog, - ) { - this.pi = pi; - this.planDir = config.planDir; - this.failures = config.failures; - this.dispatch = dispatch; - this.planRef = planRef; - this.log = log ?? createLogger("PlanDocsFix"); - this.eventLog = eventLog; - - this.state = { - active: false, - step: 1, - step1Prompt: null, - systemPrompt: null, - }; - - this.registerHandlers(); - } - - private get totalSteps(): number { - return 2 + this.failures.length; - } - - async begin(): Promise { - let basePrompt: string; - try { - basePrompt = await loadPlanDocsSystemPrompt(); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Fix phase aborted: cannot load system prompt", { error: message }); - return; - } - - const failuresXml = formatFailuresXml(this.failures); - const totalSteps = this.totalSteps; - this.state.systemPrompt = buildFixSystemPrompt( - buildPlanDocsSystemPrompt(basePrompt), - this.failures.length, - totalSteps, - ); - const conversationPath = path.join(this.planDir, "conversation.jsonl"); - this.state.step1Prompt = formatStep(fixStepGuidance(1, totalSteps, { allFailuresXml: failuresXml, conversationPath })); - this.state.active = true; - this.state.step = 1; - this.planRef.dir = this.planDir; - - hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - - this.log("Starting plan-docs fix workflow", { step: 1, totalSteps, failureCount: this.failures.length }); - await this.eventLog?.emitPhaseStart(totalSteps); - await this.eventLog?.emitStepTransition(1, fixStepName(1, totalSteps), totalSteps); - } - - private registerHandlers(): void { - this.pi.on("before_agent_start", () => { - if (!this.state.active || !this.state.systemPrompt) return undefined; - return { systemPrompt: this.state.systemPrompt }; - }); - - this.pi.on("context", (event) => { - if (!this.state.active) return undefined; - if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; - - const messages = event.messages.map((m) => { - if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; - return m; - }); - return { messages }; - }); - - this.pi.on("tool_call", (event) => { - if (!this.state.active) return undefined; - - const perm = checkPermission("plan-docs", event.toolName); - if (!perm.allowed) return { block: true, reason: perm.reason }; - - const step = this.state.step; - const total = this.totalSteps; - const inFixRange = step >= 2 && step < total; - if (!inFixRange && PLAN_MUTATION_TOOLS.has(event.toolName)) { - return { - block: true, - reason: `${event.toolName} available in steps 2-${total - 1} (current: ${step})`, - }; - } - - return undefined; - }); - } - - private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { - const prev = this.state.step; - const total = this.totalSteps; - - if (prev === total) { - const result = await this.handleFinalize(); - if (!result.ok) { - await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); - return { ok: false, error: result.errors?.join("; ") }; - } - - this.state.active = false; - unhookDispatch(this.dispatch, "onCompleteStep"); - await this.eventLog?.emitPhaseEnd("completed"); - this.log("Fix phase complete, plan-docs validation passed"); - return { ok: true, prompt: "Fix phase validation passed. Workflow complete." }; - } - - const next = prev + 1; - this.state.step = next; - - const item = next >= 2 && next < total ? this.failures[next - 2] : undefined; - const name = fixStepName(next, total, item); - const prompt = formatStep(fixStepGuidance(next, total, { item })); - - this.log("Fix step complete, advancing", { from: prev, to: next, name }); - await this.eventLog?.emitStepTransition(next, name, total); - return { ok: true, prompt }; - } - - private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { - return loadAndValidatePlanForPhase(this.planDir, "plan-docs", this.log); - } -} diff --git a/src/planner/phases/plan-docs/fix-prompts.ts b/src/planner/phases/plan-docs/fix-prompts.ts deleted file mode 100644 index 5ae245c..0000000 --- a/src/planner/phases/plan-docs/fix-prompts.ts +++ /dev/null @@ -1,106 +0,0 @@ -import type { QRItem } from "../../qr/types.js"; -import type { StepGuidance } from "../../lib/step.js"; -import { buildPlanDocsContextTrigger } from "../../lib/conversation-trigger.js"; - -export function formatFailuresXml(failures: ReadonlyArray): string { - const items = failures - .map((f) => [ - ` `, - ` ${f.check}`, - f.finding ? ` ${f.finding}` : " ", - " ", - ].join("\n")) - .join("\n"); - return ["", items, ""].join("\n"); -} - -export function fixStepName(step: number, totalSteps: number, item?: QRItem): string { - if (step === 1) return "Understand QR Failures"; - if (step === totalSteps) return "Review & Finalize"; - return item ? `Fix ${item.id}` : `Fix item ${step - 1}`; -} - -export function buildFixSystemPrompt(basePrompt: string, failureCount: number, totalSteps: number): string { - return [ - basePrompt, - "", - "---", - "", - `WORKFLOW: ${totalSteps}-STEP PLAN-DOCS FIX`, - "", - `You are fixing ${failureCount} documentation-related QR failure(s).`, - "Step 1 is read-only and covers all failures.", - `Steps 2-${totalSteps - 1} fix exactly one failure per step.`, - `Step ${totalSteps} is read-only review.`, - "", - "CONSTRAINTS:", - "- Fix only identified failures", - "- Keep docs timeless and decision-grounded", - "- Preserve already-valid doc artifacts", - ].join("\n"); -} - -function step1(totalSteps: number, failuresXml: string, conversationPath?: string): StepGuidance { - const itemCount = totalSteps - 2; - return { - title: `Step 1/${totalSteps}: Understand QR Failures`, - instructions: [ - "QR FAILURES:", - "", - failuresXml, - "", - ...buildPlanDocsContextTrigger(conversationPath ?? "/conversation.jsonl"), - "", - `There are ${itemCount} item(s). You will fix them one by one in steps 2-${totalSteps - 1}.`, - "Inspect current docs state via koan_get_plan / koan_get_change.", - "Identify exact correction needed per item.", - "", - "This step is read-only.", - ], - }; -} - -function itemStep(step: number, totalSteps: number, item?: QRItem): StepGuidance { - const itemXml = item ? formatFailuresXml([item]) : ""; - const idx = step - 1; - const total = totalSteps - 2; - return { - title: `Step ${step}/${totalSteps}: Fix ${item?.id ?? `item ${idx}`}`, - instructions: [ - `FIX ITEM ${idx} OF ${total}:`, - "", - itemXml, - "", - "Apply a targeted docs fix using doc tools (set doc_diff/comments/readme/diagram).", - "Do not batch-fix other failures in this step.", - "Keep changes minimal and scoped.", - ], - }; -} - -function finalStep(totalSteps: number): StepGuidance { - return { - title: `Step ${totalSteps}/${totalSteps}: Review & Finalize`, - instructions: [ - "All per-item fixes are complete.", - "Use koan_get_plan to verify docs coherence and completeness.", - "Confirm fixed items are addressed without regressing passing items.", - "", - "This step is read-only.", - ], - invokeAfter: [ - "WHEN DONE: Call koan_get_plan, then call koan_complete_step.", - "Do NOT call koan_complete_step before reviewing final plan state.", - ].join("\n"), - }; -} - -export function fixStepGuidance( - step: number, - totalSteps: number, - opts?: { item?: QRItem; allFailuresXml?: string; conversationPath?: string }, -): StepGuidance { - if (step === 1) return step1(totalSteps, opts?.allFailuresXml ?? "", opts?.conversationPath); - if (step === totalSteps) return finalStep(totalSteps); - return itemStep(step, totalSteps, opts?.item); -} diff --git a/src/planner/phases/plan-docs/phase.ts b/src/planner/phases/plan-docs/phase.ts deleted file mode 100644 index 24970ce..0000000 --- a/src/planner/phases/plan-docs/phase.ts +++ /dev/null @@ -1,154 +0,0 @@ -// Plan-docs phase -- 6-step technical writer workflow producing doc artifacts -// (doc_diff/comments/diagram/readme) in plan.json. - -import * as path from "node:path"; - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { loadAndValidatePlanForPhase } from "../../plan/validate.js"; -import { - loadPlanDocsSystemPrompt, - buildPlanDocsSystemPrompt, - planDocsStepGuidance, - STEP_NAMES, -} from "./prompts.js"; -import { formatStep } from "../../lib/step.js"; -import { createLogger, type Logger } from "../../../utils/logger.js"; -import { EventLog } from "../../lib/audit.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; -import { checkPermission, PLAN_MUTATION_TOOLS } from "../../lib/permissions.js"; - -type PlanDocsStep = 1 | 2 | 3 | 4 | 5 | 6; - -interface PlanDocsState { - active: boolean; - step: PlanDocsStep; - step1Prompt: string | null; - systemPrompt: string | null; -} - -const TOTAL_STEPS = 6; -const MUTATION_UNLOCK_STEP = 3; - -export class PlanDocsPhase { - private readonly pi: ExtensionAPI; - private readonly planDir: string; - private readonly log: Logger; - private readonly state: PlanDocsState; - private readonly eventLog: EventLog | undefined; - private readonly dispatch: WorkflowDispatch; - private readonly planRef: PlanRef; - - constructor( - pi: ExtensionAPI, - config: { planDir: string }, - dispatch: WorkflowDispatch, - planRef: PlanRef, - log?: Logger, - eventLog?: EventLog, - ) { - this.pi = pi; - this.planDir = config.planDir; - this.dispatch = dispatch; - this.planRef = planRef; - this.log = log ?? createLogger("PlanDocs"); - this.eventLog = eventLog; - - this.state = { - active: false, - step: 1, - step1Prompt: null, - systemPrompt: null, - }; - - this.registerHandlers(); - } - - async begin(): Promise { - let basePrompt: string; - try { - basePrompt = await loadPlanDocsSystemPrompt(); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to load plan-docs system prompt", { error: message }); - return; - } - - this.state.systemPrompt = buildPlanDocsSystemPrompt(basePrompt); - const conversationPath = path.join(this.planDir, "conversation.jsonl"); - this.state.step1Prompt = formatStep(planDocsStepGuidance(1, conversationPath)); - this.state.active = true; - this.state.step = 1; - this.planRef.dir = this.planDir; - - hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - - this.log("Starting plan-docs workflow", { step: 1 }); - await this.eventLog?.emitPhaseStart(TOTAL_STEPS); - await this.eventLog?.emitStepTransition(1, STEP_NAMES[1], TOTAL_STEPS); - } - - private registerHandlers(): void { - this.pi.on("before_agent_start", () => { - if (!this.state.active || !this.state.systemPrompt) return undefined; - return { systemPrompt: this.state.systemPrompt }; - }); - - this.pi.on("context", (event) => { - if (!this.state.active) return undefined; - if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; - - const messages = event.messages.map((m) => { - if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; - return m; - }); - return { messages }; - }); - - this.pi.on("tool_call", (event) => { - if (!this.state.active) return undefined; - - const perm = checkPermission("plan-docs", event.toolName); - if (!perm.allowed) return { block: true, reason: perm.reason }; - - if (this.state.step < MUTATION_UNLOCK_STEP && PLAN_MUTATION_TOOLS.has(event.toolName)) { - return { - block: true, - reason: `${event.toolName} available from step ${MUTATION_UNLOCK_STEP} (current: ${this.state.step})`, - }; - } - - return undefined; - }); - } - - private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { - const prev = this.state.step; - - if (prev === 6) { - const result = await this.handleFinalize(); - if (!result.ok) { - await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); - return { ok: false, error: result.errors?.join("; ") }; - } - - this.state.active = false; - unhookDispatch(this.dispatch, "onCompleteStep"); - await this.eventLog?.emitPhaseEnd("completed"); - this.log("Plan-docs finalized, workflow complete"); - return { ok: true, prompt: "Plan-docs validation passed. Workflow complete." }; - } - - this.state.step = (prev + 1) as PlanDocsStep; - const nextName = STEP_NAMES[this.state.step]; - const prompt = formatStep(planDocsStepGuidance(this.state.step)); - - this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName }); - await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); - return { ok: true, prompt }; - } - - private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { - return loadAndValidatePlanForPhase(this.planDir, "plan-docs", this.log); - } -} diff --git a/src/planner/phases/plan-docs/prompts.ts b/src/planner/phases/plan-docs/prompts.ts deleted file mode 100644 index 5d350fe..0000000 --- a/src/planner/phases/plan-docs/prompts.ts +++ /dev/null @@ -1,153 +0,0 @@ -import type { StepGuidance } from "../../lib/step.js"; -import { buildPlanDocsContextTrigger } from "../../lib/conversation-trigger.js"; -import { loadAgentPrompt } from "../../lib/agent-prompts.js"; - -export const STEP_NAMES: Record<1 | 2 | 3 | 4 | 5 | 6, string> = { - 1: "Extract Documentation Context", - 2: "Analyze Planned Code Changes", - 3: "Author Code-Adjacent Docs", - 4: "Author Cross-Cutting Docs", - 5: "Diagram & Consistency Review", - 6: "Validation & Final Review", -}; - -export async function loadPlanDocsSystemPrompt(): Promise { - return loadAgentPrompt("technical-writer"); -} - -export function buildPlanDocsSystemPrompt(basePrompt: string): string { - return [ - basePrompt, - "", - "---", - "", - "WORKFLOW: 6-STEP PLAN-DOCS", - "", - "You are in planning mode. Add documentation artifacts to plan.json.", - "Step 1 instructions are in the user message below.", - "Complete each step, then call koan_complete_step.", - "Put your findings in the `thoughts` parameter.", - "The tool result contains the next step.", - "", - "CRITICAL:", - "- NEVER use edit/write tools during plan-docs.", - "- Populate code_change.doc_diff for code changes.", - "- Keep comments and docs timeless (no temporal contamination).", - "- Keep architecture diagrams and README entries aligned with plan intent.", - "", - "USER-DECIDED DECISIONS:", - "Decisions with source user:ask or user:conversation have NO existing", - "reference in the codebase. These MUST be documented in code comments,", - "doc_diff, or README entries so future readers understand the rationale", - "without needing to ask the same question again.", - ].join("\n"); -} - -export function planDocsStepGuidance( - step: 1 | 2 | 3 | 4 | 5 | 6, - conversationPath?: string, -): StepGuidance { - switch (step) { - case 1: - return { - title: "Step 1: Extract Documentation Context", - instructions: [ - "Use koan_get_plan to review decisions, constraints, risks, and milestones.", - "Capture decision IDs that should be reflected in documentation rationale.", - "", - "PRIORITY: Identify all decisions with source user:ask or user:conversation.", - "These have NO existing reference in code or docs -- the user provided", - "the authority. They MUST be documented. Track these IDs; steps 3-4", - "must cover every one.", - "", - ...buildPlanDocsContextTrigger(conversationPath ?? "/conversation.jsonl"), - "", - "This step is read-only.", - ], - }; - - case 2: - return { - title: "Step 2: Analyze Planned Code Changes", - instructions: [ - "Inspect each milestone and code_change:", - " - What needs doc_diff coverage?", - " - Which comments are missing or weak?", - " - Which changes require architecture/README support?", - "", - "Use koan_get_milestone / koan_get_change for detail.", - "This step is read-only.", - ], - }; - - case 3: - return { - title: "Step 3: Author Code-Adjacent Docs", - instructions: [ - "Populate code-level documentation in plan.json:", - " - koan_set_change_doc_diff", - " - koan_set_change_comments", - "", - "Rules:", - " - Every code change with diff should have doc_diff", - " - comments explain WHY (reference decisions where applicable)", - " - Avoid temporal language (no 'added', 'changed from', 'now')", - "", - "USER-SOURCED DECISIONS (source user:ask / user:conversation):", - " These have no existing codebase reference. For each one that affects", - " a code change, the comment or doc_diff MUST capture the rationale so", - " future readers do not need to re-ask the same question.", - " Reference the decision ID (e.g. 'See DL-003') in the comment.", - ], - }; - - case 4: - return { - title: "Step 4: Author Cross-Cutting Docs", - instructions: [ - "Update cross-cutting documentation artifacts:", - " - koan_set_readme_entry for docs not tied to one change", - " - koan_set_diagram (title/scope/ascii_render) for architecture visuals", - "", - "If diagrams are missing but needed, create them with:", - " - koan_add_diagram", - " - koan_add_diagram_node / koan_add_diagram_edge", - ], - }; - - case 5: - return { - title: "Step 5: Diagram & Consistency Review", - instructions: [ - "Review documentation consistency across the plan:", - " - doc_diff content matches planned behavior", - " - diagrams align with milestone scope", - " - README entries do not contradict decisions/invariants", - "", - "Use getter tools to re-read affected entities and patch gaps.", - ], - }; - - case 6: - return { - title: "Step 6: Validation & Final Review", - instructions: [ - "Perform final documentation completeness check:", - " - all code changes with diff have doc_diff", - " - comments/doc diffs are coherent and timeless", - " - readme/diagram updates are present when needed", - " - every user-sourced decision (source user:*) is referenced", - " in at least one comment, doc_diff, or README entry", - "", - "Fix remaining issues before completing.", - ], - invokeAfter: [ - "WHEN DONE: Call koan_complete_step with a concise docs-completeness summary.", - "Do NOT call this tool until documentation artifacts are complete.", - ].join("\n"), - }; - - default: - return { title: "", instructions: [] }; - } -} diff --git a/src/planner/phases/qr-decompose/phase.ts b/src/planner/phases/qr-decompose/phase.ts deleted file mode 100644 index a480799..0000000 --- a/src/planner/phases/qr-decompose/phase.ts +++ /dev/null @@ -1,197 +0,0 @@ -// QR decompose phase -- 13-step workflow that decomposes a plan phase into -// verifiable QR items. Two-tier step gate: koan_qr_add_item unlocks at step 5, -// koan_qr_assign_group unlocks at step 9. - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { - loadQRDecomposeSystemPrompt, - buildDecomposeSystemPrompt, - decomposeStepGuidance, - DECOMPOSE_STEP_NAMES, - type DecomposeStep, - type WorkPhaseKey, -} from "./prompts.js"; -import { formatStep } from "../../lib/step.js"; -import { createLogger, type Logger } from "../../../utils/logger.js"; -import { EventLog } from "../../lib/audit.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; -import { checkPermission } from "../../lib/permissions.js"; -import type { QRFile } from "../../qr/types.js"; - -const QR_ADD_TOOLS = new Set(["koan_qr_add_item"]); -const QR_ASSIGN_TOOLS = new Set(["koan_qr_assign_group"]); -const ADD_ITEM_UNLOCK = 5; -const ASSIGN_GROUP_UNLOCK = 9; -const TOTAL_STEPS = 13; - -interface DecomposeState { - active: boolean; - step: DecomposeStep; - step1Prompt: string | null; - systemPrompt: string | null; -} - -export class QRDecomposePhase { - private readonly pi: ExtensionAPI; - private readonly planDir: string; - private readonly workPhase: WorkPhaseKey; - private readonly qrPhaseKey: `qr-${WorkPhaseKey}`; - private readonly log: Logger; - private readonly state: DecomposeState; - private readonly eventLog: EventLog | undefined; - private readonly dispatch: WorkflowDispatch; - private readonly planRef: PlanRef; - - constructor( - pi: ExtensionAPI, - config: { planDir: string; workPhase: WorkPhaseKey }, - dispatch: WorkflowDispatch, - planRef: PlanRef, - log?: Logger, - eventLog?: EventLog, - ) { - this.pi = pi; - this.planDir = config.planDir; - this.workPhase = config.workPhase; - this.qrPhaseKey = `qr-${config.workPhase}`; - this.dispatch = dispatch; - this.planRef = planRef; - this.log = log ?? createLogger("QRDecompose"); - this.eventLog = eventLog; - - this.state = { - active: false, - step: 1, - step1Prompt: null, - systemPrompt: null, - }; - - this.registerHandlers(); - } - - async begin(): Promise { - let basePrompt: string; - try { - basePrompt = await loadQRDecomposeSystemPrompt(); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to load qr-decompose system prompt", { error: message }); - return; - } - - this.state.systemPrompt = buildDecomposeSystemPrompt(basePrompt, this.workPhase); - const conversationPath = path.join(this.planDir, "conversation.jsonl"); - this.state.step1Prompt = formatStep(decomposeStepGuidance(1, this.workPhase, conversationPath)); - this.state.active = true; - this.state.step = 1; - this.planRef.dir = this.planDir; - this.planRef.qrPhase = this.workPhase; - - hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - - this.log("Starting qr-decompose workflow", { step: 1, phase: this.workPhase }); - await this.eventLog?.emitPhaseStart(TOTAL_STEPS); - await this.eventLog?.emitStepTransition(1, DECOMPOSE_STEP_NAMES[1], TOTAL_STEPS); - } - - private registerHandlers(): void { - this.pi.on("before_agent_start", () => { - if (!this.state.active || !this.state.systemPrompt) return undefined; - return { systemPrompt: this.state.systemPrompt }; - }); - - this.pi.on("context", (event) => { - if (!this.state.active) return undefined; - if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; - - const messages = event.messages.map((m) => { - if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; - return m; - }); - return { messages }; - }); - - this.pi.on("tool_call", (event) => { - if (!this.state.active) return undefined; - - const perm = checkPermission(this.qrPhaseKey, event.toolName); - if (!perm.allowed) return { block: true, reason: perm.reason }; - - const step = this.state.step; - if (step < ADD_ITEM_UNLOCK && QR_ADD_TOOLS.has(event.toolName)) { - return { - block: true, - reason: `${event.toolName} available from step ${ADD_ITEM_UNLOCK} (current: ${step})`, - }; - } - if (step < ASSIGN_GROUP_UNLOCK && QR_ASSIGN_TOOLS.has(event.toolName)) { - return { - block: true, - reason: `${event.toolName} available from step ${ASSIGN_GROUP_UNLOCK} (current: ${step})`, - }; - } - - return undefined; - }); - } - - private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { - const prev = this.state.step; - - if (prev === 13) { - const result = await this.handleFinalize(); - if (!result.ok) { - await this.eventLog?.emitPhaseEnd("failed", result.errors?.join("; ")); - return { ok: false, error: result.errors?.join("; ") }; - } - - this.state.active = false; - unhookDispatch(this.dispatch, "onCompleteStep"); - await this.eventLog?.emitPhaseEnd("completed"); - this.log("QR decompose finalized, workflow complete", { phase: this.workPhase }); - return { ok: true, prompt: "QR decomposition complete." }; - } - - this.state.step = (prev + 1) as DecomposeStep; - const nextName = DECOMPOSE_STEP_NAMES[this.state.step]; - const prompt = formatStep(decomposeStepGuidance(this.state.step, this.workPhase)); - - this.log("Step complete, advancing", { from: prev, to: this.state.step, name: nextName, phase: this.workPhase }); - await this.eventLog?.emitStepTransition(this.state.step, nextName, TOTAL_STEPS); - return { ok: true, prompt }; - } - - private async handleFinalize(): Promise<{ ok: boolean; errors?: string[] }> { - const qrPath = path.join(this.planDir, `qr-${this.workPhase}.json`); - let qr: QRFile; - try { - const raw = await fs.readFile(qrPath, "utf8"); - qr = JSON.parse(raw) as QRFile; - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - return { ok: false, errors: [`Failed to read qr-${this.workPhase}.json: ${message}`] }; - } - - const errors: string[] = []; - if (!qr.items || qr.items.length === 0) { - errors.push("No QR items generated"); - } else { - const ungrouped = qr.items.filter((i) => i.group_id === null); - if (ungrouped.length > 0) { - errors.push(`Ungrouped items: ${ungrouped.map((i) => i.id).join(", ")}`); - } - } - - if (errors.length > 0) { - this.log("QR decompose validation failed", { errors, phase: this.workPhase }); - return { ok: false, errors }; - } - - this.log("QR decompose validation passed", { phase: this.workPhase }); - return { ok: true }; - } -} diff --git a/src/planner/phases/qr-decompose/prompts.ts b/src/planner/phases/qr-decompose/prompts.ts deleted file mode 100644 index 7e56164..0000000 --- a/src/planner/phases/qr-decompose/prompts.ts +++ /dev/null @@ -1,260 +0,0 @@ -// QR decompose phase prompts -- 13-step workflow for decomposing a plan into -// verifiable QR items. Prompt text is shared across plan-design, plan-code, -// and plan-docs via the injected phase key. - -import type { StepGuidance } from "../../lib/step.js"; -import { loadAgentPrompt } from "../../lib/agent-prompts.js"; -import { - buildPlanDesignContextTrigger, - buildPlanDocsContextTrigger, -} from "../../lib/conversation-trigger.js"; - -export type DecomposeStep = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13; -export type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; - -export const DECOMPOSE_STEP_NAMES: Record = { - 1: "Absorb Context", - 2: "Holistic Concerns", - 3: "Structural Enumeration", - 4: "Gap Analysis", - 5: "Generate Items", - 6: "Atomicity Check", - 7: "Coverage Validation", - 8: "Validate Items", - 9: "Structural Grouping", - 10: "Component Grouping", - 11: "Concern Grouping", - 12: "Affinity Grouping", - 13: "Final Validation", -}; - -const PHASE_SCOPE_HINTS: Record = { - "plan-design": [ - "decision:DL-001 -- decision reasoning quality and source provenance", - "milestone:M-001 -- milestone structure", - "code_intent:CI-M-001-001 -- intent clarity", - ], - "plan-code": [ - "milestone:M-001 -- code change coverage", - "code_intent:CI-M-001-001 -- intent->change linkage", - "change:CC-M-001-001 -- diff quality/anchor correctness", - ], - "plan-docs": [ - "milestone:M-001 -- docs completeness", - "change:CC-M-001-001 -- doc_diff/comments quality", - "diagram:DIAG-001 -- architecture docs fidelity", - "decision:DL-001 -- user-sourced decision docs coverage", - ], -}; - -function phaseContextTrigger( - phase: WorkPhaseKey, - conversationPath?: string, -): string[] { - if (phase === "plan-design") { - return buildPlanDesignContextTrigger(conversationPath ?? "/conversation.jsonl"); - } - if (phase === "plan-docs") { - return buildPlanDocsContextTrigger(conversationPath ?? "/conversation.jsonl"); - } - return []; -} - -export async function loadQRDecomposeSystemPrompt(): Promise { - return loadAgentPrompt("quality-reviewer"); -} - -export function buildDecomposeSystemPrompt(basePrompt: string, phase: WorkPhaseKey): string { - return [ - basePrompt, - "", - "---", - "", - `WORKFLOW: 13-STEP QR DECOMPOSITION (${phase})`, - "", - "You will execute a 13-step workflow to decompose the current plan phase into verifiable QR items.", - "Step 1 instructions are in the user message below.", - "Complete the work described, then call koan_complete_step.", - "Put your findings in the `thoughts` parameter of koan_complete_step.", - "The tool result contains the next step's instructions.", - "", - "CRITICAL: Do the actual work described in each step BEFORE calling", - "koan_complete_step. Read the plan, analyze, generate items. Do not skip.", - ].join("\n"); -} - -// Phase-specific holistic concerns injected into step 2. -// plan-design adds decision source provenance checks; -// plan-docs adds user-sourced decision documentation coverage. -function holisticConcernAdditions(phase: WorkPhaseKey): string[] { - if (phase === "plan-design") { - return [ - "", - "Include decision provenance as a concern:", - " - Every decision must have a non-null source", - " - Sources must be verifiable (code/docs paths should exist)", - " - Decisions sourced as inference need strong reasoning_chain", - " - No systematic inference labeling (if >50% of decisions are", - " inference, flag as umbrella concern)", - ]; - } - if (phase === "plan-docs") { - return [ - "", - "Include user-sourced decision documentation as a concern:", - " - Decisions with source user:ask or user:conversation must be", - " referenced in at least one comment, doc_diff, or README entry", - ]; - } - return []; -} - -export function decomposeStepGuidance( - step: DecomposeStep, - phase: WorkPhaseKey, - conversationPath?: string, -): StepGuidance { - switch (step) { - case 1: - return { - title: "Step 1: Absorb Context", - instructions: [ - `PHASE: ${phase}`, - "", - ...phaseContextTrigger(phase, conversationPath), - ...(phase === "plan-code" ? [] : [""]), - "Use koan_get_plan to read the full plan.", - "Absorb the structures relevant to this phase and identify what needs verification.", - ], - }; - - case 2: - return { - title: "Step 2: Holistic Concerns", - instructions: [ - `List phase-wide concerns for ${phase}.`, - "Focus on quality/completeness/consistency concerns, not implementation details.", - "These become umbrella items (scope='*').", - ...holisticConcernAdditions(phase), - ], - }; - - case 3: - return { - title: "Step 3: Structural Enumeration", - instructions: [ - `Enumerate concrete entities touched by ${phase}.`, - "Track IDs and counts so step 7 can validate coverage.", - "Use getter tools to resolve uncertain IDs.", - ], - }; - - case 4: - return { - title: "Step 4: Gap Analysis", - instructions: [ - "Map concerns (step 2) to entities (step 3).", - "Identify uncovered concerns and under-specified entities.", - ], - }; - - case 5: - return { - title: "Step 5: Generate Items", - instructions: [ - "Generate QR items with koan_qr_add_item.", - "", - "Scope examples for this phase:", - ...PHASE_SCOPE_HINTS[phase].map((hint) => ` - ${hint}`), - "", - "Severity:", - " MUST -- critical defect", - " SHOULD -- significant quality issue", - " COULD -- non-blocking improvement", - ], - }; - - case 6: - return { - title: "Step 6: Atomicity Check", - instructions: [ - "Ensure each item checks exactly one concern.", - "Split non-atomic items by adding child items when needed.", - ], - }; - - case 7: - return { - title: "Step 7: Coverage Validation", - instructions: [ - "Cross-check item set against structural enumeration from step 3.", - "Add missing items for uncovered entities/concerns.", - ], - }; - - case 8: - return { - title: "Step 8: Validate Items", - instructions: [ - "Use koan_qr_summary and koan_qr_list_items to audit generated items.", - "Fix duplicates or malformed scopes by adding/revising items.", - ], - }; - - case 9: - return { - title: "Step 9: Structural Grouping", - instructions: [ - "Assign deterministic groups:", - " - Parent/child items share group", - " - Umbrella items (scope='*') use group_id='umbrella'", - "Use koan_qr_assign_group to assign groups.", - ], - }; - - case 10: - return { - title: "Step 10: Component Grouping", - instructions: [ - "Group remaining ungrouped items by component (milestone/decision/change cluster).", - "Use koan_qr_list_items and koan_qr_assign_group.", - ], - }; - - case 11: - return { - title: "Step 11: Concern Grouping", - instructions: [ - "Group remaining ungrouped items by concern type.", - "Example concern groups: coverage, consistency, traceability, docs quality.", - ], - }; - - case 12: - return { - title: "Step 12: Affinity Grouping", - instructions: [ - "Assign any remaining ungrouped items by semantic affinity.", - "Singleton groups are acceptable.", - ], - }; - - case 13: - return { - title: "Step 13: Final Validation", - instructions: [ - "Validate that all items are grouped and well-formed.", - "Use koan_qr_summary and koan_qr_list_items.", - "Ensure no item has null group_id.", - "Output PASS in thoughts when complete.", - ], - invokeAfter: [ - "WHEN DONE: Call koan_complete_step with PASS or issues in `thoughts`.", - "Do NOT call this tool until validation is complete.", - ].join("\n"), - }; - - default: - return { title: "", instructions: [] }; - } -} diff --git a/src/planner/phases/qr-verify/phase.ts b/src/planner/phases/qr-verify/phase.ts deleted file mode 100644 index eaf819d..0000000 --- a/src/planner/phases/qr-verify/phase.ts +++ /dev/null @@ -1,243 +0,0 @@ -// QR verify phase -- dynamic-step reviewer subagent that verifies 1..N QR items -// against the plan. Workflow: CONTEXT (once) -> N × (ANALYZE + CONFIRM) -> done. -// Items in a group share a single subagent, amortizing process startup cost. -// -// Dynamic step formula: totalSteps = 1 + (2 * numItems) -// Step 1: CONTEXT (load plan, list all assigned items) -// Step 2k: ANALYZE item k (k = 1..N) -// Step 2k+1: CONFIRM item k (record verdict) -// -// Step gating: koan_qr_set_item is blocked until the CONFIRM step for the -// current item (odd-numbered steps >= 3). - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { formatStep } from "../../lib/step.js"; -import { createLogger, type Logger } from "../../../utils/logger.js"; -import { EventLog } from "../../lib/audit.js"; -import { hookDispatch, unhookDispatch, type WorkflowDispatch, type PlanRef } from "../../lib/dispatch.js"; -import { checkPermission } from "../../lib/permissions.js"; -import type { QRItem, QRFile } from "../../qr/types.js"; -import { - loadQRVerifySystemPrompt, - buildVerifySystemPrompt, - buildContextStep, - buildAnalyzeStep, - buildConfirmStep, -} from "./prompts.js"; - -type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; - -interface VerifyState { - active: boolean; - step: number; - totalSteps: number; - itemIds: string[]; - step1Prompt: string | null; - systemPrompt: string | null; -} - -// Map step number to step type and item index. -// Step 1 is CONTEXT. Steps 2..2N+1 alternate ANALYZE/CONFIRM per item. -function stepType(step: number): { kind: "CONTEXT" } | { kind: "ANALYZE"; itemIndex: number } | { kind: "CONFIRM"; itemIndex: number } { - if (step === 1) return { kind: "CONTEXT" }; - const offset = step - 2; // 0-indexed from step 2 - const itemIndex = Math.floor(offset / 2); - const isConfirm = offset % 2 === 1; - return isConfirm ? { kind: "CONFIRM", itemIndex } : { kind: "ANALYZE", itemIndex }; -} - -function stepName(step: number, numItems: number): string { - if (step === 1) return "CONTEXT"; - const info = stepType(step); - if (info.kind === "ANALYZE") return `ANALYZE ${info.itemIndex + 1}/${numItems}`; - if (info.kind === "CONFIRM") return `CONFIRM ${info.itemIndex + 1}/${numItems}`; - return `Step ${step}`; -} - -export class QRVerifyPhase { - private readonly pi: ExtensionAPI; - private readonly planDir: string; - private readonly workPhase: WorkPhaseKey; - private readonly qrPhaseKey: `qr-${WorkPhaseKey}`; - private readonly log: Logger; - private readonly state: VerifyState; - private readonly eventLog: EventLog | undefined; - private readonly dispatch: WorkflowDispatch; - private readonly planRef: PlanRef; - private items: QRItem[] = []; - - constructor( - pi: ExtensionAPI, - config: { planDir: string; itemIds: string[]; workPhase: WorkPhaseKey }, - dispatch: WorkflowDispatch, - planRef: PlanRef, - log?: Logger, - eventLog?: EventLog, - ) { - this.pi = pi; - this.planDir = config.planDir; - this.workPhase = config.workPhase; - this.qrPhaseKey = `qr-${config.workPhase}`; - this.dispatch = dispatch; - this.planRef = planRef; - this.log = log ?? createLogger("QRVerify"); - this.eventLog = eventLog; - - const numItems = config.itemIds.length; - const totalSteps = 1 + 2 * numItems; - - this.state = { - active: false, - step: 1, - totalSteps, - itemIds: config.itemIds, - step1Prompt: null, - systemPrompt: null, - }; - - this.registerHandlers(); - } - - async begin(): Promise { - const planPath = path.join(this.planDir, "plan.json"); - try { - await fs.access(planPath); - } catch { - this.log("plan.json not found", { path: planPath }); - return; - } - - const qrPath = path.join(this.planDir, `qr-${this.workPhase}.json`); - let qrFile: QRFile; - try { - const raw = await fs.readFile(qrPath, "utf8"); - qrFile = JSON.parse(raw) as QRFile; - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log(`Failed to read qr-${this.workPhase}.json`, { error: message }); - return; - } - - // Resolve all item IDs to QRItem objects. - const resolvedItems: QRItem[] = []; - for (const id of this.state.itemIds) { - const item = qrFile.items.find((i) => i.id === id); - if (!item) { - this.log("QR item not found", { itemId: id, phase: this.workPhase }); - return; - } - resolvedItems.push(item); - } - this.items = resolvedItems; - - let basePrompt: string; - try { - basePrompt = await loadQRVerifySystemPrompt(); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - this.log("Failed to load QR verify system prompt", { error: message }); - return; - } - - this.state.systemPrompt = buildVerifySystemPrompt(basePrompt, this.workPhase, this.items.length); - const conversationPath = path.join(this.planDir, "conversation.jsonl"); - this.state.step1Prompt = formatStep(buildContextStep(this.items, this.workPhase, conversationPath)); - this.state.active = true; - this.state.step = 1; - this.planRef.dir = this.planDir; - this.planRef.qrPhase = this.workPhase; - - hookDispatch(this.dispatch, "onCompleteStep", () => this.handleStepComplete()); - - this.log("Starting QR verify workflow", { - itemIds: this.state.itemIds, - itemCount: this.items.length, - totalSteps: this.state.totalSteps, - phase: this.workPhase, - step: 1, - }); - await this.eventLog?.emitPhaseStart(this.state.totalSteps); - await this.eventLog?.emitStepTransition(1, "CONTEXT", this.state.totalSteps); - } - - private registerHandlers(): void { - this.pi.on("before_agent_start", () => { - if (!this.state.active || !this.state.systemPrompt) return undefined; - return { systemPrompt: this.state.systemPrompt }; - }); - - this.pi.on("context", (event) => { - if (!this.state.active) return undefined; - if (this.state.step !== 1 || !this.state.step1Prompt) return undefined; - - const messages = event.messages.map((m) => { - if (m.role === "user") return { ...m, content: this.state.step1Prompt! }; - return m; - }); - return { messages }; - }); - - this.pi.on("tool_call", (event) => { - if (!this.state.active) return undefined; - - const perm = checkPermission(this.qrPhaseKey, event.toolName); - if (!perm.allowed) return { block: true, reason: perm.reason }; - - // koan_qr_set_item is only allowed during CONFIRM steps (odd steps >= 3). - if (event.toolName === "koan_qr_set_item") { - const info = stepType(this.state.step); - if (info.kind !== "CONFIRM") { - return { - block: true, - reason: `koan_qr_set_item available only during CONFIRM steps (current: ${stepName(this.state.step, this.items.length)})`, - }; - } - } - - return undefined; - }); - } - - private async handleStepComplete(): Promise<{ ok: boolean; prompt?: string; error?: string }> { - const prev = this.state.step; - - if (prev >= this.state.totalSteps) { - this.state.active = false; - unhookDispatch(this.dispatch, "onCompleteStep"); - await this.eventLog?.emitPhaseEnd("completed"); - this.log("Verification complete", { - itemCount: this.items.length, - phase: this.workPhase, - }); - return { ok: true, prompt: "Verification complete." }; - } - - this.state.step = prev + 1; - const name = stepName(this.state.step, this.items.length); - const prompt = this.buildStepPrompt(this.state.step); - - this.log("Step complete, advancing", { - from: prev, - to: this.state.step, - name, - phase: this.workPhase, - }); - await this.eventLog?.emitStepTransition(this.state.step, name, this.state.totalSteps); - return { ok: true, prompt }; - } - - private buildStepPrompt(step: number): string { - const info = stepType(step); - if (info.kind === "ANALYZE") { - return formatStep(buildAnalyzeStep(this.items[info.itemIndex], info.itemIndex, this.items.length)); - } - if (info.kind === "CONFIRM") { - return formatStep(buildConfirmStep(this.items[info.itemIndex], info.itemIndex, this.items.length, this.workPhase)); - } - return ""; - } -} diff --git a/src/planner/phases/qr-verify/prompts.ts b/src/planner/phases/qr-verify/prompts.ts deleted file mode 100644 index f3d7ab0..0000000 --- a/src/planner/phases/qr-verify/prompts.ts +++ /dev/null @@ -1,175 +0,0 @@ -// Prompt guidance for the dynamic-step QR verify subagent workflow. -// Each reviewer subagent verifies 1..N QRItems (grouped by group_id). -// -// Dynamic step formula: totalSteps = 1 + (2 * numItems) -// Step 1: CONTEXT (once, lists all items) -// Steps 2..2N+1: ANALYZE/CONFIRM pairs per item - -import type { QRItem } from "../../qr/types.js"; -import { loadAgentPrompt } from "../../lib/agent-prompts.js"; -import type { StepGuidance } from "../../lib/step.js"; -import { - buildPlanDesignContextTrigger, - buildPlanDocsContextTrigger, -} from "../../lib/conversation-trigger.js"; - -type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; - -function scopeGuidance(item: QRItem): string { - const s = item.scope; - if (s === "*") { - return "MACRO CHECK -- Use koan_get_plan to read the full plan."; - } - if (s.startsWith("milestone:")) { - const milestoneId = s.slice("milestone:".length); - return `MILESTONE CHECK -- Use koan_get_milestone(id='${milestoneId}') to read the milestone.`; - } - if (s.startsWith("code_intent:")) { - const intentId = s.slice("code_intent:".length); - return `CODE INTENT CHECK -- Use koan_get_intent(id='${intentId}') to read the intent.`; - } - if (s.startsWith("change:")) { - const changeId = s.slice("change:".length); - return `CHANGE CHECK -- Use koan_get_change(id='${changeId}') to read the planned change.`; - } - if (s.startsWith("decision:")) { - const decisionId = s.slice("decision:".length); - return `DECISION CHECK -- Use koan_get_decision(id='${decisionId}') to read the decision.`; - } - return "SCOPED CHECK -- Read the relevant section using plan getter tools."; -} - -function phaseContextTrigger( - phase: WorkPhaseKey, - conversationPath?: string, -): string[] { - if (phase === "plan-design") { - return buildPlanDesignContextTrigger(conversationPath ?? "/conversation.jsonl"); - } - if (phase === "plan-docs") { - return buildPlanDocsContextTrigger(conversationPath ?? "/conversation.jsonl"); - } - return []; -} - -export async function loadQRVerifySystemPrompt(): Promise { - return loadAgentPrompt("quality-reviewer"); -} - -export function buildVerifySystemPrompt(basePrompt: string, phase: WorkPhaseKey, itemCount: number): string { - const itemLabel = itemCount === 1 ? "1 QR item" : `${itemCount} QR items`; - return [ - basePrompt, - "", - "---", - "", - `WORKFLOW: QR VERIFICATION (${phase}, ${itemLabel})`, - "", - `You will verify ${itemLabel} against the plan.`, - "Step 1 instructions are in the user message below.", - "Complete the work described, then call koan_complete_step.", - "Put your findings in the `thoughts` parameter of koan_complete_step.", - "", - "CRITICAL: Do NOT record a verdict until the CONFIRM step for each item.", - "Analyze thoroughly in the ANALYZE step before committing.", - ].join("\n"); -} - -function formatItemForContext(item: QRItem): string { - return [ - ` ${item.id} [${item.severity}]: ${item.check}`, - ` scope: ${item.scope}`, - ].join("\n"); -} - -export function buildContextStep( - items: QRItem[], - phase: WorkPhaseKey, - conversationPath?: string, -): StepGuidance { - const itemLabel = items.length === 1 ? "1 ITEM" : `${items.length} ITEMS`; - const itemSummary = items.map(formatItemForContext).join("\n"); - - return { - title: `Step 1: CONTEXT`, - instructions: [ - `PHASE: ${phase}`, - `ITEMS TO VERIFY: ${itemLabel}`, - "", - itemSummary, - "", - ...phaseContextTrigger(phase, conversationPath), - ...(phase === "plan-code" ? [] : [""]), - "Understand the checks and required evidence before analyzing.", - ], - }; -} - -export function buildAnalyzeStep(item: QRItem, itemIndex: number, totalItems: number): StepGuidance { - const positionLabel = totalItems === 1 - ? "" - : ` (item ${itemIndex + 1} of ${totalItems})`; - - return { - title: `ANALYZE ${item.id}${positionLabel}`, - instructions: [ - scopeGuidance(item), - "", - "", - ` ${item.id}`, - ` ${item.scope}`, - ` ${item.check}`, - ` ${item.severity}`, - "", - "", - "TASK:", - "1. Read relevant entities based on scope", - "2. Apply the verification check", - "3. Form preliminary PASS/FAIL conclusion", - "4. Gather concrete evidence", - "", - "Do NOT update QR state yet.", - ], - }; -} - -export function buildConfirmStep( - item: QRItem, - itemIndex: number, - totalItems: number, - phase: WorkPhaseKey, -): StepGuidance { - const positionLabel = totalItems === 1 - ? "" - : ` (item ${itemIndex + 1} of ${totalItems})`; - - return { - title: `CONFIRM ${item.id}${positionLabel}`, - instructions: [ - `CONFIRMING: ${item.id}`, - `SEVERITY: ${item.severity}`, - "", - "CONFIDENCE CHECK:", - "- Are you confident in your conclusion?", - "- Is evidence specific and verifiable?", - "", - "RECORD RESULT:", - "", - "If PASS:", - ` koan_qr_set_item(id='${item.id}', status='PASS')`, - "", - "If FAIL:", - ` koan_qr_set_item(id='${item.id}', status='FAIL', finding='')`, - "", - "RULES:", - "- FAIL requires finding", - "- PASS must not include finding", - "", - "Execute ONE verdict call, then call koan_complete_step.", - ], - invokeAfter: [ - "WHEN DONE: Call koan_complete_step after recording your verdict.", - "Do NOT call this tool until you have called koan_qr_set_item.", - ].join("\n"), - }; -} diff --git a/src/planner/plan/mutate/code.ts b/src/planner/plan/mutate/code.ts deleted file mode 100644 index 7eb74a3..0000000 --- a/src/planner/plan/mutate/code.ts +++ /dev/null @@ -1,161 +0,0 @@ -// Code intent and code change mutations. -// Pure functions -- input plan in, new plan out. No side effects. - -import type { Plan, CodeIntent, CodeChange } from "../types.js"; -import { nextIntentId, nextChangeId } from "../types.js"; - -// -- CodeIntent -- - -export function addIntent( - p: Plan, - data: { - milestone: string; - file: string; - function?: string; - behavior: string; - decision_refs?: string[]; - }, -): { plan: Plan; id: string } { - const idx = p.milestones.findIndex((m) => m.id === data.milestone); - if (idx === -1) throw new Error(`milestone ${data.milestone} not found`); - - const m = p.milestones[idx]; - const id = nextIntentId(m); - const intent: CodeIntent = { - id, - file: data.file, - function: data.function ?? null, - behavior: data.behavior, - decision_refs: data.decision_refs ?? [], - }; - - const updated = [...p.milestones]; - updated[idx] = { - ...m, - code_intents: [...m.code_intents, intent], - }; - - return { - plan: { ...p, milestones: updated }, - id, - }; -} - -export function setIntent( - p: Plan, - id: string, - data: { - file?: string; - function?: string; - behavior?: string; - decision_refs?: string[]; - }, -): Plan { - for (let i = 0; i < p.milestones.length; i++) { - const m = p.milestones[i]; - const ciIdx = m.code_intents.findIndex((ci) => ci.id === id); - if (ciIdx !== -1) { - const ci = m.code_intents[ciIdx]; - const updated: CodeIntent = { - ...ci, - file: data.file ?? ci.file, - function: data.function ?? ci.function, - behavior: data.behavior ?? ci.behavior, - decision_refs: data.decision_refs ?? ci.decision_refs, - }; - - const intents = [...m.code_intents]; - intents[ciIdx] = updated; - - const milestones = [...p.milestones]; - milestones[i] = { ...m, code_intents: intents }; - - return { ...p, milestones }; - } - } - throw new Error(`intent ${id} not found`); -} - -// -- CodeChange -- - -export function addChange( - p: Plan, - data: { - milestone: string; - file: string; - intent_ref?: string; - diff?: string; - doc_diff?: string; - comments?: string; - }, -): { plan: Plan; id: string } { - const idx = p.milestones.findIndex((m) => m.id === data.milestone); - if (idx === -1) throw new Error(`milestone ${data.milestone} not found`); - - const m = p.milestones[idx]; - const id = nextChangeId(m); - const change: CodeChange = { - id, - intent_ref: data.intent_ref ?? null, - file: data.file, - diff: data.diff ?? "", - doc_diff: data.doc_diff ?? "", - comments: data.comments ?? "", - }; - - const updated = [...p.milestones]; - updated[idx] = { - ...m, - code_changes: [...m.code_changes, change], - }; - - return { - plan: { ...p, milestones: updated }, - id, - }; -} - -function updateChange( - p: Plan, - id: string, - fn: (c: CodeChange) => CodeChange, -): Plan { - for (let i = 0; i < p.milestones.length; i++) { - const m = p.milestones[i]; - const ccIdx = m.code_changes.findIndex((cc) => cc.id === id); - if (ccIdx !== -1) { - const changes = [...m.code_changes]; - changes[ccIdx] = fn(m.code_changes[ccIdx]); - - const milestones = [...p.milestones]; - milestones[i] = { ...m, code_changes: changes }; - - return { ...p, milestones }; - } - } - throw new Error(`code_change ${id} not found`); -} - -export function setChangeDiff(p: Plan, id: string, diff: string): Plan { - return updateChange(p, id, (c) => ({ ...c, diff })); -} - -export function setChangeDocDiff(p: Plan, id: string, doc_diff: string): Plan { - return updateChange(p, id, (c) => ({ ...c, doc_diff })); -} - -export function setChangeComments(p: Plan, id: string, comments: string): Plan { - return updateChange(p, id, (c) => ({ ...c, comments })); -} - -export function setChangeFile(p: Plan, id: string, file: string): Plan { - return updateChange(p, id, (c) => ({ ...c, file })); -} - -export function setChangeIntentRef( - p: Plan, - id: string, - intent_ref: string, -): Plan { - return updateChange(p, id, (c) => ({ ...c, intent_ref })); -} diff --git a/src/planner/plan/mutate/decisions.ts b/src/planner/plan/mutate/decisions.ts deleted file mode 100644 index a43107b..0000000 --- a/src/planner/plan/mutate/decisions.ts +++ /dev/null @@ -1,180 +0,0 @@ -// Decision log mutations: decisions, rejected alternatives, risks. -// Pure functions -- input plan in, new plan out. No side effects. - -import type { Plan, Decision, RejectedAlternative, Risk } from "../types.js"; -import { - nextDecisionId, - nextRejectedAltId, - nextRiskId, -} from "../types.js"; - -// -- Decision -- - -export function addDecision( - p: Plan, - data: { decision: string; reasoning: string; source?: string }, -): { plan: Plan; id: string } { - const id = nextDecisionId(p); - const decision: Decision = { - id, - decision: data.decision, - reasoning_chain: data.reasoning, - source: data.source ?? null, - }; - return { - plan: { - ...p, - planning_context: { - ...p.planning_context, - decision_log: [...p.planning_context.decision_log, decision], - }, - }, - id, - }; -} - -export function setDecision( - p: Plan, - id: string, - data: { decision?: string; reasoning?: string; source?: string }, -): Plan { - const idx = p.planning_context.decision_log.findIndex((d) => d.id === id); - if (idx === -1) throw new Error(`decision ${id} not found`); - - const d = p.planning_context.decision_log[idx]; - const updated: Decision = { - ...d, - decision: data.decision ?? d.decision, - reasoning_chain: data.reasoning ?? d.reasoning_chain, - source: data.source ?? d.source, - }; - - const log = [...p.planning_context.decision_log]; - log[idx] = updated; - - return { - ...p, - planning_context: { ...p.planning_context, decision_log: log }, - }; -} - -// -- RejectedAlternative -- - -export function addRejectedAlternative( - p: Plan, - data: { alternative: string; rejection_reason: string; decision_ref: string }, -): { plan: Plan; id: string } { - const id = nextRejectedAltId(p); - const ra: RejectedAlternative = { - id, - alternative: data.alternative, - rejection_reason: data.rejection_reason, - decision_ref: data.decision_ref, - }; - return { - plan: { - ...p, - planning_context: { - ...p.planning_context, - rejected_alternatives: [ - ...p.planning_context.rejected_alternatives, - ra, - ], - }, - }, - id, - }; -} - -export function setRejectedAlternative( - p: Plan, - id: string, - data: { - alternative?: string; - rejection_reason?: string; - decision_ref?: string; - }, -): Plan { - const idx = p.planning_context.rejected_alternatives.findIndex( - (r) => r.id === id, - ); - if (idx === -1) throw new Error(`rejected_alternative ${id} not found`); - - const r = p.planning_context.rejected_alternatives[idx]; - const updated: RejectedAlternative = { - ...r, - alternative: data.alternative ?? r.alternative, - rejection_reason: data.rejection_reason ?? r.rejection_reason, - decision_ref: data.decision_ref ?? r.decision_ref, - }; - - const list = [...p.planning_context.rejected_alternatives]; - list[idx] = updated; - - return { - ...p, - planning_context: { ...p.planning_context, rejected_alternatives: list }, - }; -} - -// -- Risk -- - -export function addRisk( - p: Plan, - data: { - risk: string; - mitigation: string; - anchor?: string; - decision_ref?: string; - }, -): { plan: Plan; id: string } { - const id = nextRiskId(p); - const risk: Risk = { - id, - risk: data.risk, - mitigation: data.mitigation, - anchor: data.anchor ?? null, - decision_ref: data.decision_ref ?? null, - }; - return { - plan: { - ...p, - planning_context: { - ...p.planning_context, - known_risks: [...p.planning_context.known_risks, risk], - }, - }, - id, - }; -} - -export function setRisk( - p: Plan, - id: string, - data: { - risk?: string; - mitigation?: string; - anchor?: string; - decision_ref?: string; - }, -): Plan { - const idx = p.planning_context.known_risks.findIndex((r) => r.id === id); - if (idx === -1) throw new Error(`risk ${id} not found`); - - const r = p.planning_context.known_risks[idx]; - const updated: Risk = { - ...r, - risk: data.risk ?? r.risk, - mitigation: data.mitigation ?? r.mitigation, - anchor: data.anchor ?? r.anchor, - decision_ref: data.decision_ref ?? r.decision_ref, - }; - - const list = [...p.planning_context.known_risks]; - list[idx] = updated; - - return { - ...p, - planning_context: { ...p.planning_context, known_risks: list }, - }; -} diff --git a/src/planner/plan/mutate/index.ts b/src/planner/plan/mutate/index.ts deleted file mode 100644 index 0c96dcb..0000000 --- a/src/planner/plan/mutate/index.ts +++ /dev/null @@ -1,48 +0,0 @@ -// Re-exports all public mutation functions grouped by domain. -// Consumers import from this single entry point. - -export { - setOverview, - setConstraints, - setInvisibleKnowledge, -} from "./top-level.js"; - -export { - addDecision, - setDecision, - addRejectedAlternative, - setRejectedAlternative, - addRisk, - setRisk, -} from "./decisions.js"; - -export { - addMilestone, - setMilestoneName, - setMilestoneFiles, - setMilestoneFlags, - setMilestoneRequirements, - setMilestoneAcceptanceCriteria, - setMilestoneTests, -} from "./milestones.js"; - -export { - addIntent, - setIntent, - addChange, - setChangeDiff, - setChangeDocDiff, - setChangeComments, - setChangeFile, - setChangeIntentRef, -} from "./code.js"; - -export { - addWave, - setWaveMilestones, - addDiagram, - setDiagram, - addDiagramNode, - addDiagramEdge, - setReadmeEntry, -} from "./structure.js"; diff --git a/src/planner/plan/mutate/milestones.ts b/src/planner/plan/mutate/milestones.ts deleted file mode 100644 index fbb4e86..0000000 --- a/src/planner/plan/mutate/milestones.ts +++ /dev/null @@ -1,91 +0,0 @@ -// Milestone mutations: add, and per-field setters. -// Pure functions -- input plan in, new plan out. No side effects. - -import type { Plan, Milestone } from "../types.js"; -import { nextMilestoneId } from "../types.js"; - -export function addMilestone( - p: Plan, - data: { - name: string; - files?: string[]; - flags?: string[]; - requirements?: string[]; - acceptance_criteria?: string[]; - tests?: string[]; - }, -): { plan: Plan; id: string } { - const id = nextMilestoneId(p); - const milestone: Milestone = { - id, - number: p.milestones.length + 1, - name: data.name, - files: data.files ?? [], - flags: data.flags ?? [], - requirements: data.requirements ?? [], - acceptance_criteria: data.acceptance_criteria ?? [], - tests: data.tests ?? [], - code_intents: [], - code_changes: [], - documentation: { - module_comment: null, - docstrings: [], - function_blocks: [], - inline_comments: [], - }, - is_documentation_only: false, - delegated_to: null, - }; - return { - plan: { - ...p, - milestones: [...p.milestones, milestone], - }, - id, - }; -} - -function updateMilestone( - p: Plan, - id: string, - fn: (m: Milestone) => Milestone, -): Plan { - const idx = p.milestones.findIndex((m) => m.id === id); - if (idx === -1) throw new Error(`milestone ${id} not found`); - - const updated = [...p.milestones]; - updated[idx] = fn(p.milestones[idx]); - return { ...p, milestones: updated }; -} - -export function setMilestoneName(p: Plan, id: string, name: string): Plan { - return updateMilestone(p, id, (m) => ({ ...m, name })); -} - -export function setMilestoneFiles(p: Plan, id: string, files: string[]): Plan { - return updateMilestone(p, id, (m) => ({ ...m, files })); -} - -export function setMilestoneFlags(p: Plan, id: string, flags: string[]): Plan { - return updateMilestone(p, id, (m) => ({ ...m, flags })); -} - -export function setMilestoneRequirements( - p: Plan, - id: string, - requirements: string[], -): Plan { - return updateMilestone(p, id, (m) => ({ ...m, requirements })); -} - -export function setMilestoneAcceptanceCriteria( - p: Plan, - id: string, - criteria: string[], -): Plan { - return updateMilestone(p, id, (m) => ({ ...m, acceptance_criteria: criteria })); -} - -export function setMilestoneTests(p: Plan, id: string, tests: string[]): Plan { - return updateMilestone(p, id, (m) => ({ ...m, tests })); -} diff --git a/src/planner/plan/mutate/structure.ts b/src/planner/plan/mutate/structure.ts deleted file mode 100644 index f5679b1..0000000 --- a/src/planner/plan/mutate/structure.ts +++ /dev/null @@ -1,164 +0,0 @@ -// Structural plan mutations: waves, diagrams, readme entries. -// Pure functions -- input plan in, new plan out. No side effects. - -import type { - Plan, - Wave, - DiagramGraph, - DiagramNode, - DiagramEdge, - ReadmeEntry, -} from "../types.js"; -import { nextWaveId, nextDiagramId } from "../types.js"; - -// -- Wave -- - -export function addWave( - p: Plan, - data: { milestones: string[] }, -): { plan: Plan; id: string } { - const id = nextWaveId(p); - const wave: Wave = { - id, - milestones: data.milestones, - }; - return { - plan: { - ...p, - waves: [...p.waves, wave], - }, - id, - }; -} - -export function setWaveMilestones( - p: Plan, - id: string, - milestones: string[], -): Plan { - const idx = p.waves.findIndex((w) => w.id === id); - if (idx === -1) throw new Error(`wave ${id} not found`); - - const updated = [...p.waves]; - updated[idx] = { ...p.waves[idx], milestones }; - - return { ...p, waves: updated }; -} - -// -- Diagram -- - -export function addDiagram( - p: Plan, - data: { - type: "architecture" | "state" | "sequence" | "dataflow"; - scope: string; - title: string; - }, -): { plan: Plan; id: string } { - const id = nextDiagramId(p); - const diagram: DiagramGraph = { - id, - type: data.type, - scope: data.scope, - title: data.title, - nodes: [], - edges: [], - ascii_render: null, - }; - return { - plan: { - ...p, - diagram_graphs: [...p.diagram_graphs, diagram], - }, - id, - }; -} - -export function setDiagram( - p: Plan, - id: string, - data: { title?: string; scope?: string; ascii_render?: string }, -): Plan { - const idx = p.diagram_graphs.findIndex((d) => d.id === id); - if (idx === -1) throw new Error(`diagram ${id} not found`); - - const d = p.diagram_graphs[idx]; - const updated: DiagramGraph = { - ...d, - title: data.title ?? d.title, - scope: data.scope ?? d.scope, - ascii_render: data.ascii_render ?? d.ascii_render, - }; - - const diagrams = [...p.diagram_graphs]; - diagrams[idx] = updated; - - return { ...p, diagram_graphs: diagrams }; -} - -export function addDiagramNode( - p: Plan, - diagramId: string, - data: { id: string; label: string; type?: string }, -): Plan { - const idx = p.diagram_graphs.findIndex((d) => d.id === diagramId); - if (idx === -1) throw new Error(`diagram ${diagramId} not found`); - - const d = p.diagram_graphs[idx]; - const node: DiagramNode = { - id: data.id, - label: data.label, - type: data.type ?? null, - }; - - const diagrams = [...p.diagram_graphs]; - diagrams[idx] = { - ...d, - nodes: [...d.nodes, node], - }; - - return { ...p, diagram_graphs: diagrams }; -} - -export function addDiagramEdge( - p: Plan, - diagramId: string, - data: { source: string; target: string; label: string; protocol?: string }, -): Plan { - const idx = p.diagram_graphs.findIndex((d) => d.id === diagramId); - if (idx === -1) throw new Error(`diagram ${diagramId} not found`); - - const d = p.diagram_graphs[idx]; - const edge: DiagramEdge = { - source: data.source, - target: data.target, - label: data.label, - protocol: data.protocol ?? null, - }; - - const diagrams = [...p.diagram_graphs]; - diagrams[idx] = { - ...d, - edges: [...d.edges, edge], - }; - - return { ...p, diagram_graphs: diagrams }; -} - -// -- ReadmeEntry -- - -export function setReadmeEntry(p: Plan, path: string, content: string): Plan { - const idx = p.readme_entries.findIndex((r) => r.path === path); - const entry: ReadmeEntry = { path, content }; - - if (idx === -1) { - return { - ...p, - readme_entries: [...p.readme_entries, entry], - }; - } - - const entries = [...p.readme_entries]; - entries[idx] = entry; - return { ...p, readme_entries: entries }; -} diff --git a/src/planner/plan/mutate/top-level.ts b/src/planner/plan/mutate/top-level.ts deleted file mode 100644 index 2392525..0000000 --- a/src/planner/plan/mutate/top-level.ts +++ /dev/null @@ -1,37 +0,0 @@ -// Top-level plan field mutations: overview, constraints, invisible knowledge. -// Pure functions -- input plan in, new plan out. No side effects. - -import type { Plan, Overview, InvisibleKnowledge } from "../types.js"; - -export function setOverview( - p: Plan, - data: { problem?: string; approach?: string }, -): Plan { - const overview: Overview = { - problem: data.problem ?? p.overview.problem, - approach: data.approach ?? p.overview.approach, - }; - return { ...p, overview }; -} - -export function setConstraints(p: Plan, constraints: string[]): Plan { - return { - ...p, - planning_context: { - ...p.planning_context, - constraints, - }, - }; -} - -export function setInvisibleKnowledge( - p: Plan, - data: { system?: string; invariants?: string[]; tradeoffs?: string[] }, -): Plan { - const ik: InvisibleKnowledge = { - system: data.system ?? p.invisible_knowledge.system, - invariants: data.invariants ?? p.invisible_knowledge.invariants, - tradeoffs: data.tradeoffs ?? p.invisible_knowledge.tradeoffs, - }; - return { ...p, invisible_knowledge: ik }; -} diff --git a/src/planner/plan/render.ts b/src/planner/plan/render.ts deleted file mode 100644 index 4974bdd..0000000 --- a/src/planner/plan/render.ts +++ /dev/null @@ -1,155 +0,0 @@ -// Mechanical renderer: plan.json -> plan.md. -// The plan JSON is the source of truth; this file provides a deterministic -// markdown projection for human/manual review between planning and execution. - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { Plan, Milestone, DiagramGraph } from "./types.js"; -import { loadPlan } from "./serialize.js"; - -function escCell(text: string): string { - return text.replace(/\|/g, "\\|").replace(/\n/g, " ").trim(); -} - -function pushList(lines: string[], title: string, values: string[]): void { - if (values.length === 0) return; - lines.push(title, ""); - for (const value of values) lines.push(`- ${value}`); - lines.push(""); -} - -function pushScopedDiagrams(lines: string[], diagrams: DiagramGraph[], scope: string): void { - const scoped = diagrams.filter((d) => d.scope === scope); - for (const diagram of scoped) { - lines.push(`### ${diagram.title}`, ""); - if (diagram.ascii_render && diagram.ascii_render.trim().length > 0) { - lines.push("```", diagram.ascii_render, "```", ""); - } else { - lines.push(`[Diagram pending rendering: ${diagram.id}]`, ""); - } - } -} - -function pushMilestone(lines: string[], milestone: Milestone, diagrams: DiagramGraph[]): void { - lines.push(`### ${milestone.id}: ${milestone.name}`, ""); - - pushScopedDiagrams(lines, diagrams, `milestone:${milestone.id}`); - - if (milestone.files.length > 0) { - lines.push(`**Files**: ${milestone.files.join(", ")}`, ""); - } - - pushList(lines, "**Requirements**", milestone.requirements); - pushList(lines, "**Acceptance Criteria**", milestone.acceptance_criteria); - pushList(lines, "**Tests**", milestone.tests); - - if (milestone.code_intents.length > 0) { - lines.push("#### Code Intents", ""); - for (const intent of milestone.code_intents) { - const fn = intent.function ? `::${intent.function}` : ""; - const refs = intent.decision_refs.length > 0 ? ` (refs: ${intent.decision_refs.join(", ")})` : ""; - lines.push(`- **${intent.id}** \`${intent.file}${fn}\`: ${intent.behavior}${refs}`); - } - lines.push(""); - } - - if (milestone.code_changes.length > 0) { - lines.push("#### Code Changes", ""); - for (const change of milestone.code_changes) { - const intentRef = change.intent_ref ? ` - implements ${change.intent_ref}` : ""; - lines.push(`**${change.id}** (${change.file})${intentRef}`, ""); - - if (change.diff.trim().length > 0) { - lines.push("**Code Diff**", "", "```diff", change.diff, "```", ""); - } - - if (change.doc_diff.trim().length > 0) { - lines.push("**Documentation Diff**", "", "```diff", change.doc_diff, "```", ""); - } - - if (change.comments.trim().length > 0) { - lines.push(`> ${change.comments}`, ""); - } - } - } -} - -export function renderPlanMarkdown(plan: Plan): string { - const lines: string[] = ["# Plan", "", "## Overview", "", plan.overview.problem || "(empty)", ""]; - - if (plan.overview.approach.trim().length > 0) { - lines.push(`**Approach**: ${plan.overview.approach}`, ""); - } - - pushScopedDiagrams(lines, plan.diagram_graphs, "overview"); - - if (plan.planning_context.decision_log.length > 0) { - lines.push("## Planning Context", "", "### Decision Log", "", "| ID | Decision | Reasoning Chain |", "|---|---|---|"); - for (const d of plan.planning_context.decision_log) { - lines.push(`| ${d.id} | ${escCell(d.decision)} | ${escCell(d.reasoning_chain)} |`); - } - lines.push(""); - } - - if (plan.planning_context.rejected_alternatives.length > 0) { - lines.push("### Rejected Alternatives", "", "| Alternative | Why Rejected |", "|---|---|"); - for (const r of plan.planning_context.rejected_alternatives) { - lines.push(`| ${escCell(r.alternative)} | ${escCell(r.rejection_reason)} (ref: ${r.decision_ref}) |`); - } - lines.push(""); - } - - pushList(lines, "### Constraints", plan.planning_context.constraints); - - if (plan.planning_context.known_risks.length > 0) { - lines.push("### Known Risks", ""); - for (const risk of plan.planning_context.known_risks) { - lines.push(`- **${risk.risk}**: ${risk.mitigation}`); - } - lines.push(""); - } - - const ik = plan.invisible_knowledge; - if (ik.system.trim().length > 0 || ik.invariants.length > 0 || ik.tradeoffs.length > 0) { - lines.push("## Invisible Knowledge", ""); - if (ik.system.trim().length > 0) { - lines.push("### System", "", ik.system, ""); - } - pushList(lines, "### Invariants", ik.invariants); - pushList(lines, "### Tradeoffs", ik.tradeoffs); - pushScopedDiagrams(lines, plan.diagram_graphs, "invisible_knowledge"); - } - - lines.push("## Milestones", ""); - for (const milestone of plan.milestones) { - pushMilestone(lines, milestone, plan.diagram_graphs); - } - - if (plan.readme_entries.length > 0) { - lines.push("## README Entries", ""); - for (const entry of plan.readme_entries) { - lines.push(`### ${entry.path}`, "", entry.content, ""); - } - } - - if (plan.waves.length > 0) { - lines.push("## Execution Waves", ""); - for (const wave of plan.waves) { - lines.push(`- ${wave.id}: ${wave.milestones.join(", ")}`); - } - lines.push(""); - } - - return `${lines.join("\n").trimEnd()}\n`; -} - -export async function renderPlanMarkdownToFile(planDir: string): Promise { - const plan = await loadPlan(planDir); - const markdown = renderPlanMarkdown(plan); - const outputPath = path.join(planDir, "plan.md"); - const tmpPath = path.join(planDir, ".plan.md.tmp"); - await fs.writeFile(tmpPath, markdown, "utf8"); - await fs.rename(tmpPath, outputPath); - return outputPath; -} diff --git a/src/planner/plan/serialize.ts b/src/planner/plan/serialize.ts deleted file mode 100644 index 9256709..0000000 --- a/src/planner/plan/serialize.ts +++ /dev/null @@ -1,45 +0,0 @@ -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { Plan } from "./types.js"; -import { createEmptyPlan } from "./types.js"; - -export function serializePlan(p: Plan): string { - return `${JSON.stringify(p, null, 2)}\n`; -} - -export async function writePlan(p: Plan, filePath: string): Promise { - const dir = path.dirname(filePath); - try { - await fs.access(dir); - } catch { - throw new Error(`Plan directory does not exist: ${dir}`); - } - - const content = serializePlan(p); - await fs.writeFile(filePath, content, "utf8"); -} - -// Atomic write: tmp file + rename. Prevents corrupted plan.json if -// process crashes mid-write. -export async function savePlan(p: Plan, dir: string): Promise { - const planPath = path.join(dir, "plan.json"); - const tmpPath = path.join(dir, ".plan.json.tmp"); - const content = serializePlan(p); - await fs.writeFile(tmpPath, content, "utf8"); - await fs.rename(tmpPath, planPath); -} - -export async function loadPlan(dir: string): Promise { - const planPath = path.join(dir, "plan.json"); - try { - const content = await fs.readFile(planPath, "utf8"); - return JSON.parse(content) as Plan; - } catch (err: unknown) { - if ((err as NodeJS.ErrnoException).code === "ENOENT") { - const planId = path.basename(dir); - return createEmptyPlan(planId); - } - throw err; - } -} diff --git a/src/planner/plan/types.ts b/src/planner/plan/types.ts deleted file mode 100644 index 4d21ca9..0000000 --- a/src/planner/plan/types.ts +++ /dev/null @@ -1,206 +0,0 @@ -export interface Decision { - id: string; - decision: string; - reasoning_chain: string; - source: string | null; -} - -export interface RejectedAlternative { - id: string; - alternative: string; - rejection_reason: string; - decision_ref: string; -} - -export interface Risk { - id: string; - risk: string; - mitigation: string; - anchor?: string | null; - decision_ref?: string | null; -} - -export interface PlanningContext { - decision_log: Decision[]; - rejected_alternatives: RejectedAlternative[]; - constraints: string[]; - known_risks: Risk[]; -} - -export interface InvisibleKnowledge { - system: string; - invariants: string[]; - tradeoffs: string[]; -} - -export interface Overview { - problem: string; - approach: string; -} - -export interface CodeIntent { - id: string; - file: string; - function?: string | null; - behavior: string; - decision_refs: string[]; -} - -export interface CodeChange { - id: string; - intent_ref: string | null; - file: string; - diff: string; - doc_diff: string; - comments: string; -} - -export interface Docstring { - function: string; - docstring: string; -} - -export interface FunctionBlock { - function: string; - comment: string; - decision_ref: string | null; - source: string | null; -} - -export interface InlineComment { - location: string; - comment: string; - decision_ref: string | null; - source: string | null; -} - -// DEPRECATED per reference schema. Kept for backwards compatibility with -// Python-based planner plans. New plans use CodeChange.doc_diff. -export interface Documentation { - module_comment: string | null; - docstrings: Docstring[]; - function_blocks: FunctionBlock[]; - inline_comments: InlineComment[]; -} - -// DEPRECATED per reference schema. Kept for backwards compatibility with -// Python-based planner plans. New plans use CodeChange.doc_diff. -export interface ReadmeEntry { - path: string; - content: string; -} - -export interface DiagramNode { - id: string; - label: string; - type: string | null; -} - -export interface DiagramEdge { - source: string; - target: string; - label: string; - protocol: string | null; -} - -export interface DiagramGraph { - id: string; - type: "architecture" | "state" | "sequence" | "dataflow"; - scope: string; - title: string; - nodes: DiagramNode[]; - edges: DiagramEdge[]; - ascii_render: string | null; -} - -export interface Milestone { - id: string; - number: number; - name: string; - files: string[]; - flags: string[]; - requirements: string[]; - acceptance_criteria: string[]; - tests: string[]; - code_intents: CodeIntent[]; - code_changes: CodeChange[]; - documentation: Documentation; - is_documentation_only: boolean; - delegated_to: string | null; -} - -export interface Wave { - id: string; - milestones: string[]; -} - -export interface Plan { - plan_id: string; - created_at: string; - frozen_at: string | null; - overview: Overview; - planning_context: PlanningContext; - invisible_knowledge: InvisibleKnowledge; - milestones: Milestone[]; - waves: Wave[]; - diagram_graphs: DiagramGraph[]; - readme_entries: ReadmeEntry[]; -} - -export function createEmptyPlan(planId: string): Plan { - return { - plan_id: planId, - created_at: new Date().toISOString(), - frozen_at: null, - overview: { problem: "", approach: "" }, - planning_context: { - decision_log: [], - rejected_alternatives: [], - constraints: [], - known_risks: [], - }, - invisible_knowledge: { system: "", invariants: [], tradeoffs: [] }, - milestones: [], - waves: [], - diagram_graphs: [], - readme_entries: [], - }; -} - -function pad3(n: number): string { - return String(n).padStart(3, "0"); -} - -export function nextDecisionId(p: Plan): string { - return `DL-${pad3(p.planning_context.decision_log.length + 1)}`; -} - -export function nextMilestoneId(p: Plan): string { - return `M-${pad3(p.milestones.length + 1)}`; -} - -export function nextIntentId(m: Milestone): string { - const num = m.code_intents.length + 1; - return `CI-${m.id}-${pad3(num)}`; -} - -export function nextRiskId(p: Plan): string { - return `R-${pad3(p.planning_context.known_risks.length + 1)}`; -} - -export function nextRejectedAltId(p: Plan): string { - return `RA-${pad3(p.planning_context.rejected_alternatives.length + 1)}`; -} - -export function nextWaveId(p: Plan): string { - return `W-${pad3(p.waves.length + 1)}`; -} - -export function nextDiagramId(p: Plan): string { - return `DIAG-${pad3(p.diagram_graphs.length + 1)}`; -} - -export function nextChangeId(m: Milestone): string { - const num = m.code_changes.length + 1; - return `CC-${m.id}-${pad3(num)}`; -} diff --git a/src/planner/plan/validate.ts b/src/planner/plan/validate.ts deleted file mode 100644 index bfb4f52..0000000 --- a/src/planner/plan/validate.ts +++ /dev/null @@ -1,249 +0,0 @@ -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { Logger } from "../../utils/logger.js"; -import type { Plan } from "./types.js"; - -export interface ValidationResult { - ok: boolean; - errors: string[]; - warnings?: string[]; -} - -// -- Decision source provenance -- - -// Canonical source types for the type:ref format. -// "code" and "docs" carry a path ref; others stand alone. -const VALID_SOURCE_TYPES = [ - "code", "docs", "user:ask", "user:conversation", "inference", -] as const; - -export type DecisionSourceType = (typeof VALID_SOURCE_TYPES)[number]; - -const SOURCE_TYPE_SET: ReadonlySet = new Set(VALID_SOURCE_TYPES); - -// Parses "code:src/foo.ts" -> { type: "code", ref: "src/foo.ts" } -// Parses "inference" -> { type: "inference", ref: null } -// Returns null for unrecognized formats. -export function parseDecisionSource( - s: string, -): { type: DecisionSourceType; ref: string | null } | null { - const colon = s.indexOf(":"); - if (colon === -1) { - return SOURCE_TYPE_SET.has(s) ? { type: s as DecisionSourceType, ref: null } : null; - } - const prefix = s.substring(0, colon); - const rest = s.substring(colon + 1); - // "user:ask" and "user:conversation" are complete types, not type:ref pairs - const full = `${prefix}:${rest}`; - if (SOURCE_TYPE_SET.has(full)) return { type: full as DecisionSourceType, ref: null }; - // "code:" and "docs:" are type:ref pairs - if (SOURCE_TYPE_SET.has(prefix)) return { type: prefix as DecisionSourceType, ref: rest }; - return null; -} - -// Produces warnings (not errors) for decisions with missing or invalid sources. -// Soft validation: legacy plans have source: null; hard failures cause death loops. -export function validateDecisionSources(p: Plan): string[] { - const warnings: string[] = []; - for (const d of p.planning_context.decision_log) { - if (!d.source) { - warnings.push(`${d.id}: missing source -- expected code:, docs:, user:ask, user:conversation, or inference`); - continue; - } - const parsed = parseDecisionSource(d.source); - if (!parsed) { - warnings.push(`${d.id}: unrecognized source "${d.source}" -- expected code:, docs:, user:ask, user:conversation, or inference`); - } - } - return warnings; -} - -export function validatePlanDesign(p: Plan): ValidationResult { - const errors: string[] = []; - - if (p.overview.problem.trim().length === 0) { - errors.push("overview.problem must not be empty"); - } - - if (p.milestones.length === 0) { - errors.push("plan must have at least one milestone"); - } - - for (const m of p.milestones) { - if (m.code_intents.length === 0) { - errors.push(`milestone ${m.id} must have at least one code_intent`); - } - } - - const warnings = validateDecisionSources(p); - return { ok: errors.length === 0, errors, warnings }; -} - -export function validateRefs(p: Plan): ValidationResult { - const errors: string[] = []; - const decisionIds = new Set(p.planning_context.decision_log.map((d) => d.id)); - const milestoneIds = new Set(p.milestones.map((m) => m.id)); - - for (const m of p.milestones) { - const intentIds = new Set(m.code_intents.map((ci) => ci.id)); - - for (const ci of m.code_intents) { - for (const ref of ci.decision_refs) { - if (!decisionIds.has(ref)) { - errors.push(`${ci.id}.decision_refs '${ref}' not in decisions`); - } - } - } - - for (const cc of m.code_changes) { - if (cc.intent_ref && !intentIds.has(cc.intent_ref)) { - errors.push( - `${cc.id}.intent_ref '${cc.intent_ref}' not in milestone ${m.id} intents`, - ); - } - } - } - - for (const ra of p.planning_context.rejected_alternatives) { - if (!decisionIds.has(ra.decision_ref)) { - errors.push( - `rejected_alternative ${ra.id}.decision_ref '${ra.decision_ref}' not in decisions`, - ); - } - } - - for (const risk of p.planning_context.known_risks) { - if (risk.decision_ref && !decisionIds.has(risk.decision_ref)) { - errors.push(`risk ${risk.id}.decision_ref '${risk.decision_ref}' not in decisions`); - } - } - - // Milestone references in DiagramGraph.scope are validated against - // plan.milestones for referential integrity. Prevents orphaned diagrams - // when milestones are merged or deleted. - for (const diag of p.diagram_graphs) { - if (diag.scope.startsWith("milestone:")) { - const milestoneId = diag.scope.substring("milestone:".length); - if (!milestoneIds.has(milestoneId)) { - errors.push( - `diagram ${diag.id}.scope '${diag.scope}' references unknown milestone`, - ); - } - } - - const nodeIds = new Set(diag.nodes.map((n) => n.id)); - for (const edge of diag.edges) { - if (!nodeIds.has(edge.source)) { - errors.push(`diagram ${diag.id} edge source '${edge.source}' not in nodes`); - } - if (!nodeIds.has(edge.target)) { - errors.push(`diagram ${diag.id} edge target '${edge.target}' not in nodes`); - } - } - } - - return { ok: errors.length === 0, errors }; -} - -export function validateDiagramScope(scope: string): ValidationResult { - const errors: string[] = []; - if ( - scope !== "overview" && - scope !== "invisible_knowledge" && - !scope.startsWith("milestone:") - ) { - errors.push( - `diagram scope must be 'overview', 'invisible_knowledge', or 'milestone:M-XXX', got '${scope}'`, - ); - } - return { ok: errors.length === 0, errors }; -} - -export function validatePlanCode(p: Plan): ValidationResult { - const errors: string[] = []; - for (const m of p.milestones) { - const changeIntents = new Set( - m.code_changes.map((cc) => cc.intent_ref).filter((r) => r !== null), - ); - for (const ci of m.code_intents) { - if (!changeIntents.has(ci.id)) { - errors.push(`milestone ${m.id} intent ${ci.id} has no corresponding code_change`); - } - } - } - return { ok: errors.length === 0, errors }; -} - -export function validatePlanDocs(p: Plan): ValidationResult { - const errors: string[] = []; - for (const m of p.milestones) { - for (const cc of m.code_changes) { - if (cc.diff.trim().length > 0 && cc.doc_diff.trim().length === 0) { - errors.push(`milestone ${m.id} change ${cc.id} has diff but no doc_diff`); - } - } - } - return { ok: errors.length === 0, errors }; -} - -export type PlanValidationPhase = "plan-design" | "plan-code" | "plan-docs"; - -// Reads plan.json from planDir and runs phase-appropriate validation. -// All phases require plan-design + reference integrity checks. -// plan-code additionally requires intent->change completeness. -// plan-docs additionally requires doc completeness. -export async function loadAndValidatePlanForPhase( - planDir: string, - phase: PlanValidationPhase, - log: Logger, -): Promise<{ ok: boolean; errors?: string[] }> { - const planPath = path.join(planDir, "plan.json"); - let plan: Plan; - try { - const raw = await fs.readFile(planPath, "utf8"); - plan = JSON.parse(raw) as Plan; - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - log("Failed to read plan.json for validation", { error: message, phase }); - return { ok: false, errors: [`Failed to read plan.json: ${message}`] }; - } - - const designValidation = validatePlanDesign(plan); - if (!designValidation.ok) { - log("Plan design validation failed", { errors: designValidation.errors, phase }); - return { ok: false, errors: designValidation.errors }; - } - - const refValidation = validateRefs(plan); - if (!refValidation.ok) { - log("Plan reference validation failed", { errors: refValidation.errors, phase }); - return { ok: false, errors: refValidation.errors }; - } - - if (phase === "plan-code" || phase === "plan-docs") { - const codeValidation = validatePlanCode(plan); - if (!codeValidation.ok) { - log("Plan code validation failed", { errors: codeValidation.errors, phase }); - return { ok: false, errors: codeValidation.errors }; - } - } - - if (phase === "plan-docs") { - const docsValidation = validatePlanDocs(plan); - if (!docsValidation.ok) { - log("Plan docs validation failed", { errors: docsValidation.errors, phase }); - return { ok: false, errors: docsValidation.errors }; - } - } - - log("Plan validation passed", { path: planPath, phase }); - return { ok: true }; -} - -export async function loadAndValidatePlan( - planDir: string, - log: Logger, -): Promise<{ ok: boolean; errors?: string[] }> { - return loadAndValidatePlanForPhase(planDir, "plan-design", log); -} diff --git a/src/planner/qr/mutate.ts b/src/planner/qr/mutate.ts deleted file mode 100644 index e0644ff..0000000 --- a/src/planner/qr/mutate.ts +++ /dev/null @@ -1,88 +0,0 @@ -import type { QRFile, QRItem, QRSeverity, QRItemStatus } from "./types.js"; - -function pad3(n: number): string { - return String(n).padStart(3, "0"); -} - -function nextQRId(qr: QRFile): string { - return `QR-${qr.phase}-${pad3(qr.items.length + 1)}`; -} - -export function addQRItem( - qr: QRFile, - data: { scope: string; check: string; severity?: QRSeverity }, -): { qr: QRFile; id: string } { - const id = nextQRId(qr); - const item: QRItem = { - id, - scope: data.scope, - check: data.check, - status: "TODO", - finding: null, - parent_id: null, - group_id: null, - severity: data.severity ?? "MUST", - }; - return { - qr: { - ...qr, - items: [...qr.items, item], - }, - id, - }; -} - -// PASS is terminal: cannot transition from PASS to FAIL. -// FAIL requires finding (explains what failed). -// PASS forbids finding. -export function setQRItem( - qr: QRFile, - id: string, - data: { - status?: QRItemStatus; - finding?: string; - check?: string; - severity?: QRSeverity; - }, -): QRFile { - const idx = qr.items.findIndex((i) => i.id === id); - if (idx === -1) throw new Error(`qr_item ${id} not found`); - - const item = qr.items[idx]; - - if (item.status === "PASS" && data.status === "FAIL") { - throw new Error(`cannot transition ${id} from PASS to FAIL (PASS is terminal)`); - } - - const status = data.status ?? item.status; - const finding = data.finding ?? item.finding; - - if (status === "FAIL" && !finding) { - throw new Error(`FAIL status requires finding for ${id}`); - } - - if (status === "PASS" && finding) { - throw new Error(`PASS status forbids finding for ${id}`); - } - - const updated: QRItem = { - ...item, - status, - finding, - check: data.check ?? item.check, - severity: data.severity ?? item.severity, - }; - - const items = [...qr.items]; - items[idx] = updated; - - return { ...qr, items }; -} - -export function assignGroup(qr: QRFile, ids: string[], groupId: string): QRFile { - const idSet = new Set(ids); - const items = qr.items.map((item) => - idSet.has(item.id) ? { ...item, group_id: groupId } : item, - ); - return { ...qr, items }; -} diff --git a/src/planner/qr/severity.ts b/src/planner/qr/severity.ts deleted file mode 100644 index 6e40c6f..0000000 --- a/src/planner/qr/severity.ts +++ /dev/null @@ -1,41 +0,0 @@ -// Severity escalation policy for QR fix iterations. -// -// Progressive de-escalation narrows what blocks as iterations increase. -// COULD items (style, cosmetic) do not block indefinitely: after 2 fix -// attempts, only structural issues (MUST, SHOULD) block; after 3, only -// knowledge-loss risks (MUST) block. -// -// A hard cutoff ("after N attempts, ignore all failures") would let MUST -// failures through. De-escalation by tier preserves the invariant that -// MUST items always block, while preventing COULD style nits from causing -// indefinite retries. - -import type { QRItem, QRSeverity } from "./types.js"; - -export const MAX_FIX_ITERATIONS = 5; - -// Returns the set of severities that block the plan at the given iteration. -// Iterations 1-2: all severities block. Iteration 3: MUST+SHOULD. 4+: MUST only. -export function blockingSeverities(iteration: number): ReadonlySet { - if (iteration <= 2) return new Set(["MUST", "SHOULD", "COULD"]); - if (iteration === 3) return new Set(["MUST", "SHOULD"]); - return new Set(["MUST"]); -} - -// Returns the subset of items that are FAIL and have a blocking severity -// at the given iteration. -export function blockingFailures( - items: ReadonlyArray, - iteration: number, -): QRItem[] { - const blocking = blockingSeverities(iteration); - return items.filter((i) => i.status === "FAIL" && blocking.has(i.severity)); -} - -// Returns true when no blocking failures remain at this iteration. -export function qrPassesAtIteration( - items: ReadonlyArray, - iteration: number, -): boolean { - return blockingFailures(items, iteration).length === 0; -} diff --git a/src/planner/qr/types.ts b/src/planner/qr/types.ts deleted file mode 100644 index 89ab627..0000000 --- a/src/planner/qr/types.ts +++ /dev/null @@ -1,19 +0,0 @@ -export type QRSeverity = "MUST" | "SHOULD" | "COULD"; -export type QRItemStatus = "TODO" | "PASS" | "FAIL"; - -export interface QRItem { - id: string; - scope: string; - check: string; - status: QRItemStatus; - finding: string | null; - parent_id: string | null; - group_id: string | null; - severity: QRSeverity; -} - -export interface QRFile { - phase: string; - iteration: number; - items: QRItem[]; -} diff --git a/src/planner/session.ts b/src/planner/session.ts deleted file mode 100644 index ecd79a4..0000000 --- a/src/planner/session.ts +++ /dev/null @@ -1,985 +0,0 @@ -// Parent session: orchestrates the koan planning workflow. -// Flow: export conversation -> plan-design(+QR) -> plan-code(+QR) -> plan-docs(+QR) -// -> mechanical plan.json->plan.md rendering for manual review. - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { AgentToolResult, ExtensionAPI, ExtensionCommandContext, ExtensionContext, ExtensionUIContext } from "@mariozechner/pi-coding-agent"; - -import { exportConversation } from "./conversation.js"; -import { createInitialState, initializePlanState, type WorkflowState } from "./state.js"; -import { createPlanInfo } from "../utils/plan.js"; -import { - spawnArchitect, - spawnArchitectFix, - spawnDeveloper, - spawnDeveloperFix, - spawnTechnicalWriter, - spawnTechnicalWriterFix, - spawnQRDecomposer, - spawnReviewer, - type SpawnQRDecomposerOptions, - type SpawnReviewerOptions, - type SubagentResult, -} from "./subagent.js"; -import { createLogger, setLogDir, type Logger } from "../utils/logger.js"; -import { createSubagentDir } from "../utils/progress.js"; -import { readProjection, readRecentLogs, type Projection, type LogLine } from "./lib/audit.js"; -import type { WorkflowDispatch, PlanRef } from "./lib/dispatch.js"; -import { pool } from "./lib/pool.js"; -import type { QRFile } from "./qr/types.js"; -import { MAX_FIX_ITERATIONS, qrPassesAtIteration } from "./qr/severity.js"; -import { WidgetController, type WidgetUpdate } from "./ui/widget.js"; -import { renderPlanMarkdownToFile } from "./plan/render.js"; -import { - mapSpawnContextToPhaseModelKey, - resolvePhaseModelOverride, - type SpawnContext, -} from "./model-resolver.js"; -import type { PhaseRow } from "./model-phase.js"; -import { - readIpcFile, - writeIpcFile, - createAskResponse, - createCancelledResponse, - type IpcFile, - type IpcResponse, -} from "./lib/ipc.js"; -import { askSingleQuestionWithInlineNote } from "./ui/ask/ask-inline-ui.js"; -import { askQuestionsWithTabs } from "./ui/ask/ask-tabs-ui.js"; -import type { AskQuestion } from "./ui/ask/ask-logic.js"; - -type WorkPhaseKey = "plan-design" | "plan-code" | "plan-docs"; - -interface Session { - plan(ctx: ExtensionContext): Promise>; - execute(_ctx: ExtensionCommandContext): Promise; - status(ctx: ExtensionCommandContext): Promise; -} - -interface QRBlockResult { - summary: string; - passed: boolean; -} - -interface PhaseRunConfig { - key: WorkPhaseKey; - label: string; - widgetIndex: number; - role: "architect" | "developer" | "technical-writer"; - spawnWork: (opts: SpawnWorkRunOptions) => Promise; - spawnFix: (opts: SpawnFixRunOptions) => Promise; -} - -interface SpawnWorkRunOptions { - planDir: string; - subagentDir: string; - cwd: string; - extensionPath: string; - log: Logger; - modelOverride?: string; -} - -interface SpawnFixRunOptions extends SpawnWorkRunOptions {} - -function qrFilePath(planDir: string, phase: WorkPhaseKey): string { - return path.join(planDir, `qr-${phase}.json`); -} - -function singleSubagentStart(role: string): WidgetUpdate { - return { - subagentRole: role, - subagentModel: null, - subagentParallelCount: 1, - subagentQueued: 0, - subagentActive: 1, - subagentDone: 0, - }; -} - -function singleSubagentFromProjection(p: Projection): WidgetUpdate { - const running = p.status === "running"; - return { - subagentRole: p.role, - subagentModel: p.model, - subagentParallelCount: 1, - subagentQueued: 0, - subagentActive: running ? 1 : 0, - subagentDone: running ? 0 : 1, - }; -} - -function phaseRunningState(phase: WorkPhaseKey): WorkflowState["phase"] { - if (phase === "plan-design") return "architect-running"; - if (phase === "plan-code") return "plan-code-running"; - return "plan-docs-running"; -} - -function phaseCompleteState(phase: WorkPhaseKey): WorkflowState["phase"] { - if (phase === "plan-design") return "plan-design-complete"; - if (phase === "plan-code") return "plan-code-complete"; - return "plan-docs-complete"; -} - -interface ModelResolutionDeps { - mapSpawnContextToPhaseModelKeyFn?: typeof mapSpawnContextToPhaseModelKey; - resolvePhaseModelOverrideFn?: typeof resolvePhaseModelOverride; -} - -interface QRSpawnResolutionDeps extends ModelResolutionDeps { - spawnQRDecomposerFn?: typeof spawnQRDecomposer; - spawnReviewerFn?: typeof spawnReviewer; -} - -export async function resolveSpawnModelOverride( - context: SpawnContext, - phaseRow: PhaseRow, - deps: ModelResolutionDeps = {}, -): Promise { - const mapFn = deps.mapSpawnContextToPhaseModelKeyFn ?? mapSpawnContextToPhaseModelKey; - const resolveFn = deps.resolvePhaseModelOverrideFn ?? resolvePhaseModelOverride; - const key = mapFn(context, phaseRow); - return await resolveFn(key); -} - -export async function spawnWorkWithResolvedModel( - phaseRow: PhaseRow, - spawnWorkFn: (opts: SpawnWorkRunOptions) => Promise, - opts: SpawnWorkRunOptions, - deps: ModelResolutionDeps = {}, -): Promise { - const modelOverride = await resolveSpawnModelOverride("work-debut", phaseRow, deps); - return await spawnWorkFn({ ...opts, modelOverride }); -} - -export async function spawnFixWithResolvedModel( - phaseRow: PhaseRow, - spawnFixFn: (opts: SpawnFixRunOptions) => Promise, - opts: SpawnFixRunOptions, - deps: ModelResolutionDeps = {}, -): Promise { - const modelOverride = await resolveSpawnModelOverride("fix", phaseRow, deps); - return await spawnFixFn({ ...opts, modelOverride }); -} - -export async function spawnQRDecomposerWithResolvedModel( - opts: SpawnQRDecomposerOptions, - deps: QRSpawnResolutionDeps = {}, -): Promise { - const modelOverride = await resolveSpawnModelOverride("qr-decompose", opts.phase as PhaseRow, deps); - const spawnFn = deps.spawnQRDecomposerFn ?? spawnQRDecomposer; - return await spawnFn({ ...opts, modelOverride }); -} - -export async function spawnReviewerWithResolvedModel( - opts: SpawnReviewerOptions, - deps: QRSpawnResolutionDeps = {}, -): Promise { - const modelOverride = await resolveSpawnModelOverride("qr-verify", opts.phase as PhaseRow, deps); - const spawnFn = deps.spawnReviewerFn ?? spawnReviewer; - return await spawnFn({ ...opts, modelOverride }); -} - -// Routes an IpcFile ask request to the appropriate UI component and returns -// an IpcResponse. On any exception from the UI layer, the caller's catch -// block writes a cancelled response so the subagent unblocks. -async function handleAskRequest( - ui: ExtensionUIContext, - ipc: IpcFile, -): Promise { - const { request } = ipc; - const { questions } = request.payload; - const questionsAsAsk = questions as AskQuestion[]; - - if (questions.length === 1 && !questions[0].multi) { - const selection = await askSingleQuestionWithInlineNote(ui, questionsAsAsk[0]); - if (selection.selectedOptions.length === 0 && !selection.customInput) { - return createCancelledResponse(request.id); - } - const answer: { id: string; selectedOptions: string[]; customInput?: string } = { - id: questions[0].id, - selectedOptions: selection.selectedOptions, - }; - if (selection.customInput !== undefined) { - answer.customInput = selection.customInput; - } - return createAskResponse(request.id, { answers: [answer] }); - } - - const tabResult = await askQuestionsWithTabs(ui, questionsAsAsk); - if (tabResult.cancelled) { - return createCancelledResponse(request.id); - } - - const answers = questions.map((q, i) => { - const sel = tabResult.selections[i] ?? { selectedOptions: [] }; - const answer: { id: string; selectedOptions: string[]; customInput?: string } = { - id: q.id, - selectedOptions: sel.selectedOptions, - }; - if (sel.customInput !== undefined) { - answer.customInput = sel.customInput; - } - return answer; - }); - - return createAskResponse(request.id, { answers }); -} - -// Encapsulates the poll-with-request-detection pattern used by both -// the work poll loop and the fix poll loop. Returns a setInterval ID. -function pollWithIpcDetection( - subagentDir: string, - widget: WidgetController | null, - ui: ExtensionUIContext | null, - stepPrefix: string, - updateFromProjection: (p: Projection, logs: LogLine[]) => void, -): ReturnType { - let pendingRequestId: string | null = null; - - return setInterval(async () => { - const [projection, logs] = await Promise.all([ - readProjection(subagentDir), - readRecentLogs(subagentDir), - ]); - if (projection) { - updateFromProjection(projection, logs); - } - - // IPC request detection — skip if already handling a request or no UI - if (pendingRequestId || !ui) return; - - const ipc = await readIpcFile(subagentDir); - if (!ipc || !ipc.request || ipc.response !== null) return; - - pendingRequestId = ipc.request.id; - try { - widget?.update({ - step: `${stepPrefix}: waiting for user input...`, - activity: ipc.request.payload.questions[0]?.question ?? "", - }); - - const response = await handleAskRequest(ui, ipc); - const updated: IpcFile = { request: ipc.request, response }; - await writeIpcFile(subagentDir, updated); - } catch { - // On error, write cancelled response so subagent unblocks. - // The inner try-catch guards against I/O failures during error - // recovery — an unguarded throw here would propagate as an - // unhandled async rejection in the setInterval callback, - // crashing the parent process (Node.js ≥15 default behavior). - try { - const cancelled = createCancelledResponse(ipc.request.id); - await writeIpcFile(subagentDir, { request: ipc.request, response: cancelled }); - } catch { - // I/O failed during error recovery; subagent remains blocked - // until parent terminates. No further action possible. - } - } finally { - pendingRequestId = null; - } - }, 2000); -} - -export function createSession(pi: ExtensionAPI, dispatch: WorkflowDispatch, planRef: PlanRef): Session { - const state: WorkflowState = createInitialState(); - const log = createLogger("Session"); - let widget: WidgetController | null = null; - - return { - async plan(ctx: ExtensionContext): Promise> { - const planInfo = await createPlanInfo("", ctx.cwd); - initializePlanState(state, planInfo, ""); - - // Wire plan directory for subagent dispatch and logging. - planRef.dir = planInfo.directory; - setLogDir(planInfo.directory); - - log("Plan tool invoked", { - cwd: ctx.cwd, - planId: planInfo.id, - planDirectory: planInfo.directory, - }); - - if (widget) { - widget.destroy(); - widget = null; - } - - if (ctx.hasUI) { - widget = new WidgetController(ctx.ui, planInfo.id); - } - - // Export conversation to plan directory. - // Agents that need session context can Read this file. - await exportConversation(ctx.sessionManager, planInfo.directory); - log("Conversation exported", { planDir: planInfo.directory }); - - let outcome: "PASS" | "FAIL" = "FAIL"; - try { - const planDir = planInfo.directory; - const extensionPath = path.resolve(import.meta.dirname, "../../extensions/koan.ts"); - const ui = ctx.hasUI ? ctx.ui : null; - - // widgetIndex 0=design, 1=code, 2=docs - const phases: PhaseRunConfig[] = [ - { - key: "plan-design", - label: "Plan design", - widgetIndex: 0, - role: "architect", - spawnWork: (opts) => spawnArchitect(opts), - spawnFix: (opts) => spawnArchitectFix({ ...opts, fixPhase: "plan-design" }), - }, - { - key: "plan-code", - label: "Plan code", - widgetIndex: 1, - role: "developer", - spawnWork: (opts) => spawnDeveloper(opts), - spawnFix: (opts) => spawnDeveloperFix({ ...opts, fixPhase: "plan-code" }), - }, - { - key: "plan-docs", - label: "Plan docs", - widgetIndex: 2, - role: "technical-writer", - spawnWork: (opts) => spawnTechnicalWriter(opts), - spawnFix: (opts) => spawnTechnicalWriterFix({ ...opts, fixPhase: "plan-docs" }), - }, - ]; - - const phaseSummaries: string[] = []; - for (const phase of phases) { - const result = await runPlanningPhase( - phase, - planDir, - ctx.cwd, - extensionPath, - state, - log, - widget, - ui, - ); - - phaseSummaries.push(`${phase.label}: ${result.summary}`); - if (!result.passed) { - return { - content: [{ type: "text" as const, text: `Planning failed at ${phase.label}.\n\n${phaseSummaries.join("\n")}` }], - details: undefined, - }; - } - } - - try { - await renderPlanMarkdownToFile(planDir); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - log("Failed to render plan.md", { error: message, planDir }); - return { - content: [{ type: "text" as const, text: `Planning phases completed, but plan markdown rendering failed: ${message}\n\n${phaseSummaries.join("\n")}` }], - details: undefined, - }; - } - - state.phase = "plan-docs-complete"; - widget?.update({ - activeIndex: -1, - step: "planning complete; awaiting manual review of plan.md", - activity: "", - }); - - outcome = "PASS"; - return { - content: [{ type: "text" as const, text: `Planning complete.\n\n${phaseSummaries.join("\n")}` }], - details: undefined, - }; - } finally { - if (widget) { - widget.destroy(); - widget = null; - } - ctx.ui.notify(outcome, outcome === "PASS" ? "info" : "error"); - } - }, - - async execute(ctx) { - ctx.ui.notify("Execution mode is not yet implemented.", "warning"); - }, - - async status(ctx) { - ctx.ui.notify(`Phase: ${state.phase}`, "info"); - }, - }; -} - -const QR_POOL_CONCURRENCY = 6; - -async function runPlanningPhase( - phase: PhaseRunConfig, - planDir: string, - cwd: string, - extensionPath: string, - state: WorkflowState, - log: Logger, - widget: WidgetController | null, - ui: ExtensionUIContext | null, -): Promise { - state.phase = phaseRunningState(phase.key); - - widget?.update({ - phaseStatus: { index: phase.widgetIndex, status: "running" }, - activeIndex: phase.widgetIndex, - step: `${phase.key}: spawning ${phase.role}...`, - activity: "", - qrIterationsMax: MAX_FIX_ITERATIONS + 1, - qrIteration: 1, - qrMode: "initial", - qrPhase: "execute", - qrDone: null, - qrTotal: null, - qrPass: null, - qrFail: null, - qrTodo: null, - ...singleSubagentStart(phase.role), - }); - - const subagentDir = await createSubagentDir(planDir, `${phase.role}-${phase.key}`); - - const pollInterval = pollWithIpcDetection( - subagentDir, - widget, - ui, - phase.key, - (projection, logs) => { - widget?.update({ - step: `${phase.key}: ${projection.stepName}`, - activity: projection.lastAction ?? "", - logLines: logs, - ...singleSubagentFromProjection(projection), - }); - }, - ); - - const workResult = await spawnWorkWithResolvedModel( - phase.key as PhaseRow, - phase.spawnWork, - { - planDir, - subagentDir, - cwd, - extensionPath, - log, - }, - ); - - clearInterval(pollInterval); - - if (workResult.exitCode !== 0) { - const detail = workResult.stderr.slice(0, 500); - log(`${phase.key} subagent failed`, { exitCode: workResult.exitCode, stderr: detail }); - widget?.update({ - phaseStatus: { index: phase.widgetIndex, status: "failed" }, - step: `${phase.key}: worker failed`, - activity: "", - subagentActive: 0, - subagentDone: 1, - }); - return { summary: `${phase.label} subagent failed (exit ${workResult.exitCode}).\n\nStderr:\n${detail}`, passed: false }; - } - - const planJsonPath = path.join(planDir, "plan.json"); - try { - await fs.access(planJsonPath); - } catch { - log(`${phase.key} completed but plan.json missing`, { planJsonPath }); - widget?.update({ - phaseStatus: { index: phase.widgetIndex, status: "failed" }, - step: `${phase.key}: no plan produced`, - activity: "", - subagentActive: 0, - subagentDone: 1, - }); - return { summary: `${phase.label} completed but produced no plan.json.`, passed: false }; - } - - state.phase = phaseCompleteState(phase.key); - widget?.update({ - step: `${phase.key}: starting QR block...`, - activity: "", - qrIteration: 1, - qrMode: "initial", - qrPhase: "execute", - qrDone: null, - qrTotal: null, - qrPass: null, - qrFail: null, - qrTodo: null, - subagentActive: 0, - subagentDone: 1, - }); - - const qr = await runPhaseWithQR( - phase, - planDir, - cwd, - extensionPath, - state, - log, - widget, - ui, - ); - - if (qr.passed) { - state.phase = phaseCompleteState(phase.key); - widget?.update({ phaseStatus: { index: phase.widgetIndex, status: "completed" } }); - } else { - widget?.update({ phaseStatus: { index: phase.widgetIndex, status: "failed" } }); - } - - return qr; -} - - -async function runQRDecompose( - planDir: string, - cwd: string, - extensionPath: string, - phase: WorkPhaseKey, - state: WorkflowState, - log: Logger, - widget: WidgetController | null, -): Promise { - const qrPath = qrFilePath(planDir, phase); - const keyOf = (scope: string, check: string): string => `${scope}\u0000${check}`; - - const previousPassKeys = new Set(); - try { - const raw = await fs.readFile(qrPath, "utf8"); - const prev = JSON.parse(raw) as QRFile; - for (const item of prev.items) { - if (item.status === "PASS") previousPassKeys.add(keyOf(item.scope, item.check)); - } - } catch { - // First QR run for this phase. - } - - state.phase = "qr-decompose-running"; - widget?.update({ - step: `${phase} qr-decompose: starting...`, - activity: "", - qrPhase: "decompose", - qrDone: null, - qrTotal: null, - qrPass: null, - qrFail: null, - qrTodo: null, - ...singleSubagentStart("qr-decomposer"), - }); - - const decomposeDir = await createSubagentDir(planDir, `qr-decomposer-${phase}`); - - const decomposePoll = setInterval(async () => { - const [projection, logs] = await Promise.all([readProjection(decomposeDir), readRecentLogs(decomposeDir)]); - if (!projection) return; - widget?.update({ - step: `${phase} qr-decompose: ${projection.stepName}`, - activity: projection.lastAction ?? "", - logLines: logs, - ...singleSubagentFromProjection(projection), - }); - }, 2000); - - const decompose = await spawnQRDecomposerWithResolvedModel({ - planDir, - subagentDir: decomposeDir, - cwd, - extensionPath, - phase, - log, - }); - - clearInterval(decomposePoll); - - if (decompose.exitCode !== 0) { - state.phase = "qr-decompose-failed"; - const detail = decompose.stderr.slice(0, 500); - log("QR decomposer failed", { phase, exitCode: decompose.exitCode, stderr: detail }); - widget?.update({ step: `${phase} qr-decompose: failed`, activity: "", subagentActive: 0, subagentDone: 1 }); - return { summary: `${phase} QR decompose failed (exit ${decompose.exitCode}).\n\nStderr:\n${detail}`, passed: false }; - } - - let qr: QRFile; - try { - const raw = await fs.readFile(qrPath, "utf8"); - qr = JSON.parse(raw) as QRFile; - } catch (error) { - state.phase = "qr-decompose-failed"; - const message = error instanceof Error ? error.message : String(error); - log("Failed to read QR file after decompose", { phase, error: message }); - return { summary: `${phase} QR decompose completed but produced no verifiable items.`, passed: false }; - } - - if (qr.items.length === 0) { - state.phase = "qr-decompose-failed"; - log("QR decompose produced no items", { phase }); - return { summary: `${phase} QR decompose completed but produced no items.`, passed: false }; - } - - const carriedPasses = qr.items.filter((item) => item.status !== "PASS" && previousPassKeys.has(keyOf(item.scope, item.check))).length; - if (carriedPasses > 0) { - qr = { - ...qr, - items: qr.items.map((item) => - previousPassKeys.has(keyOf(item.scope, item.check)) - ? { ...item, status: "PASS", finding: null } - : item), - }; - try { - const tmpPath = `${qrPath}.tmp`; - await fs.writeFile(tmpPath, `${JSON.stringify(qr, null, 2)}\n`, "utf8"); - await fs.rename(tmpPath, qrPath); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - log("Failed to persist carried PASS statuses", { phase, error: message }); - return { summary: `${phase} QR verify aborted: failed to preserve PASS statuses.`, passed: false }; - } - } - - return { summary: `${phase} QR decompose complete.`, passed: true }; -} - -async function runQRVerify( - planDir: string, - cwd: string, - extensionPath: string, - phase: WorkPhaseKey, - state: WorkflowState, - log: Logger, - widget: WidgetController | null, -): Promise { - const qrPath = qrFilePath(planDir, phase); - - let qr: QRFile; - try { - const raw = await fs.readFile(qrPath, "utf8"); - qr = JSON.parse(raw) as QRFile; - } catch (error) { - state.phase = "qr-decompose-failed"; - const message = error instanceof Error ? error.message : String(error); - log("Failed to read QR file for verify", { phase, error: message }); - return { summary: `${phase} QR verify aborted: cannot read QR file.`, passed: false }; - } - - const resetFailures = qr.items.filter((i) => i.status === "FAIL").length; - if (resetFailures > 0) { - qr = { - ...qr, - items: qr.items.map((item) => (item.status === "FAIL" ? { ...item, status: "TODO", finding: null } : item)), - }; - try { - const tmpPath = `${qrPath}.tmp`; - await fs.writeFile(tmpPath, `${JSON.stringify(qr, null, 2)}\n`, "utf8"); - await fs.rename(tmpPath, qrPath); - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - log("Failed to persist QR FAIL->TODO reset", { phase, error: message }); - return { summary: `${phase} QR verify aborted: failed to prepare QR item states.`, passed: false }; - } - } - - // Group TODO items by group_id for batch verification. - // Items sharing a group_id are verified by a single subagent, amortizing - // process startup cost. Items without group_id are treated as singletons. - const todoItems = qr.items.filter((i) => i.status === "TODO"); - const groups = new Map(); - for (const item of todoItems) { - const gid = item.group_id ?? item.id; - const existing = groups.get(gid); - if (existing) { - existing.push(item.id); - } else { - groups.set(gid, [item.id]); - } - } - const groupEntries = Array.from(groups.entries()); // [groupId, itemIds[]] - const totalItems = qr.items.length; - const totalTodoItems = todoItems.length; - const preservedPass = qr.items.filter((i) => i.status === "PASS").length; - const initialFail = qr.items.filter((i) => i.status === "FAIL").length; - - widget?.update({ - step: `${phase} qr-verify: 0/${groupEntries.length} groups (${totalTodoItems} items)`, - activity: "", - qrPhase: "verify", - qrTotal: totalItems, - qrDone: preservedPass, - qrPass: preservedPass, - qrFail: initialFail, - qrTodo: totalTodoItems, - subagentRole: "reviewer", - subagentModel: null, - subagentParallelCount: QR_POOL_CONCURRENCY, - subagentQueued: groupEntries.length, - subagentActive: 0, - subagentDone: 0, - }); - - log("QR verify: grouped items for dispatch", { - phase, - totalItems: totalTodoItems, - groups: groupEntries.length, - groupSizes: groupEntries.map(([gid, ids]) => `${gid}:${ids.length}`), - }); - - state.phase = "qr-verify-running"; - - let verifyDone = 0; - let failedReviewers: string[] = []; - - if (groupEntries.length > 0) { - const groupIds = groupEntries.map(([gid]) => gid); - - const verifyStatsPoll = setInterval(async () => { - try { - const raw = await fs.readFile(qrPath, "utf8"); - const current = JSON.parse(raw) as QRFile; - const pass = current.items.filter((i) => i.status === "PASS").length; - const fail = current.items.filter((i) => i.status === "FAIL").length; - const todo = current.items.filter((i) => i.status === "TODO").length; - widget?.update({ - qrPass: pass, - qrFail: fail, - qrTodo: todo, - qrDone: preservedPass + verifyDone, - qrTotal: current.items.length, - }); - } catch { - // Ignore transient read races while reviewers write. - } - }, 2000); - - // Build a map from groupId -> itemIds for the pool worker. - const groupItemMap = new Map(groupEntries); - - try { - let reviewerModel: string | null = null; - const result = await pool( - groupIds, - QR_POOL_CONCURRENCY, - async (groupId) => { - const itemIds = groupItemMap.get(groupId)!; - const dirSuffix = itemIds.length === 1 - ? `qr-reviewer-${phase}-${itemIds[0]}` - : `qr-reviewer-${phase}-group-${groupId}`; - const reviewerDir = await createSubagentDir(planDir, dirSuffix); - const r = await spawnReviewerWithResolvedModel({ - planDir, - subagentDir: reviewerDir, - cwd, - extensionPath, - phase, - itemIds, - log, - }); - - if (reviewerModel === null) { - const projection = await readProjection(reviewerDir); - reviewerModel = projection?.model ?? null; - if (reviewerModel) widget?.update({ subagentModel: reviewerModel }); - } - - return r; - }, - (progress) => { - verifyDone = progress.done; - widget?.update({ - step: `${phase} qr-verify: ${progress.done}/${progress.total} groups`, - qrDone: preservedPass + progress.done, - qrTotal: totalItems, - subagentQueued: progress.queued, - subagentActive: progress.active, - subagentDone: progress.done, - }); - }, - ); - failedReviewers = result.failed; - } finally { - clearInterval(verifyStatsPoll); - } - } - - state.phase = "qr-complete"; - let finalQR: QRFile; - try { - const raw = await fs.readFile(qrPath, "utf8"); - finalQR = JSON.parse(raw) as QRFile; - } catch { - finalQR = qr; - } - - const pass = finalQR.items.filter((i) => i.status === "PASS").length; - const fail = finalQR.items.filter((i) => i.status === "FAIL").length; - const todo = finalQR.items.filter((i) => i.status === "TODO").length; - const summary = `${phase} QR complete: ${pass} PASS, ${fail} FAIL, ${todo} TODO (${failedReviewers.length} reviewer groups failed).`; - - const passed = fail === 0 && failedReviewers.length === 0; - widget?.update({ - step: summary, - activity: "", - qrDone: pass + fail, - qrTotal: totalItems, - qrPass: pass, - qrFail: fail, - qrTodo: todo, - subagentQueued: 0, - subagentActive: 0, - subagentDone: groupEntries.length, - }); - return { summary, passed }; -} - -async function runPhaseWithQR( - phase: PhaseRunConfig, - planDir: string, - cwd: string, - extensionPath: string, - state: WorkflowState, - log: Logger, - widget: WidgetController | null, - ui: ExtensionUIContext | null, -): Promise { - const qrPath = qrFilePath(planDir, phase.key); - - const decompose = await runQRDecompose(planDir, cwd, extensionPath, phase.key, state, log, widget); - if (!decompose.passed) { - widget?.update({ phaseStatus: { index: phase.widgetIndex, status: "failed" } }); - return decompose; - } - - let qr = await runQRVerify(planDir, cwd, extensionPath, phase.key, state, log, widget); - if (qr.passed) { - widget?.update({ qrPhase: "done", phaseStatus: { index: phase.widgetIndex, status: "completed" } }); - return qr; - } - - widget?.update({ qrPhase: "execute", qrDone: null, qrTotal: null, qrPass: null, qrFail: null, qrTodo: null }); - - for (let iteration = 2; iteration <= MAX_FIX_ITERATIONS + 1; iteration++) { - widget?.update({ - qrIteration: iteration, - qrMode: "fix", - qrPhase: "execute", - qrDone: null, - qrTotal: null, - qrPass: null, - qrFail: null, - qrTodo: null, - }); - - let qrFile: QRFile; - try { - const raw = await fs.readFile(qrPath, "utf8"); - qrFile = JSON.parse(raw) as QRFile; - } catch { - log("Fix loop: failed to read QR file", { phase: phase.key, iteration }); - widget?.update({ qrPhase: "done" }); - return { summary: `${phase.key} fix loop aborted: cannot read QR file.`, passed: false }; - } - - if (qrPassesAtIteration(qrFile.items, iteration)) { - const pass = qrFile.items.filter((i) => i.status === "PASS").length; - const fail = qrFile.items.filter((i) => i.status === "FAIL").length; - const todo = qrFile.items.filter((i) => i.status === "TODO").length; - widget?.update({ - qrPhase: "done", - qrDone: pass + fail, - qrTotal: qrFile.items.length, - qrPass: pass, - qrFail: fail, - qrTodo: todo, - phaseStatus: { index: phase.widgetIndex, status: "completed" }, - }); - return { - passed: true, - summary: `${phase.key} QR passed at iteration ${iteration} after severity de-escalation: ${pass} PASS, ${fail} FAIL (non-blocking).`, - }; - } - - const fixIndex = iteration - 1; - widget?.update({ - step: `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}: spawning ${phase.role}...`, - activity: "", - qrPhase: "execute", - ...singleSubagentStart(phase.role), - }); - - const fixDir = await createSubagentDir(planDir, `${phase.role}-fix-${phase.key}-${fixIndex}`); - - const fixPoll = pollWithIpcDetection( - fixDir, - widget, - ui, - `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}`, - (projection, logs) => { - widget?.update({ - step: `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}: ${projection.stepName}`, - activity: projection.lastAction ?? "", - logLines: logs, - ...singleSubagentFromProjection(projection), - }); - }, - ); - - const fixResult = await spawnFixWithResolvedModel( - phase.key as PhaseRow, - phase.spawnFix, - { - planDir, - subagentDir: fixDir, - cwd, - extensionPath, - log, - }, - ); - - clearInterval(fixPoll); - - if (fixResult.exitCode !== 0) { - log("Fix worker failed", { - phase: phase.key, - iteration: fixIndex, - exitCode: fixResult.exitCode, - stderr: fixResult.stderr.slice(0, 500), - }); - widget?.update({ - step: `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}: worker failed, re-running QR...`, - activity: "", - subagentActive: 0, - subagentDone: 1, - }); - } - - widget?.update({ - step: `${phase.key} fix ${fixIndex}/${MAX_FIX_ITERATIONS}: re-running QR...`, - activity: "", - subagentActive: 0, - subagentDone: 1, - }); - - qr = await runQRVerify(planDir, cwd, extensionPath, phase.key, state, log, widget); - if (qr.passed) { - widget?.update({ qrPhase: "done", phaseStatus: { index: phase.widgetIndex, status: "completed" } }); - return qr; - } - - widget?.update({ qrPhase: "execute", qrDone: null, qrTotal: null, qrPass: null, qrFail: null, qrTodo: null }); - } - - widget?.update({ qrPhase: "done" }); - return { - passed: false, - summary: `${phase.key} ${qr.summary} (max ${MAX_FIX_ITERATIONS} fix iterations reached)`, - }; -} diff --git a/src/planner/state.ts b/src/planner/state.ts deleted file mode 100644 index 286250f..0000000 --- a/src/planner/state.ts +++ /dev/null @@ -1,40 +0,0 @@ -export type WorkflowPhase = - | "idle" - | "architect-running" - | "architect-failed" - | "plan-design-complete" - | "plan-code-running" - | "plan-code-complete" - | "plan-docs-running" - | "plan-docs-complete" - | "qr-decompose-running" - | "qr-decompose-failed" - | "qr-verify-running" - | "qr-verify-failed" - | "qr-complete"; - -export interface PlanInfo { - id: string; - directory: string; - createdAt: string; - metadataPath: string; -} - -export interface WorkflowState { - phase: WorkflowPhase; - taskDescription: string | null; - plan: PlanInfo | null; -} - -export function createInitialState(): WorkflowState { - return { - phase: "idle", - taskDescription: null, - plan: null, - }; -} - -export function initializePlanState(state: WorkflowState, plan: PlanInfo, taskDescription: string): void { - state.plan = plan; - state.taskDescription = taskDescription; -} diff --git a/src/planner/tools/entity-code.ts b/src/planner/tools/entity-code.ts deleted file mode 100644 index ca57d75..0000000 --- a/src/planner/tools/entity-code.ts +++ /dev/null @@ -1,171 +0,0 @@ -// Plan entity tools for code-phase entities: code intents and code changes. -// Uses planTool helper from entity-design (shared load-mutate-save-lock wrapper). - -import { Type } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import type { PlanRef } from "../lib/dispatch.js"; -import { planTool } from "./entity-design.js"; -import { - addIntent, - setIntent, - addChange, - setChangeDiff, - setChangeDocDiff, - setChangeComments, - setChangeFile, - setChangeIntentRef, -} from "../plan/mutate/index.js"; - -export function registerPlanCodeEntityTools( - pi: ExtensionAPI, - planRef: PlanRef, -): void { - // -- CodeIntent -- - planTool(pi, planRef, { - name: "koan_add_intent", - label: "Add code intent", - description: "Add code intent to milestone.", - parameters: Type.Object({ - milestone: Type.String(), - file: Type.String(), - function: Type.Optional(Type.String()), - behavior: Type.String(), - decision_refs: Type.Optional(Type.Array(Type.String())), - }), - execute: (p, params) => { - const r = addIntent(p, params); - return { - plan: r.plan, - message: `Added intent ${r.id} to milestone ${params.milestone}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_intent", - label: "Update code intent", - description: "Update existing code intent by ID.", - parameters: Type.Object({ - id: Type.String(), - file: Type.Optional(Type.String()), - function: Type.Optional(Type.String()), - behavior: Type.Optional(Type.String()), - decision_refs: Type.Optional(Type.Array(Type.String())), - }), - execute: (p, params) => { - const updated = setIntent(p, params.id, params); - return { - plan: updated, - message: `Updated intent ${params.id}`, - }; - }, - }); - - // -- CodeChange -- - planTool(pi, planRef, { - name: "koan_add_change", - label: "Add code change", - description: "Add code change to milestone.", - parameters: Type.Object({ - milestone: Type.String(), - file: Type.String(), - intent_ref: Type.Optional(Type.String()), - diff: Type.Optional(Type.String()), - doc_diff: Type.Optional(Type.String()), - comments: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const r = addChange(p, params); - return { - plan: r.plan, - message: `Added change ${r.id} to milestone ${params.milestone}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_change_diff", - label: "Set code change diff", - description: "Update change diff.", - parameters: Type.Object({ - id: Type.String(), - diff: Type.String(), - }), - execute: (p, params) => { - const updated = setChangeDiff(p, params.id, params.diff); - return { - plan: updated, - message: `Set diff for change ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_change_doc_diff", - label: "Set code change doc_diff", - description: "Update change doc_diff.", - parameters: Type.Object({ - id: Type.String(), - doc_diff: Type.String(), - }), - execute: (p, params) => { - const updated = setChangeDocDiff(p, params.id, params.doc_diff); - return { - plan: updated, - message: `Set doc_diff for change ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_change_comments", - label: "Set code change comments", - description: "Update change comments.", - parameters: Type.Object({ - id: Type.String(), - comments: Type.String(), - }), - execute: (p, params) => { - const updated = setChangeComments(p, params.id, params.comments); - return { - plan: updated, - message: `Set comments for change ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_change_file", - label: "Set code change file", - description: "Update change file path.", - parameters: Type.Object({ - id: Type.String(), - file: Type.String(), - }), - execute: (p, params) => { - const updated = setChangeFile(p, params.id, params.file); - return { - plan: updated, - message: `Set file for change ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_change_intent_ref", - label: "Set code change intent_ref", - description: "Update change intent reference.", - parameters: Type.Object({ - id: Type.String(), - intent_ref: Type.String(), - }), - execute: (p, params) => { - const updated = setChangeIntentRef(p, params.id, params.intent_ref); - return { - plan: updated, - message: `Set intent_ref for change ${params.id}`, - }; - }, - }); -} diff --git a/src/planner/tools/entity-design.ts b/src/planner/tools/entity-design.ts deleted file mode 100644 index c6e5e7d..0000000 --- a/src/planner/tools/entity-design.ts +++ /dev/null @@ -1,308 +0,0 @@ -// Plan entity tools for design-phase entities: decisions, risks, milestones. -// Exports planTool helper for shared use by entity-code and entity-structure. -// load-mutate-save wrapped in file lock; disk is single source of truth. - -import { Type, type Static, type TSchema } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import * as path from "node:path"; - -import type { PlanRef } from "../lib/dispatch.js"; -import { loadPlan, savePlan } from "../plan/serialize.js"; -import type { Plan } from "../plan/types.js"; -import { withFileLock } from "../../utils/lock.js"; -import { - addDecision, - setDecision, - addRejectedAlternative, - setRejectedAlternative, - addRisk, - setRisk, - addMilestone, - setMilestoneName, - setMilestoneFiles, - setMilestoneFlags, - setMilestoneRequirements, - setMilestoneAcceptanceCriteria, - setMilestoneTests, -} from "../plan/mutate/index.js"; - -export function planTool( - pi: ExtensionAPI, - planRef: PlanRef, - opts: { - name: string; - label: string; - description: string; - parameters: TParams; - execute: (plan: Plan, params: Static) => { plan: Plan; message: string }; - }, -): void { - pi.registerTool({ - name: opts.name, - label: opts.label, - description: opts.description, - parameters: opts.parameters, - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const planPath = path.join(planRef.dir, "plan.json"); - return withFileLock(planPath, async () => { - const plan = await loadPlan(planRef.dir!); - const result = opts.execute(plan, params); - await savePlan(result.plan, planRef.dir!); - return { - content: [{ type: "text" as const, text: result.message }], - details: undefined, - }; - }); - }, - }); -} - -export function registerPlanDesignEntityTools( - pi: ExtensionAPI, - planRef: PlanRef, -): void { - // -- Decision -- - planTool(pi, planRef, { - name: "koan_add_decision", - label: "Add decision", - description: "Add decision to decision log. Source identifies where authority came from (e.g. code:src/foo.ts, docs:CLAUDE.md, user:ask, user:conversation, inference).", - parameters: Type.Object({ - decision: Type.String(), - reasoning: Type.String(), - source: Type.String({ description: "Provenance: code:, docs:, user:ask, user:conversation, or inference" }), - }), - execute: (p, params) => { - const r = addDecision(p, params); - return { - plan: r.plan, - message: `Added decision ${r.id}: "${params.decision}" [source: ${params.source}]`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_decision", - label: "Update decision", - description: "Update existing decision by ID. Omitting source preserves the existing value.", - parameters: Type.Object({ - id: Type.String(), - decision: Type.Optional(Type.String()), - reasoning: Type.Optional(Type.String()), - source: Type.Optional(Type.String({ description: "Provenance: code:, docs:, user:ask, user:conversation, or inference" })), - }), - execute: (p, params) => { - const updated = setDecision(p, params.id, params); - return { - plan: updated, - message: `Updated decision ${params.id}`, - }; - }, - }); - - // -- RejectedAlternative -- - planTool(pi, planRef, { - name: "koan_add_rejected_alternative", - label: "Add rejected alternative", - description: "Add rejected alternative to decision log.", - parameters: Type.Object({ - alternative: Type.String(), - rejection_reason: Type.String(), - decision_ref: Type.String(), - }), - execute: (p, params) => { - const r = addRejectedAlternative(p, params); - return { - plan: r.plan, - message: `Added rejected alternative ${r.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_rejected_alternative", - label: "Update rejected alternative", - description: "Update existing rejected alternative by ID.", - parameters: Type.Object({ - id: Type.String(), - alternative: Type.Optional(Type.String()), - rejection_reason: Type.Optional(Type.String()), - decision_ref: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = setRejectedAlternative(p, params.id, params); - return { - plan: updated, - message: `Updated rejected alternative ${params.id}`, - }; - }, - }); - - // -- Risk -- - planTool(pi, planRef, { - name: "koan_add_risk", - label: "Add risk", - description: "Add risk to known risks.", - parameters: Type.Object({ - risk: Type.String(), - mitigation: Type.String(), - anchor: Type.Optional(Type.String()), - decision_ref: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const r = addRisk(p, params); - return { - plan: r.plan, - message: `Added risk ${r.id}: "${params.risk}"`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_risk", - label: "Update risk", - description: "Update existing risk by ID.", - parameters: Type.Object({ - id: Type.String(), - risk: Type.Optional(Type.String()), - mitigation: Type.Optional(Type.String()), - anchor: Type.Optional(Type.String()), - decision_ref: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = setRisk(p, params.id, params); - return { - plan: updated, - message: `Updated risk ${params.id}`, - }; - }, - }); - - // -- Milestone -- - planTool(pi, planRef, { - name: "koan_add_milestone", - label: "Add milestone", - description: "Create new milestone.", - parameters: Type.Object({ - name: Type.String(), - files: Type.Optional(Type.Array(Type.String())), - flags: Type.Optional(Type.Array(Type.String())), - requirements: Type.Optional(Type.Array(Type.String())), - acceptance_criteria: Type.Optional(Type.Array(Type.String())), - tests: Type.Optional(Type.Array(Type.String())), - }), - execute: (p, params) => { - const r = addMilestone(p, params); - return { - plan: r.plan, - message: `Added milestone ${r.id}: "${params.name}"`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_name", - label: "Set milestone name", - description: "Update milestone name.", - parameters: Type.Object({ - id: Type.String(), - name: Type.String(), - }), - execute: (p, params) => { - const updated = setMilestoneName(p, params.id, params.name); - return { - plan: updated, - message: `Set name for milestone ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_files", - label: "Set milestone files", - description: "Update milestone files list.", - parameters: Type.Object({ - id: Type.String(), - files: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setMilestoneFiles(p, params.id, params.files); - return { - plan: updated, - message: `Set files for milestone ${params.id} (${params.files.length} files)`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_flags", - label: "Set milestone flags", - description: "Update milestone flags list.", - parameters: Type.Object({ - id: Type.String(), - flags: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setMilestoneFlags(p, params.id, params.flags); - return { - plan: updated, - message: `Set flags for milestone ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_requirements", - label: "Set milestone requirements", - description: "Update milestone requirements list.", - parameters: Type.Object({ - id: Type.String(), - requirements: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setMilestoneRequirements(p, params.id, params.requirements); - return { - plan: updated, - message: `Set requirements for milestone ${params.id} (${params.requirements.length} items)`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_acceptance_criteria", - label: "Set milestone acceptance criteria", - description: "Update milestone acceptance criteria list.", - parameters: Type.Object({ - id: Type.String(), - acceptance_criteria: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setMilestoneAcceptanceCriteria( - p, - params.id, - params.acceptance_criteria, - ); - return { - plan: updated, - message: `Set acceptance criteria for milestone ${params.id} (${params.acceptance_criteria.length} items)`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_milestone_tests", - label: "Set milestone tests", - description: "Update milestone tests list.", - parameters: Type.Object({ - id: Type.String(), - tests: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setMilestoneTests(p, params.id, params.tests); - return { - plan: updated, - message: `Set tests for milestone ${params.id} (${params.tests.length} tests)`, - }; - }, - }); -} diff --git a/src/planner/tools/entity-structure.ts b/src/planner/tools/entity-structure.ts deleted file mode 100644 index cc710a8..0000000 --- a/src/planner/tools/entity-structure.ts +++ /dev/null @@ -1,156 +0,0 @@ -// Plan entity tools for structural entities: waves, diagrams, readme entries. -// Uses planTool helper from entity-design (shared load-mutate-save-lock wrapper). - -import { Type } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import type { PlanRef } from "../lib/dispatch.js"; -import { planTool } from "./entity-design.js"; -import { - addWave, - setWaveMilestones, - addDiagram, - setDiagram, - addDiagramNode, - addDiagramEdge, - setReadmeEntry, -} from "../plan/mutate/index.js"; - -export function registerPlanStructureEntityTools( - pi: ExtensionAPI, - planRef: PlanRef, -): void { - // -- Wave -- - planTool(pi, planRef, { - name: "koan_add_wave", - label: "Add wave", - description: "Create wave with milestone list.", - parameters: Type.Object({ - milestones: Type.Array(Type.String()), - }), - execute: (p, params) => { - const r = addWave(p, params); - return { - plan: r.plan, - message: `Added wave ${r.id} with ${params.milestones.length} milestones`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_wave_milestones", - label: "Set wave milestones", - description: "Update wave milestones list.", - parameters: Type.Object({ - id: Type.String(), - milestones: Type.Array(Type.String()), - }), - execute: (p, params) => { - const updated = setWaveMilestones(p, params.id, params.milestones); - return { - plan: updated, - message: `Set milestones for wave ${params.id}`, - }; - }, - }); - - // -- Diagram -- - planTool(pi, planRef, { - name: "koan_add_diagram", - label: "Add diagram", - description: "Create diagram graph.", - parameters: Type.Object({ - type: Type.Union([ - Type.Literal("architecture"), - Type.Literal("state"), - Type.Literal("sequence"), - Type.Literal("dataflow"), - ]), - scope: Type.String(), - title: Type.String(), - }), - execute: (p, params) => { - const r = addDiagram(p, params); - return { - plan: r.plan, - message: `Added diagram ${r.id}: "${params.title}"`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_set_diagram", - label: "Update diagram", - description: "Update diagram properties.", - parameters: Type.Object({ - id: Type.String(), - title: Type.Optional(Type.String()), - scope: Type.Optional(Type.String()), - ascii_render: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = setDiagram(p, params.id, params); - return { - plan: updated, - message: `Updated diagram ${params.id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_add_diagram_node", - label: "Add diagram node", - description: "Add node to diagram.", - parameters: Type.Object({ - diagram_id: Type.String(), - id: Type.String(), - label: Type.String(), - type: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = addDiagramNode(p, params.diagram_id, params); - return { - plan: updated, - message: `Added node ${params.id} to diagram ${params.diagram_id}`, - }; - }, - }); - - planTool(pi, planRef, { - name: "koan_add_diagram_edge", - label: "Add diagram edge", - description: "Add edge to diagram.", - parameters: Type.Object({ - diagram_id: Type.String(), - source: Type.String(), - target: Type.String(), - label: Type.String(), - protocol: Type.Optional(Type.String()), - }), - execute: (p, params) => { - const updated = addDiagramEdge(p, params.diagram_id, params); - return { - plan: updated, - message: `Added edge ${params.source}->${params.target} to diagram ${params.diagram_id}`, - }; - }, - }); - - // -- ReadmeEntry -- - planTool(pi, planRef, { - name: "koan_set_readme_entry", - label: "Set readme entry", - description: "Upsert readme entry by path.", - parameters: Type.Object({ - path: Type.String(), - content: Type.String(), - }), - execute: (p, params) => { - const updated = setReadmeEntry(p, params.path, params.content); - return { - plan: updated, - message: `Set readme entry for ${params.path}`, - }; - }, - }); -} diff --git a/src/planner/tools/getters.ts b/src/planner/tools/getters.ts deleted file mode 100644 index d7924bb..0000000 --- a/src/planner/tools/getters.ts +++ /dev/null @@ -1,175 +0,0 @@ -import { Type } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import type { PlanRef } from "../lib/dispatch.js"; -import { loadPlan } from "../plan/serialize.js"; -import type { Plan, Milestone, CodeIntent, CodeChange } from "../plan/types.js"; - -export function registerPlanGetterTools( - pi: ExtensionAPI, - planRef: PlanRef, -): void { - pi.registerTool({ - name: "koan_get_plan", - label: "Get plan summary", - description: - "Returns plan overview and entity counts with IDs for drill-down.", - parameters: Type.Object({}), - async execute() { - if (!planRef.dir) throw new Error("No plan directory is active."); - const p = await loadPlan(planRef.dir); - const summary = formatPlanSummary(p); - return { - content: [{ type: "text" as const, text: summary }], - details: undefined, - }; - }, - }); - - pi.registerTool({ - name: "koan_get_milestone", - label: "Get milestone by ID", - description: "Returns full milestone with code_intents and code_changes.", - parameters: Type.Object({ - id: Type.String({ description: "Milestone ID (e.g., M-001)" }), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const p = await loadPlan(planRef.dir); - const m = p.milestones.find((x) => x.id === params.id); - if (!m) throw new Error(`Milestone ${params.id} not found`); - return { - content: [{ type: "text" as const, text: JSON.stringify(m, null, 2) }], - details: undefined, - }; - }, - }); - - pi.registerTool({ - name: "koan_get_decision", - label: "Get decision by ID", - description: "Returns decision from decision log.", - parameters: Type.Object({ - id: Type.String({ description: "Decision ID (e.g., DL-001)" }), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const p = await loadPlan(planRef.dir); - const d = p.planning_context.decision_log.find( - (x) => x.id === params.id, - ); - if (!d) throw new Error(`Decision ${params.id} not found`); - return { - content: [{ type: "text" as const, text: JSON.stringify(d, null, 2) }], - details: undefined, - }; - }, - }); - - pi.registerTool({ - name: "koan_get_intent", - label: "Get code intent by ID", - description: "Returns code intent and parent milestone ID.", - parameters: Type.Object({ - id: Type.String({ description: "Intent ID (e.g., CI-M-001-001)" }), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const p = await loadPlan(planRef.dir); - const result = findIntent(p, params.id); - if (!result) - throw new Error(`Intent ${params.id} not found`); - return { - content: [ - { - type: "text" as const, - text: JSON.stringify( - { milestone_id: result.milestoneId, intent: result.intent }, - null, - 2, - ), - }, - ], - details: undefined, - }; - }, - }); - - pi.registerTool({ - name: "koan_get_change", - label: "Get code change by ID", - description: "Returns code change and parent milestone ID.", - parameters: Type.Object({ - id: Type.String({ description: "Change ID (e.g., CC-M-001-001)" }), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const p = await loadPlan(planRef.dir); - const result = findChange(p, params.id); - if (!result) - throw new Error(`Change ${params.id} not found`); - return { - content: [ - { - type: "text" as const, - text: JSON.stringify( - { milestone_id: result.milestoneId, change: result.change }, - null, - 2, - ), - }, - ], - details: undefined, - }; - }, - }); -} - -function formatPlanSummary(p: Plan): string { - const lines = [ - "Plan Summary", - "============", - "", - "Overview:", - ` Problem: ${p.overview.problem || "(empty)"}`, - ` Approach: ${p.overview.approach || "(empty)"}`, - "", - `Milestones (${p.milestones.length}):`, - ...p.milestones.map((m) => ` ${m.id}: ${m.name}`), - "", - `Decisions (${p.planning_context.decision_log.length}):`, - ...p.planning_context.decision_log.map((d) => { - const src = d.source ? ` [${d.source}]` : " [no source]"; - return ` ${d.id}: ${d.decision}${src}`; - }), - "", - `Waves (${p.waves.length}):`, - ...p.waves.map((w) => ` ${w.id}: [${w.milestones.join(", ")}]`), - "", - `Diagrams (${p.diagram_graphs.length}):`, - ...p.diagram_graphs.map((d) => ` ${d.id}: ${d.title} (${d.type})`), - ]; - return lines.join("\n"); -} - -function findIntent( - p: Plan, - id: string, -): { milestoneId: string; intent: CodeIntent } | null { - for (const m of p.milestones) { - const intent = m.code_intents.find((ci) => ci.id === id); - if (intent) return { milestoneId: m.id, intent }; - } - return null; -} - -function findChange( - p: Plan, - id: string, -): { milestoneId: string; change: CodeChange } | null { - for (const m of p.milestones) { - const change = m.code_changes.find((cc) => cc.id === id); - if (change) return { milestoneId: m.id, change }; - } - return null; -} diff --git a/src/planner/tools/qr.ts b/src/planner/tools/qr.ts deleted file mode 100644 index 83364de..0000000 --- a/src/planner/tools/qr.ts +++ /dev/null @@ -1,230 +0,0 @@ -import { Type } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { PlanRef } from "../lib/dispatch.js"; -import type { QRFile } from "../qr/types.js"; -import { addQRItem, setQRItem, assignGroup } from "../qr/mutate.js"; -import { withFileLock } from "../../utils/lock.js"; - -function requirePhase(planRef: PlanRef): string { - if (!planRef.qrPhase) throw new Error("No QR phase is active."); - return planRef.qrPhase; -} - -function createEmptyQRFile(phase: string): QRFile { - return { - phase, - iteration: 1, - items: [], - }; -} - -async function loadQR(dir: string, phase: string): Promise { - const qrPath = path.join(dir, `qr-${phase}.json`); - try { - const content = await fs.readFile(qrPath, "utf8"); - return JSON.parse(content) as QRFile; - } catch (err: unknown) { - if ((err as NodeJS.ErrnoException).code === "ENOENT") { - return createEmptyQRFile(phase); - } - throw err; - } -} - -async function saveQR(qr: QRFile, dir: string, phase: string): Promise { - const qrPath = path.join(dir, `qr-${phase}.json`); - const tmpPath = path.join(dir, `.qr-${phase}.json.tmp`); - const content = `${JSON.stringify(qr, null, 2)}\n`; - await fs.writeFile(tmpPath, content, "utf8"); - await fs.rename(tmpPath, qrPath); -} - -export function registerQRTools(pi: ExtensionAPI, planRef: PlanRef): void { - pi.registerTool({ - name: "koan_qr_add_item", - label: "Add QR item", - description: "Add quality review item.", - parameters: Type.Object({ - scope: Type.String(), - check: Type.String(), - severity: Type.Optional( - Type.Union([ - Type.Literal("MUST"), - Type.Literal("SHOULD"), - Type.Literal("COULD"), - ]), - ), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const phase = requirePhase(planRef); - const qrPath = path.join(planRef.dir, `qr-${phase}.json`); - return withFileLock(qrPath, async () => { - const qr = await loadQR(planRef.dir!, phase); - const r = addQRItem(qr, params); - await saveQR(r.qr, planRef.dir!, phase); - return { - content: [{ type: "text" as const, text: `Added QR item ${r.id}` }], - details: undefined, - }; - }); - }, - }); - - pi.registerTool({ - name: "koan_qr_set_item", - label: "Update QR item", - description: "Update QR item status or finding.", - parameters: Type.Object({ - id: Type.String(), - status: Type.Optional( - Type.Union([ - Type.Literal("TODO"), - Type.Literal("PASS"), - Type.Literal("FAIL"), - ]), - ), - finding: Type.Optional(Type.String()), - check: Type.Optional(Type.String()), - severity: Type.Optional( - Type.Union([ - Type.Literal("MUST"), - Type.Literal("SHOULD"), - Type.Literal("COULD"), - ]), - ), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const phase = requirePhase(planRef); - const qrPath = path.join(planRef.dir, `qr-${phase}.json`); - return withFileLock(qrPath, async () => { - const qr = await loadQR(planRef.dir!, phase); - const updated = setQRItem(qr, params.id, params); - await saveQR(updated, planRef.dir!, phase); - return { - content: [{ type: "text" as const, text: `Updated QR item ${params.id}` }], - details: undefined, - }; - }); - }, - }); - - pi.registerTool({ - name: "koan_qr_assign_group", - label: "Assign QR group", - description: "Assign group ID to QR items.", - parameters: Type.Object({ - ids: Type.Array(Type.String()), - group_id: Type.String(), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const phase = requirePhase(planRef); - const qrPath = path.join(planRef.dir, `qr-${phase}.json`); - return withFileLock(qrPath, async () => { - const qr = await loadQR(planRef.dir!, phase); - const updated = assignGroup(qr, params.ids, params.group_id); - await saveQR(updated, planRef.dir!, phase); - return { - content: [ - { - type: "text" as const, - text: `Assigned ${params.ids.length} items to group ${params.group_id}`, - }, - ], - details: undefined, - }; - }); - }, - }); - - pi.registerTool({ - name: "koan_qr_get_item", - label: "Get QR item", - description: "Get QR item by ID.", - parameters: Type.Object({ - id: Type.String(), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const phase = requirePhase(planRef); - const qr = await loadQR(planRef.dir, phase); - const item = qr.items.find((x) => x.id === params.id); - if (!item) throw new Error(`QR item ${params.id} not found`); - return { - content: [{ type: "text" as const, text: JSON.stringify(item, null, 2) }], - details: undefined, - }; - }, - }); - - pi.registerTool({ - name: "koan_qr_list_items", - label: "List QR items", - description: "List QR items, optionally filtered by status.", - parameters: Type.Object({ - status: Type.Optional( - Type.Union([ - Type.Literal("TODO"), - Type.Literal("PASS"), - Type.Literal("FAIL"), - ]), - ), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const phase = requirePhase(planRef); - const qr = await loadQR(planRef.dir, phase); - const filtered = params.status - ? qr.items.filter((item) => item.status === params.status) - : qr.items; - return { - content: [ - { type: "text" as const, text: JSON.stringify(filtered, null, 2) }, - ], - details: undefined, - }; - }, - }); - - pi.registerTool({ - name: "koan_qr_summary", - label: "QR summary", - description: "Get QR summary with counts by status and severity.", - parameters: Type.Object({}), - async execute() { - if (!planRef.dir) throw new Error("No plan directory is active."); - const phase = requirePhase(planRef); - const qr = await loadQR(planRef.dir, phase); - - const byStatus = { - TODO: qr.items.filter((x) => x.status === "TODO").length, - PASS: qr.items.filter((x) => x.status === "PASS").length, - FAIL: qr.items.filter((x) => x.status === "FAIL").length, - }; - - const bySeverity = { - MUST: qr.items.filter((x) => x.severity === "MUST").length, - SHOULD: qr.items.filter((x) => x.severity === "SHOULD").length, - COULD: qr.items.filter((x) => x.severity === "COULD").length, - }; - - const summary = { - total: qr.items.length, - by_status: byStatus, - by_severity: bySeverity, - }; - - return { - content: [ - { type: "text" as const, text: JSON.stringify(summary, null, 2) }, - ], - details: undefined, - }; - }, - }); -} diff --git a/src/planner/tools/setters.ts b/src/planner/tools/setters.ts deleted file mode 100644 index 13e0f92..0000000 --- a/src/planner/tools/setters.ts +++ /dev/null @@ -1,82 +0,0 @@ -import { Type } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import type { PlanRef } from "../lib/dispatch.js"; -import { loadPlan, savePlan } from "../plan/serialize.js"; -import { - setOverview, - setConstraints, - setInvisibleKnowledge, -} from "../plan/mutate/index.js"; - -export function registerPlanSetterTools( - pi: ExtensionAPI, - planRef: PlanRef, -): void { - pi.registerTool({ - name: "koan_set_overview", - label: "Set plan overview", - description: "Set problem statement and approach.", - parameters: Type.Object({ - problem: Type.Optional(Type.String()), - approach: Type.Optional(Type.String()), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const p = await loadPlan(planRef.dir); - const updated = setOverview(p, params); - await savePlan(updated, planRef.dir); - return { - content: [{ type: "text" as const, text: "Overview updated." }], - details: undefined, - }; - }, - }); - - pi.registerTool({ - name: "koan_set_constraints", - label: "Set plan constraints", - description: "Set planning constraints list.", - parameters: Type.Object({ - constraints: Type.Array(Type.String()), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const p = await loadPlan(planRef.dir); - const updated = setConstraints(p, params.constraints); - await savePlan(updated, planRef.dir); - return { - content: [ - { - type: "text" as const, - text: `Constraints set (${params.constraints.length} items).`, - }, - ], - details: undefined, - }; - }, - }); - - pi.registerTool({ - name: "koan_set_invisible_knowledge", - label: "Set invisible knowledge", - description: "Set system description, invariants, and tradeoffs.", - parameters: Type.Object({ - system: Type.Optional(Type.String()), - invariants: Type.Optional(Type.Array(Type.String())), - tradeoffs: Type.Optional(Type.Array(Type.String())), - }), - async execute(_toolCallId, params) { - if (!planRef.dir) throw new Error("No plan directory is active."); - const p = await loadPlan(planRef.dir); - const updated = setInvisibleKnowledge(p, params); - await savePlan(updated, planRef.dir); - return { - content: [ - { type: "text" as const, text: "Invisible knowledge updated." }, - ], - details: undefined, - }; - }, - }); -} diff --git a/src/planner/ui/widget.ts b/src/planner/ui/widget.ts deleted file mode 100644 index bfe684e..0000000 --- a/src/planner/ui/widget.ts +++ /dev/null @@ -1,999 +0,0 @@ -// Persistent TUI widget for koan workflow progress. -// Full-width background canvas (toolPendingBg) via component factory. -// Hash-based change detection + 1s unref'd timer for elapsed updates. -// Created by session.plan(), destroyed in onContextComplete finally block. -// -// Layout and styling reference: docs/planning-widget.md and the -// corresponding execution widget design deck selections (Stacked Modular -// Cards canvas + Vertical Timeline Rail). - -import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; -import type { Theme, ThemeColor } from "@mariozechner/pi-coding-agent"; -import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui"; -import type { LogLine } from "../lib/audit.js"; - -// -- Types -- - -export type PhaseStatus = "pending" | "running" | "completed" | "failed"; - -interface PhaseEntry { - key: string; - label: string; - detail: string; - status: PhaseStatus; -} - -type WidgetMode = "planning" | "execution"; - -type QRMode = "initial" | "fix"; -type QRPhase = "idle" | "execute" | "decompose" | "verify" | "done"; - -interface WidgetState { - mode: WidgetMode; - planId: string; - phases: PhaseEntry[]; - activeIndex: number; // 0-based; -1 when done - step: string; - activity: string; - startedAt: number; - logLines: LogLine[]; - qrIteration: number | null; - qrIterationsMax: number | null; - qrMode: QRMode | null; - qrPhase: QRPhase; - qrDone: number | null; - qrTotal: number | null; - qrPass: number | null; - qrFail: number | null; - qrTodo: number | null; - subagentRole: string | null; - subagentModel: string | null; - subagentParallelCount: number | null; - subagentQueued: number | null; - subagentActive: number | null; - subagentDone: number | null; -} - -export interface WidgetUpdate { - activeIndex?: number; - step?: string; - activity?: string; - phaseStatus?: { index: number; status: PhaseStatus }; - mode?: WidgetMode; - logLines?: readonly LogLine[]; - qrIteration?: number | null; - qrIterationsMax?: number | null; - qrMode?: QRMode | null; - qrPhase?: QRPhase; - qrDone?: number | null; - qrTotal?: number | null; - qrPass?: number | null; - qrFail?: number | null; - qrTodo?: number | null; - subagentRole?: string | null; - subagentModel?: string | null; - subagentParallelCount?: number | null; - subagentQueued?: number | null; - subagentActive?: number | null; - subagentDone?: number | null; -} - -// -- Constants -- - -const WIDGET_KEY = "koan"; -const PAD = 2; // horizontal canvas padding each side -const CARD_MARGIN = 2; // left margin before card borders -const LOG_LINES = 5; - -const BODY_INDENT = " "; - -const PLANNING_PHASES: ReadonlyArray<{ key: string; label: string; detail: string }> = [ - { key: "design", label: "Plan design", detail: "Designing plan" }, - { key: "code", label: "Plan code", detail: "Creating code plan" }, - { key: "docs", label: "Plan docs", detail: "Documenting plan" }, -]; - -const STATUS_ICON: Record = { - pending: "○", - running: "●", - completed: "●", - failed: "✖", -}; - -const STATUS_COLOR: Record = { - pending: "muted", - running: "accent", - completed: "dim", - failed: "error", -}; - -const STATUS_TAG: Record = { - pending: "upcoming", - running: "current", - completed: "done", - failed: "failed", -}; - -const LOG_PLACEHOLDER = "No recent log entries"; -const TIMELINE_MIN_WIDTH = 16; -const TIMELINE_MAX_WIDTH = 28; -const CONNECTOR = "│"; -const COLUMN_GAP = 4; - -interface BorderStyle { - topLeft: string; - topRight: string; - bottomLeft: string; - bottomRight: string; - horizontal: string; - vertical: string; -} - -const BORDER_SOLID: BorderStyle = { - topLeft: "┌", - topRight: "┐", - bottomLeft: "└", - bottomRight: "┘", - horizontal: "─", - vertical: "│", -}; - -// -- Canvas primitive -- -// Content width adapts to terminal; background fills edge to edge. - -function contentWidth(termWidth: number): number { - return Math.max(40, termWidth - PAD * 2); -} - -function canvasLine(content: string, termWidth: number, theme: Theme): string { - const cw = contentWidth(termWidth); - const inner = clampToWidth(content, cw); - const line = " ".repeat(PAD) + inner + " ".repeat(PAD); - return theme.bg("toolPendingBg", line); -} - -// -- Helpers -- - -function clampToWidth(text: string, width: number, ellipsis = ""): string { - const truncated = truncateToWidth(text, width, ellipsis === "" ? "" : ellipsis, false); - const visible = visibleWidth(truncated); - if (visible >= width) { - return truncated; - } - return truncated + " ".repeat(width - visible); -} - -function indentLines(lines: string[], width: number, indent = BODY_INDENT): string[] { - if (!indent) { - return lines.map((line) => clampToWidth(line, width)); - } - const indentWidth = visibleWidth(indent); - const available = Math.max(0, width - indentWidth); - return lines.map((line) => indent + clampToWidth(line, available)); -} - -interface PlanningColumns { - innerWidth: number; - contentWidth: number; - timelineWidth: number; - detailWidth: number; -} - -function planningColumns(width: number): PlanningColumns { - const innerWidth = Math.max(0, width - 2); - const indentWidth = visibleWidth(BODY_INDENT); - const contentWidth = Math.max(0, innerWidth - indentWidth); - const timelineWidth = Math.min(TIMELINE_MAX_WIDTH, Math.max(TIMELINE_MIN_WIDTH, Math.floor(contentWidth * 0.3))); - const detailWidth = Math.max(14, contentWidth - timelineWidth - COLUMN_GAP); - return { innerWidth, contentWidth, timelineWidth, detailWidth }; -} - -function formatElapsed(ms: number): string { - const totalSec = Math.floor(ms / 1000); - const h = Math.floor(totalSec / 3600); - const m = Math.floor((totalSec % 3600) / 60); - const s = totalSec % 60; - - if (h > 0) { - return `${h}h ${String(m).padStart(2, "0")}m ${String(s).padStart(2, "0")}s`; - } - - return `${m}m ${String(s).padStart(2, "0")}s`; -} - -function rightAlign(left: string, right: string, width: number): string { - const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(right)); - return `${left}${" ".repeat(gap)}${right}`; -} - -function activePhase(state: WidgetState): PhaseEntry | null { - if (state.activeIndex < 0) return null; - return state.phases[state.activeIndex] ?? null; -} - -function normalizeLogLines(lines: readonly LogLine[] | undefined): LogLine[] { - if (!lines || lines.length === 0) return []; - return [...lines].slice(-(LOG_LINES * 2)); -} - -const HEADER_STATUS_SHORT: Record = { - CURRENT: "CUR", - UPCOMING: "UP", - DONE: "DONE", - FAILED: "FAIL", -}; - -const HEADER_PHASE_SHORT: Record = { - "Plan design": "Design", - "Plan code": "Code", - "Plan docs": "Docs", -}; - -interface PlanningHeaderVariant { - label: string; - phase: string | null; - status: string | null; -} - -function selectPlanningHeaderVariant(phaseLabel: string, statusLabel: string, budget: number): PlanningHeaderVariant { - const phaseShort = HEADER_PHASE_SHORT[phaseLabel] ?? phaseLabel; - const statusShort = HEADER_STATUS_SHORT[statusLabel] ?? statusLabel; - - const truncatedPhase = truncateToWidth( - phaseShort, - Math.max(0, budget - visibleWidth("Planning · ")), - "…", - false, - ); - - const candidates: PlanningHeaderVariant[] = [ - { label: `Planning · ${phaseLabel} · ${statusLabel}`, phase: phaseLabel, status: statusLabel }, - { label: `Planning · ${phaseLabel} · ${statusShort}`, phase: phaseLabel, status: statusShort }, - { label: `Planning · ${phaseLabel}`, phase: phaseLabel, status: null }, - { label: `Planning · ${phaseShort}`, phase: phaseShort, status: null }, - { label: `Planning · ${truncatedPhase}`, phase: truncatedPhase, status: null }, - { label: "Planning", phase: null, status: null }, - ]; - - for (const candidate of candidates) { - if (visibleWidth(candidate.label) <= budget) { - return candidate; - } - } - - return { - label: truncateToWidth("Planning", budget, "…", false), - phase: null, - status: null, - }; -} - -export function formatPlanningHeaderLabel(phaseLabel: string, statusLabel: string, budget: number): string { - return selectPlanningHeaderVariant(phaseLabel, statusLabel, budget).label; -} - -function renderPlanningHeader(state: WidgetState, theme: Theme, budget: number): string { - const active = activePhase(state); - const phaseLabel = active?.label ?? "Complete"; - const statusLabel = (active ? STATUS_TAG[active.status] : "done").toUpperCase(); - const variant = selectPlanningHeaderVariant(phaseLabel, statusLabel, budget); - - if (!variant.label.startsWith("Planning")) { - return theme.bold(theme.fg("accent", variant.label)); - } - - const statusColor: ThemeColor = active ? STATUS_COLOR[active.status] : "dim"; - - if (!variant.phase) { - return theme.bold(theme.fg("accent", variant.label)); - } - - let result = `${theme.bold(theme.fg("accent", "Planning"))}${theme.fg("muted", " · ")}${theme.fg("muted", variant.phase)}`; - if (variant.status) { - result += `${theme.fg("muted", " · ")}${theme.bold(theme.fg(statusColor, variant.status))}`; - } - return result; -} - -function renderTimelineLines(state: WidgetState, theme: Theme, width: number): string[] { - const lines: string[] = []; - const total = state.phases.length; - - state.phases.forEach((phase, index) => { - const isActive = index === state.activeIndex; - const color = STATUS_COLOR[phase.status]; - const iconBase = STATUS_ICON[phase.status]; - const icon = isActive - ? theme.bold(theme.fg("accent", iconBase)) - : theme.fg(color, iconBase); - - const labelColor: ThemeColor = phase.status === "completed" - ? "dim" - : isActive - ? "accent" - : phase.status === "failed" - ? "error" - : "muted"; - - const emphasize = isActive || phase.status === "completed"; - const label = emphasize - ? theme.bold(theme.fg(labelColor, phase.label)) - : theme.fg(labelColor, phase.label); - - lines.push(clampToWidth(`${icon} ${label}`, width, "…")); - - const connector = index < total - 1 ? theme.fg("muted", CONNECTOR) : " "; - lines.push(clampToWidth(`${connector} ${theme.fg("muted", STATUS_TAG[phase.status].toUpperCase())}`, width, "…")); - - if (index < total - 1) { - lines.push(clampToWidth(`${theme.fg("muted", CONNECTOR)} `, width)); - } - }); - - return lines; -} - -function shouldShowQR(state: WidgetState): boolean { - if (state.qrIteration === null) return false; - const active = activePhase(state); - if (!active) return false; - return true; -} - -interface QRCounterValues { - done: string; - pass: string; - fail: string; - todo: string; -} - -function qrCounterValues(state: WidgetState): QRCounterValues { - const meaningful = (state.qrPhase === "verify" || state.qrPhase === "done") && state.qrTotal !== null; - if (!meaningful || state.qrTotal === null) { - return { done: "-/-", pass: "-", fail: "-", todo: "-" }; - } - - return { - done: `${state.qrDone ?? 0}/${state.qrTotal}`, - pass: String(state.qrPass ?? 0), - fail: String(state.qrFail ?? 0), - todo: String(state.qrTodo ?? 0), - }; -} - -function runtimeStageLabel(state: WidgetState): string { - switch (state.qrPhase) { - case "idle": - case "execute": - return state.qrMode === "fix" ? "Fixing" : "Writing"; - case "decompose": - return "Analyzing"; - case "verify": - return "Verifying"; - case "done": - return "Complete"; - } -} - -function stageCycleText(state: WidgetState): string { - const iter = state.qrIteration ?? 0; - const iterMax = state.qrIterationsMax ? `/${state.qrIterationsMax}` : ""; - const mode = state.qrMode === "fix" ? "fix" : "initial"; - return `cycle ${iter}${iterMax} · ${mode}`; -} - -function shouldShowRuntimeSection(state: WidgetState): boolean { - return shouldShowQR(state) || shouldShowSubagentSection(state); -} - -function renderRuntimeRow(theme: Theme, width: number, keyWidth: number, key: string, value: string): string { - const padded = key.padEnd(keyWidth, " "); - return clampToWidth(`${theme.fg("muted", padded)} : ${value}`, width, "…"); -} - -function renderRuntimeStatusSection(state: WidgetState, theme: Theme, width: number): string[] { - if (!shouldShowRuntimeSection(state)) { - return []; - } - - const rows: Array<{ key: string; value: string }> = []; - - if (shouldShowQR(state)) { - const stageValue = `${theme.bold(theme.fg("accent", runtimeStageLabel(state)))} ${theme.fg("dim", `(${stageCycleText(state)})`)}`; - const values = qrCounterValues(state); - const qualityValue = [ - `${theme.fg("muted", "checked")} ${theme.fg("dim", values.done)}`, - `${theme.fg("muted", "pass")} ${theme.fg("accent", values.pass)}`, - `${theme.bold(theme.fg("error", "FAIL"))} ${theme.bold(theme.fg("error", values.fail))}`, - `${theme.fg("muted", "remaining")} ${theme.fg("muted", values.todo)}`, - ].join(" "); - - rows.push({ key: "stage", value: stageValue }); - rows.push({ key: "quality", value: qualityValue }); - } - - if (shouldShowSubagentSection(state)) { - const parallel = state.subagentParallelCount ?? 1; - const pool = parallel > 1 ? `pool ×${parallel}` : "single"; - const workersValue = [ - `${theme.fg("muted", "queued")} ${theme.fg("muted", subagentCount(state.subagentQueued))}`, - `${theme.fg("muted", "active")} ${theme.bold(theme.fg("accent", subagentCount(state.subagentActive)))}`, - `${theme.fg("muted", "done")} ${theme.fg("dim", subagentCount(state.subagentDone))}`, - `${theme.fg("dim", pool)}`, - ].join(" "); - - rows.push({ key: "workers", value: workersValue }); - } - - if (rows.length === 0) { - return []; - } - - const keyWidth = Math.max(...rows.map((row) => visibleWidth(row.key))); - const lines = [clampToWidth(theme.fg("dim", "Runtime"), width)]; - - for (const row of rows) { - lines.push(renderRuntimeRow(theme, width, keyWidth, row.key, row.value)); - } - - return lines; -} - -interface DetailSections { - core: string[]; - footer: string[]; -} - -interface DetailSectionDefinition { - id: string; - placement: "core" | "footer"; - select: (state: WidgetState) => ViewModel | null; - render: (view: ViewModel, theme: Theme, width: number) => string[]; -} - -interface IdentityView { - planId: string; - agentLabel: "Agent" | "Agent pool"; - agentValue: string; - model: string; -} - -function shouldShowSubagentSection(state: WidgetState): boolean { - if (state.subagentRole) return true; - return state.subagentQueued !== null || state.subagentActive !== null || state.subagentDone !== null; -} - -function subagentCount(value: number | null): string { - return value === null ? "-" : String(value); -} - -function identityView(state: WidgetState): IdentityView { - const role = state.subagentRole ?? "—"; - const parallel = state.subagentParallelCount ?? 1; - - if (parallel > 1) { - return { - planId: state.planId, - agentLabel: "Agent pool", - agentValue: `${role} x${parallel}`, - model: state.subagentModel ?? "—", - }; - } - - return { - planId: state.planId, - agentLabel: "Agent", - agentValue: role, - model: state.subagentModel ?? "—", - }; -} - -function renderIdentityRow(theme: Theme, width: number, keyWidth: number, key: string, value: string): string { - const padded = key.padEnd(keyWidth, " "); - return clampToWidth(`${theme.fg("muted", padded)} : ${theme.fg("dim", value)}`, width, "…"); -} - -function renderIdentitySection(view: IdentityView, theme: Theme, width: number): string[] { - const keys = ["Plan ID", view.agentLabel, "Model"]; - const keyWidth = Math.max(...keys.map((key) => visibleWidth(key))); - return [ - renderIdentityRow(theme, width, keyWidth, "Plan ID", view.planId), - renderIdentityRow(theme, width, keyWidth, view.agentLabel, view.agentValue), - renderIdentityRow(theme, width, keyWidth, "Model", view.model), - ]; -} - -const DETAIL_SECTION_REGISTRY: Array> = [ - { - id: "runtime-status", - placement: "core", - select: (state: WidgetState): WidgetState | null => (shouldShowRuntimeSection(state) ? state : null), - render: (view: WidgetState, theme: Theme, width: number): string[] => renderRuntimeStatusSection(view, theme, width), - }, - { - id: "identity", - placement: "footer", - select: (state: WidgetState): IdentityView => identityView(state), - render: (view: IdentityView, theme: Theme, width: number): string[] => renderIdentitySection(view, theme, width), - }, -]; - -function buildDetailSections(state: WidgetState, theme: Theme, width: number): DetailSections { - const core: string[] = []; - const footer: string[] = []; - const blank = clampToWidth("", width); - - for (const section of DETAIL_SECTION_REGISTRY) { - const view = section.select(state); - if (!view) continue; - - const rendered = section.render(view, theme, width).map((line) => clampToWidth(line, width)); - if (section.placement === "core") { - if (rendered.length === 0) continue; - if (core.length > 0 && core[core.length - 1].trim() !== "") { - core.push(blank); - } - core.push(...rendered); - continue; - } - - footer.push(...rendered); - } - - return { core, footer }; -} - -function layoutDetailColumn(sections: DetailSections, width: number, targetRows: number): string[] { - const blank = clampToWidth("", width); - const lines = [...sections.core]; - - if (sections.footer.length > 0) { - if (lines.length === 0 || lines[lines.length - 1].trim() !== "") { - lines.push(blank); - } - } - - const used = lines.length + sections.footer.length; - const goal = Math.max(targetRows, used); - - while (lines.length < goal - sections.footer.length) { - lines.push(blank); - } - - if (sections.footer.length === 0) { - return lines; - } - - return [...lines, ...sections.footer]; -} - -function renderBox( - titleLeft: string, - titleRight: string, - body: string[], - width: number, - theme: Theme, - border: BorderStyle = BORDER_SOLID, -): string[] { - const innerWidth = Math.max(0, width - 2); - const left = visibleWidth(titleLeft) > innerWidth ? truncateToWidth(titleLeft, innerWidth, "", false) : titleLeft; - const right = visibleWidth(titleRight) > innerWidth ? truncateToWidth(titleRight, innerWidth, "", false) : titleRight; - const headerContent = rightAlign(left, right, innerWidth); - - const top = `${border.topLeft}${clampToWidth(headerContent, innerWidth)}${border.topRight}`; - const bottom = `${border.bottomLeft}${clampToWidth(border.horizontal.repeat(innerWidth), innerWidth)}${border.bottomRight}`; - - const content = body.map((line) => `${border.vertical}${clampToWidth(line, innerWidth)}${border.vertical}`); - return [top, ...content, bottom]; -} - -function renderBoxWithHeaderRow( - headerLeft: string, - headerRight: string, - body: string[], - width: number, - border: BorderStyle = BORDER_SOLID, -): string[] { - const innerWidth = Math.max(0, width - 2); - const left = visibleWidth(headerLeft) > innerWidth ? truncateToWidth(headerLeft, innerWidth, "", false) : headerLeft; - const right = visibleWidth(headerRight) > innerWidth ? truncateToWidth(headerRight, innerWidth, "", false) : headerRight; - const headerContent = rightAlign(left, right, innerWidth); - - const top = `${border.topLeft}${clampToWidth(border.horizontal.repeat(innerWidth), innerWidth)}${border.topRight}`; - const header = `${border.vertical}${clampToWidth(headerContent, innerWidth)}${border.vertical}`; - const headerDivider = `${border.vertical}${clampToWidth(border.horizontal.repeat(innerWidth), innerWidth)}${border.vertical}`; - const content = body.map((line) => `${border.vertical}${clampToWidth(line, innerWidth)}${border.vertical}`); - const bottom = `${border.bottomLeft}${clampToWidth(border.horizontal.repeat(innerWidth), innerWidth)}${border.bottomRight}`; - - return [top, header, headerDivider, ...content, bottom]; -} - -function renderPlanningCard(state: WidgetState, theme: Theme, width: number): string[] { - const elapsed = theme.fg("dim", formatElapsed(Date.now() - state.startedAt)); - const { innerWidth, contentWidth, timelineWidth, detailWidth } = planningColumns(width); - const titleLeft = renderPlanningHeader(state, theme, Math.max(0, innerWidth - visibleWidth(elapsed) - 1)); - - if (innerWidth < 60 || contentWidth < 40) { - const fallbackContent: string[] = [ - "", - theme.fg("muted", `Plan · ${state.planId}`), - "", - formatStepLine(state, theme), - ]; - const runtimeCompact = formatRuntimeCompact(state, theme, contentWidth); - if (runtimeCompact.length > 0) { - fallbackContent.push(...runtimeCompact); - } - - fallbackContent.push(""); - fallbackContent.push(...formatIdentityCompact(state, theme, contentWidth)); - fallbackContent.push(""); - - const body = indentLines(fallbackContent, innerWidth); - return renderBox( - `${BODY_INDENT}${titleLeft}`, - elapsed, - body, - width, - theme, - ); - } - - const timelineLines = renderTimelineLines(state, theme, timelineWidth); - const detailSections = buildDetailSections(state, theme, detailWidth); - const detailLines = layoutDetailColumn(detailSections, detailWidth, timelineLines.length); - const combined: string[] = []; - const maxLines = Math.max(timelineLines.length, detailLines.length); - - for (let i = 0; i < maxLines; i++) { - const left = timelineLines[i] ?? ""; - const right = detailLines[i] ?? ""; - const composed = `${clampToWidth(left, timelineWidth)}${" ".repeat(COLUMN_GAP)}${clampToWidth(right, detailWidth)}`; - combined.push(clampToWidth(composed, contentWidth)); - } - - const body = indentLines( - [ - "", - ...combined, - "", - ], - innerWidth, - ); - - return renderBox( - `${BODY_INDENT}${titleLeft}`, - elapsed, - body, - width, - theme, - ); -} - -function wrapRightColumn(entry: LogLine, width: number): string[] { - const summary = entry.summary.trim(); - if (!summary) return [""]; - - if (!entry.highValue) { - return [clampToWidth(summary, width, "…")]; - } - - const wrapped = wrapTextWithAnsi(summary, width).map((line) => clampToWidth(line, width, "…")); - if (wrapped.length <= 1) return wrapped; - if (wrapped.length === 2) return wrapped; - - const tail = wrapped.slice(1).join(" ").replace(/\s+/gu, " ").trim(); - return [wrapped[0], clampToWidth(truncateToWidth(tail, width, "…", false), width)]; -} - -function renderLogEntry(entry: LogLine, theme: Theme, leftWidth: number, rightWidth: number, gap: number): string[] { - const rightLines = wrapRightColumn(entry, rightWidth); - const rows: string[] = []; - - rightLines.forEach((line, index) => { - const left = index === 0 - ? theme.bold(theme.fg("accent", entry.tool)) - : ""; - const composed = `${clampToWidth(left, leftWidth)}${" ".repeat(gap)}${clampToWidth(theme.fg("muted", line), rightWidth)}`; - rows.push(composed); - }); - - return rows; -} - -interface LogColumns { - left: number; - right: number; - gap: number; -} - -function logColumnWidths(availableWidth: number, entries: readonly LogLine[], gap: number): LogColumns { - const longestTool = entries.reduce((max, entry) => Math.max(max, visibleWidth(entry.tool)), 0); - const preferredLeft = Math.max(16, Math.min(38, longestTool + 2)); - - const minRight = availableWidth < 64 ? 18 : 24; - let left = Math.min(preferredLeft, Math.floor(availableWidth * 0.42)); - left = Math.min(left, Math.max(14, availableWidth - minRight - gap)); - left = Math.max(14, left); - - const right = Math.max(8, availableWidth - left - gap); - return { left, right, gap }; -} - -function renderLogCard(state: WidgetState, theme: Theme, width: number, forcedColumns?: LogColumns): string[] { - const innerWidth = Math.max(0, width - 2); - const availableWidth = Math.max(0, innerWidth - visibleWidth(BODY_INDENT)); - const hasEntries = state.logLines.length > 0; - const entries = hasEntries ? state.logLines.slice(-(LOG_LINES * 2)) : []; - - const columns = forcedColumns ?? logColumnWidths(availableWidth, entries, 2); - const leftWidth = Math.max(8, Math.min(columns.left, Math.max(8, availableWidth - columns.gap - 8))); - const rightWidth = Math.max(8, availableWidth - leftWidth - columns.gap); - - const visualRows: string[] = []; - if (entries.length > 0) { - const rendered = entries.map((entry) => renderLogEntry(entry, theme, leftWidth, rightWidth, columns.gap)); - const selected: string[][] = []; - let remaining = LOG_LINES; - - for (let i = rendered.length - 1; i >= 0; i--) { - if (remaining <= 0) break; - const rowLines = rendered[i]; - if (rowLines.length <= remaining) { - selected.push(rowLines); - remaining -= rowLines.length; - } else { - selected.push(rowLines.slice(0, remaining)); - remaining = 0; - } - } - - selected.reverse(); - for (const lines of selected) { - visualRows.push(...lines); - } - } - - if (visualRows.length === 0) { - visualRows.push(clampToWidth(theme.fg("muted", LOG_PLACEHOLDER), innerWidth)); - } - - while (visualRows.length < LOG_LINES) { - visualRows.push(""); - } - - const body = indentLines(visualRows, innerWidth); - return renderBox( - `${BODY_INDENT}${theme.bold(theme.fg("accent", "Latest log"))}`, - "", - body, - width, - theme, - ); -} - -function formatRuntimeCompact(state: WidgetState, theme: Theme, width: number): string[] { - if (!shouldShowRuntimeSection(state)) return []; - return renderRuntimeStatusSection(state, theme, width); -} - -function formatIdentityCompact(state: WidgetState, theme: Theme, width: number): string[] { - return renderIdentitySection(identityView(state), theme, width); -} - -function formatStepLine(state: WidgetState, theme: Theme): string { - const total = state.phases.length; - const active = activePhase(state); - const stepNumber = state.activeIndex >= 0 ? state.activeIndex + 1 : total; - const count = theme.fg("muted", `Step ${stepNumber} of ${total}`); - const label = active - ? theme.bold(theme.fg("accent", active.label)) - : theme.bold(theme.fg("muted", "Complete")); - return `${count} ${theme.fg("muted", "·")} ${label}`; -} - -// Pure render: (state, theme, termWidth) -> lines. No side effects. -function stripBoxFrame(lines: string[]): string[] { - if (lines.length <= 2) return []; - return lines.slice(1, -1).map((line) => (line.length >= 2 ? line.slice(1, -1) : "")); -} - -function renderIntegratedWorkspaceCard(state: WidgetState, theme: Theme, width: number): string[] { - const innerWidth = Math.max(0, width - 2); - const elapsed = theme.fg("dim", formatElapsed(Date.now() - state.startedAt)); - - const { innerWidth: planningInnerWidth, contentWidth, timelineWidth, detailWidth } = planningColumns(width); - const alignedColumns: LogColumns | undefined = planningInnerWidth >= 60 && contentWidth >= 40 - ? { left: timelineWidth, right: detailWidth, gap: COLUMN_GAP } - : undefined; - - const planningInner = stripBoxFrame(renderPlanningCard(state, theme, width)); - const logInner = stripBoxFrame(renderLogCard(state, theme, width, alignedColumns)); - - const divider = clampToWidth(theme.fg("muted", "─".repeat(innerWidth)), innerWidth); - const spacer = clampToWidth("", innerWidth); - const logTitle = clampToWidth(`${BODY_INDENT}${theme.bold(theme.fg("accent", "Latest log"))}`, innerWidth, "…"); - - const body = [ - ...planningInner, - divider, - spacer, - logTitle, - ...logInner, - ]; - - const rightInset = " ".repeat(visibleWidth(BODY_INDENT)); - const titleLeftBudget = Math.max( - 0, - innerWidth - visibleWidth(elapsed) - visibleWidth(rightInset) - 1 - visibleWidth(BODY_INDENT), - ); - const titleLeft = renderPlanningHeader(state, theme, titleLeftBudget); - - return renderBoxWithHeaderRow( - `${BODY_INDENT}${titleLeft}`, - `${elapsed}${rightInset}`, - body, - width, - ); -} - -// Pure render: (state, theme, termWidth) -> lines. No side effects. -function render(state: WidgetState, theme: Theme, termWidth: number): string[] { - const c = (s: string) => canvasLine(s, termWidth, theme); - const cw = contentWidth(termWidth); - const lines: string[] = []; - const margin = " ".repeat(CARD_MARGIN); - - lines.push(c("")); - for (const line of renderIntegratedWorkspaceCard(state, theme, cw - CARD_MARGIN)) { - lines.push(c(margin + line)); - } - lines.push(c("")); - - return lines; -} - -// -- WidgetController -- - -export class WidgetController { - private state: WidgetState; - private lastHash = ""; - private timer: ReturnType; - private ui: ExtensionUIContext; - - constructor(ui: ExtensionUIContext, planId: string) { - this.ui = ui; - this.state = { - mode: "planning", - planId, - phases: PLANNING_PHASES.map((p) => ({ key: p.key, label: p.label, detail: p.detail, status: "pending" as PhaseStatus })), - activeIndex: 0, - step: "", - activity: "", - startedAt: Date.now(), - logLines: [], - qrIteration: null, - qrIterationsMax: null, - qrMode: null, - qrPhase: "idle", - qrDone: null, - qrTotal: null, - qrPass: null, - qrFail: null, - qrTodo: null, - subagentRole: null, - subagentModel: null, - subagentParallelCount: null, - subagentQueued: null, - subagentActive: null, - subagentDone: null, - }; - this.state.phases[0].status = "running"; - - this.timer = setInterval(() => this.doRender(), 1000); - this.timer.unref(); - - this.doRender(); - } - - update(patch: WidgetUpdate): void { - if (patch.mode !== undefined) { - this.state.mode = patch.mode; - } - if (patch.phaseStatus !== undefined) { - const { index, status } = patch.phaseStatus; - if (index >= 0 && index < this.state.phases.length) { - this.state.phases[index].status = status; - } - } - if (patch.activeIndex !== undefined) { - this.state.activeIndex = patch.activeIndex; - const ai = patch.activeIndex; - if (ai >= 0 && ai < this.state.phases.length && this.state.phases[ai].status === "pending") { - this.state.phases[ai].status = "running"; - } - } - if (patch.step !== undefined) { - this.state.step = patch.step; - } - if (patch.activity !== undefined) { - this.state.activity = patch.activity; - } - if (patch.logLines !== undefined) { - this.state.logLines = normalizeLogLines(patch.logLines); - } - if (patch.qrIteration !== undefined) { - this.state.qrIteration = patch.qrIteration; - } - if (patch.qrIterationsMax !== undefined) { - this.state.qrIterationsMax = patch.qrIterationsMax; - } - if (patch.qrMode !== undefined) { - this.state.qrMode = patch.qrMode; - } - if (patch.qrPhase !== undefined) { - this.state.qrPhase = patch.qrPhase; - } - if (patch.qrDone !== undefined) { - this.state.qrDone = patch.qrDone; - } - if (patch.qrTotal !== undefined) { - this.state.qrTotal = patch.qrTotal; - } - if (patch.qrPass !== undefined) { - this.state.qrPass = patch.qrPass; - } - if (patch.qrFail !== undefined) { - this.state.qrFail = patch.qrFail; - } - if (patch.qrTodo !== undefined) { - this.state.qrTodo = patch.qrTodo; - } - if (patch.subagentRole !== undefined) { - this.state.subagentRole = patch.subagentRole; - } - if (patch.subagentModel !== undefined) { - this.state.subagentModel = patch.subagentModel; - } - if (patch.subagentParallelCount !== undefined) { - this.state.subagentParallelCount = patch.subagentParallelCount; - } - if (patch.subagentQueued !== undefined) { - this.state.subagentQueued = patch.subagentQueued; - } - if (patch.subagentActive !== undefined) { - this.state.subagentActive = patch.subagentActive; - } - if (patch.subagentDone !== undefined) { - this.state.subagentDone = patch.subagentDone; - } - this.doRender(); - } - - destroy(): void { - clearInterval(this.timer); - this.ui.setWidget(WIDGET_KEY, undefined); - } - - private doRender(): void { - // Capture state snapshot for the factory closure - const state = { - ...this.state, - phases: this.state.phases.map((p) => ({ ...p })), - logLines: this.state.logLines.map((l) => ({ ...l })), - }; - const theme = this.ui.theme; - - // Hash check: skip setWidget if content unchanged (ignoring width) - const hashLines = render(state, theme, 0); - const hash = hashLines.join("\n"); - if (hash === this.lastHash) return; - this.lastHash = hash; - - // Component factory: Pi calls render(width) with actual terminal width - this.ui.setWidget(WIDGET_KEY, (_tui, th) => ({ - render: (width: number) => render(state, th, width), - invalidate: () => {}, - })); - } -} diff --git a/src/utils/lock.ts b/src/utils/lock.ts deleted file mode 100644 index 47ed858..0000000 --- a/src/utils/lock.ts +++ /dev/null @@ -1,44 +0,0 @@ -import { promises as fs } from "node:fs"; - -// Advisory .lock file for serializing file mutations. Uses O_CREAT|O_EXCL -// for atomic creation (fails if lock already exists). Retry with backoff -// handles transient contention (e.g. parallel QR verifiers). - -const RETRY_INTERVAL_MS = 50; -const MAX_WAIT_MS = 5000; - -function lockPath(filePath: string): string { - return `${filePath}.lock`; -} - -async function acquire(filePath: string): Promise { - const lp = lockPath(filePath); - const deadline = Date.now() + MAX_WAIT_MS; - - while (true) { - try { - const fd = await fs.open(lp, "wx"); - await fd.close(); - return; - } catch (err: unknown) { - if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err; - if (Date.now() >= deadline) { - throw new Error(`Failed to acquire lock on ${filePath} after ${MAX_WAIT_MS}ms`); - } - await new Promise((r) => setTimeout(r, RETRY_INTERVAL_MS)); - } - } -} - -async function release(filePath: string): Promise { - await fs.rm(lockPath(filePath), { force: true }); -} - -export async function withFileLock(filePath: string, fn: () => Promise): Promise { - await acquire(filePath); - try { - return await fn(); - } finally { - await release(filePath); - } -} diff --git a/src/utils/plan.ts b/src/utils/plan.ts deleted file mode 100644 index a34f382..0000000 --- a/src/utils/plan.ts +++ /dev/null @@ -1,72 +0,0 @@ -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; - -import type { PlanInfo } from "../planner/state.js"; - -const KOAN_HOME = path.join(os.homedir(), ".koan"); -const PLANS_HOME = path.join(KOAN_HOME, "plans"); - -function slugify(input: string): string { - const base = input - .toLowerCase() - .replace(/[^a-z0-9]+/g, "-") - .replace(/^-+|-+$/g, "") - .slice(0, 48); - - return base.length > 0 ? base : "plan"; -} - -function generatePlanId(description: string, now: Date): string { - const timestamp = now.toISOString().replace(/[-:]/g, "").replace(/\..+/, ""); - const slug = slugify(description); - return `${timestamp}-${slug}`; -} - -async function ensurePlanDirectoryUnique(baseId: string): Promise<{ id: string; directory: string }> { - let suffix = 0; - while (true) { - const candidateId = suffix === 0 ? baseId : `${baseId}-${suffix}`; - const directory = path.join(PLANS_HOME, candidateId); - - try { - await fs.mkdir(directory, { recursive: false }); - return { id: candidateId, directory }; - } catch (error) { - const err = error as NodeJS.ErrnoException; - if (err.code === "EEXIST") { - suffix += 1; - continue; - } - throw error; - } - } -} - -export async function createPlanInfo(description: string, projectCwd: string, now = new Date()): Promise { - await fs.mkdir(PLANS_HOME, { recursive: true }); - - const baseId = generatePlanId(description, now); - const { id, directory } = await ensurePlanDirectoryUnique(baseId); - - const metadataPath = path.join(directory, "metadata.json"); - - const plan: PlanInfo = { - id, - directory, - metadataPath, - createdAt: now.toISOString(), - }; - - const metadata = { - id: plan.id, - createdAt: plan.createdAt, - description, - status: "created" as const, - projectCwd, - }; - - await fs.writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8"); - - return plan; -} diff --git a/src/utils/progress.ts b/src/utils/progress.ts deleted file mode 100644 index 2940ecc..0000000 --- a/src/utils/progress.ts +++ /dev/null @@ -1,14 +0,0 @@ -// Directory infrastructure for subagent working directories. -// Audit state (state.json, events.jsonl) is managed by EventLog in lib/audit.ts. -// This module is retained for createSubagentDir, used by session.ts. - -import { promises as fs } from "node:fs"; -import * as crypto from "node:crypto"; -import * as path from "node:path"; - -export async function createSubagentDir(planDir: string, role: string): Promise { - const hex = crypto.randomBytes(2).toString("hex"); - const dir = path.join(planDir, "subagents", `${role}-${hex}`); - await fs.mkdir(dir, { recursive: true }); - return dir; -} From ef195bce06cd94f46a23471395bdd686c62e603a Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Mar 2026 12:46:26 +0700 Subject: [PATCH 046/412] test(planner): replace legacy coverage with state-machine tests --- tests/model-config.test.ts | 233 -------------- tests/model-phase.test.ts | 135 -------- tests/model-resolver.test.ts | 164 ---------- tests/progress.test.ts | 321 -------------------- tests/qr-grouped-verify.test.ts | 304 ------------------- tests/session-model-threading.test.ts | 205 ------------- tests/state-machine.test.ts | 422 ++++++++++++++++++++++++++ tests/story-discovery.test.ts | 84 +++++ tests/subagent-model.test.ts | 215 ------------- tests/widget.test.ts | 173 ----------- 10 files changed, 506 insertions(+), 1750 deletions(-) delete mode 100644 tests/model-config.test.ts delete mode 100644 tests/model-phase.test.ts delete mode 100644 tests/model-resolver.test.ts delete mode 100644 tests/progress.test.ts delete mode 100644 tests/qr-grouped-verify.test.ts delete mode 100644 tests/session-model-threading.test.ts create mode 100644 tests/state-machine.test.ts create mode 100644 tests/story-discovery.test.ts delete mode 100644 tests/subagent-model.test.ts delete mode 100644 tests/widget.test.ts diff --git a/tests/model-config.test.ts b/tests/model-config.test.ts deleted file mode 100644 index a7e949f..0000000 --- a/tests/model-config.test.ts +++ /dev/null @@ -1,233 +0,0 @@ -import assert from "node:assert/strict"; -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; -import { describe, it } from "node:test"; - -import { ALL_PHASE_MODEL_KEYS, type PhaseModelKey } from "../src/planner/model-phase.js"; -import { loadPhaseModelConfig, savePhaseModelConfig } from "../src/planner/model-config.js"; - -function makeFullConfig(model = "anthropic/claude-sonnet"): Record { - const config: Partial> = {}; - for (const key of ALL_PHASE_MODEL_KEYS) { - config[key] = model; - } - return config as Record; -} - -// Test config validation logic directly using a mock config file -// by writing to a temp location and reading back. -// Note: loadPhaseModelConfig reads from ~/.koan/config.json, so we -// test validation using the raw parsing logic via an in-process approach. - -describe("config validation", () => { - it("accepts a complete 20-key config and returns it unchanged", async () => { - // We test the validation by round-tripping through save/load. - // To avoid touching ~/.koan/config.json, we verify the pure logic - // by testing that a valid config object has all required keys. - const config = makeFullConfig("anthropic/claude-opus-4"); - - // Verify it has exactly 20 keys - assert.equal(Object.keys(config).length, ALL_PHASE_MODEL_KEYS.length); - - // Verify all keys are valid PhaseModelKeys - for (const key of Object.keys(config)) { - assert.ok( - (ALL_PHASE_MODEL_KEYS as readonly string[]).includes(key), - `unexpected key: ${key}`, - ); - } - - // Verify all values are non-empty strings - for (const [key, value] of Object.entries(config)) { - assert.equal(typeof value, "string", `value for ${key} should be a string`); - assert.ok(value.length > 0, `value for ${key} should be non-empty`); - } - }); - - it("treats null as valid (no overrides)", () => { - // Null config is valid — it means inherit from pi's active model - const config: Record | null = null; - assert.equal(config, null); - }); -}); - -describe("loadPhaseModelConfig (integration)", () => { - it("returns null when config file is missing", async () => { - // loadPhaseModelConfig reads ~/.koan/config.json - if it doesn't exist, null - // We can only test this if ~/.koan/config.json doesn't exist on this machine - // or has no phaseModels. This is an integration test, so we skip the file check - // and instead verify the contract: the function always returns null or a valid config. - const result = await loadPhaseModelConfig(); - // Result is either null or a Record with exactly 20 keys - if (result !== null) { - assert.equal(Object.keys(result).length, ALL_PHASE_MODEL_KEYS.length); - for (const key of ALL_PHASE_MODEL_KEYS) { - assert.equal(typeof result[key], "string"); - assert.ok(result[key].length > 0); - } - } - }); -}); - -describe("savePhaseModelConfig + loadPhaseModelConfig (round-trip)", () => { - it("persists a full config and reads it back correctly", async () => { - // KOAN_CONFIG_PATH is computed at module load time, so tests validate - // round-trip behavior against the real path and restore prior state. - - const actualConfigPath = path.join(os.homedir(), ".koan", "config.json"); - let preExisting: string | null = null; - - try { - preExisting = await fs.readFile(actualConfigPath, "utf8"); - } catch { - preExisting = null; - } - - try { - const config = makeFullConfig("openai/gpt-5"); - await savePhaseModelConfig(config); - - const loaded = await loadPhaseModelConfig(); - assert.ok(loaded !== null, "expected config to be loaded after save"); - assert.equal(Object.keys(loaded).length, ALL_PHASE_MODEL_KEYS.length); - - for (const key of ALL_PHASE_MODEL_KEYS) { - assert.equal(loaded[key], "openai/gpt-5", `mismatch for key ${key}`); - } - } finally { - // Restore original state - if (preExisting === null) { - try { - const koanDir = path.join(os.homedir(), ".koan"); - await fs.rm(actualConfigPath, { force: true }); - // Try to remove the .koan dir if it was empty before - const entries = await fs.readdir(koanDir); - if (entries.length === 0) { - await fs.rmdir(koanDir); - } - } catch { - // Best-effort cleanup - } - } else { - await fs.writeFile(actualConfigPath, preExisting, "utf8"); - } - - } - }); - - it("persists null (clears overrides) while preserving other config keys", async () => { - const actualConfigPath = path.join(os.homedir(), ".koan", "config.json"); - let preExisting: string | null = null; - - try { - preExisting = await fs.readFile(actualConfigPath, "utf8"); - } catch { - preExisting = null; - } - - try { - // Write an initial config - await savePhaseModelConfig(makeFullConfig("anthropic/claude-sonnet")); - - // Now clear it - await savePhaseModelConfig(null); - - const loaded = await loadPhaseModelConfig(); - assert.equal(loaded, null, "expected null after clearing overrides"); - - // Verify the config file still exists but has no phaseModels key - const raw = await fs.readFile(actualConfigPath, "utf8"); - const parsed = (raw.trim().length === 0 ? {} : JSON.parse(raw)) as Record; - assert.equal("phaseModels" in parsed, false, "phaseModels should be absent after clearing"); - } finally { - if (preExisting === null) { - try { - await fs.rm(actualConfigPath, { force: true }); - } catch { - // Best-effort - } - } else { - await fs.writeFile(actualConfigPath, preExisting, "utf8"); - } - } - }); -}); - -describe("config validation: partial config treated as absent", () => { - it("validates that a partial config (missing keys) is treated as absent", async () => { - // We simulate this by checking the validation logic: - // A config with fewer than 20 keys should produce null from loadPhaseModelConfig. - // We test this indirectly by verifying the contract. - const partialKeys = ALL_PHASE_MODEL_KEYS.slice(0, 10); - assert.equal(partialKeys.length, 10); - assert.equal(partialKeys.length < ALL_PHASE_MODEL_KEYS.length, true); - - // A partial config would fail the length check in loadPhaseModelConfig. - // We verify this by writing a partial config and reading it back. - const actualConfigPath = path.join(os.homedir(), ".koan", "config.json"); - let preExisting: string | null = null; - - try { - preExisting = await fs.readFile(actualConfigPath, "utf8"); - } catch { - preExisting = null; - } - - try { - await fs.mkdir(path.dirname(actualConfigPath), { recursive: true }); - const partial: Record = {}; - for (const key of partialKeys) { - partial[key] = "anthropic/claude-sonnet"; - } - await fs.writeFile(actualConfigPath, JSON.stringify({ phaseModels: partial }), "utf8"); - - const loaded = await loadPhaseModelConfig(); - assert.equal(loaded, null, "expected null for partial config"); - } finally { - if (preExisting === null) { - try { await fs.rm(actualConfigPath, { force: true }); } catch { /* best-effort */ } - } else { - await fs.writeFile(actualConfigPath, preExisting, "utf8"); - } - } - }); - - it("validates that a config with unknown keys is treated as absent", async () => { - const actualConfigPath = path.join(os.homedir(), ".koan", "config.json"); - let preExisting: string | null = null; - - try { - preExisting = await fs.readFile(actualConfigPath, "utf8"); - } catch { - preExisting = null; - } - - try { - await fs.mkdir(path.dirname(actualConfigPath), { recursive: true }); - - // Build a 20-key config with one key replaced by an unknown key - const badConfig: Record = {}; - let first = true; - for (const key of ALL_PHASE_MODEL_KEYS) { - if (first) { - badConfig["unknown-phase-exec-debut"] = "anthropic/claude-sonnet"; - first = false; - } else { - badConfig[key] = "anthropic/claude-sonnet"; - } - } - - await fs.writeFile(actualConfigPath, JSON.stringify({ phaseModels: badConfig }), "utf8"); - - const loaded = await loadPhaseModelConfig(); - assert.equal(loaded, null, "expected null for config with unknown key"); - } finally { - if (preExisting === null) { - try { await fs.rm(actualConfigPath, { force: true }); } catch { /* best-effort */ } - } else { - await fs.writeFile(actualConfigPath, preExisting, "utf8"); - } - } - }); -}); diff --git a/tests/model-phase.test.ts b/tests/model-phase.test.ts deleted file mode 100644 index 9797d49..0000000 --- a/tests/model-phase.test.ts +++ /dev/null @@ -1,135 +0,0 @@ -import assert from "node:assert/strict"; -import { describe, it } from "node:test"; - -import { - ALL_PHASE_MODEL_KEYS, - GENERAL_PURPOSE_PHASE_MODEL_KEYS, - PHASE_ROWS, - STRONG_PHASE_MODEL_KEYS, - SUB_PHASES, - buildPhaseModelKey, - isPhaseModelKey, - type PhaseModelKey, -} from "../src/planner/model-phase.js"; - -describe("ALL_PHASE_MODEL_KEYS", () => { - it("contains exactly 20 keys (5 rows × 4 sub-phases)", () => { - assert.equal(ALL_PHASE_MODEL_KEYS.length, PHASE_ROWS.length * SUB_PHASES.length); - assert.equal(ALL_PHASE_MODEL_KEYS.length, 20); - }); - - it("contains no duplicates", () => { - const set = new Set(ALL_PHASE_MODEL_KEYS); - assert.equal(set.size, ALL_PHASE_MODEL_KEYS.length); - }); - - it("contains every combination of row and sub-phase", () => { - for (const row of PHASE_ROWS) { - for (const sub of SUB_PHASES) { - const key = `${row}-${sub}` as PhaseModelKey; - assert.ok( - ALL_PHASE_MODEL_KEYS.includes(key), - `expected key "${key}" to be present`, - ); - } - } - }); -}); - -describe("STRONG_PHASE_MODEL_KEYS", () => { - it("contains exactly 9 keys", () => { - assert.equal(STRONG_PHASE_MODEL_KEYS.size, 9); - }); - - it("contains all 5 qr-decompose keys", () => { - for (const row of PHASE_ROWS) { - const key = buildPhaseModelKey(row, "qr-decompose"); - assert.ok(STRONG_PHASE_MODEL_KEYS.has(key), `expected ${key} to be strong`); - } - }); - - it("contains plan-design exec-debut and exec-fix", () => { - assert.ok(STRONG_PHASE_MODEL_KEYS.has("plan-design-exec-debut")); - assert.ok(STRONG_PHASE_MODEL_KEYS.has("plan-design-exec-fix")); - }); - - it("contains exec-docs exec-debut and exec-fix", () => { - assert.ok(STRONG_PHASE_MODEL_KEYS.has("exec-docs-exec-debut")); - assert.ok(STRONG_PHASE_MODEL_KEYS.has("exec-docs-exec-fix")); - }); - - it("does not contain plan-code or plan-docs exec keys", () => { - assert.equal(STRONG_PHASE_MODEL_KEYS.has("plan-code-exec-debut"), false); - assert.equal(STRONG_PHASE_MODEL_KEYS.has("plan-code-exec-fix"), false); - assert.equal(STRONG_PHASE_MODEL_KEYS.has("plan-docs-exec-debut"), false); - assert.equal(STRONG_PHASE_MODEL_KEYS.has("plan-docs-exec-fix"), false); - }); -}); - -describe("GENERAL_PURPOSE_PHASE_MODEL_KEYS", () => { - it("contains exactly 11 keys (20 total - 9 strong)", () => { - assert.equal(GENERAL_PURPOSE_PHASE_MODEL_KEYS.length, 11); - }); - - it("strong and GP form a complete partition of all keys", () => { - const strongSet = STRONG_PHASE_MODEL_KEYS; - const gpSet = new Set(GENERAL_PURPOSE_PHASE_MODEL_KEYS); - - // Union equals ALL - for (const key of ALL_PHASE_MODEL_KEYS) { - assert.ok( - strongSet.has(key) || gpSet.has(key), - `key "${key}" missing from both sets`, - ); - } - - // Intersection is empty - for (const key of ALL_PHASE_MODEL_KEYS) { - assert.equal( - strongSet.has(key) && gpSet.has(key), - false, - `key "${key}" appears in both sets`, - ); - } - }); -}); - -describe("isPhaseModelKey", () => { - it("returns true for valid keys", () => { - for (const key of ALL_PHASE_MODEL_KEYS) { - assert.equal(isPhaseModelKey(key), true, `expected "${key}" to be valid`); - } - }); - - it("returns false for invalid strings", () => { - assert.equal(isPhaseModelKey("plan-design"), false); - assert.equal(isPhaseModelKey("exec-debut"), false); - assert.equal(isPhaseModelKey("plan-design-exec-init"), false); - assert.equal(isPhaseModelKey("unknown-key"), false); - assert.equal(isPhaseModelKey(""), false); - }); - - it("returns false for non-string values", () => { - assert.equal(isPhaseModelKey(42), false); - assert.equal(isPhaseModelKey(null), false); - assert.equal(isPhaseModelKey(undefined), false); - assert.equal(isPhaseModelKey({}), false); - }); -}); - -describe("buildPhaseModelKey", () => { - it("produces correct key for all combinations", () => { - assert.equal(buildPhaseModelKey("plan-design", "exec-debut"), "plan-design-exec-debut"); - assert.equal(buildPhaseModelKey("exec-docs", "qr-verify"), "exec-docs-qr-verify"); - assert.equal(buildPhaseModelKey("plan-code", "qr-decompose"), "plan-code-qr-decompose"); - }); - - it("produces keys that pass isPhaseModelKey", () => { - for (const row of PHASE_ROWS) { - for (const sub of SUB_PHASES) { - const key = buildPhaseModelKey(row, sub); - assert.equal(isPhaseModelKey(key), true, `buildPhaseModelKey(${row}, ${sub}) = "${key}" failed isPhaseModelKey`); - } - } - }); -}); diff --git a/tests/model-resolver.test.ts b/tests/model-resolver.test.ts deleted file mode 100644 index b37ef35..0000000 --- a/tests/model-resolver.test.ts +++ /dev/null @@ -1,164 +0,0 @@ -import assert from "node:assert/strict"; -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; -import { describe, it } from "node:test"; - -import { - ALL_PHASE_MODEL_KEYS, - PHASE_ROWS, - SUB_PHASES, - type PhaseModelKey, -} from "../src/planner/model-phase.js"; -import { - mapSpawnContextToPhaseModelKey, - resolvePhaseModelOverride, - type SpawnContext, -} from "../src/planner/model-resolver.js"; - -describe("mapSpawnContextToPhaseModelKey", () => { - it("maps work-debut to exec-debut for all phase rows", () => { - for (const row of PHASE_ROWS) { - const key = mapSpawnContextToPhaseModelKey("work-debut", row); - assert.equal(key, `${row}-exec-debut`, `row=${row}`); - } - }); - - it("maps fix to exec-fix for all phase rows", () => { - for (const row of PHASE_ROWS) { - const key = mapSpawnContextToPhaseModelKey("fix", row); - assert.equal(key, `${row}-exec-fix`, `row=${row}`); - } - }); - - it("maps qr-decompose to qr-decompose for all phase rows", () => { - for (const row of PHASE_ROWS) { - const key = mapSpawnContextToPhaseModelKey("qr-decompose", row); - assert.equal(key, `${row}-qr-decompose`, `row=${row}`); - } - }); - - it("maps qr-verify to qr-verify for all phase rows", () => { - for (const row of PHASE_ROWS) { - const key = mapSpawnContextToPhaseModelKey("qr-verify", row); - assert.equal(key, `${row}-qr-verify`, `row=${row}`); - } - }); - - it("produces keys that are valid PhaseModelKeys", () => { - const contexts: SpawnContext[] = ["work-debut", "fix", "qr-decompose", "qr-verify"]; - for (const context of contexts) { - for (const row of PHASE_ROWS) { - const key = mapSpawnContextToPhaseModelKey(context, row); - assert.ok( - (ALL_PHASE_MODEL_KEYS as readonly string[]).includes(key), - `key "${key}" (context=${context}, row=${row}) is not a valid PhaseModelKey`, - ); - } - } - }); - - it("covers all 20 PhaseModelKeys across context × row combinations", () => { - const produced = new Set(); - const contexts: SpawnContext[] = ["work-debut", "fix", "qr-decompose", "qr-verify"]; - for (const context of contexts) { - for (const row of PHASE_ROWS) { - produced.add(mapSpawnContextToPhaseModelKey(context, row)); - } - } - assert.equal(produced.size, ALL_PHASE_MODEL_KEYS.length); - for (const key of ALL_PHASE_MODEL_KEYS) { - assert.ok(produced.has(key), `key "${key}" not produced by any context × row combination`); - } - }); - - it("accepts optional fixPhase argument without altering output", () => { - const withoutFix = mapSpawnContextToPhaseModelKey("fix", "plan-design"); - const withFix = mapSpawnContextToPhaseModelKey("fix", "plan-design", "plan-design"); - assert.equal(withoutFix, withFix); - }); -}); - -describe("SpawnContext values cover all sub-phases", () => { - it("one SpawnContext maps to each SubPhase", () => { - const contexts: SpawnContext[] = ["work-debut", "fix", "qr-decompose", "qr-verify"]; - const row = "plan-design"; - const subPhasesProduced = contexts.map((c) => { - const key = mapSpawnContextToPhaseModelKey(c, row); - return key.replace(`${row}-`, "") as typeof SUB_PHASES[number]; - }); - - for (const sub of SUB_PHASES) { - assert.ok( - subPhasesProduced.includes(sub), - `sub-phase "${sub}" not covered by any SpawnContext`, - ); - } - }); -}); - -function makeFullConfig(model: string): Record { - const config: Partial> = {}; - for (const key of ALL_PHASE_MODEL_KEYS) { - config[key] = model; - } - return config as Record; -} - -async function withConfigFile( - setup: (configPath: string) => Promise, - run: () => Promise, -): Promise { - const configPath = path.join(os.homedir(), ".koan", "config.json"); - - let preExisting: string | null = null; - try { - preExisting = await fs.readFile(configPath, "utf8"); - } catch { - preExisting = null; - } - - try { - await fs.mkdir(path.dirname(configPath), { recursive: true }); - await setup(configPath); - return await run(); - } finally { - if (preExisting === null) { - try { - await fs.rm(configPath, { force: true }); - } catch { - // best-effort cleanup - } - } else { - await fs.writeFile(configPath, preExisting, "utf8"); - } - } -} - -describe("resolvePhaseModelOverride", () => { - it("returns configured model when full config is present", async () => { - await withConfigFile( - async (configPath) => { - const phaseModels = makeFullConfig("anthropic/claude-sonnet"); - phaseModels["plan-design-exec-debut"] = "openai/gpt-5"; - await fs.writeFile(configPath, `${JSON.stringify({ phaseModels }, null, 2)}\n`, "utf8"); - }, - async () => { - const value = await resolvePhaseModelOverride("plan-design-exec-debut"); - assert.equal(value, "openai/gpt-5"); - }, - ); - }); - - it("returns undefined when config is absent", async () => { - await withConfigFile( - async (configPath) => { - await fs.writeFile(configPath, `${JSON.stringify({ unrelated: true }, null, 2)}\n`, "utf8"); - }, - async () => { - const value = await resolvePhaseModelOverride("plan-code-exec-fix"); - assert.equal(value, undefined); - }, - ); - }); -}); diff --git a/tests/progress.test.ts b/tests/progress.test.ts deleted file mode 100644 index b1378a3..0000000 --- a/tests/progress.test.ts +++ /dev/null @@ -1,321 +0,0 @@ -import assert from "node:assert/strict"; -import { describe, it } from "node:test"; -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; - -import { EventLog, readProjection, readRecentLogs, fold, summarize, extractToolEvent } from "../src/planner/lib/audit.js"; -import type { Projection, AuditEvent, ToolEvent } from "../src/planner/lib/audit.js"; - -async function createTempDir(prefix: string): Promise { - return fs.mkdtemp(path.join(os.tmpdir(), prefix)); -} - -// -- EventLog + readProjection -- - -describe("EventLog", () => { - it("persists events and projection through step transitions", async () => { - const dir = await createTempDir("koan-audit-"); - - const log = new EventLog(dir, "architect", "plan-design", "anthropic/claude-sonnet-4-20250514"); - await log.open(); - - await log.emitPhaseStart(6); - await log.emitStepTransition(1, "Task Analysis", 6); - await log.emitStepTransition(2, "Decision Framework", 6); - await log.emitPhaseEnd("completed"); - await log.close(); - - const proj = await readProjection(dir); - assert.ok(proj, "projection should be readable"); - assert.equal(proj.role, "architect"); - assert.equal(proj.phase, "plan-design"); - assert.equal(proj.model, "anthropic/claude-sonnet-4-20250514"); - assert.equal(proj.status, "completed"); - assert.equal(proj.step, 2); - assert.equal(proj.totalSteps, 6); - assert.equal(proj.stepName, "Step 2/6: Decision Framework"); - assert.equal(proj.eventCount, 4); - - // Verify events.jsonl has correct number of lines - const raw = await fs.readFile(path.join(dir, "events.jsonl"), "utf8"); - const lines = raw.trimEnd().split("\n").filter(Boolean); - assert.equal(lines.length, 4); - - await fs.rm(dir, { recursive: true, force: true }); - }); - - it("tracks lastAction from tool events", async () => { - const dir = await createTempDir("koan-audit-"); - - const log = new EventLog(dir, "architect", "plan-design"); - await log.open(); - - await log.append({ - kind: "tool_file", - tool: "read", - path: "src/main.ts", - lines: 50, - chars: 1200, - error: false, - } as Omit); - - const proj = log.state; - assert.equal(proj.lastAction, "read src/main.ts (50L, 1200c)"); - - await log.close(); - await fs.rm(dir, { recursive: true, force: true }); - }); - - it("returns null for missing projection", async () => { - const dir = await createTempDir("koan-audit-"); - const proj = await readProjection(dir); - assert.equal(proj, null); - await fs.rm(dir, { recursive: true, force: true }); - }); -}); - -// -- readRecentLogs -- - -describe("readRecentLogs", () => { - it("returns recent non-heartbeat events as structured LogLines", async () => { - const dir = await createTempDir("koan-audit-"); - - const log = new EventLog(dir, "architect", "plan-design"); - await log.open(); - - await log.emitPhaseStart(3); - await log.emitStepTransition(1, "Analysis", 3); - await log.append({ - kind: "tool_file", - tool: "read", - path: "src/foo.ts", - lines: 100, - chars: 3000, - error: false, - } as Omit); - await log.close(); - - const lines = await readRecentLogs(dir, 5); - // 3 events (heartbeats filtered), all returned - assert.equal(lines.length, 3); - - assert.equal(lines[0].tool, "phase"); - assert.ok(lines[0].summary.includes("plan-design")); - - assert.equal(lines[1].tool, "step 1/3"); - assert.equal(lines[1].summary, "Analysis"); - - assert.equal(lines[2].tool, "read"); - assert.ok(lines[2].summary.includes("src/foo.ts")); - assert.ok(lines[2].summary.includes("100L")); - - await fs.rm(dir, { recursive: true, force: true }); - }); - - it("filters out koan_complete_step events", async () => { - const dir = await createTempDir("koan-audit-"); - - const log = new EventLog(dir, "architect", "plan-design"); - await log.open(); - - await log.append({ - kind: "tool_koan", - tool: "koan_complete_step", - input: { thoughts: "done" }, - response: ["ok"], - error: false, - } as Omit); - - await log.append({ - kind: "tool_koan", - tool: "koan_set_overview", - input: { problem: "test" }, - response: ["saved"], - error: false, - } as Omit); - - await log.close(); - - const lines = await readRecentLogs(dir, 5); - assert.equal(lines.length, 1); - assert.equal(lines[0].tool, "koan_set_overview"); - - await fs.rm(dir, { recursive: true, force: true }); - }); - - it("returns empty array for missing directory", async () => { - const lines = await readRecentLogs("/nonexistent/path", 5); - assert.deepEqual(lines, []); - }); -}); - -// -- fold (pure) -- - -describe("fold", () => { - const initial: Projection = { - role: "", - phase: "", - model: null, - status: "running", - step: 0, - totalSteps: 0, - stepName: "", - lastAction: null, - updatedAt: "", - eventCount: 0, - error: null, - }; - - it("phase_start resets projection", () => { - const e: AuditEvent = { - kind: "phase_start", - phase: "plan-design", - role: "architect", - model: "openai/gpt-5-codex", - totalSteps: 6, - ts: "2026-01-01T00:00:00Z", - seq: 0, - }; - const s = fold(initial, e); - assert.equal(s.role, "architect"); - assert.equal(s.phase, "plan-design"); - assert.equal(s.model, "openai/gpt-5-codex"); - assert.equal(s.totalSteps, 6); - assert.equal(s.eventCount, 1); - }); - - it("step_transition updates step name", () => { - const e: AuditEvent = { - kind: "step_transition", - step: 3, - name: "Risk Assessment", - totalSteps: 6, - ts: "2026-01-01T00:00:01Z", - seq: 1, - }; - const s = fold(initial, e); - assert.equal(s.step, 3); - assert.equal(s.stepName, "Step 3/6: Risk Assessment"); - }); - - it("phase_end sets status and error", () => { - const e: AuditEvent = { - kind: "phase_end", - outcome: "failed", - detail: "timeout", - ts: "2026-01-01T00:00:02Z", - seq: 2, - }; - const s = fold(initial, e); - assert.equal(s.status, "failed"); - assert.equal(s.error, "timeout"); - }); -}); - -// -- summarize -- - -describe("summarize", () => { - it("file tool with size stats", () => { - const e: ToolEvent = { - kind: "tool_file", - tool: "read", - path: "src/main.ts", - lines: 42, - chars: 1500, - error: false, - ts: "", - seq: 0, - }; - assert.equal(summarize(e), "read src/main.ts (42L, 1500c)"); - }); - - it("bash tool with size stats", () => { - const e: ToolEvent = { - kind: "tool_bash", - bin: "grep", - lines: 10, - chars: 200, - error: false, - ts: "", - seq: 0, - }; - assert.equal(summarize(e), "bash grep (10L, 200c)"); - }); - - it("file tool without size stats", () => { - const e: ToolEvent = { - kind: "tool_file", - tool: "edit", - path: "src/foo.ts", - error: false, - ts: "", - seq: 0, - }; - assert.equal(summarize(e), "edit src/foo.ts"); - }); -}); - -// -- extractToolEvent -- - -describe("extractToolEvent", () => { - it("extracts read tool with line/char counts", () => { - const content = "line1\nline2\nline3"; - const e = extractToolEvent({ - toolName: "read", - input: { path: "src/test.ts" }, - content: [{ type: "text", text: content }], - isError: false, - }); - assert.equal(e.kind, "tool_file"); - if (e.kind === "tool_file") { - assert.equal(e.tool, "read"); - assert.equal(e.path, "src/test.ts"); - assert.equal(e.lines, 3); - assert.equal(e.chars, content.length); - } - }); - - it("extracts bash tool with line/char counts", () => { - const output = "found 5 matches\n"; - const e = extractToolEvent({ - toolName: "bash", - input: { command: "grep -r pattern ." }, - content: [{ type: "text", text: output }], - isError: false, - }); - assert.equal(e.kind, "tool_bash"); - if (e.kind === "tool_bash") { - assert.equal(e.bin, "grep"); - assert.equal(e.lines, 2); - assert.equal(e.chars, output.length); - } - }); - - it("extracts koan tool with input and response", () => { - const e = extractToolEvent({ - toolName: "koan_set_overview", - input: { problem: "test problem" }, - content: [{ type: "text", text: "saved" }], - isError: false, - }); - assert.equal(e.kind, "tool_koan"); - if (e.kind === "tool_koan") { - assert.equal(e.tool, "koan_set_overview"); - assert.deepEqual(e.response, ["saved"]); - } - }); - - it("falls back to generic for unknown tools", () => { - const e = extractToolEvent({ - toolName: "unknown_tool", - input: {}, - content: [], - isError: false, - }); - assert.equal(e.kind, "tool_generic"); - if (e.kind === "tool_generic") { - assert.equal(e.tool, "unknown_tool"); - } - }); -}); diff --git a/tests/qr-grouped-verify.test.ts b/tests/qr-grouped-verify.test.ts deleted file mode 100644 index 23313cf..0000000 --- a/tests/qr-grouped-verify.test.ts +++ /dev/null @@ -1,304 +0,0 @@ -// Tests for grouped QR verification: grouping logic, step routing, -// prompt generation, and subagent spawn arg threading. - -import assert from "node:assert/strict"; -import { describe, it } from "node:test"; - -import { buildSpawnArgs } from "../src/planner/subagent.js"; -import type { QRItem } from "../src/planner/qr/types.js"; -import { - buildVerifySystemPrompt, - buildContextStep, - buildAnalyzeStep, - buildConfirmStep, -} from "../src/planner/phases/qr-verify/prompts.js"; - -// -- Grouping logic (pure function, extracted from session.ts pattern) -- - -function groupItemsByGroupId(items: QRItem[]): Map { - const groups = new Map(); - for (const item of items) { - const gid = item.group_id ?? item.id; - const existing = groups.get(gid); - if (existing) { - existing.push(item.id); - } else { - groups.set(gid, [item.id]); - } - } - return groups; -} - -function makeItem(id: string, groupId: string | null = null, status: "TODO" | "PASS" | "FAIL" = "TODO"): QRItem { - return { - id, - scope: `milestone:M-001`, - check: `Check for ${id}`, - status, - finding: null, - parent_id: null, - group_id: groupId, - severity: "MUST", - }; -} - -// -- Grouping tests -- - -describe("groupItemsByGroupId", () => { - it("groups items sharing the same group_id", () => { - const items = [ - makeItem("QR-001", "group-a"), - makeItem("QR-002", "group-a"), - makeItem("QR-003", "group-b"), - ]; - const groups = groupItemsByGroupId(items); - - assert.equal(groups.size, 2); - assert.deepEqual(groups.get("group-a"), ["QR-001", "QR-002"]); - assert.deepEqual(groups.get("group-b"), ["QR-003"]); - }); - - it("treats null group_id as singleton (uses item id as group key)", () => { - const items = [ - makeItem("QR-001", null), - makeItem("QR-002", null), - ]; - const groups = groupItemsByGroupId(items); - - assert.equal(groups.size, 2); - assert.deepEqual(groups.get("QR-001"), ["QR-001"]); - assert.deepEqual(groups.get("QR-002"), ["QR-002"]); - }); - - it("handles mixed grouped and ungrouped items", () => { - const items = [ - makeItem("QR-001", "umbrella"), - makeItem("QR-002", "umbrella"), - makeItem("QR-003", null), - makeItem("QR-004", "component-auth"), - makeItem("QR-005", "component-auth"), - makeItem("QR-006", "component-auth"), - ]; - const groups = groupItemsByGroupId(items); - - assert.equal(groups.size, 3); - assert.deepEqual(groups.get("umbrella"), ["QR-001", "QR-002"]); - assert.deepEqual(groups.get("QR-003"), ["QR-003"]); - assert.deepEqual(groups.get("component-auth"), ["QR-004", "QR-005", "QR-006"]); - }); - - it("returns empty map for empty items", () => { - const groups = groupItemsByGroupId([]); - assert.equal(groups.size, 0); - }); - - it("single item with group_id creates group of 1", () => { - const items = [makeItem("QR-001", "solo-group")]; - const groups = groupItemsByGroupId(items); - - assert.equal(groups.size, 1); - assert.deepEqual(groups.get("solo-group"), ["QR-001"]); - }); -}); - -// -- Dynamic step formula tests -- - -describe("dynamic step formula", () => { - it("totalSteps = 1 + 2*N for N items", () => { - assert.equal(1 + 2 * 1, 3); // 1 item: CONTEXT, ANALYZE, CONFIRM - assert.equal(1 + 2 * 3, 7); // 3 items: CONTEXT, 3×(ANALYZE+CONFIRM) - assert.equal(1 + 2 * 5, 11); // 5 items - }); - - it("step routing maps correctly for 3 items", () => { - // Step 1: CONTEXT - // Step 2: ANALYZE item 0 - // Step 3: CONFIRM item 0 - // Step 4: ANALYZE item 1 - // Step 5: CONFIRM item 1 - // Step 6: ANALYZE item 2 - // Step 7: CONFIRM item 2 - - function stepType(step: number): { kind: string; itemIndex?: number } { - if (step === 1) return { kind: "CONTEXT" }; - const offset = step - 2; - const itemIndex = Math.floor(offset / 2); - const isConfirm = offset % 2 === 1; - return isConfirm ? { kind: "CONFIRM", itemIndex } : { kind: "ANALYZE", itemIndex }; - } - - assert.deepEqual(stepType(1), { kind: "CONTEXT" }); - assert.deepEqual(stepType(2), { kind: "ANALYZE", itemIndex: 0 }); - assert.deepEqual(stepType(3), { kind: "CONFIRM", itemIndex: 0 }); - assert.deepEqual(stepType(4), { kind: "ANALYZE", itemIndex: 1 }); - assert.deepEqual(stepType(5), { kind: "CONFIRM", itemIndex: 1 }); - assert.deepEqual(stepType(6), { kind: "ANALYZE", itemIndex: 2 }); - assert.deepEqual(stepType(7), { kind: "CONFIRM", itemIndex: 2 }); - }); - - it("step routing works for single item (backward compat)", () => { - function stepType(step: number): { kind: string; itemIndex?: number } { - if (step === 1) return { kind: "CONTEXT" }; - const offset = step - 2; - const itemIndex = Math.floor(offset / 2); - const isConfirm = offset % 2 === 1; - return isConfirm ? { kind: "CONFIRM", itemIndex } : { kind: "ANALYZE", itemIndex }; - } - - assert.deepEqual(stepType(1), { kind: "CONTEXT" }); - assert.deepEqual(stepType(2), { kind: "ANALYZE", itemIndex: 0 }); - assert.deepEqual(stepType(3), { kind: "CONFIRM", itemIndex: 0 }); - }); -}); - -// -- Prompt generation tests -- - -describe("buildVerifySystemPrompt", () => { - it("includes item count for single item", () => { - const result = buildVerifySystemPrompt("base prompt", "plan-design", 1); - assert.ok(result.includes("1 QR item")); - assert.ok(!result.includes("items")); - }); - - it("includes item count for multiple items", () => { - const result = buildVerifySystemPrompt("base prompt", "plan-code", 5); - assert.ok(result.includes("5 QR items")); - }); - - it("includes phase name", () => { - const result = buildVerifySystemPrompt("base prompt", "plan-docs", 3); - assert.ok(result.includes("plan-docs")); - }); -}); - -describe("buildContextStep", () => { - const items: QRItem[] = [ - makeItem("QR-001", "group-a"), - makeItem("QR-002", "group-a"), - makeItem("QR-003", "group-a"), - ]; - - it("lists all items in context step", () => { - const step = buildContextStep(items, "plan-design"); - const text = step.instructions.join("\n"); - assert.ok(text.includes("QR-001")); - assert.ok(text.includes("QR-002")); - assert.ok(text.includes("QR-003")); - }); - - it("shows correct item count", () => { - const step = buildContextStep(items, "plan-design"); - const text = step.instructions.join("\n"); - assert.ok(text.includes("3 ITEMS")); - }); - - it("shows 1 ITEM for single item", () => { - const step = buildContextStep([items[0]], "plan-design"); - const text = step.instructions.join("\n"); - assert.ok(text.includes("1 ITEM")); - }); -}); - -describe("buildAnalyzeStep", () => { - const item = makeItem("QR-042", "group-x"); - - it("includes item ID and check", () => { - const step = buildAnalyzeStep(item, 0, 3); - const text = step.instructions.join("\n"); - assert.ok(text.includes("QR-042")); - assert.ok(text.includes(item.check)); - }); - - it("includes position label for multi-item groups", () => { - const step = buildAnalyzeStep(item, 1, 5); - assert.ok(step.title.includes("item 2 of 5")); - }); - - it("omits position label for single item", () => { - const step = buildAnalyzeStep(item, 0, 1); - assert.ok(!step.title.includes("item")); - }); -}); - -describe("buildConfirmStep", () => { - const item = makeItem("QR-007", "group-y"); - - it("includes koan_qr_set_item instructions with correct id", () => { - const step = buildConfirmStep(item, 0, 3, "plan-code"); - const text = step.instructions.join("\n"); - assert.ok(text.includes("id='QR-007'")); - assert.ok(text.includes("status='PASS'")); - assert.ok(text.includes("status='FAIL'")); - }); - - it("includes position label for multi-item groups", () => { - const step = buildConfirmStep(item, 2, 4, "plan-docs"); - assert.ok(step.title.includes("item 3 of 4")); - }); - - it("has invokeAfter guard", () => { - const step = buildConfirmStep(item, 0, 1, "plan-design"); - assert.ok(step.invokeAfter); - assert.ok(step.invokeAfter!.includes("koan_complete_step")); - }); -}); - -// -- Subagent spawn arg tests -- - -describe("spawnReviewer args", () => { - const baseOpts = { - planDir: "/plan", - subagentDir: "/subagent", - extensionPath: "/ext/koan.ts", - cwd: "/working", - }; - - it("passes single item ID via --koan-qr-item for single-item group", () => { - const args = buildSpawnArgs("reviewer", "qr-plan-design", "Verify the assigned QR item.", { - ...baseOpts, - extraFlags: ["--koan-qr-item", "QR-001"], - }); - const idx = args.indexOf("--koan-qr-item"); - assert.ok(idx >= 0); - assert.equal(args[idx + 1], "QR-001"); - }); - - it("passes comma-separated item IDs via --koan-qr-item for multi-item group", () => { - const itemList = "QR-001,QR-002,QR-003"; - const args = buildSpawnArgs("reviewer", "qr-plan-code", "Verify the 3 assigned QR items.", { - ...baseOpts, - extraFlags: ["--koan-qr-item", itemList], - }); - const idx = args.indexOf("--koan-qr-item"); - assert.ok(idx >= 0); - assert.equal(args[idx + 1], "QR-001,QR-002,QR-003"); - }); -}); - -// -- Comma-separated parsing (mirrors dispatch.ts logic) -- - -describe("comma-separated item ID parsing", () => { - function parseItemIds(rawFlag: string): string[] { - return rawFlag.split(",").map((s) => s.trim()).filter(Boolean); - } - - it("parses single item ID", () => { - assert.deepEqual(parseItemIds("QR-001"), ["QR-001"]); - }); - - it("parses multiple comma-separated IDs", () => { - assert.deepEqual(parseItemIds("QR-001,QR-002,QR-003"), ["QR-001", "QR-002", "QR-003"]); - }); - - it("handles whitespace around commas", () => { - assert.deepEqual(parseItemIds("QR-001 , QR-002 , QR-003"), ["QR-001", "QR-002", "QR-003"]); - }); - - it("filters empty strings from trailing comma", () => { - assert.deepEqual(parseItemIds("QR-001,QR-002,"), ["QR-001", "QR-002"]); - }); - - it("returns empty array for empty string", () => { - assert.deepEqual(parseItemIds(""), []); - }); -}); diff --git a/tests/session-model-threading.test.ts b/tests/session-model-threading.test.ts deleted file mode 100644 index 1a9c300..0000000 --- a/tests/session-model-threading.test.ts +++ /dev/null @@ -1,205 +0,0 @@ -import assert from "node:assert/strict"; -import { describe, it } from "node:test"; - -import { - resolveSpawnModelOverride, - spawnWorkWithResolvedModel, - spawnFixWithResolvedModel, - spawnQRDecomposerWithResolvedModel, - spawnReviewerWithResolvedModel, -} from "../src/planner/session.js"; -import type { PhaseModelKey } from "../src/planner/model-phase.js"; - -describe("resolveSpawnModelOverride", () => { - it("maps context -> key and resolves override", async () => { - const contexts = ["work-debut", "fix", "qr-decompose", "qr-verify"] as const; - - for (const context of contexts) { - let mappedContext: string | null = null; - let mappedRow: string | null = null; - let resolvedKey: string | null = null; - - const result = await resolveSpawnModelOverride(context, "plan-design", { - mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { - mappedContext = ctx; - mappedRow = row; - return "plan-design-exec-debut" as PhaseModelKey; - }, - resolvePhaseModelOverrideFn: async (key) => { - resolvedKey = key; - return "anthropic/claude-opus-4"; - }, - }); - - assert.equal(mappedContext, context); - assert.equal(mappedRow, "plan-design"); - assert.equal(resolvedKey, "plan-design-exec-debut"); - assert.equal(result, "anthropic/claude-opus-4"); - } - }); - - it("returns undefined when resolver reports absent config", async () => { - const result = await resolveSpawnModelOverride("work-debut", "plan-code", { - mapSpawnContextToPhaseModelKeyFn: () => "plan-code-exec-debut" as PhaseModelKey, - resolvePhaseModelOverrideFn: async () => undefined, - }); - - assert.equal(result, undefined); - }); -}); - -describe("work/fix spawn model threading", () => { - it("threads resolved modelOverride into work spawns", async () => { - let capturedModelOverride: string | undefined; - - await spawnWorkWithResolvedModel( - "plan-design", - async (opts) => { - capturedModelOverride = opts.modelOverride; - return { exitCode: 0, stderr: "", subagentDir: opts.subagentDir }; - }, - { - planDir: "/plan", - subagentDir: "/subagent", - cwd: "/cwd", - extensionPath: "/ext/koan.ts", - log: () => {}, - }, - { - mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { - assert.equal(ctx, "work-debut"); - assert.equal(row, "plan-design"); - return "plan-design-exec-debut" as PhaseModelKey; - }, - resolvePhaseModelOverrideFn: async (key) => { - assert.equal(key, "plan-design-exec-debut"); - return "anthropic/claude-opus-4"; - }, - }, - ); - - assert.equal(capturedModelOverride, "anthropic/claude-opus-4"); - }); - - it("threads resolved modelOverride into fix spawns", async () => { - let capturedModelOverride: string | undefined; - - await spawnFixWithResolvedModel( - "plan-code", - async (opts) => { - capturedModelOverride = opts.modelOverride; - return { exitCode: 0, stderr: "", subagentDir: opts.subagentDir }; - }, - { - planDir: "/plan", - subagentDir: "/subagent", - cwd: "/cwd", - extensionPath: "/ext/koan.ts", - log: () => {}, - }, - { - mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { - assert.equal(ctx, "fix"); - assert.equal(row, "plan-code"); - return "plan-code-exec-fix" as PhaseModelKey; - }, - resolvePhaseModelOverrideFn: async (key) => { - assert.equal(key, "plan-code-exec-fix"); - return "openai/gpt-5"; - }, - }, - ); - - assert.equal(capturedModelOverride, "openai/gpt-5"); - }); -}); - -describe("QR spawn model threading", () => { - it("threads resolved modelOverride into spawnQRDecomposer", async () => { - let capturedModelOverride: string | undefined; - - await spawnQRDecomposerWithResolvedModel( - { - planDir: "/plan", - subagentDir: "/subagent", - cwd: "/cwd", - extensionPath: "/ext/koan.ts", - phase: "plan-design", - }, - { - mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { - assert.equal(ctx, "qr-decompose"); - assert.equal(row, "plan-design"); - return "plan-design-qr-decompose" as PhaseModelKey; - }, - resolvePhaseModelOverrideFn: async (key) => { - assert.equal(key, "plan-design-qr-decompose"); - return "openai/gpt-5"; - }, - spawnQRDecomposerFn: async (opts) => { - capturedModelOverride = opts.modelOverride; - return { exitCode: 0, stderr: "", subagentDir: opts.subagentDir }; - }, - }, - ); - - assert.equal(capturedModelOverride, "openai/gpt-5"); - }); - - it("threads resolved modelOverride into spawnReviewer", async () => { - let capturedModelOverride: string | undefined; - - await spawnReviewerWithResolvedModel( - { - planDir: "/plan", - subagentDir: "/subagent", - cwd: "/cwd", - extensionPath: "/ext/koan.ts", - phase: "plan-code", - itemIds: ["QR-001"], - }, - { - mapSpawnContextToPhaseModelKeyFn: (ctx, row) => { - assert.equal(ctx, "qr-verify"); - assert.equal(row, "plan-code"); - return "plan-code-qr-verify" as PhaseModelKey; - }, - resolvePhaseModelOverrideFn: async (key) => { - assert.equal(key, "plan-code-qr-verify"); - return "google/gemini-3-pro"; - }, - spawnReviewerFn: async (opts) => { - capturedModelOverride = opts.modelOverride; - return { exitCode: 0, stderr: "", subagentDir: opts.subagentDir }; - }, - }, - ); - - assert.equal(capturedModelOverride, "google/gemini-3-pro"); - }); - - it("passes undefined modelOverride when config is absent", async () => { - let capturedModelOverride: string | undefined; - - await spawnReviewerWithResolvedModel( - { - planDir: "/plan", - subagentDir: "/subagent", - cwd: "/cwd", - extensionPath: "/ext/koan.ts", - phase: "plan-docs", - itemIds: ["QR-002"], - }, - { - mapSpawnContextToPhaseModelKeyFn: () => "plan-docs-qr-verify" as PhaseModelKey, - resolvePhaseModelOverrideFn: async () => undefined, - spawnReviewerFn: async (opts) => { - capturedModelOverride = opts.modelOverride; - return { exitCode: 0, stderr: "", subagentDir: opts.subagentDir }; - }, - }, - ); - - assert.equal(capturedModelOverride, undefined); - }); -}); diff --git a/tests/state-machine.test.ts b/tests/state-machine.test.ts new file mode 100644 index 0000000..eaf1fad --- /dev/null +++ b/tests/state-machine.test.ts @@ -0,0 +1,422 @@ +// Property-based state machine tests for koan. +// Verifies: +// - All valid story status transitions (§11.4 table) +// - Routing decisions for all state combinations +// - Permission matrices (role × tool × expected result) + +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import { checkPermission, ROLE_PERMISSIONS } from "../src/planner/lib/permissions.js"; +import { + loadStoryState, + saveStoryState, + ensureStoryDirectory, +} from "../src/planner/epic/state.js"; +import { createInitialStoryState } from "../src/planner/epic/types.js"; +import type { StoryStatus } from "../src/planner/types.js"; +import { assertStatus } from "../src/planner/tools/orchestrator.js"; + +async function mkTempDir(): Promise { + return fs.mkdtemp(path.join(os.tmpdir(), "koan-sm-test-")); +} + +async function withEpicDir(fn: (epicDir: string) => Promise): Promise { + const dir = await mkTempDir(); + try { + await fs.mkdir(path.join(dir, "stories"), { recursive: true }); + return await fn(dir); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } +} + +// --------------------------------------------------------------------------- +// State machine: valid transitions (§11.4) +// --------------------------------------------------------------------------- + +describe("state machine: valid transitions", () => { + // koan_select_story: pending → selected, retry → selected + it("koan_select_story accepts pending → selected", async () => { + await withEpicDir(async (epicDir) => { + await ensureStoryDirectory(epicDir, "S-001-auth"); + const state = await loadStoryState(epicDir, "S-001-auth"); + assert.equal(state.status, "pending"); + + await saveStoryState(epicDir, "S-001-auth", { ...state, status: "selected", updatedAt: new Date().toISOString() }); + const updated = await loadStoryState(epicDir, "S-001-auth"); + assert.equal(updated.status, "selected"); + }); + }); + + it("koan_select_story accepts retry → selected", async () => { + await withEpicDir(async (epicDir) => { + await ensureStoryDirectory(epicDir, "S-001-auth"); + const state = await loadStoryState(epicDir, "S-001-auth"); + + await saveStoryState(epicDir, "S-001-auth", { ...state, status: "retry", updatedAt: new Date().toISOString() }); + const retrying = await loadStoryState(epicDir, "S-001-auth"); + assert.equal(retrying.status, "retry"); + + await saveStoryState(epicDir, "S-001-auth", { ...retrying, status: "selected", updatedAt: new Date().toISOString() }); + const selected = await loadStoryState(epicDir, "S-001-auth"); + assert.equal(selected.status, "selected"); + }); + }); + + // koan_complete_story: verifying → done + it("koan_complete_story accepts verifying → done", async () => { + await withEpicDir(async (epicDir) => { + await ensureStoryDirectory(epicDir, "S-002-routes"); + const state = await loadStoryState(epicDir, "S-002-routes"); + await saveStoryState(epicDir, "S-002-routes", { ...state, status: "verifying", updatedAt: new Date().toISOString() }); + + const verifying = await loadStoryState(epicDir, "S-002-routes"); + assert.equal(verifying.status, "verifying"); + + await saveStoryState(epicDir, "S-002-routes", { ...verifying, status: "done", updatedAt: new Date().toISOString() }); + const done = await loadStoryState(epicDir, "S-002-routes"); + assert.equal(done.status, "done"); + }); + }); + + // koan_retry_story: verifying → retry + it("koan_retry_story accepts verifying → retry", async () => { + await withEpicDir(async (epicDir) => { + await ensureStoryDirectory(epicDir, "S-003-profile"); + const state = await loadStoryState(epicDir, "S-003-profile"); + await saveStoryState(epicDir, "S-003-profile", { ...state, status: "verifying", updatedAt: new Date().toISOString() }); + + const verifying = await loadStoryState(epicDir, "S-003-profile"); + await saveStoryState(epicDir, "S-003-profile", { + ...verifying, + status: "retry", + failureSummary: "Test 3 failed: expected 200 got 404", + updatedAt: new Date().toISOString(), + }); + + const retried = await loadStoryState(epicDir, "S-003-profile"); + assert.equal(retried.status, "retry"); + assert.equal(retried.failureSummary, "Test 3 failed: expected 200 got 404"); + }); + }); + + // koan_skip_story: pending → skipped + it("koan_skip_story accepts pending → skipped", async () => { + await withEpicDir(async (epicDir) => { + await ensureStoryDirectory(epicDir, "S-004-optional"); + const state = await loadStoryState(epicDir, "S-004-optional"); + assert.equal(state.status, "pending"); + + await saveStoryState(epicDir, "S-004-optional", { + ...state, + status: "skipped", + skipReason: "Already implemented by S-003", + updatedAt: new Date().toISOString(), + }); + + const skipped = await loadStoryState(epicDir, "S-004-optional"); + assert.equal(skipped.status, "skipped"); + assert.equal(skipped.skipReason, "Already implemented by S-003"); + }); + }); + + // koan_skip_story: retry → skipped + it("koan_skip_story accepts retry → skipped", async () => { + await withEpicDir(async (epicDir) => { + await ensureStoryDirectory(epicDir, "S-005-retry-skip"); + const state = await loadStoryState(epicDir, "S-005-retry-skip"); + await saveStoryState(epicDir, "S-005-retry-skip", { ...state, status: "retry", updatedAt: new Date().toISOString() }); + + const retrying = await loadStoryState(epicDir, "S-005-retry-skip"); + assert.equal(retrying.status, "retry"); + + await saveStoryState(epicDir, "S-005-retry-skip", { + ...retrying, + status: "skipped", + skipReason: "Made unnecessary by another story", + updatedAt: new Date().toISOString(), + }); + + const skipped = await loadStoryState(epicDir, "S-005-retry-skip"); + assert.equal(skipped.status, "skipped"); + }); + }); + + // No escalated status exists in the new design. + it("StoryStatus type does not include escalated", () => { + const validStatuses: StoryStatus[] = [ + "pending", "selected", "planning", "executing", + "verifying", "done", "retry", "skipped", + ]; + // Verify all expected statuses are present + assert.equal(validStatuses.length, 8); + // Ensure "escalated" is not a valid value by type-checking at runtime. + const set = new Set(validStatuses); + assert.equal(set.has("escalated"), false, "escalated should not exist as a story status"); + }); +}); + +// --------------------------------------------------------------------------- +// assertStatus enforcement +// --------------------------------------------------------------------------- + +describe("assertStatus enforcement", () => { + it("throws when current status is not in allowed list", () => { + assert.throws( + () => assertStatus("S-001", "selected", ["pending", "retry"]), + /Cannot transition story 'S-001'/, + ); + }); + + it("throws when current status does not match single allowed status", () => { + assert.throws( + () => assertStatus("S-001", "pending", ["verifying"]), + /Cannot transition story 'S-001'/, + ); + }); + + it("does not throw when current status is in allowed list", () => { + assert.doesNotThrow(() => assertStatus("S-001", "verifying", ["verifying"])); + }); + + it("does not throw when current status is one of multiple allowed statuses", () => { + assert.doesNotThrow(() => assertStatus("S-001", "retry", ["pending", "retry"])); + assert.doesNotThrow(() => assertStatus("S-001", "pending", ["pending", "retry"])); + }); + + it("koan_skip_story accepts retry status via assertStatus", () => { + assert.doesNotThrow(() => assertStatus("S-001", "retry", ["pending", "retry"])); + }); + + it("koan_skip_story rejects selected status via assertStatus", () => { + assert.throws( + () => assertStatus("S-001", "selected", ["pending", "retry"]), + /Cannot transition story 'S-001'/, + ); + }); +}); + +// --------------------------------------------------------------------------- +// State machine: tool source validation (§11.4 / §11.12) +// --------------------------------------------------------------------------- + +describe("state machine: tool source validation", () => { + const TOOL_VALID_SOURCES: Record = { + koan_select_story: ["pending", "retry"], + koan_complete_story: ["verifying"], + koan_retry_story: ["verifying"], + koan_skip_story: ["pending", "retry"], + }; + + const ALL_STATUSES: StoryStatus[] = [ + "pending", "selected", "planning", "executing", + "verifying", "done", "retry", "skipped", + ]; + + for (const [tool, validSources] of Object.entries(TOOL_VALID_SOURCES)) { + const invalidSources = ALL_STATUSES.filter((s) => !validSources.includes(s)); + + it(`${tool} allows only [${validSources.join(", ")}]`, () => { + // All valid sources should be in the set + assert.equal(validSources.length > 0, true); + // No invalid source should overlap with valid + for (const invalid of invalidSources) { + assert.equal(validSources.includes(invalid), false, + `${tool}: ${invalid} should not be a valid source status`); + } + }); + } + + it("koan_escalate does not exist in the tool inventory", () => { + // Verify koan_escalate is not in the ROLE_PERMISSIONS for orchestrator + + const orchestratorTools = ROLE_PERMISSIONS.get("orchestrator") ?? new Set(); + assert.equal(orchestratorTools.has("koan_escalate"), false, "koan_escalate must not be in orchestrator permissions"); + }); +}); + +// --------------------------------------------------------------------------- +// Routing decisions +// --------------------------------------------------------------------------- + +describe("routing decisions", () => { + // Simulate the routeFromState logic (we test inputs/outputs, not the internal function) + interface Story { storyId: string; status: StoryStatus; retryCount: number; maxRetries: number } + + function simulateRouting(stories: Story[]): string { + // Mirror driver.ts routeFromState logic + const retry = stories.find((s) => s.status === "retry"); + if (retry) return `retry:${retry.storyId}`; + const selected = stories.find((s) => s.status === "selected"); + if (selected) return `execute:${selected.storyId}`; + const terminal = new Set(["done", "skipped"]); + const allTerminal = stories.every((s) => terminal.has(s.status)); + if (allTerminal && stories.length > 0) return "complete"; + return "error"; + } + + it("routes to retry when a story has retry status", () => { + const stories: Story[] = [ + { storyId: "S-001-auth", status: "done", retryCount: 0, maxRetries: 2 }, + { storyId: "S-002-routes", status: "retry", retryCount: 1, maxRetries: 2 }, + ]; + assert.equal(simulateRouting(stories), "retry:S-002-routes"); + }); + + it("routes to execute when a story has selected status", () => { + const stories: Story[] = [ + { storyId: "S-001-auth", status: "done", retryCount: 0, maxRetries: 2 }, + { storyId: "S-002-routes", status: "selected", retryCount: 0, maxRetries: 2 }, + ]; + assert.equal(simulateRouting(stories), "execute:S-002-routes"); + }); + + it("routes to complete when all stories are done", () => { + const stories: Story[] = [ + { storyId: "S-001-auth", status: "done", retryCount: 0, maxRetries: 2 }, + { storyId: "S-002-routes", status: "done", retryCount: 0, maxRetries: 2 }, + ]; + assert.equal(simulateRouting(stories), "complete"); + }); + + it("routes to complete when all stories are done or skipped", () => { + const stories: Story[] = [ + { storyId: "S-001-auth", status: "done", retryCount: 0, maxRetries: 2 }, + { storyId: "S-002-optional", status: "skipped", retryCount: 0, maxRetries: 2 }, + ]; + assert.equal(simulateRouting(stories), "complete"); + }); + + it("routes to error when no actionable state exists", () => { + const stories: Story[] = [ + { storyId: "S-001-auth", status: "pending", retryCount: 0, maxRetries: 2 }, + { storyId: "S-002-routes", status: "pending", retryCount: 0, maxRetries: 2 }, + ]; + assert.equal(simulateRouting(stories), "error"); + }); + + it("prefers retry over selected (retry takes routing priority)", () => { + const stories: Story[] = [ + { storyId: "S-001-auth", status: "retry", retryCount: 1, maxRetries: 2 }, + { storyId: "S-002-routes", status: "selected", retryCount: 0, maxRetries: 2 }, + ]; + assert.equal(simulateRouting(stories), "retry:S-001-auth"); + }); + + it("routes to error for empty story list", () => { + assert.equal(simulateRouting([]), "error"); + }); +}); + +// --------------------------------------------------------------------------- +// Permission matrix (role × tool) +// --------------------------------------------------------------------------- + +describe("permission matrix", () => { + const epicDir = "/tmp/test-epic"; + + // Tools that should be allowed for each role. + const ROLE_ALLOWED: Record = { + intake: ["read", "bash", "grep", "glob", "find", "ls", "koan_complete_step", "koan_ask_question", "koan_request_scouts", "edit", "write"], + scout: ["read", "bash", "grep", "glob", "find", "ls", "koan_complete_step", "edit", "write"], + decomposer: ["read", "bash", "grep", "glob", "find", "ls", "koan_complete_step", "koan_ask_question", "koan_request_scouts", "edit", "write"], + orchestrator: ["read", "bash", "grep", "glob", "find", "ls", "koan_complete_step", "koan_ask_question", "koan_select_story", "koan_complete_story", "koan_retry_story", "koan_skip_story", "edit", "write"], + planner: ["read", "bash", "grep", "glob", "find", "ls", "koan_complete_step", "koan_ask_question", "koan_request_scouts", "edit", "write"], + executor: ["read", "bash", "grep", "glob", "find", "ls", "koan_complete_step", "koan_ask_question", "edit", "write"], + }; + + // Tools that must be blocked for each role. + const ROLE_BLOCKED: Record = { + intake: ["koan_select_story", "koan_complete_story", "koan_retry_story", "koan_skip_story", "koan_escalate"], + scout: ["koan_ask_question", "koan_request_scouts", "koan_select_story", "koan_complete_story", "koan_retry_story", "koan_skip_story", "koan_escalate"], + decomposer: ["koan_select_story", "koan_complete_story", "koan_retry_story", "koan_skip_story", "koan_escalate"], + orchestrator: ["koan_request_scouts", "koan_escalate"], + planner: ["koan_select_story", "koan_complete_story", "koan_retry_story", "koan_skip_story", "koan_escalate"], + executor: ["koan_select_story", "koan_complete_story", "koan_retry_story", "koan_skip_story", "koan_escalate", "koan_request_scouts"], + }; + + for (const [role, allowed] of Object.entries(ROLE_ALLOWED)) { + it(`${role}: allows expected tools`, () => { + for (const tool of allowed) { + const result = checkPermission(role, tool, epicDir); + assert.equal(result.allowed, true, `${role} should allow ${tool}: ${result.reason}`); + } + }); + } + + for (const [role, blocked] of Object.entries(ROLE_BLOCKED)) { + it(`${role}: blocks forbidden tools`, () => { + for (const tool of blocked) { + const result = checkPermission(role, tool, epicDir); + assert.equal(result.allowed, false, `${role} should block ${tool}`); + } + }); + } + + it("unknown role is blocked for all tools", () => { + const tools = ["read", "koan_complete_step", "koan_ask_question", "write"]; + for (const tool of tools) { + const result = checkPermission("unknown-role", tool, epicDir); + // read tools are always allowed, even for unknown roles + if (tool === "read") { + assert.equal(result.allowed, true); + } else { + assert.equal(result.allowed, false, `unknown-role should block ${tool}`); + } + } + }); + + it("planning roles have write access scoped to epic directory", () => { + const planningRoles = ["intake", "scout", "decomposer", "planner", "orchestrator"]; + const insidePath = path.join(epicDir, "stories", "S-001-auth", "story.md"); + const outsidePath = "/etc/passwd"; + + for (const role of planningRoles) { + const inside = checkPermission(role, "write", epicDir, { path: insidePath }); + assert.equal(inside.allowed, true, `${role} should allow write inside epic dir`); + + const outside = checkPermission(role, "write", epicDir, { path: outsidePath }); + assert.equal(outside.allowed, false, `${role} should block write outside epic dir`); + } + }); + + it("executor has unrestricted write access (can write to codebase)", () => { + // Executor does not scope-check paths — it needs to write to the codebase + const codebasePath = "/Users/lmergen/git/myapp/src/auth.ts"; + const result = checkPermission("executor", "write", epicDir, { path: codebasePath }); + assert.equal(result.allowed, true, "executor should allow writes anywhere"); + }); +}); + +// --------------------------------------------------------------------------- +// Initial state invariants +// --------------------------------------------------------------------------- + +describe("initial state invariants", () => { + it("createInitialStoryState produces pending status", () => { + const state = createInitialStoryState("S-001-auth"); + assert.equal(state.status, "pending"); + assert.equal(state.retryCount, 0); + assert.equal(state.storyId, "S-001-auth"); + assert.equal(typeof state.updatedAt, "string"); + }); + + it("createInitialStoryState uses default maxRetries of 2", () => { + const state = createInitialStoryState("S-001-auth"); + assert.equal(state.maxRetries, 2); + }); + + it("createInitialStoryState accepts custom maxRetries", () => { + const state = createInitialStoryState("S-001-auth", 5); + assert.equal(state.maxRetries, 5); + }); + + it("StoryState has no escalation field", () => { + const state = createInitialStoryState("S-001-auth"); + assert.equal("escalation" in state, false, "StoryState must not have an escalation field"); + }); +}); diff --git a/tests/story-discovery.test.ts b/tests/story-discovery.test.ts new file mode 100644 index 0000000..6cb2200 --- /dev/null +++ b/tests/story-discovery.test.ts @@ -0,0 +1,84 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import { discoverStoryIds } from "../src/planner/epic/state.js"; + +async function mkTempDir(): Promise { + return fs.mkdtemp(path.join(os.tmpdir(), "koan-test-")); +} + +describe("discoverStoryIds", () => { + it("returns empty array when stories directory does not exist", async () => { + const epicDir = await mkTempDir(); + try { + const ids = await discoverStoryIds(epicDir); + assert.deepEqual(ids, []); + } finally { + await fs.rm(epicDir, { recursive: true, force: true }); + } + }); + + it("returns empty array when stories directory is empty", async () => { + const epicDir = await mkTempDir(); + try { + await fs.mkdir(path.join(epicDir, "stories")); + const ids = await discoverStoryIds(epicDir); + assert.deepEqual(ids, []); + } finally { + await fs.rm(epicDir, { recursive: true, force: true }); + } + }); + + it("returns sorted story IDs for each subdirectory", async () => { + const epicDir = await mkTempDir(); + try { + const storiesDir = path.join(epicDir, "stories"); + await fs.mkdir(storiesDir); + // Create story directories out of alphabetical order. + for (const id of ["add-auth", "migrate-db", "update-api"]) { + await fs.mkdir(path.join(storiesDir, id)); + } + + const ids = await discoverStoryIds(epicDir); + assert.deepEqual(ids, ["add-auth", "migrate-db", "update-api"]); + } finally { + await fs.rm(epicDir, { recursive: true, force: true }); + } + }); + + it("ignores files in the stories directory", async () => { + const epicDir = await mkTempDir(); + try { + const storiesDir = path.join(epicDir, "stories"); + await fs.mkdir(storiesDir); + await fs.mkdir(path.join(storiesDir, "real-story")); + // Write a file — should be ignored. + await fs.writeFile(path.join(storiesDir, "not-a-story.md"), "# ignored\n"); + + const ids = await discoverStoryIds(epicDir); + assert.deepEqual(ids, ["real-story"]); + } finally { + await fs.rm(epicDir, { recursive: true, force: true }); + } + }); + + it("returns deterministically sorted IDs regardless of filesystem order", async () => { + const epicDir = await mkTempDir(); + try { + const storiesDir = path.join(epicDir, "stories"); + await fs.mkdir(storiesDir); + // Create in reverse order. + for (const id of ["zzz-last", "aaa-first", "mmm-middle"]) { + await fs.mkdir(path.join(storiesDir, id)); + } + + const ids = await discoverStoryIds(epicDir); + assert.deepEqual(ids, ["aaa-first", "mmm-middle", "zzz-last"]); + } finally { + await fs.rm(epicDir, { recursive: true, force: true }); + } + }); +}); diff --git a/tests/subagent-model.test.ts b/tests/subagent-model.test.ts deleted file mode 100644 index ee07ccb..0000000 --- a/tests/subagent-model.test.ts +++ /dev/null @@ -1,215 +0,0 @@ -import assert from "node:assert/strict"; -import { describe, it } from "node:test"; - -import { buildSpawnArgs } from "../src/planner/subagent.js"; -import { - ALL_PHASE_MODEL_KEYS, - type PhaseModelKey, -} from "../src/planner/model-phase.js"; -import { - applyGeneralPurposeModel, - applyStrongModel, - initConfigFromActiveModel, -} from "../src/planner/ui/config/model-selection.js"; -import { - GENERAL_PURPOSE_PHASE_MODEL_KEYS, - STRONG_PHASE_MODEL_KEYS, -} from "../src/planner/model-phase.js"; - -// -- buildSpawnArgs: --model flag threading -- - -describe("buildSpawnArgs", () => { - const baseOpts = { - planDir: "/plan", - subagentDir: "/subagent", - extensionPath: "/ext/koan.ts", - cwd: "/working", - }; - - it("omits --model flag when modelOverride is absent", () => { - const args = buildSpawnArgs("architect", "plan-design", "start", baseOpts); - assert.equal(args.includes("--model"), false); - }); - - it("omits --model flag when modelOverride is undefined", () => { - const args = buildSpawnArgs("architect", "plan-design", "start", { - ...baseOpts, - modelOverride: undefined, - }); - assert.equal(args.includes("--model"), false); - }); - - it("includes --model flag and value when modelOverride is set", () => { - const args = buildSpawnArgs("architect", "plan-design", "start", { - ...baseOpts, - modelOverride: "anthropic/claude-opus-4", - }); - assert.ok(args.includes("--model"), "expected --model flag in args"); - const idx = args.indexOf("--model"); - assert.equal(args[idx + 1], "anthropic/claude-opus-4"); - }); - - it("places --model before the prompt (last arg)", () => { - const prompt = "Begin the plan-design phase."; - const args = buildSpawnArgs("architect", "plan-design", prompt, { - ...baseOpts, - modelOverride: "openai/gpt-5", - }); - const modelIdx = args.indexOf("--model"); - const promptIdx = args.indexOf(prompt); - assert.ok(modelIdx >= 0, "--model not found"); - assert.ok(promptIdx >= 0, "prompt not found"); - assert.ok(modelIdx < promptIdx, "--model should appear before prompt"); - }); - - it("places --model after extraFlags", () => { - const args = buildSpawnArgs("reviewer", "qr-plan-design", "Verify.", { - ...baseOpts, - extraFlags: ["--koan-qr-item", "item-42"], - modelOverride: "google/gemini-2-pro", - }); - const qrItemIdx = args.indexOf("--koan-qr-item"); - const modelIdx = args.indexOf("--model"); - assert.ok(qrItemIdx >= 0, "--koan-qr-item not found"); - assert.ok(modelIdx >= 0, "--model not found"); - assert.ok(qrItemIdx < modelIdx, "--model should appear after extra flags"); - }); - - it("preserves all required fixed args regardless of modelOverride", () => { - const args = buildSpawnArgs("developer", "plan-code", "begin", { - ...baseOpts, - modelOverride: "anthropic/claude-sonnet", - }); - assert.ok(args.includes("-p"), "-p flag missing"); - assert.ok(args.includes("-e"), "-e flag missing"); - assert.ok(args.includes("--koan-role"), "--koan-role missing"); - assert.ok(args.includes("--koan-phase"), "--koan-phase missing"); - assert.ok(args.includes("--koan-plan-dir"), "--koan-plan-dir missing"); - assert.ok(args.includes("--koan-subagent-dir"), "--koan-subagent-dir missing"); - }); -}); - -// -- Quick-set utility functions -- - -describe("initConfigFromActiveModel", () => { - it("creates a 20-key config with all keys set to the given model", () => { - const config = initConfigFromActiveModel("anthropic/claude-sonnet"); - assert.equal(Object.keys(config).length, ALL_PHASE_MODEL_KEYS.length); - for (const key of ALL_PHASE_MODEL_KEYS) { - assert.equal(config[key], "anthropic/claude-sonnet", `key ${key} should be set`); - } - }); - - it("produces a config where all values are the same model", () => { - const config = initConfigFromActiveModel("openai/gpt-5"); - const values = Object.values(config); - assert.ok(values.every((v) => v === "openai/gpt-5")); - }); -}); - -describe("applyStrongModel", () => { - it("sets all strong keys to the chosen model, leaving GP keys from existing config", () => { - const existing = initConfigFromActiveModel("openai/gpt-4"); - const result = applyStrongModel("anthropic/claude-opus-4", existing, "openai/gpt-4"); - - for (const key of STRONG_PHASE_MODEL_KEYS) { - assert.equal(result[key], "anthropic/claude-opus-4", `strong key ${key} should be updated`); - } - - for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { - assert.equal(result[key], "openai/gpt-4", `GP key ${key} should be unchanged`); - } - }); - - it("initializes from activeModelId when existingConfig is null", () => { - const result = applyStrongModel("anthropic/claude-opus-4", null, "openai/gpt-5-mini"); - - for (const key of STRONG_PHASE_MODEL_KEYS) { - assert.equal(result[key], "anthropic/claude-opus-4", `strong key ${key} should be updated`); - } - - for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { - assert.equal(result[key], "openai/gpt-5-mini", `GP key ${key} should be initialized from active model`); - } - }); - - it("writes all 20 keys regardless of which keys are strong", () => { - const result = applyStrongModel("some/model", null, "active/model"); - assert.equal(Object.keys(result).length, ALL_PHASE_MODEL_KEYS.length); - }); -}); - -describe("applyGeneralPurposeModel", () => { - it("sets all GP keys to the chosen model, leaving strong keys from existing config", () => { - const existing = initConfigFromActiveModel("anthropic/claude-opus-4"); - const result = applyGeneralPurposeModel("openai/gpt-5-mini", existing, "anthropic/claude-opus-4"); - - for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { - assert.equal(result[key], "openai/gpt-5-mini", `GP key ${key} should be updated`); - } - - for (const key of STRONG_PHASE_MODEL_KEYS) { - assert.equal(result[key], "anthropic/claude-opus-4", `strong key ${key} should be unchanged`); - } - }); - - it("initializes from activeModelId when existingConfig is null", () => { - const result = applyGeneralPurposeModel("openai/gpt-5-mini", null, "anthropic/claude-sonnet"); - - for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { - assert.equal(result[key], "openai/gpt-5-mini", `GP key ${key} should be updated`); - } - - for (const key of STRONG_PHASE_MODEL_KEYS) { - assert.equal(result[key], "anthropic/claude-sonnet", `strong key ${key} should be initialized from active model`); - } - }); - - it("writes all 20 keys regardless of which keys are GP", () => { - const result = applyGeneralPurposeModel("some/model", null, "active/model"); - assert.equal(Object.keys(result).length, ALL_PHASE_MODEL_KEYS.length); - }); -}); - -describe("quick-set from empty config: all-or-none persistence invariant", () => { - it("applyStrongModel from null config produces a 20-key config (all-or-none)", () => { - const result = applyStrongModel("strong/model", null, "active/model"); - const keys = Object.keys(result) as PhaseModelKey[]; - assert.equal(keys.length, ALL_PHASE_MODEL_KEYS.length); - - // Verify every expected key is present - for (const key of ALL_PHASE_MODEL_KEYS) { - assert.ok(key in result, `key "${key}" missing from result`); - assert.equal(typeof result[key], "string"); - assert.ok(result[key].length > 0); - } - }); - - it("applyGeneralPurposeModel from null config produces a 20-key config (all-or-none)", () => { - const result = applyGeneralPurposeModel("gp/model", null, "active/model"); - const keys = Object.keys(result) as PhaseModelKey[]; - assert.equal(keys.length, ALL_PHASE_MODEL_KEYS.length); - - for (const key of ALL_PHASE_MODEL_KEYS) { - assert.ok(key in result, `key "${key}" missing from result`); - } - }); - - it("strong and GP quick-set results are complementary", () => { - const activeModel = "active/model"; - - const strongResult = applyStrongModel("strong/model", null, activeModel); - const gpResult = applyGeneralPurposeModel("gp/model", null, activeModel); - - // Strong keys in strongResult should differ from GP keys - for (const key of STRONG_PHASE_MODEL_KEYS) { - assert.equal(strongResult[key], "strong/model"); - assert.equal(gpResult[key], activeModel); // GP result left strong keys as active - } - - for (const key of GENERAL_PURPOSE_PHASE_MODEL_KEYS) { - assert.equal(strongResult[key], activeModel); // strong result left GP keys as active - assert.equal(gpResult[key], "gp/model"); - } - }); -}); diff --git a/tests/widget.test.ts b/tests/widget.test.ts deleted file mode 100644 index bd2ea8e..0000000 --- a/tests/widget.test.ts +++ /dev/null @@ -1,173 +0,0 @@ -import assert from "node:assert/strict"; -import { describe, it } from "node:test"; - -import type { ExtensionUIContext, Theme } from "@mariozechner/pi-coding-agent"; -import { visibleWidth } from "@mariozechner/pi-tui"; - -import { WidgetController, formatPlanningHeaderLabel } from "../src/planner/ui/widget.js"; - -type WidgetInstance = { - render: (width: number) => string[]; - invalidate: () => void; -}; - -type WidgetFactory = ((tui: unknown, theme: Theme) => WidgetInstance) | undefined; - -function createPlainTheme(): Theme { - return { - fg: (_color: string, text: string) => text, - bg: (_color: string, text: string) => text, - bold: (text: string) => text, - } as unknown as Theme; -} - -function createWidgetHarness(): { - controller: WidgetController; - render: (width: number) => string[]; - destroy: () => void; -} { - const theme = createPlainTheme(); - let factory: WidgetFactory; - - const ui = { - theme, - setWidget: (_key: string, next: WidgetFactory) => { - factory = next; - }, - } as unknown as ExtensionUIContext; - - const controller = new WidgetController(ui, "plan-test-id"); - - return { - controller, - render: (width: number) => { - assert.ok(factory, "widget factory should be registered"); - return factory({} as unknown, theme).render(width); - }, - destroy: () => controller.destroy(), - }; -} - -describe("formatPlanningHeaderLabel", () => { - it("applies compaction in deterministic order", () => { - const phase = "Plan design"; - const status = "CURRENT"; - - const full = `Planning · ${phase} · ${status}`; - const shortStatus = `Planning · ${phase} · CUR`; - const noStatus = `Planning · ${phase}`; - const shortPhase = "Planning · Design"; - - assert.equal(formatPlanningHeaderLabel(phase, status, visibleWidth(full)), full); - assert.equal(formatPlanningHeaderLabel(phase, status, visibleWidth(full) - 1), shortStatus); - assert.equal(formatPlanningHeaderLabel(phase, status, visibleWidth(shortStatus) - 1), noStatus); - assert.equal(formatPlanningHeaderLabel(phase, status, visibleWidth(noStatus) - 1), shortPhase); - - const tiny = formatPlanningHeaderLabel(phase, status, 14); - assert.ok(visibleWidth(tiny) <= 14); - assert.ok(tiny.startsWith("Planning")); - }); -}); - -describe("WidgetController rendering", () => { - it("renders metadata header with 3-phase layout (no context gathering)", () => { - const harness = createWidgetHarness(); - try { - const lines = harness.render(140); - const text = lines.join("\n"); - - assert.match(text, /Planning · Plan design · CURRENT/); - assert.doesNotMatch(text, /Context gathering/); - assert.doesNotMatch(text, /┃ Context gathering ┃/); - } finally { - harness.destroy(); - } - }); - - it("renders merged runtime section with stage + quality + workers", () => { - const harness = createWidgetHarness(); - try { - harness.controller.update({ - qrIteration: 2, - qrIterationsMax: 6, - qrMode: "fix", - qrPhase: "verify", - qrDone: 9, - qrTotal: 14, - qrPass: 8, - qrFail: 1, - qrTodo: 5, - subagentQueued: 2, - subagentActive: 3, - subagentDone: 7, - subagentParallelCount: 4, - }); - - const text = harness.render(140).join("\n"); - assert.match(text, /Runtime/); - assert.match(text, /stage\s+: Verifying \(cycle 2\/6 · fix\)/); - assert.match(text, /quality\s+: checked 9\/14\s+pass 8\s+FAIL 1\s+remaining 5/); - assert.match(text, /workers\s+: queued 2\s+active 3\s+done 7\s+pool ×4/); - - assert.doesNotMatch(text, /\bQR\b\s+\|/); - assert.doesNotMatch(text, /\bSubagents\b\s+\|/); - assert.doesNotMatch(text, /\bCurrent step\b/); - } finally { - harness.destroy(); - } - }); - - it("uses Writing for execute debut and Fixing for execute fix", () => { - const harness = createWidgetHarness(); - try { - harness.controller.update({ - qrIteration: 1, - qrIterationsMax: 6, - qrMode: "initial", - qrPhase: "execute", - }); - - let text = harness.render(140).join("\n"); - assert.match(text, /stage\s+: Writing \(cycle 1\/6 · initial\)/); - - harness.controller.update({ - qrMode: "fix", - qrPhase: "execute", - }); - - text = harness.render(140).join("\n"); - assert.match(text, /stage\s+: Fixing \(cycle 1\/6 · fix\)/); - } finally { - harness.destroy(); - } - }); - - it("aligns identity table separator using dynamic key width", () => { - const harness = createWidgetHarness(); - try { - harness.controller.update({ - subagentRole: "reviewer", - subagentParallelCount: 12, - subagentModel: "openai-codex/gpt-5.3-codex", - }); - - const lines = harness.render(140); - const planLine = lines.find((line) => line.includes("Plan ID") && line.includes(" : ")); - const agentLine = lines.find((line) => line.includes("Agent pool") && line.includes(" : ")); - const modelLine = lines.find((line) => line.includes("Model") && line.includes(" : ")); - - assert.ok(planLine, "expected Plan ID row"); - assert.ok(agentLine, "expected Agent pool row"); - assert.ok(modelLine, "expected Model row"); - - const planSep = planLine.indexOf(" : "); - const agentSep = agentLine.indexOf(" : "); - const modelSep = modelLine.indexOf(" : "); - - assert.equal(planSep, agentSep); - assert.equal(agentSep, modelSep); - } finally { - harness.destroy(); - } - }); -}); From c766ac66926e20a5c4742defd28a89d10285de21 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 13 Mar 2026 12:46:55 +0700 Subject: [PATCH 047/412] docs: refresh planner docs and add repo invariants --- .config/wt.toml | 12 ++ AGENTS.md | 7 + README.md | 18 +- design-decisions.md | 412 ---------------------------------------- docs/planning-widget.md | 273 ++++++++++++-------------- 5 files changed, 149 insertions(+), 573 deletions(-) create mode 100644 .config/wt.toml create mode 100644 AGENTS.md delete mode 100644 design-decisions.md diff --git a/.config/wt.toml b/.config/wt.toml new file mode 100644 index 0000000..c705010 --- /dev/null +++ b/.config/wt.toml @@ -0,0 +1,12 @@ +# Koan project worktree hooks +# Docs: https://worktrunk.dev/hook/ + +[post-create] +deps = "npm ci" + +[post-start] +copy = "wt step copy-ignored" + +[pre-merge] +check = "npm run check" +test = "npm test" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..24d8ad4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,7 @@ +# Koan Architecture Invariant + +LLMs write **markdown files only**. LLMs communicate with the driver through **tool calls only**. +The driver maintains `.json` state files internally — no LLM ever reads or writes a `.json` file. + +Example: orchestrator calls `koan_complete_story(story_id)` → tool code writes `state.json` + `status.md` → +driver reads `state.json` to route next action. The orchestrator never touches `state.json` directly. diff --git a/README.md b/README.md index a8d832b..ac8d11a 100644 --- a/README.md +++ b/README.md @@ -15,19 +15,24 @@ The parent controls progression through plan design, plan code, plan docs, quali ## Invoking the Planner -Call `koan_plan` as an MCP tool — the LLM invokes it when the user asks to plan a complex task. No parameters are needed: the conversation up to that point is automatically exported to `conversation.jsonl` in the plan directory and becomes the planning context. +Call `koan_plan` as an MCP tool — the LLM invokes it when the user asks to plan a complex task. No parameters are needed: the conversation up to that point is automatically exported to `conversation.jsonl` in the plan directory and becomes planning input. The architect then persists a structured **background context** index via koan tools. The planning pipeline runs sequentially: -1. **plan-design** (architect) — reads `conversation.jsonl` to understand intent, explores the codebase, writes `plan.json`. +1. **plan-design** (architect) — reads `conversation.jsonl`, builds structured **background context** (previous conversation(s) + indexes), explores the codebase, writes `plan.json`. 2. **plan-code** (developer) — reads `plan.json`, populates code intents and changes. -3. **plan-docs** (technical writer) — reads `plan.json` and optionally `conversation.jsonl` for decisions and tradeoffs, writes documentation entries. +3. **plan-docs** (technical writer) — reads `plan.json` plus the injected background context snippet, and optionally `conversation.jsonl` for rationale gaps; writes documentation entries. Each phase is followed by a QR (quality review) block: decompose → parallel verify → fix loop, up to `MAX_FIX_ITERATIONS`. -### conversation.jsonl +### conversation.jsonl + background context -Written once at the start of `koan_plan`. Contains the full session branch as JSONL (one JSON object per line — raw pi `SessionManager` entries, not a plain-text transcript). The plan-design architect and plan-docs writer are told about this file and may `Read` it; other phases work from `plan.json` only. +`conversation.jsonl` is written once at the start of `koan_plan`. It contains the full session branch as JSONL (one JSON object per line — raw pi `SessionManager` entries, not a plain-text transcript). + +The architect categorically analyzes this file and persists compact markdown **background context** via: +- `koan_set_background_context` + +That context is then injected directly into prompts for planning and QR agents, alongside the conversation.jsonl location. ### Prompt + convention sources @@ -50,7 +55,8 @@ Key design choices that shape implementation: - **Default-deny permissions**: each phase explicitly allowlists tools; unknown tool/phase access is blocked. - **Disk-backed mutations**: planning mutations are immediately persisted with atomic writes instead of deferred finalize steps. - **Need-to-know prompts**: each subagent only receives the minimum context needed for its task. -- **Passive conversation context**: `conversation.jsonl` is a read-only artifact on disk. No phase programmatically injects it into prompts; agents that need it use the `Read` tool. +- **Injected background context**: each workflow step prompt prepends the same `` snippet containing conversation path + compact markdown context. +- **Ephemeral runtime workspace**: intermediate subagent logs/state live in a mkdtemp workspace and are removed on plan completion and session shutdown. ## Invariants diff --git a/design-decisions.md b/design-decisions.md deleted file mode 100644 index 6349a47..0000000 --- a/design-decisions.md +++ /dev/null @@ -1,412 +0,0 @@ -# Koan Design Decisions & Invariants - -Authoritative record of design decisions, invariants, and lessons learned -across the koan project. Distilled from 6 conversations (Feb 10-13 2026), -the master plan (plans/2026-02-10-init.md), and the approved tool registry -plan (~/.claude/plans/fluffy-hopping-zebra.md). - ---- - -## Fundamental Invariants - -### INV-1: Inversion of Control - -Scripts drive the LLM, not LLM drives scripts. The extension -programmatically feeds prompts, collects output, and enforces constraints. -The LLM is a worker, not a coordinator. This is the entire reason koan -exists -- the Claude Code skill model has the LLM in the driver's seat, -which causes unreliable workflow execution. - -### INV-2: Need-to-Know Principle - -The LLM always operates on a need-to-know basis. When given the choice -between exposing more or less information, always choose less. This is -a permanent invariant. - -Concrete implications: - -- No implementation details in prompts (temp dirs, state file paths, - orchestrator internals, phase routing) -- No full plan state when partial suffices (QR reviewer for design does - not see code plan or docs plan) -- No accumulated history across phases (subagents start fresh) -- No meta-instructions about the workflow ("you are step 3 of 14") -- No defensive over-specification of edge cases - -### INV-3: Pi Tool Error Contract - -Pi framework determines isError on ToolResultMessage from whether -tool.execute() THROWS, not from the return value. The returned isError -field is silently discarded (agent-loop.ts:316-357). To signal errors -from tools: always `throw new Error(msg)` -- never `return { isError: true }`. - ---- - -## Architecture Decisions - -### AD-1: Two LLM Interaction Levels - -- `spawn()` subagent: for all substantial work (architect, developer, - writer, QR decomposer, QR reviewer). -- `complete()` from pi-ai: NOT used in koan. No direct LLM calls - without agent loop. -- `sendUserMessage()` in parent session: NOT used. Planning is triggered via - the `koan_plan` MCP tool; conversation context is captured via `exportConversation()`. - -### AD-2: Self-Loading Extension Pattern - -Same extension file (extensions/koan.ts) serves both modes: - -- **Parent mode** (no --koan-role flag): registers the `koan_plan` MCP tool, - `/koan-execute`, `/koan-status` commands, and workflow dispatch. Zero overhead - in normal pi sessions. -- **Subagent mode** (--koan-role present): activates role-specific event - hooks (state machine, tool enforcement, step prompts). - -The extension detects which mode via flag presence at before_agent_start -time (not at init -- see AD-3). - -### AD-3: CLI Flag Timing - -Pi applies CLI flag values AFTER extension factory functions run -(main.ts:568). getFlag() returns defaults during factory time. -Subagent detection MUST happen in `before_agent_start`, not in the -factory function body. Uses closure-scoped `dispatched` boolean guard -to ensure one-shot dispatch. - -### AD-4: Tool-Call-Driven Step Transitions (Uniform Pattern) - -ALL step transitions use the koan_complete_step registered tool. The LLM -calls koan_complete_step -> tool execute() returns next step's prompt. -This works in both -p mode and interactive mode. `sendUserMessage()` is not -used; planning is triggered by the LLM invoking the `koan_plan` MCP tool. - -**KEY CORRECTION**: Early design (Feb 10) considered turn_end + -agent_end + sendUserMessage() chaining for step transitions. This was -ABANDONED because subagents in -p mode exit after the first agent loop -completes. Tool calls keep the agent loop alive within a single loop. - -**ANTI-PATTERN**: agent_end + sendUserMessage for retry was removed. -sendUserMessage is fire-and-forget in the extension binding. In -p mode -(subagents), the process can exit before the retry completes. Even in -interactive mode, some models say "calling tool X now" as text without -emitting a tool_call block, causing agent_end to fire spuriously. - -### AD-5: koan_complete_step Accepts Optional `thoughts` - -The extension is stateful -- it knows exactly which step the LLM is on -via closure state. No step number parameter needed. The tool response -contains the next step's full prompt. - -The optional `thoughts` parameter captures the model's work output -(analysis, findings, review) as a tool parameter instead of as text -output. This solves a cross-model compatibility issue: GPT-5-codex -cannot produce text + tool_call in the same response, so requiring -text output alongside a tool call caused it to narrate "Calling -koan_complete_step now" without emitting an actual tool_call block. - -### AD-6: Tool Naming Conventions - -Settled names (corrected from earlier iterations): - -- `koan_complete_step` (was koan_next_step -- renamed to accept `thoughts`) -- `koan_store_context` — REMOVED (was koan_finalize_context; removed with context-capture phase) -- `koan_store_plan` — REMOVED (see AD-14) -- `koan_plan` — MCP tool replacing the former `/koan plan` slash command -- Prompts use "instructions" not "actions" - -### AD-7: invoke_after Pattern Is Critical - -Every step prompt MUST have a clear "invoke after" directive telling -the LLM to call koan_complete_step after completing the step's work. -Mirrors the reference planner's "NEXT STEP: Command: python3 -m ... ---step N" pattern. Without this, the LLM produces text-only responses -and the agent loop exits. - -Implementation: formatStep() in src/planner/prompts/step.ts appends a -default invoke-after block. Steps can override with custom invokeAfter. - -The "WHEN DONE" + "Do NOT call until" creates a two-part gate: the LLM -must do work before advancing. Unconditional imperatives ("Execute this -tool now.") cause immediate tool calls because empty-param tool calls -have zero friction. - -### AD-8: Store Tools Need "Not Yet" Guidance - -(koan_store_context was removed with the context-capture phase; koan_store_plan -was removed earlier — see AD-14.) This pattern remains relevant for any -future store-style tools: tool description should include "DO NOT call this tool -until the step instructions explicitly tell you to." - -### AD-9: Subagent Progress Tracking - -Per-subagent state directory, NOT a single progress.json. -Structure: `/subagents/-/` -Contains: state.json, stdout.log, stderr.log. -ProgressReporter class manages state.json updates with trail. - -### AD-10: Embedded Planner Prompts + File-Based Conventions - -Planner subagent prompts are hard-coded in TypeScript at -`src/planner/lib/agent-prompts.ts` (architect, developer, -quality-reviewer, technical-writer). Phase loaders call -`loadAgentPrompt(...)`, so prompt availability does not depend on runtime -filesystem paths. - -Conventions remain file-based under `resources/conventions` so the LLM can -explore them directly with `Read`. `CONVENTIONS_DIR` is resolved at runtime -via `src/planner/lib/resources.ts` and injected into phase guidance where -needed. - -### AD-11: Plan Schema Self-Documentation via TypeBox - -No 300-line schema prompt embedded in step 6. Tool parameter schemas -with rich TypeBox descriptions are sufficient for the LLM to discover -the schema through tool definitions. This is the "most elegant" approach -per user preference. - -### AD-12: Context Capture Phases (REMOVED) - -The context-capture phase (draft/verify/refine sub-phases, koan_store_context -tool, context.json artifact) was removed. The parent conversation is now -exported as `conversation.jsonl` at `koan_plan` tool invocation. Phases that -need session context read the file directly via the `Read` tool. See -`src/planner/conversation.ts` for the export implementation. - -### AD-13: Default-Deny Tool Permissions - -Centralized Map> in src/planner/tools/registry.ts. -Unknown tools blocked in all phases. READ_TOOLS (read, bash, grep, glob, -find, ls) always allowed. WRITE_TOOLS (edit, write) always blocked during -planning. Missing phase keys are denied. - -Previous code had a "fails open" bug where tool_call handlers returned -undefined at the end of if-else chains, silently allowing unknown tools. - -### AD-14: Disk-Backed Plan Mutations (No Finalize) - -Each mutation tool: loadPlan(dir) -> mutate -> savePlan(plan, dir). -Atomic write. No in-memory accumulation + finalize pattern. The -koan_store_plan/koan_finalize_plan tool was REMOVED. - -Root cause: the LLM was skipping intermediate mutation tools and calling -koan_store_plan directly. The "build in memory then finalize" pattern -makes intermediate tools feel like ceremony. Immediate disk writes give -visible results per tool call. - -Every mutation tool returns descriptive feedback ("Added decision DL-003: -'Use polling'"). This prevents the LLM from skipping tools -- the LLM -needs evidence that each tool call produces results. - -### AD-15: Module Ownership - -- Plan-design prompts belong to the "architect" (plan-design.ts / - prompts/plan-design.ts) -- Conversation export belongs to session.ts / conversation.ts -- These are organizational decisions about which module owns which prompts - -### AD-16: 6-Step Architect Workflow (plan-design execute) - -1. Task Analysis & Exploration Planning -2. Codebase Exploration -3. Testing Strategy Discovery -4. Approach Generation -5. Assumption Surfacing -6. Milestone Definition & Plan Writing (plan mutation tools available) - -Steps 1-5: only READ_TOOLS + PLAN_GETTER_TOOLS + koan_complete_step allowed. -Step 6: plan mutation tools unlocked. - ---- - -## UI Decisions - -### UI-1: Planning Widget Cards & Timeline Rail -- Chosen on Feb 25 2026 via planning-widget design deck (Stacked Modular Cards + Vertical Timeline Rail). -- Rationale: make terminal output feel like a coherent operations workspace (not plain log spam), keep active progress glanceable, and preserve enough structure to scale into future phases without redesigning the shell. -- Implementation guardrails: - - Continue rendering through `canvasLine()` so the background fills full terminal width. - - Keep consistent card padding and solid-border framing through shared `renderBox()` helpers. - - Header metadata carries active workflow context (`Planning · · `), with timer right-aligned on the same row. - - The old phase-tab strip is removed (no duplicated heading context). - - Vertical rail remains width-bounded (~20 cols) so the right detail pane keeps enough budget for high-signal telemetry. - - Detail footer (`Plan · id`) is pinned bottom via dynamic padding, independent of timeline density. - - Planning body and latest-log body share one outer card, separated by an internal divider for better cohesion. - -### UI-2: Latest Log as Deterministic Dense Grid -- Chosen on Feb 25 2026 via follow-up deck (`Declarative Shape Table` + `Two-Column Dense Grid`). -- Rationale: long-running sessions need more than tool names; users must see intent without reading full payloads. Deterministic ordering reduces scan friction and makes anomalies obvious over time. -- Contract: - - Left column anchor is always tool name. - - Right column is deterministic summary from shape-table formatters (ID-first ordering for recognized tools). - - Unknown tools degrade to name-only output (generic fallback). - - Arrays render as first-item-plus-count; free-form fields render as size-only metadata. - - Getter tools include target metadata + response size (`resp:42L/3.1k`). - - Repeated events remain repeated (no collapse), preserving temporal audit fidelity. - - Column widths adapt to terminal width and observed tool-name lengths so detail space stays useful. - - In integrated mode, latest-log columns are forced to the same split as the planning body (`timelineWidth` / `detailWidth`) to keep vertical alignment stable. - - High-value rows may wrap to 2 lines only; deeper overflow is compacted with ellipsis to protect fixed card height. - -### UI-3: QR Integrated Section (Not Sidecar) -- Chosen on Feb 25 2026 via follow-up deck (`Inline Integrated Section + Divider`). -- Rationale: QR is the acceptance loop, not optional telemetry. Rendering it as an inline first-class section prevents the "detached widget" feel and matches how users reason about plan quality over time. -- Contract: - - QR is visible during Plan design, Plan code, and Plan docs (and contractually Plan execution). - - Iteration 1 enters `execute` immediately (same stage model as fix iterations); there is no separate `initializing` stage. - - Section includes: phase + iter/mode metadata, phase rail, and counters (`done/total/pass/fail/todo`) in a compact metadata block. - - Visual treatment uses inline sectioning + divider, not a nested bordered mini-card. - - Geometry is fixed for scan consistency: header + rail + counters + divider. - - Metadata uses a hard 64-char visible-width budget with progressive compaction (`exec/decomp/vfy`, `d/p/f/t`, `iN/M`) under narrow widths. - - Counter line emphasizes severity (`fail` highlighted in error color) so blocking issues pop in long sessions. - - Detail pane hierarchy is explicit: `Current step` label first, then step body, then QR section. - -### UI-4: Header-First Metadata (No Tabs Row) -- Chosen on Feb 26 2026 via follow-up deck focused on full-widget renders (`Phase-first header`). -- Rationale: the old title + tabs combination duplicated active-phase context and made the top of the widget feel offset from the frame. Consolidating into a full-width metadata header improves hierarchy and scan speed. -- Contract: - - Keep a full top border and render one header row: `Planning · · ` + right-aligned elapsed timer. - - Remove the dedicated tabs/chips row under the title. - - Keep phase progression in the left timeline rail (status history remains visible without tabs). - - Apply deterministic truncation in this order when width is constrained: abbreviate status -> drop status -> abbreviate phase label -> ellipsis. - - Footer identity table remains key/value aligned: `Plan ID`, `Agent`/`Agent pool`, `Model`. - -## Workflow Dispatch Architecture - -### WorkflowDispatch (dispatch pattern) - -Workflow tools (koan_complete_step) are registered once at init. Their -execute() callbacks read from a mutable dispatch object. Phases hook/unhook -dispatch slots at activation/deactivation time. - -hookDispatch() throws if a slot is already occupied -- prevents silent -misrouting when two phases try to claim the same tool. - -### PlanRef (mutable reference) - -All plan mutation tools share a mutable `{ dir: string | null }` set -when koan_plan tool creates a directory or when --koan-plan-dir is received. -Decouples tool registration (init-time) from directory creation (runtime). - -### Pi Registers Tools at \_buildRuntime() - -Pi snapshots tools during \_buildRuntime(). Tools registered after this -point are invisible to the LLM. All 44+ tools register unconditionally -at init; phases restrict access via tool_call blocking at runtime. - ---- - -## What Is NOT Ported from Reference Planner - -| Reference planner component | Koan replacement | -| --------------------------------------- | ------------------------------------- | -| CLI mutation scripts (cli/plan.py) | Pi extension tool registration | -| Thin router pattern (shared/routing.py) | Orchestrator deterministic gate logic | -| File-based state_dir | In-memory state + appendEntry() | -| Template dispatch | Direct process spawning | -| Constraint enforcement via prompt | tool_call event blocking | -| Agent markdown definitions | Self-loading extension pattern | -| Question relay handler | Not implemented (may add later) | - ---- - -## Bugs & Lessons Learned - -### BUG-1: LLM Conflates Tool Instructions with Plan Content - -In the former context-capture phase, the LLM captured tool usage instructions as -constraints (e.g. "Use read tool before modifying files; edit for -surgical changes"). These are irrelevant developer instructions, not -task constraints. Solution: prompts explicitly state "Only include -constraints that are specific to this task. Do not include general -tool usage instructions, coding style guides, or editor/IDE conventions." - -### BUG-2: LLM Skips Mutation Tools - -The LLM called koan_complete_step through steps 1-5, then at step 6 skipped -all mutation tools and called koan_store_plan directly. The in-memory -plan was empty. Root cause: mutation tools returned opaque JSON with no -feedback -- they felt like ceremony. Solution: remove finalize tool, -disk-backed mutations, descriptive feedback per tool call (AD-14). - -### BUG-3: tool_call Handlers Fail Open - -Original tool_call handlers returned undefined at end of if-else chains, -silently allowing any new tool. Solution: default-deny permissions map -(AD-13). - -### BUG-4: isError Return Value Discarded - -Pi discards the isError field from tool return values. Only throw/no-throw -determines error status. This caused silent failures where tools returned -{ isError: true } but the framework treated them as success. Solution: -always throw new Error(msg) for error conditions (INV-3). - -### BUG-5: Weak invoke_after Causes Step Skipping - -Original weak format ("Now call koan_next_step.") produced skipped steps. -The LLM called the tool immediately without doing work, because tool -calls with empty params have zero friction. Solution: strengthen to -"WHEN DONE: Call koan_complete_step with your findings in the `thoughts` -parameter. Do NOT call this tool until the work described in this step -is finished." - -### BUG-6: Flag Detection at Init Time - -Early implementation tried to detect --koan-role in the extension factory -function body. Flags are unavailable at that point (main.ts:568 sets them -after). Solution: move detection to before_agent_start with dispatched -guard (AD-3). - ---- - -## Plan JSON Schema - -Matches reference planner's Pydantic schema (shared/schema.py). -Types defined in src/planner/plan/types.ts. - -Key entities: Plan, Decision, RejectedAlternative, Risk, Milestone, -CodeIntent, CodeChange, Wave, DiagramGraph, ReadmeEntry, Overview, -InvisibleKnowledge, PlanningContext. - -Cross-reference validation: intent_ref -> intents, decision_ref -> -decisions, diagram edges source/target -> nodes, wave milestones -> milestone IDs. - ---- - -## QR Block Pattern - -Work -> Decompose -> Verify (parallel) -> Gate. Repeated per phase -(design, code, docs). Gate is deterministic code, no LLM. Max 5 -iterations. Force-proceed after limit. - -QR tools: koan_qr_add_item, koan_qr_set_item, koan_qr_assign_group, -koan_qr_get_item, koan_qr_list_items, koan_qr_summary. - ---- - -## Current Implementation State (Mar 1 2026) - -Implemented: - -- [x] Extension entry point with dual-mode detection -- [x] koan_plan MCP tool (replaces /koan plan slash command) -- [x] Conversation export to conversation.jsonl (replaces context-capture phase) -- [x] Plan-design architect subagent (6-step workflow) -- [x] Developer role (plan-code phase) -- [x] Technical writer role (plan-docs phase) -- [x] QR decompose subagent -- [x] QR verify subagent (parallel pool, concurrency 6) -- [x] QR gate routing + fix loop (up to MAX_FIX_ITERATIONS) -- [x] Fix mode (architect/developer/writer fix subagents) -- [x] 44+ plan mutation/getter tools with TypeBox schemas -- [x] Default-deny tool permissions (registry.ts) -- [x] WorkflowDispatch + PlanRef patterns -- [x] Subagent spawning with progress tracking -- [x] Disk-backed plan mutations (no finalize) -- [x] Plan validation (design + cross-references) - -Not yet implemented: - -- [ ] State persistence (appendEntry + session_start restore) -- [ ] Plan execution workflow (milestone execution) -- [ ] /koan-execute command diff --git a/docs/planning-widget.md b/docs/planning-widget.md index 639a4c0..a7d40a7 100644 --- a/docs/planning-widget.md +++ b/docs/planning-widget.md @@ -1,177 +1,140 @@ -# Planning Widget Refresh +# Planning Widget ## Context -The planning widget now follows the design-deck contract selected on Feb 25 2026: +The planning widget follows the stacked-card + timeline-rail layout and optimizes for long-running sessions (30-120 minutes). -- **Canvas direction:** Stacked Modular Cards -- **Navigation direction:** Vertical Timeline Rail -- **Header strategy:** Full-width top border + metadata header row (active phase in header, no tabs strip) -- **Log strategy:** Declarative shape-table serialization + dense two-column layout -- **Runtime strategy:** Unified runtime section (stage + quality + workers) integrated into the detail pane +The runtime pane is designed around one principle: -The goal is to keep a long-running (1-2h) planning session readable in real time while preserving high-signal audit telemetry. +- show where the active subagent is **inside its workflow** (`step number + step title`), +- not the orchestrator's internal QR fix-loop iteration counter. -## Decisions & Rationale +## Design Goals -### 1) Deterministic log serialization (hybrid detail) -- Keep **tool name** as the primary scan anchor. -- Use a declarative per-tool formatter table for known `koan_*` tools. -- Unknown tools fall back to tool-name-only output. -- Field order is deterministic and curated (e.g., IDs first), not alphabetical. +1. **Immediate progress readability** + - The user should answer “how far along are we?” in one glance. +2. **Active worker clarity** + - The widget should show who is running now and pool load (`queued/active/done`). +3. **Meaningful output accounting** + - Show entity modifications as `+delta (total)`. +4. **Stable visual scan path** + - Header + timeline + runtime + latest log remain in fixed positions. -**Rationale:** Users scan continuously during execution; stable order makes visual parsing faster and reduces cognitive churn between updates. +## Runtime Information Hierarchy -### 2) Selective detail by field type -- Arrays render as **first item + count** (`[first] +N`). -- Free-form fields (`diff`, `doc_diff`, `comments`, large narrative strings) render as **size metadata only** (`184L/9.2k`), never full body. -- Getter tools (`koan_get_*`) show target identifiers plus response size metadata (`resp:42L/3.1k`). +From highest to lowest priority: -**Rationale:** Maintains observability without blowing out vertical space or flooding with low-value text. +1. `step` (`current/total · title`) +2. step-based progress bar +3. active subagents block (role/model/load/mode) +4. modifications block (`Δ / total`) +5. latest log (auditable tail) -### 3) Latest log as dense two-column grid -- Left column: tool name (bold accent anchor). -- Right column: compact deterministic summary. -- Column widths adapt to available terminal width + observed tool-name lengths (protecting right-column readability). -- High-value rows may wrap to 2 lines; if overflow exceeds 2 lines, the second line is re-compacted with ellipsis. -- Repeated events remain separate rows (no dedup/collapse). +## Layout Overview -**Rationale:** Preserves temporal fidelity while increasing information density and keeping the "what just happened" answer immediate, even under constrained widths. +``` +┌──────────────────────────────────── Runtime ──────────────────────────────────── 33m 14s ┐ +│ step : 2/6 · Codebase Exploration │ +│ progress : ███████░░░░░░░░░░ 33% │ +│──────────────────────────────────────────┬──────────────────────────────────────────│ +│ active subagents │ modifications (Δ / total) │ +│ role : architect │ milestones : +2 (6) │ +│ model : anthropic/claude-opus-4-6 │ decisions : +1 (9) │ +│ load : queued 0 active 1 done 0 │ intents : +4 (18) │ +│ mode : single │ changes : +0 (3) │ +└──────────────────────────────────────────┴──────────────────────────────────────────┘ +``` -### 4) Runtime is a first-class workflow section -- Runtime renders inline in the detail pane (no detached mini-card border). -- Visible during Plan design, Plan code, and Plan docs (and contractually Plan execution). -- Runtime unifies stage + quality counters + worker counters in one block. -- Stage follows the QR lifecycle (`execute`, `decompose`, `verify`, `done`) but uses user-facing labels (`Writing`, `Fixing`, `Analyzing`, `Verifying`, `Complete`). -- Quality counters emphasize severity: `FAIL` is error-colored; `pass` is accent; others remain muted/dim. +Elapsed time remains right-aligned in the top row. -**Rationale:** Review quality and worker throughput are part of one runtime story. Unifying them removes competing mini-status bars while keeping the left timeline as the primary progress signal. +## Phase-Specific Modifications Panel -### 5) Header-first metadata, tabs removed -- Keep a full top border and put active workflow context directly in the header row. -- Header format is phase-first: `Planning · · ` on the left, elapsed timer right-aligned. -- Remove the separate phase-tabs strip entirely; it is redundant once active context is in the header. -- Keep timeline rows in the body (left rail) because they provide progression context and status history, unlike tabs. +### A) Plan design / plan code / plan docs / execution +Show plan-modification counters: -**Rationale:** The previous title treatment felt detached from the frame and duplicated information with the tabs row. Consolidating context into the header yields a cleaner hierarchy and better information density in TUI constraints. +- `milestones : +Δ (total)` +- `decisions : +Δ (total)` +- `intents : +Δ (total)` +- `changes : +Δ (total)` -## Layout Overview -``` -┌────────────────────────────────────────────────────────────────────────────────┐ -│ Planning · Plan design · CURRENT 12m 22s │ -│ │ -│ ● Plan design Runtime │ -│ │ CURRENT stage : Writing (cycle 1/6 · initial) │ -│ │ quality : checked -/- pass - FAIL - remaining - │ -│ ○ Plan code workers : queued 0 active 1 done 0 pool ×1 │ -│ │ UPCOMING │ -│ ○ Plan docs │ -│ UPCOMING │ -│ Plan ID : │ -│ Agent : architect │ -│ Model : openai-codex/gpt-5.3-codex │ -│────────────────────────────────────────────────────────────────────────────────│ -│ Latest log │ -│ koan_set_milestone_tests id=M-002 · tests:["covers retries"] +7 │ -│ koan_get_milestone id=M-002 · resp:42L/3.1k │ -│ koan_add_intent milestone=M-002 · file=src/planner/ui/widget.ts │ -│ koan_set_change_diff id=CC-M-001-002 · diff:184L/9.2k │ -│ koan_qr_assign_group phase=plan-design · ids:[QR-001] +11 │ -└────────────────────────────────────────────────────────────────────────────────┘ -``` +### B) QR decompose +Show QR decomposition counters: -## Rendering Guide -1. **Canvas** – Keep using `canvasLine()` so widget content remains full-width over `toolPendingBg`. -2. **Main card** – Keep one solid outer border + a full top rule. No cutout title and no detached title badge. -3. **Header row** – Render `Planning · · ` on the left and elapsed timer right-aligned on the same row. -4. **No tabs strip** – Do not render a separate phase-tabs row under the header. Active phase context now lives in header metadata. -5. **Timeline rail** – Maintain status icon/color semantics (`active=accent`, `done=dim`, `failed=error`). -6. **Detail pane** – Render in this order: - - Runtime section (if stage/quality/workers are active) - - identity table (`Plan ID`, `Agent`/`Agent pool`, `Model`) pinned low in pane -7. **Runtime section** – Use inline `Runtime` header plus key/value rows: - - `stage` + cycle metadata - - `quality` counters (`checked/pass/FAIL/remaining`) - - `workers` counters (`queued/active/done`) + pool capacity - Keep this as one cohesive block to avoid competing status bars. -8. **Latest log section** – Keep it inside the same outer card, separated by a horizontal divider. Reuse the same left/right column split (`timelineWidth` / `detailWidth`) and gap as the planning body so vertical alignment stays consistent. - -## Header + Alignment Contract - -### Header composition -- Inner card width is `W` (visible cells, excluding borders). -- Timer token is right-aligned and reserved first (`T` visible cells). -- Left header budget is `W - T - 1` (one spacer between left and right chunks). -- Base left chunk: `Planning · · `. - -### Progressive compaction (left header) -Apply in order until it fits: -1. `CURRENT` -> `CUR`, `UPCOMING` -> `UP`, `DONE` unchanged. -2. Drop status chunk (keep `Planning · `). -3. Abbreviate known phases (`Plan design` -> `Design`, `Plan code` -> `Code`, `Plan docs` -> `Docs`). -4. Ellipsize active phase tail (`Planning · `). - -### Metadata table alignment -- Keys are fixed labels: `Plan ID`, `Agent` or `Agent pool`, `Model`. -- Compute key column width from max visible key length in the rendered set. -- Use a fixed `" : "` separator. -- Values are right-column free text, truncated with ellipsis when overflowing pane width. - -### Latest-log alignment -- Keep deterministic two-column geometry shared with body split. -- Left column width is based on observed max tool name (capped); right column gets remaining width. -- High-value rows may wrap to two lines max; second line must still obey right-column width budget. +- `qr items added : +Δ (total)` +- `qr items updated : +Δ (total)` +- `groups assigned : +Δ (total)` + +### C) QR verify +Show explicit placeholder (by design): + +- `[placeholder]` +- `qr-verify counters not instrumented yet` + +This placeholder is intentional and must be rendered explicitly rather than silently omitting the panel. + +## Rendering Contract + +1. **Header row** + - Left: `Planning · · ` + - Right: elapsed timer + - Keep deterministic compaction when width is constrained. + +2. **Timeline rail (left column)** + - Keep phase icons/status semantics (`pending/running/completed/failed`). + +3. **Runtime detail (right column)** + - First two lines are always step + progress bar. + - Then split into two panes: + - left: `active subagents` + - right: `modifications` + +4. **Latest log** + - Keep current deterministic two-column rendering and tool-shape serialization. + +## Progress Semantics + +- Primary progress is based on active subagent workflow steps. +- The progress bar denominator is the subagent’s step total. +- For `qr-verify`, where reviewer execution is pooled, progress uses grouped verification progress (`done/total groups`) as the step/progress source. +- QR fix-loop cycle counters are internal orchestration state and are not part of the primary runtime progress display. + +## Active Subagents Semantics + +Runtime subagent block renders aggregate execution state: -## Data Contract Notes -- Header metadata state includes: - - `activePhaseLabel`, `activePhaseStatus`, `elapsed` -- `LogLine` now carries: - - `tool` (left column) - - `summary` (right column) - - `highValue` (whether 2-line wrap is allowed) -- QR state in widget includes: - - `qrIteration`, `qrIterationsMax`, `qrMode`, `qrPhase` - - `qrDone`, `qrTotal`, `qrPass`, `qrFail`, `qrTodo` - -## Future Work (contracted, not yet implemented) -- Plan execution phase should reuse the same Runtime section semantics. -- Optional compact mode for very narrow terminals can reduce metadata verbosity while preserving deterministic ordering. - -## Update: Unified Runtime Section + Subagent Identity (2026-03-04) - -This update replaces the split QR/subagent status blocks with a single runtime -status section in the right pane. - -### Runtime merge (stage + quality + workers) -- The detail pane now has one **Runtime** section. -- Runtime includes: - - `stage` (`Writing` / `Fixing` / `Analyzing` / `Verifying` / `Complete`) with cycle metadata. - - `quality` counters (`checked`, `pass`, `FAIL`, `remaining`). - - `workers` counters (`queued`, `active`, `done`) plus pool capacity. -- The left timeline remains the primary progress signal. - -### `x` meaning in parallel mode -- `x` means configured pool capacity (target parallelism), not active count. -- Active movement remains in `queued/active/done` counters. - -### Footer identity table standard -Use a unified key/value footer block: - -- `Plan ID : ` -- `Agent : ` (single subagent) -- `Agent pool : x` (parallel mode) -- `Model : ` - -### Generic rendering rule -The widget should remain role-agnostic and render identity from generic metadata -only: - `role` -- `parallelCount` - `model` +- `load` (`queued`, `active`, `done`) +- `mode` (`single` or `pool ×N`) + +`x` denotes configured pool capacity (target parallelism), not current active count. -Label/value rule: -- `parallelCount > 1` -> `Agent pool : x` -- otherwise -> `Agent : ` +## Modifications Counter Semantics + +Formatting rule: + +- `+2 (6)` means **delta +2**, **current total 6**. + +General rules: + +- Delta is scoped to the currently running phase block. +- Total is the current persisted artifact count at render time. +- Missing counters should render explicit placeholders (never blank rows). + +## Data Contract Notes -### View-composition pattern -Use section-level selectors/renderers so `runtime-status` and `identity` remain -independently composable and testable. +- Header metadata: active phase label/status + elapsed time. +- Step/progress data: step index, step total, step title (or grouped verify progress fallback). +- Subagent telemetry: role, model, parallel count, queued/active/done. +- Log lines: deterministic `tool + summary` rows. +- Modification counters: + - plan phases: milestones/decisions/intents/changes (delta + total) + - qr-decompose: added/updated/grouped (delta + total) + - qr-verify: explicit placeholder. + +## Rationale Summary + +- Step-first progress reduces ambiguity during long runs. +- Aggregate subagent telemetry keeps runtime compact while still explaining throughput. +- `Δ / total` counters answer both “what changed recently?” and “how much exists now?”. +- Explicit placeholders prevent silent uncertainty during uninstrumented phases. +- Stable layout preserves user orientation while high-frequency updates stream in. From bf69a315bf3254e3fcf24c050fc1bc12dd6a3c07 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:47:48 +0700 Subject: [PATCH 048/412] add esbuild, preact, zustand dev dependencies --- package-lock.json | 550 +++++++++++++++++++++++++++++++++++++++++++++- package.json | 8 +- 2 files changed, 555 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 3859420..cd93c99 100644 --- a/package-lock.json +++ b/package-lock.json @@ -13,7 +13,10 @@ }, "devDependencies": { "@mariozechner/pi-coding-agent": "^0.52.10", - "typescript": "^5.9.3" + "esbuild": "^0.25.1", + "preact": "^10.26.2", + "typescript": "^5.9.3", + "zustand": "^4.5.7" } }, "node_modules/@anthropic-ai/sdk": { @@ -840,6 +843,448 @@ "url": "https://github.com/sponsors/Borewit" } }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz", + "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz", + "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz", + "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz", + "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz", + "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz", + "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz", + "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz", + "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz", + "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz", + "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz", + "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz", + "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz", + "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz", + "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz", + "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz", + "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz", + "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz", + "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz", + "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz", + "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz", + "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz", + "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz", + "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz", + "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz", + "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz", + "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, "node_modules/@google/genai": { "version": "1.41.0", "resolved": "https://registry.npmjs.org/@google/genai/-/genai-1.41.0.tgz", @@ -2387,6 +2832,48 @@ "dev": true, "license": "MIT" }, + "node_modules/esbuild": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz", + "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.25.12", + "@esbuild/android-arm": "0.25.12", + "@esbuild/android-arm64": "0.25.12", + "@esbuild/android-x64": "0.25.12", + "@esbuild/darwin-arm64": "0.25.12", + "@esbuild/darwin-x64": "0.25.12", + "@esbuild/freebsd-arm64": "0.25.12", + "@esbuild/freebsd-x64": "0.25.12", + "@esbuild/linux-arm": "0.25.12", + "@esbuild/linux-arm64": "0.25.12", + "@esbuild/linux-ia32": "0.25.12", + "@esbuild/linux-loong64": "0.25.12", + "@esbuild/linux-mips64el": "0.25.12", + "@esbuild/linux-ppc64": "0.25.12", + "@esbuild/linux-riscv64": "0.25.12", + "@esbuild/linux-s390x": "0.25.12", + "@esbuild/linux-x64": "0.25.12", + "@esbuild/netbsd-arm64": "0.25.12", + "@esbuild/netbsd-x64": "0.25.12", + "@esbuild/openbsd-arm64": "0.25.12", + "@esbuild/openbsd-x64": "0.25.12", + "@esbuild/openharmony-arm64": "0.25.12", + "@esbuild/sunos-x64": "0.25.12", + "@esbuild/win32-arm64": "0.25.12", + "@esbuild/win32-ia32": "0.25.12", + "@esbuild/win32-x64": "0.25.12" + } + }, "node_modules/escalade": { "version": "3.2.0", "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz", @@ -3237,6 +3724,17 @@ "url": "https://github.com/sponsors/isaacs" } }, + "node_modules/preact": { + "version": "10.29.0", + "resolved": "https://registry.npmjs.org/preact/-/preact-10.29.0.tgz", + "integrity": "sha512-wSAGyk2bYR1c7t3SZ3jHcM6xy0lcBcDel6lODcs9ME6Th++Dx2KU+6D3HD8wMMKGA8Wpw7OMd3/4RGzYRpzwRg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/preact" + } + }, "node_modules/proper-lockfile": { "version": "4.1.2", "resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz", @@ -3311,6 +3809,17 @@ "dev": true, "license": "MIT" }, + "node_modules/react": { + "version": "19.2.4", + "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz", + "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==", + "dev": true, + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/require-directory": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", @@ -3866,6 +4375,16 @@ "dev": true, "license": "MIT" }, + "node_modules/use-sync-external-store": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz", + "integrity": "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==", + "dev": true, + "license": "MIT", + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" + } + }, "node_modules/web-streams-polyfill": { "version": "3.3.3", "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz", @@ -4039,6 +4558,35 @@ "peerDependencies": { "zod": "^3.25 || ^4" } + }, + "node_modules/zustand": { + "version": "4.5.7", + "resolved": "https://registry.npmjs.org/zustand/-/zustand-4.5.7.tgz", + "integrity": "sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==", + "dev": true, + "license": "MIT", + "dependencies": { + "use-sync-external-store": "^1.2.2" + }, + "engines": { + "node": ">=12.7.0" + }, + "peerDependencies": { + "@types/react": ">=16.8", + "immer": ">=9.0.6", + "react": ">=16.8" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "immer": { + "optional": true + }, + "react": { + "optional": true + } + } } } } diff --git a/package.json b/package.json index b3ebab9..a7f9e41 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,8 @@ ], "scripts": { "check": "tsc --noEmit", - "build": "tsc --project tsconfig.build.json", + "build:web": "esbuild src/planner/web/js/app.jsx --bundle --format=esm --jsx=automatic --jsx-import-source=preact --alias:react=preact/compat --alias:react-dom=preact/compat --outfile=src/planner/web/dist/app.js --minify", + "build": "npm run build:web && tsc --project tsconfig.build.json", "pretest": "npm run build", "test": "node --test --test-concurrency=1 build/tests" }, @@ -33,6 +34,9 @@ }, "devDependencies": { "@mariozechner/pi-coding-agent": "^0.52.10", - "typescript": "^5.9.3" + "esbuild": "^0.25.1", + "preact": "^10.26.2", + "typescript": "^5.9.3", + "zustand": "^4.5.7" } } From 4d00b459d1e8e1e180452a044c48d70b1228ee62 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:47:56 +0700 Subject: [PATCH 049/412] add task manifest module for subagent directory contract --- src/planner/lib/task.ts | 117 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 src/planner/lib/task.ts diff --git a/src/planner/lib/task.ts b/src/planner/lib/task.ts new file mode 100644 index 0000000..e38da74 --- /dev/null +++ b/src/planner/lib/task.ts @@ -0,0 +1,117 @@ +// Subagent task manifest — the input contract for every subagent process. +// Written by the parent to {subagentDir}/task.json before spawn; +// read by the child exactly once at startup via readTaskFile(). +// +// This is one of three well-known JSON files in every subagent directory: +// task.json — what to do (parent writes before spawn, child reads once) +// state.json — what has been done (child writes continuously, parent polls) +// ipc.json — what is needed now (both sides, transient per-request) +// +// The discriminated union on `role` keeps role-specific fields naturally +// nested rather than collapsed into a flat CLI flag namespace. This directly +// prevents the naming collisions the old flag approach produced — e.g., the +// previous `--koan-role` (pipeline role: "scout") vs `--koan-scout-role` +// (investigator persona: "security auditor") collision is impossible here +// because ScoutTask.role and ScoutTask.investigatorRole are distinct typed +// fields on a struct, not adjacent strings in a flat namespace. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + +import type { SubagentRole, StepSequence } from "../types.js"; + +// -- Task types -- + +interface SubagentTaskBase { + role: SubagentRole; + epicDir: string; +} + +/** Task manifest for intake subagents. */ +export interface IntakeTask extends SubagentTaskBase { + role: "intake"; +} + +/** + * Task manifest for scout subagents. Written by the IPC responder when a + * planning role (intake, decomposer, planner) calls koan_request_scouts. + */ +export interface ScoutTask extends SubagentTaskBase { + role: "scout"; + /** The narrow investigation question, injected verbatim into step 1 guidance. */ + question: string; + /** + * Output path relative to subagentDir (e.g. "findings.md"). + * Stored relative so the manifest is location-independent. + * Resolved to absolute by dispatch: `path.join(ctx.subagentDir!, task.outputFile)`. + */ + outputFile: string; + /** Investigator persona for the scout LLM (e.g. "security auditor", "API analyst"). */ + investigatorRole: string; +} + +/** Task manifest for decomposer subagents. */ +export interface DecomposerTask extends SubagentTaskBase { + role: "decomposer"; +} + +/** Task manifest for orchestrator subagents. */ +export interface OrchestratorTask extends SubagentTaskBase { + role: "orchestrator"; + stepSequence: StepSequence; + storyId?: string; +} + +/** Task manifest for planner subagents. */ +export interface PlannerTask extends SubagentTaskBase { + role: "planner"; + storyId: string; +} + +/** Task manifest for executor subagents. */ +export interface ExecutorTask extends SubagentTaskBase { + role: "executor"; + storyId: string; + /** + * Failure summary from a previous execution attempt, sourced from the + * `failure_summary` parameter of `koan_retry_story`. Absent on first run. + */ + retryContext?: string; +} + +// The union is exhaustive over all six roles. TypeScript narrows task.role +// in switch/case so role-specific fields are accessible without casting. +export type SubagentTask = + | IntakeTask + | ScoutTask + | DecomposerTask + | OrchestratorTask + | PlannerTask + | ExecutorTask; + +// -- File paths -- + +const TASK_FILE = "task.json"; +const TASK_TMP_FILE = ".task.tmp.json"; + +// -- I/O -- + +// Atomically writes task.json to subagentDir (tmp → rename). +// MUST be called before spawn() — the child reads this file at startup and +// throws if it is missing. There is no recovery path if it arrives late. +export async function writeTaskFile(subagentDir: string, task: SubagentTask): Promise { + const tmp = path.join(subagentDir, TASK_TMP_FILE); + const target = path.join(subagentDir, TASK_FILE); + await fs.writeFile(tmp, `${JSON.stringify(task, null, 2)}\n`, "utf8"); + await fs.rename(tmp, target); +} + +// Reads and parses task.json from subagentDir. +// Called exactly once, during before_agent_start in koan.ts. +// Throws on missing file or JSON parse error — both indicate a programming +// error in the parent (wrote no file, or wrote malformed JSON), not a +// recoverable runtime condition. +export async function readTaskFile(subagentDir: string): Promise { + const raw = await fs.readFile(path.join(subagentDir, TASK_FILE), "utf8"); + return JSON.parse(raw) as SubagentTask; +} From 62d3d7b07e05fdd8a6c382133e3613d31d53b6fa Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:48:04 +0700 Subject: [PATCH 050/412] add bash output truncation override for large skill outputs --- src/planner/lib/truncation-override.ts | 90 ++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 src/planner/lib/truncation-override.ts diff --git a/src/planner/lib/truncation-override.ts b/src/planner/lib/truncation-override.ts new file mode 100644 index 0000000..d7e2338 --- /dev/null +++ b/src/planner/lib/truncation-override.ts @@ -0,0 +1,90 @@ +// Raises the effective truncation limit for bash tool output in koan subagents. +// +// Pi's built-in bash tool truncates output to 50KB / 2000 lines. When the +// prompt-engineer skill (or any skill that concatenates large reference files +// to stdout) runs via bash, the LLM loses critical context mid-output. +// +// Instead of replacing the built-in bash tool, we intercept the tool_result +// event. When truncation occurred, the bash tool has already saved the full +// output to a temp file. We re-read that file and apply truncateTail with +// higher limits, then return the replacement content. This is surgical — +// it only activates when truncation actually happened and a temp file exists. +// +// Why tool_result interception rather than registering a replacement bash tool: +// - No duplication of the bash tool implementation (exec, streaming, exit codes) +// - The bash tool's temp file mechanism is the key enabler — the full output +// is already on disk before the event fires +// - Zero cost when output fits within the default limits (handler exits early) +// +// Registration is unconditional (not gated on subagent mode) because both +// parent sessions running skills directly and spawned subagent processes +// benefit from higher limits. The truncation guard makes it a no-op for +// outputs that fit within pi's defaults. +// +// Audit handler ordering: the audit tool_result handler (registered inside +// before_agent_start, after this one) records the ORIGINAL event content +// because it does not return a modified result — it only appends to the log. +// Pi runs handlers in registration order; each handler receives the event +// state as modified by prior handlers. Since the audit handler returns nothing, +// it never sees our replacement content, and since we don't touch the audit +// log, the two handlers are fully independent. + +import { readFileSync } from "node:fs"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; +import { truncateTail, formatSize, isBashToolResult } from "@mariozechner/pi-coding-agent"; + +// 4x the pi defaults (50KB / 2000 lines). Sized for the prompt-engineer skill, +// which concatenates ~100-150KB of technique reference files into a single bash +// call. 200KB gives comfortable headroom; 5000 lines is proportional (2.5x). +const KOAN_MAX_BYTES = 200 * 1024; +const KOAN_MAX_LINES = 5000; + +export function registerTruncationOverride(pi: ExtensionAPI): void { + pi.on("tool_result", (event) => { + if (!isBashToolResult(event)) return; + if (!event.details?.truncation?.truncated) return; + if (!event.details?.fullOutputPath) return; + + const fullOutputPath = event.details.fullOutputPath; + + // readFileSync is fine here — the runner awaits handlers so async would + // also work, but there's no benefit for a single temp file read. + // + // Timing note: the bash tool calls tempFileStream.end() then immediately + // resolves. On local filesystems the OS write completes before the + // microtask chain reaches this handler. If this ever causes incomplete + // reads on network filesystems, switch to async readFile with a small + // retry delay. + let fullContent: string; + try { + fullContent = readFileSync(fullOutputPath, "utf8"); + } catch { + // Temp file gone (race condition) — leave the result unchanged. + return undefined; + } + + const truncation = truncateTail(fullContent, { maxLines: KOAN_MAX_LINES, maxBytes: KOAN_MAX_BYTES }); + let outputText = truncation.content || "(no output)"; + + if (truncation.truncated) { + // Mirror the bash tool's notice format exactly. The LLM's tool description + // says output is truncated to specific limits and references the full output + // path — a divergent format would confuse the LLM about how to recover the rest. + const startLine = truncation.totalLines - truncation.outputLines + 1; + const endLine = truncation.totalLines; + + if (truncation.lastLinePartial) { + const lines = fullContent.split("\n"); + const lastLine = lines[lines.length - 1] ?? ""; + const lastLineSize = Buffer.byteLength(lastLine, "utf8"); + outputText += `\n\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${formatSize(lastLineSize)}). Full output: ${fullOutputPath}]`; + } else if (truncation.truncatedBy === "lines") { + outputText += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${fullOutputPath}]`; + } else { + outputText += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(KOAN_MAX_BYTES)} limit). Full output: ${fullOutputPath}]`; + } + } + + return { content: [{ type: "text" as const, text: outputText }] }; + }); +} From 8603e6cbbba65ae8aaf84176a3157f90932e6739 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:48:11 +0700 Subject: [PATCH 051/412] refactor audit events to paired tool_call/tool_result model --- src/planner/lib/audit.ts | 574 +++++++++++++++++++++++++++++---------- 1 file changed, 434 insertions(+), 140 deletions(-) diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index 992ecab..86f9ebb 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -1,8 +1,10 @@ // Audit trail for subagent sessions: event-sourced append log (events.jsonl) // with an eagerly materialized projection (state.json) for parent polling. // fold() is pure so the projection can be replayed from the raw log for testing. -// Graduated tool capture: full detail for koan_* tools, paths for file ops, -// binary name for bash, name-only for everything else. +// +// Tool invocations are captured as two events: tool_call (request) and +// tool_result (response), correlated by toolCallId. The flat event stream +// can be reduced into ToolInvocation[] via correlateTools() for paired access. import { promises as fs } from "node:fs"; import * as path from "node:path"; @@ -14,38 +16,31 @@ export interface EventBase { seq: number; } -export interface ToolFileEvent extends EventBase { - kind: "tool_file"; - tool: "read" | "edit" | "write"; - path: string; - lines?: number; - chars?: number; - error: boolean; -} +// -- Tool events -- +// Every tool invocation produces a (tool_call, tool_result) pair in the log. +// tool_call fires when the LLM requests the tool; tool_result fires when +// the tool returns. Both carry toolCallId for correlation. -export interface ToolBashEvent extends EventBase { - kind: "tool_bash"; - bin: string; - lines?: number; - chars?: number; - error: boolean; -} - -export interface ToolKoanEvent extends EventBase { - kind: "tool_koan"; +export interface ToolCallEvent extends EventBase { + kind: "tool_call"; + toolCallId: string; tool: string; input: Record; - response: string[]; - error: boolean; } -export interface ToolGenericEvent extends EventBase { - kind: "tool_generic"; +export interface ToolResultEvent extends EventBase { + kind: "tool_result"; + toolCallId: string; tool: string; error: boolean; + // Summarized output metrics (not the full content — too large for the log). + lines?: number; + chars?: number; + // Koan tool response text preserved for projection (completionSummary, etc.). + koanResponse?: string[]; } -export type ToolEvent = ToolFileEvent | ToolBashEvent | ToolKoanEvent | ToolGenericEvent; +// -- Lifecycle events -- export interface PhaseStartEvent extends EventBase { kind: "phase_start"; @@ -72,15 +67,31 @@ export interface HeartbeatEvent extends EventBase { kind: "heartbeat"; } +export interface UsageEvent extends EventBase { + kind: "usage"; + input: number; + output: number; + cacheRead: number; + cacheWrite: number; +} + export type AuditEvent = - | ToolFileEvent - | ToolBashEvent - | ToolKoanEvent - | ToolGenericEvent + | ToolCallEvent + | ToolResultEvent | PhaseStartEvent | StepTransitionEvent | PhaseEndEvent - | HeartbeatEvent; + | HeartbeatEvent + | UsageEvent; + +// Distributive Omit — distributes over union members so object literals +// with fields specific to one member are accepted. +type DistributiveOmit = T extends unknown ? Omit : never; +export type AuditEventPartial = DistributiveOmit; + +// -- Projection -- +// Eagerly materialized state summary. Written atomically to state.json +// after every event so the parent (web server) can poll cheaply. export interface Projection { role: string; @@ -91,13 +102,84 @@ export interface Projection { totalSteps: number; stepName: string; lastAction: string | null; + // toolCallId of the currently in-flight tool, null when idle. + // Lets the UI distinguish "doing X" from "done with X". + currentToolCallId: string | null; updatedAt: string; eventCount: number; error: string | null; + completionSummary: string | null; + tokensSent: number; + tokensReceived: number; +} + +// -- Correlated tool invocations -- +// Reduced view of paired (tool_call, tool_result) events. + +export interface ToolInvocation { + toolCallId: string; + tool: string; + input: Record; + callTs: string; + resultTs: string | null; + error: boolean | null; + inFlight: boolean; + durationMs: number | null; + // Output metrics from the result event. + lines?: number; + chars?: number; + koanResponse?: string[]; +} + +// Reduces a flat event stream into paired tool invocations. +// In-flight tools (call without result) have inFlight=true, resultTs=null. +export function correlateTools(events: AuditEvent[]): ToolInvocation[] { + const byId = new Map(); + const ordered: ToolInvocation[] = []; + + for (const e of events) { + if (e.kind === "tool_call") { + const inv: ToolInvocation = { + toolCallId: e.toolCallId, + tool: e.tool, + input: e.input, + callTs: e.ts, + resultTs: null, + error: null, + inFlight: true, + durationMs: null, + }; + byId.set(e.toolCallId, inv); + ordered.push(inv); + } else if (e.kind === "tool_result") { + const inv = byId.get(e.toolCallId); + if (inv) { + inv.resultTs = e.ts; + inv.error = e.error; + inv.inFlight = false; + inv.durationMs = new Date(e.ts).getTime() - new Date(inv.callTs).getTime(); + inv.lines = e.lines; + inv.chars = e.chars; + inv.koanResponse = e.koanResponse; + } + // Orphan result (no matching call) — can happen if the subagent + // started before tool_call hooking was added. Silently skip. + } + } + + return ordered; +} + +// -- Pi event shapes (subset we consume) -- + +interface PiToolCallEvent { + toolCallId: string; + toolName: string; + input: Record; } -// Pi's ToolResultEvent shape (subset we need). interface PiToolResultEvent { + toolCallId: string; toolName: string; input: Record; content: Array<{ type: string; text?: string }>; @@ -115,26 +197,107 @@ function now(): string { return new Date().toISOString(); } -// Derives a concise last-action string from a tool event for display. -export function summarize(e: ToolEvent): string { - switch (e.kind) { - case "tool_file": { - const suffix = e.lines != null ? ` (${e.lines}L, ${e.chars}c)` : ""; - return `${e.tool} ${e.path}${suffix}`; - } - case "tool_bash": { - const suffix = e.lines != null ? ` (${e.lines}L, ${e.chars}c)` : ""; - return `bash ${e.bin}${suffix}`; - } - case "tool_koan": - return e.tool; - case "tool_generic": - return e.tool; +// -- Extractors -- +// Transform pi's raw hook events into our audit event types. +// ts/seq are placeholders — EventLog.append() overwrites them. + +export function extractToolCall(piEvent: PiToolCallEvent): ToolCallEvent { + return { + kind: "tool_call", + toolCallId: piEvent.toolCallId, + tool: piEvent.toolName, + input: piEvent.input, + ts: now(), + seq: 0, + }; +} + +export function extractToolResult(piEvent: PiToolResultEvent): ToolResultEvent { + const { toolCallId, toolName, input, content, isError } = piEvent; + + const ev: ToolResultEvent = { + kind: "tool_result", + toolCallId, + tool: toolName, + error: isError, + ts: now(), + seq: 0, + }; + + // Capture output size for file and bash tools. + if (FILE_TOOLS.has(toolName) && !isError) { + const text = content.find((c) => c.type === "text")?.text ?? ""; + ev.lines = text.split("\n").length; + ev.chars = text.length; + } else if (toolName === "bash") { + const text = content.find((c) => c.type === "text")?.text ?? ""; + ev.lines = text.split("\n").length; + ev.chars = text.length; + } + + // Preserve koan tool response text for projection use (completionSummary). + if (toolName.startsWith("koan_")) { + ev.koanResponse = content + .filter((c) => c.type === "text" && c.text !== undefined) + .map((c) => c.text as string); + } + + return ev; +} + +// -- Summarize -- +// Human-readable one-liner from a tool invocation. +// Uses input (from call) + output metrics (from result) when available. + +export function summarizeInvocation(inv: ToolInvocation): string { + const { tool, input } = inv; + + // Tool name / key input identifier. + let label: string; + if (FILE_TOOLS.has(tool)) { + label = `${tool} ${(input["path"] as string | undefined) ?? ""}`; + } else if (tool === "bash") { + const cmd = (input["command"] as string | undefined) ?? ""; + label = `bash ${cmd.trim().split(/\s+/)[0] ?? ""}`; + } else { + label = tool; + } + + // Append output metrics if result has landed. + if (!inv.inFlight && (inv.lines != null || inv.chars != null)) { + const lines = inv.lines ?? 0; + const chars = inv.chars ?? 0; + label += ` · ${lines}L/${formatChars(chars)}`; + } + + return label; +} + +// Summarize from a ToolCallEvent alone (in-flight, no result yet). +function summarizeCall(e: ToolCallEvent): string { + if (FILE_TOOLS.has(e.tool)) { + return `${e.tool} ${(e.input["path"] as string | undefined) ?? ""}`; + } + if (e.tool === "bash") { + const cmd = (e.input["command"] as string | undefined) ?? ""; + return `bash ${cmd.trim().split(/\s+/)[0] ?? ""}`; } + return e.tool; } +// Summarize from a ToolResultEvent alone (used in fold when call was missed). +function summarizeResult(e: ToolResultEvent): string { + let label = e.tool; + if (e.lines != null || e.chars != null) { + label += ` · ${e.lines ?? 0}L/${formatChars(e.chars ?? 0)}`; + } + return label; +} + +// -- Fold -- // Pure projection update — one case per discriminated kind. // All branches update updatedAt and increment eventCount. + export function fold(s: Projection, e: AuditEvent): Projection { const base = { ...s, updatedAt: e.ts, eventCount: s.eventCount + 1 }; @@ -150,7 +313,9 @@ export function fold(s: Projection, e: AuditEvent): Projection { totalSteps: e.totalSteps, stepName: "", lastAction: null, + currentToolCallId: null, error: null, + completionSummary: null, }; case "step_transition": @@ -166,59 +331,42 @@ export function fold(s: Projection, e: AuditEvent): Projection { ...base, status: e.outcome, error: e.detail ?? null, + currentToolCallId: null, }; - case "tool_file": - case "tool_bash": - case "tool_koan": - case "tool_generic": - return { ...base, lastAction: summarize(e) }; + case "tool_call": { + const updated: Projection = { + ...base, + lastAction: summarizeCall(e), + currentToolCallId: e.toolCallId, + }; + // Extract completionSummary from koan_complete_step's thoughts param. + // The thoughts parameter is chain-of-thought, not task output (per + // AGENTS.md invariant), but we capture a prefix for the projection + // so the web UI can show scout summaries. + if (e.tool === "koan_complete_step" && typeof e.input?.thoughts === "string") { + updated.completionSummary = e.input.thoughts.slice(0, 500) || null; + } + return updated; + } + + case "tool_result": + return { + ...base, + lastAction: summarizeResult(e), + currentToolCallId: null, + }; case "heartbeat": return base; - } -} - -// Transforms pi's ToolResultEvent into a graduated AuditEvent. -export function extractToolEvent(piEvent: PiToolResultEvent): ToolEvent { - const { toolName, input, content, isError } = piEvent; - const ts = now(); - // ts and seq are assigned by EventLog.append(); values here are - // placeholders overridden on write. - const seq = 0; - - if (FILE_TOOLS.has(toolName)) { - const ev: ToolFileEvent = { - kind: "tool_file", - tool: toolName as "read" | "edit" | "write", - path: (input["path"] as string | undefined) ?? "", - error: isError, - ts, - seq, - }; - if (toolName === "read" && !isError) { - const text = content.find((c) => c.type === "text")?.text ?? ""; - ev.lines = text.split("\n").length; - ev.chars = text.length; - } - return ev; - } - if (toolName === "bash") { - const cmd = (input["command"] as string | undefined) ?? ""; - const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; - const text = content.find((c) => c.type === "text")?.text ?? ""; - return { kind: "tool_bash", bin, lines: text.split("\n").length, chars: text.length, error: isError, ts, seq }; - } - - if (toolName.startsWith("koan_")) { - const response = content - .filter((c) => c.type === "text" && c.text !== undefined) - .map((c) => c.text as string); - return { kind: "tool_koan", tool: toolName, input, response, error: isError, ts, seq }; + case "usage": + return { + ...base, + tokensSent: s.tokensSent + e.input, + tokensReceived: s.tokensReceived + e.output, + }; } - - return { kind: "tool_generic", tool: toolName, error: isError, ts, seq }; } // -- EventLog -- @@ -249,9 +397,13 @@ export class EventLog { totalSteps: 0, stepName: "", lastAction: null, + currentToolCallId: null, updatedAt: now(), eventCount: 0, error: null, + completionSummary: null, + tokensSent: 0, + tokensReceived: 0, }; } @@ -266,13 +418,13 @@ export class EventLog { // Assigns ts + seq, appends JSON line, folds, writes state atomically. // Serialized: concurrent callers queue behind the in-flight write. - async append(partial: Omit): Promise { + async append(partial: AuditEventPartial): Promise { const task = () => this.doAppend(partial); this.pending = this.pending.then(task, task); return this.pending; } - private async doAppend(partial: Omit): Promise { + private async doAppend(partial: AuditEventPartial): Promise { if (!this.fd) { throw new Error("EventLog.append called before open()"); } @@ -336,7 +488,7 @@ export class EventLog { // -- Exports -- // Reads state.json as a Projection; returns null if missing or malformed. -// Used by driver polling loop. +// Used by web server polling loop. export async function readProjection(dir: string): Promise { try { const raw = await fs.readFile(path.join(dir, "state.json"), "utf8"); @@ -346,13 +498,15 @@ export async function readProjection(dir: string): Promise { } } -// Structured log line for the widget log card. -// `tool` is the left-column scan anchor, `summary` is the right-column detail. -// High-value rows may wrap to two visual lines in the widget. +// -- Log formatting -- +// Structured log lines for the web UI activity feed. + export interface LogLine { tool: string; summary: string; highValue: boolean; + inFlight: boolean; + details?: string[]; } interface ToolShape { @@ -366,7 +520,6 @@ interface ToolShape { const PREVIEW_CHARS = 40; const KEY_PRIORITY = ["id", "story_id", "milestone", "decision_ref", "intent_ref", "file", "path", "phase"]; -// Tool shapes for koan_* tools. No koan_escalate (eliminated in §11.3.1). const KOAN_SHAPES: Record = { koan_select_story: { keys: ["story_id"], highValue: true }, koan_complete_story: { keys: ["story_id"], highValue: true }, @@ -376,8 +529,8 @@ const KOAN_SHAPES: Record = { koan_request_scouts: { keys: ["scouts"], arrays: ["scouts"], highValue: true }, }; -// Reads the tail of events.jsonl and returns structured log entries. -// Filters out heartbeats (noisy). Used by driver to feed the widget log card. +// Reads events.jsonl, correlates tool pairs, and returns structured log entries. +// Filters out heartbeats, usage, and koan_complete_step (noisy). export async function readRecentLogs(dir: string, count = 8): Promise { try { const raw = await fs.readFile(path.join(dir, "events.jsonl"), "utf8"); @@ -385,14 +538,88 @@ export async function readRecentLogs(dir: string, count = 8): Promise .trimEnd() .split("\n") .filter(Boolean) - .map((line) => JSON.parse(line) as AuditEvent) - .filter((e) => e.kind !== "heartbeat" && !(e.kind === "tool_koan" && e.tool === "koan_complete_step")); - return events.slice(-count).map(formatLogLine); + .map((line) => JSON.parse(line) as AuditEvent); + + return buildChronologicalLog(events, count); } catch { return []; } } +// Builds a chronological log by walking events in order and emitting +// one LogLine per tool invocation (at result time, or at call time if +// still in-flight) plus lifecycle events. +function buildChronologicalLog(events: AuditEvent[], count: number): LogLine[] { + const pendingCalls = new Map }>(); + const lines: LogLine[] = []; + + for (const e of events) { + if (e.kind === "heartbeat" || e.kind === "usage") continue; + + if (e.kind === "tool_call") { + // Stash tool name + input for when the result arrives (or for + // in-flight rendering if no result appears by end of loop). + pendingCalls.set(e.toolCallId, { tool: e.tool, input: e.input }); + continue; + } + + if (e.kind === "tool_result") { + if (e.tool === "koan_complete_step") continue; + const call = pendingCalls.get(e.toolCallId); + lines.push(formatPairedResult(e, call?.input ?? {})); + pendingCalls.delete(e.toolCallId); + continue; + } + + // Lifecycle event. + lines.push(formatLifecycleEvent(e)); + } + + // Emit remaining calls without results as in-flight lines. + // The ActivityFeed renders the last in-flight line with animated dots. + for (const [, call] of pendingCalls) { + if (call.tool === "koan_complete_step") continue; + lines.push(formatInFlightCall(call.tool, call.input)); + } + + return lines.slice(-count); +} + +// Format an in-flight tool_call (no result yet). Same structure as +// formatPairedResult but with inFlight: true and no output metrics. +function formatInFlightCall(tool: string, input: Record): LogLine { + if (FILE_TOOLS.has(tool)) { + return { + tool, + summary: (input["path"] as string | undefined) ?? "", + highValue: tool === "read", + inFlight: true, + }; + } + + if (tool === "bash") { + const cmd = (input["command"] as string | undefined) ?? ""; + const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; + return { tool: "bash", summary: bin, highValue: false, inFlight: true }; + } + + if (tool.startsWith("koan_")) { + const shape = KOAN_SHAPES[tool]; + if (shape) { + const inv: ToolInvocation = { + toolCallId: "", tool, input, + callTs: "", resultTs: null, + error: null, inFlight: true, durationMs: null, + }; + return formatKoanInvocation(inv); + } + } + + return { tool, summary: "", highValue: false, inFlight: true }; +} + +// -- Formatters -- + function formatChars(chars: number): string { if (chars < 1000) return `${chars}c`; const k = chars / 1000; @@ -464,75 +691,142 @@ function orderedShapeKeys(keys: string[]): string[] { return indexed.map((x) => x.key); } -function formatKnownKoan(e: ToolKoanEvent, shape: ToolShape): LogLine { +// Format a completed tool invocation from its correlated pair. +function formatToolInvocation(inv: ToolInvocation): LogLine { + if (inv.tool.startsWith("koan_")) { + return formatKoanInvocation(inv); + } + + if (FILE_TOOLS.has(inv.tool)) { + const p = (inv.input["path"] as string | undefined) ?? ""; + const suffix = inv.lines != null ? ` · ${inv.lines}L/${formatChars(inv.chars ?? 0)}` : ""; + return { + tool: inv.tool, + summary: `${p}${suffix}`, + highValue: inv.tool === "read", + inFlight: inv.inFlight, + }; + } + + if (inv.tool === "bash") { + const cmd = (inv.input["command"] as string | undefined) ?? ""; + const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; + const suffix = inv.lines != null ? ` · ${inv.lines}L/${formatChars(inv.chars ?? 0)}` : ""; + return { + tool: "bash", + summary: `${bin}${suffix}`, + highValue: false, + inFlight: inv.inFlight, + }; + } + + return { tool: inv.tool, summary: "", highValue: false, inFlight: inv.inFlight }; +} + +function formatKoanInvocation(inv: ToolInvocation): LogLine { + const shape = KOAN_SHAPES[inv.tool]; + if (!shape) { + return { tool: inv.tool, summary: "", highValue: false, inFlight: inv.inFlight }; + } + const arrayKeys = new Set(shape.arrays ?? []); const freeformKeys = new Set(shape.freeform ?? []); const chunks: string[] = []; for (const key of orderedShapeKeys(shape.keys)) { - if (!hasKey(e.input, key)) continue; - const value = e.input[key]; + if (!hasKey(inv.input, key)) continue; + const value = inv.input[key]; if (arrayKeys.has(key)) { chunks.push(`${key}:${arrayPreview(value)}`); continue; } - if (freeformKeys.has(key)) { chunks.push(`${key}:${freeformSize(value)}`); continue; } - chunks.push(`${key}=${inlineScalar(value)}`); } - if (shape.getter) { + if (shape.getter && inv.koanResponse) { if (chunks.length === 0) { chunks.push("scope=plan"); } - chunks.push(`resp:${responseSize(e.response)}`); + chunks.push(`resp:${responseSize(inv.koanResponse)}`); } - return { - tool: e.tool, + const line: LogLine = { + tool: inv.tool, summary: chunks.join(" · "), highValue: shape.highValue ?? chunks.length >= 3, + inFlight: inv.inFlight, }; + + // Expand koan_request_scouts with per-scout detail lines. + if (inv.tool === "koan_request_scouts" && Array.isArray(inv.input["scouts"])) { + line.details = (inv.input["scouts"] as Array>).map( + (s) => `${s["id"] ?? "?"} (${s["role"] ?? "agent"})`, + ); + } + + return line; } -function formatKoanLogLine(e: ToolKoanEvent): LogLine { - const shape = KOAN_SHAPES[e.tool]; - if (!shape) { - return { tool: e.tool, summary: "", highValue: false }; +// Format a tool_result event paired with its call's input. +function formatPairedResult(e: ToolResultEvent, input: Record): LogLine { + if (FILE_TOOLS.has(e.tool)) { + const p = (input["path"] as string | undefined) ?? ""; + const suffix = e.lines != null ? ` · ${e.lines}L/${formatChars(e.chars ?? 0)}` : ""; + return { + tool: e.tool, + summary: `${p}${suffix}`, + highValue: e.tool === "read", + inFlight: false, + }; } - return formatKnownKoan(e, shape); + + if (e.tool === "bash") { + const cmd = (input["command"] as string | undefined) ?? ""; + const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; + const suffix = e.lines != null ? ` · ${e.lines}L/${formatChars(e.chars ?? 0)}` : ""; + return { + tool: "bash", + summary: `${bin}${suffix}`, + highValue: false, + inFlight: false, + }; + } + + if (e.tool.startsWith("koan_")) { + const shape = KOAN_SHAPES[e.tool]; + if (shape) { + // Rebuild invocation-like object for the koan formatter. + const inv: ToolInvocation = { + toolCallId: e.toolCallId, + tool: e.tool, + input, + callTs: e.ts, + resultTs: e.ts, + error: e.error, + inFlight: false, + durationMs: null, + koanResponse: e.koanResponse, + }; + return formatKoanInvocation(inv); + } + return { tool: e.tool, summary: "", highValue: false, inFlight: false }; + } + + return { tool: e.tool, summary: "", highValue: false, inFlight: false }; } -function formatLogLine(e: AuditEvent): LogLine { +function formatLifecycleEvent(e: PhaseStartEvent | StepTransitionEvent | PhaseEndEvent): LogLine { switch (e.kind) { case "phase_start": - return { tool: "phase", summary: `${e.phase} (${e.totalSteps} steps)`, highValue: false }; + return { tool: "phase", summary: `${e.phase} (${e.totalSteps} steps)`, highValue: false, inFlight: false }; case "step_transition": - return { tool: `step ${e.step}/${e.totalSteps}`, summary: e.name, highValue: false }; + return { tool: `step ${e.step}/${e.totalSteps}`, summary: e.name, highValue: false, inFlight: false }; case "phase_end": - return { tool: "phase", summary: e.detail ? `${e.outcome} · ${e.detail}` : e.outcome, highValue: false }; - case "tool_file": - return { - tool: e.tool, - summary: e.lines != null ? `${e.path} · ${e.lines}L/${formatChars(e.chars ?? 0)}` : e.path, - highValue: e.tool === "read", - }; - case "tool_bash": - return { - tool: "bash", - summary: e.lines != null ? `${e.bin} · ${e.lines}L/${formatChars(e.chars ?? 0)}` : e.bin, - highValue: false, - }; - case "tool_koan": - return formatKoanLogLine(e); - case "tool_generic": - return { tool: e.tool, summary: "", highValue: false }; - case "heartbeat": - return { tool: "heartbeat", summary: "", highValue: false }; + return { tool: "phase", summary: e.detail ? `${e.outcome} · ${e.detail}` : e.outcome, highValue: false, inFlight: false }; } } From 0f68190e1a29b95a6d6c6228c3d7d5f6d5448459 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:48:20 +0700 Subject: [PATCH 052/412] implement step 0 boot state and reinforce completion directive --- src/planner/lib/step.ts | 13 +++- src/planner/phases/base-phase.ts | 77 +++++++++++++--------- src/planner/phases/decomposer/prompts.ts | 4 +- src/planner/phases/executor/prompts.ts | 4 +- src/planner/phases/intake/prompts.ts | 4 +- src/planner/phases/orchestrator/prompts.ts | 4 +- src/planner/phases/planner/prompts.ts | 4 +- src/planner/tools/workflow.ts | 28 ++++++-- 8 files changed, 84 insertions(+), 54 deletions(-) diff --git a/src/planner/lib/step.ts b/src/planner/lib/step.ts index 9771f6f..a6f3f5e 100644 --- a/src/planner/lib/step.ts +++ b/src/planner/lib/step.ts @@ -1,5 +1,11 @@ // Step prompt assembly for koan phase workflows. // +// formatStep() wraps step guidance with a header and a mandatory invoke-after +// directive. The directive at the END of every step is as important as the +// boot prompt at the beginning: primacy (first message) establishes the +// koan_complete_step habit; recency (last thing in each step) reinforces it. +// Together they make the calling pattern robust across model capability levels. +// // The `thoughts` parameter on koan_complete_step captures the model's work output // (analysis, review, findings) as a tool parameter rather than text output. This // ensures models that can't mix text + tool_call in one response still advance @@ -8,11 +14,14 @@ export interface StepGuidance { title: string; instructions: string[]; - // Custom invoke-after directive. When omitted, formatStep appends the default - // koan_complete_step directive. Terminal steps may override this. + // Override the default "WHEN DONE: Call koan_complete_step..." directive. + // Use for terminal steps that must call a domain tool (e.g. koan_select_story) + // before koan_complete_step, or for steps where the completion signal differs. invokeAfter?: string; } +// Appended to every step that doesn't override invokeAfter. +// Positioned last for recency — LLMs weight end-of-context instructions heavily. const DEFAULT_INVOKE = [ "WHEN DONE: Call koan_complete_step with your findings in the `thoughts` parameter.", "Do NOT call this tool until the work described in this step is finished.", diff --git a/src/planner/phases/base-phase.ts b/src/planner/phases/base-phase.ts index 775b835..62bf1a7 100644 --- a/src/planner/phases/base-phase.ts +++ b/src/planner/phases/base-phase.ts @@ -1,11 +1,21 @@ // BasePhase: shared lifecycle for all six koan subagent roles. // Subclasses define only their step structure and system prompt. -// Eliminates ~40 lines of duplicated skeleton per phase. +// +// Step-first workflow invariant (see AGENTS.md): +// Every subagent launches with a minimal boot prompt that contains only +// "call koan_complete_step". This forces the LLM's very first action to be +// a tool call rather than text output — critical because pi -p processes exit +// the moment the LLM finishes a turn without a tool call, with no recovery. +// +// Step 0 is the silent boot state. The first koan_complete_step call +// transitions 0→1 and returns step 1 guidance (just-in-time delivery). +// Subsequent calls advance through steps until the phase completes. // // Lifecycle: // constructor → registerHandlers() (hooks event listeners) -// begin() → activates phase, sets onCompleteStep in ctx, emits phase_start -// handleStepComplete() → advances step counter, returns next prompt or null +// begin() → activates phase at step 0, arms onCompleteStep, emits phase_start +// handleStepComplete(0) → returns step 1 guidance, emits step_transition(1) +// handleStepComplete(N) → returns step N+1 guidance, or null when done import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; @@ -25,9 +35,8 @@ export abstract class BasePhase { protected abstract getStepName(step: number): string; protected abstract getStepGuidance(step: number): StepGuidance; - private step = 1; + private step = 0; private active = false; - private step1Prompt: string | null = null; protected readonly log: Logger; @@ -44,29 +53,17 @@ export abstract class BasePhase { // -- Event handler registration -- private registerHandlers(): void { - // before_agent_start: inject system prompt when this phase is active. + // Inject the system prompt when this phase is active. The system prompt + // establishes role identity but deliberately omits task details — those + // arrive via step 1 guidance so the first message stays minimal. this.pi.on("before_agent_start", () => { if (!this.active) return undefined; return { systemPrompt: this.getSystemPrompt() }; }); - // context: append step 1 guidance to the spawn prompt (§9.8 append pattern). - // Preserves context embedded by the spawn function (scout question, retry - // context, etc.) while adding structured step instructions after a separator. - this.pi.on("context", (event) => { - if (!this.active || this.step !== 1 || !this.step1Prompt) return undefined; - const messages = event.messages.map((m) => { - if (m.role !== "user") return m; - const existing = typeof m.content === "string" ? m.content.trim() : ""; - const combined = existing.length > 0 - ? `${existing}\n\n---\n\n${this.step1Prompt!}` - : this.step1Prompt!; - return { ...m, content: combined }; - }); - return { messages }; - }); - - // tool_call: default-deny permission check for every tool call. + // Default-deny permission fence: every tool call is checked against the + // role's allowed set. Prevents roles from using tools outside their scope + // even though all tools are registered unconditionally at init. this.pi.on("tool_call", (event) => { if (!this.active) return undefined; const perm = checkPermission( @@ -80,33 +77,50 @@ export abstract class BasePhase { } return undefined; }); + + // NOTE: There is deliberately NO `context` event handler here. + // A previous design injected step 1 guidance into the first user message, + // but that front-loaded complex instructions before the LLM had established + // the koan_complete_step calling pattern — causing weaker models to produce + // text output and exit without entering the workflow at all. + // Step guidance is now delivered exclusively through koan_complete_step return values. } // -- Public lifecycle -- async begin(): Promise { - this.step1Prompt = formatStep(this.getStepGuidance(1)); this.active = true; - this.step = 1; + this.step = 0; // Boot state: waiting for the first koan_complete_step call. if (this.ctx.onCompleteStep !== null) { throw new Error(`ctx.onCompleteStep is already occupied — cannot begin ${this.role} phase`); } this.ctx.onCompleteStep = (thoughts: string) => this.handleStepComplete(thoughts); - this.log("Starting phase", { role: this.role, step: 1, totalSteps: this.totalSteps }); + this.log("Starting phase", { role: this.role, step: 0, totalSteps: this.totalSteps }); await this.eventLog?.emitPhaseStart(this.totalSteps); - await this.eventLog?.emitStepTransition(1, this.getStepName(1), this.totalSteps); + // step_transition is NOT emitted here — it fires when step 1 guidance is first + // returned, so the event log reflects when the LLM actually begins work. } // -- Private step progression -- private async handleStepComplete(thoughts: string): Promise { - void thoughts; // captured in event log via tool_result; used by subclass prompts if needed - const prev = this.step; + void thoughts; // captured in event log via tool_result; subclass prompts may reference it + + if (this.step === 0) { + // Boot transition: the LLM called koan_complete_step as instructed by the + // boot prompt. Reward it with step 1 guidance. This is the critical moment + // that establishes the call→receive→work→call pattern for the session. + this.step = 1; + const prompt = formatStep(this.getStepGuidance(1)); + await this.eventLog?.emitStepTransition(1, this.getStepName(1), this.totalSteps); + this.log("Boot transition", { role: this.role, to: 1 }); + return prompt; + } - if (prev === this.totalSteps) { - // Phase complete. + if (this.step === this.totalSteps) { + // Phase complete — return null signals koan_complete_step to reply "Phase complete." this.active = false; this.ctx.onCompleteStep = null; await this.eventLog?.emitPhaseEnd("completed"); @@ -115,6 +129,7 @@ export abstract class BasePhase { } // Advance to next step. + const prev = this.step; this.step = prev + 1; const prompt = formatStep(this.getStepGuidance(this.step)); await this.eventLog?.emitStepTransition(this.step, this.getStepName(this.step), this.totalSteps); diff --git a/src/planner/phases/decomposer/prompts.ts b/src/planner/phases/decomposer/prompts.ts index 7f18450..f54b48d 100644 --- a/src/planner/phases/decomposer/prompts.ts +++ b/src/planner/phases/decomposer/prompts.ts @@ -54,9 +54,7 @@ You write the following files, all inside the epic directory: - All read tools (read, bash, grep, glob, find, ls) — for reading intake output and scout reports. - \`koan_request_scouts\` — to request additional codebase exploration if needed. - \`write\` / \`edit\` — for writing output files inside the epic directory. -- \`koan_complete_step\` — to signal step completion. - -You work in two steps. First you read and analyze. Then you write the decomposition.`; +- \`koan_complete_step\` — to signal step completion.`; } export function decomposerStepGuidance(step: number): StepGuidance { diff --git a/src/planner/phases/executor/prompts.ts b/src/planner/phases/executor/prompts.ts index b27bf14..7b4636b 100644 --- a/src/planner/phases/executor/prompts.ts +++ b/src/planner/phases/executor/prompts.ts @@ -51,9 +51,7 @@ Improvised solutions that seem reasonable in isolation frequently break other pa ## On retries -If retryContext is present, this is your second (or later) attempt at this story. The failure summary tells you what went wrong. Read it before you read the plan, and keep the failure context in mind as you implement. Do not repeat the mistake from the previous attempt. - -You work in steps. Each step has specific instructions. Follow them precisely.`; +If retryContext is present, this is your second (or later) attempt at this story. The failure summary tells you what went wrong. Read it before you read the plan, and keep the failure context in mind as you implement. Do not repeat the mistake from the previous attempt.`; } export function executorStepGuidance(step: number, storyId: string, retryContext?: string): StepGuidance { diff --git a/src/planner/phases/intake/prompts.ts b/src/planner/phases/intake/prompts.ts index 80161f4..0e13445 100644 --- a/src/planner/phases/intake/prompts.ts +++ b/src/planner/phases/intake/prompts.ts @@ -43,9 +43,7 @@ You write two files, both inside the epic directory: - \`koan_request_scouts\` — to request parallel codebase exploration. - \`koan_ask_question\` — to ask the user clarifying questions via IPC. - \`write\` / \`edit\` — for writing output files inside the epic directory only. -- \`koan_complete_step\` — to signal step completion with your findings. - -You work in three steps. Each step has specific instructions. Follow them precisely.`; +- \`koan_complete_step\` — to signal step completion with your findings.`; } export function intakeStepGuidance(step: number, conversationPath?: string): StepGuidance { diff --git a/src/planner/phases/orchestrator/prompts.ts b/src/planner/phases/orchestrator/prompts.ts index 15c5db3..efafd41 100644 --- a/src/planner/phases/orchestrator/prompts.ts +++ b/src/planner/phases/orchestrator/prompts.ts @@ -78,9 +78,7 @@ When you make a decision that modifies artifacts without explicit human instruct - MUST NOT call more than one verdict tool per verdict step. - MUST run ALL verification checks in verify.md before issuing a verdict. - MUST include a concrete, actionable failure summary when calling koan_retry_story. -- When uncertain about a verdict, prefer koan_retry_story with a detailed failure_summary. Ask the user only when the failure reveals a genuine requirements ambiguity. - -You work in steps. Each step has specific instructions. Follow them precisely.`; +- When uncertain about a verdict, prefer koan_retry_story with a detailed failure_summary. Ask the user only when the failure reveals a genuine requirements ambiguity.`; } export function orchestratorPreStepGuidance(step: number): StepGuidance { diff --git a/src/planner/phases/planner/prompts.ts b/src/planner/phases/planner/prompts.ts index b7d77f9..1b6a9e0 100644 --- a/src/planner/phases/planner/prompts.ts +++ b/src/planner/phases/planner/prompts.ts @@ -56,9 +56,7 @@ Each check entry must include: - MUST NOT plan beyond the current story's scope. If a step would touch something not in the story, flag it as out-of-scope. - MUST NOT make architectural decisions. If a decision is needed that is outside the planner's scope, note it in plan.md as: \`BLOCKER: [description]. The orchestrator will ask the user via koan_ask_question during verification.\` - MUST include enough detail that the executor can implement the plan in one pass without guessing. -- MUST scope plan/context.md to only what the executor needs — context files that include too much code obscure the relevant parts. - -You work in steps. Each step has specific instructions. Follow them precisely.`; +- MUST scope plan/context.md to only what the executor needs — context files that include too much code obscure the relevant parts.`; } export function plannerStepGuidance(step: number, storyId: string): StepGuidance { diff --git a/src/planner/tools/workflow.ts b/src/planner/tools/workflow.ts index 71eb74e..cff27d9 100644 --- a/src/planner/tools/workflow.ts +++ b/src/planner/tools/workflow.ts @@ -1,4 +1,14 @@ // Workflow tool registration: koan_complete_step. +// +// This is the single most critical tool in koan. Every subagent workflow depends +// on it being called — it is the mechanism that keeps a pi -p process alive across +// multiple steps. Without it, the LLM would do one turn of work and exit, because +// pi -p processes terminate as soon as the LLM finishes a turn without a tool call. +// +// The workflow pattern: boot prompt → LLM calls koan_complete_step → receives step 1 +// instructions → does work → calls koan_complete_step → receives step 2 (or "Phase +// complete.") → repeat. The tool name itself is a call to action: "complete the step." +// // Tools register once at init; execute callbacks read from the mutable // RuntimeContext at call time, decoupling static registration from phase routing. @@ -24,21 +34,27 @@ export function registerWorkflowTools( ctx: RuntimeContext, ): void { // -- koan_complete_step -- - // The `thoughts` parameter captures the model's work output (analysis, - // review, findings) as a tool parameter instead of as text output. - // This ensures models that cannot mix text + tool_call in one response - // (e.g. GPT-5-codex) still advance the workflow reliably. + // INVARIANT: `thoughts` is internal chain-of-thought reasoning only. + // It is NOT captured as task output and must NOT be treated as such. + // Its purpose: models that cannot mix text output + tool_call in one + // response (e.g. GPT-5-codex) still express reasoning via this param. + // Task output is written to files in the subagent directory: + // - scouts: {subagentDir}/findings.md + // - intake: {subagentDir}/context.md + // - others: as defined by step instructions + // The driver/parent reads those files after the subagent exits. pi.registerTool({ name: "koan_complete_step", label: "Complete current workflow step", description: [ "Signal completion of the current workflow step.", - "Put your analysis, findings, or work output in the `thoughts` parameter.", + "The `thoughts` parameter is for internal chain-of-thought reasoning only — it is NOT captured as task output.", + "Task output must be written to files in your subagent directory (e.g., findings.md for scouts).", "DO NOT call this tool until the step instructions explicitly tell you to.", ].join(" "), parameters: Type.Object({ thoughts: Type.Optional(Type.String({ - description: "Your analysis, findings, or work output for this step.", + description: "Internal chain-of-thought reasoning only. NOT task output. Write task output to files in your subagent directory.", })), }), async execute(_toolCallId, params) { From 668de5ce19a1e0e18ca2afe1df3e02e7d85c1e05 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:48:28 +0700 Subject: [PATCH 053/412] expand scout phase to 4-step verified investigation workflow --- src/planner/phases/scout/phase.ts | 21 +++- src/planner/phases/scout/prompts.ts | 165 +++++++++++++++++++++------- 2 files changed, 139 insertions(+), 47 deletions(-) diff --git a/src/planner/phases/scout/phase.ts b/src/planner/phases/scout/phase.ts index 6685505..ed193b5 100644 --- a/src/planner/phases/scout/phase.ts +++ b/src/planner/phases/scout/phase.ts @@ -1,5 +1,7 @@ // Scout phase: answers one narrow codebase question and writes findings. -// Single-step, cheap model, no user interaction. +// Four-step workflow (orient → investigate → verify → report), cheap model, no user interaction. +// Task context (question, outputFile, role) is received via CLI flags and +// delivered to the LLM through step guidance (returned by koan_complete_step). import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; @@ -12,17 +14,24 @@ import type { StepGuidance } from "../../lib/step.js"; export class ScoutPhase extends BasePhase { protected readonly role = "scout"; - protected readonly totalSteps = 1; + protected readonly totalSteps = 4; + + private readonly question: string; + private readonly outputFile: string; + private readonly investigatorRole: string; constructor( pi: ExtensionAPI, - config: { epicDir: string }, + config: { epicDir: string; question: string; outputFile: string; investigatorRole: string }, ctx: RuntimeContext, log?: Logger, eventLog?: EventLog, ) { super(pi, ctx, log ?? createLogger("ScoutPhase"), eventLog); - void config; // epicDir used via ctx.epicDir for permission scoping + void config.epicDir; // used via ctx.epicDir for permission scoping + this.question = config.question; + this.outputFile = config.outputFile; + this.investigatorRole = config.investigatorRole; } protected getSystemPrompt(): string { @@ -33,7 +42,7 @@ export class ScoutPhase extends BasePhase { return SCOUT_STEP_NAMES[step] ?? `Step ${step}`; } - protected getStepGuidance(_step: number): StepGuidance { - return scoutStepGuidance(); + protected getStepGuidance(step: number): StepGuidance { + return scoutStepGuidance(step, this.question, this.outputFile, this.investigatorRole); } } diff --git a/src/planner/phases/scout/prompts.ts b/src/planner/phases/scout/prompts.ts index 1512e83..e947ceb 100644 --- a/src/planner/phases/scout/prompts.ts +++ b/src/planner/phases/scout/prompts.ts @@ -1,15 +1,30 @@ -// Scout phase prompts — single step: explore & report. -// Role-specific context (the question and output file) is embedded in the -// spawn prompt by the spawn function. This provides only process guidance. +// Scout phase prompts — 4-step investigation workflow: +// Step 1: Orient (identify entry points, plan investigation) +// Step 2: Investigate (deep read, trace dependencies, gather evidence) +// Step 3: Verify & Analyze (re-read cited files, organize findings) +// Step 4: Report (write findings.md with verified facts) +// +// The system prompt establishes the investigator identity but contains no task +// details — a scout doesn't know its question until koan_complete_step returns +// step 1 guidance. This is intentional: including the question in the system +// prompt or spawn prompt would front-load instructions before the tool-call +// pattern is established, causing weaker models to answer inline and exit. +// +// The verification step (3) is the key addition over the original single-step +// design. Cheap models hallucinate file paths and API names. Re-reading every +// file before reporting catches confabulation before it reaches the intake-LLM. import type { StepGuidance } from "../../lib/step.js"; export const SCOUT_STEP_NAMES: Record = { - 1: "Explore & Report", + 1: "Orient", + 2: "Investigate", + 3: "Verify & Analyze", + 4: "Report", }; export function scoutSystemPrompt(): string { - return `You are a codebase investigator. You are assigned one narrow, specific question about a codebase. Your job is to read the relevant files, find the answer, and write your findings to a designated output file. + return `You are a codebase investigator. You are assigned one narrow, specific question about a codebase. Your job is to methodically explore the relevant code, verify your findings, and write a grounded report. ## Your role @@ -27,48 +42,116 @@ You find facts. You do NOT interpret, recommend, or opine. - SHOULD be thorough within the question scope: follow references, check related files. - SHOULD note explicitly when something is NOT present (e.g., "No tests found for this module"). -## Output format +## Output file -Write a markdown file with these sections: - -## Question -Restate the assigned question verbatim. - -## Findings -Factual observations that answer the question. Use sub-sections if the answer has multiple parts. -Cite file paths and line numbers for every claim. Include code snippets where relevant. - -## Files Examined -List every file you read during this investigation. - -## Gaps -Note anything you could not determine. If no gaps, write: (none) +You write a single markdown file with your findings. The file location and format are provided in your final step. ## Tools available - All read tools (read, bash, grep, glob, find, ls) — for reading the codebase. - \`write\` / \`edit\` — for writing the output file only. -- \`koan_complete_step\` — to signal completion. - -You work in a single step. Read the codebase, answer the question, write the output file.`; +- \`koan_complete_step\` — to signal completion.`; } -// Role-specific context (the question and output file) is embedded in the -// spawn prompt by the spawn function. This provides process guidance only. -export function scoutStepGuidance(): StepGuidance { - return { - title: SCOUT_STEP_NAMES[1], - instructions: [ - "Investigate the codebase to answer the assigned question. Write your findings to the output file.", - "", - "## Process", - "", - "1. Identify the files most likely to contain the answer. Start broad (grep, glob, ls),", - " then narrow down (read specific files).", - "2. Follow cross-references: if a file imports from another file, check that file too.", - "3. Be thorough within the question scope. Do not stop at the first partial answer.", - "4. Write your findings to the output file using the format described in your system prompt.", - "5. Call `koan_complete_step` with a one-sentence summary of your key finding.", - ], - }; +export function scoutStepGuidance( + step: number, + question: string, + outputFile: string, + investigatorRole: string, +): StepGuidance { + switch (step) { + case 1: + return { + title: SCOUT_STEP_NAMES[1], + instructions: [ + "Understand the question and identify where to look in the codebase.", + "", + "## Your Assignment", + "", + ...(question ? [`**Question:** ${question}`] : []), + ...(investigatorRole ? [`**Your investigator role:** ${investigatorRole}`] : []), + "", + "## Actions", + "", + "1. Parse the question: what exactly are you being asked to find?", + "2. Identify search terms, file patterns, and likely directory locations.", + "3. Use grep, glob, find, or ls to locate 3–8 candidate entry-point files.", + "4. Do NOT read file contents yet — just identify targets.", + "", + "Report your entry points and investigation plan in the `thoughts` parameter.", + ], + }; + + case 2: + return { + title: SCOUT_STEP_NAMES[2], + instructions: [ + "Read the entry-point files and trace through the code to answer the question.", + "", + "## Actions", + "", + "1. Read each entry-point file identified in the previous step.", + "2. Follow imports, cross-references, and call chains to related files.", + "3. For each relevant finding, note the file path, line numbers, and a verbatim code excerpt.", + "4. Be thorough: do not stop at the first partial answer. Check related files.", + "5. If a file turns out to be irrelevant, move on — do not force-fit it.", + "", + "Report your findings and the files you read in the `thoughts` parameter.", + ], + }; + + case 3: + return { + title: SCOUT_STEP_NAMES[3], + instructions: [ + "Verify every claim you plan to report and organize your findings.", + "", + "## Verification", + "", + "1. Re-read every file you plan to cite in your report.", + "2. Confirm that file paths are correct and the code excerpts match the actual content.", + "3. If you find a discrepancy, correct it. If a file does not exist, remove the reference.", + "", + "## Analysis", + "", + "4. Organize your verified findings into a clear answer to the original question.", + "5. Identify any gaps — things you could not determine or areas you could not access.", + "6. Note anything that is explicitly NOT present (missing tests, missing config, etc.).", + "", + "Report your verified findings and any gaps in the `thoughts` parameter.", + ], + }; + + case 4: + return { + title: SCOUT_STEP_NAMES[4], + instructions: [ + "Write your findings to the output file.", + "", + `**Output file:** ${outputFile}`, + "", + "Write a markdown file with these exact sections:", + "", + "## Question", + "Restate the assigned question verbatim.", + "", + "## Findings", + "Factual observations that answer the question. Use sub-sections if the answer has multiple parts.", + "Cite file paths and line numbers for every claim. Include code snippets where relevant.", + "Every finding must be backed by a file you actually read — no inferred claims.", + "", + "## Files Examined", + "List every file you read during this investigation.", + "", + "## Gaps", + "Note anything you could not determine. If no gaps, write: (none)", + ], + }; + + default: + return { + title: `Step ${step}`, + instructions: [`Execute step ${step}.`], + }; + } } From 8d5104c9f9e11ce1dd6efadc86b69fc479d73c40 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:48:35 +0700 Subject: [PATCH 054/412] inline scout findings content in koan_request_scouts response --- src/planner/tools/ask.ts | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/src/planner/tools/ask.ts b/src/planner/tools/ask.ts index 57a8b8a..c567549 100644 --- a/src/planner/tools/ask.ts +++ b/src/planner/tools/ask.ts @@ -5,6 +5,9 @@ // koan_ask_question — ask the user a question, get answers // koan_request_scouts — request parallel codebase scouts, get findings paths +import { promises as fs } from "node:fs"; +import * as path from "node:path"; + import { Type, type Static } from "@sinclair/typebox"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; @@ -322,19 +325,27 @@ export function registerAskTools(pi: ExtensionAPI, ctx: RuntimeContext): void { switch (pollResult) { case "completed": { - const lines: string[] = [ + const sections: string[] = [ `Scout findings: ${findings.length} completed, ${failures.length} failed.`, "", ]; - if (findings.length > 0) { - lines.push("Findings files (read these for codebase context):"); - for (const f of findings) lines.push(` ${f}`); + // Read each findings file and include contents verbatim. + for (const f of findings) { + try { + const content = await fs.readFile(f, "utf8"); + sections.push(`--- scout: ${path.basename(path.dirname(f))} ---`); + sections.push(content.trim()); + sections.push(""); + } catch { + sections.push(`--- scout: ${path.basename(path.dirname(f))} --- (could not read findings)`); + sections.push(""); + } } if (failures.length > 0) { - lines.push(`Failed scouts (non-fatal, proceed without them): ${failures.join(", ")}`); + sections.push(`Failed scouts (non-fatal, proceed without them): ${failures.join(", ")}`); } return { - content: [{ type: "text" as const, text: lines.join("\n") }], + content: [{ type: "text" as const, text: sections.join("\n") }], details: undefined, }; } From b25322e5f9c04bb8169635bcd3a12ffeeddac5ae Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:48:41 +0700 Subject: [PATCH 055/412] add web dashboard for pipeline monitoring and user interaction --- src/planner/web/ARCHITECTURE.md | 143 +++ src/planner/web/css/animations.css | 40 + src/planner/web/css/components.css | 740 ++++++++++++++++ src/planner/web/css/layout.css | 212 +++++ src/planner/web/css/variables.css | 75 ++ src/planner/web/html/index.html | 17 + src/planner/web/js/app.jsx | 17 + .../web/js/components/ActivityFeed.jsx | 76 ++ .../web/js/components/AgentMonitor.jsx | 48 ++ src/planner/web/js/components/AgentRow.jsx | 40 + src/planner/web/js/components/App.jsx | 39 + src/planner/web/js/components/Header.jsx | 24 + src/planner/web/js/components/ModelConfig.jsx | 152 ++++ .../web/js/components/Notifications.jsx | 25 + .../web/js/components/PhaseContent.jsx | 32 + src/planner/web/js/components/PillStrip.jsx | 29 + src/planner/web/js/components/ProgressBar.jsx | 15 + .../web/js/components/SubagentMeta.jsx | 20 + src/planner/web/js/components/Timer.jsx | 17 + .../web/js/components/forms/QuestionCard.jsx | 84 ++ .../web/js/components/forms/QuestionForm.jsx | 60 ++ .../web/js/components/forms/ReviewForm.jsx | 51 ++ .../web/js/components/phases/Completion.jsx | 23 + .../js/components/phases/Consolidation.jsx | 39 + .../js/components/phases/ContextAnalysis.jsx | 21 + .../web/js/components/phases/Execution.jsx | 34 + .../web/js/components/phases/Loading.jsx | 14 + .../js/components/phases/ScoutExploration.jsx | 60 ++ src/planner/web/js/lib/api.js | 27 + src/planner/web/js/lib/utils.js | 21 + src/planner/web/js/sse.js | 48 ++ src/planner/web/js/store.js | 19 + src/planner/web/server-types.ts | 249 ++++++ src/planner/web/server.ts | 815 ++++++++++++++++++ 34 files changed, 3326 insertions(+) create mode 100644 src/planner/web/ARCHITECTURE.md create mode 100644 src/planner/web/css/animations.css create mode 100644 src/planner/web/css/components.css create mode 100644 src/planner/web/css/layout.css create mode 100644 src/planner/web/css/variables.css create mode 100644 src/planner/web/html/index.html create mode 100644 src/planner/web/js/app.jsx create mode 100644 src/planner/web/js/components/ActivityFeed.jsx create mode 100644 src/planner/web/js/components/AgentMonitor.jsx create mode 100644 src/planner/web/js/components/AgentRow.jsx create mode 100644 src/planner/web/js/components/App.jsx create mode 100644 src/planner/web/js/components/Header.jsx create mode 100644 src/planner/web/js/components/ModelConfig.jsx create mode 100644 src/planner/web/js/components/Notifications.jsx create mode 100644 src/planner/web/js/components/PhaseContent.jsx create mode 100644 src/planner/web/js/components/PillStrip.jsx create mode 100644 src/planner/web/js/components/ProgressBar.jsx create mode 100644 src/planner/web/js/components/SubagentMeta.jsx create mode 100644 src/planner/web/js/components/Timer.jsx create mode 100644 src/planner/web/js/components/forms/QuestionCard.jsx create mode 100644 src/planner/web/js/components/forms/QuestionForm.jsx create mode 100644 src/planner/web/js/components/forms/ReviewForm.jsx create mode 100644 src/planner/web/js/components/phases/Completion.jsx create mode 100644 src/planner/web/js/components/phases/Consolidation.jsx create mode 100644 src/planner/web/js/components/phases/ContextAnalysis.jsx create mode 100644 src/planner/web/js/components/phases/Execution.jsx create mode 100644 src/planner/web/js/components/phases/Loading.jsx create mode 100644 src/planner/web/js/components/phases/ScoutExploration.jsx create mode 100644 src/planner/web/js/lib/api.js create mode 100644 src/planner/web/js/lib/utils.js create mode 100644 src/planner/web/js/sse.js create mode 100644 src/planner/web/js/store.js create mode 100644 src/planner/web/server-types.ts create mode 100644 src/planner/web/server.ts diff --git a/src/planner/web/ARCHITECTURE.md b/src/planner/web/ARCHITECTURE.md new file mode 100644 index 0000000..8731e36 --- /dev/null +++ b/src/planner/web/ARCHITECTURE.md @@ -0,0 +1,143 @@ +# Web UI Architecture + +Single-page dashboard served by `server.ts`. Pushes state via SSE; receives +user input via POST. Built with Preact + Zustand — see +`plans/2026-03-16-preact-zustand-rewrite.md` for the full decision record. + +--- + +## Directory layout + +``` +server.ts HTTP server, SSE push, WebServerHandle API +server-types.ts Shared TypeScript types +html/index.html Shell —

+ module script, no static skeleton +css/ Four unchanged stylesheets (variables, layout, components, animations) +dist/app.js Compiled bundle — generated, not committed +js/ + app.jsx Entry: render(), connectSSE(), heartbeat interval + store.js Zustand store (single source of truth) + sse.js SSE connection + store updates + lib/utils.js formatTokens, formatElapsed, shortenModel + lib/api.js submitAnswers, submitReview (fetch wrappers) + components/ Preact component tree (see §Component tree below) +``` + +--- + +## Build pipeline + +esbuild compiles `js/app.jsx` and all imports into `dist/app.js` (single ESM +bundle, ~44KB raw / ~16KB gzip). + +**The alias flags are mandatory.** zustand v4 imports from `react` internally. +Without aliasing, esbuild bundles the full React 19 runtime (~17KB) alongside +Preact — two competing VDOM reconcilers that cannot share a hook dispatcher. +The aliases redirect those imports to `preact/compat`: + +``` +--alias:react=preact/compat --alias:react-dom=preact/compat +``` + +These appear in both the npm script (`build:web`) and in the `esbuild.build()` +call inside `ensureBundle()` in `server.ts`. If you add them to one, add them +to both. + +**On-demand build:** `ensureBundle()` in `server.ts` runs at the top of +`startWebServer()`. It stats `dist/app.js` against the newest file in `js/` +and rebuilds only when stale. Adds ~100ms on first start; skips on subsequent +starts. No manual build step is needed during development — pi loads extensions +from source, so `startWebServer()` is always the entry point. + +**CI/test path:** `npm run build` runs `build:web` then `tsc`. The tsc step +does not process JSX; it type-checks the TypeScript source only. + +**zustand version:** Pinned to v4 (`^4.5.7`). zustand v5 moved its default +export to `zustand/react`, which imports React at module level and breaks +the esbuild bundle even with the alias. + +--- + +## Data flow + +``` +server.ts ──SSE──► sse.js ──setState──► Zustand store ──selector──► components + │ +user action ◄──fetch── lib/api.js ◄──────────────────────────┘ +``` + +1. `server.ts` pushes SSE events on a 2-second polling tick. +2. `sse.js` registers one `addEventListener` per event type. Each handler + calls `useStore.setState()` — the static method, callable outside + component context. +3. Components subscribe via `useStore(s => s.slice)`. Zustand shallow-merges + `setState` calls and notifies only subscribers whose selected slice changed. + A component reading `s.agents` does not re-render when `s.phase` changes. +4. User actions (form submit, heartbeat) call `lib/api.js` fetch wrappers + which POST to `/api/answer`, `/api/review`, or `/api/heartbeat`. + +`pendingInput` is cleared by the server: a phase transition out of `intake` +clears it in the `phase` handler; `ask-cancelled` / `review-cancelled` clear +it by request ID. + +--- + +## Component tree + +``` +App +├── ProgressBar reads intakeProgress.{subPhase,intakeDone} +├── Header +│ ├── PillStrip reads intakeProgress.{subPhase,intakeDone} +│ └── Timer reads subagent.startedAt, ticks via useEffect interval +├── main.phase-content +│ └── PhaseContent dispatch hub (see below) +├── AgentMonitor reads agents; renders AgentRow per agent +└── Notifications reads notifications; auto-dismisses via useEffect +``` + +**PhaseContent dispatch order:** + +1. `!phase` → `` +2. `pendingInput.type === 'ask'` → `` +3. `pendingInput.type === 'review'` → `` +4. `phase === 'intake'` → dispatches on `intakeProgress.subPhase`: + - `'context'` or null → `` + - `'explore'` → `` + - `'questions'` or `'spec'` → `` +5. `phase === 'completed'` → `` +6. default → `` + +`key={requestId}` on forms forces a full remount when a new request arrives, +resetting local selection state without any explicit cleanup. + +--- + +## Server-side changes + +**`ensureBundle()`** — async function before `startWebServer()` body. Uses +esbuild JS API via dynamic `await import("esbuild")`. `STATIC_ASSETS` is +constructed inside `startWebServer()` after this call completes (it was at +module scope in the old code; moved because asset loading must follow the build). + +**`intake-progress` SSE event** — denormalized event carrying +`{ subPhase: string | null, intakeDone: boolean }`. Pushed from: +- `startAgentPolling()` — after each `agents` push, if subPhase or intakeDone changed +- `handle.pushPhase()` — updates `intakeDone` on every phase transition + +Replayed in `replayState()` on SSE reconnect. Allows `PhaseContent`, +`PillStrip`, and `ProgressBar` to all subscribe to the same store slice +(`intakeProgress`) rather than using two different mechanisms. + +--- + +## Conventions + +| Convention | Rule | +|---|---| +| JSX attribute | `class`, not `className` (Preact uses HTML attribute names) | +| Hook imports | `import { useState, useEffect } from 'preact/hooks'` | +| Render import | `import { render } from 'preact'` (not `preact/compat`) | +| External setState | `useStore.setState(...)` — static method, works outside components | +| Fragment syntax | `<>…` — works because build uses `--jsx=automatic` | +| Zustand merge | `setState` merges shallowly; always replace the full slice, never mutate nested objects | diff --git a/src/planner/web/css/animations.css b/src/planner/web/css/animations.css new file mode 100644 index 0000000..046b2b8 --- /dev/null +++ b/src/planner/web/css/animations.css @@ -0,0 +1,40 @@ +/* CSS-only spinner */ +@keyframes spin { + to { transform: rotate(360deg); } +} + +/* Phase content crossfade */ +@keyframes fade-in { + from { opacity: 0; } + to { opacity: 1; } +} + +.phase-content .phase-inner { + animation: fade-in 250ms ease-out; +} + +/* Sliding text input for "Other" option */ +@keyframes slide-open { + from { max-height: 0; opacity: 0; } + to { max-height: 80px; opacity: 1; } +} + +/* Pill state transitions */ +.pill { + transition: background 200ms ease, color 200ms ease, border-color 200ms ease; +} + +/* Progress bar fill */ +.progress-fill { + transition: width 400ms cubic-bezier(0.4, 0, 0.2, 1); +} + +/* Notification fade-out */ +.notification.fade-out { + animation: fade-out 300ms ease-in forwards; +} + +@keyframes fade-out { + from { opacity: 1; transform: translateY(0); } + to { opacity: 0; transform: translateY(8px); } +} diff --git a/src/planner/web/css/components.css b/src/planner/web/css/components.css new file mode 100644 index 0000000..a81ccc7 --- /dev/null +++ b/src/planner/web/css/components.css @@ -0,0 +1,740 @@ +/* ---- Pill strip ---- */ +.pill-strip { + display: flex; + border-radius: var(--radius-md); + overflow: hidden; + border: 1px solid var(--border); +} + +.pill { + font-family: var(--font-mono); + font-size: var(--font-size-sm); + padding: 3px 10px; + border-right: 1px solid var(--border); + color: var(--text-dim); + background: var(--bg); + transition: background 150ms, color 150ms; + white-space: nowrap; +} + +.pill:last-child { + border-right: none; +} + +.pill.active { + background: var(--blue-border); + color: #fff; + border-color: var(--blue-border); +} + +.pill.done { + background: var(--green-border); + color: #fff; + border-color: var(--green-border); +} + +.pill.done::before { + content: "✓ "; +} + +.pill.active::before { + content: "● "; +} + +/* ---- Badges ---- */ +.badge { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + padding: 1px 6px; + border-radius: 10px; + font-weight: 600; +} + +.badge.done { background: var(--green-border); color: #fff; } +.badge.active { background: var(--blue-border); color: #fff; } +.badge.failed { background: var(--red-border); color: #fff; } + +/* ---- Agent table ---- */ +.agent-table { + width: 100%; + border-collapse: collapse; + font-size: var(--font-size-sm); +} + +.agent-table th { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--text-dim); + text-transform: uppercase; + letter-spacing: 0.06em; + padding: 4px 8px; + text-align: left; + border-bottom: 1px solid var(--border); +} + +.agent-table td { + padding: 5px 8px; + vertical-align: top; + border-bottom: 1px solid var(--border-light); +} + +.col-status { width: 24px; text-align: center; } +.col-model { width: 90px; white-space: nowrap; } +.col-parent { width: 90px; white-space: nowrap; } +.col-tokens { width: 60px; text-align: right; white-space: nowrap; } +.col-doing { /* flex */ } + +.agent-status-running { color: var(--blue); } +.agent-status-done { color: var(--green); font-weight: 600; } +.agent-status-failed { color: var(--red); } + +.agent-name-running { color: var(--text); font-weight: 600; font-family: var(--font-mono); } +.agent-name-done { color: var(--green); font-family: var(--font-mono); } +.agent-name-failed { color: var(--red); font-family: var(--font-mono); } + +.agent-model-cell { font-family: var(--font-mono); color: var(--text-muted); } +.agent-parent-cell { font-family: var(--font-mono); color: var(--text-dim); } +.agent-tokens-cell { font-family: var(--font-mono); color: var(--text-muted); } + +.agent-doing-lines { + display: flex; + flex-direction: column; + gap: 1px; +} + +.agent-doing-line { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--text-muted); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; + max-width: 600px; +} + +.agent-doing-line:last-child { + color: var(--text); +} + +/* ---- Card ---- */ +.card { + background: var(--bg-surface); + border: 1px solid var(--border); + border-radius: var(--radius-md); + padding: var(--gap-md) var(--gap-lg); + margin-bottom: var(--gap-md); +} + +.card.card-running { + border-left: 3px solid var(--blue); +} + +.card.card-done { + background: var(--green-bg); + border-color: var(--green-border); +} + +.card.card-failed { + background: var(--red-bg); + border-color: var(--red-border); +} + +.card-header { + display: flex; + align-items: center; + gap: var(--gap-sm); + margin-bottom: var(--gap-sm); +} + +.card-title { + font-family: var(--font-mono); + font-weight: 700; + font-size: var(--font-size-lg); + color: var(--text-strong); +} + +.card-role { + margin-left: auto; + font-family: var(--font-mono); + font-size: var(--font-size-sm); + color: var(--text-dim); +} + +.card-body { + font-family: var(--font-sans); + font-size: var(--font-size-lg); + color: var(--text-muted); + line-height: 1.5; +} + +/* ---- Question cards ---- */ +.question-card { + background: var(--bg-surface); + border: 1px solid var(--border); + border-radius: var(--radius-md); + padding: var(--gap-lg); + margin-bottom: var(--gap-lg); +} + +.question-header { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--text-dim); + text-transform: uppercase; + letter-spacing: 0.06em; + margin-bottom: var(--gap-sm); +} + +.question-text { + font-family: var(--font-sans); + font-size: 18px; + font-weight: 500; + color: var(--text-strong); + margin-bottom: var(--gap-md); + line-height: 1.5; +} + +.question-multi-hint { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--blue); + margin-bottom: var(--gap-sm); +} + +.options-list { + display: flex; + flex-direction: column; + gap: var(--gap-xs); +} + +.option { + display: flex; + align-items: flex-start; + gap: var(--gap-sm); + padding: var(--gap-sm) var(--gap-md); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + background: var(--bg); + cursor: pointer; + transition: border-color 100ms, background 100ms; + user-select: none; +} + +.option:hover { + border-color: var(--text-dim); +} + +.option.selected { + border-color: var(--blue-border); + background: var(--blue-bg); +} + +.option-other { + border-style: dashed; +} + +.radio-dot, .checkbox-dot { + width: 14px; + height: 14px; + border: 2px solid var(--text-ghost); + border-radius: 50%; + flex-shrink: 0; + margin-top: 2px; + transition: border-color 100ms, background 100ms; +} + +.checkbox-dot { + border-radius: 3px; +} + +.option.selected .radio-dot, +.option.selected .checkbox-dot { + border-color: var(--blue); + background: var(--blue); +} + +.option.selected .checkbox-dot::after { + content: "✓"; + display: block; + color: #fff; + font-size: 9px; + text-align: center; + line-height: 10px; +} + +.option-text { + font-family: var(--font-sans); + font-size: var(--font-size-lg); + color: var(--text); + flex: 1; +} + +.option-other .option-text { + color: var(--text-dim); +} + +.recommended-badge { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--blue); + margin-left: auto; + white-space: nowrap; +} + +.other-input { + display: none; + width: 100%; + margin-top: var(--gap-sm); + padding: var(--gap-sm); + background: var(--bg); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + color: var(--text); + font-family: var(--font-sans); + font-size: var(--font-size-md); + outline: none; +} + +.other-input:focus { + border-color: var(--blue-border); +} + +.other-input.visible { + display: block; + animation: slide-open 150ms ease-out; +} + +/* ---- Form actions ---- */ +.form-actions { + display: flex; + gap: var(--gap-md); + margin-top: var(--gap-xl); + align-items: center; +} + +.form-helper { + font-family: var(--font-mono); + font-size: var(--font-size-sm); + color: var(--text-dim); + margin-left: auto; +} + +.btn { + padding: var(--gap-sm) var(--gap-lg); + border-radius: var(--radius-sm); + font-size: var(--font-size-md); + font-family: var(--font-sans); + cursor: pointer; + border: 1px solid transparent; + transition: opacity 100ms; +} + +.btn:disabled { + opacity: 0.5; + cursor: not-allowed; +} + +.btn-primary { + background: var(--green-border); + color: #fff; + border-color: var(--green-border); +} + +.btn-secondary { + background: transparent; + color: var(--text-muted); + border-color: var(--border); +} + +/* ---- Review checklist ---- */ +.review-story { + display: flex; + align-items: center; + gap: var(--gap-md); + padding: var(--gap-sm) var(--gap-md); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + background: var(--bg); + margin-bottom: var(--gap-sm); + cursor: pointer; + user-select: none; +} + +.review-story.checked { + border-color: var(--green-border); + background: var(--green-bg); +} + +.review-story-checkbox { + width: 16px; + height: 16px; + border: 2px solid var(--text-ghost); + border-radius: 3px; + flex-shrink: 0; + transition: border-color 100ms, background 100ms; +} + +.review-story.checked .review-story-checkbox { + border-color: var(--green-border); + background: var(--green-border); +} + +.review-story.checked .review-story-checkbox::after { + content: "✓"; + display: block; + color: #fff; + font-size: 10px; + text-align: center; + line-height: 12px; +} + +.review-story-id { + font-family: var(--font-mono); + font-size: var(--font-size-md); + color: var(--text); + font-weight: 600; +} + +.review-story-title { + font-family: var(--font-sans); + font-size: var(--font-size-md); + color: var(--text-muted); +} + +/* ---- Loading spinner ---- */ +.spinner { + width: 24px; + height: 24px; + border: 2px solid var(--border); + border-top-color: var(--blue); + border-radius: 50%; + animation: spin 800ms linear infinite; +} + +/* ---- Topic card ---- */ +.topic-card { + background: var(--bg-surface); + border: 1px solid var(--border); + border-radius: var(--radius-md); + padding: var(--gap-md) var(--gap-lg); + margin-top: var(--gap-lg); + max-width: 640px; +} + +.topic-label { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--text-dim); + text-transform: uppercase; + letter-spacing: 0.08em; + margin-bottom: var(--gap-xs); +} + +.topic-text { + font-family: var(--font-sans); + font-size: var(--font-size-lg); + color: var(--text); + font-style: italic; + line-height: 1.5; +} + +/* ---- Activity feed (context analysis) ---- */ +.activity-feed { + background: var(--bg-surface); + border: 1px solid var(--border); + border-radius: var(--radius-md); + padding: var(--gap-md); + margin-top: var(--gap-md); +} + +.activity-line { + display: flex; + gap: var(--gap-sm); + font-family: var(--font-mono); + font-size: var(--font-size-md); + color: var(--text-muted); + padding: 3px 0; +} + +.activity-tool { + color: var(--blue); + min-width: 60px; +} + +/* ---- Phase status messages ---- */ +.phase-status { + font-family: var(--font-sans); + font-size: var(--font-size-lg); + color: var(--text); + margin-bottom: var(--gap-lg); +} + +.phase-heading { + font-family: var(--font-sans); + font-size: 22px; + font-weight: 600; + color: var(--text-strong); + margin-bottom: var(--gap-lg); +} + +/* ---- Summary checklist ---- */ +.summary-list { + background: var(--bg-surface); + border: 1px solid var(--border); + border-radius: var(--radius-md); + padding: var(--gap-md) var(--gap-lg); +} + +.summary-item { + display: flex; + align-items: center; + gap: var(--gap-md); + padding: 4px 0; + font-family: var(--font-sans); + font-size: var(--font-size-md); +} + +.summary-item .icon-done { color: var(--green); } +.summary-item .icon-pending { color: var(--text-dim); } + +/* ---- Notification toasts ---- */ +#notifications { + position: fixed; + bottom: var(--gap-xl); + right: var(--gap-xl); + display: flex; + flex-direction: column; + gap: var(--gap-sm); + z-index: 200; +} + +.notification { + padding: var(--gap-sm) var(--gap-lg); + border-radius: var(--radius-md); + font-family: var(--font-sans); + font-size: var(--font-size-md); + color: #fff; + animation: fade-in 150ms ease-out; +} + +.notification.info { background: var(--blue-border); } +.notification.warning { background: #9a6700; } +.notification.error { background: var(--red-border); } + +/* ---- Count progress indicator ---- */ +.count-progress { + font-family: var(--font-mono); + font-size: var(--font-size-sm); + color: var(--text-dim); + margin-bottom: var(--gap-lg); +} + +/* ---- Context so far section ---- */ +.context-section-label { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--text-dim); + text-transform: uppercase; + letter-spacing: 0.08em; + margin: var(--gap-lg) 0 var(--gap-sm); +} + +.context-items { + list-style: none; + padding: 0; + margin: 0; +} + +.context-items li { + padding: 3px 0; + font-family: var(--font-sans); + font-size: var(--font-size-md); + color: var(--text-muted); +} + +.context-items li::before { + content: "• "; + color: var(--green); +} + +/* ---- Model config ---- */ +.model-config-tiers { + display: flex; + flex-direction: column; + gap: var(--gap-lg); + margin-top: var(--gap-lg); + margin-bottom: var(--gap-xl); +} + +.model-tier-row { + background: var(--bg-surface); + border: 1px solid var(--border); + border-radius: var(--radius-md); + padding: var(--gap-md) var(--gap-lg); +} + +.model-tier-header { + display: flex; + align-items: center; + gap: var(--gap-sm); + margin-bottom: var(--gap-xs); +} + +.model-tier-label { + font-family: var(--font-mono); + font-size: var(--font-size-lg); + font-weight: 700; + color: var(--text-strong); + text-transform: uppercase; + letter-spacing: 0.06em; +} + +.model-tier-description { + font-family: var(--font-sans); + font-size: var(--font-size-md); + color: var(--text-muted); + line-height: 1.5; + margin: 0 0 var(--gap-md); +} + +.model-tier-input { + width: 100%; + padding: var(--gap-sm) var(--gap-md); + background: var(--bg); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + color: var(--text); + font-family: var(--font-mono); + font-size: var(--font-size-md); + outline: none; + box-sizing: border-box; +} + +.model-tier-input:focus { + border-color: var(--blue-border); +} + +.model-tier-input::placeholder { + color: var(--text-dim); + font-style: italic; +} +.model-tier-select { + width: 100%; + padding: var(--gap-sm) var(--gap-md); + background: var(--bg); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + color: var(--text); + font-family: var(--font-mono); + font-size: var(--font-size-md); + outline: none; + box-sizing: border-box; + cursor: pointer; + -webkit-appearance: none; + appearance: none; + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8'%3E%3Cpath d='M1 1l5 5 5-5' stroke='%23727d8a' stroke-width='1.5' fill='none'/%3E%3C/svg%3E"); + background-repeat: no-repeat; + background-position: right 12px center; + padding-right: 36px; +} + +.model-tier-select:focus { + border-color: var(--blue-border); +} + +.model-tier-select option { + background: var(--bg-surface); + color: var(--text); +} + +.model-tier-select optgroup { + color: var(--text-muted); + font-style: normal; +} + +.model-config-warning { + font-family: var(--font-sans); + font-size: var(--font-size-sm); + color: var(--red); + margin-bottom: var(--gap-md); +} + +/* ---- Settings button ---- */ +.header-right { + display: flex; + align-items: center; + gap: var(--gap-lg); +} + +.settings-btn { + background: none; + border: 1px solid var(--border); + border-radius: var(--radius-sm); + color: var(--text-muted); + font-size: 16px; + padding: 4px 8px; + cursor: pointer; + transition: color 150ms, border-color 150ms; + line-height: 1; +} + +.settings-btn:hover { + color: var(--text-strong); + border-color: var(--text-dim); +} + +/* ---- Activity feed: in-flight + flash ---- */ +@keyframes result-flash { + 0% { background: rgba(126, 231, 135, 0.15); } + 100% { background: transparent; } +} + +.activity-inflight .activity-summary { + color: var(--yellow); +} + +.activity-flash { + animation: result-flash 400ms ease-out; + border-radius: 3px; +} + +.activity-dots { + display: inline-block; + overflow: hidden; + vertical-align: bottom; + animation: dots-anim 1.5s steps(4, end) infinite; + width: 0; + max-width: 18px; +} + +@keyframes dots-anim { + 0% { width: 0; } + 100% { width: 18px; } +} + +/* ---- Agent row: spinner prefix dots ---- */ +@keyframes pulse-dot { + 0%, 100% { opacity: 0.3; } + 50% { opacity: 1; } +} + +.agent-doing-prefix { + display: inline-block; + width: 12px; + text-align: center; + margin-right: 4px; + flex-shrink: 0; +} + +.prefix-done { + color: var(--green); +} + +.prefix-active { + color: var(--blue); + animation: pulse-dot 1s ease-in-out infinite; +} + +.agent-doing-inflight { + color: var(--text) !important; +} diff --git a/src/planner/web/css/layout.css b/src/planner/web/css/layout.css new file mode 100644 index 0000000..b20b374 --- /dev/null +++ b/src/planner/web/css/layout.css @@ -0,0 +1,212 @@ +.app { + display: flex; + flex-direction: column; + height: 100vh; + overflow: hidden; +} + +/* Progress bar — 3px at the very top */ +.progress-bar { + position: fixed; + top: 0; + left: 0; + right: 0; + height: 3px; + background: var(--border); + z-index: 100; +} + +.progress-fill { + height: 100%; + width: 0%; + background: linear-gradient(90deg, var(--green), var(--blue)); + transition: width 400ms cubic-bezier(0.4, 0, 0.2, 1); +} + +/* Header */ +.header { + position: fixed; + top: 3px; /* below progress bar */ + left: 0; + right: 0; + height: var(--header-height); + display: flex; + align-items: center; + justify-content: space-between; + padding: 0 var(--gap-xl); + background: var(--bg); + border-bottom: 1px solid var(--border); + z-index: 50; +} + +.header-left { + display: flex; + align-items: center; + gap: var(--gap-lg); +} + +.logo { + font-family: var(--font-mono); + font-size: 18px; + font-weight: 600; + color: var(--text-strong); + letter-spacing: 0.05em; +} + +.timer { + font-family: var(--font-mono); + font-size: var(--font-size-md); + color: var(--text-muted); +} + +/* Main panel — fills all remaining vertical space */ +.main-panel { + flex: 1 1 0; + min-height: 0; + display: flex; + flex-direction: column; + margin-top: calc(3px + var(--header-height)); +} + +/* Subagent metadata bar */ +.subagent-meta { + flex: 0 0 auto; + display: flex; + align-items: center; + gap: var(--gap-lg); + padding: var(--gap-sm) var(--gap-xl); + border-bottom: 1px solid var(--border); + background: var(--bg-surface); + font-family: var(--font-mono); + font-size: var(--font-size-sm); +} + +.meta-role { + color: var(--blue); + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.06em; +} + +.meta-item { + color: var(--text-muted); +} + +.meta-item::before { + content: '·'; + color: var(--text-ghost); + margin-right: var(--gap-lg); +} + +.meta-tokens { + margin-left: auto; + color: var(--text-dim); +} + +/* Phase content area — scrollable, fills remaining space */ +.phase-content { + flex: 1 1 0; + min-height: 0; + overflow-y: auto; + padding: var(--gap-xl); + display: flex; + flex-direction: column; + align-items: center; +} + +.phase-inner { + width: 100%; + max-width: 960px; +} + +/* Activity feed — fills remaining space in phase-content, scrollable */ +.activity-feed-scroll { + flex: 1 1 0; + min-height: 0; + overflow-y: auto; + padding: var(--gap-md) var(--gap-xl); + /* Subtle fade at top when scrolled */ + mask-image: linear-gradient(to bottom, transparent, black 8px, black); + -webkit-mask-image: linear-gradient(to bottom, transparent, black 8px, black); +} + +.activity-feed-inner { + display: flex; + flex-direction: column; + gap: 1px; +} + +.activity-line { + display: flex; + gap: var(--gap-sm); + font-family: var(--font-mono); + font-size: var(--font-size-sm); + color: var(--text-dim); + padding: 2px 0; + line-height: 1.4; +} + +.activity-line.activity-high { + color: var(--text-muted); +} + +.activity-tool { + color: var(--text-ghost); + min-width: 48px; + flex-shrink: 0; +} + +.activity-high .activity-tool { + color: var(--blue); +} + +.activity-summary { + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; +} + +.activity-detail { + color: var(--text-ghost); + padding-left: 12px; +} + +/* Monitor — sticky bottom, sizes to content */ +.monitor { + flex: 0 0 auto; + max-height: 40vh; + overflow-y: auto; + border-top: 1px solid var(--border); + background: var(--bg-elevated); + padding: var(--gap-md) var(--gap-xl); + /* Fade at top edge when scrollable */ + mask-image: linear-gradient(to bottom, transparent, black 12px, black); + -webkit-mask-image: linear-gradient(to bottom, transparent, black 12px, black); +} + +.agent-table-header { + display: flex; + align-items: center; + gap: var(--gap-md); + margin-bottom: var(--gap-sm); +} + +.monitor-label { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--text-dim); + text-transform: uppercase; + letter-spacing: 0.08em; +} + +.agent-badges { + display: flex; + gap: var(--gap-xs); +} + +.token-totals { + margin-left: auto; + font-family: var(--font-mono); + font-size: var(--font-size-sm); + color: var(--text-muted); +} diff --git a/src/planner/web/css/variables.css b/src/planner/web/css/variables.css new file mode 100644 index 0000000..3e967aa --- /dev/null +++ b/src/planner/web/css/variables.css @@ -0,0 +1,75 @@ +:root { + /* Background layers */ + --bg: #0d1117; + --bg-surface: #161b22; + --bg-elevated: #0c0f14; + + /* Borders */ + --border: #21262d; + --border-light: #161b22; + + /* Text hierarchy */ + --text: #d6dde5; + --text-strong: #f0f3f6; + --text-muted: #9da7b3; + --text-dim: #727d8a; + --text-ghost: #444d56; + + /* Status colors */ + --green: #7ee787; + --green-bg: rgba(35, 134, 54, 0.06); + --green-border: #238636; + --blue: #58a6ff; + --blue-bg: rgba(31, 111, 235, 0.06); + --blue-border: #1f6feb; + --purple: #d2a8ff; + --orange: #ffa657; + --red: #f85149; + --red-bg: rgba(248, 81, 73, 0.06); + --red-border: #da3633; + --yellow: #e3b341; + --pink: #f778ba; + + /* Typography */ + --font-mono: 'SF Mono', 'JetBrains Mono', 'Cascadia Code', 'Fira Code', monospace; + --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; + + /* Font sizes */ + --font-size-xs: 12px; + --font-size-sm: 13px; + --font-size-md: 15px; + --font-size-lg: 16px; + + /* Spacing */ + --gap-xs: 4px; + --gap-sm: 8px; + --gap-md: 12px; + --gap-lg: 16px; + --gap-xl: 20px; + + /* Header */ + --header-height: 52px; + + /* Monitor */ + --monitor-min-height: 120px; + + /* Radius */ + --radius-sm: 4px; + --radius-md: 6px; + --radius-lg: 8px; +} + +*, *::before, *::after { + box-sizing: border-box; +} + +html, body { + margin: 0; + padding: 0; + height: 100%; + background: var(--bg); + color: var(--text); + font-family: var(--font-sans); + font-size: var(--font-size-md); + line-height: 1.5; +} diff --git a/src/planner/web/html/index.html b/src/planner/web/html/index.html new file mode 100644 index 0000000..91b9e10 --- /dev/null +++ b/src/planner/web/html/index.html @@ -0,0 +1,17 @@ + + + + + + koan + + + + + + + +
+ + + diff --git a/src/planner/web/js/app.jsx b/src/planner/web/js/app.jsx new file mode 100644 index 0000000..035a254 --- /dev/null +++ b/src/planner/web/js/app.jsx @@ -0,0 +1,17 @@ +import { render } from 'preact' +import { App } from './components/App.jsx' +import { connectSSE } from './sse.js' + +const data = window.__DATA__ +const token = data?.token || new URLSearchParams(location.search).get('session') || '' + +render(, document.getElementById('app')) +connectSSE(token) + +setInterval(() => { + fetch('/api/heartbeat', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ token }), + }).catch(() => {}) +}, 5000) diff --git a/src/planner/web/js/components/ActivityFeed.jsx b/src/planner/web/js/components/ActivityFeed.jsx new file mode 100644 index 0000000..ed71786 --- /dev/null +++ b/src/planner/web/js/components/ActivityFeed.jsx @@ -0,0 +1,76 @@ +import { useRef, useEffect, useState } from 'preact/hooks' +import { useStore } from '../store.js' + +export function ActivityFeed() { + const logs = useStore(s => s.logs) + const containerRef = useRef(null) + const stickRef = useRef(true) + + // Track previous last-line to detect in-flight → completed transitions. + const prevLastRef = useRef(null) + const [flashIndex, setFlashIndex] = useState(-1) + + // Auto-scroll to bottom when new logs arrive, but only if already at bottom. + useEffect(() => { + const el = containerRef.current + if (el && stickRef.current) { + el.scrollTop = el.scrollHeight + } + }, [logs]) + + // Detect when the last line transitions from in-flight to completed and flash it. + useEffect(() => { + const lastLine = logs[logs.length - 1] + if (prevLastRef.current?.inFlight && lastLine && !lastLine.inFlight) { + const idx = logs.length - 1 + setFlashIndex(idx) + setTimeout(() => setFlashIndex(-1), 400) + } + prevLastRef.current = lastLine ? { ...lastLine } : null + }, [logs]) + + function onScroll() { + const el = containerRef.current + if (!el) return + // "At bottom" if within 30px of the end. + stickRef.current = el.scrollTop + el.clientHeight >= el.scrollHeight - 30 + } + + if (logs.length === 0) return null + + return ( +
+
+ {logs.map((line, i) => { + // Only the last line can be in-flight — earlier lines are always done. + const isInFlight = !!line.inFlight && i === logs.length - 1 + const isFlashing = i === flashIndex + const cls = [ + 'activity-line', + line.highValue ? 'activity-high' : '', + isInFlight ? 'activity-inflight' : '', + isFlashing ? 'activity-flash' : '', + ].filter(Boolean).join(' ') + + return ( + <> +
+ {line.tool} + + {line.summary || ''} + {isInFlight && ...} + +
+ {line.details?.map((d, j) => ( +
+ + {d} +
+ ))} + + ) + })} +
+
+ ) +} diff --git a/src/planner/web/js/components/AgentMonitor.jsx b/src/planner/web/js/components/AgentMonitor.jsx new file mode 100644 index 0000000..b87d763 --- /dev/null +++ b/src/planner/web/js/components/AgentMonitor.jsx @@ -0,0 +1,48 @@ +import { useStore } from '../store.js' +import { formatTokens } from '../lib/utils.js' +import { AgentRow } from './AgentRow.jsx' + +export function AgentMonitor() { + const allAgents = useStore(s => s.agents) + // Only show nested subagents (those with a parent), and only running ones + const agents = allAgents.filter(a => a.status === 'running' && a.parent) + const sent = agents.reduce((s, a) => s + (a.tokensSent || 0), 0) + const recv = agents.reduce((s, a) => s + (a.tokensReceived || 0), 0) + + if (agents.length === 0) return null + + // Dynamic lines-per-agent based on count + const maxLines = agents.length <= 3 ? 5 + : agents.length <= 6 ? 3 + : agents.length <= 10 ? 2 + : 1 + + return ( +
+
+ Subagents +
+ {agents.length} +
+ + {(sent > 0 || recv > 0) ? `↑${formatTokens(sent)} ↓${formatTokens(recv)}` : ''} + +
+ + + + + + + + + + + + + {agents.map(a => )} + +
agentmodel↑ sent↓ recvdoing
+
+ ) +} diff --git a/src/planner/web/js/components/AgentRow.jsx b/src/planner/web/js/components/AgentRow.jsx new file mode 100644 index 0000000..8bc678f --- /dev/null +++ b/src/planner/web/js/components/AgentRow.jsx @@ -0,0 +1,40 @@ +import { shortenModel, formatTokens } from '../lib/utils.js' + +export function AgentRow({ agent, maxLines = 5 }) { + const actions = agent.recentActions || [] + const start = Math.max(0, actions.length - maxLines) + + return ( + + ● + {agent.name || agent.id} + {shortenModel(agent.model)} + {formatTokens(agent.tokensSent || 0)} + {formatTokens(agent.tokensReceived || 0)} + + {actions.length > 0 ? ( +
+ {actions.slice(start).map((action, i) => { + // Gracefully handle both old string[] and new object[] formats. + const text = typeof action === 'string' + ? action + : (action.summary ? `${action.tool}: ${action.summary}` : action.tool) + const inFlight = typeof action === 'object' && !!action.inFlight + + return ( +
+ + {inFlight ? '●' : '·'} + + {text} +
+ ) + })} +
+ ) : ( + initializing... + )} + + + ) +} diff --git a/src/planner/web/js/components/App.jsx b/src/planner/web/js/components/App.jsx new file mode 100644 index 0000000..031ae91 --- /dev/null +++ b/src/planner/web/js/components/App.jsx @@ -0,0 +1,39 @@ +import { ProgressBar } from './ProgressBar.jsx' +import { Header } from './Header.jsx' +import { SubagentMeta } from './SubagentMeta.jsx' +import { PhaseContent } from './PhaseContent.jsx' +import { ActivityFeed } from './ActivityFeed.jsx' +import { AgentMonitor } from './AgentMonitor.jsx' +import { Notifications } from './Notifications.jsx' +import { useStore } from '../store.js' + +export function App({ token, topic }) { + const phase = useStore(s => s.phase) + const pending = useStore(s => s.pendingInput) + const showSettings = useStore(s => s.showSettings) + + // When showing interactive content (forms, model config, loading, completion), use scroll layout + // When showing live subagent activity, use fill layout with activity feed + const isInteractive = !phase || pending || showSettings || phase === 'completed' + + return ( +
+ +
+ {isInteractive ? ( +
+
+ +
+
+ ) : ( +
+ + +
+ )} + + +
+ ) +} diff --git a/src/planner/web/js/components/Header.jsx b/src/planner/web/js/components/Header.jsx new file mode 100644 index 0000000..2e3dc9d --- /dev/null +++ b/src/planner/web/js/components/Header.jsx @@ -0,0 +1,24 @@ +import { PillStrip } from './PillStrip.jsx' +import { Timer } from './Timer.jsx' +import { useStore } from '../store.js' + +export function Header() { + return ( +
+
+ + +
+
+ + +
+
+ ) +} diff --git a/src/planner/web/js/components/ModelConfig.jsx b/src/planner/web/js/components/ModelConfig.jsx new file mode 100644 index 0000000..64feb3f --- /dev/null +++ b/src/planner/web/js/components/ModelConfig.jsx @@ -0,0 +1,152 @@ +import { useState, useEffect } from 'preact/hooks' +import { useStore } from '../store.js' + +const TIERS = [ + { + key: 'strong', + label: 'Strong', + description: 'Complex reasoning \u2014 intake analysis, task decomposition, orchestration, and planning. Requires deep understanding of requirements and codebase architecture.', + }, + { + key: 'standard', + label: 'Standard', + description: 'Implementation \u2014 executing planned changes based on well-specified work. Balances capability with cost for coding tasks.', + }, + { + key: 'cheap', + label: 'Cheap', + description: 'Narrow investigations \u2014 codebase scouting and targeted information gathering. Fast and cost-effective for focused questions.', + }, +] + +function groupByProvider(models) { + const groups = {} + for (const m of models) { + if (!groups[m.provider]) groups[m.provider] = [] + groups[m.provider].push(m) + } + // Sort providers alphabetically, models by name within each group + return Object.keys(groups).sort().map(provider => ({ + provider, + models: groups[provider].sort((a, b) => a.name.localeCompare(b.name)), + })) +} + +export function ModelConfig({ token, isGate = false, onClose }) { + const pending = useStore(s => s.pendingInput) + const availableModels = useStore(s => s.availableModels) + const [tiers, setTiers] = useState({ strong: '', standard: '', cheap: '' }) + const [loading, setLoading] = useState(true) + const [saving, setSaving] = useState(false) + + // Load current config on mount + useEffect(() => { + if (isGate && pending?.payload) { + const t = pending.payload + setTiers({ + strong: t?.strong || '', + standard: t?.standard || '', + cheap: t?.cheap || '', + }) + setLoading(false) + return + } + fetch(`/api/model-config?session=${encodeURIComponent(token)}`) + .then(r => r.json()) + .then(data => { + if (data.tiers) { + setTiers({ + strong: data.tiers.strong || '', + standard: data.tiers.standard || '', + cheap: data.tiers.cheap || '', + }) + } + setLoading(false) + }) + .catch(() => setLoading(false)) + }, []) + + const handleSave = async () => { + setSaving(true) + const body = { + tiers: { + strong: tiers.strong || null, + standard: tiers.standard || null, + cheap: tiers.cheap || null, + }, + } + if (isGate && pending?.requestId) { + body.requestId = pending.requestId + } + try { + await fetch(`/api/model-config?session=${encodeURIComponent(token)}`, { + method: 'PUT', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(body), + }) + if (!isGate && onClose) onClose() + } finally { + setSaving(false) + } + } + + const grouped = groupByProvider(availableModels) + + if (loading) { + return ( +
+ + ) + } + + return ( +
+

Model Configuration

+

+ Choose which models to use for each task type. Leave as “Inherited” to use the active model. +

+ +
+ {TIERS.map(tier => ( +
+
+ {tier.label} +
+

{tier.description}

+ +
+ ))} +
+ +
+ {!isGate && ( + + )} + + {isGate && !tiers.strong && !tiers.standard && !tiers.cheap && ( + All models will be inherited from the active model + )} +
+
+ ) +} diff --git a/src/planner/web/js/components/Notifications.jsx b/src/planner/web/js/components/Notifications.jsx new file mode 100644 index 0000000..09ab09d --- /dev/null +++ b/src/planner/web/js/components/Notifications.jsx @@ -0,0 +1,25 @@ +import { useEffect } from 'preact/hooks' +import { useStore } from '../store.js' + +export function Notifications() { + const notifications = useStore(s => s.notifications) + + useEffect(() => { + if (notifications.length === 0) return + const newest = notifications[notifications.length - 1] + const timer = setTimeout(() => { + useStore.setState(s => ({ + notifications: s.notifications.filter(n => n.id !== newest.id), + })) + }, 5000) + return () => clearTimeout(timer) + }, [notifications[notifications.length - 1]?.id]) + + return ( +
+ {notifications.map(n => ( +
{n.message}
+ ))} +
+ ) +} diff --git a/src/planner/web/js/components/PhaseContent.jsx b/src/planner/web/js/components/PhaseContent.jsx new file mode 100644 index 0000000..d552837 --- /dev/null +++ b/src/planner/web/js/components/PhaseContent.jsx @@ -0,0 +1,32 @@ +import { useStore } from '../store.js' +import { Loading } from './phases/Loading.jsx' +import { Completion } from './phases/Completion.jsx' +import { QuestionForm } from './forms/QuestionForm.jsx' +import { ReviewForm } from './forms/ReviewForm.jsx' +import { ModelConfig } from './ModelConfig.jsx' + +export function PhaseContent({ token, topic }) { + const phase = useStore(s => s.phase) + const pending = useStore(s => s.pendingInput) + + // Settings overlay + const showSettings = useStore(s => s.showSettings) + if (showSettings) { + return useStore.setState({ showSettings: false })} /> + } + + // Model config gate (startup) + if (pending?.type === 'model-config') { + return + } + + if (!phase) return + + if (pending?.type === 'ask') return + if (pending?.type === 'review') return + + if (phase === 'completed') return + + // For running phases, App renders ActivityFeed directly — this shouldn't be reached + return null +} diff --git a/src/planner/web/js/components/PillStrip.jsx b/src/planner/web/js/components/PillStrip.jsx new file mode 100644 index 0000000..079a38a --- /dev/null +++ b/src/planner/web/js/components/PillStrip.jsx @@ -0,0 +1,29 @@ +import { useStore } from '../store.js' + +const PHASES = [ + { id: 'intake', label: 'intake' }, + { id: 'decomposition', label: 'decompose' }, + { id: 'review', label: 'review' }, + { id: 'executing', label: 'execute' }, +] + +const PHASE_ORDER = ['intake', 'decomposition', 'review', 'executing', 'completed'] + +export function PillStrip() { + const phase = useStore(s => s.phase) + if (!phase) return null + + const phaseIdx = PHASE_ORDER.indexOf(phase) + + return ( +
+ {PHASES.map(({ id, label }) => { + const pillIdx = PHASE_ORDER.indexOf(id) + const cls = phase === 'completed' || phaseIdx > pillIdx ? 'pill done' + : phase === id ? 'pill active' + : 'pill pending' + return {label} + })} +
+ ) +} diff --git a/src/planner/web/js/components/ProgressBar.jsx b/src/planner/web/js/components/ProgressBar.jsx new file mode 100644 index 0000000..a5f6ab3 --- /dev/null +++ b/src/planner/web/js/components/ProgressBar.jsx @@ -0,0 +1,15 @@ +import { useStore } from '../store.js' + +const PHASE_ORDER = ['intake', 'decomposition', 'review', 'executing', 'completed'] + +export function ProgressBar() { + const phase = useStore(s => s.phase) + const idx = PHASE_ORDER.indexOf(phase || '') + const pct = idx < 0 ? 0 : (idx / (PHASE_ORDER.length - 1)) * 100 + + return ( +
+
+
+ ) +} diff --git a/src/planner/web/js/components/SubagentMeta.jsx b/src/planner/web/js/components/SubagentMeta.jsx new file mode 100644 index 0000000..ad3e117 --- /dev/null +++ b/src/planner/web/js/components/SubagentMeta.jsx @@ -0,0 +1,20 @@ +import { useStore } from '../store.js' +import { shortenModel, formatTokens } from '../lib/utils.js' + +export function SubagentMeta() { + const sub = useStore(s => s.subagent) + if (!sub) return null + + const stepLabel = sub.stepName || (sub.step && sub.totalSteps ? `Step ${sub.step}/${sub.totalSteps}` : null) + + return ( +
+ {sub.role} + {sub.model && {shortenModel(sub.model)}} + {stepLabel && {stepLabel}} + {(sub.tokensSent > 0 || sub.tokensReceived > 0) && ( + ↑{formatTokens(sub.tokensSent || 0)} ↓{formatTokens(sub.tokensReceived || 0)} + )} +
+ ) +} diff --git a/src/planner/web/js/components/Timer.jsx b/src/planner/web/js/components/Timer.jsx new file mode 100644 index 0000000..694d754 --- /dev/null +++ b/src/planner/web/js/components/Timer.jsx @@ -0,0 +1,17 @@ +import { useState, useEffect } from 'preact/hooks' +import { useStore } from '../store.js' +import { formatElapsed } from '../lib/utils.js' + +export function Timer() { + const startedAt = useStore(s => s.subagent?.startedAt) + const [now, setNow] = useState(Date.now()) + + useEffect(() => { + if (!startedAt) return + const id = setInterval(() => setNow(Date.now()), 1000) + return () => clearInterval(id) + }, [startedAt]) + + if (!startedAt) return — + return {formatElapsed(now - startedAt)} +} diff --git a/src/planner/web/js/components/forms/QuestionCard.jsx b/src/planner/web/js/components/forms/QuestionCard.jsx new file mode 100644 index 0000000..97a92af --- /dev/null +++ b/src/planner/web/js/components/forms/QuestionCard.jsx @@ -0,0 +1,84 @@ +import { useState } from 'preact/hooks' + +export function QuestionCard({ question, index, total, onSelect }) { + const [selectedIndexes, setSelectedIndexes] = useState(() => new Set()) + const [otherInput, setOtherInput] = useState('') + + const options = question.options || [] + const allOptions = options.map(o => o.label) + const otherIndex = allOptions.findIndex(l => l === 'Other (type your own)') + + function buildSelection(indexes, otherVal) { + if (question.multi) { + const selectedOptions = [] + let customInput + for (const idx of indexes) { + if (idx === otherIndex) { + const val = otherVal.trim() + if (val) customInput = val + } else { + selectedOptions.push(allOptions[idx]) + } + } + return customInput !== undefined ? { selectedOptions, customInput } : { selectedOptions } + } else { + const idx = [...indexes][0] + if (idx === otherIndex) { + const val = otherVal.trim() + return val ? { selectedOptions: [], customInput: val } : null + } + return { selectedOptions: [allOptions[idx]] } + } + } + + function handleSelect(i) { + let next + if (question.multi) { + next = new Set(selectedIndexes) + if (next.has(i)) next.delete(i) + else next.add(i) + } else { + next = new Set([i]) + } + setSelectedIndexes(next) + onSelect(buildSelection(next, otherInput)) + } + + function handleOtherInput(e) { + const val = e.target.value + setOtherInput(val) + if (selectedIndexes.has(otherIndex)) { + onSelect(buildSelection(selectedIndexes, val)) + } + } + + const showOtherInput = otherIndex !== -1 && selectedIndexes.has(otherIndex) + + return ( +
+
{index + 1}/{total} · {question.id}
+ {question.multi &&
select all that apply
} +
{question.question}
+
+ {allOptions.map((label, i) => { + const isSelected = selectedIndexes.has(i) + const isRecommended = i === question.recommended && i !== otherIndex + return ( +
handleSelect(i)}> + + {label} + {isRecommended && recommended} +
+ ) + })} + +
+
+ ) +} diff --git a/src/planner/web/js/components/forms/QuestionForm.jsx b/src/planner/web/js/components/forms/QuestionForm.jsx new file mode 100644 index 0000000..b019463 --- /dev/null +++ b/src/planner/web/js/components/forms/QuestionForm.jsx @@ -0,0 +1,60 @@ +import { useState } from 'preact/hooks' +import { useStore } from '../../store.js' +import { submitAnswers } from '../../lib/api.js' +import { QuestionCard } from './QuestionCard.jsx' + +export function QuestionForm({ token }) { + const { requestId, payload: questions } = useStore(s => s.pendingInput) + const [selections, setSelections] = useState(() => new Array(questions.length).fill(null)) + + const allAnswered = selections.every(s => s !== null && (s.selectedOptions?.length > 0 || s.customInput)) + const answeredCount = selections.filter(s => s !== null && (s.selectedOptions?.length > 0 || s.customInput)).length + + function updateSelection(index, selection) { + setSelections(prev => { + const next = [...prev] + next[index] = selection + return next + }) + } + + function acceptDefaults() { + const answers = questions.map((q) => { + const idx = q.recommended ?? 0 + const label = q.options[idx]?.label + return { questionId: q.id, selectedOptions: label ? [label] : [] } + }) + submitAnswers({ token, requestId, answers }) + } + + function submit() { + const answers = questions.map((q, i) => ({ + questionId: q.id, + ...(selections[i] || { selectedOptions: [] }), + })) + submitAnswers({ token, requestId, answers }) + } + + return ( +
+

A few questions to shape the plan

+
{answeredCount} of {questions.length} answered
+ + {questions.map((q, i) => ( + updateSelection(i, sel)} + /> + ))} + +
+ + + {!allAnswered && {questions.length - answeredCount} remaining} +
+
+ ) +} diff --git a/src/planner/web/js/components/forms/ReviewForm.jsx b/src/planner/web/js/components/forms/ReviewForm.jsx new file mode 100644 index 0000000..ee878e3 --- /dev/null +++ b/src/planner/web/js/components/forms/ReviewForm.jsx @@ -0,0 +1,51 @@ +import { useState } from 'preact/hooks' +import { useStore } from '../../store.js' +import { submitReview } from '../../lib/api.js' + +export function ReviewForm({ token }) { + const { requestId, payload: stories } = useStore(s => s.pendingInput) + const [approved, setApproved] = useState(() => new Set(stories.map(s => s.storyId))) + + function toggle(storyId) { + setApproved(prev => { + const next = new Set(prev) + if (next.has(storyId)) next.delete(storyId) + else next.add(storyId) + return next + }) + } + + function approveAll() { + setApproved(new Set(stories.map(s => s.storyId))) + } + + function submit() { + const approvedList = stories.filter(s => approved.has(s.storyId)).map(s => s.storyId) + const skippedList = stories.filter(s => !approved.has(s.storyId)).map(s => s.storyId) + submitReview({ token, requestId, approved: approvedList, skipped: skippedList }) + } + + return ( +
+

Review story sketches

+

Review stories before execution begins.

+ + {stories.map(story => ( +
toggle(story.storyId)} + > +
+ {story.storyId} + — {story.title} +
+ ))} + +
+ + +
+
+ ) +} diff --git a/src/planner/web/js/components/phases/Completion.jsx b/src/planner/web/js/components/phases/Completion.jsx new file mode 100644 index 0000000..f016bf9 --- /dev/null +++ b/src/planner/web/js/components/phases/Completion.jsx @@ -0,0 +1,23 @@ +import { useStore } from '../../store.js' + +export function Completion() { + const pipelineEnd = useStore(s => s.pipelineEnd) + + return ( +
+

+ {pipelineEnd?.success ? 'Pipeline complete ✓' : 'Pipeline failed'} +

+ {pipelineEnd?.summary && ( +
+
+ + {pipelineEnd.success ? '✓' : '✗'} + + {pipelineEnd.summary} +
+
+ )} +
+ ) +} diff --git a/src/planner/web/js/components/phases/Consolidation.jsx b/src/planner/web/js/components/phases/Consolidation.jsx new file mode 100644 index 0000000..5af7e54 --- /dev/null +++ b/src/planner/web/js/components/phases/Consolidation.jsx @@ -0,0 +1,39 @@ +import { useStore } from '../../store.js' + +export function Consolidation() { + const logs = useStore(s => s.logs) + const scouts = useStore(s => s.scouts) + const scoutCount = scouts.length + + return ( +
+

Writing project specification...

+
+
+ ✓ + Context extracted from conversation +
+ {scoutCount > 0 && ( +
+ ✓ + {scoutCount} scout{scoutCount !== 1 ? 's' : ''} explored the codebase +
+ )} +
+ ◌ + Writing decisions.md... +
+
+ {logs.length > 0 && ( +
+ {logs.slice(-3).map((line, i) => ( +
+ {line.tool} + {line.summary || ''} +
+ ))} +
+ )} +
+ ) +} diff --git a/src/planner/web/js/components/phases/ContextAnalysis.jsx b/src/planner/web/js/components/phases/ContextAnalysis.jsx new file mode 100644 index 0000000..3962b03 --- /dev/null +++ b/src/planner/web/js/components/phases/ContextAnalysis.jsx @@ -0,0 +1,21 @@ +import { useStore } from '../../store.js' + +export function ContextAnalysis() { + const logs = useStore(s => s.logs) + + return ( +
+

Reading your conversation to understand the task...

+ {logs.length > 0 && ( +
+ {logs.slice(-4).map((line, i) => ( +
+ {line.tool} + {line.summary || ''} +
+ ))} +
+ )} +
+ ) +} diff --git a/src/planner/web/js/components/phases/Execution.jsx b/src/planner/web/js/components/phases/Execution.jsx new file mode 100644 index 0000000..5efa4bf --- /dev/null +++ b/src/planner/web/js/components/phases/Execution.jsx @@ -0,0 +1,34 @@ +import { useStore } from '../../store.js' + +export function Execution({ phase }) { + const stories = useStore(s => s.stories) + + const phaseLabel = phase === 'decomposition' ? 'Decomposing into stories...' + : phase === 'review' ? 'Awaiting spec review...' + : phase === 'executing' ? 'Executing stories...' + : `Phase: ${phase}` + + return ( +
+

{phaseLabel}

+ {stories.length > 0 && ( +
+ {stories.map(story => { + const icon = story.status === 'done' ? '✓' + : story.status === 'skipped' ? '—' + : (story.status === 'executing' || story.status === 'planning' || story.status === 'verifying') ? '●' + : '◌' + const iconCls = story.status === 'done' ? 'icon-done' : 'icon-pending' + return ( +
+ {icon} + {story.storyId} + [{story.status}] +
+ ) + })} +
+ )} +
+ ) +} diff --git a/src/planner/web/js/components/phases/Loading.jsx b/src/planner/web/js/components/phases/Loading.jsx new file mode 100644 index 0000000..6dbc4ad --- /dev/null +++ b/src/planner/web/js/components/phases/Loading.jsx @@ -0,0 +1,14 @@ +export function Loading({ topic }) { + return ( +
+ + ) +} diff --git a/src/planner/web/js/components/phases/ScoutExploration.jsx b/src/planner/web/js/components/phases/ScoutExploration.jsx new file mode 100644 index 0000000..7a287a1 --- /dev/null +++ b/src/planner/web/js/components/phases/ScoutExploration.jsx @@ -0,0 +1,60 @@ +import { useStore } from '../../store.js' + +const COLORS = ['var(--blue)', 'var(--purple)', 'var(--orange)', 'var(--yellow)', 'var(--pink)'] + +export function ScoutExploration() { + const scouts = useStore(s => s.scouts) + + return ( +
+

+ Exploring your codebase with {scouts.length} scout{scouts.length !== 1 ? 's' : ''}… +

+ {scouts.map((scout, i) => ( + + ))} + +
+ ) +} + +function ScoutCard({ scout, color }) { + const cls = scout.status === 'completed' ? 'card card-done' + : scout.status === 'failed' ? 'card card-failed' + : 'card card-running' + const symbol = scout.status === 'completed' ? '✓' : scout.status === 'failed' ? '✗' : '●' + + return ( +
+
+ {symbol} + {scout.id} + {scout.role} +
+
+ {scout.status === 'completed' ? scout.completionSummary + : scout.status === 'failed' ? Scout failed + : {scout.lastAction || 'Starting…'}} +
+
+ ) +} + +function CompletedContext({ scouts }) { + const completed = scouts.filter(s => s.status === 'completed' && s.completionSummary) + if (completed.length === 0) return null + + return ( + <> +
CONTEXT SO FAR
+
    + {completed.map(s => ( +
  • + {s.id}: {s.completionSummary?.slice(0, 100)} + {(s.completionSummary?.length ?? 0) > 100 ? '…' : ''} +
    • + ))} +
+ + ) +} diff --git a/src/planner/web/js/lib/api.js b/src/planner/web/js/lib/api.js new file mode 100644 index 0000000..1f98da0 --- /dev/null +++ b/src/planner/web/js/lib/api.js @@ -0,0 +1,27 @@ +import { useStore } from '../store.js' + +export async function submitAnswers({ token, requestId, answers }) { + const resp = await fetch('/api/answer', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ token, requestId, answers }), + }) + if (resp.ok) { + useStore.setState({ pendingInput: null }) + } else { + console.error('Failed to submit answers:', await resp.text()) + } +} + +export async function submitReview({ token, requestId, approved, skipped }) { + const resp = await fetch('/api/review', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ token, requestId, approved, skipped }), + }) + if (resp.ok) { + useStore.setState({ pendingInput: null }) + } else { + console.error('Failed to submit review:', await resp.text()) + } +} diff --git a/src/planner/web/js/lib/utils.js b/src/planner/web/js/lib/utils.js new file mode 100644 index 0000000..2a55efe --- /dev/null +++ b/src/planner/web/js/lib/utils.js @@ -0,0 +1,21 @@ +export function formatTokens(n) { + if (n === 0) return '—'; + if (n < 1000) return String(n); + const k = n / 1000; + if (k >= 10) return `${Math.round(k)}k`; + return `${k.toFixed(1)}k`; +} + +export function formatElapsed(ms) { + const totalSeconds = Math.floor(ms / 1000); + const minutes = Math.floor(totalSeconds / 60); + const seconds = totalSeconds % 60; + return `${minutes}m ${String(seconds).padStart(2, '0')}s`; +} + +export function shortenModel(model) { + if (!model) return '—'; + const parts = model.split('/'); + const name = parts[parts.length - 1] ?? model; + return name.replace(/^claude-/, ''); +} diff --git a/src/planner/web/js/sse.js b/src/planner/web/js/sse.js new file mode 100644 index 0000000..20b5ae6 --- /dev/null +++ b/src/planner/web/js/sse.js @@ -0,0 +1,48 @@ +import { useStore } from './store.js' + +export function connectSSE(token) { + const es = new EventSource(`/events?session=${encodeURIComponent(token)}`) + const set = useStore.setState + + const handlers = { + 'init': (d) => set({ availableModels: d.availableModels || [] }), + phase: (d) => set({ phase: d.phase, ...(d.phase !== 'intake' && { pendingInput: null }) }), + 'intake-progress': () => {}, // data model preserved server-side; UI unused for now + stories: (d) => set({ stories: d.stories }), + scouts: (d) => set({ scouts: d.scouts }), + agents: (d) => set({ agents: d.agents }), + logs: (d) => set({ logs: d.lines, currentToolCallId: d.currentToolCallId ?? null }), + subagent: (d) => set({ subagent: d }), + 'subagent-idle': () => set({ subagent: null }), + 'pipeline-end': (d) => set(s => ({ phase: d.success ? 'completed' : s.phase, pipelineEnd: d })), + ask: (d) => set({ pendingInput: { type: 'ask', requestId: d.requestId, payload: d.questions } }), + review: (d) => set({ pendingInput: { type: 'review', requestId: d.requestId, payload: d.stories } }), + 'model-config': (d) => set(s => ({ + pendingInput: { type: 'model-config', requestId: d.requestId, payload: d.tiers }, + ...(d.availableModels ? { availableModels: d.availableModels } : {}), + })), + 'model-config-confirmed': () => set(s => s.pendingInput?.type === 'model-config' ? { pendingInput: null } : {}), + 'ask-cancelled': (d) => set(s => s.pendingInput?.requestId === d.requestId + ? { pendingInput: null, notifications: [...s.notifications, { id: Date.now(), message: 'The question was cancelled — the subagent has exited.', level: 'warning' }] } + : {}), + 'review-cancelled': (d) => set(s => s.pendingInput?.requestId === d.requestId + ? { pendingInput: null, notifications: [...s.notifications, { id: Date.now(), message: 'The review was cancelled.', level: 'warning' }] } + : {}), + notification: (d) => set(s => ({ + notifications: [...s.notifications, { id: Date.now(), message: d.message, level: d.level }], + })), + } + + for (const [event, handler] of Object.entries(handlers)) { + es.addEventListener(event, (e) => { + try { handler(JSON.parse(e.data)) } + catch (err) { console.error(`[koan] SSE "${event}":`, err) } + }) + } + + es.onerror = () => set(s => ({ + notifications: [...s.notifications, { id: Date.now(), message: 'Connection lost — reconnecting…', level: 'warning' }], + })) + + return es +} diff --git a/src/planner/web/js/store.js b/src/planner/web/js/store.js new file mode 100644 index 0000000..99c7b0a --- /dev/null +++ b/src/planner/web/js/store.js @@ -0,0 +1,19 @@ +import { create } from 'zustand' + +export const useStore = create((set) => ({ + // Server-pushed state + phase: null, + stories: [], + scouts: [], + agents: [], + logs: [], // Array<{ tool, summary, highValue, inFlight }> + currentToolCallId: null, // string | null — in-flight tool for the main agent + subagent: null, + pendingInput: null, + + // Client-only state + notifications: [], + pipelineEnd: null, + showSettings: false, + availableModels: [], +})) diff --git a/src/planner/web/server-types.ts b/src/planner/web/server-types.ts new file mode 100644 index 0000000..6cc8edc --- /dev/null +++ b/src/planner/web/server-types.ts @@ -0,0 +1,249 @@ +// Shared types for the koan web UI: WebServerHandle interface, SSE event +// types, result types, and ask model types relocated from ask-logic.ts. + +import type { LogLine } from "../lib/audit.js"; +import type { EpicPhase, StoryStatus } from "../types.js"; + +export type { LogLine, EpicPhase, StoryStatus }; + +// --------------------------------------------------------------------------- +// Ask model types (relocated from ui/ask/ask-logic.ts) +// --------------------------------------------------------------------------- + +export const OTHER_OPTION = "Other (type your own)"; +const RECOMMENDED_OPTION_TAG = " (Recommended)"; + +export interface AskOption { + label: string; +} + +export interface AskQuestion { + id: string; + question: string; + options: AskOption[]; + multi?: boolean; + recommended?: number; +} + +export interface AskSelection { + selectedOptions: string[]; + customInput?: string; +} + +export function appendRecommendedTagToOptionLabels( + optionLabels: string[], + recommendedOptionIndex?: number, +): string[] { + if ( + recommendedOptionIndex == null || + recommendedOptionIndex < 0 || + recommendedOptionIndex >= optionLabels.length + ) { + return optionLabels; + } + return optionLabels.map((label, idx) => { + if (idx !== recommendedOptionIndex) return label; + if (label.endsWith(RECOMMENDED_OPTION_TAG)) return label; + return `${label}${RECOMMENDED_OPTION_TAG}`; + }); +} + +function removeRecommendedTag(label: string): string { + if (!label.endsWith(RECOMMENDED_OPTION_TAG)) return label; + return label.slice(0, -RECOMMENDED_OPTION_TAG.length); +} + +export function buildSingleSelectionResult(selectedOptionLabel: string, note?: string): AskSelection { + const normalized = removeRecommendedTag(selectedOptionLabel); + const trimmedNote = note?.trim(); + if (normalized === OTHER_OPTION) { + return trimmedNote ? { selectedOptions: [], customInput: trimmedNote } : { selectedOptions: [] }; + } + if (trimmedNote) { + return { selectedOptions: [`${normalized} - ${trimmedNote}`] }; + } + return { selectedOptions: [normalized] }; +} + +export function buildMultiSelectionResult( + optionLabels: string[], + selectedOptionIndexes: number[], + optionNotes: string[], + otherOptionIndex: number, +): AskSelection { + const selected = new Set(selectedOptionIndexes); + const selectedOptions: string[] = []; + let customInput: string | undefined; + + for (let i = 0; i < optionLabels.length; i++) { + if (!selected.has(i)) continue; + const label = removeRecommendedTag(optionLabels[i]); + const note = optionNotes[i]?.trim(); + if (i === otherOptionIndex) { + if (note) customInput = note; + continue; + } + selectedOptions.push(note ? `${label} - ${note}` : label); + } + + return customInput ? { selectedOptions, customInput } : { selectedOptions }; +} + +// --------------------------------------------------------------------------- +// Result types +// --------------------------------------------------------------------------- + +export interface ReviewStory { + storyId: string; + title: string; +} + +export interface ReviewResult { + approved: string[]; + skipped: string[]; +} + +export type AnswerElement = AskSelection & { questionId: string }; + +export interface AnswerResult { + cancelled: boolean; + answers: AnswerElement[]; +} + +// --------------------------------------------------------------------------- +// SSE event payload types (server → browser) +// --------------------------------------------------------------------------- + +export interface AvailableModel { + id: string; + name: string; + provider: string; +} + +export interface InitEvent { + availableModels: AvailableModel[]; +} + +export interface PhaseEvent { + phase: EpicPhase; +} + +export interface StoriesEvent { + stories: Array<{ storyId: string; status: StoryStatus }>; +} + +export interface SubagentEvent { + role: string; + storyId?: string; + step: number; + totalSteps: number; + stepName: string; + startedAt: number; +} + +export interface SubagentIdleEvent {} + +export interface LogsEvent { + lines: LogLine[]; +} + +export interface NotificationEvent { + message: string; + level: "info" | "warning" | "error"; +} + +export interface AskEvent { + requestId: string; + questions: AskQuestion[]; +} + +export interface ReviewEvent { + requestId: string; + stories: ReviewStory[]; +} + +export interface AskCancelledEvent { + requestId: string; +} + +export interface PipelineEndEvent { + success: boolean; + summary: string; +} + +export interface ScoutState { + id: string; + role: string; + status: "running" | "completed" | "failed"; + lastAction: string | null; + eventCount: number; + model: string | null; + completionSummary: string | null; + tokensSent: number; + tokensReceived: number; +} + +export interface ScoutsEvent { + scouts: ScoutState[]; +} + +export interface AgentEntry { + id: string; + name: string; + role: string; + model: string | null; + parent: string | null; + status: "running" | "completed" | "failed"; + tokensSent: number; + tokensReceived: number; + recentActions: Array<{ tool: string; summary: string; inFlight: boolean }>; + subPhase: string | null; +} + +export interface AgentsEvent { + agents: AgentEntry[]; +} + +export interface ModelConfigEvent { + requestId: string; + tiers: Record | null; + availableModels: AvailableModel[]; +} + +// --------------------------------------------------------------------------- +// WebServerHandle interface +// --------------------------------------------------------------------------- + +export interface WebServerHandle { + readonly url: string; + readonly port: number; + + // Push methods (fire-and-forget, SSE) + pushPhase(phase: EpicPhase): void; + pushStories(stories: Array<{ storyId: string; status: StoryStatus }>): void; + pushLogs(lines: LogLine[], currentToolCallId?: string | null): void; + pushNotification(message: string, level: "info" | "warning" | "error"): void; + + // Observation polling (replaces startActivePolling) + trackSubagent(dir: string, role: string, storyId?: string): void; + clearSubagent(): void; + + // Agent registration for the flat table + registerAgent(info: { + id: string; + name: string; + dir: string; + role: string; + model: string | null; + parent: string | null; + }): void; + completeAgent(id: string): void; + + // Blocking input methods + requestReview(stories: ReviewStory[], signal?: AbortSignal): Promise; + requestAnswer(questions: AskQuestion[], signal: AbortSignal): Promise; + requestModelConfig(): Promise; + + // Lifecycle + close(): void; +} diff --git a/src/planner/web/server.ts b/src/planner/web/server.ts new file mode 100644 index 0000000..5424178 --- /dev/null +++ b/src/planner/web/server.ts @@ -0,0 +1,815 @@ +// Koan web UI HTTP server. +// Serves the single-page dashboard, pushes state via SSE, and receives +// user input via POST endpoints. One server per pipeline run; lifecycle +// owned by koan_plan.execute(). + +import http from "node:http"; +import { promises as fs, readFileSync } from "node:fs"; +import * as path from "node:path"; +import { fileURLToPath } from "node:url"; +import { randomUUID } from "node:crypto"; + +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; +import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent"; + +import { readProjection, readRecentLogs } from "../lib/audit.js"; +import { loadModelTierConfig, saveModelTierConfig, type ModelTierConfig } from "../model-config.js"; +import type { + WebServerHandle, + AskQuestion, + ReviewStory, + ReviewResult, + AnswerResult, + AnswerElement, + LogLine, +} from "./server-types.js"; +import type { EpicPhase, StoryStatus } from "../types.js"; + +// --------------------------------------------------------------------------- +// Static asset loading (at module init) +// --------------------------------------------------------------------------- + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); + +function loadAsset(relativePath: string): string { + try { + return readFileSync(path.join(__dirname, relativePath), "utf8"); + } catch { + return ""; + } +} + +const HTML_TEMPLATE = loadAsset("html/index.html"); + +interface StaticAsset { + content: string; + mimeType: string; +} + +// --------------------------------------------------------------------------- +// On-demand bundle build +// --------------------------------------------------------------------------- + +async function ensureBundle(): Promise { + const entryPoint = path.join(__dirname, "js", "app.jsx"); + const outfile = path.join(__dirname, "dist", "app.js"); + + // Skip build if bundle exists and is newer than all source files + try { + const bundleStat = await fs.stat(outfile); + const sourceDir = path.join(__dirname, "js"); + const sourceFiles = await fs.readdir(sourceDir, { recursive: true }); + let newest = 0; + for (const f of sourceFiles) { + const s = await fs.stat(path.join(sourceDir, String(f))); + if (s.mtimeMs > newest) newest = s.mtimeMs; + } + if (bundleStat.mtimeMs >= newest) return; // bundle is fresh + } catch { + // Bundle doesn't exist — build it + } + + await fs.mkdir(path.join(__dirname, "dist"), { recursive: true }); + const esbuild = await import("esbuild"); + await esbuild.build({ + entryPoints: [entryPoint], + bundle: true, + format: "esm", + jsx: "automatic", + jsxImportSource: "preact", + alias: { + "react": "preact/compat", + "react-dom": "preact/compat", + }, + // Resolve aliases and node_modules from the koan package root, not + // process.cwd(). Without this, running `pi -e .../koan/extensions/koan.ts` + // from a different project directory fails because preact/compat is looked + // up in that project's node_modules instead of koan's. + absWorkingDir: path.resolve(__dirname, "../../.."), + outfile, + minify: true, + }); +} + +// --------------------------------------------------------------------------- +// Body parsing +// --------------------------------------------------------------------------- + +const MAX_BODY_SIZE = 1_000_000; + +function readBody(req: http.IncomingMessage): Promise { + return new Promise((resolve, reject) => { + const chunks: Buffer[] = []; + let total = 0; + req.on("data", (chunk: Buffer) => { + total += chunk.length; + if (total > MAX_BODY_SIZE) { + reject(new Error("Body too large")); + return; + } + chunks.push(chunk); + }); + req.on("end", () => { + try { + resolve(JSON.parse(Buffer.concat(chunks).toString("utf8"))); + } catch { + reject(new Error("Invalid JSON body")); + } + }); + req.on("error", reject); + }); +} + +function sendJson(res: http.ServerResponse, status: number, data: unknown): void { + const body = JSON.stringify(data); + res.writeHead(status, { + "Content-Type": "application/json; charset=utf-8", + "Content-Length": Buffer.byteLength(body), + }); + res.end(body); +} + +function sendText(res: http.ServerResponse, status: number, text: string): void { + res.writeHead(status, { "Content-Type": "text/plain; charset=utf-8" }); + res.end(text); +} + +function safeInlineJSON(data: unknown): string { + return JSON.stringify(data) + .replace(//g, "\\u003e") + .replace(/&/g, "\\u0026"); +} + +// --------------------------------------------------------------------------- +// Topic extraction from conversation.jsonl +// --------------------------------------------------------------------------- + +async function extractTopic(epicDir: string): Promise { + try { + const raw = await fs.readFile(path.join(epicDir, "conversation.jsonl"), "utf8"); + const lines = raw.trimEnd().split("\n").filter(Boolean); + let lastUserContent: string | null = null; + for (const line of lines) { + try { + const entry = JSON.parse(line) as { type?: string; role?: string; content?: unknown }; + if (entry.type === "message" && entry.role === "user") { + const content = entry.content; + if (typeof content === "string" && content.trim()) { + lastUserContent = content.trim().slice(0, 200); + } else if (Array.isArray(content)) { + for (const block of content as Array<{ type?: string; text?: string }>) { + if (block.type === "text" && block.text?.trim()) { + lastUserContent = block.text.trim().slice(0, 200); + break; + } + } + } + } + } catch { + // Skip malformed lines + } + } + return lastUserContent; + } catch { + return null; + } +} + +// --------------------------------------------------------------------------- +// Agent internal state +// --------------------------------------------------------------------------- + +interface AgentInfoInternal { + id: string; + name: string; + dir: string; + role: string; + model: string | null; + parent: string | null; + status: "running" | "completed" | "failed"; + tokensSent: number; + tokensReceived: number; + recentActions: Array<{ tool: string; summary: string; inFlight: boolean }>; + spawnOrder: number; + completionOrder?: number; + pollingTimer?: ReturnType; + // Internal derived fields + subPhase: string | null; + eventCount: number; + completionSummary: string | null; +} + +// --------------------------------------------------------------------------- +// startWebServer +// --------------------------------------------------------------------------- + +export async function startWebServer(epicDir: string): Promise { + await ensureBundle(); + + // Discover available models from pi's registry + const authStorage = new AuthStorage(); + const modelRegistry = new ModelRegistry(authStorage); + const availableModels = modelRegistry.getAll().map((m) => ({ + id: `${m.provider}/${m.id}`, + name: m.name, + provider: m.provider, + })); + + const STATIC_ASSETS: Map = new Map([ + ["/static/css/variables.css", { content: loadAsset("css/variables.css"), mimeType: "text/css; charset=utf-8" }], + ["/static/css/layout.css", { content: loadAsset("css/layout.css"), mimeType: "text/css; charset=utf-8" }], + ["/static/css/components.css", { content: loadAsset("css/components.css"), mimeType: "text/css; charset=utf-8" }], + ["/static/css/animations.css", { content: loadAsset("css/animations.css"), mimeType: "text/css; charset=utf-8" }], + ["/static/js/app.js", { content: loadAsset("dist/app.js"), mimeType: "application/javascript; charset=utf-8" }], + ]); + + const sessionToken = randomUUID(); + + // Buffered state for SSE replay on reconnect + let currentPhase: EpicPhase | null = null; + let currentStories: Array<{ storyId: string; status: StoryStatus }> = []; + let currentSubagent: unknown | null = null; + let lastLogs: LogLine[] = []; + let pipelineEnd: { success: boolean; summary: string } | null = null; + + // Denormalized intake progress buffer + let currentIntakeProgress: { subPhase: string | null; intakeDone: boolean } = { + subPhase: null, + intakeDone: false, + }; + + // SSE clients + const sseClients = new Set(); + + // Pending inputs (requestReview / requestAnswer / requestModelConfig) + interface PendingEntry { + type: "review" | "ask" | "model-config"; + resolve: (result: unknown) => void; + reject: (err: Error) => void; + payload: unknown; + } + const pendingInputs = new Map(); + + // Agent registry + const agents = new Map(); + let spawnCounter = 0; + let completionCounter = 0; + + // Subagent observation polling + let trackingTimer: ReturnType | null = null; + + // --------------------------------------------------------------------------- + // SSE helpers + // --------------------------------------------------------------------------- + + function pushEvent(name: string, payload: unknown): void { + const chunk = `event: ${name}\ndata: ${JSON.stringify(payload)}\n\n`; + for (const client of sseClients) { + try { + client.write(chunk); + } catch { + sseClients.delete(client); + } + } + } + + function replayState(res: http.ServerResponse): void { + const write = (name: string, payload: unknown) => { + try { + res.write(`event: ${name}\ndata: ${JSON.stringify(payload)}\n\n`); + } catch { + // Ignore broken connection + } + }; + + write("init", { availableModels }); + + if (currentPhase) write("phase", { phase: currentPhase }); + if (currentStories.length > 0) write("stories", { stories: currentStories }); + + const agentArray = buildAgentsArray(); + if (agentArray.length > 0) write("agents", { agents: agentArray }); + + const scoutArray = buildScoutsArray(); + if (scoutArray.length > 0) write("scouts", { scouts: scoutArray }); + + if (currentIntakeProgress.subPhase !== null || currentIntakeProgress.intakeDone) { + write("intake-progress", currentIntakeProgress); + } + + if (currentSubagent) write("subagent", currentSubagent); + if (lastLogs.length > 0) write("logs", { lines: lastLogs }); + + for (const [requestId, entry] of pendingInputs) { + if (entry.type === "ask") { + write("ask", { requestId, questions: entry.payload }); + } else if (entry.type === "review") { + write("review", { requestId, stories: entry.payload }); + } else if (entry.type === "model-config") { + write("model-config", entry.payload); + } + } + + if (pipelineEnd !== null) write("pipeline-end", pipelineEnd); + } + + // --------------------------------------------------------------------------- + // Agent array builders + // --------------------------------------------------------------------------- + + function buildAgentsArray(): Array<{ + id: string; name: string; role: string; model: string | null; + parent: string | null; status: string; tokensSent: number; + tokensReceived: number; recentActions: Array<{ tool: string; summary: string; inFlight: boolean }>; subPhase: string | null; + }> { + const sorted = Array.from(agents.values()).sort((a, b) => { + if (a.status === "running" && b.status !== "running") return -1; + if (b.status === "running" && a.status !== "running") return 1; + if (a.status !== "failed" && b.status === "failed") return -1; + if (b.status !== "failed" && a.status === "failed") return 1; + const aOrder = a.status === "running" ? a.spawnOrder : (a.completionOrder ?? a.spawnOrder); + const bOrder = b.status === "running" ? b.spawnOrder : (b.completionOrder ?? b.spawnOrder); + return aOrder - bOrder; + }); + return sorted.map((a) => ({ + id: a.id, + name: a.name, + role: a.role, + model: a.model, + parent: a.parent, + status: a.status, + tokensSent: a.tokensSent, + tokensReceived: a.tokensReceived, + recentActions: a.recentActions, + subPhase: a.subPhase, + })); + } + + function buildScoutsArray(): Array<{ + id: string; role: string; status: string; lastAction: string | null; + eventCount: number; model: string | null; completionSummary: string | null; + tokensSent: number; tokensReceived: number; + }> { + return Array.from(agents.values()) + .filter((a) => a.role === "scout") + .map((a) => ({ + id: a.id, + role: a.name, + status: a.status, + lastAction: a.recentActions.length > 0 ? (() => { const l = a.recentActions[a.recentActions.length - 1]; return l ? (l.summary ? `${l.tool}: ${l.summary}` : l.tool) : null; })() : null, + eventCount: a.eventCount, + model: a.model, + completionSummary: a.completionSummary, + tokensSent: a.tokensSent, + tokensReceived: a.tokensReceived, + })); + } + + // --------------------------------------------------------------------------- + // Agent polling + // --------------------------------------------------------------------------- + + async function pollAgent(agent: AgentInfoInternal): Promise { + try { + const [projection, logs] = await Promise.all([ + readProjection(agent.dir), + readRecentLogs(agent.dir, 5), + ]); + if (projection) { + agent.model = projection.model ?? agent.model; + agent.tokensSent = projection.tokensSent; + agent.tokensReceived = projection.tokensReceived; + agent.eventCount = projection.eventCount; + if (projection.status !== "running") { + agent.status = projection.status; + } + if (agent.role === "intake") { + const hasPendingAsk = Array.from(pendingInputs.values()).some((p) => p.type === "ask"); + const STEP_PHASE: Record = { 0: "context", 1: "context", 2: "explore", 3: "spec" }; + agent.subPhase = hasPendingAsk ? "questions" : (STEP_PHASE[projection.step] ?? "spec"); + } + } + if (logs.length > 0) { + agent.recentActions = logs.slice(-5).map((l) => ({ tool: l.tool, summary: l.summary || '', inFlight: l.inFlight })); + } + if (agent.role === "scout" && projection?.completionSummary && !agent.completionSummary) { + agent.completionSummary = projection.completionSummary; + } + } catch { + // Non-fatal + } + } + + function startAgentPolling(agent: AgentInfoInternal): void { + if (agent.pollingTimer) return; + const timer = setInterval(async () => { + await pollAgent(agent); + pushEvent("agents", { agents: buildAgentsArray() }); + if (agent.role === "scout") { + const scouts = buildScoutsArray(); + if (scouts.length > 0) pushEvent("scouts", { scouts }); + } + // Push intake-progress event if the intake agent's sub-phase changed + const intake = Array.from(agents.values()).find(a => a.role === "intake"); + if (intake) { + const next = { subPhase: intake.subPhase, intakeDone: currentPhase !== "intake" && currentPhase !== null }; + if (next.subPhase !== currentIntakeProgress.subPhase || next.intakeDone !== currentIntakeProgress.intakeDone) { + currentIntakeProgress = next; + pushEvent("intake-progress", currentIntakeProgress); + } + } + }, 500); + timer.unref(); + agent.pollingTimer = timer; + } + + function stopAgentPolling(agent: AgentInfoInternal): void { + if (agent.pollingTimer) { + clearInterval(agent.pollingTimer); + agent.pollingTimer = undefined; + } + } + + // --------------------------------------------------------------------------- + // HTTP server + // --------------------------------------------------------------------------- + + const server = http.createServer(async (req, res) => { + try { + const method = req.method ?? "GET"; + const url = new URL(req.url ?? "/", "http://127.0.0.1"); + const { pathname } = url; + + if (method === "GET" && pathname === "/") { + const token = url.searchParams.get("session"); + if (token !== sessionToken) { sendText(res, 403, "Invalid session token"); return; } + const topic = await extractTopic(epicDir); + const initialData = safeInlineJSON({ token: sessionToken, topic }); + const html = HTML_TEMPLATE.replace("/* __DATA__ */", initialData); + res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" }); + res.end(html); + return; + } + + if (method === "GET" && pathname.startsWith("/static/")) { + const asset = STATIC_ASSETS.get(pathname); + if (!asset) { sendText(res, 404, "Not found"); return; } + res.writeHead(200, { "Content-Type": asset.mimeType, "Cache-Control": "no-store" }); + res.end(asset.content); + return; + } + + if (method === "GET" && pathname === "/events") { + const token = url.searchParams.get("session"); + if (token !== sessionToken) { sendText(res, 403, "Invalid session token"); return; } + res.writeHead(200, { + "Content-Type": "text/event-stream", + "Cache-Control": "no-cache, no-transform", + "Connection": "keep-alive", + "X-Accel-Buffering": "no", + }); + res.write(": connected\n\n"); + sseClients.add(res); + replayState(res); + req.on("close", () => { sseClients.delete(res); }); + return; + } + + if (method === "GET" && pathname === "/health") { + sendJson(res, 200, { ok: true }); + return; + } + + if (method === "GET" && pathname === "/api/model-config") { + const config = await loadModelTierConfig(); + sendJson(res, 200, { tiers: config }); + return; + } + + if (method === "PUT" && pathname === "/api/model-config") { + const body = await readBody(req).catch(() => null); + const b = body as { requestId?: string; tiers: Record } | null; + if (!b) { sendJson(res, 400, { ok: false, error: "Invalid body" }); return; } + const { requestId, tiers } = b; + + // Save config if all 3 tiers are non-null non-empty strings + const strong = tiers?.strong; + const standard = tiers?.standard; + const cheap = tiers?.cheap; + if (strong && standard && cheap) { + await saveModelTierConfig({ strong, standard, cheap } as ModelTierConfig); + } + + // Resolve the blocking gate if requestId matches + if (requestId) { + const entry = pendingInputs.get(requestId); + if (entry && entry.type === "model-config") { + pendingInputs.delete(requestId); + entry.resolve(undefined); + } + } + + // Push confirmation so client clears pendingInput + pushEvent("model-config-confirmed", {}); + + sendJson(res, 200, { ok: true }); + return; + } + + if (method === "POST" && pathname === "/api/heartbeat") { + const body = await readBody(req).catch(() => null); + const b = body as { token?: string } | null; + if (!b || b.token !== sessionToken) { sendJson(res, 403, { ok: false, error: "Invalid token" }); return; } + sendJson(res, 200, { ok: true }); + return; + } + + if (method === "POST" && pathname === "/api/answer") { + const body = await readBody(req).catch(() => null); + const b = body as { token?: string; requestId?: string; answers?: unknown[] } | null; + if (!b) { sendJson(res, 400, { ok: false, error: "Invalid body" }); return; } + if (b.token !== sessionToken) { sendJson(res, 403, { ok: false, error: "Invalid token" }); return; } + const { requestId, answers } = b; + if (!requestId || !Array.isArray(answers)) { + sendJson(res, 400, { ok: false, error: "Missing requestId or answers" }); return; + } + const pending = pendingInputs.get(requestId); + if (!pending || pending.type !== "ask") { + sendJson(res, 409, { ok: false, error: "No pending ask with this requestId" }); return; + } + const result: AnswerResult = { cancelled: false, answers: answers as AnswerElement[] }; + pending.resolve(result); + pendingInputs.delete(requestId); + sendJson(res, 200, { ok: true }); + return; + } + + if (method === "POST" && pathname === "/api/review") { + const body = await readBody(req).catch(() => null); + const b = body as { token?: string; requestId?: string; approved?: string[]; skipped?: string[] } | null; + if (!b) { sendJson(res, 400, { ok: false, error: "Invalid body" }); return; } + if (b.token !== sessionToken) { sendJson(res, 403, { ok: false, error: "Invalid token" }); return; } + const { requestId, approved, skipped } = b; + if (!requestId || !Array.isArray(approved) || !Array.isArray(skipped)) { + sendJson(res, 400, { ok: false, error: "Missing fields" }); return; + } + const pending = pendingInputs.get(requestId); + if (!pending || pending.type !== "review") { + sendJson(res, 409, { ok: false, error: "No pending review with this requestId" }); return; + } + const result: ReviewResult = { approved, skipped }; + pending.resolve(result); + pendingInputs.delete(requestId); + sendJson(res, 200, { ok: true }); + return; + } + + if (method === "POST" && pathname === "/api/cancel") { + const body = await readBody(req).catch(() => null); + const b = body as { token?: string } | null; + if (!b || b.token !== sessionToken) { sendJson(res, 403, { ok: false, error: "Invalid token" }); return; } + pipelineEnd = { success: false, summary: "Cancelled by user" }; + pushEvent("pipeline-end", pipelineEnd); + const err = new Error("Pipeline cancelled by user"); + err.name = "AbortError"; + for (const [, entry] of pendingInputs) entry.reject(err); + pendingInputs.clear(); + sendJson(res, 200, { ok: true }); + return; + } + + sendText(res, 404, "Not found"); + } catch (err) { + const msg = err instanceof Error ? err.message : "Server error"; + sendJson(res, 500, { ok: false, error: msg }); + } + }); + + return new Promise((resolve, reject) => { + server.once("error", (err: Error) => { + reject(new Error(`Failed to start koan web server: ${err.message}`)); + }); + + server.listen(0, "127.0.0.1", () => { + const addr = server.address(); + if (!addr || typeof addr === "string") { + reject(new Error("Failed to start koan web server: invalid address")); + return; + } + const { port } = addr; + const url = `http://127.0.0.1:${port}/?session=${sessionToken}`; + + const handle: WebServerHandle = { + url, + port, + + pushPhase(phase: EpicPhase): void { + currentPhase = phase; + pushEvent("phase", { phase }); + currentIntakeProgress = { ...currentIntakeProgress, intakeDone: phase !== "intake" }; + pushEvent("intake-progress", currentIntakeProgress); + }, + + pushStories(stories: Array<{ storyId: string; status: StoryStatus }>): void { + currentStories = stories; + pushEvent("stories", { stories }); + }, + + pushLogs(lines: LogLine[], currentToolCallId?: string | null): void { + lastLogs = lines; + pushEvent("logs", { lines, currentToolCallId: currentToolCallId ?? null }); + }, + + pushNotification(message: string, level: "info" | "warning" | "error"): void { + pushEvent("notification", { message, level }); + }, + + trackSubagent(dir: string, role: string, storyId?: string): void { + if (trackingTimer) { clearInterval(trackingTimer); trackingTimer = null; } + const startedAt = Date.now(); + const timer = setInterval(async () => { + try { + const [projection, logs] = await Promise.all([readProjection(dir), readRecentLogs(dir, 50)]); + if (logs.length > 0) { + lastLogs = logs; + pushEvent("logs", { lines: logs, currentToolCallId: projection?.currentToolCallId ?? null }); + } + if (projection) { + const event = { + role, storyId, + model: projection.model, + step: projection.step, + totalSteps: projection.totalSteps, + stepName: projection.stepName, + tokensSent: projection.tokensSent, + tokensReceived: projection.tokensReceived, + startedAt, + }; + currentSubagent = event; + pushEvent("subagent", event); + } + } catch { /* Non-fatal */ } + }, 500); + timer.unref(); + trackingTimer = timer; + }, + + clearSubagent(): void { + if (trackingTimer) { clearInterval(trackingTimer); trackingTimer = null; } + currentSubagent = null; + pushEvent("subagent-idle", {}); + }, + + registerAgent(info: { + id: string; name: string; dir: string; role: string; + model: string | null; parent: string | null; + }): void { + const agent: AgentInfoInternal = { + ...info, + status: "running", + tokensSent: 0, + tokensReceived: 0, + recentActions: [], + spawnOrder: spawnCounter++, + subPhase: null, + eventCount: 0, + completionSummary: null, + }; + agents.set(info.id, agent); + startAgentPolling(agent); + pushEvent("agents", { agents: buildAgentsArray() }); + if (info.role === "scout") pushEvent("scouts", { scouts: buildScoutsArray() }); + }, + + completeAgent(id: string): void { + const agent = agents.get(id); + if (!agent) return; + stopAgentPolling(agent); + void readProjection(agent.dir).then((projection) => { + if (projection) { + agent.tokensSent = projection.tokensSent; + agent.tokensReceived = projection.tokensReceived; + agent.status = projection.status !== "running" ? projection.status : "failed"; + } else { + agent.status = "failed"; + } + agent.completionOrder = completionCounter++; + pushEvent("agents", { agents: buildAgentsArray() }); + if (agent.role === "scout") { + agent.completionSummary = projection?.completionSummary ?? null; + pushEvent("scouts", { scouts: buildScoutsArray() }); + } + }); + }, + + requestReview(stories: ReviewStory[], signal?: AbortSignal): Promise { + return new Promise((res, rej) => { + const requestId = randomUUID(); + const abortHandler = () => { + pendingInputs.delete(requestId); + pushEvent("review-cancelled", { requestId }); + const err = new Error(`Review cancelled: signal aborted`); + (err as NodeJS.ErrnoException).name = "AbortError"; + rej(err); + }; + pendingInputs.set(requestId, { + type: "review", + resolve: (result: unknown) => { + signal?.removeEventListener("abort", abortHandler); + res(result as ReviewResult); + }, + reject: (err: Error) => { + signal?.removeEventListener("abort", abortHandler); + rej(err); + }, + payload: stories, + }); + pushEvent("review", { requestId, stories }); + if (signal?.aborted) { + abortHandler(); + } else { + signal?.addEventListener("abort", abortHandler, { once: true }); + } + }); + }, + + requestAnswer(questions: AskQuestion[], signal: AbortSignal): Promise { + return new Promise((res, rej) => { + const requestId = randomUUID(); + const abortHandler = () => { + pendingInputs.delete(requestId); + pushEvent("ask-cancelled", { requestId }); + const err = new Error(`Ask cancelled: signal aborted`); + (err as NodeJS.ErrnoException).name = "AbortError"; + rej(err); + }; + pendingInputs.set(requestId, { + type: "ask", + resolve: (result: unknown) => { + signal.removeEventListener("abort", abortHandler); + res(result as AnswerResult); + }, + reject: (err: Error) => { + signal.removeEventListener("abort", abortHandler); + rej(err); + }, + payload: questions, + }); + pushEvent("ask", { requestId, questions }); + if (signal.aborted) { + abortHandler(); + } else { + signal.addEventListener("abort", abortHandler, { once: true }); + } + }); + }, + + async requestModelConfig(): Promise { + const requestId = randomUUID(); + const config = await loadModelTierConfig(); + const payload = { requestId, tiers: config, availableModels }; + return new Promise((resolve, reject) => { + pendingInputs.set(requestId, { + type: "model-config" as const, + resolve: resolve as (v: unknown) => void, + reject, + payload, + }); + pushEvent("model-config", payload); + }); + }, + + close(): void { + for (const [, entry] of pendingInputs) entry.reject(new Error("Server closed")); + pendingInputs.clear(); + if (trackingTimer) { clearInterval(trackingTimer); trackingTimer = null; } + for (const agent of agents.values()) stopAgentPolling(agent); + for (const client of sseClients) { try { client.end(); } catch { /* Ignore */ } } + sseClients.clear(); + try { server.close(); } catch { /* Ignore */ } + }, + }; + + resolve(handle); + }); + }); +} + +// --------------------------------------------------------------------------- +// Open browser helper (§12.2) +// --------------------------------------------------------------------------- + +export async function openBrowser(pi: ExtensionAPI, url: string): Promise { + try { + if (process.platform === "darwin") { + await pi.exec("open", [url]); + } else if (process.platform === "win32") { + await pi.exec("cmd", ["/c", "start", "", url]); + } else { + await pi.exec("xdg-open", [url]); + } + } catch { + // Non-fatal — URL is always in the tool result + } +} From ea2b391eefe13eb8f8af2d4c9ae2dc3b50aae0c8 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:48:50 +0700 Subject: [PATCH 056/412] remove old TUI UI components replaced by web dashboard --- src/planner/ui/ask/ask-inline-note.ts | 65 ---- src/planner/ui/ask/ask-inline-ui.ts | 221 ----------- src/planner/ui/ask/ask-logic.ts | 98 ----- src/planner/ui/ask/ask-tabs-ui.ts | 512 -------------------------- src/planner/ui/epic-widget.ts | 243 ------------ src/planner/ui/spec-review.ts | 152 -------- 6 files changed, 1291 deletions(-) delete mode 100644 src/planner/ui/ask/ask-inline-note.ts delete mode 100644 src/planner/ui/ask/ask-inline-ui.ts delete mode 100644 src/planner/ui/ask/ask-logic.ts delete mode 100644 src/planner/ui/ask/ask-tabs-ui.ts delete mode 100644 src/planner/ui/epic-widget.ts delete mode 100644 src/planner/ui/spec-review.ts diff --git a/src/planner/ui/ask/ask-inline-note.ts b/src/planner/ui/ask/ask-inline-note.ts deleted file mode 100644 index a22ab8f..0000000 --- a/src/planner/ui/ask/ask-inline-note.ts +++ /dev/null @@ -1,65 +0,0 @@ -import { wrapTextWithAnsi } from "@mariozechner/pi-tui"; - -const INLINE_NOTE_SEPARATOR = " — note: "; -const INLINE_EDIT_CURSOR = "▍"; - -export const INLINE_NOTE_WRAP_PADDING = 2; - -function sanitizeNoteForInlineDisplay(rawNote: string): string { - return rawNote.replace(/[\r\n\t]/g, " ").replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, ""); -} - -function truncateTextKeepingTail(text: string, maxLength: number): string { - if (maxLength <= 0) return ""; - if (text.length <= maxLength) return text; - if (maxLength === 1) return "…"; - return `…${text.slice(-(maxLength - 1))}`; -} - -function truncateTextKeepingHead(text: string, maxLength: number): string { - if (maxLength <= 0) return ""; - if (text.length <= maxLength) return text; - if (maxLength === 1) return "…"; - return `${text.slice(0, maxLength - 1)}…`; -} - -export function buildOptionLabelWithInlineNote( - baseOptionLabel: string, - rawNote: string, - isEditingNote: boolean, - maxInlineLabelLength?: number, -): string { - const sanitizedNote = sanitizeNoteForInlineDisplay(rawNote); - if (!isEditingNote && sanitizedNote.trim().length === 0) { - return baseOptionLabel; - } - - const labelPrefix = `${baseOptionLabel}${INLINE_NOTE_SEPARATOR}`; - const inlineNote = isEditingNote ? `${sanitizedNote}${INLINE_EDIT_CURSOR}` : sanitizedNote.trim(); - const inlineLabel = `${labelPrefix}${inlineNote}`; - - if (maxInlineLabelLength == null) { - return inlineLabel; - } - - return isEditingNote - ? truncateTextKeepingTail(inlineLabel, maxInlineLabelLength) - : truncateTextKeepingHead(inlineLabel, maxInlineLabelLength); -} - -export function buildWrappedOptionLabelWithInlineNote( - baseOptionLabel: string, - rawNote: string, - isEditingNote: boolean, - maxInlineLabelLength: number, - wrapPadding = INLINE_NOTE_WRAP_PADDING, -): string[] { - const inlineLabel = buildOptionLabelWithInlineNote(baseOptionLabel, rawNote, isEditingNote); - const sanitizedWrapPadding = Number.isFinite(wrapPadding) ? Math.max(0, Math.floor(wrapPadding)) : 0; - const sanitizedMaxInlineLabelLength = Number.isFinite(maxInlineLabelLength) - ? Math.max(1, Math.floor(maxInlineLabelLength)) - : 1; - const wrapWidth = Math.max(1, sanitizedMaxInlineLabelLength - sanitizedWrapPadding); - const wrappedLines = wrapTextWithAnsi(inlineLabel, wrapWidth); - return wrappedLines.length > 0 ? wrappedLines : [""]; -} diff --git a/src/planner/ui/ask/ask-inline-ui.ts b/src/planner/ui/ask/ask-inline-ui.ts deleted file mode 100644 index e57ed04..0000000 --- a/src/planner/ui/ask/ask-inline-ui.ts +++ /dev/null @@ -1,221 +0,0 @@ -import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; -import { Editor, type EditorTheme, Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui"; -import { - OTHER_OPTION, - appendRecommendedTagToOptionLabels, - buildSingleSelectionResult, - type AskOption, - type AskSelection, -} from "./ask-logic.js"; -import { INLINE_NOTE_WRAP_PADDING, buildWrappedOptionLabelWithInlineNote } from "./ask-inline-note.js"; - -interface SingleQuestionInput { - question: string; - options: AskOption[]; - recommended?: number; -} - -interface InlineSelectionResult { - cancelled: boolean; - selectedOption?: string; - note?: string; -} - -function resolveInitialCursorIndexFromRecommendedOption( - recommendedOptionIndex: number | undefined, - optionCount: number, -): number { - if (recommendedOptionIndex == null) return 0; - if (recommendedOptionIndex < 0 || recommendedOptionIndex >= optionCount) return 0; - return recommendedOptionIndex; -} - -export async function askSingleQuestionWithInlineNote( - ui: ExtensionUIContext, - questionInput: SingleQuestionInput, -): Promise { - const baseOptionLabels = questionInput.options.map((option) => option.label); - const optionLabelsWithRecommendedTag = appendRecommendedTagToOptionLabels( - baseOptionLabels, - questionInput.recommended, - ); - const selectableOptionLabels = [...optionLabelsWithRecommendedTag, OTHER_OPTION]; - const initialCursorIndex = resolveInitialCursorIndexFromRecommendedOption( - questionInput.recommended, - optionLabelsWithRecommendedTag.length, - ); - - const result = await ui.custom((tui, theme, _keybindings, done) => { - let cursorOptionIndex = initialCursorIndex; - let isNoteEditorOpen = false; - let cachedRenderedLines: string[] | undefined; - const noteByOptionIndex = new Map(); - - const editorTheme: EditorTheme = { - borderColor: (text) => theme.fg("accent", text), - selectList: { - selectedPrefix: (text) => theme.fg("accent", text), - selectedText: (text) => theme.fg("accent", text), - description: (text) => theme.fg("muted", text), - scrollInfo: (text) => theme.fg("dim", text), - noMatch: (text) => theme.fg("warning", text), - }, - }; - const noteEditor = new Editor(tui, editorTheme); - - const requestUiRerender = () => { - cachedRenderedLines = undefined; - tui.requestRender(); - }; - - const getRawNoteForOption = (optionIndex: number): string => noteByOptionIndex.get(optionIndex) ?? ""; - const getTrimmedNoteForOption = (optionIndex: number): string => getRawNoteForOption(optionIndex).trim(); - - const loadCurrentNoteIntoEditor = () => { - noteEditor.setText(getRawNoteForOption(cursorOptionIndex)); - }; - - const saveCurrentNoteFromEditor = (value: string) => { - noteByOptionIndex.set(cursorOptionIndex, value); - }; - - const submitCurrentSelection = (selectedOptionLabel: string, note: string) => { - done({ - cancelled: false, - selectedOption: selectedOptionLabel, - note, - }); - }; - - noteEditor.onChange = (value) => { - saveCurrentNoteFromEditor(value); - requestUiRerender(); - }; - - noteEditor.onSubmit = (value) => { - saveCurrentNoteFromEditor(value); - const selectedOptionLabel = selectableOptionLabels[cursorOptionIndex]; - const trimmedNote = value.trim(); - - if (selectedOptionLabel === OTHER_OPTION && !trimmedNote) { - requestUiRerender(); - return; - } - - submitCurrentSelection(selectedOptionLabel, trimmedNote); - }; - - const render = (width: number): string[] => { - if (cachedRenderedLines) return cachedRenderedLines; - - const renderedLines: string[] = []; - const addLine = (line: string) => renderedLines.push(truncateToWidth(line, width)); - - addLine(theme.fg("accent", "─".repeat(width))); - addLine(theme.fg("text", ` ${questionInput.question}`)); - renderedLines.push(""); - - for (let optionIndex = 0; optionIndex < selectableOptionLabels.length; optionIndex++) { - const optionLabel = selectableOptionLabels[optionIndex]; - const isCursorOption = optionIndex === cursorOptionIndex; - const isEditingThisOption = isNoteEditorOpen && isCursorOption; - const cursorPrefixText = isCursorOption ? "→ " : " "; - const cursorPrefix = isCursorOption ? theme.fg("accent", cursorPrefixText) : cursorPrefixText; - const bullet = isCursorOption ? "●" : "○"; - const markerText = `${bullet} `; - const optionColor = isCursorOption ? "accent" : "text"; - const prefixWidth = visibleWidth(cursorPrefixText) + visibleWidth(markerText); - const wrappedInlineLabelLines = buildWrappedOptionLabelWithInlineNote( - optionLabel, - getRawNoteForOption(optionIndex), - isEditingThisOption, - Math.max(1, width - prefixWidth), - INLINE_NOTE_WRAP_PADDING, - ); - const continuationPrefix = " ".repeat(prefixWidth); - addLine(`${cursorPrefix}${theme.fg(optionColor, `${markerText}${wrappedInlineLabelLines[0] ?? ""}`)}`); - for (const wrappedLine of wrappedInlineLabelLines.slice(1)) { - addLine(`${continuationPrefix}${theme.fg(optionColor, wrappedLine)}`); - } - } - - renderedLines.push(""); - - if (isNoteEditorOpen) { - addLine(theme.fg("dim", " Typing note inline • Enter submit • Tab/Esc stop editing")); - } else if (getTrimmedNoteForOption(cursorOptionIndex).length > 0) { - addLine(theme.fg("dim", " ↑↓ move • Enter submit • Tab edit note • Esc cancel")); - } else { - addLine(theme.fg("dim", " ↑↓ move • Enter submit • Tab add note • Esc cancel")); - } - - addLine(theme.fg("accent", "─".repeat(width))); - cachedRenderedLines = renderedLines; - return renderedLines; - }; - - const handleInput = (data: string) => { - if (isNoteEditorOpen) { - if (matchesKey(data, Key.tab) || matchesKey(data, Key.escape)) { - isNoteEditorOpen = false; - requestUiRerender(); - return; - } - noteEditor.handleInput(data); - requestUiRerender(); - return; - } - - if (matchesKey(data, Key.up)) { - cursorOptionIndex = Math.max(0, cursorOptionIndex - 1); - requestUiRerender(); - return; - } - if (matchesKey(data, Key.down)) { - cursorOptionIndex = Math.min(selectableOptionLabels.length - 1, cursorOptionIndex + 1); - requestUiRerender(); - return; - } - - if (matchesKey(data, Key.tab)) { - isNoteEditorOpen = true; - loadCurrentNoteIntoEditor(); - requestUiRerender(); - return; - } - - if (matchesKey(data, Key.enter)) { - const selectedOptionLabel = selectableOptionLabels[cursorOptionIndex]; - const trimmedNote = getTrimmedNoteForOption(cursorOptionIndex); - - if (selectedOptionLabel === OTHER_OPTION && !trimmedNote) { - isNoteEditorOpen = true; - loadCurrentNoteIntoEditor(); - requestUiRerender(); - return; - } - - submitCurrentSelection(selectedOptionLabel, trimmedNote); - return; - } - - if (matchesKey(data, Key.escape)) { - done({ cancelled: true }); - } - }; - - return { - render, - invalidate: () => { - cachedRenderedLines = undefined; - }, - handleInput, - }; - }); - - if (result.cancelled || !result.selectedOption) { - return { selectedOptions: [] }; - } - - return buildSingleSelectionResult(result.selectedOption, result.note); -} diff --git a/src/planner/ui/ask/ask-logic.ts b/src/planner/ui/ask/ask-logic.ts deleted file mode 100644 index ccdf6fc..0000000 --- a/src/planner/ui/ask/ask-logic.ts +++ /dev/null @@ -1,98 +0,0 @@ -export const OTHER_OPTION = "Other (type your own)"; -const RECOMMENDED_OPTION_TAG = " (Recommended)"; - -export interface AskOption { - label: string; -} - -export interface AskQuestion { - id: string; - question: string; - options: AskOption[]; - multi?: boolean; - recommended?: number; -} - -export interface AskSelection { - selectedOptions: string[]; - customInput?: string; -} - -export function appendRecommendedTagToOptionLabels( - optionLabels: string[], - recommendedOptionIndex?: number, -): string[] { - if ( - recommendedOptionIndex == null || - recommendedOptionIndex < 0 || - recommendedOptionIndex >= optionLabels.length - ) { - return optionLabels; - } - - return optionLabels.map((optionLabel, optionIndex) => { - if (optionIndex !== recommendedOptionIndex) return optionLabel; - if (optionLabel.endsWith(RECOMMENDED_OPTION_TAG)) return optionLabel; - return `${optionLabel}${RECOMMENDED_OPTION_TAG}`; - }); -} - -function removeRecommendedTagFromOptionLabel(optionLabel: string): string { - if (!optionLabel.endsWith(RECOMMENDED_OPTION_TAG)) { - return optionLabel; - } - return optionLabel.slice(0, -RECOMMENDED_OPTION_TAG.length); -} - -export function buildSingleSelectionResult(selectedOptionLabel: string, note?: string): AskSelection { - const normalizedSelectedOption = removeRecommendedTagFromOptionLabel(selectedOptionLabel); - const normalizedNote = note?.trim(); - - if (normalizedSelectedOption === OTHER_OPTION) { - if (normalizedNote) { - return { selectedOptions: [], customInput: normalizedNote }; - } - return { selectedOptions: [] }; - } - - if (normalizedNote) { - return { selectedOptions: [`${normalizedSelectedOption} - ${normalizedNote}`] }; - } - - return { selectedOptions: [normalizedSelectedOption] }; -} - -export function buildMultiSelectionResult( - optionLabels: string[], - selectedOptionIndexes: number[], - optionNotes: string[], - otherOptionIndex: number, -): AskSelection { - const selectedOptionSet = new Set(selectedOptionIndexes); - const selectedOptions: string[] = []; - let customInput: string | undefined; - - for (let optionIndex = 0; optionIndex < optionLabels.length; optionIndex++) { - if (!selectedOptionSet.has(optionIndex)) continue; - - const optionLabel = removeRecommendedTagFromOptionLabel(optionLabels[optionIndex]); - const optionNote = optionNotes[optionIndex]?.trim(); - - if (optionIndex === otherOptionIndex) { - if (optionNote) customInput = optionNote; - continue; - } - - if (optionNote) { - selectedOptions.push(`${optionLabel} - ${optionNote}`); - } else { - selectedOptions.push(optionLabel); - } - } - - if (customInput) { - return { selectedOptions, customInput }; - } - - return { selectedOptions }; -} diff --git a/src/planner/ui/ask/ask-tabs-ui.ts b/src/planner/ui/ask/ask-tabs-ui.ts deleted file mode 100644 index dd58190..0000000 --- a/src/planner/ui/ask/ask-tabs-ui.ts +++ /dev/null @@ -1,512 +0,0 @@ -import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; -import { Editor, type EditorTheme, Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui"; -import { - OTHER_OPTION, - appendRecommendedTagToOptionLabels, - buildMultiSelectionResult, - buildSingleSelectionResult, - type AskQuestion, - type AskSelection, -} from "./ask-logic.js"; -import { INLINE_NOTE_WRAP_PADDING, buildWrappedOptionLabelWithInlineNote } from "./ask-inline-note.js"; - -interface PreparedQuestion { - id: string; - question: string; - options: string[]; - tabLabel: string; - multi: boolean; - otherOptionIndex: number; -} - -interface TabsUIState { - cancelled: boolean; - selectedOptionIndexesByQuestion: number[][]; - noteByQuestionByOption: string[][]; -} - -export function formatSelectionForSubmitReview(selection: AskSelection, isMulti: boolean): string { - const hasSelectedOptions = selection.selectedOptions.length > 0; - const hasCustomInput = Boolean(selection.customInput); - - if (hasSelectedOptions && hasCustomInput) { - const selectedPart = isMulti - ? `[${selection.selectedOptions.join(", ")}]` - : selection.selectedOptions[0]; - return `${selectedPart} + Other: ${selection.customInput}`; - } - - if (hasCustomInput) { - return `Other: ${selection.customInput}`; - } - - if (hasSelectedOptions) { - return isMulti ? `[${selection.selectedOptions.join(", ")}]` : selection.selectedOptions[0]; - } - - return "(not answered)"; -} - -function clampIndex(index: number | undefined, maxExclusive: number): number { - if (index == null || Number.isNaN(index) || maxExclusive <= 0) return 0; - if (index < 0) return 0; - if (index >= maxExclusive) return maxExclusive - 1; - return index; -} - -function normalizeTabLabel(id: string, fallback: string): string { - const normalized = id.trim().replace(/[_-]+/g, " "); - return normalized.length > 0 ? normalized : fallback; -} - -function buildSelectionForQuestion( - question: PreparedQuestion, - selectedOptionIndexes: number[], - noteByOptionIndex: string[], -): AskSelection { - if (selectedOptionIndexes.length === 0) { - return { selectedOptions: [] }; - } - - if (question.multi) { - return buildMultiSelectionResult(question.options, selectedOptionIndexes, noteByOptionIndex, question.otherOptionIndex); - } - - const selectedOptionIndex = selectedOptionIndexes[0]; - const selectedOptionLabel = question.options[selectedOptionIndex] ?? OTHER_OPTION; - const note = noteByOptionIndex[selectedOptionIndex] ?? ""; - return buildSingleSelectionResult(selectedOptionLabel, note); -} - -function isQuestionSelectionValid( - question: PreparedQuestion, - selectedOptionIndexes: number[], - noteByOptionIndex: string[], -): boolean { - if (selectedOptionIndexes.length === 0) return false; - if (!selectedOptionIndexes.includes(question.otherOptionIndex)) return true; - const otherNote = noteByOptionIndex[question.otherOptionIndex]?.trim() ?? ""; - return otherNote.length > 0; -} - -function createTabsUiStateSnapshot( - cancelled: boolean, - selectedOptionIndexesByQuestion: number[][], - noteByQuestionByOption: string[][], -): TabsUIState { - return { - cancelled, - selectedOptionIndexesByQuestion: selectedOptionIndexesByQuestion.map((indexes) => [...indexes]), - noteByQuestionByOption: noteByQuestionByOption.map((notes) => [...notes]), - }; -} - -function addIndexToSelection(selectedOptionIndexes: number[], optionIndex: number): number[] { - if (selectedOptionIndexes.includes(optionIndex)) return selectedOptionIndexes; - return [...selectedOptionIndexes, optionIndex].sort((a, b) => a - b); -} - -function removeIndexFromSelection(selectedOptionIndexes: number[], optionIndex: number): number[] { - return selectedOptionIndexes.filter((index) => index !== optionIndex); -} - -export async function askQuestionsWithTabs( - ui: ExtensionUIContext, - questions: AskQuestion[], -): Promise<{ cancelled: boolean; selections: AskSelection[] }> { - const preparedQuestions: PreparedQuestion[] = questions.map((question, questionIndex) => { - const baseOptionLabels = question.options.map((option) => option.label); - const optionLabels = [...appendRecommendedTagToOptionLabels(baseOptionLabels, question.recommended), OTHER_OPTION]; - return { - id: question.id, - question: question.question, - options: optionLabels, - tabLabel: normalizeTabLabel(question.id, `Q${questionIndex + 1}`), - multi: question.multi === true, - otherOptionIndex: optionLabels.length - 1, - }; - }); - - const initialCursorOptionIndexByQuestion = preparedQuestions.map((preparedQuestion, questionIndex) => - clampIndex(questions[questionIndex].recommended, preparedQuestion.options.length), - ); - - const result = await ui.custom((tui, theme, _keybindings, done) => { - let activeTabIndex = 0; - let isNoteEditorOpen = false; - let cachedRenderedLines: string[] | undefined; - const cursorOptionIndexByQuestion = [...initialCursorOptionIndexByQuestion]; - const selectedOptionIndexesByQuestion = preparedQuestions.map(() => [] as number[]); - const noteByQuestionByOption = preparedQuestions.map((preparedQuestion) => - Array(preparedQuestion.options.length).fill("") as string[], - ); - - const editorTheme: EditorTheme = { - borderColor: (text) => theme.fg("accent", text), - selectList: { - selectedPrefix: (text) => theme.fg("accent", text), - selectedText: (text) => theme.fg("accent", text), - description: (text) => theme.fg("muted", text), - scrollInfo: (text) => theme.fg("dim", text), - noMatch: (text) => theme.fg("warning", text), - }, - }; - const noteEditor = new Editor(tui, editorTheme); - - const submitTabIndex = preparedQuestions.length; - - const requestUiRerender = () => { - cachedRenderedLines = undefined; - tui.requestRender(); - }; - - const getActiveQuestionIndex = (): number | null => { - if (activeTabIndex >= preparedQuestions.length) return null; - return activeTabIndex; - }; - - const getQuestionNote = (questionIndex: number, optionIndex: number): string => - noteByQuestionByOption[questionIndex]?.[optionIndex] ?? ""; - - const getTrimmedQuestionNote = (questionIndex: number, optionIndex: number): string => - getQuestionNote(questionIndex, optionIndex).trim(); - - const isAllQuestionSelectionsValid = (): boolean => - preparedQuestions.every((preparedQuestion, questionIndex) => - isQuestionSelectionValid( - preparedQuestion, - selectedOptionIndexesByQuestion[questionIndex], - noteByQuestionByOption[questionIndex], - ), - ); - - const openNoteEditorForActiveOption = () => { - const questionIndex = getActiveQuestionIndex(); - if (questionIndex == null) return; - - isNoteEditorOpen = true; - const optionIndex = cursorOptionIndexByQuestion[questionIndex]; - noteEditor.setText(getQuestionNote(questionIndex, optionIndex)); - requestUiRerender(); - }; - - const advanceToNextTabOrSubmit = () => { - activeTabIndex = Math.min(submitTabIndex, activeTabIndex + 1); - }; - - noteEditor.onChange = (value) => { - const questionIndex = getActiveQuestionIndex(); - if (questionIndex == null) return; - const optionIndex = cursorOptionIndexByQuestion[questionIndex]; - noteByQuestionByOption[questionIndex][optionIndex] = value; - requestUiRerender(); - }; - - noteEditor.onSubmit = (value) => { - const questionIndex = getActiveQuestionIndex(); - if (questionIndex == null) return; - - const preparedQuestion = preparedQuestions[questionIndex]; - const optionIndex = cursorOptionIndexByQuestion[questionIndex]; - noteByQuestionByOption[questionIndex][optionIndex] = value; - const trimmedNote = value.trim(); - - if (preparedQuestion.multi) { - if (trimmedNote.length > 0) { - selectedOptionIndexesByQuestion[questionIndex] = addIndexToSelection( - selectedOptionIndexesByQuestion[questionIndex], - optionIndex, - ); - } - if (optionIndex === preparedQuestion.otherOptionIndex && trimmedNote.length === 0) { - requestUiRerender(); - return; - } - isNoteEditorOpen = false; - requestUiRerender(); - return; - } - - selectedOptionIndexesByQuestion[questionIndex] = [optionIndex]; - if (optionIndex === preparedQuestion.otherOptionIndex && trimmedNote.length === 0) { - requestUiRerender(); - return; - } - - isNoteEditorOpen = false; - advanceToNextTabOrSubmit(); - requestUiRerender(); - }; - - const renderTabs = (): string => { - const tabParts: string[] = ["← "]; - for (let questionIndex = 0; questionIndex < preparedQuestions.length; questionIndex++) { - const preparedQuestion = preparedQuestions[questionIndex]; - const isActiveTab = questionIndex === activeTabIndex; - const isQuestionValid = isQuestionSelectionValid( - preparedQuestion, - selectedOptionIndexesByQuestion[questionIndex], - noteByQuestionByOption[questionIndex], - ); - const statusIcon = isQuestionValid ? "■" : "□"; - const tabLabel = ` ${statusIcon} ${preparedQuestion.tabLabel} `; - const styledTabLabel = isActiveTab - ? theme.bg("selectedBg", theme.fg("text", tabLabel)) - : theme.fg(isQuestionValid ? "success" : "muted", tabLabel); - tabParts.push(`${styledTabLabel} `); - } - - const isSubmitTabActive = activeTabIndex === submitTabIndex; - const canSubmit = isAllQuestionSelectionsValid(); - const submitLabel = " ✓ Submit "; - const styledSubmitLabel = isSubmitTabActive - ? theme.bg("selectedBg", theme.fg("text", submitLabel)) - : theme.fg(canSubmit ? "success" : "dim", submitLabel); - tabParts.push(`${styledSubmitLabel} →`); - return tabParts.join(""); - }; - - const renderSubmitTab = (width: number, renderedLines: string[]): void => { - const addLine = (line: string) => renderedLines.push(truncateToWidth(line, width)); - - addLine(theme.fg("accent", theme.bold(" Review answers"))); - renderedLines.push(""); - - for (let questionIndex = 0; questionIndex < preparedQuestions.length; questionIndex++) { - const preparedQuestion = preparedQuestions[questionIndex]; - const selection = buildSelectionForQuestion( - preparedQuestion, - selectedOptionIndexesByQuestion[questionIndex], - noteByQuestionByOption[questionIndex], - ); - const value = formatSelectionForSubmitReview(selection, preparedQuestion.multi); - const isValid = isQuestionSelectionValid( - preparedQuestion, - selectedOptionIndexesByQuestion[questionIndex], - noteByQuestionByOption[questionIndex], - ); - const statusIcon = isValid ? theme.fg("success", "●") : theme.fg("warning", "○"); - addLine(` ${statusIcon} ${theme.fg("muted", `${preparedQuestion.tabLabel}:`)} ${theme.fg("text", value)}`); - } - - renderedLines.push(""); - if (isAllQuestionSelectionsValid()) { - addLine(theme.fg("success", " Press Enter to submit")); - } else { - const missingQuestions = preparedQuestions - .filter((preparedQuestion, questionIndex) => - !isQuestionSelectionValid( - preparedQuestion, - selectedOptionIndexesByQuestion[questionIndex], - noteByQuestionByOption[questionIndex], - ), - ) - .map((preparedQuestion) => preparedQuestion.tabLabel) - .join(", "); - addLine(theme.fg("warning", ` Complete required answers: ${missingQuestions}`)); - } - addLine(theme.fg("dim", " ←/→ switch tabs • Esc cancel")); - }; - - const renderQuestionTab = (width: number, renderedLines: string[], questionIndex: number): void => { - const addLine = (line: string) => renderedLines.push(truncateToWidth(line, width)); - const preparedQuestion = preparedQuestions[questionIndex]; - const cursorOptionIndex = cursorOptionIndexByQuestion[questionIndex]; - const selectedOptionIndexes = selectedOptionIndexesByQuestion[questionIndex]; - - addLine(theme.fg("text", ` ${preparedQuestion.question}`)); - renderedLines.push(""); - - for (let optionIndex = 0; optionIndex < preparedQuestion.options.length; optionIndex++) { - const optionLabel = preparedQuestion.options[optionIndex]; - const isCursorOption = optionIndex === cursorOptionIndex; - const isOptionSelected = selectedOptionIndexes.includes(optionIndex); - const isEditingThisOption = isNoteEditorOpen && isCursorOption; - const cursorPrefixText = isCursorOption ? "→ " : " "; - const cursorPrefix = isCursorOption ? theme.fg("accent", cursorPrefixText) : cursorPrefixText; - const markerText = preparedQuestion.multi - ? `${isOptionSelected ? "[x]" : "[ ]"} ` - : `${isOptionSelected ? "●" : "○"} `; - const optionColor = isCursorOption ? "accent" : isOptionSelected ? "success" : "text"; - const prefixWidth = visibleWidth(cursorPrefixText) + visibleWidth(markerText); - const wrappedInlineLabelLines = buildWrappedOptionLabelWithInlineNote( - optionLabel, - getQuestionNote(questionIndex, optionIndex), - isEditingThisOption, - Math.max(1, width - prefixWidth), - INLINE_NOTE_WRAP_PADDING, - ); - const continuationPrefix = " ".repeat(prefixWidth); - addLine(`${cursorPrefix}${theme.fg(optionColor, `${markerText}${wrappedInlineLabelLines[0] ?? ""}`)}`); - for (const wrappedLine of wrappedInlineLabelLines.slice(1)) { - addLine(`${continuationPrefix}${theme.fg(optionColor, wrappedLine)}`); - } - } - - renderedLines.push(""); - if (isNoteEditorOpen) { - addLine(theme.fg("dim", " Typing note inline • Enter save note • Tab/Esc stop editing")); - } else { - if (preparedQuestion.multi) { - addLine( - theme.fg( - "dim", - " ↑↓ move • Enter toggle/select • Tab add note • ←/→ switch tabs • Esc cancel", - ), - ); - } else { - addLine( - theme.fg("dim", " ↑↓ move • Enter select • Tab add note • ←/→ switch tabs • Esc cancel"), - ); - } - } - }; - - const render = (width: number): string[] => { - if (cachedRenderedLines) return cachedRenderedLines; - - const renderedLines: string[] = []; - const addLine = (line: string) => renderedLines.push(truncateToWidth(line, width)); - - addLine(theme.fg("accent", "─".repeat(width))); - addLine(` ${renderTabs()}`); - renderedLines.push(""); - - if (activeTabIndex === submitTabIndex) { - renderSubmitTab(width, renderedLines); - } else { - renderQuestionTab(width, renderedLines, activeTabIndex); - } - - addLine(theme.fg("accent", "─".repeat(width))); - cachedRenderedLines = renderedLines; - return renderedLines; - }; - - const handleInput = (data: string) => { - if (isNoteEditorOpen) { - if (matchesKey(data, Key.tab) || matchesKey(data, Key.escape)) { - isNoteEditorOpen = false; - requestUiRerender(); - return; - } - noteEditor.handleInput(data); - requestUiRerender(); - return; - } - - if (matchesKey(data, Key.left)) { - activeTabIndex = (activeTabIndex - 1 + preparedQuestions.length + 1) % (preparedQuestions.length + 1); - requestUiRerender(); - return; - } - - if (matchesKey(data, Key.right)) { - activeTabIndex = (activeTabIndex + 1) % (preparedQuestions.length + 1); - requestUiRerender(); - return; - } - - if (activeTabIndex === submitTabIndex) { - if (matchesKey(data, Key.enter) && isAllQuestionSelectionsValid()) { - done(createTabsUiStateSnapshot(false, selectedOptionIndexesByQuestion, noteByQuestionByOption)); - return; - } - if (matchesKey(data, Key.escape)) { - done(createTabsUiStateSnapshot(true, selectedOptionIndexesByQuestion, noteByQuestionByOption)); - } - return; - } - - const questionIndex = activeTabIndex; - const preparedQuestion = preparedQuestions[questionIndex]; - - if (matchesKey(data, Key.up)) { - cursorOptionIndexByQuestion[questionIndex] = Math.max(0, cursorOptionIndexByQuestion[questionIndex] - 1); - requestUiRerender(); - return; - } - - if (matchesKey(data, Key.down)) { - cursorOptionIndexByQuestion[questionIndex] = Math.min( - preparedQuestion.options.length - 1, - cursorOptionIndexByQuestion[questionIndex] + 1, - ); - requestUiRerender(); - return; - } - - if (matchesKey(data, Key.tab)) { - openNoteEditorForActiveOption(); - return; - } - - if (matchesKey(data, Key.enter)) { - const cursorOptionIndex = cursorOptionIndexByQuestion[questionIndex]; - - if (preparedQuestion.multi) { - const currentlySelected = selectedOptionIndexesByQuestion[questionIndex]; - if (currentlySelected.includes(cursorOptionIndex)) { - selectedOptionIndexesByQuestion[questionIndex] = removeIndexFromSelection(currentlySelected, cursorOptionIndex); - } else { - selectedOptionIndexesByQuestion[questionIndex] = addIndexToSelection(currentlySelected, cursorOptionIndex); - } - - if ( - cursorOptionIndex === preparedQuestion.otherOptionIndex && - selectedOptionIndexesByQuestion[questionIndex].includes(cursorOptionIndex) && - getTrimmedQuestionNote(questionIndex, cursorOptionIndex).length === 0 - ) { - openNoteEditorForActiveOption(); - return; - } - - requestUiRerender(); - return; - } - - selectedOptionIndexesByQuestion[questionIndex] = [cursorOptionIndex]; - if ( - cursorOptionIndex === preparedQuestion.otherOptionIndex && - getTrimmedQuestionNote(questionIndex, cursorOptionIndex).length === 0 - ) { - openNoteEditorForActiveOption(); - return; - } - - advanceToNextTabOrSubmit(); - requestUiRerender(); - return; - } - - if (matchesKey(data, Key.escape)) { - done(createTabsUiStateSnapshot(true, selectedOptionIndexesByQuestion, noteByQuestionByOption)); - } - }; - - return { - render, - invalidate: () => { - cachedRenderedLines = undefined; - }, - handleInput, - }; - }); - - if (result.cancelled) { - return { - cancelled: true, - selections: preparedQuestions.map(() => ({ selectedOptions: [] } satisfies AskSelection)), - }; - } - - const selections = preparedQuestions.map((preparedQuestion, questionIndex) => - buildSelectionForQuestion( - preparedQuestion, - result.selectedOptionIndexesByQuestion[questionIndex] ?? [], - result.noteByQuestionByOption[questionIndex] ?? Array(preparedQuestion.options.length).fill(""), - ), - ); - - return { cancelled: result.cancelled, selections }; -} diff --git a/src/planner/ui/epic-widget.ts b/src/planner/ui/epic-widget.ts deleted file mode 100644 index 88e9cb7..0000000 --- a/src/planner/ui/epic-widget.ts +++ /dev/null @@ -1,243 +0,0 @@ -// Epic execution status widget. Renders a TUI panel showing: -// - Story list with status icons -// - Active subagent: role, step, elapsed time -// - Recent log tail from the active subagent directory -// - Autonomous decision counter -// -// The driver creates one instance at the start of runEpicPipeline (before intake) -// and calls update() after each state change. Spans the full epic lifecycle (Phase -// A + B), not just story execution. Pure observation layer — never influences routing. -// Self-renders via pi's setWidget API; a 1-second unref'd timer keeps elapsed time fresh. - -import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; -import type { Theme, ThemeColor } from "@mariozechner/pi-coding-agent"; -import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui"; - -import type { EpicPhase, StoryStatus } from "../types.js"; -import type { LogLine } from "../lib/audit.js"; - -// -- Types -- - -export interface ActiveSubagentInfo { - role: string; - storyId?: string; - step: number; - totalSteps: number; - stepName: string; - startedAt: number; -} - -export interface EpicWidgetState { - epicId: string; - epicPhase: EpicPhase; - stories: Array<{ storyId: string; status: StoryStatus }>; - activeSubagent: ActiveSubagentInfo | null; - logLines: LogLine[]; -} - -export interface EpicWidgetUpdate { - epicPhase?: EpicPhase; - stories?: Array<{ storyId: string; status: StoryStatus }>; - activeSubagent?: ActiveSubagentInfo | null; - logLines?: LogLine[]; -} - -// -- Constants -- - -const WIDGET_KEY = "koan-epic"; -const PAD = 2; -const MAX_LOG_LINES = 5; - -// Status icons and colors — no escalated status per §11.3.1. -const STATUS_ICON: Record = { - pending: "○", - selected: "◎", - planning: "◐", - executing: "●", - verifying: "◑", - done: "✓", - retry: "↺", - skipped: "—", -}; - -const STATUS_COLOR: Record = { - pending: "muted", - selected: "accent", - planning: "accent", - executing: "accent", - verifying: "accent", - done: "success", - retry: "warning", - skipped: "dim", -}; - -// -- Helpers -- - -function cw(termWidth: number): number { - return Math.max(40, termWidth - PAD * 2); -} - -function line(content: string, termWidth: number, theme: Theme): string { - const w = cw(termWidth); - const inner = clamp(content, w); - return theme.bg("toolPendingBg", " ".repeat(PAD) + inner + " ".repeat(PAD)); -} - -function clamp(text: string, width: number): string { - const truncated = truncateToWidth(text, width, "", false); - const vw = visibleWidth(truncated); - return vw >= width ? truncated : truncated + " ".repeat(width - vw); -} - -function formatElapsed(ms: number): string { - const s = Math.floor(ms / 1000); - const h = Math.floor(s / 3600); - const m = Math.floor((s % 3600) / 60); - const sec = s % 60; - if (h > 0) return `${h}h ${String(m).padStart(2, "0")}m`; - return `${m}m ${String(sec).padStart(2, "0")}s`; -} - -// -- Render -- - -function renderHeader(state: EpicWidgetState, theme: Theme, width: number): string { - const elapsed = state.activeSubagent - ? theme.fg("dim", formatElapsed(Date.now() - state.activeSubagent.startedAt)) - : ""; - const title = theme.bold(theme.fg("accent", `Epic · ${state.epicId}`)); - const phaseBadge = theme.fg("muted", ` · ${state.epicPhase}`); - const left = `${title}${phaseBadge}`; - const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(elapsed)); - return clamp(`${left}${" ".repeat(gap)}${elapsed}`, width); -} - -function renderStoryList(state: EpicWidgetState, theme: Theme, width: number): string[] { - if (state.stories.length === 0) { - return [clamp(theme.fg("muted", " No stories yet"), width)]; - } - return state.stories.map(({ storyId, status }) => { - const icon = STATUS_ICON[status] ?? "?"; - const color = STATUS_COLOR[status] ?? "muted"; - const iconStr = theme.fg(color, icon); - const label = status === "executing" || status === "planning" || status === "verifying" - ? theme.bold(theme.fg(color, storyId)) - : theme.fg(color, storyId); - const statusLabel = theme.fg("dim", ` (${status})`); - return clamp(` ${iconStr} ${label}${statusLabel}`, width); - }); -} - -function renderActiveSubagent(state: EpicWidgetState, theme: Theme, width: number): string[] { - const sa = state.activeSubagent; - if (!sa) { - return [clamp(theme.fg("muted", " idle"), width)]; - } - const roleLabel = sa.storyId ? `${sa.role} · ${sa.storyId}` : sa.role; - const stepLabel = sa.totalSteps > 0 - ? `step ${sa.step}/${sa.totalSteps}${sa.stepName ? ` · ${sa.stepName}` : ""}` - : "starting"; - const elapsedStr = formatElapsed(Date.now() - sa.startedAt); - return [ - clamp(` ${theme.bold(theme.fg("accent", roleLabel))} ${theme.fg("muted", stepLabel)}`, width), - clamp(` ${theme.fg("dim", elapsedStr)}`, width), - ]; -} - -function renderLogTail(state: EpicWidgetState, theme: Theme, width: number): string[] { - const entries = state.logLines.slice(-MAX_LOG_LINES); - if (entries.length === 0) { - return [clamp(theme.fg("dim", " (no log entries)"), width)]; - } - return entries.map((entry) => { - const toolStr = theme.bold(theme.fg("accent", entry.tool)); - const summary = entry.summary.trim(); - const sep = summary ? " " : ""; - return clamp(` ${toolStr}${sep}${theme.fg("muted", summary)}`, width); - }); -} - -function renderDivider(label: string, theme: Theme, width: number): string { - const tag = ` ${label} `; - const tagLen = visibleWidth(tag); - const dashCount = Math.max(0, width - tagLen); - const left = Math.floor(dashCount / 2); - const right = dashCount - left; - return clamp( - `${theme.fg("dim", "─".repeat(left))}${theme.bold(theme.fg("muted", tag))}${theme.fg("dim", "─".repeat(right))}`, - width, - ); -} - -function render(state: EpicWidgetState, theme: Theme, termWidth: number): string[] { - const w = cw(termWidth); - const L = (content: string) => line(content, termWidth, theme); - const lines: string[] = []; - - lines.push(L("")); - lines.push(L(renderHeader(state, theme, w))); - lines.push(L(renderDivider("stories", theme, w))); - for (const l of renderStoryList(state, theme, w)) lines.push(L(l)); - lines.push(L(renderDivider("active", theme, w))); - for (const l of renderActiveSubagent(state, theme, w)) lines.push(L(l)); - lines.push(L(renderDivider("log", theme, w))); - for (const l of renderLogTail(state, theme, w)) lines.push(L(l)); - lines.push(L("")); - - return lines; -} - -// -- EpicWidgetController -- - -export class EpicWidgetController { - private state: EpicWidgetState; - private lastHash = ""; - private timer: ReturnType; - private ui: ExtensionUIContext; - - constructor(ui: ExtensionUIContext, epicId: string) { - this.ui = ui; - this.state = { - epicId, - epicPhase: "intake", - stories: [], - activeSubagent: null, - logLines: [], - }; - this.timer = setInterval(() => this.doRender(), 1000); - this.timer.unref(); - this.doRender(); - } - - update(patch: EpicWidgetUpdate): void { - if (patch.epicPhase !== undefined) this.state.epicPhase = patch.epicPhase; - if (patch.stories !== undefined) this.state.stories = patch.stories; - if (patch.activeSubagent !== undefined) this.state.activeSubagent = patch.activeSubagent; - if (patch.logLines !== undefined) this.state.logLines = patch.logLines; - this.doRender(); - } - - destroy(): void { - clearInterval(this.timer); - this.ui.setWidget(WIDGET_KEY, undefined); - } - - private doRender(): void { - const snapshot = { - ...this.state, - stories: this.state.stories.map((s) => ({ ...s })), - logLines: this.state.logLines.map((l) => ({ ...l })), - activeSubagent: this.state.activeSubagent ? { ...this.state.activeSubagent } : null, - }; - const { theme } = this.ui; - - const hashLines = render(snapshot, theme, 0); - const hash = hashLines.join("\n"); - if (hash === this.lastHash) return; - this.lastHash = hash; - - this.ui.setWidget(WIDGET_KEY, (_tui, th) => ({ - render: (width: number) => render(snapshot, th, width), - invalidate: () => {}, - })); - } -} diff --git a/src/planner/ui/spec-review.ts b/src/planner/ui/spec-review.ts deleted file mode 100644 index 9f5e1a3..0000000 --- a/src/planner/ui/spec-review.ts +++ /dev/null @@ -1,152 +0,0 @@ -// Spec review gate: interactive story approval UI. -// Shown after decomposition so the user can approve, or skip individual stories -// before execution begins. Driver blocks until the user confirms. -// -// Controls: -// ↑↓ move cursor -// Space toggle selected story between "include" and "skip" -// A approve all (mark all as include) -// Enter confirm and proceed -// Esc confirm current selections and proceed - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; -import { Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui"; - -export interface SpecReviewResult { - approved: string[]; - skipped: string[]; -} - -interface StoryEntry { - storyId: string; - title: string; - include: boolean; -} - -async function readStoryTitle(epicDir: string, storyId: string): Promise { - try { - const raw = await fs.readFile(path.join(epicDir, "stories", storyId, "story.md"), "utf8"); - // Extract first non-empty, non-heading line after a heading, or first heading text. - for (const rawLine of raw.split("\n")) { - const l = rawLine.trim(); - if (!l) continue; - // Strip leading # characters for headings. - const text = l.replace(/^#+\s*/, "").trim(); - if (text) return text.slice(0, 80); - } - return storyId; - } catch { - return storyId; - } -} - -export async function reviewStorySketches( - epicDir: string, - storyIds: string[], - ui: ExtensionUIContext, -): Promise { - if (storyIds.length === 0) { - return { approved: [], skipped: [] }; - } - - // Load story titles asynchronously. - const titles = await Promise.all(storyIds.map((id) => readStoryTitle(epicDir, id))); - const entries: StoryEntry[] = storyIds.map((storyId, i) => ({ - storyId, - title: titles[i] ?? storyId, - include: true, - })); - - const result = await ui.custom<{ entries: StoryEntry[] }>((tui, theme, _keybindings, done) => { - let cursor = 0; - let cachedLines: string[] | undefined; - - const requestRender = () => { - cachedLines = undefined; - tui.requestRender(); - }; - - const render = (width: number): string[] => { - if (cachedLines) return cachedLines; - const lines: string[] = []; - const addLine = (l: string) => lines.push(truncateToWidth(l, width)); - - addLine(theme.fg("accent", "─".repeat(width))); - addLine( - ` ${theme.bold(theme.fg("accent", "Spec Review"))} ${theme.fg("muted", `${entries.length} stories`)}`, - ); - addLine(theme.fg("dim", " Review story sketches before execution begins.")); - addLine(""); - - for (let i = 0; i < entries.length; i++) { - const e = entries[i]; - const isCursor = i === cursor; - const prefix = isCursor ? theme.fg("accent", "→ ") : " "; - const checkbox = e.include - ? theme.fg("success", "[✓]") - : theme.fg("dim", "[ ]"); - const label = isCursor - ? theme.bold(theme.fg(e.include ? "text" : "dim", e.storyId)) - : theme.fg(e.include ? "text" : "dim", e.storyId); - const titleStr = theme.fg("muted", ` — ${e.title}`); - addLine(`${prefix}${checkbox} ${label}${titleStr}`); - } - - addLine(""); - - const approvedCount = entries.filter((e) => e.include).length; - const skippedCount = entries.length - approvedCount; - addLine( - ` ${theme.fg("success", `${approvedCount} approved`)} ${theme.fg("dim", `${skippedCount} skipped`)}`, - ); - addLine(""); - addLine( - theme.fg("dim", " ↑↓ move • Space toggle • A approve all • Enter confirm • Esc confirm"), - ); - addLine(theme.fg("accent", "─".repeat(width))); - - cachedLines = lines; - return lines; - }; - - const handleInput = (data: string) => { - if (matchesKey(data, Key.up)) { - cursor = Math.max(0, cursor - 1); - requestRender(); - return; - } - if (matchesKey(data, Key.down)) { - cursor = Math.min(entries.length - 1, cursor + 1); - requestRender(); - return; - } - if (data === " ") { - entries[cursor].include = !entries[cursor].include; - requestRender(); - return; - } - if (data === "a" || data === "A") { - for (const e of entries) e.include = true; - requestRender(); - return; - } - if (matchesKey(data, Key.enter) || matchesKey(data, Key.escape)) { - done({ entries: entries.map((e) => ({ ...e })) }); - return; - } - }; - - return { - render, - invalidate: () => { cachedLines = undefined; }, - handleInput, - }; - }); - - const approved = result.entries.filter((e) => e.include).map((e) => e.storyId); - const skipped = result.entries.filter((e) => !e.include).map((e) => e.storyId); - return { approved, skipped }; -} From 43303d59aa7dfc2668cc39d3331d5134c0e7f3f6 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:48:58 +0700 Subject: [PATCH 057/412] consolidate subagent spawning into single task-driven function --- src/planner/subagent.ts | 297 +++++++++++++--------------------------- 1 file changed, 94 insertions(+), 203 deletions(-) diff --git a/src/planner/subagent.ts b/src/planner/subagent.ts index 99c637d..d722d2d 100644 --- a/src/planner/subagent.ts +++ b/src/planner/subagent.ts @@ -1,19 +1,27 @@ -// Subagent spawn helpers. Each public function delegates to spawnSubagent, -// which handles process lifecycle, stdout/stderr routing to disk, and -// exit-code normalization. When a UI context is provided, an IPC responder -// runs concurrently so subagents can ask questions and request scouts. +// Subagent spawn infrastructure. +// +// A single public function, spawnSubagent(), handles all six roles. +// It writes task.json to the subagent directory before spawning (the +// directory-as-contract invariant: the child reads task.json to discover +// its role and parameters — no structured data flows through CLI flags). +// +// The spawn command carries only what pi needs at the OS level: +// pi -p -e {ext} --koan-dir {subagentDir} [--model {model}] "{bootPrompt}" +// +// All tools register unconditionally at init. Task-specific content is +// intentionally absent from spawn prompts: it arrives as step 1 guidance +// returned by the first koan_complete_step call, after the calling pattern +// is established. import { spawn } from "node:child_process"; import { createWriteStream } from "node:fs"; import * as path from "node:path"; -import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; - import { createLogger, type Logger } from "../utils/logger.js"; -import type { SubagentRole, StepSequence } from "./types.js"; import { resolveModelForRole } from "./model-resolver.js"; import { runIpcResponder, type ScoutSpawnContext } from "./lib/ipc-responder.js"; -import type { ScoutTask } from "./lib/ipc.js"; +import { writeTaskFile, type SubagentTask, type ScoutTask } from "./lib/task.js"; +import type { WebServerHandle } from "./web/server-types.js"; // -- Result type -- @@ -23,66 +31,95 @@ export interface SubagentResult { subagentDir: string; } -// -- Public spawn option types -- +// -- Spawn options -- export interface SpawnOptions { - epicDir: string; - subagentDir: string; cwd: string; extensionPath: string; modelOverride?: string; log?: Logger; - ui?: ExtensionUIContext; + webServer?: WebServerHandle; } -export interface SpawnStoryOptions extends SpawnOptions { - storyId: string; -} +// -- Constants -- -// -- Internal spawn infrastructure -- +// Roles that support koan_request_scouts and therefore need a ScoutSpawnContext +// wired into their IPC responder. +const ROLES_WITH_SCOUT_SUPPORT = new Set([ + "intake", + "decomposer", + "planner", +]); -interface SpawnSubagentOpts { - epicDir: string; - subagentDir: string; - cwd: string; - extensionPath: string; - extraFlags?: string[]; - modelOverride?: string; - ui?: ExtensionUIContext; - // Scout spawning context for the IPC responder. Provided for all non-scout - // subagents that may call koan_request_scouts. - scoutContext?: ScoutSpawnContext; +// -- Private helpers -- + +// The entire spawn prompt. Kept to one sentence deliberately: the LLM must +// call koan_complete_step before seeing any task instructions. Putting task +// content here risks text output + immediate exit on weaker models. +function bootPrompt(role: string): string { + return `You are a koan ${role} agent. Call koan_complete_step to receive your instructions.`; +} + +// Builds the ScoutSpawnContext injected into the IPC responder. Scouts spawned +// via this context do not receive a web server — they are narrow investigators +// with no user interaction and no nested IPC. +function makeScoutSpawnContext( + parentRole: string, + epicDir: string, + opts: SpawnOptions, + log: Logger, +): ScoutSpawnContext { + return { + epicDir, + parentRole, + async spawnScout(task: ScoutTask, scoutSubagentDir: string): Promise { + const result = await spawnSubagent(task, scoutSubagentDir, { + cwd: opts.cwd, + extensionPath: opts.extensionPath, + // Deliberately no webServer — scouts are narrow investigators. + log, + }); + return result.exitCode; + }, + }; } -export function buildSpawnArgs( - role: string, - prompt: string, - opts: SpawnSubagentOpts, -): string[] { - return [ +// -- Public API -- + +/** + * Spawn a koan subagent for the given task. + * + * Writes task.json to subagentDir before spawning so the child process can + * read its role and parameters without relying on CLI flags. + */ +export async function spawnSubagent( + task: SubagentTask, + subagentDir: string, + opts: SpawnOptions, +): Promise { + const log = opts.log ?? createLogger("Subagent"); + + await writeTaskFile(subagentDir, task); + + const modelOverride = opts.modelOverride ?? await resolveModelForRole(task.role); + + const scoutContext = ROLES_WITH_SCOUT_SUPPORT.has(task.role) + ? makeScoutSpawnContext(task.role, task.epicDir, opts, log) + : undefined; + + const args = [ "-p", "-e", opts.extensionPath, - "--koan-role", role, - "--koan-epic-dir", opts.epicDir, - "--koan-subagent-dir", opts.subagentDir, - ...(opts.extraFlags ?? []), - ...(opts.modelOverride ? ["--model", opts.modelOverride] : []), - prompt, + "--koan-dir", subagentDir, + ...(modelOverride ? ["--model", modelOverride] : []), + bootPrompt(task.role), ]; -} -function spawnSubagent( - role: string, - prompt: string, - opts: SpawnSubagentOpts, - log: Logger, -): Promise { - const args = buildSpawnArgs(role, prompt, opts); - log(`Spawning ${role} subagent`, { epicDir: opts.epicDir, subagentDir: opts.subagentDir }); + log(`Spawning ${task.role} subagent`, { subagentDir }); return new Promise((resolve) => { - const stdoutLog = createWriteStream(path.join(opts.subagentDir, "stdout.log"), { flags: "w" }); - const stderrLog = createWriteStream(path.join(opts.subagentDir, "stderr.log"), { flags: "w" }); + const stdoutLog = createWriteStream(path.join(subagentDir, "stdout.log"), { flags: "w" }); + const stderrLog = createWriteStream(path.join(subagentDir, "stderr.log"), { flags: "w" }); const proc = spawn("pi", args, { cwd: opts.cwd, @@ -90,20 +127,12 @@ function spawnSubagent( stdio: ["ignore", "pipe", "pipe"], }); - // Start IPC responder concurrently when a UI context is available. - // The responder polls ipc.json in the subagent directory and routes - // ask-question requests to the ask UI and scout-request requests to - // the scout spawning pool. + // Start IPC responder concurrently when a web server handle is available. let abortIpc: (() => void) | undefined; - if (opts.ui) { + if (opts.webServer) { const ac = new AbortController(); abortIpc = () => ac.abort(); - void runIpcResponder( - opts.subagentDir, - opts.ui, - ac.signal, - opts.scoutContext, - ); + void runIpcResponder(subagentDir, opts.webServer, ac.signal, scoutContext); } let stderr = ""; @@ -122,154 +151,16 @@ function spawnSubagent( stdoutLog.end(); stderrLog.end(); const exitCode = code ?? 1; - log(`${role} subagent exited`, { exitCode }); - resolve({ exitCode, stderr, subagentDir: opts.subagentDir }); + log(`${task.role} subagent exited`, { exitCode }); + resolve({ exitCode, stderr, subagentDir }); }); proc.on("error", (error) => { abortIpc?.(); stdoutLog.end(); stderrLog.end(); - log(`${role} subagent spawn error`, { error: error.message }); - resolve({ exitCode: 1, stderr: error.message, subagentDir: opts.subagentDir }); + log(`${task.role} subagent spawn error`, { error: error.message }); + resolve({ exitCode: 1, stderr: error.message, subagentDir }); }); }); } - -// -- Scout spawner (injected into IPC responder) -- -// Defined here to avoid circular imports: ipc-responder.ts uses a callback -// type, not a direct import from this module. - -function makeScoutSpawnContext( - opts: SpawnOptions, - log: Logger, -): ScoutSpawnContext { - return { - epicDir: opts.epicDir, - async spawnScout(task: ScoutTask, scoutSubagentDir: string, outputFile: string): Promise { - const scoutModel = await resolveModelForRole("scout"); - const prompt = `${task.prompt}\n\nWrite your findings to: ${outputFile}\nYour investigator role: ${task.role}`; - const result = await spawnSubagent( - "scout", - prompt, - { - epicDir: opts.epicDir, - subagentDir: scoutSubagentDir, - cwd: opts.cwd, - extensionPath: opts.extensionPath, - modelOverride: scoutModel, - // Scouts do not get an IPC responder — they are narrow investigators. - }, - log, - ); - return result.exitCode; - }, - }; -} - -// -- Public spawn functions -- - -// Intake: reads conversation, extracts context, requests scouts, asks user questions. -export async function spawnIntake(opts: SpawnOptions): Promise { - const role: SubagentRole = "intake"; - const log = opts.log ?? createLogger("Subagent"); - const modelOverride = opts.modelOverride ?? await resolveModelForRole(role); - const scoutContext = makeScoutSpawnContext(opts, log); - return spawnSubagent( - role, - "Begin the intake phase.", - { ...opts, modelOverride, scoutContext }, - log, - ); -} - -// Scout: answers one narrow codebase question and writes findings to outputFile. -// Note: scouts are spawned by the IPC responder (via makeScoutSpawnContext) when -// a subagent calls koan_request_scouts. This function is also callable directly -// from the driver if needed. -export async function spawnScout( - opts: SpawnOptions & { question: string; role?: string; outputFile: string }, -): Promise { - const subagentRole: SubagentRole = "scout"; - const log = opts.log ?? createLogger("Subagent"); - const modelOverride = opts.modelOverride ?? await resolveModelForRole(subagentRole); - const prompt = [ - opts.question, - opts.role ? `Your investigator role: ${opts.role}` : "", - `Write your findings to: ${opts.outputFile}`, - ].filter(Boolean).join("\n"); - return spawnSubagent(subagentRole, prompt, { ...opts, modelOverride }, log); -} - -// Decomposer: splits the epic into stories. -export async function spawnDecomposer(opts: SpawnOptions): Promise { - const role: SubagentRole = "decomposer"; - const log = opts.log ?? createLogger("Subagent"); - const modelOverride = opts.modelOverride ?? await resolveModelForRole(role); - const scoutContext = makeScoutSpawnContext(opts, log); - return spawnSubagent( - role, - "Begin the decomposition phase.", - { ...opts, modelOverride, scoutContext }, - log, - ); -} - -// Orchestrator: pre-execution or post-execution decision making. -export async function spawnOrchestrator( - opts: SpawnOptions & { stepSequence: StepSequence; storyId?: string }, -): Promise { - const role: SubagentRole = "orchestrator"; - const log = opts.log ?? createLogger("Subagent"); - const modelOverride = opts.modelOverride ?? await resolveModelForRole(role); - const extraFlags: string[] = ["--koan-step-sequence", opts.stepSequence]; - if (opts.storyId) { - extraFlags.push("--koan-story-id", opts.storyId); - } - const prompt = `Begin the ${opts.stepSequence} orchestrator phase.`; - return spawnSubagent( - role, - prompt, - { ...opts, extraFlags, modelOverride }, - log, - ); -} - -// Planner: produces a detailed plan for a story. -export async function spawnPlanner(opts: SpawnStoryOptions): Promise { - const role: SubagentRole = "planner"; - const log = opts.log ?? createLogger("Subagent"); - const modelOverride = opts.modelOverride ?? await resolveModelForRole(role); - const extraFlags: string[] = ["--koan-story-id", opts.storyId]; - const scoutContext = makeScoutSpawnContext(opts, log); - const prompt = `Begin the planning phase for story ${opts.storyId}.`; - return spawnSubagent( - role, - prompt, - { ...opts, extraFlags, modelOverride, scoutContext }, - log, - ); -} - -// Executor: implements a story plan. -export async function spawnExecutor( - opts: SpawnStoryOptions & { retryContext?: string }, -): Promise { - const role: SubagentRole = "executor"; - const log = opts.log ?? createLogger("Subagent"); - const modelOverride = opts.modelOverride ?? await resolveModelForRole(role); - const extraFlags: string[] = ["--koan-story-id", opts.storyId]; - if (opts.retryContext) { - extraFlags.push("--koan-retry-context", opts.retryContext); - } - const basePrompt = `Implement the plan for story ${opts.storyId}.`; - const prompt = opts.retryContext - ? `${basePrompt}\n\nPrevious attempt failed: ${opts.retryContext}` - : basePrompt; - return spawnSubagent( - role, - prompt, - { ...opts, extraFlags, modelOverride }, - log, - ); -} From 2e6be1206342a65a0a19938bb484f9081baf1433 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:49:05 +0700 Subject: [PATCH 058/412] rewrite phase dispatch to read from task manifest --- src/planner/phases/dispatch.ts | 99 ++++++++++++---------------------- 1 file changed, 34 insertions(+), 65 deletions(-) diff --git a/src/planner/phases/dispatch.ts b/src/planner/phases/dispatch.ts index b880cc0..5bc63f5 100644 --- a/src/planner/phases/dispatch.ts +++ b/src/planner/phases/dispatch.ts @@ -1,14 +1,15 @@ -// Phase dispatch: detects subagent mode from CLI flags and routes to the -// appropriate phase class based on role. Flags are unavailable at extension -// init (getFlag returns undefined before _buildRuntime), so detection is -// deferred to before_agent_start. +// Phase dispatch: routes a SubagentTask to the appropriate phase class. +// +// Called from koan.ts after readTaskFile() resolves the task manifest. +// There is no flag-parsing here — all task parameters come from task.json. +import * as path from "node:path"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { createLogger, type Logger } from "../../utils/logger.js"; import type { RuntimeContext } from "../lib/runtime-context.js"; import type { EventLog } from "../lib/audit.js"; -import type { SubagentRole, StepSequence } from "../types.js"; +import type { SubagentTask } from "../lib/task.js"; import { IntakePhase } from "./intake/phase.js"; import { ScoutPhase } from "./scout/phase.js"; import { DecomposerPhase } from "./decomposer/phase.js"; @@ -16,109 +17,77 @@ import { OrchestratorPhase } from "./orchestrator/phase.js"; import { PlannerPhase } from "./planner/phase.js"; import { ExecutorPhase } from "./executor/phase.js"; -// -- Config -- - -export interface SubagentConfig { - role: SubagentRole; - epicDir: string; - subagentDir: string; - storyId: string | null; - stepSequence: StepSequence | null; -} - -// -- Detection -- - -// Detects subagent mode by reading flags set via CLI -// (pi -p --koan-role intake --koan-epic-dir /path ...). -// Must be called from before_agent_start or later; flags are -// undefined before _buildRuntime() runs. -export function detectSubagentMode(pi: ExtensionAPI): SubagentConfig | null { - const role = pi.getFlag("koan-role"); - if (!role || typeof role !== "string" || role.trim().length === 0) { - return null; - } - - const epicDir = pi.getFlag("koan-epic-dir"); - const subagentDir = pi.getFlag("koan-subagent-dir"); - const storyId = pi.getFlag("koan-story-id"); - const stepSequence = pi.getFlag("koan-step-sequence"); - - return { - role: role.trim() as SubagentRole, - epicDir: typeof epicDir === "string" ? epicDir.trim() : "", - subagentDir: typeof subagentDir === "string" ? subagentDir.trim() : "", - storyId: typeof storyId === "string" && storyId.trim().length > 0 ? storyId.trim() : null, - stepSequence: typeof stepSequence === "string" && stepSequence.trim().length > 0 - ? stepSequence.trim() as StepSequence - : null, - }; -} - -// -- Dispatch -- - export async function dispatchPhase( pi: ExtensionAPI, - config: SubagentConfig, + task: SubagentTask, ctx: RuntimeContext, log?: Logger, eventLog?: EventLog, ): Promise { const logger = log ?? createLogger("Dispatch"); - switch (config.role) { + switch (task.role) { case "intake": { - const phase = new IntakePhase(pi, { epicDir: config.epicDir }, ctx, logger, eventLog); + const phase = new IntakePhase(pi, { epicDir: task.epicDir }, ctx, logger, eventLog); await phase.begin(); break; } + case "scout": { - const phase = new ScoutPhase(pi, { epicDir: config.epicDir }, ctx, logger, eventLog); + // outputFile is relative to subagentDir in the task manifest. + // ScoutPhase receives the resolved absolute path. + const phase = new ScoutPhase(pi, { + epicDir: task.epicDir, + question: task.question, + outputFile: path.join(ctx.subagentDir!, task.outputFile), + investigatorRole: task.investigatorRole, + }, ctx, logger, eventLog); await phase.begin(); break; } + case "decomposer": { - const phase = new DecomposerPhase(pi, { epicDir: config.epicDir }, ctx, logger, eventLog); + const phase = new DecomposerPhase(pi, { epicDir: task.epicDir }, ctx, logger, eventLog); await phase.begin(); break; } + case "orchestrator": { - const stepSequence = config.stepSequence ?? "pre-execution"; const phase = new OrchestratorPhase( pi, - { epicDir: config.epicDir, stepSequence, storyId: config.storyId ?? undefined }, + { epicDir: task.epicDir, stepSequence: task.stepSequence, storyId: task.storyId }, ctx, logger, eventLog, ); await phase.begin(); break; } + case "planner": { - // Fail-fast: missing storyId produces malformed paths like stories//plan/plan.md (§12.4.3). - if (!config.storyId) throw new Error("planner phase requires --koan-story-id flag"); const phase = new PlannerPhase( pi, - { epicDir: config.epicDir, storyId: config.storyId }, + { epicDir: task.epicDir, storyId: task.storyId }, ctx, logger, eventLog, ); await phase.begin(); break; } + case "executor": { - // Fail-fast: missing storyId produces malformed paths like stories//plan/plan.md (§12.4.3). - if (!config.storyId) throw new Error("executor phase requires --koan-story-id flag"); - const retryContext = pi.getFlag("koan-retry-context"); const phase = new ExecutorPhase( pi, - { - epicDir: config.epicDir, - storyId: config.storyId, - retryContext: typeof retryContext === "string" && retryContext.length > 0 ? retryContext : undefined, - }, + { epicDir: task.epicDir, storyId: task.storyId, retryContext: task.retryContext }, ctx, logger, eventLog, ); await phase.begin(); break; } - default: - logger("Unknown role", { role: config.role }); + + default: { + // TypeScript narrows task to `never` here — this branch is unreachable + // when all roles are covered above. + const exhaustive: never = task; + logger("Unrecognized role in task manifest", { role: (exhaustive as { role: string }).role }); + break; + } } } From 44403036c05f1cd1fc10581b9ed19de12d1c7ff6 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:49:15 +0700 Subject: [PATCH 059/412] route IPC responder through web server instead of TUI --- src/planner/lib/ipc-responder.ts | 201 ++++++++++++++++++------------- 1 file changed, 114 insertions(+), 87 deletions(-) diff --git a/src/planner/lib/ipc-responder.ts b/src/planner/lib/ipc-responder.ts index bf9c31a..7d55cee 100644 --- a/src/planner/lib/ipc-responder.ts +++ b/src/planner/lib/ipc-responder.ts @@ -2,29 +2,30 @@ // handles them, and writes responses back. Runs concurrently with subagent // process execution and terminates when the provided AbortSignal fires. // -// Supports two request types (§11.2.4): -// "ask" → render ask UI, write answer back +// Supports two request types: +// "ask" → route to web server, write answer back // "scout-request" → spawn scouts via pool(), write findings paths back import { promises as fs } from "node:fs"; import * as path from "node:path"; -import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; - import { readIpcFile, writeIpcFile, createAskResponse, createCancelledResponse, type AskAnswerPayload, - type ScoutTask, type AskIpcFile, type ScoutIpcFile, } from "./ipc.js"; +// ipc.ts exports ScoutTask (IPC-level: id/role/prompt for the LLM-facing request); +// task.ts also exports ScoutTask (manifest-level: role/epicDir/question/outputFile/investigatorRole). +// Aliased here to avoid shadowing the ipc.ts type used by ScoutIpcFile fields. +import type { ScoutTask as TaskScoutTask } from "./task.js"; import { pool } from "./pool.js"; -import { askSingleQuestionWithInlineNote } from "../ui/ask/ask-inline-ui.js"; -import { askQuestionsWithTabs } from "../ui/ask/ask-tabs-ui.js"; -import type { AskQuestion, AskSelection } from "../ui/ask/ask-logic.js"; +import { readProjection } from "./audit.js"; +import type { WebServerHandle, AskQuestion, AnswerResult } from "../web/server-types.js"; +import { OTHER_OPTION } from "../web/server-types.js"; const POLL_INTERVAL_MS = 300; @@ -32,91 +33,81 @@ function sleep(ms: number): Promise { return new Promise((resolve) => setTimeout(resolve, ms)); } -// Provided by subagent.ts when starting the IPC responder. Avoids circular -// imports: ipc-responder.ts never imports from subagent.ts. +/** + * Provided by subagent.ts when starting the IPC responder. Avoids circular + * imports: ipc-responder.ts never imports from subagent.ts. + * + * `spawnScout` does not accept an `outputFile` argument — the output path is + * part of the task manifest (task.json). The responder writes `outputFile` + * into the ScoutTask before handing it to `spawnScout`, then resolves the + * absolute path via `path.join(subagentDir, scoutTask.outputFile)` itself. + */ export interface ScoutSpawnContext { epicDir: string; + // The role of the subagent that requested scouting (intake, decomposer, planner). + // Used for UI attribution when registering scouts with the web server. + parentRole: string; // Spawns a single scout; returns exit code. - spawnScout: (task: ScoutTask, scoutSubagentDir: string, outputFile: string) => Promise; + spawnScout: (task: TaskScoutTask, scoutSubagentDir: string) => Promise; } -// Handles a pending ask request: renders UI, writes response. +// Handles a pending ask request: routes to web server, writes response. async function handleAskRequest( subagentDir: string, ipc: AskIpcFile, - ui: ExtensionUIContext, + webServer: WebServerHandle, signal: AbortSignal, ): Promise { const { payload } = ipc; const questions: AskQuestion[] = payload.questions.map((q) => ({ id: q.id, question: q.question, - options: q.options, + options: q.options.map((o) => ({ label: o.label })), multi: q.multi, recommended: q.recommended, })); - let cancelled = false; - let answers: AskAnswerPayload["answers"] = []; - - if (questions.length === 1) { - const q = questions[0]; - const selection = await askSingleQuestionWithInlineNote(ui, { - question: q.question, - options: q.options, - recommended: q.recommended, - }); - - // ask UI components do not accept an AbortSignal — they block until the - // user interacts even after the subagent exits. Check after return to - // prevent writing a stale answer to a dead subagent's IPC file. - if (signal.aborted) { - const current = await readIpcFile(subagentDir); - if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { - await writeIpcFile(subagentDir, { ...current, response: createCancelledResponse(ipc.id) }); - } - return; - } - - cancelled = selection.selectedOptions.length === 0 && !selection.customInput; - if (!cancelled) { - answers = [{ - id: q.id, - selectedOptions: selection.selectedOptions, - customInput: selection.customInput, - }]; - } - } else { - const result = await askQuestionsWithTabs(ui, questions); + // Append "Other" option to each question before presenting to the user. + const withOther: AskQuestion[] = questions.map((q) => ({ + ...q, + options: [...q.options, { label: OTHER_OPTION }], + })); - if (signal.aborted) { + let result: AnswerResult; + try { + result = await webServer.requestAnswer(withOther, signal); + } catch (err: unknown) { + if (err instanceof Error && (err.name === "AbortError" || signal.aborted)) { const current = await readIpcFile(subagentDir); if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { await writeIpcFile(subagentDir, { ...current, response: createCancelledResponse(ipc.id) }); } return; } + throw err; + } - cancelled = result.cancelled; - if (!cancelled) { - answers = questions.map((q, i) => { - const sel: AskSelection = result.selections[i] ?? { selectedOptions: [] }; - const entry: AskAnswerPayload["answers"][number] = { - id: q.id, - selectedOptions: sel.selectedOptions, - }; - if (sel.customInput !== undefined) { - entry.customInput = sel.customInput; - } - return entry; - }); + if (result.cancelled) { + const current = await readIpcFile(subagentDir); + if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { + await writeIpcFile(subagentDir, { ...current, response: createCancelledResponse(ipc.id) }); } + return; } - const response = cancelled - ? createCancelledResponse(ipc.id) - : createAskResponse(ipc.id, { answers }); + const answers: AskAnswerPayload["answers"] = result.answers.map((a) => { + const entry: AskAnswerPayload["answers"][number] = { + id: a.questionId, + selectedOptions: a.selectedOptions, + }; + if (a.customInput !== undefined) { + entry.customInput = a.customInput; + } + return entry; + }); + const response = createAskResponse(ipc.id, { answers }); + // Re-read and validate before writing — idempotence guard against stale requests. const current = await readIpcFile(subagentDir); if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { await writeIpcFile(subagentDir, { ...current, response }); @@ -128,40 +119,82 @@ async function handleScoutRequest( subagentDir: string, ipc: ScoutIpcFile, scoutCtx: ScoutSpawnContext, + webServer: WebServerHandle | undefined, signal: AbortSignal, ): Promise { - const { scouts, id } = ipc; - const { epicDir } = scoutCtx; + const { scouts: ipcScouts, id } = ipc; const findings: string[] = []; const failures: string[] = []; - // Each scout writes to ${subagentDir}/output.md — output is scoped to the - // scout's own directory, avoiding collisions. Compute subagentDir once and - // derive outputFile from it (never call Date.now() twice for the same entry). - const scoutEntries = scouts.map((task) => { - const scoutDir = path.join(epicDir, "subagents", `scout-${task.id}-${Date.now()}`); - return { task, subagentDir: scoutDir, outputFile: path.join(scoutDir, "output.md") }; + // Compute per-scout directories. Scout dirs live under the epic's subagents/ + // directory so they appear in the standard directory layout. + const scoutEntries = ipcScouts.map((ipcTask) => { + const scoutDir = path.join(scoutCtx.epicDir, "subagents", `scout-${ipcTask.id}-${Date.now()}`); + return { ipcTask, subagentDir: scoutDir }; }); - const taskIds = scoutEntries.map((t) => t.task.id); + // Register scouts with the web server before spawning so the UI shows them + // immediately rather than waiting for the first audit poll. + if (webServer) { + for (const entry of scoutEntries) { + webServer.registerAgent({ + id: entry.ipcTask.id, + name: entry.ipcTask.id, + dir: entry.subagentDir, + role: "scout", + model: null, + parent: scoutCtx.parentRole, + }); + } + } + + const taskIds = scoutEntries.map((t) => t.ipcTask.id); await pool( taskIds, - 4, // up to 4 concurrent scouts + 4, async (taskId) => { if (signal.aborted) return { exitCode: 1, stderr: "aborted", subagentDir: "" }; - const entry = scoutEntries.find((t) => t.task.id === taskId)!; + + const entry = scoutEntries.find((t) => t.ipcTask.id === taskId)!; await fs.mkdir(entry.subagentDir, { recursive: true }); - const exitCode = await scoutCtx.spawnScout(entry.task, entry.subagentDir, entry.outputFile); + + // Construct the task manifest for this scout. The IPC-level ipcTask carries + // id/role/prompt (LLM-facing); the task manifest carries the full SubagentTask + // fields the scout process needs. + const scoutTask: TaskScoutTask = { + role: "scout", + epicDir: scoutCtx.epicDir, + question: entry.ipcTask.prompt, + outputFile: "findings.md", // relative — ScoutPhase resolves to absolute + investigatorRole: entry.ipcTask.role, + }; + + const exitCode = await scoutCtx.spawnScout(scoutTask, entry.subagentDir); + + // Derive success from the JSON audit projection, not from file existence. + // A scout can write a partial findings.md and then crash. + let succeeded = false; if (exitCode === 0) { - findings.push(entry.outputFile); + const projection = await readProjection(entry.subagentDir); + succeeded = projection?.status === "completed"; + } + + const absoluteOutputFile = path.join(entry.subagentDir, scoutTask.outputFile); + if (succeeded) { + findings.push(absoluteOutputFile); } else { failures.push(taskId); } + + if (webServer) { + webServer.completeAgent(taskId); + } + return { exitCode, stderr: "", subagentDir: entry.subagentDir }; }, ); - // Write response back to the ipc file. + // Re-read and validate before writing response — idempotence guard. const current = await readIpcFile(subagentDir); if (current !== null && current.type === "scout-request" && current.response === null && current.id === id) { const updated: ScoutIpcFile = { ...current, response: { findings, failures } }; @@ -169,13 +202,9 @@ async function handleScoutRequest( } } -// Runs the parent-side IPC poll loop for a single subagent directory. -// Routes to ask UI or scout spawning based on request type. -// Terminates when `signal` is aborted. Errors are swallowed — transient -// filesystem issues must not crash the parent session. export async function runIpcResponder( subagentDir: string, - ui: ExtensionUIContext, + webServer: WebServerHandle, signal: AbortSignal, scoutContext?: ScoutSpawnContext, ): Promise { @@ -188,14 +217,12 @@ export async function runIpcResponder( if (ipc === null || ipc.response !== null) continue; if (ipc.type === "ask") { - await handleAskRequest(subagentDir, ipc, ui, signal); + await handleAskRequest(subagentDir, ipc, webServer, signal); } else if (ipc.type === "scout-request" && scoutContext) { - await handleScoutRequest(subagentDir, ipc, scoutContext, signal); + await handleScoutRequest(subagentDir, ipc, scoutContext, webServer, signal); } - // Unknown type: ignore (forward-compatibility) } catch { - // Swallow all errors — transient filesystem or UI issues must not - // abort the parent session. + // Swallow all errors — transient filesystem issues must not abort the parent session. } } } From 26467a8442116abb166fd620ac1e46104a3abf12 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:49:22 +0700 Subject: [PATCH 060/412] replace TUI widget with web server in pipeline driver --- src/planner/driver.ts | 492 ++++++++++++++++++------------------------ 1 file changed, 206 insertions(+), 286 deletions(-) diff --git a/src/planner/driver.ts b/src/planner/driver.ts index 5d03543..0216637 100644 --- a/src/planner/driver.ts +++ b/src/planner/driver.ts @@ -1,8 +1,14 @@ // Epic pipeline driver — deterministic coordinator for the full epic lifecycle. // Reads JSON state and exit codes; applies routing rules. Never parses markdown. // Per AGENTS.md: driver owns .json state; LLMs own .md files. +// +// Spawn pattern used throughout: spawnSubagent(task, subagentDir, opts). +// epicDir is part of the task (written to task.json) rather than SpawnOptions +// because it is subagent configuration, not process infrastructure. SpawnOptions +// holds only what the OS-level spawn needs: cwd, extensionPath, model, webServer. -import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent"; +import { promises as fs } from "node:fs"; +import * as path from "node:path"; import { loadEpicState, @@ -14,18 +20,29 @@ import { ensureStoryDirectory, discoverStoryIds, } from "./epic/state.js"; -import { - spawnIntake, - spawnDecomposer, - spawnOrchestrator, - spawnPlanner, - spawnExecutor, -} from "./subagent.js"; +import { spawnSubagent, type SpawnOptions } from "./subagent.js"; import type { Logger } from "../utils/logger.js"; import type { StoryState } from "./epic/types.js"; -import { readRecentLogs, readProjection } from "./lib/audit.js"; -import { EpicWidgetController } from "./ui/epic-widget.js"; -import { reviewStorySketches } from "./ui/spec-review.js"; +import type { WebServerHandle, ReviewStory } from "./web/server-types.js"; + +// --------------------------------------------------------------------------- +// readStoryTitle +// --------------------------------------------------------------------------- + +async function readStoryTitle(epicDir: string, storyId: string): Promise { + try { + const raw = await fs.readFile(path.join(epicDir, "stories", storyId, "story.md"), "utf8"); + for (const rawLine of raw.split("\n")) { + const l = rawLine.trim(); + if (!l) continue; + const text = l.replace(/^#+\s*/, "").trim(); + if (text) return text.slice(0, 80); + } + return storyId; + } catch { + return storyId; + } +} // --------------------------------------------------------------------------- // Routing @@ -37,15 +54,9 @@ interface RoutingDecision { error?: string; } -// Simplified routing — no escalation path per §11.3.1 and §11.6.3. -// Retry budget exhaustion is handled inside the retry case (skip + notify). function routeFromState(stories: StoryState[], log: Logger): RoutingDecision { - // Priority order: - // 1. Any story with status 'retry'? → check budget, then re-execute or skip - // 2. Any story with status 'selected'? → execute it - // 3. All stories terminal? → complete - // 4. None of the above → error - + // retry is checked before selected — a story queued for retry takes + // precedence over a newly selected story. const retry = stories.find((s) => s.status === "retry"); if (retry) { log("Routing: retry", { storyId: retry.storyId }); @@ -58,6 +69,7 @@ function routeFromState(stories: StoryState[], log: Logger): RoutingDecision { return { action: "execute", storyId: selected.storyId }; } + // Terminal states are exactly "done" and "skipped". const terminal = new Set(["done", "skipped"]); const allTerminal = stories.every((s) => terminal.has(s.status)); if (allTerminal && stories.length > 0) { @@ -71,47 +83,6 @@ function routeFromState(stories: StoryState[], log: Logger): RoutingDecision { }; } -// --------------------------------------------------------------------------- -// Active widget polling (§11.6.1) -// --------------------------------------------------------------------------- - -// Starts a 2s polling interval that reads the active subagent's projection -// and log tail, then updates the widget. Interval is unref'd so it does not -// prevent process exit. -function startActivePolling( - activeSubagentDir: string, - widget: EpicWidgetController, - startedAt: number, - role: string, - storyId?: string, -): () => void { - const timer = setInterval(async () => { - try { - const [projection, logs] = await Promise.all([ - readProjection(activeSubagentDir), - readRecentLogs(activeSubagentDir), - ]); - widget.update({ logLines: logs }); - if (projection) { - widget.update({ - activeSubagent: { - role, - storyId, - step: projection.step, - totalSteps: projection.totalSteps, - stepName: projection.stepName, - startedAt, - }, - }); - } - } catch { - // Non-fatal — polling is best-effort. - } - }, 2000); - timer.unref(); - return () => clearInterval(timer); -} - // --------------------------------------------------------------------------- // Phase A helpers // --------------------------------------------------------------------------- @@ -121,22 +92,20 @@ async function runIntake( cwd: string, extensionPath: string, log: Logger, - ui: ExtensionUIContext | null, - widget: EpicWidgetController | null, + webServer: WebServerHandle | null, ): Promise { const subagentDir = await ensureSubagentDirectory(epicDir, "intake"); - const startedAt = Date.now(); - let stopPolling: (() => void) | undefined; - if (widget) { - widget.update({ activeSubagent: { role: "intake", step: 0, totalSteps: 3, stepName: "", startedAt } }); - stopPolling = startActivePolling(subagentDir, widget, startedAt, "intake"); - } - const result = await spawnIntake({ epicDir, subagentDir, cwd, extensionPath, log, ui: ui ?? undefined }); - stopPolling?.(); - if (widget) { - const logs = await readRecentLogs(subagentDir); - widget.update({ logLines: logs, activeSubagent: null }); - } + webServer?.registerAgent({ id: "intake", name: "intake", dir: subagentDir, role: "intake", model: null, parent: null }); + webServer?.trackSubagent(subagentDir, "intake"); + + const result = await spawnSubagent( + { role: "intake", epicDir }, + subagentDir, + { cwd, extensionPath, log, webServer: webServer ?? undefined }, + ); + + webServer?.clearSubagent(); + webServer?.completeAgent("intake"); if (result.exitCode !== 0) { log("Intake failed", { exitCode: result.exitCode }); return false; @@ -149,22 +118,20 @@ async function runDecomposer( cwd: string, extensionPath: string, log: Logger, - ui: ExtensionUIContext | null, - widget: EpicWidgetController | null, + webServer: WebServerHandle | null, ): Promise { const subagentDir = await ensureSubagentDirectory(epicDir, "decomposer"); - const startedAt = Date.now(); - let stopPolling: (() => void) | undefined; - if (widget) { - widget.update({ activeSubagent: { role: "decomposer", step: 0, totalSteps: 2, stepName: "", startedAt } }); - stopPolling = startActivePolling(subagentDir, widget, startedAt, "decomposer"); - } - const result = await spawnDecomposer({ epicDir, subagentDir, cwd, extensionPath, log, ui: ui ?? undefined }); - stopPolling?.(); - if (widget) { - const logs = await readRecentLogs(subagentDir); - widget.update({ logLines: logs, activeSubagent: null }); - } + webServer?.registerAgent({ id: "decomposer", name: "decomposer", dir: subagentDir, role: "decomposer", model: null, parent: null }); + webServer?.trackSubagent(subagentDir, "decomposer"); + + const result = await spawnSubagent( + { role: "decomposer", epicDir }, + subagentDir, + { cwd, extensionPath, log, webServer: webServer ?? undefined }, + ); + + webServer?.clearSubagent(); + webServer?.completeAgent("decomposer"); if (result.exitCode !== 0) { log("Decomposer failed", { exitCode: result.exitCode }); return false; @@ -182,88 +149,61 @@ async function runStoryExecution( extensionPath: string, storyId: string, log: Logger, - ui: ExtensionUIContext | null, - widget: EpicWidgetController | null, + webServer: WebServerHandle | null, ): Promise { + const opts: SpawnOptions = { cwd, extensionPath, log, webServer: webServer ?? undefined }; + // 1. Set status to 'planning'. const story = await loadStoryState(epicDir, storyId); - await saveStoryState(epicDir, storyId, { - ...story, - status: "planning", - updatedAt: new Date().toISOString(), - }); + await saveStoryState(epicDir, storyId, { ...story, status: "planning", updatedAt: new Date().toISOString() }); // 2. Spawn planner. const plannerDir = await ensureSubagentDirectory(epicDir, `planner-${storyId}`); - const plannerStarted = Date.now(); - let stopPolling: (() => void) | undefined; - if (widget) { - widget.update({ - activeSubagent: { role: "planner", storyId, step: 0, totalSteps: 3, stepName: "", startedAt: plannerStarted }, - }); - stopPolling = startActivePolling(plannerDir, widget, plannerStarted, "planner", storyId); - } + const plannerId = `planner-${storyId}`; + webServer?.registerAgent({ id: plannerId, name: `planner-${storyId}`, dir: plannerDir, role: "planner", model: null, parent: null }); + webServer?.trackSubagent(plannerDir, "planner", storyId); - const planResult = await spawnPlanner({ epicDir, subagentDir: plannerDir, cwd, extensionPath, storyId, log, ui: ui ?? undefined }); - stopPolling?.(); + const planResult = await spawnSubagent({ role: "planner", epicDir, storyId }, plannerDir, opts); - if (widget) { - const logs = await readRecentLogs(plannerDir); - widget.update({ logLines: logs }); - } + webServer?.clearSubagent(); + webServer?.completeAgent(plannerId); if (planResult.exitCode !== 0) { + // Planner failed — skip executor, proceed directly to post-execution + // orchestrator so it can make a routing decision (retry or skip). log("Planner failed — skipping executor, proceeding to post-execution orchestrator", { storyId, exitCode: planResult.exitCode, }); const s2 = await loadStoryState(epicDir, storyId); - await saveStoryState(epicDir, storyId, { - ...s2, - status: "verifying", - updatedAt: new Date().toISOString(), - }); + await saveStoryState(epicDir, storyId, { ...s2, status: "verifying", updatedAt: new Date().toISOString() }); const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}`); - const orchStarted = Date.now(); - if (widget) { - widget.update({ activeSubagent: { role: "orchestrator", storyId, step: 0, totalSteps: 4, stepName: "", startedAt: orchStarted } }); - stopPolling = startActivePolling(postDir, widget, orchStarted, "orchestrator", storyId); - } + const postId = `orchestrator-post-${storyId}`; + webServer?.registerAgent({ id: postId, name: `orchestrator-post-${storyId}`, dir: postDir, role: "orchestrator", model: null, parent: null }); + webServer?.trackSubagent(postDir, "orchestrator", storyId); - await spawnOrchestrator({ epicDir, subagentDir: postDir, cwd, extensionPath, stepSequence: "post-execution", storyId, log, ui: ui ?? undefined }); - stopPolling?.(); + await spawnSubagent({ role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, opts); - if (widget) { - const logs = await readRecentLogs(postDir); - widget.update({ logLines: logs }); - } + webServer?.clearSubagent(); + webServer?.completeAgent(postId); return; } // 3. Set status to 'executing'. const s3 = await loadStoryState(epicDir, storyId); - await saveStoryState(epicDir, storyId, { - ...s3, - status: "executing", - updatedAt: new Date().toISOString(), - }); + await saveStoryState(epicDir, storyId, { ...s3, status: "executing", updatedAt: new Date().toISOString() }); // 4. Spawn executor. const execDir = await ensureSubagentDirectory(epicDir, `executor-${storyId}`); - const execStarted = Date.now(); - if (widget) { - widget.update({ activeSubagent: { role: "executor", storyId, step: 0, totalSteps: 2, stepName: "", startedAt: execStarted } }); - stopPolling = startActivePolling(execDir, widget, execStarted, "executor", storyId); - } + const execId = `executor-${storyId}`; + webServer?.registerAgent({ id: execId, name: `executor-${storyId}`, dir: execDir, role: "executor", model: null, parent: null }); + webServer?.trackSubagent(execDir, "executor", storyId); - const execResult = await spawnExecutor({ epicDir, subagentDir: execDir, cwd, extensionPath, storyId, log, ui: ui ?? undefined }); - stopPolling?.(); + const execResult = await spawnSubagent({ role: "executor", epicDir, storyId }, execDir, opts); - if (widget) { - const logs = await readRecentLogs(execDir); - widget.update({ logLines: logs }); - } + webServer?.clearSubagent(); + webServer?.completeAgent(execId); if (execResult.exitCode !== 0) { log("Executor failed", { storyId, exitCode: execResult.exitCode }); @@ -271,33 +211,20 @@ async function runStoryExecution( // 5. Set status to 'verifying'. const s4 = await loadStoryState(epicDir, storyId); - await saveStoryState(epicDir, storyId, { - ...s4, - status: "verifying", - updatedAt: new Date().toISOString(), - }); + await saveStoryState(epicDir, storyId, { ...s4, status: "verifying", updatedAt: new Date().toISOString() }); - // 6. Spawn orchestrator (post-execution) — writes verdict to story state. + // 6. Spawn orchestrator (post-execution). const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}`); - const orchStarted = Date.now(); - if (widget) { - widget.update({ activeSubagent: { role: "orchestrator", storyId, step: 0, totalSteps: 4, stepName: "", startedAt: orchStarted } }); - stopPolling = startActivePolling(postDir, widget, orchStarted, "orchestrator", storyId); - } + const postId = `orchestrator-post-${storyId}`; + webServer?.registerAgent({ id: postId, name: `orchestrator-post-${storyId}`, dir: postDir, role: "orchestrator", model: null, parent: null }); + webServer?.trackSubagent(postDir, "orchestrator", storyId); - await spawnOrchestrator({ epicDir, subagentDir: postDir, cwd, extensionPath, stepSequence: "post-execution", storyId, log, ui: ui ?? undefined }); - stopPolling?.(); + await spawnSubagent({ role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, opts); - if (widget) { - const logs = await readRecentLogs(postDir); - widget.update({ logLines: logs }); - } + webServer?.clearSubagent(); + webServer?.completeAgent(postId); } -// retryCount is the 1-based retry attempt number (1 for first retry, 2 for -// second, etc.). It is included in directory names so each retry gets its own -// isolated stdout.log and events.jsonl, preventing directory collision when -// DEFAULT_MAX_RETRIES > 1. async function runStoryReexecution( epicDir: string, cwd: string, @@ -306,54 +233,42 @@ async function runStoryReexecution( retryCount: number, failureContext: string | undefined, log: Logger, - ui: ExtensionUIContext | null, - widget: EpicWidgetController | null, + webServer: WebServerHandle | null, ): Promise { + const opts: SpawnOptions = { cwd, extensionPath, log, webServer: webServer ?? undefined }; + const execDir = await ensureSubagentDirectory(epicDir, `executor-${storyId}-retry-${retryCount}`); - const execStarted = Date.now(); - let stopPolling: (() => void) | undefined; - if (widget) { - widget.update({ activeSubagent: { role: "executor", storyId, step: 0, totalSteps: 2, stepName: "retry", startedAt: execStarted } }); - stopPolling = startActivePolling(execDir, widget, execStarted, "executor", storyId); - } + const execId = `executor-${storyId}-retry-${retryCount}`; + webServer?.registerAgent({ id: execId, name: `executor-${storyId}-retry-${retryCount}`, dir: execDir, role: "executor", model: null, parent: null }); + webServer?.trackSubagent(execDir, "executor", storyId); - await spawnExecutor({ epicDir, subagentDir: execDir, cwd, extensionPath, storyId, retryContext: failureContext, log, ui: ui ?? undefined }); - stopPolling?.(); + // retryContext flows from koan_retry_story's failure_summary into the task + // manifest, where the executor reads it from step 1 guidance. + await spawnSubagent({ role: "executor", epicDir, storyId, retryContext: failureContext }, execDir, opts); - if (widget) { - const logs = await readRecentLogs(execDir); - widget.update({ logLines: logs }); - } + webServer?.clearSubagent(); + webServer?.completeAgent(execId); const story = await loadStoryState(epicDir, storyId); - await saveStoryState(epicDir, storyId, { - ...story, - status: "verifying", - updatedAt: new Date().toISOString(), - }); + await saveStoryState(epicDir, storyId, { ...story, status: "verifying", updatedAt: new Date().toISOString() }); const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}-retry-${retryCount}`); - const orchStarted = Date.now(); - if (widget) { - widget.update({ activeSubagent: { role: "orchestrator", storyId, step: 0, totalSteps: 4, stepName: "", startedAt: orchStarted } }); - stopPolling = startActivePolling(postDir, widget, orchStarted, "orchestrator", storyId); - } + const postId = `orchestrator-post-${storyId}-retry-${retryCount}`; + webServer?.registerAgent({ id: postId, name: `orchestrator-post-${storyId}-retry-${retryCount}`, dir: postDir, role: "orchestrator", model: null, parent: null }); + webServer?.trackSubagent(postDir, "orchestrator", storyId); - await spawnOrchestrator({ epicDir, subagentDir: postDir, cwd, extensionPath, stepSequence: "post-execution", storyId, log, ui: ui ?? undefined }); - stopPolling?.(); + await spawnSubagent({ role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, opts); - if (widget) { - const logs = await readRecentLogs(postDir); - widget.update({ logLines: logs }); - } + webServer?.clearSubagent(); + webServer?.completeAgent(postId); } -async function refreshWidgetStories(epicDir: string, widget: EpicWidgetController): Promise { +async function refreshWebServerStories(epicDir: string, webServer: WebServerHandle): Promise { try { const stories = await loadAllStoryStates(epicDir); - widget.update({ stories: stories.map((s) => ({ storyId: s.storyId, status: s.status })) }); + webServer.pushStories(stories.map((s) => ({ storyId: s.storyId, status: s.status }))); } catch { - // Non-fatal — widget update is best-effort. + // Non-fatal } } @@ -362,43 +277,42 @@ async function runStoryLoop( cwd: string, extensionPath: string, log: Logger, - ui: ExtensionUIContext | null, - widget: EpicWidgetController | null, + webServer: WebServerHandle | null, ): Promise<{ success: boolean; summary: string }> { { - - // 2. Spawn orchestrator (pre-execution) — selects first story. + // 1. Spawn orchestrator (pre-execution) — selects first story. const preDir = await ensureSubagentDirectory(epicDir, "orchestrator-pre"); - const preStarted = Date.now(); - let stopPolling: (() => void) | undefined; - if (widget) { - widget.update({ activeSubagent: { role: "orchestrator", step: 0, totalSteps: 2, stepName: "pre-execution", startedAt: preStarted } }); - stopPolling = startActivePolling(preDir, widget, preStarted, "orchestrator"); - } + const preId = "orchestrator-pre"; + webServer?.registerAgent({ id: preId, name: "orchestrator-pre", dir: preDir, role: "orchestrator", model: null, parent: null }); + webServer?.trackSubagent(preDir, "orchestrator"); + + const preResult = await spawnSubagent( + { role: "orchestrator", epicDir, stepSequence: "pre-execution" }, + preDir, + { cwd, extensionPath, log, webServer: webServer ?? undefined }, + ); - const preResult = await spawnOrchestrator({ epicDir, subagentDir: preDir, cwd, extensionPath, stepSequence: "pre-execution", log, ui: ui ?? undefined }); - stopPolling?.(); + webServer?.clearSubagent(); + webServer?.completeAgent(preId); if (preResult.exitCode !== 0) { return { success: false, summary: "Pre-execution orchestrator failed" }; } - if (widget) await refreshWidgetStories(epicDir, widget); + if (webServer) await refreshWebServerStories(epicDir, webServer); - // 3. Story execution loop — route until terminal state. + // 2. Story execution loop — route until terminal state. while (true) { const stories = await loadAllStoryStates(epicDir); - if (widget) { - widget.update({ stories: stories.map((s) => ({ storyId: s.storyId, status: s.status })) }); - } + webServer?.pushStories(stories.map((s) => ({ storyId: s.storyId, status: s.status }))); const routing = routeFromState(stories, log); switch (routing.action) { case "execute": { const storyId = routing.storyId as string; - await runStoryExecution(epicDir, cwd, extensionPath, storyId, log, ui, widget); - if (widget) await refreshWidgetStories(epicDir, widget); + await runStoryExecution(epicDir, cwd, extensionPath, storyId, log, webServer); + if (webServer) await refreshWebServerStories(epicDir, webServer); break; } @@ -406,7 +320,6 @@ async function runStoryLoop( const storyId = routing.storyId as string; const story = stories.find((s) => s.storyId === storyId) as StoryState; - // Retry budget exhaustion: skip + notify per §11.6.3. if (story.retryCount >= story.maxRetries) { log("Retry budget exhausted, skipping story", { storyId, retryCount: story.retryCount }); await saveStoryState(epicDir, storyId, { @@ -415,9 +328,11 @@ async function runStoryLoop( skipReason: `Retry budget exhausted after ${story.retryCount} attempt(s). Last failure: ${story.failureSummary ?? "(none recorded)"}`, updatedAt: new Date().toISOString(), }); - ui?.notify(`Story ${storyId} skipped after ${story.retryCount} failed attempt(s).`, "warning"); - if (widget) await refreshWidgetStories(epicDir, widget); - // Continue loop — other stories may still be runnable. + webServer?.pushNotification( + `Story ${storyId} skipped after ${story.retryCount} failed attempt(s).`, + "warning", + ); + if (webServer) await refreshWebServerStories(epicDir, webServer); continue; } @@ -427,15 +342,14 @@ async function runStoryLoop( retryCount: story.retryCount + 1, updatedAt: new Date().toISOString(), }); - await runStoryReexecution(epicDir, cwd, extensionPath, storyId, story.retryCount + 1, story.failureSummary, log, ui, widget); - if (widget) await refreshWidgetStories(epicDir, widget); + await runStoryReexecution(epicDir, cwd, extensionPath, storyId, story.retryCount + 1, story.failureSummary, log, webServer); + if (webServer) await refreshWebServerStories(epicDir, webServer); break; } case "complete": { const done = stories.filter((s) => s.status === "done").length; const skipped = stories.filter((s) => s.status === "skipped").length; - if (widget) widget.update({ activeSubagent: null }); return { success: true, summary: `Epic complete: ${done} done, ${skipped} skipped` }; } @@ -450,90 +364,96 @@ async function runStoryLoop( // Public API // --------------------------------------------------------------------------- -export async function runEpicPipeline( +export async function runPipeline( epicDir: string, cwd: string, extensionPath: string, log: Logger, - ui: ExtensionUIContext | null, + webServer: WebServerHandle | null, ): Promise<{ success: boolean; summary: string }> { - // Widget created at pipeline start — spans the full epic lifecycle (Phase A + B). - // Widget is an observation layer: receives one-way update() calls, never - // influences routing decisions. const epicState = await loadEpicState(epicDir); - const widget = ui ? new EpicWidgetController(ui, epicState.epicId) : null; - try { - // Phase A: Epic Creation. - ui?.notify("Starting intake...", "info"); - await saveEpicState(epicDir, { ...epicState, phase: "intake" }); - if (widget) widget.update({ epicPhase: "intake" }); + // Model config gate — blocks until user confirms model selection in the web UI. + if (webServer) { + await webServer.requestModelConfig(); + } - const intakeOk = await runIntake(epicDir, cwd, extensionPath, log, ui, widget); - if (!intakeOk) return { success: false, summary: "Intake phase failed" }; + // Phase A: Epic Creation. + webServer?.pushNotification("Starting intake...", "info"); + await saveEpicState(epicDir, { ...epicState, phase: "intake" }); + webServer?.pushPhase("intake"); - const afterIntake = await loadEpicState(epicDir); - await saveEpicState(epicDir, { ...afterIntake, phase: "decomposition" }); - if (widget) widget.update({ epicPhase: "decomposition" }); + const intakeOk = await runIntake(epicDir, cwd, extensionPath, log, webServer); + if (!intakeOk) return { success: false, summary: "Intake phase failed" }; - const decompOk = await runDecomposer(epicDir, cwd, extensionPath, log, ui, widget); - if (!decompOk) return { success: false, summary: "Decomposition phase failed" }; + const afterIntake = await loadEpicState(epicDir); + await saveEpicState(epicDir, { ...afterIntake, phase: "decomposition" }); + webServer?.pushPhase("decomposition"); - // Discover stories by scanning the filesystem — per AGENTS.md invariant, - // LLMs write markdown files only. The decomposer wrote stories/{id}/story.md - // files; the driver scans to discover IDs and populates epic-state.json. - const storyIds = await discoverStoryIds(epicDir); - log("Discovered story IDs", { count: storyIds.length, ids: storyIds }); + const decompOk = await runDecomposer(epicDir, cwd, extensionPath, log, webServer); + if (!decompOk) return { success: false, summary: "Decomposition phase failed" }; - for (const storyId of storyIds) { - await ensureStoryDirectory(epicDir, storyId); - } + // Discover stories by scanning the filesystem — the decomposer LLM wrote + // story.md files using the write tool; the driver discovers them here and + // populates the JSON story list (never asks the LLM to update JSON directly). + const storyIds = await discoverStoryIds(epicDir); + log("Discovered story IDs", { count: storyIds.length, ids: storyIds }); - const afterDecomp = await loadEpicState(epicDir); - await saveEpicState(epicDir, { ...afterDecomp, stories: storyIds, phase: "review" }); - if (widget) { - widget.update({ epicPhase: "review" }); - const initialStories = await loadAllStoryStates(epicDir); - widget.update({ stories: initialStories.map((s) => ({ storyId: s.storyId, status: s.status })) }); - } + for (const storyId of storyIds) { + await ensureStoryDirectory(epicDir, storyId); + } - // Spec review gate — present story sketches for human approval if UI is available. - if (ui && storyIds.length > 0) { - ui.notify("Decomposition complete. Review story sketches...", "info"); - const reviewResult = await reviewStorySketches(epicDir, storyIds, ui); - log("Spec review complete", { approved: reviewResult.approved.length, skipped: reviewResult.skipped.length }); - - for (const skippedId of reviewResult.skipped) { - const skippedStory = await loadStoryState(epicDir, skippedId); - await saveStoryState(epicDir, skippedId, { - ...skippedStory, - status: "skipped", - skipReason: "Removed during spec review", - updatedAt: new Date().toISOString(), - }); - } + const afterDecomp = await loadEpicState(epicDir); + await saveEpicState(epicDir, { ...afterDecomp, stories: storyIds, phase: "review" }); + webServer?.pushPhase("review"); + + if (webServer) { + const initialStories = await loadAllStoryStates(epicDir); + webServer.pushStories(initialStories.map((s) => ({ storyId: s.storyId, status: s.status }))); + } - const reviewedState = await loadEpicState(epicDir); - await saveEpicState(epicDir, { ...reviewedState, stories: storyIds }); - } else { - log("Spec review gate: auto-approving (no UI or no stories)"); + // Spec review gate — present story sketches for human approval. + // Auto-approves when no web server is running (CI/headless mode). + if (webServer && storyIds.length > 0) { + webServer.pushNotification("Decomposition complete. Review story sketches...", "info"); + + const titles = await Promise.all(storyIds.map((id) => readStoryTitle(epicDir, id))); + const reviewStories: ReviewStory[] = storyIds.map((storyId, i) => ({ + storyId, + title: titles[i] ?? storyId, + })); + + const reviewResult = await webServer.requestReview(reviewStories); + log("Spec review complete", { approved: reviewResult.approved.length, skipped: reviewResult.skipped.length }); + + for (const skippedId of reviewResult.skipped) { + const skippedStory = await loadStoryState(epicDir, skippedId); + await saveStoryState(epicDir, skippedId, { + ...skippedStory, + status: "skipped", + skipReason: "Removed during spec review", + updatedAt: new Date().toISOString(), + }); } - // Phase B: Execution. - const beforeExec = await loadEpicState(epicDir); - await saveEpicState(epicDir, { ...beforeExec, phase: "executing" }); - if (widget) widget.update({ epicPhase: "executing" }); + const reviewedState = await loadEpicState(epicDir); + await saveEpicState(epicDir, { ...reviewedState, stories: storyIds }); + } else { + log("Spec review gate: auto-approving (no web server or no stories)"); + } - const result = await runStoryLoop(epicDir, cwd, extensionPath, log, ui, widget); + // Phase B: Execution. + const beforeExec = await loadEpicState(epicDir); + await saveEpicState(epicDir, { ...beforeExec, phase: "executing" }); + webServer?.pushPhase("executing"); - if (result.success) { - const afterExec = await loadEpicState(epicDir); - await saveEpicState(epicDir, { ...afterExec, phase: "completed" }); - if (widget) widget.update({ epicPhase: "completed" }); - } + const result = await runStoryLoop(epicDir, cwd, extensionPath, log, webServer); - return result; - } finally { - widget?.destroy(); + if (result.success) { + const afterExec = await loadEpicState(epicDir); + await saveEpicState(epicDir, { ...afterExec, phase: "completed" }); + webServer?.pushPhase("completed"); } + + return result; } From 7c766f147751866a90c99c2f460966ca8a5e3155 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:49:30 +0700 Subject: [PATCH 061/412] wire extension entry point to task manifest and web dashboard --- extensions/koan.ts | 214 ++++++++++++++++++++++----------------------- 1 file changed, 104 insertions(+), 110 deletions(-) diff --git a/extensions/koan.ts b/extensions/koan.ts index 24e0efc..5a5a999 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -1,23 +1,32 @@ -// Entry point for the koan pi extension. Serves dual roles: parent session -// (registers koan_plan tool and /koan commands) and subagent mode (dispatches -// to phase workflow via CLI flags). All tools register unconditionally at init; -// phases restrict access via tool_call blocking at runtime. +// Entry point for the koan pi extension. Serves dual roles: // -// RuntimeContext replaces the three separate mutable refs (PlanRef, -// SubagentRef, WorkflowDispatch) used in the previous design. +// Parent session mode — registers the koan_plan tool and /koan commands. +// Subagent mode — reads task.json from --koan-dir, dispatches to +// the appropriate phase workflow. +// +// All tools register unconditionally at init; phases restrict access at +// runtime via the tool_call permission fence in BasePhase. +// +// RuntimeContext is a mutable carrier set once during before_agent_start. +// Tools register at init (before flags are available) and read ctx at +// call time — the mutable-ref pattern decouples static registration from +// dynamic phase routing. import * as path from "node:path"; import { Type } from "@sinclair/typebox"; import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"; -import { detectSubagentMode, dispatchPhase } from "../src/planner/phases/dispatch.js"; +import { dispatchPhase } from "../src/planner/phases/dispatch.js"; import { registerAllTools, createRuntimeContext } from "../src/planner/tools/index.js"; import { createLogger, setLogDir } from "../src/utils/logger.js"; -import { EventLog, extractToolEvent } from "../src/planner/lib/audit.js"; +import { EventLog, extractToolCall, extractToolResult } from "../src/planner/lib/audit.js"; +import { readTaskFile } from "../src/planner/lib/task.js"; import { openKoanConfig } from "../src/planner/ui/config/menu.js"; import { createEpicDirectory } from "../src/planner/epic/state.js"; import { exportConversation } from "../src/planner/conversation.js"; -import { runEpicPipeline } from "../src/planner/driver.js"; +import { runPipeline } from "../src/planner/driver.js"; +import { startWebServer, openBrowser } from "../src/planner/web/server.js"; +import { registerTruncationOverride } from "../src/planner/lib/truncation-override.js"; function currentModelId(ctx: ExtensionContext): string | null { const model = ctx.model; @@ -28,92 +37,97 @@ function currentModelId(ctx: ExtensionContext): string | null { export default function koan(pi: ExtensionAPI): void { const log = createLogger("Koan"); - // -- Flags -- - pi.registerFlag("koan-role", { - description: "Koan subagent role", - type: "string", - default: "", - }); - pi.registerFlag("koan-epic-dir", { - description: "Koan epic directory path", - type: "string", - default: "", - }); - pi.registerFlag("koan-subagent-dir", { - description: "Koan subagent working directory", - type: "string", - default: "", - }); - pi.registerFlag("koan-story-id", { - description: "Current story ID for per-story subagents", - type: "string", - default: "", - }); - pi.registerFlag("koan-step-sequence", { - description: "Orchestrator step sequence (pre-execution or post-execution)", - type: "string", - default: "", - }); - pi.registerFlag("koan-retry-context", { - description: "Failure context from previous execution attempt", + // Single flag: the subagent directory path. The child reads task.json from + // this directory to discover its role and task parameters — no structured + // data flows through CLI flags. + pi.registerFlag("koan-dir", { + description: "Subagent working directory (internal — set by parent before spawn)", type: "string", default: "", }); - // RuntimeContext: single mutable object that carries epicDir, subagentDir, - // and the active onCompleteStep handler. Replaces the old PlanRef + - // SubagentRef + WorkflowDispatch triple. const ctx = createRuntimeContext(); registerAllTools(pi, ctx); - + // Registered unconditionally — applies in both parent and subagent mode. + // Self-guards: no-op when bash output fits within pi's default limits. + // Must precede before_agent_start so the audit tool_result handler (which + // registers later, inside before_agent_start) sees the original event and + // does not interfere with the replacement content we return. + registerTruncationOverride(pi); + + // Dispatch happens exactly once per session (guard prevents re-entry on + // subsequent before_agent_start calls, which pi may emit on reconnect). let dispatched = false; pi.on("before_agent_start", async (_event, extCtx) => { if (dispatched) return; dispatched = true; - const config = detectSubagentMode(pi); - if (config) { - // Populate RuntimeContext from CLI flags. - if (config.epicDir) { - ctx.epicDir = config.epicDir; - } - - let eventLog: EventLog | undefined; - if (config.subagentDir) { - ctx.subagentDir = config.subagentDir; - eventLog = new EventLog( - config.subagentDir, - config.role, - config.role, - currentModelId(extCtx), - ); - await eventLog.open(); - - pi.on("tool_result", (event) => { - void eventLog!.append(extractToolEvent(event as { - toolName: string; - input: Record; - content: Array<{ type: string; text?: string }>; - isError: boolean; - })); - }); + const dirFlag = pi.getFlag("koan-dir"); + if (!dirFlag || typeof dirFlag !== "string" || dirFlag.trim().length === 0) { + // No --koan-dir flag: running as parent session, not as a subagent. + return; + } - pi.on("session_shutdown", () => { - void eventLog!.close(); + const subagentDir = dirFlag.trim(); + + // task.json was written by the parent before spawning this process. + // Throws if missing or malformed — that is a programming error, not a user error. + const task = await readTaskFile(subagentDir); + + ctx.epicDir = task.epicDir; + ctx.subagentDir = subagentDir; + + const eventLog = new EventLog( + subagentDir, + task.role, + task.role, + currentModelId(extCtx), + ); + await eventLog.open(); + + pi.on("tool_call", (event) => { + void eventLog.append(extractToolCall(event as { + toolCallId: string; + toolName: string; + input: Record; + })); + }); + + pi.on("tool_result", (event) => { + void eventLog.append(extractToolResult(event as { + toolCallId: string; + toolName: string; + input: Record; + content: Array<{ type: string; text?: string }>; + isError: boolean; + })); + }); + + pi.on("turn_end", (event) => { + const msg = event.message as { + role: string; + usage?: { input: number; output: number; cacheRead: number; cacheWrite: number }; + }; + if (msg.role === "assistant" && msg.usage) { + void eventLog.append({ + kind: "usage", + input: msg.usage.input, + output: msg.usage.output, + cacheRead: msg.usage.cacheRead, + cacheWrite: msg.usage.cacheWrite, }); } + }); - await dispatchPhase(pi, config, ctx, log, eventLog); - } + pi.on("session_shutdown", () => { + void eventLog.close(); + }); + + await dispatchPhase(pi, task, ctx, log, eventLog); }); // -- koan_plan tool -- - // Requires an interactive terminal session: subagents use koan_ask_question - // and koan_request_scouts, which are answered by the IPC responder running - // in the parent session. Without a UI, no IPC responder starts and any - // subagent calling those tools will poll ipc.json forever, hanging the - // pipeline permanently. pi.registerTool({ name: "koan_plan", label: "Plan", @@ -130,33 +144,27 @@ export default function koan(pi: ExtensionAPI): void { ].join("\n"), parameters: Type.Object({}), async execute(_toolCallId, _params, _signal, _onUpdate, extCtx) { - // koan_plan requires an interactive terminal session. Subagents use - // koan_ask_question and koan_request_scouts, which are answered by the - // IPC responder that only starts when a UI is present. Without a UI, - // subagents would poll ipc.json forever and the pipeline would hang. - if (!extCtx.hasUI) { - return { - content: [{ type: "text" as const, text: "koan_plan requires an interactive terminal session." }], - details: undefined, - }; - } - const epicInfo = await createEpicDirectory("", extCtx.cwd); ctx.epicDir = epicInfo.directory; setLogDir(epicInfo.directory); - await exportConversation(extCtx.sessionManager, epicInfo.directory); - log("Conversation exported", { epicDir: epicInfo.directory }); - const extensionPath = path.resolve(import.meta.dirname, "koan.ts"); - const ui = extCtx.hasUI ? extCtx.ui : null; - const result = await runEpicPipeline(epicInfo.directory, extCtx.cwd, extensionPath, log, ui); + const server = await startWebServer(epicInfo.directory); + try { + await openBrowser(pi, server.url); + await exportConversation(extCtx.sessionManager, epicInfo.directory); + log("Conversation exported", { epicDir: epicInfo.directory }); - return { - content: [{ type: "text" as const, text: result.summary }], - details: undefined, - }; + const result = await runPipeline(epicInfo.directory, extCtx.cwd, extensionPath, log, server); + + return { + content: [{ type: "text" as const, text: `Dashboard: ${server.url}\n\n${result.summary}` }], + details: undefined, + }; + } finally { + server.close(); + } }, }); @@ -174,18 +182,4 @@ export default function koan(pi: ExtensionAPI): void { } }, }); - - pi.registerCommand("koan-execute", { - description: "Execute a koan plan", - handler: async (_args, extCtx) => { - extCtx.ui.notify("Execution mode is not yet implemented.", "warning"); - }, - }); - - pi.registerCommand("koan-status", { - description: "Show koan workflow status", - handler: async (_args, extCtx) => { - extCtx.ui.notify("Status: idle", "info"); - }, - }); } From 6b1faeab165619326e1f94fde8530b7f8d2a3c7d Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Wed, 18 Mar 2026 23:49:39 +0700 Subject: [PATCH 062/412] update AGENTS.md with six core architecture invariants --- AGENTS.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 24d8ad4..ea5ff9f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,66 @@ -# Koan Architecture Invariant +# Koan Architecture Invariants -LLMs write **markdown files only**. LLMs communicate with the driver through **tool calls only**. -The driver maintains `.json` state files internally — no LLM ever reads or writes a `.json` file. +Full architecture documentation: **[docs/architecture.md](docs/architecture.md)** -Example: orchestrator calls `koan_complete_story(story_id)` → tool code writes `state.json` + `status.md` → -driver reads `state.json` to route next action. The orchestrator never touches `state.json` directly. +Spoke documents: +- [docs/subagents.md](docs/subagents.md) — spawn lifecycle, task manifest, step-first workflow, permissions +- [docs/ipc.md](docs/ipc.md) — file-based IPC protocol, scout spawning, question routing +- [docs/state.md](docs/state.md) — driver/LLM boundary, epic and story state, routing rules + +--- + +The six core invariants (see architecture.md for full detail + pitfalls): + +## 1. File Boundary + +LLMs write **markdown files only**. The driver maintains **JSON state files** +internally — no LLM ever reads or writes a `.json` file. Tool code bridges +both worlds. + +## 2. Step-First Workflow Pattern (critical) + +Every subagent is a `pi -p` process. Once the LLM produces text without a tool +call, the process exits — there is no stdin to recover. + +**The first thing any subagent does is call `koan_complete_step`.** The spawn +prompt contains *only* this directive. The tool returns step 1 instructions. +This establishes the calling pattern before the LLM sees complex instructions. + +``` +Boot prompt: "You are a koan {role} agent. Call koan_complete_step to receive your instructions." + ↓ LLM calls koan_complete_step (step 0 → 1 transition) +Tool returns: Step 1 instructions (rich context, task details, guidance) + ↓ LLM does work... + ↓ LLM calls koan_complete_step +Tool returns: Step 2 instructions (or "Phase complete.") +``` + +## 3. Driver Determinism + +The driver reads JSON state files and exit codes, applies routing rules, and +spawns the next subagent. It never makes judgment calls or parses free-text. + +## 4. Default-Deny Permissions + +Every tool call passes through a role-based permission fence. Unknown roles +and tools are blocked. Planning roles can only write inside the epic directory. + +## 5. Need-to-Know Prompts + +Boot prompt is one sentence. System prompt has role identity, no task details. +Task details arrive via step 1 guidance after the tool-calling pattern is +established. + +## 6. Directory-as-Contract + +The subagent directory is the sole interface between parent and child. +Three well-known JSON files: + +| File | Writer | Reader | Purpose | +|------|--------|--------|---------| +| `task.json` | Parent (before spawn) | Child (once, at startup) | What to do | +| `state.json` | Child (continuously) | Parent (polling) | What has been done | +| `ipc.json` | Both (request/response) | Both (polling) | What is needed right now | + +No structured configuration flows through CLI flags. The spawn command carries +only the directory path. From 454635f624bd9867b97a56895919fb9e74fac731 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 19 Mar 2026 20:47:29 +0700 Subject: [PATCH 063/412] audit infrastructure for thinking and confidence events --- extensions/koan.ts | 15 ++++ src/planner/lib/audit.ts | 167 +++++++++++++++++++++++++++++++++++++-- 2 files changed, 174 insertions(+), 8 deletions(-) diff --git a/extensions/koan.ts b/extensions/koan.ts index 5a5a999..c5c6cae 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -86,6 +86,9 @@ export default function koan(pi: ExtensionAPI): void { ); await eventLog.open(); + // Make the event log available to tools (e.g. koan_set_confidence) via ctx. + ctx.eventLog = eventLog; + pi.on("tool_call", (event) => { void eventLog.append(extractToolCall(event as { toolCallId: string; @@ -108,6 +111,7 @@ export default function koan(pi: ExtensionAPI): void { const msg = event.message as { role: string; usage?: { input: number; output: number; cacheRead: number; cacheWrite: number }; + content?: Array<{ type: string; thinking?: string }>; }; if (msg.role === "assistant" && msg.usage) { void eventLog.append({ @@ -118,6 +122,17 @@ export default function koan(pi: ExtensionAPI): void { cacheWrite: msg.usage.cacheWrite, }); } + if (msg.role === "assistant" && Array.isArray(msg.content)) { + for (const block of msg.content) { + if (block.type === "thinking" && typeof block.thinking === "string" && block.thinking.length > 0) { + void eventLog.append({ + kind: "thinking", + text: block.thinking, + chars: block.thinking.length, + }); + } + } + } }); pi.on("session_shutdown", () => { diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index 86f9ebb..91ebabe 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -75,6 +75,30 @@ export interface UsageEvent extends EventBase { cacheWrite: number; } +export interface ThinkingEvent extends EventBase { + kind: "thinking"; + // Truncated thinking content (first 2000 chars for log size). + text: string; + // Original length before truncation. + chars: number; +} + +export interface ConfidenceChangeEvent extends EventBase { + kind: "confidence_change"; + // The confidence level declared by the intake agent via koan_set_confidence. + level: "exploring" | "low" | "medium" | "high" | "certain"; + // Which iteration of the Scout→Deliberate→Reflect loop this was declared in. + iteration: number; +} + +export interface IterationStartEvent extends EventBase { + kind: "iteration_start"; + // The new iteration number (incremented from the previous Reflect step). + iteration: number; + // Maximum allowed iterations before the loop is forced to exit. + maxIterations: number; +} + export type AuditEvent = | ToolCallEvent | ToolResultEvent @@ -82,7 +106,10 @@ export type AuditEvent = | StepTransitionEvent | PhaseEndEvent | HeartbeatEvent - | UsageEvent; + | UsageEvent + | ThinkingEvent + | ConfidenceChangeEvent + | IterationStartEvent; // Distributive Omit — distributes over union members so object literals // with fields specific to one member are accepted. @@ -111,6 +138,13 @@ export interface Projection { completionSummary: string | null; tokensSent: number; tokensReceived: number; + // Timestamp of the most recent tool_result event; used to track thinking gaps. + lastToolResultAt: string | null; + // Intake-specific: the most recent confidence level declared by koan_set_confidence. + // Null for non-intake subagents or before any confidence is declared. + intakeConfidence: "exploring" | "low" | "medium" | "high" | "certain" | null; + // Intake-specific: the current loop iteration (1-based). Zero for non-intake. + intakeIteration: number; } // -- Correlated tool invocations -- @@ -355,6 +389,7 @@ export function fold(s: Projection, e: AuditEvent): Projection { ...base, lastAction: summarizeResult(e), currentToolCallId: null, + lastToolResultAt: e.ts, }; case "heartbeat": @@ -366,6 +401,22 @@ export function fold(s: Projection, e: AuditEvent): Projection { tokensSent: s.tokensSent + e.input, tokensReceived: s.tokensReceived + e.output, }; + + case "thinking": + return base; + + case "confidence_change": + return { + ...base, + intakeConfidence: e.level, + intakeIteration: e.iteration, + }; + + case "iteration_start": + return { + ...base, + intakeIteration: e.iteration, + }; } } @@ -404,6 +455,9 @@ export class EventLog { completionSummary: null, tokensSent: 0, tokensReceived: 0, + lastToolResultAt: null, + intakeConfidence: null, + intakeIteration: 0, }; } @@ -462,6 +516,22 @@ export class EventLog { } as Omit); } + async emitConfidenceChange(level: ConfidenceChangeEvent["level"], iteration: number): Promise { + await this.append({ + kind: "confidence_change", + level, + iteration, + } as Omit); + } + + async emitIterationStart(iteration: number, maxIterations: number): Promise { + await this.append({ + kind: "iteration_start", + iteration, + maxIterations, + } as Omit); + } + async close(): Promise { if (this.heartbeat) { clearInterval(this.heartbeat); @@ -507,6 +577,10 @@ export interface LogLine { highValue: boolean; inFlight: boolean; details?: string[]; + // Timestamp used by thinking entries to drive the live elapsed timer. + ts?: string; + // Expandable content body: thinking text, tool output, etc. + body?: string; } interface ToolShape { @@ -548,35 +622,101 @@ export async function readRecentLogs(dir: string, count = 8): Promise // Builds a chronological log by walking events in order and emitting // one LogLine per tool invocation (at result time, or at call time if -// still in-flight) plus lifecycle events. +// still in-flight) plus lifecycle events. Inserts thinking lines to +// represent gaps between visible events where the LLM is reasoning. function buildChronologicalLog(events: AuditEvent[], count: number): LogLine[] { const pendingCalls = new Map }>(); const lines: LogLine[] = []; + let thinkingStartTs: string | null = null; + // Index of the last thinking line pushed to `lines`. Thinking events fire + // AFTER the turn's tool_result (message_update is a post-turn event), so the + // text belongs to the PREVIOUS thinking gap, not the current one. We + // retroactively set body on the already-emitted line. + let lastThinkingIdx = -1; + let phaseEnded = false; for (const e of events) { if (e.kind === "heartbeat" || e.kind === "usage") continue; + if (e.kind === "confidence_change" || e.kind === "iteration_start") continue; + + if (e.kind === "thinking") { + // Retroactive: this text is from the turn that just completed. + // Overwrite (not append) — later message_update events have more + // complete content, so the last one wins. + if (lastThinkingIdx >= 0) { + lines[lastThinkingIdx].body = e.text; + } + continue; + } if (e.kind === "tool_call") { - // Stash tool name + input for when the result arrives (or for - // in-flight rendering if no result appears by end of loop). + // Before a visible tool_call, insert a completed thinking line if gap ≥ 1s + if (e.tool !== "koan_complete_step" && thinkingStartTs) { + const gapMs = new Date(e.ts).getTime() - new Date(thinkingStartTs).getTime(); + if (gapMs >= 1000) { + lines.push({ + tool: "thinking", + summary: formatThinkingDuration(gapMs), + highValue: false, + inFlight: false, + }); + lastThinkingIdx = lines.length - 1; + } + thinkingStartTs = null; + } pendingCalls.set(e.toolCallId, { tool: e.tool, input: e.input }); continue; } if (e.kind === "tool_result") { - if (e.tool === "koan_complete_step") continue; + if (e.tool === "koan_complete_step") { + pendingCalls.delete(e.toolCallId); + continue; + } const call = pendingCalls.get(e.toolCallId); lines.push(formatPairedResult(e, call?.input ?? {})); pendingCalls.delete(e.toolCallId); + thinkingStartTs = e.ts; continue; } - // Lifecycle event. - lines.push(formatLifecycleEvent(e)); + if ( + e.kind === "phase_start" || + e.kind === "step_transition" || + e.kind === "phase_end" + ) { + // Flush any pending thinking gap before the lifecycle line. + if (thinkingStartTs) { + const gapMs = new Date(e.ts).getTime() - new Date(thinkingStartTs).getTime(); + if (gapMs >= 1000) { + lines.push({ + tool: "thinking", + summary: formatThinkingDuration(gapMs), + highValue: false, + inFlight: false, + }); + lastThinkingIdx = lines.length - 1; + } + thinkingStartTs = null; + } + if (e.kind === "phase_end") phaseEnded = true; + lines.push(formatLifecycleEvent(e)); + thinkingStartTs = e.ts; + } + } + + // Currently-thinking indicator: all tools completed, phase still running + if (thinkingStartTs && pendingCalls.size === 0 && !phaseEnded) { + lines.push({ + tool: "thinking", + summary: "", + highValue: false, + inFlight: true, + ts: thinkingStartTs, + }); } // Emit remaining calls without results as in-flight lines. - // The ActivityFeed renders the last in-flight line with animated dots. for (const [, call] of pendingCalls) { if (call.tool === "koan_complete_step") continue; lines.push(formatInFlightCall(call.tool, call.input)); @@ -636,6 +776,14 @@ function responseSize(response: string[]): string { return textStats(response.join("\n")); } +function formatThinkingDuration(ms: number): string { + const sec = Math.round(ms / 1000); + if (sec < 60) return `${sec}s`; + const min = Math.floor(sec / 60); + const remSec = sec % 60; + return remSec > 0 ? `${min}m ${remSec}s` : `${min}m`; +} + function truncateUnicode(text: string, maxChars: number): string { const chars = Array.from(text); if (chars.length <= maxChars) return text; @@ -830,3 +978,6 @@ function formatLifecycleEvent(e: PhaseStartEvent | StepTransitionEvent | PhaseEn return { tool: "phase", summary: e.detail ? `${e.outcome} · ${e.detail}` : e.outcome, highValue: false, inFlight: false }; } } + +// formatToolInvocation is kept for callers outside buildChronologicalLog. +void formatToolInvocation; From 081529e943cd69c8b582b3f2762de604ab93358b Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 19 Mar 2026 20:47:48 +0700 Subject: [PATCH 064/412] intake phase 5-step confidence loop --- src/planner/lib/permissions.ts | 26 ++ src/planner/lib/runtime-context.ts | 26 ++ src/planner/phases/base-phase.ts | 94 ++++- src/planner/phases/decomposer/prompts.ts | 5 +- src/planner/phases/intake/phase.ts | 133 ++++++- src/planner/phases/intake/prompts.ts | 364 +++++++++++++----- src/planner/phases/orchestrator/prompts.ts | 8 +- src/planner/phases/planner/prompts.ts | 6 +- src/planner/tools/confidence.ts | 76 ++++ src/planner/tools/index.ts | 2 + .../js/components/phases/Consolidation.jsx | 2 +- 11 files changed, 619 insertions(+), 123 deletions(-) create mode 100644 src/planner/tools/confidence.ts diff --git a/src/planner/lib/permissions.ts b/src/planner/lib/permissions.ts index 058be7c..2a5bf6e 100644 --- a/src/planner/lib/permissions.ts +++ b/src/planner/lib/permissions.ts @@ -33,6 +33,7 @@ export const ROLE_PERMISSIONS: ReadonlyMap> = new Ma "koan_complete_step", "koan_ask_question", "koan_request_scouts", + "koan_set_confidence", "edit", "write", ]), @@ -99,17 +100,42 @@ export const ROLE_PERMISSIONS: ReadonlyMap> = new Ma // Executor has unrestricted write access (must implement stories in the codebase). const PLANNING_ROLES = new Set(["intake", "scout", "decomposer", "orchestrator", "planner"]); +// STEP_1_BLOCKED_TOOLS: tools disallowed during the intake Extract step (step 1). +// Step 1 is read-only comprehension. Blocking these tools here provides a +// mechanical enforcement layer on top of the prompt-level prohibition, ensuring +// the LLM cannot frontload scouting or question-asking before understanding +// the conversation. +const STEP_1_BLOCKED_TOOLS = new Set([ + "koan_request_scouts", + "koan_ask_question", + "koan_set_confidence", + "write", + "edit", +]); + export function checkPermission( role: string, toolName: string, epicDir?: string, toolArgs?: Record, + intakeStep?: number, ): { allowed: boolean; reason?: string } { // Read tools are always allowed — check before role map lookup. if (READ_TOOLS.has(toolName)) { return { allowed: true }; } + // Intake step 1 (Extract) is read-only: block all side-effecting tools so + // the LLM cannot frontload scouting or question-asking before it has read + // and understood the conversation. + if (role === "intake" && intakeStep === 1 && STEP_1_BLOCKED_TOOLS.has(toolName)) { + return { + allowed: false, + reason: `${toolName} is not available during the Extract step (step 1). ` + + "Complete koan_complete_step first to advance to the Scout step.", + }; + } + // Unknown role: blocked under default-deny policy. if (!ROLE_PERMISSIONS.has(role)) { log("Unknown role blocked", { role, toolName }); diff --git a/src/planner/lib/runtime-context.ts b/src/planner/lib/runtime-context.ts index 5019bb1..1138f88 100644 --- a/src/planner/lib/runtime-context.ts +++ b/src/planner/lib/runtime-context.ts @@ -5,10 +5,32 @@ // onCompleteStep return value: // string → next step's formatted prompt (tool returns it to the LLM) // null → phase is complete (tool returns "Phase complete.") +// +// intakeConfidence: set by koan_set_confidence during the intake Reflect step. +// IntakePhase reads this in getNextStep() to decide whether to loop or advance. +// Reset to null after each loop-back to enforce re-assessment each iteration. +// +// intakeStep: current step number, kept in sync by IntakePhase.onStepUpdated(). +// The permission fence reads this to block side-effecting tools during the +// read-only Extract step (step 1). +// +// intakeIteration: current loop iteration (1-based), kept in sync by IntakePhase. +// The confidence tool uses this when emitting confidence_change audit events. +// +// eventLog: the active EventLog for the current subagent session. Set during +// before_agent_start after the log file is opened. Tools that need to emit +// audit events (e.g. koan_set_confidence) read this at call time. + +import type { EventLog } from "./audit.js"; + export interface RuntimeContext { epicDir: string | null; subagentDir: string | null; onCompleteStep: ((thoughts: string) => Promise) | null; + intakeConfidence: "exploring" | "low" | "medium" | "high" | "certain" | null; + intakeStep: number; + intakeIteration: number; + eventLog: EventLog | null; } export function createRuntimeContext(): RuntimeContext { @@ -16,5 +38,9 @@ export function createRuntimeContext(): RuntimeContext { epicDir: null, subagentDir: null, onCompleteStep: null, + intakeConfidence: null, + intakeStep: 0, + intakeIteration: 1, + eventLog: null, }; } diff --git a/src/planner/phases/base-phase.ts b/src/planner/phases/base-phase.ts index 62bf1a7..6830e20 100644 --- a/src/planner/phases/base-phase.ts +++ b/src/planner/phases/base-phase.ts @@ -11,11 +11,25 @@ // transitions 0→1 and returns step 1 guidance (just-in-time delivery). // Subsequent calls advance through steps until the phase completes. // +// Non-linear step progression: +// Subclasses may override getNextStep() to implement loops or conditional +// transitions. getNextStep() MUST be pure — it only returns the next step +// number. Side effects that accompany a loop decision (state resets, counter +// increments, event emission) belong in onLoopBack(), which handleStepComplete +// calls whenever getNextStep() returns a step number less than the current one. +// +// The default implementation is strictly linear: each step advances to the +// next, and the final step (totalSteps) signals completion by returning null. +// IntakePhase overrides both getNextStep() and onLoopBack() to loop steps 2–4 +// until the confidence gate is satisfied. +// // Lifecycle: // constructor → registerHandlers() (hooks event listeners) // begin() → activates phase at step 0, arms onCompleteStep, emits phase_start // handleStepComplete(0) → returns step 1 guidance, emits step_transition(1) -// handleStepComplete(N) → returns step N+1 guidance, or null when done +// handleStepComplete(N) → calls getNextStep(N) to determine next step, +// calls onLoopBack() on backward transitions, +// returns guidance or null when done import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; @@ -50,6 +64,23 @@ export abstract class BasePhase { this.registerHandlers(); } + // -- Non-linear progression hook -- + // + // Returns the step number to transition to after `currentStep` completes, + // or null to signal phase completion. Subclasses override this to implement + // confidence loops, conditional branches, or any other non-linear flow. + // + // MUST be pure: do not mutate state or emit events here. Side effects that + // accompany a loop-back (counter increments, state resets, event emission) + // belong in onLoopBack(), which handleStepComplete calls after this method + // returns a backward step number. + // + // Default: linear progression. The step after totalSteps is null (done). + protected getNextStep(currentStep: number): number | null { + if (currentStep === this.totalSteps) return null; + return currentStep + 1; + } + // -- Event handler registration -- private registerHandlers(): void { @@ -71,8 +102,15 @@ export abstract class BasePhase { event.toolName, this.ctx.epicDir ?? undefined, event.input as Record, + this.ctx.intakeStep, ); if (!perm.allowed) { + void this.eventLog?.append({ + kind: "tool_result", + toolCallId: event.toolCallId, + tool: event.toolName, + error: true, + }); return { block: true, reason: perm.reason }; } return undefined; @@ -113,13 +151,24 @@ export abstract class BasePhase { // boot prompt. Reward it with step 1 guidance. This is the critical moment // that establishes the call→receive→work→call pattern for the session. this.step = 1; + this.onStepUpdated(1); const prompt = formatStep(this.getStepGuidance(1)); await this.eventLog?.emitStepTransition(1, this.getStepName(1), this.totalSteps); this.log("Boot transition", { role: this.role, to: 1 }); return prompt; } - if (this.step === this.totalSteps) { + // Validate pre-conditions before advancing (subclasses may override). + const preError = await this.validateStepCompletion(this.step); + if (preError !== null) { + // Return the error as the tool result — the LLM sees it and must fix + // the pre-condition before calling koan_complete_step again. + return preError; + } + + const nextStep = this.getNextStep(this.step); + + if (nextStep === null) { // Phase complete — return null signals koan_complete_step to reply "Phase complete." this.active = false; this.ctx.onCompleteStep = null; @@ -128,12 +177,49 @@ export abstract class BasePhase { return null; } - // Advance to next step. const prev = this.step; - this.step = prev + 1; + this.step = nextStep; + + // If the step went backward (loop-back), give the subclass a chance to + // perform side effects before the new step's guidance is delivered: + // resetting state, incrementing counters, emitting events. This keeps + // getNextStep() pure — it only decides where to go, not what to do there. + if (nextStep < prev) { + await this.onLoopBack(prev, nextStep); + } + + this.onStepUpdated(nextStep); const prompt = formatStep(this.getStepGuidance(this.step)); await this.eventLog?.emitStepTransition(this.step, this.getStepName(this.step), this.totalSteps); this.log("Step transition", { role: this.role, from: prev, to: this.step }); return prompt; } + + // -- Overridable hooks -- + + // Called whenever this.step is updated (including loop-backs). Subclasses + // use this to sync ctx fields (e.g., intakeStep) with the current step. + // eslint-disable-next-line @typescript-eslint/no-unused-vars + protected onStepUpdated(_step: number): void { + // Default: no-op. + } + + // Called when a loop-back occurs (nextStep < previousStep), after this.step + // has been updated but before onStepUpdated() and getStepGuidance() run. + // Subclasses use this to perform side effects that accompany the loop decision + // — resetting state, incrementing counters, emitting events — separate from + // the pure getNextStep() query. The hook is async so event emission can be + // properly awaited, preserving event order in events.jsonl. + // eslint-disable-next-line @typescript-eslint/no-unused-vars + protected async onLoopBack(_from: number, _to: number): Promise { + // Default: no-op. + } + + // Called before advancing from the given step. Return null to allow + // advancement, or an error string to block it (returned as the tool + // result so the LLM sees the message and must fix the pre-condition). + // eslint-disable-next-line @typescript-eslint/no-unused-vars + protected async validateStepCompletion(_step: number): Promise { + return null; // Default: no pre-conditions. + } } diff --git a/src/planner/phases/decomposer/prompts.ts b/src/planner/phases/decomposer/prompts.ts index f54b48d..6cbfc8b 100644 --- a/src/planner/phases/decomposer/prompts.ts +++ b/src/planner/phases/decomposer/prompts.ts @@ -35,7 +35,7 @@ This format is sortable and human-readable. - MUST NOT include implementation details (specific functions, algorithms, data structures). - MUST NOT make decisions that require user input. Those belong to intake. -- MUST NOT invent scope not present in context.md or decisions.md. +- MUST NOT invent scope not present in context.md. - MUST produce one story sketch per deliverable unit of work. - SHOULD keep stories small: prefer 4–8 stories over 1–2 large ones. - SHOULD order stories so foundational work (types, interfaces, data models) comes first. @@ -69,8 +69,7 @@ export function decomposerStepGuidance(step: number): StepGuidance { "## Files to read", "", "From the epic directory:", - "- `context.md` — structured requirements extracted from the conversation", - "- `decisions.md` — user answers to clarifying questions", + "- `context.md` — intake analysis: conversation context, codebase findings, and user decisions", "", "If scout reports were referenced in your initial instructions above, read them now.", "If no scout reports were mentioned, proceed without them.", diff --git a/src/planner/phases/intake/phase.ts b/src/planner/phases/intake/phase.ts index 5ef4d79..f7becf0 100644 --- a/src/planner/phases/intake/phase.ts +++ b/src/planner/phases/intake/phase.ts @@ -1,6 +1,31 @@ -// Intake phase: reads conversation, extracts context, requests scouts, -// identifies gaps, asks user questions, writes context.md and decisions.md. -// Three-step sequence per §11.2.2. +// Intake phase: reads conversation, scouts codebase, asks clarifying questions, +// and writes context.md — the sole input for all downstream phases. +// +// Five-step workflow with a confidence-gated loop: +// +// Step 1 (Extract) — read-only comprehension of conversation.jsonl +// Step 2 (Scout) — dispatch codebase scouts for targeted exploration +// Step 3 (Deliberate) — enumerate knowns/unknowns, ask user questions +// Step 4 (Reflect) — self-verify completeness, set confidence level +// Step 5 (Synthesize) — write context.md from all accumulated findings +// +// Steps 2–4 form the confidence loop. After Reflect, getNextStep() checks +// ctx.intakeConfidence: +// - If "certain" or max iterations reached → return 5 (Synthesize) +// - Otherwise → return 2 (Scout), triggering a loop-back +// +// getNextStep() is pure — it only returns the next step number. All side effects +// that accompany a loop-back (confidence reset, iteration increment, event emission) +// live in onLoopBack(), which BasePhase calls after detecting a backward transition. +// This keeps the two concerns separate and makes getNextStep() safe to reason about. +// +// The loop enforces that koan_set_confidence is called before koan_complete_step +// in Reflect via validateStepCompletion(). Confidence is reset to null in onLoopBack() +// so each iteration requires a fresh assessment. +// +// Step 1 is read-only: the permission fence blocks koan_request_scouts, +// koan_ask_question, koan_set_confidence, write, and edit during that step, +// enforced via ctx.intakeStep which is kept in sync via onStepUpdated(). import * as path from "node:path"; import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; @@ -14,7 +39,15 @@ import type { StepGuidance } from "../../lib/step.js"; export class IntakePhase extends BasePhase { protected readonly role = "intake"; - protected readonly totalSteps = 3; + protected readonly totalSteps = 5; + + // Maximum number of Scout→Deliberate→Reflect iterations before forcing exit + // to Synthesize regardless of confidence level. + private static readonly MAX_ITERATIONS = 4; + + // Current loop iteration (1-based). Starts at 1 for the initial pass through + // steps 2–4; incremented in onLoopBack() each time the loop continues. + private iteration = 1; private readonly conversationPath: string; @@ -34,10 +67,98 @@ export class IntakePhase extends BasePhase { } protected getStepName(step: number): string { - return INTAKE_STEP_NAMES[step] ?? `Step ${step}`; + const base = INTAKE_STEP_NAMES[step] ?? `Step ${step}`; + // Annotate loop steps with the iteration number so the UI shows + // e.g. "Scout (round 2)" instead of just "Scout". + if (step >= 2 && step <= 4 && this.iteration > 1) { + return `${base} (round ${this.iteration})`; + } + return base; } protected getStepGuidance(step: number): StepGuidance { - return intakeStepGuidance(step, this.conversationPath); + return intakeStepGuidance(step, this.conversationPath, this.iteration); + } + + // -- Non-linear progression: pure query, no side effects -- + // + // Step 4 (Reflect) is the loop gate. Returns 2 (Scout) to loop back, or 5 + // (Synthesize) to exit. Side effects for the loop-back case (iteration + // increment, confidence reset, event emission) live in onLoopBack(). + protected getNextStep(currentStep: number): number | null { + if (currentStep === 4) { + const confidence = this.ctx.intakeConfidence; + const isExhausted = this.iteration >= IntakePhase.MAX_ITERATIONS; + + if (confidence === "certain" || isExhausted) { + if (isExhausted && confidence !== "certain") { + this.log("Max iterations reached — forcing exit to Synthesize", { + iteration: this.iteration, + confidence, + }); + } + return 5; + } + + // Signal loop-back. onLoopBack() handles the side effects. + return 2; + } + + // Step 5 (Synthesize) is the final step. + if (currentStep === 5) return null; + + // All other steps: linear progression. + return currentStep + 1; + } + + // -- Loop-back side effects -- + // + // Called by BasePhase after getNextStep() returns a backward step number. + // Increments the iteration counter, resets confidence so the next Reflect + // step requires a fresh assessment, and emits the iteration_start event. + // Properly awaited so the event appears in correct sequence in events.jsonl. + protected override async onLoopBack(_from: number, _to: number): Promise { + this.iteration++; + this.ctx.intakeConfidence = null; + this.ctx.intakeIteration = this.iteration; + await this.eventLog?.emitIterationStart(this.iteration, IntakePhase.MAX_ITERATIONS); + this.log("Confidence loop: iterating", { newIteration: this.iteration }); + } + + // -- Pre-condition enforcement for Reflect (step 4) -- + // + // The LLM must call koan_set_confidence before koan_complete_step during + // the Reflect step. If it hasn't, we return an error message that the LLM + // sees as the tool result — it must fix the pre-condition before retrying. + protected async validateStepCompletion(step: number): Promise { + if (step === 4 && this.ctx.intakeConfidence === null) { + return "You must call koan_set_confidence before completing the Reflect step. " + + "Assess your confidence level based on the verification questions you answered, " + + "then call koan_set_confidence, then call koan_complete_step."; + } + return null; + } + + // -- Sync ctx fields whenever the active step changes -- + // + // ctx.intakeStep is read by the permission fence to block side-effecting tools + // during the read-only Extract step (step 1). + // + // iteration_start is emitted here for iteration 1 when Scout (step 2) is first + // entered. Subsequent iterations emit iteration_start via onLoopBack(). This + // ensures the web UI always knows which iteration is active from the moment + // scouting begins, not just after the first confidence assessment. + // + // The void on emitIterationStart is intentional: onStepUpdated is synchronous. + // EventLog.append() serializes all appends via an internal promise queue, so + // this event is enqueued before the emitStepTransition that follows in + // handleStepComplete, preserving correct order in events.jsonl. + protected override onStepUpdated(step: number): void { + this.ctx.intakeStep = step; + this.ctx.intakeIteration = this.iteration; + + if (step === 2 && this.iteration === 1) { + void this.eventLog?.emitIterationStart(1, IntakePhase.MAX_ITERATIONS); + } } } diff --git a/src/planner/phases/intake/prompts.ts b/src/planner/phases/intake/prompts.ts index 0e13445..de1525e 100644 --- a/src/planner/phases/intake/prompts.ts +++ b/src/planner/phases/intake/prompts.ts @@ -1,174 +1,334 @@ -// Intake phase prompts — 3-step sequence per §11.2.2: -// Step 1: Context extraction (read conversation → write context.md) -// Step 2: Codebase scouting (call koan_request_scouts with targeted questions) -// Step 3: Gap analysis + questions (review findings → ask user → write decisions.md) +// Intake phase prompts — 5-step workflow with a confidence-gated loop. +// +// Step 1 (Extract) — read-only comprehension of conversation.jsonl +// Step 2 (Scout) — dispatch codebase scouts for targeted exploration +// Step 3 (Deliberate) — enumerate knowns/unknowns, formulate & ask questions +// Step 4 (Reflect) — self-verify completeness, declare confidence level +// Step 5 (Synthesize) — write context.md from all accumulated findings +// +// Steps 2–4 repeat until the LLM declares "certain" confidence (or max +// iterations are exhausted). The iteration parameter is threaded through +// intakeStepGuidance() to produce iteration-aware prompts for steps 2–4: +// first-iteration guidance focuses on initial exploration; subsequent +// iterations focus on narrowing remaining gaps from the previous reflection. +// +// Design note — Prompt Chaining over Stepwise: +// Each step has exactly one cognitive goal (scout / deliberate / reflect). +// This prevents the "simulated refinement" anti-pattern where a monolithic +// prompt causes the model to artificially downgrade its draft quality to +// manufacture visible improvement. Separate koan_complete_step calls enforce +// genuinely isolated reasoning for each phase of the loop. import type { StepGuidance } from "../../lib/step.js"; export const INTAKE_STEP_NAMES: Record = { - 1: "Context Extraction", - 2: "Codebase Scouting", - 3: "Gap Analysis & Questions", + 1: "Extract", + 2: "Scout", + 3: "Deliberate", + 4: "Reflect", + 5: "Synthesize", }; export function intakeSystemPrompt(): string { - return `You are an intake analyst for a coding task planner. You read a conversation history, extract structured context, explore the codebase via scouts, and ask the user targeted clarifying questions grounded in both the conversation and what actually exists in the codebase. + return `You are an intake analyst for a coding task planner. You read a conversation history, explore the codebase, and ask the user targeted questions until you have complete context for planning. + +Your output — a single context.md file — is the sole foundation for all downstream work. Every story boundary, every implementation plan, and every line of code written downstream depends on the quality and completeness of this file. Gaps here compound into wrong plans and wrong code. ## Your role -You extract and organize information. You do NOT plan, design, or implement. +You extract, verify, and organize information. You do NOT plan, design, or implement. -## Strict rules — violations invalidate your output +## Strict rules -- MUST NOT infer decisions that were not explicitly stated in the conversation. +- MUST NOT infer decisions not explicitly stated in the conversation. - MUST NOT add architectural opinions or suggest approaches. -- MUST NOT summarize, paraphrase, or analyze code beyond extracting factual references. -- MUST NOT produce implementation recommendations of any kind. -- MUST only capture what was explicitly said. If something is unclear, note it as an unresolved question. -- MUST ask at most 8 questions total. Prioritize the most important gaps. +- MUST NOT produce implementation recommendations. +- MUST capture only what was explicitly said. If unclear, mark it as unresolved. - SHOULD prefer multiple-choice questions when the answer space is bounded. -- SHOULD ask open-ended questions only when the space of valid answers is genuinely unbounded. -- SHOULD ask questions grounded in what you found in the codebase (e.g., "the codebase uses X — should this story follow the same pattern or switch to Y?"). +- SHOULD ground questions in codebase findings. + +## Workflow -## Output files +You work in a loop: scout the codebase, think through what you know, ask the user questions, then verify your understanding. You repeat until you are certain the decomposer has everything it needs. -You write two files, both inside the epic directory: +## Output -1. **context.md** — structured extraction of what was said in the conversation. -2. **decisions.md** — answers to the questions you asked the user. +One file: **context.md** in the epic directory. -## Tools available +## Tools -- All read tools (read, bash, grep, glob, find, ls) — for reading the conversation and codebase. -- \`koan_request_scouts\` — to request parallel codebase exploration. -- \`koan_ask_question\` — to ask the user clarifying questions via IPC. -- \`write\` / \`edit\` — for writing output files inside the epic directory only. -- \`koan_complete_step\` — to signal step completion with your findings.`; +- Read tools (read, bash, grep, glob, find, ls) — reading the conversation and codebase. +- \`koan_request_scouts\` — request parallel codebase exploration. +- \`koan_ask_question\` — ask the user clarifying questions. +- \`koan_set_confidence\` — declare your confidence level. +- \`write\` / \`edit\` — for writing context.md (final step only). +- \`koan_complete_step\` — signal step completion.`; } -export function intakeStepGuidance(step: number, conversationPath?: string): StepGuidance { +export function intakeStepGuidance(step: number, conversationPath?: string, iteration = 1): StepGuidance { switch (step) { + // ------------------------------------------------------------------------- + // Step 1: Extract — read the conversation, build a mental model. + // + // This step is intentionally read-only. The permission fence blocks + // koan_request_scouts, koan_ask_question, koan_set_confidence, write, and + // edit during step 1 so that comprehension cannot be short-circuited by + // premature action. + // ------------------------------------------------------------------------- case 1: return { title: INTAKE_STEP_NAMES[1], instructions: [ - "Read the conversation file and extract structured context into `context.md`.", + "Read the conversation file. Build a thorough mental model of what is being requested.", "", conversationPath ? `Conversation file: ${conversationPath}` : "Conversation file: locate `conversation.jsonl` in the epic directory.", "", - "The conversation file is JSONL (JSON Lines). Each line is a JSON object.", - "Look for entries with type 'message' and role 'user' or 'assistant' for content.", - "Ignore internal session entries (header, compaction, etc.).", - "", - "Write `context.md` to the epic directory with these exact sections:", - "", - "## Topic", - "One paragraph describing what is being built or changed. Use only information explicitly stated in the conversation.", - "", - "## File References", - "List every file, directory, or module mentioned in the conversation. One item per line.", - "If none were mentioned, write: (none mentioned)", + "The file is JSONL. Each line is a JSON object.", + "Read entries with type 'message' and role 'user' or 'assistant'.", + "Ignore internal entries (header, compaction, etc.).", "", - "## Decisions Made", - "List every decision that was explicitly stated and agreed upon. Format: `- [decision text]`", - "A decision must be explicitly stated — do not infer from context.", - "If none were made, write: (none recorded)", + "## What to internalize", "", - "## Constraints", - "List every explicit constraint: technical, timeline, compatibility, budget, etc.", - "If none were stated, write: (none stated)", + "As you read, track these categories:", + "- **Topic**: What is being built or changed?", + "- **File references**: Every file, directory, or module mentioned.", + "- **Decisions already made**: Only those explicitly stated and agreed upon.", + "- **Constraints**: Technical, timeline, compatibility requirements.", + "- **Gaps**: Questions raised but unanswered. Things unclear or unstated that would affect story boundaries.", "", - "## Unresolved Questions", - "List every question raised in the conversation that was NOT answered.", - "Also list any gaps you observe — things that must be known before planning can proceed.", - "Format: `- [question or gap description]`", + "## Rules for this step", "", - "Be faithful to the conversation. Do not invent context.", + "- Do NOT call koan_request_scouts, koan_ask_question, koan_set_confidence, write, or edit.", + "- This step is read-only. Understand the conversation before acting on it.", + "- Be faithful to what was said. Do not invent context or infer unstated decisions.", + "- If the conversation references specific files or systems, note them — you will scout those next.", ], }; + // ------------------------------------------------------------------------- + // Step 2: Scout — dispatch codebase investigators. + // + // Iteration-aware: first iteration explores based on the conversation; + // subsequent iterations follow up on gaps from the previous Reflect step. + // This is a focused step — do NOT ask the user questions here. + // ------------------------------------------------------------------------- case 2: return { title: INTAKE_STEP_NAMES[2], instructions: [ - "Based on the file references and topic in context.md, identify what needs codebase exploration.", + iteration === 1 + ? "Based on your reading of the conversation, identify areas of the codebase that need exploration." + : "Based on gaps identified in your previous reflection, identify follow-up areas to explore.", "", - "Use `koan_request_scouts` to gather codebase context before asking the user questions.", - "This grounds the questions in what actually exists — preventing questions the codebase already answers.", + "## What to scout", "", - "## When to scout", + "Use `koan_request_scouts` to dispatch parallel codebase investigators.", + "Each scout answers one narrow question. Formulate 1–5 scout tasks.", "", - "Scout when context.md mentions:", - "- Specific files, modules, or packages that should be verified or understood.", - "- Integration points with existing code (APIs, databases, auth, etc.).", - "- Areas where the user's assumptions may not match the codebase (e.g., 'we use React' but you should verify).", - "", - "Formulate 1–5 focused scout tasks. Each scout answers one narrow question.", - "", - "## Scout task format", + "Scout when:", + "- The conversation references specific files, modules, or systems.", + "- Integration points with existing code need verification (APIs, databases, auth).", + "- User assumptions about the codebase might not match reality.", + ...(iteration > 1 ? ["- Previous scout findings raised new questions or revealed unexpected patterns."] : []), "", "Each scout needs:", - "- id: short kebab-case identifier (e.g., 'auth-setup', 'api-structure')", - "- role: a focused investigator role (e.g., 'auth system auditor', 'API structure analyst')", - "- prompt: exactly what to find (e.g., 'Find all auth-related files and identify which auth library is used')", + "- id: short kebab-case identifier (e.g., 'auth-setup')", + "- role: investigator focus (e.g., 'authentication auditor')", + "- prompt: what to find (e.g., 'Find all auth middleware in src/ and identify the auth library used')", "", "## If no scouting is needed", "", - "If context.md has no file references and the topic is purely conceptual (no codebase inspection needed),", - "skip scouting and call koan_complete_step with: 'Scouting skipped — no codebase references in context.'", + "If the topic is purely conceptual and no codebase inspection is needed, skip scouting.", + "Do NOT ask the user questions in this step — that happens in Deliberate.", ], }; + // ------------------------------------------------------------------------- + // Step 3: Deliberate — enumerate knowns/unknowns, ask questions. + // + // Thread-of-Thought technique: explicitly walking through each area before + // formulating questions prevents asking things already answered and surfaces + // gaps that would otherwise be missed. + // + // Iteration-aware: first iteration covers all areas; subsequent iterations + // focus on new information and updated understanding. + // ------------------------------------------------------------------------- case 3: return { title: INTAKE_STEP_NAMES[3], instructions: [ - "Review `context.md` and scout findings together. Identify gaps. Ask the user. Write `decisions.md`.", + "Before asking questions, explicitly enumerate what you know and what you don't.", + "This grounds your questions in reality and prevents asking things already answered.", + "", + "## Phase A: Recite what you know", + "", + "Walk through each area relevant to the task and state what you have learned.", + "Use this structure for each area:", + "", + " **[Area name]** (e.g., 'Authentication', 'Database schema', 'API endpoints')", + " - Known: [what the conversation and/or scouts established]", + " - Unknown: [what remains unclear or unverified]", + " - Source: [conversation / scout findings / user answer from round N]", "", - "## Gap identification criteria", + iteration === 1 + ? "Cover every area relevant to the task. Be thorough — gaps you miss here become gaps in the final output." + : "Focus on areas where new information arrived since last round. Re-state updated understanding.", "", - "Ask about a gap if:", - "- The answer materially changes WHAT is built (scope, features, API shape).", - "- The answer materially changes HOW the work is sequenced (dependencies, ordering).", - "- Without the answer, the decomposer cannot split the work into stories.", - "- Scout findings reveal a contradiction with what the user described (e.g., user said 'we use Postgres' but scout found SQLite).", + "## Phase B: Formulate and ask questions", "", - "Do NOT ask about:", - "- Implementation choices (those belong to the planner role).", - "- Things the scout findings already answered.", - "- Nice-to-have clarifications that don't change the plan.", + "Review your 'Unknown' items. For each, decide:", + "- Can a follow-up scout answer this? → Note it for the next scout round.", + "- Must the user decide this? → Include it in your questions.", + "- Is this an implementation detail the planner should decide? → Skip it.", "", - "## Asking questions", + "Ask about a gap ONLY if:", + "- It materially changes WHAT is built (scope, features, API shape).", + "- It materially changes HOW work is sequenced (dependencies, ordering).", + "- Without the answer, story boundaries cannot be determined.", + "- Scout findings contradict what the user described.", "", - "Use `koan_ask_question` to send questions to the user. Maximum 8 questions.", + "Use `koan_ask_question`. Limit: 5 questions per round.", "Prefer multiple-choice when the answer space is bounded.", - "Reference scout findings in questions when relevant: 'The codebase uses X — should this follow the same pattern?'", + "Ground questions in specific findings: 'Scout found X — should this story follow the same pattern?'", + "", + "## If no questions are needed", + "", + "If all 'Unknown' items are either implementation details or answerable by follow-up scouts,", + "you may skip asking questions. Your recitation of knowns/unknowns is still required.", + ], + }; + + // ------------------------------------------------------------------------- + // Step 4: Reflect — verify completeness, declare confidence. + // + // Chain-of-Verification (CoVe) technique: the LLM generates its own + // verification questions and answers them using only gathered evidence + // (not intuition). This surfaces gaps that casual self-assessment misses. + // + // Metacognitive structure: understand → judge → critique → decide → assess. + // The "certain" level has a contrastive definition (positive checklist + + // "you are NOT certain if" list) to prevent premature exits from the loop. + // + // REQUIRED: koan_set_confidence must be called before koan_complete_step. + // The phase handler enforces this — koan_complete_step will be rejected + // with an error message if confidence has not been set. + // ------------------------------------------------------------------------- + case 4: + return { + title: INTAKE_STEP_NAMES[4], + instructions: [ + "Verify the completeness of your understanding before deciding whether to continue or stop.", + "This step is pure verification — do not scout or ask questions here.", + "", + "## Step 1: Verification questions", + "", + "Generate 3–5 questions that test whether your understanding is complete.", + "Frame them from the decomposer's perspective — the decomposer must split this work into stories.", + "", + "Example verification questions:", + "- 'Could I define the boundary between story 1 and story 2 right now?'", + "- 'If the user's codebase uses pattern X (per scout), does our understanding account for that?'", + "- 'Are there any user decisions that could split one story into two or merge two into one?'", + "", + "## Step 2: Answer each question", + "", + "Answer each verification question using ONLY evidence you have:", + "- Direct quotes or facts from the conversation", + "- Specific findings from scouts", + "- Explicit answers from the user", + "", + "If you cannot answer a verification question with evidence, that is a gap.", + "", + "## Step 3: Assess confidence", + "", + "Based on your verification answers, call `koan_set_confidence`.", + "", + "**certain** — all verification questions answered with evidence. The decomposer can define every story boundary.", + "**high** — most questions answered. Remaining unknowns would not change story structure.", + "**medium** — broad shape understood, but specific boundaries or sequencing decisions are unclear.", + "**low** — major gaps remain. Cannot define story boundaries.", + "**exploring** — have not yet scouted or asked questions.", + "", + "### Certain means ALL of these are true:", + "- Topic and scope are unambiguous.", + "- Codebase architecture relevant to the task is understood.", + "- All user decisions affecting story boundaries have been made.", + "- No question you could ask would change the number, order, or scope of stories.", + "", + "### You are NOT certain if:", + "- A scout revealed something surprising that needs follow-up.", + "- A user answer raised a new question you haven't explored.", + "- You skipped scouting an area that might affect story boundaries.", + "- You're unsure whether two pieces of work should be one story or two.", + "", + "## Step 4: If not certain, plan the next round", + "", + "If confidence < certain, briefly note:", + "- What gaps remain?", + "- Should the next round focus on scouting, asking, or both?", + "- What specific areas need follow-up?", + "", + "This plan will guide your next Scout step.", + ], + invokeAfter: [ + "WHEN DONE: First call koan_set_confidence, then call koan_complete_step.", + "You MUST call koan_set_confidence before koan_complete_step — step completion will be rejected without it.", + "Do NOT call koan_complete_step until you have worked through all four steps above.", + ].join("\n"), + }; + + // ------------------------------------------------------------------------- + // Step 5: Synthesize — write context.md. + // + // This step runs once, after the confidence loop exits. The LLM consolidates + // everything gathered across all iterations into a single structured file. + // + // A pre-write verification checklist ensures the output serves the + // decomposer's needs: if any checklist question cannot be answered, it must + // be noted in Open Items rather than silently omitted. + // ------------------------------------------------------------------------- + case 5: + return { + title: INTAKE_STEP_NAMES[5], + instructions: [ + "Write `context.md` to the epic directory.", + "This file is the sole input for all downstream phases. Write it carefully.", + "", + "## Required sections", + "", + "### Topic", + "One paragraph: what is being built or changed. Facts from the conversation only.", + "", + "### Codebase Findings", + "Key findings from scouts: architecture, patterns, existing code, integration points.", + "Organize by area, not by scout task or iteration.", + "If no scouts were needed: (no codebase exploration was needed)", "", - "## Writing decisions.md", + "### Decisions", + "Every question asked and the user's answer, across all rounds.", + "Format: **Q: [question]** / A: [answer]", + "If no questions were needed: (no questions were needed — context was sufficient)", "", - "After the user responds, write `decisions.md` to the epic directory:", + "### Constraints", + "All constraints discovered: from conversation, from codebase (scouts), from user answers.", + "If none: (none identified)", "", - "## Answers", - "For each question asked, record the question and the user's answer.", - "Format:", - "```", - "**Q: [question text]**", - "A: [user's answer]", - "```", + "### Open Items", + "Anything unresolved. Should be empty or near-empty if confidence was 'certain'.", + "If none: (none)", "", - "## Remaining Unknowns", - "List any gaps that remain unresolved. If none: write (none)", + "## Pre-write verification", "", - "If there were no meaningful gaps, write:", - "`## Answers\\n(no questions were needed — context and codebase survey were sufficient)`", + "Before writing, verify context.md answers these questions (the decomposer needs them):", + "- What is the top-level goal?", + "- What are the distinct deliverable units of work?", + "- What existing code does this touch and how is it structured?", + "- What decisions constrain how the work is split?", + "- Are there dependencies between work units?", "", - "Then call `koan_complete_step` with a brief summary:", - "- File references found", - "- Scouts requested and key findings", - "- Questions asked and answered", - "- Any remaining unknowns", + "If you cannot answer any of these from what you've gathered, note it in Open Items.", ], }; diff --git a/src/planner/phases/orchestrator/prompts.ts b/src/planner/phases/orchestrator/prompts.ts index efafd41..942ee78 100644 --- a/src/planner/phases/orchestrator/prompts.ts +++ b/src/planner/phases/orchestrator/prompts.ts @@ -41,7 +41,7 @@ You are a decision-maker. You read content, apply judgment, and direct the workf - **Verification**: Running the checks defined in a story's verify.md to determine whether the implementation is correct. - **Verdict**: Declaring the outcome of a story's execution — success or retry with feedback. - **Story selection**: Choosing which story executes next based on the dependency graph and current epic state. -- **Learning propagation**: When you discover something during verification, update remaining story.md files and decisions.md. Mark every autonomous update with \`[autonomous]\`. +- **Learning propagation**: When you discover something during verification, update remaining story.md files and the Decisions section of context.md. Mark every autonomous update with \`[autonomous]\`. - **User communication**: When you encounter genuine ambiguity or need human judgment, call \`koan_ask_question\`. After getting the answer, decide what to do (retry with new context, skip, etc.) and call the appropriate tool. ## When to ask the user @@ -92,7 +92,7 @@ export function orchestratorPreStepGuidance(step: number): StepGuidance { "## What to read", "", "1. Read `epic.md` in the epic directory — understand the overall goal and scope.", - "2. Read `decisions.md` in the epic directory — understand decisions that shape execution.", + "2. Read the Decisions section of `context.md` in the epic directory — understand decisions that shape execution.", "3. Read each `story.md` file for every story in the epic — understand what each story builds and depends on.", "", "## What to analyze", @@ -223,7 +223,7 @@ export function orchestratorPostStepGuidance(step: number, storyId?: string): St return { title: ORCHESTRATOR_POST_STEP_NAMES[3], instructions: [ - "Propagate lessons from this story's execution to remaining stories and the decisions log.", + "Propagate lessons from this story's execution to remaining stories and the Decisions section of context.md.", "", "## What to propagate", "", @@ -240,7 +240,7 @@ export function orchestratorPostStepGuidance(step: number, storyId?: string): St "1. Read its `story.md`.", "2. Add a `## [autonomous] Propagated Context` section with the relevant information.", "", - "Update `decisions.md` if a new decision was made or an existing one was invalidated.", + "Update the Decisions section of `context.md` if a new decision was made or an existing one was invalidated.", "Add `[autonomous]` prefix to any autonomous additions.", "", "If no propagation is needed, skip file updates and proceed.", diff --git a/src/planner/phases/planner/prompts.ts b/src/planner/phases/planner/prompts.ts index 1b6a9e0..bff6125 100644 --- a/src/planner/phases/planner/prompts.ts +++ b/src/planner/phases/planner/prompts.ts @@ -11,7 +11,7 @@ export function plannerSystemPrompt(): string { ## Your role -You read stories, codebase artifacts, and scout reports, then produce three output files: a step-by-step plan, a curated code context file, and a verification checklist. You do NOT write code. You do NOT make design decisions beyond what the story and decisions log specify. +You read stories, codebase artifacts, and scout reports, then produce three output files: a step-by-step plan, a curated code context file, and a verification checklist. You do NOT write code. You do NOT make design decisions beyond what the story and context.md specify. ## What you produce @@ -74,7 +74,7 @@ export function plannerStepGuidance(step: number, storyId: string): StepGuidance "## What to read", "", `1. Read \`stories/${storyId}/story.md\` in the epic directory — understand exactly what this story must accomplish, its acceptance criteria, and any noted constraints or dependencies.`, - "2. Read `decisions.md` in the epic directory — understand the architectural decisions and open questions that apply to this story. If a decision is marked as unresolved, check whether it blocks this story.", + "2. Read `context.md` in the epic directory — understand the scope, codebase findings, constraints, and decisions that apply to this story. If a decision is marked as unresolved, check whether it blocks this story.", "3. Read the scout reports returned by `koan_request_scouts` for current codebase context.", "", "## What to analyze", @@ -93,7 +93,7 @@ export function plannerStepGuidance(step: number, storyId: string): StepGuidance "- The list of files that will be modified or created", "- The sequence you plan for the steps (high-level)", "- Any risks or unresolved questions you identified", - "- Whether any open decisions in decisions.md block this story", + "- Whether any open decisions in context.md block this story", ], }; diff --git a/src/planner/tools/confidence.ts b/src/planner/tools/confidence.ts new file mode 100644 index 0000000..f293614 --- /dev/null +++ b/src/planner/tools/confidence.ts @@ -0,0 +1,76 @@ +// koan_set_confidence tool — intake phase confidence gate. +// +// Called by the intake agent during the Reflect step (step 4) to declare its +// current confidence that sufficient context has been gathered for the +// decomposer to split the work into stories. +// +// The IntakePhase reads ctx.intakeConfidence in getNextStep() to decide +// whether to loop back to Scout (step 2) or advance to Synthesize (step 5). +// Confidence is reset to null at every loop-back, so each Reflect step +// requires a fresh assessment — carry-over from a previous iteration is +// not possible. +// +// Confidence changes are appended to events.jsonl via the EventLog. The +// web server polls state.json (the folded projection) and can push SSE events +// to the UI when the intakeConfidence or intakeIteration fields change. + +import { Type } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import type { RuntimeContext } from "../lib/runtime-context.js"; + +// All valid confidence levels, ordered from least to most confident. +export type ConfidenceLevel = "exploring" | "low" | "medium" | "high" | "certain"; + +const CONFIDENCE_TOOL_DESCRIPTION = ` +Declare your current confidence that you have gathered sufficient context for the decomposer to split the work into stories. + +Call this BEFORE koan_complete_step during the Reflect step. Required — step completion will be rejected without it. + +Levels (from lowest to highest): +- exploring: Just started. Have not yet scouted or asked questions. +- low: Major gaps. Cannot define story boundaries. +- medium: Broad shape understood, specific boundaries unclear. +- high: Scope, boundaries, key decisions understood. Minor unknowns remain that would not change story structure. +- certain: Decomposer has everything it needs. No question would change story boundaries. +`.trim(); + +export function registerConfidenceTool(pi: ExtensionAPI, ctx: RuntimeContext): void { + pi.registerTool({ + name: "koan_set_confidence", + label: "Set intake confidence", + description: CONFIDENCE_TOOL_DESCRIPTION, + parameters: Type.Object({ + level: Type.Union( + [ + Type.Literal("exploring"), + Type.Literal("low"), + Type.Literal("medium"), + Type.Literal("high"), + Type.Literal("certain"), + ], + { description: "Your current confidence level (exploring | low | medium | high | certain)" }, + ), + }), + async execute(_toolCallId, params) { + const { level } = params as { level: ConfidenceLevel }; + + // Store on context so IntakePhase.getNextStep() can read it at step completion. + ctx.intakeConfidence = level; + + // Emit a confidence_change audit event. The EventLog folds it into + // state.json (updating intakeConfidence and intakeIteration fields), + // which the web server polls to push SSE events to the UI. + if (ctx.eventLog) { + // ctx.intakeIteration is set by IntakePhase.onStepUpdated() when each step + // is entered, so it always reflects the current iteration at tool call time. + await ctx.eventLog.emitConfidenceChange(level, ctx.intakeIteration); + } + + return { + content: [{ type: "text" as const, text: `Confidence set to ${level}.` }], + details: undefined, + }; + }, + }); +} diff --git a/src/planner/tools/index.ts b/src/planner/tools/index.ts index 6383a34..51f62fe 100644 --- a/src/planner/tools/index.ts +++ b/src/planner/tools/index.ts @@ -8,6 +8,7 @@ import type { RuntimeContext } from "../lib/runtime-context.js"; import { registerWorkflowTools } from "./workflow.js"; import { registerOrchestratorTools } from "./orchestrator.js"; import { registerAskTools } from "./ask.js"; +import { registerConfidenceTool } from "./confidence.js"; export type { RuntimeContext } from "../lib/runtime-context.js"; export { createRuntimeContext } from "../lib/runtime-context.js"; @@ -16,4 +17,5 @@ export function registerAllTools(pi: ExtensionAPI, ctx: RuntimeContext): void { registerWorkflowTools(pi, ctx); registerOrchestratorTools(pi, ctx); registerAskTools(pi, ctx); + registerConfidenceTool(pi, ctx); } diff --git a/src/planner/web/js/components/phases/Consolidation.jsx b/src/planner/web/js/components/phases/Consolidation.jsx index 5af7e54..96c3c51 100644 --- a/src/planner/web/js/components/phases/Consolidation.jsx +++ b/src/planner/web/js/components/phases/Consolidation.jsx @@ -21,7 +21,7 @@ export function Consolidation() { )}
◌ - Writing decisions.md... + Writing context.md...
{logs.length > 0 && ( From 88f8f42bdf3b16f76e1b974988fb10911cb13f7f Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 19 Mar 2026 20:48:05 +0700 Subject: [PATCH 065/412] thinking cards in activity feed with centered layout --- src/planner/web/css/animations.css | 22 +++ src/planner/web/css/layout.css | 70 ++++++++- .../web/js/components/ActivityFeed.jsx | 146 ++++++++++++++---- 3 files changed, 211 insertions(+), 27 deletions(-) diff --git a/src/planner/web/css/animations.css b/src/planner/web/css/animations.css index 046b2b8..d5a4680 100644 --- a/src/planner/web/css/animations.css +++ b/src/planner/web/css/animations.css @@ -38,3 +38,25 @@ from { opacity: 1; transform: translateY(0); } to { opacity: 0; transform: translateY(8px); } } + +/* Thinking indicator */ +@keyframes thinking-pulse { + 0%, 100% { opacity: 0.3; } + 50% { opacity: 1; } +} + +.thinking-dot { + animation: thinking-pulse 1.5s ease-in-out infinite; +} + +.thinking-timer { + color: var(--text-muted); + font-variant-numeric: tabular-nums; + margin-left: 0.4em; +} + +.agent-doing-thinking { + color: var(--text-muted); +} + + diff --git a/src/planner/web/css/layout.css b/src/planner/web/css/layout.css index b20b374..43e5214 100644 --- a/src/planner/web/css/layout.css +++ b/src/planner/web/css/layout.css @@ -133,7 +133,75 @@ .activity-feed-inner { display: flex; flex-direction: column; - gap: 1px; + gap: 2px; + max-width: 960px; + margin: 0 auto; +} + +/* ---- Activity cards (thinking, future: tool results) ---- */ + +.activity-card { + background: var(--bg-surface); + border: 1px solid var(--border); + border-radius: var(--radius-md); + margin: var(--gap-xs) 0; + overflow: hidden; +} + +.activity-card-active { + border-color: var(--blue-border); +} + +.activity-card-header { + display: flex; + justify-content: space-between; + align-items: center; + padding: var(--gap-xs) var(--gap-md); + font-family: var(--font-mono); + font-size: var(--font-size-sm); +} + +.activity-card-tool { + color: var(--text-muted); +} + +.activity-card-thinking .activity-card-tool { + color: var(--purple); +} + +.activity-card-meta { + color: var(--text-dim); + font-size: var(--font-size-xs); +} + +.activity-card-body { + padding: 0 var(--gap-md) var(--gap-sm); + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--text-dim); + white-space: pre-wrap; + word-break: break-word; + line-height: 1.5; +} + +.activity-card-body:not(.expanded) { + display: -webkit-box; + -webkit-line-clamp: 3; + -webkit-box-orient: vertical; + overflow: hidden; +} + +.activity-card-more { + padding: 2px var(--gap-md) var(--gap-sm); + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--blue); + cursor: pointer; + user-select: none; +} + +.activity-card-more:hover { + color: var(--text-strong); } .activity-line { diff --git a/src/planner/web/js/components/ActivityFeed.jsx b/src/planner/web/js/components/ActivityFeed.jsx index ed71786..f3c5c50 100644 --- a/src/planner/web/js/components/ActivityFeed.jsx +++ b/src/planner/web/js/components/ActivityFeed.jsx @@ -1,6 +1,106 @@ -import { useRef, useEffect, useState } from 'preact/hooks' +import { useRef, useEffect, useState, useCallback } from 'preact/hooks' import { useStore } from '../store.js' +function ThinkingTimer({ since }) { + const [elapsed, setElapsed] = useState(0) + + useEffect(() => { + const start = new Date(since).getTime() + const tick = () => setElapsed(Math.floor((Date.now() - start) / 1000)) + tick() + const id = setInterval(tick, 1000) + return () => clearInterval(id) + }, [since]) + + const text = elapsed < 60 + ? `${elapsed}s` + : `${Math.floor(elapsed / 60)}m ${elapsed % 60}s` + + return {text} +} + +/** Card for thinking entries — shows expandable thought content */ +function ThinkingCard({ line, isInFlight, isFlashing }) { + const [expanded, setExpanded] = useState(false) + const bodyRef = useRef(null) + const [isClamped, setIsClamped] = useState(false) + + // Detect whether the body text is actually clamped (more content than visible) + useEffect(() => { + const el = bodyRef.current + if (el) setIsClamped(el.scrollHeight > el.clientHeight + 2) + }, [line.body, expanded]) + + const cls = [ + 'activity-card', + 'activity-card-thinking', + isInFlight ? 'activity-card-active' : '', + isFlashing ? 'activity-flash' : '', + ].filter(Boolean).join(' ') + + return ( +
+
+ thinking + + {isInFlight + ? + : line.summary + } + +
+ {line.body && ( + <> +
+ {line.body} +
+ {(isClamped && !expanded) && ( +
setExpanded(true)}> + show more ▸ +
+ )} + {expanded && ( +
setExpanded(false)}> + show less ▴ +
+ )} + + )} +
+ ) +} + +/** Standard line for tool calls and lifecycle events */ +function ActivityLine({ line, isInFlight, isFlashing }) { + const cls = [ + 'activity-line', + line.highValue ? 'activity-high' : '', + isInFlight ? 'activity-inflight' : '', + isFlashing ? 'activity-flash' : '', + ].filter(Boolean).join(' ') + + return ( + <> +
+ {line.tool} + + {line.summary || ''} + {isInFlight && ...} + +
+ {line.details?.map((d, j) => ( +
+ + {d} +
+ ))} + + ) +} + export function ActivityFeed() { const logs = useStore(s => s.logs) const containerRef = useRef(null) @@ -29,12 +129,11 @@ export function ActivityFeed() { prevLastRef.current = lastLine ? { ...lastLine } : null }, [logs]) - function onScroll() { + const onScroll = useCallback(() => { const el = containerRef.current if (!el) return - // "At bottom" if within 30px of the end. stickRef.current = el.scrollTop + el.clientHeight >= el.scrollHeight - 30 - } + }, []) if (logs.length === 0) return null @@ -42,32 +141,27 @@ export function ActivityFeed() {
{logs.map((line, i) => { - // Only the last line can be in-flight — earlier lines are always done. const isInFlight = !!line.inFlight && i === logs.length - 1 const isFlashing = i === flashIndex - const cls = [ - 'activity-line', - line.highValue ? 'activity-high' : '', - isInFlight ? 'activity-inflight' : '', - isFlashing ? 'activity-flash' : '', - ].filter(Boolean).join(' ') + + if (line.tool === 'thinking') { + return ( + + ) + } return ( - <> -
- {line.tool} - - {line.summary || ''} - {isInFlight && ...} - -
- {line.details?.map((d, j) => ( -
- - {d} -
- ))} - + ) })}
From cc27be69a3c8ea194408ed9bd7f501e5ab224332 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 19 Mar 2026 21:00:31 +0700 Subject: [PATCH 066/412] scout queued status, agent monitor UI, configurable concurrency --- src/planner/lib/ipc-responder.ts | 11 ++- src/planner/model-config.ts | 39 ++++++++ src/planner/web/css/components.css | 57 +++++++++-- .../web/js/components/AgentMonitor.jsx | 15 ++- src/planner/web/js/components/AgentRow.jsx | 99 ++++++++++++++----- src/planner/web/js/components/ModelConfig.jsx | 21 ++++ src/planner/web/js/sse.js | 2 +- src/planner/web/server-types.ts | 21 +++- src/planner/web/server.ts | 97 +++++++++++++----- 9 files changed, 292 insertions(+), 70 deletions(-) diff --git a/src/planner/lib/ipc-responder.ts b/src/planner/lib/ipc-responder.ts index 7d55cee..49ff0bd 100644 --- a/src/planner/lib/ipc-responder.ts +++ b/src/planner/lib/ipc-responder.ts @@ -24,6 +24,7 @@ import { import type { ScoutTask as TaskScoutTask } from "./task.js"; import { pool } from "./pool.js"; import { readProjection } from "./audit.js"; +import { loadScoutConcurrency } from "../model-config.js"; import type { WebServerHandle, AskQuestion, AnswerResult } from "../web/server-types.js"; import { OTHER_OPTION } from "../web/server-types.js"; @@ -133,8 +134,9 @@ async function handleScoutRequest( return { ipcTask, subagentDir: scoutDir }; }); - // Register scouts with the web server before spawning so the UI shows them - // immediately rather than waiting for the first audit poll. + // Register scouts with the web server as queued (status: null) so the UI + // shows them immediately. They transition to "running" when the pool picks + // them up and the pi process is actually launched. if (webServer) { for (const entry of scoutEntries) { webServer.registerAgent({ @@ -144,18 +146,21 @@ async function handleScoutRequest( role: "scout", model: null, parent: scoutCtx.parentRole, + status: null, }); } } const taskIds = scoutEntries.map((t) => t.ipcTask.id); + const concurrency = await loadScoutConcurrency(); await pool( taskIds, - 4, + concurrency, async (taskId) => { if (signal.aborted) return { exitCode: 1, stderr: "aborted", subagentDir: "" }; const entry = scoutEntries.find((t) => t.ipcTask.id === taskId)!; + webServer?.startAgent(taskId); await fs.mkdir(entry.subagentDir, { recursive: true }); // Construct the task manifest for this scout. The IPC-level ipcTask carries diff --git a/src/planner/model-config.ts b/src/planner/model-config.ts index 80d968a..248d727 100644 --- a/src/planner/model-config.ts +++ b/src/planner/model-config.ts @@ -18,6 +18,7 @@ export type ModelTierConfig = Record; interface KoanConfigFile { modelTiers?: Record; + scoutConcurrency?: number; [key: string]: unknown; } @@ -73,6 +74,44 @@ export async function loadModelTierConfig(): Promise { return result as ModelTierConfig; } +// -- Scout concurrency ------------------------------------------------------- + +const DEFAULT_SCOUT_CONCURRENCY = 8; + +export async function loadScoutConcurrency(): Promise { + try { + const raw = await fs.readFile(CONFIG_PATH, "utf8"); + const parsed = JSON.parse(raw) as KoanConfigFile; + if (typeof parsed.scoutConcurrency === "number" && parsed.scoutConcurrency > 0) { + return parsed.scoutConcurrency; + } + } catch { + // File missing or invalid — use default. + } + return DEFAULT_SCOUT_CONCURRENCY; +} + +export async function saveScoutConcurrency(concurrency: number): Promise { + const configDir = path.dirname(CONFIG_PATH); + await fs.mkdir(configDir, { recursive: true }); + + let existing: KoanConfigFile = {}; + try { + const raw = await fs.readFile(CONFIG_PATH, "utf8"); + existing = JSON.parse(raw) as KoanConfigFile; + } catch { + // Start fresh. + } + + existing.scoutConcurrency = concurrency; + + const tmpPath = `${CONFIG_PATH}.tmp`; + await fs.writeFile(tmpPath, `${JSON.stringify(existing, null, 2)}\n`, "utf8"); + await fs.rename(tmpPath, CONFIG_PATH); +} + +// -- Model tiers (save) ------------------------------------------------------ + export async function saveModelTierConfig(config: ModelTierConfig): Promise { const configDir = path.dirname(CONFIG_PATH); await fs.mkdir(configDir, { recursive: true }); diff --git a/src/planner/web/css/components.css b/src/planner/web/css/components.css index a81ccc7..ce2c191 100644 --- a/src/planner/web/css/components.css +++ b/src/planner/web/css/components.css @@ -58,6 +58,7 @@ .agent-table { width: 100%; border-collapse: collapse; + table-layout: fixed; font-size: var(--font-size-sm); } @@ -78,24 +79,39 @@ border-bottom: 1px solid var(--border-light); } -.col-status { width: 24px; text-align: center; } -.col-model { width: 90px; white-space: nowrap; } -.col-parent { width: 90px; white-space: nowrap; } -.col-tokens { width: 60px; text-align: right; white-space: nowrap; } -.col-doing { /* flex */ } +.col-status { width: 28px; text-align: center; } +.col-agent { width: 170px; } +.col-model { width: 170px; } +.col-tokens { width: 70px; text-align: right; } +.col-doing { /* takes remaining */ } +.agent-table td, +.agent-table th { + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.agent-table td.col-doing { + white-space: normal; +} + +.agent-status-queued { color: var(--text-dim); } .agent-status-running { color: var(--blue); } .agent-status-done { color: var(--green); font-weight: 600; } .agent-status-failed { color: var(--red); } +.agent-name-queued { color: var(--text-dim); font-family: var(--font-mono); } .agent-name-running { color: var(--text); font-weight: 600; font-family: var(--font-mono); } .agent-name-done { color: var(--green); font-family: var(--font-mono); } .agent-name-failed { color: var(--red); font-family: var(--font-mono); } .agent-model-cell { font-family: var(--font-mono); color: var(--text-muted); } -.agent-parent-cell { font-family: var(--font-mono); color: var(--text-dim); } .agent-tokens-cell { font-family: var(--font-mono); color: var(--text-muted); } +.agent-doing-dim { font-family: var(--font-mono); font-size: var(--font-size-xs); color: var(--text-dim); } +.agent-doing-failed { color: var(--red); } + .agent-doing-lines { display: flex; flex-direction: column; @@ -109,7 +125,6 @@ white-space: nowrap; overflow: hidden; text-overflow: ellipsis; - max-width: 600px; } .agent-doing-line:last-child { @@ -304,6 +319,34 @@ animation: slide-open 150ms ease-out; } +/* ---- Config sections ---- */ +.model-config-section { + margin-top: var(--gap-xl); +} + +.model-config-section-heading { + font-size: var(--font-size-lg); + font-weight: 600; + color: var(--text-strong); + margin: 0 0 var(--gap-xs) 0; +} + +.scout-concurrency-input { + width: 80px; + padding: var(--gap-sm) var(--gap-md); + background: var(--bg); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + color: var(--text); + font-family: var(--font-mono); + font-size: var(--font-size-md); +} + +.scout-concurrency-input:focus { + border-color: var(--blue-border); + outline: none; +} + /* ---- Form actions ---- */ .form-actions { display: flex; diff --git a/src/planner/web/js/components/AgentMonitor.jsx b/src/planner/web/js/components/AgentMonitor.jsx index b87d763..e6a7966 100644 --- a/src/planner/web/js/components/AgentMonitor.jsx +++ b/src/planner/web/js/components/AgentMonitor.jsx @@ -4,13 +4,17 @@ import { AgentRow } from './AgentRow.jsx' export function AgentMonitor() { const allAgents = useStore(s => s.agents) - // Only show nested subagents (those with a parent), and only running ones - const agents = allAgents.filter(a => a.status === 'running' && a.parent) + const agents = allAgents.filter(a => a.parent) + + // Hide entirely when no agents, or when all are done (batch complete) + const hasActive = agents.some(a => a.status === 'running' || a.status === null) + if (agents.length === 0 || !hasActive) return null + + const running = agents.filter(a => a.status === 'running' || a.status === null).length + const done = agents.filter(a => a.status === 'completed').length const sent = agents.reduce((s, a) => s + (a.tokensSent || 0), 0) const recv = agents.reduce((s, a) => s + (a.tokensReceived || 0), 0) - if (agents.length === 0) return null - // Dynamic lines-per-agent based on count const maxLines = agents.length <= 3 ? 5 : agents.length <= 6 ? 3 @@ -22,7 +26,8 @@ export function AgentMonitor() {
Subagents
- {agents.length} + {running} + {done > 0 && {done}}
{(sent > 0 || recv > 0) ? `↑${formatTokens(sent)} ↓${formatTokens(recv)}` : ''} diff --git a/src/planner/web/js/components/AgentRow.jsx b/src/planner/web/js/components/AgentRow.jsx index 8bc678f..aad1a0b 100644 --- a/src/planner/web/js/components/AgentRow.jsx +++ b/src/planner/web/js/components/AgentRow.jsx @@ -1,40 +1,91 @@ +import { useState, useEffect } from 'preact/hooks' import { shortenModel, formatTokens } from '../lib/utils.js' +function ThinkingTimer({ since }) { + const [elapsed, setElapsed] = useState(0) + + useEffect(() => { + const start = new Date(since).getTime() + const tick = () => setElapsed(Math.floor((Date.now() - start) / 1000)) + tick() + const id = setInterval(tick, 1000) + return () => clearInterval(id) + }, [since]) + + const text = elapsed < 60 + ? `${elapsed}s` + : `${Math.floor(elapsed / 60)}m ${elapsed % 60}s` + + return {text} +} + +const STATUS = { + null: { symbol: '○', statusCls: 'agent-status-queued', nameCls: 'agent-name-queued' }, + running: { symbol: '●', statusCls: 'agent-status-running', nameCls: 'agent-name-running' }, + completed: { symbol: '✓', statusCls: 'agent-status-done', nameCls: 'agent-name-done' }, + failed: { symbol: '✗', statusCls: 'agent-status-failed', nameCls: 'agent-name-failed' }, +} + export function AgentRow({ agent, maxLines = 5 }) { + const s = STATUS[agent.status] || STATUS.running const actions = agent.recentActions || [] const start = Math.max(0, actions.length - maxLines) return ( - ● - {agent.name || agent.id} + {s.symbol} + {agent.name || agent.id} {shortenModel(agent.model)} {formatTokens(agent.tokensSent || 0)} {formatTokens(agent.tokensReceived || 0)} - {actions.length > 0 ? ( -
- {actions.slice(start).map((action, i) => { - // Gracefully handle both old string[] and new object[] formats. - const text = typeof action === 'string' - ? action - : (action.summary ? `${action.tool}: ${action.summary}` : action.tool) - const inFlight = typeof action === 'object' && !!action.inFlight - - return ( -
- - {inFlight ? '●' : '·'} - - {text} -
- ) - })} -
- ) : ( - initializing... - )} + ) } + +function DoingCell({ status, actions, start }) { + if (status === null) return queued + if (status === 'completed') return done + if (status === 'failed') return failed + + // running + if (actions.length === 0) return initializing... + + return ( +
+ {actions.slice(start).map((action, i) => { + const isThinking = typeof action === 'object' && action.tool === 'thinking' + const inFlight = typeof action === 'object' && !!action.inFlight + + if (isThinking) { + return ( +
+ + {inFlight ? '●' : '·'} + + {inFlight + ? <>thinking + : `thought for ${action.summary}` + } +
+ ) + } + + const text = typeof action === 'string' + ? action + : (action.summary ? `${action.tool}: ${action.summary}` : action.tool) + + return ( +
+ + {inFlight ? '●' : '·'} + + {text} +
+ ) + })} +
+ ) +} diff --git a/src/planner/web/js/components/ModelConfig.jsx b/src/planner/web/js/components/ModelConfig.jsx index 64feb3f..f067a46 100644 --- a/src/planner/web/js/components/ModelConfig.jsx +++ b/src/planner/web/js/components/ModelConfig.jsx @@ -32,10 +32,13 @@ function groupByProvider(models) { })) } +const DEFAULT_SCOUT_CONCURRENCY = 8 + export function ModelConfig({ token, isGate = false, onClose }) { const pending = useStore(s => s.pendingInput) const availableModels = useStore(s => s.availableModels) const [tiers, setTiers] = useState({ strong: '', standard: '', cheap: '' }) + const [scoutConcurrency, setScoutConcurrency] = useState(DEFAULT_SCOUT_CONCURRENCY) const [loading, setLoading] = useState(true) const [saving, setSaving] = useState(false) @@ -48,6 +51,7 @@ export function ModelConfig({ token, isGate = false, onClose }) { standard: t?.standard || '', cheap: t?.cheap || '', }) + setScoutConcurrency(t?.scoutConcurrency || DEFAULT_SCOUT_CONCURRENCY) setLoading(false) return } @@ -61,6 +65,7 @@ export function ModelConfig({ token, isGate = false, onClose }) { cheap: data.tiers.cheap || '', }) } + if (data.scoutConcurrency) setScoutConcurrency(data.scoutConcurrency) setLoading(false) }) .catch(() => setLoading(false)) @@ -74,6 +79,7 @@ export function ModelConfig({ token, isGate = false, onClose }) { standard: tiers.standard || null, cheap: tiers.cheap || null, }, + scoutConcurrency, } if (isGate && pending?.requestId) { body.requestId = pending.requestId @@ -132,6 +138,21 @@ export function ModelConfig({ token, isGate = false, onClose }) { ))}
+
+

Scout Concurrency

+

+ Maximum number of scout agents to run in parallel during codebase investigation. +

+ setScoutConcurrency(Math.max(1, Math.min(32, parseInt(e.target.value) || DEFAULT_SCOUT_CONCURRENCY)))} + /> +
+
{!isGate && ( diff --git a/src/planner/web/js/sse.js b/src/planner/web/js/sse.js index 20b5ae6..35d0cb1 100644 --- a/src/planner/web/js/sse.js +++ b/src/planner/web/js/sse.js @@ -18,7 +18,7 @@ export function connectSSE(token) { ask: (d) => set({ pendingInput: { type: 'ask', requestId: d.requestId, payload: d.questions } }), review: (d) => set({ pendingInput: { type: 'review', requestId: d.requestId, payload: d.stories } }), 'model-config': (d) => set(s => ({ - pendingInput: { type: 'model-config', requestId: d.requestId, payload: d.tiers }, + pendingInput: { type: 'model-config', requestId: d.requestId, payload: { ...d.tiers, scoutConcurrency: d.scoutConcurrency } }, ...(d.availableModels ? { availableModels: d.availableModels } : {}), })), 'model-config-confirmed': () => set(s => s.pendingInput?.type === 'model-config' ? { pendingInput: null } : {}), diff --git a/src/planner/web/server-types.ts b/src/planner/web/server-types.ts index 6cc8edc..2812073 100644 --- a/src/planner/web/server-types.ts +++ b/src/planner/web/server-types.ts @@ -171,10 +171,23 @@ export interface PipelineEndEvent { summary: string; } +// Confidence level type for the intake confidence loop. +export type IntakeConfidenceLevel = "exploring" | "low" | "medium" | "high" | "certain" | null; + +export interface IntakeProgressEvent { + subPhase: string | null; + intakeDone: boolean; + // The most recent confidence level declared by koan_set_confidence. + // Null before the first Reflect step completes. + confidence: IntakeConfidenceLevel; + // The current loop iteration (1-based). Zero before the loop begins. + iteration: number; +} + export interface ScoutState { id: string; role: string; - status: "running" | "completed" | "failed"; + status: "running" | "completed" | "failed" | null; lastAction: string | null; eventCount: number; model: string | null; @@ -193,10 +206,10 @@ export interface AgentEntry { role: string; model: string | null; parent: string | null; - status: "running" | "completed" | "failed"; + status: "running" | "completed" | "failed" | null; tokensSent: number; tokensReceived: number; - recentActions: Array<{ tool: string; summary: string; inFlight: boolean }>; + recentActions: Array<{ tool: string; summary: string; inFlight: boolean; ts?: string }>; subPhase: string | null; } @@ -236,7 +249,9 @@ export interface WebServerHandle { role: string; model: string | null; parent: string | null; + status?: "running" | null; }): void; + startAgent(id: string): void; completeAgent(id: string): void; // Blocking input methods diff --git a/src/planner/web/server.ts b/src/planner/web/server.ts index 5424178..075a30a 100644 --- a/src/planner/web/server.ts +++ b/src/planner/web/server.ts @@ -13,7 +13,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent"; import { readProjection, readRecentLogs } from "../lib/audit.js"; -import { loadModelTierConfig, saveModelTierConfig, type ModelTierConfig } from "../model-config.js"; +import { loadModelTierConfig, saveModelTierConfig, loadScoutConcurrency, saveScoutConcurrency, type ModelTierConfig } from "../model-config.js"; import type { WebServerHandle, AskQuestion, @@ -22,6 +22,7 @@ import type { AnswerResult, AnswerElement, LogLine, + IntakeProgressEvent, } from "./server-types.js"; import type { EpicPhase, StoryStatus } from "../types.js"; @@ -187,10 +188,10 @@ interface AgentInfoInternal { role: string; model: string | null; parent: string | null; - status: "running" | "completed" | "failed"; + status: "running" | "completed" | "failed" | null; tokensSent: number; tokensReceived: number; - recentActions: Array<{ tool: string; summary: string; inFlight: boolean }>; + recentActions: Array<{ tool: string; summary: string; inFlight: boolean; ts?: string }>; spawnOrder: number; completionOrder?: number; pollingTimer?: ReturnType; @@ -198,6 +199,9 @@ interface AgentInfoInternal { subPhase: string | null; eventCount: number; completionSummary: string | null; + // Cached most-recent projection from pollAgent(), used by the polling timer + // to read confidence/iteration without issuing a second readProjection call. + lastProjection?: import("../lib/audit.js").Projection; } // --------------------------------------------------------------------------- @@ -233,10 +237,14 @@ export async function startWebServer(epicDir: string): Promise let lastLogs: LogLine[] = []; let pipelineEnd: { success: boolean; summary: string } | null = null; - // Denormalized intake progress buffer - let currentIntakeProgress: { subPhase: string | null; intakeDone: boolean } = { + // Denormalized intake progress buffer. Includes confidence and iteration from + // the intake agent's projection so the UI can visualize loop progress. + // Typed as IntakeProgressEvent so the SSE payload is compile-time verified. + let currentIntakeProgress: IntakeProgressEvent = { subPhase: null, intakeDone: false, + confidence: null, + iteration: 0, }; // SSE clients @@ -294,7 +302,7 @@ export async function startWebServer(epicDir: string): Promise const scoutArray = buildScoutsArray(); if (scoutArray.length > 0) write("scouts", { scouts: scoutArray }); - if (currentIntakeProgress.subPhase !== null || currentIntakeProgress.intakeDone) { + if (currentIntakeProgress.subPhase !== null || currentIntakeProgress.intakeDone || currentIntakeProgress.confidence !== null) { write("intake-progress", currentIntakeProgress); } @@ -320,18 +328,10 @@ export async function startWebServer(epicDir: string): Promise function buildAgentsArray(): Array<{ id: string; name: string; role: string; model: string | null; - parent: string | null; status: string; tokensSent: number; - tokensReceived: number; recentActions: Array<{ tool: string; summary: string; inFlight: boolean }>; subPhase: string | null; + parent: string | null; status: string | null; tokensSent: number; + tokensReceived: number; recentActions: Array<{ tool: string; summary: string; inFlight: boolean; ts?: string }>; subPhase: string | null; }> { - const sorted = Array.from(agents.values()).sort((a, b) => { - if (a.status === "running" && b.status !== "running") return -1; - if (b.status === "running" && a.status !== "running") return 1; - if (a.status !== "failed" && b.status === "failed") return -1; - if (b.status !== "failed" && a.status === "failed") return 1; - const aOrder = a.status === "running" ? a.spawnOrder : (a.completionOrder ?? a.spawnOrder); - const bOrder = b.status === "running" ? b.spawnOrder : (b.completionOrder ?? b.spawnOrder); - return aOrder - bOrder; - }); + const sorted = Array.from(agents.values()).sort((a, b) => a.spawnOrder - b.spawnOrder); return sorted.map((a) => ({ id: a.id, name: a.name, @@ -347,7 +347,7 @@ export async function startWebServer(epicDir: string): Promise } function buildScoutsArray(): Array<{ - id: string; role: string; status: string; lastAction: string | null; + id: string; role: string; status: string | null; lastAction: string | null; eventCount: number; model: string | null; completionSummary: string | null; tokensSent: number; tokensReceived: number; }> { @@ -381,17 +381,31 @@ export async function startWebServer(epicDir: string): Promise agent.tokensSent = projection.tokensSent; agent.tokensReceived = projection.tokensReceived; agent.eventCount = projection.eventCount; + // Cache the latest projection so polling timers can read confidence/iteration + // without issuing a second readProjection call for the same agent. + agent.lastProjection = projection; if (projection.status !== "running") { agent.status = projection.status; } if (agent.role === "intake") { const hasPendingAsk = Array.from(pendingInputs.values()).some((p) => p.type === "ask"); - const STEP_PHASE: Record = { 0: "context", 1: "context", 2: "explore", 3: "spec" }; - agent.subPhase = hasPendingAsk ? "questions" : (STEP_PHASE[projection.step] ?? "spec"); + // Map intake step numbers to display sub-phase names. + // Steps 2-4 repeat across iterations; show "questions" when user input is pending. + const STEP_PHASE: Record = { + 0: "extract", 1: "extract", + 2: "scout", 3: "deliberate", 4: "reflect", + 5: "synthesize", + }; + agent.subPhase = hasPendingAsk ? "questions" : (STEP_PHASE[projection.step] ?? "reflect"); } } if (logs.length > 0) { - agent.recentActions = logs.slice(-5).map((l) => ({ tool: l.tool, summary: l.summary || '', inFlight: l.inFlight })); + agent.recentActions = logs.slice(-5).map((l) => ({ + tool: l.tool, + summary: l.summary || '', + inFlight: l.inFlight, + ...(l.ts ? { ts: l.ts } : {}), + })); } if (agent.role === "scout" && projection?.completionSummary && !agent.completionSummary) { agent.completionSummary = projection.completionSummary; @@ -413,8 +427,21 @@ export async function startWebServer(epicDir: string): Promise // Push intake-progress event if the intake agent's sub-phase changed const intake = Array.from(agents.values()).find(a => a.role === "intake"); if (intake) { - const next = { subPhase: intake.subPhase, intakeDone: currentPhase !== "intake" && currentPhase !== null }; - if (next.subPhase !== currentIntakeProgress.subPhase || next.intakeDone !== currentIntakeProgress.intakeDone) { + // Use the projection already read by pollAgent (cached on agent.lastProjection) + // to avoid a redundant readProjection call for the same file in the same tick. + const intakeProjection = intake.lastProjection ?? null; + const next: IntakeProgressEvent = { + subPhase: intake.subPhase, + intakeDone: currentPhase !== "intake" && currentPhase !== null, + confidence: intakeProjection?.intakeConfidence ?? null, + iteration: intakeProjection?.intakeIteration ?? 0, + }; + const changed = + next.subPhase !== currentIntakeProgress.subPhase || + next.intakeDone !== currentIntakeProgress.intakeDone || + next.confidence !== currentIntakeProgress.confidence || + next.iteration !== currentIntakeProgress.iteration; + if (changed) { currentIntakeProgress = next; pushEvent("intake-progress", currentIntakeProgress); } @@ -489,7 +516,7 @@ export async function startWebServer(epicDir: string): Promise if (method === "PUT" && pathname === "/api/model-config") { const body = await readBody(req).catch(() => null); - const b = body as { requestId?: string; tiers: Record } | null; + const b = body as { requestId?: string; tiers: Record; scoutConcurrency?: number } | null; if (!b) { sendJson(res, 400, { ok: false, error: "Invalid body" }); return; } const { requestId, tiers } = b; @@ -501,6 +528,11 @@ export async function startWebServer(epicDir: string): Promise await saveModelTierConfig({ strong, standard, cheap } as ModelTierConfig); } + // Save scout concurrency + if (typeof b.scoutConcurrency === "number" && b.scoutConcurrency > 0) { + await saveScoutConcurrency(b.scoutConcurrency); + } + // Resolve the blocking gate if requestId matches if (requestId) { const entry = pendingInputs.get(requestId); @@ -664,10 +696,11 @@ export async function startWebServer(epicDir: string): Promise registerAgent(info: { id: string; name: string; dir: string; role: string; model: string | null; parent: string | null; + status?: "running" | null; }): void { const agent: AgentInfoInternal = { ...info, - status: "running", + status: info.status ?? "running", tokensSent: 0, tokensReceived: 0, recentActions: [], @@ -677,11 +710,20 @@ export async function startWebServer(epicDir: string): Promise completionSummary: null, }; agents.set(info.id, agent); - startAgentPolling(agent); + if (agent.status === "running") startAgentPolling(agent); pushEvent("agents", { agents: buildAgentsArray() }); if (info.role === "scout") pushEvent("scouts", { scouts: buildScoutsArray() }); }, + startAgent(id: string): void { + const agent = agents.get(id); + if (!agent || agent.status !== null) return; + agent.status = "running"; + startAgentPolling(agent); + pushEvent("agents", { agents: buildAgentsArray() }); + if (agent.role === "scout") pushEvent("scouts", { scouts: buildScoutsArray() }); + }, + completeAgent(id: string): void { const agent = agents.get(id); if (!agent) return; @@ -768,7 +810,8 @@ export async function startWebServer(epicDir: string): Promise async requestModelConfig(): Promise { const requestId = randomUUID(); const config = await loadModelTierConfig(); - const payload = { requestId, tiers: config, availableModels }; + const scoutConcurrency = await loadScoutConcurrency(); + const payload = { requestId, tiers: config, scoutConcurrency, availableModels }; return new Promise((resolve, reject) => { pendingInputs.set(requestId, { type: "model-config" as const, From 1161c4e8ccb37a95276707292a1579d7bc4b700a Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 19 Mar 2026 21:00:38 +0700 Subject: [PATCH 067/412] architecture documentation --- AGENTS.md | 8 + docs/architecture.md | 289 +++++++++++++++++++++++++++++++ docs/intake-loop.md | 388 ++++++++++++++++++++++++++++++++++++++++++ docs/ipc.md | 320 ++++++++++++++++++++++++++++++++++ docs/state.md | 298 ++++++++++++++++++++++++++++++++ docs/subagents.md | 397 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 1700 insertions(+) create mode 100644 docs/architecture.md create mode 100644 docs/intake-loop.md create mode 100644 docs/ipc.md create mode 100644 docs/state.md create mode 100644 docs/subagents.md diff --git a/AGENTS.md b/AGENTS.md index ea5ff9f..d0bcee7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,7 @@ Spoke documents: - [docs/subagents.md](docs/subagents.md) — spawn lifecycle, task manifest, step-first workflow, permissions - [docs/ipc.md](docs/ipc.md) — file-based IPC protocol, scout spawning, question routing - [docs/state.md](docs/state.md) — driver/LLM boundary, epic and story state, routing rules +- [docs/intake-loop.md](docs/intake-loop.md) — confidence-gated loop, non-linear step progression, prompt engineering --- @@ -35,6 +36,10 @@ Tool returns: Step 1 instructions (rich context, task details, guidance) Tool returns: Step 2 instructions (or "Phase complete.") ``` +Step progression is normally linear, but subclasses may override `getNextStep()` +to implement non-linear flows. The intake phase loops steps 2–4 until a +confidence gate is satisfied. See [docs/intake-loop.md](docs/intake-loop.md). + ## 3. Driver Determinism The driver reads JSON state files and exit codes, applies routing rules, and @@ -45,6 +50,9 @@ spawns the next subagent. It never makes judgment calls or parses free-text. Every tool call passes through a role-based permission fence. Unknown roles and tools are blocked. Planning roles can only write inside the epic directory. +The fence also supports step-level gating for individual roles: the intake +phase blocks side-effecting tools during its read-only Extract step (step 1). + ## 5. Need-to-Know Prompts Boot prompt is one sentence. System prompt has role identity, no task details. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..ad5c34d --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,289 @@ +# Koan Architecture + +Koan is a deterministic pipeline that spawns isolated LLM subagents to plan and +execute complex coding tasks. This document captures the design invariants, +principles, and pitfalls that govern the codebase. + +**Spoke documents** cover subsystems in depth: + +- [Subagents](./subagents.md) — spawn lifecycle, boot protocol, step-first + workflow, phase dispatch, permissions, model tiers +- [IPC](./ipc.md) — file-based inter-process communication between parent and + subagent, scout spawning, question routing +- [State & Driver](./state.md) — the driver/LLM boundary, JSON vs markdown + ownership, epic and story state, routing rules +- [Intake Loop](./intake-loop.md) — confidence-gated investigation loop, + non-linear step progression, prompt engineering principles + +--- + +## Core Invariants + +These are load-bearing rules. Violating any one of them breaks the system in +ways that are difficult to diagnose. + +### 1. File boundary + +LLMs write **markdown files only**. The driver maintains **JSON state files** +internally — no LLM ever reads or writes a `.json` file. + +Tool code bridges both worlds: orchestrator tools write JSON state (for the +driver) and templated `status.md` (for LLMs). The driver reads JSON and exit +codes; it never parses markdown. + +``` +Orchestrator calls koan_complete_story(story_id) + → tool code writes state.json + status.md + → driver reads state.json to route next action + → LLM reads status.md if it needs to reference the decision +``` + +**Why:** If an LLM writes JSON, schema drift and parse errors become runtime +failures in the deterministic driver. Markdown is forgiving; JSON is not. + +### 2. Step-first workflow + +Every subagent is a `pi -p` process. Once the LLM produces text without a tool +call, the process exits — there is no stdin to recover. The entire workflow +depends on the LLM calling `koan_complete_step` reliably. + +**The first thing any subagent does is call `koan_complete_step`.** The spawn +prompt contains *only* this directive. The tool returns step 1 instructions. +This establishes the calling pattern before the LLM sees complex instructions. + +``` +Boot prompt: "You are a koan {role} agent. Call koan_complete_step to receive your instructions." + ↓ LLM calls koan_complete_step (step 0 → 1 transition) +Tool returns: Step 1 instructions (rich context, task details, guidance) + ↓ LLM does work... + ↓ LLM calls koan_complete_step +Tool returns: Step 2 instructions (or "Phase complete.") +``` + +Three reinforcement mechanisms make this robust across model capability levels: + +| Mechanism | Where | Why | +|-----------|-------|-----| +| **Primacy** | Boot prompt is the LLM's very first message | First action = tool call, at the top of conversation history | +| **Recency** | `formatStep()` appends "WHEN DONE: Call koan_complete_step..." last | LLMs weight end-of-context instructions heavily | +| **Muscle memory** | By step 2+ the LLM has called the tool N times | Pattern is locked in through repetition | + +### 3. Driver determinism + +The driver (`driver.ts`) is a deterministic state machine. It reads JSON state +files and exit codes, applies routing rules, and spawns the next subagent. It +never makes judgment calls, parses free-text output, or adapts to LLM behavior. + +**Routing priority** in the story loop: +1. `retry` status → re-execute (retry takes precedence over new work) +2. `selected` status → plan + execute +3. All stories `done` or `skipped` → epic complete +4. None of the above → error ("orchestrator may have exited without a routing decision") + +### 4. Default-deny permissions + +Every tool call in a subagent passes through a permission fence (`tool_call` +event handler in `BasePhase`). Unknown roles are blocked. Unknown tools are +blocked. Planning roles can only write inside the epic directory. + +The one accepted limitation: `READ_TOOLS` (bash, read, grep, glob, find, ls) +are always allowed because distinguishing "read bash" from "write bash" is +intractable at the permission layer. **Prompt engineering constrains intended +bash use; enforcement does not.** + +### 5. Need-to-know prompts + +Each subagent receives only the minimum context for its task: + +- The **boot prompt** is one sentence (role identity + "call koan_complete_step") +- The **system prompt** establishes role identity and rules, but no task details +- **Task details** arrive via step 1 guidance (returned by the first tool call) + +This is not just tidiness — it is load-bearing. A previous design injected +step 1 guidance into the first user message (via a `context` event handler), +but that front-loaded complex instructions before the LLM had established the +`koan_complete_step` calling pattern. Weaker models (haiku) produced text +output and exited without entering the workflow. The `context` event handler +was deliberately removed; step guidance is now delivered exclusively through +`koan_complete_step` return values. + +### 6. Directory-as-contract + +The subagent directory is the **sole interface** between parent and child. +Everything a subagent needs — its task, its communication channel, its +observable state — lives in well-known files inside that directory. + +Three JSON files, three lifecycles: + +| File | Writer | Reader | Lifecycle | +|------|--------|--------|-----------| +| **`task.json`** | Parent (before spawn) | Child (once, at startup) | Write-once, never modified | +| **`state.json`** | Child (continuously) | Parent (polling) | Eagerly materialized audit projection | +| **`ipc.json`** | Both (request/response) | Both (polling) | Temporary — created per request, deleted after response | + +The spawn command carries only the directory path. The child reads `task.json` +to discover its role, epic context, and task-specific parameters. No +structured configuration flows through CLI flags, environment variables, or +other process-level channels. + +``` +# Spawn interface: one koan flag, the rest is pi-level +pi -p -e {extensionPath} --koan-dir {subagentDir} [--model {model}] "{bootPrompt}" +``` + +**Why:** CLI flags are a flat namespace — they cause naming collisions (e.g., +`--koan-role` for pipeline role vs `--koan-scout-role` for investigator +persona), cannot represent nested structure, are visible in process listings, +and are subject to `ARG_MAX` limits for large values like retry context. +Files are structured, inspectable (`cat task.json`), typed, and consistent +with how we already handle runtime communication (IPC) and observation (audit). + +See [subagents.md § Task Manifest](./subagents.md#task-manifest) for the +`task.json` schema and spawn flow. + +--- + +## Atomic Writes + +All persistent writes (JSON state, IPC files, status.md, audit state.json) +use the same pattern: write to a `.tmp` file, then `fs.rename()` to the target. +This prevents partial reads during concurrent access. + +```typescript +const tmp = path.join(dir, "file.tmp"); +await fs.writeFile(tmp, content, "utf8"); +await fs.rename(tmp, target); +``` + +This is not optional — the IPC responder, web server, and audit system all +poll files concurrently. A partial read of `ipc.json` or `state.json` would +cause silent data corruption or spurious errors. + +--- + +## Tool Registration Constraint + +All tools **must** be registered unconditionally at extension init, before +pi's `_buildRuntime()` snapshot. Tools registered after `_buildRuntime()` are +invisible to the LLM. + +CLI flags are unavailable during init (`getFlag()` returns undefined before +`_buildRuntime()` sets flagValues), so conditional registration based on role +is impossible. Instead: + +1. All tools register at init, reading from the mutable `RuntimeContext` at call time +2. `BasePhase.registerHandlers()` adds a `tool_call` event listener that checks permissions per-role at runtime +3. The `RuntimeContext` is populated later, during `before_agent_start` + +This is the **mutable-ref pattern**: static registration, dynamic dispatch. + +--- + +## Pitfalls + +Lessons learned from previous failures. Check new changes against these. + +### Don't put task content in spawn prompts + +The boot prompt must be exactly one sentence: role identity + "call +koan_complete_step". Putting task content (file paths, instructions, context) +risks the LLM producing text output on the first turn and exiting. This has +happened with haiku-class models and is not recoverable. + +### Don't inject step guidance via the `context` event + +A `context` event handler that injects step 1 guidance into the first user +message was tried and removed. It creates the same problem as putting content +in the spawn prompt — the LLM sees complex instructions before establishing +the tool-calling pattern. + +### Don't add `escalated` as a story status + +Escalation is handled via `koan_ask_question` (IPC → web server → user +answers → IPC response). A separate `escalated` status was tried and created +a dead routing path — the driver had nowhere clean to send it without +duplicating the ask UI flow that IPC already handles. + +### Don't add `scouting` as an epic phase + +Scouts run inside the IPC responder during intake/decomposer/planner phases, +not as a top-level driver phase. Adding `scouting` to `EpicPhase` would imply +a driver state that never exists, creating dead code paths. + +### Don't rely on file existence for scout success + +Scout success is derived from the JSON projection (`readProjection()` → +`status === "completed"`), not from checking whether `findings.md` exists. +A scout can write a partial findings file and then crash — file existence is +not proof of completion. + +### Don't write state.json from outside state.ts / tool code + +The state module (`epic/state.ts`) and orchestrator tools are the only +writers of JSON state. `status.md` writes belong exclusively in +`tools/orchestrator.ts`. Mixing these responsibilities violates the file +boundary invariant. + +### Don't call koan_complete_step in the tool description eagerly + +The tool description says "DO NOT call this tool until the step instructions +explicitly tell you to." Without this guard, aggressive models call +`koan_complete_step` immediately after receiving step guidance, skipping +the actual work. + +### Don't assume bash is restricted per role + +`bash` is in `READ_TOOLS` and always allowed. The permission layer cannot +distinguish a read-bash from a write-bash. Prompt engineering is the only +constraint. Do not assume bash calls are blocked for planning roles. + +### Don't rely on prompt instructions alone to restrict step behavior + +Prompt instructions can be ignored by the LLM. The intake phase learned this +the hard way: the original 3-step design told the LLM not to scout in step 1, +but the LLM frontloaded all work into step 1 anyway, causing duplicate scout +requests in later steps. + +Mechanical enforcement is required for any behavior that is critical to +correctness. Use the permission fence (`checkPermission` with `intakeStep`) to +block tools that must not be used in a given step. Use +`validateStepCompletion()` to block step advancement when required pre-calls +have not been made. Prompts express intent; enforcement catches non-compliance. + +See [intake-loop.md § Step-Aware Permission Gating](./intake-loop.md#step-aware-permission-gating). + +### Don't parse free-text for loop control decisions + +Confidence (the gate that controls the intake loop) is a structured enum +value set via a dedicated tool call, not a sentiment extracted from the LLM's +`thoughts` text. The driver determinism invariant prohibits parsing free-text +for routing decisions. Any loop gate must flow through a typed tool parameter +and a structured context field. + +### Don't put side effects in getNextStep() + +`getNextStep()` must be a pure query — it returns the next step number and +nothing else. Putting state mutations, counter increments, or event emission +inside `getNextStep()` violates this contract and makes the method unsafe to +reason about (e.g., a test that calls `getNextStep()` to inspect the decision +should not trigger side effects). + +Side effects that accompany a loop-back belong in `onLoopBack()`, which +`BasePhase` calls after detecting a backward transition: + +``` +BAD: getNextStep(4) { this.iteration++; this.ctx.confidence = null; return 2; } +GOOD: getNextStep(4) { return 2; } + onLoopBack(4, 2) { this.iteration++; this.ctx.confidence = null; } +``` + +The `onLoopBack()` hook is async and properly awaited, ensuring event +emission (`emitIterationStart`) is correctly sequenced in `events.jsonl`. + +### Don't pass structured data through CLI flags + +If information is needed by a subagent, write it to `task.json` in the +subagent directory before spawning. CLI flags are for bootstrap only (locating +the directory). Structured data in flags creates flat-namespace collisions, +size limits, and an uninspectable interface. The directory-as-contract +invariant exists specifically to prevent this. diff --git a/docs/intake-loop.md b/docs/intake-loop.md new file mode 100644 index 0000000..47a4563 --- /dev/null +++ b/docs/intake-loop.md @@ -0,0 +1,388 @@ +# Intake Loop Design + +How the intake phase implements a confidence-gated investigation loop, and the +prompt engineering principles that govern it. + +> Parent doc: [architecture.md](./architecture.md) +> Related: [subagents.md § Step-First Workflow](./subagents.md#step-first-workflow-basephase) + +--- + +## Overview + +The intake phase is the most consequential subagent in the pipeline. Its +single output — `context.md` — is the sole input for all downstream phases. +Every story boundary, every implementation plan, and every line of code +produced downstream depends on the completeness and accuracy of that file. +Gaps in `context.md` compound: a missed decision becomes a wrong story +boundary becomes a wrong plan becomes wrong code. + +This weight justifies a more elaborate workflow than other phases. Rather than +a fixed sequence of steps, intake runs a **confidence-gated loop**: the LLM +scouts the codebase, enumerates what it knows, asks the user questions, and +then explicitly self-verifies its understanding. The loop repeats until the +LLM declares it is "certain" the decomposer has everything it needs. + +### Step structure + +| Step | Name | Runs | Purpose | +|------|------|------|---------| +| 1 | Extract | 1× | Read `conversation.jsonl`. No side effects. | +| 2 | Scout | 1–4× | Dispatch codebase investigators. | +| 3 | Deliberate | 1–4× | Enumerate knowns/unknowns, ask user questions. | +| 4 | Reflect | 1–4× | Self-verify completeness, declare confidence. | +| 5 | Synthesize | 1× | Write `context.md`. | + +Steps 2–4 form the loop. Each call to `koan_complete_step` during these steps +either returns the next step in sequence or loops back from step 4 to step 2. +Steps 1 and 5 execute exactly once. + +--- + +## Non-Linear Step Progression + +### `getNextStep()` hook + +The `BasePhase` class previously used a hardcoded linear counter: +`step+1` until `totalSteps`, then `null` (done). This was extended with a +`getNextStep(currentStep)` hook that subclasses override to implement +non-linear flows. + +```typescript +// Default: strictly linear. +protected getNextStep(currentStep: number): number | null { + if (currentStep === this.totalSteps) return null; + return currentStep + 1; +} +``` + +`IntakePhase` overrides this to implement the confidence gate: + +```typescript +// Pure query — returns where to go, does not mutate state. +protected getNextStep(currentStep: number): number | null { + if (currentStep === 4) { // Reflect step + if (confidence === "certain" || isExhausted) { + return 5; // → Synthesize + } + return 2; // → Scout (loop back) + } + if (currentStep === 5) return null; // Synthesize → done + return currentStep + 1; // linear for steps 1–3 +} + +// Side effects of the loop-back decision live here, not in getNextStep(). +protected override async onLoopBack(_from: number, _to: number): Promise { + this.iteration++; + this.ctx.intakeConfidence = null; // reset for next round + await this.eventLog?.emitIterationStart(this.iteration, MAX_ITERATIONS); +} +``` + +`getNextStep()` is a **pure query** — it only decides where to go. All side +effects (counter increments, state resets, event emission) belong in +`onLoopBack()`, which `BasePhase.handleStepComplete()` calls whenever +`getNextStep()` returns a step number less than the current one. This +separation makes `getNextStep()` safe to reason about and test in isolation. + +All other phase classes inherit the default linear behavior. The hook localizes +non-linear logic to the one class that needs it without touching other phases. + +**Why not a separate loop-phase class?** The `BasePhase` machinery (boot +transition, permission fence, event logging, step formatting) is the same +regardless of whether progression is linear or not. A hook is cheaper than a +new abstraction tier and does not require refactoring the six existing phase +classes. + +### `totalSteps` semantics with a loop + +For `IntakePhase`, `totalSteps = 5` reflects the number of distinct step +definitions, not the number of `koan_complete_step` calls. The loop may +execute steps 2–4 up to four times, producing up to 1 + (3 × 4) + 1 = 14 +calls in the worst case. The `step_transition` event carries both the step +number and the iteration-annotated step name (e.g., "Scout (round 3)") so the +UI can distinguish loop iterations. + +--- + +## The Confidence Gate + +### Why a separate tool, not a parameter + +An earlier design considered adding `confidence` as an optional parameter to +`koan_complete_step`. This was rejected for two reasons: + +1. **Optional parameters are skippable.** LLMs frequently omit optional + parameters, especially when under token pressure. A separate tool call is + harder to skip accidentally — the LLM must make an explicit decision. + +2. **`koan_complete_step` is shared across all phases.** Adding confidence to + it would either bloat the parameter schema for roles that never set + confidence, or require conditional schema logic that the permission fence + cannot express cleanly. A dedicated `koan_set_confidence` tool, restricted + to the intake role via `ROLE_PERMISSIONS`, keeps the boundary clean. + +### Mandatory enforcement via `validateStepCompletion()` + +`BasePhase` exposes a `validateStepCompletion(step)` hook that runs before +`getNextStep()`. It returns null to allow advancement or an error string that +is returned as the `koan_complete_step` tool result — the LLM sees it and +must fix the pre-condition before retrying. + +`IntakePhase` uses this to enforce that `koan_set_confidence` was called in +the Reflect step: + +```typescript +protected async validateStepCompletion(step: number): Promise { + if (step === 4 && this.ctx.intakeConfidence === null) { + return "You must call koan_set_confidence before completing the Reflect step. ..."; + } + return null; +} +``` + +This is mechanical enforcement on top of the prompt-level instruction. If the +LLM ignores the prompt and calls `koan_complete_step` without first calling +`koan_set_confidence`, it receives an error and must comply. + +### Confidence reset on loop-back + +When `getNextStep()` returns step 2 (loop-back), `BasePhase` detects the +backward transition and calls `onLoopBack()`. `IntakePhase.onLoopBack()` +resets `ctx.intakeConfidence = null`. This ensures that in the next Reflect +step, the LLM must call `koan_set_confidence` again — carry-over from the +previous iteration is not possible. + +Without the reset, a LLM that set confidence to "high" in iteration 1 could +call `koan_complete_step` in iteration 2's Reflect step without reassessing, +and `validateStepCompletion` would let it through. + +**Note:** The audit projection's `intakeConfidence` field is updated only when +a `confidence_change` event is appended (i.e., when `koan_set_confidence` is +called). Between loop-back and the next Reflect step, the projection still +shows the previous iteration's confidence level. This is intentional: the +projection reflects the last declared state, not the reset internal state. The +UI reads the projection, so it shows the previous confidence until a new one +is declared. + +### Maximum iterations + +The loop is bounded at 4 iterations (`IntakePhase.MAX_ITERATIONS`). When +exhausted, `getNextStep()` returns step 5 (Synthesize) instead of step 2. +`IntakePhase` logs a warning when this forced exit occurs. This prevents +infinite loops if the LLM consistently declares non-certain confidence. + +--- + +## Step-Aware Permission Gating + +### Why step 1 is mechanically read-only + +Step 1 (Extract) should only read the conversation. Before this redesign, step +isolation was enforced only through prompt instructions ("do NOT call +koan_request_scouts in this step"). The LLM frequently violated this by +frontloading all work into step 1, leading to duplicate scout requests in +later steps. + +The new design adds a mechanical layer: `checkPermission()` accepts an +optional `intakeStep` parameter and blocks a defined set of tools when +`role === "intake" && intakeStep === 1`: + +``` +koan_request_scouts, koan_ask_question, koan_set_confidence, write, edit +``` + +The current step is propagated via `ctx.intakeStep`, kept in sync by the +`onStepUpdated()` hook in `IntakePhase`: + +```typescript +protected onStepUpdated(step: number): void { + this.ctx.intakeStep = step; + this.ctx.intakeIteration = this.iteration; +} +``` + +`BasePhase.handleStepComplete()` calls `onStepUpdated()` on every step +transition (including loop-backs), so `ctx.intakeStep` always reflects the +current active step at tool call time. + +### Prompt + enforcement is not redundant + +The prompt still tells the LLM not to use side-effecting tools in step 1. +The permission gate is a fallback that catches prompt non-compliance. Together: +the prompt prevents the behavior; the gate catches it when the prompt fails. +Neither alone is sufficient — the prompt can be ignored; the gate with no +prompt would produce confusing "blocked" errors with no context for the LLM. + +--- + +## Audit Events and SSE Propagation + +Two new audit event types support UI visualization of confidence and iteration: + +| Event | Emitted by | When | +|-------|-----------|------| +| `confidence_change` | `koan_set_confidence` tool | Every call to koan_set_confidence | +| `iteration_start` | `IntakePhase.onLoopBack()` + `onStepUpdated()` | At every loop iteration start: `onLoopBack` for iterations 2+, `onStepUpdated` for iteration 1 | + +Both events are folded into the `state.json` projection: + +- `confidence_change` → `intakeConfidence`, `intakeIteration` +- `iteration_start` → `intakeIteration` + +The web server polls `state.json` every 500ms for each active agent. When it +detects a change in `intakeConfidence` or `intakeIteration`, it pushes an +`intake-progress` SSE event to connected browser clients. The event payload +includes both the `confidence` string and the `iteration` number, allowing the +UI to render a progress visualization without maintaining its own state. + +The `confidence_change` event requires `ctx.eventLog` to be set. This is +populated in `extensions/koan.ts` during `before_agent_start`, after +`eventLog.open()`. The confidence tool reads `ctx.eventLog` at call time +(mutable-ref pattern) — no reference is needed at registration time. + +--- + +## Prompt Engineering Principles + +The intake loop prompts apply several techniques from the prompting literature. +This section records the reasoning so future changes don't inadvertently remove +mechanisms that address specific failure modes. + +### Prompt Chaining over Stepwise (Scout / Deliberate / Reflect as separate steps) + +A monolithic "investigate" step — containing scouting, deliberation, and +reflection in sequence within a single prompt — was rejected in favor of three +separate `koan_complete_step` calls. + +The risk with a monolithic step is **simulated refinement**: the LLM +artificially degrades its initial output to manufacture visible improvement. +When draft, critique, and refine happen in one cognitive context, the model +sandbaggs the draft to make its self-correction look meaningful. When each +phase is a separate tool call with a distinct cognitive goal, the model must +genuinely complete each phase before seeing the next instruction. There is no +opportunity to pre-plan the "improvement" because the next step's instructions +are not yet visible. + +This is why Scout, Deliberate, and Reflect are separate steps rather than +phases within a single step. + +### Thread-of-Thought in Deliberate (explicit enumeration before questions) + +The Deliberate step instructs the LLM to walk through each area relevant to +the task and explicitly state what is known, unknown, and its source — before +formulating questions. This is the Thread-of-Thought pattern: "walk through +this context in manageable parts step by step, summarizing and analyzing as we +go." + +Without this enumeration, the LLM tends to ask questions based on what +immediately comes to mind rather than what is actually unknown. Gaps that are +not top-of-mind are missed. Forcing explicit enumeration of knowns and unknowns +before question formulation surfaces those gaps and prevents asking questions +the conversation or scouts already answered. + +The enumeration also has a secondary benefit in iteration 2+: it forces the +LLM to re-state updated understanding before forming follow-up questions, +preventing the "lost in the middle" problem where findings from early scout +tool results are effectively forgotten by the time questions are formulated. + +### Chain-of-Verification in Reflect (evidence-grounded self-assessment) + +The Reflect step instructs the LLM to generate 3–5 verification questions +framed from the decomposer's perspective, then answer each using only concrete +evidence (quotes from conversation, specific scout findings, explicit user +answers). Verification questions that cannot be answered with evidence identify +gaps. This is the Chain-of-Verification (CoVe) pattern. + +The framing matters: "from the decomposer's perspective" anchors the LLM's +self-assessment to the actual consumer of its output. Without this framing, the +LLM tends to ask generic comprehension questions ("do I understand the topic?") +rather than boundary-defining questions ("could I define the scope of story 1 +vs story 2 right now?"). Generic questions produce generic assessments; +boundary-specific questions surface the gaps that actually matter downstream. + +This is explicitly NOT intrinsic self-correction, which degrades reasoning +performance when no external feedback source is available. The LLM is not +being asked to critique its reasoning — it is being asked to generate specific +verification questions and answer them against gathered evidence. The evidence +is external (conversation, scouts, user answers), not the LLM's own reasoning. + +### Contrastive confidence definitions (preventing premature "certain") + +The Reflect step provides two contrastive definitions of the "certain" +confidence level: + +- **Positive:** "certain means ALL of these are true" (four specific + conditions about scope, codebase knowledge, user decisions, and story + immutability) +- **Negative:** "you are NOT certain if" (four failure modes that preclude + certainty) + +This is the Contrastive Chain-of-Thought pattern. A single positive definition +("certain means you have everything you need") leaves the LLM to interpret what +"everything" means — and LLMs tend to interpret this charitably, setting +confidence to "certain" prematurely to exit the loop faster (token-saving +behavior). The negative examples make the failure modes concrete and explicit, +raising the bar for claiming certainty. + +### Iteration-aware guidance (first iteration vs. refinement) + +Steps 2 (Scout) and 3 (Deliberate) produce different instruction text for +the first iteration vs. subsequent iterations. First-iteration Scout says: +"Based on your reading of the conversation..." Subsequent Scout says: "Based +on gaps identified in your previous reflection..." + +This is context reframing. The first iteration is an initial exploration; the +second iteration is a targeted follow-up. If both iterations received the same +prompt, the LLM would repeat its initial exploration rather than narrowing in +on the gaps surfaced by reflection. The iteration number is passed as a +parameter to `intakeStepGuidance()`, which branches on it to produce the +appropriate framing. + +--- + +## Pitfalls + +### Don't put confidence in koan_complete_step's `thoughts` parameter + +`thoughts` is for internal chain-of-thought reasoning. A previous design +considered parsing confidence from the thoughts string. This violates the +driver determinism invariant: the driver never parses free-text. Confidence +must flow through a structured tool call with a typed parameter. + +### Don't rely on the Reflect prompt alone to enforce koan_set_confidence + +The Reflect step prompt ends with "WHEN DONE: First call koan_set_confidence, +then call koan_complete_step." This is a prompt instruction and can be ignored. +The `validateStepCompletion()` hook is the mechanical enforcement layer. Both +must be present: the prompt tells the LLM what to do; the hook catches +non-compliance. + +### Don't remove the confidence null-reset on loop-back + +The null-reset lives in `onLoopBack()` in `IntakePhase`. When looping from +step 4 → step 2, `ctx.intakeConfidence` must be set to null. Without this +reset, the `validateStepCompletion()` check in the next Reflect step sees the +old confidence value and allows `koan_complete_step` through without the LLM +calling `koan_set_confidence` again. + +The reset must happen in `onLoopBack()`, not in `getNextStep()`. Placing it +in `getNextStep()` would make the query impure — see +[architecture.md § Don't put side effects in getNextStep()](./architecture.md#dont-put-side-effects-in-getnextstep). + +### Don't add koan_set_confidence to non-intake roles + +`koan_set_confidence` is gated to the intake role via `ROLE_PERMISSIONS`. If +it were available to other roles, they could set `ctx.intakeConfidence` +spuriously, affecting the intake loop's behavior if intake is running +concurrently (which it isn't currently, but could be in the future). + +### Don't skip `ctx.intakeStep` sync in onStepUpdated + +The permission gate reads `ctx.intakeStep` at tool call time. If +`onStepUpdated()` were not called on loop-back (step 4 → step 2), step 2 +would execute with `ctx.intakeStep = 4`, and the step-1 gate would not fire +(step 4 ≠ 1). The step 1 gate is specifically `intakeStep === 1`. Only step 1 +needs gating, so the only critical sync is the boot → step 1 transition. But +keeping `ctx.intakeStep` accurate at all times makes the invariant easier to +reason about and avoids subtle bugs if the gating logic is ever extended. diff --git a/docs/ipc.md b/docs/ipc.md new file mode 100644 index 0000000..a2de236 --- /dev/null +++ b/docs/ipc.md @@ -0,0 +1,320 @@ +# IPC Protocol + +File-based inter-process communication between parent and subagent processes. + +> Parent doc: [architecture.md](./architecture.md) +> +> `ipc.json` is one of three well-known files in the subagent directory. +> See [architecture.md § Directory-as-contract](./architecture.md#6-directory-as-contract) +> for how it relates to `task.json` (input) and `state.json` (observation). + +--- + +## Overview + +Subagent `pi -p` processes cannot communicate with the parent via stdin (it is +`"ignore"`). Instead, they share a single `ipc.json` file in the subagent +directory. The subagent writes a request; the parent polls, handles it, and +writes the response back. The subagent polls for the response. + +``` +subagent: writeIpcFile(dir, { response: null }) ← atomic write creates request +subagent: poll loop (500ms): readIpcFile(dir) ← blocks LLM turn +parent: poll loop (300ms): readIpcFile(dir) ← detects request +parent: handles request (web server or scout pool) ← does work +parent: writeIpcFile(dir, { ..., response: data }) ← atomic write with response +subagent: readIpcFile → response !== null ← breaks poll loop +subagent: deleteIpcFile(dir) ← cleanup +``` + +### Why file-based IPC + +- **Cross-process simplicity** — no socket management, no connection lifecycle +- **Debuggable** — `cat ipc.json` shows the current state +- **Atomic via rename** — tmp file → `fs.rename()` prevents partial reads +- **Cross-platform** — no POSIX-specific constructs + +### Constraints + +- **One request at a time** per subagent directory. Tools check + `ipcFileExists(dir)` before writing and return an error if a request is + already pending. +- **Polling, not push** — inherent latency of poll intervals (300ms parent, + 500ms subagent). +- **The subagent's LLM turn is blocked** while polling. The tool's `execute` + function is in a `sleep(500)` loop — the LLM cannot do other work until + the response arrives. + +--- + +## Message Types + +The protocol supports exactly two request types, discriminated by the `type` +field: + +### `ask` — User questions + +The subagent needs human input. The request contains questions with options; +the response contains the user's selections. + +```typescript +interface AskIpcFile { + type: "ask"; + id: string; // UUID, for response correlation + createdAt: string; + payload: { + questions: Array<{ + id: string; + question: string; + options: Array<{ label: string }>; + multi?: boolean; + recommended?: number; // 0-indexed + }>; + }; + response: AskResponse | null; // null = pending, non-null = answered +} +``` + +### `scout-request` — Parallel codebase exploration + +The subagent needs codebase context. The request contains scout task +definitions; the response contains file paths to findings. + +```typescript +interface ScoutIpcFile { + type: "scout-request"; + id: string; + createdAt: string; + scouts: Array<{ + id: string; // e.g., "auth-patterns" + role: string; // e.g., "security auditor" + prompt: string; // e.g., "Find all auth middleware in src/" + }>; + response: { findings: string[]; failures: string[] } | null; +} +``` + +--- + +## Atomic Writes + +All IPC file operations use atomic tmp-rename: + +```typescript +// Write: .ipc.tmp.json → rename → ipc.json +async function writeIpcFile(dir, data) { + const tmp = path.join(dir, ".ipc.tmp.json"); + const target = path.join(dir, "ipc.json"); + await fs.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", "utf8"); + await fs.rename(tmp, target); +} + +// Read: returns null on missing file OR parse error +// Parse errors are treated as "not ready" — handles partial writes on non-POSIX systems +async function readIpcFile(dir): IpcFile | null { + try { + const raw = await fs.readFile(path.join(dir, "ipc.json"), "utf8"); + return JSON.parse(raw); + } catch { + return null; + } +} + +// Delete: removes both ipc.json and .ipc.tmp.json, swallows ENOENT +async function deleteIpcFile(dir) { ... } +``` + +--- + +## Poll Timing + +| Poller | Interval | Purpose | +|--------|----------|---------| +| **Parent IPC responder** | 300ms | Detect subagent requests quickly | +| **Subagent tool** | 500ms | Wait for parent response | +| **Web server agent polling** | 500ms | Update agent status in UI | + +The parent polls slightly faster than the subagent to ensure it picks up +requests promptly. Both intervals are low enough for interactive feel. + +--- + +## Parent-Side IPC Responder + +`runIpcResponder()` starts concurrently with the child process (when a web +server handle is available) and terminates when the `AbortSignal` fires +(child process exit → abort). + +``` +while (!signal.aborted) { + sleep(300ms) + ipc = readIpcFile(subagentDir) + if ipc === null or ipc.response !== null → continue + if ipc.type === "ask" → handleAskRequest(...) + if ipc.type === "scout-request" → handleScoutRequest(...) +} +``` + +### Error handling + +The poll loop swallows **all** errors. Transient filesystem issues (e.g., +file being renamed) must not abort the parent session. The next poll cycle +will pick up the file successfully. + +### Idempotence guard + +Before writing a response, the responder re-reads `ipc.json` and validates: +- The file still exists +- The `type` matches the expected request type +- The `id` matches the original request ID +- `response` is still `null` + +This prevents writing a response to a stale or replaced request. + +### Circular import avoidance + +The IPC responder needs to spawn scouts, but importing from `subagent.ts` +would create a circular dependency. Instead, `subagent.ts` injects a +`ScoutSpawnContext` interface at startup: + +```typescript +interface ScoutSpawnContext { + epicDir: string; + spawnScout(task: ScoutTask, scoutDir: string, outputFile: string): Promise; +} +``` + +--- + +## Ask Flow + +``` +intake-llm calls koan_ask_question({ questions: [...] }) + → tool writes AskIpcFile { type: "ask", response: null } + → tool enters 500ms poll loop (LLM turn blocked) + +ipc-responder detects { type: "ask", response: null } + → appends "Other" option to each question + → calls webServer.requestAnswer(questions, signal) + → creates Promise in pendingInputs map + → SSE "ask" event → browser renders QuestionForm + → user fills form, clicks Submit + → POST /api/answer → resolves Promise + → maps answers to AskAnswerPayload + → writes AskResponse to ipc.json (atomic) + +tool poll detects response !== null + → breaks loop + → deleteIpcFile(dir) + → formats answers as structured text + → returns to LLM +``` + +The "Other" option is appended server-side — the LLM never includes it. On +the result side, `removeRecommendedTag()` strips the ` (Recommended)` display +suffix before building selection results. + +--- + +## Scout Flow + +``` +intake-llm calls koan_request_scouts({ scouts: [...] }) + → tool writes ScoutIpcFile { type: "scout-request", response: null } + → tool enters 500ms poll loop (LLM turn blocked) + +ipc-responder detects { type: "scout-request", response: null } + → computes scoutDir + outputFile for each task + → webServer.registerAgent(...) for each scout (UI tracking) + → pool(taskIds, concurrency=4, worker): + for each scout (up to 4 concurrent): + → mkdir(scoutDir, { recursive: true }) + → spawnScout(task, scoutDir, outputFile) + → full subagent lifecycle: boot → step 1 → work → complete → exit + → readProjection(scoutDir) → check status === "completed" + → if succeeded: findings.push(outputFile) + → if failed: failures.push(taskId) + → webServer.completeAgent(taskId) + → writes ScoutResponse { findings: [paths], failures: [ids] } to ipc.json + +tool poll detects response !== null + → breaks loop + → deleteIpcFile(dir) + → reads each findings.md file verbatim (inline, not just paths) + → returns concatenated content to LLM +``` + +### Scout pool behavior + +The pool uses a semaphore with limit 4. All scouts are submitted to +`Promise.all` simultaneously; the semaphore gates actual execution. The pool: + +- **Runs all items to completion** regardless of individual failures +- **Reports progress** via optional callback (done/total/active/queued) +- **Does not implement timeouts** — timeout logic belongs in the worker closure + +### Scout success determination + +Scout success is derived from the JSON audit projection, not file existence: + +```typescript +const projection = await readProjection(scoutDir); +succeeded = projection?.status === "completed"; +``` + +A scout can write a partial `findings.md` and then crash. File existence is +not proof of completion. + +### Failed scouts are non-fatal + +The tool result tells the LLM: +`"Failed scouts (non-fatal, proceed without them): task-id-1, task-id-2"` + +The LLM must proceed with whatever findings are available. + +--- + +## Audit Integration + +The audit system (`lib/audit.ts`) runs inside each subagent process and +provides the observability bridge between subagent work and parent/UI polling. + +### Event-sourced design + +- `events.jsonl` — append-only truth (one JSON object per line) +- `state.json` — eagerly materialized projection, written atomically after + every event + +The parent polls `state.json` (cheap file read) instead of parsing the event +log. `fold()` is a pure function so the projection can be rebuilt from the raw +log for testing and crash recovery. + +### Event types + +| Event | Trigger | Key data | +|-------|---------|----------| +| `phase_start` | `BasePhase.begin()` | totalSteps | +| `step_transition` | `handleStepComplete()` | step number, name, total | +| `tool_call` | pi `tool_call` hook | toolCallId, name, input | +| `tool_result` | pi `tool_result` hook | toolCallId, summarized metrics (not full content) | +| `usage` | pi `turn_end` hook | input/output/cacheRead/cacheWrite tokens | +| `heartbeat` | 10s timer | (keeps `updatedAt` fresh during long tool calls) | +| `phase_end` | phase completion | "completed" | + +### Projection fields consumed by parent + +| Field | Consumer | Purpose | +|-------|----------|---------| +| `status` | IPC responder, web server | Scout success, agent completion | +| `step` | Web server | Intake sub-phase derivation | +| `currentToolCallId` | Web server | "doing X" vs "done with X" in UI | +| `completionSummary` | Web server | Scout card summary (500-char prefix of `thoughts`) | +| `tokensSent/Received` | Web server | Token usage display | +| `model` | Web server | Model display | + +### Serialization + +`EventLog.append()` calls are serialized via a promise chain. The heartbeat +timer and `tool_result` handler both call `append()` concurrently — without +serialization, two `writeState()` calls race on the shared `.tmp.json` file, +causing ENOENT on rename. diff --git a/docs/state.md b/docs/state.md new file mode 100644 index 0000000..e959595 --- /dev/null +++ b/docs/state.md @@ -0,0 +1,298 @@ +# State & Driver + +How the driver manages epic and story state, routes between phases, and +enforces the file boundary invariant. + +> Parent doc: [architecture.md](./architecture.md) + +--- + +## The File Boundary in Practice + +The driver writes JSON; LLMs write markdown. Tool code bridges both. + +| Actor | Reads | Writes | +|-------|-------|--------| +| **Driver** | `.json` state files, exit codes | `.json` state files | +| **LLM** | `.md` files, codebase files | `.md` files (output) | +| **Tool code** | `.json` state (to validate) | `.json` state + `.md` status (both) | + +### Why state.ts must not write markdown + +The state module (`epic/state.ts`) reads and writes JSON only. Putting +`writeStatusMarkdown()` there would make one module responsible for both +communication channels. `status.md` writes belong exclusively in +`tools/orchestrator.ts`, which bridges the two worlds by writing JSON state +(for the driver) and templated markdown (for LLMs) in the same operation. + +### Filesystem-driven story discovery + +Story IDs are discovered by scanning `stories/*/story.md`, not by reading a +driver-maintained JSON list. The decomposer LLM creates `story.md` files using +the `write` tool — it has no reason to know the JSON state format. Requiring +it to update `epic-state.json` would force an LLM to write JSON, violating the +core invariant. + +The driver discovers what the LLM created by scanning, then populates the JSON +story list itself. + +--- + +## Epic State + +`epic-state.json` in the epic directory root. Tracks the current pipeline +phase and the list of story IDs. + +```typescript +interface EpicState { + phase: EpicPhase; // intake → decomposition → review → executing → completed + stories: string[]; // populated by driver after filesystem scan +} +``` + +### Epic phases + +| Phase | What happens | +|-------|-------------| +| `intake` | Intake subagent reads conversation, scouts codebase, asks user questions | +| `decomposition` | Decomposer subagent splits work into stories | +| `review` | User reviews story sketches in web UI (approve/remove) | +| `executing` | Story loop: orchestrator → planner → executor → orchestrator → next | +| `completed` | All stories done or skipped | + +**`scouting` is intentionally absent.** Scouts run inside the IPC responder +during intake/decomposer/planner phases, not as a top-level phase. Adding it +would imply a driver state that never exists. + +--- + +## Story State + +One `state.json` per story in `stories/{storyId}/`. + +```typescript +interface StoryState { + storyId: string; + status: StoryStatus; + retryCount: number; + maxRetries: number; // default: 2 + failureSummary?: string; // set by koan_retry_story + skipReason?: string; // set by koan_skip_story or driver on budget exhaustion + updatedAt: string; +} +``` + +### Story status lifecycle + +``` +pending ──→ selected ──→ planning ──→ executing ──→ verifying ──→ done + │ ↑ │ + │ └──────────── retry ←───────────────────┤ + │ │ + └──→ skipped ←───────────────────────────────────────┘ +``` + +| Status | Set by | Meaning | +|--------|--------|---------| +| `pending` | Driver (initial) | Story exists, not yet started | +| `selected` | Orchestrator (`koan_select_story`) | Chosen for execution | +| `planning` | Driver | Planner subagent is running | +| `executing` | Driver | Executor subagent is running | +| `verifying` | Driver | Post-execution orchestrator is evaluating | +| `done` | Orchestrator (`koan_complete_story`) | Successfully completed | +| `retry` | Orchestrator (`koan_retry_story`) | Failed, queued for re-execution | +| `skipped` | Orchestrator (`koan_skip_story`) or Driver | Permanently skipped | + +**Driver-internal states** (`planning`, `executing`, `verifying`) are set by +the driver only. The LLM never writes these — it reads them indirectly via +`status.md`. + +**Orchestrator-driven transitions** (`selected`, `done`, `retry`, `skipped`) +are set by orchestrator tool calls. Each tool validates the source status +before transitioning: + +| Tool | Valid source | Target | +|------|-------------|--------| +| `koan_select_story` | `pending`, `retry` | `selected` | +| `koan_complete_story` | `verifying` | `done` | +| `koan_retry_story` | `verifying` | `retry` | +| `koan_skip_story` | `pending`, `retry` | `skipped` | + +### No `escalated` status + +Escalation is handled via `koan_ask_question` — the orchestrator asks the user +a question through IPC, gets an answer, then decides `retry` or `skip`. A +separate `escalated` status was tried and created a dead routing path. + +### Retry budget + +Each story starts with `maxRetries: 2`. When the driver sees `status: "retry"`, +it increments `retryCount` and re-executes. When `retryCount >= maxRetries`, +the driver sets the story to `skipped`: + +``` +skipReason: "Retry budget exhausted after N attempt(s). Last failure: {failureSummary}" +``` + +The `failureSummary` field flows from `koan_retry_story` (the orchestrator +writes a concrete description of what went wrong) to `retryContext` in the +executor's `task.json` on re-execution. + +--- + +## Driver Routing + +The driver's story loop is a deterministic state machine: + +```typescript +while (true) { + const stories = await loadAllStoryStates(epicDir); + const routing = routeFromState(stories); + + switch (routing.action) { + case "retry": → re-execute story (increment retryCount) + case "execute": → plan + execute story + case "complete": → all stories terminal → exit loop + case "error": → no actionable state → fail + } +} +``` + +**Priority:** `retry` is checked before `selected`. A story queued for retry +takes precedence over a newly selected story. + +**Terminal states:** exactly `done` and `skipped`. The epic is complete when +every story is in a terminal state. + +**Error state:** If no story is `retry` or `selected` and not all are terminal, +the driver reports: "orchestrator may have exited without a routing decision." + +### Story execution pipeline + +For each story selected for execution: + +``` +Driver sets status → planning + → spawn planner subagent + → if planner fails: skip executor, go to post-execution orchestrator +Driver sets status → executing + → spawn executor subagent +Driver sets status → verifying + → spawn orchestrator (post-execution) + → orchestrator decides: koan_complete_story / koan_retry_story / koan_skip_story +``` + +### Planner failure fallthrough + +When the planner exits with non-zero exit code, the driver skips the executor +and proceeds directly to the post-execution orchestrator. This gives the +orchestrator a chance to make a routing decision (retry, skip) rather than +leaving the story in a dead state. + +### Model config gate + +When a web server is available, the pipeline blocks at startup until the user +confirms model tier selection. This happens before any subagent spawns. + +### Spec review gate + +After decomposition, story sketches are presented for human review in the web +UI. The user can approve or remove stories. Removed stories get +`status: "skipped"`, `skipReason: "Removed during spec review"`. When no web +server is running, the gate auto-approves. + +--- + +## Atomic Writes + +All state writes use atomic tmp-file + rename: + +```typescript +async function atomicWriteJson(filePath: string, data: unknown): Promise { + const tmp = `${filePath}.tmp`; + await fs.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", "utf8"); + await fs.rename(tmp, filePath); +} +``` + +This applies to: +- `epic-state.json` (driver) +- `stories/{id}/state.json` (driver + orchestrator tools) +- `stories/{id}/status.md` (orchestrator tools) +- `subagents/{label}/task.json` (driver, before spawn) +- `subagents/{label}/state.json` (audit projection) +- `subagents/{label}/ipc.json` (both sides) + +--- + +## Epic Directory Structure + +``` +{epicDir}/ + epic-state.json # Epic phase + story list + conversation.jsonl # Exported conversation (input to intake) + context.md # Written by intake (conversation, codebase findings, decisions) + stories/ + {storyId}/ + story.md # Written by decomposer + state.json # Story lifecycle state + status.md # Templated status for LLM consumption + plan/ + plan.md # Written by planner + subagents/ + intake/ + task.json # Task manifest + state.json # Audit projection + events.jsonl # Audit log + stdout.log, stderr.log + decomposer/ + ... + scout-{id}-{timestamp}/ + task.json + findings.md # Scout output + ... + planner-{storyId}/ + ... + executor-{storyId}/ + ... + orchestrator-pre/ + ... + orchestrator-post-{storyId}/ + ... +``` + +--- + +## Audit Projection (`state.json`) + +Each subagent writes a `state.json` (the "projection") to its directory. The +projection is an eagerly-materialized summary of the subagent's current state, +updated atomically after every audit event. The web server polls it to push +SSE events to the UI without having to replay the full `events.jsonl`. + +Key projection fields common to all roles: + +| Field | Type | Meaning | +|-------|------|---------| +| `phase` | string | Overall phase name (e.g., "intake", "decomposition") | +| `step` | number | Current step index within the phase | +| `stepName` | string | Human-readable step label (e.g., "Scout (round 2)") | +| `tokensSent` | number | Cumulative tokens in | +| `tokensReceived` | number | Cumulative tokens out | + +Intake-specific fields (zero/null for all other roles): + +| Field | Type | Meaning | +|-------|------|---------| +| `intakeConfidence` | `"exploring"\|"low"\|"medium"\|"high"\|"certain"\|null` | Last confidence level declared by `koan_set_confidence`. Null until first declaration; retains last value between loop iterations (not reset in projection on loop-back). | +| `intakeIteration` | number | Current loop iteration (1-based). Updated by `confidence_change` and `iteration_start` events. Zero for non-intake subagents. | + +**Note on `intakeConfidence` and loop-back:** When `getNextStep()` decides to +loop from Reflect (step 4) back to Scout (step 2), it resets +`ctx.intakeConfidence = null` internally. This internal reset is NOT +propagated to the projection immediately — the projection retains the +previous iteration's confidence level until the next `koan_set_confidence` +call emits a `confidence_change` event. The UI therefore shows the last +declared confidence between iterations, which is intentional: it reflects +the most recent authoritative assessment rather than showing a transient +null state. diff --git a/docs/subagents.md b/docs/subagents.md new file mode 100644 index 0000000..5278690 --- /dev/null +++ b/docs/subagents.md @@ -0,0 +1,397 @@ +# Subagents + +How koan spawns, manages, and terminates LLM subagent processes. + +> Parent doc: [architecture.md](./architecture.md) + +--- + +## Task Manifest + +Every subagent starts as a generic `pi -p` process with one koan-specific +input: a directory path. The koan extension reads `task.json` from that +directory to learn what kind of subagent it is, what epic it belongs to, and +what work to perform. + +### `task.json` schema + +The manifest is a discriminated union on the `role` field. Common fields +(`role`, `epicDir`) appear on every variant; role-specific fields are nested +naturally rather than flattened into a shared namespace. + +```typescript +// Common to all subagents +interface SubagentTaskBase { + role: SubagentRole; + epicDir: string; +} + +// Role-specific variants +interface IntakeTask extends SubagentTaskBase { + role: "intake"; +} + +interface ScoutTask extends SubagentTaskBase { + role: "scout"; + question: string; // What to investigate + outputFile: string; // Where to write findings (relative to subagentDir) + investigatorRole: string; // Persona for the scout ("security auditor", etc.) +} + +interface DecomposerTask extends SubagentTaskBase { + role: "decomposer"; +} + +interface OrchestratorTask extends SubagentTaskBase { + role: "orchestrator"; + stepSequence: "pre-execution" | "post-execution"; + storyId?: string; +} + +interface PlannerTask extends SubagentTaskBase { + role: "planner"; + storyId: string; +} + +interface ExecutorTask extends SubagentTaskBase { + role: "executor"; + storyId: string; + retryContext?: string; // Failure summary from previous attempt +} + +type SubagentTask = + | IntakeTask | ScoutTask | DecomposerTask + | OrchestratorTask | PlannerTask | ExecutorTask; +``` + +### Lifecycle + +`task.json` is **write-once, read-once**: + +1. Parent calls `ensureSubagentDirectory()` → creates the directory +2. Parent writes `task.json` (atomic: tmp + rename) +3. Parent spawns `pi -p --koan-dir {subagentDir} ...` +4. Child extension reads `task.json` at startup → dispatches to phase +5. `task.json` is never modified after spawn + +This makes every subagent directory **self-describing** and **inspectable** +after the fact. `cat task.json` shows exactly what the subagent was asked +to do. + +### Why not CLI flags + +The previous design passed task configuration as 9 CLI flags +(`--koan-role`, `--koan-epic-dir`, `--koan-subagent-dir`, +`--koan-story-id`, `--koan-step-sequence`, `--koan-retry-context`, +`--koan-scout-question`, `--koan-scout-output-file`, `--koan-scout-role`). + +Problems this caused: + +| Problem | Example | +|---------|---------| +| **Flat namespace collision** | `--koan-role` (pipeline role: "scout") vs `--koan-scout-role` (investigator persona: "security auditor") — two unrelated concepts sharing a prefix | +| **Unstructured** | Role-specific fields mixed with common fields; `extraFlags: string[]` escape hatch needed for extensibility | +| **Size limits** | `--koan-retry-context` carries multi-paragraph failure summaries — visible in `ps aux`, subject to `ARG_MAX` | +| **Uninspectable** | After a crash, reconstructing what a subagent was asked to do requires parsing process arguments from logs | +| **Inconsistent** | Runtime communication uses files (ipc.json); observation uses files (state.json); but task input used CLI args | + +--- + +## Spawn Flow + +### Parent side + +``` +driver: ensureSubagentDirectory(epicDir, label) → subagentDir +driver: write task.json to subagentDir (atomic) +driver: webServer.registerAgent(...) +driver: webServer.trackSubagent(subagentDir, role) +driver: spawnSubagent(task, subagentDir, opts) + → resolves model for role (3-tier: strong/standard/cheap) + → builds CLI args: pi -p -e ext --koan-dir dir [--model model] "boot prompt" + → spawn("pi", args, { cwd, stdio: ["ignore", "pipe", "pipe"] }) + → captures stdout/stderr to subagentDir/stdout.log, stderr.log + → starts IPC responder concurrently (if webServer available) + → waits for proc.on("close") + → aborts IPC responder + → returns { exitCode, stderr, subagentDir } +driver: webServer.clearSubagent() +driver: webServer.completeAgent(id) +driver: checks exitCode, routes to next phase +``` + +### Child side + +``` +pi -p starts with koan extension +koan.ts init: + → registers --koan-dir flag + → creates RuntimeContext { epicDir: null, subagentDir: null, onCompleteStep: null } + → registerAllTools(pi, ctx) — all tools, unconditionally + +before_agent_start fires (after _buildRuntime snapshot): + → reads --koan-dir flag + → reads task.json from dir → SubagentTask (typed, validated) + → sets ctx.epicDir = task.epicDir, ctx.subagentDir = dir + → opens EventLog (audit trail) + → wires pi event hooks (tool_call, tool_result, turn_end, session_shutdown) + → dispatchPhase(pi, task, ctx): + → matches task.role → instantiates phase class → phase.begin() + +phase.begin(): + → step = 0, active = true + → ctx.onCompleteStep = handleStepComplete + +LLM receives boot prompt: + "You are a koan {role} agent. Call koan_complete_step to receive your instructions." +``` + +### Boot prompt + +``` +"You are a koan {role} agent. Call koan_complete_step to receive your instructions." +``` + +One sentence. No task content. The role name is included for primacy — it +anchors the LLM's identity before it receives any instructions. Task-specific +parameters live in `task.json` and flow into step guidance via the phase class. + +### Fail-fast guards + +`dispatchPhase` validates required `task.json` fields before instantiating: + +| Role | Required fields | Failure if missing | +|------|----------------|-------------------| +| scout | `question`, `outputFile` | Step 1 guidance has no assignment → LLM outputs confused text → exits | +| planner | `storyId` | Malformed paths like `stories//plan/plan.md` | +| executor | `storyId` | Same path issue | + +--- + +## Step-First Workflow (BasePhase) + +`BasePhase` is the abstract superclass for all six phase classes. It manages: + +- **Step counter** — starts at 0 (boot state), increments monotonically +- **System prompt injection** — via `before_agent_start` event handler +- **Permission fence** — via `tool_call` event handler (default-deny) +- **Step transition** — via `handleStepComplete()` callback + +### Step progression state machine + +``` +begin() → step=0, active=true, arms ctx.onCompleteStep + +LLM calls koan_complete_step: + step == 0 → step=1, return formatStep(getStepGuidance(1)) [boot transition] + otherwise → validateStepCompletion(step) [pre-condition check] + → nextStep = getNextStep(step) [pure: decides where to go] + nextStep == null → active=false, return null → "Phase complete." [done] + nextStep < prev → onLoopBack(prev, nextStep) [side effects of loop] + nextStep != null → onStepUpdated(nextStep) [sync ctx fields] + → step=nextStep, return formatStep(getStepGuidance(nextStep)) [advance] +``` + +`BasePhase` provides three overridable hooks for non-linear flows: + +| Hook | Purpose | Default | +|------|---------|---------| +| `getNextStep(step)` | Returns next step number or null (done). **Must be pure.** | Linear: step+1, null at totalSteps | +| `onLoopBack(from, to)` | Side effects of backward transitions: state resets, counter increments, event emission. Async — properly awaited. | no-op | +| `validateStepCompletion(step)` | Pre-condition check before advancing. Returns null to allow or an error string to block (returned as tool result so LLM can fix it). | null (always allow) | + +`IntakePhase` overrides all three to implement a confidence-gated loop over +steps 2–4. See [intake-loop.md](./intake-loop.md) for details. + +Key invariants: +- **`getNextStep()` is pure** — it only returns a step number. Mutation belongs in `onLoopBack()`. +- **`step_transition` is NOT emitted at `begin()`** — it fires when step 1 + guidance is first returned, so the event log reflects when the LLM actually + begins work. +- **`ctx.onCompleteStep` is nulled on completion** — prevents stale callbacks. +- **Only one phase per RuntimeContext** — `begin()` throws if `ctx.onCompleteStep` + is already occupied. + +### System prompt vs task content + +The system prompt (injected via `before_agent_start`) establishes **role +identity and rules** — who you are, what you must/must not do, what output +files you produce, what tools you have. It deliberately omits task details. + +Task details arrive as **step guidance** — the return value of +`koan_complete_step` — after the LLM has already established the tool-calling +pattern. This separation is load-bearing (see +[architecture pitfalls](./architecture.md#pitfalls)). + +### formatStep structure + +Every step guidance string has the same structure: + +``` +{title} +{"=".repeat(title.length)} + +{instructions} + +WHEN DONE: Call koan_complete_step with your findings in the `thoughts` parameter. +Do NOT call this tool until the work described in this step is finished. +``` + +The invoke-after directive is always **last** (recency reinforcement). Steps +that need the LLM to call a domain tool before `koan_complete_step` (e.g., +`koan_select_story`) can override `invokeAfter`. + +### The `thoughts` parameter + +`thoughts` is **internal chain-of-thought reasoning only**. It is NOT task +output and MUST NOT be treated as such: + +- Task output goes to files (`findings.md`, `context.md`, etc.) +- The driver/parent reads those files after the subagent exits +- `thoughts` exists so models that cannot mix text + tool_call in one response + (e.g., GPT-5-codex) can still express reasoning while advancing the workflow +- A 500-char prefix of `thoughts` is captured in the audit projection as + `completionSummary` for scout UI display — this is the only consumer + +--- + +## Permissions + +Default-deny, role-based, enforced at runtime via the `tool_call` event handler +in `BasePhase`. + +### READ_TOOLS (always allowed) + +`bash`, `read`, `grep`, `glob`, `find`, `ls` — allowed for all roles. This is +an accepted limitation: `bash` can write files, but distinguishing read-bash +from write-bash is intractable at the permission layer. Prompt engineering +constrains intended use; enforcement does not. + +### Role permission matrix + +| Role | koan tools | write/edit | notes | +|------|-----------|------------|-------| +| **intake** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `koan_set_confidence` | path-scoped to epicDir | `koan_set_confidence` blocked in step 1 (Extract) | +| **scout** | `koan_complete_step` | path-scoped to epicDir | No `koan_ask_question` (no user interaction). No `koan_request_scouts` (no nested scouts). | +| **decomposer** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | — | +| **orchestrator** | `koan_complete_step`, `koan_ask_question`, `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | path-scoped to epicDir | No `koan_request_scouts` — orchestrator uses bash for verification | +| **planner** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | — | +| **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | + +### Path scoping + +Planning roles (intake, scout, decomposer, orchestrator, planner) can only +`write`/`edit` files inside the epic directory. The permission check resolves +both the tool's `path` argument and the epic directory, then verifies the tool +path starts with the epic path. If `epicDir` or the path argument is missing, +the write is allowed (cannot scope-check without context). + +--- + +## Model Tiers + +Roles map deterministically to 3 tiers: + +| Tier | Roles | Purpose | +|------|-------|---------| +| **strong** | intake, decomposer, orchestrator, planner | Complex reasoning, planning, decomposition | +| **standard** | executor | Code implementation | +| **cheap** | scout | Narrow codebase investigation | + +The user configures which specific model each tier uses via the web UI at +pipeline start (model config gate). If no config exists, `resolveModelForRole` +returns `undefined` and the `--model` flag is omitted, preserving pi's +current active model as the implicit fallback. + +Model tier config is all-or-nothing: all 3 tiers must be present. Partial +configs are treated as absent and logged. + +--- + +## Scout Isolation + +Scouts are deliberately constrained compared to other roles: + +- **No web server handle** — scouts cannot interact with the user or the UI +- **No `koan_ask_question`** — scouts do not ask questions +- **No `koan_request_scouts`** — scouts do not spawn nested scouts +- **No IPC responder** — since there is no web server, no IPC responder runs +- **Single step** — scouts have `totalSteps = 1`; they do one job and exit +- **Cheap model** — scouts use the cheapest available model +- **Parallel execution** — up to 4 scouts run concurrently via bounded pool +- **Non-fatal failures** — a failed scout does not abort the parent; its task + ID is reported in the `failures` array and the LLM is told to proceed + +Scout task parameters (`question`, `outputFile`, `investigatorRole`) live in +the scout's `task.json`. The boot prompt stays minimal; `ScoutPhase` reads the +task manifest and injects the parameters into step 1 guidance. + +--- + +## Subagent Directory Layout + +After a subagent runs, its directory contains: + +``` +{subagentDir}/ + task.json # Input: what to do (written by parent before spawn) + state.json # Output: audit projection (written by child, polled by parent) + events.jsonl # Output: append-only audit log + ipc.json # Transient: runtime communication (created/deleted per request) + stdout.log # Captured stdout from pi -p process + stderr.log # Captured stderr from pi -p process + findings.md # Task output (scouts) + context.md # Task output (intake — conversation, codebase findings, decisions) +``` + +The three JSON files have distinct lifecycles per +[architecture.md § Directory-as-contract](./architecture.md#6-directory-as-contract): + +| File | Writer | Reader | When | +|------|--------|--------|------| +| `task.json` | Parent | Child | Once at startup | +| `state.json` | Child | Parent | Continuous (500ms polling) | +| `ipc.json` | Both | Both | Per-request (created, answered, deleted) | + +--- + +## Web Server Integration + +The parent registers each subagent with the web server for UI tracking: + +```typescript +webServer.registerAgent({ id, name, dir, role, model, parent }); +// → starts 500ms polling of audit projection + recent logs +// → SSE "agents" event to browser + +webServer.trackSubagent(dir, role, storyId?); +// → starts 500ms polling for "subagent" + "logs" SSE events + +// ... subagent runs ... + +webServer.clearSubagent(); +// → stops tracking timer, emits SSE "subagent-idle" + +webServer.completeAgent(id); +// → stops polling, final readProjection, emits SSE "agents" with terminal status +``` + +**Dual polling for intake agent:** Both `registerAgent()` and +`trackSubagent()` poll at 500ms. `registerAgent` polling derives the intake +sub-phase for the progress bar: + +| Step | Pending ask? | Sub-phase | +|------|-------------|-----------| +| 1 | — | `"extract"` | +| 2 | — | `"scout"` | +| 3 | yes | `"questions"` | +| 3 | no | `"deliberate"` | +| 4 | — | `"reflect"` | +| 5 | — | `"synthesize"` | + +Steps 2–4 repeat across iterations; the server additionally reads +`intakeConfidence` and `intakeIteration` from the audit projection to populate +the `intake-progress` SSE event for UI visualization. + +This derivation is server-side — the server maps step numbers to sub-phase +names. The LLM does not report its sub-phase. From e85281ca2eb72908cdfd66781dedf49007ffc074 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 19 Mar 2026 23:24:20 +0700 Subject: [PATCH 068/412] scout dispatch card, monitor centering alignment --- src/planner/lib/audit.ts | 10 ++-- src/planner/web/css/layout.css | 41 +++++++++++++++- .../web/js/components/ActivityFeed.jsx | 41 ++++++++++++++++ .../web/js/components/AgentMonitor.jsx | 48 ++++++++++--------- 4 files changed, 112 insertions(+), 28 deletions(-) diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index 91ebabe..424115e 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -581,6 +581,8 @@ export interface LogLine { ts?: string; // Expandable content body: thinking text, tool output, etc. body?: string; + // Structured scout data for koan_request_scouts cards. + scouts?: Array<{ id: string; role: string }>; } interface ToolShape { @@ -600,7 +602,7 @@ const KOAN_SHAPES: Record = { koan_retry_story: { keys: ["story_id", "failure_summary"], freeform: ["failure_summary"], highValue: true }, koan_skip_story: { keys: ["story_id", "reason"], freeform: ["reason"], highValue: true }, koan_ask_question: { keys: ["questions"], arrays: ["questions"], highValue: true }, - koan_request_scouts: { keys: ["scouts"], arrays: ["scouts"], highValue: true }, + koan_request_scouts: { keys: [], highValue: true }, }; // Reads events.jsonl, correlates tool pairs, and returns structured log entries. @@ -910,10 +912,10 @@ function formatKoanInvocation(inv: ToolInvocation): LogLine { inFlight: inv.inFlight, }; - // Expand koan_request_scouts with per-scout detail lines. + // Structured scout data for the UI card. if (inv.tool === "koan_request_scouts" && Array.isArray(inv.input["scouts"])) { - line.details = (inv.input["scouts"] as Array>).map( - (s) => `${s["id"] ?? "?"} (${s["role"] ?? "agent"})`, + line.scouts = (inv.input["scouts"] as Array>).map( + (s) => ({ id: String(s["id"] ?? "?"), role: String(s["role"] ?? "agent") }), ); } diff --git a/src/planner/web/css/layout.css b/src/planner/web/css/layout.css index 43e5214..c3e79f7 100644 --- a/src/planner/web/css/layout.css +++ b/src/planner/web/css/layout.css @@ -200,6 +200,40 @@ user-select: none; } +/* ---- Scout dispatch card ---- */ + +.activity-card-scouts .activity-card-tool { + color: var(--blue); +} + +.scout-list { + display: flex; + flex-wrap: wrap; + gap: var(--gap-xs); + padding: 0 var(--gap-md) var(--gap-sm); +} + +.scout-entry { + display: flex; + align-items: baseline; + gap: var(--gap-sm); + padding: 3px var(--gap-sm); + font-family: var(--font-mono); + font-size: var(--font-size-xs); + background: var(--bg); + border-radius: var(--radius-sm); + border: 1px solid var(--border); +} + +.scout-name { + color: var(--text-muted); + font-weight: 500; +} + +.scout-role { + color: var(--text-ghost); +} + .activity-card-more:hover { color: var(--text-strong); } @@ -239,7 +273,7 @@ padding-left: 12px; } -/* Monitor — sticky bottom, sizes to content */ +/* Monitor — sticky bottom, sizes to content, centered like activity feed */ .monitor { flex: 0 0 auto; max-height: 40vh; @@ -252,6 +286,11 @@ -webkit-mask-image: linear-gradient(to bottom, transparent, black 12px, black); } +.monitor-inner { + max-width: 960px; + margin: 0 auto; +} + .agent-table-header { display: flex; align-items: center; diff --git a/src/planner/web/js/components/ActivityFeed.jsx b/src/planner/web/js/components/ActivityFeed.jsx index f3c5c50..0bc2477 100644 --- a/src/planner/web/js/components/ActivityFeed.jsx +++ b/src/planner/web/js/components/ActivityFeed.jsx @@ -73,6 +73,36 @@ function ThinkingCard({ line, isInFlight, isFlashing }) { ) } +/** Card for koan_request_scouts — shows dispatched scouts with name + role */ +function ScoutCard({ line, isInFlight, isFlashing }) { + const scouts = line.scouts || [] + const cls = [ + 'activity-card', + 'activity-card-scouts', + isInFlight ? 'activity-card-active' : '', + isFlashing ? 'activity-flash' : '', + ].filter(Boolean).join(' ') + + return ( +
+
+ + dispatching {scouts.length} scout{scouts.length !== 1 ? 's' : ''} + + {isInFlight && …} +
+
+ {scouts.map((s, i) => ( +
+ {s.id} + {s.role} +
+ ))} +
+
+ ) +} + /** Standard line for tool calls and lifecycle events */ function ActivityLine({ line, isInFlight, isFlashing }) { const cls = [ @@ -155,6 +185,17 @@ export function ActivityFeed() { ) } + if (line.scouts) { + return ( + + ) + } + return ( -
- Subagents -
- {running} - {done > 0 && {done}} +
+
+ Subagents +
+ {running} + {done > 0 && {done}} +
+ + {(sent > 0 || recv > 0) ? `↑${formatTokens(sent)} ↓${formatTokens(recv)}` : ''} +
- - {(sent > 0 || recv > 0) ? `↑${formatTokens(sent)} ↓${formatTokens(recv)}` : ''} - + + + + + + + + + + + + + {agents.map(a => )} + +
agentmodel↑ sent↓ recvdoing
- - - - - - - - - - - - - {agents.map(a => )} - -
agentmodel↑ sent↓ recvdoing
) } From 71eb4422473fe34a8a9524c931f182e470fd4053 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Thu, 19 Mar 2026 23:48:30 +0700 Subject: [PATCH 069/412] expandable story cards in review gate --- src/planner/driver.ts | 12 ++- src/planner/web/css/components.css | 95 +++++++++++++++---- .../web/js/components/forms/ReviewForm.jsx | 71 ++++++++++++-- src/planner/web/server-types.ts | 1 + 4 files changed, 151 insertions(+), 28 deletions(-) diff --git a/src/planner/driver.ts b/src/planner/driver.ts index 0216637..f5c9035 100644 --- a/src/planner/driver.ts +++ b/src/planner/driver.ts @@ -417,10 +417,18 @@ export async function runPipeline( if (webServer && storyIds.length > 0) { webServer.pushNotification("Decomposition complete. Review story sketches...", "info"); - const titles = await Promise.all(storyIds.map((id) => readStoryTitle(epicDir, id))); + const storyData = await Promise.all(storyIds.map(async (id) => { + const storyPath = path.join(epicDir, "stories", id, "story.md"); + try { + const raw = await fs.readFile(storyPath, "utf8"); + const title = readStoryTitle(epicDir, id); + return { raw, title: await title }; + } catch { return { raw: "", title: id }; } + })); const reviewStories: ReviewStory[] = storyIds.map((storyId, i) => ({ storyId, - title: titles[i] ?? storyId, + title: storyData[i].title ?? storyId, + content: storyData[i].raw, })); const reviewResult = await webServer.requestReview(reviewStories); diff --git a/src/planner/web/css/components.css b/src/planner/web/css/components.css index ce2c191..a112b3f 100644 --- a/src/planner/web/css/components.css +++ b/src/planner/web/css/components.css @@ -390,39 +390,49 @@ } /* ---- Review checklist ---- */ -.review-story { +/* ---- Review story cards ---- */ + +.review-card { + border: 1px solid var(--border); + border-radius: var(--radius-md); + background: var(--bg-surface); + margin-bottom: var(--gap-sm); + overflow: hidden; + transition: border-color 150ms; +} + +.review-card-approved { + border-color: var(--green-border); +} + +.review-card-header { display: flex; align-items: center; gap: var(--gap-md); padding: var(--gap-sm) var(--gap-md); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - background: var(--bg); - margin-bottom: var(--gap-sm); cursor: pointer; user-select: none; } -.review-story.checked { - border-color: var(--green-border); - background: var(--green-bg); +.review-card-checkbox { + flex-shrink: 0; + padding: 2px; } -.review-story-checkbox { +.review-checkbox { width: 16px; height: 16px; border: 2px solid var(--text-ghost); border-radius: 3px; - flex-shrink: 0; transition: border-color 100ms, background 100ms; } -.review-story.checked .review-story-checkbox { +.review-checkbox.checked { border-color: var(--green-border); background: var(--green-border); } -.review-story.checked .review-story-checkbox::after { +.review-checkbox.checked::after { content: "✓"; display: block; color: #fff; @@ -431,17 +441,70 @@ line-height: 12px; } -.review-story-id { +.review-card-title { + flex: 1; + min-width: 0; + display: flex; + align-items: baseline; + gap: var(--gap-sm); +} + +.review-card-id { font-family: var(--font-mono); font-size: var(--font-size-md); color: var(--text); font-weight: 600; + flex-shrink: 0; } -.review-story-title { - font-family: var(--font-sans); - font-size: var(--font-size-md); +.review-card-desc { + font-family: var(--font-mono); + font-size: var(--font-size-sm); color: var(--text-muted); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.review-card-chevron { + font-family: var(--font-mono); + font-size: var(--font-size-sm); + color: var(--text-ghost); + flex-shrink: 0; + width: 16px; + text-align: center; +} + +.review-card-body { + padding: 0 var(--gap-md) var(--gap-sm); + padding-left: calc(var(--gap-md) + 16px + var(--gap-md)); + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--text-dim); + white-space: pre-wrap; + word-break: break-word; + line-height: 1.5; +} + +.review-card-body:not(.expanded) { + display: -webkit-box; + -webkit-line-clamp: 3; + -webkit-box-orient: vertical; + overflow: hidden; +} + +.review-card-more { + padding: 2px var(--gap-md) var(--gap-sm); + padding-left: calc(var(--gap-md) + 16px + var(--gap-md)); + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--blue); + cursor: pointer; + user-select: none; +} + +.review-card-more:hover { + color: var(--text-strong); } /* ---- Loading spinner ---- */ diff --git a/src/planner/web/js/components/forms/ReviewForm.jsx b/src/planner/web/js/components/forms/ReviewForm.jsx index ee878e3..9e5839b 100644 --- a/src/planner/web/js/components/forms/ReviewForm.jsx +++ b/src/planner/web/js/components/forms/ReviewForm.jsx @@ -1,7 +1,59 @@ -import { useState } from 'preact/hooks' +import { useState, useRef, useEffect } from 'preact/hooks' import { useStore } from '../../store.js' import { submitReview } from '../../lib/api.js' +function StoryCard({ story, isApproved, onToggle }) { + const [expanded, setExpanded] = useState(false) + const bodyRef = useRef(null) + const [isClamped, setIsClamped] = useState(false) + + useEffect(() => { + const el = bodyRef.current + if (el) setIsClamped(el.scrollHeight > el.clientHeight + 2) + }, [story.content, expanded]) + + function handleCheckbox(e) { + e.stopPropagation() + onToggle() + } + + function handleExpand() { + if (story.content) setExpanded(v => !v) + } + + return ( +
+
+
+
+
+
+ {story.storyId} + {story.title} +
+ {story.content && ( + {expanded ? '▾' : '▸'} + )} +
+ {story.content && ( + <> +
+ {story.content} +
+ {!expanded && isClamped && ( +
+ show spec ▸ +
+ )} + + )} +
+ ) +} + export function ReviewForm({ token }) { const { requestId, payload: stories } = useStore(s => s.pendingInput) const [approved, setApproved] = useState(() => new Set(stories.map(s => s.storyId))) @@ -28,18 +80,17 @@ export function ReviewForm({ token }) { return (

Review story sketches

-

Review stories before execution begins.

+

+ Review stories before execution begins. Click a story to inspect its specification. +

{stories.map(story => ( -
toggle(story.storyId)} - > -
- {story.storyId} - — {story.title} -
+ story={story} + isApproved={approved.has(story.storyId)} + onToggle={() => toggle(story.storyId)} + /> ))}
diff --git a/src/planner/web/server-types.ts b/src/planner/web/server-types.ts index 2812073..23aacbb 100644 --- a/src/planner/web/server-types.ts +++ b/src/planner/web/server-types.ts @@ -96,6 +96,7 @@ export function buildMultiSelectionResult( export interface ReviewStory { storyId: string; title: string; + content: string; } export interface ReviewResult { From 2b3afeb19ec621e994e9559a309364b8dddc0c03 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 20 Mar 2026 13:35:24 +0700 Subject: [PATCH 070/412] increase web server polling interval from 500ms to 50ms --- src/planner/web/server.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/planner/web/server.ts b/src/planner/web/server.ts index 075a30a..4943f75 100644 --- a/src/planner/web/server.ts +++ b/src/planner/web/server.ts @@ -446,7 +446,7 @@ export async function startWebServer(epicDir: string): Promise pushEvent("intake-progress", currentIntakeProgress); } } - }, 500); + }, 50); timer.unref(); agent.pollingTimer = timer; } @@ -682,7 +682,7 @@ export async function startWebServer(epicDir: string): Promise pushEvent("subagent", event); } } catch { /* Non-fatal */ } - }, 500); + }, 50); timer.unref(); trackingTimer = timer; }, From 355cb64b2510ef9d51264062e579caf7410ff75d Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 20 Mar 2026 13:35:35 +0700 Subject: [PATCH 071/412] document event-sourced audit, SSE lifecycle, and general architecture principles --- docs/architecture.md | 147 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 138 insertions(+), 9 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index ad5c34d..55cf4eb 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -159,6 +159,7 @@ This is not optional — the IPC responder, web server, and audit system all poll files concurrently. A partial read of `ipc.json` or `state.json` would cause silent data corruption or spurious errors. + --- ## Tool Registration Constraint @@ -177,6 +178,100 @@ is impossible. Instead: This is the **mutable-ref pattern**: static registration, dynamic dispatch. +--- + +## Event-Sourced Audit + +Each subagent maintains an append-only event log (`events.jsonl`) and an +eagerly-materialized projection (`state.json`). This is the observability +layer that drives the web dashboard. + +``` +audit event appended → fold(events) → state.json written atomically +web server polls state.json (50ms) → detects change → pushes SSE event +sse.js handler → Zustand store update → component re-render +``` + +### Rules + +- **`fold()` is pure** — given the same event sequence, it must produce the same + projection. No I/O, no randomness, no side effects inside `fold()`. +- **New event types require a fold handler.** Unknown events are silently ignored + (forward compatibility), but a new event that is not folded contributes nothing + to the projection and will not be visible to the web server or UI. +- **Projection is eagerly materialized.** It is written atomically after every + `append()` call. The web server reads `state.json`, not `events.jsonl`. This + keeps polling cheap (one file read) without needing to replay the log. +- **`append()` calls are serialized.** `EventLog` serializes appends via an + internal promise chain. Concurrent callers (e.g., heartbeat timer and + `tool_result` handler) enqueue without racing on the `.tmp.json` file. + +### Adding new observable state + +When adding a new piece of state that the UI should see, wire all five layers: + +1. **Emit an audit event** — add a typed event and an `emit*()` helper in `lib/audit.ts` +2. **Update `fold()`** — handle the new event type to update the projection field +3. **Update the Projection type** — add the field to the `Projection` interface +4. **Web server polling** — read the new field from the cached projection in the 50ms polling callback and include it in the SSE payload +5. **Frontend** — add a handler in `sse.js` and a slice in `store.js` + +All five layers must be present. Missing any one of them produces silent data +loss — the event is appended but never reaches the browser. + +--- + +## SSE Event Lifecycle + +State flows from LLM tool calls to the browser through a five-layer pipeline. +All layers must be wired for a new event type to be visible end-to-end. + +``` +[LLM calls tool] + ↓ +[tool mutates ctx + calls ctx.eventLog.emit*()] ← lib/audit.ts + ↓ +[fold() updates Projection → state.json written atomically] + ↓ +[web server polls state.json every 50ms, detects change] ← web/server.ts + ↓ +[pushEvent(type, payload) → SSE stream → browser] + ↓ +[sse.js addEventListener(type, handler) → useStore.setState()] ← web/js/sse.js + ↓ +[Zustand component selector → React re-render] ← web/js/store.js +``` + +### Concrete example: `koan_set_confidence` + +``` +LLM calls koan_set_confidence({ level: "high" }) + → ctx.intakeConfidence = "high" + → ctx.eventLog.emitConfidenceChange("high", 2) + → append({ kind: "confidence_change", level: "high", iteration: 2 }) + → fold: projection.intakeConfidence = "high", projection.intakeIteration = 2 + → writeState(projection) → state.json + → returns "Confidence set to high." + +web server polling timer fires (50ms) + → pollAgent(intake) → readProjection(dir) → intakeConfidence: "high" + → agent.lastProjection = projection + → intake sub-phase → builds IntakeProgressEvent { confidence: "high", iteration: 2, ... } + → pushEvent("intake-progress", event) → SSE stream + +browser receives "intake-progress" event + → sse.js handler → useStore.setState({ intakeProgress: event }) + → confidence visualization component re-renders +``` + +### Replay on reconnect + +The web server buffers the last value of every stateful SSE event type. On +reconnect, `replayState()` writes all buffered events to the new client. This +ensures the browser always has current state after a network drop, without +requiring a full page reload. + + --- ## Pitfalls @@ -239,19 +334,53 @@ constraint. Do not assume bash calls are blocked for planning roles. ### Don't rely on prompt instructions alone to restrict step behavior -Prompt instructions can be ignored by the LLM. The intake phase learned this -the hard way: the original 3-step design told the LLM not to scout in step 1, -but the LLM frontloaded all work into step 1 anyway, causing duplicate scout -requests in later steps. +**The pattern: prompt expresses intent; mechanical gate catches non-compliance. +Neither alone is sufficient.** -Mechanical enforcement is required for any behavior that is critical to -correctness. Use the permission fence (`checkPermission` with `intakeStep`) to -block tools that must not be used in a given step. Use -`validateStepCompletion()` to block step advancement when required pre-calls -have not been made. Prompts express intent; enforcement catches non-compliance. +- **Prompt alone** — the LLM can ignore it. The original 3-step intake design + told the LLM not to scout in step 1; it frontloaded all work into step 1 + anyway, producing duplicate scout requests in later steps. +- **Gate alone** — the LLM receives a cryptic "blocked" error with no context. + It cannot fix the problem if it does not know what it did wrong. + +Three enforcement mechanisms are available — use the appropriate one for the +constraint: + +| Mechanism | What it enforces | How | +|-----------|-----------------|-----| +| **Permission fence** (`checkPermission`) | Which tools a role (or step) can use | Block at `tool_call` event; LLM sees a rejection message | +| **`validateStepCompletion()`** | Required pre-calls before step advancement | Block `koan_complete_step`; LLM sees an error and must comply | +| **Tool description** | Soft guidance on when to call | Cannot be enforced; LLM can ignore it | + +Any behavioral constraint that matters for correctness needs **both** a prompt +instruction (so the LLM knows what to do) and a mechanical gate (so +non-compliance is caught and corrected, not silently propagated). See [intake-loop.md § Step-Aware Permission Gating](./intake-loop.md#step-aware-permission-gating). +### Don't give a step multiple cognitive goals + +Each step should have exactly one cognitive goal. Grouping multiple goals into +a single step ("do A, then B, then C") enables **simulated refinement**: the +LLM artificially downgrades its output for A to manufacture visible improvement +in C. When all three goals are in one step, the model can pre-plan the +"improvement" because it already knows C is coming. + +Separate `koan_complete_step` calls enforce genuinely isolated reasoning: the +LLM must complete each goal before it sees the next goal's instructions. There +is no opportunity to sandbag — the next step's prompt has not arrived yet. + +This is why the intake phase has three loop steps (Scout / Deliberate / Reflect) +rather than a single monolithic "investigate" step. The scout phase follows the +same principle (orient → investigate → verify → report — four distinct goals, +four distinct steps). + +When designing a new phase, each step should answer: "What is the single thing +this step accomplishes?" If the answer requires "and then", split the step. + +See [intake-loop.md § Prompt Chaining over Stepwise](./intake-loop.md#prompt-engineering-principles) +for the detailed rationale. + ### Don't parse free-text for loop control decisions Confidence (the gate that controls the intake loop) is a structured enum From 923c441879d072d9434f7fbb72551eec637baae5 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 20 Mar 2026 13:35:46 +0700 Subject: [PATCH 072/412] expand model tier documentation and update polling interval references --- docs/ipc.md | 2 +- docs/subagents.md | 63 +++++++++++++++++++++++++++++++++++------------ 2 files changed, 48 insertions(+), 17 deletions(-) diff --git a/docs/ipc.md b/docs/ipc.md index a2de236..e16d75d 100644 --- a/docs/ipc.md +++ b/docs/ipc.md @@ -132,7 +132,7 @@ async function deleteIpcFile(dir) { ... } |--------|----------|---------| | **Parent IPC responder** | 300ms | Detect subagent requests quickly | | **Subagent tool** | 500ms | Wait for parent response | -| **Web server agent polling** | 500ms | Update agent status in UI | +| **Web server agent polling** | 50ms | Update agent status in UI | The parent polls slightly faster than the subagent to ensure it picks up requests promptly. Both intervals are low enough for interactive feel. diff --git a/docs/subagents.md b/docs/subagents.md index 5278690..dec9ecf 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -290,21 +290,52 @@ the write is allowed (cannot scope-check without context). ## Model Tiers -Roles map deterministically to 3 tiers: +### Why 3 tiers instead of per-role configuration + +Koan has 6 roles, but they cluster into 3 capability bands. Configuring 3 +model names is simpler than 6 and matches the natural grouping: + +| Tier | Roles | Why this tier | +|------|-------|--------------| +| **strong** | intake, decomposer, orchestrator, planner | Complex multi-step reasoning: investigating ambiguous requirements, splitting work into stories, verifying correctness, producing precise implementation plans | +| **standard** | executor | Code implementation: reliable tool use and file editing without requiring the deepest reasoning | +| **cheap** | scout | Narrow codebase investigation: reading files, grepping patterns, writing a focused findings report — no deep reasoning needed | + +The mapping is hardcoded in `types.ts` (`ROLE_MODEL_TIER`). Adding a new role +requires updating that map. + +### Configuration + +Model tiers are configured via the web UI at pipeline start (the **model config +gate** fires before any subagent spawns). The user selects one model per tier. +Config is persisted to `~/.koan/config.json` under the `modelTiers` key: + +```json +{ + "modelTiers": { + "strong": "claude-opus-4-5", + "standard": "claude-sonnet-4-5", + "cheap": "claude-haiku-4-5" + }, + "scoutConcurrency": 4 +} +``` + +If no config exists or the config is partial, `resolveModelForRole` returns +`undefined` and the `--model` flag is omitted — pi's current active model +becomes the implicit fallback for all roles. -| Tier | Roles | Purpose | -|------|-------|---------| -| **strong** | intake, decomposer, orchestrator, planner | Complex reasoning, planning, decomposition | -| **standard** | executor | Code implementation | -| **cheap** | scout | Narrow codebase investigation | +Config is **all-or-nothing**: all 3 tiers must be present. Partial configs +are treated as absent and logged. This prevents a half-configured state where +some roles use intended models and others silently fall back. -The user configures which specific model each tier uses via the web UI at -pipeline start (model config gate). If no config exists, `resolveModelForRole` -returns `undefined` and the `--model` flag is omitted, preserving pi's -current active model as the implicit fallback. +### Scout concurrency -Model tier config is all-or-nothing: all 3 tiers must be present. Partial -configs are treated as absent and logged. +`scoutConcurrency` (default: 4) controls how many scout subagents run in +parallel via the bounded pool (`lib/pool.ts`). The pool uses an in-process +semaphore: all scout tasks are submitted to `Promise.all` simultaneously; the +semaphore gates actual execution. Increase this for faster scouting on machines +with ample resources; decrease it to reduce peak memory pressure. --- @@ -350,7 +381,7 @@ The three JSON files have distinct lifecycles per | File | Writer | Reader | When | |------|--------|--------|------| | `task.json` | Parent | Child | Once at startup | -| `state.json` | Child | Parent | Continuous (500ms polling) | +| `state.json` | Child | Parent | Continuous (50ms polling) | | `ipc.json` | Both | Both | Per-request (created, answered, deleted) | --- @@ -361,11 +392,11 @@ The parent registers each subagent with the web server for UI tracking: ```typescript webServer.registerAgent({ id, name, dir, role, model, parent }); -// → starts 500ms polling of audit projection + recent logs +// → starts 50ms polling of audit projection + recent logs // → SSE "agents" event to browser webServer.trackSubagent(dir, role, storyId?); -// → starts 500ms polling for "subagent" + "logs" SSE events +// → starts 50ms polling for "subagent" + "logs" SSE events // ... subagent runs ... @@ -377,7 +408,7 @@ webServer.completeAgent(id); ``` **Dual polling for intake agent:** Both `registerAgent()` and -`trackSubagent()` poll at 500ms. `registerAgent` polling derives the intake +`trackSubagent()` poll at 50ms. `registerAgent` polling derives the intake sub-phase for the progress bar: | Step | Pending ask? | Sub-phase | From 3373332c5def9dddf90bf8d3704a6062d8f9f745 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 20 Mar 2026 13:36:05 +0700 Subject: [PATCH 073/412] update intake-loop polling interval reference to 50ms --- docs/intake-loop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intake-loop.md b/docs/intake-loop.md index 47a4563..d8d7629 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -230,7 +230,7 @@ Both events are folded into the `state.json` projection: - `confidence_change` → `intakeConfidence`, `intakeIteration` - `iteration_start` → `intakeIteration` -The web server polls `state.json` every 500ms for each active agent. When it +The web server polls `state.json` every 50ms for each active agent. When it detects a change in `intakeConfidence` or `intakeIteration`, it pushes an `intake-progress` SSE event to connected browser clients. The event payload includes both the `confidence` string and the `iteration` number, allowing the From 6b1b8bcdf161170d9942f9d9c4b69475548f1577 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 20 Mar 2026 13:36:20 +0700 Subject: [PATCH 074/412] rewrite README to reflect current epic pipeline architecture --- README.md | 171 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 99 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index ac8d11a..7d0c31d 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,99 @@ -# Koan Pi Package - -## Overview - -Koan is an opinionated planning workflow extension for the pi coding agent. It constrains model behavior with deterministic phase orchestration, explicit tool boundaries, and durable file-backed state so planning sessions are repeatable and auditable. - -## Architecture - -The runtime is split into two modes from the same extension entrypoint: - -- **Parent session mode** registers the `koan_plan` MCP tool and the `/koan-execute`, `/koan-status` commands. The parent orchestrates the full workflow when `koan_plan` is invoked. -- **Subagent mode** runs role/phase-specific workflows (architect, developer, technical writer, QR decomposer, reviewer, fix mode). - -The parent controls progression through plan design, plan code, plan docs, quality review, and iterative fixes. Subagents are isolated processes that communicate through persisted artifacts (`plan.json`, `qr-*.json`) and audit projections. - -## Invoking the Planner - -Call `koan_plan` as an MCP tool — the LLM invokes it when the user asks to plan a complex task. No parameters are needed: the conversation up to that point is automatically exported to `conversation.jsonl` in the plan directory and becomes planning input. The architect then persists a structured **background context** index via koan tools. - -The planning pipeline runs sequentially: - -1. **plan-design** (architect) — reads `conversation.jsonl`, builds structured **background context** (previous conversation(s) + indexes), explores the codebase, writes `plan.json`. -2. **plan-code** (developer) — reads `plan.json`, populates code intents and changes. -3. **plan-docs** (technical writer) — reads `plan.json` plus the injected background context snippet, and optionally `conversation.jsonl` for rationale gaps; writes documentation entries. - -Each phase is followed by a QR (quality review) block: decompose → parallel verify → fix loop, up to `MAX_FIX_ITERATIONS`. - -### conversation.jsonl + background context - -`conversation.jsonl` is written once at the start of `koan_plan`. It contains the full session branch as JSONL (one JSON object per line — raw pi `SessionManager` entries, not a plain-text transcript). - -The architect categorically analyzes this file and persists compact markdown **background context** via: -- `koan_set_background_context` - -That context is then injected directly into prompts for planning and QR agents, alongside the conversation.jsonl location. - -### Prompt + convention sources - -- Subagent system prompts are hard-coded in `src/planner/lib/agent-prompts.ts`. -- Convention docs stay file-based in `resources/conventions` and are surfaced to prompts via `CONVENTIONS_DIR`. - -### Slash commands - -| Command | Description | -|---|---| -| `/koan-execute` | Execute a koan plan (not yet implemented) | -| `/koan-status` | Show current workflow phase | - -## Design Decisions - -Key design choices that shape implementation: - -- **Inversion of control**: TypeScript orchestration code drives agent behavior; models do not self-route workflow steps. -- **Tool-call-driven transitions**: step progression happens via `koan_complete_step` tool calls, not conversational chaining. -- **Default-deny permissions**: each phase explicitly allowlists tools; unknown tool/phase access is blocked. -- **Disk-backed mutations**: planning mutations are immediately persisted with atomic writes instead of deferred finalize steps. -- **Need-to-know prompts**: each subagent only receives the minimum context needed for its task. -- **Injected background context**: each workflow step prompt prepends the same `` snippet containing conversation path + compact markdown context. -- **Ephemeral runtime workspace**: intermediate subagent logs/state live in a mkdtemp workspace and are removed on plan completion and session shutdown. - -## Invariants - -The workflow depends on these invariants: - -- Planning phases must block direct `edit`/`write` tools. -- Tool failures must throw errors (not return soft error payloads). -- Cross-reference integrity in the plan must validate before progression. -- MUST-severity QR failures remain blocking even as lower-severity checks de-escalate in later fix iterations. - -## Boundaries - -Current scope focuses on planning and QR orchestration. `/koan-execute` is intentionally not implemented yet. +# Koan + +Koan is a deterministic planning pipeline for the pi coding agent. It takes a +conversation describing a coding task and produces working code — through a +structured sequence of isolated LLM subagents, each with a narrow, auditable +responsibility. + +## How it works + +``` +Conversation + → Intake (confidence-gated investigation loop) + → Decomposer (splits scope into stories) + → Review gate (user approves story list) + → Story loop: + Orchestrator (selects + verifies) → Planner → Executor → repeat + → Done +``` + +Each stage is a separate `pi -p` subprocess. Subagents communicate through +files in a per-session directory, not through shared memory or sockets. The +parent driver reads JSON state and exit codes; it never parses LLM output. + +## Phases + +| Phase | Role | What it does | +|-------|------|-------------| +| **Intake** | `intake` | Reads the conversation, scouts the codebase, asks clarifying questions. Iterates until confident. Writes `context.md`. | +| **Scout** | `scout` | Narrow codebase investigator. Spawned in parallel by intake, decomposer, and planner via `koan_request_scouts`. | +| **Decomposer** | `decomposer` | Reads `context.md`, splits work into story sketches. Each story = one pull request. | +| **Orchestrator** | `orchestrator` | Selects the next story, verifies execution results, routes to retry/done/next. | +| **Planner** | `planner` | Reads a story sketch, writes a step-by-step implementation plan and code context file. | +| **Executor** | `executor` | Follows the plan, modifies the codebase, reports what changed. | + +## Web Dashboard + +Koan serves a local web dashboard at `http://localhost:{port}` during pipeline +execution. The dashboard provides: + +- **Activity feed** — real-time tool calls, scout dispatches, thinking traces +- **Agent monitor** — status, token counts, and recent actions for each + running subagent +- **User interaction** — question forms (intake clarifications), review gates + (story approval), model configuration + +The dashboard uses Server-Sent Events for real-time updates. State is polled +from each subagent's audit projection every 50ms. + +## Key Concepts + +**Step-first workflow.** Every subagent's first action is calling +`koan_complete_step`. This forces a tool call before any text output — critical +because `pi -p` processes exit the moment the LLM produces text without a tool +call. Task instructions are delivered as the return value of that first call. + +**Directory-as-contract.** Each subagent gets a directory with `task.json` +(input), `state.json` (live projection), and `events.jsonl` (audit log). The +spawn command carries only the directory path. No structured data flows through +CLI flags. + +**Default-deny permissions.** Every tool call passes through a permission +fence. Roles cannot use tools outside their scope. Planning roles can only +write inside the epic directory. The intake phase's Extract step additionally +blocks scouting and writing tools at the mechanism level. + +**Driver determinism.** The driver (`driver.ts`) reads JSON and exit codes, +applies routing rules, and spawns the next subagent. It never parses markdown +or adapts to LLM behavior. Routing decisions are deterministic. + +## Configuration + +Model tiers and scout concurrency are configured via the web UI at pipeline +start, then saved to `~/.koan/config.json`: + +```json +{ + "modelTiers": { + "strong": "claude-opus-4-5", + "standard": "claude-sonnet-4-5", + "cheap": "claude-haiku-4-5" + }, + "scoutConcurrency": 4 +} +``` + +Roles map to tiers: intake/decomposer/orchestrator/planner → strong, +executor → standard, scout → cheap. + +## Architecture Documentation + +- **[docs/architecture.md](./docs/architecture.md)** — core invariants, + design principles, pitfalls +- **[docs/subagents.md](./docs/subagents.md)** — spawn lifecycle, step-first + workflow, permissions, model tiers +- **[docs/ipc.md](./docs/ipc.md)** — file-based IPC between subagent and parent +- **[docs/state.md](./docs/state.md)** — driver state machine, story lifecycle, + routing rules +- **[docs/intake-loop.md](./docs/intake-loop.md)** — confidence-gated intake + loop, prompt engineering principles From d9f299cfa6c93435062bdd698690da5072cd1180 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 20 Mar 2026 13:36:33 +0700 Subject: [PATCH 075/412] wire intake-progress SSE events to frontend store --- src/planner/web/js/sse.js | 14 +++++++++++--- src/planner/web/js/store.js | 1 + 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/src/planner/web/js/sse.js b/src/planner/web/js/sse.js index 35d0cb1..68908f5 100644 --- a/src/planner/web/js/sse.js +++ b/src/planner/web/js/sse.js @@ -6,15 +6,23 @@ export function connectSSE(token) { const handlers = { 'init': (d) => set({ availableModels: d.availableModels || [] }), - phase: (d) => set({ phase: d.phase, ...(d.phase !== 'intake' && { pendingInput: null }) }), - 'intake-progress': () => {}, // data model preserved server-side; UI unused for now + phase: (d) => set({ + phase: d.phase, + // Clear interaction state and intake progress when leaving intake + ...(d.phase !== 'intake' && { pendingInput: null, intakeProgress: null }), + }), + 'intake-progress': (d) => set({ intakeProgress: d }), stories: (d) => set({ stories: d.stories }), scouts: (d) => set({ scouts: d.scouts }), agents: (d) => set({ agents: d.agents }), logs: (d) => set({ logs: d.lines, currentToolCallId: d.currentToolCallId ?? null }), subagent: (d) => set({ subagent: d }), 'subagent-idle': () => set({ subagent: null }), - 'pipeline-end': (d) => set(s => ({ phase: d.success ? 'completed' : s.phase, pipelineEnd: d })), + 'pipeline-end': (d) => set(s => ({ + phase: d.success ? 'completed' : s.phase, + pipelineEnd: d, + intakeProgress: null, + })), ask: (d) => set({ pendingInput: { type: 'ask', requestId: d.requestId, payload: d.questions } }), review: (d) => set({ pendingInput: { type: 'review', requestId: d.requestId, payload: d.stories } }), 'model-config': (d) => set(s => ({ diff --git a/src/planner/web/js/store.js b/src/planner/web/js/store.js index 99c7b0a..18ad55a 100644 --- a/src/planner/web/js/store.js +++ b/src/planner/web/js/store.js @@ -10,6 +10,7 @@ export const useStore = create((set) => ({ currentToolCallId: null, // string | null — in-flight tool for the main agent subagent: null, pendingInput: null, + intakeProgress: null, // IntakeProgressEvent | null — set during intake phase // Client-only state notifications: [], From 7a1e9826bfc066407df91f5514ecc74135831eaf Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 20 Mar 2026 13:36:49 +0700 Subject: [PATCH 076/412] add status sidebar with intake confidence visualization, remove orphan phase components --- src/planner/web/ARCHITECTURE.md | 113 +++++++++++----- src/planner/web/css/layout.css | 109 +++++++++++++++ src/planner/web/js/components/App.jsx | 20 ++- .../web/js/components/StatusSidebar.jsx | 126 ++++++++++++++++++ .../js/components/phases/Consolidation.jsx | 39 ------ .../js/components/phases/ContextAnalysis.jsx | 21 --- .../web/js/components/phases/Execution.jsx | 34 ----- .../js/components/phases/ScoutExploration.jsx | 60 --------- 8 files changed, 329 insertions(+), 193 deletions(-) create mode 100644 src/planner/web/js/components/StatusSidebar.jsx delete mode 100644 src/planner/web/js/components/phases/Consolidation.jsx delete mode 100644 src/planner/web/js/components/phases/ContextAnalysis.jsx delete mode 100644 src/planner/web/js/components/phases/Execution.jsx delete mode 100644 src/planner/web/js/components/phases/ScoutExploration.jsx diff --git a/src/planner/web/ARCHITECTURE.md b/src/planner/web/ARCHITECTURE.md index 8731e36..b71ea99 100644 --- a/src/planner/web/ARCHITECTURE.md +++ b/src/planner/web/ARCHITECTURE.md @@ -12,7 +12,7 @@ user input via POST. Built with Preact + Zustand — see server.ts HTTP server, SSE push, WebServerHandle API server-types.ts Shared TypeScript types html/index.html Shell —
+ module script, no static skeleton -css/ Four unchanged stylesheets (variables, layout, components, animations) +css/ Four stylesheets (variables, layout, components, animations) dist/app.js Compiled bundle — generated, not committed js/ app.jsx Entry: render(), connectSSE(), heartbeat interval @@ -31,9 +31,9 @@ esbuild compiles `js/app.jsx` and all imports into `dist/app.js` (single ESM bundle, ~44KB raw / ~16KB gzip). **The alias flags are mandatory.** zustand v4 imports from `react` internally. -Without aliasing, esbuild bundles the full React 19 runtime (~17KB) alongside -Preact — two competing VDOM reconcilers that cannot share a hook dispatcher. -The aliases redirect those imports to `preact/compat`: +Without aliasing, esbuild bundles the full React 19 runtime alongside Preact — +two competing VDOM reconcilers that cannot share a hook dispatcher. The aliases +redirect those imports to `preact/compat`: ``` --alias:react=preact/compat --alias:react-dom=preact/compat @@ -46,8 +46,7 @@ to both. **On-demand build:** `ensureBundle()` in `server.ts` runs at the top of `startWebServer()`. It stats `dist/app.js` against the newest file in `js/` and rebuilds only when stale. Adds ~100ms on first start; skips on subsequent -starts. No manual build step is needed during development — pi loads extensions -from source, so `startWebServer()` is always the entry point. +starts. No manual build step is needed during development. **CI/test path:** `npm run build` runs `build:web` then `tsc`. The tsc step does not process JSX; it type-checks the TypeScript source only. @@ -66,19 +65,19 @@ server.ts ──SSE──► sse.js ──setState──► Zustand store user action ◄──fetch── lib/api.js ◄──────────────────────────┘ ``` -1. `server.ts` pushes SSE events on a 2-second polling tick. +1. `server.ts` pushes SSE events on a 50ms polling tick. 2. `sse.js` registers one `addEventListener` per event type. Each handler calls `useStore.setState()` — the static method, callable outside component context. 3. Components subscribe via `useStore(s => s.slice)`. Zustand shallow-merges `setState` calls and notifies only subscribers whose selected slice changed. - A component reading `s.agents` does not re-render when `s.phase` changes. 4. User actions (form submit, heartbeat) call `lib/api.js` fetch wrappers which POST to `/api/answer`, `/api/review`, or `/api/heartbeat`. `pendingInput` is cleared by the server: a phase transition out of `intake` clears it in the `phase` handler; `ask-cancelled` / `review-cancelled` clear -it by request ID. +it by request ID. `intakeProgress` is cleared when the phase transitions away +from intake or when the pipeline ends. --- @@ -86,48 +85,96 @@ it by request ID. ``` App -├── ProgressBar reads intakeProgress.{subPhase,intakeDone} +├── ProgressBar reads phase for step-fraction fill ├── Header -│ ├── PillStrip reads intakeProgress.{subPhase,intakeDone} +│ ├── PillStrip reads phase for active/done pill state │ └── Timer reads subagent.startedAt, ticks via useEffect interval -├── main.phase-content +│ +├── (isInteractive) main.main-panel │ └── PhaseContent dispatch hub (see below) -├── AgentMonitor reads agents; renders AgentRow per agent +│ +├── (live) div.live-layout ← row split +│ ├── div.live-main +│ │ └── main.main-panel +│ │ ├── SubagentMeta reads subagent +│ │ └── ActivityFeed reads logs, currentToolCallId +│ └── StatusSidebar reads subagent, phase, intakeProgress +│ +├── AgentMonitor reads agents (hides when none active) └── Notifications reads notifications; auto-dismisses via useEffect ``` +**App layout modes:** + +`isInteractive = !phase || pendingInput || showSettings || phase === 'completed'` + +- **Interactive mode** — `PhaseContent` fills the scrollable area. Used for forms, + loading screen, settings overlay, and completion. +- **Live mode** — `SubagentMeta` + `ActivityFeed` fill the left column. + `StatusSidebar` sits in the right column (200px), showing phase-specific + status that updates as SSE events arrive. + **PhaseContent dispatch order:** -1. `!phase` → `` -2. `pendingInput.type === 'ask'` → `` -3. `pendingInput.type === 'review'` → `` -4. `phase === 'intake'` → dispatches on `intakeProgress.subPhase`: - - `'context'` or null → `` - - `'explore'` → `` - - `'questions'` or `'spec'` → `` -5. `phase === 'completed'` → `` -6. default → `` +1. `showSettings` → `` +2. `pending.type === 'model-config'` → `` +3. `!phase` → `` +4. `pending.type === 'ask'` → `` +5. `pending.type === 'review'` → `` +6. `phase === 'completed'` → `` +7. default → `null` (live mode renders the ActivityFeed instead) `key={requestId}` on forms forces a full remount when a new request arrives, resetting local selection state without any explicit cleanup. --- +## StatusSidebar + +The `StatusSidebar` renders phase-specific context in the right column during +live mode. It reads three store slices: `subagent` (visibility gate), `phase` +(which content to show), and `intakeProgress` (intake-specific data). + +**During intake** (`phase === 'intake' && intakeProgress != null`): +- Confidence meter — 5 segments filled according to level (exploring=0, + low=1, medium=3, high=4, certain=5), with a level-appropriate colour +- Iteration indicator — 4 dots, filled up to the current round +- Sub-phase label — current sub-phase name in purple +- Summary — a static description derived from the sub-phase + +**During other phases** — a simple label and "Phase in progress…" message. +Per-phase rich content (e.g. story progress for `executing`) will be added +as those phases are instrumented. + +--- + +## intake-progress SSE event + +`IntakeProgressEvent { subPhase, intakeDone, confidence, iteration }` is pushed +from the server's 50ms agent-polling tick whenever the intake agent's projection +changes. The full pipeline: + +``` +LLM calls koan_set_confidence + → ctx.intakeConfidence set + → confidence_change appended to events.jsonl + → fold() updates state.json projection + → server polls state.json (50ms) → detects change + → pushes intake-progress SSE event + → sse.js: set({ intakeProgress: d }) + → StatusSidebar re-renders with new confidence/iteration +``` + +The event is replayed in `replayState()` on SSE reconnect so the sidebar +recovers its state after a network drop. + +--- + ## Server-side changes **`ensureBundle()`** — async function before `startWebServer()` body. Uses esbuild JS API via dynamic `await import("esbuild")`. `STATIC_ASSETS` is -constructed inside `startWebServer()` after this call completes (it was at -module scope in the old code; moved because asset loading must follow the build). - -**`intake-progress` SSE event** — denormalized event carrying -`{ subPhase: string | null, intakeDone: boolean }`. Pushed from: -- `startAgentPolling()` — after each `agents` push, if subPhase or intakeDone changed -- `handle.pushPhase()` — updates `intakeDone` on every phase transition - -Replayed in `replayState()` on SSE reconnect. Allows `PhaseContent`, -`PillStrip`, and `ProgressBar` to all subscribe to the same store slice -(`intakeProgress`) rather than using two different mechanisms. +constructed inside `startWebServer()` after this call completes. --- diff --git a/src/planner/web/css/layout.css b/src/planner/web/css/layout.css index c3e79f7..ac03c0c 100644 --- a/src/planner/web/css/layout.css +++ b/src/planner/web/css/layout.css @@ -317,3 +317,112 @@ font-size: var(--font-size-sm); color: var(--text-muted); } + +/* ---- Live layout: activity feed + status sidebar ---- */ + +/* Row wrapper that replaces main-panel in live (non-interactive) mode. + * Handles the header offset so inner .main-panel does not need margin-top. */ +.live-layout { + flex: 1 1 0; + min-height: 0; + display: flex; + flex-direction: row; + margin-top: calc(3px + var(--header-height)); +} + +/* Left column — takes all remaining width, scroll contained within. */ +.live-main { + flex: 1 1 0; + min-width: 0; + min-height: 0; + display: flex; + flex-direction: column; +} + +/* Cancel the top margin when main-panel lives inside live-main + * (the live-layout wrapper already provides the header offset). */ +.live-main > .main-panel { + margin-top: 0; +} + +/* ---- Status sidebar ---- */ + +.status-sidebar { + width: 200px; + flex-shrink: 0; + background: var(--bg-elevated); + border-left: 1px solid var(--border); + overflow-y: auto; + padding: var(--gap-md); +} + +.sidebar-heading { + font-family: var(--font-mono); + font-size: 10px; + color: var(--text-dim); + text-transform: uppercase; + letter-spacing: 0.08em; + margin-bottom: var(--gap-md); +} + +.sidebar-section { + margin-bottom: var(--gap-md); +} + +.sidebar-label { + font-family: var(--font-mono); + font-size: 10px; + color: var(--text-ghost); + text-transform: uppercase; + letter-spacing: 0.06em; + margin-bottom: var(--gap-xs); +} + +/* Five-segment confidence bar */ +.sidebar-segments { + display: flex; + gap: 3px; + margin-bottom: var(--gap-xs); +} + +.sidebar-segment { + flex: 1; + height: 6px; + border-radius: 3px; + transition: background 300ms ease; +} + +/* Value line beneath a segment bar or dots */ +.sidebar-value { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + font-weight: 500; + color: var(--text-muted); +} + +/* Four-dot iteration indicator */ +.sidebar-dots { + display: flex; + gap: 4px; + margin-bottom: var(--gap-xs); +} + +.sidebar-dot { + width: 8px; + height: 8px; + border-radius: 50%; + transition: background 300ms ease; +} + +.sidebar-divider { + height: 1px; + background: var(--border); + margin: var(--gap-md) 0; +} + +.sidebar-summary { + font-family: var(--font-mono); + font-size: 11px; + color: var(--text-dim); + line-height: 1.4; +} diff --git a/src/planner/web/js/components/App.jsx b/src/planner/web/js/components/App.jsx index 031ae91..4bb6f71 100644 --- a/src/planner/web/js/components/App.jsx +++ b/src/planner/web/js/components/App.jsx @@ -4,6 +4,7 @@ import { SubagentMeta } from './SubagentMeta.jsx' import { PhaseContent } from './PhaseContent.jsx' import { ActivityFeed } from './ActivityFeed.jsx' import { AgentMonitor } from './AgentMonitor.jsx' +import { StatusSidebar } from './StatusSidebar.jsx' import { Notifications } from './Notifications.jsx' import { useStore } from '../store.js' @@ -12,8 +13,8 @@ export function App({ token, topic }) { const pending = useStore(s => s.pendingInput) const showSettings = useStore(s => s.showSettings) - // When showing interactive content (forms, model config, loading, completion), use scroll layout - // When showing live subagent activity, use fill layout with activity feed + // Interactive mode: forms, settings overlay, loading screen, completion. + // Live mode: active subagent activity feed with status sidebar. const isInteractive = !phase || pending || showSettings || phase === 'completed' return ( @@ -27,10 +28,17 @@ export function App({ token, topic }) {
) : ( -
- - -
+ // Live layout: activity feed on the left, status sidebar on the right. + // The sidebar spans the full height of the content area, independently scrollable. +
+
+
+ + +
+
+ +
)} diff --git a/src/planner/web/js/components/StatusSidebar.jsx b/src/planner/web/js/components/StatusSidebar.jsx new file mode 100644 index 0000000..3a9c315 --- /dev/null +++ b/src/planner/web/js/components/StatusSidebar.jsx @@ -0,0 +1,126 @@ +import { useStore } from '../store.js' + +// Maps confidence level to number of filled segments (out of 5) and accent colour. +const CONFIDENCE_DISPLAY = { + exploring: { segments: 0, color: 'var(--text-ghost)' }, + low: { segments: 1, color: 'var(--red)' }, + medium: { segments: 3, color: 'var(--orange)' }, + high: { segments: 4, color: 'var(--green)' }, + certain: { segments: 5, color: 'var(--green)' }, +} + +// Default summary text per sub-phase shown while the agent is working. +const SUBPHASE_SUMMARY = { + extract: 'Reading conversation to understand the task…', + scout: 'Exploring codebase via parallel scouts…', + deliberate: 'Analyzing findings, preparing questions…', + reflect: 'Verifying completeness of understanding…', + questions: 'Waiting for user response…', + synthesize: 'Writing context.md…', +} + +export function StatusSidebar() { + const subagent = useStore(s => s.subagent) + const phase = useStore(s => s.phase) + const intakeProgress = useStore(s => s.intakeProgress) + + // Only render when there is an active subagent. + if (!subagent) return null + + const isIntake = phase === 'intake' + + return ( + + ) +} + +// -- Intake-specific status: confidence meter, iteration dots, sub-phase, summary -- + +function IntakeStatus({ progress }) { + const { confidence, iteration, subPhase, intakeDone } = progress + const conf = CONFIDENCE_DISPLAY[confidence] ?? CONFIDENCE_DISPLAY.exploring + + return ( + <> + +
+ {Array.from({ length: 5 }, (_, i) => ( +
+ ))} +
+
+ {confidence ?? 'exploring'} +
+ + + {iteration > 0 && ( + +
+ {Array.from({ length: 4 }, (_, i) => ( +
+ ))} +
+
Round {iteration} of 4
+ + )} + + {subPhase && ( + +
{subPhase}
+ + )} + +
+ + +
+ {intakeDone + ? 'Intake complete.' + : (SUBPHASE_SUMMARY[subPhase] ?? 'Working…')} +
+ + + ) +} + +// -- Generic status for decompose / review / execute phases -- + +function GenericStatus({ phase }) { + const label = + phase === 'decomposition' ? 'Decomposing into stories' + : phase === 'review' ? 'Review in progress' + : phase === 'executing' ? 'Executing stories' + : phase ?? 'In progress' + + return ( + +
{label}
+
Phase in progress…
+ + ) +} + +// -- Shared section wrapper -- + +function SidebarSection({ label, children }) { + return ( +
+
{label}
+ {children} +
+ ) +} diff --git a/src/planner/web/js/components/phases/Consolidation.jsx b/src/planner/web/js/components/phases/Consolidation.jsx deleted file mode 100644 index 96c3c51..0000000 --- a/src/planner/web/js/components/phases/Consolidation.jsx +++ /dev/null @@ -1,39 +0,0 @@ -import { useStore } from '../../store.js' - -export function Consolidation() { - const logs = useStore(s => s.logs) - const scouts = useStore(s => s.scouts) - const scoutCount = scouts.length - - return ( -
-

Writing project specification...

-
-
- ✓ - Context extracted from conversation -
- {scoutCount > 0 && ( -
- ✓ - {scoutCount} scout{scoutCount !== 1 ? 's' : ''} explored the codebase -
- )} -
- ◌ - Writing context.md... -
-
- {logs.length > 0 && ( -
- {logs.slice(-3).map((line, i) => ( -
- {line.tool} - {line.summary || ''} -
- ))} -
- )} -
- ) -} diff --git a/src/planner/web/js/components/phases/ContextAnalysis.jsx b/src/planner/web/js/components/phases/ContextAnalysis.jsx deleted file mode 100644 index 3962b03..0000000 --- a/src/planner/web/js/components/phases/ContextAnalysis.jsx +++ /dev/null @@ -1,21 +0,0 @@ -import { useStore } from '../../store.js' - -export function ContextAnalysis() { - const logs = useStore(s => s.logs) - - return ( -
-

Reading your conversation to understand the task...

- {logs.length > 0 && ( -
- {logs.slice(-4).map((line, i) => ( -
- {line.tool} - {line.summary || ''} -
- ))} -
- )} -
- ) -} diff --git a/src/planner/web/js/components/phases/Execution.jsx b/src/planner/web/js/components/phases/Execution.jsx deleted file mode 100644 index 5efa4bf..0000000 --- a/src/planner/web/js/components/phases/Execution.jsx +++ /dev/null @@ -1,34 +0,0 @@ -import { useStore } from '../../store.js' - -export function Execution({ phase }) { - const stories = useStore(s => s.stories) - - const phaseLabel = phase === 'decomposition' ? 'Decomposing into stories...' - : phase === 'review' ? 'Awaiting spec review...' - : phase === 'executing' ? 'Executing stories...' - : `Phase: ${phase}` - - return ( -
-

{phaseLabel}

- {stories.length > 0 && ( -
- {stories.map(story => { - const icon = story.status === 'done' ? '✓' - : story.status === 'skipped' ? '—' - : (story.status === 'executing' || story.status === 'planning' || story.status === 'verifying') ? '●' - : '◌' - const iconCls = story.status === 'done' ? 'icon-done' : 'icon-pending' - return ( -
- {icon} - {story.storyId} - [{story.status}] -
- ) - })} -
- )} -
- ) -} diff --git a/src/planner/web/js/components/phases/ScoutExploration.jsx b/src/planner/web/js/components/phases/ScoutExploration.jsx deleted file mode 100644 index 7a287a1..0000000 --- a/src/planner/web/js/components/phases/ScoutExploration.jsx +++ /dev/null @@ -1,60 +0,0 @@ -import { useStore } from '../../store.js' - -const COLORS = ['var(--blue)', 'var(--purple)', 'var(--orange)', 'var(--yellow)', 'var(--pink)'] - -export function ScoutExploration() { - const scouts = useStore(s => s.scouts) - - return ( -
-

- Exploring your codebase with {scouts.length} scout{scouts.length !== 1 ? 's' : ''}… -

- {scouts.map((scout, i) => ( - - ))} - -
- ) -} - -function ScoutCard({ scout, color }) { - const cls = scout.status === 'completed' ? 'card card-done' - : scout.status === 'failed' ? 'card card-failed' - : 'card card-running' - const symbol = scout.status === 'completed' ? '✓' : scout.status === 'failed' ? '✗' : '●' - - return ( -
-
- {symbol} - {scout.id} - {scout.role} -
-
- {scout.status === 'completed' ? scout.completionSummary - : scout.status === 'failed' ? Scout failed - : {scout.lastAction || 'Starting…'}} -
-
- ) -} - -function CompletedContext({ scouts }) { - const completed = scouts.filter(s => s.status === 'completed' && s.completionSummary) - if (completed.length === 0) return null - - return ( - <> -
CONTEXT SO FAR
-
    - {completed.map(s => ( -
  • - {s.id}: {s.completionSummary?.slice(0, 100)} - {(s.completionSummary?.length ?? 0) > 100 ? '…' : ''} -
    • - ))} -
- - ) -} From c07bddda0bb6fd2ddf915deb34685d7ac6294400 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 20 Mar 2026 22:51:25 +0700 Subject: [PATCH 077/412] T1 Stale Noise (23 files) --- docs/intake-loop.md | 170 ++++++++++++++---- docs/ipc.md | 31 ++-- docs/subagents.md | 103 ++++++----- src/planner/lib/audit.ts | 10 +- src/planner/lib/ipc-responder.ts | 55 +++--- src/planner/lib/ipc.ts | 28 ++- src/planner/lib/permissions.ts | 19 ++ src/planner/model-config.ts | 2 +- src/planner/model-phase.ts | 14 -- src/planner/model-resolver.ts | 2 +- src/planner/phases/intake/prompts.ts | 73 ++++++-- src/planner/tools/ask.ts | 79 ++++---- src/planner/tools/workflow.ts | 2 +- src/planner/types.ts | 7 + src/planner/ui/config/menu.ts | 2 +- src/planner/ui/config/model-selection.ts | 2 +- src/planner/web/css/components.css | 17 ++ .../web/js/components/forms/QuestionCard.jsx | 16 +- .../web/js/components/forms/QuestionForm.jsx | 66 +++---- src/planner/web/js/lib/api.js | 46 +++-- src/planner/web/js/sse.js | 2 +- src/planner/web/server-types.ts | 7 +- src/planner/web/server.ts | 37 +++- 23 files changed, 496 insertions(+), 294 deletions(-) delete mode 100644 src/planner/model-phase.ts diff --git a/docs/intake-loop.md b/docs/intake-loop.md index d8d7629..4d7ade5 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -43,10 +43,9 @@ Steps 1 and 5 execute exactly once. ### `getNextStep()` hook -The `BasePhase` class previously used a hardcoded linear counter: -`step+1` until `totalSteps`, then `null` (done). This was extended with a -`getNextStep(currentStep)` hook that subclasses override to implement -non-linear flows. +`BasePhase` provides a default linear counter: `step+1` until `totalSteps`, +then `null` (done). Subclasses override `getNextStep(currentStep)` to +implement non-linear flows. ```typescript // Default: strictly linear. @@ -109,8 +108,8 @@ UI can distinguish loop iterations. ### Why a separate tool, not a parameter -An earlier design considered adding `confidence` as an optional parameter to -`koan_complete_step`. This was rejected for two reasons: +`koan_set_confidence` is a dedicated tool rather than a parameter on +`koan_complete_step` for two reasons: 1. **Optional parameters are skippable.** LLMs frequently omit optional parameters, especially when under token pressure. A separate tool call is @@ -176,22 +175,43 @@ infinite loops if the LLM consistently declares non-certain confidence. ## Step-Aware Permission Gating -### Why step 1 is mechanically read-only +The permission fence accepts an optional `intakeStep` parameter and blocks +specific tools during steps where they would undermine the workflow. Two +steps have mechanical tool restrictions: -Step 1 (Extract) should only read the conversation. Before this redesign, step -isolation was enforced only through prompt instructions ("do NOT call -koan_request_scouts in this step"). The LLM frequently violated this by -frontloading all work into step 1, leading to duplicate scout requests in -later steps. +### Step 1 (Extract): read-only -The new design adds a mechanical layer: `checkPermission()` accepts an -optional `intakeStep` parameter and blocks a defined set of tools when +Step 1 should only read the conversation. Without a mechanical gate, the LLM +frontloads all work into step 1, leading to duplicate scout requests in +later steps and bypassing the step-first workflow pattern. + +`checkPermission()` blocks all side-effecting tools when `role === "intake" && intakeStep === 1`: ``` koan_request_scouts, koan_ask_question, koan_set_confidence, write, edit ``` +### Step 3 (Deliberate): no confidence assessment + +Step 3 is for enumerating knowns/unknowns and asking questions. Confidence +assessment belongs exclusively in step 4 (Reflect), where the LLM must +generate verification questions and answer them with evidence before declaring +confidence. + +Without this gate, the LLM calls `koan_set_confidence("high")` during +Deliberate — mentally committing to completion before entering verification. +This anchors the subsequent Reflect step toward "certain," undermining the +verification loop. + +`checkPermission()` blocks `koan_set_confidence` when +`role === "intake" && intakeStep === 3`. + +The gate enforces temporal separation between deliberation (asking/deciding +what to ask) and reflection (verifying completeness). + +### Step propagation + The current step is propagated via `ctx.intakeStep`, kept in sync by the `onStepUpdated()` hook in `IntakePhase`: @@ -208,17 +228,18 @@ current active step at tool call time. ### Prompt + enforcement is not redundant -The prompt still tells the LLM not to use side-effecting tools in step 1. -The permission gate is a fallback that catches prompt non-compliance. Together: -the prompt prevents the behavior; the gate catches it when the prompt fails. -Neither alone is sufficient — the prompt can be ignored; the gate with no -prompt would produce confusing "blocked" errors with no context for the LLM. +The prompt tells the LLM not to use side-effecting tools in step 1 and not +to assess confidence in step 3. The permission gates are fallbacks that catch +prompt non-compliance. Together: the prompt prevents the behavior; the gate +catches it when the prompt fails. Neither alone is sufficient — the prompt can +be ignored; the gate with no prompt would produce confusing "blocked" errors +with no context for the LLM. --- ## Audit Events and SSE Propagation -Two new audit event types support UI visualization of confidence and iteration: +Two audit event types support UI visualization of confidence and iteration: | Event | Emitted by | When | |-------|-----------|------| @@ -252,7 +273,7 @@ mechanisms that address specific failure modes. ### Prompt Chaining over Stepwise (Scout / Deliberate / Reflect as separate steps) A monolithic "investigate" step — containing scouting, deliberation, and -reflection in sequence within a single prompt — was rejected in favor of three +reflection in sequence within a single prompt — is rejected in favor of three separate `koan_complete_step` calls. The risk with a monolithic step is **simulated refinement**: the LLM @@ -286,6 +307,43 @@ LLM to re-state updated understanding before forming follow-up questions, preventing the "lost in the middle" problem where findings from early scout tool results are effectively forgotten by the time questions are formulated. +### Anticipatory Reflection in Deliberate (downstream impact assessment) + +Between the Thread-of-Thought enumeration (Phase A) and question formulation +(Phase B), the Deliberate step includes a downstream impact assessment +(Phase A.5). For each unknown, the LLM must assess: if this assumption is +wrong, what happens to downstream planning? Could it split or merge stories? +Would the executor hit a surprise? + +Each unknown is classified as ASK (user input needed), SCOUT (follow-up can +resolve), or SAFE (genuinely an implementation detail). This is the +Anticipatory Reflection pattern: before deciding on an action (ask or skip), +anticipate the consequences of getting it wrong. + +Without this step, the LLM classifies unknowns as "implementation details" +without considering downstream consequences, avoiding questions it should ask. +The explicit impact assessment makes the cost of wrong assumptions concrete +and forces the LLM to justify each skip. + +### Default-ask question framing (preventing question avoidance) + +The Deliberate step frames question-asking as the default, with skipping +requiring justification. The criteria use "Default: ask. You may skip a +question ONLY if ALL of these are true" — three restrictive conditions that +require the unknown to be purely about implementation, incapable of changing +story boundaries, and unambiguous. + +This inverts the typical LLM bias. LLMs prefer advancing the workflow over +pausing it, and will exploit any "skip if" framing by finding reasons to skip. +By making "ask" the default and "skip" the exception requiring triple +justification, the prompt aligns the path of least resistance with the desired +behavior. + +The framing also explicitly positions the user as a collaborator ("The user is +your collaborator, not an interruption") and emphasizes that intake is the only +phase where the user can be consulted ("The decomposer cannot ask questions +later — this is the only chance to get clarification"). + ### Chain-of-Verification in Reflect (evidence-grounded self-assessment) The Reflect step instructs the LLM to generate 3–5 verification questions @@ -315,8 +373,8 @@ confidence level: - **Positive:** "certain means ALL of these are true" (four specific conditions about scope, codebase knowledge, user decisions, and story immutability) -- **Negative:** "you are NOT certain if" (four failure modes that preclude - certainty) +- **Negative:** "you are NOT certain if ANY of these are true" (seven + failure modes that preclude certainty) This is the Contrastive Chain-of-Thought pattern. A single positive definition ("certain means you have everything you need") leaves the LLM to interpret what @@ -325,6 +383,23 @@ confidence to "certain" prematurely to exit the loop faster (token-saving behavior). The negative examples make the failure modes concrete and explicit, raising the bar for claiming certainty. +The negative checklist includes conditions that require positive evidence +(questions asked, assumptions verified) rather than the absence of negative +signals. The critical first condition — "you have not asked the user any +questions in this or any previous round" — is mechanically non-vacuous: it is +true or false based on whether `koan_ask_question` was called, not on a +judgment call the LLM can rationalize. This prevents the checklist from being +vacuously satisfied when no user interaction has occurred. + +### Stakes framing (EmotionPrompt for accountability) + +The system prompt includes accountability-invoking language: "A question you +don't ask is an answer you're making up." This is the EmotionPrompt pattern +(self-monitoring theory variant), which increases truthfulness and factual +accuracy by invoking social accountability. The framing connects intake +shortcuts directly to downstream failures, making the cost of skipping +questions concrete rather than abstract. + ### Iteration-aware guidance (first iteration vs. refinement) Steps 2 (Scout) and 3 (Deliberate) produce different instruction text for @@ -339,16 +414,31 @@ on the gaps surfaced by reflection. The iteration number is passed as a parameter to `intakeStepGuidance()`, which branches on it to produce the appropriate framing. +### Iteration expectations (soft minimum via GIoT) + +The Reflect step includes soft guidance that round 1 should rarely produce +"certain" confidence, and that confidence should be capped at "high" if no +questions have been asked. This is inspired by the GIoT (Guided Iteration of +Thought) pattern, which forces a minimum number of iterations to ensure +adequate exploration. + +The guidance is soft rather than mechanically enforced (unlike the hard +`MAX_ITERATIONS` cap) to avoid forcing unnecessary iterations on genuinely +trivial tasks. It provides directional pressure: the LLM can still declare +"certain" on round 1, but it must do so against explicit guidance that this +is unusual. This makes premature exit a deliberate, justified choice rather +than the path of least resistance. + --- ## Pitfalls ### Don't put confidence in koan_complete_step's `thoughts` parameter -`thoughts` is for internal chain-of-thought reasoning. A previous design -considered parsing confidence from the thoughts string. This violates the -driver determinism invariant: the driver never parses free-text. Confidence -must flow through a structured tool call with a typed parameter. +`thoughts` is for internal chain-of-thought reasoning. Parsing confidence from +the thoughts string would violate the driver determinism invariant: the driver +never parses free-text. Confidence must flow through a structured tool call +with a typed parameter. ### Don't rely on the Reflect prompt alone to enforce koan_set_confidence @@ -377,12 +467,30 @@ it were available to other roles, they could set `ctx.intakeConfidence` spuriously, affecting the intake loop's behavior if intake is running concurrently (which it isn't currently, but could be in the future). +### Don't allow koan_set_confidence during Deliberate (step 3) + +`koan_set_confidence` is blocked during step 3 via `STEP_3_BLOCKED_TOOLS`. +Without this gate, the LLM sets confidence during Deliberate, anchoring the +subsequent Reflect step toward "certain" and undermining the verification +loop. Confidence assessment must happen only during Reflect (step 4), after +the LLM has generated and answered verification questions. + +### Don't make the "NOT certain" checklist vacuously satisfiable + +Every condition in the negative confidence checklist must be non-vacuously +testable — it must be possible for the condition to fire based on observable +facts. Conditions framed as "a user answer raised a new question" are +vacuously false when no questions have been asked (no answers exist, so no +follow-up can be triggered). Prefer conditions that require positive evidence: +"you have not asked any questions" is mechanically true or false based on +whether `koan_ask_question` was called. + ### Don't skip `ctx.intakeStep` sync in onStepUpdated The permission gate reads `ctx.intakeStep` at tool call time. If `onStepUpdated()` were not called on loop-back (step 4 → step 2), step 2 would execute with `ctx.intakeStep = 4`, and the step-1 gate would not fire -(step 4 ≠ 1). The step 1 gate is specifically `intakeStep === 1`. Only step 1 -needs gating, so the only critical sync is the boot → step 1 transition. But -keeping `ctx.intakeStep` accurate at all times makes the invariant easier to -reason about and avoids subtle bugs if the gating logic is ever extended. +(step 4 ≠ 1). Steps 1 and 3 both need gating (step 1 blocks side-effecting +tools; step 3 blocks `koan_set_confidence`), so keeping `ctx.intakeStep` +accurate at all times is essential for correct gate behavior across loop +iterations. diff --git a/docs/ipc.md b/docs/ipc.md index e16d75d..72fff81 100644 --- a/docs/ipc.md +++ b/docs/ipc.md @@ -54,8 +54,8 @@ field: ### `ask` — User questions -The subagent needs human input. The request contains questions with options; -the response contains the user's selections. +The subagent needs human input. The request contains one question with +options; the response contains the user's selection. ```typescript interface AskIpcFile { @@ -63,13 +63,12 @@ interface AskIpcFile { id: string; // UUID, for response correlation createdAt: string; payload: { - questions: Array<{ - id: string; - question: string; - options: Array<{ label: string }>; - multi?: boolean; - recommended?: number; // 0-indexed - }>; + id: string; + question: string; + context?: string; // optional multi-paragraph background + options: Array<{ label: string }>; + multi?: boolean; + recommended?: number; // 0-indexed }; response: AskResponse | null; // null = pending, non-null = answered } @@ -189,30 +188,28 @@ interface ScoutSpawnContext { ## Ask Flow ``` -intake-llm calls koan_ask_question({ questions: [...] }) +intake-llm calls koan_ask_question({ id, question, context?, options, ... }) → tool writes AskIpcFile { type: "ask", response: null } → tool enters 500ms poll loop (LLM turn blocked) ipc-responder detects { type: "ask", response: null } - → appends "Other" option to each question - → calls webServer.requestAnswer(questions, signal) + → appends "Other" option to the question + → calls webServer.requestAnswer(question, signal) → creates Promise in pendingInputs map → SSE "ask" event → browser renders QuestionForm → user fills form, clicks Submit → POST /api/answer → resolves Promise - → maps answers to AskAnswerPayload + → maps answer to AskAnswerPayload → writes AskResponse to ipc.json (atomic) tool poll detects response !== null → breaks loop → deleteIpcFile(dir) - → formats answers as structured text + → formats answer as structured text → returns to LLM ``` -The "Other" option is appended server-side — the LLM never includes it. On -the result side, `removeRecommendedTag()` strips the ` (Recommended)` display -suffix before building selection results. +The "Other" option is appended server-side — the LLM never includes it. --- diff --git a/docs/subagents.md b/docs/subagents.md index dec9ecf..87e069a 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -33,9 +33,9 @@ interface IntakeTask extends SubagentTaskBase { interface ScoutTask extends SubagentTaskBase { role: "scout"; - question: string; // What to investigate - outputFile: string; // Where to write findings (relative to subagentDir) - investigatorRole: string; // Persona for the scout ("security auditor", etc.) + question: string; // What to investigate + outputFile: string; // Where to write findings (relative to subagentDir) + investigatorRole: string; // Persona for the scout ("security auditor", etc.) } interface DecomposerTask extends SubagentTaskBase { @@ -56,12 +56,16 @@ interface PlannerTask extends SubagentTaskBase { interface ExecutorTask extends SubagentTaskBase { role: "executor"; storyId: string; - retryContext?: string; // Failure summary from previous attempt + retryContext?: string; // Failure summary from previous attempt } type SubagentTask = - | IntakeTask | ScoutTask | DecomposerTask - | OrchestratorTask | PlannerTask | ExecutorTask; + | IntakeTask + | ScoutTask + | DecomposerTask + | OrchestratorTask + | PlannerTask + | ExecutorTask; ``` ### Lifecycle @@ -87,13 +91,13 @@ The previous design passed task configuration as 9 CLI flags Problems this caused: -| Problem | Example | -|---------|---------| +| Problem | Example | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Flat namespace collision** | `--koan-role` (pipeline role: "scout") vs `--koan-scout-role` (investigator persona: "security auditor") — two unrelated concepts sharing a prefix | -| **Unstructured** | Role-specific fields mixed with common fields; `extraFlags: string[]` escape hatch needed for extensibility | -| **Size limits** | `--koan-retry-context` carries multi-paragraph failure summaries — visible in `ps aux`, subject to `ARG_MAX` | -| **Uninspectable** | After a crash, reconstructing what a subagent was asked to do requires parsing process arguments from logs | -| **Inconsistent** | Runtime communication uses files (ipc.json); observation uses files (state.json); but task input used CLI args | +| **Unstructured** | Role-specific fields mixed with common fields; `extraFlags: string[]` escape hatch needed for extensibility | +| **Size limits** | `--koan-retry-context` carries multi-paragraph failure summaries — visible in `ps aux`, subject to `ARG_MAX` | +| **Uninspectable** | After a crash, reconstructing what a subagent was asked to do requires parsing process arguments from logs | +| **Inconsistent** | Runtime communication uses files (ipc.json); observation uses files (state.json); but task input used CLI args | --- @@ -160,11 +164,11 @@ parameters live in `task.json` and flow into step guidance via the phase class. `dispatchPhase` validates required `task.json` fields before instantiating: -| Role | Required fields | Failure if missing | -|------|----------------|-------------------| -| scout | `question`, `outputFile` | Step 1 guidance has no assignment → LLM outputs confused text → exits | -| planner | `storyId` | Malformed paths like `stories//plan/plan.md` | -| executor | `storyId` | Same path issue | +| Role | Required fields | Failure if missing | +| -------- | ------------------------ | --------------------------------------------------------------------- | +| scout | `question`, `outputFile` | Step 1 guidance has no assignment → LLM outputs confused text → exits | +| planner | `storyId` | Malformed paths like `stories//plan/plan.md` | +| executor | `storyId` | Same path issue | --- @@ -194,16 +198,17 @@ LLM calls koan_complete_step: `BasePhase` provides three overridable hooks for non-linear flows: -| Hook | Purpose | Default | -|------|---------|---------| -| `getNextStep(step)` | Returns next step number or null (done). **Must be pure.** | Linear: step+1, null at totalSteps | -| `onLoopBack(from, to)` | Side effects of backward transitions: state resets, counter increments, event emission. Async — properly awaited. | no-op | -| `validateStepCompletion(step)` | Pre-condition check before advancing. Returns null to allow or an error string to block (returned as tool result so LLM can fix it). | null (always allow) | +| Hook | Purpose | Default | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | +| `getNextStep(step)` | Returns next step number or null (done). **Must be pure.** | Linear: step+1, null at totalSteps | +| `onLoopBack(from, to)` | Side effects of backward transitions: state resets, counter increments, event emission. Async — properly awaited. | no-op | +| `validateStepCompletion(step)` | Pre-condition check before advancing. Returns null to allow or an error string to block (returned as tool result so LLM can fix it). | null (always allow) | `IntakePhase` overrides all three to implement a confidence-gated loop over steps 2–4. See [intake-loop.md](./intake-loop.md) for details. Key invariants: + - **`getNextStep()` is pure** — it only returns a step number. Mutation belongs in `onLoopBack()`. - **`step_transition` is NOT emitted at `begin()`** — it fires when step 1 guidance is first returned, so the event log reflects when the LLM actually @@ -269,14 +274,14 @@ constrains intended use; enforcement does not. ### Role permission matrix -| Role | koan tools | write/edit | notes | -|------|-----------|------------|-------| -| **intake** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `koan_set_confidence` | path-scoped to epicDir | `koan_set_confidence` blocked in step 1 (Extract) | -| **scout** | `koan_complete_step` | path-scoped to epicDir | No `koan_ask_question` (no user interaction). No `koan_request_scouts` (no nested scouts). | -| **decomposer** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | — | -| **orchestrator** | `koan_complete_step`, `koan_ask_question`, `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | path-scoped to epicDir | No `koan_request_scouts` — orchestrator uses bash for verification | -| **planner** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | — | -| **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | +| Role | koan tools | write/edit | notes | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------ | +| **intake** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `koan_set_confidence` | path-scoped to epicDir | `koan_set_confidence` blocked in step 1 (Extract) | +| **scout** | `koan_complete_step` | path-scoped to epicDir | No `koan_ask_question` (no user interaction). No `koan_request_scouts` (no nested scouts). | +| **decomposer** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | — | +| **orchestrator** | `koan_complete_step`, `koan_ask_question`, `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | path-scoped to epicDir | No `koan_request_scouts` — orchestrator uses bash for verification | +| **planner** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | — | +| **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | ### Path scoping @@ -295,11 +300,11 @@ the write is allowed (cannot scope-check without context). Koan has 6 roles, but they cluster into 3 capability bands. Configuring 3 model names is simpler than 6 and matches the natural grouping: -| Tier | Roles | Why this tier | -|------|-------|--------------| -| **strong** | intake, decomposer, orchestrator, planner | Complex multi-step reasoning: investigating ambiguous requirements, splitting work into stories, verifying correctness, producing precise implementation plans | -| **standard** | executor | Code implementation: reliable tool use and file editing without requiring the deepest reasoning | -| **cheap** | scout | Narrow codebase investigation: reading files, grepping patterns, writing a focused findings report — no deep reasoning needed | +| Tier | Roles | Why this tier | +| ------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **strong** | intake, decomposer, orchestrator, planner | Complex multi-step reasoning: investigating ambiguous requirements, splitting work into stories, verifying correctness, producing precise implementation plans | +| **standard** | executor | Code implementation: reliable tool use and file editing without requiring the deepest reasoning | +| **cheap** | scout | Narrow codebase investigation: reading files, grepping patterns, writing a focused findings report — no deep reasoning needed | The mapping is hardcoded in `types.ts` (`ROLE_MODEL_TIER`). Adding a new role requires updating that map. @@ -347,7 +352,7 @@ Scouts are deliberately constrained compared to other roles: - **No `koan_ask_question`** — scouts do not ask questions - **No `koan_request_scouts`** — scouts do not spawn nested scouts - **No IPC responder** — since there is no web server, no IPC responder runs -- **Single step** — scouts have `totalSteps = 1`; they do one job and exit +- **Four steps** -- scouts have `totalSteps = 4` (orient -> investigate -> verify -> report). Each step has exactly one cognitive goal, following the "don't give a step multiple cognitive goals" principle from [architecture.md Pitfalls](./architecture.md#pitfalls): separate `koan_complete_step` calls enforce genuinely isolated reasoning and prevent the LLM from sandbagging an earlier step because it already knows a later step is coming - **Cheap model** — scouts use the cheapest available model - **Parallel execution** — up to 4 scouts run concurrently via bounded pool - **Non-fatal failures** — a failed scout does not abort the parent; its task @@ -378,11 +383,11 @@ After a subagent runs, its directory contains: The three JSON files have distinct lifecycles per [architecture.md § Directory-as-contract](./architecture.md#6-directory-as-contract): -| File | Writer | Reader | When | -|------|--------|--------|------| -| `task.json` | Parent | Child | Once at startup | -| `state.json` | Child | Parent | Continuous (50ms polling) | -| `ipc.json` | Both | Both | Per-request (created, answered, deleted) | +| File | Writer | Reader | When | +| ------------ | ------ | ------ | ---------------------------------------- | +| `task.json` | Parent | Child | Once at startup | +| `state.json` | Child | Parent | Continuous (50ms polling) | +| `ipc.json` | Both | Both | Per-request (created, answered, deleted) | --- @@ -411,14 +416,14 @@ webServer.completeAgent(id); `trackSubagent()` poll at 50ms. `registerAgent` polling derives the intake sub-phase for the progress bar: -| Step | Pending ask? | Sub-phase | -|------|-------------|-----------| -| 1 | — | `"extract"` | -| 2 | — | `"scout"` | -| 3 | yes | `"questions"` | -| 3 | no | `"deliberate"` | -| 4 | — | `"reflect"` | -| 5 | — | `"synthesize"` | +| Step | Pending ask? | Sub-phase | +| ---- | ------------ | -------------- | +| 1 | — | `"extract"` | +| 2 | — | `"scout"` | +| 3 | yes | `"questions"` | +| 3 | no | `"deliberate"` | +| 4 | — | `"reflect"` | +| 5 | — | `"synthesize"` | Steps 2–4 repeat across iterations; the server additionally reads `intakeConfidence` and `intakeIteration` from the audit projection to populate diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index 424115e..a952284 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -601,7 +601,12 @@ const KOAN_SHAPES: Record = { koan_complete_story: { keys: ["story_id"], highValue: true }, koan_retry_story: { keys: ["story_id", "failure_summary"], freeform: ["failure_summary"], highValue: true }, koan_skip_story: { keys: ["story_id", "reason"], freeform: ["reason"], highValue: true }, - koan_ask_question: { keys: ["questions"], arrays: ["questions"], highValue: true }, + koan_ask_question: { + keys: ["id", "question", "context", "options", "multi", "recommended"], + arrays: ["options"], + freeform: ["question", "context"], + highValue: true, + }, koan_request_scouts: { keys: [], highValue: true }, }; @@ -980,6 +985,3 @@ function formatLifecycleEvent(e: PhaseStartEvent | StepTransitionEvent | PhaseEn return { tool: "phase", summary: e.detail ? `${e.outcome} · ${e.detail}` : e.outcome, highValue: false, inFlight: false }; } } - -// formatToolInvocation is kept for callers outside buildChronologicalLog. -void formatToolInvocation; diff --git a/src/planner/lib/ipc-responder.ts b/src/planner/lib/ipc-responder.ts index 49ff0bd..7a7c6df 100644 --- a/src/planner/lib/ipc-responder.ts +++ b/src/planner/lib/ipc-responder.ts @@ -18,10 +18,7 @@ import { type AskIpcFile, type ScoutIpcFile, } from "./ipc.js"; -// ipc.ts exports ScoutTask (IPC-level: id/role/prompt for the LLM-facing request); -// task.ts also exports ScoutTask (manifest-level: role/epicDir/question/outputFile/investigatorRole). -// Aliased here to avoid shadowing the ipc.ts type used by ScoutIpcFile fields. -import type { ScoutTask as TaskScoutTask } from "./task.js"; +import type { ScoutTask } from "./task.js"; import { pool } from "./pool.js"; import { readProjection } from "./audit.js"; import { loadScoutConcurrency } from "../model-config.js"; @@ -49,7 +46,7 @@ export interface ScoutSpawnContext { // Used for UI attribution when registering scouts with the web server. parentRole: string; // Spawns a single scout; returns exit code. - spawnScout: (task: TaskScoutTask, scoutSubagentDir: string) => Promise; + spawnScout: (task: ScoutTask, scoutSubagentDir: string) => Promise; } // Handles a pending ask request: routes to web server, writes response. @@ -60,19 +57,20 @@ async function handleAskRequest( signal: AbortSignal, ): Promise { const { payload } = ipc; - const questions: AskQuestion[] = payload.questions.map((q) => ({ - id: q.id, - question: q.question, - options: q.options.map((o) => ({ label: o.label })), - multi: q.multi, - recommended: q.recommended, - })); - - // Append "Other" option to each question before presenting to the user. - const withOther: AskQuestion[] = questions.map((q) => ({ - ...q, - options: [...q.options, { label: OTHER_OPTION }], - })); + const question: AskQuestion = { + id: payload.id, + question: payload.question, + context: payload.context, + options: payload.options.map((o) => ({ label: o.label })), + multi: payload.multi, + recommended: payload.recommended, + }; + + // Append "Other" option before presenting to the user. + const withOther: AskQuestion = { + ...question, + options: [...question.options, { label: OTHER_OPTION }], + }; let result: AnswerResult; try { @@ -96,18 +94,15 @@ async function handleAskRequest( return; } - const answers: AskAnswerPayload["answers"] = result.answers.map((a) => { - const entry: AskAnswerPayload["answers"][number] = { - id: a.questionId, - selectedOptions: a.selectedOptions, - }; - if (a.customInput !== undefined) { - entry.customInput = a.customInput; - } - return entry; - }); + const answer: AskAnswerPayload = { + id: result.answer.questionId, + selectedOptions: result.answer.selectedOptions, + }; + if (result.answer.customInput !== undefined) { + answer.customInput = result.answer.customInput; + } - const response = createAskResponse(ipc.id, { answers }); + const response = createAskResponse(ipc.id, answer); // Re-read and validate before writing — idempotence guard against stale requests. const current = await readIpcFile(subagentDir); if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { @@ -166,7 +161,7 @@ async function handleScoutRequest( // Construct the task manifest for this scout. The IPC-level ipcTask carries // id/role/prompt (LLM-facing); the task manifest carries the full SubagentTask // fields the scout process needs. - const scoutTask: TaskScoutTask = { + const scoutTask: ScoutTask = { role: "scout", epicDir: scoutCtx.epicDir, question: entry.ipcTask.prompt, diff --git a/src/planner/lib/ipc.ts b/src/planner/lib/ipc.ts index 3d26828..25298ef 100644 --- a/src/planner/lib/ipc.ts +++ b/src/planner/lib/ipc.ts @@ -12,7 +12,8 @@ import * as crypto from "node:crypto"; // -- Scout types -- -export interface ScoutTask { +/** IPC-level scout request: id/role/prompt fields sent by the LLM-facing tool. */ +export interface ScoutRequest { id: string; // Unique task ID, e.g. "auth-libs" role: string; // Custom role description for the scout prompt: string; // What the scout should find @@ -26,21 +27,18 @@ export interface ScoutResponse { // -- Ask types -- export interface AskQuestionPayload { - questions: Array<{ - id: string; - question: string; - options: Array<{ label: string }>; - multi?: boolean; - recommended?: number; - }>; + id: string; + question: string; + context?: string; + options: Array<{ label: string }>; + multi?: boolean; + recommended?: number; } export interface AskAnswerPayload { - answers: Array<{ - id: string; - selectedOptions: string[]; - customInput?: string; - }>; + id: string; + selectedOptions: string[]; + customInput?: string; } export interface AskResponse { @@ -64,7 +62,7 @@ export interface ScoutIpcFile { type: "scout-request"; id: string; createdAt: string; - scouts: ScoutTask[]; + scouts: ScoutRequest[]; response: ScoutResponse | null; } @@ -129,7 +127,7 @@ export function createAskRequest(payload: AskQuestionPayload): AskIpcFile { }; } -export function createScoutRequest(scouts: ScoutTask[]): ScoutIpcFile { +export function createScoutRequest(scouts: ScoutRequest[]): ScoutIpcFile { return { type: "scout-request", id: crypto.randomUUID(), diff --git a/src/planner/lib/permissions.ts b/src/planner/lib/permissions.ts index 2a5bf6e..5a899aa 100644 --- a/src/planner/lib/permissions.ts +++ b/src/planner/lib/permissions.ts @@ -113,6 +113,15 @@ const STEP_1_BLOCKED_TOOLS = new Set([ "edit", ]); +// STEP_3_BLOCKED_TOOLS: tools disallowed during the intake Deliberate step (step 3). +// Confidence assessment belongs exclusively in the Reflect step (step 4). +// Allowing koan_set_confidence during Deliberate lets the LLM pre-commit to a +// confidence level before verification, anchoring the subsequent Reflect step +// toward premature "certain" declarations. +const STEP_3_BLOCKED_TOOLS = new Set([ + "koan_set_confidence", +]); + export function checkPermission( role: string, toolName: string, @@ -136,6 +145,16 @@ export function checkPermission( }; } + // Intake step 3 (Deliberate): block koan_set_confidence so the LLM cannot + // pre-commit to a confidence level before the Reflect step's verification. + if (role === "intake" && intakeStep === 3 && STEP_3_BLOCKED_TOOLS.has(toolName)) { + return { + allowed: false, + reason: `${toolName} is not available during the Deliberate step (step 3). ` + + "Confidence assessment belongs in the Reflect step (step 4).", + }; + } + // Unknown role: blocked under default-deny policy. if (!ROLE_PERMISSIONS.has(role)) { log("Unknown role blocked", { role, toolName }); diff --git a/src/planner/model-config.ts b/src/planner/model-config.ts index 248d727..403a7c5 100644 --- a/src/planner/model-config.ts +++ b/src/planner/model-config.ts @@ -7,7 +7,7 @@ import { promises as fs } from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; -import { ALL_MODEL_TIERS, isModelTier, type ModelTier } from "./model-phase.js"; +import { ALL_MODEL_TIERS, isModelTier, type ModelTier } from "./types.js"; import { createLogger } from "../utils/logger.js"; const log = createLogger("model-config"); diff --git a/src/planner/model-phase.ts b/src/planner/model-phase.ts deleted file mode 100644 index 0bd642c..0000000 --- a/src/planner/model-phase.ts +++ /dev/null @@ -1,14 +0,0 @@ -// Role-based model tier types for koan. -// Replaces the old 5×4 PhaseRow × SubPhase matrix with a 3-tier system. -// Tiers map deterministically from role via ROLE_MODEL_TIER in types.ts. - -import type { ModelTier } from "./types.js"; - -export type { ModelTier, SubagentRole } from "./types.js"; -export { ROLE_MODEL_TIER } from "./types.js"; - -export const ALL_MODEL_TIERS: readonly ModelTier[] = ["strong", "standard", "cheap"]; - -export function isModelTier(value: unknown): value is ModelTier { - return typeof value === "string" && ALL_MODEL_TIERS.includes(value as ModelTier); -} diff --git a/src/planner/model-resolver.ts b/src/planner/model-resolver.ts index bc4e530..ab3d656 100644 --- a/src/planner/model-resolver.ts +++ b/src/planner/model-resolver.ts @@ -3,7 +3,7 @@ // Returns undefined when no config exists so the caller omits --model, // preserving pi's current active model as the implicit fallback. -import { ROLE_MODEL_TIER, type SubagentRole } from "./model-phase.js"; +import { ROLE_MODEL_TIER, type SubagentRole } from "./types.js"; import { loadModelTierConfig } from "./model-config.js"; export async function resolveModelForRole(role: SubagentRole): Promise { diff --git a/src/planner/phases/intake/prompts.ts b/src/planner/phases/intake/prompts.ts index de1525e..7c59c20 100644 --- a/src/planner/phases/intake/prompts.ts +++ b/src/planner/phases/intake/prompts.ts @@ -34,6 +34,8 @@ export function intakeSystemPrompt(): string { Your output — a single context.md file — is the sole foundation for all downstream work. Every story boundary, every implementation plan, and every line of code written downstream depends on the quality and completeness of this file. Gaps here compound into wrong plans and wrong code. +An assumption you make without verifying will become a fact the decomposer treats as decided. A question you don't ask is an answer you're making up. When the executor writes the wrong code because context.md contained an unchecked assumption, that failure traces back to this phase. + ## Your role You extract, verify, and organize information. You do NOT plan, design, or implement. @@ -176,27 +178,43 @@ export function intakeStepGuidance(step: number, conversationPath?: string, iter ? "Cover every area relevant to the task. Be thorough — gaps you miss here become gaps in the final output." : "Focus on areas where new information arrived since last round. Re-state updated understanding.", "", + "## Phase A.5: Downstream impact assessment", + "", + "For each 'Unknown' item from Phase A, briefly assess:", + "- If you assume wrong about this, what happens to downstream planning?", + "- Could a wrong assumption split a story that should be one, or merge two that should be separate?", + "- Would the executor hit a surprise that requires re-planning?", + "", + "This is the only phase where the user can be consulted. After intake, all", + "downstream phases work from context.md alone. Anything you get wrong here", + "will silently propagate through decomposition, planning, and execution.", + "", + "Mark each unknown as:", + "- **ASK**: user input needed — this affects scope, boundaries, or sequencing.", + "- **SCOUT**: a follow-up scout can resolve this factually.", + "- **SAFE**: genuinely an implementation detail with no scope impact.", + "", "## Phase B: Formulate and ask questions", "", - "Review your 'Unknown' items. For each, decide:", - "- Can a follow-up scout answer this? → Note it for the next scout round.", - "- Must the user decide this? → Include it in your questions.", - "- Is this an implementation detail the planner should decide? → Skip it.", + "For each 'Unknown' item, ask yourself: if I get this wrong, does it affect", + "the decomposer's ability to define correct story boundaries? If yes or maybe — ask.", "", - "Ask about a gap ONLY if:", - "- It materially changes WHAT is built (scope, features, API shape).", - "- It materially changes HOW work is sequenced (dependencies, ordering).", - "- Without the answer, story boundaries cannot be determined.", - "- Scout findings contradict what the user described.", + "The user is your collaborator, not an interruption. Questions are how you verify", + "your understanding against reality. The decomposer cannot ask questions later —", + "this is the only chance to get clarification.", "", - "Use `koan_ask_question`. Limit: 5 questions per round.", + "Default: ask. You may skip a question ONLY if ALL of these are true:", + "- It is purely an implementation detail (HOW to code something, not WHAT to build).", + "- Getting it wrong would not change any story boundary.", + "- It cannot be misinterpreted — there is exactly one reasonable interpretation.", + "", + "Use `koan_ask_question` (one question per call). Limit: 5 questions per round.", "Prefer multiple-choice when the answer space is bounded.", + "Include the optional context field when background is needed for an informed decision.", "Ground questions in specific findings: 'Scout found X — should this story follow the same pattern?'", "", - "## If no questions are needed", - "", - "If all 'Unknown' items are either implementation details or answerable by follow-up scouts,", - "you may skip asking questions. Your recitation of knowns/unknowns is still required.", + "When in doubt, check with the user. It is always better to confirm an assumption", + "than to let a wrong assumption propagate through planning and execution.", ], }; @@ -222,6 +240,16 @@ export function intakeStepGuidance(step: number, conversationPath?: string, iter "Verify the completeness of your understanding before deciding whether to continue or stop.", "This step is pure verification — do not scout or ask questions here.", "", + "## Iteration expectations", + "", + "Round 1 is for initial exploration. It is rare that a single round of scouting", + "produces enough certainty to proceed. Expect 2–3 rounds for typical tasks.", + "", + "If this is round 1 and you have not asked any questions, your confidence should", + "be at most \"high\" — reserve \"certain\" for when you have verified your", + "understanding through at least one exchange with the user or a targeted", + "follow-up scout round.", + "", "## Step 1: Verification questions", "", "Generate 3–5 questions that test whether your understanding is complete.", @@ -257,11 +285,18 @@ export function intakeStepGuidance(step: number, conversationPath?: string, iter "- All user decisions affecting story boundaries have been made.", "- No question you could ask would change the number, order, or scope of stories.", "", - "### You are NOT certain if:", - "- A scout revealed something surprising that needs follow-up.", - "- A user answer raised a new question you haven't explored.", - "- You skipped scouting an area that might affect story boundaries.", - "- You're unsure whether two pieces of work should be one story or two.", + "### You are NOT certain if ANY of these are true:", + "- You have not asked the user any questions in this or any previous round.", + "- A scout revealed something you did not expect from reading the conversation.", + "- You classified an unknown as \"implementation detail\" but it could affect story scope or boundaries.", + "- You skipped scouting an area mentioned or implied by the conversation.", + "- You are unsure whether two pieces of work should be one story or two.", + "- You assumed a design decision the user did not explicitly state.", + "- You could not answer a verification question with a direct quote from the conversation, a scout finding, or a user answer.", + "", + "The first condition is critical: if you have never asked the user a single", + "question, you cannot be certain. Conversations are ambiguous. Your", + "interpretation may be wrong. Confirm it.", "", "## Step 4: If not certain, plan the next round", "", diff --git a/src/planner/tools/ask.ts b/src/planner/tools/ask.ts index c567549..d2ce9bd 100644 --- a/src/planner/tools/ask.ts +++ b/src/planner/tools/ask.ts @@ -2,7 +2,7 @@ // Both tools use file-based IPC to pause subagent execution and communicate // with the parent session, then resume with the response. // -// koan_ask_question — ask the user a question, get answers +// koan_ask_question — ask the user a question, get an answer // koan_request_scouts — request parallel codebase scouts, get findings paths import { promises as fs } from "node:fs"; @@ -20,7 +20,7 @@ import { createAskRequest, createScoutRequest, type AskAnswerPayload, - type ScoutTask, + type ScoutRequest, } from "../lib/ipc.js"; // -- Schemas -- @@ -29,23 +29,20 @@ const OptionItemSchema = Type.Object({ label: Type.String({ description: "Display label" }), }); -const QuestionItemSchema = Type.Object({ +const AskParamsSchema = Type.Object({ id: Type.String({ description: "Question id (e.g. auth, cache, priority)" }), question: Type.String({ description: "Question text" }), + context: Type.Optional(Type.String({ description: "Optional background/context to help the user answer." })), options: Type.Array(OptionItemSchema, { description: "Available options. Do not include 'Other'.", minItems: 1, }), multi: Type.Optional(Type.Boolean({ description: "Allow multi-select" })), recommended: Type.Optional( - Type.Number({ description: "0-indexed recommended option. '(Recommended)' is shown automatically." }), + Type.Number({ description: "0-indexed recommended option." }), ), }); -const AskParamsSchema = Type.Object({ - questions: Type.Array(QuestionItemSchema, { description: "Questions to ask", minItems: 1 }), -}); - type AskParams = Static; const ScoutTaskSchema = Type.Object({ @@ -62,16 +59,17 @@ type RequestScoutsParams = Static; // -- Result formatting (ask) -- -interface QuestionResult { +interface AskResult { id: string; question: string; + context?: string; options: string[]; multi: boolean; selectedOptions: string[]; customInput?: string; } -function formatSelectionForSummary(result: QuestionResult): string { +function formatSelectionForSummary(result: AskResult): string { const hasSelectedOptions = result.selectedOptions.length > 0; const hasCustomInput = Boolean(result.customInput); @@ -89,14 +87,24 @@ function formatSelectionForSummary(result: QuestionResult): string { return result.selectedOptions[0] ?? "(no selection)"; } -function formatQuestionContext(result: QuestionResult, index: number): string { +function formatQuestionContext(result: AskResult): string { const lines: string[] = [ - `Question ${index + 1} (${result.id})`, + `Question (${result.id})`, `Prompt: ${result.question}`, + ]; + + if (result.context?.trim()) { + lines.push("Context:"); + for (const paragraph of result.context.trim().split(/\n\s*\n/u)) { + lines.push(` ${paragraph}`); + } + } + + lines.push( "Options:", ...result.options.map((o, i) => ` ${i + 1}. ${o}`), "Response:", - ]; + ); const hasSelectedOptions = result.selectedOptions.length > 0; const hasCustomInput = Boolean(result.customInput); @@ -121,27 +129,26 @@ function formatQuestionContext(result: QuestionResult, index: number): string { return lines.join("\n"); } -function buildSessionContent(results: QuestionResult[]): string { - const summaryLines = results.map((r) => `${r.id}: ${formatSelectionForSummary(r)}`).join("\n"); - const contextBlocks = results.map((r, i) => formatQuestionContext(r, i)).join("\n\n"); - return `User answers:\n${summaryLines}\n\nAnswer context:\n${contextBlocks}`; +function buildSessionContent(result: AskResult): string { + return `User answer:\n${result.id}: ${formatSelectionForSummary(result)}\n\nAnswer context:\n${formatQuestionContext(result)}`; } -function buildQuestionResults( +function buildQuestionResult( params: AskParams, - answers: AskAnswerPayload["answers"], -): QuestionResult[] { - return params.questions.map((q) => { - const answer = answers.find((a) => a.id === q.id) ?? { id: q.id, selectedOptions: [] }; - return { - id: q.id, - question: q.question, - options: q.options.map((o) => o.label), - multi: q.multi ?? false, - selectedOptions: answer.selectedOptions, - customInput: answer.customInput, - }; - }); + answer: AskAnswerPayload | null, +): AskResult { + const selectedOptions = answer?.id === params.id ? answer.selectedOptions : []; + const customInput = answer?.id === params.id ? answer.customInput : undefined; + + return { + id: params.id, + question: params.question, + context: params.context, + options: params.options.map((o) => o.label), + multi: params.multi ?? false, + selectedOptions, + customInput, + }; } // -- Shared poll helper -- @@ -155,11 +162,11 @@ function sleep(ms: number): Promise { const ASK_TOOL_DESCRIPTION = ` Ask the user for clarification when a choice materially affects the outcome. -- Use when multiple valid approaches have different trade-offs. +- Ask exactly one question per call. - Prefer 2-5 concise options. - Use multi=true when multiple answers are valid. - Use recommended= (0-indexed) to mark the default option. -- You can ask multiple related questions in one call using questions[]. +- Optionally include context to give enough background for an informed answer. - Do NOT include an 'Other' option; UI adds it automatically. `.trim(); @@ -239,9 +246,9 @@ export function registerAskTools(pi: ExtensionAPI, ctx: RuntimeContext): void { switch (pollResult) { case "answered": { - const results = buildQuestionResults(askParams, answeredPayload?.answers ?? []); + const result = buildQuestionResult(askParams, answeredPayload); return { - content: [{ type: "text" as const, text: buildSessionContent(results) }], + content: [{ type: "text" as const, text: buildSessionContent(result) }], details: undefined, }; } @@ -290,7 +297,7 @@ export function registerAskTools(pi: ExtensionAPI, ctx: RuntimeContext): void { }; } - const ipc = createScoutRequest(scouts as ScoutTask[]); + const ipc = createScoutRequest(scouts as ScoutRequest[]); await writeIpcFile(dir, ipc); let aborted = false; diff --git a/src/planner/tools/workflow.ts b/src/planner/tools/workflow.ts index cff27d9..1d4ddfa 100644 --- a/src/planner/tools/workflow.ts +++ b/src/planner/tools/workflow.ts @@ -18,7 +18,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { createLogger } from "../../utils/logger.js"; import type { RuntimeContext } from "../lib/runtime-context.js"; -const log = createLogger("Dispatch"); +const log = createLogger("Workflow"); // Registers workflow tools. Called once at init in koan.ts, // before pi's _buildRuntime() snapshot. Tool execute callbacks read diff --git a/src/planner/types.ts b/src/planner/types.ts index c2c0a5a..b92d0ab 100644 --- a/src/planner/types.ts +++ b/src/planner/types.ts @@ -51,3 +51,10 @@ export type StoryStatus = // Epic lifecycle phases (driver-managed, not LLM-visible directly). // Note: "scouting" is intentionally absent — scouts run within other phases via IPC. export type EpicPhase = "intake" | "decomposition" | "review" | "executing" | "completed"; + +// All model tiers as a runtime-iterable array. +export const ALL_MODEL_TIERS: readonly ModelTier[] = ["strong", "standard", "cheap"]; + +export function isModelTier(value: unknown): value is ModelTier { + return typeof value === "string" && ALL_MODEL_TIERS.includes(value as ModelTier); +} diff --git a/src/planner/ui/config/menu.ts b/src/planner/ui/config/menu.ts index e50f517..f297c3c 100644 --- a/src/planner/ui/config/menu.ts +++ b/src/planner/ui/config/menu.ts @@ -6,7 +6,7 @@ import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent"; import { getSettingsListTheme } from "@mariozechner/pi-coding-agent"; import { type SettingItem, SettingsList } from "@mariozechner/pi-tui"; -import { ALL_MODEL_TIERS, type ModelTier } from "../../model-phase.js"; +import { ALL_MODEL_TIERS, type ModelTier } from "../../types.js"; import { loadModelTierConfig } from "../../model-config.js"; import type { ModelTierConfig } from "../../model-config.js"; import { createModelSelectionComponent } from "./model-selection.js"; diff --git a/src/planner/ui/config/model-selection.ts b/src/planner/ui/config/model-selection.ts index ee2a695..c612f83 100644 --- a/src/planner/ui/config/model-selection.ts +++ b/src/planner/ui/config/model-selection.ts @@ -14,7 +14,7 @@ import { visibleWidth, } from "@mariozechner/pi-tui"; -import { ALL_MODEL_TIERS, type ModelTier } from "../../model-phase.js"; +import { ALL_MODEL_TIERS, type ModelTier } from "../../types.js"; import { saveModelTierConfig } from "../../model-config.js"; import type { ModelTierConfig } from "../../model-config.js"; diff --git a/src/planner/web/css/components.css b/src/planner/web/css/components.css index a112b3f..8d287f2 100644 --- a/src/planner/web/css/components.css +++ b/src/planner/web/css/components.css @@ -200,6 +200,23 @@ margin-bottom: var(--gap-sm); } +.question-context { + font-family: var(--font-sans); + font-size: var(--font-size-md); + color: var(--text-muted); + line-height: 1.6; + margin-bottom: var(--gap-md); +} + +.question-context p { + margin: 0 0 var(--gap-sm) 0; + white-space: pre-wrap; +} + +.question-context p:last-child { + margin-bottom: 0; +} + .question-text { font-family: var(--font-sans); font-size: 18px; diff --git a/src/planner/web/js/components/forms/QuestionCard.jsx b/src/planner/web/js/components/forms/QuestionCard.jsx index 97a92af..18e5550 100644 --- a/src/planner/web/js/components/forms/QuestionCard.jsx +++ b/src/planner/web/js/components/forms/QuestionCard.jsx @@ -1,12 +1,17 @@ import { useState } from 'preact/hooks' -export function QuestionCard({ question, index, total, onSelect }) { +export function QuestionCard({ question, onSelect }) { const [selectedIndexes, setSelectedIndexes] = useState(() => new Set()) const [otherInput, setOtherInput] = useState('') const options = question.options || [] const allOptions = options.map(o => o.label) const otherIndex = allOptions.findIndex(l => l === 'Other (type your own)') + const contextParagraphs = (question.context || '') + .trim() + .split(/\n\s*\n/g) + .map(p => p.trim()) + .filter(Boolean) function buildSelection(indexes, otherVal) { if (question.multi) { @@ -56,8 +61,15 @@ export function QuestionCard({ question, index, total, onSelect }) { return (
-
{index + 1}/{total} · {question.id}
+
{question.id}
{question.multi &&
select all that apply
} + + {contextParagraphs.length > 0 && ( +
+ {contextParagraphs.map((p, i) =>

{p}

)} +
+ )} +
{question.question}
{allOptions.map((label, i) => { diff --git a/src/planner/web/js/components/forms/QuestionForm.jsx b/src/planner/web/js/components/forms/QuestionForm.jsx index b019463..a2898eb 100644 --- a/src/planner/web/js/components/forms/QuestionForm.jsx +++ b/src/planner/web/js/components/forms/QuestionForm.jsx @@ -4,56 +4,42 @@ import { submitAnswers } from '../../lib/api.js' import { QuestionCard } from './QuestionCard.jsx' export function QuestionForm({ token }) { - const { requestId, payload: questions } = useStore(s => s.pendingInput) - const [selections, setSelections] = useState(() => new Array(questions.length).fill(null)) - - const allAnswered = selections.every(s => s !== null && (s.selectedOptions?.length > 0 || s.customInput)) - const answeredCount = selections.filter(s => s !== null && (s.selectedOptions?.length > 0 || s.customInput)).length - - function updateSelection(index, selection) { - setSelections(prev => { - const next = [...prev] - next[index] = selection - return next - }) - } - - function acceptDefaults() { - const answers = questions.map((q) => { - const idx = q.recommended ?? 0 - const label = q.options[idx]?.label - return { questionId: q.id, selectedOptions: label ? [label] : [] } - }) - submitAnswers({ token, requestId, answers }) + const { requestId, payload: question } = useStore(s => s.pendingInput) + const [selection, setSelection] = useState(null) + + const answered = selection !== null && (selection.selectedOptions?.length > 0 || selection.customInput) + + function acceptDefault() { + const idx = question.recommended ?? 0 + const label = question.options[idx]?.label + const answer = { + questionId: question.id, + selectedOptions: label ? [label] : [], + } + submitAnswers({ token, requestId, answer }) } function submit() { - const answers = questions.map((q, i) => ({ - questionId: q.id, - ...(selections[i] || { selectedOptions: [] }), - })) - submitAnswers({ token, requestId, answers }) + const answer = { + questionId: question.id, + ...(selection || { selectedOptions: [] }), + } + submitAnswers({ token, requestId, answer }) } return (
-

A few questions to shape the plan

-
{answeredCount} of {questions.length} answered
+

A question to shape the plan

- {questions.map((q, i) => ( - updateSelection(i, sel)} - /> - ))} +
- - - {!allAnswered && {questions.length - answeredCount} remaining} + + + {!answered && Choose an option or provide custom input}
) diff --git a/src/planner/web/js/lib/api.js b/src/planner/web/js/lib/api.js index 1f98da0..639c76d 100644 --- a/src/planner/web/js/lib/api.js +++ b/src/planner/web/js/lib/api.js @@ -1,27 +1,35 @@ import { useStore } from '../store.js' -export async function submitAnswers({ token, requestId, answers }) { - const resp = await fetch('/api/answer', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ token, requestId, answers }), - }) - if (resp.ok) { - useStore.setState({ pendingInput: null }) - } else { - console.error('Failed to submit answers:', await resp.text()) +export async function submitAnswers({ token, requestId, answer }) { + try { + const resp = await fetch('/api/answer', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ token, requestId, answer }), + }) + if (resp.ok) { + useStore.setState({ pendingInput: null }) + } else { + console.error('Failed to submit answers:', await resp.text()) + } + } catch (err) { + console.error('Failed to submit answers:', err) } } export async function submitReview({ token, requestId, approved, skipped }) { - const resp = await fetch('/api/review', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ token, requestId, approved, skipped }), - }) - if (resp.ok) { - useStore.setState({ pendingInput: null }) - } else { - console.error('Failed to submit review:', await resp.text()) + try { + const resp = await fetch('/api/review', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ token, requestId, approved, skipped }), + }) + if (resp.ok) { + useStore.setState({ pendingInput: null }) + } else { + console.error('Failed to submit review:', await resp.text()) + } + } catch (err) { + console.error('Failed to submit review:', err) } } diff --git a/src/planner/web/js/sse.js b/src/planner/web/js/sse.js index 68908f5..036cc5d 100644 --- a/src/planner/web/js/sse.js +++ b/src/planner/web/js/sse.js @@ -23,7 +23,7 @@ export function connectSSE(token) { pipelineEnd: d, intakeProgress: null, })), - ask: (d) => set({ pendingInput: { type: 'ask', requestId: d.requestId, payload: d.questions } }), + ask: (d) => set({ pendingInput: { type: 'ask', requestId: d.requestId, payload: d.question } }), review: (d) => set({ pendingInput: { type: 'review', requestId: d.requestId, payload: d.stories } }), 'model-config': (d) => set(s => ({ pendingInput: { type: 'model-config', requestId: d.requestId, payload: { ...d.tiers, scoutConcurrency: d.scoutConcurrency } }, diff --git a/src/planner/web/server-types.ts b/src/planner/web/server-types.ts index 23aacbb..21971f3 100644 --- a/src/planner/web/server-types.ts +++ b/src/planner/web/server-types.ts @@ -20,6 +20,7 @@ export interface AskOption { export interface AskQuestion { id: string; question: string; + context?: string; options: AskOption[]; multi?: boolean; recommended?: number; @@ -108,7 +109,7 @@ export type AnswerElement = AskSelection & { questionId: string }; export interface AnswerResult { cancelled: boolean; - answers: AnswerElement[]; + answer: AnswerElement; } // --------------------------------------------------------------------------- @@ -155,7 +156,7 @@ export interface NotificationEvent { export interface AskEvent { requestId: string; - questions: AskQuestion[]; + question: AskQuestion; } export interface ReviewEvent { @@ -257,7 +258,7 @@ export interface WebServerHandle { // Blocking input methods requestReview(stories: ReviewStory[], signal?: AbortSignal): Promise; - requestAnswer(questions: AskQuestion[], signal: AbortSignal): Promise; + requestAnswer(question: AskQuestion, signal: AbortSignal): Promise; requestModelConfig(): Promise; // Lifecycle diff --git a/src/planner/web/server.ts b/src/planner/web/server.ts index 4943f75..1c522d4 100644 --- a/src/planner/web/server.ts +++ b/src/planner/web/server.ts @@ -311,7 +311,7 @@ export async function startWebServer(epicDir: string): Promise for (const [requestId, entry] of pendingInputs) { if (entry.type === "ask") { - write("ask", { requestId, questions: entry.payload }); + write("ask", { requestId, question: entry.payload }); } else if (entry.type === "review") { write("review", { requestId, stories: entry.payload }); } else if (entry.type === "model-config") { @@ -559,18 +559,37 @@ export async function startWebServer(epicDir: string): Promise if (method === "POST" && pathname === "/api/answer") { const body = await readBody(req).catch(() => null); - const b = body as { token?: string; requestId?: string; answers?: unknown[] } | null; + const b = body as { token?: string; requestId?: string; answer?: unknown } | null; if (!b) { sendJson(res, 400, { ok: false, error: "Invalid body" }); return; } if (b.token !== sessionToken) { sendJson(res, 403, { ok: false, error: "Invalid token" }); return; } - const { requestId, answers } = b; - if (!requestId || !Array.isArray(answers)) { - sendJson(res, 400, { ok: false, error: "Missing requestId or answers" }); return; + const { requestId, answer } = b; + if (!requestId || !answer || typeof answer !== "object") { + sendJson(res, 400, { ok: false, error: "Missing requestId or answer" }); return; } + const parsed = answer as { + questionId?: unknown; + selectedOptions?: unknown; + customInput?: unknown; + }; + if ( + typeof parsed.questionId !== "string" || + !Array.isArray(parsed.selectedOptions) || + parsed.selectedOptions.some((s) => typeof s !== "string") || + (parsed.customInput !== undefined && typeof parsed.customInput !== "string") + ) { + sendJson(res, 400, { ok: false, error: "Invalid answer payload" }); return; + } + const pending = pendingInputs.get(requestId); if (!pending || pending.type !== "ask") { sendJson(res, 409, { ok: false, error: "No pending ask with this requestId" }); return; } - const result: AnswerResult = { cancelled: false, answers: answers as AnswerElement[] }; + const normalizedAnswer: AnswerElement = { + questionId: parsed.questionId, + selectedOptions: parsed.selectedOptions, + ...(parsed.customInput !== undefined ? { customInput: parsed.customInput } : {}), + }; + const result: AnswerResult = { cancelled: false, answer: normalizedAnswer }; pending.resolve(result); pendingInputs.delete(requestId); sendJson(res, 200, { ok: true }); @@ -776,7 +795,7 @@ export async function startWebServer(epicDir: string): Promise }); }, - requestAnswer(questions: AskQuestion[], signal: AbortSignal): Promise { + requestAnswer(question: AskQuestion, signal: AbortSignal): Promise { return new Promise((res, rej) => { const requestId = randomUUID(); const abortHandler = () => { @@ -796,9 +815,9 @@ export async function startWebServer(epicDir: string): Promise signal.removeEventListener("abort", abortHandler); rej(err); }, - payload: questions, + payload: question, }); - pushEvent("ask", { requestId, questions }); + pushEvent("ask", { requestId, question }); if (signal.aborted) { abortHandler(); } else { From 1e041f222a0994e202d5fdbf88d1257535cfbf14 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Sat, 21 Mar 2026 13:41:33 +0700 Subject: [PATCH 078/412] T2 implement (8 files) --- docs/architecture.md | 100 ++++++--- docs/subagents.md | 12 +- extensions/koan.ts | 21 +- src/planner/tools/ask.ts | 345 ++++++++++++++++-------------- src/planner/tools/orchestrator.ts | 202 +++++++++-------- src/planner/tools/workflow.ts | 30 ++- src/planner/web/js/sse.js | 81 +++---- src/planner/web/js/store.js | 106 ++++++++- 8 files changed, 558 insertions(+), 339 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 55cf4eb..2f2e406 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -48,7 +48,7 @@ call, the process exits — there is no stdin to recover. The entire workflow depends on the LLM calling `koan_complete_step` reliably. **The first thing any subagent does is call `koan_complete_step`.** The spawn -prompt contains *only* this directive. The tool returns step 1 instructions. +prompt contains _only_ this directive. The tool returns step 1 instructions. This establishes the calling pattern before the LLM sees complex instructions. ``` @@ -62,11 +62,11 @@ Tool returns: Step 2 instructions (or "Phase complete.") Three reinforcement mechanisms make this robust across model capability levels: -| Mechanism | Where | Why | -|-----------|-------|-----| -| **Primacy** | Boot prompt is the LLM's very first message | First action = tool call, at the top of conversation history | -| **Recency** | `formatStep()` appends "WHEN DONE: Call koan_complete_step..." last | LLMs weight end-of-context instructions heavily | -| **Muscle memory** | By step 2+ the LLM has called the tool N times | Pattern is locked in through repetition | +| Mechanism | Where | Why | +| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------------------ | +| **Primacy** | Boot prompt is the LLM's very first message | First action = tool call, at the top of conversation history | +| **Recency** | `formatStep()` appends "WHEN DONE: Call koan_complete_step..." last | LLMs weight end-of-context instructions heavily | +| **Muscle memory** | By step 2+ the LLM has called the tool N times | Pattern is locked in through repetition | ### 3. Driver determinism @@ -75,6 +75,7 @@ files and exit codes, applies routing rules, and spawns the next subagent. It never makes judgment calls, parses free-text output, or adapts to LLM behavior. **Routing priority** in the story loop: + 1. `retry` status → re-execute (retry takes precedence over new work) 2. `selected` status → plan + execute 3. All stories `done` or `skipped` → epic complete @@ -115,11 +116,11 @@ observable state — lives in well-known files inside that directory. Three JSON files, three lifecycles: -| File | Writer | Reader | Lifecycle | -|------|--------|--------|-----------| -| **`task.json`** | Parent (before spawn) | Child (once, at startup) | Write-once, never modified | -| **`state.json`** | Child (continuously) | Parent (polling) | Eagerly materialized audit projection | -| **`ipc.json`** | Both (request/response) | Both (polling) | Temporary — created per request, deleted after response | +| File | Writer | Reader | Lifecycle | +| ---------------- | ----------------------- | ------------------------ | ------------------------------------------------------- | +| **`task.json`** | Parent (before spawn) | Child (once, at startup) | Write-once, never modified | +| **`state.json`** | Child (continuously) | Parent (polling) | Eagerly materialized audit projection | +| **`ipc.json`** | Both (request/response) | Both (polling) | Temporary — created per request, deleted after response | The spawn command carries only the directory path. The child reads `task.json` to discover its role, epic context, and task-specific parameters. No @@ -159,7 +160,6 @@ This is not optional — the IPC responder, web server, and audit system all poll files concurrently. A partial read of `ipc.json` or `state.json` would cause silent data corruption or spurious errors. - --- ## Tool Registration Constraint @@ -228,18 +228,20 @@ All layers must be wired for a new event type to be visible end-to-end. ``` [LLM calls tool] - ↓ -[tool mutates ctx + calls ctx.eventLog.emit*()] ← lib/audit.ts - ↓ -[fold() updates Projection → state.json written atomically] - ↓ -[web server polls state.json every 50ms, detects change] ← web/server.ts - ↓ -[pushEvent(type, payload) → SSE stream → browser] - ↓ -[sse.js addEventListener(type, handler) → useStore.setState()] ← web/js/sse.js - ↓ -[Zustand component selector → React re-render] ← web/js/store.js + | +[tool mutates ctx + calls ctx.eventLog.emit*()] <- lib/audit.ts + | +[fold() updates Projection -> state.json written atomically] + | +[web server polls state.json every 50ms, detects change] <- web/server.ts + | +[pushEvent(type, payload) -> SSE stream -> browser] + | +[sse.js dispatches to named handler from store.js] <- web/js/sse.js + | +[named handler calls useStore.setState()] <- web/js/store.js + | +[Zustand component selector -> React re-render] ``` ### Concrete example: `koan_set_confidence` @@ -264,6 +266,18 @@ browser receives "intake-progress" event → confidence visualization component re-renders ``` +### `sse.js` / `store.js` boundary + +`sse.js` connects to the SSE stream and routes each event type to a named +handler. It does not import `useStore` or know the store's internal shape. + +`store.js` owns the Zustand store shape and exports named handler functions +(one per SSE event type). Each handler maps a raw SSE payload to a store +state update. + +Changing the store shape only requires updating `store.js`; `sse.js` is +stable across store shape changes. + ### Replay on reconnect The web server buffers the last value of every stateful SSE event type. On @@ -271,7 +285,6 @@ reconnect, `replayState()` writes all buffered events to the new client. This ensures the browser always has current state after a network drop, without requiring a full page reload. - --- ## Pitfalls @@ -312,6 +325,33 @@ Scout success is derived from the JSON projection (`readProjection()` → A scout can write a partial findings file and then crash — file existence is not proof of completion. +### Don't crash on recoverable model-output parse errors + +Fail-fast is scoped to **unrecoverable conditions**: + +- invariant/contract violations (e.g., broken `task.json` bootstrap contract) +- unexpected states where there is no safe deterministic next action +- failures with no simple local recovery path + +If a model emits malformed tool-call payloads (invalid JSON/args) or other +per-turn formatting errors, treat them as recoverable execution errors: +return a structured tool error (`tool_result` with `isError=true`) so the model +can self-correct and retry in the same subagent process. + +Contrastive examples: + +| Condition | Classification | Expected handling | +| --------- | -------------- | ----------------- | +| Malformed tool-call JSON/args from LLM | Recoverable | Return `tool_result` error (`isError=true`), keep process alive | +| Tool argument schema validation failure | Recoverable | Return validation error as `tool_result`, let model retry | +| Disallowed/unknown tool call | Recoverable | Return blocked tool error, continue turn | +| Missing/malformed `task.json` at subagent startup | Unrecoverable | Fail fast (bootstrap contract broken) | +| Impossible phase routing / internal invariant breach | Unrecoverable | Fail fast | +| Unexpected runtime state with no clear deterministic recovery | Unrecoverable | Fail fast | + +Crashing the process for recoverable model-output errors converts a local retry +loop into a pipeline-level failure and should be avoided. + ### Don't write state.json from outside state.ts / tool code The state module (`epic/state.ts`) and orchestrator tools are the only @@ -346,11 +386,11 @@ Neither alone is sufficient.** Three enforcement mechanisms are available — use the appropriate one for the constraint: -| Mechanism | What it enforces | How | -|-----------|-----------------|-----| -| **Permission fence** (`checkPermission`) | Which tools a role (or step) can use | Block at `tool_call` event; LLM sees a rejection message | -| **`validateStepCompletion()`** | Required pre-calls before step advancement | Block `koan_complete_step`; LLM sees an error and must comply | -| **Tool description** | Soft guidance on when to call | Cannot be enforced; LLM can ignore it | +| Mechanism | What it enforces | How | +| ---------------------------------------- | ------------------------------------------ | ------------------------------------------------------------- | +| **Permission fence** (`checkPermission`) | Which tools a role (or step) can use | Block at `tool_call` event; LLM sees a rejection message | +| **`validateStepCompletion()`** | Required pre-calls before step advancement | Block `koan_complete_step`; LLM sees an error and must comply | +| **Tool description** | Soft guidance on when to call | Cannot be enforced; LLM can ignore it | Any behavioral constraint that matters for correctness needs **both** a prompt instruction (so the LLM knows what to do) and a mechanical gate (so diff --git a/docs/subagents.md b/docs/subagents.md index 87e069a..a3317d7 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -160,7 +160,7 @@ One sentence. No task content. The role name is included for primacy — it anchors the LLM's identity before it receives any instructions. Task-specific parameters live in `task.json` and flow into step guidance via the phase class. -### Fail-fast guards +### Fail-fast guards (bootstrap invariants only) `dispatchPhase` validates required `task.json` fields before instantiating: @@ -170,6 +170,16 @@ parameters live in `task.json` and flow into step guidance via the phase class. | planner | `storyId` | Malformed paths like `stories//plan/plan.md` | | executor | `storyId` | Same path issue | +These checks are intentionally fail-fast because they indicate a broken +parent→child contract (programming/configuration error), not model behavior. + +**Boundary:** fail-fast is for unrecoverable conditions only (invariant or +contract violations, unexpected states, or cases with no simple deterministic +local recovery path). Recoverable model-output errors (for example malformed +tool-call JSON/args or schema validation failures) should be surfaced as +normal tool errors (`tool_result` with `isError=true`) so the LLM can retry +in-process, rather than terminating the subagent process. + --- ## Step-First Workflow (BasePhase) diff --git a/extensions/koan.ts b/extensions/koan.ts index c5c6cae..33da64b 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -34,6 +34,20 @@ function currentModelId(ctx: ExtensionContext): string | null { return `${model.provider}/${model.id}`; } +// Registers infrastructure-level event handlers that must be in place before +// before_agent_start fires. Currently this is only the truncation override, +// but the wrapper makes the ordering constraint visible at the call site. +// +// Why before before_agent_start? The audit tool_result handler registers +// inside before_agent_start. The truncation override must precede it so the +// audit handler sees the original event, not the replacement content we +// return. Calling this function immediately after registerAllTools (and +// before the dispatched guard) makes the ordering structural rather than +// relying on a comment buried inside registerTruncationOverride's impl. +function registerInfrastructureHandlers(pi: ExtensionAPI): void { + registerTruncationOverride(pi); +} + export default function koan(pi: ExtensionAPI): void { const log = createLogger("Koan"); @@ -49,12 +63,7 @@ export default function koan(pi: ExtensionAPI): void { const ctx = createRuntimeContext(); registerAllTools(pi, ctx); - // Registered unconditionally — applies in both parent and subagent mode. - // Self-guards: no-op when bash output fits within pi's default limits. - // Must precede before_agent_start so the audit tool_result handler (which - // registers later, inside before_agent_start) sees the original event and - // does not interfere with the replacement content we return. - registerTruncationOverride(pi); + registerInfrastructureHandlers(pi); // Dispatch happens exactly once per session (guard prevents re-entry on // subsequent before_agent_start calls, which pi may emit on reconnect). diff --git a/src/planner/tools/ask.ts b/src/planner/tools/ask.ts index d2ce9bd..9039142 100644 --- a/src/planner/tools/ask.ts +++ b/src/planner/tools/ask.ts @@ -182,191 +182,210 @@ Scouts run in parallel. The tool returns the file paths to read. - prompt: what to find (e.g., "Find all authentication middleware in src/") `.trim(); -export function registerAskTools(pi: ExtensionAPI, ctx: RuntimeContext): void { - // -- koan_ask_question -- +// -- Extracted execute logic -- - pi.registerTool({ - name: "koan_ask_question", - label: "Ask question", - description: ASK_TOOL_DESCRIPTION, - parameters: AskParamsSchema, +type ToolResult = { content: Array<{ type: "text"; text: string }>; details: undefined }; - async execute(_toolCallId, params, signal) { - const askParams = params as AskParams; - const dir = ctx.subagentDir; - - if (!dir) { - return { - content: [{ type: "text" as const, text: "Error: koan_ask_question is only available in subagent context." }], - details: undefined, - }; - } +export async function executeAskQuestion( + params: AskParams, + subagentDir: string | null, + signal?: AbortSignal | null, +): Promise { + const dir = subagentDir; + + if (!dir) { + return { + content: [{ type: "text" as const, text: "Error: koan_ask_question is only available in subagent context." }], + details: undefined, + }; + } - if (await ipcFileExists(dir)) { - return { - content: [{ type: "text" as const, text: "Error: An IPC request is already pending." }], - details: undefined, - }; - } + if (await ipcFileExists(dir)) { + return { + content: [{ type: "text" as const, text: "Error: An IPC request is already pending." }], + details: undefined, + }; + } - const ipc = createAskRequest(askParams); - await writeIpcFile(dir, ipc); - - let aborted = false; - const onAbort = () => { aborted = true; }; - if (signal) signal.addEventListener("abort", onAbort, { once: true }); - - type PollResult = "answered" | "cancelled" | "aborted" | "file-gone"; - let pollResult: PollResult = "file-gone"; - let answeredPayload: AskAnswerPayload | null = null; - - try { - while (!aborted) { - await sleep(500); - if (signal?.aborted) { aborted = true; break; } - - const current = await readIpcFile(dir); - if (current === null) { pollResult = "file-gone"; break; } - - if (current.type === "ask" && current.response !== null && current.response.id === ipc.id) { - if (current.response.cancelled) { - pollResult = "cancelled"; - } else { - pollResult = "answered"; - answeredPayload = current.response.payload; - } - break; - } - } + const ipc = createAskRequest(params); + await writeIpcFile(dir, ipc); - if (aborted) pollResult = "aborted"; - } finally { - await deleteIpcFile(dir); - } + let aborted = false; + const onAbort = () => { aborted = true; }; + if (signal) signal.addEventListener("abort", onAbort, { once: true }); - switch (pollResult) { - case "answered": { - const result = buildQuestionResult(askParams, answeredPayload); - return { - content: [{ type: "text" as const, text: buildSessionContent(result) }], - details: undefined, - }; - } - case "cancelled": - return { - content: [{ type: "text" as const, text: "The user declined to answer. Proceed with your best judgment." }], - details: undefined, - }; - case "aborted": - return { - content: [{ type: "text" as const, text: "The question was aborted." }], - details: undefined, - }; - case "file-gone": - return { - content: [{ type: "text" as const, text: "The question was cancelled." }], - details: undefined, - }; - } - }, - }); + type PollResult = "answered" | "cancelled" | "aborted" | "file-gone"; + let pollResult: PollResult = "file-gone"; + let answeredPayload: AskAnswerPayload | null = null; - // -- koan_request_scouts -- + try { + while (!aborted) { + await sleep(500); + if (signal?.aborted) { aborted = true; break; } - pi.registerTool({ - name: "koan_request_scouts", - label: "Request codebase scouts", - description: SCOUTS_TOOL_DESCRIPTION, - parameters: RequestScoutsSchema, + const current = await readIpcFile(dir); + if (current === null) { pollResult = "file-gone"; break; } - async execute(_toolCallId, params, signal) { - const { scouts } = params as RequestScoutsParams; - const dir = ctx.subagentDir; - - if (!dir) { - return { - content: [{ type: "text" as const, text: "Error: koan_request_scouts is only available in subagent context." }], - details: undefined, - }; + if (current.type === "ask" && current.response !== null && current.response.id === ipc.id) { + if (current.response.cancelled) { + pollResult = "cancelled"; + } else { + pollResult = "answered"; + answeredPayload = current.response.payload; + } + break; } + } - if (await ipcFileExists(dir)) { - return { - content: [{ type: "text" as const, text: "Error: An IPC request is already pending." }], - details: undefined, - }; - } + if (aborted) pollResult = "aborted"; + } finally { + await deleteIpcFile(dir); + } + + switch (pollResult) { + case "answered": { + const result = buildQuestionResult(params, answeredPayload); + return { + content: [{ type: "text" as const, text: buildSessionContent(result) }], + details: undefined, + }; + } + case "cancelled": + return { + content: [{ type: "text" as const, text: "The user declined to answer. Proceed with your best judgment." }], + details: undefined, + }; + case "aborted": + return { + content: [{ type: "text" as const, text: "The question was aborted." }], + details: undefined, + }; + case "file-gone": + return { + content: [{ type: "text" as const, text: "The question was cancelled." }], + details: undefined, + }; + } +} + +export async function executeRequestScouts( + params: RequestScoutsParams, + subagentDir: string | null, + signal?: AbortSignal | null, +): Promise { + const dir = subagentDir; + + if (!dir) { + return { + content: [{ type: "text" as const, text: "Error: koan_request_scouts is only available in subagent context." }], + details: undefined, + }; + } - const ipc = createScoutRequest(scouts as ScoutRequest[]); - await writeIpcFile(dir, ipc); + if (await ipcFileExists(dir)) { + return { + content: [{ type: "text" as const, text: "Error: An IPC request is already pending." }], + details: undefined, + }; + } - let aborted = false; - const onAbort = () => { aborted = true; }; - if (signal) signal.addEventListener("abort", onAbort, { once: true }); + const ipc = createScoutRequest(params.scouts as ScoutRequest[]); + await writeIpcFile(dir, ipc); - type PollResult = "completed" | "aborted" | "file-gone"; - let pollResult: PollResult = "file-gone"; - let findings: string[] = []; - let failures: string[] = []; + let aborted = false; + const onAbort = () => { aborted = true; }; + if (signal) signal.addEventListener("abort", onAbort, { once: true }); - try { - while (!aborted) { - await sleep(500); - if (signal?.aborted) { aborted = true; break; } + type PollResult = "completed" | "aborted" | "file-gone"; + let pollResult: PollResult = "file-gone"; + let findings: string[] = []; + let failures: string[] = []; - const current = await readIpcFile(dir); - if (current === null) { pollResult = "file-gone"; break; } + try { + while (!aborted) { + await sleep(500); + if (signal?.aborted) { aborted = true; break; } - if (current.type === "scout-request" && current.response !== null && current.id === ipc.id) { - pollResult = "completed"; - findings = current.response.findings; - failures = current.response.failures; - break; - } - } + const current = await readIpcFile(dir); + if (current === null) { pollResult = "file-gone"; break; } - if (aborted) pollResult = "aborted"; - } finally { - await deleteIpcFile(dir); + if (current.type === "scout-request" && current.response !== null && current.id === ipc.id) { + pollResult = "completed"; + findings = current.response.findings; + failures = current.response.failures; + break; } + } - switch (pollResult) { - case "completed": { - const sections: string[] = [ - `Scout findings: ${findings.length} completed, ${failures.length} failed.`, - "", - ]; - // Read each findings file and include contents verbatim. - for (const f of findings) { - try { - const content = await fs.readFile(f, "utf8"); - sections.push(`--- scout: ${path.basename(path.dirname(f))} ---`); - sections.push(content.trim()); - sections.push(""); - } catch { - sections.push(`--- scout: ${path.basename(path.dirname(f))} --- (could not read findings)`); - sections.push(""); - } - } - if (failures.length > 0) { - sections.push(`Failed scouts (non-fatal, proceed without them): ${failures.join(", ")}`); - } - return { - content: [{ type: "text" as const, text: sections.join("\n") }], - details: undefined, - }; + if (aborted) pollResult = "aborted"; + } finally { + await deleteIpcFile(dir); + } + + switch (pollResult) { + case "completed": { + const sections: string[] = [ + `Scout findings: ${findings.length} completed, ${failures.length} failed.`, + "", + ]; + for (const f of findings) { + try { + const content = await fs.readFile(f, "utf8"); + sections.push(`--- scout: ${path.basename(path.dirname(f))} ---`); + sections.push(content.trim()); + sections.push(""); + } catch { + sections.push(`--- scout: ${path.basename(path.dirname(f))} --- (could not read findings)`); + sections.push(""); } - case "aborted": - return { - content: [{ type: "text" as const, text: "Scout request aborted. Proceed without codebase context." }], - details: undefined, - }; - case "file-gone": - return { - content: [{ type: "text" as const, text: "Scout request cancelled. Proceed without codebase context." }], - details: undefined, - }; } + if (failures.length > 0) { + sections.push(`Failed scouts (non-fatal, proceed without them): ${failures.join(", ")}`); + } + return { + content: [{ type: "text" as const, text: sections.join("\n") }], + details: undefined, + }; + } + case "aborted": + return { + content: [{ type: "text" as const, text: "Scout request aborted. Proceed without codebase context." }], + details: undefined, + }; + case "file-gone": + return { + content: [{ type: "text" as const, text: "Scout request cancelled. Proceed without codebase context." }], + details: undefined, + }; + } +} + +// -- Tool registration -- + +export function registerAskTools(pi: ExtensionAPI, ctx: RuntimeContext): void { + // -- koan_ask_question -- + + pi.registerTool({ + name: "koan_ask_question", + label: "Ask question", + description: ASK_TOOL_DESCRIPTION, + parameters: AskParamsSchema, + + async execute(_toolCallId, params, signal) { + return executeAskQuestion(params as AskParams, ctx.subagentDir, signal); + }, + }); + + // -- koan_request_scouts -- + + pi.registerTool({ + name: "koan_request_scouts", + label: "Request codebase scouts", + description: SCOUTS_TOOL_DESCRIPTION, + parameters: RequestScoutsSchema, + + async execute(_toolCallId, params, signal) { + return executeRequestScouts(params as RequestScoutsParams, ctx.subagentDir, signal); }, }); } diff --git a/src/planner/tools/orchestrator.ts b/src/planner/tools/orchestrator.ts index 0348aa4..21a757b 100644 --- a/src/planner/tools/orchestrator.ts +++ b/src/planner/tools/orchestrator.ts @@ -75,6 +75,115 @@ export function assertStatus(storyId: string, current: StoryStatus, allowed: Sto } } +// -- Extracted execute logic -- + +type ToolResult = { content: Array<{ type: "text"; text: string }>; details: undefined }; + +export async function executeSelectStory(epicDir: string, storyId: string): Promise { + const ts = now(); + const state = await loadStoryState(epicDir, storyId); + assertStatus(storyId, state.status, ["pending", "retry"]); + + await saveStoryState(epicDir, storyId, { ...state, status: "selected", updatedAt: ts }); + await writeStatusMd( + epicDir, storyId, + statusMd(storyId, "selected", `Selected at: ${ts}`, "(pending -- not yet verified)", ""), + ); + + return { + content: [{ type: "text" as const, text: `Story '${storyId}' selected.` }], + details: undefined, + }; +} + +export async function executeCompleteStory( + epicDir: string, + storyId: string, + verificationSummary?: string, +): Promise { + const ts = now(); + const state = await loadStoryState(epicDir, storyId); + assertStatus(storyId, state.status, ["verifying"]); + + await saveStoryState(epicDir, storyId, { ...state, status: "done", updatedAt: ts }); + await writeStatusMd( + epicDir, storyId, + statusMd( + storyId, "done", + `Completed at: ${ts}`, + verificationSummary ?? "All checks passed.", + "", + ), + ); + + return { + content: [{ type: "text" as const, text: `Story '${storyId}' completed.` }], + details: undefined, + }; +} + +export async function executeRetryStory( + epicDir: string, + storyId: string, + failureSummary: string, +): Promise { + const ts = now(); + const state = await loadStoryState(epicDir, storyId); + assertStatus(storyId, state.status, ["verifying"]); + + await saveStoryState(epicDir, storyId, { + ...state, + status: "retry", + updatedAt: ts, + failureSummary: failureSummary, + }); + await writeStatusMd( + epicDir, storyId, + statusMd( + storyId, "retry", + `Queued for retry at: ${ts}`, + "Failed -- see Notes for details.", + failureSummary, + ), + ); + + return { + content: [{ type: "text" as const, text: `Story '${storyId}' queued for retry.` }], + details: undefined, + }; +} + +export async function executeSkipStory( + epicDir: string, + storyId: string, + reason: string, +): Promise { + const ts = now(); + const state = await loadStoryState(epicDir, storyId); + assertStatus(storyId, state.status, ["pending", "retry"]); + + await saveStoryState(epicDir, storyId, { + ...state, + status: "skipped", + updatedAt: ts, + skipReason: reason, + }); + await writeStatusMd( + epicDir, storyId, + statusMd( + storyId, "skipped", + `Skipped at: ${ts}`, + "(not executed)", + reason, + ), + ); + + return { + content: [{ type: "text" as const, text: `Story '${storyId}' skipped.` }], + details: undefined, + }; +} + // -- Tool registration -- export function registerOrchestratorTools(pi: ExtensionAPI, ctx: RuntimeContext): void { @@ -90,22 +199,7 @@ export function registerOrchestratorTools(pi: ExtensionAPI, ctx: RuntimeContext) }), async execute(_toolCallId, params) { const { story_id } = params as { story_id: string }; - const epicDir = requireEpicDir(ctx); - const ts = now(); - - const state = await loadStoryState(epicDir, story_id); - assertStatus(story_id, state.status, ["pending", "retry"]); - - await saveStoryState(epicDir, story_id, { ...state, status: "selected", updatedAt: ts }); - await writeStatusMd( - epicDir, story_id, - statusMd(story_id, "selected", `Selected at: ${ts}`, "(pending — not yet verified)", ""), - ); - - return { - content: [{ type: "text" as const, text: `Story '${story_id}' selected.` }], - details: undefined, - }; + return executeSelectStory(requireEpicDir(ctx), story_id); }, }); @@ -127,27 +221,7 @@ export function registerOrchestratorTools(pi: ExtensionAPI, ctx: RuntimeContext) story_id: string; verification_summary?: string; }; - const epicDir = requireEpicDir(ctx); - const ts = now(); - - const state = await loadStoryState(epicDir, story_id); - assertStatus(story_id, state.status, ["verifying"]); - - await saveStoryState(epicDir, story_id, { ...state, status: "done", updatedAt: ts }); - await writeStatusMd( - epicDir, story_id, - statusMd( - story_id, "done", - `Completed at: ${ts}`, - verification_summary ?? "All checks passed.", - "", - ), - ); - - return { - content: [{ type: "text" as const, text: `Story '${story_id}' completed.` }], - details: undefined, - }; + return executeCompleteStory(requireEpicDir(ctx), story_id, verification_summary); }, }); @@ -166,32 +240,7 @@ export function registerOrchestratorTools(pi: ExtensionAPI, ctx: RuntimeContext) }), async execute(_toolCallId, params) { const { story_id, failure_summary } = params as { story_id: string; failure_summary: string }; - const epicDir = requireEpicDir(ctx); - const ts = now(); - - const state = await loadStoryState(epicDir, story_id); - assertStatus(story_id, state.status, ["verifying"]); - - await saveStoryState(epicDir, story_id, { - ...state, - status: "retry", - updatedAt: ts, - failureSummary: failure_summary, - }); - await writeStatusMd( - epicDir, story_id, - statusMd( - story_id, "retry", - `Queued for retry at: ${ts}`, - "Failed — see Notes for details.", - failure_summary, - ), - ); - - return { - content: [{ type: "text" as const, text: `Story '${story_id}' queued for retry.` }], - details: undefined, - }; + return executeRetryStory(requireEpicDir(ctx), story_id, failure_summary); }, }); @@ -208,32 +257,7 @@ export function registerOrchestratorTools(pi: ExtensionAPI, ctx: RuntimeContext) }), async execute(_toolCallId, params) { const { story_id, reason } = params as { story_id: string; reason: string }; - const epicDir = requireEpicDir(ctx); - const ts = now(); - - const state = await loadStoryState(epicDir, story_id); - assertStatus(story_id, state.status, ["pending", "retry"]); - - await saveStoryState(epicDir, story_id, { - ...state, - status: "skipped", - updatedAt: ts, - skipReason: reason, - }); - await writeStatusMd( - epicDir, story_id, - statusMd( - story_id, "skipped", - `Skipped at: ${ts}`, - "(not executed)", - reason, - ), - ); - - return { - content: [{ type: "text" as const, text: `Story '${story_id}' skipped.` }], - details: undefined, - }; + return executeSkipStory(requireEpicDir(ctx), story_id, reason); }, }); } diff --git a/src/planner/tools/workflow.ts b/src/planner/tools/workflow.ts index 1d4ddfa..4b432a8 100644 --- a/src/planner/tools/workflow.ts +++ b/src/planner/tools/workflow.ts @@ -20,6 +20,26 @@ import type { RuntimeContext } from "../lib/runtime-context.js"; const log = createLogger("Workflow"); +// -- Extracted execute logic -- + +export async function executeCompleteStep( + thoughts: string, + onCompleteStep: ((thoughts: string) => Promise) | null, +): Promise<{ content: Array<{ type: "text"; text: string }>; details: undefined }> { + if (!onCompleteStep) { + log("koan_complete_step called with no active phase"); + return { + content: [{ type: "text" as const, text: "No workflow phase is active." }], + details: undefined, + }; + } + const nextPrompt = await onCompleteStep(thoughts); + return { + content: [{ type: "text" as const, text: nextPrompt ?? "Phase complete." }], + details: undefined, + }; +} + // Registers workflow tools. Called once at init in koan.ts, // before pi's _buildRuntime() snapshot. Tool execute callbacks read // from the RuntimeContext at call time — the context is mutable, @@ -58,16 +78,8 @@ export function registerWorkflowTools( })), }), async execute(_toolCallId, params) { - if (!ctx.onCompleteStep) { - log("koan_complete_step called with no active phase"); - throw new Error("No workflow phase is active."); - } const thoughts = (params as { thoughts?: string }).thoughts ?? ""; - const nextPrompt = await ctx.onCompleteStep(thoughts); - return { - content: [{ type: "text" as const, text: nextPrompt ?? "Phase complete." }], - details: undefined, - }; + return executeCompleteStep(thoughts, ctx.onCompleteStep); }, }); } diff --git a/src/planner/web/js/sse.js b/src/planner/web/js/sse.js index 036cc5d..0c55088 100644 --- a/src/planner/web/js/sse.js +++ b/src/planner/web/js/sse.js @@ -1,44 +1,49 @@ -import { useStore } from './store.js' +// SSE dispatch layer. Connects to the event stream and routes each event +// type to a named handler from store.js. This file does not import useStore +// or know the store's internal shape -- all state mapping lives in store.js. + +import { + handleInitEvent, + handlePhaseEvent, + handleIntakeProgressEvent, + handleStoriesEvent, + handleScoutsEvent, + handleAgentsEvent, + handleLogsEvent, + handleSubagentEvent, + handleSubagentIdleEvent, + handlePipelineEndEvent, + handleAskEvent, + handleReviewEvent, + handleModelConfigEvent, + handleModelConfigConfirmedEvent, + handleAskCancelledEvent, + handleReviewCancelledEvent, + handleNotificationEvent, + handleConnectionError, +} from './store.js' export function connectSSE(token) { const es = new EventSource(`/events?session=${encodeURIComponent(token)}`) - const set = useStore.setState const handlers = { - 'init': (d) => set({ availableModels: d.availableModels || [] }), - phase: (d) => set({ - phase: d.phase, - // Clear interaction state and intake progress when leaving intake - ...(d.phase !== 'intake' && { pendingInput: null, intakeProgress: null }), - }), - 'intake-progress': (d) => set({ intakeProgress: d }), - stories: (d) => set({ stories: d.stories }), - scouts: (d) => set({ scouts: d.scouts }), - agents: (d) => set({ agents: d.agents }), - logs: (d) => set({ logs: d.lines, currentToolCallId: d.currentToolCallId ?? null }), - subagent: (d) => set({ subagent: d }), - 'subagent-idle': () => set({ subagent: null }), - 'pipeline-end': (d) => set(s => ({ - phase: d.success ? 'completed' : s.phase, - pipelineEnd: d, - intakeProgress: null, - })), - ask: (d) => set({ pendingInput: { type: 'ask', requestId: d.requestId, payload: d.question } }), - review: (d) => set({ pendingInput: { type: 'review', requestId: d.requestId, payload: d.stories } }), - 'model-config': (d) => set(s => ({ - pendingInput: { type: 'model-config', requestId: d.requestId, payload: { ...d.tiers, scoutConcurrency: d.scoutConcurrency } }, - ...(d.availableModels ? { availableModels: d.availableModels } : {}), - })), - 'model-config-confirmed': () => set(s => s.pendingInput?.type === 'model-config' ? { pendingInput: null } : {}), - 'ask-cancelled': (d) => set(s => s.pendingInput?.requestId === d.requestId - ? { pendingInput: null, notifications: [...s.notifications, { id: Date.now(), message: 'The question was cancelled — the subagent has exited.', level: 'warning' }] } - : {}), - 'review-cancelled': (d) => set(s => s.pendingInput?.requestId === d.requestId - ? { pendingInput: null, notifications: [...s.notifications, { id: Date.now(), message: 'The review was cancelled.', level: 'warning' }] } - : {}), - notification: (d) => set(s => ({ - notifications: [...s.notifications, { id: Date.now(), message: d.message, level: d.level }], - })), + 'init': handleInitEvent, + 'phase': handlePhaseEvent, + 'intake-progress': handleIntakeProgressEvent, + 'stories': handleStoriesEvent, + 'scouts': handleScoutsEvent, + 'agents': handleAgentsEvent, + 'logs': handleLogsEvent, + 'subagent': handleSubagentEvent, + 'subagent-idle': handleSubagentIdleEvent, + 'pipeline-end': handlePipelineEndEvent, + 'ask': handleAskEvent, + 'review': handleReviewEvent, + 'model-config': handleModelConfigEvent, + 'model-config-confirmed': handleModelConfigConfirmedEvent, + 'ask-cancelled': handleAskCancelledEvent, + 'review-cancelled': handleReviewCancelledEvent, + 'notification': handleNotificationEvent, } for (const [event, handler] of Object.entries(handlers)) { @@ -48,9 +53,7 @@ export function connectSSE(token) { }) } - es.onerror = () => set(s => ({ - notifications: [...s.notifications, { id: Date.now(), message: 'Connection lost — reconnecting…', level: 'warning' }], - })) + es.onerror = () => handleConnectionError() return es } diff --git a/src/planner/web/js/store.js b/src/planner/web/js/store.js index 18ad55a..664ad6c 100644 --- a/src/planner/web/js/store.js +++ b/src/planner/web/js/store.js @@ -1,3 +1,10 @@ +// Zustand store and SSE event->state handlers. +// +// store.js owns both the store shape and the event->state mapping. +// sse.js only knows event type names and raw payloads -- it imports +// named handler functions from here and never calls useStore directly. +// Changing the store shape only requires updating this file. + import { create } from 'zustand' export const useStore = create((set) => ({ @@ -7,10 +14,10 @@ export const useStore = create((set) => ({ scouts: [], agents: [], logs: [], // Array<{ tool, summary, highValue, inFlight }> - currentToolCallId: null, // string | null — in-flight tool for the main agent + currentToolCallId: null, // string | null -- in-flight tool for the main agent subagent: null, pendingInput: null, - intakeProgress: null, // IntakeProgressEvent | null — set during intake phase + intakeProgress: null, // IntakeProgressEvent | null -- set during intake phase // Client-only state notifications: [], @@ -18,3 +25,98 @@ export const useStore = create((set) => ({ showSettings: false, availableModels: [], })) + +// -- SSE event handlers -- + +const set = useStore.setState + +export function handleInitEvent(d) { + set({ availableModels: d.availableModels || [] }) +} + +export function handlePhaseEvent(d) { + set({ + phase: d.phase, + // Clear interaction state and intake progress when leaving intake + ...(d.phase !== 'intake' && { pendingInput: null, intakeProgress: null }), + }) +} + +export function handleIntakeProgressEvent(d) { + set({ intakeProgress: d }) +} + +export function handleStoriesEvent(d) { + set({ stories: d.stories }) +} + +export function handleScoutsEvent(d) { + set({ scouts: d.scouts }) +} + +export function handleAgentsEvent(d) { + set({ agents: d.agents }) +} + +export function handleLogsEvent(d) { + set({ logs: d.lines, currentToolCallId: d.currentToolCallId ?? null }) +} + +export function handleSubagentEvent(d) { + set({ subagent: d }) +} + +export function handleSubagentIdleEvent() { + set({ subagent: null }) +} + +export function handlePipelineEndEvent(d) { + set(s => ({ + phase: d.success ? 'completed' : s.phase, + pipelineEnd: d, + intakeProgress: null, + })) +} + +export function handleAskEvent(d) { + set({ pendingInput: { type: 'ask', requestId: d.requestId, payload: d.question } }) +} + +export function handleReviewEvent(d) { + set({ pendingInput: { type: 'review', requestId: d.requestId, payload: d.stories } }) +} + +export function handleModelConfigEvent(d) { + set(s => ({ + pendingInput: { type: 'model-config', requestId: d.requestId, payload: { ...d.tiers, scoutConcurrency: d.scoutConcurrency } }, + ...(d.availableModels ? { availableModels: d.availableModels } : {}), + })) +} + +export function handleModelConfigConfirmedEvent() { + set(s => s.pendingInput?.type === 'model-config' ? { pendingInput: null } : {}) +} + +export function handleAskCancelledEvent(d) { + set(s => s.pendingInput?.requestId === d.requestId + ? { pendingInput: null, notifications: [...s.notifications, { id: Date.now(), message: 'The question was cancelled -- the subagent has exited.', level: 'warning' }] } + : {}) +} + +export function handleReviewCancelledEvent(d) { + set(s => s.pendingInput?.requestId === d.requestId + ? { pendingInput: null, notifications: [...s.notifications, { id: Date.now(), message: 'The review was cancelled.', level: 'warning' }] } + : {}) +} + +export function handleNotificationEvent(d) { + set(s => ({ + notifications: [...s.notifications, { id: Date.now(), message: d.message, level: d.level }], + })) +} + +export function handleConnectionError() { + set(s => ({ + notifications: [...s.notifications, { id: Date.now(), message: 'Connection lost -- reconnecting...', level: 'warning' }], + })) +} From a157efecb975d44e8859f1b750e745ca22a78bcd Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Sat, 21 Mar 2026 15:10:36 +0700 Subject: [PATCH 079/412] T2 audit.ts split (6 files) --- src/planner/lib/audit-events.ts | 157 ++++ src/planner/lib/audit-fold.ts | 205 +++++ src/planner/lib/audit-log-formatter.ts | 434 +++++++++++ src/planner/lib/audit.ts | 996 +------------------------ src/planner/lib/event-log.ts | 242 ++++++ src/planner/lib/runtime-context.ts | 2 +- 6 files changed, 1050 insertions(+), 986 deletions(-) create mode 100644 src/planner/lib/audit-events.ts create mode 100644 src/planner/lib/audit-fold.ts create mode 100644 src/planner/lib/audit-log-formatter.ts create mode 100644 src/planner/lib/event-log.ts diff --git a/src/planner/lib/audit-events.ts b/src/planner/lib/audit-events.ts new file mode 100644 index 0000000..1fc031c --- /dev/null +++ b/src/planner/lib/audit-events.ts @@ -0,0 +1,157 @@ +// Event type definitions for the audit trail. No I/O, no Node.js imports. + +// -- Types -- + +export interface EventBase { + ts: string; + seq: number; +} + +// -- Tool events -- +// Every tool invocation produces a (tool_call, tool_result) pair in the log. +// tool_call fires when the LLM requests the tool; tool_result fires when +// the tool returns. Both carry toolCallId for correlation. + +export interface ToolCallEvent extends EventBase { + kind: "tool_call"; + toolCallId: string; + tool: string; + input: Record; +} + +export interface ToolResultEvent extends EventBase { + kind: "tool_result"; + toolCallId: string; + tool: string; + error: boolean; + // Summarized output metrics (not the full content -- too large for the log). + lines?: number; + chars?: number; + // Koan tool response text preserved for projection (completionSummary, etc.). + koanResponse?: string[]; +} + +// -- Lifecycle events -- + +export interface PhaseStartEvent extends EventBase { + kind: "phase_start"; + phase: string; + role: string; + model?: string | null; + totalSteps: number; +} + +export interface StepTransitionEvent extends EventBase { + kind: "step_transition"; + step: number; + name: string; + totalSteps: number; +} + +export interface PhaseEndEvent extends EventBase { + kind: "phase_end"; + outcome: "completed" | "failed"; + detail?: string; +} + +export interface HeartbeatEvent extends EventBase { + kind: "heartbeat"; +} + +export interface UsageEvent extends EventBase { + kind: "usage"; + input: number; + output: number; + cacheRead: number; + cacheWrite: number; +} + +export interface ThinkingEvent extends EventBase { + kind: "thinking"; + // Truncated thinking content (first 2000 chars for log size). + text: string; + // Original length before truncation. + chars: number; +} + +export interface ConfidenceChangeEvent extends EventBase { + kind: "confidence_change"; + // The confidence level declared by the intake agent via koan_set_confidence. + level: "exploring" | "low" | "medium" | "high" | "certain"; + // Which iteration of the Scout->Deliberate->Reflect loop this was declared in. + iteration: number; +} + +export interface IterationStartEvent extends EventBase { + kind: "iteration_start"; + // The new iteration number (incremented from the previous Reflect step). + iteration: number; + // Maximum allowed iterations before the loop is forced to exit. + maxIterations: number; +} + +export type AuditEvent = + | ToolCallEvent + | ToolResultEvent + | PhaseStartEvent + | StepTransitionEvent + | PhaseEndEvent + | HeartbeatEvent + | UsageEvent + | ThinkingEvent + | ConfidenceChangeEvent + | IterationStartEvent; + +// Distributive Omit -- distributes over union members so object literals +// with fields specific to one member are accepted. +type DistributiveOmit = T extends unknown ? Omit : never; +export type AuditEventPartial = DistributiveOmit; + +// -- Projection -- +// Eagerly materialized state summary. Written atomically to state.json +// after every event so the parent (web server) can poll cheaply. + +export interface Projection { + role: string; + phase: string; + model: string | null; + status: "running" | "completed" | "failed"; + step: number; + totalSteps: number; + stepName: string; + lastAction: string | null; + // toolCallId of the currently in-flight tool, null when idle. + // Lets the UI distinguish "doing X" from "done with X". + currentToolCallId: string | null; + updatedAt: string; + eventCount: number; + error: string | null; + completionSummary: string | null; + tokensSent: number; + tokensReceived: number; + // Timestamp of the most recent tool_result event; used to track thinking gaps. + lastToolResultAt: string | null; + // Intake-specific: the most recent confidence level declared by koan_set_confidence. + // Null for non-intake subagents or before any confidence is declared. + intakeConfidence: "exploring" | "low" | "medium" | "high" | "certain" | null; + // Intake-specific: the current loop iteration (1-based). Zero for non-intake. + intakeIteration: number; +} + +// -- Correlated tool invocations -- +// Reduced view of paired (tool_call, tool_result) events. + +export interface ToolInvocation { + toolCallId: string; + tool: string; + input: Record; + callTs: string; + resultTs: string | null; + error: boolean | null; + inFlight: boolean; + durationMs: number | null; + // Output metrics from the result event. + lines?: number; + chars?: number; + koanResponse?: string[]; +} diff --git a/src/planner/lib/audit-fold.ts b/src/planner/lib/audit-fold.ts new file mode 100644 index 0000000..5f10940 --- /dev/null +++ b/src/planner/lib/audit-fold.ts @@ -0,0 +1,205 @@ +// Pure fold/correlate/summarize functions. No I/O, no Node.js or pi imports +// -- safe to unit-test directly. + +import type { + AuditEvent, + Projection, + ToolInvocation, + ToolCallEvent, + ToolResultEvent, +} from "./audit-events.js"; + +// -- Constants -- + +const FILE_TOOLS = new Set(["read", "edit", "write"]); + +// -- Formatters -- + +export function formatChars(chars: number): string { + if (chars < 1000) return `${chars}c`; + const k = chars / 1000; + if (k >= 10) return `${Math.round(k)}k`; + return `${k.toFixed(1)}k`; +} + +// -- Correlate -- + +// Reduces a flat event stream into paired tool invocations. +// In-flight tools (call without result) have inFlight=true, resultTs=null. +export function correlateTools(events: AuditEvent[]): ToolInvocation[] { + const byId = new Map(); + const ordered: ToolInvocation[] = []; + + for (const e of events) { + if (e.kind === "tool_call") { + const inv: ToolInvocation = { + toolCallId: e.toolCallId, + tool: e.tool, + input: e.input, + callTs: e.ts, + resultTs: null, + error: null, + inFlight: true, + durationMs: null, + }; + byId.set(e.toolCallId, inv); + ordered.push(inv); + } else if (e.kind === "tool_result") { + const inv = byId.get(e.toolCallId); + if (inv) { + inv.resultTs = e.ts; + inv.error = e.error; + inv.inFlight = false; + inv.durationMs = new Date(e.ts).getTime() - new Date(inv.callTs).getTime(); + inv.lines = e.lines; + inv.chars = e.chars; + inv.koanResponse = e.koanResponse; + } + // Orphan result (no matching call) -- can happen if the subagent + // started before tool_call hooking was added. Silently skip. + } + } + + return ordered; +} + +// -- Summarize -- +// Human-readable one-liner from a tool invocation. +// Uses input (from call) + output metrics (from result) when available. + +export function summarizeInvocation(inv: ToolInvocation): string { + const { tool, input } = inv; + + // Tool name / key input identifier. + let label: string; + if (FILE_TOOLS.has(tool)) { + label = `${tool} ${(input["path"] as string | undefined) ?? ""}`; + } else if (tool === "bash") { + const cmd = (input["command"] as string | undefined) ?? ""; + label = `bash ${cmd.trim().split(/\s+/)[0] ?? ""}`; + } else { + label = tool; + } + + // Append output metrics if result has landed. + if (!inv.inFlight && (inv.lines != null || inv.chars != null)) { + const lines = inv.lines ?? 0; + const chars = inv.chars ?? 0; + label += ` · ${lines}L/${formatChars(chars)}`; + } + + return label; +} + +// Summarize from a ToolCallEvent alone (in-flight, no result yet). +function summarizeCall(e: ToolCallEvent): string { + if (FILE_TOOLS.has(e.tool)) { + return `${e.tool} ${(e.input["path"] as string | undefined) ?? ""}`; + } + if (e.tool === "bash") { + const cmd = (e.input["command"] as string | undefined) ?? ""; + return `bash ${cmd.trim().split(/\s+/)[0] ?? ""}`; + } + return e.tool; +} + +// Summarize from a ToolResultEvent alone (used in fold when call was missed). +function summarizeResult(e: ToolResultEvent): string { + let label = e.tool; + if (e.lines != null || e.chars != null) { + label += ` · ${e.lines ?? 0}L/${formatChars(e.chars ?? 0)}`; + } + return label; +} + +// -- Fold -- +// Pure projection update -- one case per discriminated kind. +// All branches update updatedAt and increment eventCount. + +export function fold(s: Projection, e: AuditEvent): Projection { + const base = { ...s, updatedAt: e.ts, eventCount: s.eventCount + 1 }; + + switch (e.kind) { + case "phase_start": + return { + ...base, + role: e.role, + phase: e.phase, + model: e.model ?? s.model, + status: "running", + step: 0, + totalSteps: e.totalSteps, + stepName: "", + lastAction: null, + currentToolCallId: null, + error: null, + completionSummary: null, + }; + + case "step_transition": + return { + ...base, + step: e.step, + totalSteps: e.totalSteps, + stepName: `Step ${e.step}/${e.totalSteps}: ${e.name}`, + }; + + case "phase_end": + return { + ...base, + status: e.outcome, + error: e.detail ?? null, + currentToolCallId: null, + }; + + case "tool_call": { + const updated: Projection = { + ...base, + lastAction: summarizeCall(e), + currentToolCallId: e.toolCallId, + }; + // Extract completionSummary from koan_complete_step's thoughts param. + // The thoughts parameter is chain-of-thought, not task output (per + // AGENTS.md invariant), but we capture a prefix for the projection + // so the web UI can show scout summaries. + if (e.tool === "koan_complete_step" && typeof e.input?.thoughts === "string") { + updated.completionSummary = e.input.thoughts.slice(0, 500) || null; + } + return updated; + } + + case "tool_result": + return { + ...base, + lastAction: summarizeResult(e), + currentToolCallId: null, + lastToolResultAt: e.ts, + }; + + case "heartbeat": + return base; + + case "usage": + return { + ...base, + tokensSent: s.tokensSent + e.input, + tokensReceived: s.tokensReceived + e.output, + }; + + case "thinking": + return base; + + case "confidence_change": + return { + ...base, + intakeConfidence: e.level, + intakeIteration: e.iteration, + }; + + case "iteration_start": + return { + ...base, + intakeIteration: e.iteration, + }; + } +} diff --git a/src/planner/lib/audit-log-formatter.ts b/src/planner/lib/audit-log-formatter.ts new file mode 100644 index 0000000..1255f83 --- /dev/null +++ b/src/planner/lib/audit-log-formatter.ts @@ -0,0 +1,434 @@ +// Log formatters for the web UI activity feed. Reads events.jsonl and +// produces structured LogLine entries. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; +import type { + AuditEvent, + ToolResultEvent, + PhaseStartEvent, + StepTransitionEvent, + PhaseEndEvent, + ToolInvocation, +} from "./audit-events.js"; +import { correlateTools, formatChars } from "./audit-fold.js"; + +// -- Types -- + +export interface LogLine { + tool: string; + summary: string; + highValue: boolean; + inFlight: boolean; + details?: string[]; + // Timestamp used by thinking entries to drive the live elapsed timer. + ts?: string; + // Expandable content body: thinking text, tool output, etc. + body?: string; + // Structured scout data for koan_request_scouts cards. + scouts?: Array<{ id: string; role: string }>; +} + +interface ToolShape { + keys: string[]; + arrays?: string[]; + freeform?: string[]; + getter?: boolean; + highValue?: boolean; +} + +// -- Constants -- + +const PREVIEW_CHARS = 40; +const KEY_PRIORITY = ["id", "story_id", "milestone", "decision_ref", "intent_ref", "file", "path", "phase"]; + +const KOAN_SHAPES: Record = { + koan_select_story: { keys: ["story_id"], highValue: true }, + koan_complete_story: { keys: ["story_id"], highValue: true }, + koan_retry_story: { keys: ["story_id", "failure_summary"], freeform: ["failure_summary"], highValue: true }, + koan_skip_story: { keys: ["story_id", "reason"], freeform: ["reason"], highValue: true }, + koan_ask_question: { + keys: ["id", "question", "context", "options", "multi", "recommended"], + arrays: ["options"], + freeform: ["question", "context"], + highValue: true, + }, + koan_request_scouts: { keys: [], highValue: true }, +}; + +const FILE_TOOLS = new Set(["read", "edit", "write"]); + +// -- Public API -- + +// Reads events.jsonl, correlates tool pairs, and returns structured log entries. +// Filters out heartbeats, usage, and koan_complete_step (noisy). +export async function readRecentLogs(dir: string, count = 8): Promise { + try { + const raw = await fs.readFile(path.join(dir, "events.jsonl"), "utf8"); + const events = raw + .trimEnd() + .split("\n") + .filter(Boolean) + .map((line) => JSON.parse(line) as AuditEvent); + + return buildChronologicalLog(events, count); + } catch { + return []; + } +} + +// -- Helpers -- + +function textStats(text: string): string { + const lines = text.length === 0 ? 0 : text.split("\n").length; + return `${lines}L/${formatChars(text.length)}`; +} + +function responseSize(response: string[]): string { + return textStats(response.join("\n")); +} + +function formatThinkingDuration(ms: number): string { + const sec = Math.round(ms / 1000); + if (sec < 60) return `${sec}s`; + const min = Math.floor(sec / 60); + const remSec = sec % 60; + return remSec > 0 ? `${min}m ${remSec}s` : `${min}m`; +} + +function truncateUnicode(text: string, maxChars: number): string { + const chars = Array.from(text); + if (chars.length <= maxChars) return text; + return `${chars.slice(0, maxChars).join("")}\u2026`; +} + +function inlineScalar(value: unknown): string { + if (typeof value === "string") { + return truncateUnicode(value.replace(/\r\n?|\n/gu, "\\n"), PREVIEW_CHARS); + } + if (typeof value === "number" || typeof value === "boolean") { + return String(value); + } + if (value === null) return "null"; + if (Array.isArray(value)) return `[${value.length}]`; + if (typeof value === "object") return "{\u2026}"; + return String(value); +} + +function arrayPreview(value: unknown): string { + if (!Array.isArray(value) || value.length === 0) { + return "[]"; + } + const first = inlineScalar(value[0]); + if (value.length === 1) { + return `[${first}]`; + } + return `[${first}] +${value.length - 1}`; +} + +function freeformSize(value: unknown): string { + if (typeof value === "string") { + return textStats(value); + } + const json = JSON.stringify(value); + return textStats(json ?? String(value)); +} + +function hasKey(input: Record, key: string): boolean { + return Object.prototype.hasOwnProperty.call(input, key); +} + +function orderedShapeKeys(keys: string[]): string[] { + const indexed = keys.map((key, index) => ({ key, index })); + indexed.sort((a, b) => { + const pa = KEY_PRIORITY.indexOf(a.key); + const pb = KEY_PRIORITY.indexOf(b.key); + const ra = pa === -1 ? Number.MAX_SAFE_INTEGER : pa; + const rb = pb === -1 ? Number.MAX_SAFE_INTEGER : pb; + if (ra !== rb) return ra - rb; + return a.index - b.index; + }); + return indexed.map((x) => x.key); +} + +// -- Formatters -- + +// Format a completed tool invocation from its correlated pair. +function formatToolInvocation(inv: ToolInvocation): LogLine { + if (inv.tool.startsWith("koan_")) { + return formatKoanInvocation(inv); + } + + if (FILE_TOOLS.has(inv.tool)) { + const p = (inv.input["path"] as string | undefined) ?? ""; + const suffix = inv.lines != null ? ` · ${inv.lines}L/${formatChars(inv.chars ?? 0)}` : ""; + return { + tool: inv.tool, + summary: `${p}${suffix}`, + highValue: inv.tool === "read", + inFlight: inv.inFlight, + }; + } + + if (inv.tool === "bash") { + const cmd = (inv.input["command"] as string | undefined) ?? ""; + const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; + const suffix = inv.lines != null ? ` · ${inv.lines}L/${formatChars(inv.chars ?? 0)}` : ""; + return { + tool: "bash", + summary: `${bin}${suffix}`, + highValue: false, + inFlight: inv.inFlight, + }; + } + + return { tool: inv.tool, summary: "", highValue: false, inFlight: inv.inFlight }; +} + +function formatKoanInvocation(inv: ToolInvocation): LogLine { + const shape = KOAN_SHAPES[inv.tool]; + if (!shape) { + return { tool: inv.tool, summary: "", highValue: false, inFlight: inv.inFlight }; + } + + const arrayKeys = new Set(shape.arrays ?? []); + const freeformKeys = new Set(shape.freeform ?? []); + const chunks: string[] = []; + + for (const key of orderedShapeKeys(shape.keys)) { + if (!hasKey(inv.input, key)) continue; + const value = inv.input[key]; + + if (arrayKeys.has(key)) { + chunks.push(`${key}:${arrayPreview(value)}`); + continue; + } + if (freeformKeys.has(key)) { + chunks.push(`${key}:${freeformSize(value)}`); + continue; + } + chunks.push(`${key}=${inlineScalar(value)}`); + } + + if (shape.getter && inv.koanResponse) { + if (chunks.length === 0) { + chunks.push("scope=plan"); + } + chunks.push(`resp:${responseSize(inv.koanResponse)}`); + } + + const line: LogLine = { + tool: inv.tool, + summary: chunks.join(" · "), + highValue: shape.highValue ?? chunks.length >= 3, + inFlight: inv.inFlight, + }; + + // Structured scout data for the UI card. + if (inv.tool === "koan_request_scouts" && Array.isArray(inv.input["scouts"])) { + line.scouts = (inv.input["scouts"] as Array>).map( + (s) => ({ id: String(s["id"] ?? "?"), role: String(s["role"] ?? "agent") }), + ); + } + + return line; +} + +// Format a tool_result event paired with its call's input. +function formatPairedResult(e: ToolResultEvent, input: Record): LogLine { + if (FILE_TOOLS.has(e.tool)) { + const p = (input["path"] as string | undefined) ?? ""; + const suffix = e.lines != null ? ` · ${e.lines}L/${formatChars(e.chars ?? 0)}` : ""; + return { + tool: e.tool, + summary: `${p}${suffix}`, + highValue: e.tool === "read", + inFlight: false, + }; + } + + if (e.tool === "bash") { + const cmd = (input["command"] as string | undefined) ?? ""; + const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; + const suffix = e.lines != null ? ` · ${e.lines}L/${formatChars(e.chars ?? 0)}` : ""; + return { + tool: "bash", + summary: `${bin}${suffix}`, + highValue: false, + inFlight: false, + }; + } + + if (e.tool.startsWith("koan_")) { + const shape = KOAN_SHAPES[e.tool]; + if (shape) { + // Rebuild invocation-like object for the koan formatter. + const inv: ToolInvocation = { + toolCallId: e.toolCallId, + tool: e.tool, + input, + callTs: e.ts, + resultTs: e.ts, + error: e.error, + inFlight: false, + durationMs: null, + koanResponse: e.koanResponse, + }; + return formatKoanInvocation(inv); + } + return { tool: e.tool, summary: "", highValue: false, inFlight: false }; + } + + return { tool: e.tool, summary: "", highValue: false, inFlight: false }; +} + +function formatLifecycleEvent(e: PhaseStartEvent | StepTransitionEvent | PhaseEndEvent): LogLine { + switch (e.kind) { + case "phase_start": + return { tool: "phase", summary: `${e.phase} (${e.totalSteps} steps)`, highValue: false, inFlight: false }; + case "step_transition": + return { tool: `step ${e.step}/${e.totalSteps}`, summary: e.name, highValue: false, inFlight: false }; + case "phase_end": + return { tool: "phase", summary: e.detail ? `${e.outcome} · ${e.detail}` : e.outcome, highValue: false, inFlight: false }; + } +} + +// Format an in-flight tool_call (no result yet). Same structure as +// formatPairedResult but with inFlight: true and no output metrics. +function formatInFlightCall(tool: string, input: Record): LogLine { + if (FILE_TOOLS.has(tool)) { + return { + tool, + summary: (input["path"] as string | undefined) ?? "", + highValue: tool === "read", + inFlight: true, + }; + } + + if (tool === "bash") { + const cmd = (input["command"] as string | undefined) ?? ""; + const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; + return { tool: "bash", summary: bin, highValue: false, inFlight: true }; + } + + if (tool.startsWith("koan_")) { + const shape = KOAN_SHAPES[tool]; + if (shape) { + const inv: ToolInvocation = { + toolCallId: "", tool, input, + callTs: "", resultTs: null, + error: null, inFlight: true, durationMs: null, + }; + return formatKoanInvocation(inv); + } + } + + return { tool, summary: "", highValue: false, inFlight: true }; +} + +// -- Chronological log builder -- + +// Builds a chronological log by walking events in order and emitting +// one LogLine per tool invocation (at result time, or at call time if +// still in-flight) plus lifecycle events. Inserts thinking lines to +// represent gaps between visible events where the LLM is reasoning. +function buildChronologicalLog(events: AuditEvent[], count: number): LogLine[] { + const pendingCalls = new Map }>(); + const lines: LogLine[] = []; + let thinkingStartTs: string | null = null; + // Index of the last thinking line pushed to `lines`. Thinking events fire + // AFTER the turn's tool_result (message_update is a post-turn event), so the + // text belongs to the PREVIOUS thinking gap, not the current one. We + // retroactively set body on the already-emitted line. + let lastThinkingIdx = -1; + let phaseEnded = false; + + for (const e of events) { + if (e.kind === "heartbeat" || e.kind === "usage") continue; + if (e.kind === "confidence_change" || e.kind === "iteration_start") continue; + + if (e.kind === "thinking") { + // Retroactive: this text is from the turn that just completed. + // Overwrite (not append) -- later message_update events have more + // complete content, so the last one wins. + if (lastThinkingIdx >= 0) { + lines[lastThinkingIdx].body = e.text; + } + continue; + } + + if (e.kind === "tool_call") { + // Before a visible tool_call, insert a completed thinking line if gap >= 1s + if (e.tool !== "koan_complete_step" && thinkingStartTs) { + const gapMs = new Date(e.ts).getTime() - new Date(thinkingStartTs).getTime(); + if (gapMs >= 1000) { + lines.push({ + tool: "thinking", + summary: formatThinkingDuration(gapMs), + highValue: false, + inFlight: false, + }); + lastThinkingIdx = lines.length - 1; + } + thinkingStartTs = null; + } + pendingCalls.set(e.toolCallId, { tool: e.tool, input: e.input }); + continue; + } + + if (e.kind === "tool_result") { + if (e.tool === "koan_complete_step") { + pendingCalls.delete(e.toolCallId); + continue; + } + const call = pendingCalls.get(e.toolCallId); + lines.push(formatPairedResult(e, call?.input ?? {})); + pendingCalls.delete(e.toolCallId); + thinkingStartTs = e.ts; + continue; + } + + if ( + e.kind === "phase_start" || + e.kind === "step_transition" || + e.kind === "phase_end" + ) { + // Flush any pending thinking gap before the lifecycle line. + if (thinkingStartTs) { + const gapMs = new Date(e.ts).getTime() - new Date(thinkingStartTs).getTime(); + if (gapMs >= 1000) { + lines.push({ + tool: "thinking", + summary: formatThinkingDuration(gapMs), + highValue: false, + inFlight: false, + }); + lastThinkingIdx = lines.length - 1; + } + thinkingStartTs = null; + } + if (e.kind === "phase_end") phaseEnded = true; + lines.push(formatLifecycleEvent(e)); + thinkingStartTs = e.ts; + } + } + + // Currently-thinking indicator: all tools completed, phase still running + if (thinkingStartTs && pendingCalls.size === 0 && !phaseEnded) { + lines.push({ + tool: "thinking", + summary: "", + highValue: false, + inFlight: true, + ts: thinkingStartTs, + }); + } + + // Emit remaining calls without results as in-flight lines. + for (const [, call] of pendingCalls) { + if (call.tool === "koan_complete_step") continue; + lines.push(formatInFlightCall(call.tool, call.input)); + } + + return lines.slice(-count); +} diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts index a952284..4b22c5e 100644 --- a/src/planner/lib/audit.ts +++ b/src/planner/lib/audit.ts @@ -1,987 +1,13 @@ -// Audit trail for subagent sessions: event-sourced append log (events.jsonl) -// with an eagerly materialized projection (state.json) for parent polling. -// fold() is pure so the projection can be replayed from the raw log for testing. +// Barrel re-export: preserves import paths for callers outside lib/. +// Real implementations live in the four sub-modules: +// audit-events.ts -- event type definitions (no I/O) +// audit-fold.ts -- pure fold/correlate/summarize (no I/O) +// event-log.ts -- EventLog class, extractors, readProjection +// audit-log-formatter.ts -- LogLine formatters for the web UI // -// Tool invocations are captured as two events: tool_call (request) and -// tool_result (response), correlated by toolCallId. The flat event stream -// can be reduced into ToolInvocation[] via correlateTools() for paired access. +// Internal lib/ imports should target the specific sub-module directly. -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -// -- Types -- - -export interface EventBase { - ts: string; - seq: number; -} - -// -- Tool events -- -// Every tool invocation produces a (tool_call, tool_result) pair in the log. -// tool_call fires when the LLM requests the tool; tool_result fires when -// the tool returns. Both carry toolCallId for correlation. - -export interface ToolCallEvent extends EventBase { - kind: "tool_call"; - toolCallId: string; - tool: string; - input: Record; -} - -export interface ToolResultEvent extends EventBase { - kind: "tool_result"; - toolCallId: string; - tool: string; - error: boolean; - // Summarized output metrics (not the full content — too large for the log). - lines?: number; - chars?: number; - // Koan tool response text preserved for projection (completionSummary, etc.). - koanResponse?: string[]; -} - -// -- Lifecycle events -- - -export interface PhaseStartEvent extends EventBase { - kind: "phase_start"; - phase: string; - role: string; - model?: string | null; - totalSteps: number; -} - -export interface StepTransitionEvent extends EventBase { - kind: "step_transition"; - step: number; - name: string; - totalSteps: number; -} - -export interface PhaseEndEvent extends EventBase { - kind: "phase_end"; - outcome: "completed" | "failed"; - detail?: string; -} - -export interface HeartbeatEvent extends EventBase { - kind: "heartbeat"; -} - -export interface UsageEvent extends EventBase { - kind: "usage"; - input: number; - output: number; - cacheRead: number; - cacheWrite: number; -} - -export interface ThinkingEvent extends EventBase { - kind: "thinking"; - // Truncated thinking content (first 2000 chars for log size). - text: string; - // Original length before truncation. - chars: number; -} - -export interface ConfidenceChangeEvent extends EventBase { - kind: "confidence_change"; - // The confidence level declared by the intake agent via koan_set_confidence. - level: "exploring" | "low" | "medium" | "high" | "certain"; - // Which iteration of the Scout→Deliberate→Reflect loop this was declared in. - iteration: number; -} - -export interface IterationStartEvent extends EventBase { - kind: "iteration_start"; - // The new iteration number (incremented from the previous Reflect step). - iteration: number; - // Maximum allowed iterations before the loop is forced to exit. - maxIterations: number; -} - -export type AuditEvent = - | ToolCallEvent - | ToolResultEvent - | PhaseStartEvent - | StepTransitionEvent - | PhaseEndEvent - | HeartbeatEvent - | UsageEvent - | ThinkingEvent - | ConfidenceChangeEvent - | IterationStartEvent; - -// Distributive Omit — distributes over union members so object literals -// with fields specific to one member are accepted. -type DistributiveOmit = T extends unknown ? Omit : never; -export type AuditEventPartial = DistributiveOmit; - -// -- Projection -- -// Eagerly materialized state summary. Written atomically to state.json -// after every event so the parent (web server) can poll cheaply. - -export interface Projection { - role: string; - phase: string; - model: string | null; - status: "running" | "completed" | "failed"; - step: number; - totalSteps: number; - stepName: string; - lastAction: string | null; - // toolCallId of the currently in-flight tool, null when idle. - // Lets the UI distinguish "doing X" from "done with X". - currentToolCallId: string | null; - updatedAt: string; - eventCount: number; - error: string | null; - completionSummary: string | null; - tokensSent: number; - tokensReceived: number; - // Timestamp of the most recent tool_result event; used to track thinking gaps. - lastToolResultAt: string | null; - // Intake-specific: the most recent confidence level declared by koan_set_confidence. - // Null for non-intake subagents or before any confidence is declared. - intakeConfidence: "exploring" | "low" | "medium" | "high" | "certain" | null; - // Intake-specific: the current loop iteration (1-based). Zero for non-intake. - intakeIteration: number; -} - -// -- Correlated tool invocations -- -// Reduced view of paired (tool_call, tool_result) events. - -export interface ToolInvocation { - toolCallId: string; - tool: string; - input: Record; - callTs: string; - resultTs: string | null; - error: boolean | null; - inFlight: boolean; - durationMs: number | null; - // Output metrics from the result event. - lines?: number; - chars?: number; - koanResponse?: string[]; -} - -// Reduces a flat event stream into paired tool invocations. -// In-flight tools (call without result) have inFlight=true, resultTs=null. -export function correlateTools(events: AuditEvent[]): ToolInvocation[] { - const byId = new Map(); - const ordered: ToolInvocation[] = []; - - for (const e of events) { - if (e.kind === "tool_call") { - const inv: ToolInvocation = { - toolCallId: e.toolCallId, - tool: e.tool, - input: e.input, - callTs: e.ts, - resultTs: null, - error: null, - inFlight: true, - durationMs: null, - }; - byId.set(e.toolCallId, inv); - ordered.push(inv); - } else if (e.kind === "tool_result") { - const inv = byId.get(e.toolCallId); - if (inv) { - inv.resultTs = e.ts; - inv.error = e.error; - inv.inFlight = false; - inv.durationMs = new Date(e.ts).getTime() - new Date(inv.callTs).getTime(); - inv.lines = e.lines; - inv.chars = e.chars; - inv.koanResponse = e.koanResponse; - } - // Orphan result (no matching call) — can happen if the subagent - // started before tool_call hooking was added. Silently skip. - } - } - - return ordered; -} - -// -- Pi event shapes (subset we consume) -- - -interface PiToolCallEvent { - toolCallId: string; - toolName: string; - input: Record; -} - -interface PiToolResultEvent { - toolCallId: string; - toolName: string; - input: Record; - content: Array<{ type: string; text?: string }>; - isError: boolean; -} - -// -- Constants -- - -const FILE_TOOLS = new Set(["read", "edit", "write"]); -const HEARTBEAT_MS = 10_000; - -// -- Helpers -- - -function now(): string { - return new Date().toISOString(); -} - -// -- Extractors -- -// Transform pi's raw hook events into our audit event types. -// ts/seq are placeholders — EventLog.append() overwrites them. - -export function extractToolCall(piEvent: PiToolCallEvent): ToolCallEvent { - return { - kind: "tool_call", - toolCallId: piEvent.toolCallId, - tool: piEvent.toolName, - input: piEvent.input, - ts: now(), - seq: 0, - }; -} - -export function extractToolResult(piEvent: PiToolResultEvent): ToolResultEvent { - const { toolCallId, toolName, input, content, isError } = piEvent; - - const ev: ToolResultEvent = { - kind: "tool_result", - toolCallId, - tool: toolName, - error: isError, - ts: now(), - seq: 0, - }; - - // Capture output size for file and bash tools. - if (FILE_TOOLS.has(toolName) && !isError) { - const text = content.find((c) => c.type === "text")?.text ?? ""; - ev.lines = text.split("\n").length; - ev.chars = text.length; - } else if (toolName === "bash") { - const text = content.find((c) => c.type === "text")?.text ?? ""; - ev.lines = text.split("\n").length; - ev.chars = text.length; - } - - // Preserve koan tool response text for projection use (completionSummary). - if (toolName.startsWith("koan_")) { - ev.koanResponse = content - .filter((c) => c.type === "text" && c.text !== undefined) - .map((c) => c.text as string); - } - - return ev; -} - -// -- Summarize -- -// Human-readable one-liner from a tool invocation. -// Uses input (from call) + output metrics (from result) when available. - -export function summarizeInvocation(inv: ToolInvocation): string { - const { tool, input } = inv; - - // Tool name / key input identifier. - let label: string; - if (FILE_TOOLS.has(tool)) { - label = `${tool} ${(input["path"] as string | undefined) ?? ""}`; - } else if (tool === "bash") { - const cmd = (input["command"] as string | undefined) ?? ""; - label = `bash ${cmd.trim().split(/\s+/)[0] ?? ""}`; - } else { - label = tool; - } - - // Append output metrics if result has landed. - if (!inv.inFlight && (inv.lines != null || inv.chars != null)) { - const lines = inv.lines ?? 0; - const chars = inv.chars ?? 0; - label += ` · ${lines}L/${formatChars(chars)}`; - } - - return label; -} - -// Summarize from a ToolCallEvent alone (in-flight, no result yet). -function summarizeCall(e: ToolCallEvent): string { - if (FILE_TOOLS.has(e.tool)) { - return `${e.tool} ${(e.input["path"] as string | undefined) ?? ""}`; - } - if (e.tool === "bash") { - const cmd = (e.input["command"] as string | undefined) ?? ""; - return `bash ${cmd.trim().split(/\s+/)[0] ?? ""}`; - } - return e.tool; -} - -// Summarize from a ToolResultEvent alone (used in fold when call was missed). -function summarizeResult(e: ToolResultEvent): string { - let label = e.tool; - if (e.lines != null || e.chars != null) { - label += ` · ${e.lines ?? 0}L/${formatChars(e.chars ?? 0)}`; - } - return label; -} - -// -- Fold -- -// Pure projection update — one case per discriminated kind. -// All branches update updatedAt and increment eventCount. - -export function fold(s: Projection, e: AuditEvent): Projection { - const base = { ...s, updatedAt: e.ts, eventCount: s.eventCount + 1 }; - - switch (e.kind) { - case "phase_start": - return { - ...base, - role: e.role, - phase: e.phase, - model: e.model ?? s.model, - status: "running", - step: 0, - totalSteps: e.totalSteps, - stepName: "", - lastAction: null, - currentToolCallId: null, - error: null, - completionSummary: null, - }; - - case "step_transition": - return { - ...base, - step: e.step, - totalSteps: e.totalSteps, - stepName: `Step ${e.step}/${e.totalSteps}: ${e.name}`, - }; - - case "phase_end": - return { - ...base, - status: e.outcome, - error: e.detail ?? null, - currentToolCallId: null, - }; - - case "tool_call": { - const updated: Projection = { - ...base, - lastAction: summarizeCall(e), - currentToolCallId: e.toolCallId, - }; - // Extract completionSummary from koan_complete_step's thoughts param. - // The thoughts parameter is chain-of-thought, not task output (per - // AGENTS.md invariant), but we capture a prefix for the projection - // so the web UI can show scout summaries. - if (e.tool === "koan_complete_step" && typeof e.input?.thoughts === "string") { - updated.completionSummary = e.input.thoughts.slice(0, 500) || null; - } - return updated; - } - - case "tool_result": - return { - ...base, - lastAction: summarizeResult(e), - currentToolCallId: null, - lastToolResultAt: e.ts, - }; - - case "heartbeat": - return base; - - case "usage": - return { - ...base, - tokensSent: s.tokensSent + e.input, - tokensReceived: s.tokensReceived + e.output, - }; - - case "thinking": - return base; - - case "confidence_change": - return { - ...base, - intakeConfidence: e.level, - intakeIteration: e.iteration, - }; - - case "iteration_start": - return { - ...base, - intakeIteration: e.iteration, - }; - } -} - -// -- EventLog -- - -export class EventLog { - private readonly eventsPath: string; - private readonly statePath: string; - private readonly stateTmpPath: string; - private fd: fs.FileHandle | null = null; - private seq = 0; - private projection: Projection; - private heartbeat: ReturnType | null = null; - // Serializes append() calls. Heartbeat timer and tool_result handler - // both call append() concurrently — without serialization, two - // writeState() calls race on the shared tmp file (ENOENT on rename). - private pending: Promise = Promise.resolve(); - - constructor(dir: string, role: string, phase: string, model: string | null = null) { - this.eventsPath = path.join(dir, "events.jsonl"); - this.statePath = path.join(dir, "state.json"); - this.stateTmpPath = path.join(dir, "state.tmp.json"); - this.projection = { - role, - phase, - model, - status: "running", - step: 0, - totalSteps: 0, - stepName: "", - lastAction: null, - currentToolCallId: null, - updatedAt: now(), - eventCount: 0, - error: null, - completionSummary: null, - tokensSent: 0, - tokensReceived: 0, - lastToolResultAt: null, - intakeConfidence: null, - intakeIteration: 0, - }; - } - - async open(): Promise { - this.fd = await fs.open(this.eventsPath, "a"); - await this.writeState(); - // Heartbeat keeps updatedAt fresh even during long-running steps. - this.heartbeat = setInterval(() => { - void this.append({ kind: "heartbeat" } as Omit); - }, HEARTBEAT_MS); - } - - // Assigns ts + seq, appends JSON line, folds, writes state atomically. - // Serialized: concurrent callers queue behind the in-flight write. - async append(partial: AuditEventPartial): Promise { - const task = () => this.doAppend(partial); - this.pending = this.pending.then(task, task); - return this.pending; - } - - private async doAppend(partial: AuditEventPartial): Promise { - if (!this.fd) { - throw new Error("EventLog.append called before open()"); - } - - const e = { ...partial, ts: now(), seq: this.seq++ } as AuditEvent; - await this.fd.write(JSON.stringify(e) + "\n"); - this.projection = fold(this.projection, e); - await this.writeState(); - } - - async emitPhaseStart(totalSteps: number): Promise { - await this.append({ - kind: "phase_start", - phase: this.projection.phase, - role: this.projection.role, - model: this.projection.model, - totalSteps, - } as Omit); - } - - async emitStepTransition(step: number, name: string, totalSteps: number): Promise { - await this.append({ - kind: "step_transition", - step, - name, - totalSteps, - } as Omit); - } - - async emitPhaseEnd(outcome: "completed" | "failed", detail?: string): Promise { - await this.append({ - kind: "phase_end", - outcome, - detail, - } as Omit); - } - - async emitConfidenceChange(level: ConfidenceChangeEvent["level"], iteration: number): Promise { - await this.append({ - kind: "confidence_change", - level, - iteration, - } as Omit); - } - - async emitIterationStart(iteration: number, maxIterations: number): Promise { - await this.append({ - kind: "iteration_start", - iteration, - maxIterations, - } as Omit); - } - - async close(): Promise { - if (this.heartbeat) { - clearInterval(this.heartbeat); - this.heartbeat = null; - } - if (this.fd) { - await this.fd.close(); - this.fd = null; - } - } - - get state(): Readonly { - return this.projection; - } - - // Atomic write: tmp file then rename so readers never see partial JSON. - private async writeState(): Promise { - const json = JSON.stringify(this.projection, null, 2) + "\n"; - await fs.writeFile(this.stateTmpPath, json); - await fs.rename(this.stateTmpPath, this.statePath); - } -} - -// -- Exports -- - -// Reads state.json as a Projection; returns null if missing or malformed. -// Used by web server polling loop. -export async function readProjection(dir: string): Promise { - try { - const raw = await fs.readFile(path.join(dir, "state.json"), "utf8"); - return JSON.parse(raw) as Projection; - } catch { - return null; - } -} - -// -- Log formatting -- -// Structured log lines for the web UI activity feed. - -export interface LogLine { - tool: string; - summary: string; - highValue: boolean; - inFlight: boolean; - details?: string[]; - // Timestamp used by thinking entries to drive the live elapsed timer. - ts?: string; - // Expandable content body: thinking text, tool output, etc. - body?: string; - // Structured scout data for koan_request_scouts cards. - scouts?: Array<{ id: string; role: string }>; -} - -interface ToolShape { - keys: string[]; - arrays?: string[]; - freeform?: string[]; - getter?: boolean; - highValue?: boolean; -} - -const PREVIEW_CHARS = 40; -const KEY_PRIORITY = ["id", "story_id", "milestone", "decision_ref", "intent_ref", "file", "path", "phase"]; - -const KOAN_SHAPES: Record = { - koan_select_story: { keys: ["story_id"], highValue: true }, - koan_complete_story: { keys: ["story_id"], highValue: true }, - koan_retry_story: { keys: ["story_id", "failure_summary"], freeform: ["failure_summary"], highValue: true }, - koan_skip_story: { keys: ["story_id", "reason"], freeform: ["reason"], highValue: true }, - koan_ask_question: { - keys: ["id", "question", "context", "options", "multi", "recommended"], - arrays: ["options"], - freeform: ["question", "context"], - highValue: true, - }, - koan_request_scouts: { keys: [], highValue: true }, -}; - -// Reads events.jsonl, correlates tool pairs, and returns structured log entries. -// Filters out heartbeats, usage, and koan_complete_step (noisy). -export async function readRecentLogs(dir: string, count = 8): Promise { - try { - const raw = await fs.readFile(path.join(dir, "events.jsonl"), "utf8"); - const events = raw - .trimEnd() - .split("\n") - .filter(Boolean) - .map((line) => JSON.parse(line) as AuditEvent); - - return buildChronologicalLog(events, count); - } catch { - return []; - } -} - -// Builds a chronological log by walking events in order and emitting -// one LogLine per tool invocation (at result time, or at call time if -// still in-flight) plus lifecycle events. Inserts thinking lines to -// represent gaps between visible events where the LLM is reasoning. -function buildChronologicalLog(events: AuditEvent[], count: number): LogLine[] { - const pendingCalls = new Map }>(); - const lines: LogLine[] = []; - let thinkingStartTs: string | null = null; - // Index of the last thinking line pushed to `lines`. Thinking events fire - // AFTER the turn's tool_result (message_update is a post-turn event), so the - // text belongs to the PREVIOUS thinking gap, not the current one. We - // retroactively set body on the already-emitted line. - let lastThinkingIdx = -1; - let phaseEnded = false; - - for (const e of events) { - if (e.kind === "heartbeat" || e.kind === "usage") continue; - if (e.kind === "confidence_change" || e.kind === "iteration_start") continue; - - if (e.kind === "thinking") { - // Retroactive: this text is from the turn that just completed. - // Overwrite (not append) — later message_update events have more - // complete content, so the last one wins. - if (lastThinkingIdx >= 0) { - lines[lastThinkingIdx].body = e.text; - } - continue; - } - - if (e.kind === "tool_call") { - // Before a visible tool_call, insert a completed thinking line if gap ≥ 1s - if (e.tool !== "koan_complete_step" && thinkingStartTs) { - const gapMs = new Date(e.ts).getTime() - new Date(thinkingStartTs).getTime(); - if (gapMs >= 1000) { - lines.push({ - tool: "thinking", - summary: formatThinkingDuration(gapMs), - highValue: false, - inFlight: false, - }); - lastThinkingIdx = lines.length - 1; - } - thinkingStartTs = null; - } - pendingCalls.set(e.toolCallId, { tool: e.tool, input: e.input }); - continue; - } - - if (e.kind === "tool_result") { - if (e.tool === "koan_complete_step") { - pendingCalls.delete(e.toolCallId); - continue; - } - const call = pendingCalls.get(e.toolCallId); - lines.push(formatPairedResult(e, call?.input ?? {})); - pendingCalls.delete(e.toolCallId); - thinkingStartTs = e.ts; - continue; - } - - if ( - e.kind === "phase_start" || - e.kind === "step_transition" || - e.kind === "phase_end" - ) { - // Flush any pending thinking gap before the lifecycle line. - if (thinkingStartTs) { - const gapMs = new Date(e.ts).getTime() - new Date(thinkingStartTs).getTime(); - if (gapMs >= 1000) { - lines.push({ - tool: "thinking", - summary: formatThinkingDuration(gapMs), - highValue: false, - inFlight: false, - }); - lastThinkingIdx = lines.length - 1; - } - thinkingStartTs = null; - } - if (e.kind === "phase_end") phaseEnded = true; - lines.push(formatLifecycleEvent(e)); - thinkingStartTs = e.ts; - } - } - - // Currently-thinking indicator: all tools completed, phase still running - if (thinkingStartTs && pendingCalls.size === 0 && !phaseEnded) { - lines.push({ - tool: "thinking", - summary: "", - highValue: false, - inFlight: true, - ts: thinkingStartTs, - }); - } - - // Emit remaining calls without results as in-flight lines. - for (const [, call] of pendingCalls) { - if (call.tool === "koan_complete_step") continue; - lines.push(formatInFlightCall(call.tool, call.input)); - } - - return lines.slice(-count); -} - -// Format an in-flight tool_call (no result yet). Same structure as -// formatPairedResult but with inFlight: true and no output metrics. -function formatInFlightCall(tool: string, input: Record): LogLine { - if (FILE_TOOLS.has(tool)) { - return { - tool, - summary: (input["path"] as string | undefined) ?? "", - highValue: tool === "read", - inFlight: true, - }; - } - - if (tool === "bash") { - const cmd = (input["command"] as string | undefined) ?? ""; - const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; - return { tool: "bash", summary: bin, highValue: false, inFlight: true }; - } - - if (tool.startsWith("koan_")) { - const shape = KOAN_SHAPES[tool]; - if (shape) { - const inv: ToolInvocation = { - toolCallId: "", tool, input, - callTs: "", resultTs: null, - error: null, inFlight: true, durationMs: null, - }; - return formatKoanInvocation(inv); - } - } - - return { tool, summary: "", highValue: false, inFlight: true }; -} - -// -- Formatters -- - -function formatChars(chars: number): string { - if (chars < 1000) return `${chars}c`; - const k = chars / 1000; - if (k >= 10) return `${Math.round(k)}k`; - return `${k.toFixed(1)}k`; -} - -function textStats(text: string): string { - const lines = text.length === 0 ? 0 : text.split("\n").length; - return `${lines}L/${formatChars(text.length)}`; -} - -function responseSize(response: string[]): string { - return textStats(response.join("\n")); -} - -function formatThinkingDuration(ms: number): string { - const sec = Math.round(ms / 1000); - if (sec < 60) return `${sec}s`; - const min = Math.floor(sec / 60); - const remSec = sec % 60; - return remSec > 0 ? `${min}m ${remSec}s` : `${min}m`; -} - -function truncateUnicode(text: string, maxChars: number): string { - const chars = Array.from(text); - if (chars.length <= maxChars) return text; - return `${chars.slice(0, maxChars).join("")}…`; -} - -function inlineScalar(value: unknown): string { - if (typeof value === "string") { - return truncateUnicode(value.replace(/\r\n?|\n/gu, "\\n"), PREVIEW_CHARS); - } - if (typeof value === "number" || typeof value === "boolean") { - return String(value); - } - if (value === null) return "null"; - if (Array.isArray(value)) return `[${value.length}]`; - if (typeof value === "object") return "{…}"; - return String(value); -} - -function arrayPreview(value: unknown): string { - if (!Array.isArray(value) || value.length === 0) { - return "[]"; - } - const first = inlineScalar(value[0]); - if (value.length === 1) { - return `[${first}]`; - } - return `[${first}] +${value.length - 1}`; -} - -function freeformSize(value: unknown): string { - if (typeof value === "string") { - return textStats(value); - } - const json = JSON.stringify(value); - return textStats(json ?? String(value)); -} - -function hasKey(input: Record, key: string): boolean { - return Object.prototype.hasOwnProperty.call(input, key); -} - -function orderedShapeKeys(keys: string[]): string[] { - const indexed = keys.map((key, index) => ({ key, index })); - indexed.sort((a, b) => { - const pa = KEY_PRIORITY.indexOf(a.key); - const pb = KEY_PRIORITY.indexOf(b.key); - const ra = pa === -1 ? Number.MAX_SAFE_INTEGER : pa; - const rb = pb === -1 ? Number.MAX_SAFE_INTEGER : pb; - if (ra !== rb) return ra - rb; - return a.index - b.index; - }); - return indexed.map((x) => x.key); -} - -// Format a completed tool invocation from its correlated pair. -function formatToolInvocation(inv: ToolInvocation): LogLine { - if (inv.tool.startsWith("koan_")) { - return formatKoanInvocation(inv); - } - - if (FILE_TOOLS.has(inv.tool)) { - const p = (inv.input["path"] as string | undefined) ?? ""; - const suffix = inv.lines != null ? ` · ${inv.lines}L/${formatChars(inv.chars ?? 0)}` : ""; - return { - tool: inv.tool, - summary: `${p}${suffix}`, - highValue: inv.tool === "read", - inFlight: inv.inFlight, - }; - } - - if (inv.tool === "bash") { - const cmd = (inv.input["command"] as string | undefined) ?? ""; - const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; - const suffix = inv.lines != null ? ` · ${inv.lines}L/${formatChars(inv.chars ?? 0)}` : ""; - return { - tool: "bash", - summary: `${bin}${suffix}`, - highValue: false, - inFlight: inv.inFlight, - }; - } - - return { tool: inv.tool, summary: "", highValue: false, inFlight: inv.inFlight }; -} - -function formatKoanInvocation(inv: ToolInvocation): LogLine { - const shape = KOAN_SHAPES[inv.tool]; - if (!shape) { - return { tool: inv.tool, summary: "", highValue: false, inFlight: inv.inFlight }; - } - - const arrayKeys = new Set(shape.arrays ?? []); - const freeformKeys = new Set(shape.freeform ?? []); - const chunks: string[] = []; - - for (const key of orderedShapeKeys(shape.keys)) { - if (!hasKey(inv.input, key)) continue; - const value = inv.input[key]; - - if (arrayKeys.has(key)) { - chunks.push(`${key}:${arrayPreview(value)}`); - continue; - } - if (freeformKeys.has(key)) { - chunks.push(`${key}:${freeformSize(value)}`); - continue; - } - chunks.push(`${key}=${inlineScalar(value)}`); - } - - if (shape.getter && inv.koanResponse) { - if (chunks.length === 0) { - chunks.push("scope=plan"); - } - chunks.push(`resp:${responseSize(inv.koanResponse)}`); - } - - const line: LogLine = { - tool: inv.tool, - summary: chunks.join(" · "), - highValue: shape.highValue ?? chunks.length >= 3, - inFlight: inv.inFlight, - }; - - // Structured scout data for the UI card. - if (inv.tool === "koan_request_scouts" && Array.isArray(inv.input["scouts"])) { - line.scouts = (inv.input["scouts"] as Array>).map( - (s) => ({ id: String(s["id"] ?? "?"), role: String(s["role"] ?? "agent") }), - ); - } - - return line; -} - -// Format a tool_result event paired with its call's input. -function formatPairedResult(e: ToolResultEvent, input: Record): LogLine { - if (FILE_TOOLS.has(e.tool)) { - const p = (input["path"] as string | undefined) ?? ""; - const suffix = e.lines != null ? ` · ${e.lines}L/${formatChars(e.chars ?? 0)}` : ""; - return { - tool: e.tool, - summary: `${p}${suffix}`, - highValue: e.tool === "read", - inFlight: false, - }; - } - - if (e.tool === "bash") { - const cmd = (input["command"] as string | undefined) ?? ""; - const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; - const suffix = e.lines != null ? ` · ${e.lines}L/${formatChars(e.chars ?? 0)}` : ""; - return { - tool: "bash", - summary: `${bin}${suffix}`, - highValue: false, - inFlight: false, - }; - } - - if (e.tool.startsWith("koan_")) { - const shape = KOAN_SHAPES[e.tool]; - if (shape) { - // Rebuild invocation-like object for the koan formatter. - const inv: ToolInvocation = { - toolCallId: e.toolCallId, - tool: e.tool, - input, - callTs: e.ts, - resultTs: e.ts, - error: e.error, - inFlight: false, - durationMs: null, - koanResponse: e.koanResponse, - }; - return formatKoanInvocation(inv); - } - return { tool: e.tool, summary: "", highValue: false, inFlight: false }; - } - - return { tool: e.tool, summary: "", highValue: false, inFlight: false }; -} - -function formatLifecycleEvent(e: PhaseStartEvent | StepTransitionEvent | PhaseEndEvent): LogLine { - switch (e.kind) { - case "phase_start": - return { tool: "phase", summary: `${e.phase} (${e.totalSteps} steps)`, highValue: false, inFlight: false }; - case "step_transition": - return { tool: `step ${e.step}/${e.totalSteps}`, summary: e.name, highValue: false, inFlight: false }; - case "phase_end": - return { tool: "phase", summary: e.detail ? `${e.outcome} · ${e.detail}` : e.outcome, highValue: false, inFlight: false }; - } -} +export * from "./audit-events.js"; +export * from "./audit-fold.js"; +export * from "./event-log.js"; +export * from "./audit-log-formatter.js"; diff --git a/src/planner/lib/event-log.ts b/src/planner/lib/event-log.ts new file mode 100644 index 0000000..00a3317 --- /dev/null +++ b/src/planner/lib/event-log.ts @@ -0,0 +1,242 @@ +// EventLog class: file I/O, heartbeat, serialization, and emit helpers. +// Extractors transform pi hook events into AuditEvent types. + +import { promises as fs } from "node:fs"; +import * as path from "node:path"; +import type { + AuditEvent, + AuditEventPartial, + HeartbeatEvent, + PhaseStartEvent, + StepTransitionEvent, + PhaseEndEvent, + ConfidenceChangeEvent, + IterationStartEvent, + Projection, + ToolCallEvent, + ToolResultEvent, +} from "./audit-events.js"; +import { fold } from "./audit-fold.js"; + +// -- Pi event shapes (subset we consume) -- + +interface PiToolCallEvent { + toolCallId: string; + toolName: string; + input: Record; +} + +interface PiToolResultEvent { + toolCallId: string; + toolName: string; + input: Record; + content: Array<{ type: string; text?: string }>; + isError: boolean; +} + +// -- Constants -- + +const FILE_TOOLS = new Set(["read", "edit", "write"]); +const HEARTBEAT_MS = 10_000; + +// -- Helpers -- + +function now(): string { + return new Date().toISOString(); +} + +// -- Extractors -- +// Transform pi's raw hook events into our audit event types. +// ts/seq are placeholders -- EventLog.append() overwrites them. + +export function extractToolCall(piEvent: PiToolCallEvent): ToolCallEvent { + return { + kind: "tool_call", + toolCallId: piEvent.toolCallId, + tool: piEvent.toolName, + input: piEvent.input, + ts: now(), + seq: 0, + }; +} + +export function extractToolResult(piEvent: PiToolResultEvent): ToolResultEvent { + const { toolCallId, toolName, input, content, isError } = piEvent; + + const ev: ToolResultEvent = { + kind: "tool_result", + toolCallId, + tool: toolName, + error: isError, + ts: now(), + seq: 0, + }; + + // Capture output size for file and bash tools. + if (FILE_TOOLS.has(toolName) && !isError) { + const text = content.find((c) => c.type === "text")?.text ?? ""; + ev.lines = text.split("\n").length; + ev.chars = text.length; + } else if (toolName === "bash") { + const text = content.find((c) => c.type === "text")?.text ?? ""; + ev.lines = text.split("\n").length; + ev.chars = text.length; + } + + // Preserve koan tool response text for projection use (completionSummary). + if (toolName.startsWith("koan_")) { + ev.koanResponse = content + .filter((c) => c.type === "text" && c.text !== undefined) + .map((c) => c.text as string); + } + + return ev; +} + +// -- EventLog -- + +export class EventLog { + private readonly eventsPath: string; + private readonly statePath: string; + private readonly stateTmpPath: string; + private fd: fs.FileHandle | null = null; + private seq = 0; + private projection: Projection; + private heartbeat: ReturnType | null = null; + // Serializes append() calls. Heartbeat timer and tool_result handler + // both call append() concurrently -- without serialization, two + // writeState() calls race on the shared tmp file (ENOENT on rename). + private pending: Promise = Promise.resolve(); + + constructor(dir: string, role: string, phase: string, model: string | null = null) { + this.eventsPath = path.join(dir, "events.jsonl"); + this.statePath = path.join(dir, "state.json"); + this.stateTmpPath = path.join(dir, "state.tmp.json"); + this.projection = { + role, + phase, + model, + status: "running", + step: 0, + totalSteps: 0, + stepName: "", + lastAction: null, + currentToolCallId: null, + updatedAt: now(), + eventCount: 0, + error: null, + completionSummary: null, + tokensSent: 0, + tokensReceived: 0, + lastToolResultAt: null, + intakeConfidence: null, + intakeIteration: 0, + }; + } + + async open(): Promise { + this.fd = await fs.open(this.eventsPath, "a"); + await this.writeState(); + // Heartbeat keeps updatedAt fresh even during long-running steps. + this.heartbeat = setInterval(() => { + void this.append({ kind: "heartbeat" } as Omit); + }, HEARTBEAT_MS); + } + + // Assigns ts + seq, appends JSON line, folds, writes state atomically. + // Serialized: concurrent callers queue behind the in-flight write. + async append(partial: AuditEventPartial): Promise { + const task = () => this.doAppend(partial); + this.pending = this.pending.then(task, task); + return this.pending; + } + + private async doAppend(partial: AuditEventPartial): Promise { + if (!this.fd) { + throw new Error("EventLog.append called before open()"); + } + + const e = { ...partial, ts: now(), seq: this.seq++ } as AuditEvent; + await this.fd.write(JSON.stringify(e) + "\n"); + this.projection = fold(this.projection, e); + await this.writeState(); + } + + async emitPhaseStart(totalSteps: number): Promise { + await this.append({ + kind: "phase_start", + phase: this.projection.phase, + role: this.projection.role, + model: this.projection.model, + totalSteps, + } as Omit); + } + + async emitStepTransition(step: number, name: string, totalSteps: number): Promise { + await this.append({ + kind: "step_transition", + step, + name, + totalSteps, + } as Omit); + } + + async emitPhaseEnd(outcome: "completed" | "failed", detail?: string): Promise { + await this.append({ + kind: "phase_end", + outcome, + detail, + } as Omit); + } + + async emitConfidenceChange(level: ConfidenceChangeEvent["level"], iteration: number): Promise { + await this.append({ + kind: "confidence_change", + level, + iteration, + } as Omit); + } + + async emitIterationStart(iteration: number, maxIterations: number): Promise { + await this.append({ + kind: "iteration_start", + iteration, + maxIterations, + } as Omit); + } + + async close(): Promise { + if (this.heartbeat) { + clearInterval(this.heartbeat); + this.heartbeat = null; + } + if (this.fd) { + await this.fd.close(); + this.fd = null; + } + } + + get state(): Readonly { + return this.projection; + } + + // Atomic write: tmp file then rename so readers never see partial JSON. + private async writeState(): Promise { + const json = JSON.stringify(this.projection, null, 2) + "\n"; + await fs.writeFile(this.stateTmpPath, json); + await fs.rename(this.stateTmpPath, this.statePath); + } +} + +// -- Exports -- + +// Reads state.json as a Projection; returns null if missing or malformed. +// Used by web server polling loop. +export async function readProjection(dir: string): Promise { + try { + const raw = await fs.readFile(path.join(dir, "state.json"), "utf8"); + return JSON.parse(raw) as Projection; + } catch { + return null; + } +} diff --git a/src/planner/lib/runtime-context.ts b/src/planner/lib/runtime-context.ts index 1138f88..f700249 100644 --- a/src/planner/lib/runtime-context.ts +++ b/src/planner/lib/runtime-context.ts @@ -21,7 +21,7 @@ // before_agent_start after the log file is opened. Tools that need to emit // audit events (e.g. koan_set_confidence) read this at call time. -import type { EventLog } from "./audit.js"; +import type { EventLog } from "./event-log.js"; export interface RuntimeContext { epicDir: string | null; From 2586b8fa36e3e3e52e98f526c4a989b8efda05d3 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Sat, 21 Mar 2026 15:53:35 +0700 Subject: [PATCH 080/412] T3 spawnTracked + pollIpc (10 files) --- extensions/koan.ts | 22 +++-- src/planner/driver.ts | 122 ++++++++++--------------- src/planner/lib/ipc.ts | 63 +++++++++++++ src/planner/model-config.ts | 70 +++++++++----- src/planner/phases/decomposer/phase.ts | 2 - src/planner/phases/dispatch.ts | 5 +- src/planner/phases/intake/phase.ts | 3 +- src/planner/phases/scout/phase.ts | 3 +- src/planner/tools/ask.ts | 86 ++++------------- src/planner/web/server-types.ts | 30 ++++-- 10 files changed, 208 insertions(+), 198 deletions(-) diff --git a/extensions/koan.ts b/extensions/koan.ts index 33da64b..bbc0584 100644 --- a/extensions/koan.ts +++ b/extensions/koan.ts @@ -34,16 +34,18 @@ function currentModelId(ctx: ExtensionContext): string | null { return `${model.provider}/${model.id}`; } -// Registers infrastructure-level event handlers that must be in place before -// before_agent_start fires. Currently this is only the truncation override, -// but the wrapper makes the ordering constraint visible at the call site. -// -// Why before before_agent_start? The audit tool_result handler registers -// inside before_agent_start. The truncation override must precede it so the -// audit handler sees the original event, not the replacement content we -// return. Calling this function immediately after registerAllTools (and -// before the dispatched guard) makes the ordering structural rather than -// relying on a comment buried inside registerTruncationOverride's impl. +/** + * Registers infrastructure-level event handlers that must be in place before + * `before_agent_start` fires. + * + * **Ordering contract:** call immediately after `registerAllTools` and before + * the `before_agent_start` dispatch guard. The audit system's `tool_result` + * handler is registered inside `before_agent_start`; the truncation override + * installed here must precede it so the audit handler observes the original + * event rather than the replacement content we return. Placing this call + * structurally before `before_agent_start` makes the constraint positional + * rather than implicit. + */ function registerInfrastructureHandlers(pi: ExtensionAPI): void { registerTruncationOverride(pi); } diff --git a/src/planner/driver.ts b/src/planner/driver.ts index f5c9035..ef3e5e4 100644 --- a/src/planner/driver.ts +++ b/src/planner/driver.ts @@ -20,7 +20,8 @@ import { ensureStoryDirectory, discoverStoryIds, } from "./epic/state.js"; -import { spawnSubagent, type SpawnOptions } from "./subagent.js"; +import { spawnSubagent, type SpawnOptions, type SubagentResult } from "./subagent.js"; +import type { SubagentTask } from "./lib/task.js"; import type { Logger } from "../utils/logger.js"; import type { StoryState } from "./epic/types.js"; import type { WebServerHandle, ReviewStory } from "./web/server-types.js"; @@ -83,6 +84,38 @@ function routeFromState(stories: StoryState[], log: Logger): RoutingDecision { }; } +// --------------------------------------------------------------------------- +// spawnTracked +// --------------------------------------------------------------------------- + +/** + * Owns the web-server lifecycle (register -> track -> spawn -> clear -> complete) + * for a single subagent invocation. + * + * Does not own story status transitions -- those remain in the callers + * (runStoryExecution, runStoryReexecution). + * + * Full DI of spawnSubagent is out of scope: driver.ts is an entry point, + * exempt from the "no hard-coded dependencies" rule per project conventions. + */ +async function spawnTracked( + id: string, + name: string, + role: string, + task: SubagentTask, + dir: string, + storyId: string | undefined, + opts: SpawnOptions, + webServer: WebServerHandle | null, +): Promise { + webServer?.registerAgent({ id, name, dir, role, model: null, parent: null }); + webServer?.trackSubagent(dir, role, storyId); + const result = await spawnSubagent(task, dir, opts); + webServer?.clearSubagent(); + webServer?.completeAgent(id); + return result; +} + // --------------------------------------------------------------------------- // Phase A helpers // --------------------------------------------------------------------------- @@ -95,17 +128,8 @@ async function runIntake( webServer: WebServerHandle | null, ): Promise { const subagentDir = await ensureSubagentDirectory(epicDir, "intake"); - webServer?.registerAgent({ id: "intake", name: "intake", dir: subagentDir, role: "intake", model: null, parent: null }); - webServer?.trackSubagent(subagentDir, "intake"); - - const result = await spawnSubagent( - { role: "intake", epicDir }, - subagentDir, - { cwd, extensionPath, log, webServer: webServer ?? undefined }, - ); - - webServer?.clearSubagent(); - webServer?.completeAgent("intake"); + const opts: SpawnOptions = { cwd, extensionPath, log, webServer: webServer ?? undefined }; + const result = await spawnTracked("intake", "intake", "intake", { role: "intake", epicDir }, subagentDir, undefined, opts, webServer); if (result.exitCode !== 0) { log("Intake failed", { exitCode: result.exitCode }); return false; @@ -121,17 +145,8 @@ async function runDecomposer( webServer: WebServerHandle | null, ): Promise { const subagentDir = await ensureSubagentDirectory(epicDir, "decomposer"); - webServer?.registerAgent({ id: "decomposer", name: "decomposer", dir: subagentDir, role: "decomposer", model: null, parent: null }); - webServer?.trackSubagent(subagentDir, "decomposer"); - - const result = await spawnSubagent( - { role: "decomposer", epicDir }, - subagentDir, - { cwd, extensionPath, log, webServer: webServer ?? undefined }, - ); - - webServer?.clearSubagent(); - webServer?.completeAgent("decomposer"); + const opts: SpawnOptions = { cwd, extensionPath, log, webServer: webServer ?? undefined }; + const result = await spawnTracked("decomposer", "decomposer", "decomposer", { role: "decomposer", epicDir }, subagentDir, undefined, opts, webServer); if (result.exitCode !== 0) { log("Decomposer failed", { exitCode: result.exitCode }); return false; @@ -160,13 +175,7 @@ async function runStoryExecution( // 2. Spawn planner. const plannerDir = await ensureSubagentDirectory(epicDir, `planner-${storyId}`); const plannerId = `planner-${storyId}`; - webServer?.registerAgent({ id: plannerId, name: `planner-${storyId}`, dir: plannerDir, role: "planner", model: null, parent: null }); - webServer?.trackSubagent(plannerDir, "planner", storyId); - - const planResult = await spawnSubagent({ role: "planner", epicDir, storyId }, plannerDir, opts); - - webServer?.clearSubagent(); - webServer?.completeAgent(plannerId); + const planResult = await spawnTracked(plannerId, `planner-${storyId}`, "planner", { role: "planner", epicDir, storyId }, plannerDir, storyId, opts, webServer); if (planResult.exitCode !== 0) { // Planner failed — skip executor, proceed directly to post-execution @@ -180,13 +189,7 @@ async function runStoryExecution( const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}`); const postId = `orchestrator-post-${storyId}`; - webServer?.registerAgent({ id: postId, name: `orchestrator-post-${storyId}`, dir: postDir, role: "orchestrator", model: null, parent: null }); - webServer?.trackSubagent(postDir, "orchestrator", storyId); - - await spawnSubagent({ role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, opts); - - webServer?.clearSubagent(); - webServer?.completeAgent(postId); + await spawnTracked(postId, `orchestrator-post-${storyId}`, "orchestrator", { role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, storyId, opts, webServer); return; } @@ -197,13 +200,7 @@ async function runStoryExecution( // 4. Spawn executor. const execDir = await ensureSubagentDirectory(epicDir, `executor-${storyId}`); const execId = `executor-${storyId}`; - webServer?.registerAgent({ id: execId, name: `executor-${storyId}`, dir: execDir, role: "executor", model: null, parent: null }); - webServer?.trackSubagent(execDir, "executor", storyId); - - const execResult = await spawnSubagent({ role: "executor", epicDir, storyId }, execDir, opts); - - webServer?.clearSubagent(); - webServer?.completeAgent(execId); + const execResult = await spawnTracked(execId, `executor-${storyId}`, "executor", { role: "executor", epicDir, storyId }, execDir, storyId, opts, webServer); if (execResult.exitCode !== 0) { log("Executor failed", { storyId, exitCode: execResult.exitCode }); @@ -216,13 +213,7 @@ async function runStoryExecution( // 6. Spawn orchestrator (post-execution). const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}`); const postId = `orchestrator-post-${storyId}`; - webServer?.registerAgent({ id: postId, name: `orchestrator-post-${storyId}`, dir: postDir, role: "orchestrator", model: null, parent: null }); - webServer?.trackSubagent(postDir, "orchestrator", storyId); - - await spawnSubagent({ role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, opts); - - webServer?.clearSubagent(); - webServer?.completeAgent(postId); + await spawnTracked(postId, `orchestrator-post-${storyId}`, "orchestrator", { role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, storyId, opts, webServer); } async function runStoryReexecution( @@ -239,28 +230,16 @@ async function runStoryReexecution( const execDir = await ensureSubagentDirectory(epicDir, `executor-${storyId}-retry-${retryCount}`); const execId = `executor-${storyId}-retry-${retryCount}`; - webServer?.registerAgent({ id: execId, name: `executor-${storyId}-retry-${retryCount}`, dir: execDir, role: "executor", model: null, parent: null }); - webServer?.trackSubagent(execDir, "executor", storyId); - // retryContext flows from koan_retry_story's failure_summary into the task // manifest, where the executor reads it from step 1 guidance. - await spawnSubagent({ role: "executor", epicDir, storyId, retryContext: failureContext }, execDir, opts); - - webServer?.clearSubagent(); - webServer?.completeAgent(execId); + await spawnTracked(execId, `executor-${storyId}-retry-${retryCount}`, "executor", { role: "executor", epicDir, storyId, retryContext: failureContext }, execDir, storyId, opts, webServer); const story = await loadStoryState(epicDir, storyId); await saveStoryState(epicDir, storyId, { ...story, status: "verifying", updatedAt: new Date().toISOString() }); const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}-retry-${retryCount}`); const postId = `orchestrator-post-${storyId}-retry-${retryCount}`; - webServer?.registerAgent({ id: postId, name: `orchestrator-post-${storyId}-retry-${retryCount}`, dir: postDir, role: "orchestrator", model: null, parent: null }); - webServer?.trackSubagent(postDir, "orchestrator", storyId); - - await spawnSubagent({ role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, opts); - - webServer?.clearSubagent(); - webServer?.completeAgent(postId); + await spawnTracked(postId, `orchestrator-post-${storyId}-retry-${retryCount}`, "orchestrator", { role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, storyId, opts, webServer); } async function refreshWebServerStories(epicDir: string, webServer: WebServerHandle): Promise { @@ -283,17 +262,8 @@ async function runStoryLoop( // 1. Spawn orchestrator (pre-execution) — selects first story. const preDir = await ensureSubagentDirectory(epicDir, "orchestrator-pre"); const preId = "orchestrator-pre"; - webServer?.registerAgent({ id: preId, name: "orchestrator-pre", dir: preDir, role: "orchestrator", model: null, parent: null }); - webServer?.trackSubagent(preDir, "orchestrator"); - - const preResult = await spawnSubagent( - { role: "orchestrator", epicDir, stepSequence: "pre-execution" }, - preDir, - { cwd, extensionPath, log, webServer: webServer ?? undefined }, - ); - - webServer?.clearSubagent(); - webServer?.completeAgent(preId); + const opts: SpawnOptions = { cwd, extensionPath, log, webServer: webServer ?? undefined }; + const preResult = await spawnTracked(preId, "orchestrator-pre", "orchestrator", { role: "orchestrator", epicDir, stepSequence: "pre-execution" }, preDir, undefined, opts, webServer); if (preResult.exitCode !== 0) { return { success: false, summary: "Pre-execution orchestrator failed" }; diff --git a/src/planner/lib/ipc.ts b/src/planner/lib/ipc.ts index 25298ef..be23d0e 100644 --- a/src/planner/lib/ipc.ts +++ b/src/planner/lib/ipc.ts @@ -154,3 +154,66 @@ export function createCancelledResponse(requestId: string): AskResponse { payload: null, }; } + +// -- Poll helper -- + +function sleep(ms: number): Promise { + return new Promise((resolve) => setTimeout(resolve, ms)); +} + +/** Outcome of a single pollIpcUntilResponse call. */ +export type PollOutcome = "answered" | "cancelled" | "aborted" | "file-gone" | "completed"; + +/** Return value of pollIpcUntilResponse: outcome tag + the IPC file snapshot (if any). */ +export interface PollIpcResult { + outcome: PollOutcome; + ipc: IpcFile | null; +} + +/** + * Poll ipc.json until a response appears, the signal aborts, or the file vanishes. + * + * Extracted because executeAskQuestion and executeRequestScouts share identical + * poll logic. The finally block guarantees ipc.json deletion even when the signal + * aborts mid-poll -- without it, a stale ipc.json would block the next tool call. + */ +export async function pollIpcUntilResponse( + dir: string, + ipc: IpcFile, + signal?: AbortSignal | null, +): Promise { + let aborted = false; + const onAbort = () => { aborted = true; }; + if (signal) signal.addEventListener("abort", onAbort, { once: true }); + + let outcome: PollOutcome = "file-gone"; + let finalIpc: IpcFile | null = null; + + try { + while (!aborted) { + await sleep(500); + if (signal?.aborted) { aborted = true; break; } + + const current = await readIpcFile(dir); + if (current === null) { outcome = "file-gone"; break; } + + if (current.type === "ask" && current.response !== null && current.response.id === ipc.id) { + outcome = current.response.cancelled ? "cancelled" : "answered"; + finalIpc = current; + break; + } + + if (current.type === "scout-request" && current.response !== null && current.id === ipc.id) { + outcome = "completed"; + finalIpc = current; + break; + } + } + + if (aborted) outcome = "aborted"; + } finally { + await deleteIpcFile(dir); + } + + return { outcome, ipc: finalIpc }; +} diff --git a/src/planner/model-config.ts b/src/planner/model-config.ts index 403a7c5..2025bf3 100644 --- a/src/planner/model-config.ts +++ b/src/planner/model-config.ts @@ -16,28 +16,22 @@ export const CONFIG_PATH = path.join(os.homedir(), ".koan", "config.json"); export type ModelTierConfig = Record; +export interface KoanConfig { + modelTiers: ModelTierConfig | null; + scoutConcurrency: number; +} + interface KoanConfigFile { modelTiers?: Record; scoutConcurrency?: number; [key: string]: unknown; } -export async function loadModelTierConfig(): Promise { - let raw: string; - try { - raw = await fs.readFile(CONFIG_PATH, "utf8"); - } catch { - return null; - } +// -- Private helpers -------------------------------------------------------- - let parsed: KoanConfigFile; - try { - parsed = JSON.parse(raw) as KoanConfigFile; - } catch { - log("config.json is not valid JSON; treating model tier config as absent."); - return null; - } +const DEFAULT_SCOUT_CONCURRENCY = 8; +function parseModelTiers(parsed: KoanConfigFile): ModelTierConfig | null { if (!parsed.modelTiers || typeof parsed.modelTiers !== "object") { return null; } @@ -74,21 +68,47 @@ export async function loadModelTierConfig(): Promise { return result as ModelTierConfig; } -// -- Scout concurrency ------------------------------------------------------- +function parseScoutConcurrency(parsed: KoanConfigFile): number { + if (typeof parsed.scoutConcurrency === "number" && parsed.scoutConcurrency > 0) { + return parsed.scoutConcurrency; + } + return DEFAULT_SCOUT_CONCURRENCY; +} -const DEFAULT_SCOUT_CONCURRENCY = 8; +// -- Public loaders --------------------------------------------------------- -export async function loadScoutConcurrency(): Promise { +export async function loadKoanConfig(): Promise { + const defaults: KoanConfig = { modelTiers: null, scoutConcurrency: DEFAULT_SCOUT_CONCURRENCY }; + + let raw: string; try { - const raw = await fs.readFile(CONFIG_PATH, "utf8"); - const parsed = JSON.parse(raw) as KoanConfigFile; - if (typeof parsed.scoutConcurrency === "number" && parsed.scoutConcurrency > 0) { - return parsed.scoutConcurrency; - } + raw = await fs.readFile(CONFIG_PATH, "utf8"); } catch { - // File missing or invalid — use default. + return defaults; } - return DEFAULT_SCOUT_CONCURRENCY; + + let parsed: KoanConfigFile; + try { + parsed = JSON.parse(raw) as KoanConfigFile; + } catch { + log("config.json is not valid JSON; treating config as absent."); + return defaults; + } + + return { + modelTiers: parseModelTiers(parsed), + scoutConcurrency: parseScoutConcurrency(parsed), + }; +} + +export async function loadModelTierConfig(): Promise { + return (await loadKoanConfig()).modelTiers; +} + +// -- Scout concurrency ------------------------------------------------------ + +export async function loadScoutConcurrency(): Promise { + return (await loadKoanConfig()).scoutConcurrency; } export async function saveScoutConcurrency(concurrency: number): Promise { @@ -110,7 +130,7 @@ export async function saveScoutConcurrency(concurrency: number): Promise { await fs.rename(tmpPath, CONFIG_PATH); } -// -- Model tiers (save) ------------------------------------------------------ +// -- Model tiers (save) ----------------------------------------------------- export async function saveModelTierConfig(config: ModelTierConfig): Promise { const configDir = path.dirname(CONFIG_PATH); diff --git a/src/planner/phases/decomposer/phase.ts b/src/planner/phases/decomposer/phase.ts index b5ab322..c443803 100644 --- a/src/planner/phases/decomposer/phase.ts +++ b/src/planner/phases/decomposer/phase.ts @@ -16,13 +16,11 @@ export class DecomposerPhase extends BasePhase { constructor( pi: ExtensionAPI, - config: { epicDir: string }, ctx: RuntimeContext, log?: Logger, eventLog?: EventLog, ) { super(pi, ctx, log ?? createLogger("DecomposerPhase"), eventLog); - void config; } protected getSystemPrompt(): string { diff --git a/src/planner/phases/dispatch.ts b/src/planner/phases/dispatch.ts index 5bc63f5..7036410 100644 --- a/src/planner/phases/dispatch.ts +++ b/src/planner/phases/dispatch.ts @@ -28,7 +28,7 @@ export async function dispatchPhase( switch (task.role) { case "intake": { - const phase = new IntakePhase(pi, { epicDir: task.epicDir }, ctx, logger, eventLog); + const phase = new IntakePhase(pi, ctx, logger, eventLog); await phase.begin(); break; } @@ -37,7 +37,6 @@ export async function dispatchPhase( // outputFile is relative to subagentDir in the task manifest. // ScoutPhase receives the resolved absolute path. const phase = new ScoutPhase(pi, { - epicDir: task.epicDir, question: task.question, outputFile: path.join(ctx.subagentDir!, task.outputFile), investigatorRole: task.investigatorRole, @@ -47,7 +46,7 @@ export async function dispatchPhase( } case "decomposer": { - const phase = new DecomposerPhase(pi, { epicDir: task.epicDir }, ctx, logger, eventLog); + const phase = new DecomposerPhase(pi, ctx, logger, eventLog); await phase.begin(); break; } diff --git a/src/planner/phases/intake/phase.ts b/src/planner/phases/intake/phase.ts index f7becf0..3812be0 100644 --- a/src/planner/phases/intake/phase.ts +++ b/src/planner/phases/intake/phase.ts @@ -53,13 +53,12 @@ export class IntakePhase extends BasePhase { constructor( pi: ExtensionAPI, - config: { epicDir: string }, ctx: RuntimeContext, log?: Logger, eventLog?: EventLog, ) { super(pi, ctx, log ?? createLogger("IntakePhase"), eventLog); - this.conversationPath = path.join(config.epicDir, "conversation.jsonl"); + this.conversationPath = path.join(ctx.epicDir!, "conversation.jsonl"); } protected getSystemPrompt(): string { diff --git a/src/planner/phases/scout/phase.ts b/src/planner/phases/scout/phase.ts index ed193b5..e67e2e9 100644 --- a/src/planner/phases/scout/phase.ts +++ b/src/planner/phases/scout/phase.ts @@ -22,13 +22,12 @@ export class ScoutPhase extends BasePhase { constructor( pi: ExtensionAPI, - config: { epicDir: string; question: string; outputFile: string; investigatorRole: string }, + config: { question: string; outputFile: string; investigatorRole: string }, ctx: RuntimeContext, log?: Logger, eventLog?: EventLog, ) { super(pi, ctx, log ?? createLogger("ScoutPhase"), eventLog); - void config.epicDir; // used via ctx.epicDir for permission scoping this.question = config.question; this.outputFile = config.outputFile; this.investigatorRole = config.investigatorRole; diff --git a/src/planner/tools/ask.ts b/src/planner/tools/ask.ts index 9039142..8b722fd 100644 --- a/src/planner/tools/ask.ts +++ b/src/planner/tools/ask.ts @@ -15,11 +15,12 @@ import type { RuntimeContext } from "../lib/runtime-context.js"; import { ipcFileExists, writeIpcFile, - readIpcFile, - deleteIpcFile, createAskRequest, createScoutRequest, + pollIpcUntilResponse, type AskAnswerPayload, + type AskIpcFile, + type ScoutIpcFile, type ScoutRequest, } from "../lib/ipc.js"; @@ -151,12 +152,6 @@ function buildQuestionResult( }; } -// -- Shared poll helper -- - -function sleep(ms: number): Promise { - return new Promise((resolve) => setTimeout(resolve, ms)); -} - // -- Tool registration -- const ASK_TOOL_DESCRIPTION = ` @@ -210,39 +205,13 @@ export async function executeAskQuestion( const ipc = createAskRequest(params); await writeIpcFile(dir, ipc); - let aborted = false; - const onAbort = () => { aborted = true; }; - if (signal) signal.addEventListener("abort", onAbort, { once: true }); - - type PollResult = "answered" | "cancelled" | "aborted" | "file-gone"; - let pollResult: PollResult = "file-gone"; - let answeredPayload: AskAnswerPayload | null = null; - - try { - while (!aborted) { - await sleep(500); - if (signal?.aborted) { aborted = true; break; } - - const current = await readIpcFile(dir); - if (current === null) { pollResult = "file-gone"; break; } - - if (current.type === "ask" && current.response !== null && current.response.id === ipc.id) { - if (current.response.cancelled) { - pollResult = "cancelled"; - } else { - pollResult = "answered"; - answeredPayload = current.response.payload; - } - break; - } - } - - if (aborted) pollResult = "aborted"; - } finally { - await deleteIpcFile(dir); - } + const { outcome, ipc: answeredIpc } = await pollIpcUntilResponse(dir, ipc, signal); + const answeredPayload: AskAnswerPayload | null = + outcome === "answered" && answeredIpc?.type === "ask" + ? (answeredIpc as AskIpcFile).response?.payload ?? null + : null; - switch (pollResult) { + switch (outcome) { case "answered": { const result = buildQuestionResult(params, answeredPayload); return { @@ -261,6 +230,7 @@ export async function executeAskQuestion( details: undefined, }; case "file-gone": + default: return { content: [{ type: "text" as const, text: "The question was cancelled." }], details: undefined, @@ -292,38 +262,13 @@ export async function executeRequestScouts( const ipc = createScoutRequest(params.scouts as ScoutRequest[]); await writeIpcFile(dir, ipc); - let aborted = false; - const onAbort = () => { aborted = true; }; - if (signal) signal.addEventListener("abort", onAbort, { once: true }); - - type PollResult = "completed" | "aborted" | "file-gone"; - let pollResult: PollResult = "file-gone"; - let findings: string[] = []; - let failures: string[] = []; - - try { - while (!aborted) { - await sleep(500); - if (signal?.aborted) { aborted = true; break; } - - const current = await readIpcFile(dir); - if (current === null) { pollResult = "file-gone"; break; } - - if (current.type === "scout-request" && current.response !== null && current.id === ipc.id) { - pollResult = "completed"; - findings = current.response.findings; - failures = current.response.failures; - break; - } - } - - if (aborted) pollResult = "aborted"; - } finally { - await deleteIpcFile(dir); - } + const { outcome, ipc: completedIpc } = await pollIpcUntilResponse(dir, ipc, signal); - switch (pollResult) { + switch (outcome) { case "completed": { + const scoutIpc = completedIpc as ScoutIpcFile; + const findings = scoutIpc.response!.findings; + const failures = scoutIpc.response!.failures; const sections: string[] = [ `Scout findings: ${findings.length} completed, ${failures.length} failed.`, "", @@ -353,6 +298,7 @@ export async function executeRequestScouts( details: undefined, }; case "file-gone": + default: return { content: [{ type: "text" as const, text: "Scout request cancelled. Proceed without codebase context." }], details: undefined, diff --git a/src/planner/web/server-types.ts b/src/planner/web/server-types.ts index 21971f3..6094c9e 100644 --- a/src/planner/web/server-types.ts +++ b/src/planner/web/server-types.ts @@ -233,17 +233,30 @@ export interface WebServerHandle { readonly url: string; readonly port: number; - // Push methods (fire-and-forget, SSE) + // --------------------------------------------------------------------------- + // Concern 1 -- Push / SSE (fire-and-forget, no response expected) + // pushPhase, pushStories, pushLogs, pushNotification + // + // Concern 2 -- Agent lifecycle / observation + // registerAgent, startAgent, completeAgent, trackSubagent, clearSubagent + // + // Concern 3 -- Blocking human input (returns a Promise that resolves when the + // user responds; must be called with an AbortSignal for cancellation) + // requestReview, requestAnswer, requestModelConfig + // + // Note: this interface conflates three unrelated responsibilities. A future + // split into three narrower interfaces (PushHandle, AgentHandle, InputHandle) + // would allow callers to depend only on what they use. The split is deferred + // because it requires updating all call sites in driver.ts and koan.ts. + // --------------------------------------------------------------------------- + + // Concern 1 -- Push / SSE pushPhase(phase: EpicPhase): void; pushStories(stories: Array<{ storyId: string; status: StoryStatus }>): void; pushLogs(lines: LogLine[], currentToolCallId?: string | null): void; pushNotification(message: string, level: "info" | "warning" | "error"): void; - // Observation polling (replaces startActivePolling) - trackSubagent(dir: string, role: string, storyId?: string): void; - clearSubagent(): void; - - // Agent registration for the flat table + // Concern 2 -- Agent lifecycle / observation registerAgent(info: { id: string; name: string; @@ -255,12 +268,13 @@ export interface WebServerHandle { }): void; startAgent(id: string): void; completeAgent(id: string): void; + trackSubagent(dir: string, role: string, storyId?: string): void; + clearSubagent(): void; - // Blocking input methods + // Concern 3 -- Blocking human input requestReview(stories: ReviewStory[], signal?: AbortSignal): Promise; requestAnswer(question: AskQuestion, signal: AbortSignal): Promise; requestModelConfig(): Promise; - // Lifecycle close(): void; } From 8ad5cd0280e37f41e48fb1ad20c2a1c0ad102954 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Sat, 21 Mar 2026 17:03:18 +0700 Subject: [PATCH 081/412] T3+T4 complete; T6 JSDoc ordering fix --- src/planner/web/server.ts | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/planner/web/server.ts b/src/planner/web/server.ts index 1c522d4..bd0d1d2 100644 --- a/src/planner/web/server.ts +++ b/src/planner/web/server.ts @@ -13,7 +13,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent"; import { readProjection, readRecentLogs } from "../lib/audit.js"; -import { loadModelTierConfig, saveModelTierConfig, loadScoutConcurrency, saveScoutConcurrency, type ModelTierConfig } from "../model-config.js"; +import { loadKoanConfig, loadModelTierConfig, saveModelTierConfig, saveScoutConcurrency, type ModelTierConfig } from "../model-config.js"; import type { WebServerHandle, AskQuestion, @@ -828,9 +828,8 @@ export async function startWebServer(epicDir: string): Promise async requestModelConfig(): Promise { const requestId = randomUUID(); - const config = await loadModelTierConfig(); - const scoutConcurrency = await loadScoutConcurrency(); - const payload = { requestId, tiers: config, scoutConcurrency, availableModels }; + const { modelTiers, scoutConcurrency } = await loadKoanConfig(); + const payload = { requestId, tiers: modelTiers, scoutConcurrency, availableModels }; return new Promise((resolve, reject) => { pendingInputs.set(requestId, { type: "model-config" as const, From 2631f1aeb25667c6d5d27dbb4bf5df661092f295 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Sat, 21 Mar 2026 18:37:18 +0700 Subject: [PATCH 082/412] add marked dependency for client-side markdown rendering --- package-lock.json | 38 ++++++++++++++++++++++++++++++++------ package.json | 3 ++- 2 files changed, 34 insertions(+), 7 deletions(-) diff --git a/package-lock.json b/package-lock.json index cd93c99..68b6b3b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,8 @@ "version": "0.0.1", "license": "Apache-2.0", "dependencies": { - "@sinclair/typebox": "^0.32.30" + "@sinclair/typebox": "^0.32.30", + "marked": "^17.0.5" }, "devDependencies": { "@mariozechner/pi-coding-agent": "^0.52.10", @@ -1605,6 +1606,19 @@ "@mariozechner/clipboard": "^0.3.2" } }, + "node_modules/@mariozechner/pi-coding-agent/node_modules/marked": { + "version": "15.0.12", + "resolved": "https://registry.npmjs.org/marked/-/marked-15.0.12.tgz", + "integrity": "sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==", + "dev": true, + "license": "MIT", + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 18" + } + }, "node_modules/@mariozechner/pi-tui": { "version": "0.52.10", "resolved": "https://registry.npmjs.org/@mariozechner/pi-tui/-/pi-tui-0.52.10.tgz", @@ -1622,6 +1636,19 @@ "node": ">=20.0.0" } }, + "node_modules/@mariozechner/pi-tui/node_modules/marked": { + "version": "15.0.12", + "resolved": "https://registry.npmjs.org/marked/-/marked-15.0.12.tgz", + "integrity": "sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==", + "dev": true, + "license": "MIT", + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 18" + } + }, "node_modules/@mistralai/mistralai": { "version": "1.10.0", "resolved": "https://registry.npmjs.org/@mistralai/mistralai/-/mistralai-1.10.0.tgz", @@ -3443,16 +3470,15 @@ } }, "node_modules/marked": { - "version": "15.0.12", - "resolved": "https://registry.npmjs.org/marked/-/marked-15.0.12.tgz", - "integrity": "sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==", - "dev": true, + "version": "17.0.5", + "resolved": "https://registry.npmjs.org/marked/-/marked-17.0.5.tgz", + "integrity": "sha512-6hLvc0/JEbRjRgzI6wnT2P1XuM1/RrrDEX0kPt0N7jGm1133g6X7DlxFasUIx+72aKAr904GTxhSLDrd5DIlZg==", "license": "MIT", "bin": { "marked": "bin/marked.js" }, "engines": { - "node": ">= 18" + "node": ">= 20" } }, "node_modules/mime-db": { diff --git a/package.json b/package.json index a7f9e41..34c67c5 100644 --- a/package.json +++ b/package.json @@ -30,7 +30,8 @@ "test": "node --test --test-concurrency=1 build/tests" }, "dependencies": { - "@sinclair/typebox": "^0.32.30" + "@sinclair/typebox": "^0.32.30", + "marked": "^17.0.5" }, "devDependencies": { "@mariozechner/pi-coding-agent": "^0.52.10", From 18aa2fbe710b6b45ec645d583ef14609a9c85932 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Sat, 21 Mar 2026 18:37:26 +0700 Subject: [PATCH 083/412] add artifact-review IPC types, poll support, and koan_review_artifact tool --- src/planner/lib/ipc.ts | 47 +++++++++- src/planner/tools/review-artifact.ts | 129 +++++++++++++++++++++++++++ 2 files changed, 172 insertions(+), 4 deletions(-) create mode 100644 src/planner/tools/review-artifact.ts diff --git a/src/planner/lib/ipc.ts b/src/planner/lib/ipc.ts index be23d0e..53b1c7a 100644 --- a/src/planner/lib/ipc.ts +++ b/src/planner/lib/ipc.ts @@ -2,9 +2,10 @@ // A single ipc.json file per subagent directory holds the current request and // its response. Atomic writes (tmp-rename) prevent partial reads. // -// IPC protocol supports two message types (§11.2.4): -// "ask" — subagent asks the user a question -// "scout-request" — subagent requests parallel codebase scout spawning +// IPC protocol supports three message types (§11.2.4): +// "ask" — subagent asks the user a question +// "scout-request" — subagent requests parallel codebase scout spawning +// "artifact-review" — subagent presents a written artifact for human review import { promises as fs } from "node:fs"; import * as path from "node:path"; @@ -48,6 +49,20 @@ export interface AskResponse { payload: AskAnswerPayload | null; } +// -- Artifact review types -- + +export interface ArtifactReviewPayload { + artifactPath: string; // relative path within epic dir (e.g., "brief.md") + content: string; // raw markdown content of the artifact + description?: string; // optional context for the reviewer +} + +export interface ArtifactReviewResponse { + id: string; + respondedAt: string; + feedback: string; // "Accept" or free-form text +} + // -- IPC file union -- export interface AskIpcFile { @@ -66,7 +81,15 @@ export interface ScoutIpcFile { response: ScoutResponse | null; } -export type IpcFile = AskIpcFile | ScoutIpcFile; +export interface ArtifactReviewIpcFile { + type: "artifact-review"; + id: string; + createdAt: string; + payload: ArtifactReviewPayload; + response: ArtifactReviewResponse | null; +} + +export type IpcFile = AskIpcFile | ScoutIpcFile | ArtifactReviewIpcFile; // -- File paths -- @@ -137,6 +160,16 @@ export function createScoutRequest(scouts: ScoutRequest[]): ScoutIpcFile { }; } +export function createArtifactReviewRequest(payload: ArtifactReviewPayload): ArtifactReviewIpcFile { + return { + type: "artifact-review", + id: crypto.randomUUID(), + createdAt: new Date().toISOString(), + payload, + response: null, + }; +} + export function createAskResponse(requestId: string, payload: AskAnswerPayload): AskResponse { return { id: requestId, @@ -208,6 +241,12 @@ export async function pollIpcUntilResponse( finalIpc = current; break; } + + if (current.type === "artifact-review" && current.response !== null && current.id === ipc.id) { + outcome = "answered"; + finalIpc = current; + break; + } } if (aborted) outcome = "aborted"; diff --git a/src/planner/tools/review-artifact.ts b/src/planner/tools/review-artifact.ts new file mode 100644 index 0000000..0ceb272 --- /dev/null +++ b/src/planner/tools/review-artifact.ts @@ -0,0 +1,129 @@ +// IPC-based tool: koan_review_artifact. +// Presents a written markdown artifact for human review via file-based IPC, +// pausing subagent execution until the user responds with feedback or accepts. +// +// The review loop is LLM-driven: if the user provides feedback, the LLM revises +// the artifact and invokes this tool again. The tool itself is stateless — it +// reads the artifact, presents it, and returns the user's response verbatim. + +import { promises as fs } from "node:fs"; + +import { Type, type Static } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +import type { RuntimeContext } from "../lib/runtime-context.js"; +import { + ipcFileExists, + writeIpcFile, + createArtifactReviewRequest, + pollIpcUntilResponse, + type ArtifactReviewIpcFile, +} from "../lib/ipc.js"; + +// -- Schema -- + +const ReviewArtifactSchema = Type.Object({ + path: Type.String({ description: "File path of the artifact to present for review" }), + description: Type.Optional(Type.String({ description: "Optional context for the reviewer (e.g. 'This is the epic brief')" })), +}); + +type ReviewArtifactParams = Static; + +// -- Tool description -- + +const REVIEW_ARTIFACT_DESCRIPTION = ` +Present a written artifact (markdown file) for human review and collect feedback. + +Use this after writing an artifact file to get human approval before proceeding. + +The user will see the rendered artifact content and can either: +- Accept it — call koan_complete_step after receiving "Accept" +- Provide feedback — revise the artifact and call koan_review_artifact again + +Parameters: +- path: the file path of the artifact to review +- description: optional context for the reviewer +`.trim(); + +// -- Execute logic -- + +type ToolResult = { content: Array<{ type: "text"; text: string }>; details: undefined }; + +export async function executeReviewArtifact( + params: ReviewArtifactParams, + subagentDir: string | null, + signal?: AbortSignal | null, +): Promise { + const dir = subagentDir; + + if (!dir) { + return { + content: [{ type: "text" as const, text: "Error: koan_review_artifact is only available in subagent context." }], + details: undefined, + }; + } + + if (await ipcFileExists(dir)) { + return { + content: [{ type: "text" as const, text: "Error: An IPC request is already pending." }], + details: undefined, + }; + } + + let content: string; + try { + content = await fs.readFile(params.path, "utf8"); + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + return { + content: [{ type: "text" as const, text: `Error: Could not read artifact at "${params.path}": ${msg}` }], + details: undefined, + }; + } + + const ipc = createArtifactReviewRequest({ + artifactPath: params.path, + content, + description: params.description, + }); + await writeIpcFile(dir, ipc); + + const { outcome, ipc: answeredIpc } = await pollIpcUntilResponse(dir, ipc, signal); + + switch (outcome) { + case "answered": { + const artifactIpc = answeredIpc as ArtifactReviewIpcFile; + const feedback = artifactIpc.response?.feedback || "(no feedback)"; + return { + content: [{ type: "text" as const, text: `User feedback:\n${feedback}` }], + details: undefined, + }; + } + case "aborted": + return { + content: [{ type: "text" as const, text: "The review was aborted." }], + details: undefined, + }; + case "file-gone": + default: + return { + content: [{ type: "text" as const, text: "The review was cancelled." }], + details: undefined, + }; + } +} + +// -- Tool registration -- + +export function registerReviewArtifactTool(pi: ExtensionAPI, ctx: RuntimeContext): void { + pi.registerTool({ + name: "koan_review_artifact", + label: "Review artifact", + description: REVIEW_ARTIFACT_DESCRIPTION, + parameters: ReviewArtifactSchema, + + async execute(_toolCallId, params, signal) { + return executeReviewArtifact(params as ReviewArtifactParams, ctx.subagentDir, signal); + }, + }); +} From 4599566f3229dabdbd16c3a260ce5590947ad49b Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Sat, 21 Mar 2026 18:37:34 +0700 Subject: [PATCH 084/412] add artifact-review IPC responder and web server endpoints --- src/planner/lib/ipc-responder.ts | 52 +++++++++++++++++++++-- src/planner/web/server-types.ts | 22 +++++++++- src/planner/web/server.ts | 72 ++++++++++++++++++++++++++++++-- 3 files changed, 139 insertions(+), 7 deletions(-) diff --git a/src/planner/lib/ipc-responder.ts b/src/planner/lib/ipc-responder.ts index 7a7c6df..673e83d 100644 --- a/src/planner/lib/ipc-responder.ts +++ b/src/planner/lib/ipc-responder.ts @@ -2,9 +2,10 @@ // handles them, and writes responses back. Runs concurrently with subagent // process execution and terminates when the provided AbortSignal fires. // -// Supports two request types: -// "ask" → route to web server, write answer back -// "scout-request" → spawn scouts via pool(), write findings paths back +// Supports three request types: +// "ask" → route to web server, write answer back +// "scout-request" → spawn scouts via pool(), write findings paths back +// "artifact-review" → route to web server, write feedback back import { promises as fs } from "node:fs"; import * as path from "node:path"; @@ -17,6 +18,8 @@ import { type AskAnswerPayload, type AskIpcFile, type ScoutIpcFile, + type ArtifactReviewIpcFile, + type ArtifactReviewResponse, } from "./ipc.js"; import type { ScoutTask } from "./task.js"; import { pool } from "./pool.js"; @@ -110,6 +113,47 @@ async function handleAskRequest( } } +// Handles a pending artifact-review request: routes to web server, writes feedback. +async function handleArtifactReviewRequest( + subagentDir: string, + ipc: ArtifactReviewIpcFile, + webServer: WebServerHandle, + signal: AbortSignal, +): Promise { + const { payload } = ipc; + + let feedback: string; + try { + const result = await webServer.requestArtifactReview(payload, signal); + feedback = result.feedback; + } catch (err: unknown) { + if (err instanceof Error && (err.name === "AbortError" || signal.aborted)) { + const current = await readIpcFile(subagentDir); + if (current !== null && current.type === "artifact-review" && current.response === null && current.id === ipc.id) { + const cancelledResponse: ArtifactReviewResponse = { + id: ipc.id, + respondedAt: new Date().toISOString(), + feedback: "Review cancelled.", + }; + await writeIpcFile(subagentDir, { ...current, response: cancelledResponse }); + } + return; + } + throw err; + } + + const response: ArtifactReviewResponse = { + id: ipc.id, + respondedAt: new Date().toISOString(), + feedback, + }; + // Re-read and validate before writing — idempotence guard against stale requests. + const current = await readIpcFile(subagentDir); + if (current !== null && current.type === "artifact-review" && current.response === null && current.id === ipc.id) { + await writeIpcFile(subagentDir, { ...current, response }); + } +} + // Handles a pending scout-request: spawns scouts via pool(), writes findings. async function handleScoutRequest( subagentDir: string, @@ -220,6 +264,8 @@ export async function runIpcResponder( await handleAskRequest(subagentDir, ipc, webServer, signal); } else if (ipc.type === "scout-request" && scoutContext) { await handleScoutRequest(subagentDir, ipc, scoutContext, webServer, signal); + } else if (ipc.type === "artifact-review") { + await handleArtifactReviewRequest(subagentDir, ipc, webServer, signal); } } catch { // Swallow all errors — transient filesystem issues must not abort the parent session. diff --git a/src/planner/web/server-types.ts b/src/planner/web/server-types.ts index 6094c9e..4d0b8d5 100644 --- a/src/planner/web/server-types.ts +++ b/src/planner/web/server-types.ts @@ -3,6 +3,7 @@ import type { LogLine } from "../lib/audit.js"; import type { EpicPhase, StoryStatus } from "../types.js"; +import type { ArtifactReviewPayload } from "../lib/ipc.js"; export type { LogLine, EpicPhase, StoryStatus }; @@ -112,6 +113,24 @@ export interface AnswerResult { answer: AnswerElement; } +// --------------------------------------------------------------------------- +// Artifact review types +// --------------------------------------------------------------------------- + +export interface ArtifactReviewEvent { + requestId: string; + artifactPath: string; + content: string; // raw markdown + description?: string; +} + +export interface ArtifactReviewFeedback { + feedback: string; // "Accept" or free-form text +} + +// Re-export for use in ipc-responder.ts without double-importing ipc.ts +export type { ArtifactReviewPayload }; + // --------------------------------------------------------------------------- // SSE event payload types (server → browser) // --------------------------------------------------------------------------- @@ -242,7 +261,7 @@ export interface WebServerHandle { // // Concern 3 -- Blocking human input (returns a Promise that resolves when the // user responds; must be called with an AbortSignal for cancellation) - // requestReview, requestAnswer, requestModelConfig + // requestReview, requestAnswer, requestModelConfig, requestArtifactReview // // Note: this interface conflates three unrelated responsibilities. A future // split into three narrower interfaces (PushHandle, AgentHandle, InputHandle) @@ -275,6 +294,7 @@ export interface WebServerHandle { requestReview(stories: ReviewStory[], signal?: AbortSignal): Promise; requestAnswer(question: AskQuestion, signal: AbortSignal): Promise; requestModelConfig(): Promise; + requestArtifactReview(payload: ArtifactReviewPayload, signal: AbortSignal): Promise; close(): void; } diff --git a/src/planner/web/server.ts b/src/planner/web/server.ts index bd0d1d2..0b971d6 100644 --- a/src/planner/web/server.ts +++ b/src/planner/web/server.ts @@ -23,7 +23,9 @@ import type { AnswerElement, LogLine, IntakeProgressEvent, + ArtifactReviewFeedback, } from "./server-types.js"; +import type { ArtifactReviewPayload } from "../lib/ipc.js"; import type { EpicPhase, StoryStatus } from "../types.js"; // --------------------------------------------------------------------------- @@ -250,9 +252,9 @@ export async function startWebServer(epicDir: string): Promise // SSE clients const sseClients = new Set(); - // Pending inputs (requestReview / requestAnswer / requestModelConfig) + // Pending inputs (requestReview / requestAnswer / requestModelConfig / requestArtifactReview) interface PendingEntry { - type: "review" | "ask" | "model-config"; + type: "review" | "ask" | "model-config" | "artifact-review"; resolve: (result: unknown) => void; reject: (err: Error) => void; payload: unknown; @@ -316,6 +318,14 @@ export async function startWebServer(epicDir: string): Promise write("review", { requestId, stories: entry.payload }); } else if (entry.type === "model-config") { write("model-config", entry.payload); + } else if (entry.type === "artifact-review") { + const p = entry.payload as ArtifactReviewPayload; + write("artifact-review", { + requestId, + artifactPath: p.artifactPath, + content: p.content, + description: p.description, + }); } } @@ -382,7 +392,7 @@ export async function startWebServer(epicDir: string): Promise agent.tokensReceived = projection.tokensReceived; agent.eventCount = projection.eventCount; // Cache the latest projection so polling timers can read confidence/iteration - // without issuing a second readProjection call for the same agent. + // without issuing a second readProjection call for the same file in the same tick. agent.lastProjection = projection; if (projection.status !== "running") { agent.status = projection.status; @@ -616,6 +626,26 @@ export async function startWebServer(epicDir: string): Promise return; } + if (method === "POST" && pathname === "/api/artifact-review") { + const body = await readBody(req).catch(() => null); + const b = body as { token?: string; requestId?: string; feedback?: string } | null; + if (!b) { sendJson(res, 400, { ok: false, error: "Invalid body" }); return; } + if (b.token !== sessionToken) { sendJson(res, 403, { ok: false, error: "Invalid token" }); return; } + const { requestId, feedback } = b; + if (!requestId || typeof feedback !== "string" || feedback.trim() === "") { + sendJson(res, 400, { ok: false, error: "Missing requestId or feedback" }); return; + } + const pending = pendingInputs.get(requestId); + if (!pending || pending.type !== "artifact-review") { + sendJson(res, 409, { ok: false, error: "No pending artifact review with this requestId" }); return; + } + const artifactResult: ArtifactReviewFeedback = { feedback }; + pending.resolve(artifactResult); + pendingInputs.delete(requestId); + sendJson(res, 200, { ok: true }); + return; + } + if (method === "POST" && pathname === "/api/cancel") { const body = await readBody(req).catch(() => null); const b = body as { token?: string } | null; @@ -841,6 +871,42 @@ export async function startWebServer(epicDir: string): Promise }); }, + requestArtifactReview(payload: ArtifactReviewPayload, signal: AbortSignal): Promise { + return new Promise((res, rej) => { + const requestId = randomUUID(); + const abortHandler = () => { + pendingInputs.delete(requestId); + pushEvent("artifact-review-cancelled", { requestId }); + const err = new Error(`Artifact review cancelled: signal aborted`); + (err as NodeJS.ErrnoException).name = "AbortError"; + rej(err); + }; + pendingInputs.set(requestId, { + type: "artifact-review", + resolve: (result: unknown) => { + signal.removeEventListener("abort", abortHandler); + res(result as ArtifactReviewFeedback); + }, + reject: (err: Error) => { + signal.removeEventListener("abort", abortHandler); + rej(err); + }, + payload, + }); + pushEvent("artifact-review", { + requestId, + artifactPath: payload.artifactPath, + content: payload.content, + description: payload.description, + }); + if (signal.aborted) { + abortHandler(); + } else { + signal.addEventListener("abort", abortHandler, { once: true }); + } + }); + }, + close(): void { for (const [, entry] of pendingInputs) entry.reject(new Error("Server closed")); pendingInputs.clear(); From dfdf05091d4282631300b04dcd5989d12b24d563 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Sat, 21 Mar 2026 18:37:41 +0700 Subject: [PATCH 085/412] add ArtifactReview web UI component with markdown rendering --- src/planner/web/css/components.css | 102 ++++++++++++++++++ .../web/js/components/PhaseContent.jsx | 2 + .../js/components/forms/ArtifactReview.jsx | 81 ++++++++++++++ src/planner/web/js/sse.js | 38 ++++--- src/planner/web/js/store.js | 16 +++ 5 files changed, 222 insertions(+), 17 deletions(-) create mode 100644 src/planner/web/js/components/forms/ArtifactReview.jsx diff --git a/src/planner/web/css/components.css b/src/planner/web/css/components.css index 8d287f2..2194de4 100644 --- a/src/planner/web/css/components.css +++ b/src/planner/web/css/components.css @@ -861,3 +861,105 @@ .agent-doing-inflight { color: var(--text) !important; } + +/* ---- Artifact review ---- */ +.artifact-review-content { + background: var(--bg-surface); + border: 1px solid var(--border); + border-radius: var(--radius-md); + padding: var(--gap-lg); + overflow-y: auto; + max-height: 60vh; + margin-bottom: var(--gap-md); + font-family: var(--font-sans); + font-size: var(--font-size-md); + line-height: 1.7; + color: var(--text); +} + +.artifact-review-content h1, +.artifact-review-content h2, +.artifact-review-content h3, +.artifact-review-content h4 { + color: var(--text-strong); + margin-top: var(--gap-lg); + margin-bottom: var(--gap-sm); +} + +.artifact-review-content h1 { font-size: 1.4em; } +.artifact-review-content h2 { font-size: 1.2em; border-bottom: 1px solid var(--border); padding-bottom: 4px; } +.artifact-review-content h3 { font-size: 1.05em; } + +.artifact-review-content p { margin: var(--gap-sm) 0; } + +.artifact-review-content ul, +.artifact-review-content ol { + padding-left: var(--gap-lg); + margin: var(--gap-sm) 0; +} + +.artifact-review-content li { margin: 2px 0; } + +.artifact-review-content code { + background: var(--bg); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + padding: 1px 5px; + font-family: var(--font-mono); + font-size: 0.9em; +} + +.artifact-review-content pre { + background: var(--bg); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + padding: var(--gap-md); + overflow-x: auto; + margin: var(--gap-sm) 0; +} + +.artifact-review-content pre code { + background: none; + border: none; + padding: 0; + font-size: var(--font-size-sm); +} + +.artifact-review-content blockquote { + border-left: 3px solid var(--border); + padding-left: var(--gap-md); + color: var(--text-muted); + margin: var(--gap-sm) 0; +} + +.artifact-review-content strong { color: var(--text-strong); } + +.artifact-review-content a { + color: var(--blue); + text-decoration: underline; +} + +.artifact-review-feedback { + width: 100%; + min-height: 80px; + padding: var(--gap-sm) var(--gap-md); + background: var(--bg); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + color: var(--text); + font-family: var(--font-sans); + font-size: var(--font-size-md); + resize: vertical; + outline: none; + box-sizing: border-box; + margin-bottom: var(--gap-md); +} + +.artifact-review-feedback:focus { + border-color: var(--blue-border); +} + +.artifact-review-feedback::placeholder { + color: var(--text-dim); + font-style: italic; +} diff --git a/src/planner/web/js/components/PhaseContent.jsx b/src/planner/web/js/components/PhaseContent.jsx index d552837..db94923 100644 --- a/src/planner/web/js/components/PhaseContent.jsx +++ b/src/planner/web/js/components/PhaseContent.jsx @@ -3,6 +3,7 @@ import { Loading } from './phases/Loading.jsx' import { Completion } from './phases/Completion.jsx' import { QuestionForm } from './forms/QuestionForm.jsx' import { ReviewForm } from './forms/ReviewForm.jsx' +import { ArtifactReview } from './forms/ArtifactReview.jsx' import { ModelConfig } from './ModelConfig.jsx' export function PhaseContent({ token, topic }) { @@ -24,6 +25,7 @@ export function PhaseContent({ token, topic }) { if (pending?.type === 'ask') return if (pending?.type === 'review') return + if (pending?.type === 'artifact-review') return if (phase === 'completed') return diff --git a/src/planner/web/js/components/forms/ArtifactReview.jsx b/src/planner/web/js/components/forms/ArtifactReview.jsx new file mode 100644 index 0000000..4f40833 --- /dev/null +++ b/src/planner/web/js/components/forms/ArtifactReview.jsx @@ -0,0 +1,81 @@ +import { useState } from 'preact/hooks' +import { marked } from 'marked' +import { useStore } from '../../store.js' + +export function ArtifactReview({ token }) { + const { requestId, payload } = useStore(s => s.pendingInput) + const { content, description } = payload + + const [feedback, setFeedback] = useState('') + const [submitting, setSubmitting] = useState(false) + + const renderedHtml = marked.parse(content) + + async function submit(feedbackText) { + if (submitting) return + setSubmitting(true) + try { + const resp = await fetch('/api/artifact-review', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ token, requestId, feedback: feedbackText }), + }) + if (!resp.ok) { + console.error('Failed to submit artifact review:', await resp.text()) + setSubmitting(false) + } + // On success, the server sends an SSE event that clears pendingInput + } catch (err) { + console.error('Failed to submit artifact review:', err) + setSubmitting(false) + } + } + + function handleAccept() { + submit('Accept') + } + + function handleSendFeedback() { + if (!feedback.trim()) return + submit(feedback.trim()) + } + + return ( +
+

Review Artifact

+ {description && ( +

{description}

+ )} + +
+ + +
+ + +
+
+
+
diff --git a/koan/web/templates/fragments/interaction_ask.html b/koan/web/templates/fragments/interaction_ask.html new file mode 100644 index 0000000..c2076c5 --- /dev/null +++ b/koan/web/templates/fragments/interaction_ask.html @@ -0,0 +1,49 @@ +
+
+
+
1 / {{ questions|length }}
+ {% for q in questions %} +
+
Question {{ loop.index }} of {{ questions|length }}
+ {% if q.context %} +
{{ q.context }}
+ {% endif %} +
{{ q.question }}
+ {% if q.multi %} +
Select all that apply
+ {% endif %} +
+ {% for opt in q.options %} +
+ + {{ opt.label }} + {% if opt.recommended %} + recommended + {% endif %} +
+ {% endfor %} + {% if q.allow_other %} +
+ + Other (type your own) + +
+ {% endif %} +
+
+ {% endfor %} + +
+ + + {% if questions|length > 1 %} + + {% endif %} + +
+
+
+
diff --git a/koan/web/templates/fragments/interaction_workflow.html b/koan/web/templates/fragments/interaction_workflow.html new file mode 100644 index 0000000..064e4bc --- /dev/null +++ b/koan/web/templates/fragments/interaction_workflow.html @@ -0,0 +1,37 @@ +
+ {% for turn in chat_turns %} +
+ {% if turn.role == "orchestrator" %} +
+
+ Orchestrator +
+
{{ turn.status_report }}
+
+ {% if turn.recommended_phases %} +
+ {% for rp in turn.recommended_phases %} + + {% endfor %} +
+ {% endif %} + {% elif turn.role == "user" %} +
{{ turn.message }}
+ {% endif %} +
+ {% endfor %} + +
+ +
+ +
+
+
diff --git a/koan/web/templates/fragments/monitor.html b/koan/web/templates/fragments/monitor.html new file mode 100644 index 0000000..5ced290 --- /dev/null +++ b/koan/web/templates/fragments/monitor.html @@ -0,0 +1,33 @@ +{% if agents %} +
+
+ Agents +
+ + + + + + + + + + + + + {% for a in agents %} + + + + + + + + + {% endfor %} + +
AgentModelTokensTimeDoing
+ {% if a.status == "running" %}>>{% elif a.status == "done" %}[OK]{% elif a.status == "failed" %}[!!]{% else %}[ ]{% endif %} + {{ a.role }}{{ a.model or "--" }}{{ a.tokens_display }}{{ a.elapsed }}{{ a.doing or "--" }}
+
+{% endif %} diff --git a/koan/web/templates/fragments/status_sidebar.html b/koan/web/templates/fragments/status_sidebar.html new file mode 100644 index 0000000..16934db --- /dev/null +++ b/koan/web/templates/fragments/status_sidebar.html @@ -0,0 +1,38 @@ +{% if subagent %} +
+
{{ subagent.role }}
+
{{ subagent.model or "--" }}
+
{{ subagent.step_name or ("step " ~ subagent.step) }}
+
+ {{ subagent.tokens_display }} + {{ subagent.elapsed or "0m 00s" }} +
+
+
+{% endif %} +{% if phase_status %} +
+
Phase
+
{{ phase_status.phase }}
+
+{% if phase_status.sub_phase %} +
+
Sub-phase
+
{{ phase_status.sub_phase }}
+
+{% endif %} +{% if phase_status.confidence is not none %} +
+
Confidence
+
{{ phase_status.confidence }}%
+
+{% endif %} +{% if phase_status.summary %} +
+
{{ phase_status.summary }}
+{% endif %} +{% endif %} +{% if not subagent and not phase_status %} +
Status
+
Waiting...
+{% endif %} diff --git a/koan/web/templates/landing.html b/koan/web/templates/landing.html new file mode 100644 index 0000000..7acf1cc --- /dev/null +++ b/koan/web/templates/landing.html @@ -0,0 +1,65 @@ +{% extends "base.html" %} +{% block content %} +
+
+ +
+
+
+
+
+

New Run

+ +
+
Task
+ +
+ +
+

Model Configuration

+
+
+
+ Strong +
+

Architect, complex reasoning

+ +
+
+
+ Standard +
+

General tasks, coding

+ +
+
+
+ Cheap +
+

Scouts, lightweight analysis

+ +
+
+
+ +
+

Scout Concurrency

+ +
+ +
+ +
+
+
+
+{% endblock %} diff --git a/koan/web/templates/live.html b/koan/web/templates/live.html new file mode 100644 index 0000000..c9148dd --- /dev/null +++ b/koan/web/templates/live.html @@ -0,0 +1,72 @@ +{% extends "base.html" %} +{% block content %} +
+
+ +
+ {% for p in phases %} + {{ p }} + {% endfor %} +
+
+
+ +
+
+
+ +
+
+
+
+
+
+
+ {% include "fragments/monitor.html" %} +
+
+ +
+ + + +{% endblock %} diff --git a/tests/__pycache__/test_web_flows.cpython-312-pytest-9.0.2.pyc b/tests/__pycache__/test_web_flows.cpython-312-pytest-9.0.2.pyc new file mode 100644 index 0000000000000000000000000000000000000000..977cdd7248e8358794e2125a5ea4ff1960101db7 GIT binary patch literal 22213 zcmeHPZHybodEOcJB=z-!rEYl=PdxIv z%ae2$5>-;SJ=I37Hg0@Ih34|7mEZ)>kD?Irqkw@FND!bPk9Xl=W1|MrAn`v%YT-iY zk3R3rejP=Ll%v>5s|D}fcV^$2ot>GRdER&4nIA`gZli)~@-9sZGc2`Ce+`ZZG zL}VnwWTk9$A~q76Xd7uW)3%SaL&lfwnCKkoWO4p%*TkxkRg4d0yC+tUtY*BNT{F=$ z(jyA#_VGPdp`E)Ld_{QM434b3k4(rVvtCtR5k@wsVbG0g1ay-c1&ymQ(9LQaXs_B1 zx<%~(?Nd8Jx2j#B{nMVrst@RG3DHnexm>=GDrE9GeHdZs^QpqwgvSUT)2DNzpUaP) zGklY&!suB%3!O^qg=eyvbgn?57xJmxGx^+D<_tpevB}AokWZSPjB06c$<*ZJsPm12 zK#k-T1o6%RFmDP4G!?(BPcI1tJYN}C6q07+3PMqM31uEmc(oveG#SM3k6K0W=mnj! zjNcs^`jVd3^r7rTT04`@4V}pphR&h1Lj`<*&S>&N`gC$Eo4=qBPEH#^6g8<+@wFIo z=*FME8sw7jAHnul*IqjQZrj>#gfAU`<>aywxpeXl9top%@ev5%Zwr0eKZAKe5LbMj zDi-Wd_>Sjoliv%ef)C>CDhh9#`IW>1<;G)0D|W9?@)SMa^uEb^GfpMD_}E629~)AWyn$KH*und_-Wx6FFqjjW#YzLuO9mpeND^0^PaLUhB2 zJ|T2mEC-MMJhFZ^dDjm9kG>O`eZAvYkNC#wV-fG$zGI^Ah79gz5OME_zGI=_JN^J7 z-ii2*bqC(*2q1pcZWW}a4`7{hL88uC6vo}{i-&Znc6(53jJwlw0ionoJte8=ElTIM z3qr|P^y%MqT6vsmt?p92Mc*N8-dina~GmGMv(rqj@zQD#efR2YVB`A!%uS^19dXLXOBT zB75&fQ#z*H0!zOiVu;*76Dp+ia|4;&>8VV%kjd$WKbyydrW;BUzSsWh_t65j(JJY ze-E?UC1F`V{sWvO>g2PrG-=JblvTa)OwWJd6iO)FCG z>>eJfI_x47=Ftn3oh@%OkX}|+m!-bBJ>NR`)WZ?Z-y40 zI51ia0eQqIh0{K+G>wo)&_W(f>f+e3vDEjQWixeaJx7ALy>yhm3DG)*spo) z01jI-d^b9jn#>FVwrGU`Z7K)U0GKorBV3}!_54J-a269c5R){n=W`nU-)Jc#);1IA1u;DNbEg=>(t)r#Y=osVgtaH3U-xL+NDeq^&kCrvk3+S6GpAkn4Urs@ zfiWQ&^59Wm%&7YVM-8CpJd8x4(qKkU>S-|B6QL3VM6eueq+)L(@*I(qAPMoVKcmNC ziAsnwdrUOi2$rTNGowj0qXCn0c?&}(qJ}h?*9+PX%JT^#pCU3qWRS=Zktd0eu|V5J z3Y_#&rw8@w*$wv2Kz?H=$zbykfPNkc7TM|FI3@4qraJEU#IPc9pxgl_T44`GoN5 zJAyatzjWf3EQH%Wc4!xS{ov(;uO4Q&@``l%P+8hA*99_r2sdRzO`_it5A#5k0-RkS zVa~cKB$kz~ni8)l@v;Q`7OyGWD#|wSpj8FH4h$ff^IMVaL<)X25etk^n;8@ZL3Fc~6kSW1Iv%MoN zx3{gZSvk7f8*Ls&dzo#jcG5qK+C{V!RnZ@cXcyL!v0@BH0jG~PZpj#0auuarL%8jRI}zYIRMq&8(01mg}S4dZTqW>m!P~h@t<|BD`zC^4s!HJKiqP-nth;-9s`p}W4R!q~up8LmM=f69!dMhki?Dw1z3lTGU%P=AGv z@g(UO4U`&~zPFp|2Q(JT?#&F^*>vvuJ<1CW1}hY*gIu9HsL|RWR1&PFUw5fwrXd|~ z);Y(eEAr+=dCU8;Rj0QH?!;9Acfd*rrNsQ(5kx-wjfZZJOU* ziS^fH`Yo9eJY>^~+&^33p{m0!GGQLQK-t;yHUnwA@%8D;)31INFYjDE7x?QVc@I5Mk%S85H6*owLZ+Vo``IM|dpCP>yZ3`Fk?J6MP@abLF|q zr8&HB)4abD+g6qjUONg>j%~Ykv=Td5lj*l)M(|LTg*d-J@|<;3h1(a zQShTdj6}>q7up%h=PVIs%YGoZXb2uiJ$66?;~F9dt7h_$CtRYx@({@3@Xf%Y{OJ~v z!~SaQz$c9yVr$Cs6LTl#d)|5x%%+^9v-;SvQ5qy)*ywyHB=zf7tFjx%NIY{~G|& zk7DL;Xr~e3ib>i4u8-ADW7~lqV5gC|odz>XD^?mGv(hljjx(dEftIy>x9z2Yw(r

7xrZ}sD>WBmF6MFbY=JyTw>+)MW`mp{JELly1{&KaESlX zh0&o&EUjHo6Q0Z!bhpeKAl6Xbx&xNuEY)cJ54zjR;oI;{oWm;FqZz~83nw2tX@q!K3!S_&@4I{d6o!wKtLTGe#C;*apBFM!-%yOYDOhc1WaPRxcD<;^V) z&PS`Ur&kQl1M`Q<@&KuIhsv>mnoPeXGlGX~T9F4xts{x5!!9ym9=#wVJ6qmnApK#i zUe`GhKXKIi{iD8T11m>7vLiG5^f=RX9y=d9cK6>7=i_EhL2yon^Knteh)%9RZ@Ip& zkt+~nVD(cdg)^eN($JD|-R0Pz)v&Yb@GH8G+m6jm-Dhk`*mc8d#C9@@!lB7>GV-_V zWMq%|)(mah6N9CY+V;36OOK=`u?*Qhe7BuVT@�%?|LbG%aW!hOdwzcT!S0+~!Sl znt}r_vkaPUC)#$1t+0~9*O$5T8g2S$eyZ?HJ~ujr*(x_Wolriih7oqnQV*k7xIHuW zFq4#9wQ%bdtdigoOBpH~VS3Y+yAxGq$0y@Y>vFp2C`)T+_g_(G zpRP%3@mu0S9;i})vo?kN71e%hvG!vyNVQBZ5L?OF0ZtrSYZCpI%m^N;vJmHOiZt`^ z=OAf3w^;izm_=#p1J-T-4Ws0PT^>|P^2OmxxguP zE^v=-thKd~rem!wNn>r3S;5ven#kEJu^79pZ8|h|f6VT)Y8$hs$!a^?5@qH(OPh9@ zxz2X5O*@^GqUHJ0p0S$LjIF1rUFNJ7Qdg4TwTwmB2ZA5`KR#O_M_S7|x3`N+kwM~1rEs37J##QP@c&F8# zZMR>O{A|bOCUW-LuiA6f$DDOz>RNSOF=qCMwwC)to7E4jyNPm`>n_<@@fSr~-ruFV zfwm4W4}Ym09vkhpMfM%n7d38w@)lT6Y5pI#zrBX7ZZN$A0_sL}Q!!w+YpmsVjalt! z-Rs-6)DG+wAJ(RT9SkWyIfcDQ@bt~W@6>lTl{q(+@FJq1<#T5Y8QxbpHKnPBZ}e|oMmZo<{Yhu|4J^w z95KNg*i~eN_y;{vSIF2cS>F2Y(81)GVv+?01>7a3OAr*Ri&zI2}j{rh+++eNyk z;+*ne)nEGqs*OJ+La$H6;6Xk05qyj_TItmOjL6rB{5fUjT5xY-2)A8|odtBh&hA=y zU$IGSzc!9HtXPKMrDYJ+!n*qkluKXx8q!fu)q7!%wfBrI%j@3n|J2RxKln;z-Ita( z_x{r7jfTkUxciRaXI{tAPtfc5N}-~x#}2W138bv7$KAEDj79LhVb~ak5a$<2-rh21 zGi>h|oR0a{xC7V~XE_~%-&RuwE6QM5I&h;Oq^u0y=&vXTY7+gH%m^N`X+=6fF3BWO zb=XA`UdN*sh=)rui7ALXA)RuxS!tZR<6R1jh8Avb4m2JG|J!-S)U9VQG03H5ounHtfAv-|;ff z0qU#Yb+y&~`)WI-_y~QqwADfVDVaU_j5P>C-61<&lYxuE|iY#nb&?Ylsme-*;6JRz+?E>PB zAdAPjJ(_kAVQrd79AtP#?&UA;1vK1G(6IT519e|!?pM?LDbvkFdWldcVJ;K(Kv^-u z?C>0%D>R7nZ?wOHpb@Lf)U`3~Ny?~hcbdI1EfMCcZIp@j4I&N%{3-?6rZeV{d60r^ zBiiSQW6qU?Ht#iJ#@O;3wH%+^9v-;SvOsjj^ArGwEphg>Atgm3O%gMhH{IS6lV3#A=z!Bd8Xqd_ZO=RtwXd>qr zT`kuJKXYxcraYGmhbyNB`?;H*jij*Ccp90DR-TRI)IkH2n;K?j)=1siNKTqY^=41T zs5N`r(r;v|Ijs@30SGyoJi6Af&PIwoZjGk@Lmyjfz!cXuj2$J|@-Q?8tTMp1J-m*A zO`{_KTd<+cgeEiD>;P~`W|G5`t(1_E!%Qdkr)17&3ey8)>9mTokaB4a&XAuafiWV( zLO$^25qzPV1Fh>F!hQe?!x2WF=2u1*9(JMu+fdB5`Do;^%Ur_P8ap#VGPuh6?RA0G7+;!~pMt@1 zDw{s4T|*i|Ao|~c-13T|_+NfO-12ilct!Zr=uZUYCqfMLJz>qi3p;))MBWpg_?giA zp0MdXVau(M;F14g@wrQ-R_dazS|u^amVd79&yX< ns3IP^ytest

", "target": "status-sidebar"} + + # Verify the SSE event formatter produces correct output + event_str = _sse_event("phase", app_state.last_sse_values["phase"]) + assert "event: phase" in event_str + assert '"intake"' in event_str + + # Verify replay cache is populated + assert "phase" in app_state.last_sse_values + assert app_state.last_sse_values["phase"]["phase"] == "intake" + + +# -- Live page redirect ------------------------------------------------------- + +def test_live_page_when_running(client, app_state): + app_state.start_event.set() + app_state.epic_dir = "/tmp/fake-epic" + app_state.phase = "intake" + + resp = client.get("/") + assert resp.status_code == 200 + assert "pill-strip" in resp.text + assert "activity-feed-inner" in resp.text From 919621dfbeec3dd035effaf840d50b2aa7b1c443 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 27 Mar 2026 02:23:23 +0700 Subject: [PATCH 172/412] T6-T8 Fixups (14 files) --- koan/__pycache__/driver.cpython-312.pyc | Bin 25157 -> 25251 bytes koan/__pycache__/state.cpython-312.pyc | Bin 3166 -> 3207 bytes koan/__pycache__/subagent.cpython-312.pyc | Bin 13182 -> 13639 bytes koan/web/__pycache__/app.cpython-312.pyc | Bin 20606 -> 21324 bytes .../__pycache__/mcp_endpoint.cpython-312.pyc | Bin 16353 -> 16902 bytes koan/web/app.py | 24 +- koan/web/mcp_endpoint.py | 2 +- koan/web/static/js/koan.js | 19 +- ..._interactions.cpython-312-pytest-9.0.2.pyc | Bin 26068 -> 43941 bytes ...test_subagent.cpython-312-pytest-9.0.2.pyc | Bin 53020 -> 55680 bytes ...est_web_flows.cpython-312-pytest-9.0.2.pyc | Bin 22213 -> 24395 bytes tests/test_interactions.py | 212 ++++++++++++++++++ tests/test_subagent.py | 34 +++ tests/test_web_flows.py | 26 +++ 14 files changed, 311 insertions(+), 6 deletions(-) diff --git a/koan/__pycache__/driver.cpython-312.pyc b/koan/__pycache__/driver.cpython-312.pyc index e689a5d3268704ce8ea930c521e052a0da7a28aa..a9b0928a60346c3fa473af87c991c2c4a984dcd2 100644 GIT binary patch delta 2698 zcmb7_e{57$7RTpJ=S}BFOMlPMqT5#5vX6EI7222up<=0pwxAuFK!w*w``SJ_of+1K@mKtXgTL5a6_sevkTmZ4<0eMqpBfc)H!=Nd&-Xq`t7fB4 z(ofGj_ndprIrrRq&%dRdJg+Q!x3o0mp`Z6J=dB0#o?iAtFmQ%GAMiK|ZwoDtOn63> zlggdG8D+*d?O|mzMKhiQUVd9+)hcBJ8Pb;z{y+ZR;@KPVcWRuTLkRPekqEe!5nMM7$IfYN;)PZ(Ml!fOVU=_ zOjt=XW+q4HOBd{8)@Z_cNajCVmRGLH^h(#2rXy>BuprkzVt%ar(z5fIdP$yOo%YEY!hXGnGnOPKsTN z2{c6xi{i^lwvCMW7m?Mbbw0rq% z)g;8l0D9?@*VNv2bq4xr;AQ|B$fa06N&HxC?3O#A+6(LhbYK`Tfc?M-FiH?1%eIoX zVpV)U68bfE|!3d|#&r6_XD%4J!^m)ATnb z&*RMV|ZJf7W{YRjvWXWHIt22{mEtHxuk6?{BMD9^uKh8`Nh>Ur~6pt)aMOmPGat z&`QvJ>|w}x;3Tk~knP|PZffC`>kfpMjPj%Fe)vOyhU3~Y*P#*)zXxz=SPAeb@EA}F zJPteoJju_luk*WMa`8Wp543lv@6q^{!m;*; z1MxRu8e()P4sS_ik`D7?-WP%A0o-!z1>hw@wm2qDV{8^GnR1LIOQ4ELG&l z=7#dOVek%c0eF|6-n>bDpTq|W|J^(kxDJ{2%S^JRX-45jv&HQ#vyt<9A=p|`+$yMtNJPFKP{Z@JE|%fe&fK(t7c)13jX|LoZ^QD zHXg{s0B&x0Yaq$~mf8H@te+%1E$Cj4KZ)Bk7-Q`^oH_d5V7IzoB0L5s2fTTUpri{+{1Sc*CkNkcq)agi;Fr03+p45K$q4C_;#Y1mlFHe<(2lQ4>uh#6;&iOKFQS;w60g z_RX7__vXEM!=BU9=~Gh9+3akui~j;IoHj|zP|l6aj6wdn-PM~$lePJ@!Rtx0-89Er zIK9`kPKN3DU#)9RzRT4oXS#Z2y3wmj67BbvNNMzhx2Ci~RhU1bTefCdhPF|U#0`t( zYQ%_!4We}ry|deh+VmCQEJ>k5zKTX=L)_pt3g07uADPW1meCWpy08RkIixZb_siUj1mgasivBsTt(w$l3 zS5D?gHU8AztUPZzQ+m2|%b>^eXLwnL6>rl!;mi;D(~>RNRqnF8Bg|v#q|>m;TCO50 zhnhxOA?qB8?2&0fGaNA*m`AK(CGtmNvnsk{QPYl*`>~oT5jf7$Zz)-(PHeM7Z?`Ry ziS+_v9^FuIuN0{9 zDV-2o0l0ZHtHa3oeZ3LvA+b(kSQfor6s&E+ za5L~E@D%Vg@C<;2kkvqlgLzHMj9RuHZ8w709zL^MT?l0%_k7UV2WvP?lG986O9In zXL}!q9bl#!i?vK?4IP@l}qO- zJNVF*)WfA-r3jm{tdaWA!X_cxxQbA^w(NY~ZioXMYPRFv4!XE})fC49W8z@M8cIZO zGa{s)9w;x7cGGj^^OXbK!k3bRf%GYF!+0l9#-Yk&7i1A}Kdr8O%QyD>O685vK|bEB z<~SyKFuo7K%_3RA9$*kC0`>y?fOh~tATo-=QT^mWC>(F;LsdcP811Nfp!id+Wf?Kj z-i63nrjTsiT2F@PP}KtE3?E;Vx?VMqA)TOGmrPom!ZIHML%<>6Fh?RiNci>J93-QW z2Dx5U#zp%5lIG+`nDa4k1UUK+D`#TTlxbv{Y z5oL`%BCJ0|hpPj*ry!mNz68Fa{+cDqH(Y!@)l?J8n2Ve?h)5FIJ%r!fO-6ehU0{6V zm@C2=pu@{T9)fQxRlR(Xl=hcIlPeZTXX%j@&+}8BUl;Tt`L_<3uCG%IaO%8f=0h#c z<1D0ubbsCEq^P00s0ai}vVliAm~2KnVg&hRa@5#lJH;{?<9D1Og5~8eY6n+Alq5^% z!J=m9p8Cnt_d{I?h^jcxCFbkaH}NOLCZ=JLi*&fYOu5YU-=+KwFDVkC+nZ*L-iq-T z0t*e$OHGT`iQq8JajycBC~^_azebHKpk_Ml@(#Z}yj#X2wo{e;SnoaHecIPNT^Z(L zX=&Nx*0LTs+));w$SaX%RNq?pl4RksdrL4GF#1a z{Jq2#%*Wd;u{C2Of54dhoNn6A^%lY8V9Erb5#X=2iwx81(6lKBAT9*ZlGTjSro-EH zU#LpjPY;J?C|CJlUFvdZXIgSI>||2Q|0KNVq@l3cZm%KNxPtUz@YW(FP>8;cDNb`w zhXhL|H^idGU6~S0;+Du)!kf>ZlR$4^rEYgQ&9oRxQtHe+7vCZh>qL6>VhQgtrxx^1_bbQ3k ze3x3uyqeY#x8uCvHR8scLHef_$bA)}C=u~g{z%JPb!jbqt+k}!WenZR!4#fz{yzf| x(LQ>rb*3uPE8egjusQ(X9uizMav4A!lB;xrK2`dIR_Jdi+0umH0`!c|{syP$jc@<} diff --git a/koan/__pycache__/state.cpython-312.pyc b/koan/__pycache__/state.cpython-312.pyc index 1c6e77ca600378f3bc66b7a6806e1f0b6df8555d..9e95857cdae946a2b102fa502cb4295c6ac82496 100644 GIT binary patch delta 417 zcmca7(Jsk*nwOW00SHuEj%I$@$jiyX_-b-5qsnA!mh6NS?kMgQ(NyLXF&m%?CWcg= z6!8{@H4>{CK{^;1qIgpzfwEFC*;KwPIfx80iKJd2MH;AH2Bf}{TT^!O506de44Z|l2~d3z8;Gy~5$r(X7F%gaa$bIU zk>%tyY>JHSlh3ima@~-SX>jeZy38W8S(|+dBWsZ{Q03;+9D0n5c9VZ`D#zP{w2OcU z2N2;1BAh^kGl*aT5iTIY4Mezu2yPJJ0U|s>gcpdA0uj<6LIy;Dd;=!5C)aRol>~7$ zMQ?G%$ETH+loqAN#}_e!RCrJJ;`U_pm^_7Bh0$j6PHtJopvl*{1I2k6oftnbfXL6x Q3{2b~n7{%GlkIur0o$)xNB{r; delta 426 zcmZpdyeGkXnwOW00SK(Cu*I}l+HA{;=3BZy!D5l$e&1w^=l2yPJJ z1|r-+ga?Q~bA=U13`A&6Udpvq62#IJy~PzDpH^B@T9g_eU&IVj;W@dO+mq34@?LHg zd9W5KkSN?Uw>WHa^HWN5QtgTYCh-J{^DsIweqaERpP3n$xIZv~1>`1Y@W=xIyS-Go diff --git a/koan/__pycache__/subagent.cpython-312.pyc b/koan/__pycache__/subagent.cpython-312.pyc index 63f02d2c2faa743104231bdc6d256685c17a776f..4890efeb74970bc37ab40909af46079f18ab0d3f 100644 GIT binary patch delta 2550 zcmb7GZERcB89vAN`oBJJxvH!&e- z(lkqc&hwu0emwU*=Un?=L-R?)jhY%Ag3kk|f19`*c*nr&byxHVoyBKWXPpI~em`T% zRsGyDr=?B^opa`$qxiJ1MHwN1o)nDCwz~nz@fo(%4~|Oj-t5gDK|os zrkpAHZSsjA;KQV-;mI9SwcnJ$bIf{DjHaE_u4z2&p7u$b`N2(7MO+f zn;XpLxpikWht~-)n>*ROI~gYpRu{QwHV1?pe+r4{yO8!3)dl7SwHjfRvwnGQ(w4I& zB_--p^LE}QBC+0u=GclDcmThpAKS@ataiZfTiO9*Al^=j7J;!Rcat{^JdArc#y;ht zYHc+;MZ=_!O>YQAc~>6KsVZr6f@pra6(LzAZcAaYWzvzWP9CQz$T^Ffyv)D-zj}sE zHE9)^ zF`W^}5y85_W;U2_!@m3Ziq0lC8J{yw7(_G)<2W8i&oBqkI94j|kE<~3_@s&a*cJe- z3$|ZjEjeS~qm~~7A>_LKPTTviH!pJ!!@gWVc}=pS?+fEe)qeCn3uhP&bhp1P37P`3)4yv z97Q|V4OW(~c;>4_ZH`TvNX*8YIZ<~>wRuQqj?=Px^h(*UV_xBP$d4_T=E9FnbD<>Zjai&jy%#C*9pJe;i}a&w&A+Jb88 zMP76{v5mGapb-uKE!Qlb*}J8#JnW;P?GvSn>NJu*5hWhJrC$H?@i z$)gmGQ%DoLCxolXK2Q6T`fU1XDHV;U$5L5&FRYfCVJRg)Lzy-@I+i&W&157Q-cCrK z0PyL{+TmCx8_lNE!(~Q}jmsJ8%Sk7oZl$HQN%yMh(V2D}a@VB(wO4V))7`L2w(8JwwDf}yH2)h+hgX^tMHsS}Pn}ewmOLLT} z6x1nLqo7Ga9>NIY|7p+rume6;J_AEpr`(2Uc4Aa2SB=IdhSM=orVbhU>q+l}>;fWB zRlrmDlb>hsMe>ifKKudM)85G`Yk4x&-p0|K@&}~Q-mUv3r4*VAYwb;VY8EI|t)tVF z%S#pJ9jm3LhXU<;S<^j|7RQFA b9{KJM?@L+_Fj)B8FvsA)JyQb?D31RDq&j#^ delta 2177 zcmah}Yit`;7QSa*vGcG!9*-Zfo!ZT#bzM7{lvGtqiMvS)6e>YbB3QcJG~<+*)@jF1 z1H^7q+R{XgwC&!7vf3h$06_^L6{B5*x~c+wsOn>zwkpWWWA_i@2SO1Pp-2cg_ogNd zLSiI;^PO|Q^W8IZkLPUq$3ENnnwm<2m-Xq>{l}Lcw`o?g+ByG!XMr!BK7=9CS)|(OrUt{v^pXt~cNCEFdFhrgZA0|V<_r9lB06f@&N?&!yu-~ihe}RP_^!$Nd^?YV~Qy}D7c|D%M z5i(XmPkI+X1^wK+4Xm^+towvt&Q8pW?PTLuI2}@6N?Z6;9P%kE{W%=H*=tNO6kMw= z$8+~F*{C=w%uUaDtn9JQ!VjQso{QD67?nm<&R%vXPm)o6R6?(sd0vl{y;^MCt20kb z*L=S`G3+hguBMZIx1&Jj%P|?0o$OJl-S2DGjH=%%9X~Oz$~7jBS$He#kHc!& zP=4&wn+*M^e9Na!r@4&Y0TT{7|u{I)_ z8GHxk0E6uecz6fBCz!w!8V)wEvToWwn0;(hHk&ecG6DX7i8+K2sVrHy_GELLasvZf zOQP8`WSW>RDXE>QOfFjzQah(S|7)q4CE1ymHSLe5jJxyUi#;ssuge)2#Ra zJ=nNTd0^J()5fO7p|-X*vzF~-%Wm%(%52IGZsw)tdzf5{zw8c~kROWCrek2ep;~K{ zk&bCs@qddvP??ZD(*)s0UlAe`ps!bm_imV(ZXj~&%ycc0{WH@G>Ex34pq)MyjqE;< zT-dF{WCS`L(&Umg%P}|=hE7d7wJ;gN;EVvBZt0Ae^k8td7CL>>S--@1D9{-oXICW? z7@UhiSF3a`p42cn523CVw)5d+5Q7V=p=-5t;Vvukix%hx>7tc$Cv;2F#obzRF|J%% z3EdUarBz9`|K%3wu9Pk>V>?b&L3fQbRh<+txMB-+J8W0t^~kSkz|hUn$1z~-Y7wtC z)^)|jYa%?PDA%MlP7JQQq06US_i!GOvFv(WM(OnysXL0n3I$Ui0rU7s;#k44l4A`= z2bR$bOJB3RkFP%>nIm*K<_oeQ%RcsOH2IO4!x(Y!6_3X>5&lL`-?kP`(&|L3!q@iE zyAyF`gvn0Qd}3AQF-94LiytKFVfR6#xWfXLX573~W)a1VmAM&5R+5bV-W(T{qzwa^ z6e>EH;y(=LwA`Tza}n4OvD_jVVLFw;BM48`JUE#7Va#%DcJ;C(6 zvwt(j_u@NT#t=K;qs-UmYG&8z$rg{}1y&Sc5M?k-+NAU}x>a#>b~^{6Sm@Hefy+V`w2tqy)K_+r>U?-yO4S z8{7l)nUKT{IHS}ANb963fdVP$P(nYVhM*F)p#eiu+-=m*s%h0IicCSO+O(wa?b$U{ z`J*e}&u`z%do%CN+nKpLLM|U8?)P$X92`9A)4zy2>(9EIJUq{{)8=U`MlYI8|+>IXVQELo*t>;YKHe1Bb-pXCVOx_NmHIl;;-pbXq9X!zvL>%!AfbP_i zol2rDmh4Gry3np@bS0=Gg3ha&ZjQDqpmr!-(UhvlZQZIWKr1u*O2j@8`r)Tu2khi- zvVRBbeK-C2!_7m@V}XL<$A=!j7APNC&QAOKEoRO;V|+TB>n|dgSd0H5a)CYPKgOqd z3_3WO16i1g7@A%Y{Zlc!*{h=Oo|yCVVOZly3nxidlC5cea{>Expp;x>w*$2Uv>6(7 zEA2@n;)!;;4&Eq_*o0635zACobc?D*wH}prVrv&bH_J&djJRn6RY^oE;t50wu?4XZ zF_m3RETtS5=BSDyX4FV|#6&fe>k&POUiMC~%#jB1+wfB_u)hT#aZDvIvnsDbcyIuF z?nLYY=oYFZWQEc_sL2695OYyR-@2eAdUcc5o$8{y+1Y|}^AKoX&HTP#uRwONSkY>d zV5f^h^}Er+aIqJqeSnCM&P4fH1VcQB7)0DN2li!A(Q2G7twStAU^P$-gT@e3Q?q6x zejc?45HBK(!P`(e$j(&xo%9)$5kJoCd*Bm+sH`(wPc(KcypnvJ`8@n6Ay2UtrIO_Y zcGOr`X`%TPh##@%OYhEn4VA|Mx=D^|QKLvDNup(_|NbQYp2?Km79xK=2IWFSs5K(< zf^>rDo;68X>Dmxi=(1#DQ@ow-VOM4?otJ@D-4UZoRD%y7szrF6Pj=G7Xg&iF$)i6) z*;we;*^=1>0V8SWQEB)$3T6*W%&uBuSUn9bx}Yjr#BMB`ZhA5)Z=*O+Hdls~VUKCl ztx75$Ym3YDF#C9RnfaHX`&Y&>r&$P{GdxArPWp3@Hk@!yOoesL50lI6;QV>wyU;-2 zLtI8^?EU$*&JRH>h9syz;Fvfkz-Cmu011DyqL{t)kewZ0&__&6sxJ1JW&R|7F7RwO zX=e6HqmRX^tBHjjs@^47kMeAORbap-+v8;N6I{>Laf6xDLLZ4ZT6G&$)KoH|D%6;& zEgFj{DahjrV>bPsDAnSdqA_hQReIw}UxcSOU@SU@FhZj5gBY=8%iD-$szWv)4wjEz zM}rRlstq8q^Hn9z--1+$LB5d<@}E_r$KyM&^_i`Q93xHFJ+pSMVp44-t6xy3tUT9e1J8n-n_cQkuk5>jsSlFDW@EAat=SF3SZ8Z2nb4H28okWE zSrZ(9&!;1*wP`&xq3T|$#FE|JxP!@Usg9_ss4H}*(w)+_WncS4jgq04x_eYjdQy>8 zrAvuH)kFlNC}88tGn)*y9%2(WJ>30ihd1Ejk-qPu%k)rXEmjcKf%jV zEbR{FnG6qvpwhUPg_Kon@#qj<{-6M{P({G5bod z#(bfX#a9h*cSxsnUvOC6IoG+j4sK{sgY72^+23xPkQ_Adx53c3Mtj#V#uDrD@u zm_*%~ifSEgsVI$ht5jvz7S+`qG4vE}Ia<6|Y15MT9jLI0ZGrw;hi<~1Shr|Viua^( z*06Y%`3tc9RwlXlr+g09KHUL;dfLtE8VW1E^7zDFI1}TLgqr^E(G5m>8)lmCLfcE3 zGYuE{$RKvZ^NGHR7(f`K>_ll70>^`+>gcjUC0n_!Y~>n7t77Bp05})pF)e$XpGT$P zxz(^ma8OOgq$1XP_FBxe&Ub4RP2fTpgMRF6m7l%X;I*fEG-?8~0V`O7RS&c#2Wns=vqXGecm#?_n`{`yedPa&04$7f^VrI@g^qHVH2iU@oh8=(#4Hl=b{U(y TuFUBsWw%ShfEL0wt}Ffz!T~S_ delta 2510 zcma)8eQaCR6@S;y&vxuMcKj8`jYHxl?(C+`2PjF?EJ5o>N+3x|ize8*%=3FqTpHWl z_mZ?xOWF;xZnTv4uz@zhs0I;GC@S748)#C65SrM!c4Bk%*0HXe_6OC}O5G;Zp>*e5 z6Pls@v8VdibI-@U=j)!EU(K_{=UB!2Znsmy@BG1cGrKxYS8VcFR13VStbn{HYJGz3 z@WD~fv{kk2m*HwSWaUkU2L{5m<*IzrLWYvWLnx_&h}&=7FYjY86AqTidzfxvl4^z5 zydjIK(0{%kN^=&Ys$?Wd``E59wAT2+)9&}GHr2kg-*Q1nb=(pxDHu_>>fPZfd&Zu| zGqy=qX|E;Wgs)WgItEQ;U})o}d*BC^W0r&m6kqF3vpheR(zTKCoI0^vGwrxY83yMX z`94Oli(nYRbQ!q^wd_bbH<2|=c~moaAF>lx)1n)uk{Z>J?bLRs^17yujO#puQr(JB z2Q$7{bQ&r8>7O7RkSR`=UJNu{2s9nqbSY5%RR6L5g<$0Pj;B>v^iA7blCR-f3?BB^ zvX^1b-@^)U(Le7~Evjr(;-TW(XW8WwsU7YKz}1cA^76Gi7^uEg1oN02-TYB#iF`qM61guF zc0?YL*+IA*y^H0bsW#m8C|QUtzD?92goK~3BKioy_X!>+I7+b02Y9%)c80v<9R%G3 z)E}I@=V^jluGve09wY8?f~N_@;Uh!=f^J8sD}6jp+`~)oHi`XM%>&X!XW+4>0~;1x z6-C#I!iw9@$!ronigmFmXk6LHE*HjEewnfFz`G4~wpYl03a&InmDiB`6Sx}}Z7&n^ zBvi($obyBy+$glgugm3`c|3xLiF*`UlQnD>29sZ6Z@{r+sA`Vb4G4)U{yNd3n5W?v z$w*Kn=;y+YK(xaw{5{#$E3CeYOjFi1BT*(wWLm$GQ}^;WNLMs~$gQxal$mxdpGl8o zR6Yk^TOD`4kGz}s(Sj57hV)~;mdz|*|e`%4t? zUlW`on1X@kc2^O}28>dFK|0=tT(T%d_d8nt9zj$XrrTn!Kj7*P za${b&@phXRF1D%8=el0pb3WGjfps0!wFDKufNId+as=2Nr{PfRU46D^EK8S~Nk$OG z;#2LaBg2*?+oTTZaN$*XiY3YhOC2oIWl!g_hPKDx=OEu6>Pc8ivOnS$%Oi0ti$t`) zP$=b)R7>H&Lv11Wu%k-(5P2KnMB54oc8Ob$@Q(SDKZqD z{#ST?eUtJxT;Est%la}oc!@-RCJ>Fcov1UwdS}C;cgk^Xy7DPwY$TuJDV)ob@T1<2 z$g_gaab6plNo~Z)eRlofT5k>e2;6rjm4BkrSfTsQw=55cDjvi&hE4a*^y>H$7#nig z^aQ>a+4SCogRe!w|Gw=cAXmhlPRO?=4UU(4H>^@VM%ip(|Au!g3DL|x()}5M7#ZU9 z&t?}VKlm(UHb=FyNN!J*m)cjHU%FSwHmzzVZIt}^{N@UfLn6;5sWhvhZ}Nq&NiU1_eR3`{QG zGmJS&>I$5_`-|)+g`0PKS-*q!32-Y3JOnglIn5egK|s55y1u+fKwZzNUpUpDQ*}5c zjxS1Z|3Hh4w&NZ+IVc_%~|MO977$MZFXquOb*C@WER{HT9oke)<@Q zK^G&flkoA-7Viln#pDt%)jNf)TU!|O!ohp{W~NCd2DgadFfBzGG#&rH2vARiOP-54 z$s5Twj$k^vOMjsB@EA(*pQKZ)*JQ@nznl_-zTs1fpLwr0!Hwa#)6L@7>nadpuzFkl Fe*oLlciaE~ diff --git a/koan/web/__pycache__/mcp_endpoint.cpython-312.pyc b/koan/web/__pycache__/mcp_endpoint.cpython-312.pyc index db3f81f71c9278cf2b5685980379a287b5af73cb..f86a20a5f2d3a2fd2f1ad363635060735e89d539 100644 GIT binary patch delta 1493 zcmZ`%Z){Ul6u;-a*Y{rAwPW38_lL331=-@YyUI_3w~VZK-tIKv5WP6Z#ZKhpf$?!1 zdr?z!!pNXLniB`2QEgn$$$R$hRrVcJB2yIyltVrJJ$=0m2bBF!Dg9K}-azKPNf;r~ zrcBtlA%AJVY0m_^ZwGsC1$#5Wed&WnI%s4{r)RsfTUuw8GkvG}eiS@+t2dr)PYc~? zZ^waG*Etwz^5SK)radSnajbEyR$To3lgTT1U%Je>nvJSSK?q2Y@;)Zvz^<+*;smq9RGlA&BfQS>7d4p5i6N z;y@{jUkUQ5pg_Y?9iW8Cb6YoAY_vutnV&WFpvQ!AV@^?(u5fIQ2(A6sY$kb)InDp?Mdn@BDz)SS|0Z|tus~By z^Q!FvKM2!;ZYFm(S4wuZ)DVV&fIG0!T1MbiJ$k{jtc{8f1 zy;ym^^4-Zxuwc4ux^(Q?3mMPOOm%yT9!Y8&ge+=>$G>}gGI{9_mX;>s`iz*g6vq-*g@mrV`GjJuu*02duq$}v5 z7z<8Yzh*YpT>K6BD>ww<#Pd7vf%P`i{LCOr4um$D?ob*`7$Gz4D2(G5W-=JeQt*n! zK`@RN85GzQb}JQ*mAs!$cX_cFpQEQY;4C+`}KsS_jGZk(qg&=Zd( yMt9dka}TWYh;!$;8t8$1JK{`ds!mm_WTEg`Jtfz delta 1071 zcmYjPO>7fK6rQ&`yK83?2md6*Mzn-B@!GMClQ>|Kf&%ucTu6|LC`d?E#2WHfobFl; zqMKq86jT+dsz#*;+N$jd$pzXvhxS05b?s9taAZm&9}rYXKu?y^L+PRI%vw~8wBLO1 zdvD&pd2g04z=LzHpWE765MAYWD^sr6H?Ai=@F%H8UN4UKK81GaHM9#|`kj8i(C-J5 zQC@;u0 zcaj_7n>+OH96!3gch!;yeoKz6CC6&XL)F82HL2Iyjr@W2zQMeDas2%F9jx4!z4>uc z=*yf-LLs2?$Pyr}h?dAR?)0T&ytNh5VbOX4GrnDBdKA(TY{f9+1Aa9LB^lHNF10!t z?*MftE_LqrP@}8>4JwC$9xg|09urk0l@pNO)mk2s7=J}lc@L`aF}0ts^kaIgvJ=!K z`6ALIJLrv<5Q2@bfviQ2kf+;Z@<(s08=J_4GhlFlP9cr^gd-62@8(T@32EpZ9-+(J z$NaJ&paqy|Xfvz!YwV^iJgd`=a$7E`!_G}#odpil9%pF9W#j@sjYpN@LT9(C)OUZ8&p zarz|P>f+qwgpo1yW7Ih7p3mwtCug(sQ7v;~%9zTY)`L_(To>%9=JSwFWKZWZXL7_B z?RojZOx^}naaws;UDI{i-;8;-2Bkn zyY6Vabhf%Bw(j+Re&oyJSM@c=0CD$?kk$TIhZ Response: async def api_artifact_review(r: Request) -> Response: body = await r.json() response = body.get("response", "") + accepted = body.get("accepted", False) token = body.get("token", "") st = _app_state(r) @@ -314,7 +315,7 @@ async def api_artifact_review(r: Request) -> Response: interaction = active activate_next_interaction(st) - interaction.future.set_result({"response": response}) + interaction.future.set_result({"response": response, "accepted": accepted}) return JSONResponse({"ok": True}) @@ -329,6 +330,27 @@ async def api_workflow_decision(r: Request) -> Response: if active is None or active.type != "workflow-decision" or active.token != token: return _stale_response() + # Extract valid phases from the active interaction payload + valid_phases: set[str] = set() + for turn in active.payload.get("chat_turns", []): + for rp in turn.get("recommended_phases", []): + p = rp.get("phase", "") + if p: + valid_phases.add(p) + + if not phase: + return JSONResponse( + {"ok": False, "error": "empty_phase", "message": "A phase must be selected"}, + status_code=422, + ) + + if valid_phases and phase not in valid_phases: + return JSONResponse( + {"ok": False, "error": "invalid_phase", + "message": f"Phase '{phase}' is not among the proposed options"}, + status_code=422, + ) + interaction = active activate_next_interaction(st) interaction.future.set_result({"phase": phase, "context": context}) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index f7843bc..c5d124c 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -248,7 +248,7 @@ async def koan_review_artifact(path: str = "", description: str = "") -> str: accepted = result.get("accepted", response == "" or response.strip().lower() in ("", "ok", "approved", "lgtm", "accept")) agent.phase_ctx.last_review_accepted = accepted - return response + return "ACCEPTED" if accepted else f"REVISION REQUESTED: {response}" @mcp.tool(name="koan_propose_workflow") diff --git a/koan/web/static/js/koan.js b/koan/web/static/js/koan.js index fa5b0c1..bd22d93 100644 --- a/koan/web/static/js/koan.js +++ b/koan/web/static/js/koan.js @@ -130,6 +130,10 @@ var el = document.getElementById(d.target); if (el) { el.outerHTML = d.html; + // Reset workflow state when a new workflow-decision interaction arrives + if (evt === "workflow-decision") { + selectedWorkflowPhase = null; + } // Re-bind event listeners after swap bindDynamicHandlers(); } @@ -340,7 +344,7 @@ // Artifact review accept if (tgt.id === "btn-accept-artifact" || tgt.closest("#btn-accept-artifact")) { - submitArtifactReview("accept"); + submitArtifactReview(null, true); return; } @@ -502,12 +506,15 @@ .catch(function () { notify("Network error", "error"); }); } - function submitArtifactReview(response) { + function submitArtifactReview(response, accepted) { var token = ($("#artifact-review-form") || {}).getAttribute("data-token") || ""; + var body = accepted + ? { accepted: true, token: token } + : { response: response, token: token }; fetch("/api/artifact-review", { method: "POST", headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ response: response, token: token }), + body: JSON.stringify(body), }) .then(function (r) { return r.json(); }) .then(function (d) { @@ -517,13 +524,17 @@ } function submitWorkflowDecision() { + if (!selectedWorkflowPhase) { + notify("Please select a phase before continuing", "warning"); + return; + } var token = ($("#workflow-form") || {}).getAttribute("data-token") || ""; var ta = $("#workflow-textarea"); fetch("/api/workflow-decision", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ - phase: selectedWorkflowPhase || "", + phase: selectedWorkflowPhase, context: ta ? ta.value : "", token: token, }), diff --git a/tests/__pycache__/test_interactions.cpython-312-pytest-9.0.2.pyc b/tests/__pycache__/test_interactions.cpython-312-pytest-9.0.2.pyc index 46de97b50108d51fa135e4ced5dd2591cb873b84..c4a5aab1b79ceefb6547479a7f260b7e3b9c72da 100644 GIT binary patch literal 43941 zcmeHw33MFCd1m*VJ@*U-C&2?e!Qlbk1Vo9Xc#5QK>LP6kl06!shvYzm!`%akfM!fu zl4B@gA}YyRbgbRbiIb3PdY5^dw~sF`$x5=ck8<*MXNZ9ScBDj3#W}#3C6ULjj z-(P)V(BJ?T6-kMj;6Hy?{Z(CERbBPfUw>8oVJPJ1aDD9?uV<3GIPTBsM!(!D!(Z#< zIqpSHw|c{E9&>AeTchDNf6$R=evjTG!7G7OZ*N~NmCN+?$_H`p7SmrD zNGBYMPfX=fUD=c@EAAtibXJ6?b4TysdC2sqa$U!8UvqD|SIqPt-QSx_OQ|l3q)W>m z_TyA<_-iY`yvU`wPG00X9fwh>C`U)yB|7hbkLc=ji*DR`=x&ftcoqNN)Z^)0eZ5CA zM-NI~xGI63J~5q5<}ztXevb-6ab|jRN=)wR8^|TQ@Zz4Jsm>2Khu>IGg2Zh#So)ZLxgIRkiEF|J0vWUnM zB1?%ZBZ9o*q&gz38d5!#nsh>p{2a*FxgW(F&()UWZ725*?;dfrU2U3wZm8U}1-A!A zTwBJYwI_EEFCKB#UTvIrPAoTWKs~P=acvmi*im%V7aP}&xH_(G=(t>0-f#~pez9Tg zi0hv5g^P-=rZXExT#G7#U7fq|;*#>*_LKLVJ~ZNLA8%f8a^G-w*|k7TC8ev2UP-^G zT|g7VU+V|+BA0iZT$Iy3502~B8f;yde)Yz?TkB@*{0fd7#mlZdm*?}2yz@9OqqE6y z_#Cw7Kfom%2NN#El^g6&D*~&K$&9FYjtt}mq_pDgPYq`KQX)jWDS5EBE7PZhkEV0U z^b@Fxs0V%hN~lXpqn;<#AQE+o5RY1G5XCN0<0-8qvI<0|6tv)ysMM4g>eu6ws;#sR z?o`0?R*;k2M3580C%^hutZ^*XT8g!f#1dn%_EM~UBzD`d=dHlJ@zA{SSkri?&#yHfpKM#1BGKKy@%D#kw}y?1jwQY!L54?q$HLJ~aifuqM+K%s(n zWq~FNPM*tApTI7?q7+;?YEsxGx-WS2);I4;8ti)aAFQL>5?!2p;KGTY; zn@Xq(32&aG z27_JQ)M`{*d80qs#1*`V*_rp`U1C^_9OW`bWq$_P>nS|xo30m~KjU^IR+0VF5yjN| z95qDj>Tb~(%TI2xesjXxy+r5DUp@W$Z$ZclVw7I6;1gp7f8Lk(KfWAyfqX#D=BTc- zs~c{Wmspbz9O1<{g*oETKVM52`noEvyib2}6*<2yC)U2?7()A82#R%LeLk4s*BK9qH|xQnNIStn-g{uFm#?pPYK zY6C=NcEjHSA0l^%+RRfPE%TydW*Q))uP4BX3z6C99y@Z z=Z9*RF7F>)mylbwZfzlUV?sXfP@HfhvhhY35H>C4nBV4vOpcoqjY`cC^uj$|{cY*v zUFm-IL}?S=QSq~M$^=2Ac5Sd5V5msDsI(vk@8G9R+Y{iGPCD|(~ zd`5AzLQ(|e1S-IhKE;WgR{}^$Qq8-y)|(C1oAv6A`s7X4n|3*j7pIQOywomh5#>bk zw%jqi87u9inkkmT9a>{;+uN!K*n(%t%h3n?CHD^}xgQH_e=H>47Ph`y+ww~Xhkb9g zcD&qLZapyUD+^2Bjn$w2$~PN_cZ>(?#)7S-VCz`0trTo~E4uL9{TKOj^0|(3bmQMS z9ii}qldGBYzMqRVkJl}rKC)@a2VPgqKkWV>$c5v@_{P!Drnh1ZFV1^m-kHI2EOG9^ ztM!Rx?PcO!JCvR9bA%3En!XrJ(M zu`lrdz@A-%y5QE^!@M&|_?KOlzS8KCwI0`%cXrbluHx!8`e@U`@*Hp8#d=)hY5G%* z9+wvd>T@pyj2_pWBmB%RF{sN^k4yb?-ko=fAu(**i#pX_wBV`iMNfFT3657>tY7vT z`GdYNh<-5dlYd@}h*7iO@19c;5Vv}$Cpft-N5cemb<sI2DOn|3D#UPWO7`-2 zz8R~XtbvHC$O(E5im{iRtnc)jD8Ule1})@`URaMq>pQ*ZI|byFZH*`d%pN%(&_kmC zt|^4_!F-6}i*P=CnwR~S=i4EScs>k-QA?prgdx_=xMZ3v@!OP4jz(mzIMb5xfV#7;rR;MCj zqu7*>Xy`0D;~Ey#-&ghUsMC1?=2EttQ?n;nw&0_&<2>+`3JDFBOQbTPMd5jS0LoPQ_nM3{G`e@RvN$)s;?*^3bxWu***F z3y56)Efa0sVyM+L9n`wo+;(o@V&>(#%gx0vJXqZK&`5LVSY7AvUIuF>JY4OZ7jJ*z z_M*`8!tKAb6+fr979%bAEk#* zHq{vtc#y$gTxWze7(5!Nul`~FA6c%H2<*`a<>?)p54ibPI%4}foUi)${hK_m`d!3_ z?`nm|8=H9CywTx4;PAeℜOEgixu1JWQ3-)svDQ$DpBiFw-YJ4j1WXh*YQ(H;@|< z`YL2<)}H0Y-GOgB{I!S2-1Q}Q{riq4cgHm+=V_QAZela%30i&Y-J6*2`wnob29Tno zugbV+WQ&Wx_Sc{vpE_z5YAmNkjU~(?oXZlMN$>b(saOz8* zp^WKpR>R;{4H#ip9WxeOOdsUZ`@Di1_k12RHPB3H8DH?^J>7=ZjEX|NM6W0i_Pt=t zn-#oyZ#RtyE3Sed`hn4eypJI+f8H;DKSzxhyShpHU2%y4XmWTlNMS5^D`etvI~1+I z6+^;i{EZcn<2G+#Rv=+h(gt0dl0Y}1DzXN`ts-aWp2V<*gad^0^8pRD1WnXqiOCM7 z88}HVK@GJCKrEE!-tL7{-(JrrG1dgnLI`-+pATvJHsE3C+sr(%FC9X|aSCIWjwOs; zJ{m}^ikyM;4SidL>Dx?1XN*QHG1=wKbcim*&>Zw_R^1t?%jjd<#paQ4C+Krjj5?Pl{X9wBN91`BC1|L~kPXrcs6#qJ z&IGNb43Tb-n?a=Y3?iw8lzcJ+sMOn+oH|1YoQT<;UOBmO?QKIlE81gKYc;Dl2v*84 zOwhGh8-6UbzAdc$QSIDcg6`^SxbaNWNOu3*jYM5gtbk-Lfp5B zyabY{k^TemlN(U!SILdqO*VV0&fcG;+wTye!RZVd&hsJZQIfQ2Go@c6k6$M;U4too z7rt@`WYW0NsBJTRpJGMY47Bpzf9P^h8- z3R^zMdX#O&r6bIb42g#=*v}4anhlWoc6M@R0~9eDpr{zLG(a;&n=@;GYHS-IwV}CD ztHQ_0ZIL1n?1SZATJh|F3a39e(`M*=v`RB{7Ns_;#z#7j5Ysgu%Tzq2r5>#YwWKrw z2?%P%P@CYz77MN+fA^m40>ZYIi za`vg~PfO}gv-#LNY(MrHgd`mGQ-AIoF15eBx47kQ`rJSFv3%~*ZzKH&6Mj48s`L%Y z-(e!ZLF7LYxk!YXw@MxB&ypJ>VC3T!@PVw~{zThSr zE5ho&?>oS$`dLbfy?*w0;bZD&$q29$=FD~mg55!gR$SsF=n8}mbI|l8>6#xgdD}U|p!OYC`5CG4jc(sm5MGq-cRf9h<_!5~F z_+g+2?x;fqFgeNt+!>1nU~&kf!=y2C#i%!y6?%LH4>L^gUb02X$z*SCkp3vOY$<9RGP{%H2-r53XO$(_|T2j3&stTn= z|Hh5BsKsLA)yC}Aq{+juq1co#(7YXkwG&goD8W9d>ljK%O2JMXR=Hqr_;Ts4W2>ok zQ@BG3r}R504aEy{@m%^iEW@QVjH-HIp_LYg{9S!gdNnnV@?J>pAjy!XY=f~C*^}2; zGPi9I8O-;^k$%5lXGo7eO-^Usmg?J+L4?Ru;i8E zNwT#V=I~CYnNDK>rw-mCP)Ftl`jdJV4z=C9GPhO8e;-lG-vJ@Zs)`|6ee3wVweLjd zj?Y~&zI5d~i&kG+boo%J@&55eZI{+xPL~=FO}L#a>)-c!TWTga?}GS*(^nV%z#VMx z4+qfVEZ@KecRv=^T@A&HwVOsmo3GZ)J@e2=P3!Qkt91*`IxihA*X_a-pPLJ}V~Q_Y zfBLCnWKmIAblqF&azm!Z$ZNm2u+thM0o^5 zwgO*p&PSjyrg~lUnJtFhB#Zt&Y{+HCAJv~^{+b3G(D|5>Hu@@45;`AW z6V2OTh$mJCSnCkIrIv>FtT3TYVL5g`}kf*nI+T@1|3VzCSXE)7nR9t#K zi6QcYv2hp^T)w<#fWst+A5$M@j`%Br;#Q2X;c%2fm}O%LW0#A@AhU{`VV(s8Db>_C zAl6`-#ngrw$k`H;UCvB57$s9Rdcc%5x$aPDe+LfX)fhE?z!Dr> zVuMzD9ct}0CRVG}UoWe_ji2uNt7&ta4od$8StI>Eh~hZfhq*E8|E2#%_wHQZzWX>Xp9bc8R2HFiwoK1js5;|WMVe@&V2qy>9*z(; zo;nu6la`M}R-D7MAtow!UVI9q7};>~sZwO;m_UD{nuB^b!tPZ53dyUim6nB_nm+#S zm3Ob6Myd9@fNkoO;fDr+j%h%k6Cltv0}$w*B?tsi1PFxH`Xmr2+_FyBYTs)@9=ndu zkVK~|ROuvV+Uc4g&}V=^takes2Z2GY8x75}8}(?@vL7uBj2JL*@|?sc1O{S_0$B@v zhd}BrtCt4En-v(0-=casdoWn5fx%leYym(I6~Y?8snY4`r(LvS+h+#>XR?fXjji|zm9fD_gDXXDud zGl^b&wqTebI2N9oX zlDL2Unxt8d#Umf_SUhTgh{={!pEM8=7i&Le5K;TFfrz?~5Jc3gAVTq_kEgo^Xd+9R zj3=Zrb*490k1#wD%Jf6e>pIA=Y1vo#qR&4^|G7Ko+t{NsZ%{sieNnx{f%l4>fH#tQ~4_b#$cx2mZ#&ol}749z^B1UJUoQdR(d(p7MpyCA_T+H`kW z+&va|x5eFSy5}89s9DqtN)nq{6T9U@*oFqGjiZKg0o&LR5@(la%-Pc>$z z9o>`%6&D8Zp1c#YI52&b6^nVGjY>nr!Wbx5{1n2R#SsIhKHtt3ThGrK7&RKH#UM7O zC)94v#e6T|qCgc{V{j@4Z&^x>{I8l)LlP+siXlyHBhW@dc|n`I^UZkSk})Tym#a2+ z=V4nR%(T2+vo3Gfr?R}Gx2(L4ue@q`8kRs*=lhP`vhp?*tyRn0 zkVJXMJ_+S5(u_P5ty-B^TQaJ)=`|GM)A)^7Y5UD(k#WON9dqy&+kg*isP2L4(Od9W zZdfxo#R_bYvut*O(FK8^1g|tP!!O$Guot#h)>VfJzk}_5q3}BuewX6Sz!oZ#%Bq%B ze}vGOaouv06_Kh%nKec%jI_+mrVxd~r=&jon(G=B{xOB``VdiL&874!6s5VaC#r5n zLF0>xZNaqt!0_h!eqb}5iA`uLdRV0ND$-vPd5_3n5&0^SqeL=9x`}*^$VnpK1)0ty zU)=@bNajdivQHARR<$3Kt+Z-Y99lIMWvW_BJL$irXFQ8?)@<*0X?t$H8=QAmE(cc* z^KaR3?_x);M7i~I%=l|uh>Z!0O9Iq^D@wwOb34v`<>JC~x0QuW?}lpBO}2g%TzWQB z4z6W8Fsv!X*A#=;6ahOfzKdIok|Hs)jk%azfsLWy)$Sj*iNNH5+f#CX2PoTl^~)sT6S$SKndIDG=L0c zmuL)y^Z_CnY3j4^Q}-&Z?9^ZyNLHj37c+pf+rNT##c=DxKN@Ia&JzaPmM+_7kg3bF z;Ud*EcG(RqO*2b?G*hxs4`cqCk^pIz8OLrrSp&dViPOmADso1ii#|G4%)KB6U{?XNbf$Et9rLo5l(d*Rr*kkg^lrOW z14|gYoHW!CRpgAE#J(P?0jHns>*3di#~(hwXkQN>-q>CR;sRt2K&=u0WX2)^7#f?k z$u2Kq$O9hBtr5Zknd7&tUR%{5W=iaG*pNiMj$2Y~Cp*)6ZR|CNokZ0A1}k^&ZPsgr z<%xE+*D(FGt-XP%5c#y@)D{&aS1zG|&vpxZ)^_fN;o)3t1WV0rk~WmZc?(v!E8p<4 z?ORu`V>tRogSvgKw)3vJy{?L=|0mwcqJw9u`=Gi6!jXqSB-sKVqKMpDZI zNqiSXL(bdu-D>MwFE*9yZyyefx2{*WtR)z{YBaR^EgcVE4K6>|ba8(EvA68am}9Mn65mV^z%gX-Og$(EV0>U@QwGvo~hBG&`JlmL`$zudM`X!TFz zji@(IuQ|}f|90>|(E0oR{oCEIcm=SpME0$P^BddU2YkLCy2$B=LHB`r?+;@F+$XI- zA>B07&#wT)xMliztKQzKpSSAmr|A~D14vQD1;B+hDU-DCAzfrLxH9KtMPmn$pBi-8 zfh)i%yX}0ZZix%fg*9^KR{VC`?oR?;G+o3lTXP*FKvESs zBQLAS8PEf(Wz+{72TGq=@9_BY|5j1VMR2!)pJ!0Fwo`4E;d+4 zkoPjsrEbt~rex97@PJ#iL4TOSm_Vb-n;ROhDso0nVx^?MK|h&G>KpWb`26w%bOrFn zF1!4q;lM2FZ_O>MzXlAdT7L~mfUBA+x%p|TzqaM^S^dTL3cx{^Hm9c7U-yTrzcBYz z*M5?8Ih-llFNApp(eYu$i`}Q}A_P3rwneDIGFym5e zvgEf-Ddv{w>D1p5+n1XuvguQ&hCrz{h>bH&k+sjZNs&3PUbS9Xhn|f$PqkSJRpcUi zK2(u229{!zwtaaF2M0FiW17OCX2!M5So5zxS*vBVeR%}`qtn$gkyrb4^vyK8O1=5F zEUC7uO>7f4%epIqf1s1AN8Plj%(-*D>pQw%w=n zcjUK^h|SPmlV7h|=xu@2d(=rt5)s;yQXTQuB$Vkda)i|{#;7yy~H z1u4y%Jwd_Z(%+Lng^qygll0d_K7^uxB^Z0eKWaQ6Mch9Uxj}^9&oXZ|t=`~ilA{?k zbwUlpHcon$$k#!vyNhmQlWj67u_h}Pv^!P5u-d9$V23SqUx<+C#))z1EG!edA}nT$3n>WW&9G`P$kM`1JaH^S zv5!QSo;_NMV4L=Vm}SL=wr1CQ#-9FVQDJ%^87CgdO z{B_nUR2DX0ubZN4YDZJ@^p5!t#`#xTf)9GImx=$2x4B>0ED*o#@a^yzyUqQe(>Jz_ zoW?!w2czEcfB^SN>Lz2ulizgRLUof>t%UQItg~~oF!3}7o|B9_jUgtR(=&}eje-16 ztzNR(?1bh)?Dn;+*wliIMpgBaIZsiK5~{c+4QvQEvCG!5)2d!FCGBPx3`sy>pJiiT zJ6U58R7K9n<0^7So*U{V!93T|61GKqRm;z`+po9*H(|y(&7g*DUIm~@v#5&Y33fm; zz}7$qNmXeAP3*#dtIEiL{um_Oyo?M+=4PLcx-09_)~v44bSfwCS3Z z3U~>aN`FCwke?!GFzK-h8!+s|YzIOYQb2}84-q$eB+6#1{FV5V0~C{ZB6d?&G*Kn{ zK}-OtqQ+K+8ky0Y_8Ph+otR7=!3mYx%;36l>tjY8_U>M&xmWfqo+T@jYD z#iSI3@n%>x7-TJzNbNL#bi8OeSCKhbk4^+%!U2nzKcbTt>8wSK#hHo_t`NmhjpvX+ zO;l&CLI`%N}E9Z=DT=!TyA&o=Y5y&Ag4E6?)_o! z8$JQ<2eCz5j4Egi5z@FxhlzZH$S{%XME;ow4vd{*&-8!EgGii8z7xz8d!~?kqqYPF z+{FBf1v0hncFh;u#HtG4h+zu_PPK)ihjrnr~lMb4NA6Kf1R7O3Ej39gW-Cbq=1 zOi#V}TkQmDl;UzzTIae~>YVwj=N;|;A=VLeDMVn26@Y@7Y>%Lnh8@;T5e<~lq>^r+ z5GJ;>gt5ypQ>|*oZ6{}1{xoW;zL?k~&atRf4aK_UiFP?Qomy2@sRr=&&Dz_~Ro|XX ziO%HxBkcX>eY)S@76V$(!kllr-@Wu(s4>zxBBapN&e^yC_E5s10P4{;_pnp?AxV6b z$R846y3I4heT&Gi5HW1?CG38yDlDb{K^}J#IY{IlBHt(S2Si9YdcJ<9JGZLf@GJ#n zsre3Z%#?{RpvAn&&a#QV9A@5hKCWWLpC^asiM&80MdURizeeQOiLh5=`0;CWdz8pY zBHtxaB2r=e)D1V88fFt%8k~wSRg)z(TPyclQ;$Bm1FWn}lESmfUT z(NO1N5j!4lqVpfeqszt@ExXt}wr*z$e|5XCaJzN^_HL^U z5AUX3V>eGkKZXt5Vspo0i%YS^W3d&b*ou+ZDt36&>29|7TH@@XqL6@^6Tgwfm_UD{ znuB^b!tPZ5iU4_)wNi*cQK`k)diMUJ&`L4hUy8Jj3G_FrIjDCd>`vvc2#{A_l>y%_|Jd~&wU15P)l%GI#0W9 z_|pPhgn!e(MT2d#1TJ&`l>?V~vji?f_4j7eIBKIMC5kOQ*lE5+Oy^RWEapiW^tjbf zhER;;MYk#m)WP1g`(MWtOh<6~^JA&5$EyHyF8A{{%j|K#6dHLb7 zJzpr{ukMSV0uZp`?BSxYg1YR(#R&E$qrXwjLA@JccPf8HfV|3DDMU;Vu(h}p=V0R$ z?1f-T5u9mFf1|pKdON~yRsIV2rJ9)PqSCUk)c^vLAEh;^uO}_(Gqmr>@619;(c>w& zupEmQxvZ=BY7(+>qy%GTv3Ghk!slTC%6ceIb^jz?oiUm@Hu=6uK zc>#x@A$@ceEVjDXVP3cpG(upfcRQQl?q)TlmEtT8QllFa0N8&7tJ0H($35l+Cr$O zt`KG?gM^H{jv&WiLx$K<%5>!;Nn^T;{KWc6euga<^J|#oXINiZ-ZIYOcBpY{(|Inj zQEa*}M}MDZpbUD-$#LKGzUcfJw;M`>O7+le?@ae-m?)FLjl*gfsgW46S!Q+G3e^V8Wq)f8fbTswE_ z&np)@o%%ET>7Y~pYZ~{zn#TQabobeo@srlQ3Kpq-Iu=_6@1(C-ju;3_JaF&>OBbxt@M$I}?{$@gq?--3UG$a69XM_*l{=;c#I)Qc zW%_B$IUJ|GYuBE85AE5_v^cs=*;?8!e=FN!A2wx7y8*z|PuVs=oe~u{ZN-qAsVYe~c4O~NuWWfYFTGYzpQuiShWfIYHZ)$Ufl|{&0hpfY zhs3QVH#3<&I+7?!wLw)c9U~d0f%<>Modl_7_{J$mgNU6PV>EY&L_K4hYLc($Qm z!tqU5+&J{P>iBZzv3(8iBmXgorea$4wvhN!;lN)AYl^}eZNc4mzIUQ?UJSnwJ~J>9T{`TZaMbwLycMf2 zHf$S>ZD-8R;(d>d-PcvRuj|d22$$0*${Y8*8QY8FA!99n8r}Azxl6x&_i5kN*0q;1 z<<@*k!QgH5>!{y-O@r7-}ca?+l-)SPF zz2PU$%rOl2n91H5yy_%NJnZ0MZ^$=AQZ?k82ypXL{6DDaDc0?}p{A)A+e_>2kgj4( zWZa$Lw*QlD`bLBEe9UW9(B*)8Uv21e)Cg)kyS&D|ufuzJqZffM-#%x5o%4-4Ct{d{kOd@>A>?29 z3?a`FAp@;Ov(cVdA;^$wP)ALL5D;fDAG%Vq8Z@3}2h>wbS77n2uj7vhij)yt&<&Dx;lys_?O5}NHW zvFtid=AXof_#uqic<$8oY25!wcL(;JRq0Q{zPdgOBSDSkHci(EZphyY?UBq5b=)g8!6m_~2x2bDEg~|9NHdZ7L>3bvJSdTc z`cVA-Jzv=W!2Wvaty7p zsX}9^!_8HK8ws%|4HcdpWTU|kogoYihw+3=#~$2Q9ktCe%HPH-$fF>)9J+;X4&Cm! ze7LmifwFLDI_MVmt$91R=0}YSza1Ffe|7PyONsL0-NV?8q2=nLm6z(ui?-9vf~)hE z6*ulJ&%0}Q|EYuTR>67~A9^#k{px}Zm*y7_KU`k$$XL@Or#%FN?wkzL{L_H6NZnYZ zg`Eu5UR(&va~#Cb0%j!A&Ums-GyX} zKoJGt+ng^k_=YqBpxJ{qyYw>9HiXJapv?`?w!^V+IroF6#(i_0KUf#u7j^$&dw8GA z`&x+K=kUK4b`f7A!2Pv30%TrWBtZVP6}uV{`m%$E_hpxRUnp?d=Y`PasC!?N?{b|N zqL=5o_bv5aUg$-D%gg8NcR1g0I1$QbyXnL9wS0rfFcBYpL4X{b)Io$SBr7)sgZh$_ zh}?_+@*qM@F`}z;FW1cEz)iGOn90?-w;8_MrueRQFVTF#O?;WJ2)x{|u>+^t*il*% zE@?NV{~E|add;hW5=*z_TMqX1rrB|}Ljf_VI5y$NFAl&BEt>EW zCvf2=CW8lg8m|T5c74f4e$)FL$aRU|#J9fBfn3k=ck=w|_c@~14>;!W9q)4>*LU+B U#DZKO;tx3Zj=$xIvYPb&0TCl9)&Kwi delta 3399 zcmb7{Yitx%6vubA+wHd7?Sr~)ffg2|meIDfo*sLjEgQ;nuUFiZ2e5VHnBG&U#RRYKJRv?TH?RHTxt_m*}AP_ z9^EC(5=44hIG2~s<{FujB>VjVUDnlrUy~$~Ne@`(+MR5SIO#9eNvUowGSKTnZtQ`i zNkR@r4SP$#->SB$nZ?XBgRZw-60=~M4U7Wpz!+dGkOOeX1++0a-)Y111mJ$!m7L?g z4a<+g58p=X$sLRNGlcc#tCiIlh?%Ju{E#UIxjA3R$`8=Qzq?3vh43x17rhS z?F8adq!PMHdTaDzGes(CU&`p%6Jz>q&Q)ya=3aq~*V8fM>l%10g0K%U{FPy@$5S*p z*gaF!5XPBgAsaEW*?D&iPnE@(wgh+-Xr$5c1vM{18A}23Dpa;$ zK+_E;@+YK8EdifG)?(5+D)@3DaWTbu?}U@PhF9)~$J9t-Zdu87sES`FZ(wXIunlMh zA`E7zTLYw1)~kpDbsO*$pfYGEPLzcwgL42R_wYfFt^Ng=y#&0%5YCi|uC}roD<#TC zRoNs8WD3(SBE2x7z-z$kz;2)(*h3GM=GBO!$bLKx4-+{69il_Z0T1vNa1a;_k1{+w zQJ0x$2_i!dVdmSwNMRv|*{J4X7`kcJ8e%7kf=TY-+cvisrZdFJS&4R55zYFKoh8~& z@$mhSBO|ToH?d=+6?K&sC0bE_;d|Kph#r3|EfyZ@VY9_* z+4m0gr}%-m$i|=pj?>dk#b$J4v0F`@cA=WCYbg|J>5Xb{#BdI|#iBN|$pnz=g?IR~q_LvcWdUQfD#Fz__M z&t?mx;rVaaS-e6Wx_OIan8nRKdtrPL7(AV4@QC)sS{nQ1Aw6vyl;&yCe`@mVx$M~} zq1SvR^sH~8^@=6tR4Ov0&tY~RsAdSK@U4_qk_%AP0$(r~_D7VkzPm|unE`<^wSGkL1ZaJogqB*CYmm4{CW~|$YmJB z#TvO!&H(>A;N%LX;m+nOi-_*{n16+_uL102gy^$@HjMIm*$xS<)hwE4Aw37|U>JH8 zP2)$TxtV&P0n?xMWtxXoO6P=1X;EmA^@b(Z8R~aLa9DSaX#TJRtBpS}2VMX-Dw1p- z8BgVpumUfG;phq}A;l*(4{bMWfL%?AqU&Kp?EQyj6IlWA|HqiW5~all_Io({0Z5e5 zh@_UraOY~W;hmL=kq+x0me`(1OsKziE4d2K-vR~@*Hq3z2VAz$-tEmBa0dKYw3%;| z=b54rHv_JAvKkQYN+{{DTh_Y$Eoz`_QAiIF#k0lJ81O6nEj#S=sV(||1~ttL{3Mml z5)0{>Xn_!>*P~ONybF}T>nd7sY}N+D6=K%|T4-5kprzf6^h%5`12EtGpTLTJp!f4P zy&gQGL-HNOZPjqh?hN=s9m*W?D>FeQYG>)GV<+YhCdewRYKM876$$|<6kdh B^ojrg diff --git a/tests/__pycache__/test_subagent.cpython-312-pytest-9.0.2.pyc b/tests/__pycache__/test_subagent.cpython-312-pytest-9.0.2.pyc index a70386ba011698e027f84cdd169e8f0fd83057e1..6392174b7173b1893d0740648a93eeb0f65a3cee 100644 GIT binary patch delta 7328 zcmbtZ3wTu3wLW`Z$z<|=ha@mjAdW(KN_d7uN%%-0R1>%bs>7I>gfa7CpA$(!!X$zM ziUMwxhd_zeVg!^r{q6;^wNOF%01b*4Jf9Y9^{d+JS5zz(?e*?|pCl(tV@rDn{aJgh zwb$8ut+m&Fuw$38BVtTEnUD}C@!xF^9`l~8{YB#Jd~%g7%>NVdv)hK=X<5NVw3%%m zTAM4#Aa7qybjh-ZD)tdKg<2*#WZJ^4!@eg9v)ZSUMmEcS3u$5@dnM^$hdKRVW%KGrxB0zp~v*3oqkt_M5>XaO7q zJitM<$cjs8l2uE+%j@&F)zn5db4(6tXN$%ZST;g!6YCgLuKYz4I& z@FZXhU>jgN;3>ckKo{U?4vu6x74$QJpK(x47%go?yNMMX&Spy&n6g!~=RQwBq5Hx9 zIbaXqKxD?)pwaRR(62>anlQ&=TMN1euz^{oP9m?e8BL;S75PJcaL^yK#Mw85&!X1` zfF81_XkDAZj`%^RHegmTHXs^kiU@tmDLI~lUH?U1oc%4C0RPeBfY$+^0WJZ)0^|Ym z0Yd>N1h5b0_zWi`w%30?@~6tOSS|g>L)OEJYZlrLfz*v9MJeR;5!cLOHtN97Km-0tTrrj%;d&Xd|Pwj_}_=P6S-1pXn1& z-U-l4O@H+eMaPk;mk`zJ3Wc1gVjfWhRFmS88>#rLM5Hki73)RBMPD>x+Im$%QB{eL z8VRdjkZGX%Bd!IVvB_63h;IP%0Dom)-gSXk*xPqsvRnn@TlR)?a`-!t|I49TOV97o z=AV`*0q9;P=+2k1`Si>3vg zQzPSCYYeO_F*7{ZC`oH=Rov1R$xYk_pX4X)1|lhDt}T9U<37_~-V48WqY|T0l4OwD z3~uv2OP_3COdr)|bfVCSpJMBy+K4;0mACq|+D%G=l-4V4>;J^PN$g0{kP;%ftpoe^ z^=dP@<8~O^%?;8+wsp38;`UBh&~$F)bLBHl z^2PaW?cAY!9x-j^Hlvc$X9JGHZ(s6W?j8JAOYW4FoPN@@#rUAv3=1jv(`R##c53Px zX}xWh)Mu@^$2hvS#R`~^1J#**~ciMW}Q_@aD-_+dct^8B&45ffwn3TsZEw&kR zlzg^pNnWNhL=1yNpE8B0XL(-s--`l-+kh~ijY^9n8ue?gA^x5Nz z$x0rx?}=lp=Glg&G?Vt&c56#Yv9#fX8>MlQOjhu0Sj1;cqz&)04*RWty4+a_>gr-9_pc?RI zU2nWNDM`p+o?qlEl+P!~7KvvdX}pPd8n5)`v&3^)>CFr7+g^$mtT(bR64TkRq%2mt z!5Z#!I+0q$ABVA8jpeJ|g{jjS+`Pl2#(8CLfY-f1orm7QS(I^5jSU`!3yr)es&S%t zJC&A@M~w-&T6{s5TTQHUg_I`hapS<@@yS>@d|T=edyHy>l+8aB8@{8~BP%r_*NQ+* z?}v*N&e3`~>%AVI+sUg>$ko6j;dUxPrx=}9iHoNDf^{yRTvF8gH77p@-_D&NV<-5g zLpq<7vvu*?Nrn3=53G32baqtv`Q)MJl1H3L9rBF$mDiEfhT%W zXLJXiOW8DTYy7)u!@C226%n~VDTTD&Qr;Z$)N$|H3*q|F;)8{DZ@^wtQ*KY~ji@}z z-VjvmtwnJqY;*q5@K}d@6Yd-19kL^?oo7Ozg<^wuWU98tpesx0zqQk>dN$1jH){_#bi?-=zA%!)CHEkc~% z#db3Sw#8QVEL8OUWH=W@AEQdO$lR=_X851wX6y9-S7u`njKen~dS6>4>)4Od?YrG) z({EX4eLr_Z)_d87&$XS+o_^VA$ctNNJsX>SIabQfWht*rvJS~xmw4G^uuf+`dZj!Z zFQt`q2i{4YaY-W9DzZW5x$sU>Z|h9bjLU+3VM^thDV05mQw|pOOqtUYUwOp{?Ox%m z$|DsT<4a9@eC3((m6wfDa@rNa_(EfsRUXM1z=d+Sid+DjFR`=|O<5aAA2+#|tI2xp z7gwGs?j6Ekgy~CWDPcDG=1Po|IGgk&R9wAcloJ1gQwzV7=kN%wE-R@RPL7hqifrT2 zr2L9_^U+bHA};o5c(e(Paj_6gxjltz9gicNbv)i&kzqZa62k?@v&|I+F~{>`xU||~ zrP;^{?3@%^l(>KlI6zyGJ2`;SfIO(=1H=LPYfymC`Tz1=?EAW@qc0f>%teEE zC%_1<5Z8OObHr(9IhYf@RT5H(hfXHBoG}GlEHBko8fxiX!V~BoHf-5KQX9E%*=0j` zJalmG?KTXU=dIvIFpz2v4l~uKEc_rmqD>h}#Zc#mD}GB1IqQO<7CIH2X#nAaM2c;J zP6x~a%mDD|I{&@-3TwiUa2Y;Ld2}T@6Cf%|DJV>pKQ#C%$lYv@@7RrHV9o|aCCwP{ z05xo*e+U^9dETFp7<&?vH_~(L)s=HbzQr5eG4yRrSj=A(GjSz*2fVX@cOyk@29hj9 z4}kG2Kqf0~cjR<&QZ>7q{2|#9Lq!!Vz-JG!``cHM)r_o?$$8eaY92{vzg;!a@goS^ z(H{>S+S5QMsQUq{0e3*It^|Ho+RcZ}_5M%|tJUpiE?H{kX(JMsqHEyO3Iz9x2o-@(!n{&6+N zUl+nzLrvi6&rWpM9G^h;K0w?v#5F{}(22;3y`r1_tz)5O5oWNME$UoO0+ExQFImST zWIUC{XT|(Rz!o-R?Y3ME3i+Ml?? z@2I4iI?-4v8ZFc<{%)o9U^cL#O?FEsNWyA26^BJ4lyVD>p}h|yu%?H4K$Ia6Cx9$a zEOk>quL zz>5hp!F1K(@^r4Wf34H73gnSazSeynP2GJEzZFS!^= z+A-WvdX+1Q+_#p9G}uH#pnX8NBn z^c3dE`s_Hu$d2(r@IaGM!+TjTtSZj9tU&*o(Aj$Yz6EFTpJTH@N2_X z#?KQ2O60HS1y@+ji52fV$2=K(JQK4s55zr~Pfh)m!6lZ3y2`g-o5CxdZ4 zz8VVnOy~`O8#%Dihw@@5PVKFW*$aou+0H{5WD<)U8Wp|@yWav(y|jO(_zq3+TE<`M z_{~&%Myvr>I9vv$a8Pac1cQn*5LCSNgFiq<#|Aw`Y;Ohivcxw>E%perzF(?lVKe&Q z14Mk%s2#c@J{C|W3|#DdE;OU=L3T(n*a4B!7gOmrNUn{XBV$02M1|{tk|;3x%|{$t zo+2!1Y$kIqFpr=+@F6{jB7S<^+s37G2D`g6iz$c0q%d;%@JqIP!~re>>*eSzPHw`_ zzXWe1cw%LUWZ%S_YK-FbdxA|0-?7@Dvjz~I?BKyy)s(T=H_9eo0OKOyLx4~pbm>5< zFTKsI^Nq>jzSCasVJ`tXk6~nb=Ij0(#GPWfIubRX>L)&N*xL;|Vuuh(F0xB@(@Qc=U`XPABF>wlvOU6XeltJr1>S-GC&{m~ ZJKo%$Ol+%FBl=QfZJnCLWKvrvCYsdV?^)#G2J=Vj z=*M&KJ@34G&$;*9^R`I~?|3OZ?pSPWOqlqS(9rAr;^8;qN;0H+z9i#{BkN&U*Q0$a9jan?d#l)K44nszSD5|YYQ@7oLN7UkJoXxzuLHXP^4)Ij z-!qm*NFVUB!u#j`L3Do_fw4aVe*#Vj$dVpi;q|(T8S^ssA-em3v%onhB(RH+kMZ8Z z$xA+m_%~o+M(posV$tk~fbg%wsVXYFBpPy5Fy7?0e?Wy+Lskp}m$lM4>1Hue=e&{S zm?*mf+&R&q<`z5=e;Kg*F{BH?Uj^jU+cWQ*myveYNnhe|C8GnU@KhUMge)Xl6v2Uz z$-{FoAF2MDY+?4h5uMDa1{6y_!9URkPc)3nZWx5ety2o z^nMs$)Sbc;;-1zr7tV_c9)T$sKhC}7ORR4~3~q3KqI_JA3+*+4vHw@1=>+I7RzsrH z^EMw-F{=b8T({z|+UX#wp_%6(9?*ax(u|zKY#7?i_f^PQ-$Kj-hV(U3M&K71?f{G| z(~0Iz0JD*kja;HfJA6Jn5|~0qUytxR)M`dAx`hYmkWes;lS1n>QVG(JF1eUV68gNU zH^rnT^9yaM+QA=JM#X;xE7yTVz}Nh~$1X@_9%KKfSTG z?+=4f!`bUG@Q#2UUFmiET#8?*8q#mc{eFYK1qkOIkLPAbz#Ofv1f6$v&O8P6tYPRDvvahW*oDdPbbHuUbt8_NV_Gc%S?J|WHE@}V>u>au`t@!2cA zzB)DrJ!1h648*Y<$m4)qU_2leZ2#X@OxDN{ISsF7lY#pHI))POWKO+KJ9 zfD++J^qm4uYdsrGQalX}oI{qx-`gmsb_xaETvg-tsd6O4;n2fHW?^sg@a9Iz!Phmb zQXl`Sd6AUJi(2yJ8JJfCtTqC4DK|k{3s7D0AXH}Zoh@6F2KF6!Jy?I$^F^(B*%zTs zm!xq`O~ZrvfDNOY`R>-S0pqUCL+2&HIQ_K$LT;^r3rjaUJylAroIWTA&@1W6GTuff z`aBGmh?nb;?n)nu5j|EM0=}TlDqqGJEtL`irB)-WQgkUv?B$JZODx4$!91?Ft&&Q$ z(oOrLCn02FJJV}vePdv7I`qmRJphTaEaJ%uw44_rOiM!J1*O>ny2)EjWv^^u$!MEZ zm!kNB*|HE?ov<=TNc|yYbJ0t8Vi9lNHrs-A)|YVGrV;$ownMQ1thX}4M25X1O~?fDaE6BG&ya%O)y0&7N?2S+%6 zdq#lP5K-!_tY%ALWf?%x`Qg}ygdJN!Pw3Ap_F$TGt1FC>^Nzc~*avfIK6mZ`_A|`k zF@R!E5vMpCVXwxh3vlzujy2*7CeU%*l8soi73emC92#HFx|oH+JDY#jWy?j-M2e@Y zX;7#{uNooDp=b(LKoqyd6t~5@9*|D()?Ks4-92opjIfC?eYtC75q(h6B~9Bo4D(!z z85=>nT|=UG=%CHno*4LlBQ+>2gTIiBu>5dT(u^Y+8XG=yQYKH?-J=u@{eF4 zy}(gG!IJ$zEfA7+^Uwz@gnc6uShBE08IUs*J`8Z9E3<` z>n%vX6VM~86u_Ej?j;V%xpvkd=a%C6BF$dNIQ0}8V zM=sxkzI_0Fd%X_n6P|ovtLbw|>pAe#*zZ@6BM&P%TZEq2>)7Uc3>DUPf1OX!BYloK zm)B9H4-*B7y}zOIV=L38r9AFvG5_vxl5`JGJTfux4PJEvKz0iL0&o*eDnvykEbIjf zbIPvdbcS(NK)3$f>-F0`UcYns&?S9neDEa2_kKukg#`pD{^Y-byHGciP1XdhwE#tn zVwA{i=%5%`AcbS%F_0X9QQhK_)5BMY4{1zx&`oD#yW(vap_{KA(sltkX;9oKmr;75 zjM9R4eG5%0OWM$UIgCHmJ0g1%WFxK=QX|7Pi%~U6d=ZS`r+WjES*tj@-|D0S4JU$4 z!qYZ@{H&p`0ZsA_ZTP1|Q;+mJ-HNxyFK(kJp+i+`=!VAtd{xGp1ZAmy8vP{EdNOPJ z#~3qqJv}+(NrIkn5*zu&lhbo<7k2%1T`Y70m}KxEplP_4e!Q9gj_4E>Vgbf7p-O(E zO71x{=^~&_Pp2Wc^Py~12f@R^yG}Jo<2BpqPSf;|G_($eHUnFLbUdCxF9hn*2V9Z( z*JmCPKdvq48znu@U42unG;iFQtdsBStB{WHTYYKLIG%QPSrUCAUxS4-C{Q-5=dEWm fVs?nO_#37k=5L&Bx6YPwu7(L*f5^m_o*VmLNpjGm diff --git a/tests/__pycache__/test_web_flows.cpython-312-pytest-9.0.2.pyc b/tests/__pycache__/test_web_flows.cpython-312-pytest-9.0.2.pyc index 977cdd7248e8358794e2125a5ea4ff1960101db7..bad6e6dbeeea9ec2762cf72ca854df9d412e651a 100644 GIT binary patch delta 1710 zcmcJPO>7%Q6vubGldSFaM-rN^#vvh&nmDPG(nFG#Qm8OZ(n_VIg#r??R-P@fV(*&S z&6ly|f>7y!stHpF6*;8PL!*LJ8V0;l18z%s+3+ipoAiEW!|o1az=TiYNNMt3hUQd$3rG^2M7&uei}n@zKdYkbISwp`QRgW52!nJ-S}Zp8Ci=u*f}G zpE{#z=JC$Vq++Nv3_)`omdEzT4U^J&aAsNf%;)F^yMHFucmo_a0mlI^0dmZ9b{s7g zFPv?Y&;rvZ(rA%AnfMUhD!y@H0lkwzJZi7`xDW*aJ-dSiVM!o}xKctI|nE z&rXewv+WTd`#shdtS1f2u52xjts&2m11x=dl-&>E4l$2&F4AaM5lK^C%85B?s+Y&% z95zzyw6d)i?H*DTG+40a68UR zB$OBV907X{yZ+4n>du+`(s7Qu_&bgu%bl4vCgX;oT5?h|RjMS+ zq^@P_XLUMtIi=4=iJC|n++~TTK4tlInwV7iHBwBSS~#X_YSv?_iOFatrDzt`)H(BF zM5J&TEh(Y%l5?gdQ#GNd)2c=aDv5{|rg}=X{D!HR(?*=C8J(I|Lp4Yxar^!n5Ngh6 zRI7&1t!kDxF{zkwbDC-f{esW1?}AGiWj>`Vq;kDsuoJ*IvQ4lXBcmkLLNu);wWz%? z&7^RAQ~{g@i~+_uvcc;9^$ffas)4tOD5es%*Yh2Al`H$zi~6q_f&+fSXpo$MqSqt>s^{)knu8fxD z`VtOZ8(O$jl0#b<`le$$#zp}wM_0)+7A{rB|CQBYE;eweEH^BStjVDg9w~K>0J-ku zo{=pKeRI#_m>ag~=yf~A(FNyG4Jt#$!4>Il?d>2Jyy!}>BoA(3=$jRXV{O=$qt|&( z(2@JeL&|cvgojpU@6OyVa8Z)OD}|EGw+wv~A9Fm8xnYkxdYvcn#Z>~U;t?LAb^N#@ zz3l15$LLG;^IJz=%WwxZ0eQf6z!KmV08V&Su(O;C;y#hq$#hCRNq^!)@bfm7SpVA# R!9Tm*XyDnwMl@_k{{!NF^Jf46 delta 338 zcmX@TkMZbQM!wU$yj%=G@S^ExCX?_)J_$ypjq1vbER{@}qMJh)ud6d^Zr0HhW#q~S zDhdMP;+DyRO4^&twDMUQi#I>h-^|8Xvw4=8JqKgy=392}7zJ8^ii#RRL>rLM6q;Nw zqA|&_p0Q_hgJU&^-UOgv6;EneYF>$zLP17iacYq=NO3ukxWx$;k1sAMDyjepR!-LR z>S64gyv@r+v=1aO8AMot2x|~gJ(=IzlX2SSNN;I&&VG=HIFOk9QA1_&!XQT$kX@7C znHo=)47O&Ru{kt&0wa^A`sCQy+l*5tTgDmKfjm`I3?gbkL=T9V1|ntviIogR0w6XY lkhsNRlbfGXnv-f*v;xRw1mfaJlh?#e;QFk>!KepT2mk`CTKoV2 diff --git a/tests/test_interactions.py b/tests/test_interactions.py index db659bb..5e33d4c 100644 --- a/tests/test_interactions.py +++ b/tests/test_interactions.py @@ -167,6 +167,75 @@ async def test_workflow_decision_stale_returns_409(self): assert resp.status_code == 409 +# -- TestWorkflowDecisionValidation ------------------------------------------- + +class TestWorkflowDecisionValidation: + def _setup_workflow(self): + """Create app with an active workflow-decision interaction.""" + from starlette.testclient import TestClient + + from koan.state import AppState + from koan.web.app import create_app + + app_state = AppState() + interaction = _make_interaction( + interaction_type="workflow-decision", + payload={ + "chat_turns": [{ + "role": "orchestrator", + "status_report": "test", + "recommended_phases": [ + {"phase": "tech-plan", "context": "", "recommended": True}, + {"phase": "core-flows", "context": "", "recommended": False}, + ], + }], + }, + ) + app_state.active_interaction = interaction + + from unittest.mock import patch as _patch + with _patch("koan.web.interactions._push_sse"): + app = create_app(app_state) + client = TestClient(app, raise_server_exceptions=False) + return client, interaction + + @pytest.mark.anyio + async def test_valid_phase_resolves_future(self): + client, interaction = self._setup_workflow() + resp = client.post( + "/api/workflow-decision", + json={"phase": "tech-plan", "context": "go", "token": interaction.token}, + ) + assert resp.status_code == 200 + assert resp.json()["ok"] is True + assert interaction.future.done() + assert interaction.future.result()["phase"] == "tech-plan" + + @pytest.mark.anyio + async def test_empty_phase_rejected(self): + client, interaction = self._setup_workflow() + resp = client.post( + "/api/workflow-decision", + json={"phase": "", "context": "", "token": interaction.token}, + ) + assert resp.status_code == 422 + assert resp.json()["error"] == "empty_phase" + # Interaction stays active (future not resolved) + assert not interaction.future.done() + + @pytest.mark.anyio + async def test_stale_phase_rejected(self): + client, interaction = self._setup_workflow() + resp = client.post( + "/api/workflow-decision", + json={"phase": "execution", "context": "", "token": interaction.token}, + ) + assert resp.status_code == 422 + assert resp.json()["error"] == "invalid_phase" + # Interaction stays active (future not resolved) + assert not interaction.future.done() + + # -- TestFIFOActivation ------------------------------------------------------- class TestFIFOActivation: @@ -260,3 +329,146 @@ async def test_next_queued_activated_after_cancel(self): assert active_a.future.done() assert app_state.active_interaction is queued_b + + +# -- TestArtifactReviewResolution --------------------------------------------- + +class TestArtifactReviewResolution: + @pytest.mark.anyio + async def test_accept_resolves_future_with_accepted_true(self): + from starlette.testclient import TestClient + + from koan.state import AppState + from koan.web.app import create_app + + app_state = AppState() + interaction = _make_interaction(interaction_type="artifact-review") + app_state.active_interaction = interaction + + with patch("koan.web.interactions._push_sse"): + app = create_app(app_state) + client = TestClient(app, raise_server_exceptions=False) + resp = client.post( + "/api/artifact-review", + json={"accepted": True, "token": interaction.token}, + ) + + assert resp.status_code == 200 + result = interaction.future.result() + assert result["accepted"] is True + assert result["response"] == "" + + @pytest.mark.anyio + async def test_feedback_resolves_future_with_accepted_false(self): + from starlette.testclient import TestClient + + from koan.state import AppState + from koan.web.app import create_app + + app_state = AppState() + interaction = _make_interaction(interaction_type="artifact-review") + app_state.active_interaction = interaction + + with patch("koan.web.interactions._push_sse"): + app = create_app(app_state) + client = TestClient(app, raise_server_exceptions=False) + resp = client.post( + "/api/artifact-review", + json={"response": "Please add more detail", "token": interaction.token}, + ) + + assert resp.status_code == 200 + result = interaction.future.result() + assert result["accepted"] is False + assert result["response"] == "Please add more detail" + + @pytest.mark.anyio + async def test_accept_mcp_handler_returns_accepted_string(self): + from koan.phases import PhaseContext + from koan.state import AgentState + from koan.web.mcp_endpoint import _agent_ctx, koan_review_artifact + + import koan.web.mcp_endpoint as mcp_mod + + app_state = FakeAppState() + old_app_state = mcp_mod._app_state + mcp_mod._app_state = app_state + + phase_ctx = PhaseContext(epic_dir="/tmp", subagent_dir="/tmp/test") + agent = AgentState( + agent_id="test-review", + role="intake", + subagent_dir="/tmp/test", + phase_ctx=phase_ctx, + ) + + # Pre-create and resolve the interaction future + interaction = _make_interaction(interaction_type="artifact-review", agent_id="test-review") + interaction.future.set_result({"response": "", "accepted": True}) + app_state.active_interaction = interaction + + token = _agent_ctx.set(agent) + try: + with patch("koan.web.mcp_endpoint._check_or_raise"), \ + patch("koan.web.mcp_endpoint.enqueue_interaction", return_value=interaction.future), \ + patch("aiofiles.open", side_effect=FileNotFoundError): + # We need to provide a real file for the artifact read; + # patch aiofiles to return content + import aiofiles + from unittest.mock import AsyncMock, MagicMock + + mock_file = AsyncMock() + mock_file.__aenter__ = AsyncMock(return_value=mock_file) + mock_file.__aexit__ = AsyncMock(return_value=False) + mock_file.read = AsyncMock(return_value="artifact content") + + with patch("aiofiles.open", return_value=mock_file): + result = await koan_review_artifact(path="/tmp/test.md", description="test") + finally: + _agent_ctx.reset(token) + mcp_mod._app_state = old_app_state + + assert result == "ACCEPTED" + + @pytest.mark.anyio + async def test_feedback_mcp_handler_returns_revision_requested(self): + from koan.phases import PhaseContext + from koan.state import AgentState + from koan.web.mcp_endpoint import _agent_ctx, koan_review_artifact + + import koan.web.mcp_endpoint as mcp_mod + + app_state = FakeAppState() + old_app_state = mcp_mod._app_state + mcp_mod._app_state = app_state + + phase_ctx = PhaseContext(epic_dir="/tmp", subagent_dir="/tmp/test") + agent = AgentState( + agent_id="test-review", + role="intake", + subagent_dir="/tmp/test", + phase_ctx=phase_ctx, + ) + + interaction = _make_interaction(interaction_type="artifact-review", agent_id="test-review") + interaction.future.set_result({"response": "needs work", "accepted": False}) + app_state.active_interaction = interaction + + token = _agent_ctx.set(agent) + try: + from unittest.mock import AsyncMock + + mock_file = AsyncMock() + mock_file.__aenter__ = AsyncMock(return_value=mock_file) + mock_file.__aexit__ = AsyncMock(return_value=False) + mock_file.read = AsyncMock(return_value="artifact content") + + with patch("koan.web.mcp_endpoint._check_or_raise"), \ + patch("koan.web.mcp_endpoint.enqueue_interaction", return_value=interaction.future), \ + patch("aiofiles.open", return_value=mock_file): + result = await koan_review_artifact(path="/tmp/test.md", description="test") + finally: + _agent_ctx.reset(token) + mcp_mod._app_state = old_app_state + + assert result.startswith("REVISION REQUESTED:") diff --git a/tests/test_subagent.py b/tests/test_subagent.py index e569aa8..f4245c9 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -299,6 +299,40 @@ async def patched_subprocess(*args, **kwargs): state = json.loads((Path(subagent_dir) / "state.json").read_text()) assert state["status"] == "completed" + @pytest.mark.anyio + async def test_model_field_propagated_to_agent_state(self, tmp_path): + """AgentState.model is set from config model_tiers via ROLE_MODEL_TIER.""" + from koan.config import ModelTierConfig + + app_state = FakeAppState(port=9999) + app_state.config = FakeConfig( + model_tiers=ModelTierConfig(strong="test-model"), + ) + + subagent_dir = str(tmp_path / "sub") + Path(subagent_dir).mkdir() + + task = { + "role": "intake", + "epic_dir": str(tmp_path), + "subagent_dir": subagent_dir, + } + + captured_model = [] + + def capture_sse(app, event_type, payload): + if event_type == "subagent" and isinstance(payload, dict): + captured_model.append(payload.get("model")) + + with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}), \ + patch("koan.subagent._push_sse", side_effect=capture_sse): + from koan.subagent import spawn_subagent + + await spawn_subagent(task, app_state, runner=FakeRunner()) + + assert any(m == "test-model" for m in captured_model), \ + f"Expected 'test-model' in SSE payloads, got {captured_model}" + # -- fold purity (supplementary) ---------------------------------------------- diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index 88e71e4..bb582f3 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -157,3 +157,29 @@ def test_live_page_when_running(client, app_state): assert resp.status_code == 200 assert "pill-strip" in resp.text assert "activity-feed-inner" in resp.text + + +# -- Workflow interaction SSE payload ----------------------------------------- + +def test_workflow_interaction_sse_payload_shape(app_state): + from koan.driver import push_sse + + push_sse(app_state, "interaction", { + "type": "workflow-decision", + "token": "tok", + "chat_turns": [{ + "role": "orchestrator", + "status_report": "Done", + "recommended_phases": [{ + "phase": "tech-plan", + "context": "next", + "recommended": True, + }], + }], + }) + + payload = app_state.last_sse_values["interaction"] + assert "html" in payload + assert payload["target"] == "workspace-main-content" + assert "workflow-option" in payload["html"] + assert 'data-phase="tech-plan"' in payload["html"] From 0d414daca7a0bdb2af5e93c68bde0cd69a75f585 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Fri, 27 Mar 2026 02:41:22 +0700 Subject: [PATCH 173/412] T9 TS Deletion (113 files) --- .config/wt.toml | 6 +- .github/workflows/ci.yml | 21 +- .gitignore | 4 - AGENTS.md | 67 +- README.md | 100 +- docs/architecture.md | 414 +- docs/artifact-review.md | 181 +- docs/design-system.md | 76 +- docs/epic-brief.md | 119 +- docs/intake-loop.md | 452 +- docs/ipc.md | 458 +- docs/planning-widget.md | 4 + docs/state.md | 284 +- docs/subagents.md | 458 +- docs/token-streaming.md | 228 +- extensions/koan.ts | 242 - package-lock.json | 4618 ----------------- package.json | 43 - src/planner/conversation.ts | 35 - src/planner/driver.ts | 525 -- src/planner/epic/artifacts.ts | 107 - src/planner/epic/state.ts | 220 - src/planner/epic/types.ts | 66 - src/planner/lib/audit-events.ts | 139 - src/planner/lib/audit-fold.ts | 196 - src/planner/lib/audit-log-formatter.ts | 475 -- src/planner/lib/audit.ts | 13 - src/planner/lib/constants.ts | 5 - src/planner/lib/event-log.ts | 247 - src/planner/lib/ipc-responder.ts | 319 -- src/planner/lib/ipc.ts | 308 -- src/planner/lib/permissions.ts | 211 - src/planner/lib/phase-dag.ts | 74 - src/planner/lib/pool.ts | 91 - src/planner/lib/runtime-context.ts | 53 - src/planner/lib/step.ts | 60 - src/planner/lib/task.ts | 140 - src/planner/lib/time.ts | 3 - src/planner/lib/truncation-override.ts | 90 - src/planner/model-config.ts | 152 - src/planner/model-resolver.ts | 14 - src/planner/phases/base-phase.ts | 225 - src/planner/phases/brief-writer/phase.ts | 49 - src/planner/phases/brief-writer/prompts.ts | 101 - src/planner/phases/decomposer/phase.ts | 37 - src/planner/phases/decomposer/prompts.ts | 148 - src/planner/phases/dispatch.ts | 113 - src/planner/phases/executor/phase.ts | 43 - src/planner/phases/executor/prompts.ts | 154 - src/planner/phases/intake/phase.ts | 74 - src/planner/phases/intake/prompts.ts | 499 -- src/planner/phases/orchestrator/phase.ts | 59 - src/planner/phases/orchestrator/prompts.ts | 297 -- src/planner/phases/planner/phase.ts | 41 - src/planner/phases/planner/prompts.ts | 212 - src/planner/phases/review-protocol.ts | 33 - src/planner/phases/reviewable-phase.ts | 75 - src/planner/phases/scout/phase.ts | 47 - src/planner/phases/scout/prompts.ts | 151 - .../phases/workflow-orchestrator/phase.ts | 107 - .../phases/workflow-orchestrator/prompts.ts | 102 - src/planner/subagent.ts | 266 - src/planner/tools/ask.ts | 364 -- src/planner/tools/index.ts | 23 - src/planner/tools/orchestrator.ts | 245 - src/planner/tools/review-artifact.ts | 148 - src/planner/tools/types.ts | 1 - src/planner/tools/workflow-decision.ts | 243 - src/planner/tools/workflow.ts | 102 - src/planner/types.ts | 81 - src/planner/ui/config/menu.ts | 88 - src/planner/ui/config/model-selection.ts | 205 - src/planner/web/ARCHITECTURE.md | 199 - src/planner/web/css/animations.css | 76 - src/planner/web/css/components.css | 1087 ---- src/planner/web/css/layout.css | 545 -- src/planner/web/css/variables.css | 110 - src/planner/web/html/index.html | 17 - src/planner/web/js/app.jsx | 17 - .../web/js/components/ActivityFeed.jsx | 444 -- .../web/js/components/AgentMonitor.jsx | 56 - src/planner/web/js/components/AgentRow.jsx | 132 - src/planner/web/js/components/App.jsx | 64 - .../web/js/components/ArtifactsFolder.jsx | 245 - src/planner/web/js/components/Header.jsx | 28 - src/planner/web/js/components/Markdown.jsx | 21 - src/planner/web/js/components/ModelConfig.jsx | 173 - .../web/js/components/Notifications.jsx | 25 - .../web/js/components/PhaseContent.jsx | 32 - src/planner/web/js/components/PillStrip.jsx | 37 - .../web/js/components/StatusSidebar.jsx | 166 - .../js/components/forms/ArtifactReview.jsx | 82 - .../web/js/components/forms/QuestionCard.jsx | 89 - .../web/js/components/forms/QuestionForm.jsx | 134 - .../web/js/components/phases/Completion.jsx | 23 - .../web/js/components/phases/Loading.jsx | 14 - src/planner/web/js/lib/api.js | 31 - src/planner/web/js/lib/utils.js | 21 - src/planner/web/js/sse.js | 71 - src/planner/web/js/store.js | 194 - src/planner/web/server-types.ts | 336 -- src/planner/web/server.ts | 1150 ---- src/utils/logger.ts | 41 - tests/audit-log-formatter.test.ts | 205 - tests/conversation.test.ts | 103 - tests/event-log.test.ts | 131 - tests/phase-dag.test.ts | 227 - tests/pool.test.ts | 72 - tests/state-machine.test.ts | 480 -- tests/story-discovery.test.ts | 84 - tests/subagent-args.test.ts | 43 - tsconfig.build.json | 14 - tsconfig.json | 15 - 113 files changed, 1047 insertions(+), 21638 deletions(-) delete mode 100644 extensions/koan.ts delete mode 100644 package-lock.json delete mode 100644 package.json delete mode 100644 src/planner/conversation.ts delete mode 100644 src/planner/driver.ts delete mode 100644 src/planner/epic/artifacts.ts delete mode 100644 src/planner/epic/state.ts delete mode 100644 src/planner/epic/types.ts delete mode 100644 src/planner/lib/audit-events.ts delete mode 100644 src/planner/lib/audit-fold.ts delete mode 100644 src/planner/lib/audit-log-formatter.ts delete mode 100644 src/planner/lib/audit.ts delete mode 100644 src/planner/lib/constants.ts delete mode 100644 src/planner/lib/event-log.ts delete mode 100644 src/planner/lib/ipc-responder.ts delete mode 100644 src/planner/lib/ipc.ts delete mode 100644 src/planner/lib/permissions.ts delete mode 100644 src/planner/lib/phase-dag.ts delete mode 100644 src/planner/lib/pool.ts delete mode 100644 src/planner/lib/runtime-context.ts delete mode 100644 src/planner/lib/step.ts delete mode 100644 src/planner/lib/task.ts delete mode 100644 src/planner/lib/time.ts delete mode 100644 src/planner/lib/truncation-override.ts delete mode 100644 src/planner/model-config.ts delete mode 100644 src/planner/model-resolver.ts delete mode 100644 src/planner/phases/base-phase.ts delete mode 100644 src/planner/phases/brief-writer/phase.ts delete mode 100644 src/planner/phases/brief-writer/prompts.ts delete mode 100644 src/planner/phases/decomposer/phase.ts delete mode 100644 src/planner/phases/decomposer/prompts.ts delete mode 100644 src/planner/phases/dispatch.ts delete mode 100644 src/planner/phases/executor/phase.ts delete mode 100644 src/planner/phases/executor/prompts.ts delete mode 100644 src/planner/phases/intake/phase.ts delete mode 100644 src/planner/phases/intake/prompts.ts delete mode 100644 src/planner/phases/orchestrator/phase.ts delete mode 100644 src/planner/phases/orchestrator/prompts.ts delete mode 100644 src/planner/phases/planner/phase.ts delete mode 100644 src/planner/phases/planner/prompts.ts delete mode 100644 src/planner/phases/review-protocol.ts delete mode 100644 src/planner/phases/reviewable-phase.ts delete mode 100644 src/planner/phases/scout/phase.ts delete mode 100644 src/planner/phases/scout/prompts.ts delete mode 100644 src/planner/phases/workflow-orchestrator/phase.ts delete mode 100644 src/planner/phases/workflow-orchestrator/prompts.ts delete mode 100644 src/planner/subagent.ts delete mode 100644 src/planner/tools/ask.ts delete mode 100644 src/planner/tools/index.ts delete mode 100644 src/planner/tools/orchestrator.ts delete mode 100644 src/planner/tools/review-artifact.ts delete mode 100644 src/planner/tools/types.ts delete mode 100644 src/planner/tools/workflow-decision.ts delete mode 100644 src/planner/tools/workflow.ts delete mode 100644 src/planner/types.ts delete mode 100644 src/planner/ui/config/menu.ts delete mode 100644 src/planner/ui/config/model-selection.ts delete mode 100644 src/planner/web/ARCHITECTURE.md delete mode 100644 src/planner/web/css/animations.css delete mode 100644 src/planner/web/css/components.css delete mode 100644 src/planner/web/css/layout.css delete mode 100644 src/planner/web/css/variables.css delete mode 100644 src/planner/web/html/index.html delete mode 100644 src/planner/web/js/app.jsx delete mode 100644 src/planner/web/js/components/ActivityFeed.jsx delete mode 100644 src/planner/web/js/components/AgentMonitor.jsx delete mode 100644 src/planner/web/js/components/AgentRow.jsx delete mode 100644 src/planner/web/js/components/App.jsx delete mode 100644 src/planner/web/js/components/ArtifactsFolder.jsx delete mode 100644 src/planner/web/js/components/Header.jsx delete mode 100644 src/planner/web/js/components/Markdown.jsx delete mode 100644 src/planner/web/js/components/ModelConfig.jsx delete mode 100644 src/planner/web/js/components/Notifications.jsx delete mode 100644 src/planner/web/js/components/PhaseContent.jsx delete mode 100644 src/planner/web/js/components/PillStrip.jsx delete mode 100644 src/planner/web/js/components/StatusSidebar.jsx delete mode 100644 src/planner/web/js/components/forms/ArtifactReview.jsx delete mode 100644 src/planner/web/js/components/forms/QuestionCard.jsx delete mode 100644 src/planner/web/js/components/forms/QuestionForm.jsx delete mode 100644 src/planner/web/js/components/phases/Completion.jsx delete mode 100644 src/planner/web/js/components/phases/Loading.jsx delete mode 100644 src/planner/web/js/lib/api.js delete mode 100644 src/planner/web/js/lib/utils.js delete mode 100644 src/planner/web/js/sse.js delete mode 100644 src/planner/web/js/store.js delete mode 100644 src/planner/web/server-types.ts delete mode 100644 src/planner/web/server.ts delete mode 100644 src/utils/logger.ts delete mode 100644 tests/audit-log-formatter.test.ts delete mode 100644 tests/conversation.test.ts delete mode 100644 tests/event-log.test.ts delete mode 100644 tests/phase-dag.test.ts delete mode 100644 tests/pool.test.ts delete mode 100644 tests/state-machine.test.ts delete mode 100644 tests/story-discovery.test.ts delete mode 100644 tests/subagent-args.test.ts delete mode 100644 tsconfig.build.json delete mode 100644 tsconfig.json diff --git a/.config/wt.toml b/.config/wt.toml index c705010..6ac8dde 100644 --- a/.config/wt.toml +++ b/.config/wt.toml @@ -2,11 +2,11 @@ # Docs: https://worktrunk.dev/hook/ [post-create] -deps = "npm ci" +deps = "uv sync --dev" [post-start] copy = "wt step copy-ignored" [pre-merge] -check = "npm run check" -test = "npm test" +check = "uv run ruff check ." +test = "uv run pytest" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e305aad..1c572e3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,23 +7,22 @@ on: workflow_dispatch: jobs: - build-and-test: + test: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - - name: Set up Node.js - uses: actions/setup-node@v4 + - name: Set up Python + uses: actions/setup-python@v5 with: - node-version: 20 - cache: npm + python-version: "3.12" - - name: Install dependencies - run: npm ci + - name: Install uv + uses: astral-sh/setup-uv@v4 - - name: Type check - run: npm run check + - name: Install dependencies + run: uv sync --dev - - name: Build and test - run: npm test + - name: Run tests + run: uv run pytest diff --git a/.gitignore b/.gitignore index b3bc902..373c44c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,13 +1,9 @@ -node_modules/ -dist/ -build/ .pi/ .DS_Store .claude/ plans/ .koan/ -*.tsbuildinfo .env .env.* *.log diff --git a/AGENTS.md b/AGENTS.md index d97348a..fc91d0d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,15 +3,16 @@ Full architecture documentation: **[docs/architecture.md](docs/architecture.md)** Spoke documents: -- [docs/subagents.md](docs/subagents.md) — spawn lifecycle, task manifest, step-first workflow, permissions -- [docs/ipc.md](docs/ipc.md) — file-based IPC protocol, scout spawning, question routing -- [docs/state.md](docs/state.md) — driver/LLM boundary, epic and story state, routing rules -- [docs/intake-loop.md](docs/intake-loop.md) — confidence-gated loop, non-linear step progression, prompt engineering -- [docs/epic-brief.md](docs/epic-brief.md) — brief artifact, brief-writer subagent, downstream references -- [docs/artifact-review.md](docs/artifact-review.md) — artifact review IPC protocol, review loop, reusability -- [docs/token-streaming.md](docs/token-streaming.md) — stdout JSONL parsing, pi `--mode json` integration, SSE delta path -**Pipeline phases:** `intake` → `brief-generation` → `core-flows` → `tech-plan` → `ticket-breakdown` → `cross-artifact-validation` → `execution` → `implementation-validation` → `completed` +- [docs/subagents.md](docs/subagents.md) -- spawn lifecycle, task manifest, step-first workflow, permissions +- [docs/ipc.md](docs/ipc.md) -- HTTP MCP tool calls, blocking interactions, scout spawning +- [docs/state.md](docs/state.md) -- driver/LLM boundary, epic and story state, routing rules +- [docs/intake-loop.md](docs/intake-loop.md) -- confidence-gated loop, non-linear step progression, prompt engineering +- [docs/epic-brief.md](docs/epic-brief.md) -- brief artifact, brief-writer subagent, downstream references +- [docs/artifact-review.md](docs/artifact-review.md) -- artifact review protocol, review loop, reusability +- [docs/token-streaming.md](docs/token-streaming.md) -- runner stdout parsing, SSE delta path + +**Pipeline phases:** `intake` -> `brief-generation` -> `core-flows` -> `tech-plan` -> `ticket-breakdown` -> `cross-artifact-validation` -> `execution` -> `implementation-validation` -> `completed` --- @@ -20,35 +21,39 @@ The six core invariants (see architecture.md for full detail + pitfalls): ## 1. File Boundary LLMs write **markdown files only**. The driver maintains **JSON state files** -internally — no LLM ever reads or writes a `.json` file. Tool code bridges +internally -- no LLM ever reads or writes a `.json` file. Tool code bridges both worlds. ## 2. Step-First Workflow Pattern (critical) -Every subagent is a `pi --mode json -p` process. The `--mode json` flag makes pi emit structured JSONL on stdout instead of human-readable text; `-p` keeps it non-interactive (exits after processing the boot prompt without waiting on stdin). Once the LLM produces text without a tool -call, the process exits — there is no stdin to recover. +Every subagent is a CLI process (`claude`, `codex`, or `gemini`) that connects +to the driver's HTTP MCP endpoint at `http://localhost:{port}/mcp?agent_id={id}`. +The subagent receives tools via MCP and calls them over HTTP. The driver handles +all tool logic in-process. **The first thing any subagent does is call `koan_complete_step`.** The spawn -prompt contains *only* this directive. The tool returns step 1 instructions. +prompt contains _only_ this directive. The tool returns step 1 instructions. This establishes the calling pattern before the LLM sees complex instructions. ``` Boot prompt: "You are a koan {role} agent. Call koan_complete_step to receive your instructions." - ↓ LLM calls koan_complete_step (step 0 → 1 transition) + | LLM calls koan_complete_step (step 0 -> 1 transition) Tool returns: Step 1 instructions (rich context, task details, guidance) - ↓ LLM does work... - ↓ LLM calls koan_complete_step + | LLM does work... + | LLM calls koan_complete_step Tool returns: Step 2 instructions (or "Phase complete.") ``` -Step progression is normally linear, but subclasses may override `getNextStep()` -to implement non-linear flows. The intake phase loops steps 2–4 until a -confidence gate is satisfied. See [docs/intake-loop.md](docs/intake-loop.md). +Step progression is normally linear, but phase modules may override +`get_next_step()` to implement non-linear flows. The intake phase loops steps +2-4 until a confidence gate is satisfied. See +[docs/intake-loop.md](docs/intake-loop.md). ## 3. Driver Determinism -The driver reads JSON state files and exit codes, applies routing rules, and -spawns the next subagent. It never makes judgment calls or parses free-text. +The driver (`koan/driver.py`) reads JSON state files and exit codes, applies +routing rules, and spawns the next subagent. It never makes judgment calls or +parses free-text. ## 4. Default-Deny Permissions @@ -67,13 +72,15 @@ established. ## 6. Directory-as-Contract The subagent directory is the sole interface between parent and child. -Three well-known JSON files: - -| File | Writer | Reader | Purpose | -|------|--------|--------|---------| -| `task.json` | Parent (before spawn) | Child (once, at startup) | What to do | -| `state.json` | Child (continuously) | Parent (polling) | What has been done | -| `ipc.json` | Both (request/response) | Both (polling) | What is needed right now | - -No structured configuration flows through CLI flags. The spawn command carries -only the directory path. +Two well-known JSON files plus the MCP endpoint URL: + +| File | Writer | Reader | Purpose | +| -------------- | ------------------------- | ------------------------------ | ------------------ | +| `task.json` | Parent (before spawn) | Parent (at agent registration) | What to do | +| `state.json` | Parent (audit projection) | Available for debugging | What has been done | +| `events.jsonl` | Parent (audit log) | Available for replay | Full event history | + +The `mcp_url` field in `task.json` tells the child where to connect for tool +calls. No structured configuration flows through CLI flags. The spawn command +carries the directory path and the MCP config pointing at the driver's HTTP +endpoint. diff --git a/README.md b/README.md index 7d0c31d..93d00c2 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,87 @@ # Koan -Koan is a deterministic planning pipeline for the pi coding agent. It takes a -conversation describing a coding task and produces working code — through a -structured sequence of isolated LLM subagents, each with a narrow, auditable -responsibility. +Koan is a deterministic planning pipeline that takes a conversation describing a +coding task and produces working code -- through a structured sequence of +isolated LLM subagents, each with a narrow, auditable responsibility. + +## Setup + +```bash +uv sync +uv run koan +``` ## How it works ``` Conversation - → Intake (confidence-gated investigation loop) - → Decomposer (splits scope into stories) - → Review gate (user approves story list) - → Story loop: - Orchestrator (selects + verifies) → Planner → Executor → repeat - → Done + -> Intake (confidence-gated investigation loop) + -> Brief generation (distill landscape into product brief) + -> Core flows (user journeys, sequence diagrams) + -> Tech plan (technical architecture) + -> Ticket breakdown (story-sized implementation tickets) + -> Cross-artifact validation (consistency check) + -> Execution (implement tickets) + -> Implementation validation (post-execution review) + -> Done ``` -Each stage is a separate `pi -p` subprocess. Subagents communicate through -files in a per-session directory, not through shared memory or sockets. The -parent driver reads JSON state and exit codes; it never parses LLM output. +A single Python process (`koan/driver.py`) runs a Starlette HTTP server that +hosts both the web dashboard and an MCP tool endpoint. Subagents are CLI +processes (`claude`, `codex`, or `gemini`) that connect to +`http://localhost:{port}/mcp?agent_id={id}` to receive step guidance and call +koan tools. The driver reads JSON state and exit codes; it never parses LLM +output. ## Phases -| Phase | Role | What it does | -|-------|------|-------------| -| **Intake** | `intake` | Reads the conversation, scouts the codebase, asks clarifying questions. Iterates until confident. Writes `context.md`. | -| **Scout** | `scout` | Narrow codebase investigator. Spawned in parallel by intake, decomposer, and planner via `koan_request_scouts`. | -| **Decomposer** | `decomposer` | Reads `context.md`, splits work into story sketches. Each story = one pull request. | -| **Orchestrator** | `orchestrator` | Selects the next story, verifies execution results, routes to retry/done/next. | -| **Planner** | `planner` | Reads a story sketch, writes a step-by-step implementation plan and code context file. | -| **Executor** | `executor` | Follows the plan, modifies the codebase, reports what changed. | +| Phase | Role | What it does | +| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ | +| **Intake** | `intake` | Reads the conversation, scouts the codebase, asks clarifying questions. Iterates until confident. Writes `landscape.md`. | +| **Scout** | `scout` | Narrow codebase investigator. Spawned in parallel by intake, decomposer, and planner via `koan_request_scouts`. | +| **Brief writer** | `brief-writer` | Distills `landscape.md` into `brief.md`. User reviews via artifact review. | +| **Orchestrator** | `orchestrator` | Selects the next story, verifies execution results, routes to retry/done/next. | +| **Planner** | `planner` | Reads a story sketch, writes a step-by-step implementation plan and code context file. | +| **Executor** | `executor` | Follows the plan, modifies the codebase, reports what changed. | ## Web Dashboard Koan serves a local web dashboard at `http://localhost:{port}` during pipeline execution. The dashboard provides: -- **Activity feed** — real-time tool calls, scout dispatches, thinking traces -- **Agent monitor** — status, token counts, and recent actions for each +- **Activity feed** -- real-time tool calls, scout dispatches, thinking traces +- **Agent monitor** -- status, token counts, and recent actions for each running subagent -- **User interaction** — question forms (intake clarifications), review gates +- **User interaction** -- question forms (intake clarifications), review gates (story approval), model configuration -The dashboard uses Server-Sent Events for real-time updates. State is polled -from each subagent's audit projection every 50ms. +The dashboard uses Server-Sent Events for real-time updates. SSE events are +pushed directly from in-process state transitions and tool handlers. ## Key Concepts **Step-first workflow.** Every subagent's first action is calling -`koan_complete_step`. This forces a tool call before any text output — critical -because `pi -p` processes exit the moment the LLM produces text without a tool -call. Task instructions are delivered as the return value of that first call. +`koan_complete_step`. This forces a tool call before any text output. Task +instructions are delivered as the return value of that first call. **Directory-as-contract.** Each subagent gets a directory with `task.json` (input), `state.json` (live projection), and `events.jsonl` (audit log). The -spawn command carries only the directory path. No structured data flows through -CLI flags. +spawn command carries the directory path and the MCP endpoint URL. **Default-deny permissions.** Every tool call passes through a permission fence. Roles cannot use tools outside their scope. Planning roles can only write inside the epic directory. The intake phase's Extract step additionally blocks scouting and writing tools at the mechanism level. -**Driver determinism.** The driver (`driver.ts`) reads JSON and exit codes, +**Driver determinism.** The driver (`koan/driver.py`) reads JSON and exit codes, applies routing rules, and spawns the next subagent. It never parses markdown or adapts to LLM behavior. Routing decisions are deterministic. +**HTTP MCP.** Subagents connect to the driver's MCP endpoint at +`/mcp?agent_id={id}`. Tool calls arrive as HTTP requests; the driver looks up +the agent's state by `agent_id` in an in-process registry and handles the call +directly. No separate MCP server processes, no file-based IPC polling. + ## Configuration Model tiers and scout concurrency are configured via the web UI at pipeline @@ -83,17 +98,24 @@ start, then saved to `~/.koan/config.json`: } ``` -Roles map to tiers: intake/decomposer/orchestrator/planner → strong, -executor → standard, scout → cheap. +Roles map to tiers: intake/decomposer/orchestrator/planner -> strong, +executor -> standard, scout -> cheap. ## Architecture Documentation -- **[docs/architecture.md](./docs/architecture.md)** — core invariants, +- **[docs/architecture.md](./docs/architecture.md)** -- core invariants, design principles, pitfalls -- **[docs/subagents.md](./docs/subagents.md)** — spawn lifecycle, step-first +- **[docs/subagents.md](./docs/subagents.md)** -- spawn lifecycle, step-first workflow, permissions, model tiers -- **[docs/ipc.md](./docs/ipc.md)** — file-based IPC between subagent and parent -- **[docs/state.md](./docs/state.md)** — driver state machine, story lifecycle, +- **[docs/ipc.md](./docs/ipc.md)** -- HTTP MCP inter-process communication, + blocking tool calls +- **[docs/state.md](./docs/state.md)** -- driver state machine, story lifecycle, routing rules -- **[docs/intake-loop.md](./docs/intake-loop.md)** — confidence-gated intake +- **[docs/intake-loop.md](./docs/intake-loop.md)** -- confidence-gated intake loop, prompt engineering principles +- **[docs/epic-brief.md](./docs/epic-brief.md)** -- brief artifact, brief-writer + subagent, downstream references +- **[docs/artifact-review.md](./docs/artifact-review.md)** -- artifact review + protocol, review loop, reusability +- **[docs/token-streaming.md](./docs/token-streaming.md)** -- runner stdout + parsing, SSE delta path diff --git a/docs/architecture.md b/docs/architecture.md index 68476e6..c06a429 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,17 +6,17 @@ principles, and pitfalls that govern the codebase. **Spoke documents** cover subsystems in depth: -- [Subagents](./subagents.md) — spawn lifecycle, boot protocol, step-first +- [Subagents](./subagents.md) -- spawn lifecycle, boot protocol, step-first workflow, phase dispatch, permissions, model tiers -- [IPC](./ipc.md) — file-based inter-process communication between parent and - subagent, scout spawning, question routing -- [Token Streaming](./token-streaming.md) — stdout JSONL parsing, pi `--mode json` integration, SSE delta path -- [State & Driver](./state.md) — the driver/LLM boundary, JSON vs markdown +- [IPC](./ipc.md) -- HTTP MCP inter-process communication, blocking tool calls, + scout spawning +- [Token Streaming](./token-streaming.md) -- runner stdout parsing, SSE delta path +- [State & Driver](./state.md) -- the driver/LLM boundary, JSON vs markdown ownership, epic and story state, routing rules -- [Intake Loop](./intake-loop.md) — confidence-gated investigation loop, +- [Intake Loop](./intake-loop.md) -- confidence-gated investigation loop, non-linear step progression, prompt engineering principles -- [Epic Brief](./epic-brief.md) — brief artifact, brief-writer subagent, downstream references -- [Artifact Review](./artifact-review.md) — artifact review IPC protocol, review loop, reusability +- [Epic Brief](./epic-brief.md) -- brief artifact, brief-writer subagent, downstream references +- [Artifact Review](./artifact-review.md) -- artifact review protocol, review loop, reusability --- @@ -28,7 +28,7 @@ ways that are difficult to diagnose. ### 1. File boundary LLMs write **markdown files only**. The driver maintains **JSON state files** -internally — no LLM ever reads or writes a `.json` file. +internally -- no LLM ever reads or writes a `.json` file. Tool code bridges both worlds: orchestrator tools write JSON state (for the driver) and templated `status.md` (for LLMs). The driver reads JSON and exit @@ -36,9 +36,9 @@ codes; it never parses markdown. ``` Orchestrator calls koan_complete_story(story_id) - → tool code writes state.json + status.md - → driver reads state.json to route next action - → LLM reads status.md if it needs to reference the decision + -> tool code writes state.json + status.md + -> driver reads state.json to route next action + -> LLM reads status.md if it needs to reference the decision ``` **Why:** If an LLM writes JSON, schema drift and parse errors become runtime @@ -46,8 +46,12 @@ failures in the deterministic driver. Markdown is forgiving; JSON is not. ### 2. Step-first workflow -Every subagent is a `pi --mode json -p` process. `--mode json` makes pi emit structured JSONL on stdout instead of human-readable text; `-p` keeps it non-interactive (exits after processing the boot prompt without waiting on stdin). Once the LLM produces text without a tool call, the process exits — there is no stdin to recover. The entire workflow -depends on the LLM calling `koan_complete_step` reliably. +Every subagent is a CLI process (`claude`, `codex`, or `gemini`) that connects +to the driver's HTTP MCP endpoint at `http://localhost:{port}/mcp?agent_id={id}`. +The subagent receives tools via MCP and calls them over HTTP. Once the LLM +produces text without a tool call, the process may exit -- there is no stdin to +recover. The entire workflow depends on the LLM calling `koan_complete_step` +reliably. **The first thing any subagent does is call `koan_complete_step`.** The spawn prompt contains _only_ this directive. The tool returns step 1 instructions. @@ -55,38 +59,39 @@ This establishes the calling pattern before the LLM sees complex instructions. ``` Boot prompt: "You are a koan {role} agent. Call koan_complete_step to receive your instructions." - ↓ LLM calls koan_complete_step (step 0 → 1 transition) + | LLM calls koan_complete_step (step 0 -> 1 transition) Tool returns: Step 1 instructions (rich context, task details, guidance) - ↓ LLM does work... - ↓ LLM calls koan_complete_step + | LLM does work... + | LLM calls koan_complete_step Tool returns: Step 2 instructions (or "Phase complete.") ``` Three reinforcement mechanisms make this robust across model capability levels: -| Mechanism | Where | Why | -| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------------------ | -| **Primacy** | Boot prompt is the LLM's very first message | First action = tool call, at the top of conversation history | -| **Recency** | `formatStep()` appends "WHEN DONE: Call koan_complete_step..." last | LLMs weight end-of-context instructions heavily | -| **Muscle memory** | By step 2+ the LLM has called the tool N times | Pattern is locked in through repetition | +| Mechanism | Where | Why | +| ----------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ | +| **Primacy** | Boot prompt is the LLM's very first message | First action = tool call, at the top of conversation history | +| **Recency** | `format_step()` appends "WHEN DONE: Call koan_complete_step..." last | LLMs weight end-of-context instructions heavily | +| **Muscle memory** | By step 2+ the LLM has called the tool N times | Pattern is locked in through repetition | ### 3. Driver determinism -The driver (`driver.ts`) is a deterministic state machine. It reads JSON state -files and exit codes, applies routing rules, and spawns the next subagent. It -never makes judgment calls, parses free-text output, or adapts to LLM behavior. +The driver (`koan/driver.py`) is a deterministic state machine. It reads JSON +state files and exit codes, applies routing rules, and spawns the next subagent. +It never makes judgment calls, parses free-text output, or adapts to LLM +behavior. **Routing priority** in the story loop: -1. `retry` status → re-execute (retry takes precedence over new work) -2. `selected` status → plan + execute -3. All stories `done` or `skipped` → epic complete -4. None of the above → error ("orchestrator may have exited without a routing decision") +1. `retry` status -> re-execute (retry takes precedence over new work) +2. `selected` status -> plan + execute +3. All stories `done` or `skipped` -> epic complete +4. None of the above -> error ("orchestrator may have exited without a routing decision") ### 4. Default-deny permissions -Every tool call in a subagent passes through a permission fence (`tool_call` -event handler in `BasePhase`). Unknown roles are blocked. Unknown tools are +Every tool call passes through a permission fence (`check_permission()` in +`koan/lib/permissions.py`). Unknown roles are blocked. Unknown tools are blocked. Planning roles can only write inside the epic directory. The one accepted limitation: `READ_TOOLS` (bash, read, grep, glob, find, ls) @@ -102,196 +107,150 @@ Each subagent receives only the minimum context for its task: - The **system prompt** establishes role identity and rules, but no task details - **Task details** arrive via step 1 guidance (returned by the first tool call) -This is not just tidiness — it is load-bearing. A previous design injected -step 1 guidance into the first user message (via a `context` event handler), -but that front-loaded complex instructions before the LLM had established the -`koan_complete_step` calling pattern. Weaker models (haiku) produced text -output and exited without entering the workflow. The `context` event handler -was deliberately removed; step guidance is now delivered exclusively through -`koan_complete_step` return values. +This is not just tidiness -- it is load-bearing. A previous design injected +step 1 guidance into the first user message, but that front-loaded complex +instructions before the LLM had established the `koan_complete_step` calling +pattern. Weaker models produced text output and exited without entering the +workflow. Step guidance is now delivered exclusively through `koan_complete_step` +return values. ### 6. Directory-as-contract The subagent directory is the **sole interface** between parent and child. -Everything a subagent needs — its task, its communication channel, its -observable state — lives in well-known files inside that directory. +Everything a subagent needs -- its task, its observable state -- lives in +well-known files inside that directory. -Three JSON files, three lifecycles: +Two JSON files and an MCP URL: -| File | Writer | Reader | Lifecycle | -| ---------------- | ----------------------- | ------------------------ | ------------------------------------------------------- | -| **`task.json`** | Parent (before spawn) | Child (once, at startup) | Write-once, never modified | -| **`state.json`** | Child (continuously) | Parent (polling) | Eagerly materialized audit projection | -| **`ipc.json`** | Both (request/response) | Both (polling) | Temporary — created per request, deleted after response | +| File | Writer | Reader | Lifecycle | +| ------------------ | ------------------------- | ------------------------ | ------------------------------------------- | +| **`task.json`** | Parent (before spawn) | Parent (at registration) | Write-once, never modified | +| **`state.json`** | Parent (audit projection) | Available for debugging | Eagerly materialized after each audit event | +| **`events.jsonl`** | Parent (audit log) | Available for replay | Append-only event log | -The spawn command carries only the directory path. The child reads `task.json` -to discover its role, epic context, and task-specific parameters. No -structured configuration flows through CLI flags, environment variables, or -other process-level channels. +The `task.json` includes an `mcp_url` field pointing at +`http://localhost:{port}/mcp?agent_id={id}`. The child reads this to discover +its MCP endpoint. No structured configuration flows through CLI flags, +environment variables, or other process-level channels. -``` -# Spawn interface: one koan flag, the rest is pi-level -pi --mode json -p -e {extensionPath} --koan-dir {subagentDir} [--model {model}] "{bootPrompt}" -``` +**Why:** CLI flags are a flat namespace -- they cause naming collisions, cannot +represent nested structure, are visible in process listings, and are subject to +`ARG_MAX` limits for large values like retry context. Files are structured, +inspectable (`cat task.json`), typed, and consistent with how we handle +observation (audit). -**Why:** CLI flags are a flat namespace — they cause naming collisions (e.g., -`--koan-role` for pipeline role vs `--koan-scout-role` for investigator -persona), cannot represent nested structure, are visible in process listings, -and are subject to `ARG_MAX` limits for large values like retry context. -Files are structured, inspectable (`cat task.json`), typed, and consistent -with how we already handle runtime communication (IPC) and observation (audit). - -See [subagents.md § Task Manifest](./subagents.md#task-manifest) for the +See [subagents.md -- Task Manifest](./subagents.md#task-manifest) for the `task.json` schema and spawn flow. --- ## Atomic Writes -All persistent writes (JSON state, IPC files, status.md, audit state.json) -use the same pattern: write to a `.tmp` file, then `fs.rename()` to the target. -This prevents partial reads during concurrent access. +All persistent writes (JSON state, status.md, audit state.json) use the same +pattern: write to a `.tmp` file, then `os.rename()` to the target. This +prevents partial reads during concurrent access. -```typescript -const tmp = path.join(dir, "file.tmp"); -await fs.writeFile(tmp, content, "utf8"); -await fs.rename(tmp, target); -``` - -This is not optional — the IPC responder, web server, and audit system all -poll files concurrently. A partial read of `ipc.json` or `state.json` would -cause silent data corruption or spurious errors. +The `koan/audit/event_log.py` module uses this pattern for all state writes. +This is not optional -- the web server and audit system access files +concurrently. A partial read of `state.json` would cause silent data +corruption or spurious errors. --- -## Tool Registration Constraint - -All tools **must** be registered unconditionally at extension init, before -pi's `_buildRuntime()` snapshot. Tools registered after `_buildRuntime()` are -invisible to the LLM. +## Tool Registration -CLI flags are unavailable during init (`getFlag()` returns undefined before -`_buildRuntime()` sets flagValues), so conditional registration based on role -is impossible. Instead: +Tools are registered as `fastmcp` tool handlers in `koan/web/mcp_endpoint.py`. +When a tool call arrives via HTTP, the MCP endpoint: -1. All tools register at init, reading from the mutable `RuntimeContext` at call time -2. `BasePhase.registerHandlers()` adds a `tool_call` event listener that checks permissions per-role at runtime -3. The `RuntimeContext` is populated later, during `before_agent_start` +1. Extracts `agent_id` from the URL query parameter +2. Looks up the agent's state (role, step counter, permissions) in the in-process registry +3. Calls `check_permission()` from `koan/lib/permissions.py` +4. If allowed, dispatches to the tool handler +5. Returns the result as the MCP tool response -This is the **mutable-ref pattern**: static registration, dynamic dispatch. +This replaces the previous TypeScript pattern of registering tools at extension +init and checking permissions via event hooks. The Python model is simpler: +tools are HTTP handlers, permissions are checked per-call. --- ## Event-Sourced Audit -Each subagent maintains an append-only event log (`events.jsonl`) and an -eagerly-materialized projection (`state.json`). This is the observability -layer that drives the web dashboard. +Each subagent's audit state is maintained in-process by the driver. The event +log (`events.jsonl`) is append-only, and the projection (`state.json`) is +eagerly materialized after each event. ``` -audit event appended → fold(events) → state.json written atomically -web server polls state.json (50ms) → detects change → pushes SSE event -sse.js handler → Zustand store update → component re-render +tool call arrives via MCP -> driver handles it -> emits audit event + -> fold(events) -> state.json written atomically + -> SSE event pushed directly to connected browsers ``` ### Rules -- **`fold()` is pure** — given the same event sequence, it must produce the same +- **`fold()` is pure** -- given the same event sequence, it must produce the same projection. No I/O, no randomness, no side effects inside `fold()`. - **New event types require a fold handler.** Unknown events are silently ignored (forward compatibility), but a new event that is not folded contributes nothing - to the projection and will not be visible to the web server or UI. + to the projection and will not be visible in the UI. - **Projection is eagerly materialized.** It is written atomically after every - `append()` call. The web server reads `state.json`, not `events.jsonl`. This - keeps polling cheap (one file read) without needing to replay the log. -- **`append()` calls are serialized.** `EventLog` serializes appends via an - internal promise chain. Concurrent callers (e.g., heartbeat timer and - `tool_result` handler) enqueue without racing on the `.tmp.json` file. + event. The web server reads the projection from in-process state; `state.json` + on disk is for debugging and post-mortem. +- **SSE is pushed directly.** There is no polling loop. When a tool handler + emits an audit event, the SSE push happens in the same call chain. ### Adding new observable state -When adding a new piece of state that the UI should see, wire all five layers: +When adding a new piece of state that the UI should see, wire three layers: -1. **Emit an audit event** — add a typed event and an `emit*()` helper in `lib/audit.ts` -2. **Update `fold()`** — handle the new event type to update the projection field -3. **Update the Projection type** — add the field to the `Projection` interface -4. **Web server polling** — read the new field from the cached projection in the 50ms polling callback and include it in the SSE payload -5. **Frontend** — add a handler in `sse.js` and a slice in `store.js` +1. **Emit an audit event** -- add a typed event in `koan/audit/events.py` +2. **Update `fold()`** -- handle the new event type in `koan/audit/fold.py` +3. **Push SSE** -- emit the SSE event from the tool handler or state transition + in `koan/web/app.py` -All five layers must be present. Missing any one of them produces silent data -loss — the event is appended but never reaches the browser. +The HTMX frontend receives SSE events and swaps server-rendered HTML fragments. -**Exception — ephemeral display data:** High-frequency data with no persistence +**Exception -- ephemeral display data:** High-frequency data with no persistence value (e.g., token deltas) should bypass the audit pipeline and push directly -to SSE. Routing hundreds of events per second through `events.jsonl` + `fold()` -+ `state.json` adds I/O overhead with no benefit. See -[token-streaming.md](./token-streaming.md) for the alternate path. +to SSE. See [token-streaming.md](./token-streaming.md) for the alternate path. --- ## SSE Event Lifecycle -State flows from LLM tool calls to the browser through a five-layer pipeline. -All layers must be wired for a new event type to be visible end-to-end. +State flows from LLM tool calls to the browser through a direct push pipeline. ``` -[LLM calls tool] - | -[tool mutates ctx + calls ctx.eventLog.emit*()] <- lib/audit.ts +[LLM calls tool via HTTP MCP] | -[fold() updates Projection -> state.json written atomically] +[MCP endpoint handles call, emits audit event] | -[web server polls state.json every 50ms, detects change] <- web/server.ts +[fold() updates projection, state.json written atomically] | -[pushEvent(type, payload) -> SSE stream -> browser] +[SSE event pushed to connected browsers] <- koan/web/app.py | -[sse.js dispatches to named handler from store.js] <- web/js/sse.js - | -[named handler calls useStore.setState()] <- web/js/store.js - | -[Zustand component selector -> React re-render] +[HTMX receives SSE, swaps server-rendered fragment] ``` ### Concrete example: `koan_set_confidence` ``` -LLM calls koan_set_confidence({ level: "high" }) - → ctx.intakeConfidence = "high" - → ctx.eventLog.emitConfidenceChange("high", 2) - → append({ kind: "confidence_change", level: "high", iteration: 2 }) - → fold: projection.intakeConfidence = "high", projection.intakeIteration = 2 - → writeState(projection) → state.json - → returns "Confidence set to high." - -web server polling timer fires (50ms) - → pollAgent(intake) → readProjection(dir) → intakeConfidence: "high" - → agent.lastProjection = projection - → intake sub-phase → builds IntakeProgressEvent { confidence: "high", iteration: 2, ... } - → pushEvent("intake-progress", event) → SSE stream - -browser receives "intake-progress" event - → sse.js handler → useStore.setState({ intakeProgress: event }) - → confidence visualization component re-renders +LLM calls koan_set_confidence({ level: "high" }) via MCP + -> MCP endpoint checks permissions + -> emits confidence_change audit event + -> fold: projection.intake_confidence = "high", projection.intake_iteration = 2 + -> write_state(projection) -> state.json + -> push SSE "intake-progress" event to connected browsers + -> HTMX swaps confidence visualization fragment + -> returns "Confidence set to high." as MCP tool result ``` -### `sse.js` / `store.js` boundary - -`sse.js` connects to the SSE stream and routes each event type to a named -handler. It does not import `useStore` or know the store's internal shape. - -`store.js` owns the Zustand store shape and exports named handler functions -(one per SSE event type). Each handler maps a raw SSE payload to a store -state update. - -Changing the store shape only requires updating `store.js`; `sse.js` is -stable across store shape changes. - ### Replay on reconnect The web server buffers the last value of every stateful SSE event type. On -reconnect, `replayState()` writes all buffered events to the new client. This -ensures the browser always has current state after a network drop, without -requiring a full page reload. +reconnect, all buffered events are written to the new client. This ensures +the browser always has current state after a network drop, without requiring +a full page reload. --- @@ -306,32 +265,25 @@ koan_complete_step". Putting task content (file paths, instructions, context) risks the LLM producing text output on the first turn and exiting. This has happened with haiku-class models and is not recoverable. -### Don't inject step guidance via the `context` event - -A `context` event handler that injects step 1 guidance into the first user -message was tried and removed. It creates the same problem as putting content -in the spawn prompt — the LLM sees complex instructions before establishing -the tool-calling pattern. - ### Don't add `escalated` as a story status -Escalation is handled via `koan_ask_question` (IPC → web server → user -answers → IPC response). A separate `escalated` status was tried and created -a dead routing path — the driver had nowhere clean to send it without -duplicating the ask UI flow that IPC already handles. +Escalation is handled via `koan_ask_question` (MCP tool call -> web UI -> user +answers -> MCP response). A separate `escalated` status was tried and created +a dead routing path -- the driver had nowhere clean to send it without +duplicating the ask UI flow. ### Don't add `scouting` as an epic phase -Scouts run inside the IPC responder during intake/decomposer/planner phases, -not as a top-level driver phase. Adding `scouting` to `EpicPhase` would imply -a driver state that never exists, creating dead code paths. +Scouts run inside the `koan_request_scouts` tool handler during +intake/decomposer/planner phases, not as a top-level driver phase. Adding +`scouting` to `EpicPhase` would imply a driver state that never exists, +creating dead code paths. ### Don't rely on file existence for scout success -Scout success is derived from the JSON projection (`readProjection()` → -`status === "completed"`), not from checking whether `findings.md` exists. -A scout can write a partial findings file and then crash — file existence is -not proof of completion. +Scout success is derived from the JSON projection (`status === "completed"`), +not from checking whether `findings.md` exists. A scout can write a partial +findings file and then crash -- file existence is not proof of completion. ### Don't crash on recoverable model-output parse errors @@ -343,36 +295,17 @@ Fail-fast is scoped to **unrecoverable conditions**: If a model emits malformed tool-call payloads (invalid JSON/args) or other per-turn formatting errors, treat them as recoverable execution errors: -return a structured tool error (`tool_result` with `isError=true`) so the model -can self-correct and retry in the same subagent process. - -Contrastive examples: - -| Condition | Classification | Expected handling | -| --------- | -------------- | ----------------- | -| Malformed tool-call JSON/args from LLM | Recoverable | Return `tool_result` error (`isError=true`), keep process alive | -| Tool argument schema validation failure | Recoverable | Return validation error as `tool_result`, let model retry | -| Disallowed/unknown tool call | Recoverable | Return blocked tool error, continue turn | -| Missing/malformed `task.json` at subagent startup | Unrecoverable | Fail fast (bootstrap contract broken) | -| Impossible phase routing / internal invariant breach | Unrecoverable | Fail fast | -| Unexpected runtime state with no clear deterministic recovery | Unrecoverable | Fail fast | - -Crashing the process for recoverable model-output errors converts a local retry -loop into a pipeline-level failure and should be avoided. - -### Don't write state.json from outside state.ts / tool code - -The state module (`epic/state.ts`) and orchestrator tools are the only -writers of JSON state. `status.md` writes belong exclusively in -`tools/orchestrator.ts`. Mixing these responsibilities violates the file -boundary invariant. - -### Don't call koan_complete_step in the tool description eagerly - -The tool description says "DO NOT call this tool until the step instructions -explicitly tell you to." Without this guard, aggressive models call -`koan_complete_step` immediately after receiving step guidance, skipping -the actual work. +return a structured tool error so the model can self-correct and retry in +the same subagent process. + +| Condition | Classification | Expected handling | +| ------------------------------------------------------------- | -------------- | ---------------------------------------- | +| Malformed tool-call JSON/args from LLM | Recoverable | Return tool error, keep process alive | +| Tool argument schema validation failure | Recoverable | Return validation error, let model retry | +| Disallowed/unknown tool call | Recoverable | Return blocked tool error, continue turn | +| Missing/malformed `task.json` at subagent startup | Unrecoverable | Fail fast (bootstrap contract broken) | +| Impossible phase routing / internal invariant breach | Unrecoverable | Fail fast | +| Unexpected runtime state with no clear deterministic recovery | Unrecoverable | Fail fast | ### Don't assume bash is restricted per role @@ -385,48 +318,35 @@ constraint. Do not assume bash calls are blocked for planning roles. **The pattern: prompt expresses intent; mechanical gate catches non-compliance. Neither alone is sufficient.** -- **Prompt alone** — the LLM can ignore it. The original 3-step intake design - told the LLM not to scout in step 1; it frontloaded all work into step 1 - anyway, producing duplicate scout requests in later steps. -- **Gate alone** — the LLM receives a cryptic "blocked" error with no context. - It cannot fix the problem if it does not know what it did wrong. +- **Prompt alone** -- the LLM can ignore it. +- **Gate alone** -- the LLM receives a cryptic "blocked" error with no context. -Three enforcement mechanisms are available — use the appropriate one for the +Three enforcement mechanisms are available -- use the appropriate one for the constraint: -| Mechanism | What it enforces | How | -| ---------------------------------------- | ------------------------------------------ | ------------------------------------------------------------- | -| **Permission fence** (`checkPermission`) | Which tools a role (or step) can use | Block at `tool_call` event; LLM sees a rejection message | -| **`validateStepCompletion()`** | Required pre-calls before step advancement | Block `koan_complete_step`; LLM sees an error and must comply | -| **Tool description** | Soft guidance on when to call | Cannot be enforced; LLM can ignore it | +| Mechanism | What it enforces | How | +| ----------------------------------------- | ------------------------------------------ | ------------------------------------------------------------- | +| **Permission fence** (`check_permission`) | Which tools a role (or step) can use | Block at MCP endpoint; LLM sees a rejection message | +| **`validate_step_completion()`** | Required pre-calls before step advancement | Block `koan_complete_step`; LLM sees an error and must comply | +| **Tool description** | Soft guidance on when to call | Cannot be enforced; LLM can ignore it | Any behavioral constraint that matters for correctness needs **both** a prompt instruction (so the LLM knows what to do) and a mechanical gate (so non-compliance is caught and corrected, not silently propagated). -See [intake-loop.md § Step-Aware Permission Gating](./intake-loop.md#step-aware-permission-gating). +See [intake-loop.md -- Step-Aware Permission Gating](./intake-loop.md#step-aware-permission-gating). ### Don't give a step multiple cognitive goals Each step should have exactly one cognitive goal. Grouping multiple goals into a single step ("do A, then B, then C") enables **simulated refinement**: the LLM artificially downgrades its output for A to manufacture visible improvement -in C. When all three goals are in one step, the model can pre-plan the -"improvement" because it already knows C is coming. - -Separate `koan_complete_step` calls enforce genuinely isolated reasoning: the -LLM must complete each goal before it sees the next goal's instructions. There -is no opportunity to sandbag — the next step's prompt has not arrived yet. - -This is why the intake phase has three loop steps (Scout / Deliberate / Reflect) -rather than a single monolithic "investigate" step. The scout phase follows the -same principle (orient → investigate → verify → report — four distinct goals, -four distinct steps). +in C. Separate `koan_complete_step` calls enforce genuinely isolated reasoning. When designing a new phase, each step should answer: "What is the single thing this step accomplishes?" If the answer requires "and then", split the step. -See [intake-loop.md § Prompt Chaining over Stepwise](./intake-loop.md#prompt-engineering-principles) +See [intake-loop.md -- Prompt Chaining over Stepwise](./intake-loop.md#prompt-engineering-principles) for the detailed rationale. ### Don't parse free-text for loop control decisions @@ -437,42 +357,30 @@ value set via a dedicated tool call, not a sentiment extracted from the LLM's for routing decisions. Any loop gate must flow through a typed tool parameter and a structured context field. -### Don't put side effects in getNextStep() +### Don't put side effects in get_next_step() -`getNextStep()` must be a pure query — it returns the next step number and +`get_next_step()` must be a pure query -- it returns the next step number and nothing else. Putting state mutations, counter increments, or event emission -inside `getNextStep()` violates this contract and makes the method unsafe to -reason about (e.g., a test that calls `getNextStep()` to inspect the decision -should not trigger side effects). +inside `get_next_step()` violates this contract. -Side effects that accompany a loop-back belong in `onLoopBack()`, which -`BasePhase` calls after detecting a backward transition: +Side effects that accompany a loop-back belong in `on_loop_back()`: ``` -BAD: getNextStep(4) { this.iteration++; this.ctx.confidence = null; return 2; } -GOOD: getNextStep(4) { return 2; } - onLoopBack(4, 2) { this.iteration++; this.ctx.confidence = null; } +BAD: get_next_step(4) { self.iteration += 1; self.confidence = None; return 2 } +GOOD: get_next_step(4) { return 2 } + on_loop_back(4, 2) { self.iteration += 1; self.confidence = None } ``` -The `onLoopBack()` hook is async and properly awaited, ensuring event -emission (`emitIterationStart`) is correctly sequenced in `events.jsonl`. - ### Don't pass structured data through CLI flags If information is needed by a subagent, write it to `task.json` in the -subagent directory before spawning. CLI flags are for bootstrap only (locating -the directory). Structured data in flags creates flat-namespace collisions, -size limits, and an uninspectable interface. The directory-as-contract -invariant exists specifically to prevent this. +subagent directory before spawning. CLI flags are for bootstrap only. The +directory-as-contract invariant exists specifically to prevent this. ### Don't put high-frequency ephemeral data through the audit pipeline Token deltas and similar high-frequency signals arrive at hundreds of events -per second. Routing them through the audit pipeline (`events.jsonl` → `fold()` -→ `state.json`) would mean hundreds of append + fold + atomic-write cycles per -second for data that has no persistence value — it is display-only and cleared -when the subagent finishes. - -The stdout JSONL parsing path exists for exactly this case: parse `text_delta` -events directly from the subagent's stdout and push them to SSE clients without -touching the audit system. See [token-streaming.md](./token-streaming.md). +per second. Routing them through the audit pipeline would mean hundreds of +append + fold + atomic-write cycles per second for data that has no persistence +value. The runner stdout parsing path exists for exactly this case. See +[token-streaming.md](./token-streaming.md). diff --git a/docs/artifact-review.md b/docs/artifact-review.md index 0153817..0a3da10 100644 --- a/docs/artifact-review.md +++ b/docs/artifact-review.md @@ -1,12 +1,12 @@ # Artifact Review -IPC-based protocol for presenting a written artifact to the user and collecting -feedback. Used by the brief-writer phase; reusable for any future markdown -artifact that requires a review-revise loop before pipeline advancement. +Protocol for presenting a written artifact to the user and collecting feedback. +Used by the brief-writer phase; reusable for any future markdown artifact that +requires a review-revise loop before pipeline advancement. > Parent doc: [architecture.md](./architecture.md) > -> General IPC patterns: [ipc.md](./ipc.md) +> IPC model: [ipc.md](./ipc.md) --- @@ -16,36 +16,24 @@ The artifact review protocol pauses subagent execution while the user reads a rendered markdown artifact and either accepts it or provides revision feedback. The review loop is LLM-driven: the subagent writes the artifact, calls `koan_review_artifact`, revises on feedback, and calls the tool again. The -protocol is stateless — each invocation is a fresh IPC request. +protocol is stateless -- each invocation is a fresh request. --- -## Message Type - -Third discriminated union member of `IpcFile`, alongside `ask` and -`scout-request`: - -```typescript -interface ArtifactReviewPayload { - artifactPath: string; // file path of the artifact (for display label) - content: string; // raw markdown content (read from file by the tool) - description?: string; // optional context for the reviewer -} - -interface ArtifactReviewResponse { - id: string; - respondedAt: string; - feedback: string; // "Accept" or free-form text -} - -interface ArtifactReviewIpcFile { - type: "artifact-review"; - id: string; // UUID, for response correlation - createdAt: string; - payload: ArtifactReviewPayload; - response: ArtifactReviewResponse | null; // null = pending -} -``` +## Interaction Model + +When `koan_review_artifact` is called via MCP, the tool handler: + +1. Reads the file at `path` to obtain raw markdown content +2. Creates a `PendingInteraction` with type `"artifact-review"` and an `asyncio.Future` +3. Stores it in `AgentState.pending_tool` +4. Pushes SSE `"artifact-review"` event to connected browsers +5. Awaits the Future -- the MCP HTTP connection stays open +6. When the user responds (Accept or feedback), the web endpoint resolves the Future +7. Returns feedback string to the LLM as the MCP tool result + +There is no file-based IPC. The entire interaction is in-process via +`asyncio.Future`. --- @@ -54,17 +42,9 @@ interface ArtifactReviewIpcFile { **Name:** `koan_review_artifact` **Parameters:** -- `path` (string) — file path of the artifact to review -- `description` (string, optional) — context for the reviewer - -**Execution flow:** -1. Reads the file at `path` to obtain raw markdown content -2. Creates `ArtifactReviewIpcFile` with content embedded -3. Writes `ipc.json` (atomic tmp-rename) -4. Polls at 500ms intervals until response appears or signal aborts -5. Deletes `ipc.json` in the `finally` block (cleanup even on abort) -6. Returns feedback string to the LLM +- `path` (string) -- file path of the artifact to review +- `description` (string, optional) -- context for the reviewer **Return values:** @@ -79,8 +59,9 @@ The goals section needs a latency metric. Constraint #3 is too broad. ``` **LLM behavior on response:** -- `"Accept"` → call `koan_complete_step` -- Any other text → revise the artifact, call `koan_review_artifact` again + +- `"Accept"` -> call `koan_complete_step` +- Any other text -> revise the artifact, call `koan_review_artifact` again --- @@ -88,101 +69,88 @@ The goals section needs a latency metric. Constraint #3 is too broad. When the user clicks "Accept" in the web UI, the feedback string sent to the subagent is literally `"Accept"`. When the user provides feedback, it is their -typed text. Both cases travel the same code path in the tool and the IPC -responder. - -The tool interface is uniform: the LLM reads the feedback string and applies -judgment. There are no special fields, no boolean flags, no branching protocol. +typed text. Both cases travel the same code path. **Why:** A dedicated `accepted: boolean` field would create two response shapes -and require the protocol and tool handler to branch. Uniform text keeps the -tool stateless and lets the LLM decide how to proceed rather than executing a -mechanical branch. +and require branching. Uniform text keeps the tool stateless and lets the LLM +decide how to proceed. --- ## Web UI Component -`ArtifactReview.jsx` is mounted when `pendingInput.type === "artifact-review"`. +The artifact review is rendered as a server-side HTML fragment via +`koan/web/templates/fragments/interaction_artifact_review.html`. The template +receives the raw markdown content and renders it server-side. **Layout:** + ``` -┌─────────────────────────────────────────┐ -│ Review: │ -│ ───────────────────────── │ -│ ┌─────────────────────────────────┐ │ -│ │ [rendered markdown content] │ │ -│ └─────────────────────────────────┘ │ -│ ┌─────────────────────────────────┐ │ -│ │ Feedback (optional) │ │ -│ └─────────────────────────────────┘ │ -│ [Send Feedback] [Accept ✓] │ -└─────────────────────────────────────────┘ ++------------------------------------------+ +| Review: | +| --------------------- | +| +----------------------------------+ | +| | [rendered markdown content] | | +| +----------------------------------+ | +| +----------------------------------+ | +| | Feedback (optional) | | +| +----------------------------------+ | +| [Send Feedback] [Accept] | ++------------------------------------------+ ``` **Behavior:** -- Receives raw markdown from `pendingInput.payload.content` -- Renders client-side via `marked.parse(content)` → `dangerouslySetInnerHTML` -- "Accept" → `POST /api/artifact-review` with `{ token, requestId, feedback: "Accept" }` -- "Send Feedback" → `POST /api/artifact-review` with `{ token, requestId, feedback: textareaValue }` (button disabled when textarea is empty) -- Unmounts when the server clears `pendingInput` after writing the response -- Remounts with updated content when the LLM revises and re-invokes the tool -**Markdown safety:** `marked` does not sanitize by default. Content is -LLM-generated from a local file — not user-provided — so this is acceptable -here. If the pattern is reused for user-provided content, add DOMPurify. +- Server renders markdown content in the HTML fragment +- "Accept" -> `POST /api/artifact-review` with `{ feedback: "Accept" }` +- "Send Feedback" -> `POST /api/artifact-review` with `{ feedback: text }` +- HTMX swaps the fragment on SSE events (new review, review cleared) --- ## HTTP Endpoint -**`POST /api/artifact-review`** +**`POST /api/artifact-review`** in `koan/web/interactions.py` -Validates `token` (403 if mismatch), `requestId`, and `feedback` (must be a -non-null string). Resolves the pending `Promise` in `pendingInputs`. Returns -`{ ok: true }` on success, `{ ok: false, error: "..." }` on validation failure -or missing `requestId`. +Validates request parameters and resolves the pending `asyncio.Future` in the +agent's `PendingInteraction`. Returns `{ ok: true }` on success, error on +validation failure or missing pending interaction. --- ## SSE Events -| Event | Direction | Payload | -|-------|-----------|---------| -| `artifact-review` | server → browser | `{ requestId, artifactPath, content, description }` | -| `artifact-review-cancelled` | server → browser | `{ requestId }` | +| Event | Direction | Payload | +| --------------------------- | ----------------- | ----------------------------------------------------- | +| `artifact-review` | server -> browser | `{ request_id, artifact_path, content, description }` | +| `artifact-review-cancelled` | server -> browser | `{ request_id }` | -**SSE replay:** `replayState()` replays the `artifact-review` event if a -review is pending when a browser reconnects. Without this, a reconnect during -an active review loses the pending form and stalls the pipeline indefinitely. +SSE events are pushed directly from the tool handler. On browser reconnect, +pending reviews are replayed so the user does not lose the review form. --- ## Review Loop ``` -brief-writer LLM calls koan_review_artifact({ path: "…/brief.md" }) - → tool reads brief.md content - → tool writes ArtifactReviewIpcFile { type: "artifact-review", response: null } - → tool enters 500ms poll loop (LLM turn blocked) - -ipc-responder detects { type: "artifact-review", response: null } - → calls webServer.requestArtifactReview(payload, signal) - → creates Promise in pendingInputs map - → pushes SSE "artifact-review" event → browser mounts ArtifactReview - → user reads rendered markdown, submits feedback or clicks Accept - → POST /api/artifact-review → resolves Promise - → writes ArtifactReviewResponse { feedback } to ipc.json (atomic) - -tool poll detects response !== null - → breaks loop, deletes ipc.json - → returns "User feedback:\n{feedback}" to LLM - -if feedback === "Accept": - LLM calls koan_complete_step → phase advances +subagent calls koan_review_artifact({ path: ".../brief.md" }) via MCP + -> MCP endpoint reads brief.md content + -> creates PendingInteraction { type: "artifact-review", future: Future() } + -> pushes SSE "artifact-review" event to browsers + -> awaits Future + +user sees rendered markdown in web UI + -> clicks "Accept" or types feedback + -> POST /api/artifact-review -> resolves Future + +MCP handler returns feedback as tool result + -> subagent receives "User feedback:\n{feedback}" + +if feedback == "Accept": + LLM calls koan_complete_step -> phase advances else: LLM revises artifact, calls koan_review_artifact again - (loop repeats with fresh IPC request) + (loop repeats with fresh PendingInteraction) ``` --- @@ -198,6 +166,5 @@ that produces a markdown artifact can use the same pattern: Future phases that could use this pattern: core flows document, technical plan, architecture decision record. Adding a new phase requires only: assigning the -`koan_review_artifact` permission to the new role (in `permissions.ts`) and -implementing the review loop in the phase's step 2 guidance. The web UI -component, HTTP endpoint, and SSE plumbing are shared. +`koan_review_artifact` permission to the new role (in `koan/lib/permissions.py`) +and implementing the review loop in the phase's step guidance. diff --git a/docs/design-system.md b/docs/design-system.md index e628aa1..903c278 100644 --- a/docs/design-system.md +++ b/docs/design-system.md @@ -59,12 +59,12 @@ component references tokens — never raw color codes or pixel values. #### Backgrounds -| Token | Value | Usage | -| --------------- | --------- | --------------------------------------------------- | -| `--bg` | `#FEFAE0` | Cornsilk base — the "desk" | -| `--bg-surface` | `#E0D8C8` | Stone — sidebars, panels, monitor | -| `--bg-elevated` | `#FFFFFF` | Cards, overlays — "paper on paper" | -| `--bg-inset` | `#D4CCB8` | Pressed/inset areas | +| Token | Value | Usage | +| --------------- | --------- | ---------------------------------- | +| `--bg` | `#FEFAE0` | Cornsilk base — the "desk" | +| `--bg-surface` | `#E0D8C8` | Stone — sidebars, panels, monitor | +| `--bg-elevated` | `#FFFFFF` | Cards, overlays — "paper on paper" | +| `--bg-inset` | `#D4CCB8` | Pressed/inset areas | #### Text @@ -243,11 +243,11 @@ Base-level elements. Every component is built from these. Three variants. All use `--radius-sm` (6px), `--font-sans`. -| Variant | Background | Text | Border | When to use | -| ----------- | -------------- | -------- | --------------------------- | ---------------------------------------------------- | -| **Primary** | `--green` | `#fff` | none | Single main action per view (Begin Planning, Submit) | -| **Accent** | `--copper` | `#fff` | none | Secondary prominent action (Submit Review) | -| **Ghost** | `transparent` | `--text` | `1px solid --border-strong` | Cancel, Back, non-committal actions | +| Variant | Background | Text | Border | When to use | +| ----------- | ------------- | -------- | --------------------------- | ---------------------------------------------------- | +| **Primary** | `--green` | `#fff` | none | Single main action per view (Begin Planning, Submit) | +| **Accent** | `--copper` | `#fff` | none | Secondary prominent action (Submit Review) | +| **Ghost** | `transparent` | `--text` | `1px solid --border-strong` | Cancel, Back, non-committal actions | Sizing: `padding: 12px 24px`, `font-size: --font-size-md`, `font-weight: 600`. @@ -272,13 +272,13 @@ All inputs: `--radius-sm`, `padding: 12px 16px`, `border: 1px solid --border`, Inline status indicators. `--radius-md` (10px), `padding: 5px 14px`, `font-size: --font-size-sm`, `font-weight: 600`. -| State | Background | Text | -| ------- | ----------------- | -------------- | -| Done | `--green-bg` | `--green` | -| Active | `--copper-bg` | `--copper` | -| Failed | `--red-bg` | `--red` | -| Warning | `--ochre-bg` | `--ochre` | -| Neutral | `--bg-inset` | `--text-muted` | +| State | Background | Text | +| ------- | ------------- | -------------- | +| Done | `--green-bg` | `--green` | +| Active | `--copper-bg` | `--copper` | +| Failed | `--red-bg` | `--red` | +| Warning | `--ochre-bg` | `--ochre` | +| Neutral | `--bg-inset` | `--text-muted` | ### 3.5 Labels @@ -309,12 +309,12 @@ padding: --space-6 (24px) **Status variants** — left accent border, tinted background: -| State | Background | Left border | -| ------- | ----------------- | ------------------------ | -| Default | `--bg-elevated` | none | -| Running | `--copper-bg` | `3px solid --copper` | -| Done | `--green-bg` | `3px solid --green` | -| Failed | `--red-bg` | `3px solid --red` | +| State | Background | Left border | +| ------- | --------------- | -------------------- | +| Default | `--bg-elevated` | none | +| Running | `--copper-bg` | `3px solid --copper` | +| Done | `--green-bg` | `3px solid --green` | +| Failed | `--red-bg` | `3px solid --red` | When a card has a status border, use `border-radius: 0 --radius-lg --radius-lg 0` so the left edge is straight. @@ -347,11 +347,11 @@ background: --bg Individual pills: `padding: 6px 16px`, `font-size: --font-size-sm`, `font-weight: 600`. -| State | Background | Text | Prefix | -| -------- | -------------- | -------------- | ------ | -| Inactive | `--bg` | `--text-ghost` | none | +| State | Background | Text | Prefix | +| -------- | ---------- | -------------- | ------ | +| Inactive | `--bg` | `--text-ghost` | none | | Active | `--copper` | `#fff` | `● ` | -| Done | `--green` | `#fff` | `✓ ` | +| Done | `--green` | `#fff` | `✓ ` | Pills are separated by `border-right: 1px solid --border`. Last pill has no right border. @@ -435,11 +435,11 @@ color: #fff animation: fade-in --duration-fast, then fade-out --duration-slow after 3s ``` -| Type | Background | -| ------- | -------------- | +| Type | Background | +| ------- | ---------- | | Info | `--copper` | -| Warning | `--ochre` | -| Error | `--red` | +| Warning | `--ochre` | +| Error | `--red` | ### 4.7 Overlay / Modal @@ -586,7 +586,7 @@ tempted to add them, stop. | ❌ Don't | ✅ Do instead | | --------------------------------------------- | ---------------------------------------------- | | Use `box-shadow` for elevation | Use `border: 1px solid --border` | -| Use blue (`#58a6ff`) for anything | Use `--copper` for active/accent | +| Use blue (`#58a6ff`) for anything | Use `--copper` for active/accent | | Use raw hex colors in components | Reference `var(--token)` | | Make text uppercase in body copy | Uppercase only in `.text-label` elements | | Add `transform: scale()` animations | Use `opacity` transitions only | @@ -603,11 +603,11 @@ tempted to add them, stop. ### File Organization ``` -src/planner/web/css/ - variables.css ← all tokens defined here - layout.css ← app shell, grid, sidebar layouts - components.css ← card, badge, pill, table, form components - animations.css ← keyframes and motion utilities +koan/web/static/css/ + variables.css <- all tokens defined here + layout.css <- app shell, grid, sidebar layouts + components.css <- card, badge, pill, table, form components + animations.css <- keyframes and motion utilities ``` ### Token Naming Convention diff --git a/docs/epic-brief.md b/docs/epic-brief.md index 5be0aa0..1a7d3c9 100644 --- a/docs/epic-brief.md +++ b/docs/epic-brief.md @@ -4,27 +4,23 @@ The epic brief is a compact product-level artifact produced between intake and core-flows. It captures the **what and why** of an epic and serves as a correctness anchor for all downstream phases. -> Related: [artifact-review.md](./artifact-review.md) — the IPC mechanism used +> Related: [artifact-review.md](./artifact-review.md) -- the mechanism used > to present brief.md for human review before pipeline advancement. --- ## What It Captures -| Section | Content | -|---------|---------| -| **Summary** | 3–8 sentences: what this epic is about | -| **Context & Problem** | Who is affected, where in the product, what the current pain is | -| **Goals** | Numbered list of measurable objectives | -| **Constraints** | Hard constraints from landscape.md (technical, timeline, compatibility) | +| Section | Content | +| --------------------- | ----------------------------------------------------------------------- | +| **Summary** | 3-8 sentences: what this epic is about | +| **Context & Problem** | Who is affected, where in the product, what the current pain is | +| **Goals** | Numbered list of measurable objectives | +| **Constraints** | Hard constraints from landscape.md (technical, timeline, compatibility) | -**Size constraint:** Under 50 lines. The brief is consulted by the core-flows phase, planner, and orchestrator on every pipeline run — compact size ensures it -remains a quick reference rather than a specification to read in full. - -The 50-line limit is a forcing function: a brief that requires 200 lines is -not a brief — it is a spec. If the brief writer cannot distill intake context -into 50 lines, the intake phase likely gathered more context than necessary, -or the epic scope is too large to address in one pipeline run. +**Size constraint:** Under 50 lines. The brief is consulted by the core-flows +phase, planner, and orchestrator on every pipeline run -- compact size ensures +it remains a quick reference rather than a specification to read in full. ## What It Excludes @@ -33,78 +29,67 @@ or the epic scope is too large to address in one pipeline run. - Implementation details - Story decomposition -These belong in later artifacts (story sketches, `plan/context.md`). The brief -is deliberately non-technical so it remains stable as the pipeline progresses. +These belong in later artifacts (story sketches, `plan/context.md`). --- ## Pipeline Position ``` -intake → brief-generation → core-flows → tech-plan → ticket-breakdown → cross-artifact-validation → execution → implementation-validation +intake -> brief-generation -> core-flows -> tech-plan -> ticket-breakdown -> cross-artifact-validation -> execution -> implementation-validation ``` The brief sits between intake and core-flows: -- **After intake:** `landscape.md` is complete — the LLM has investigated the - codebase, asked all clarifying questions, and produced a synthesis of - findings and decisions. The brief distills this into a problem statement. +- **After intake:** `landscape.md` is complete. The brief distills this into a + problem statement. - **Before core-flows:** Downstream phases read `brief.md` to scope work - against stated goals and constraints. Without the brief, downstream phases - would invent scope not present in the user's intent. + against stated goals and constraints. --- ## Brief-Writer Subagent -Role: `"brief-writer"`. Model tier: `"strong"` (same tier as intake — synthesis from intake context requires genuine reasoning, not -mechanical transformation). +Role: `"brief-writer"`. Model tier: `"strong"` (synthesis from intake context +requires genuine reasoning). ### Step Progression ``` -Boot → koan_complete_step (step 0 → 1) +Boot -> koan_complete_step (step 0 -> 1) Step 1 (Read): - Read landscape.md. Build mental model of task summary, prior art, codebase findings, project conventions, - decisions, and constraints. No file writes allowed. + Read landscape.md. Build mental model. No file writes allowed. Step 2 (Draft & Review): Write brief.md. Call koan_review_artifact. - If feedback → revise brief.md, call koan_review_artifact again. - If "Accept" → call koan_complete_step. + If feedback -> revise brief.md, call koan_review_artifact again. + If "Accept" -> call koan_complete_step. [Loops within step 2 until user accepts] Step 3 (Finalize): Phase complete. ``` -**Review gate:** `validateStepCompletion(step=2)` requires at least one -`koan_review_artifact` call before `koan_complete_step` is allowed. The LLM -cannot skip the review by calling `koan_complete_step` directly after writing -the file. - -**Step 2 loop is implicit:** The LLM remains in step 2 by continuing to call -`koan_review_artifact` rather than advancing. There is no backward step -transition and no `getNextStep()` override. - -See [artifact-review.md](./artifact-review.md) for the IPC protocol that -powers the review gate. +**Review gate:** `validate_step_completion(step=2)` in +`koan/phases/brief_writer.py` requires at least one `koan_review_artifact` call +before `koan_complete_step` is allowed. ### Permissions -```typescript -["brief-writer", new Set([ - "koan_complete_step", - "koan_review_artifact", - "edit", - "write", - // No koan_ask_question — uses artifact review, not structured questions. - // No koan_request_scouts — all codebase context arrives via landscape.md. -])] +```python +# koan/lib/permissions.py +"brief-writer": { + "koan_complete_step", + "koan_review_artifact", + "edit", + "write", + # No koan_ask_question -- uses artifact review, not structured questions. + # No koan_request_scouts -- all codebase context arrives via landscape.md. +} ``` -Write/edit access is path-scoped to the epic directory (`PLANNING_ROLES`). +Write/edit access is path-scoped to the epic directory. --- @@ -112,19 +97,14 @@ Write/edit access is path-scoped to the epic directory (`PLANNING_ROLES`). All planning phases are prompted to read `brief.md` before acting: -| Phase | Why | -|-------|-----| +| Phase | Why | +| ------------------------------- | ----------------------------------------------------------------------- | | **Core-flows and later phases** | Scope work against brief goals; must not invent scope absent from brief | -| **Planner** | Plans must serve product-level goals and respect constraints | -| **Orchestrator** | Validates story completion against product goals | +| **Planner** | Plans must serve product-level goals and respect constraints | +| **Orchestrator** | Validates story completion against product goals | The executor reads `plan/context.md` (story-level context) and does not -consult the epic brief directly — it works from the plan, which already -incorporates brief context via the planner. - -Downstream agents receive a nudge in step 1 guidance: they are told to read -`brief.md` themselves. This keeps prompts stable across brief evolution and -ensures agents see current file content rather than a spawn-time snapshot. +consult the epic brief directly. --- @@ -132,28 +112,23 @@ ensures agents see current file content rather than a spawn-time snapshot. ### Artifact cascade -Each phase produces an artifact that downstream phases consult. The cascade -in this pipeline: +Each phase produces an artifact that downstream phases consult: ``` landscape.md (intake synthesis) - → brief.md (problem + goals + constraints) - → core-flows.md (user journeys) - → story.md × N (ticket-breakdown) - → plan/context.md × N (story plans) + -> brief.md (problem + goals + constraints) + -> core-flows.md (user journeys) + -> story.md x N (ticket-breakdown) + -> plan/context.md x N (story plans) ``` -Each artifact is progressively more specific. The brief is the -most-referenced — every phase from core-flows through implementation-validation can check -it to stay aligned with the original problem. +Each artifact is progressively more specific. ### Why a separate brief phase A merged "brief + core-flows" agent would violate the single-cognitive-goal -principle: writing a product brief and defining user journeys are -distinct reasoning tasks. Separating them: +principle. Separating them: - Forces the brief to be reviewed and accepted before core-flows begins - Prevents downstream phases from anchoring on their own interpretation of scope - Creates a reviewable artifact that can be corrected before downstream work starts -- Enables downstream phase scope to be validated against an explicit human-approved brief diff --git a/docs/intake-loop.md b/docs/intake-loop.md index 466fd55..e049fb4 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -4,14 +4,14 @@ How the intake phase implements a confidence-gated investigation loop, and the prompt engineering principles that govern it. > Parent doc: [architecture.md](./architecture.md) -> Related: [subagents.md § Step-First Workflow](./subagents.md#step-first-workflow-basephase) +> Related: [subagents.md -- Step-First Workflow](./subagents.md#step-first-workflow) --- ## Overview The intake phase is the most consequential subagent in the pipeline. Its -single output — `landscape.md` — is the sole input for all downstream phases. +single output -- `landscape.md` -- is the sole input for all downstream phases. Every story boundary, every implementation plan, and every line of code produced downstream depends on the completeness and accuracy of that file. Gaps in `landscape.md` compound: a missed decision becomes a wrong story @@ -25,15 +25,15 @@ LLM declares it is "certain" the decomposer has everything it needs. ### Step structure -| Step | Name | Runs | Purpose | -|------|------|------|---------| -| 1 | Extract | 1× | Read `conversation.jsonl`. No side effects. | -| 2 | Scout | 1–4× | Dispatch codebase investigators. | -| 3 | Deliberate | 1–4× | Enumerate knowns/unknowns, ask user questions. | -| 4 | Reflect | 1–4× | Self-verify completeness, declare confidence. | -| 5 | Synthesize | 1× | Write `landscape.md`. Review gate: calls `koan_review_artifact` before completing (same pattern as brief-writer). | +| Step | Name | Runs | Purpose | +| ---- | ---------- | ---- | ---------------------------------------------------------------------------------- | +| 1 | Extract | 1x | Read conversation input. No side effects. | +| 2 | Scout | 1-4x | Dispatch codebase investigators. | +| 3 | Deliberate | 1-4x | Enumerate knowns/unknowns, ask user questions. | +| 4 | Reflect | 1-4x | Self-verify completeness, declare confidence. | +| 5 | Synthesize | 1x | Write `landscape.md`. Review gate: calls `koan_review_artifact` before completing. | -Steps 2–4 form the loop. Each call to `koan_complete_step` during these steps +Steps 2-4 form the loop. Each call to `koan_complete_step` during these steps either returns the next step in sequence or loops back from step 4 to step 2. Steps 1 and 5 execute exactly once. @@ -41,66 +41,48 @@ Steps 1 and 5 execute exactly once. ## Non-Linear Step Progression -### `getNextStep()` hook +### `get_next_step()` hook -`BasePhase` provides a default linear counter: `step+1` until `totalSteps`, -then `null` (done). Subclasses override `getNextStep(currentStep)` to -implement non-linear flows. +The default step engine provides linear progression: `step+1` until +`total_steps`, then `None` (done). Phase modules override `get_next_step(step, ctx)` +to implement non-linear flows. -```typescript -// Default: strictly linear. -protected getNextStep(currentStep: number): number | null { - if (currentStep === this.totalSteps) return null; - return currentStep + 1; -} +`koan/phases/intake.py` overrides this to implement the confidence gate: + +```python +def get_next_step(step, ctx): + """Pure query -- returns where to go, does not mutate state.""" + if step == 4: # Reflect step + if confidence == "certain" or is_exhausted: + return 5 # -> Synthesize + return 2 # -> Scout (loop back) + if step == 5: + return None # Synthesize -> done + return step + 1 # linear for steps 1-3 ``` -`IntakePhase` overrides this to implement the confidence gate: - -```typescript -// Pure query — returns where to go, does not mutate state. -protected getNextStep(currentStep: number): number | null { - if (currentStep === 4) { // Reflect step - if (confidence === "certain" || isExhausted) { - return 5; // → Synthesize - } - return 2; // → Scout (loop back) - } - if (currentStep === 5) return null; // Synthesize → done - return currentStep + 1; // linear for steps 1–3 -} - -// Side effects of the loop-back decision live here, not in getNextStep(). -protected override async onLoopBack(_from: number, _to: number): Promise { - this.iteration++; - this.ctx.intakeConfidence = null; // reset for next round - await this.eventLog?.emitIterationStart(this.iteration, MAX_ITERATIONS); -} +```python +def on_loop_back(from_step, to_step, ctx): + """Side effects of the loop-back decision live here, not in get_next_step().""" + ctx.iteration += 1 + ctx.intake_confidence = None # reset for next round + emit_iteration_start(ctx.event_log, ctx.iteration, MAX_ITERATIONS) ``` -`getNextStep()` is a **pure query** — it only decides where to go. All side +`get_next_step()` is a **pure query** -- it only decides where to go. All side effects (counter increments, state resets, event emission) belong in -`onLoopBack()`, which `BasePhase.handleStepComplete()` calls whenever -`getNextStep()` returns a step number less than the current one. This -separation makes `getNextStep()` safe to reason about and test in isolation. - -All other phase classes inherit the default linear behavior. The hook localizes -non-linear logic to the one class that needs it without touching other phases. +`on_loop_back()`, which the step engine calls whenever `get_next_step()` returns +a step number less than the current one. -**Why not a separate loop-phase class?** The `BasePhase` machinery (boot -transition, permission fence, event logging, step formatting) is the same -regardless of whether progression is linear or not. A hook is cheaper than a -new abstraction tier and does not require refactoring the six existing phase -classes. +All other phase modules inherit the default linear behavior. The hook localizes +non-linear logic to the one module that needs it without touching other phases. -### `totalSteps` semantics with a loop +### `total_steps` semantics with a loop -For `IntakePhase`, `totalSteps = 5` reflects the number of distinct step +For the intake phase, `total_steps = 5` reflects the number of distinct step definitions, not the number of `koan_complete_step` calls. The loop may -execute steps 2–4 up to four times, producing up to 1 + (3 × 4) + 1 = 14 -calls in the worst case. The `step_transition` event carries both the step -number and the iteration-annotated step name (e.g., "Scout (round 3)") so the -UI can distinguish loop iterations. +execute steps 2-4 up to four times, producing up to 1 + (3 x 4) + 1 = 14 +calls in the worst case. --- @@ -113,80 +95,58 @@ UI can distinguish loop iterations. 1. **Optional parameters are skippable.** LLMs frequently omit optional parameters, especially when under token pressure. A separate tool call is - harder to skip accidentally — the LLM must make an explicit decision. + harder to skip accidentally. 2. **`koan_complete_step` is shared across all phases.** Adding confidence to - it would either bloat the parameter schema for roles that never set - confidence, or require conditional schema logic that the permission fence - cannot express cleanly. A dedicated `koan_set_confidence` tool, restricted - to the intake role via `ROLE_PERMISSIONS`, keeps the boundary clean. + it would bloat the parameter schema for roles that never set confidence. + A dedicated `koan_set_confidence` tool, restricted to the intake role via + permissions, keeps the boundary clean. -### Mandatory enforcement via `validateStepCompletion()` +### Mandatory enforcement via `validate_step_completion()` -`BasePhase` exposes a `validateStepCompletion(step)` hook that runs before -`getNextStep()`. It returns null to allow advancement or an error string that -is returned as the `koan_complete_step` tool result — the LLM sees it and +The step engine calls `validate_step_completion(step, ctx)` before +`get_next_step()`. It returns None to allow advancement or an error string that +is returned as the `koan_complete_step` tool result -- the LLM sees it and must fix the pre-condition before retrying. -`IntakePhase` uses this to enforce that `koan_set_confidence` was called in +The intake phase uses this to enforce that `koan_set_confidence` was called in the Reflect step: -```typescript -protected async validateStepCompletion(step: number): Promise { - if (step === 4 && this.ctx.intakeConfidence === null) { - return "You must call koan_set_confidence before completing the Reflect step. ..."; - } - return null; -} +```python +def validate_step_completion(step, ctx): + if step == 4 and ctx.intake_confidence is None: + return "You must call koan_set_confidence before completing the Reflect step." + return None ``` -This is mechanical enforcement on top of the prompt-level instruction. If the -LLM ignores the prompt and calls `koan_complete_step` without first calling -`koan_set_confidence`, it receives an error and must comply. - ### Confidence reset on loop-back -When `getNextStep()` returns step 2 (loop-back), `BasePhase` detects the -backward transition and calls `onLoopBack()`. `IntakePhase.onLoopBack()` -resets `ctx.intakeConfidence = null`. This ensures that in the next Reflect -step, the LLM must call `koan_set_confidence` again — carry-over from the -previous iteration is not possible. - -Without the reset, a LLM that set confidence to "high" in iteration 1 could -call `koan_complete_step` in iteration 2's Reflect step without reassessing, -and `validateStepCompletion` would let it through. - -**Note:** The audit projection's `intakeConfidence` field is updated only when -a `confidence_change` event is appended (i.e., when `koan_set_confidence` is -called). Between loop-back and the next Reflect step, the projection still -shows the previous iteration's confidence level. This is intentional: the -projection reflects the last declared state, not the reset internal state. The -UI reads the projection, so it shows the previous confidence until a new one -is declared. +When `get_next_step()` returns step 2 (loop-back), the step engine detects the +backward transition and calls `on_loop_back()`. The intake module's +`on_loop_back()` resets `ctx.intake_confidence = None`. This ensures that in +the next Reflect step, the LLM must call `koan_set_confidence` again. ### Maximum iterations -The loop is bounded at 4 iterations (`IntakePhase.MAX_ITERATIONS`). When -exhausted, `getNextStep()` returns step 5 (Synthesize) instead of step 2. -`IntakePhase` logs a warning when this forced exit occurs. This prevents -infinite loops if the LLM consistently declares non-certain confidence. +The loop is bounded at 4 iterations. When exhausted, `get_next_step()` returns +step 5 (Synthesize) instead of step 2. This prevents infinite loops if the LLM +consistently declares non-certain confidence. --- ## Step-Aware Permission Gating -The permission fence accepts an optional `intakeStep` parameter and blocks -specific tools during steps where they would undermine the workflow. Two -steps have mechanical tool restrictions: +The permission fence in `koan/lib/permissions.py` accepts the current step +context and blocks specific tools during steps where they would undermine the +workflow. ### Step 1 (Extract): read-only Step 1 should only read the conversation. Without a mechanical gate, the LLM -frontloads all work into step 1, leading to duplicate scout requests in -later steps and bypassing the step-first workflow pattern. +frontloads all work into step 1. -`checkPermission()` blocks all side-effecting tools when -`role === "intake" && intakeStep === 1`: +`check_permission()` blocks all side-effecting tools when +`role == "intake" and intake_step == 1`: ``` koan_request_scouts, koan_ask_question, koan_set_confidence, write, edit @@ -195,45 +155,17 @@ koan_request_scouts, koan_ask_question, koan_set_confidence, write, edit ### Step 3 (Deliberate): no confidence assessment Step 3 is for enumerating knowns/unknowns and asking questions. Confidence -assessment belongs exclusively in step 4 (Reflect), where the LLM must -generate verification questions and answer them with evidence before declaring -confidence. - -Without this gate, the LLM calls `koan_set_confidence("high")` during -Deliberate — mentally committing to completion before entering verification. -This anchors the subsequent Reflect step toward "certain," undermining the -verification loop. - -`checkPermission()` blocks `koan_set_confidence` when -`role === "intake" && intakeStep === 3`. - -The gate enforces temporal separation between deliberation (asking/deciding -what to ask) and reflection (verifying completeness). - -### Step propagation - -The current step is propagated via `ctx.intakeStep`, kept in sync by the -`onStepUpdated()` hook in `IntakePhase`: - -```typescript -protected onStepUpdated(step: number): void { - this.ctx.intakeStep = step; - this.ctx.intakeIteration = this.iteration; -} -``` +assessment belongs exclusively in step 4 (Reflect). -`BasePhase.handleStepComplete()` calls `onStepUpdated()` on every step -transition (including loop-backs), so `ctx.intakeStep` always reflects the -current active step at tool call time. +`check_permission()` blocks `koan_set_confidence` when +`role == "intake" and intake_step == 3`. ### Prompt + enforcement is not redundant The prompt tells the LLM not to use side-effecting tools in step 1 and not to assess confidence in step 3. The permission gates are fallbacks that catch prompt non-compliance. Together: the prompt prevents the behavior; the gate -catches it when the prompt fails. Neither alone is sufficient — the prompt can -be ignored; the gate with no prompt would produce confusing "blocked" errors -with no context for the LLM. +catches it when the prompt fails. --- @@ -241,26 +173,19 @@ with no context for the LLM. Two audit event types support UI visualization of confidence and iteration: -| Event | Emitted by | When | -|-------|-----------|------| -| `confidence_change` | `koan_set_confidence` tool | Every call to koan_set_confidence | -| `iteration_start` | `IntakePhase.onLoopBack()` + `onStepUpdated()` | At every loop iteration start: `onLoopBack` for iterations 2+, `onStepUpdated` for iteration 1 | +| Event | Emitted by | When | +| ------------------- | ---------------------------------- | --------------------------------- | +| `confidence_change` | `koan_set_confidence` tool | Every call to koan_set_confidence | +| `iteration_start` | `on_loop_back()` + step transition | At every loop iteration start | Both events are folded into the `state.json` projection: -- `confidence_change` → `intakeConfidence`, `intakeIteration` -- `iteration_start` → `intakeIteration` +- `confidence_change` -> `intake_confidence`, `intake_iteration` +- `iteration_start` -> `intake_iteration` -The web server polls `state.json` every 50ms for each active agent. When it -detects a change in `intakeConfidence` or `intakeIteration`, it pushes an -`intake-progress` SSE event to connected browser clients. The event payload -includes both the `confidence` string and the `iteration` number, allowing the -UI to render a progress visualization without maintaining its own state. - -The `confidence_change` event requires `ctx.eventLog` to be set. This is -populated in `extensions/koan.ts` during `before_agent_start`, after -`eventLog.open()`. The confidence tool reads `ctx.eventLog` at call time -(mutable-ref pattern) — no reference is needed at registration time. +SSE events are pushed directly from the tool handlers and step engine -- no +polling loop. When the driver handles a `koan_set_confidence` call or detects +a loop-back, it pushes an `intake-progress` SSE event to connected browsers. --- @@ -272,162 +197,57 @@ mechanisms that address specific failure modes. ### Prompt Chaining over Stepwise (Scout / Deliberate / Reflect as separate steps) -A monolithic "investigate" step — containing scouting, deliberation, and -reflection in sequence within a single prompt — is rejected in favor of three -separate `koan_complete_step` calls. - -The risk with a monolithic step is **simulated refinement**: the LLM -artificially degrades its initial output to manufacture visible improvement. -When draft, critique, and refine happen in one cognitive context, the model -sandbaggs the draft to make its self-correction look meaningful. When each -phase is a separate tool call with a distinct cognitive goal, the model must -genuinely complete each phase before seeing the next instruction. There is no -opportunity to pre-plan the "improvement" because the next step's instructions -are not yet visible. - -This is why Scout, Deliberate, and Reflect are separate steps rather than -phases within a single step. +A monolithic "investigate" step is rejected in favor of three separate +`koan_complete_step` calls. The risk with a monolithic step is **simulated +refinement**: the LLM artificially degrades its initial output to manufacture +visible improvement. Separate steps enforce genuinely isolated reasoning. ### Thread-of-Thought in Deliberate (explicit enumeration before questions) -The Deliberate step instructs the LLM to walk through each area relevant to -the task and explicitly state what is known, unknown, and its source — before -formulating questions. This is the Thread-of-Thought pattern: "walk through -this context in manageable parts step by step, summarizing and analyzing as we -go." - -Without this enumeration, the LLM tends to ask questions based on what -immediately comes to mind rather than what is actually unknown. Gaps that are -not top-of-mind are missed. Forcing explicit enumeration of knowns and unknowns -before question formulation surfaces those gaps and prevents asking questions -the conversation or scouts already answered. - -The enumeration also has a secondary benefit in iteration 2+: it forces the -LLM to re-state updated understanding before forming follow-up questions, -preventing the "lost in the middle" problem where findings from early scout -tool results are effectively forgotten by the time questions are formulated. +The Deliberate step instructs the LLM to walk through each area and explicitly +state what is known, unknown, and its source -- before formulating questions. +This surfaces gaps that are not top-of-mind. ### Anticipatory Reflection in Deliberate (downstream impact assessment) -Between the Thread-of-Thought enumeration (Phase A) and question formulation -(Phase B), the Deliberate step includes a downstream impact assessment -(Phase A.5). For each unknown, the LLM must assess: if this assumption is -wrong, what happens to downstream planning? Could it split or merge stories? -Would the executor hit a surprise? - -Each unknown is classified as ASK (user input needed), SCOUT (follow-up can -resolve), or SAFE (genuinely an implementation detail). This is the -Anticipatory Reflection pattern: before deciding on an action (ask or skip), -anticipate the consequences of getting it wrong. - -Without this step, the LLM classifies unknowns as "implementation details" -without considering downstream consequences, avoiding questions it should ask. -The explicit impact assessment makes the cost of wrong assumptions concrete -and forces the LLM to justify each skip. +Between enumeration and question formulation, the Deliberate step includes a +downstream impact assessment. Each unknown is classified as ASK (user input +needed), SCOUT (follow-up can resolve), or SAFE (implementation detail). ### Default-ask question framing (preventing question avoidance) The Deliberate step frames question-asking as the default, with skipping -requiring justification. The criteria use "Default: ask. You may skip a -question ONLY if ALL of these are true" — three restrictive conditions that -require the unknown to be purely about implementation, incapable of changing -story boundaries, and unambiguous. - -This inverts the typical LLM bias. LLMs prefer advancing the workflow over -pausing it, and will exploit any "skip if" framing by finding reasons to skip. -By making "ask" the default and "skip" the exception requiring triple -justification, the prompt aligns the path of least resistance with the desired -behavior. - -The framing also explicitly positions the user as a collaborator ("The user is -your collaborator, not an interruption") and emphasizes that intake is the only -phase where the user can be consulted ("The decomposer cannot ask questions -later — this is the only chance to get clarification"). +requiring triple justification. This inverts the typical LLM bias toward +advancing the workflow. ### Chain-of-Verification in Reflect (evidence-grounded self-assessment) -The Reflect step instructs the LLM to generate 3–5 verification questions +The Reflect step instructs the LLM to generate 3-5 verification questions framed from the decomposer's perspective, then answer each using only concrete -evidence (quotes from conversation, specific scout findings, explicit user -answers). Verification questions that cannot be answered with evidence identify -gaps. This is the Chain-of-Verification (CoVe) pattern. - -The framing matters: "from the decomposer's perspective" anchors the LLM's -self-assessment to the actual consumer of its output. Without this framing, the -LLM tends to ask generic comprehension questions ("do I understand the topic?") -rather than boundary-defining questions ("could I define the scope of story 1 -vs story 2 right now?"). Generic questions produce generic assessments; -boundary-specific questions surface the gaps that actually matter downstream. - -This is explicitly NOT intrinsic self-correction, which degrades reasoning -performance when no external feedback source is available. The LLM is not -being asked to critique its reasoning — it is being asked to generate specific -verification questions and answer them against gathered evidence. The evidence -is external (conversation, scouts, user answers), not the LLM's own reasoning. +evidence. This is the Chain-of-Verification (CoVe) pattern. ### Contrastive confidence definitions (preventing premature "certain") -The Reflect step provides two contrastive definitions of the "certain" -confidence level: - -- **Positive:** "certain means ALL of these are true" (four specific - conditions about scope, codebase knowledge, user decisions, and story - immutability) -- **Negative:** "you are NOT certain if ANY of these are true" (seven - failure modes that preclude certainty) - -This is the Contrastive Chain-of-Thought pattern. A single positive definition -("certain means you have everything you need") leaves the LLM to interpret what -"everything" means — and LLMs tend to interpret this charitably, setting -confidence to "certain" prematurely to exit the loop faster (token-saving -behavior). The negative examples make the failure modes concrete and explicit, -raising the bar for claiming certainty. - -The negative checklist includes conditions that require positive evidence -(questions asked, assumptions verified) rather than the absence of negative -signals. The critical first condition — "you have not asked the user any -questions in this or any previous round" — is mechanically non-vacuous: it is -true or false based on whether `koan_ask_question` was called, not on a -judgment call the LLM can rationalize. This prevents the checklist from being -vacuously satisfied when no user interaction has occurred. +The Reflect step provides both positive ("certain means ALL of these are true") +and negative ("you are NOT certain if ANY of these are true") definitions. +The negative examples make failure modes concrete and explicit. ### Stakes framing (EmotionPrompt for accountability) -The system prompt includes accountability-invoking language: "A question you -don't ask is an answer you're making up." This is the EmotionPrompt pattern -(self-monitoring theory variant), which increases truthfulness and factual -accuracy by invoking social accountability. The framing connects intake -shortcuts directly to downstream failures, making the cost of skipping -questions concrete rather than abstract. +The system prompt includes: "A question you don't ask is an answer you're +making up." This connects intake shortcuts directly to downstream failures. ### Iteration-aware guidance (first iteration vs. refinement) Steps 2 (Scout) and 3 (Deliberate) produce different instruction text for -the first iteration vs. subsequent iterations. First-iteration Scout says: -"Based on your reading of the conversation..." Subsequent Scout says: "Based -on gaps identified in your previous reflection..." - -This is context reframing. The first iteration is an initial exploration; the -second iteration is a targeted follow-up. If both iterations received the same -prompt, the LLM would repeat its initial exploration rather than narrowing in -on the gaps surfaced by reflection. The iteration number is passed as a -parameter to `intakeStepGuidance()`, which branches on it to produce the -appropriate framing. +the first iteration vs. subsequent iterations. This prevents the LLM from +repeating its initial exploration. ### Iteration expectations (soft minimum via GIoT) The Reflect step includes soft guidance that round 1 should rarely produce -"certain" confidence, and that confidence should be capped at "high" if no -questions have been asked. This is inspired by the GIoT (Guided Iteration of -Thought) pattern, which forces a minimum number of iterations to ensure -adequate exploration. - -The guidance is soft rather than mechanically enforced (unlike the hard -`MAX_ITERATIONS` cap) to avoid forcing unnecessary iterations on genuinely -trivial tasks. It provides directional pressure: the LLM can still declare -"certain" on round 1, but it must do so against explicit guidance that this -is unusual. This makes premature exit a deliberate, justified choice rather -than the path of least resistance. +"certain" confidence. This provides directional pressure without forcing +unnecessary iterations on trivial tasks. --- @@ -435,64 +255,38 @@ than the path of least resistance. ### Don't put confidence in koan_complete_step's `thoughts` parameter -`thoughts` is an escape hatch for models that can't mix text + tool_call in -one response (see [subagents.md § The thoughts parameter](./subagents.md#the-thoughts-parameter--escape-hatch-not-data-channel)). -It must never be actively used to capture task output, and parsing it for -routing decisions would violate the driver determinism invariant: the driver -never parses free-text. Confidence must flow through a structured tool call -with a typed parameter. +`thoughts` is an escape hatch for models that can't mix text + tool_call. +Parsing it for routing decisions would violate driver determinism. Confidence +must flow through a structured tool call. ### Don't rely on the Reflect prompt alone to enforce koan_set_confidence -The Reflect step prompt ends with "WHEN DONE: First call koan_set_confidence, -then call koan_complete_step." This is a prompt instruction and can be ignored. -The `validateStepCompletion()` hook is the mechanical enforcement layer. Both -must be present: the prompt tells the LLM what to do; the hook catches -non-compliance. +The `validate_step_completion()` hook is the mechanical enforcement layer. +Both prompt and hook must be present. ### Don't remove the confidence null-reset on loop-back -The null-reset lives in `onLoopBack()` in `IntakePhase`. When looping from -step 4 → step 2, `ctx.intakeConfidence` must be set to null. Without this -reset, the `validateStepCompletion()` check in the next Reflect step sees the -old confidence value and allows `koan_complete_step` through without the LLM -calling `koan_set_confidence` again. - -The reset must happen in `onLoopBack()`, not in `getNextStep()`. Placing it -in `getNextStep()` would make the query impure — see -[architecture.md § Don't put side effects in getNextStep()](./architecture.md#dont-put-side-effects-in-getnextstep). +Without this reset, `validate_step_completion()` sees the old confidence value +and allows advancement without the LLM calling `koan_set_confidence` again. +The reset must happen in `on_loop_back()`, not in `get_next_step()`. ### Don't add koan_set_confidence to non-intake roles -`koan_set_confidence` is gated to the intake role via `ROLE_PERMISSIONS`. If -it were available to other roles, they could set `ctx.intakeConfidence` -spuriously, affecting the intake loop's behavior if intake is running -concurrently (which it isn't currently, but could be in the future). +`koan_set_confidence` is gated to the intake role via permissions. ### Don't allow koan_set_confidence during Deliberate (step 3) -`koan_set_confidence` is blocked during step 3 via `STEP_3_BLOCKED_TOOLS`. Without this gate, the LLM sets confidence during Deliberate, anchoring the -subsequent Reflect step toward "certain" and undermining the verification -loop. Confidence assessment must happen only during Reflect (step 4), after -the LLM has generated and answered verification questions. +subsequent Reflect step toward "certain". Confidence assessment must happen +only during Reflect (step 4). ### Don't make the "NOT certain" checklist vacuously satisfiable -Every condition in the negative confidence checklist must be non-vacuously -testable — it must be possible for the condition to fire based on observable -facts. Conditions framed as "a user answer raised a new question" are -vacuously false when no questions have been asked (no answers exist, so no -follow-up can be triggered). Prefer conditions that require positive evidence: -"you have not asked any questions" is mechanically true or false based on -whether `koan_ask_question` was called. - -### Don't skip `ctx.intakeStep` sync in onStepUpdated - -The permission gate reads `ctx.intakeStep` at tool call time. If -`onStepUpdated()` were not called on loop-back (step 4 → step 2), step 2 -would execute with `ctx.intakeStep = 4`, and the step-1 gate would not fire -(step 4 ≠ 1). Steps 1 and 3 both need gating (step 1 blocks side-effecting -tools; step 3 blocks `koan_set_confidence`), so keeping `ctx.intakeStep` -accurate at all times is essential for correct gate behavior across loop -iterations. +Every condition must be non-vacuously testable. Prefer conditions that require +positive evidence: "you have not asked any questions" is mechanically true or +false based on whether `koan_ask_question` was called. + +### Don't skip step sync on loop-back + +The permission gate reads the current step at tool call time. If the step +context is not updated on loop-back, gates fire at the wrong step. diff --git a/docs/ipc.md b/docs/ipc.md index 5e2547d..9caa548 100644 --- a/docs/ipc.md +++ b/docs/ipc.md @@ -1,380 +1,224 @@ -# IPC Protocol +# Inter-Process Communication -File-based inter-process communication between parent and subagent processes. +HTTP MCP-based communication between the driver and subagent processes. > Parent doc: [architecture.md](./architecture.md) > -> `ipc.json` is one of three well-known files in the subagent directory. -> See [architecture.md § Directory-as-contract](./architecture.md#6-directory-as-contract) -> for how it relates to `task.json` (input) and `state.json` (observation). +> The MCP endpoint at `http://localhost:{port}/mcp?agent_id={id}` is the sole +> communication channel between parent and child. See +> [architecture.md -- Directory-as-contract](./architecture.md#6-directory-as-contract). --- ## Overview -Subagent `pi --mode json -p` processes cannot communicate with the parent via -stdin (it is `"ignore"`). Instead, they share a single `ipc.json` file in the subagent -directory. The subagent writes a request; the parent polls, handles it, and -writes the response back. The subagent polls for the response. +Subagent CLI processes (`claude`, `codex`, `gemini`) communicate with the +driver via HTTP MCP tool calls. The driver runs a single Starlette HTTP server +that handles both the web dashboard and the MCP tool endpoint. When a tool call +arrives, the server looks up the agent's state by `agent_id` in an in-process +registry and handles the call directly. -``` -subagent: writeIpcFile(dir, { response: null }) ← atomic write creates request -subagent: poll loop (500ms): readIpcFile(dir) ← blocks LLM turn -parent: poll loop (300ms): readIpcFile(dir) ← detects request -parent: handles request (web server or scout pool) ← does work -parent: writeIpcFile(dir, { ..., response: data }) ← atomic write with response -subagent: readIpcFile → response !== null ← breaks poll loop -subagent: deleteIpcFile(dir) ← cleanup -``` - -### Why file-based IPC +Three tool calls involve blocking interactions -- the HTTP request is held open +while the driver awaits an external response: -- **Cross-process simplicity** — no socket management, no connection lifecycle -- **Debuggable** — `cat ipc.json` shows the current state -- **Atomic via rename** — tmp file → `fs.rename()` prevents partial reads -- **Cross-platform** — no POSIX-specific constructs +| Tool | What blocks | Who responds | +| ---------------------- | ----------------------- | ------------------------------ | +| `koan_ask_question` | User input needed | User via web UI | +| `koan_request_scouts` | Scout subagents running | Driver (after scouts complete) | +| `koan_review_artifact` | User review needed | User via web UI | -### Constraints - -- **One request at a time** per subagent directory. Tools check - `ipcFileExists(dir)` before writing and return an error if a request is - already pending. -- **Polling, not push** — inherent latency of poll intervals (300ms parent, - 500ms subagent). -- **The subagent's LLM turn is blocked** while polling. The tool's `execute` - function is in a `sleep(500)` loop — the LLM cannot do other work until - the response arrives. +For all three, the MCP tool handler creates an `asyncio.Future`, stores it in +`AgentState.pending_tool`, and awaits it. The HTTP connection stays open until +the Future resolves. There is no polling, no intermediate files. --- -## Message Types - -The protocol supports three request types, discriminated by the `type` field: - -### `ask` — User questions - -The subagent needs human input. The request contains one question with -options; the response contains the user's selection. - -```typescript -interface AskIpcFile { - type: "ask"; - id: string; // UUID, for response correlation - createdAt: string; - payload: { - id: string; - question: string; - context?: string; // optional multi-paragraph background - options: Array<{ label: string }>; - multi?: boolean; - recommended?: number; // 0-indexed - }; - response: AskResponse | null; // null = pending, non-null = answered -} -``` - -### `scout-request` — Parallel codebase exploration - -The subagent needs codebase context. The request contains scout task -definitions; the response contains file paths to findings. - -```typescript -interface ScoutIpcFile { - type: "scout-request"; - id: string; - createdAt: string; - scouts: Array<{ - id: string; // e.g., "auth-patterns" - role: string; // e.g., "security auditor" - prompt: string; // e.g., "Find all auth middleware in src/" - }>; - response: { findings: string[]; failures: string[] } | null; -} -``` +## Blocking Interaction Model -### `artifact-review` — Human review of a written artifact - -The subagent has produced a markdown artifact and needs human review before -advancing. The request contains the file path and raw markdown content; the -response contains the user's feedback string or `"Accept"`. - -```typescript -interface ArtifactReviewIpcFile { - type: "artifact-review"; - id: string; - createdAt: string; - payload: { - artifactPath: string; // file path (used as display label) - content: string; // raw markdown (read from the file by the tool) - description?: string; // optional reviewer context - }; - response: { - id: string; - respondedAt: string; - feedback: string; // "Accept" or free-form revision feedback - } | null; -} -``` +### `asyncio.Future` resolution -See [artifact-review.md](./artifact-review.md) for the full protocol, tool -interface, web UI behavior, and reusability guidance. +When a blocking tool is called: ---- +1. MCP endpoint receives tool call with `agent_id` +2. Handler creates `asyncio.Future` and stores it as a `PendingInteraction` in `AgentState` +3. For user-facing interactions: pushes SSE event to browsers (question form, review form) +4. Handler `await`s the Future -- HTTP connection stays open +5. External actor resolves the Future: + - User interactions: web UI `POST /api/answer` or `POST /api/artifact-review` resolves it + - Scout requests: driver spawns scouts, awaits completion, resolves Future with findings +6. Handler returns the resolved value as the MCP tool result -## Atomic Writes - -All IPC file operations use atomic tmp-rename: - -```typescript -// Write: .ipc.tmp.json → rename → ipc.json -async function writeIpcFile(dir, data) { - const tmp = path.join(dir, ".ipc.tmp.json"); - const target = path.join(dir, "ipc.json"); - await fs.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", "utf8"); - await fs.rename(tmp, target); -} - -// Read: returns null on missing file OR parse error -// Parse errors are treated as "not ready" — handles partial writes on non-POSIX systems -async function readIpcFile(dir): IpcFile | null { - try { - const raw = await fs.readFile(path.join(dir, "ipc.json"), "utf8"); - return JSON.parse(raw); - } catch { - return null; - } -} - -// Delete: removes both ipc.json and .ipc.tmp.json, swallows ENOENT -async function deleteIpcFile(dir) { ... } ``` - ---- - -## Poll Timing - -| Poller | Interval | Purpose | -|--------|----------|---------| -| **Parent IPC responder** | 300ms | Detect subagent requests quickly | -| **Subagent tool** | 500ms | Wait for parent response | -| **Web server agent polling** | 50ms | Update agent status in UI | - -The parent polls slightly faster than the subagent to ensure it picks up -requests promptly. Both intervals are low enough for interactive feel. - ---- - -## Parent-Side IPC Responder - -`runIpcResponder()` starts concurrently with the child process (when a web -server handle is available) and terminates when the `AbortSignal` fires -(child process exit → abort). - -``` -while (!signal.aborted) { - sleep(300ms) - ipc = readIpcFile(subagentDir) - if ipc === null or ipc.response !== null → continue - if ipc.type === "ask" → handleAskRequest(...) - if ipc.type === "scout-request" → handleScoutRequest(...) - if ipc.type === "artifact-review" → handleArtifactReviewRequest(...) -} +subagent ---POST /mcp koan_ask_question---> driver + | + +-- create Future + +-- push SSE "ask" event to browser + +-- await Future + | + user fills form <---+ + POST /api/answer ---+ + | + +-- resolve Future with answer + | +subagent <---tool result (answer)----------- + ``` -### Error handling - -The poll loop swallows **all** errors. Transient filesystem issues (e.g., -file being renamed) must not abort the parent session. The next poll cycle -will pick up the file successfully. - -### Idempotence guard +### `PendingInteraction` -Before writing a response, the responder re-reads `ipc.json` and validates: -- The file still exists -- The `type` matches the expected request type -- The `id` matches the original request ID -- `response` is still `null` +The `PendingInteraction` object stored in `AgentState.pending_tool`: -This prevents writing a response to a stale or replaced request. +- `type` -- one of `"ask"`, `"scout-request"`, `"artifact-review"` +- `id` -- UUID for correlation +- `payload` -- type-specific request data +- `future` -- the `asyncio.Future` awaiting resolution -### Circular import avoidance - -The IPC responder needs to spawn scouts, but importing from `subagent.ts` -would create a circular dependency. Instead, `subagent.ts` injects a -`ScoutSpawnContext` interface at startup: +### Constraints -```typescript -interface ScoutSpawnContext { - epicDir: string; - spawnScout(task: ScoutTask, scoutDir: string, outputFile: string): Promise; -} -``` +- **One pending interaction at a time** per agent. A second blocking tool call + while one is pending returns an error. +- **No polling** -- the Future model replaces the previous file-polling design. + Resolution is immediate when the external actor responds. +- **The subagent's LLM turn is blocked** while the Future is pending. The MCP + HTTP connection is held open; the LLM cannot call other tools until the + response arrives. --- ## Ask Flow ``` -intake-llm calls koan_ask_question({ id, question, context?, options, ... }) - → tool writes AskIpcFile { type: "ask", response: null } - → tool enters 500ms poll loop (LLM turn blocked) - -ipc-responder detects { type: "ask", response: null } - → appends "Other" option to the question - → calls webServer.requestAnswer(question, signal) - → creates Promise in pendingInputs map - → SSE "ask" event → browser renders QuestionForm - → user fills form, clicks Submit - → POST /api/answer → resolves Promise - → maps answer to AskAnswerPayload - → writes AskResponse to ipc.json (atomic) - -tool poll detects response !== null - → breaks loop - → deleteIpcFile(dir) - → formats answer as structured text - → returns to LLM +subagent calls koan_ask_question({ questions: [...] }) + -> MCP endpoint checks permissions + -> creates PendingInteraction { type: "ask", future: asyncio.Future() } + -> stores in AgentState.pending_tool + -> pushes SSE "ask" event to browsers + -> awaits Future + +user sees question form in web UI + -> fills form, clicks Submit + -> POST /api/answer -> resolves Future with user's selection + +MCP handler receives resolved value + -> clears AgentState.pending_tool + -> formats answer as structured text + -> returns as MCP tool result to subagent ``` -The "Other" option is appended server-side — the LLM never includes it. +The "Other" option is appended server-side -- the LLM never includes it. --- ## Scout Flow ``` -intake-llm calls koan_request_scouts({ scouts: [...] }) - → tool writes ScoutIpcFile { type: "scout-request", response: null } - → tool enters 500ms poll loop (LLM turn blocked) - -ipc-responder detects { type: "scout-request", response: null } - → computes scoutDir + outputFile for each task - → webServer.registerAgent(...) for each scout (UI tracking) - → pool(taskIds, concurrency=4, worker): - for each scout (up to 4 concurrent): - → mkdir(scoutDir, { recursive: true }) - → spawnScout(task, scoutDir, outputFile) - → full subagent lifecycle: boot → step 1 → work → complete → exit - → readProjection(scoutDir) → check status === "completed" - → if succeeded: findings.push(outputFile) - → if failed: failures.push(taskId) - → webServer.completeAgent(taskId) - → writes ScoutResponse { findings: [paths], failures: [ids] } to ipc.json - -tool poll detects response !== null - → breaks loop - → deleteIpcFile(dir) - → reads each findings.md file verbatim (inline, not just paths) - → returns concatenated content to LLM +subagent calls koan_request_scouts({ scouts: [...] }) + -> MCP endpoint checks permissions + -> creates PendingInteraction { type: "scout-request", future: asyncio.Future() } + -> stores in AgentState.pending_tool + + driver handles scout request in-process: + -> for each scout task: + -> assign scout agent_id + -> register scout in agent registry + -> write MCP config pointing at same HTTP server + -> spawn scout CLI process + -> scout connects to /mcp?agent_id={scout_id} + -> scout calls koan_complete_step, does work, completes + -> deregister scout + -> collect findings from completed scouts + -> resolve Future with { findings: [paths], failures: [ids] } + +MCP handler receives resolved value + -> clears AgentState.pending_tool + -> reads each findings.md file verbatim + -> returns concatenated content as MCP tool result ``` ### Scout pool behavior -The pool uses a semaphore with limit 4. All scouts are submitted to -`Promise.all` simultaneously; the semaphore gates actual execution. The pool: +All scouts are submitted concurrently with a configurable concurrency limit +(default: 4). The pool: - **Runs all items to completion** regardless of individual failures -- **Reports progress** via optional callback (done/total/active/queued) -- **Does not implement timeouts** — timeout logic belongs in the worker closure +- **Reports progress** via SSE events +- **Does not implement timeouts** -- timeout logic belongs in the caller ### Scout success determination -Scout success is derived from the JSON audit projection, not file existence: +Scout success is derived from the audit projection, not file existence: -```typescript -const projection = await readProjection(scoutDir); -succeeded = projection?.status === "completed"; +```python +projection = read_projection(scout_dir) +succeeded = projection.get("status") == "completed" ``` -A scout can write a partial `findings.md` and then crash. File existence is -not proof of completion. - ### Failed scouts are non-fatal The tool result tells the LLM: `"Failed scouts (non-fatal, proceed without them): task-id-1, task-id-2"` -The LLM must proceed with whatever findings are available. - --- ## Artifact Review Flow ``` -brief-writer LLM calls koan_review_artifact({ path: "…/brief.md" }) - → tool reads file content - → tool writes ArtifactReviewIpcFile { type: "artifact-review", response: null } - → tool enters 500ms poll loop (LLM turn blocked) - -ipc-responder detects { type: "artifact-review", response: null } - → calls webServer.requestArtifactReview(payload, signal) - → creates Promise in pendingInputs map - → SSE "artifact-review" event → browser renders ArtifactReview component - → user reads rendered markdown - → clicks "Accept" or types feedback and clicks "Send Feedback" - → POST /api/artifact-review → resolves Promise - → writes ArtifactReviewResponse { feedback } to ipc.json (atomic) - -tool poll detects response !== null - → breaks loop - → deleteIpcFile(dir) - → returns "User feedback:\n{feedback}" to LLM - -if feedback === "Accept": - LLM calls koan_complete_step → phase advances +subagent calls koan_review_artifact({ path: ".../brief.md" }) + -> MCP endpoint checks permissions + -> reads file content from path + -> creates PendingInteraction { type: "artifact-review", future: asyncio.Future() } + -> pushes SSE "artifact-review" event to browsers (with rendered content) + -> awaits Future + +user sees rendered markdown in web UI + -> clicks "Accept" or types feedback and clicks "Send Feedback" + -> POST /api/artifact-review -> resolves Future with feedback string + +MCP handler receives resolved value + -> clears AgentState.pending_tool + -> returns "User feedback:\n{feedback}" as MCP tool result + +if feedback == "Accept": + LLM calls koan_complete_step -> phase advances else: LLM revises artifact, calls koan_review_artifact again - (loop repeats with a fresh IPC request) + (loop repeats with fresh PendingInteraction) ``` -The "Accept" button sends the literal string `"Accept"` as feedback — no -special field or boolean. The LLM reads the feedback string and decides what -to do. See [artifact-review.md § "Accept" Is Verbatim Text](./artifact-review.md). - +See [artifact-review.md](./artifact-review.md) for the full protocol. --- -## Audit Integration - -The audit system (`lib/audit.ts`) runs inside each subagent process and -provides the observability bridge between subagent work and parent/UI polling. - -### Event-sourced design - -- `events.jsonl` — append-only truth (one JSON object per line) -- `state.json` — eagerly materialized projection, written atomically after - every event - -The parent polls `state.json` (cheap file read) instead of parsing the event -log. `fold()` is a pure function so the projection can be rebuilt from the raw -log for testing and crash recovery. - -### Event types +## Sequence Diagrams -| Event | Trigger | Key data | -|-------|---------|----------| -| `phase_start` | `BasePhase.begin()` | totalSteps | -| `step_transition` | `handleStepComplete()` | step number, name, total | -| `tool_call` | pi `tool_call` hook | toolCallId, name, input | -| `tool_result` | pi `tool_result` hook | toolCallId, summarized metrics (not full content) | -| `usage` | pi `turn_end` hook | input/output/cacheRead/cacheWrite tokens | -| `heartbeat` | 10s timer | (keeps `updatedAt` fresh during long tool calls) | -| `phase_end` | phase completion | "completed" | +### Scout flow (blocking interaction) -### Projection fields consumed by parent - -| Field | Consumer | Purpose | -|-------|----------|---------| -| `status` | IPC responder, web server | Scout success, agent completion | -| `step` | Web server | Intake sub-phase derivation | -| `currentToolCallId` | Web server | "doing X" vs "done with X" in UI | -| `completionSummary` | Web server | Scout card summary (incidental 500-char prefix of `thoughts` escape hatch) | -| `tokensSent/Received` | Web server | Token usage display | -| `model` | Web server | Model display | +``` +Driver Scout CLI Web UI + | | | + |<--koan_request_scouts---------| | + | create Future | | + | spawn scout processes------->| | + | |--koan_complete_step->| + | |<-step 1 guidance----| + | | (does work) | + | |--koan_complete_step->| + | |<-"Phase complete."--| + | scout exits | | + | resolve Future | | + |--tool result (findings)------>| | +``` -### Serialization +### User interaction flow (blocking) -`EventLog.append()` calls are serialized via a promise chain. The heartbeat -timer and `tool_result` handler both call `append()` concurrently — without -serialization, two `writeState()` calls race on the shared `.tmp.json` file, -causing ENOENT on rename. +``` +Subagent Driver Web UI + | | | + |--koan_ask_question---------->| | + | | create Future | + | |--SSE "ask" event------>| + | | | user sees form + | | | user submits + | |<-POST /api/answer------| + | | resolve Future | + |<-tool result (answer)--------| | +``` diff --git a/docs/planning-widget.md b/docs/planning-widget.md index a7d40a7..196ac96 100644 --- a/docs/planning-widget.md +++ b/docs/planning-widget.md @@ -1,6 +1,7 @@ # Planning Widget ## Context + The planning widget follows the stacked-card + timeline-rail layout and optimizes for long-running sessions (30-120 minutes). The runtime pane is designed around one principle: @@ -49,6 +50,7 @@ Elapsed time remains right-aligned in the top row. ## Phase-Specific Modifications Panel ### A) Plan design / plan code / plan docs / execution + Show plan-modification counters: - `milestones : +Δ (total)` @@ -57,6 +59,7 @@ Show plan-modification counters: - `changes : +Δ (total)` ### B) QR decompose + Show QR decomposition counters: - `qr items added : +Δ (total)` @@ -64,6 +67,7 @@ Show QR decomposition counters: - `groups assigned : +Δ (total)` ### C) QR verify + Show explicit placeholder (by design): - `[placeholder]` diff --git a/docs/state.md b/docs/state.md index 661bc70..97db0c5 100644 --- a/docs/state.md +++ b/docs/state.md @@ -11,30 +11,26 @@ enforces the file boundary invariant. The driver writes JSON; LLMs write markdown. Tool code bridges both. -| Actor | Reads | Writes | -|-------|-------|--------| -| **Driver** | `.json` state files, exit codes | `.json` state files | -| **LLM** | `.md` files, codebase files | `.md` files (output) | -| **Tool code** | `.json` state (to validate) | `.json` state + `.md` status (both) | +| Actor | Reads | Writes | +| ------------- | ------------------------------- | ----------------------------------- | +| **Driver** | `.json` state files, exit codes | `.json` state files | +| **LLM** | `.md` files, codebase files | `.md` files (output) | +| **Tool code** | `.json` state (to validate) | `.json` state + `.md` status (both) | -### Why state.ts must not write markdown +### Why the epic state module must not write markdown -The state module (`epic/state.ts`) reads and writes JSON only. Putting -`writeStatusMarkdown()` there would make one module responsible for both -communication channels. `status.md` writes belong exclusively in -`tools/orchestrator.ts`, which bridges the two worlds by writing JSON state -(for the driver) and templated markdown (for LLMs) in the same operation. +The epic state module (`koan/epic_state.py`) reads and writes JSON only. +`status.md` writes belong exclusively in orchestrator tool handlers, which +bridge the two worlds by writing JSON state (for the driver) and templated +markdown (for LLMs) in the same operation. ### Filesystem-driven story discovery Story IDs are discovered by scanning `stories/*/story.md`, not by reading a driver-maintained JSON list. The decomposer LLM creates `story.md` files using -the `write` tool — it has no reason to know the JSON state format. Requiring -it to update `epic-state.json` would force an LLM to write JSON, violating the -core invariant. - -The driver discovers what the LLM created by scanning, then populates the JSON -story list itself. +the `write` tool -- it has no reason to know the JSON state format. The driver +discovers what the LLM created by scanning, then populates the JSON story list +itself. --- @@ -43,104 +39,90 @@ story list itself. `epic-state.json` in the epic directory root. Tracks the current pipeline phase and the list of story IDs. -```typescript -interface EpicState { - phase: EpicPhase; // intake → brief-generation → core-flows → tech-plan → ticket-breakdown → cross-artifact-validation → execution → implementation-validation → completed - stories: string[]; // populated by driver after filesystem scan +```python +# koan/epic_state.py +{ + "phase": "intake", # intake -> brief-generation -> core-flows -> tech-plan + # -> ticket-breakdown -> cross-artifact-validation + # -> execution -> implementation-validation -> completed + "stories": [] # populated by driver after filesystem scan } ``` ### Epic phases -| Phase | What happens | -|-------|-------------| -| `intake` | Intake subagent reads conversation, scouts codebase, asks user questions | -| `brief-generation` | Brief-writer subagent distills landscape.md into brief.md; user reviews via artifact review | -| `core-flows` | Define user journeys with sequence diagrams (stub — auto-advances) | -| `tech-plan` | Specify technical architecture (stub — auto-advances) | -| `ticket-breakdown` | Generate story-sized implementation tickets (stub — auto-advances) | -| `cross-artifact-validation` | Validate cross-boundary consistency (stub — auto-advances) | -| `execution` | Implement tickets through supervised batch process (stub — auto-advances) | -| `implementation-validation` | Post-execution alignment review (stub — auto-advances) | -| `completed` | All phases done | - -**`scouting` is intentionally absent.** Scouts run inside the IPC responder -during intake/decomposer/planner phases, not as a top-level phase. Adding it -would imply a driver state that never exists. +| Phase | What happens | +| --------------------------- | ------------------------------------------------------------------------------------------- | +| `intake` | Intake subagent reads conversation, scouts codebase, asks user questions | +| `brief-generation` | Brief-writer subagent distills landscape.md into brief.md; user reviews via artifact review | +| `core-flows` | Define user journeys with sequence diagrams | +| `tech-plan` | Specify technical architecture | +| `ticket-breakdown` | Generate story-sized implementation tickets | +| `cross-artifact-validation` | Validate cross-boundary consistency | +| `execution` | Implement tickets through supervised batch process | +| `implementation-validation` | Post-execution alignment review | +| `completed` | All phases done | + +Additional epic directory files: + +| File | Purpose | +| ------------------------ | -------------------------------------------------- | +| `workflow-decision.json` | Records workflow orchestrator decisions | +| `workflow-status.md` | Human-readable workflow status for LLM consumption | + +**`scouting` is intentionally absent.** Scouts run inside the +`koan_request_scouts` tool handler during intake/decomposer/planner phases, +not as a top-level phase. --- ## Story State -One `state.json` per story in `stories/{storyId}/`. - -```typescript -interface StoryState { - storyId: string; - status: StoryStatus; - retryCount: number; - maxRetries: number; // default: 2 - failureSummary?: string; // set by koan_retry_story - skipReason?: string; // set by koan_skip_story or driver on budget exhaustion - updatedAt: string; +One `state.json` per story in `stories/{story_id}/`. + +```python +{ + "story_id": "auth-middleware", + "status": "pending", + "retry_count": 0, + "max_retries": 2, + "failure_summary": None, # set by koan_retry_story + "skip_reason": None, # set by koan_skip_story or driver + "updated_at": "2026-03-27T..." } ``` ### Story status lifecycle ``` -pending ──→ selected ──→ planning ──→ executing ──→ verifying ──→ done - │ ↑ │ - │ └──────────── retry ←───────────────────┤ - │ │ - └──→ skipped ←───────────────────────────────────────┘ +pending --> selected --> planning --> executing --> verifying --> done + | ^ | + | +------------- retry <------------------+ + | | + +---> skipped <--------------------------------------+ ``` -| Status | Set by | Meaning | -|--------|--------|---------| -| `pending` | Driver (initial) | Story exists, not yet started | -| `selected` | Orchestrator (`koan_select_story`) | Chosen for execution | -| `planning` | Driver | Planner subagent is running | -| `executing` | Driver | Executor subagent is running | -| `verifying` | Driver | Post-execution orchestrator is evaluating | -| `done` | Orchestrator (`koan_complete_story`) | Successfully completed | -| `retry` | Orchestrator (`koan_retry_story`) | Failed, queued for re-execution | -| `skipped` | Orchestrator (`koan_skip_story`) or Driver | Permanently skipped | - -**Driver-internal states** (`planning`, `executing`, `verifying`) are set by -the driver only. The LLM never writes these — it reads them indirectly via -`status.md`. - -**Orchestrator-driven transitions** (`selected`, `done`, `retry`, `skipped`) -are set by orchestrator tool calls. Each tool validates the source status -before transitioning: - -| Tool | Valid source | Target | -|------|-------------|--------| -| `koan_select_story` | `pending`, `retry` | `selected` | -| `koan_complete_story` | `verifying` | `done` | -| `koan_retry_story` | `verifying` | `retry` | -| `koan_skip_story` | `pending`, `retry` | `skipped` | +| Status | Set by | Meaning | +| ----------- | ------------------------------------------ | ----------------------------------------- | +| `pending` | Driver (initial) | Story exists, not yet started | +| `selected` | Orchestrator (`koan_select_story`) | Chosen for execution | +| `planning` | Driver | Planner subagent is running | +| `executing` | Driver | Executor subagent is running | +| `verifying` | Driver | Post-execution orchestrator is evaluating | +| `done` | Orchestrator (`koan_complete_story`) | Successfully completed | +| `retry` | Orchestrator (`koan_retry_story`) | Failed, queued for re-execution | +| `skipped` | Orchestrator (`koan_skip_story`) or Driver | Permanently skipped | ### No `escalated` status -Escalation is handled via `koan_ask_question` — the orchestrator asks the user -a question through IPC, gets an answer, then decides `retry` or `skip`. A -separate `escalated` status was tried and created a dead routing path. +Escalation is handled via `koan_ask_question` -- the orchestrator asks the user +a question through MCP, gets an answer, then decides `retry` or `skip`. ### Retry budget -Each story starts with `maxRetries: 2`. When the driver sees `status: "retry"`, -it increments `retryCount` and re-executes. When `retryCount >= maxRetries`, -the driver sets the story to `skipped`: - -``` -skipReason: "Retry budget exhausted after N attempt(s). Last failure: {failureSummary}" -``` - -The `failureSummary` field flows from `koan_retry_story` (the orchestrator -writes a concrete description of what went wrong) to `retryContext` in the -executor's `task.json` on re-execution. +Each story starts with `max_retries: 2`. When the driver sees `status: "retry"`, +it increments `retry_count` and re-executes. When `retry_count >= max_retries`, +the driver sets the story to `skipped`. --- @@ -148,18 +130,16 @@ executor's `task.json` on re-execution. The driver's story loop is a deterministic state machine: -```typescript -while (true) { - const stories = await loadAllStoryStates(epicDir); - const routing = routeFromState(stories); - - switch (routing.action) { - case "retry": → re-execute story (increment retryCount) - case "execute": → plan + execute story - case "complete": → all stories terminal → exit loop - case "error": → no actionable state → fail - } -} +```python +# koan/driver.py +while True: + stories = load_all_story_states(epic_dir) + routing = route_from_state(stories) + + if routing.action == "retry": # re-execute story + elif routing.action == "execute": # plan + execute story + elif routing.action == "complete": # all stories terminal -> exit loop + elif routing.action == "error": # no actionable state -> fail ``` **Priority:** `retry` is checked before `selected`. A story queued for retry @@ -176,67 +156,62 @@ the driver reports: "orchestrator may have exited without a routing decision." For each story selected for execution: ``` -Driver sets status → planning - → spawn planner subagent - → if planner fails: skip executor, go to post-execution orchestrator -Driver sets status → executing - → spawn executor subagent -Driver sets status → verifying - → spawn orchestrator (post-execution) - → orchestrator decides: koan_complete_story / koan_retry_story / koan_skip_story +Driver sets status -> planning + -> spawn planner subagent + -> if planner fails: skip executor, go to post-execution orchestrator +Driver sets status -> executing + -> spawn executor subagent +Driver sets status -> verifying + -> spawn orchestrator (post-execution) + -> orchestrator decides: koan_complete_story / koan_retry_story / koan_skip_story ``` ### Planner failure fallthrough When the planner exits with non-zero exit code, the driver skips the executor and proceeds directly to the post-execution orchestrator. This gives the -orchestrator a chance to make a routing decision (retry, skip) rather than -leaving the story in a dead state. +orchestrator a chance to make a routing decision. ### Model config gate When a web server is available, the pipeline blocks at startup until the user confirms model tier selection. This happens before any subagent spawns. -### Spec review gate - -The spec review gate was removed as development scaffolding. Story review will -be revisited in the `cross-artifact-validation` phase using a different -mechanism. No web UI review gate exists in the current pipeline. - --- ## Atomic Writes -All state writes use atomic tmp-file + rename: +All state writes use atomic tmp-file + rename via `os.rename()`: -```typescript -async function atomicWriteJson(filePath: string, data: unknown): Promise { - const tmp = `${filePath}.tmp`; - await fs.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", "utf8"); - await fs.rename(tmp, filePath); -} +```python +tmp = f"{file_path}.tmp" +with open(tmp, "w") as f: + json.dump(data, f, indent=2) + f.write("\n") +os.rename(tmp, file_path) ``` This applies to: + - `epic-state.json` (driver) - `stories/{id}/state.json` (driver + orchestrator tools) - `stories/{id}/status.md` (orchestrator tools) - `subagents/{label}/task.json` (driver, before spawn) - `subagents/{label}/state.json` (audit projection) -- `subagents/{label}/ipc.json` (both sides) --- ## Epic Directory Structure ``` -{epicDir}/ +{epic_dir}/ epic-state.json # Epic phase + story list - conversation.jsonl # Exported conversation (input to intake) - landscape.md # Written by intake (task summary, prior art, codebase findings, project conventions, decisions, constraints, open items) + workflow-decision.json # Workflow orchestrator decisions + workflow-status.md # Human-readable workflow status + landscape.md # Written by intake + brief.md # Written by brief-writer stories/ - {storyId}/ + {story_id}/ story.md # Written by decomposer state.json # Story lifecycle state status.md # Templated status for LLM consumption @@ -247,20 +222,19 @@ This applies to: task.json # Task manifest state.json # Audit projection events.jsonl # Audit log - stdout.log, stderr.log decomposer/ ... scout-{id}-{timestamp}/ task.json findings.md # Scout output ... - planner-{storyId}/ + planner-{story_id}/ ... - executor-{storyId}/ + executor-{story_id}/ ... orchestrator-pre/ ... - orchestrator-post-{storyId}/ + orchestrator-post-{story_id}/ ... ``` @@ -268,34 +242,24 @@ This applies to: ## Audit Projection (`state.json`) -Each subagent writes a `state.json` (the "projection") to its directory. The -projection is an eagerly-materialized summary of the subagent's current state, -updated atomically after every audit event. The web server polls it to push -SSE events to the UI without having to replay the full `events.jsonl`. +Each subagent's `state.json` is an eagerly-materialized summary written +atomically after every audit event. It is available on disk for debugging and +post-mortem analysis. Live SSE events are pushed directly from in-process state +transitions. Key projection fields common to all roles: -| Field | Type | Meaning | -|-------|------|---------| -| `phase` | string | Overall phase name (e.g., "intake", "brief-generation") | -| `step` | number | Current step index within the phase | -| `stepName` | string | Human-readable step label (e.g., "Scout (round 2)") | -| `tokensSent` | number | Cumulative tokens in | -| `tokensReceived` | number | Cumulative tokens out | +| Field | Type | Meaning | +| ----------------- | ------ | ------------------------------------------------------- | +| `phase` | string | Overall phase name (e.g., "intake", "brief-generation") | +| `step` | number | Current step index within the phase | +| `step_name` | string | Human-readable step label (e.g., "Scout (round 2)") | +| `tokens_sent` | number | Cumulative tokens in | +| `tokens_received` | number | Cumulative tokens out | Intake-specific fields (zero/null for all other roles): -| Field | Type | Meaning | -|-------|------|---------| -| `intakeConfidence` | `"exploring"\|"low"\|"medium"\|"high"\|"certain"\|null` | Last confidence level declared by `koan_set_confidence`. Null until first declaration; retains last value between loop iterations (not reset in projection on loop-back). | -| `intakeIteration` | number | Current loop iteration (1-based). Updated by `confidence_change` and `iteration_start` events. Zero for non-intake subagents. | - -**Note on `intakeConfidence` and loop-back:** When `getNextStep()` decides to -loop from Reflect (step 4) back to Scout (step 2), it resets -`ctx.intakeConfidence = null` internally. This internal reset is NOT -propagated to the projection immediately — the projection retains the -previous iteration's confidence level until the next `koan_set_confidence` -call emits a `confidence_change` event. The UI therefore shows the last -declared confidence between iterations, which is intentional: it reflects -the most recent authoritative assessment rather than showing a transient -null state. +| Field | Type | Meaning | +| ------------------- | ------------------------------------------------------- | -------------------------------- | +| `intake_confidence` | `"exploring"\|"low"\|"medium"\|"high"\|"certain"\|null` | Last confidence level | +| `intake_iteration` | number | Current loop iteration (1-based) | diff --git a/docs/subagents.md b/docs/subagents.md index a013ce6..664337b 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -8,75 +8,46 @@ How koan spawns, manages, and terminates LLM subagent processes. ## Task Manifest -Every subagent starts as a generic `pi --mode json -p` process with one koan-specific -input: a directory path. The koan extension reads `task.json` from that -directory to learn what kind of subagent it is, what epic it belongs to, and -what work to perform. +Every subagent starts as a CLI process (`claude`, `codex`, or `gemini`) with +MCP config pointing at the driver's HTTP endpoint. The driver reads `task.json` +from the subagent directory to set up the agent's state in the in-process +registry. ### `task.json` schema The manifest is a discriminated union on the `role` field. Common fields -(`role`, `epicDir`) appear on every variant; role-specific fields are nested -naturally rather than flattened into a shared namespace. - -```typescript -// Common to all subagents -interface SubagentTaskBase { - role: SubagentRole; - epicDir: string; -} - -// Role-specific variants -interface IntakeTask extends SubagentTaskBase { - role: "intake"; -} - -interface ScoutTask extends SubagentTaskBase { - role: "scout"; - question: string; // What to investigate - outputFile: string; // Where to write findings (relative to subagentDir) - investigatorRole: string; // Persona for the scout ("security auditor", etc.) -} +(`role`, `epic_dir`, `mcp_url`) appear on every variant; role-specific fields +are nested naturally rather than flattened into a shared namespace. -interface DecomposerTask extends SubagentTaskBase { - role: "decomposer"; -} - -interface OrchestratorTask extends SubagentTaskBase { - role: "orchestrator"; - stepSequence: "pre-execution" | "post-execution"; - storyId?: string; -} - -interface PlannerTask extends SubagentTaskBase { - role: "planner"; - storyId: string; +```json +{ + "role": "intake", + "epic_dir": "/path/to/epic", + "mcp_url": "http://localhost:8420/mcp?agent_id=intake-abc123" } +``` -interface ExecutorTask extends SubagentTaskBase { - role: "executor"; - storyId: string; - retryContext?: string; // Failure summary from previous attempt -} +Role-specific fields: -type SubagentTask = - | IntakeTask - | ScoutTask - | DecomposerTask - | OrchestratorTask - | PlannerTask - | ExecutorTask; -``` +| Role | Additional fields | +| -------------- | -------------------------------------- | +| `intake` | -- | +| `scout` | `output_file`, `investigator_role` | +| `decomposer` | -- | +| `orchestrator` | `step_sequence`, `story_id` (optional) | +| `planner` | `story_id` | +| `executor` | `story_id`, `retry_context` (optional) | ### Lifecycle `task.json` is **write-once, read-once**: -1. Parent calls `ensureSubagentDirectory()` → creates the directory -2. Parent writes `task.json` (atomic: tmp + rename) -3. Parent spawns `pi --mode json -p --koan-dir {subagentDir} ...` -4. Child extension reads `task.json` at startup → dispatches to phase -5. `task.json` is never modified after spawn +1. Driver creates the subagent directory +2. Driver writes `task.json` (atomic: tmp + rename) +3. Driver assigns `agent_id`, registers agent in in-process registry +4. Driver writes MCP config and spawns the CLI process +5. Child connects to `mcp_url`, calls `koan_complete_step` +6. `task.json` is never modified after spawn This makes every subagent directory **self-describing** and **inspectable** after the fact. `cat task.json` shows exactly what the subagent was asked @@ -84,20 +55,14 @@ to do. ### Why not CLI flags -The previous design passed task configuration as 9 CLI flags -(`--koan-role`, `--koan-epic-dir`, `--koan-subagent-dir`, -`--koan-story-id`, `--koan-step-sequence`, `--koan-retry-context`, -`--koan-scout-question`, `--koan-scout-output-file`, `--koan-scout-role`). - -Problems this caused: +The previous design passed task configuration as 9 CLI flags. Problems: -| Problem | Example | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Flat namespace collision** | `--koan-role` (pipeline role: "scout") vs `--koan-scout-role` (investigator persona: "security auditor") — two unrelated concepts sharing a prefix | -| **Unstructured** | Role-specific fields mixed with common fields; `extraFlags: string[]` escape hatch needed for extensibility | -| **Size limits** | `--koan-retry-context` carries multi-paragraph failure summaries — visible in `ps aux`, subject to `ARG_MAX` | -| **Uninspectable** | After a crash, reconstructing what a subagent was asked to do requires parsing process arguments from logs | -| **Inconsistent** | Runtime communication uses files (ipc.json); observation uses files (state.json); but task input used CLI args | +| Problem | Example | +| ---------------------------- | -------------------------------------------------------------------------- | +| **Flat namespace collision** | `--koan-role` vs `--koan-scout-role` -- two unrelated concepts | +| **Unstructured** | Role-specific fields mixed with common fields | +| **Size limits** | `--koan-retry-context` carries multi-paragraph summaries | +| **Uninspectable** | After a crash, reconstructing what was asked requires parsing process args | --- @@ -106,49 +71,35 @@ Problems this caused: ### Parent side ``` -driver: ensureSubagentDirectory(epicDir, label) → subagentDir -driver: write task.json to subagentDir (atomic) -driver: webServer.registerAgent(...) -driver: webServer.trackSubagent(subagentDir, role) -driver: spawnSubagent(task, subagentDir, opts) - → resolves model for role (3-tier: strong/standard/cheap) - → builds CLI args: pi --mode json -p -e ext --koan-dir dir [--model model] "boot prompt" - → spawn("pi", args, { cwd, stdio: ["ignore", "pipe", "pipe"] }) - → captures stdout/stderr to subagentDir/stdout.log, stderr.log - → parses stdout JSONL for text_delta events → forwards deltas to web server SSE - → starts IPC responder concurrently (if webServer available) - → waits for proc.on("close") - → aborts IPC responder - → returns { exitCode, stderr, subagentDir } -driver: webServer.clearSubagent() -driver: webServer.completeAgent(id) -driver: checks exitCode, routes to next phase +driver: mkdir subagent_dir +driver: write task.json to subagent_dir (atomic) +driver: assign agent_id, register in agent registry + -> init step engine, permissions, event log from task.json +driver: write MCP config (runner-specific): + claude: mcp-config.json + codex: -c runtime override + gemini: .gemini/settings.json in cwd +driver: spawn_subagent(task, subagent_dir, runner) + -> runner.build_command(boot_prompt, mcp_url, model, cwd) + -> subprocess.Popen(cmd, cwd=cwd, stdout=PIPE, stderr=PIPE) + -> parse stdout line-by-line for streaming events + -> wait for process exit +driver: deregister agent_id +driver: check exit code, route to next phase ``` ### Child side ``` -pi --mode json -p starts with koan extension -koan.ts init: - → registers --koan-dir flag - → creates RuntimeContext { epicDir: null, subagentDir: null, onCompleteStep: null } - → registerAllTools(pi, ctx) — all tools, unconditionally - -before_agent_start fires (after _buildRuntime snapshot): - → reads --koan-dir flag - → reads task.json from dir → SubagentTask (typed, validated) - → sets ctx.epicDir = task.epicDir, ctx.subagentDir = dir - → opens EventLog (audit trail) - → wires pi event hooks (tool_call, tool_result, turn_end, session_shutdown) - → dispatchPhase(pi, task, ctx): - → matches task.role → instantiates phase class → phase.begin() - -phase.begin(): - → step = 0, active = true - → ctx.onCompleteStep = handleStepComplete +CLI process starts (claude/codex/gemini) + -> connects to MCP endpoint at mcp_url + -> discovers available tools via MCP LLM receives boot prompt: "You are a koan {role} agent. Call koan_complete_step to receive your instructions." + -> LLM calls koan_complete_step via MCP + -> MCP endpoint looks up agent_id, advances step 0 -> 1 + -> returns step 1 guidance as tool result ``` ### Boot prompt @@ -157,116 +108,88 @@ LLM receives boot prompt: "You are a koan {role} agent. Call koan_complete_step to receive your instructions." ``` -One sentence. No task content. The role name is included for primacy — it +One sentence. No task content. The role name is included for primacy -- it anchors the LLM's identity before it receives any instructions. Task-specific -parameters live in `task.json` and flow into step guidance via the phase class. +parameters live in `task.json` and flow into step guidance via the phase module. ### Fail-fast guards (bootstrap invariants only) -`dispatchPhase` validates required `task.json` fields before instantiating: +The MCP endpoint validates required `task.json` fields at agent registration: -| Role | Required fields | Failure if missing | -| -------- | ------------------------ | --------------------------------------------------------------------- | -| scout | `question`, `outputFile` | Step 1 guidance has no assignment → LLM outputs confused text → exits | -| planner | `storyId` | Malformed paths like `stories//plan/plan.md` | -| executor | `storyId` | Same path issue | +| Role | Required fields | Failure if missing | +| -------- | --------------- | ----------------------------------------------------------------------- | +| scout | `output_file` | Step 1 guidance has no assignment -> LLM outputs confused text -> exits | +| planner | `story_id` | Malformed paths like `stories//plan/plan.md` | +| executor | `story_id` | Same path issue | These checks are intentionally fail-fast because they indicate a broken -parent→child contract (programming/configuration error), not model behavior. - -**Boundary:** fail-fast is for unrecoverable conditions only (invariant or -contract violations, unexpected states, or cases with no simple deterministic -local recovery path). Recoverable model-output errors (for example malformed -tool-call JSON/args or schema validation failures) should be surfaced as -normal tool errors (`tool_result` with `isError=true`) so the LLM can retry -in-process, rather than terminating the subagent process. +parent->child contract (programming/configuration error), not model behavior. --- -## Step-First Workflow (BasePhase) - -`BasePhase` is the abstract superclass for all phase classes. It manages: +## Step-First Workflow -- **Step counter** — starts at 0 (boot state), increments monotonically -- **System prompt injection** — via `before_agent_start` event handler -- **Permission fence** — via `tool_call` event handler (default-deny) -- **Step transition** — via `handleStepComplete()` callback +Phase modules in `koan/phases/` define step guidance, system prompts, and +hooks for non-linear flows. The step engine in `koan/web/mcp_endpoint.py` +manages the step counter and dispatches to phase module functions. -Class hierarchy: +Phase modules: ``` -BasePhase -├── ReviewablePhase (abstract) -│ ├── IntakePhase -│ └── BriefWriterPhase -├── ScoutPhase -├── DecomposerPhase -├── OrchestratorPhase -├── PlannerPhase -└── ExecutorPhase +koan/phases/ + intake.py + brief_writer.py + scout.py + orchestrator.py + planner.py + executor.py + core_flows.py + tech_plan.py + ticket_breakdown.py + cross_artifact_validation.py + workflow_orchestrator.py ``` -**`ReviewablePhase`** is an abstract subclass of `BasePhase` used by phases that -require artifact review acceptance before advancing. It owns the -`koan_review_artifact` listener registration, the `lastReviewAccepted` gate -state, and a `validateStepCompletion` override that enforces the gate. -`IntakePhase` and `BriefWriterPhase` extend `ReviewablePhase`; the remaining -five phases extend `BasePhase` directly. +Each phase module exposes: + +| Symbol | Kind | Purpose | Default | +| --------------------------------------- | -------- | ------------------------------------ | ----------------------------------- | +| `SYSTEM_PROMPT` | constant | Role identity and rules | Required | +| `step_guidance(step, ctx)` | function | Return step instructions | Required | +| `get_next_step(step, ctx)` | function | Next step or None (done) | Linear: step+1, None at total_steps | +| `validate_step_completion(step, ctx)` | function | Pre-condition check before advancing | None (always allow) | +| `on_loop_back(from_step, to_step, ctx)` | function | Side effects of backward transitions | no-op | ### Step progression state machine ``` -begin() → step=0, active=true, arms ctx.onCompleteStep - -LLM calls koan_complete_step: - step == 0 → step=1, return formatStep(getStepGuidance(1)) [boot transition] - otherwise → validateStepCompletion(step) [pre-condition check] - → nextStep = getNextStep(step) [pure: decides where to go] - nextStep == null → active=false, return null → "Phase complete." [done] - nextStep < prev → onLoopBack(prev, nextStep) [side effects of loop] - nextStep != null → onStepUpdated(nextStep) [sync ctx fields] - → step=nextStep, return formatStep(getStepGuidance(nextStep)) [advance] +koan_complete_step arrives via MCP: + step == 0 -> step=1, return format_step(step_guidance(1)) [boot transition] + otherwise -> validate_step_completion(step) [pre-condition check] + -> next_step = get_next_step(step) [pure: decides where to go] + next_step is None -> return "Phase complete." [done] + next_step < prev -> on_loop_back(prev, next_step) [side effects of loop] + next_step != None -> step=next_step, return format_step(step_guidance(next_step)) [advance] ``` -`BasePhase` provides three overridable hooks for non-linear flows: - -| Hook | Purpose | Default | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | -| `getNextStep(step)` | Returns next step number or null (done). **Must be pure.** | Linear: step+1, null at totalSteps | -| `onLoopBack(from, to)` | Side effects of backward transitions: state resets, counter increments, event emission. Async — properly awaited. | no-op | -| `validateStepCompletion(step)` | Pre-condition check before advancing. Returns null to allow or an error string to block (returned as tool result so LLM can fix it). | null (always allow) | - -`IntakePhase` overrides all three to implement a confidence-gated loop over -steps 2–4. See [intake-loop.md](./intake-loop.md) for details. - -Key invariants: - -- **`getNextStep()` is pure** — it only returns a step number. Mutation belongs in `onLoopBack()`. -- **`step_transition` is NOT emitted at `begin()`** — it fires when step 1 - guidance is first returned, so the event log reflects when the LLM actually - begins work. -- **`ctx.onCompleteStep` is nulled on completion** — prevents stale callbacks. -- **Only one phase per RuntimeContext** — `begin()` throws if `ctx.onCompleteStep` - is already occupied. - ### System prompt vs task content -The system prompt (injected via `before_agent_start`) establishes **role -identity and rules** — who you are, what you must/must not do, what output -files you produce, what tools you have. It deliberately omits task details. +The system prompt establishes **role identity and rules** -- who you are, what +you must/must not do, what output files you produce, what tools you have. It +deliberately omits task details. -Task details arrive as **step guidance** — the return value of -`koan_complete_step` — after the LLM has already established the tool-calling +Task details arrive as **step guidance** -- the return value of +`koan_complete_step` -- after the LLM has already established the tool-calling pattern. This separation is load-bearing (see [architecture pitfalls](./architecture.md#pitfalls)). -### formatStep structure +### format_step structure Every step guidance string has the same structure: ``` {title} -{"=".repeat(title.length)} +{"=".repeat(len(title))} {instructions} @@ -274,55 +197,31 @@ WHEN DONE: Call koan_complete_step to advance to the next step. Do NOT call this tool until the work described in this step is finished. ``` -The invoke-after directive is always **last** (recency reinforcement). Steps -that need the LLM to call a domain tool before `koan_complete_step` (e.g., -`koan_select_story`) can override `invokeAfter`. +The invoke-after directive is always **last** (recency reinforcement). -### The `thoughts` parameter — escape hatch, not data channel +### The `thoughts` parameter -- escape hatch, not data channel `thoughts` on `koan_complete_step` is an **escape hatch** for models that cannot produce both text output and a tool call in the same response. -**Why it exists:** Many of our workflows instruct the LLM to "write down a -list of X items and evaluate each one-by-one," use chain-of-draft reasoning, -or work through multi-step analysis. These patterns work best when the LLM has -a place to write intermediate reasoning. Models that can mix text + tool_call -do this naturally in their text output. Models that can't (e.g., GPT-5-codex) -would be stuck: they need to call `koan_complete_step` to advance, but calling -a tool means they can't produce text. The `thoughts` parameter gives them -somewhere to put their working. - -Extended thinking / `` blocks are not sufficient: not all models -support them, they are not visible in audit logs, and some reasoning patterns -work better as explicit text the model can reference in subsequent turns. - **The invariant:** `thoughts` must **NEVER** be actively used to capture task output. No summaries, no reports, no structured data extraction. -- ❌ "Call koan_complete_step with your analysis in the `thoughts` parameter" -- ❌ "Report your findings in the `thoughts` parameter" -- ✅ "Call koan_complete_step to advance to the next step" -- ✅ (LLM fills `thoughts` with whatever it wants — that's fine) - Task output goes to files (`findings.md`, `landscape.md`, `plan.md`, etc.). The driver/parent reads those files after the subagent exits. -A 500-char prefix of `thoughts` is captured in the audit projection as -`completionSummary` for UI display — this is incidental, not a contract. - --- ## Permissions -Default-deny, role-based, enforced at runtime via the `tool_call` event handler -in `BasePhase`. +Default-deny, role-based, enforced at runtime via `check_permission()` in +`koan/lib/permissions.py`. ### READ_TOOLS (always allowed) -`bash`, `read`, `grep`, `glob`, `find`, `ls` — allowed for all roles. This is +`bash`, `read`, `grep`, `glob`, `find`, `ls` -- allowed for all roles. This is an accepted limitation: `bash` can write files, but distinguishing read-bash -from write-bash is intractable at the permission layer. Prompt engineering -constrains intended use; enforcement does not. +from write-bash is intractable at the permission layer. ### Role permission matrix @@ -330,9 +229,9 @@ constrains intended use; enforcement does not. | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------ | | **intake** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `koan_set_confidence` | path-scoped to epicDir | `koan_set_confidence` blocked in step 1 (Extract) | | **scout** | `koan_complete_step` | path-scoped to epicDir | No `koan_ask_question` (no user interaction). No `koan_request_scouts` (no nested scouts). | -| **decomposer** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | — | -| **orchestrator** | `koan_complete_step`, `koan_ask_question`, `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | path-scoped to epicDir | No `koan_request_scouts` — orchestrator uses bash for verification | -| **planner** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | — | +| **decomposer** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | -- | +| **orchestrator** | `koan_complete_step`, `koan_ask_question`, `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | path-scoped to epicDir | No `koan_request_scouts` -- orchestrator uses bash for verification | +| **planner** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | -- | | **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | ### Path scoping @@ -340,8 +239,7 @@ constrains intended use; enforcement does not. Planning roles (intake, scout, decomposer, orchestrator, planner) can only `write`/`edit` files inside the epic directory. The permission check resolves both the tool's `path` argument and the epic directory, then verifies the tool -path starts with the epic path. If `epicDir` or the path argument is missing, -the write is allowed (cannot scope-check without context). +path starts with the epic path. --- @@ -349,23 +247,21 @@ the write is allowed (cannot scope-check without context). ### Why 3 tiers instead of per-role configuration -Koan has 6 roles, but they cluster into 3 capability bands. Configuring 3 -model names is simpler than 6 and matches the natural grouping: +Koan has 6+ roles, but they cluster into 3 capability bands: -| Tier | Roles | Why this tier | -| ------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **strong** | intake, decomposer, orchestrator, planner | Complex multi-step reasoning: investigating ambiguous requirements, splitting work into stories, verifying correctness, producing precise implementation plans | -| **standard** | executor | Code implementation: reliable tool use and file editing without requiring the deepest reasoning | -| **cheap** | scout | Narrow codebase investigation: reading files, grepping patterns, writing a focused findings report — no deep reasoning needed | +| Tier | Roles | Why this tier | +| ------------ | ----------------------------------------- | ---------------------------------------------------------------- | +| **strong** | intake, decomposer, orchestrator, planner | Complex multi-step reasoning | +| **standard** | executor | Code implementation: reliable tool use without deepest reasoning | +| **cheap** | scout | Narrow codebase investigation: reading files, writing findings | -The mapping is hardcoded in `types.ts` (`ROLE_MODEL_TIER`). Adding a new role -requires updating that map. +The mapping is defined in `koan/config.py`. Adding a new role requires +updating that map. ### Configuration -Model tiers are configured via the web UI at pipeline start (the **model config -gate** fires before any subagent spawns). The user selects one model per tier. -Config is persisted to `~/.koan/config.json` under the `modelTiers` key: +Model tiers are configured via the web UI at pipeline start. Config is +persisted to `~/.koan/config.json`: ```json { @@ -378,21 +274,11 @@ Config is persisted to `~/.koan/config.json` under the `modelTiers` key: } ``` -If no config exists or the config is partial, `resolveModelForRole` returns -`undefined` and the `--model` flag is omitted — pi's current active model -becomes the implicit fallback for all roles. - -Config is **all-or-nothing**: all 3 tiers must be present. Partial configs -are treated as absent and logged. This prevents a half-configured state where -some roles use intended models and others silently fall back. - ### Scout concurrency `scoutConcurrency` (default: 4) controls how many scout subagents run in -parallel via the bounded pool (`lib/pool.ts`). The pool uses an in-process -semaphore: all scout tasks are submitted to `Promise.all` simultaneously; the -semaphore gates actual execution. Increase this for faster scouting on machines -with ample resources; decrease it to reduce peak memory pressure. +parallel. Increase for faster scouting on machines with ample resources; +decrease to reduce peak memory pressure. --- @@ -400,19 +286,17 @@ with ample resources; decrease it to reduce peak memory pressure. Scouts are deliberately constrained compared to other roles: -- **No web server handle** — scouts cannot interact with the user or the UI -- **No `koan_ask_question`** — scouts do not ask questions -- **No `koan_request_scouts`** — scouts do not spawn nested scouts -- **No IPC responder** — since there is no web server, no IPC responder runs -- **Three steps** — scouts have `totalSteps = 3` (investigate → verify → report). Each step has exactly one cognitive goal, following the "don't give a step multiple cognitive goals" principle from [architecture.md Pitfalls](./architecture.md#pitfalls). The original 4-step design separated "orient" (find files) from "investigate" (read files), but this was an artificial split that wasted a full round trip — finding entry points and reading them is one cognitive activity -- **Cheap model** — scouts use the cheapest available model -- **Parallel execution** — up to 4 scouts run concurrently via bounded pool -- **Non-fatal failures** — a failed scout does not abort the parent; its task - ID is reported in the `failures` array and the LLM is told to proceed +- **No `koan_ask_question`** -- scouts do not ask questions +- **No `koan_request_scouts`** -- scouts do not spawn nested scouts +- **Three steps** -- investigate -> verify -> report +- **Cheap model** -- scouts use the cheapest available model +- **Parallel execution** -- up to 4 scouts run concurrently +- **Non-fatal failures** -- a failed scout does not abort the parent; its task + ID is reported in the `failures` array -Scout task parameters (`question`, `outputFile`, `investigatorRole`) live in -the scout's `task.json`. The boot prompt stays minimal; `ScoutPhase` reads the -task manifest and injects the parameters into step 1 guidance. +Scout task parameters (`output_file`, `investigator_role`) live in the scout's +`task.json`. The boot prompt stays minimal; step 1 guidance injects the +parameters. --- @@ -421,65 +305,49 @@ task manifest and injects the parameters into step 1 guidance. After a subagent runs, its directory contains: ``` -{subagentDir}/ +{subagent_dir}/ task.json # Input: what to do (written by parent before spawn) - state.json # Output: audit projection (written by child, polled by parent) + state.json # Output: audit projection (written by driver) events.jsonl # Output: append-only audit log - ipc.json # Transient: runtime communication (created/deleted per request) - stdout.log # JSONL event stream from pi --mode json -p (structured, not raw text) - stderr.log # Captured stderr from pi process findings.md # Task output (scouts) - landscape.md # Task output (intake — task summary, prior art, codebase findings, project conventions, decisions, constraints, open items) + landscape.md # Task output (intake) ``` -The three JSON files have distinct lifecycles per -[architecture.md § Directory-as-contract](./architecture.md#6-directory-as-contract): +The JSON files have distinct lifecycles per +[architecture.md -- Directory-as-contract](./architecture.md#6-directory-as-contract): -| File | Writer | Reader | When | -| ------------ | ------ | ------ | ---------------------------------------- | -| `task.json` | Parent | Child | Once at startup | -| `state.json` | Child | Parent | Continuous (50ms polling) | -| `ipc.json` | Both | Both | Per-request (created, answered, deleted) | +| File | Writer | Reader | When | +| ------------ | ------ | ------ | -------------------------- | +| `task.json` | Parent | Parent | Once at agent registration | +| `state.json` | Parent | Debug | Continuous (after events) | --- ## Web Server Integration -The parent registers each subagent with the web server for UI tracking: - -```typescript -webServer.registerAgent({ id, name, dir, role, model, parent }); -// → starts 50ms polling of audit projection + recent logs -// → SSE "agents" event to browser - -webServer.trackSubagent(dir, role, storyId?); -// → starts 50ms polling for "subagent" + "logs" SSE events - -// ... subagent runs ... - -webServer.clearSubagent(); -// → stops tracking timer, emits SSE "subagent-idle" +The driver pushes SSE events directly from in-process state transitions. When +a tool call arrives via MCP, the handler emits audit events and pushes SSE +updates to connected browsers in the same call chain. -webServer.completeAgent(id); -// → stops polling, final readProjection, emits SSE "agents" with terminal status ``` +tool call arrives via MCP + -> handler processes call + -> emits audit event -> fold -> state.json + -> pushes SSE event to browsers + -> returns tool result to subagent +``` + +Agent registration and deregistration are tracked in the in-process +`AgentState` registry. SSE events for agent lifecycle (`agent-start`, +`agent-complete`) are pushed when agents are registered/deregistered. -**Dual polling for intake agent:** Both `registerAgent()` and -`trackSubagent()` poll at 50ms. `registerAgent` polling derives the intake -sub-phase for the progress bar: +Intake sub-phase derivation happens server-side based on step number: | Step | Pending ask? | Sub-phase | | ---- | ------------ | -------------- | -| 1 | — | `"extract"` | -| 2 | — | `"scout"` | +| 1 | -- | `"extract"` | +| 2 | -- | `"scout"` | | 3 | yes | `"questions"` | | 3 | no | `"deliberate"` | -| 4 | — | `"reflect"` | -| 5 | — | `"synthesize"` | - -Steps 2–4 repeat across iterations; the server additionally reads -`intakeConfidence` and `intakeIteration` from the audit projection to populate -the `intake-progress` SSE event for UI visualization. - -This derivation is server-side — the server maps step numbers to sub-phase -names. The LLM does not report its sub-phase. +| 4 | -- | `"reflect"` | +| 5 | -- | `"synthesize"` | diff --git a/docs/token-streaming.md b/docs/token-streaming.md index be8793f..988e738 100644 --- a/docs/token-streaming.md +++ b/docs/token-streaming.md @@ -9,104 +9,51 @@ realtime. ## Overview -Koan receives incremental token output from subagent `pi` processes by parsing -the JSONL stream on their stdout. Token deltas flow directly to connected -browsers via SSE — bypassing the audit system and the file-based IPC protocol -entirely. +Koan receives incremental token output from subagent CLI processes by parsing +their stdout line-by-line via `runner.parse_stream_event(line)` in +`koan/subagent.py`. The runner normalizes provider-specific formats into +`StreamEvent` objects. Token deltas flow directly to connected browsers via +SSE -- bypassing the audit system entirely. -**Design invariant:** Token streaming flows through stdout JSONL parsing, not -through the extension event system or file-based IPC. +**Design invariant:** Token streaming flows through runner stdout parsing, not +through the audit pipeline or file-based communication. --- -## Pi's Streaming Architecture +## Runner Streaming Differences -Pi exposes a three-layer streaming pipeline: +Each runner implementation parses its CLI's stdout format differently: -``` -Provider stream (HTTP chunked response from the LLM API) - ↓ -Agent layer (assembles chunks into messages, emits typed session events) - ↓ -Session output (--mode json → JSONL on stdout; default → human-readable text) -``` - -The transition from provider chunks to typed session events happens inside pi. -Koan does not intercept provider chunks. It hooks into the **session output -layer** by launching pi with `--mode json -p`. - -### `--mode json` and `-p` compose - -- `-p` (non-interactive / print mode): pi runs to completion and exits without - waiting for stdin. This is koan's spawn mode. -- `--mode json`: instead of printing human-readable text, pi emits every - session event as a JSONL line on stdout. +| Runner | Stdout format | Streaming behavior | Source | +| ------------------------------------- | ------------------------------------------- | ---------------------------------------------- | --------------------------------------------------- | +| **Claude** (`koan/runners/claude.py`) | Stream JSON (`--output-format stream-json`) | Incremental token deltas | `text_delta` events in JSONL stream | +| **Gemini** (`koan/runners/gemini.py`) | Provider-specific JSON | Incremental token deltas | Parsed from Gemini CLI output | +| **Codex** (`koan/runners/codex.py`) | Turn-level completion events | No incremental deltas; "thinking..." indicator | Codex emits completed turns, not token-level events | -The two flags compose cleanly. Pi's own subagent extension -(`examples/extensions/subagent/index.ts`) uses the identical combination — -`["--mode", "json", "-p"]` — confirming this is the supported integration -surface for external processes that spawn pi as a subprocess. - -### Session event types on stdout - -With `--mode json`, each stdout line is a JSON object with a `type` field. -Relevant event types for token streaming: - -| Event type | When emitted | Relevant subfield | -|---|---|---| -| `message_update` | Each streamed token during generation | `assistantMessageEvent.type === "text_delta"` | -| `message_update` | Other message lifecycle events | `assistantMessageEvent.type` is not `text_delta` | -| `tool_execution_update` | Tool call lifecycle | — (not used for streaming) | -| `turn_end` | LLM turn finished | — | -| others | Compaction, session events, etc. | — | - -Only `message_update` events where `assistantMessageEvent.type === "text_delta"` -carry new tokens. All other event types are discarded by the token streaming -parser. The existing `state.json` polling path handles tool-call-level status. +All runners implement `parse_stream_event(line) -> StreamEvent | None`. The +method returns a `StreamEvent` with a `delta` string for display, or `None` to +skip the line. The caller (`spawn_subagent()` in `koan/subagent.py`) handles +all events uniformly. --- -## Stdout JSONL Parser - -The parser runs inside `spawnSubagent()` in `src/planner/subagent.ts`, -alongside the existing `stdoutLog.write(data)` call. +## Stdout Line-Buffer Pattern -### Why preserve the log file - -The log file write happens before any parsing. `--mode json` changes the -format of stdout (text → JSONL), but the log file still captures the complete -raw output for post-mortem debugging. The parser is an additional consumer of -the same bytes; it does not replace or modify the log path. - -### Line-buffer pattern - -Node.js `"data"` events do not respect line boundaries — a single event may -contain multiple complete lines, a partial line, or both. The parser maintains -a `buffer` string across events: +The subagent process's stdout is read line-by-line. Each complete line is +passed to `runner.parse_stream_event(line)`. A line buffer handles the case +where stdout data arrives split across multiple read calls: ``` buffer += incoming bytes lines = buffer.split("\n") -buffer = lines.pop() ← keep trailing partial line for next event -process lines[0..n-2] ← only complete lines +buffer = lines[-1] # keep trailing partial line for next read +process lines[0:-1] # only complete lines ``` -The trailing partial line **must** be kept in `buffer`. Parsing it prematurely -would produce a JSON parse error and silently drop the event. - -On process close, the buffer is flushed in case the process exited mid-line -(e.g., SIGKILL). Under normal operation the buffer is empty at close. The -flush is merged into the existing `proc.on("close")` handler, before -`resolve()`, so any final delta arrives before the driver calls -`clearSubagent()` → `pushEvent("subagent-idle")`. - -### Why filter to `text_delta` only +The trailing partial line **must** be kept in the buffer. Parsing it +prematurely would produce a parse error and silently drop the event. -`--mode json` is verbose — it emits events for every tool execution, turn -boundary, and compaction cycle. Forwarding all events to SSE clients would -add noise and bandwidth with no UI benefit. Tool execution status is already -tracked via the audit projection (`state.json` polling → `agents` SSE event). -Only `text_delta` events carry information the streaming display needs. +On process exit, the buffer is flushed in case the process exited mid-line. --- @@ -114,120 +61,47 @@ Only `text_delta` events carry information the streaming display needs. Koan has two data paths from subagents to the browser: -1. **Audit pipeline** — durable, tool-call-level, polled via `state.json`. Use - for state that must survive restarts, participate in `fold()`, and be - replayed in full on reconnect. -2. **Stdout pipeline** — ephemeral, token-level, pushed directly to SSE. Use +1. **Audit pipeline** -- durable, tool-call-level. Use for state that must + survive restarts, participate in `fold()`, and be replayed on reconnect. +2. **Stdout pipeline** -- ephemeral, token-level, pushed directly to SSE. Use for high-frequency display data with no persistence value. -Token streaming uses the stdout pipeline. Token deltas flow from the parser -directly to SSE clients without touching the audit system or IPC files: +Token streaming uses the stdout pipeline: ``` -pi stdout → JSONL parser → pushTokenDelta(delta) → pushEvent("token-delta", { delta }) → SSE stream +CLI stdout -> line parser -> runner.parse_stream_event(line) + -> StreamEvent with delta + -> push SSE "token-delta" event to connected browsers ``` -This path bypasses the standard five-layer audit pipeline -([architecture.md § SSE Event Lifecycle](./architecture.md#sse-event-lifecycle)) -intentionally. Going through the audit system would require: - -- Appending a new event type to `events.jsonl` per token (hundreds per second) -- Running `fold()` per token to update `state.json` -- Polling `state.json` at 50ms and detecting changes - -That is appropriate for durable, tool-call-level state. For ephemeral token -deltas — which are cleared when the subagent finishes — direct SSE push is -correct. - -### `pushTokenDelta` is parameterless - -`WebServerHandle.pushTokenDelta(delta)` takes only the delta string. There is -no `subagentDir` or `agentId` parameter because only one subagent is tracked -at a time (`trackSubagent()` / `clearSubagent()`). The server always knows -which subagent is active; no disambiguation is needed. +This path bypasses the audit pipeline intentionally. Going through audit would +require appending events to `events.jsonl` and running `fold()` per token -- +hundreds of cycles per second for ephemeral display data. ### Replay on reconnect -The web server maintains a `streamingText` string variable alongside the other -replay state (`currentPhase`, `currentSubagent`, etc.). - -**Lifecycle:** - -1. `trackSubagent()` — reset `streamingText = ""` -2. `pushTokenDelta(delta)` — append `streamingText += delta`, then `pushEvent()` -3. `replayState(res)` — if `streamingText` is non-empty, write a single - `token-delta` event containing the full accumulated string. The frontend's - `handleTokenDeltaEvent` handles this transparently — it accumulates from - zero after each clear, so receiving the full text as one delta produces the - correct state. -4. `clearSubagent()` — reset `streamingText = ""` - -Without server-side accumulation, a client that reconnects mid-stream would -see an empty streaming area with no error signal — a silent failure that only -surfaces during network interruptions. +The web server maintains accumulated streaming text. On browser reconnect, +a single `token-delta` event containing the full accumulated text is sent. +When the subagent completes, the accumulated text is cleared. --- ## Frontend -### Store (`src/planner/web/js/store.js`) - -`streamingText` is a plain string in the Zustand store, initialized to `""`. - -``` -streamingText: "" -``` - -Two handlers operate on it: - -- **`handleTokenDeltaEvent(d)`** — appended on each `token-delta` SSE event: - `set(s => ({ streamingText: s.streamingText + d.delta }))` +The frontend (`koan/web/static/js/koan.js`) receives SSE `token-delta` events +and appends the delta text to the streaming display area. The HTMX SSE +integration handles connection and reconnection. -- **`handleSubagentIdleEvent()`** — resets `streamingText: ""` alongside - `subagent: null`. Clearing is done inside the idle handler rather than as a - separate `token-delta` teardown because `subagent-idle` is the canonical - signal that the active subagent has finished; consolidating the reset here - avoids a second SSE handler registration in `sse.js` and keeps all - subagent-end side-effects in one place. - -### SSE dispatch (`src/planner/web/js/sse.js`) - -``` -'token-delta' → handleTokenDeltaEvent -'subagent-idle' → handleSubagentIdleEvent (also clears streamingText) -``` - -The frontend accumulates deltas; the server sends only the new tokens each -event. Accumulation on the client matches the provider stream's own framing -and avoids growing SSE payload sizes as text grows. - -### Component (`src/planner/web/js/components/ActivityFeed.jsx`) - -Streamed tokens render inline inside the in-flight `ThinkingCard`. While -`isInFlight && streamingText`, the card's `body` is overridden with -`streamingText` and the card auto-expands. A blinking cursor element -(`.streaming-cursor`) marks the insertion point. When the turn completes, -the official thinking text from `events.jsonl` replaces the streamed version -via the normal audit poll path. +Server-rendered HTML fragments from `koan/web/templates/` provide the +structural layout. The JavaScript in `koan.js` handles only the incremental +text accumulation for streaming display. --- ## What Is Not Streamed -| Signal | Why excluded | -|---|---| -| Thinking blocks (`thinking_delta`) | Not visible to users in current UI; same mechanism could add them later | -| Tool execution updates | Handled by `state.json` polling → `agents` SSE event | -| Scout output | Scouts have no `WebServerHandle`; they are not tracked by `trackSubagent` | - ---- - -## Alternatives Considered - -| Alternative | Reason rejected | -|---|---| -| Extension `message_update` hook + file append | File I/O per token; requires polling; adds new file to directory-as-contract | -| Extension + HTTP POST per token | Port must be passed to extension; HTTP overhead per token | -| RPC mode (`--mode rpc`) | Requires bidirectional stdin/stdout; `stdin` is `"ignore"` in koan | -| Tail `stdout.log` in `-p` mode | Raw text — cannot distinguish token deltas from tool output | -| SDK embedding (`createAgentSession`) | Destroys process isolation (core architectural invariant) | +| Signal | Why excluded | +| ---------------------- | ------------------------------------------------------------- | +| Thinking blocks | Not visible to users in current UI | +| Tool execution updates | Handled by audit projection -> SSE events | +| Scout output | Scouts push their own audit events; no token streaming needed | diff --git a/extensions/koan.ts b/extensions/koan.ts deleted file mode 100644 index 162c08f..0000000 --- a/extensions/koan.ts +++ /dev/null @@ -1,242 +0,0 @@ -// Entry point for the koan pi extension. Serves dual roles: -// -// Parent session mode — registers the koan_plan tool and /koan commands. -// Subagent mode — reads task.json from --koan-dir, dispatches to -// the appropriate phase workflow. -// -// All tools register unconditionally at init; phases restrict access at -// runtime via the tool_call permission fence in BasePhase. -// -// RuntimeContext is a mutable carrier set once during before_agent_start. -// Tools register at init (before flags are available) and read ctx at -// call time — the mutable-ref pattern decouples static registration from -// dynamic phase routing. - -import * as path from "node:path"; -import { Type } from "@sinclair/typebox"; -import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"; - -import { dispatchPhase } from "../src/planner/phases/dispatch.js"; -import { KOAN_DEBUG_FLAG } from "../src/planner/lib/constants.js"; -import { registerAllTools, createRuntimeContext } from "../src/planner/tools/index.js"; -import { createLogger, setLogDir } from "../src/utils/logger.js"; -import { EventLog, extractToolCall, extractToolResult } from "../src/planner/lib/audit.js"; -import { readTaskFile } from "../src/planner/lib/task.js"; -import { openKoanConfig } from "../src/planner/ui/config/menu.js"; -import { createEpicDirectory } from "../src/planner/epic/state.js"; -import { exportConversation } from "../src/planner/conversation.js"; -import { runPipeline } from "../src/planner/driver.js"; -import { startWebServer, openBrowser } from "../src/planner/web/server.js"; -import { registerTruncationOverride } from "../src/planner/lib/truncation-override.js"; - -function currentModelId(ctx: ExtensionContext): string | null { - const model = ctx.model; - if (!model) return null; - return `${model.provider}/${model.id}`; -} - -/** - * Registers infrastructure-level event handlers that must be in place before - * `before_agent_start` fires. - * - * **Ordering contract:** call immediately after `registerAllTools` and before - * the `before_agent_start` dispatch guard. The audit system's `tool_result` - * handler is registered inside `before_agent_start`; the truncation override - * installed here must precede it so the audit handler observes the original - * event rather than the replacement content we return. Placing this call - * structurally before `before_agent_start` makes the constraint positional - * rather than implicit. - */ -function registerInfrastructureHandlers(pi: ExtensionAPI): void { - registerTruncationOverride(pi); -} - -export default function koan(pi: ExtensionAPI): void { - const log = createLogger("Koan"); - - // Single flag: the subagent directory path. The child reads task.json from - // this directory to discover its role and task parameters — no structured - // data flows through CLI flags. - pi.registerFlag("koan-dir", { - description: "Subagent working directory (internal — set by parent before spawn)", - type: "string", - default: "", - }); - - pi.registerFlag("koan-webserver-port", { - description: "Fixed port for the koan web server (default: random)", - type: "string", - default: "", - }); - - pi.registerFlag("koan-webserver-token", { - description: "Fixed session token (UUID) for the koan web server (default: random)", - type: "string", - default: "", - }); - - pi.registerFlag(KOAN_DEBUG_FLAG, { - description: "Developer mode: show verbatim step prompts in the activity feed.", - type: "boolean", - default: false, - }); - - const ctx = createRuntimeContext(); - - registerAllTools(pi, ctx); - registerInfrastructureHandlers(pi); - - // Dispatch happens exactly once per session (guard prevents re-entry on - // subsequent before_agent_start calls, which pi may emit on reconnect). - let dispatched = false; - pi.on("before_agent_start", async (_event, extCtx) => { - if (dispatched) return; - dispatched = true; - - const dirFlag = pi.getFlag("koan-dir"); - if (!dirFlag || typeof dirFlag !== "string" || dirFlag.trim().length === 0) { - // No --koan-dir flag: running as parent session, not as a subagent. - return; - } - - const subagentDir = dirFlag.trim(); - - // task.json was written by the parent before spawning this process. - // Throws if missing or malformed — that is a programming error, not a user error. - const task = await readTaskFile(subagentDir); - - ctx.epicDir = task.epicDir; - ctx.subagentDir = subagentDir; - // Thread phaseInstructions from the workflow orchestrator's decision into context. - // Present only when the user provided focus instructions during the workflow - // decision interaction. Phases access this via this.ctx.phaseInstructions in - // their getStepGuidance() implementation. - ctx.phaseInstructions = task.phaseInstructions; - ctx.debugMode = !!pi.getFlag(KOAN_DEBUG_FLAG); - - const eventLog = new EventLog( - subagentDir, - task.role, - task.role, - currentModelId(extCtx), - ); - await eventLog.open(); - - // Make the event log available to tools via ctx. - ctx.eventLog = eventLog; - - pi.on("tool_call", (event) => { - void eventLog.append(extractToolCall(event as { - toolCallId: string; - toolName: string; - input: Record; - })); - }); - - pi.on("tool_result", (event) => { - void eventLog.append(extractToolResult(event as { - toolCallId: string; - toolName: string; - input: Record; - content: Array<{ type: string; text?: string }>; - isError: boolean; - }, { debug: ctx.debugMode })); - }); - - pi.on("turn_end", (event) => { - const msg = event.message as { - role: string; - usage?: { input: number; output: number; cacheRead: number; cacheWrite: number }; - content?: Array<{ type: string; thinking?: string }>; - }; - if (msg.role === "assistant" && msg.usage) { - void eventLog.append({ - kind: "usage", - input: msg.usage.input, - output: msg.usage.output, - cacheRead: msg.usage.cacheRead, - cacheWrite: msg.usage.cacheWrite, - }); - } - if (msg.role === "assistant" && Array.isArray(msg.content)) { - for (const block of msg.content) { - if (block.type === "thinking" && typeof block.thinking === "string" && block.thinking.length > 0) { - void eventLog.append({ - kind: "thinking", - text: block.thinking, - chars: block.thinking.length, - }); - } - } - } - }); - - pi.on("session_shutdown", () => { - void eventLog.close(); - }); - - await dispatchPhase(pi, task, ctx, log, eventLog); - }); - - // -- koan_plan tool -- - pi.registerTool({ - name: "koan_plan", - label: "Plan", - description: [ - "Launch a structured planning pipeline for complex, multi-file tasks.", - "Invoke when the user asks to plan, use the planner, or when the task", - "is too large to implement directly.", - "", - "The current conversation is automatically captured — it becomes the", - "planning context. The pipeline spawns specialized agents that decompose", - "the task into stories and execute them one at a time.", - "", - "This is a long-running operation. Do not invoke for simple tasks.", - ].join("\n"), - parameters: Type.Object({}), - async execute(_toolCallId, _params, _signal, _onUpdate, extCtx) { - const epicInfo = await createEpicDirectory("", extCtx.cwd); - ctx.epicDir = epicInfo.directory; - setLogDir(epicInfo.directory); - - const extensionPath = path.resolve(import.meta.dirname, "koan.ts"); - - const portFlag = pi.getFlag("koan-webserver-port") as string || ""; - const serverPort = portFlag ? parseInt(portFlag, 10) : 0; - const serverToken = (pi.getFlag("koan-webserver-token") as string) || ""; - const debugMode = !!pi.getFlag(KOAN_DEBUG_FLAG); - const server = await startWebServer(epicInfo.directory, { port: serverPort, token: serverToken, debugMode }); - try { - // Skip opening the browser when a fixed port is set — the caller - // (e.g. an automated agent or test harness) already knows the URL. - if (!serverPort) await openBrowser(pi, server.url); - await exportConversation(extCtx.sessionManager, epicInfo.directory); - log("Conversation exported", { epicDir: epicInfo.directory }); - - const result = await runPipeline(epicInfo.directory, extCtx.cwd, extensionPath, log, server, { debugMode }); - - return { - content: [{ type: "text" as const, text: `Dashboard: ${server.url}\n\n${result.summary}` }], - details: undefined, - }; - } finally { - server.close(); - } - }, - }); - - // -- Commands -- - pi.registerCommand("koan", { - description: "Koan commands. Usage: /koan config", - handler: async (args, extCtx) => { - const subcommand = args.trim(); - if (subcommand === "config") { - await openKoanConfig(extCtx); - } else if (subcommand === "") { - extCtx.ui.notify("Usage: /koan config", "info"); - } else { - extCtx.ui.notify(`Unknown koan subcommand: "${subcommand}". Usage: /koan config`, "warning"); - } - }, - }); -} diff --git a/package-lock.json b/package-lock.json deleted file mode 100644 index 68b6b3b..0000000 --- a/package-lock.json +++ /dev/null @@ -1,4618 +0,0 @@ -{ - "name": "@solatis/koan", - "version": "0.0.1", - "lockfileVersion": 3, - "requires": true, - "packages": { - "": { - "name": "@solatis/koan", - "version": "0.0.1", - "license": "Apache-2.0", - "dependencies": { - "@sinclair/typebox": "^0.32.30", - "marked": "^17.0.5" - }, - "devDependencies": { - "@mariozechner/pi-coding-agent": "^0.52.10", - "esbuild": "^0.25.1", - "preact": "^10.26.2", - "typescript": "^5.9.3", - "zustand": "^4.5.7" - } - }, - "node_modules/@anthropic-ai/sdk": { - "version": "0.73.0", - "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.73.0.tgz", - "integrity": "sha512-URURVzhxXGJDGUGFunIOtBlSl7KWvZiAAKY/ttTkZAkXT9bTPqdk2eK0b8qqSxXpikh3QKPnPYpiyX98zf5ebw==", - "dev": true, - "license": "MIT", - "dependencies": { - "json-schema-to-ts": "^3.1.1" - }, - "bin": { - "anthropic-ai-sdk": "bin/cli" - }, - "peerDependencies": { - "zod": "^3.25.0 || ^4.0.0" - }, - "peerDependenciesMeta": { - "zod": { - "optional": true - } - } - }, - "node_modules/@aws-crypto/crc32": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@aws-crypto/crc32/-/crc32-5.2.0.tgz", - "integrity": "sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-crypto/util": "^5.2.0", - "@aws-sdk/types": "^3.222.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=16.0.0" - } - }, - "node_modules/@aws-crypto/sha256-browser": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-browser/-/sha256-browser-5.2.0.tgz", - "integrity": "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-crypto/sha256-js": "^5.2.0", - "@aws-crypto/supports-web-crypto": "^5.2.0", - "@aws-crypto/util": "^5.2.0", - "@aws-sdk/types": "^3.222.0", - "@aws-sdk/util-locate-window": "^3.0.0", - "@smithy/util-utf8": "^2.0.0", - "tslib": "^2.6.2" - } - }, - "node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/is-array-buffer": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz", - "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/util-buffer-from": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz", - "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/is-array-buffer": "^2.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/util-utf8": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz", - "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/util-buffer-from": "^2.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/@aws-crypto/sha256-js": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-js/-/sha256-js-5.2.0.tgz", - "integrity": "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-crypto/util": "^5.2.0", - "@aws-sdk/types": "^3.222.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=16.0.0" - } - }, - "node_modules/@aws-crypto/supports-web-crypto": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@aws-crypto/supports-web-crypto/-/supports-web-crypto-5.2.0.tgz", - "integrity": "sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - } - }, - "node_modules/@aws-crypto/util": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@aws-crypto/util/-/util-5.2.0.tgz", - "integrity": "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.222.0", - "@smithy/util-utf8": "^2.0.0", - "tslib": "^2.6.2" - } - }, - "node_modules/@aws-crypto/util/node_modules/@smithy/is-array-buffer": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz", - "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/@aws-crypto/util/node_modules/@smithy/util-buffer-from": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz", - "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/is-array-buffer": "^2.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/@aws-crypto/util/node_modules/@smithy/util-utf8": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz", - "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/util-buffer-from": "^2.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/@aws-sdk/client-bedrock-runtime": { - "version": "3.989.0", - "resolved": "https://registry.npmjs.org/@aws-sdk/client-bedrock-runtime/-/client-bedrock-runtime-3.989.0.tgz", - "integrity": "sha512-qVa5B0wXjIuPRhX1dcZo1sa9Y4ycI9tiqK7B4FLok67gUWckiKmEf1xQDFrTmc2eCK5g0CTaeiRdbeM1eWmW1Q==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-crypto/sha256-browser": "5.2.0", - "@aws-crypto/sha256-js": "5.2.0", - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/credential-provider-node": "^3.972.8", - "@aws-sdk/eventstream-handler-node": "^3.972.5", - "@aws-sdk/middleware-eventstream": "^3.972.3", - "@aws-sdk/middleware-host-header": "^3.972.3", - "@aws-sdk/middleware-logger": "^3.972.3", - "@aws-sdk/middleware-recursion-detection": "^3.972.3", - "@aws-sdk/middleware-user-agent": "^3.972.9", - "@aws-sdk/middleware-websocket": "^3.972.6", - "@aws-sdk/region-config-resolver": "^3.972.3", - "@aws-sdk/token-providers": "3.989.0", - "@aws-sdk/types": "^3.973.1", - "@aws-sdk/util-endpoints": "3.989.0", - "@aws-sdk/util-user-agent-browser": "^3.972.3", - "@aws-sdk/util-user-agent-node": "^3.972.7", - "@smithy/config-resolver": "^4.4.6", - "@smithy/core": "^3.23.0", - "@smithy/eventstream-serde-browser": "^4.2.8", - "@smithy/eventstream-serde-config-resolver": "^4.3.8", - "@smithy/eventstream-serde-node": "^4.2.8", - "@smithy/fetch-http-handler": "^5.3.9", - "@smithy/hash-node": "^4.2.8", - "@smithy/invalid-dependency": "^4.2.8", - "@smithy/middleware-content-length": "^4.2.8", - "@smithy/middleware-endpoint": "^4.4.14", - "@smithy/middleware-retry": "^4.4.31", - "@smithy/middleware-serde": "^4.2.9", - "@smithy/middleware-stack": "^4.2.8", - "@smithy/node-config-provider": "^4.3.8", - "@smithy/node-http-handler": "^4.4.10", - "@smithy/protocol-http": "^5.3.8", - "@smithy/smithy-client": "^4.11.3", - "@smithy/types": "^4.12.0", - "@smithy/url-parser": "^4.2.8", - "@smithy/util-base64": "^4.3.0", - "@smithy/util-body-length-browser": "^4.2.0", - "@smithy/util-body-length-node": "^4.2.1", - "@smithy/util-defaults-mode-browser": "^4.3.30", - "@smithy/util-defaults-mode-node": "^4.2.33", - "@smithy/util-endpoints": "^3.2.8", - "@smithy/util-middleware": "^4.2.8", - "@smithy/util-retry": "^4.2.8", - "@smithy/util-stream": "^4.5.12", - "@smithy/util-utf8": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/client-sso": { - "version": "3.989.0", - "resolved": "https://registry.npmjs.org/@aws-sdk/client-sso/-/client-sso-3.989.0.tgz", - "integrity": "sha512-3sC+J1ru5VFXLgt9KZmXto0M7mnV5RkS6FNGwRMK3XrojSjHso9DLOWjbnXhbNv4motH8vu53L1HK2VC1+Nj5w==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-crypto/sha256-browser": "5.2.0", - "@aws-crypto/sha256-js": "5.2.0", - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/middleware-host-header": "^3.972.3", - "@aws-sdk/middleware-logger": "^3.972.3", - "@aws-sdk/middleware-recursion-detection": "^3.972.3", - "@aws-sdk/middleware-user-agent": "^3.972.9", - "@aws-sdk/region-config-resolver": "^3.972.3", - "@aws-sdk/types": "^3.973.1", - "@aws-sdk/util-endpoints": "3.989.0", - "@aws-sdk/util-user-agent-browser": "^3.972.3", - "@aws-sdk/util-user-agent-node": "^3.972.7", - "@smithy/config-resolver": "^4.4.6", - "@smithy/core": "^3.23.0", - "@smithy/fetch-http-handler": "^5.3.9", - "@smithy/hash-node": "^4.2.8", - "@smithy/invalid-dependency": "^4.2.8", - "@smithy/middleware-content-length": "^4.2.8", - "@smithy/middleware-endpoint": "^4.4.14", - "@smithy/middleware-retry": "^4.4.31", - "@smithy/middleware-serde": "^4.2.9", - "@smithy/middleware-stack": "^4.2.8", - "@smithy/node-config-provider": "^4.3.8", - "@smithy/node-http-handler": "^4.4.10", - "@smithy/protocol-http": "^5.3.8", - "@smithy/smithy-client": "^4.11.3", - "@smithy/types": "^4.12.0", - "@smithy/url-parser": "^4.2.8", - "@smithy/util-base64": "^4.3.0", - "@smithy/util-body-length-browser": "^4.2.0", - "@smithy/util-body-length-node": "^4.2.1", - "@smithy/util-defaults-mode-browser": "^4.3.30", - "@smithy/util-defaults-mode-node": "^4.2.33", - "@smithy/util-endpoints": "^3.2.8", - "@smithy/util-middleware": "^4.2.8", - "@smithy/util-retry": "^4.2.8", - "@smithy/util-utf8": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/core": { - "version": "3.973.9", - "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.973.9.tgz", - "integrity": "sha512-cyUOfJSizn8da7XrBEFBf4UMI4A6JQNX6ZFcKtYmh/CrwfzsDcabv3k/z0bNwQ3pX5aeq5sg/8Bs/ASiL0bJaA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@aws-sdk/xml-builder": "^3.972.4", - "@smithy/core": "^3.23.0", - "@smithy/node-config-provider": "^4.3.8", - "@smithy/property-provider": "^4.2.8", - "@smithy/protocol-http": "^5.3.8", - "@smithy/signature-v4": "^5.3.8", - "@smithy/smithy-client": "^4.11.3", - "@smithy/types": "^4.12.0", - "@smithy/util-base64": "^4.3.0", - "@smithy/util-middleware": "^4.2.8", - "@smithy/util-utf8": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/credential-provider-env": { - "version": "3.972.7", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.7.tgz", - "integrity": "sha512-r8kBtglvLjGxBT87l6Lqkh9fL8yJJ6O4CYQPjKlj3AkCuL4/4784x3rxxXWw9LTKXOo114VB6mjxAuy5pI7XIg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/types": "^3.973.1", - "@smithy/property-provider": "^4.2.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/credential-provider-http": { - "version": "3.972.9", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.9.tgz", - "integrity": "sha512-40caFblEg/TPrp9EpvyMxp4xlJ5TuTI+A8H6g8FhHn2hfH2PObFAPLF9d5AljK/G69E1YtTklkuQeAwPlV3w8Q==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/types": "^3.973.1", - "@smithy/fetch-http-handler": "^5.3.9", - "@smithy/node-http-handler": "^4.4.10", - "@smithy/property-provider": "^4.2.8", - "@smithy/protocol-http": "^5.3.8", - "@smithy/smithy-client": "^4.11.3", - "@smithy/types": "^4.12.0", - "@smithy/util-stream": "^4.5.12", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/credential-provider-ini": { - "version": "3.972.7", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.972.7.tgz", - "integrity": "sha512-zeYKrMwM5bCkHFho/x3+1OL0vcZQ0OhTR7k35tLq74+GP5ieV3juHXTZfa2LVE0Bg75cHIIerpX0gomVOhzo/w==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/credential-provider-env": "^3.972.7", - "@aws-sdk/credential-provider-http": "^3.972.9", - "@aws-sdk/credential-provider-login": "^3.972.7", - "@aws-sdk/credential-provider-process": "^3.972.7", - "@aws-sdk/credential-provider-sso": "^3.972.7", - "@aws-sdk/credential-provider-web-identity": "^3.972.7", - "@aws-sdk/nested-clients": "3.989.0", - "@aws-sdk/types": "^3.973.1", - "@smithy/credential-provider-imds": "^4.2.8", - "@smithy/property-provider": "^4.2.8", - "@smithy/shared-ini-file-loader": "^4.4.3", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/credential-provider-login": { - "version": "3.972.7", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.7.tgz", - "integrity": "sha512-Q103cLU6OjAllYjX7+V+PKQw654jjvZUkD+lbUUiFbqut6gR5zwl1DrelvJPM5hnzIty7BCaxaRB3KMuz3M/ug==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/nested-clients": "3.989.0", - "@aws-sdk/types": "^3.973.1", - "@smithy/property-provider": "^4.2.8", - "@smithy/protocol-http": "^5.3.8", - "@smithy/shared-ini-file-loader": "^4.4.3", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/credential-provider-node": { - "version": "3.972.8", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.8.tgz", - "integrity": "sha512-AaDVOT7iNJyLjc3j91VlucPZ4J8Bw+eu9sllRDugJqhHWYyR3Iyp2huBUW8A3+DfHoh70sxGkY92cThAicSzlQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/credential-provider-env": "^3.972.7", - "@aws-sdk/credential-provider-http": "^3.972.9", - "@aws-sdk/credential-provider-ini": "^3.972.7", - "@aws-sdk/credential-provider-process": "^3.972.7", - "@aws-sdk/credential-provider-sso": "^3.972.7", - "@aws-sdk/credential-provider-web-identity": "^3.972.7", - "@aws-sdk/types": "^3.973.1", - "@smithy/credential-provider-imds": "^4.2.8", - "@smithy/property-provider": "^4.2.8", - "@smithy/shared-ini-file-loader": "^4.4.3", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/credential-provider-process": { - "version": "3.972.7", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.7.tgz", - "integrity": "sha512-hxMo1V3ujWWrQSONxQJAElnjredkRpB6p8SDjnvRq70IwYY38R/CZSys0IbhRPxdgWZ5j12yDRk2OXhxw4Gj3g==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/types": "^3.973.1", - "@smithy/property-provider": "^4.2.8", - "@smithy/shared-ini-file-loader": "^4.4.3", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/credential-provider-sso": { - "version": "3.972.7", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.972.7.tgz", - "integrity": "sha512-ZGKBOHEj8Ap15jhG2XMncQmKLTqA++2DVU2eZfLu3T/pkwDyhCp5eZv5c/acFxbZcA/6mtxke+vzO/n+aeHs4A==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/client-sso": "3.989.0", - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/token-providers": "3.989.0", - "@aws-sdk/types": "^3.973.1", - "@smithy/property-provider": "^4.2.8", - "@smithy/shared-ini-file-loader": "^4.4.3", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/credential-provider-web-identity": { - "version": "3.972.7", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.7.tgz", - "integrity": "sha512-AbYupBIoSJoVMlbMqBhNvPhqj+CdGtzW7Uk4ZIMBm2br18pc3rkG1VaKVFV85H87QCvLHEnni1idJjaX1wOmIw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/nested-clients": "3.989.0", - "@aws-sdk/types": "^3.973.1", - "@smithy/property-provider": "^4.2.8", - "@smithy/shared-ini-file-loader": "^4.4.3", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/eventstream-handler-node": { - "version": "3.972.5", - "resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.5.tgz", - "integrity": "sha512-xEmd3dnyn83K6t4AJxBJA63wpEoCD45ERFG0XMTViD2E/Ohls9TLxjOWPb1PAxR9/46cKy/TImez1GoqP6xVNQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@smithy/eventstream-codec": "^4.2.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/middleware-eventstream": { - "version": "3.972.3", - "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.3.tgz", - "integrity": "sha512-pbvZ6Ye/Ks6BAZPa3RhsNjHrvxU9li25PMhSdDpbX0jzdpKpAkIR65gXSNKmA/REnSdEMWSD4vKUW+5eMFzB6w==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@smithy/protocol-http": "^5.3.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/middleware-host-header": { - "version": "3.972.3", - "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-host-header/-/middleware-host-header-3.972.3.tgz", - "integrity": "sha512-aknPTb2M+G3s+0qLCx4Li/qGZH8IIYjugHMv15JTYMe6mgZO8VBpYgeGYsNMGCqCZOcWzuf900jFBG5bopfzmA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@smithy/protocol-http": "^5.3.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/middleware-logger": { - "version": "3.972.3", - "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-logger/-/middleware-logger-3.972.3.tgz", - "integrity": "sha512-Ftg09xNNRqaz9QNzlfdQWfpqMCJbsQdnZVJP55jfhbKi1+FTWxGuvfPoBhDHIovqWKjqbuiew3HuhxbJ0+OjgA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/middleware-recursion-detection": { - "version": "3.972.3", - "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-recursion-detection/-/middleware-recursion-detection-3.972.3.tgz", - "integrity": "sha512-PY57QhzNuXHnwbJgbWYTrqIDHYSeOlhfYERTAuc16LKZpTZRJUjzBFokp9hF7u1fuGeE3D70ERXzdbMBOqQz7Q==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@aws/lambda-invoke-store": "^0.2.2", - "@smithy/protocol-http": "^5.3.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/middleware-user-agent": { - "version": "3.972.9", - "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-user-agent/-/middleware-user-agent-3.972.9.tgz", - "integrity": "sha512-1g1B7yf7KzessB0mKNiV9gAHEwbM662xgU+VE4LxyGe6kVGZ8LqYsngjhE+Stna09CJ7Pxkjr6Uq1OtbGwJJJg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/types": "^3.973.1", - "@aws-sdk/util-endpoints": "3.989.0", - "@smithy/core": "^3.23.0", - "@smithy/protocol-http": "^5.3.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/middleware-websocket": { - "version": "3.972.6", - "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.6.tgz", - "integrity": "sha512-1DedO6N3m8zQ/vG6twNiHtsdwBgk773VdavLEbB3NXeKZDlzSK1BTviqWwvJdKx5UnIy4kGGP6WWpCEFEt/bhQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@aws-sdk/util-format-url": "^3.972.3", - "@smithy/eventstream-codec": "^4.2.8", - "@smithy/eventstream-serde-browser": "^4.2.8", - "@smithy/fetch-http-handler": "^5.3.9", - "@smithy/protocol-http": "^5.3.8", - "@smithy/signature-v4": "^5.3.8", - "@smithy/types": "^4.12.0", - "@smithy/util-base64": "^4.3.0", - "@smithy/util-hex-encoding": "^4.2.0", - "@smithy/util-utf8": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">= 14.0.0" - } - }, - "node_modules/@aws-sdk/nested-clients": { - "version": "3.989.0", - "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.989.0.tgz", - "integrity": "sha512-Dbk2HMPU3mb6RrSRzgf0WCaWSbgtZG258maCpuN2/ONcAQNpOTw99V5fU5CA1qVK6Vkm4Fwj2cnOnw7wbGVlOw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-crypto/sha256-browser": "5.2.0", - "@aws-crypto/sha256-js": "5.2.0", - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/middleware-host-header": "^3.972.3", - "@aws-sdk/middleware-logger": "^3.972.3", - "@aws-sdk/middleware-recursion-detection": "^3.972.3", - "@aws-sdk/middleware-user-agent": "^3.972.9", - "@aws-sdk/region-config-resolver": "^3.972.3", - "@aws-sdk/types": "^3.973.1", - "@aws-sdk/util-endpoints": "3.989.0", - "@aws-sdk/util-user-agent-browser": "^3.972.3", - "@aws-sdk/util-user-agent-node": "^3.972.7", - "@smithy/config-resolver": "^4.4.6", - "@smithy/core": "^3.23.0", - "@smithy/fetch-http-handler": "^5.3.9", - "@smithy/hash-node": "^4.2.8", - "@smithy/invalid-dependency": "^4.2.8", - "@smithy/middleware-content-length": "^4.2.8", - "@smithy/middleware-endpoint": "^4.4.14", - "@smithy/middleware-retry": "^4.4.31", - "@smithy/middleware-serde": "^4.2.9", - "@smithy/middleware-stack": "^4.2.8", - "@smithy/node-config-provider": "^4.3.8", - "@smithy/node-http-handler": "^4.4.10", - "@smithy/protocol-http": "^5.3.8", - "@smithy/smithy-client": "^4.11.3", - "@smithy/types": "^4.12.0", - "@smithy/url-parser": "^4.2.8", - "@smithy/util-base64": "^4.3.0", - "@smithy/util-body-length-browser": "^4.2.0", - "@smithy/util-body-length-node": "^4.2.1", - "@smithy/util-defaults-mode-browser": "^4.3.30", - "@smithy/util-defaults-mode-node": "^4.2.33", - "@smithy/util-endpoints": "^3.2.8", - "@smithy/util-middleware": "^4.2.8", - "@smithy/util-retry": "^4.2.8", - "@smithy/util-utf8": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/region-config-resolver": { - "version": "3.972.3", - "resolved": "https://registry.npmjs.org/@aws-sdk/region-config-resolver/-/region-config-resolver-3.972.3.tgz", - "integrity": "sha512-v4J8qYAWfOMcZ4MJUyatntOicTzEMaU7j3OpkRCGGFSL2NgXQ5VbxauIyORA+pxdKZ0qQG2tCQjQjZDlXEC3Ow==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@smithy/config-resolver": "^4.4.6", - "@smithy/node-config-provider": "^4.3.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/token-providers": { - "version": "3.989.0", - "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.989.0.tgz", - "integrity": "sha512-OdBByMv+OjOZoekrk4THPFpLuND5aIQbDHCGh3n2rvifAbm31+6e0OLhxSeCF1UMPm+nKq12bXYYEoCIx5SQBg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/core": "^3.973.9", - "@aws-sdk/nested-clients": "3.989.0", - "@aws-sdk/types": "^3.973.1", - "@smithy/property-provider": "^4.2.8", - "@smithy/shared-ini-file-loader": "^4.4.3", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/types": { - "version": "3.973.1", - "resolved": "https://registry.npmjs.org/@aws-sdk/types/-/types-3.973.1.tgz", - "integrity": "sha512-DwHBiMNOB468JiX6+i34c+THsKHErYUdNQ3HexeXZvVn4zouLjgaS4FejiGSi2HyBuzuyHg7SuOPmjSvoU9NRg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/util-endpoints": { - "version": "3.989.0", - "resolved": "https://registry.npmjs.org/@aws-sdk/util-endpoints/-/util-endpoints-3.989.0.tgz", - "integrity": "sha512-eKmAOeQM4Qusq0jtcbZPiNWky8XaojByKC/n+THbJ8vJf7t4ys8LlcZ4PrBSHZISe9cC484mQsPVOQh6iySjqw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@smithy/types": "^4.12.0", - "@smithy/url-parser": "^4.2.8", - "@smithy/util-endpoints": "^3.2.8", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/util-format-url": { - "version": "3.972.3", - "resolved": "https://registry.npmjs.org/@aws-sdk/util-format-url/-/util-format-url-3.972.3.tgz", - "integrity": "sha512-n7F2ycckcKFXa01vAsT/SJdjFHfKH9s96QHcs5gn8AaaigASICeME8WdUL9uBp8XV/OVwEt8+6gzn6KFUgQa8g==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@smithy/querystring-builder": "^4.2.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/util-locate-window": { - "version": "3.965.4", - "resolved": "https://registry.npmjs.org/@aws-sdk/util-locate-window/-/util-locate-window-3.965.4.tgz", - "integrity": "sha512-H1onv5SkgPBK2P6JR2MjGgbOnttoNzSPIRoeZTNPZYyaplwGg50zS3amXvXqF0/qfXpWEC9rLWU564QTB9bSog==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws-sdk/util-user-agent-browser": { - "version": "3.972.3", - "resolved": "https://registry.npmjs.org/@aws-sdk/util-user-agent-browser/-/util-user-agent-browser-3.972.3.tgz", - "integrity": "sha512-JurOwkRUcXD/5MTDBcqdyQ9eVedtAsZgw5rBwktsPTN7QtPiS2Ld1jkJepNgYoCufz1Wcut9iup7GJDoIHp8Fw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/types": "^3.973.1", - "@smithy/types": "^4.12.0", - "bowser": "^2.11.0", - "tslib": "^2.6.2" - } - }, - "node_modules/@aws-sdk/util-user-agent-node": { - "version": "3.972.7", - "resolved": "https://registry.npmjs.org/@aws-sdk/util-user-agent-node/-/util-user-agent-node-3.972.7.tgz", - "integrity": "sha512-oyhv+FjrgHjP+F16cmsrJzNP4qaRJzkV1n9Lvv4uyh3kLqo3rIe9NSBSBa35f2TedczfG2dD+kaQhHBB47D6Og==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-sdk/middleware-user-agent": "^3.972.9", - "@aws-sdk/types": "^3.973.1", - "@smithy/node-config-provider": "^4.3.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - }, - "peerDependencies": { - "aws-crt": ">=1.0.0" - }, - "peerDependenciesMeta": { - "aws-crt": { - "optional": true - } - } - }, - "node_modules/@aws-sdk/xml-builder": { - "version": "3.972.4", - "resolved": "https://registry.npmjs.org/@aws-sdk/xml-builder/-/xml-builder-3.972.4.tgz", - "integrity": "sha512-0zJ05ANfYqI6+rGqj8samZBFod0dPPousBjLEqg8WdxSgbMAkRgLyn81lP215Do0rFJ/17LIXwr7q0yK24mP6Q==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "fast-xml-parser": "5.3.4", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@aws/lambda-invoke-store": { - "version": "0.2.3", - "resolved": "https://registry.npmjs.org/@aws/lambda-invoke-store/-/lambda-invoke-store-0.2.3.tgz", - "integrity": "sha512-oLvsaPMTBejkkmHhjf09xTgk71mOqyr/409NKhRIL08If7AhVfUsJhVsx386uJaqNd42v9kWamQ9lFbkoC2dYw==", - "dev": true, - "license": "Apache-2.0", - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@babel/runtime": { - "version": "7.28.6", - "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.28.6.tgz", - "integrity": "sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=6.9.0" - } - }, - "node_modules/@borewit/text-codec": { - "version": "0.2.1", - "resolved": "https://registry.npmjs.org/@borewit/text-codec/-/text-codec-0.2.1.tgz", - "integrity": "sha512-k7vvKPbf7J2fZ5klGRD9AeKfUvojuZIQ3BT5u7Jfv+puwXkUBUT5PVyMDfJZpy30CBDXGMgw7fguK/lpOMBvgw==", - "dev": true, - "license": "MIT", - "funding": { - "type": "github", - "url": "https://github.com/sponsors/Borewit" - } - }, - "node_modules/@esbuild/aix-ppc64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz", - "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==", - "cpu": [ - "ppc64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "aix" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/android-arm": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz", - "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==", - "cpu": [ - "arm" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "android" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/android-arm64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz", - "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "android" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/android-x64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz", - "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "android" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/darwin-arm64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz", - "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/darwin-x64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz", - "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/freebsd-arm64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz", - "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "freebsd" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/freebsd-x64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz", - "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "freebsd" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/linux-arm": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz", - "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==", - "cpu": [ - "arm" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/linux-arm64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz", - "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/linux-ia32": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz", - "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==", - "cpu": [ - "ia32" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/linux-loong64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz", - "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==", - "cpu": [ - "loong64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/linux-mips64el": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz", - "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==", - "cpu": [ - "mips64el" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/linux-ppc64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz", - "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==", - "cpu": [ - "ppc64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/linux-riscv64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz", - "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==", - "cpu": [ - "riscv64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/linux-s390x": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz", - "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==", - "cpu": [ - "s390x" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/linux-x64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz", - "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/netbsd-arm64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz", - "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "netbsd" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/netbsd-x64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz", - "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "netbsd" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/openbsd-arm64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz", - "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "openbsd" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/openbsd-x64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz", - "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "openbsd" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/openharmony-arm64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz", - "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "openharmony" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/sunos-x64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz", - "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "sunos" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/win32-arm64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz", - "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "win32" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/win32-ia32": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz", - "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==", - "cpu": [ - "ia32" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "win32" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@esbuild/win32-x64": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz", - "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "win32" - ], - "engines": { - "node": ">=18" - } - }, - "node_modules/@google/genai": { - "version": "1.41.0", - "resolved": "https://registry.npmjs.org/@google/genai/-/genai-1.41.0.tgz", - "integrity": "sha512-S4WGil+PG0NBQRAx+0yrQuM/TWOLn2gGEy5wn4IsoOI6ouHad0P61p3OWdhJ3aqr9kfj8o904i/jevfaGoGuIQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "google-auth-library": "^10.3.0", - "p-retry": "^7.1.1", - "protobufjs": "^7.5.4", - "ws": "^8.18.0" - }, - "engines": { - "node": ">=20.0.0" - }, - "peerDependencies": { - "@modelcontextprotocol/sdk": "^1.25.2" - }, - "peerDependenciesMeta": { - "@modelcontextprotocol/sdk": { - "optional": true - } - } - }, - "node_modules/@isaacs/cliui": { - "version": "9.0.0", - "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-9.0.0.tgz", - "integrity": "sha512-AokJm4tuBHillT+FpMtxQ60n8ObyXBatq7jD2/JA9dxbDDokKQm8KMht5ibGzLVU9IJDIKK4TPKgMHEYMn3lMg==", - "dev": true, - "license": "BlueOak-1.0.0", - "engines": { - "node": ">=18" - } - }, - "node_modules/@mariozechner/clipboard": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard/-/clipboard-0.3.2.tgz", - "integrity": "sha512-IHQpksNjo7EAtGuHFU+tbWDp5LarH3HU/8WiB9O70ZEoBPHOg0/6afwSLK0QyNMMmx4Bpi/zl6+DcBXe95nWYA==", - "dev": true, - "license": "MIT", - "optional": true, - "engines": { - "node": ">= 10" - }, - "optionalDependencies": { - "@mariozechner/clipboard-darwin-arm64": "0.3.2", - "@mariozechner/clipboard-darwin-universal": "0.3.2", - "@mariozechner/clipboard-darwin-x64": "0.3.2", - "@mariozechner/clipboard-linux-arm64-gnu": "0.3.2", - "@mariozechner/clipboard-linux-arm64-musl": "0.3.2", - "@mariozechner/clipboard-linux-riscv64-gnu": "0.3.2", - "@mariozechner/clipboard-linux-x64-gnu": "0.3.2", - "@mariozechner/clipboard-linux-x64-musl": "0.3.2", - "@mariozechner/clipboard-win32-arm64-msvc": "0.3.2", - "@mariozechner/clipboard-win32-x64-msvc": "0.3.2" - } - }, - "node_modules/@mariozechner/clipboard-darwin-arm64": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-arm64/-/clipboard-darwin-arm64-0.3.2.tgz", - "integrity": "sha512-uBf6K7Je1ihsgvmWxA8UCGCeI+nbRVRXoarZdLjl6slz94Zs1tNKFZqx7aCI5O1i3e0B6ja82zZ06BWrl0MCVw==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@mariozechner/clipboard-darwin-universal": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-universal/-/clipboard-darwin-universal-0.3.2.tgz", - "integrity": "sha512-mxSheKTW2U9LsBdXy0SdmdCAE5HqNS9QUmpNHLnfJ+SsbFKALjEZc5oRrVMXxGQSirDvYf5bjmRyT0QYYonnlg==", - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@mariozechner/clipboard-darwin-x64": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-x64/-/clipboard-darwin-x64-0.3.2.tgz", - "integrity": "sha512-U1BcVEoidvwIp95+HJswSW+xr28EQiHR7rZjH6pn8Sja5yO4Yoe3yCN0Zm8Lo72BbSOK/fTSq0je7CJpaPCspg==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@mariozechner/clipboard-linux-arm64-gnu": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-arm64-gnu/-/clipboard-linux-arm64-gnu-0.3.2.tgz", - "integrity": "sha512-BsinwG3yWTIjdgNCxsFlip7LkfwPk+ruw/aFCXHUg/fb5XC/Ksp+YMQ7u0LUtiKzIv/7LMXgZInJQH6gxbAaqQ==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@mariozechner/clipboard-linux-arm64-musl": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-arm64-musl/-/clipboard-linux-arm64-musl-0.3.2.tgz", - "integrity": "sha512-0/Gi5Xq2V6goXBop19ePoHvXsmJD9SzFlO3S+d6+T2b+BlPcpOu3Oa0wTjl+cZrLAAEzA86aPNBI+VVAFDFPKw==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@mariozechner/clipboard-linux-riscv64-gnu": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-riscv64-gnu/-/clipboard-linux-riscv64-gnu-0.3.2.tgz", - "integrity": "sha512-2AFFiXB24qf0zOZsxI1GJGb9wQGlOJyN6UwoXqmKS3dpQi/l6ix30IzDDA4c4ZcCcx4D+9HLYXhC1w7Sov8pXA==", - "cpu": [ - "riscv64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@mariozechner/clipboard-linux-x64-gnu": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-x64-gnu/-/clipboard-linux-x64-gnu-0.3.2.tgz", - "integrity": "sha512-v6fVnsn7WMGg73Dab8QMwyFce7tzGfgEixKgzLP8f1GJqkJZi5zO4k4FOHzSgUufgLil63gnxvMpjWkgfeQN7A==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@mariozechner/clipboard-linux-x64-musl": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-x64-musl/-/clipboard-linux-x64-musl-0.3.2.tgz", - "integrity": "sha512-xVUtnoMQ8v2JVyfJLKKXACA6avdnchdbBkTsZs8BgJQo29qwCp5NIHAUO8gbJ40iaEGToW5RlmVk2M9V0HsHEw==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@mariozechner/clipboard-win32-arm64-msvc": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-win32-arm64-msvc/-/clipboard-win32-arm64-msvc-0.3.2.tgz", - "integrity": "sha512-AEgg95TNi8TGgak2wSXZkXKCvAUTjWoU1Pqb0ON7JHrX78p616XUFNTJohtIon3e0w6k0pYPZeCuqRCza/Tqeg==", - "cpu": [ - "arm64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "win32" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@mariozechner/clipboard-win32-x64-msvc": { - "version": "0.3.2", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-win32-x64-msvc/-/clipboard-win32-x64-msvc-0.3.2.tgz", - "integrity": "sha512-tGRuYpZwDOD7HBrCpyRuhGnHHSCknELvqwKKUG4JSfSB7JIU7LKRh6zx6fMUOQd8uISK35TjFg5UcNih+vJhFA==", - "cpu": [ - "x64" - ], - "dev": true, - "license": "MIT", - "optional": true, - "os": [ - "win32" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@mariozechner/jiti": { - "version": "2.6.5", - "resolved": "https://registry.npmjs.org/@mariozechner/jiti/-/jiti-2.6.5.tgz", - "integrity": "sha512-faGUlTcXka5l7rv0lP3K3vGW/ejRuOS24RR2aSFWREUQqzjgdsuWNo/IiPqL3kWRGt6Ahl2+qcDAwtdeWeuGUw==", - "dev": true, - "license": "MIT", - "dependencies": { - "std-env": "^3.10.0", - "yoctocolors": "^2.1.2" - }, - "bin": { - "jiti": "lib/jiti-cli.mjs" - } - }, - "node_modules/@mariozechner/pi-agent-core": { - "version": "0.52.10", - "resolved": "https://registry.npmjs.org/@mariozechner/pi-agent-core/-/pi-agent-core-0.52.10.tgz", - "integrity": "sha512-rTM3ug6rMuDFbQINympIIV9CW3Z8ONyBSehsoDNWtdXTWNA7Nzpx3mAYsA91B856HM0Zbl45UBNRN1YHDeaFTg==", - "dev": true, - "license": "MIT", - "dependencies": { - "@mariozechner/pi-ai": "^0.52.10" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@mariozechner/pi-ai": { - "version": "0.52.10", - "resolved": "https://registry.npmjs.org/@mariozechner/pi-ai/-/pi-ai-0.52.10.tgz", - "integrity": "sha512-dgV5emMbDoz0GGyDy6CjY+RcW/PqwQvUzqAehjDUj1M+3b7+fIB7E2WKZQKvjYIY79qTvAIyrdEmIs2BQX+enA==", - "dev": true, - "license": "MIT", - "dependencies": { - "@anthropic-ai/sdk": "^0.73.0", - "@aws-sdk/client-bedrock-runtime": "^3.983.0", - "@google/genai": "^1.40.0", - "@mistralai/mistralai": "1.10.0", - "@sinclair/typebox": "^0.34.41", - "ajv": "^8.17.1", - "ajv-formats": "^3.0.1", - "chalk": "^5.6.2", - "openai": "6.10.0", - "partial-json": "^0.1.7", - "proxy-agent": "^6.5.0", - "undici": "^7.19.1", - "zod-to-json-schema": "^3.24.6" - }, - "bin": { - "pi-ai": "dist/cli.js" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@mariozechner/pi-ai/node_modules/@sinclair/typebox": { - "version": "0.34.48", - "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.34.48.tgz", - "integrity": "sha512-kKJTNuK3AQOrgjjotVxMrCn1sUJwM76wMszfq1kdU4uYVJjvEWuFQ6HgvLt4Xz3fSmZlTOxJ/Ie13KnIcWQXFA==", - "dev": true, - "license": "MIT" - }, - "node_modules/@mariozechner/pi-coding-agent": { - "version": "0.52.10", - "resolved": "https://registry.npmjs.org/@mariozechner/pi-coding-agent/-/pi-coding-agent-0.52.10.tgz", - "integrity": "sha512-88gBrk+aDKMe4M6hY63LT8ylXEeoNdwnKHB7Ijmxzw5ShtWl7+H8vTBIwxZu/5yNR2b4VhjB0NGi3khpwT5I1A==", - "dev": true, - "license": "MIT", - "dependencies": { - "@mariozechner/jiti": "^2.6.2", - "@mariozechner/pi-agent-core": "^0.52.10", - "@mariozechner/pi-ai": "^0.52.10", - "@mariozechner/pi-tui": "^0.52.10", - "@silvia-odwyer/photon-node": "^0.3.4", - "chalk": "^5.5.0", - "cli-highlight": "^2.1.11", - "diff": "^8.0.2", - "file-type": "^21.1.1", - "glob": "^13.0.1", - "hosted-git-info": "^9.0.2", - "ignore": "^7.0.5", - "marked": "^15.0.12", - "minimatch": "^10.1.1", - "proper-lockfile": "^4.1.2", - "yaml": "^2.8.2" - }, - "bin": { - "pi": "dist/cli.js" - }, - "engines": { - "node": ">=20.0.0" - }, - "optionalDependencies": { - "@mariozechner/clipboard": "^0.3.2" - } - }, - "node_modules/@mariozechner/pi-coding-agent/node_modules/marked": { - "version": "15.0.12", - "resolved": "https://registry.npmjs.org/marked/-/marked-15.0.12.tgz", - "integrity": "sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==", - "dev": true, - "license": "MIT", - "bin": { - "marked": "bin/marked.js" - }, - "engines": { - "node": ">= 18" - } - }, - "node_modules/@mariozechner/pi-tui": { - "version": "0.52.10", - "resolved": "https://registry.npmjs.org/@mariozechner/pi-tui/-/pi-tui-0.52.10.tgz", - "integrity": "sha512-j0re5FXzznkrzC7BOc1fb+DUWYetRZAVSUbdZoxa6S5S7amxmIJzbSNCgKBaF1ZyY40jp+B5Z4W60Qc7Pn1rxA==", - "dev": true, - "license": "MIT", - "dependencies": { - "@types/mime-types": "^2.1.4", - "chalk": "^5.5.0", - "get-east-asian-width": "^1.3.0", - "marked": "^15.0.12", - "mime-types": "^3.0.1" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@mariozechner/pi-tui/node_modules/marked": { - "version": "15.0.12", - "resolved": "https://registry.npmjs.org/marked/-/marked-15.0.12.tgz", - "integrity": "sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==", - "dev": true, - "license": "MIT", - "bin": { - "marked": "bin/marked.js" - }, - "engines": { - "node": ">= 18" - } - }, - "node_modules/@mistralai/mistralai": { - "version": "1.10.0", - "resolved": "https://registry.npmjs.org/@mistralai/mistralai/-/mistralai-1.10.0.tgz", - "integrity": "sha512-tdIgWs4Le8vpvPiUEWne6tK0qbVc+jMenujnvTqOjogrJUsCSQhus0tHTU1avDDh5//Rq2dFgP9mWRAdIEoBqg==", - "dev": true, - "dependencies": { - "zod": "^3.20.0", - "zod-to-json-schema": "^3.24.1" - } - }, - "node_modules/@mistralai/mistralai/node_modules/zod": { - "version": "3.25.76", - "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", - "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", - "dev": true, - "license": "MIT", - "funding": { - "url": "https://github.com/sponsors/colinhacks" - } - }, - "node_modules/@pkgjs/parseargs": { - "version": "0.11.0", - "resolved": "https://registry.npmjs.org/@pkgjs/parseargs/-/parseargs-0.11.0.tgz", - "integrity": "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==", - "dev": true, - "license": "MIT", - "optional": true, - "engines": { - "node": ">=14" - } - }, - "node_modules/@protobufjs/aspromise": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz", - "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==", - "dev": true, - "license": "BSD-3-Clause" - }, - "node_modules/@protobufjs/base64": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz", - "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==", - "dev": true, - "license": "BSD-3-Clause" - }, - "node_modules/@protobufjs/codegen": { - "version": "2.0.4", - "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.4.tgz", - "integrity": "sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg==", - "dev": true, - "license": "BSD-3-Clause" - }, - "node_modules/@protobufjs/eventemitter": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.0.tgz", - "integrity": "sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q==", - "dev": true, - "license": "BSD-3-Clause" - }, - "node_modules/@protobufjs/fetch": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.0.tgz", - "integrity": "sha512-lljVXpqXebpsijW71PZaCYeIcE5on1w5DlQy5WH6GLbFryLUrBD4932W/E2BSpfRJWseIL4v/KPgBFxDOIdKpQ==", - "dev": true, - "license": "BSD-3-Clause", - "dependencies": { - "@protobufjs/aspromise": "^1.1.1", - "@protobufjs/inquire": "^1.1.0" - } - }, - "node_modules/@protobufjs/float": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz", - "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==", - "dev": true, - "license": "BSD-3-Clause" - }, - "node_modules/@protobufjs/inquire": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.0.tgz", - "integrity": "sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q==", - "dev": true, - "license": "BSD-3-Clause" - }, - "node_modules/@protobufjs/path": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz", - "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==", - "dev": true, - "license": "BSD-3-Clause" - }, - "node_modules/@protobufjs/pool": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz", - "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==", - "dev": true, - "license": "BSD-3-Clause" - }, - "node_modules/@protobufjs/utf8": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.0.tgz", - "integrity": "sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==", - "dev": true, - "license": "BSD-3-Clause" - }, - "node_modules/@silvia-odwyer/photon-node": { - "version": "0.3.4", - "resolved": "https://registry.npmjs.org/@silvia-odwyer/photon-node/-/photon-node-0.3.4.tgz", - "integrity": "sha512-bnly4BKB3KDTFxrUIcgCLbaeVVS8lrAkri1pEzskpmxu9MdfGQTy8b8EgcD83ywD3RPMsIulY8xJH5Awa+t9fA==", - "dev": true, - "license": "Apache-2.0" - }, - "node_modules/@sinclair/typebox": { - "version": "0.32.35", - "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.32.35.tgz", - "integrity": "sha512-Ul3YyOTU++to8cgNkttakC0dWvpERr6RYoHO2W47DLbFvrwBDJUY31B1sImH6JZSYc4Kt4PyHtoPNu+vL2r2dA==", - "license": "MIT" - }, - "node_modules/@smithy/abort-controller": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/abort-controller/-/abort-controller-4.2.8.tgz", - "integrity": "sha512-peuVfkYHAmS5ybKxWcfraK7WBBP0J+rkfUcbHJJKQ4ir3UAUNQI+Y4Vt/PqSzGqgloJ5O1dk7+WzNL8wcCSXbw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/config-resolver": { - "version": "4.4.6", - "resolved": "https://registry.npmjs.org/@smithy/config-resolver/-/config-resolver-4.4.6.tgz", - "integrity": "sha512-qJpzYC64kaj3S0fueiu3kXm8xPrR3PcXDPEgnaNMRn0EjNSZFoFjvbUp0YUDsRhN1CB90EnHJtbxWKevnH99UQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/node-config-provider": "^4.3.8", - "@smithy/types": "^4.12.0", - "@smithy/util-config-provider": "^4.2.0", - "@smithy/util-endpoints": "^3.2.8", - "@smithy/util-middleware": "^4.2.8", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/core": { - "version": "3.23.0", - "resolved": "https://registry.npmjs.org/@smithy/core/-/core-3.23.0.tgz", - "integrity": "sha512-Yq4UPVoQICM9zHnByLmG8632t2M0+yap4T7ANVw482J0W7HW0pOuxwVmeOwzJqX2Q89fkXz0Vybz55Wj2Xzrsg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/middleware-serde": "^4.2.9", - "@smithy/protocol-http": "^5.3.8", - "@smithy/types": "^4.12.0", - "@smithy/util-base64": "^4.3.0", - "@smithy/util-body-length-browser": "^4.2.0", - "@smithy/util-middleware": "^4.2.8", - "@smithy/util-stream": "^4.5.12", - "@smithy/util-utf8": "^4.2.0", - "@smithy/uuid": "^1.1.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/credential-provider-imds": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/credential-provider-imds/-/credential-provider-imds-4.2.8.tgz", - "integrity": "sha512-FNT0xHS1c/CPN8upqbMFP83+ul5YgdisfCfkZ86Jh2NSmnqw/AJ6x5pEogVCTVvSm7j9MopRU89bmDelxuDMYw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/node-config-provider": "^4.3.8", - "@smithy/property-provider": "^4.2.8", - "@smithy/types": "^4.12.0", - "@smithy/url-parser": "^4.2.8", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/eventstream-codec": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/eventstream-codec/-/eventstream-codec-4.2.8.tgz", - "integrity": "sha512-jS/O5Q14UsufqoGhov7dHLOPCzkYJl9QDzusI2Psh4wyYx/izhzvX9P4D69aTxcdfVhEPhjK+wYyn/PzLjKbbw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@aws-crypto/crc32": "5.2.0", - "@smithy/types": "^4.12.0", - "@smithy/util-hex-encoding": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/eventstream-serde-browser": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-browser/-/eventstream-serde-browser-4.2.8.tgz", - "integrity": "sha512-MTfQT/CRQz5g24ayXdjg53V0mhucZth4PESoA5IhvaWVDTOQLfo8qI9vzqHcPsdd2v6sqfTYqF5L/l+pea5Uyw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/eventstream-serde-universal": "^4.2.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/eventstream-serde-config-resolver": { - "version": "4.3.8", - "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-config-resolver/-/eventstream-serde-config-resolver-4.3.8.tgz", - "integrity": "sha512-ah12+luBiDGzBruhu3efNy1IlbwSEdNiw8fOZksoKoWW1ZHvO/04MQsdnws/9Aj+5b0YXSSN2JXKy/ClIsW8MQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/eventstream-serde-node": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-node/-/eventstream-serde-node-4.2.8.tgz", - "integrity": "sha512-cYpCpp29z6EJHa5T9WL0KAlq3SOKUQkcgSoeRfRVwjGgSFl7Uh32eYGt7IDYCX20skiEdRffyDpvF2efEZPC0A==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/eventstream-serde-universal": "^4.2.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/eventstream-serde-universal": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-universal/-/eventstream-serde-universal-4.2.8.tgz", - "integrity": "sha512-iJ6YNJd0bntJYnX6s52NC4WFYcZeKrPUr1Kmmr5AwZcwCSzVpS7oavAmxMR7pMq7V+D1G4s9F5NJK0xwOsKAlQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/eventstream-codec": "^4.2.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/fetch-http-handler": { - "version": "5.3.9", - "resolved": "https://registry.npmjs.org/@smithy/fetch-http-handler/-/fetch-http-handler-5.3.9.tgz", - "integrity": "sha512-I4UhmcTYXBrct03rwzQX1Y/iqQlzVQaPxWjCjula++5EmWq9YGBrx6bbGqluGc1f0XEfhSkiY4jhLgbsJUMKRA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/protocol-http": "^5.3.8", - "@smithy/querystring-builder": "^4.2.8", - "@smithy/types": "^4.12.0", - "@smithy/util-base64": "^4.3.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/hash-node": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/hash-node/-/hash-node-4.2.8.tgz", - "integrity": "sha512-7ZIlPbmaDGxVoxErDZnuFG18WekhbA/g2/i97wGj+wUBeS6pcUeAym8u4BXh/75RXWhgIJhyC11hBzig6MljwA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "@smithy/util-buffer-from": "^4.2.0", - "@smithy/util-utf8": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/invalid-dependency": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/invalid-dependency/-/invalid-dependency-4.2.8.tgz", - "integrity": "sha512-N9iozRybwAQ2dn9Fot9kI6/w9vos2oTXLhtK7ovGqwZjlOcxu6XhPlpLpC+INsxktqHinn5gS2DXDjDF2kG5sQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/is-array-buffer": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-4.2.0.tgz", - "integrity": "sha512-DZZZBvC7sjcYh4MazJSGiWMI2L7E0oCiRHREDzIxi/M2LY79/21iXt6aPLHge82wi5LsuRF5A06Ds3+0mlh6CQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/middleware-content-length": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/middleware-content-length/-/middleware-content-length-4.2.8.tgz", - "integrity": "sha512-RO0jeoaYAB1qBRhfVyq0pMgBoUK34YEJxVxyjOWYZiOKOq2yMZ4MnVXMZCUDenpozHue207+9P5ilTV1zeda0A==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/protocol-http": "^5.3.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/middleware-endpoint": { - "version": "4.4.14", - "resolved": "https://registry.npmjs.org/@smithy/middleware-endpoint/-/middleware-endpoint-4.4.14.tgz", - "integrity": "sha512-FUFNE5KVeaY6U/GL0nzAAHkaCHzXLZcY1EhtQnsAqhD8Du13oPKtMB9/0WK4/LK6a/T5OZ24wPoSShff5iI6Ag==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/core": "^3.23.0", - "@smithy/middleware-serde": "^4.2.9", - "@smithy/node-config-provider": "^4.3.8", - "@smithy/shared-ini-file-loader": "^4.4.3", - "@smithy/types": "^4.12.0", - "@smithy/url-parser": "^4.2.8", - "@smithy/util-middleware": "^4.2.8", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/middleware-retry": { - "version": "4.4.31", - "resolved": "https://registry.npmjs.org/@smithy/middleware-retry/-/middleware-retry-4.4.31.tgz", - "integrity": "sha512-RXBzLpMkIrxBPe4C8OmEOHvS8aH9RUuCOH++Acb5jZDEblxDjyg6un72X9IcbrGTJoiUwmI7hLypNfuDACypbg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/node-config-provider": "^4.3.8", - "@smithy/protocol-http": "^5.3.8", - "@smithy/service-error-classification": "^4.2.8", - "@smithy/smithy-client": "^4.11.3", - "@smithy/types": "^4.12.0", - "@smithy/util-middleware": "^4.2.8", - "@smithy/util-retry": "^4.2.8", - "@smithy/uuid": "^1.1.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/middleware-serde": { - "version": "4.2.9", - "resolved": "https://registry.npmjs.org/@smithy/middleware-serde/-/middleware-serde-4.2.9.tgz", - "integrity": "sha512-eMNiej0u/snzDvlqRGSN3Vl0ESn3838+nKyVfF2FKNXFbi4SERYT6PR392D39iczngbqqGG0Jl1DlCnp7tBbXQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/protocol-http": "^5.3.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/middleware-stack": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/middleware-stack/-/middleware-stack-4.2.8.tgz", - "integrity": "sha512-w6LCfOviTYQjBctOKSwy6A8FIkQy7ICvglrZFl6Bw4FmcQ1Z420fUtIhxaUZZshRe0VCq4kvDiPiXrPZAe8oRA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/node-config-provider": { - "version": "4.3.8", - "resolved": "https://registry.npmjs.org/@smithy/node-config-provider/-/node-config-provider-4.3.8.tgz", - "integrity": "sha512-aFP1ai4lrbVlWjfpAfRSL8KFcnJQYfTl5QxLJXY32vghJrDuFyPZ6LtUL+JEGYiFRG1PfPLHLoxj107ulncLIg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/property-provider": "^4.2.8", - "@smithy/shared-ini-file-loader": "^4.4.3", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/node-http-handler": { - "version": "4.4.10", - "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.4.10.tgz", - "integrity": "sha512-u4YeUwOWRZaHbWaebvrs3UhwQwj+2VNmcVCwXcYTvPIuVyM7Ex1ftAj+fdbG/P4AkBwLq/+SKn+ydOI4ZJE9PA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/abort-controller": "^4.2.8", - "@smithy/protocol-http": "^5.3.8", - "@smithy/querystring-builder": "^4.2.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/property-provider": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/property-provider/-/property-provider-4.2.8.tgz", - "integrity": "sha512-EtCTbyIveCKeOXDSWSdze3k612yCPq1YbXsbqX3UHhkOSW8zKsM9NOJG5gTIya0vbY2DIaieG8pKo1rITHYL0w==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/protocol-http": { - "version": "5.3.8", - "resolved": "https://registry.npmjs.org/@smithy/protocol-http/-/protocol-http-5.3.8.tgz", - "integrity": "sha512-QNINVDhxpZ5QnP3aviNHQFlRogQZDfYlCkQT+7tJnErPQbDhysondEjhikuANxgMsZrkGeiAxXy4jguEGsDrWQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/querystring-builder": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/querystring-builder/-/querystring-builder-4.2.8.tgz", - "integrity": "sha512-Xr83r31+DrE8CP3MqPgMJl+pQlLLmOfiEUnoyAlGzzJIrEsbKsPy1hqH0qySaQm4oWrCBlUqRt+idEgunKB+iw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "@smithy/util-uri-escape": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/querystring-parser": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/querystring-parser/-/querystring-parser-4.2.8.tgz", - "integrity": "sha512-vUurovluVy50CUlazOiXkPq40KGvGWSdmusa3130MwrR1UNnNgKAlj58wlOe61XSHRpUfIIh6cE0zZ8mzKaDPA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/service-error-classification": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/service-error-classification/-/service-error-classification-4.2.8.tgz", - "integrity": "sha512-mZ5xddodpJhEt3RkCjbmUQuXUOaPNTkbMGR0bcS8FE0bJDLMZlhmpgrvPNCYglVw5rsYTpSnv19womw9WWXKQQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/shared-ini-file-loader": { - "version": "4.4.3", - "resolved": "https://registry.npmjs.org/@smithy/shared-ini-file-loader/-/shared-ini-file-loader-4.4.3.tgz", - "integrity": "sha512-DfQjxXQnzC5UbCUPeC3Ie8u+rIWZTvuDPAGU/BxzrOGhRvgUanaP68kDZA+jaT3ZI+djOf+4dERGlm9mWfFDrg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/signature-v4": { - "version": "5.3.8", - "resolved": "https://registry.npmjs.org/@smithy/signature-v4/-/signature-v4-5.3.8.tgz", - "integrity": "sha512-6A4vdGj7qKNRF16UIcO8HhHjKW27thsxYci+5r/uVRkdcBEkOEiY8OMPuydLX4QHSrJqGHPJzPRwwVTqbLZJhg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/is-array-buffer": "^4.2.0", - "@smithy/protocol-http": "^5.3.8", - "@smithy/types": "^4.12.0", - "@smithy/util-hex-encoding": "^4.2.0", - "@smithy/util-middleware": "^4.2.8", - "@smithy/util-uri-escape": "^4.2.0", - "@smithy/util-utf8": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/smithy-client": { - "version": "4.11.3", - "resolved": "https://registry.npmjs.org/@smithy/smithy-client/-/smithy-client-4.11.3.tgz", - "integrity": "sha512-Q7kY5sDau8OoE6Y9zJoRGgje8P4/UY0WzH8R2ok0PDh+iJ+ZnEKowhjEqYafVcubkbYxQVaqwm3iufktzhprGg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/core": "^3.23.0", - "@smithy/middleware-endpoint": "^4.4.14", - "@smithy/middleware-stack": "^4.2.8", - "@smithy/protocol-http": "^5.3.8", - "@smithy/types": "^4.12.0", - "@smithy/util-stream": "^4.5.12", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/types": { - "version": "4.12.0", - "resolved": "https://registry.npmjs.org/@smithy/types/-/types-4.12.0.tgz", - "integrity": "sha512-9YcuJVTOBDjg9LWo23Qp0lTQ3D7fQsQtwle0jVfpbUHy9qBwCEgKuVH4FqFB3VYu0nwdHKiEMA+oXz7oV8X1kw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/url-parser": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/url-parser/-/url-parser-4.2.8.tgz", - "integrity": "sha512-NQho9U68TGMEU639YkXnVMV3GEFFULmmaWdlu1E9qzyIePOHsoSnagTGSDv1Zi8DCNN6btxOSdgmy5E/hsZwhA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/querystring-parser": "^4.2.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-base64": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/@smithy/util-base64/-/util-base64-4.3.0.tgz", - "integrity": "sha512-GkXZ59JfyxsIwNTWFnjmFEI8kZpRNIBfxKjv09+nkAWPt/4aGaEWMM04m4sxgNVWkbt2MdSvE3KF/PfX4nFedQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/util-buffer-from": "^4.2.0", - "@smithy/util-utf8": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-body-length-browser": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/@smithy/util-body-length-browser/-/util-body-length-browser-4.2.0.tgz", - "integrity": "sha512-Fkoh/I76szMKJnBXWPdFkQJl2r9SjPt3cMzLdOB6eJ4Pnpas8hVoWPYemX/peO0yrrvldgCUVJqOAjUrOLjbxg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-body-length-node": { - "version": "4.2.1", - "resolved": "https://registry.npmjs.org/@smithy/util-body-length-node/-/util-body-length-node-4.2.1.tgz", - "integrity": "sha512-h53dz/pISVrVrfxV1iqXlx5pRg3V2YWFcSQyPyXZRrZoZj4R4DeWRDo1a7dd3CPTcFi3kE+98tuNyD2axyZReA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-buffer-from": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-4.2.0.tgz", - "integrity": "sha512-kAY9hTKulTNevM2nlRtxAG2FQ3B2OR6QIrPY3zE5LqJy1oxzmgBGsHLWTcNhWXKchgA0WHW+mZkQrng/pgcCew==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/is-array-buffer": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-config-provider": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/@smithy/util-config-provider/-/util-config-provider-4.2.0.tgz", - "integrity": "sha512-YEjpl6XJ36FTKmD+kRJJWYvrHeUvm5ykaUS5xK+6oXffQPHeEM4/nXlZPe+Wu0lsgRUcNZiliYNh/y7q9c2y6Q==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-defaults-mode-browser": { - "version": "4.3.30", - "resolved": "https://registry.npmjs.org/@smithy/util-defaults-mode-browser/-/util-defaults-mode-browser-4.3.30.tgz", - "integrity": "sha512-cMni0uVU27zxOiU8TuC8pQLC1pYeZ/xEMxvchSK/ILwleRd1ugobOcIRr5vXtcRqKd4aBLWlpeBoDPJJ91LQng==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/property-provider": "^4.2.8", - "@smithy/smithy-client": "^4.11.3", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-defaults-mode-node": { - "version": "4.2.33", - "resolved": "https://registry.npmjs.org/@smithy/util-defaults-mode-node/-/util-defaults-mode-node-4.2.33.tgz", - "integrity": "sha512-LEb2aq5F4oZUSzWBG7S53d4UytZSkOEJPXcBq/xbG2/TmK9EW5naUZ8lKu1BEyWMzdHIzEVN16M3k8oxDq+DJA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/config-resolver": "^4.4.6", - "@smithy/credential-provider-imds": "^4.2.8", - "@smithy/node-config-provider": "^4.3.8", - "@smithy/property-provider": "^4.2.8", - "@smithy/smithy-client": "^4.11.3", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-endpoints": { - "version": "3.2.8", - "resolved": "https://registry.npmjs.org/@smithy/util-endpoints/-/util-endpoints-3.2.8.tgz", - "integrity": "sha512-8JaVTn3pBDkhZgHQ8R0epwWt+BqPSLCjdjXXusK1onwJlRuN69fbvSK66aIKKO7SwVFM6x2J2ox5X8pOaWcUEw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/node-config-provider": "^4.3.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-hex-encoding": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/@smithy/util-hex-encoding/-/util-hex-encoding-4.2.0.tgz", - "integrity": "sha512-CCQBwJIvXMLKxVbO88IukazJD9a4kQ9ZN7/UMGBjBcJYvatpWk+9g870El4cB8/EJxfe+k+y0GmR9CAzkF+Nbw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-middleware": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/util-middleware/-/util-middleware-4.2.8.tgz", - "integrity": "sha512-PMqfeJxLcNPMDgvPbbLl/2Vpin+luxqTGPpW3NAQVLbRrFRzTa4rNAASYeIGjRV9Ytuhzny39SpyU04EQreF+A==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-retry": { - "version": "4.2.8", - "resolved": "https://registry.npmjs.org/@smithy/util-retry/-/util-retry-4.2.8.tgz", - "integrity": "sha512-CfJqwvoRY0kTGe5AkQokpURNCT1u/MkRzMTASWMPPo2hNSnKtF1D45dQl3DE2LKLr4m+PW9mCeBMJr5mCAVThg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/service-error-classification": "^4.2.8", - "@smithy/types": "^4.12.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-stream": { - "version": "4.5.12", - "resolved": "https://registry.npmjs.org/@smithy/util-stream/-/util-stream-4.5.12.tgz", - "integrity": "sha512-D8tgkrmhAX/UNeCZbqbEO3uqyghUnEmmoO9YEvRuwxjlkKKUE7FOgCJnqpTlQPe9MApdWPky58mNQQHbnCzoNg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/fetch-http-handler": "^5.3.9", - "@smithy/node-http-handler": "^4.4.10", - "@smithy/types": "^4.12.0", - "@smithy/util-base64": "^4.3.0", - "@smithy/util-buffer-from": "^4.2.0", - "@smithy/util-hex-encoding": "^4.2.0", - "@smithy/util-utf8": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-uri-escape": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/@smithy/util-uri-escape/-/util-uri-escape-4.2.0.tgz", - "integrity": "sha512-igZpCKV9+E/Mzrpq6YacdTQ0qTiLm85gD6N/IrmyDvQFA4UnU3d5g3m8tMT/6zG/vVkWSU+VxeUyGonL62DuxA==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/util-utf8": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-4.2.0.tgz", - "integrity": "sha512-zBPfuzoI8xyBtR2P6WQj63Rz8i3AmfAaJLuNG8dWsfvPe8lO4aCPYLn879mEgHndZH1zQ2oXmG8O1GGzzaoZiw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "@smithy/util-buffer-from": "^4.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@smithy/uuid": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@smithy/uuid/-/uuid-1.1.0.tgz", - "integrity": "sha512-4aUIteuyxtBUhVdiQqcDhKFitwfd9hqoSDYY2KRXiWtgoWJ9Bmise+KfEPDiVHWeJepvF8xJO9/9+WDIciMFFw==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@tokenizer/inflate": { - "version": "0.4.1", - "resolved": "https://registry.npmjs.org/@tokenizer/inflate/-/inflate-0.4.1.tgz", - "integrity": "sha512-2mAv+8pkG6GIZiF1kNg1jAjh27IDxEPKwdGul3snfztFerfPGI1LjDezZp3i7BElXompqEtPmoPx6c2wgtWsOA==", - "dev": true, - "license": "MIT", - "dependencies": { - "debug": "^4.4.3", - "token-types": "^6.1.1" - }, - "engines": { - "node": ">=18" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/Borewit" - } - }, - "node_modules/@tokenizer/token": { - "version": "0.3.0", - "resolved": "https://registry.npmjs.org/@tokenizer/token/-/token-0.3.0.tgz", - "integrity": "sha512-OvjF+z51L3ov0OyAU0duzsYuvO01PH7x4t6DJx+guahgTnBHkhJdG7soQeTSFLWN3efnHyibZ4Z8l2EuWwJN3A==", - "dev": true, - "license": "MIT" - }, - "node_modules/@tootallnate/quickjs-emscripten": { - "version": "0.23.0", - "resolved": "https://registry.npmjs.org/@tootallnate/quickjs-emscripten/-/quickjs-emscripten-0.23.0.tgz", - "integrity": "sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA==", - "dev": true, - "license": "MIT" - }, - "node_modules/@types/mime-types": { - "version": "2.1.4", - "resolved": "https://registry.npmjs.org/@types/mime-types/-/mime-types-2.1.4.tgz", - "integrity": "sha512-lfU4b34HOri+kAY5UheuFMWPDOI+OPceBSHZKp69gEyTL/mmJ4cnU6Y/rlme3UL3GyOn6Y42hyIEw0/q8sWx5w==", - "dev": true, - "license": "MIT" - }, - "node_modules/@types/node": { - "version": "25.2.3", - "resolved": "https://registry.npmjs.org/@types/node/-/node-25.2.3.tgz", - "integrity": "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ==", - "dev": true, - "license": "MIT", - "dependencies": { - "undici-types": "~7.16.0" - } - }, - "node_modules/agent-base": { - "version": "7.1.4", - "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz", - "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 14" - } - }, - "node_modules/ajv": { - "version": "8.17.1", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", - "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", - "dev": true, - "license": "MIT", - "dependencies": { - "fast-deep-equal": "^3.1.3", - "fast-uri": "^3.0.1", - "json-schema-traverse": "^1.0.0", - "require-from-string": "^2.0.2" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/epoberezkin" - } - }, - "node_modules/ajv-formats": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz", - "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==", - "dev": true, - "license": "MIT", - "dependencies": { - "ajv": "^8.0.0" - }, - "peerDependencies": { - "ajv": "^8.0.0" - }, - "peerDependenciesMeta": { - "ajv": { - "optional": true - } - } - }, - "node_modules/ansi-regex": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", - "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=8" - } - }, - "node_modules/ansi-styles": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", - "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", - "dev": true, - "license": "MIT", - "dependencies": { - "color-convert": "^2.0.1" - }, - "engines": { - "node": ">=8" - }, - "funding": { - "url": "https://github.com/chalk/ansi-styles?sponsor=1" - } - }, - "node_modules/any-promise": { - "version": "1.3.0", - "resolved": "https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz", - "integrity": "sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==", - "dev": true, - "license": "MIT" - }, - "node_modules/ast-types": { - "version": "0.13.4", - "resolved": "https://registry.npmjs.org/ast-types/-/ast-types-0.13.4.tgz", - "integrity": "sha512-x1FCFnFifvYDDzTaLII71vG5uvDwgtmDTEVWAxrgeiR8VjMONcCXJx7E+USjDtHlwFmt9MysbqgF9b9Vjr6w+w==", - "dev": true, - "license": "MIT", - "dependencies": { - "tslib": "^2.0.1" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/balanced-match": { - "version": "4.0.2", - "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.2.tgz", - "integrity": "sha512-x0K50QvKQ97fdEz2kPehIerj+YTeptKF9hyYkKf6egnwmMWAkADiO0QCzSp0R5xN8FTZgYaBfSaue46Ej62nMg==", - "dev": true, - "license": "MIT", - "dependencies": { - "jackspeak": "^4.2.3" - }, - "engines": { - "node": "20 || >=22" - } - }, - "node_modules/base64-js": { - "version": "1.5.1", - "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", - "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==", - "dev": true, - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/feross" - }, - { - "type": "patreon", - "url": "https://www.patreon.com/feross" - }, - { - "type": "consulting", - "url": "https://feross.org/support" - } - ], - "license": "MIT" - }, - "node_modules/basic-ftp": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.1.0.tgz", - "integrity": "sha512-RkaJzeJKDbaDWTIPiJwubyljaEPwpVWkm9Rt5h9Nd6h7tEXTJ3VB4qxdZBioV7JO5yLUaOKwz7vDOzlncUsegw==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=10.0.0" - } - }, - "node_modules/bignumber.js": { - "version": "9.3.1", - "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.3.1.tgz", - "integrity": "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": "*" - } - }, - "node_modules/bowser": { - "version": "2.14.1", - "resolved": "https://registry.npmjs.org/bowser/-/bowser-2.14.1.tgz", - "integrity": "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==", - "dev": true, - "license": "MIT" - }, - "node_modules/brace-expansion": { - "version": "5.0.2", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.2.tgz", - "integrity": "sha512-Pdk8c9poy+YhOgVWw1JNN22/HcivgKWwpxKq04M/jTmHyCZn12WPJebZxdjSa5TmBqISrUSgNYU3eRORljfCCw==", - "dev": true, - "license": "MIT", - "dependencies": { - "balanced-match": "^4.0.2" - }, - "engines": { - "node": "20 || >=22" - } - }, - "node_modules/buffer-equal-constant-time": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz", - "integrity": "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==", - "dev": true, - "license": "BSD-3-Clause" - }, - "node_modules/chalk": { - "version": "5.6.2", - "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz", - "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==", - "dev": true, - "license": "MIT", - "engines": { - "node": "^12.17.0 || ^14.13 || >=16.0.0" - }, - "funding": { - "url": "https://github.com/chalk/chalk?sponsor=1" - } - }, - "node_modules/cli-highlight": { - "version": "2.1.11", - "resolved": "https://registry.npmjs.org/cli-highlight/-/cli-highlight-2.1.11.tgz", - "integrity": "sha512-9KDcoEVwyUXrjcJNvHD0NFc/hiwe/WPVYIleQh2O1N2Zro5gWJZ/K+3DGn8w8P/F6FxOgzyC5bxDyHIgCSPhGg==", - "dev": true, - "license": "ISC", - "dependencies": { - "chalk": "^4.0.0", - "highlight.js": "^10.7.1", - "mz": "^2.4.0", - "parse5": "^5.1.1", - "parse5-htmlparser2-tree-adapter": "^6.0.0", - "yargs": "^16.0.0" - }, - "bin": { - "highlight": "bin/highlight" - }, - "engines": { - "node": ">=8.0.0", - "npm": ">=5.0.0" - } - }, - "node_modules/cli-highlight/node_modules/chalk": { - "version": "4.1.2", - "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", - "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", - "dev": true, - "license": "MIT", - "dependencies": { - "ansi-styles": "^4.1.0", - "supports-color": "^7.1.0" - }, - "engines": { - "node": ">=10" - }, - "funding": { - "url": "https://github.com/chalk/chalk?sponsor=1" - } - }, - "node_modules/cliui": { - "version": "7.0.4", - "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz", - "integrity": "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==", - "dev": true, - "license": "ISC", - "dependencies": { - "string-width": "^4.2.0", - "strip-ansi": "^6.0.0", - "wrap-ansi": "^7.0.0" - } - }, - "node_modules/color-convert": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", - "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", - "dev": true, - "license": "MIT", - "dependencies": { - "color-name": "~1.1.4" - }, - "engines": { - "node": ">=7.0.0" - } - }, - "node_modules/color-name": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", - "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", - "dev": true, - "license": "MIT" - }, - "node_modules/cross-spawn": { - "version": "7.0.6", - "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", - "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", - "dev": true, - "license": "MIT", - "dependencies": { - "path-key": "^3.1.0", - "shebang-command": "^2.0.0", - "which": "^2.0.1" - }, - "engines": { - "node": ">= 8" - } - }, - "node_modules/data-uri-to-buffer": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz", - "integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 12" - } - }, - "node_modules/debug": { - "version": "4.4.3", - "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", - "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", - "dev": true, - "license": "MIT", - "dependencies": { - "ms": "^2.1.3" - }, - "engines": { - "node": ">=6.0" - }, - "peerDependenciesMeta": { - "supports-color": { - "optional": true - } - } - }, - "node_modules/degenerator": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/degenerator/-/degenerator-5.0.1.tgz", - "integrity": "sha512-TllpMR/t0M5sqCXfj85i4XaAzxmS5tVA16dqvdkMwGmzI+dXLXnw3J+3Vdv7VKw+ThlTMboK6i9rnZ6Nntj5CQ==", - "dev": true, - "license": "MIT", - "dependencies": { - "ast-types": "^0.13.4", - "escodegen": "^2.1.0", - "esprima": "^4.0.1" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/diff": { - "version": "8.0.3", - "resolved": "https://registry.npmjs.org/diff/-/diff-8.0.3.tgz", - "integrity": "sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==", - "dev": true, - "license": "BSD-3-Clause", - "engines": { - "node": ">=0.3.1" - } - }, - "node_modules/eastasianwidth": { - "version": "0.2.0", - "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz", - "integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==", - "dev": true, - "license": "MIT" - }, - "node_modules/ecdsa-sig-formatter": { - "version": "1.0.11", - "resolved": "https://registry.npmjs.org/ecdsa-sig-formatter/-/ecdsa-sig-formatter-1.0.11.tgz", - "integrity": "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "safe-buffer": "^5.0.1" - } - }, - "node_modules/emoji-regex": { - "version": "8.0.0", - "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", - "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", - "dev": true, - "license": "MIT" - }, - "node_modules/esbuild": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz", - "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==", - "dev": true, - "hasInstallScript": true, - "license": "MIT", - "bin": { - "esbuild": "bin/esbuild" - }, - "engines": { - "node": ">=18" - }, - "optionalDependencies": { - "@esbuild/aix-ppc64": "0.25.12", - "@esbuild/android-arm": "0.25.12", - "@esbuild/android-arm64": "0.25.12", - "@esbuild/android-x64": "0.25.12", - "@esbuild/darwin-arm64": "0.25.12", - "@esbuild/darwin-x64": "0.25.12", - "@esbuild/freebsd-arm64": "0.25.12", - "@esbuild/freebsd-x64": "0.25.12", - "@esbuild/linux-arm": "0.25.12", - "@esbuild/linux-arm64": "0.25.12", - "@esbuild/linux-ia32": "0.25.12", - "@esbuild/linux-loong64": "0.25.12", - "@esbuild/linux-mips64el": "0.25.12", - "@esbuild/linux-ppc64": "0.25.12", - "@esbuild/linux-riscv64": "0.25.12", - "@esbuild/linux-s390x": "0.25.12", - "@esbuild/linux-x64": "0.25.12", - "@esbuild/netbsd-arm64": "0.25.12", - "@esbuild/netbsd-x64": "0.25.12", - "@esbuild/openbsd-arm64": "0.25.12", - "@esbuild/openbsd-x64": "0.25.12", - "@esbuild/openharmony-arm64": "0.25.12", - "@esbuild/sunos-x64": "0.25.12", - "@esbuild/win32-arm64": "0.25.12", - "@esbuild/win32-ia32": "0.25.12", - "@esbuild/win32-x64": "0.25.12" - } - }, - "node_modules/escalade": { - "version": "3.2.0", - "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz", - "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=6" - } - }, - "node_modules/escodegen": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/escodegen/-/escodegen-2.1.0.tgz", - "integrity": "sha512-2NlIDTwUWJN0mRPQOdtQBzbUHvdGY2P1VXSyU83Q3xKxM7WHX2Ql8dKq782Q9TgQUNOLEzEYu9bzLNj1q88I5w==", - "dev": true, - "license": "BSD-2-Clause", - "dependencies": { - "esprima": "^4.0.1", - "estraverse": "^5.2.0", - "esutils": "^2.0.2" - }, - "bin": { - "escodegen": "bin/escodegen.js", - "esgenerate": "bin/esgenerate.js" - }, - "engines": { - "node": ">=6.0" - }, - "optionalDependencies": { - "source-map": "~0.6.1" - } - }, - "node_modules/esprima": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", - "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", - "dev": true, - "license": "BSD-2-Clause", - "bin": { - "esparse": "bin/esparse.js", - "esvalidate": "bin/esvalidate.js" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/estraverse": { - "version": "5.3.0", - "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz", - "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==", - "dev": true, - "license": "BSD-2-Clause", - "engines": { - "node": ">=4.0" - } - }, - "node_modules/esutils": { - "version": "2.0.3", - "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz", - "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==", - "dev": true, - "license": "BSD-2-Clause", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/extend": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", - "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", - "dev": true, - "license": "MIT" - }, - "node_modules/fast-deep-equal": { - "version": "3.1.3", - "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", - "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", - "dev": true, - "license": "MIT" - }, - "node_modules/fast-uri": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz", - "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==", - "dev": true, - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/fastify" - }, - { - "type": "opencollective", - "url": "https://opencollective.com/fastify" - } - ], - "license": "BSD-3-Clause" - }, - "node_modules/fast-xml-parser": { - "version": "5.3.4", - "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.3.4.tgz", - "integrity": "sha512-EFd6afGmXlCx8H8WTZHhAoDaWaGyuIBoZJ2mknrNxug+aZKjkp0a0dlars9Izl+jF+7Gu1/5f/2h68cQpe0IiA==", - "dev": true, - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } - ], - "license": "MIT", - "dependencies": { - "strnum": "^2.1.0" - }, - "bin": { - "fxparser": "src/cli/cli.js" - } - }, - "node_modules/fetch-blob": { - "version": "3.2.0", - "resolved": "https://registry.npmjs.org/fetch-blob/-/fetch-blob-3.2.0.tgz", - "integrity": "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==", - "dev": true, - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/jimmywarting" - }, - { - "type": "paypal", - "url": "https://paypal.me/jimmywarting" - } - ], - "license": "MIT", - "dependencies": { - "node-domexception": "^1.0.0", - "web-streams-polyfill": "^3.0.3" - }, - "engines": { - "node": "^12.20 || >= 14.13" - } - }, - "node_modules/file-type": { - "version": "21.3.0", - "resolved": "https://registry.npmjs.org/file-type/-/file-type-21.3.0.tgz", - "integrity": "sha512-8kPJMIGz1Yt/aPEwOsrR97ZyZaD1Iqm8PClb1nYFclUCkBi0Ma5IsYNQzvSFS9ib51lWyIw5mIT9rWzI/xjpzA==", - "dev": true, - "license": "MIT", - "dependencies": { - "@tokenizer/inflate": "^0.4.1", - "strtok3": "^10.3.4", - "token-types": "^6.1.1", - "uint8array-extras": "^1.4.0" - }, - "engines": { - "node": ">=20" - }, - "funding": { - "url": "https://github.com/sindresorhus/file-type?sponsor=1" - } - }, - "node_modules/foreground-child": { - "version": "3.3.1", - "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz", - "integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==", - "dev": true, - "license": "ISC", - "dependencies": { - "cross-spawn": "^7.0.6", - "signal-exit": "^4.0.1" - }, - "engines": { - "node": ">=14" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/foreground-child/node_modules/signal-exit": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", - "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", - "dev": true, - "license": "ISC", - "engines": { - "node": ">=14" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/formdata-polyfill": { - "version": "4.0.10", - "resolved": "https://registry.npmjs.org/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz", - "integrity": "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==", - "dev": true, - "license": "MIT", - "dependencies": { - "fetch-blob": "^3.1.2" - }, - "engines": { - "node": ">=12.20.0" - } - }, - "node_modules/gaxios": { - "version": "7.1.3", - "resolved": "https://registry.npmjs.org/gaxios/-/gaxios-7.1.3.tgz", - "integrity": "sha512-YGGyuEdVIjqxkxVH1pUTMY/XtmmsApXrCVv5EU25iX6inEPbV+VakJfLealkBtJN69AQmh1eGOdCl9Sm1UP6XQ==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "extend": "^3.0.2", - "https-proxy-agent": "^7.0.1", - "node-fetch": "^3.3.2", - "rimraf": "^5.0.1" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/gcp-metadata": { - "version": "8.1.2", - "resolved": "https://registry.npmjs.org/gcp-metadata/-/gcp-metadata-8.1.2.tgz", - "integrity": "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "gaxios": "^7.0.0", - "google-logging-utils": "^1.0.0", - "json-bigint": "^1.0.0" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/get-caller-file": { - "version": "2.0.5", - "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", - "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", - "dev": true, - "license": "ISC", - "engines": { - "node": "6.* || 8.* || >= 10.*" - } - }, - "node_modules/get-east-asian-width": { - "version": "1.4.0", - "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.4.0.tgz", - "integrity": "sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=18" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/get-uri": { - "version": "6.0.5", - "resolved": "https://registry.npmjs.org/get-uri/-/get-uri-6.0.5.tgz", - "integrity": "sha512-b1O07XYq8eRuVzBNgJLstU6FYc1tS6wnMtF1I1D9lE8LxZSOGZ7LhxN54yPP6mGw5f2CkXY2BQUL9Fx41qvcIg==", - "dev": true, - "license": "MIT", - "dependencies": { - "basic-ftp": "^5.0.2", - "data-uri-to-buffer": "^6.0.2", - "debug": "^4.3.4" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/get-uri/node_modules/data-uri-to-buffer": { - "version": "6.0.2", - "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-6.0.2.tgz", - "integrity": "sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 14" - } - }, - "node_modules/glob": { - "version": "13.0.3", - "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.3.tgz", - "integrity": "sha512-/g3B0mC+4x724v1TgtBlBtt2hPi/EWptsIAmXUx9Z2rvBYleQcsrmaOzd5LyL50jf/Soi83ZDJmw2+XqvH/EeA==", - "dev": true, - "license": "BlueOak-1.0.0", - "dependencies": { - "minimatch": "^10.2.0", - "minipass": "^7.1.2", - "path-scurry": "^2.0.0" - }, - "engines": { - "node": "20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/google-auth-library": { - "version": "10.5.0", - "resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-10.5.0.tgz", - "integrity": "sha512-7ABviyMOlX5hIVD60YOfHw4/CxOfBhyduaYB+wbFWCWoni4N7SLcV46hrVRktuBbZjFC9ONyqamZITN7q3n32w==", - "dev": true, - "license": "Apache-2.0", - "dependencies": { - "base64-js": "^1.3.0", - "ecdsa-sig-formatter": "^1.0.11", - "gaxios": "^7.0.0", - "gcp-metadata": "^8.0.0", - "google-logging-utils": "^1.0.0", - "gtoken": "^8.0.0", - "jws": "^4.0.0" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/google-logging-utils": { - "version": "1.1.3", - "resolved": "https://registry.npmjs.org/google-logging-utils/-/google-logging-utils-1.1.3.tgz", - "integrity": "sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==", - "dev": true, - "license": "Apache-2.0", - "engines": { - "node": ">=14" - } - }, - "node_modules/graceful-fs": { - "version": "4.2.11", - "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", - "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", - "dev": true, - "license": "ISC" - }, - "node_modules/gtoken": { - "version": "8.0.0", - "resolved": "https://registry.npmjs.org/gtoken/-/gtoken-8.0.0.tgz", - "integrity": "sha512-+CqsMbHPiSTdtSO14O51eMNlrp9N79gmeqmXeouJOhfucAedHw9noVe/n5uJk3tbKE6a+6ZCQg3RPhVhHByAIw==", - "dev": true, - "license": "MIT", - "dependencies": { - "gaxios": "^7.0.0", - "jws": "^4.0.0" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/has-flag": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", - "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=8" - } - }, - "node_modules/highlight.js": { - "version": "10.7.3", - "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-10.7.3.tgz", - "integrity": "sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==", - "dev": true, - "license": "BSD-3-Clause", - "engines": { - "node": "*" - } - }, - "node_modules/hosted-git-info": { - "version": "9.0.2", - "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-9.0.2.tgz", - "integrity": "sha512-M422h7o/BR3rmCQ8UHi7cyyMqKltdP9Uo+J2fXK+RSAY+wTcKOIRyhTuKv4qn+DJf3g+PL890AzId5KZpX+CBg==", - "dev": true, - "license": "ISC", - "dependencies": { - "lru-cache": "^11.1.0" - }, - "engines": { - "node": "^20.17.0 || >=22.9.0" - } - }, - "node_modules/http-proxy-agent": { - "version": "7.0.2", - "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz", - "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==", - "dev": true, - "license": "MIT", - "dependencies": { - "agent-base": "^7.1.0", - "debug": "^4.3.4" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/https-proxy-agent": { - "version": "7.0.6", - "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz", - "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==", - "dev": true, - "license": "MIT", - "dependencies": { - "agent-base": "^7.1.2", - "debug": "4" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/ieee754": { - "version": "1.2.1", - "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", - "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==", - "dev": true, - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/feross" - }, - { - "type": "patreon", - "url": "https://www.patreon.com/feross" - }, - { - "type": "consulting", - "url": "https://feross.org/support" - } - ], - "license": "BSD-3-Clause" - }, - "node_modules/ignore": { - "version": "7.0.5", - "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz", - "integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 4" - } - }, - "node_modules/ip-address": { - "version": "10.1.0", - "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz", - "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 12" - } - }, - "node_modules/is-fullwidth-code-point": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", - "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=8" - } - }, - "node_modules/is-network-error": { - "version": "1.3.0", - "resolved": "https://registry.npmjs.org/is-network-error/-/is-network-error-1.3.0.tgz", - "integrity": "sha512-6oIwpsgRfnDiyEDLMay/GqCl3HoAtH5+RUKW29gYkL0QA+ipzpDLA16yQs7/RHCSu+BwgbJaOUqa4A99qNVQVw==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=16" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/isexe": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", - "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", - "dev": true, - "license": "ISC" - }, - "node_modules/jackspeak": { - "version": "4.2.3", - "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-4.2.3.tgz", - "integrity": "sha512-ykkVRwrYvFm1nb2AJfKKYPr0emF6IiXDYUaFx4Zn9ZuIH7MrzEZ3sD5RlqGXNRpHtvUHJyOnCEFxOlNDtGo7wg==", - "dev": true, - "license": "BlueOak-1.0.0", - "dependencies": { - "@isaacs/cliui": "^9.0.0" - }, - "engines": { - "node": "20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/json-bigint": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", - "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", - "dev": true, - "license": "MIT", - "dependencies": { - "bignumber.js": "^9.0.0" - } - }, - "node_modules/json-schema-to-ts": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz", - "integrity": "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==", - "dev": true, - "license": "MIT", - "dependencies": { - "@babel/runtime": "^7.18.3", - "ts-algebra": "^2.0.0" - }, - "engines": { - "node": ">=16" - } - }, - "node_modules/json-schema-traverse": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", - "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", - "dev": true, - "license": "MIT" - }, - "node_modules/jwa": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/jwa/-/jwa-2.0.1.tgz", - "integrity": "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==", - "dev": true, - "license": "MIT", - "dependencies": { - "buffer-equal-constant-time": "^1.0.1", - "ecdsa-sig-formatter": "1.0.11", - "safe-buffer": "^5.0.1" - } - }, - "node_modules/jws": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/jws/-/jws-4.0.1.tgz", - "integrity": "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==", - "dev": true, - "license": "MIT", - "dependencies": { - "jwa": "^2.0.1", - "safe-buffer": "^5.0.1" - } - }, - "node_modules/long": { - "version": "5.3.2", - "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz", - "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==", - "dev": true, - "license": "Apache-2.0" - }, - "node_modules/lru-cache": { - "version": "11.2.6", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.6.tgz", - "integrity": "sha512-ESL2CrkS/2wTPfuend7Zhkzo2u0daGJ/A2VucJOgQ/C48S/zB8MMeMHSGKYpXhIjbPxfuezITkaBH1wqv00DDQ==", - "dev": true, - "license": "BlueOak-1.0.0", - "engines": { - "node": "20 || >=22" - } - }, - "node_modules/marked": { - "version": "17.0.5", - "resolved": "https://registry.npmjs.org/marked/-/marked-17.0.5.tgz", - "integrity": "sha512-6hLvc0/JEbRjRgzI6wnT2P1XuM1/RrrDEX0kPt0N7jGm1133g6X7DlxFasUIx+72aKAr904GTxhSLDrd5DIlZg==", - "license": "MIT", - "bin": { - "marked": "bin/marked.js" - }, - "engines": { - "node": ">= 20" - } - }, - "node_modules/mime-db": { - "version": "1.54.0", - "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz", - "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 0.6" - } - }, - "node_modules/mime-types": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz", - "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==", - "dev": true, - "license": "MIT", - "dependencies": { - "mime-db": "^1.54.0" - }, - "engines": { - "node": ">=18" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, - "node_modules/minimatch": { - "version": "10.2.0", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.0.tgz", - "integrity": "sha512-ugkC31VaVg9cF0DFVoADH12k6061zNZkZON+aX8AWsR9GhPcErkcMBceb6znR8wLERM2AkkOxy2nWRLpT9Jq5w==", - "dev": true, - "license": "BlueOak-1.0.0", - "dependencies": { - "brace-expansion": "^5.0.2" - }, - "engines": { - "node": "20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/minipass": { - "version": "7.1.2", - "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.2.tgz", - "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==", - "dev": true, - "license": "ISC", - "engines": { - "node": ">=16 || 14 >=14.17" - } - }, - "node_modules/ms": { - "version": "2.1.3", - "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", - "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", - "dev": true, - "license": "MIT" - }, - "node_modules/mz": { - "version": "2.7.0", - "resolved": "https://registry.npmjs.org/mz/-/mz-2.7.0.tgz", - "integrity": "sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==", - "dev": true, - "license": "MIT", - "dependencies": { - "any-promise": "^1.0.0", - "object-assign": "^4.0.1", - "thenify-all": "^1.0.0" - } - }, - "node_modules/netmask": { - "version": "2.0.2", - "resolved": "https://registry.npmjs.org/netmask/-/netmask-2.0.2.tgz", - "integrity": "sha512-dBpDMdxv9Irdq66304OLfEmQ9tbNRFnFTuZiLo+bD+r332bBmMJ8GBLXklIXXgxd3+v9+KUnZaUR5PJMa75Gsg==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 0.4.0" - } - }, - "node_modules/node-domexception": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz", - "integrity": "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==", - "deprecated": "Use your platform's native DOMException instead", - "dev": true, - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/jimmywarting" - }, - { - "type": "github", - "url": "https://paypal.me/jimmywarting" - } - ], - "license": "MIT", - "engines": { - "node": ">=10.5.0" - } - }, - "node_modules/node-fetch": { - "version": "3.3.2", - "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz", - "integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==", - "dev": true, - "license": "MIT", - "dependencies": { - "data-uri-to-buffer": "^4.0.0", - "fetch-blob": "^3.1.4", - "formdata-polyfill": "^4.0.10" - }, - "engines": { - "node": "^12.20.0 || ^14.13.1 || >=16.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/node-fetch" - } - }, - "node_modules/object-assign": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", - "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/openai": { - "version": "6.10.0", - "resolved": "https://registry.npmjs.org/openai/-/openai-6.10.0.tgz", - "integrity": "sha512-ITxOGo7rO3XRMiKA5l7tQ43iNNu+iXGFAcf2t+aWVzzqRaS0i7m1K2BhxNdaveB+5eENhO0VY1FkiZzhBk4v3A==", - "dev": true, - "license": "Apache-2.0", - "bin": { - "openai": "bin/cli" - }, - "peerDependencies": { - "ws": "^8.18.0", - "zod": "^3.25 || ^4.0" - }, - "peerDependenciesMeta": { - "ws": { - "optional": true - }, - "zod": { - "optional": true - } - } - }, - "node_modules/p-retry": { - "version": "7.1.1", - "resolved": "https://registry.npmjs.org/p-retry/-/p-retry-7.1.1.tgz", - "integrity": "sha512-J5ApzjyRkkf601HpEeykoiCvzHQjWxPAHhyjFcEUP2SWq0+35NKh8TLhpLw+Dkq5TZBFvUM6UigdE9hIVYTl5w==", - "dev": true, - "license": "MIT", - "dependencies": { - "is-network-error": "^1.1.0" - }, - "engines": { - "node": ">=20" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/pac-proxy-agent": { - "version": "7.2.0", - "resolved": "https://registry.npmjs.org/pac-proxy-agent/-/pac-proxy-agent-7.2.0.tgz", - "integrity": "sha512-TEB8ESquiLMc0lV8vcd5Ql/JAKAoyzHFXaStwjkzpOpC5Yv+pIzLfHvjTSdf3vpa2bMiUQrg9i6276yn8666aA==", - "dev": true, - "license": "MIT", - "dependencies": { - "@tootallnate/quickjs-emscripten": "^0.23.0", - "agent-base": "^7.1.2", - "debug": "^4.3.4", - "get-uri": "^6.0.1", - "http-proxy-agent": "^7.0.0", - "https-proxy-agent": "^7.0.6", - "pac-resolver": "^7.0.1", - "socks-proxy-agent": "^8.0.5" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/pac-resolver": { - "version": "7.0.1", - "resolved": "https://registry.npmjs.org/pac-resolver/-/pac-resolver-7.0.1.tgz", - "integrity": "sha512-5NPgf87AT2STgwa2ntRMr45jTKrYBGkVU36yT0ig/n/GMAa3oPqhZfIQ2kMEimReg0+t9kZViDVZ83qfVUlckg==", - "dev": true, - "license": "MIT", - "dependencies": { - "degenerator": "^5.0.0", - "netmask": "^2.0.2" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/package-json-from-dist": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz", - "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==", - "dev": true, - "license": "BlueOak-1.0.0" - }, - "node_modules/parse5": { - "version": "5.1.1", - "resolved": "https://registry.npmjs.org/parse5/-/parse5-5.1.1.tgz", - "integrity": "sha512-ugq4DFI0Ptb+WWjAdOK16+u/nHfiIrcE+sh8kZMaM0WllQKLI9rOUq6c2b7cwPkXdzfQESqvoqK6ug7U/Yyzug==", - "dev": true, - "license": "MIT" - }, - "node_modules/parse5-htmlparser2-tree-adapter": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/parse5-htmlparser2-tree-adapter/-/parse5-htmlparser2-tree-adapter-6.0.1.tgz", - "integrity": "sha512-qPuWvbLgvDGilKc5BoicRovlT4MtYT6JfJyBOMDsKoiT+GiuP5qyrPCnR9HcPECIJJmZh5jRndyNThnhhb/vlA==", - "dev": true, - "license": "MIT", - "dependencies": { - "parse5": "^6.0.1" - } - }, - "node_modules/parse5-htmlparser2-tree-adapter/node_modules/parse5": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/parse5/-/parse5-6.0.1.tgz", - "integrity": "sha512-Ofn/CTFzRGTTxwpNEs9PP93gXShHcTq255nzRYSKe8AkVpZY7e1fpmTfOyoIvjP5HG7Z2ZM7VS9PPhQGW2pOpw==", - "dev": true, - "license": "MIT" - }, - "node_modules/partial-json": { - "version": "0.1.7", - "resolved": "https://registry.npmjs.org/partial-json/-/partial-json-0.1.7.tgz", - "integrity": "sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==", - "dev": true, - "license": "MIT" - }, - "node_modules/path-key": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", - "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=8" - } - }, - "node_modules/path-scurry": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.1.tgz", - "integrity": "sha512-oWyT4gICAu+kaA7QWk/jvCHWarMKNs6pXOGWKDTr7cw4IGcUbW+PeTfbaQiLGheFRpjo6O9J0PmyMfQPjH71oA==", - "dev": true, - "license": "BlueOak-1.0.0", - "dependencies": { - "lru-cache": "^11.0.0", - "minipass": "^7.1.2" - }, - "engines": { - "node": "20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/preact": { - "version": "10.29.0", - "resolved": "https://registry.npmjs.org/preact/-/preact-10.29.0.tgz", - "integrity": "sha512-wSAGyk2bYR1c7t3SZ3jHcM6xy0lcBcDel6lODcs9ME6Th++Dx2KU+6D3HD8wMMKGA8Wpw7OMd3/4RGzYRpzwRg==", - "dev": true, - "license": "MIT", - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/preact" - } - }, - "node_modules/proper-lockfile": { - "version": "4.1.2", - "resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz", - "integrity": "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==", - "dev": true, - "license": "MIT", - "dependencies": { - "graceful-fs": "^4.2.4", - "retry": "^0.12.0", - "signal-exit": "^3.0.2" - } - }, - "node_modules/protobufjs": { - "version": "7.5.4", - "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.4.tgz", - "integrity": "sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg==", - "dev": true, - "hasInstallScript": true, - "license": "BSD-3-Clause", - "dependencies": { - "@protobufjs/aspromise": "^1.1.2", - "@protobufjs/base64": "^1.1.2", - "@protobufjs/codegen": "^2.0.4", - "@protobufjs/eventemitter": "^1.1.0", - "@protobufjs/fetch": "^1.1.0", - "@protobufjs/float": "^1.0.2", - "@protobufjs/inquire": "^1.1.0", - "@protobufjs/path": "^1.1.2", - "@protobufjs/pool": "^1.1.0", - "@protobufjs/utf8": "^1.1.0", - "@types/node": ">=13.7.0", - "long": "^5.0.0" - }, - "engines": { - "node": ">=12.0.0" - } - }, - "node_modules/proxy-agent": { - "version": "6.5.0", - "resolved": "https://registry.npmjs.org/proxy-agent/-/proxy-agent-6.5.0.tgz", - "integrity": "sha512-TmatMXdr2KlRiA2CyDu8GqR8EjahTG3aY3nXjdzFyoZbmB8hrBsTyMezhULIXKnC0jpfjlmiZ3+EaCzoInSu/A==", - "dev": true, - "license": "MIT", - "dependencies": { - "agent-base": "^7.1.2", - "debug": "^4.3.4", - "http-proxy-agent": "^7.0.1", - "https-proxy-agent": "^7.0.6", - "lru-cache": "^7.14.1", - "pac-proxy-agent": "^7.1.0", - "proxy-from-env": "^1.1.0", - "socks-proxy-agent": "^8.0.5" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/proxy-agent/node_modules/lru-cache": { - "version": "7.18.3", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-7.18.3.tgz", - "integrity": "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==", - "dev": true, - "license": "ISC", - "engines": { - "node": ">=12" - } - }, - "node_modules/proxy-from-env": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz", - "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==", - "dev": true, - "license": "MIT" - }, - "node_modules/react": { - "version": "19.2.4", - "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz", - "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==", - "dev": true, - "license": "MIT", - "peer": true, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/require-directory": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", - "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/require-from-string": { - "version": "2.0.2", - "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", - "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/retry": { - "version": "0.12.0", - "resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz", - "integrity": "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 4" - } - }, - "node_modules/rimraf": { - "version": "5.0.10", - "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-5.0.10.tgz", - "integrity": "sha512-l0OE8wL34P4nJH/H2ffoaniAokM2qSmrtXHmlpvYr5AVVX8msAyW0l8NVJFDxlSK4u3Uh/f41cQheDVdnYijwQ==", - "dev": true, - "license": "ISC", - "dependencies": { - "glob": "^10.3.7" - }, - "bin": { - "rimraf": "dist/esm/bin.mjs" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/rimraf/node_modules/@isaacs/cliui": { - "version": "8.0.2", - "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz", - "integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==", - "dev": true, - "license": "ISC", - "dependencies": { - "string-width": "^5.1.2", - "string-width-cjs": "npm:string-width@^4.2.0", - "strip-ansi": "^7.0.1", - "strip-ansi-cjs": "npm:strip-ansi@^6.0.1", - "wrap-ansi": "^8.1.0", - "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0" - }, - "engines": { - "node": ">=12" - } - }, - "node_modules/rimraf/node_modules/ansi-regex": { - "version": "6.2.2", - "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz", - "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/chalk/ansi-regex?sponsor=1" - } - }, - "node_modules/rimraf/node_modules/ansi-styles": { - "version": "6.2.3", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz", - "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/chalk/ansi-styles?sponsor=1" - } - }, - "node_modules/rimraf/node_modules/balanced-match": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", - "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", - "dev": true, - "license": "MIT" - }, - "node_modules/rimraf/node_modules/brace-expansion": { - "version": "2.0.2", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", - "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", - "dev": true, - "license": "MIT", - "dependencies": { - "balanced-match": "^1.0.0" - } - }, - "node_modules/rimraf/node_modules/emoji-regex": { - "version": "9.2.2", - "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz", - "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==", - "dev": true, - "license": "MIT" - }, - "node_modules/rimraf/node_modules/glob": { - "version": "10.5.0", - "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz", - "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==", - "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me", - "dev": true, - "license": "ISC", - "dependencies": { - "foreground-child": "^3.1.0", - "jackspeak": "^3.1.2", - "minimatch": "^9.0.4", - "minipass": "^7.1.2", - "package-json-from-dist": "^1.0.0", - "path-scurry": "^1.11.1" - }, - "bin": { - "glob": "dist/esm/bin.mjs" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/rimraf/node_modules/jackspeak": { - "version": "3.4.3", - "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-3.4.3.tgz", - "integrity": "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==", - "dev": true, - "license": "BlueOak-1.0.0", - "dependencies": { - "@isaacs/cliui": "^8.0.2" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - }, - "optionalDependencies": { - "@pkgjs/parseargs": "^0.11.0" - } - }, - "node_modules/rimraf/node_modules/lru-cache": { - "version": "10.4.3", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz", - "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==", - "dev": true, - "license": "ISC" - }, - "node_modules/rimraf/node_modules/minimatch": { - "version": "9.0.5", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz", - "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==", - "dev": true, - "license": "ISC", - "dependencies": { - "brace-expansion": "^2.0.1" - }, - "engines": { - "node": ">=16 || 14 >=14.17" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/rimraf/node_modules/path-scurry": { - "version": "1.11.1", - "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-1.11.1.tgz", - "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==", - "dev": true, - "license": "BlueOak-1.0.0", - "dependencies": { - "lru-cache": "^10.2.0", - "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0" - }, - "engines": { - "node": ">=16 || 14 >=14.18" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/rimraf/node_modules/string-width": { - "version": "5.1.2", - "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz", - "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==", - "dev": true, - "license": "MIT", - "dependencies": { - "eastasianwidth": "^0.2.0", - "emoji-regex": "^9.2.2", - "strip-ansi": "^7.0.1" - }, - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/rimraf/node_modules/strip-ansi": { - "version": "7.1.2", - "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.2.tgz", - "integrity": "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==", - "dev": true, - "license": "MIT", - "dependencies": { - "ansi-regex": "^6.0.1" - }, - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/chalk/strip-ansi?sponsor=1" - } - }, - "node_modules/rimraf/node_modules/wrap-ansi": { - "version": "8.1.0", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz", - "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==", - "dev": true, - "license": "MIT", - "dependencies": { - "ansi-styles": "^6.1.0", - "string-width": "^5.0.1", - "strip-ansi": "^7.0.1" - }, - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/chalk/wrap-ansi?sponsor=1" - } - }, - "node_modules/safe-buffer": { - "version": "5.2.1", - "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", - "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==", - "dev": true, - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/feross" - }, - { - "type": "patreon", - "url": "https://www.patreon.com/feross" - }, - { - "type": "consulting", - "url": "https://feross.org/support" - } - ], - "license": "MIT" - }, - "node_modules/shebang-command": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", - "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", - "dev": true, - "license": "MIT", - "dependencies": { - "shebang-regex": "^3.0.0" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/shebang-regex": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", - "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=8" - } - }, - "node_modules/signal-exit": { - "version": "3.0.7", - "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz", - "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", - "dev": true, - "license": "ISC" - }, - "node_modules/smart-buffer": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz", - "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 6.0.0", - "npm": ">= 3.0.0" - } - }, - "node_modules/socks": { - "version": "2.8.7", - "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.7.tgz", - "integrity": "sha512-HLpt+uLy/pxB+bum/9DzAgiKS8CX1EvbWxI4zlmgGCExImLdiad2iCwXT5Z4c9c3Eq8rP2318mPW2c+QbtjK8A==", - "dev": true, - "license": "MIT", - "dependencies": { - "ip-address": "^10.0.1", - "smart-buffer": "^4.2.0" - }, - "engines": { - "node": ">= 10.0.0", - "npm": ">= 3.0.0" - } - }, - "node_modules/socks-proxy-agent": { - "version": "8.0.5", - "resolved": "https://registry.npmjs.org/socks-proxy-agent/-/socks-proxy-agent-8.0.5.tgz", - "integrity": "sha512-HehCEsotFqbPW9sJ8WVYB6UbmIMv7kUUORIF2Nncq4VQvBfNBLibW9YZR5dlYCSUhwcD628pRllm7n+E+YTzJw==", - "dev": true, - "license": "MIT", - "dependencies": { - "agent-base": "^7.1.2", - "debug": "^4.3.4", - "socks": "^2.8.3" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/source-map": { - "version": "0.6.1", - "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", - "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", - "dev": true, - "license": "BSD-3-Clause", - "optional": true, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/std-env": { - "version": "3.10.0", - "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz", - "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==", - "dev": true, - "license": "MIT" - }, - "node_modules/string-width": { - "version": "4.2.3", - "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", - "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", - "dev": true, - "license": "MIT", - "dependencies": { - "emoji-regex": "^8.0.0", - "is-fullwidth-code-point": "^3.0.0", - "strip-ansi": "^6.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/string-width-cjs": { - "name": "string-width", - "version": "4.2.3", - "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", - "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", - "dev": true, - "license": "MIT", - "dependencies": { - "emoji-regex": "^8.0.0", - "is-fullwidth-code-point": "^3.0.0", - "strip-ansi": "^6.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/strip-ansi": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", - "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", - "dev": true, - "license": "MIT", - "dependencies": { - "ansi-regex": "^5.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/strip-ansi-cjs": { - "name": "strip-ansi", - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", - "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", - "dev": true, - "license": "MIT", - "dependencies": { - "ansi-regex": "^5.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/strnum": { - "version": "2.1.2", - "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.1.2.tgz", - "integrity": "sha512-l63NF9y/cLROq/yqKXSLtcMeeyOfnSQlfMSlzFt/K73oIaD8DGaQWd7Z34X9GPiKqP5rbSh84Hl4bOlLcjiSrQ==", - "dev": true, - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } - ], - "license": "MIT" - }, - "node_modules/strtok3": { - "version": "10.3.4", - "resolved": "https://registry.npmjs.org/strtok3/-/strtok3-10.3.4.tgz", - "integrity": "sha512-KIy5nylvC5le1OdaaoCJ07L+8iQzJHGH6pWDuzS+d07Cu7n1MZ2x26P8ZKIWfbK02+XIL8Mp4RkWeqdUCrDMfg==", - "dev": true, - "license": "MIT", - "dependencies": { - "@tokenizer/token": "^0.3.0" - }, - "engines": { - "node": ">=18" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/Borewit" - } - }, - "node_modules/supports-color": { - "version": "7.2.0", - "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", - "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", - "dev": true, - "license": "MIT", - "dependencies": { - "has-flag": "^4.0.0" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/thenify": { - "version": "3.3.1", - "resolved": "https://registry.npmjs.org/thenify/-/thenify-3.3.1.tgz", - "integrity": "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==", - "dev": true, - "license": "MIT", - "dependencies": { - "any-promise": "^1.0.0" - } - }, - "node_modules/thenify-all": { - "version": "1.6.0", - "resolved": "https://registry.npmjs.org/thenify-all/-/thenify-all-1.6.0.tgz", - "integrity": "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==", - "dev": true, - "license": "MIT", - "dependencies": { - "thenify": ">= 3.1.0 < 4" - }, - "engines": { - "node": ">=0.8" - } - }, - "node_modules/token-types": { - "version": "6.1.2", - "resolved": "https://registry.npmjs.org/token-types/-/token-types-6.1.2.tgz", - "integrity": "sha512-dRXchy+C0IgK8WPC6xvCHFRIWYUbqqdEIKPaKo/AcTUNzwLTK6AH7RjdLWsEZcAN/TBdtfUw3PYEgPr5VPr6ww==", - "dev": true, - "license": "MIT", - "dependencies": { - "@borewit/text-codec": "^0.2.1", - "@tokenizer/token": "^0.3.0", - "ieee754": "^1.2.1" - }, - "engines": { - "node": ">=14.16" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/Borewit" - } - }, - "node_modules/ts-algebra": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/ts-algebra/-/ts-algebra-2.0.0.tgz", - "integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==", - "dev": true, - "license": "MIT" - }, - "node_modules/tslib": { - "version": "2.8.1", - "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", - "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", - "dev": true, - "license": "0BSD" - }, - "node_modules/typescript": { - "version": "5.9.3", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", - "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", - "dev": true, - "license": "Apache-2.0", - "bin": { - "tsc": "bin/tsc", - "tsserver": "bin/tsserver" - }, - "engines": { - "node": ">=14.17" - } - }, - "node_modules/uint8array-extras": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/uint8array-extras/-/uint8array-extras-1.5.0.tgz", - "integrity": "sha512-rvKSBiC5zqCCiDZ9kAOszZcDvdAHwwIKJG33Ykj43OKcWsnmcBRL09YTU4nOeHZ8Y2a7l1MgTd08SBe9A8Qj6A==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=18" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/undici": { - "version": "7.21.0", - "resolved": "https://registry.npmjs.org/undici/-/undici-7.21.0.tgz", - "integrity": "sha512-Hn2tCQpoDt1wv23a68Ctc8Cr/BHpUSfaPYrkajTXOS9IKpxVRx/X5m1K2YkbK2ipgZgxXSgsUinl3x+2YdSSfg==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=20.18.1" - } - }, - "node_modules/undici-types": { - "version": "7.16.0", - "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz", - "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==", - "dev": true, - "license": "MIT" - }, - "node_modules/use-sync-external-store": { - "version": "1.6.0", - "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz", - "integrity": "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==", - "dev": true, - "license": "MIT", - "peerDependencies": { - "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" - } - }, - "node_modules/web-streams-polyfill": { - "version": "3.3.3", - "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz", - "integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 8" - } - }, - "node_modules/which": { - "version": "2.0.2", - "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", - "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", - "dev": true, - "license": "ISC", - "dependencies": { - "isexe": "^2.0.0" - }, - "bin": { - "node-which": "bin/node-which" - }, - "engines": { - "node": ">= 8" - } - }, - "node_modules/wrap-ansi": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", - "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", - "dev": true, - "license": "MIT", - "dependencies": { - "ansi-styles": "^4.0.0", - "string-width": "^4.1.0", - "strip-ansi": "^6.0.0" - }, - "engines": { - "node": ">=10" - }, - "funding": { - "url": "https://github.com/chalk/wrap-ansi?sponsor=1" - } - }, - "node_modules/wrap-ansi-cjs": { - "name": "wrap-ansi", - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", - "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", - "dev": true, - "license": "MIT", - "dependencies": { - "ansi-styles": "^4.0.0", - "string-width": "^4.1.0", - "strip-ansi": "^6.0.0" - }, - "engines": { - "node": ">=10" - }, - "funding": { - "url": "https://github.com/chalk/wrap-ansi?sponsor=1" - } - }, - "node_modules/ws": { - "version": "8.19.0", - "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz", - "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=10.0.0" - }, - "peerDependencies": { - "bufferutil": "^4.0.1", - "utf-8-validate": ">=5.0.2" - }, - "peerDependenciesMeta": { - "bufferutil": { - "optional": true - }, - "utf-8-validate": { - "optional": true - } - } - }, - "node_modules/y18n": { - "version": "5.0.8", - "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", - "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", - "dev": true, - "license": "ISC", - "engines": { - "node": ">=10" - } - }, - "node_modules/yaml": { - "version": "2.8.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz", - "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==", - "dev": true, - "license": "ISC", - "bin": { - "yaml": "bin.mjs" - }, - "engines": { - "node": ">= 14.6" - }, - "funding": { - "url": "https://github.com/sponsors/eemeli" - } - }, - "node_modules/yargs": { - "version": "16.2.0", - "resolved": "https://registry.npmjs.org/yargs/-/yargs-16.2.0.tgz", - "integrity": "sha512-D1mvvtDG0L5ft/jGWkLpG1+m0eQxOfaBvTNELraWj22wSVUMWxZUvYgJYcKh6jGGIkJFhH4IZPQhR4TKpc8mBw==", - "dev": true, - "license": "MIT", - "dependencies": { - "cliui": "^7.0.2", - "escalade": "^3.1.1", - "get-caller-file": "^2.0.5", - "require-directory": "^2.1.1", - "string-width": "^4.2.0", - "y18n": "^5.0.5", - "yargs-parser": "^20.2.2" - }, - "engines": { - "node": ">=10" - } - }, - "node_modules/yargs-parser": { - "version": "20.2.9", - "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.9.tgz", - "integrity": "sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==", - "dev": true, - "license": "ISC", - "engines": { - "node": ">=10" - } - }, - "node_modules/yoctocolors": { - "version": "2.1.2", - "resolved": "https://registry.npmjs.org/yoctocolors/-/yoctocolors-2.1.2.tgz", - "integrity": "sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=18" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/zod": { - "version": "4.3.6", - "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz", - "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==", - "dev": true, - "license": "MIT", - "peer": true, - "funding": { - "url": "https://github.com/sponsors/colinhacks" - } - }, - "node_modules/zod-to-json-schema": { - "version": "3.25.1", - "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.1.tgz", - "integrity": "sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==", - "dev": true, - "license": "ISC", - "peerDependencies": { - "zod": "^3.25 || ^4" - } - }, - "node_modules/zustand": { - "version": "4.5.7", - "resolved": "https://registry.npmjs.org/zustand/-/zustand-4.5.7.tgz", - "integrity": "sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==", - "dev": true, - "license": "MIT", - "dependencies": { - "use-sync-external-store": "^1.2.2" - }, - "engines": { - "node": ">=12.7.0" - }, - "peerDependencies": { - "@types/react": ">=16.8", - "immer": ">=9.0.6", - "react": ">=16.8" - }, - "peerDependenciesMeta": { - "@types/react": { - "optional": true - }, - "immer": { - "optional": true - }, - "react": { - "optional": true - } - } - } - } -} diff --git a/package.json b/package.json deleted file mode 100644 index 2f27a2b..0000000 --- a/package.json +++ /dev/null @@ -1,43 +0,0 @@ -{ - "name": "@solatis/koan", - "version": "0.0.1", - "description": "Opinionated workflow resources for the pi coding agent.", - "private": true, - "license": "Apache-2.0", - "type": "module", - "keywords": [ - "pi-package", - "pi-extension", - "koan" - ], - "pi": { - "extensions": [ - "./extensions" - ] - }, - "files": [ - "extensions", - "src", - "resources", - "README.md", - "LICENSE" - ], - "scripts": { - "check": "tsc --noEmit", - "build:web": "esbuild src/planner/web/js/app.jsx --bundle --format=esm --jsx=automatic --jsx-import-source=preact --alias:react=preact/compat --alias:react-dom=preact/compat --outfile=src/planner/web/dist/app.js --minify", - "build": "npm run build:web && tsc --project tsconfig.build.json && cp -r src/planner/web/css src/planner/web/html build/src/planner/web/", - "pretest": "npm run build", - "test": "node --test --test-concurrency=1 build/tests" - }, - "dependencies": { - "@sinclair/typebox": "^0.32.30", - "marked": "^17.0.5" - }, - "devDependencies": { - "@mariozechner/pi-coding-agent": "^0.52.10", - "esbuild": "^0.25.1", - "preact": "^10.26.2", - "typescript": "^5.9.3", - "zustand": "^4.5.7" - } -} diff --git a/src/planner/conversation.ts b/src/planner/conversation.ts deleted file mode 100644 index bc51285..0000000 --- a/src/planner/conversation.ts +++ /dev/null @@ -1,35 +0,0 @@ -// Export the parent session conversation to a JSONL file in the epic directory. -// -// The output is raw pi SessionManager entries — NOT a plain-text transcript. -// Each line is a JSON-serialized session entry (header first, then branch entries). -// -// Agents reading this file should look for entries with type "message" and -// role "user" or "assistant" for conversation content. Entries with type -// "compaction" contain synthesized summaries of earlier context. Internal -// session management entries should be ignored. -// -// The file is write-once from the driver's perspective — planning phases read it. - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { ExtensionContext } from "@mariozechner/pi-coding-agent"; - -// Export the current conversation branch as a JSONL file. -// Returns the absolute path to the written file. -export async function exportConversation( - sessionManager: ExtensionContext["sessionManager"], - planDir: string, -): Promise { - const filePath = path.join(planDir, "conversation.jsonl"); - - const header = sessionManager.getHeader(); - const branch = sessionManager.getBranch(); - - const lines: string[] = []; - if (header) lines.push(JSON.stringify(header)); - for (const entry of branch) lines.push(JSON.stringify(entry)); - - await fs.writeFile(filePath, `${lines.join("\n")}\n`, "utf8"); - return filePath; -} diff --git a/src/planner/driver.ts b/src/planner/driver.ts deleted file mode 100644 index ee1e7e6..0000000 --- a/src/planner/driver.ts +++ /dev/null @@ -1,525 +0,0 @@ -// Epic pipeline driver — deterministic coordinator for the full epic lifecycle. -// Reads JSON state and exit codes; applies routing rules. Never parses markdown. -// Per AGENTS.md: driver owns .json state; LLMs own .md files. -// -// Spawn pattern used throughout: spawnSubagent(task, subagentDir, opts). -// epicDir is part of the task (written to task.json) rather than SpawnOptions -// because it is subagent configuration, not process infrastructure. SpawnOptions -// holds only what the OS-level spawn needs: cwd, extensionPath, model, webServer, -// and the debug mode flag. - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import { - loadEpicState, - saveEpicState, - loadStoryState, - saveStoryState, - loadAllStoryStates, - ensureSubagentDirectory, - ensureStoryDirectory, - discoverStoryIds, - readWorkflowDecision, -} from "./epic/state.js"; -import { listArtifacts } from "./epic/artifacts.js"; -import { spawnSubagent, type SpawnOptions, type SubagentResult } from "./subagent.js"; -import type { SubagentTask, WorkflowOrchestratorTask } from "./lib/task.js"; -import type { Logger } from "../utils/logger.js"; -import type { StoryState } from "./epic/types.js"; -import type { WebServerHandle } from "./web/server-types.js"; -import type { SubagentRole, EpicPhase } from "./types.js"; -import { - getSuccessorPhases, - isAutoAdvance, - isStubPhase, - isValidTransition, - PHASE_DESCRIPTIONS, -} from "./lib/phase-dag.js"; - -// --------------------------------------------------------------------------- -// readStoryTitle -// --------------------------------------------------------------------------- - -async function readStoryTitle(epicDir: string, storyId: string): Promise { - try { - const raw = await fs.readFile(path.join(epicDir, "stories", storyId, "story.md"), "utf8"); - for (const rawLine of raw.split("\n")) { - const l = rawLine.trim(); - if (!l) continue; - const text = l.replace(/^#+\s*/, "").trim(); - if (text) return text.slice(0, 80); - } - return storyId; - } catch { - return storyId; - } -} - -// --------------------------------------------------------------------------- -// Routing (dormant — used when execution phase is implemented) -// --------------------------------------------------------------------------- - -interface RoutingDecision { - action: "execute" | "retry" | "complete" | "error"; - storyId?: string; - error?: string; -} - -function routeFromState(stories: StoryState[], log: Logger): RoutingDecision { - // retry is checked before selected — a story queued for retry takes - // precedence over a newly selected story. - const retry = stories.find((s) => s.status === "retry"); - if (retry) { - log("Routing: retry", { storyId: retry.storyId }); - return { action: "retry", storyId: retry.storyId }; - } - - const selected = stories.find((s) => s.status === "selected"); - if (selected) { - log("Routing: execute", { storyId: selected.storyId }); - return { action: "execute", storyId: selected.storyId }; - } - - // Terminal states are exactly "done" and "skipped". - const terminal = new Set(["done", "skipped"]); - const allTerminal = stories.every((s) => terminal.has(s.status)); - if (allTerminal && stories.length > 0) { - log("Routing: complete", { total: stories.length }); - return { action: "complete" }; - } - - return { - action: "error", - error: "No actionable story state found (orchestrator may have exited without a routing decision)", - }; -} - -// --------------------------------------------------------------------------- -// spawnTracked -// --------------------------------------------------------------------------- - -/** - * Owns the web-server lifecycle (register -> track -> spawn -> clear -> complete) - * for a single subagent invocation. - * - * Does not own story status transitions -- those remain in the callers - * (runStoryExecution, runStoryReexecution). - * - * Full DI of spawnSubagent is out of scope: driver.ts is an entry point, - * exempt from the "no hard-coded dependencies" rule per project conventions. - */ -async function spawnTracked( - id: string, - name: string, - role: string, - task: SubagentTask, - dir: string, - storyId: string | undefined, - opts: SpawnOptions, - webServer: WebServerHandle | null, -): Promise { - webServer?.registerAgent({ id, name, dir, role, model: null, parent: null }); - webServer?.trackSubagent(dir, role, storyId); - const result = await spawnSubagent(task, dir, opts); - webServer?.clearSubagent(); - webServer?.completeAgent(id); - return result; -} - -// --------------------------------------------------------------------------- -// Phase role mapping -// --------------------------------------------------------------------------- - -/** Maps implemented phases to the subagent role that executes them. - * Stubs are not listed — they never spawn a subagent. */ -const PHASE_ROLE: Partial> = { - "intake": "intake", - "brief-generation": "brief-writer", -}; - -// --------------------------------------------------------------------------- -// Phase runners -// --------------------------------------------------------------------------- - -async function runSimplePhase( - role: SubagentRole, - epicDir: string, - cwd: string, - extensionPath: string, - log: Logger, - webServer: WebServerHandle | null, - debugMode: boolean, - phaseInstructions?: string, -): Promise { - const subagentDir = await ensureSubagentDirectory(epicDir, role); - const opts: SpawnOptions = { cwd, extensionPath, log, webServer: webServer ?? undefined, debugMode }; - const task = (phaseInstructions - ? { role, epicDir, phaseInstructions } - : { role, epicDir }) as SubagentTask; - const result = await spawnTracked(role, role, role, task, subagentDir, undefined, opts, webServer); - if (result.exitCode !== 0) { - log(`${role} phase failed`, { exitCode: result.exitCode }); - return false; - } - return true; -} - -async function runPhase( - phase: EpicPhase, - epicDir: string, - cwd: string, - extensionPath: string, - log: Logger, - webServer: WebServerHandle | null, - debugMode: boolean, - phaseInstructions?: string, -): Promise { - const role = PHASE_ROLE[phase]; - if (!role) { - // Should never happen — isStubPhase() guards this in the loop above. - throw new Error(`No role mapping for implemented phase: ${phase}`); - } - return runSimplePhase(role, epicDir, cwd, extensionPath, log, webServer, debugMode, phaseInstructions); -} - -// --------------------------------------------------------------------------- -// Story execution helpers (dormant — used when execution phase is implemented) -// --------------------------------------------------------------------------- - -async function runStoryExecution( - epicDir: string, - cwd: string, - extensionPath: string, - storyId: string, - log: Logger, - webServer: WebServerHandle | null, - debugMode: boolean, -): Promise { - const opts: SpawnOptions = { cwd, extensionPath, log, webServer: webServer ?? undefined, debugMode }; - - // 1. Set status to 'planning'. - const story = await loadStoryState(epicDir, storyId); - await saveStoryState(epicDir, storyId, { ...story, status: "planning", updatedAt: new Date().toISOString() }); - - // 2. Spawn planner. - const plannerDir = await ensureSubagentDirectory(epicDir, `planner-${storyId}`); - const plannerId = `planner-${storyId}`; - const planResult = await spawnTracked(plannerId, `planner-${storyId}`, "planner", { role: "planner", epicDir, storyId }, plannerDir, storyId, opts, webServer); - - if (planResult.exitCode !== 0) { - // Planner failed — skip executor, proceed directly to post-execution - // orchestrator so it can make a routing decision (retry or skip). - log("Planner failed — skipping executor, proceeding to post-execution orchestrator", { - storyId, exitCode: planResult.exitCode, - }); - - const s2 = await loadStoryState(epicDir, storyId); - await saveStoryState(epicDir, storyId, { ...s2, status: "verifying", updatedAt: new Date().toISOString() }); - - const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}`); - const postId = `orchestrator-post-${storyId}`; - await spawnTracked(postId, `orchestrator-post-${storyId}`, "orchestrator", { role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, storyId, opts, webServer); - return; - } - - // 3. Set status to 'executing'. - const s3 = await loadStoryState(epicDir, storyId); - await saveStoryState(epicDir, storyId, { ...s3, status: "executing", updatedAt: new Date().toISOString() }); - - // 4. Spawn executor. - const execDir = await ensureSubagentDirectory(epicDir, `executor-${storyId}`); - const execId = `executor-${storyId}`; - const execResult = await spawnTracked(execId, `executor-${storyId}`, "executor", { role: "executor", epicDir, storyId }, execDir, storyId, opts, webServer); - - if (execResult.exitCode !== 0) { - log("Executor failed", { storyId, exitCode: execResult.exitCode }); - } - - // 5. Set status to 'verifying'. - const s4 = await loadStoryState(epicDir, storyId); - await saveStoryState(epicDir, storyId, { ...s4, status: "verifying", updatedAt: new Date().toISOString() }); - - // 6. Spawn orchestrator (post-execution). - const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}`); - const postId = `orchestrator-post-${storyId}`; - await spawnTracked(postId, `orchestrator-post-${storyId}`, "orchestrator", { role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, storyId, opts, webServer); -} - -async function runStoryReexecution( - epicDir: string, - cwd: string, - extensionPath: string, - storyId: string, - retryCount: number, - failureContext: string | undefined, - log: Logger, - webServer: WebServerHandle | null, - debugMode: boolean, -): Promise { - const opts: SpawnOptions = { cwd, extensionPath, log, webServer: webServer ?? undefined, debugMode }; - - const execDir = await ensureSubagentDirectory(epicDir, `executor-${storyId}-retry-${retryCount}`); - const execId = `executor-${storyId}-retry-${retryCount}`; - // retryContext flows from koan_retry_story's failure_summary into the task - // manifest, where the executor reads it from step 1 guidance. - await spawnTracked(execId, `executor-${storyId}-retry-${retryCount}`, "executor", { role: "executor", epicDir, storyId, retryContext: failureContext }, execDir, storyId, opts, webServer); - - const story = await loadStoryState(epicDir, storyId); - await saveStoryState(epicDir, storyId, { ...story, status: "verifying", updatedAt: new Date().toISOString() }); - - const postDir = await ensureSubagentDirectory(epicDir, `orchestrator-post-${storyId}-retry-${retryCount}`); - const postId = `orchestrator-post-${storyId}-retry-${retryCount}`; - await spawnTracked(postId, `orchestrator-post-${storyId}-retry-${retryCount}`, "orchestrator", { role: "orchestrator", epicDir, stepSequence: "post-execution", storyId }, postDir, storyId, opts, webServer); -} - -async function refreshWebServerStories(epicDir: string, webServer: WebServerHandle): Promise { - try { - const stories = await loadAllStoryStates(epicDir); - webServer.pushStories(stories.map((s) => ({ storyId: s.storyId, status: s.status }))); - } catch { - // Non-fatal - } -} - -async function runStoryLoop( - epicDir: string, - cwd: string, - extensionPath: string, - log: Logger, - webServer: WebServerHandle | null, - debugMode: boolean, -): Promise<{ success: boolean; summary: string }> { - { - // 1. Spawn orchestrator (pre-execution) — selects first story. - const preDir = await ensureSubagentDirectory(epicDir, "orchestrator-pre"); - const preId = "orchestrator-pre"; - const opts: SpawnOptions = { cwd, extensionPath, log, webServer: webServer ?? undefined, debugMode }; - const preResult = await spawnTracked(preId, "orchestrator-pre", "orchestrator", { role: "orchestrator", epicDir, stepSequence: "pre-execution" }, preDir, undefined, opts, webServer); - - if (preResult.exitCode !== 0) { - return { success: false, summary: "Pre-execution orchestrator failed" }; - } - - if (webServer) await refreshWebServerStories(epicDir, webServer); - - // 2. Story execution loop — route until terminal state. - while (true) { - const stories = await loadAllStoryStates(epicDir); - webServer?.pushStories(stories.map((s) => ({ storyId: s.storyId, status: s.status }))); - - const routing = routeFromState(stories, log); - - switch (routing.action) { - case "execute": { - const storyId = routing.storyId as string; - await runStoryExecution(epicDir, cwd, extensionPath, storyId, log, webServer, debugMode); - if (webServer) await refreshWebServerStories(epicDir, webServer); - break; - } - - case "retry": { - const storyId = routing.storyId as string; - const story = stories.find((s) => s.storyId === storyId) as StoryState; - - if (story.retryCount >= story.maxRetries) { - log("Retry budget exhausted, skipping story", { storyId, retryCount: story.retryCount }); - await saveStoryState(epicDir, storyId, { - ...story, - status: "skipped", - skipReason: `Retry budget exhausted after ${story.retryCount} attempt(s). Last failure: ${story.failureSummary ?? "(none recorded)"}`, - updatedAt: new Date().toISOString(), - }); - webServer?.pushNotification( - `Story ${storyId} skipped after ${story.retryCount} failed attempt(s).`, - "warning", - ); - if (webServer) await refreshWebServerStories(epicDir, webServer); - continue; - } - - await saveStoryState(epicDir, storyId, { - ...story, - status: "executing", - retryCount: story.retryCount + 1, - updatedAt: new Date().toISOString(), - }); - await runStoryReexecution(epicDir, cwd, extensionPath, storyId, story.retryCount + 1, story.failureSummary, log, webServer, debugMode); - if (webServer) await refreshWebServerStories(epicDir, webServer); - break; - } - - case "complete": { - const done = stories.filter((s) => s.status === "done").length; - const skipped = stories.filter((s) => s.status === "skipped").length; - return { success: true, summary: `Epic complete: ${done} done, ${skipped} skipped` }; - } - - case "error": - return { success: false, summary: routing.error as string }; - } - } - } -} - -// --------------------------------------------------------------------------- -// Workflow orchestrator helpers -// --------------------------------------------------------------------------- - -/** Write {epicDir}/workflow-status.md — a markdown bridge from driver JSON - * state to the orchestrator LLM's context. Called before orchestrator spawn. - * - * completedPhase is the single just-completed phase (not a history). - * The driver does not maintain a phase history array; the orchestrator - * infers prior phases from the artifacts present in epicDir. */ -async function writeWorkflowStatus( - epicDir: string, - completedPhase: EpicPhase, - availablePhases: readonly EpicPhase[], -): Promise { - const artifacts = await listArtifacts(epicDir); - const lines = [ - "# Workflow Status", "", - "## Current Position", "", - `The **${completedPhase}** phase has just completed.`, "", - "## Available Next Phases", "", - ...availablePhases.map((p) => `- **${p}** — ${PHASE_DESCRIPTIONS[p]}`), - "", "## Artifacts Available", "", - ...artifacts.map((a) => `- \`${a.path}\``), - ]; - await fs.writeFile(path.join(epicDir, "workflow-status.md"), lines.join("\n"), "utf8"); -} - -async function runWorkflowOrchestrator( - completedPhase: EpicPhase, - availablePhases: readonly EpicPhase[], - epicDir: string, - cwd: string, - extensionPath: string, - log: Logger, - webServer: WebServerHandle, - debugMode: boolean, -): Promise<{ nextPhase: EpicPhase; instructions?: string } | null> { - await writeWorkflowStatus(epicDir, completedPhase, availablePhases); - - const task: WorkflowOrchestratorTask = { - role: "workflow-orchestrator", - epicDir, - completedPhase, - availablePhases: availablePhases as EpicPhase[], - }; - - // Timestamp ensures no stale workflow-decision.json from a crashed run - // is accidentally read on restart. - const dirLabel = `workflow-orch-${completedPhase}-${Date.now()}`; - const dir = await ensureSubagentDirectory(epicDir, dirLabel); - const id = `workflow-orchestrator-${completedPhase}`; - const opts: SpawnOptions = { cwd, extensionPath, log, webServer, debugMode }; - const result = await spawnTracked(id, id, "workflow-orchestrator", task, dir, undefined, opts, webServer); - - if (result.exitCode !== 0) { - log("Workflow orchestrator failed", { exitCode: result.exitCode, completedPhase }); - return null; - } - - const decision = await readWorkflowDecision(dir); - if (!decision) { - log("Workflow orchestrator exited without committing a decision", { completedPhase }); - return null; - } - if (!isValidTransition(completedPhase, decision.nextPhase as EpicPhase)) { - log("Workflow orchestrator committed an invalid transition", { - completedPhase, nextPhase: decision.nextPhase, - }); - return null; - } - - return { nextPhase: decision.nextPhase as EpicPhase, instructions: decision.instructions }; -} - -// --------------------------------------------------------------------------- -// Public API -// --------------------------------------------------------------------------- - -export async function runPipeline( - epicDir: string, - cwd: string, - extensionPath: string, - log: Logger, - webServer: WebServerHandle | null, - opts: { debugMode: boolean } = { debugMode: false }, -): Promise<{ success: boolean; summary: string }> { - const { debugMode } = opts; - const epicState = await loadEpicState(epicDir); - - // Model config gate — blocks until user confirms model selection in the web UI. - if (webServer) { - await webServer.requestModelConfig(); - } - - let phase: EpicPhase = "intake"; - let pendingInstructions: string | undefined; - - while (phase !== "completed") { - await saveEpicState(epicDir, { ...epicState, phase }); - webServer?.pushPhase(phase); - - if (isStubPhase(phase)) { - // Stub phases register in the DAG but perform no subagent work. - // pendingInstructions are carried forward — stubs don't consume them. - log(`Phase "${phase}" is a placeholder — auto-advancing`, { phase }); - } else { - const phaseOk = await runPhase(phase, epicDir, cwd, extensionPath, log, webServer, debugMode, pendingInstructions); - // Consumed by the real phase — clear regardless of success. - pendingInstructions = undefined; - if (!phaseOk) return { success: false, summary: `Phase "${phase}" failed` }; - } - - const successors = getSuccessorPhases(phase); - if (successors.length === 0) { - // Terminal or unknown phase — break and let the completed handler run. - break; - } - - if (isAutoAdvance(phase)) { - // Single successor — unambiguous, advance at zero cost. - phase = successors[0]; - continue; - } - - // Multiple successors: requires user direction. - // In headless mode (no webServer), the orchestrator cannot run because - // koan_propose_workflow requires requestWorkflowDecision() on the server - // and the IPC responder is not started. Auto-advance to the recommended - // (first) successor to preserve CI correctness. - if (!webServer) { - log("No web server — auto-advancing to recommended phase (headless mode)", { - from: phase, to: successors[0], - }); - phase = successors[0]; - continue; - } - - // Snapshot the completed phase's activity before spawning the orchestrator. - // trackSubagent() for the orchestrator will replace the live log buffer; - // freezeLogs() preserves the phase's final state for the frozen zone in - // the ActivityFeed. - webServer.freezeLogs(); - - const decision = await runWorkflowOrchestrator( - phase, successors, epicDir, cwd, extensionPath, log, webServer, debugMode, - ); - if (!decision) { - return { success: false, summary: `Workflow orchestrator failed after "${phase}"` }; - } - phase = decision.nextPhase; - pendingInstructions = decision.instructions; - } - - // Save "completed" as the final pipeline state. - await saveEpicState(epicDir, { ...epicState, phase: "completed" }); - webServer?.pushPhase("completed"); - - return { success: true, summary: "Pipeline completed successfully" }; -} - diff --git a/src/planner/epic/artifacts.ts b/src/planner/epic/artifacts.ts deleted file mode 100644 index a39d2cc..0000000 --- a/src/planner/epic/artifacts.ts +++ /dev/null @@ -1,107 +0,0 @@ -// Epic artifact I/O -- list, read, and write markdown artifacts within an epic directory. -// All writes use atomic tmp+rename to prevent partial reads during concurrent access. -// Artifacts are .md files in the epic root and under stories/ (excluding subagents/). - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -// -- Types -- - -export interface ArtifactEntry { - path: string; - size: number; - modifiedAt: string; -} - -// -- Scope -- - -export function isArtifactInScope(relativePath: string): boolean { - const norm = path.normalize(relativePath); - if (!norm.endsWith(".md")) return false; - const segments = norm.split(path.sep); - if (segments.includes("subagents")) return false; - // Must be root-level or under stories/ - return segments.length === 1 || segments[0] === "stories"; -} - -// -- List -- - -export async function listArtifacts(epicDir: string): Promise { - const results: ArtifactEntry[] = []; - - // Pass 1: epic root .md files - const rootEntries = await fs.readdir(epicDir, { withFileTypes: true }); - for (const e of rootEntries) { - if (!e.isFile() || !isArtifactInScope(e.name)) continue; - const abs = path.join(epicDir, e.name); - const stat = await fs.stat(abs); - results.push({ - path: e.name, - size: stat.size, - modifiedAt: stat.mtime.toISOString(), - }); - } - - // Pass 2: stories/ recursive scan - const storiesDir = path.join(epicDir, "stories"); - try { - const entries = await fs.readdir(storiesDir, { withFileTypes: true, recursive: true }); - for (const e of entries) { - if (!e.isFile()) continue; - const parent = (e as any).parentPath ?? (e as any).path ?? storiesDir; - const abs = path.join(parent, e.name); - const rel = path.relative(epicDir, abs); - if (!isArtifactInScope(rel)) continue; - const stat = await fs.stat(abs); - results.push({ - path: rel, - size: stat.size, - modifiedAt: stat.mtime.toISOString(), - }); - } - } catch (err: unknown) { - if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err; - } - - results.sort((a, b) => a.path.localeCompare(b.path)); - return results; -} - -// -- Read -- - -export async function readArtifact(epicDir: string, relativePath: string): Promise { - const abs = path.resolve(epicDir, relativePath); - const root = path.resolve(epicDir); - const rel = path.relative(root, abs); - if (rel !== "" && (rel.startsWith("..") || path.isAbsolute(rel))) { - throw new Error(`Path "${relativePath}" escapes the epic directory.`); - } - if (!isArtifactInScope(rel)) { - throw new Error(`Path "${relativePath}" is outside artifact scope.`); - } - return fs.readFile(abs, "utf8"); -} - -// -- Display helpers -- - -export function formatArtifactSize(bytes: number): string { - if (bytes < 1024) return bytes + " B"; - if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + " KB"; - return (bytes / (1024 * 1024)).toFixed(1) + " MB"; -} - -export function artifactDisplayPath(relativePath: string): string { - const norm = path.posix.normalize(relativePath.replace(/\\/g, "/")); - const segments = norm.split("/"); - if (segments.length === 1) return "epic root / " + segments[0]; - return segments.join(" / "); -} - -// -- Write -- - -export async function writeArtifact(epicDir: string, relativePath: string, content: string): Promise { - const abs = path.resolve(epicDir, relativePath); - const tmp = `${abs}.tmp`; - await fs.writeFile(tmp, content, "utf8"); - await fs.rename(tmp, abs); -} diff --git a/src/planner/epic/state.ts b/src/planner/epic/state.ts deleted file mode 100644 index 09423b0..0000000 --- a/src/planner/epic/state.ts +++ /dev/null @@ -1,220 +0,0 @@ -// Epic and story state I/O — read/write JSON state files for driver routing. -// All JSON writes use atomic tmp+rename to prevent partial reads during concurrent access. -// Paths follow: ~/.koan/state/epics/{epic-id}/... -// -// The driver reads and writes .json files only — never .md files. This is the -// core invariant (AGENTS.md): LLMs read/write markdown; the driver reads/writes -// JSON; tool code bridges both. Putting writeStatusMarkdown here would violate the -// invariant boundary and make the module responsible for two communication channels. -// status.md writes belong exclusively in tools/orchestrator.ts. -// -// discoverStoryIds scans the filesystem instead of reading a driver-maintained -// list because the decomposer LLM writes story.md files using the Write tool — -// it has no reason to know the JSON state format, and requiring it to update -// epic-state.json would force an LLM to write JSON, violating the core invariant. -// See docs/subagents.md "Why not CLI flags". The driver discovers what the LLM created by scanning stories/*/story.md, -// then populates the JSON story list itself. - -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; - -import { - createInitialEpicState, - createInitialStoryState, - type EpicInfo, - type EpicState, - type StoryState, - type WorkflowDecisionState, -} from "./types.js"; - -export const KOAN_HOME = path.join(os.homedir(), ".koan"); -export const EPICS_HOME = path.join(KOAN_HOME, "state", "epics"); - -// --------------------------------------------------------------------------- -// Path helpers -// --------------------------------------------------------------------------- - -function epicStatePath(epicDir: string): string { - return path.join(epicDir, "epic-state.json"); -} - -function storyStatePath(epicDir: string, storyId: string): string { - return path.join(epicDir, "stories", storyId, "state.json"); -} - -// --------------------------------------------------------------------------- -// Atomic JSON write -// --------------------------------------------------------------------------- - -// Writes to a .tmp file first, then renames — preventing partial reads. -async function atomicWriteJson(filePath: string, value: unknown): Promise { - const tmpPath = `${filePath}.tmp`; - await fs.writeFile(tmpPath, `${JSON.stringify(value, null, 2)}\n`, "utf8"); - await fs.rename(tmpPath, filePath); -} - -// --------------------------------------------------------------------------- -// ID generation -// --------------------------------------------------------------------------- - -function slugify(input: string): string { - const base = input - .toLowerCase() - .replace(/[^a-z0-9]+/g, "-") - .replace(/^-+|-+$/g, "") - .slice(0, 48); - return base.length > 0 ? base : "epic"; -} - -export function generateEpicId(description: string, now: Date): string { - const timestamp = now.toISOString().replace(/[-:]/g, "").replace(/\..+/, ""); - const slug = slugify(description); - return `${timestamp}-${slug}`; -} - -async function ensureEpicDirectoryUnique(baseId: string): Promise<{ id: string; directory: string }> { - let suffix = 0; - while (true) { - const candidateId = suffix === 0 ? baseId : `${baseId}-${suffix}`; - const directory = path.join(EPICS_HOME, candidateId); - try { - await fs.mkdir(directory, { recursive: false }); - return { id: candidateId, directory }; - } catch (error) { - const err = error as NodeJS.ErrnoException; - if (err.code === "EEXIST") { - suffix += 1; - continue; - } - throw error; - } - } -} - -// --------------------------------------------------------------------------- -// Epic directory creation -// --------------------------------------------------------------------------- - -// Creates the epic directory with standard subdirectories. -// Creates only 'stories/' and 'subagents/' — no 'scouts/' directory. -// Scout output lives in per-scout subagent directories under subagents/. -export async function createEpicDirectory(description: string, _cwd: string, now = new Date()): Promise { - await fs.mkdir(EPICS_HOME, { recursive: true }); - - const baseId = generateEpicId(description, now); - const { id, directory } = await ensureEpicDirectoryUnique(baseId); - - await Promise.all([ - fs.mkdir(path.join(directory, "stories"), { recursive: true }), - fs.mkdir(path.join(directory, "subagents"), { recursive: true }), - ]); - - const epicState = createInitialEpicState(id); - await atomicWriteJson(epicStatePath(directory), epicState); - - return { id, directory, createdAt: epicState.createdAt }; -} - -// --------------------------------------------------------------------------- -// Epic state I/O -// --------------------------------------------------------------------------- - -export async function loadEpicState(epicDir: string): Promise { - const raw = await fs.readFile(epicStatePath(epicDir), "utf8"); - return JSON.parse(raw) as EpicState; -} - -export async function saveEpicState(epicDir: string, state: EpicState): Promise { - await atomicWriteJson(epicStatePath(epicDir), state); -} - -// --------------------------------------------------------------------------- -// Story state I/O -// --------------------------------------------------------------------------- - -export async function loadStoryState(epicDir: string, storyId: string): Promise { - const raw = await fs.readFile(storyStatePath(epicDir, storyId), "utf8"); - return JSON.parse(raw) as StoryState; -} - -export async function saveStoryState(epicDir: string, storyId: string, state: StoryState): Promise { - await atomicWriteJson(storyStatePath(epicDir, storyId), state); -} - -export async function loadAllStoryStates(epicDir: string): Promise { - const epicState = await loadEpicState(epicDir); - return Promise.all(epicState.stories.map((id) => loadStoryState(epicDir, id))); -} - -// --------------------------------------------------------------------------- -// Workflow decision I/O -// --------------------------------------------------------------------------- - -/** Read {subagentDir}/workflow-decision.json written by koan_set_next_phase. - * Returns null if absent (orchestrator crashed before committing) or - * malformed (should never happen — koan_set_next_phase writes valid JSON). */ -export async function readWorkflowDecision( - subagentDir: string, -): Promise { - try { - const raw = await fs.readFile( - path.join(subagentDir, "workflow-decision.json"), "utf8", - ); - return JSON.parse(raw) as WorkflowDecisionState; - } catch { - return null; - } -} - -// --------------------------------------------------------------------------- -// Directory provisioning -// --------------------------------------------------------------------------- - -// Ensures the story directory and plan subdirectory exist, and that state.json -// is initialized if not already present. -export async function ensureStoryDirectory(epicDir: string, storyId: string): Promise { - const storyDir = path.join(epicDir, "stories", storyId); - await fs.mkdir(path.join(storyDir, "plan"), { recursive: true }); - - const statePath = storyStatePath(epicDir, storyId); - try { - await fs.access(statePath); - } catch { - const initialState = createInitialStoryState(storyId); - await atomicWriteJson(statePath, initialState); - } - - return storyDir; -} - -// Ensures a uniquely labeled subagent directory exists under {epicDir}/subagents/. -// The label should be descriptive (e.g., "intake-20260313T105232" or "scout-task1-1741830752000"). -export async function ensureSubagentDirectory(epicDir: string, label: string): Promise { - const subagentDir = path.join(epicDir, "subagents", label); - await fs.mkdir(subagentDir, { recursive: true }); - return subagentDir; -} - -// --------------------------------------------------------------------------- -// Story discovery -// --------------------------------------------------------------------------- - -// Scans {epicDir}/stories/ for subdirectories and returns their names sorted. -// This is the authoritative discovery mechanism after decomposition. -// The driver calls this after the decomposer LLM creates stories/*/story.md files. -// Never reads epic-state.json.stories — that list is populated by the driver AFTER -// discovery, not by the LLM. -export async function discoverStoryIds(epicDir: string): Promise { - const storiesDir = path.join(epicDir, "stories"); - try { - const entries = await fs.readdir(storiesDir, { withFileTypes: true }); - return entries - .filter((e) => e.isDirectory()) - .map((e) => e.name) - .sort(); - } catch (err: unknown) { - if ((err as NodeJS.ErrnoException).code === "ENOENT") return []; - throw err; - } -} diff --git a/src/planner/epic/types.ts b/src/planner/epic/types.ts deleted file mode 100644 index 638a539..0000000 --- a/src/planner/epic/types.ts +++ /dev/null @@ -1,66 +0,0 @@ -// Epic and story state types — JSON structures for driver consumption. -// Persisted as .json files under ~/.koan/state/epics/{epic-id}/. -// Per AGENTS.md invariant: LLMs write markdown only; driver reads JSON only. -// LLMs never read these files directly — they read the corresponding .md files. - -import type { EpicPhase, StoryStatus } from "../types.js"; - -// Persisted at {epic-dir}/epic-state.json -export interface EpicState { - epicId: string; - createdAt: string; - phase: EpicPhase; - stories: string[]; // Story IDs in declaration order -} - -// Persisted at {epic-dir}/stories/{story-id}/state.json -// Note: no `escalation` field — escalation is handled via koan_ask_question, -// not a separate status or state field. -export interface StoryState { - storyId: string; - status: StoryStatus; - updatedAt: string; - retryCount: number; - maxRetries: number; - failureSummary?: string; // Set by koan_retry_story; used as retry context for executor - skipReason?: string; // Set by koan_skip_story or driver on budget exhaustion -} - -// Metadata about an epic directory — returned by createEpicDirectory. -export interface EpicInfo { - id: string; - directory: string; - createdAt: string; -} - -// Default retry budget per story. -export const DEFAULT_MAX_RETRIES = 2; - -export function createInitialStoryState(storyId: string, maxRetries = DEFAULT_MAX_RETRIES): StoryState { - return { - storyId, - status: "pending", - updatedAt: new Date().toISOString(), - retryCount: 0, - maxRetries, - }; -} - -export function createInitialEpicState(epicId: string, stories: string[] = []): EpicState { - return { - epicId, - createdAt: new Date().toISOString(), - phase: "intake", - stories, - }; -} - -/** Written by koan_set_next_phase to {subagentDir}/workflow-decision.json. - * Read by the driver after the orchestrator process exits. - * nextPhase is string (not EpicPhase) because it's read from JSON - * and validated via isValidTransition() before casting. */ -export interface WorkflowDecisionState { - nextPhase: string; - instructions?: string; - decidedAt: string; -} diff --git a/src/planner/lib/audit-events.ts b/src/planner/lib/audit-events.ts deleted file mode 100644 index ca8e6ab..0000000 --- a/src/planner/lib/audit-events.ts +++ /dev/null @@ -1,139 +0,0 @@ -// Event type definitions for the audit trail. No I/O, no Node.js imports. - -// -- Types -- - -export interface EventBase { - ts: string; - seq: number; -} - -// -- Tool events -- -// Every tool invocation produces a (tool_call, tool_result) pair in the log. -// tool_call fires when the LLM requests the tool; tool_result fires when -// the tool returns. Both carry toolCallId for correlation. - -export interface ToolCallEvent extends EventBase { - kind: "tool_call"; - toolCallId: string; - tool: string; - input: Record; -} - -export interface ToolResultEvent extends EventBase { - kind: "tool_result"; - toolCallId: string; - tool: string; - error: boolean; - // Summarized output metrics (not the full content -- too large for the log). - lines?: number; - chars?: number; - // Koan tool response text preserved for projection (completionSummary, etc.). - koanResponse?: string[]; - // Reserved for debug mode: bounded preview of tool output content. - // Populated by extractToolResult() when debugMode is active. - // NOT written in normal mode. Never folded into Projection. - debugOutput?: string; -} - -// -- Lifecycle events -- - -export interface PhaseStartEvent extends EventBase { - kind: "phase_start"; - phase: string; - role: string; - model?: string | null; - totalSteps: number; -} - -export interface StepTransitionEvent extends EventBase { - kind: "step_transition"; - step: number; - name: string; - totalSteps: number; -} - -export interface PhaseEndEvent extends EventBase { - kind: "phase_end"; - outcome: "completed" | "failed"; - detail?: string; -} - -export interface HeartbeatEvent extends EventBase { - kind: "heartbeat"; -} - -export interface UsageEvent extends EventBase { - kind: "usage"; - input: number; - output: number; - cacheRead: number; - cacheWrite: number; -} - -export interface ThinkingEvent extends EventBase { - kind: "thinking"; - // Truncated thinking content (first 2000 chars for log size). - text: string; - // Original length before truncation. - chars: number; -} - -export type AuditEvent = - | ToolCallEvent - | ToolResultEvent - | PhaseStartEvent - | StepTransitionEvent - | PhaseEndEvent - | HeartbeatEvent - | UsageEvent - | ThinkingEvent; - -// Distributive Omit -- distributes over union members so object literals -// with fields specific to one member are accepted. -type DistributiveOmit = T extends unknown ? Omit : never; -export type AuditEventPartial = DistributiveOmit; - -// -- Projection -- -// Eagerly materialized state summary. Written atomically to state.json -// after every event so the parent (web server) can poll cheaply. - -export interface Projection { - role: string; - phase: string; - model: string | null; - status: "running" | "completed" | "failed"; - step: number; - totalSteps: number; - stepName: string; - lastAction: string | null; - // toolCallId of the currently in-flight tool, null when idle. - // Lets the UI distinguish "doing X" from "done with X". - currentToolCallId: string | null; - updatedAt: string; - eventCount: number; - error: string | null; - completionSummary: string | null; - tokensSent: number; - tokensReceived: number; - // Timestamp of the most recent tool_result event; used to track thinking gaps. - lastToolResultAt: string | null; - -} - -// -- Correlated tool invocations -- -// Reduced view of paired (tool_call, tool_result) events. - -export interface ToolInvocation { - toolCallId: string; - tool: string; - input: Record; - callTs: string; - resultTs: string | null; - error: boolean | null; - inFlight: boolean; - durationMs: number | null; - // Output metrics from the result event. - lines?: number; - chars?: number; - koanResponse?: string[]; -} diff --git a/src/planner/lib/audit-fold.ts b/src/planner/lib/audit-fold.ts deleted file mode 100644 index 168d7c5..0000000 --- a/src/planner/lib/audit-fold.ts +++ /dev/null @@ -1,196 +0,0 @@ -// Pure fold/correlate/summarize functions. No I/O, no Node.js or pi imports -// -- safe to unit-test directly. - -import type { - AuditEvent, - Projection, - ToolInvocation, - ToolCallEvent, - ToolResultEvent, -} from "./audit-events.js"; - -// -- Constants -- - -const FILE_TOOLS = new Set(["read", "edit", "write"]); - -// -- Formatters -- - -export function formatChars(chars: number): string { - if (chars < 1000) return `${chars}c`; - const k = chars / 1000; - if (k >= 10) return `${Math.round(k)}k`; - return `${k.toFixed(1)}k`; -} - -// -- Correlate -- - -// Reduces a flat event stream into paired tool invocations. -// In-flight tools (call without result) have inFlight=true, resultTs=null. -export function correlateTools(events: AuditEvent[]): ToolInvocation[] { - const byId = new Map(); - const ordered: ToolInvocation[] = []; - - for (const e of events) { - if (e.kind === "tool_call") { - const inv: ToolInvocation = { - toolCallId: e.toolCallId, - tool: e.tool, - input: e.input, - callTs: e.ts, - resultTs: null, - error: null, - inFlight: true, - durationMs: null, - }; - byId.set(e.toolCallId, inv); - ordered.push(inv); - } else if (e.kind === "tool_result") { - const inv = byId.get(e.toolCallId); - if (inv) { - inv.resultTs = e.ts; - inv.error = e.error; - inv.inFlight = false; - inv.durationMs = new Date(e.ts).getTime() - new Date(inv.callTs).getTime(); - inv.lines = e.lines; - inv.chars = e.chars; - inv.koanResponse = e.koanResponse; - } - // Orphan result (no matching call) -- can happen if the subagent - // started before tool_call hooking was added. Silently skip. - } - } - - return ordered; -} - -// -- Summarize -- -// Human-readable one-liner from a tool invocation. -// Uses input (from call) + output metrics (from result) when available. - -export function summarizeInvocation(inv: ToolInvocation): string { - const { tool, input } = inv; - - // Tool name / key input identifier. - let label: string; - if (FILE_TOOLS.has(tool)) { - label = `${tool} ${(input["path"] as string | undefined) ?? ""}`; - } else if (tool === "bash") { - const cmd = (input["command"] as string | undefined) ?? ""; - label = `bash ${cmd.trim().split(/\s+/)[0] ?? ""}`; - } else { - label = tool; - } - - // Append output metrics if result has landed. - if (!inv.inFlight && (inv.lines != null || inv.chars != null)) { - const lines = inv.lines ?? 0; - const chars = inv.chars ?? 0; - label += ` · ${lines}L/${formatChars(chars)}`; - } - - return label; -} - -// Summarize from a ToolCallEvent alone (in-flight, no result yet). -function summarizeCall(e: ToolCallEvent): string { - if (FILE_TOOLS.has(e.tool)) { - return `${e.tool} ${(e.input["path"] as string | undefined) ?? ""}`; - } - if (e.tool === "bash") { - const cmd = (e.input["command"] as string | undefined) ?? ""; - return `bash ${cmd.trim().split(/\s+/)[0] ?? ""}`; - } - return e.tool; -} - -// Summarize from a ToolResultEvent alone (used in fold when call was missed). -function summarizeResult(e: ToolResultEvent): string { - let label = e.tool; - if (e.lines != null || e.chars != null) { - label += ` · ${e.lines ?? 0}L/${formatChars(e.chars ?? 0)}`; - } - return label; -} - -// -- Fold -- -// Pure projection update -- one case per discriminated kind. -// All branches update updatedAt and increment eventCount. - -export function fold(s: Projection, e: AuditEvent): Projection { - const base = { ...s, updatedAt: e.ts, eventCount: s.eventCount + 1 }; - - switch (e.kind) { - case "phase_start": - return { - ...base, - role: e.role, - phase: e.phase, - model: e.model ?? s.model, - status: "running", - step: 0, - totalSteps: e.totalSteps, - stepName: "", - lastAction: null, - currentToolCallId: null, - error: null, - completionSummary: null, - }; - - case "step_transition": - return { - ...base, - step: e.step, - totalSteps: e.totalSteps, - stepName: e.name, - }; - - case "phase_end": - return { - ...base, - status: e.outcome, - error: e.detail ?? null, - currentToolCallId: null, - }; - - case "tool_call": { - const updated: Projection = { - ...base, - lastAction: summarizeCall(e), - currentToolCallId: e.toolCallId, - }; - // Extract completionSummary from koan_complete_step's thoughts param. - // `thoughts` is an escape hatch for models that can't mix text + - // tool_call (see step.ts invariant), NOT task output. We capture a - // 500-char prefix for UI display — this is incidental, not a contract. - if (e.tool === "koan_complete_step" && typeof e.input?.thoughts === "string") { - updated.completionSummary = e.input.thoughts.slice(0, 500) || null; - } - return updated; - } - - case "tool_result": - // NOTE: ToolResultEvent.debugOutput is intentionally NOT folded into - // Projection/state.json. It is debug-only and can be large; keeping it - // out of Projection preserves lightweight 50ms polling behavior. - return { - ...base, - lastAction: summarizeResult(e), - currentToolCallId: null, - lastToolResultAt: e.ts, - }; - - case "heartbeat": - return base; - - case "usage": - return { - ...base, - tokensSent: s.tokensSent + e.input, - tokensReceived: s.tokensReceived + e.output, - }; - - case "thinking": - return base; - - } -} diff --git a/src/planner/lib/audit-log-formatter.ts b/src/planner/lib/audit-log-formatter.ts deleted file mode 100644 index 6900b51..0000000 --- a/src/planner/lib/audit-log-formatter.ts +++ /dev/null @@ -1,475 +0,0 @@ -// Log formatters for the web UI activity feed. Reads events.jsonl and -// produces structured LogLine entries. - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; -import type { - AuditEvent, - ToolResultEvent, - PhaseStartEvent, - StepTransitionEvent, - PhaseEndEvent, - ToolInvocation, -} from "./audit-events.js"; -import { correlateTools, formatChars } from "./audit-fold.js"; - -// -- Types -- - -export interface LogLine { - tool: string; - summary: string; - highValue: boolean; - inFlight: boolean; - details?: string[]; - // Timestamp used by thinking entries to drive the live elapsed timer. - ts?: string; - // Expandable content body: thinking text, tool output, step guidance, etc. - body?: string; - // Structured scout data for koan_request_scouts cards. - scouts?: Array<{ id: string; role: string }>; -} - -interface ToolShape { - keys: string[]; - arrays?: string[]; - freeform?: string[]; - getter?: boolean; - highValue?: boolean; -} - -// -- Constants -- - -const PREVIEW_CHARS = 40; -const KEY_PRIORITY = ["id", "story_id", "milestone", "decision_ref", "intent_ref", "file", "path", "phase"]; - -const KOAN_SHAPES: Record = { - koan_select_story: { keys: ["story_id"], highValue: true }, - koan_complete_story: { keys: ["story_id"], highValue: true }, - koan_retry_story: { keys: ["story_id", "failure_summary"], freeform: ["failure_summary"], highValue: true }, - koan_skip_story: { keys: ["story_id", "reason"], freeform: ["reason"], highValue: true }, - koan_ask_question: { - keys: ["questions"], - arrays: ["questions"], - highValue: true, - }, - koan_request_scouts: { keys: [], highValue: true }, -}; - -const FILE_TOOLS = new Set(["read", "edit", "write"]); - -// -- Public API -- - -// Reads events.jsonl, correlates tool pairs, and returns structured log entries. -// Filters out heartbeats, usage, and koan_complete_step (noisy in non-debug mode). -// In debug mode, koan_complete_step results are used to attach step guidance text -// as an expandable body on the preceding step line. -export async function readRecentLogs( - dir: string, - count = 8, - opts?: { debug?: boolean }, -): Promise { - try { - const raw = await fs.readFile(path.join(dir, "events.jsonl"), "utf8"); - const events = raw - .trimEnd() - .split("\n") - .filter(Boolean) - .map((line) => JSON.parse(line) as AuditEvent); - - return buildChronologicalLog(events, count, opts?.debug ?? false); - } catch { - return []; - } -} - -// -- Helpers -- - -function textStats(text: string): string { - const lines = text.length === 0 ? 0 : text.split("\n").length; - return `${lines}L/${formatChars(text.length)}`; -} - -function responseSize(response: string[]): string { - return textStats(response.join("\n")); -} - -function formatThinkingDuration(ms: number): string { - const sec = Math.round(ms / 1000); - if (sec < 60) return `${sec}s`; - const min = Math.floor(sec / 60); - const remSec = sec % 60; - return remSec > 0 ? `${min}m ${remSec}s` : `${min}m`; -} - -function truncateUnicode(text: string, maxChars: number): string { - const chars = Array.from(text); - if (chars.length <= maxChars) return text; - return `${chars.slice(0, maxChars).join("")}\u2026`; -} - -function inlineScalar(value: unknown): string { - if (typeof value === "string") { - return truncateUnicode(value.replace(/\r\n?|\n/gu, "\\n"), PREVIEW_CHARS); - } - if (typeof value === "number" || typeof value === "boolean") { - return String(value); - } - if (value === null) return "null"; - if (Array.isArray(value)) return `[${value.length}]`; - if (typeof value === "object") return "{\u2026}"; - return String(value); -} - -function arrayPreview(value: unknown): string { - if (!Array.isArray(value) || value.length === 0) { - return "[]"; - } - const first = inlineScalar(value[0]); - if (value.length === 1) { - return `[${first}]`; - } - return `[${first}] +${value.length - 1}`; -} - -function freeformSize(value: unknown): string { - if (typeof value === "string") { - return textStats(value); - } - const json = JSON.stringify(value); - return textStats(json ?? String(value)); -} - -function hasKey(input: Record, key: string): boolean { - return Object.prototype.hasOwnProperty.call(input, key); -} - -function orderedShapeKeys(keys: string[]): string[] { - const indexed = keys.map((key, index) => ({ key, index })); - indexed.sort((a, b) => { - const pa = KEY_PRIORITY.indexOf(a.key); - const pb = KEY_PRIORITY.indexOf(b.key); - const ra = pa === -1 ? Number.MAX_SAFE_INTEGER : pa; - const rb = pb === -1 ? Number.MAX_SAFE_INTEGER : pb; - if (ra !== rb) return ra - rb; - return a.index - b.index; - }); - return indexed.map((x) => x.key); -} - -// -- Formatters -- - -// Format a completed tool invocation from its correlated pair. -function formatToolInvocation(inv: ToolInvocation): LogLine { - if (inv.tool.startsWith("koan_")) { - return formatKoanInvocation(inv); - } - - if (FILE_TOOLS.has(inv.tool)) { - const p = (inv.input["path"] as string | undefined) ?? ""; - const suffix = inv.lines != null ? ` · ${inv.lines}L/${formatChars(inv.chars ?? 0)}` : ""; - return { - tool: inv.tool, - summary: `${p}${suffix}`, - highValue: inv.tool === "read", - inFlight: inv.inFlight, - }; - } - - if (inv.tool === "bash") { - const cmd = (inv.input["command"] as string | undefined) ?? ""; - const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; - const suffix = inv.lines != null ? ` · ${inv.lines}L/${formatChars(inv.chars ?? 0)}` : ""; - return { - tool: "bash", - summary: `${bin}${suffix}`, - highValue: false, - inFlight: inv.inFlight, - }; - } - - return { tool: inv.tool, summary: "", highValue: false, inFlight: inv.inFlight }; -} - -function formatKoanInvocation(inv: ToolInvocation): LogLine { - const shape = KOAN_SHAPES[inv.tool]; - if (!shape) { - return { tool: inv.tool, summary: "", highValue: false, inFlight: inv.inFlight }; - } - - const arrayKeys = new Set(shape.arrays ?? []); - const freeformKeys = new Set(shape.freeform ?? []); - const chunks: string[] = []; - - for (const key of orderedShapeKeys(shape.keys)) { - if (!hasKey(inv.input, key)) continue; - const value = inv.input[key]; - - if (arrayKeys.has(key)) { - chunks.push(`${key}:${arrayPreview(value)}`); - continue; - } - if (freeformKeys.has(key)) { - chunks.push(`${key}:${freeformSize(value)}`); - continue; - } - chunks.push(`${key}=${inlineScalar(value)}`); - } - - if (shape.getter && inv.koanResponse) { - if (chunks.length === 0) { - chunks.push("scope=plan"); - } - chunks.push(`resp:${responseSize(inv.koanResponse)}`); - } - - const line: LogLine = { - tool: inv.tool, - summary: chunks.join(" · "), - highValue: shape.highValue ?? chunks.length >= 3, - inFlight: inv.inFlight, - }; - - // Structured scout data for the UI card. - if (inv.tool === "koan_request_scouts" && Array.isArray(inv.input["scouts"])) { - line.scouts = (inv.input["scouts"] as Array>).map( - (s) => ({ id: String(s["id"] ?? "?"), role: String(s["role"] ?? "agent") }), - ); - } - - return line; -} - -// Format a tool_result event paired with its call's input. -function formatPairedResult(e: ToolResultEvent, input: Record): LogLine { - if (FILE_TOOLS.has(e.tool)) { - const p = (input["path"] as string | undefined) ?? ""; - const suffix = e.lines != null ? ` · ${e.lines}L/${formatChars(e.chars ?? 0)}` : ""; - // Placeholder for future debug body rendering. - // In debug mode, a per-tool formatter may populate line.body. - // See: formatDebugBody(tool, input, e.debugOutput) - return { - tool: e.tool, - summary: `${p}${suffix}`, - highValue: e.tool === "read", - inFlight: false, - }; - } - - if (e.tool === "bash") { - const cmd = (input["command"] as string | undefined) ?? ""; - const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; - const suffix = e.lines != null ? ` · ${e.lines}L/${formatChars(e.chars ?? 0)}` : ""; - // Placeholder for future debug body rendering. - // In debug mode, a per-tool formatter may populate line.body. - // See: formatDebugBody(tool, input, e.debugOutput) - return { - tool: "bash", - summary: `${bin}${suffix}`, - highValue: false, - inFlight: false, - }; - } - - if (e.tool.startsWith("koan_")) { - const shape = KOAN_SHAPES[e.tool]; - if (shape) { - // Rebuild invocation-like object for the koan formatter. - const inv: ToolInvocation = { - toolCallId: e.toolCallId, - tool: e.tool, - input, - callTs: e.ts, - resultTs: e.ts, - error: e.error, - inFlight: false, - durationMs: null, - koanResponse: e.koanResponse, - }; - return formatKoanInvocation(inv); - } - return { tool: e.tool, summary: "", highValue: false, inFlight: false }; - } - - return { tool: e.tool, summary: "", highValue: false, inFlight: false }; -} - -function formatLifecycleEvent(e: PhaseStartEvent | StepTransitionEvent | PhaseEndEvent): LogLine | null { - switch (e.kind) { - case "phase_start": - // Phase labels removed — subagent activity flows seamlessly. - return null; - case "step_transition": - return { tool: "step", summary: e.name, highValue: false, inFlight: false }; - case "phase_end": - // Phase end labels removed — subagent activity flows seamlessly. - return null; - } -} - -// Format an in-flight tool_call (no result yet). Same structure as -// formatPairedResult but with inFlight: true and no output metrics. -function formatInFlightCall(tool: string, input: Record): LogLine { - if (FILE_TOOLS.has(tool)) { - // Placeholder for future debug body rendering. - // In debug mode, a per-tool formatter may populate line.body. - // See: formatDebugBody(tool, input, debugOutput) - return { - tool, - summary: (input["path"] as string | undefined) ?? "", - highValue: tool === "read", - inFlight: true, - }; - } - - if (tool === "bash") { - const cmd = (input["command"] as string | undefined) ?? ""; - const bin = cmd.trim().split(/\s+/)[0] ?? "bash"; - // Placeholder for future debug body rendering. - // In debug mode, a per-tool formatter may populate line.body. - // See: formatDebugBody(tool, input, debugOutput) - return { tool: "bash", summary: bin, highValue: false, inFlight: true }; - } - - if (tool.startsWith("koan_")) { - const shape = KOAN_SHAPES[tool]; - if (shape) { - const inv: ToolInvocation = { - toolCallId: "", tool, input, - callTs: "", resultTs: null, - error: null, inFlight: true, durationMs: null, - }; - return formatKoanInvocation(inv); - } - } - - return { tool, summary: "", highValue: false, inFlight: true }; -} - -// -- Chronological log builder -- - -// Builds a chronological log by walking events in order and emitting -// one LogLine per tool invocation (at result time, or at call time if -// still in-flight) plus lifecycle events. Inserts thinking lines to -// represent gaps between visible events where the LLM is reasoning. -// -// In debug mode, koan_complete_step results are not dropped: the -// koanResponse text is attached as an expandable body to the most -// recent step line (tool === "step"), which was emitted by the -// step_transition event immediately preceding this result. -function buildChronologicalLog(events: AuditEvent[], count: number, debug: boolean = false): LogLine[] { - const pendingCalls = new Map }>(); - const lines: LogLine[] = []; - let thinkingStartTs: string | null = null; - // Index of the last thinking line pushed to `lines`. Thinking events fire - // AFTER the turn's tool_result (message_update is a post-turn event), so the - // text belongs to the PREVIOUS thinking gap, not the current one. We - // retroactively set body on the already-emitted line. - let lastThinkingIdx = -1; - let phaseEnded = false; - - for (const e of events) { - if (e.kind === "heartbeat" || e.kind === "usage") continue; - - - if (e.kind === "thinking") { - // Retroactive: this text is from the turn that just completed. - // Overwrite (not append) -- later message_update events have more - // complete content, so the last one wins. - if (lastThinkingIdx >= 0) { - lines[lastThinkingIdx].body = e.text; - } - continue; - } - - if (e.kind === "tool_call") { - // Before a visible tool_call, insert a completed thinking line if gap >= 1s - if (e.tool !== "koan_complete_step" && thinkingStartTs) { - const gapMs = new Date(e.ts).getTime() - new Date(thinkingStartTs).getTime(); - if (gapMs >= 1000) { - lines.push({ - tool: "thinking", - summary: formatThinkingDuration(gapMs), - highValue: false, - inFlight: false, - }); - lastThinkingIdx = lines.length - 1; - } - thinkingStartTs = null; - } - pendingCalls.set(e.toolCallId, { tool: e.tool, input: e.input }); - continue; - } - - if (e.kind === "tool_result") { - if (e.tool === "koan_complete_step") { - pendingCalls.delete(e.toolCallId); - // In debug mode, attach the step guidance text to the most recent step - // line. step_transition fires immediately before this tool_result in - // events.jsonl (guaranteed by the serialised EventLog.append chain), so - // lines[lines.length - 1] is the step line when it exists. - // - // "Phase complete." edge case: when handleStepComplete returns null, - // phase_end has already been emitted. phaseEnded blocks attachment so - // the terminal koan_complete_step result cannot overwrite the previous - // step's guidance body. - if (debug && e.koanResponse?.length && !phaseEnded) { - const last = lines[lines.length - 1]; - if (last?.tool === "step") { - last.body = e.koanResponse.join("\n"); - } - } - continue; - } - const call = pendingCalls.get(e.toolCallId); - lines.push(formatPairedResult(e, call?.input ?? {})); - pendingCalls.delete(e.toolCallId); - thinkingStartTs = e.ts; - continue; - } - - if ( - e.kind === "phase_start" || - e.kind === "step_transition" || - e.kind === "phase_end" - ) { - // Flush any pending thinking gap before the lifecycle line. - if (thinkingStartTs) { - const gapMs = new Date(e.ts).getTime() - new Date(thinkingStartTs).getTime(); - if (gapMs >= 1000) { - lines.push({ - tool: "thinking", - summary: formatThinkingDuration(gapMs), - highValue: false, - inFlight: false, - }); - lastThinkingIdx = lines.length - 1; - } - thinkingStartTs = null; - } - if (e.kind === "phase_end") phaseEnded = true; - const lifecycleLine = formatLifecycleEvent(e); - if (lifecycleLine) lines.push(lifecycleLine); - thinkingStartTs = e.ts; - } - } - - // Currently-thinking indicator: all tools completed, phase still running - if (thinkingStartTs && pendingCalls.size === 0 && !phaseEnded) { - lines.push({ - tool: "thinking", - summary: "", - highValue: false, - inFlight: true, - ts: thinkingStartTs, - }); - } - - // Emit remaining calls without results as in-flight lines. - for (const [, call] of pendingCalls) { - if (call.tool === "koan_complete_step") continue; - lines.push(formatInFlightCall(call.tool, call.input)); - } - - return lines.slice(-count); -} - diff --git a/src/planner/lib/audit.ts b/src/planner/lib/audit.ts deleted file mode 100644 index 4b22c5e..0000000 --- a/src/planner/lib/audit.ts +++ /dev/null @@ -1,13 +0,0 @@ -// Barrel re-export: preserves import paths for callers outside lib/. -// Real implementations live in the four sub-modules: -// audit-events.ts -- event type definitions (no I/O) -// audit-fold.ts -- pure fold/correlate/summarize (no I/O) -// event-log.ts -- EventLog class, extractors, readProjection -// audit-log-formatter.ts -- LogLine formatters for the web UI -// -// Internal lib/ imports should target the specific sub-module directly. - -export * from "./audit-events.js"; -export * from "./audit-fold.js"; -export * from "./event-log.js"; -export * from "./audit-log-formatter.js"; diff --git a/src/planner/lib/constants.ts b/src/planner/lib/constants.ts deleted file mode 100644 index 3742af3..0000000 --- a/src/planner/lib/constants.ts +++ /dev/null @@ -1,5 +0,0 @@ -// Shared constants for use across both the extension entry-point and the -// subagent spawn infrastructure. Keeping the flag name here prevents string -// drift between registerFlag() and the child-process args construction. - -export const KOAN_DEBUG_FLAG = "koan-debug" as const; diff --git a/src/planner/lib/event-log.ts b/src/planner/lib/event-log.ts deleted file mode 100644 index b5ca4e2..0000000 --- a/src/planner/lib/event-log.ts +++ /dev/null @@ -1,247 +0,0 @@ -// EventLog class: file I/O, heartbeat, serialization, and emit helpers. -// Extractors transform pi hook events into AuditEvent types. - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; -import type { - AuditEvent, - AuditEventPartial, - HeartbeatEvent, - PhaseStartEvent, - StepTransitionEvent, - PhaseEndEvent, - Projection, - ToolCallEvent, - ToolResultEvent, -} from "./audit-events.js"; -import { fold } from "./audit-fold.js"; - -// -- Pi event shapes (subset we consume) -- - -interface PiToolCallEvent { - toolCallId: string; - toolName: string; - input: Record; -} - -interface PiToolResultEvent { - toolCallId: string; - toolName: string; - input: Record; - content: Array<{ type: string; text?: string }>; - isError: boolean; -} - -// -- Constants -- - -const FILE_TOOLS = new Set(["read", "edit", "write"]); -const HEARTBEAT_MS = 10_000; - -// Tools for which a bounded debug output preview is captured when debug mode -// is active. Intentionally narrow: only bash in this iteration. -const DEBUG_CAPTURE_TOOLS = new Set(["bash"]); - -const DEBUG_CAPTURE_LIMIT = 4096; - -// -- Helpers -- - -import { now } from "./time.js"; - -// -- Extractors -- -// Transform pi's raw hook events into our audit event types. -// ts/seq are placeholders -- EventLog.append() overwrites them. - -export function extractToolCall(piEvent: PiToolCallEvent): ToolCallEvent { - return { - kind: "tool_call", - toolCallId: piEvent.toolCallId, - tool: piEvent.toolName, - input: piEvent.input, - ts: now(), - seq: 0, - }; -} - -export function extractToolResult( - piEvent: PiToolResultEvent, - opts?: { debug?: boolean }, -): ToolResultEvent { - const { toolCallId, toolName, input, content, isError } = piEvent; - - const ev: ToolResultEvent = { - kind: "tool_result", - toolCallId, - tool: toolName, - error: isError, - ts: now(), - seq: 0, - }; - - // Capture output size for file and bash tools. - if (FILE_TOOLS.has(toolName) && !isError) { - const text = content.find((c) => c.type === "text")?.text ?? ""; - ev.lines = text.split("\n").length; - ev.chars = text.length; - } else if (toolName === "bash") { - const text = content.find((c) => c.type === "text")?.text ?? ""; - ev.lines = text.split("\n").length; - ev.chars = text.length; - } - - // Preserve koan tool response text for projection use (completionSummary). - if (toolName.startsWith("koan_")) { - ev.koanResponse = content - .filter((c) => c.type === "text" && c.text !== undefined) - .map((c) => c.text as string); - } - - // Debug mode: capture a bounded preview of tool output for designated tools. - // Only populated when debug is active; never written in normal mode. - // NOT folded into Projection — debug-only; never add to Projection. - if (opts?.debug && DEBUG_CAPTURE_TOOLS.has(toolName) && !isError) { - const text = content.find((c) => c.type === "text")?.text ?? ""; - ev.debugOutput = - text.slice(0, DEBUG_CAPTURE_LIMIT) + - (text.length > DEBUG_CAPTURE_LIMIT ? "\n\u2026[truncated]" : ""); - } - - void input; // suppress unused-variable warning (input is part of the public API shape) - - return ev; -} - -// -- EventLog -- - -export class EventLog { - private readonly eventsPath: string; - private readonly statePath: string; - private readonly stateTmpPath: string; - private fd: fs.FileHandle | null = null; - private seq = 0; - private projection: Projection; - private heartbeat: ReturnType | null = null; - // Serializes append() calls. Heartbeat timer and tool_result handler - // both call append() concurrently -- without serialization, two - // writeState() calls race on the shared tmp file (ENOENT on rename). - private pending: Promise = Promise.resolve(); - - constructor(dir: string, role: string, phase: string, model: string | null = null) { - this.eventsPath = path.join(dir, "events.jsonl"); - this.statePath = path.join(dir, "state.json"); - this.stateTmpPath = path.join(dir, "state.tmp.json"); - this.projection = { - role, - phase, - model, - status: "running", - step: 0, - totalSteps: 0, - stepName: "", - lastAction: null, - currentToolCallId: null, - updatedAt: now(), - eventCount: 0, - error: null, - completionSummary: null, - tokensSent: 0, - tokensReceived: 0, - lastToolResultAt: null, - }; - } - - async open(): Promise { - this.fd = await fs.open(this.eventsPath, "a"); - await this.writeState(); - // Heartbeat keeps updatedAt fresh even during long-running steps. - // unref() so the timer doesn't prevent process exit — pi's print mode - // relies on natural event loop drain (no process.exit()) and never - // emits session_shutdown, so EventLog.close() may not be called. - this.heartbeat = setInterval(() => { - void this.append({ kind: "heartbeat" } as Omit); - }, HEARTBEAT_MS); - this.heartbeat.unref(); - } - - // Assigns ts + seq, appends JSON line, folds, writes state atomically. - // Serialized: concurrent callers queue behind the in-flight write. - async append(partial: AuditEventPartial): Promise { - const task = () => this.doAppend(partial); - this.pending = this.pending.then(task, task); - return this.pending; - } - - private async doAppend(partial: AuditEventPartial): Promise { - if (!this.fd) { - throw new Error("EventLog.append called before open()"); - } - - const e = { ...partial, ts: now(), seq: this.seq++ } as AuditEvent; - await this.fd.write(JSON.stringify(e) + "\n"); - this.projection = fold(this.projection, e); - await this.writeState(); - } - - async emitPhaseStart(totalSteps: number): Promise { - await this.append({ - kind: "phase_start", - phase: this.projection.phase, - role: this.projection.role, - model: this.projection.model, - totalSteps, - } as Omit); - } - - async emitStepTransition(step: number, name: string, totalSteps: number): Promise { - await this.append({ - kind: "step_transition", - step, - name, - totalSteps, - } as Omit); - } - - async emitPhaseEnd(outcome: "completed" | "failed", detail?: string): Promise { - await this.append({ - kind: "phase_end", - outcome, - detail, - } as Omit); - } - - - - async close(): Promise { - if (this.heartbeat) { - clearInterval(this.heartbeat); - this.heartbeat = null; - } - if (this.fd) { - await this.fd.close(); - this.fd = null; - } - } - - get state(): Readonly { - return this.projection; - } - - // Atomic write: tmp file then rename so readers never see partial JSON. - private async writeState(): Promise { - const json = JSON.stringify(this.projection, null, 2) + "\n"; - await fs.writeFile(this.stateTmpPath, json); - await fs.rename(this.stateTmpPath, this.statePath); - } -} - -// -- Exports -- - -// Reads state.json as a Projection; returns null if missing or malformed. -// Used by web server polling loop. -export async function readProjection(dir: string): Promise { - try { - const raw = await fs.readFile(path.join(dir, "state.json"), "utf8"); - return JSON.parse(raw) as Projection; - } catch { - return null; - } -} diff --git a/src/planner/lib/ipc-responder.ts b/src/planner/lib/ipc-responder.ts deleted file mode 100644 index aafbf73..0000000 --- a/src/planner/lib/ipc-responder.ts +++ /dev/null @@ -1,319 +0,0 @@ -// Parent-side IPC responder: polls for requests from active subagents, -// handles them, and writes responses back. Runs concurrently with subagent -// process execution and terminates when the provided AbortSignal fires. -// -// Supports four request types: -// "ask" → route to web server, write answer back -// "scout-request" → spawn scouts via pool(), write findings paths back -// "artifact-review" → route to web server, write feedback back -// "workflow-decision" → route to web server, write feedback back - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import { - readIpcFile, - writeIpcFile, - createAskResponse, - createCancelledResponse, - type AskAnswerPayload, - type AskIpcFile, - type ScoutIpcFile, - type ArtifactReviewIpcFile, - type ArtifactReviewResponse, - type WorkflowDecisionIpcFile, - type WorkflowDecisionResponse, -} from "./ipc.js"; -import type { ScoutTask } from "./task.js"; -import { pool } from "./pool.js"; -import { readProjection } from "./audit.js"; -import { loadScoutConcurrency } from "../model-config.js"; -import type { WebServerHandle, AskQuestion, AnswerResult } from "../web/server-types.js"; -import { OTHER_OPTION } from "../web/server-types.js"; - -const POLL_INTERVAL_MS = 300; - -function sleep(ms: number): Promise { - return new Promise((resolve) => setTimeout(resolve, ms)); -} - -/** - * Provided by subagent.ts when starting the IPC responder. Avoids circular - * imports: ipc-responder.ts never imports from subagent.ts. - * - * `spawnScout` does not accept an `outputFile` argument — the output path is - * part of the task manifest (task.json). The responder writes `outputFile` - * into the ScoutTask before handing it to `spawnScout`, then resolves the - * absolute path via `path.join(subagentDir, scoutTask.outputFile)` itself. - */ -export interface ScoutSpawnContext { - epicDir: string; - // The role of the subagent that requested scouting (intake, decomposer, planner). - // Used for UI attribution when registering scouts with the web server. - parentRole: string; - // Spawns a single scout; returns exit code. - spawnScout: (task: ScoutTask, scoutSubagentDir: string) => Promise; -} - -// Handles a pending ask request: routes to web server, writes response. -async function handleAskRequest( - subagentDir: string, - ipc: AskIpcFile, - webServer: WebServerHandle, - signal: AbortSignal, -): Promise { - // Build the batch of questions, appending "Other" to each. - const questions: AskQuestion[] = ipc.questions.map((q) => ({ - id: q.id, - question: q.question, - context: q.context, - options: [...q.options.map((o) => ({ label: o.label })), { label: OTHER_OPTION }], - multi: q.multi, - recommended: q.recommended, - })); - - let result: AnswerResult; - try { - result = await webServer.requestAnswer(questions, signal); - } catch (err: unknown) { - if (err instanceof Error && (err.name === "AbortError" || signal.aborted)) { - const current = await readIpcFile(subagentDir); - if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { - await writeIpcFile(subagentDir, { ...current, response: createCancelledResponse(ipc.id) }); - } - return; - } - throw err; - } - - if (result.cancelled) { - const current = await readIpcFile(subagentDir); - if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { - await writeIpcFile(subagentDir, { ...current, response: createCancelledResponse(ipc.id) }); - } - return; - } - - // Map each answer element to AskAnswerPayload - const answers: AskAnswerPayload[] = result.answers.map((a) => { - const answer: AskAnswerPayload = { - id: a.questionId, - selectedOptions: a.selectedOptions, - }; - if (a.customInput !== undefined) { - answer.customInput = a.customInput; - } - return answer; - }); - - const response = createAskResponse(ipc.id, answers); - const current = await readIpcFile(subagentDir); - if (current !== null && current.type === "ask" && current.response === null && current.id === ipc.id) { - await writeIpcFile(subagentDir, { ...current, response }); - } -} - -// Handles a pending artifact-review request: routes to web server, writes feedback. -async function handleArtifactReviewRequest( - subagentDir: string, - ipc: ArtifactReviewIpcFile, - webServer: WebServerHandle, - signal: AbortSignal, -): Promise { - const { payload } = ipc; - - let feedback: string; - try { - const result = await webServer.requestArtifactReview(payload, signal); - feedback = result.feedback; - } catch (err: unknown) { - if (err instanceof Error && (err.name === "AbortError" || signal.aborted)) { - const current = await readIpcFile(subagentDir); - if (current !== null && current.type === "artifact-review" && current.response === null && current.id === ipc.id) { - const cancelledResponse: ArtifactReviewResponse = { - id: ipc.id, - respondedAt: new Date().toISOString(), - feedback: "Review cancelled.", - }; - await writeIpcFile(subagentDir, { ...current, response: cancelledResponse }); - } - return; - } - throw err; - } - - const response: ArtifactReviewResponse = { - id: ipc.id, - respondedAt: new Date().toISOString(), - feedback, - }; - // Re-read and validate before writing — idempotence guard against stale requests. - const current = await readIpcFile(subagentDir); - if (current !== null && current.type === "artifact-review" && current.response === null && current.id === ipc.id) { - await writeIpcFile(subagentDir, { ...current, response }); - } -} - -// Handles a pending workflow-decision request: routes to web server, writes feedback. -async function handleWorkflowDecisionRequest( - subagentDir: string, - ipc: WorkflowDecisionIpcFile, - webServer: WebServerHandle, - signal: AbortSignal, -): Promise { - const { payload } = ipc; - - let feedback: string; - try { - const result = await webServer.requestWorkflowDecision(payload, signal); - feedback = result.feedback; - } catch (err: unknown) { - if (err instanceof Error && (err.name === "AbortError" || signal.aborted)) { - const current = await readIpcFile(subagentDir); - if (current !== null && current.type === "workflow-decision" && current.response === null && current.id === ipc.id) { - const cancelledResponse: WorkflowDecisionResponse = { - id: ipc.id, - respondedAt: new Date().toISOString(), - feedback: "Decision cancelled.", - }; - await writeIpcFile(subagentDir, { ...current, response: cancelledResponse }); - } - return; - } - throw err; - } - - const response: WorkflowDecisionResponse = { - id: ipc.id, - respondedAt: new Date().toISOString(), - feedback, - }; - // Re-read and validate before writing — idempotence guard against stale requests. - const current = await readIpcFile(subagentDir); - if (current !== null && current.type === "workflow-decision" && current.response === null && current.id === ipc.id) { - await writeIpcFile(subagentDir, { ...current, response }); - } -} - -// Handles a pending scout-request: spawns scouts via pool(), writes findings. -async function handleScoutRequest( - subagentDir: string, - ipc: ScoutIpcFile, - scoutCtx: ScoutSpawnContext, - webServer: WebServerHandle | undefined, - signal: AbortSignal, -): Promise { - const { scouts: ipcScouts, id } = ipc; - const findings: string[] = []; - - // Compute per-scout directories. Scout dirs live under the epic's subagents/ - // directory so they appear in the standard directory layout. - const scoutEntries = ipcScouts.map((ipcTask) => { - const scoutDir = path.join(scoutCtx.epicDir, "subagents", `scout-${ipcTask.id}-${Date.now()}`); - return { ipcTask, subagentDir: scoutDir }; - }); - - // Clear finished agents from previous rounds so the UI starts clean. - // Without this, completed scouts from round N stay in the table when - // round N+1 begins — a visual leak since no phase transition fires. - webServer?.evictFinishedAgents(); - - // Register scouts with the web server as queued (status: null) so the UI - // shows them immediately. They transition to "running" when the pool picks - // them up and the pi process is actually launched. - if (webServer) { - for (const entry of scoutEntries) { - webServer.registerAgent({ - id: entry.ipcTask.id, - name: entry.ipcTask.id, - dir: entry.subagentDir, - role: "scout", - model: null, - parent: scoutCtx.parentRole, - status: null, - }); - } - } - - const taskIds = scoutEntries.map((t) => t.ipcTask.id); - const concurrency = await loadScoutConcurrency(); - const poolResult = await pool( - taskIds, - concurrency, - async (taskId) => { - if (signal.aborted) return false; - - const entry = scoutEntries.find((t) => t.ipcTask.id === taskId)!; - webServer?.startAgent(taskId); - await fs.mkdir(entry.subagentDir, { recursive: true }); - - // Construct the task manifest for this scout. The IPC-level ipcTask carries - // id/role/prompt (LLM-facing); the task manifest carries the full SubagentTask - // fields the scout process needs. - const scoutTask: ScoutTask = { - role: "scout", - epicDir: scoutCtx.epicDir, - question: entry.ipcTask.prompt, - outputFile: "findings.md", // relative -- ScoutPhase resolves to absolute - investigatorRole: entry.ipcTask.role, - }; - - const exitCode = await scoutCtx.spawnScout(scoutTask, entry.subagentDir); - - // Derive success from the JSON audit projection, not from file existence. - // A scout can write a partial findings.md and then crash. - let succeeded = false; - if (exitCode === 0) { - const projection = await readProjection(entry.subagentDir); - succeeded = projection?.status === "completed"; - } - - if (succeeded) { - const absoluteOutputFile = path.join(entry.subagentDir, scoutTask.outputFile); - findings.push(absoluteOutputFile); - } - - if (webServer) { - webServer.completeAgent(taskId); - } - - return succeeded; - }, - ); - - // Re-read and validate before writing response -- idempotence guard. - const current = await readIpcFile(subagentDir); - if (current !== null && current.type === "scout-request" && current.response === null && current.id === id) { - const updated: ScoutIpcFile = { ...current, response: { findings, failures: poolResult.failed } }; - await writeIpcFile(subagentDir, updated); - } -} - -export async function runIpcResponder( - subagentDir: string, - webServer: WebServerHandle, - signal: AbortSignal, - scoutContext?: ScoutSpawnContext, -): Promise { - while (!signal.aborted) { - try { - await sleep(POLL_INTERVAL_MS); - if (signal.aborted) break; - - const ipc = await readIpcFile(subagentDir); - if (ipc === null || ipc.response !== null) continue; - - if (ipc.type === "ask") { - await handleAskRequest(subagentDir, ipc, webServer, signal); - } else if (ipc.type === "scout-request" && scoutContext) { - await handleScoutRequest(subagentDir, ipc, scoutContext, webServer, signal); - } else if (ipc.type === "artifact-review") { - await handleArtifactReviewRequest(subagentDir, ipc, webServer, signal); - } else if (ipc.type === "workflow-decision") { - await handleWorkflowDecisionRequest(subagentDir, ipc, webServer, signal); - } - } catch { - // Swallow all errors — transient filesystem issues must not abort the parent session. - } - } -} diff --git a/src/planner/lib/ipc.ts b/src/planner/lib/ipc.ts deleted file mode 100644 index 2a24665..0000000 --- a/src/planner/lib/ipc.ts +++ /dev/null @@ -1,308 +0,0 @@ -// File-based IPC between subagent and parent session. -// A single ipc.json file per subagent directory holds the current request and -// its response. Atomic writes (tmp-rename) prevent partial reads. -// -// IPC protocol supports four message types (see docs/subagents.md): -// "ask" — subagent asks the user a question -// "scout-request" — subagent requests parallel codebase scout spawning -// "artifact-review" — subagent presents a written artifact for human review -// "workflow-decision" — workflow orchestrator requests user direction on next phase - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; -import * as crypto from "node:crypto"; - -// -- Scout types -- - -/** IPC-level scout request: id/role/prompt fields sent by the LLM-facing tool. */ -export interface ScoutRequest { - id: string; // Unique task ID, e.g. "auth-libs" - role: string; // Custom role description for the scout - prompt: string; // What the scout should find -} - -export interface ScoutResponse { - findings: string[]; // File paths to scout output markdown files (absolute) - failures: string[]; // Scout task IDs that failed (non-fatal) -} - -// -- Ask types -- - -export interface AskQuestionPayload { - id: string; - question: string; - context?: string; - options: Array<{ label: string }>; - multi?: boolean; - recommended?: number; -} - -export interface AskAnswerPayload { - id: string; - selectedOptions: string[]; - customInput?: string; -} - -export interface AskResponse { - id: string; - respondedAt: string; - cancelled: boolean; - answers: AskAnswerPayload[]; -} - -// -- Artifact review types -- - -export interface ArtifactReviewPayload { - artifactPath: string; // relative path within epic dir (e.g., "brief.md") - content: string; // raw markdown content of the artifact - description?: string; // optional context for the reviewer -} - -export interface ArtifactReviewResponse { - id: string; - respondedAt: string; - feedback: string; // "Accept" or free-form text -} - -// -- Workflow decision types -- - -export interface WorkflowPhaseOption { - phase: string; // EpicPhase value - label: string; // human-readable, e.g. "Write Epic Brief" - context: string; // why this phase is useful right now - recommended?: boolean; -} - -export interface WorkflowDecisionPayload { - statusReport: string; // markdown summary of current state - recommendedPhases: WorkflowPhaseOption[]; - completedPhase: string; // the just-completed phase -} - -export interface WorkflowDecisionResponse { - id: string; - respondedAt: string; - feedback: string; // user's free-form text response -} - -// -- IPC file union -- - -export interface AskIpcFile { - type: "ask"; - id: string; - createdAt: string; - questions: AskQuestionPayload[]; - response: AskResponse | null; -} - -export interface ScoutIpcFile { - type: "scout-request"; - id: string; - createdAt: string; - scouts: ScoutRequest[]; - response: ScoutResponse | null; -} - -export interface ArtifactReviewIpcFile { - type: "artifact-review"; - id: string; - createdAt: string; - payload: ArtifactReviewPayload; - response: ArtifactReviewResponse | null; -} - -export interface WorkflowDecisionIpcFile { - type: "workflow-decision"; - id: string; - createdAt: string; - payload: WorkflowDecisionPayload; - response: WorkflowDecisionResponse | null; -} - -export type IpcFile = - | AskIpcFile - | ScoutIpcFile - | ArtifactReviewIpcFile - | WorkflowDecisionIpcFile; - -// -- File paths -- - -const IPC_FILE = "ipc.json"; -const IPC_TMP_FILE = ".ipc.tmp.json"; - -// -- I/O helpers -- - -// Atomic write: .ipc.tmp.json → ipc.json rename. -export async function writeIpcFile(dir: string, data: IpcFile): Promise { - const tmp = path.join(dir, IPC_TMP_FILE); - const target = path.join(dir, IPC_FILE); - await fs.writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8"); - await fs.rename(tmp, target); -} - -// Returns null on missing file or parse error. -// Treats parse errors as "not ready" to handle partial writes on non-POSIX systems. -export async function readIpcFile(dir: string): Promise { - try { - const raw = await fs.readFile(path.join(dir, IPC_FILE), "utf8"); - return JSON.parse(raw) as IpcFile; - } catch { - return null; - } -} - -// Fast existence check without parsing. -export async function ipcFileExists(dir: string): Promise { - try { - await fs.access(path.join(dir, IPC_FILE)); - return true; - } catch { - return false; - } -} - -// Removes ipc.json and any lingering .ipc.tmp.json; swallows ENOENT. -export async function deleteIpcFile(dir: string): Promise { - for (const name of [IPC_FILE, IPC_TMP_FILE]) { - try { - await fs.unlink(path.join(dir, name)); - } catch (err: unknown) { - if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err; - } - } -} - -// -- Factory helpers -- - -export function createAskRequest(questions: AskQuestionPayload[]): AskIpcFile { - return { - type: "ask", - id: crypto.randomUUID(), - createdAt: new Date().toISOString(), - questions, - response: null, - }; -} - -export function createScoutRequest(scouts: ScoutRequest[]): ScoutIpcFile { - return { - type: "scout-request", - id: crypto.randomUUID(), - createdAt: new Date().toISOString(), - scouts, - response: null, - }; -} - -export function createArtifactReviewRequest(payload: ArtifactReviewPayload): ArtifactReviewIpcFile { - return { - type: "artifact-review", - id: crypto.randomUUID(), - createdAt: new Date().toISOString(), - payload, - response: null, - }; -} - -export function createWorkflowDecisionRequest(payload: WorkflowDecisionPayload): WorkflowDecisionIpcFile { - return { - type: "workflow-decision", - id: crypto.randomUUID(), - createdAt: new Date().toISOString(), - payload, - response: null, - }; -} - -export function createAskResponse(requestId: string, answers: AskAnswerPayload[]): AskResponse { - return { - id: requestId, - respondedAt: new Date().toISOString(), - cancelled: false, - answers, - }; -} - -export function createCancelledResponse(requestId: string): AskResponse { - return { - id: requestId, - respondedAt: new Date().toISOString(), - cancelled: true, - answers: [], - }; -} - -// -- Poll helper -- - -function sleep(ms: number): Promise { - return new Promise((resolve) => setTimeout(resolve, ms)); -} - -/** Outcome of a single pollIpcUntilResponse call. */ -export type PollOutcome = "answered" | "cancelled" | "aborted" | "file-gone" | "completed"; - -/** Return value of pollIpcUntilResponse: outcome tag + the IPC file snapshot (if any). */ -export interface PollIpcResult { - outcome: PollOutcome; - ipc: IpcFile | null; -} - -/** - * Poll ipc.json until a response appears, the signal aborts, or the file vanishes. - * - * Extracted because executeAskQuestion and executeRequestScouts share identical - * poll logic. The finally block guarantees ipc.json deletion even when the signal - * aborts mid-poll -- without it, a stale ipc.json would block the next tool call. - */ -export async function pollIpcUntilResponse( - dir: string, - ipc: IpcFile, - signal?: AbortSignal | null, -): Promise { - let aborted = false; - const onAbort = () => { aborted = true; }; - if (signal) signal.addEventListener("abort", onAbort, { once: true }); - - let outcome: PollOutcome = "file-gone"; - let finalIpc: IpcFile | null = null; - - try { - while (!aborted) { - await sleep(500); - if (signal?.aborted) { aborted = true; break; } - - const current = await readIpcFile(dir); - if (current === null) { outcome = "file-gone"; break; } - - if (current.type === "ask" && current.response !== null && current.response.id === ipc.id) { - outcome = current.response.cancelled ? "cancelled" : "answered"; - finalIpc = current; - break; - } - - if (current.type === "scout-request" && current.response !== null && current.id === ipc.id) { - outcome = "completed"; - finalIpc = current; - break; - } - - if (current.type === "artifact-review" && current.response !== null && current.id === ipc.id) { - outcome = "answered"; - finalIpc = current; - break; - } - - if (current.type === "workflow-decision" && current.response !== null && current.id === ipc.id) { - outcome = "answered"; - finalIpc = current; - break; - } - } - - if (aborted) outcome = "aborted"; - } finally { - await deleteIpcFile(dir); - } - - return { outcome, ipc: finalIpc }; -} diff --git a/src/planner/lib/permissions.ts b/src/planner/lib/permissions.ts deleted file mode 100644 index f0afccc..0000000 --- a/src/planner/lib/permissions.ts +++ /dev/null @@ -1,211 +0,0 @@ -// Default-deny role-based permissions for koan subagents. -// -// Permission model overview: -// 1. READ_TOOLS (bash, read, grep, glob, find, ls) are always allowed for all -// roles. This is an accepted limitation: distinguishing -// "read bash" from "write bash" is intractable at the permission layer. -// Prompt engineering constrains intended bash use; enforcement does not. -// Do not assume bash is restricted to roles that list it explicitly. -// -// 2. ROLE_PERMISSIONS controls koan-specific tools and write/edit access. -// Unknown roles are blocked under default-deny policy. -// -// 3. Planning roles (intake, scout, decomposer, brief-writer, orchestrator, -// planner, workflow-orchestrator) have write/edit access path-scoped to -// the epic directory. Only the executor role has unrestricted write access -// — it must modify the codebase. - -import * as path from "node:path"; - -import { createLogger } from "../../utils/logger.js"; - -const log = createLogger("permissions"); - -// Read tools always allowed for all roles — early return in checkPermission. -const READ_TOOLS = new Set(["read", "bash", "grep", "glob", "find", "ls"]); -const WRITE_TOOLS = new Set(["edit", "write"]); - -// Tools allowed per role beyond READ_TOOLS. -// Write/edit are tracked here but enforced via path-scoping below. -export const ROLE_PERMISSIONS: ReadonlyMap> = new Map([ - [ - "intake", - new Set([ - "koan_complete_step", - "koan_ask_question", - "koan_request_scouts", - "koan_review_artifact", - "edit", - "write", - ]), - ], - [ - "scout", - new Set([ - "koan_complete_step", - "edit", - "write", - // No koan_ask_question — scouts are narrow investigators; no user interaction. - // No koan_request_scouts — scouts do not spawn scouts. - ]), - ], - [ - "decomposer", - new Set([ - "koan_complete_step", - "koan_ask_question", - "koan_request_scouts", - "edit", - "write", - ]), - ], - [ - "brief-writer", - new Set([ - "koan_complete_step", - "koan_review_artifact", - "edit", - "write", - // No koan_ask_question — the brief-writer uses artifact review, not structured questions. - // No koan_request_scouts — all codebase context arrives via landscape.md from intake. - ]), - ], - [ - "orchestrator", - new Set([ - "koan_complete_step", - "koan_ask_question", - // koan_request_scouts excluded from orchestrator — scouts serve planning roles; - // orchestrator uses bash for verification. - "koan_select_story", - "koan_complete_story", - "koan_retry_story", - "koan_skip_story", - "edit", - "write", - "bash", // also in READ_TOOLS; explicit here for documentation - ]), - ], - [ - "planner", - new Set([ - "koan_complete_step", - "koan_ask_question", - "koan_request_scouts", - "edit", - "write", - ]), - ], - [ - "executor", - new Set([ - "koan_complete_step", - "koan_ask_question", - "edit", - "write", - "bash", // also in READ_TOOLS; explicit here for documentation - ]), - ], - [ - "workflow-orchestrator", - new Set([ - "koan_complete_step", - "koan_propose_workflow", - "koan_set_next_phase", - // No koan_ask_question — koan_propose_workflow handles user interaction - // No koan_request_scouts — orchestrator reads existing artifacts only - // No write/edit — orchestrator routes, it does not produce artifacts - ]), - ], -]); - -// Planning roles write only inside the epic directory. -// Executor has unrestricted write access (must implement stories in the codebase). -const PLANNING_ROLES = new Set([ - "intake", - "scout", - "decomposer", - "brief-writer", - "orchestrator", - "planner", - "workflow-orchestrator", -]); - -// STEP_1_BLOCKED_TOOLS: tools disallowed during the intake Extract step (step 1) -// and brief-writer Read step (step 1). Step 1 is read-only comprehension. -// Blocking these tools here provides a mechanical enforcement layer on top of -// the prompt-level prohibition. -const STEP_1_BLOCKED_TOOLS = new Set([ - "koan_request_scouts", - "koan_ask_question", - "write", - "edit", -]); - -export function checkPermission( - role: string, - toolName: string, - epicDir?: string, - toolArgs?: Record, - currentStep?: number, -): { allowed: boolean; reason?: string } { - // Read tools are always allowed — check before role map lookup. - if (READ_TOOLS.has(toolName)) { - return { allowed: true }; - } - - // Intake step 1 (Extract) is read-only: block all side-effecting tools so - // the LLM cannot frontload scouting or question-asking before it has read - // and understood the conversation. - if (role === "intake" && currentStep === 1 && STEP_1_BLOCKED_TOOLS.has(toolName)) { - return { - allowed: false, - reason: `${toolName} is not available during the Extract step (step 1). ` + - "Complete koan_complete_step first to advance to the Scout step.", - }; - } - - // Brief-writer step 1 (Read) is read-only: block write and edit so the LLM - // cannot draft files before it has comprehended landscape.md. - if (role === "brief-writer" && currentStep === 1 && STEP_1_BLOCKED_TOOLS.has(toolName)) { - return { - allowed: false, - reason: `${toolName} is not available during the Read step (step 1). ` + - "Complete koan_complete_step first to advance to the Draft & Review step.", - }; - } - - // Unknown role: blocked under default-deny policy. - if (!ROLE_PERMISSIONS.has(role)) { - log("Unknown role blocked", { role, toolName }); - return { allowed: false, reason: `Unknown role: ${role}` }; - } - - const roleAllowed = ROLE_PERMISSIONS.get(role)!; - - if (!roleAllowed.has(toolName)) { - return { allowed: false, reason: `${toolName} is not available for role ${role}` }; - } - - // Path-scope enforcement: planning roles may only write inside the epic directory. - if (WRITE_TOOLS.has(toolName) && PLANNING_ROLES.has(role)) { - if (epicDir && toolArgs) { - const rawPath = toolArgs["path"]; - if (typeof rawPath === "string") { - const resolvedTool = path.resolve(rawPath); - const resolvedEpic = path.resolve(epicDir); - if (!resolvedTool.startsWith(resolvedEpic + path.sep) && resolvedTool !== resolvedEpic) { - log("Write blocked: path outside epic dir", { role, toolName, rawPath, epicDir }); - return { - allowed: false, - reason: `${toolName} path "${rawPath}" is outside epic directory`, - }; - } - } - } - // No epicDir or no path arg: allow (cannot scope-check without context). - return { allowed: true }; - } - - return { allowed: true }; -} diff --git a/src/planner/lib/phase-dag.ts b/src/planner/lib/phase-dag.ts deleted file mode 100644 index bccf091..0000000 --- a/src/planner/lib/phase-dag.ts +++ /dev/null @@ -1,74 +0,0 @@ -// Phase transition DAG — the single source of truth for valid epic phase transitions. -// -// Consulted by: -// - the driver (to decide whether to spawn the orchestrator or auto-advance) -// - koan_set_next_phase (to validate the committed transition) -// - WorkflowOrchestratorPhase step 2 guidance (lists available phases) -// -// Updating the DAG here is sufficient when adding new successor edges. -// Promoting a stub phase to a real implementation additionally requires the -// Phase Promotion Checklist in docs/architecture.md. - -import type { EpicPhase } from "../types.js"; - -/** Valid successor phases for each phase. Order = recommendation priority. - * The first entry is the most-recommended default path when the orchestrator - * presents options. */ -export const PHASE_TRANSITIONS: Readonly> = { - "intake": ["brief-generation", "core-flows"], - "brief-generation": ["core-flows"], - "core-flows": ["tech-plan"], - "tech-plan": ["ticket-breakdown"], - "ticket-breakdown": ["cross-artifact-validation"], - "cross-artifact-validation": ["execution"], - "execution": ["implementation-validation"], - "implementation-validation": ["completed"], - "completed": [], -}; - -/** Phases that have a real implementation (subagent-backed). - * All other phases are stubs that auto-advance when reached. - * Add a phase here when promoting its stub to a real implementation. */ -export const IMPLEMENTED_PHASES: ReadonlySet = new Set([ - "intake", - "brief-generation", -]); - -/** Returns valid next phases from the DAG. */ -export function getSuccessorPhases(phase: EpicPhase): readonly EpicPhase[] { - return PHASE_TRANSITIONS[phase] ?? []; -} - -/** True when the driver can auto-advance without consulting the orchestrator. - * A single successor means the transition is unambiguous — spawning an - * orchestrator would add latency and LLM cost with no user value. */ -export function isAutoAdvance(phase: EpicPhase): boolean { - return getSuccessorPhases(phase).length === 1; -} - -/** True when the phase has no subagent implementation and should be skipped. - * Stubs log a placeholder message and carry forward pendingInstructions. */ -export function isStubPhase(phase: EpicPhase): boolean { - return phase !== "completed" && !IMPLEMENTED_PHASES.has(phase); -} - -/** Validates that a proposed transition is legal before committing. - * Called by koan_set_next_phase to prevent the orchestrator from - * hallucinating a phase name not in the DAG. */ -export function isValidTransition(from: EpicPhase, to: EpicPhase): boolean { - return getSuccessorPhases(from).includes(to); -} - -/** Human-readable one-line description of each phase. - * Used by writeWorkflowStatus() and the orchestrator's step 2 guidance. */ -export const PHASE_DESCRIPTIONS: Readonly> = { - "intake": "Multi-round codebase exploration and structured Q&A to align on requirements", - "brief-generation": "Distill intake context into a compact product-level epic brief", - "core-flows": "Define user journeys with sequence diagrams", - "tech-plan": "Specify technical architecture: approach, data model, component design", - "ticket-breakdown": "Generate story-sized implementation tickets with dependency diagrams", - "cross-artifact-validation": "Validate cross-boundary consistency across all spec artifacts", - "execution": "Implement tickets through a supervised batch process with verification", - "implementation-validation": "Post-execution review evaluating alignment and correctness against specs", - "completed": "Pipeline complete", -}; diff --git a/src/planner/lib/pool.ts b/src/planner/lib/pool.ts deleted file mode 100644 index e54d5cc..0000000 --- a/src/planner/lib/pool.ts +++ /dev/null @@ -1,91 +0,0 @@ -// Bounded-parallel subagent pool using an in-process semaphore. -// Runs all items to completion regardless of individual failures. -// Timeout logic belongs in the worker closure, not here. - -// -- Types -- - -export interface PoolResult { - total: number; - completed: number; - failed: string[]; -} - -export interface PoolProgress { - done: number; - total: number; - active: number; - queued: number; -} - -// -- Private helpers -- - -class Semaphore { - private readonly queue: Array<() => void> = []; - private count: number; - - constructor(limit: number) { - this.count = limit; - } - - acquire(): Promise { - if (this.count > 0) { - this.count--; - return Promise.resolve(); - } - return new Promise((resolve) => this.queue.push(resolve)); - } - - release(): void { - const next = this.queue.shift(); - if (next) next(); - else this.count++; - } -} - -// -- Exports -- - -export async function pool( - itemIds: string[], - limit: number, - worker: (itemId: string) => Promise, - onProgress?: (progress: PoolProgress) => void, -): Promise { - const sem = new Semaphore(limit); - const total = itemIds.length; - const failed: string[] = []; - let completed = 0; - let running = 0; - - const emit = () => { - onProgress?.({ - done: completed, - total, - active: running, - queued: Math.max(0, total - completed - running), - }); - }; - - emit(); - - await Promise.all( - itemIds.map(async (id) => { - await sem.acquire(); - running++; - emit(); - - try { - const ok = await worker(id); - if (!ok) { - failed.push(id); - } - } finally { - running = Math.max(0, running - 1); - completed++; - emit(); - sem.release(); - } - }), - ); - - return { total, completed, failed }; -} diff --git a/src/planner/lib/runtime-context.ts b/src/planner/lib/runtime-context.ts deleted file mode 100644 index f625a66..0000000 --- a/src/planner/lib/runtime-context.ts +++ /dev/null @@ -1,53 +0,0 @@ -// RuntimeContext replaces the old PlanRef + SubagentRef + WorkflowDispatch triple. -// Set once during before_agent_start; tools read from it at call time. The mutable-ref -// pattern accommodates pi's extension lifecycle: tools register at init before state exists. -// -// onCompleteStep return value: -// string -> next step's formatted prompt (tool returns it to the LLM) -// null -> phase is complete (tool returns "Phase complete.") -// -// currentStep is kept on RuntimeContext (not on individual phases) because -// BasePhase's permission fence reads it on every tool_call event without -// knowing the active phase type. -// -// eventLog: the active EventLog for the current subagent session. Set during -// before_agent_start after the log file is opened. Tools that need to emit -// audit events read this at call time. -// -// phaseInstructions: optional context injected by the workflow orchestrator's -// decision. Present when the user provided focus instructions during the -// workflow decision interaction. Absent when the orchestrator is skipped or -// the user gave no additional direction. Applies uniformly to all phases. -// -// debugMode: true when the parent session was launched with --koan-debug. -// Forwarded to child processes via the CLI flag. Enables verbatim step -// guidance text in the activity feed (audit-log-formatter) and bounded -// debug output capture for designated tools (extractToolResult). - -import type { EventLog } from "./event-log.js"; - -export interface RuntimeContext { - epicDir: string | null; - subagentDir: string | null; - onCompleteStep: ((thoughts: string) => Promise) | null; - currentStep: number; - eventLog: EventLog | null; - /** Optional instructions from the workflow orchestrator's decision. - * Injected into step 1 guidance when the user provides context during - * the workflow decision interaction. */ - phaseInstructions?: string; - /** True when the parent session was launched with --koan-debug. - * Set during before_agent_start from the CLI flag. */ - debugMode: boolean; -} - -export function createRuntimeContext(): RuntimeContext { - return { - epicDir: null, - subagentDir: null, - onCompleteStep: null, - currentStep: 0, - eventLog: null, - debugMode: false, - }; -} diff --git a/src/planner/lib/step.ts b/src/planner/lib/step.ts deleted file mode 100644 index 0e4fc6f..0000000 --- a/src/planner/lib/step.ts +++ /dev/null @@ -1,60 +0,0 @@ -// Step prompt assembly for koan phase workflows. -// -// formatStep() wraps step guidance with a header and a mandatory invoke-after -// directive. The directive at the END of every step is as important as the -// boot prompt at the beginning: primacy (first message) establishes the -// koan_complete_step habit; recency (last thing in each step) reinforces it. -// Together they make the calling pattern robust across model capability levels. -// -// ## The `thoughts` parameter invariant -// -// `thoughts` on koan_complete_step is an ESCAPE HATCH, not a data channel. -// -// Many LLMs cannot produce both text output and a tool call in the same -// response. Without `thoughts`, these models would have no way to do -// chain-of-thought reasoning (lists, chain-of-draft, working through items -// one-by-one) while still calling koan_complete_step to advance the workflow. -// The parameter gives them a place to write intermediate reasoning. -// -// Extended thinking / blocks exist but are insufficient: not all -// models support them, they are not visible in audit logs, and some reasoning -// patterns (e.g., "write down a list of X items and evaluate each") work -// better as explicit text the model can reference in subsequent turns. -// -// THE INVARIANT: `thoughts` must NEVER be actively used to capture task -// output. No summaries, no reports, no structured data. Step instructions -// must NOT say "put your findings in the `thoughts` parameter" or similar. -// Task output goes to files (findings.md, landscape.md, plan.md, etc.). -// The LLM may fill `thoughts` with whatever it wants — that's fine — but -// no prompt should instruct it to put specific content there. -// -// A 500-char prefix of `thoughts` is captured in the audit projection as -// `completionSummary` for UI display — this is incidental, not a contract. - -export interface StepGuidance { - title: string; - instructions: string[]; - // Override the default "WHEN DONE: Call koan_complete_step..." directive. - // Use for terminal steps that must call a domain tool (e.g. koan_select_story) - // before koan_complete_step, or for steps where the completion signal differs. - invokeAfter?: string; -} - -// Appended to every step that doesn't override invokeAfter. -// Positioned last for recency — LLMs weight end-of-context instructions heavily. -// -// NOTE: The default invoke deliberately does NOT mention the `thoughts` parameter. -// See the invariant above — `thoughts` is an escape hatch for models that can't -// mix text + tool_call, not a data channel. Prompts must not instruct the LLM -// to put specific content there. -const DEFAULT_INVOKE = [ - "WHEN DONE: Call koan_complete_step to advance to the next step.", - "Do NOT call this tool until the work described in this step is finished.", -].join("\n"); - -export function formatStep(g: StepGuidance): string { - const header = `${g.title}\n${"=".repeat(g.title.length)}\n\n`; - const body = g.instructions.join("\n"); - const invoke = g.invokeAfter ?? DEFAULT_INVOKE; - return `${header}${body}\n\n${invoke}`; -} diff --git a/src/planner/lib/task.ts b/src/planner/lib/task.ts deleted file mode 100644 index 6188404..0000000 --- a/src/planner/lib/task.ts +++ /dev/null @@ -1,140 +0,0 @@ -// Subagent task manifest — the input contract for every subagent process. -// Written by the parent to {subagentDir}/task.json before spawn; -// read by the child exactly once at startup via readTaskFile(). -// -// This is one of three well-known JSON files in every subagent directory: -// task.json — what to do (parent writes before spawn, child reads once) -// state.json — what has been done (child writes continuously, parent polls) -// ipc.json — what is needed now (both sides, transient per-request) -// -// The discriminated union on `role` keeps role-specific fields naturally -// nested rather than collapsed into a flat CLI flag namespace. This directly -// prevents the naming collisions the old flag approach produced — e.g., the -// previous `--koan-role` (pipeline role: "scout") vs `--koan-scout-role` -// (investigator persona: "security auditor") collision is impossible here -// because ScoutTask.role and ScoutTask.investigatorRole are distinct typed -// fields on a struct, not adjacent strings in a flat namespace. - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import type { SubagentRole, StepSequence, EpicPhase } from "../types.js"; - -// -- Task types -- - -interface SubagentTaskBase { - role: SubagentRole; - epicDir: string; - /** Optional instructions from the workflow orchestrator's decision. - * Injected into step 1 guidance of the next phase when the user provides - * context during the workflow decision interaction. Absent when the - * orchestrator is skipped or when the user gives no additional direction. - * JSON.stringify omits undefined values, so existing construction sites - * ({ role, epicDir }) remain valid subtypes. */ - phaseInstructions?: string; -} - -/** Task manifest for intake subagents. */ -export interface IntakeTask extends SubagentTaskBase { - role: "intake"; -} - -/** - * Task manifest for scout subagents. Written by the IPC responder when a - * planning role (intake, decomposer, planner) calls koan_request_scouts. - */ -export interface ScoutTask extends SubagentTaskBase { - role: "scout"; - /** The narrow investigation question, injected verbatim into step 1 guidance. */ - question: string; - /** - * Output path relative to subagentDir (e.g. "findings.md"). - * Stored relative so the manifest is location-independent. - * Resolved to absolute by dispatch: `path.join(ctx.subagentDir!, task.outputFile)`. - */ - outputFile: string; - /** Investigator persona for the scout LLM (e.g. "security auditor", "API analyst"). */ - investigatorRole: string; -} - -/** Task manifest for decomposer subagents. */ -export interface DecomposerTask extends SubagentTaskBase { - role: "decomposer"; -} - -/** Task manifest for brief-writer subagents. */ -export interface BriefWriterTask extends SubagentTaskBase { - role: "brief-writer"; -} - -/** Task manifest for orchestrator subagents. */ -export interface OrchestratorTask extends SubagentTaskBase { - role: "orchestrator"; - stepSequence: StepSequence; - storyId?: string; -} - -/** Task manifest for planner subagents. */ -export interface PlannerTask extends SubagentTaskBase { - role: "planner"; - storyId: string; -} - -/** Task manifest for executor subagents. */ -export interface ExecutorTask extends SubagentTaskBase { - role: "executor"; - storyId: string; - /** - * Failure summary from a previous execution attempt, sourced from the - * `failure_summary` parameter of `koan_retry_story`. Absent on first run. - */ - retryContext?: string; -} - -/** Task manifest for workflow-orchestrator subagents. */ -export interface WorkflowOrchestratorTask extends SubagentTaskBase { - role: "workflow-orchestrator"; - /** The phase that just completed — used by the orchestrator as context. */ - completedPhase: EpicPhase; - /** Valid successor phases from the DAG — orchestrator proposes from this list. */ - availablePhases: EpicPhase[]; -} - -// The union is exhaustive over all roles. TypeScript narrows task.role -// in switch/case so role-specific fields are accessible without casting. -export type SubagentTask = - | IntakeTask - | ScoutTask - | DecomposerTask - | BriefWriterTask - | OrchestratorTask - | PlannerTask - | ExecutorTask - | WorkflowOrchestratorTask; - -// -- File paths -- - -const TASK_FILE = "task.json"; -const TASK_TMP_FILE = ".task.tmp.json"; - -// -- I/O -- - -// Atomically writes task.json to subagentDir (tmp → rename). -// MUST be called before spawn() — the child reads this file at startup and -// throws if it is missing. There is no recovery path if it arrives late. -export async function writeTaskFile(subagentDir: string, task: SubagentTask): Promise { - const tmp = path.join(subagentDir, TASK_TMP_FILE); - const target = path.join(subagentDir, TASK_FILE); - await fs.writeFile(tmp, `${JSON.stringify(task, null, 2)}\n`, "utf8"); - await fs.rename(tmp, target); -} - -// Reads and parses task.json from subagentDir. -// Called exactly once, during before_agent_start in koan.ts. -// Throws on missing file or JSON parse error — both indicate a programming -// error in the parent (wrote no file, or wrote malformed JSON), not a -// recoverable runtime condition. -export async function readTaskFile(subagentDir: string): Promise { - const raw = await fs.readFile(path.join(subagentDir, TASK_FILE), "utf8"); - return JSON.parse(raw) as SubagentTask; -} diff --git a/src/planner/lib/time.ts b/src/planner/lib/time.ts deleted file mode 100644 index b9bf4b5..0000000 --- a/src/planner/lib/time.ts +++ /dev/null @@ -1,3 +0,0 @@ -export function now(): string { - return new Date().toISOString(); -} diff --git a/src/planner/lib/truncation-override.ts b/src/planner/lib/truncation-override.ts deleted file mode 100644 index d7e2338..0000000 --- a/src/planner/lib/truncation-override.ts +++ /dev/null @@ -1,90 +0,0 @@ -// Raises the effective truncation limit for bash tool output in koan subagents. -// -// Pi's built-in bash tool truncates output to 50KB / 2000 lines. When the -// prompt-engineer skill (or any skill that concatenates large reference files -// to stdout) runs via bash, the LLM loses critical context mid-output. -// -// Instead of replacing the built-in bash tool, we intercept the tool_result -// event. When truncation occurred, the bash tool has already saved the full -// output to a temp file. We re-read that file and apply truncateTail with -// higher limits, then return the replacement content. This is surgical — -// it only activates when truncation actually happened and a temp file exists. -// -// Why tool_result interception rather than registering a replacement bash tool: -// - No duplication of the bash tool implementation (exec, streaming, exit codes) -// - The bash tool's temp file mechanism is the key enabler — the full output -// is already on disk before the event fires -// - Zero cost when output fits within the default limits (handler exits early) -// -// Registration is unconditional (not gated on subagent mode) because both -// parent sessions running skills directly and spawned subagent processes -// benefit from higher limits. The truncation guard makes it a no-op for -// outputs that fit within pi's defaults. -// -// Audit handler ordering: the audit tool_result handler (registered inside -// before_agent_start, after this one) records the ORIGINAL event content -// because it does not return a modified result — it only appends to the log. -// Pi runs handlers in registration order; each handler receives the event -// state as modified by prior handlers. Since the audit handler returns nothing, -// it never sees our replacement content, and since we don't touch the audit -// log, the two handlers are fully independent. - -import { readFileSync } from "node:fs"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import { truncateTail, formatSize, isBashToolResult } from "@mariozechner/pi-coding-agent"; - -// 4x the pi defaults (50KB / 2000 lines). Sized for the prompt-engineer skill, -// which concatenates ~100-150KB of technique reference files into a single bash -// call. 200KB gives comfortable headroom; 5000 lines is proportional (2.5x). -const KOAN_MAX_BYTES = 200 * 1024; -const KOAN_MAX_LINES = 5000; - -export function registerTruncationOverride(pi: ExtensionAPI): void { - pi.on("tool_result", (event) => { - if (!isBashToolResult(event)) return; - if (!event.details?.truncation?.truncated) return; - if (!event.details?.fullOutputPath) return; - - const fullOutputPath = event.details.fullOutputPath; - - // readFileSync is fine here — the runner awaits handlers so async would - // also work, but there's no benefit for a single temp file read. - // - // Timing note: the bash tool calls tempFileStream.end() then immediately - // resolves. On local filesystems the OS write completes before the - // microtask chain reaches this handler. If this ever causes incomplete - // reads on network filesystems, switch to async readFile with a small - // retry delay. - let fullContent: string; - try { - fullContent = readFileSync(fullOutputPath, "utf8"); - } catch { - // Temp file gone (race condition) — leave the result unchanged. - return undefined; - } - - const truncation = truncateTail(fullContent, { maxLines: KOAN_MAX_LINES, maxBytes: KOAN_MAX_BYTES }); - let outputText = truncation.content || "(no output)"; - - if (truncation.truncated) { - // Mirror the bash tool's notice format exactly. The LLM's tool description - // says output is truncated to specific limits and references the full output - // path — a divergent format would confuse the LLM about how to recover the rest. - const startLine = truncation.totalLines - truncation.outputLines + 1; - const endLine = truncation.totalLines; - - if (truncation.lastLinePartial) { - const lines = fullContent.split("\n"); - const lastLine = lines[lines.length - 1] ?? ""; - const lastLineSize = Buffer.byteLength(lastLine, "utf8"); - outputText += `\n\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${formatSize(lastLineSize)}). Full output: ${fullOutputPath}]`; - } else if (truncation.truncatedBy === "lines") { - outputText += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${fullOutputPath}]`; - } else { - outputText += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(KOAN_MAX_BYTES)} limit). Full output: ${fullOutputPath}]`; - } - } - - return { content: [{ type: "text" as const, text: outputText }] }; - }); -} diff --git a/src/planner/model-config.ts b/src/planner/model-config.ts deleted file mode 100644 index 2025bf3..0000000 --- a/src/planner/model-config.ts +++ /dev/null @@ -1,152 +0,0 @@ -// Koan config persistence for role-based model tier overrides. -// Storage location: ~/.koan/config.json under a `modelTiers` key. -// All 3 tiers (strong, standard, cheap) must be present when a config exists. -// Partial configs are treated as absent and logged. - -import { promises as fs } from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; - -import { ALL_MODEL_TIERS, isModelTier, type ModelTier } from "./types.js"; -import { createLogger } from "../utils/logger.js"; - -const log = createLogger("model-config"); - -export const CONFIG_PATH = path.join(os.homedir(), ".koan", "config.json"); - -export type ModelTierConfig = Record; - -export interface KoanConfig { - modelTiers: ModelTierConfig | null; - scoutConcurrency: number; -} - -interface KoanConfigFile { - modelTiers?: Record; - scoutConcurrency?: number; - [key: string]: unknown; -} - -// -- Private helpers -------------------------------------------------------- - -const DEFAULT_SCOUT_CONCURRENCY = 8; - -function parseModelTiers(parsed: KoanConfigFile): ModelTierConfig | null { - if (!parsed.modelTiers || typeof parsed.modelTiers !== "object") { - return null; - } - - const modelTiers = parsed.modelTiers; - const keys = Object.keys(modelTiers); - - if (keys.length !== ALL_MODEL_TIERS.length) { - log(`config.json modelTiers has ${keys.length} entries (expected ${ALL_MODEL_TIERS.length}); treating as absent.`); - return null; - } - - const result: Partial = {}; - for (const tier of ALL_MODEL_TIERS) { - if (!(tier in modelTiers)) { - log(`config.json modelTiers is missing key "${tier}"; treating as absent.`); - return null; - } - const value = modelTiers[tier]; - if (typeof value !== "string" || value.length === 0) { - log(`config.json modelTiers["${tier}"] is not a non-empty string; treating as absent.`); - return null; - } - result[tier] = value; - } - - for (const key of keys) { - if (!isModelTier(key)) { - log(`config.json modelTiers contains unknown key "${key}"; treating as absent.`); - return null; - } - } - - return result as ModelTierConfig; -} - -function parseScoutConcurrency(parsed: KoanConfigFile): number { - if (typeof parsed.scoutConcurrency === "number" && parsed.scoutConcurrency > 0) { - return parsed.scoutConcurrency; - } - return DEFAULT_SCOUT_CONCURRENCY; -} - -// -- Public loaders --------------------------------------------------------- - -export async function loadKoanConfig(): Promise { - const defaults: KoanConfig = { modelTiers: null, scoutConcurrency: DEFAULT_SCOUT_CONCURRENCY }; - - let raw: string; - try { - raw = await fs.readFile(CONFIG_PATH, "utf8"); - } catch { - return defaults; - } - - let parsed: KoanConfigFile; - try { - parsed = JSON.parse(raw) as KoanConfigFile; - } catch { - log("config.json is not valid JSON; treating config as absent."); - return defaults; - } - - return { - modelTiers: parseModelTiers(parsed), - scoutConcurrency: parseScoutConcurrency(parsed), - }; -} - -export async function loadModelTierConfig(): Promise { - return (await loadKoanConfig()).modelTiers; -} - -// -- Scout concurrency ------------------------------------------------------ - -export async function loadScoutConcurrency(): Promise { - return (await loadKoanConfig()).scoutConcurrency; -} - -export async function saveScoutConcurrency(concurrency: number): Promise { - const configDir = path.dirname(CONFIG_PATH); - await fs.mkdir(configDir, { recursive: true }); - - let existing: KoanConfigFile = {}; - try { - const raw = await fs.readFile(CONFIG_PATH, "utf8"); - existing = JSON.parse(raw) as KoanConfigFile; - } catch { - // Start fresh. - } - - existing.scoutConcurrency = concurrency; - - const tmpPath = `${CONFIG_PATH}.tmp`; - await fs.writeFile(tmpPath, `${JSON.stringify(existing, null, 2)}\n`, "utf8"); - await fs.rename(tmpPath, CONFIG_PATH); -} - -// -- Model tiers (save) ----------------------------------------------------- - -export async function saveModelTierConfig(config: ModelTierConfig): Promise { - const configDir = path.dirname(CONFIG_PATH); - await fs.mkdir(configDir, { recursive: true }); - - let existing: KoanConfigFile = {}; - try { - const raw = await fs.readFile(CONFIG_PATH, "utf8"); - existing = JSON.parse(raw) as KoanConfigFile; - } catch { - // Start fresh if file is missing or contains invalid JSON. - } - - existing.modelTiers = config as Record; - - const tmpPath = `${CONFIG_PATH}.tmp`; - await fs.writeFile(tmpPath, `${JSON.stringify(existing, null, 2)}\n`, "utf8"); - await fs.rename(tmpPath, CONFIG_PATH); -} diff --git a/src/planner/model-resolver.ts b/src/planner/model-resolver.ts deleted file mode 100644 index ab3d656..0000000 --- a/src/planner/model-resolver.ts +++ /dev/null @@ -1,14 +0,0 @@ -// Spawn-time model resolver for role-based model overrides. -// Maps SubagentRole → ModelTier → configured model string. -// Returns undefined when no config exists so the caller omits --model, -// preserving pi's current active model as the implicit fallback. - -import { ROLE_MODEL_TIER, type SubagentRole } from "./types.js"; -import { loadModelTierConfig } from "./model-config.js"; - -export async function resolveModelForRole(role: SubagentRole): Promise { - const config = await loadModelTierConfig(); - if (config === null) return undefined; - const tier = ROLE_MODEL_TIER[role]; - return config[tier]; -} diff --git a/src/planner/phases/base-phase.ts b/src/planner/phases/base-phase.ts deleted file mode 100644 index 96237b1..0000000 --- a/src/planner/phases/base-phase.ts +++ /dev/null @@ -1,225 +0,0 @@ -// BasePhase: shared lifecycle for all six koan subagent roles. -// Subclasses define only their step structure and system prompt. -// -// Step-first workflow invariant (see AGENTS.md): -// Every subagent launches with a minimal boot prompt that contains only -// "call koan_complete_step". This forces the LLM's very first action to be -// a tool call rather than text output — critical because pi -p processes exit -// the moment the LLM finishes a turn without a tool call, with no recovery. -// -// Step 0 is the silent boot state. The first koan_complete_step call -// transitions 0→1 and returns step 1 guidance (just-in-time delivery). -// Subsequent calls advance through steps until the phase completes. -// -// Non-linear step progression: -// Subclasses may override getNextStep() to implement loops or conditional -// transitions. getNextStep() MUST be pure — it only returns the next step -// number. Side effects that accompany a loop decision (state resets, counter -// increments, event emission) belong in onLoopBack(), which handleStepComplete -// calls whenever getNextStep() returns a step number less than the current one. -// -// The default implementation is strictly linear: each step advances to the -// next, and the final step (totalSteps) signals completion by returning null. -// IntakePhase overrides both getNextStep() and onLoopBack() to loop steps 2–4 -// until the confidence gate is satisfied. -// -// Lifecycle: -// constructor → registerHandlers() (hooks event listeners) -// begin() → activates phase at step 0, arms onCompleteStep, emits phase_start -// handleStepComplete(0) → returns step 1 guidance, emits step_transition(1) -// handleStepComplete(N) → calls getNextStep(N) to determine next step, -// calls onLoopBack() on backward transitions, -// returns guidance or null when done - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger, type Logger } from "../../utils/logger.js"; -import { checkPermission } from "../lib/permissions.js"; -import { formatStep, type StepGuidance } from "../lib/step.js"; -import { EventLog } from "../lib/audit.js"; -import type { RuntimeContext } from "../lib/runtime-context.js"; - -export abstract class BasePhase { - // Subclasses declare these as readonly properties. - protected abstract readonly role: string; - protected abstract readonly totalSteps: number; - - // Subclasses implement these to define step content. - protected abstract getSystemPrompt(): string; - protected abstract getStepName(step: number): string; - protected abstract getStepGuidance(step: number): StepGuidance; - - private step = 0; - private active = false; - - protected readonly log: Logger; - - constructor( - protected readonly pi: ExtensionAPI, - protected readonly ctx: RuntimeContext, - log?: Logger, - protected readonly eventLog?: EventLog, - ) { - this.log = log ?? createLogger("Phase"); - this.registerHandlers(); - } - - // -- Non-linear progression hook -- - // - // Returns the step number to transition to after `currentStep` completes, - // or null to signal phase completion. Subclasses override this to implement - // confidence loops, conditional branches, or any other non-linear flow. - // - // MUST be pure: do not mutate state or emit events here. Side effects that - // accompany a loop-back (counter increments, state resets, event emission) - // belong in onLoopBack(), which handleStepComplete calls after this method - // returns a backward step number. - // - // Default: linear progression. The step after totalSteps is null (done). - protected getNextStep(currentStep: number): number | null { - if (currentStep === this.totalSteps) return null; - return currentStep + 1; - } - - // -- Event handler registration -- - - private registerHandlers(): void { - // Inject the system prompt when this phase is active. The system prompt - // establishes role identity but deliberately omits task details — those - // arrive via step 1 guidance so the first message stays minimal. - this.pi.on("before_agent_start", () => { - if (!this.active) return undefined; - return { systemPrompt: this.getSystemPrompt() }; - }); - - // Default-deny permission fence: every tool call is checked against the - // role's allowed set. Prevents roles from using tools outside their scope - // even though all tools are registered unconditionally at init. - this.pi.on("tool_call", (event) => { - if (!this.active) return undefined; - const perm = checkPermission( - this.role, - event.toolName, - this.ctx.epicDir ?? undefined, - event.input as Record, - this.ctx.currentStep, - ); - if (!perm.allowed) { - void this.eventLog?.append({ - kind: "tool_result", - toolCallId: event.toolCallId, - tool: event.toolName, - error: true, - }); - return { block: true, reason: perm.reason }; - } - return undefined; - }); - - // NOTE: There is deliberately NO `context` event handler here. - // A previous design injected step 1 guidance into the first user message, - // but that front-loaded complex instructions before the LLM had established - // the koan_complete_step calling pattern — causing weaker models to produce - // text output and exit without entering the workflow at all. - // Step guidance is now delivered exclusively through koan_complete_step return values. - } - - // -- Public lifecycle -- - - async begin(): Promise { - this.active = true; - this.step = 0; // Boot state: waiting for the first koan_complete_step call. - - if (this.ctx.onCompleteStep !== null) { - throw new Error(`ctx.onCompleteStep is already occupied — cannot begin ${this.role} phase`); - } - this.ctx.onCompleteStep = (thoughts: string) => this.handleStepComplete(thoughts); - - this.log("Starting phase", { role: this.role, step: 0, totalSteps: this.totalSteps }); - await this.eventLog?.emitPhaseStart(this.totalSteps); - // step_transition is NOT emitted here — it fires when step 1 guidance is first - // returned, so the event log reflects when the LLM actually begins work. - } - - // -- Private step progression -- - - private async handleStepComplete(thoughts: string): Promise { - void thoughts; // captured in event log via tool_result; escape hatch for models that can't mix text + tool_call - - if (this.step === 0) { - // Boot transition: the LLM called koan_complete_step as instructed by the - // boot prompt. Reward it with step 1 guidance. This is the critical moment - // that establishes the call→receive→work→call pattern for the session. - this.step = 1; - this.onStepUpdated(1); - const prompt = formatStep(this.getStepGuidance(1)); - await this.eventLog?.emitStepTransition(1, this.getStepName(1), this.totalSteps); - this.log("Boot transition", { role: this.role, to: 1 }); - return prompt; - } - - // Validate pre-conditions before advancing (subclasses may override). - const preError = await this.validateStepCompletion(this.step); - if (preError !== null) { - // Return the error as the tool result — the LLM sees it and must fix - // the pre-condition before calling koan_complete_step again. - return preError; - } - - const nextStep = this.getNextStep(this.step); - - if (nextStep === null) { - // Phase complete — return null signals koan_complete_step to reply "Phase complete." - this.active = false; - this.ctx.onCompleteStep = null; - await this.eventLog?.emitPhaseEnd("completed"); - this.log("Phase complete", { role: this.role }); - return null; - } - - const prev = this.step; - this.step = nextStep; - - // If the step went backward (loop-back), give the subclass a chance to - // perform side effects before the new step's guidance is delivered: - // resetting state, incrementing counters, emitting events. This keeps - // getNextStep() pure — it only decides where to go, not what to do there. - if (nextStep < prev) { - await this.onLoopBack(prev, nextStep); - } - - this.onStepUpdated(nextStep); - const prompt = formatStep(this.getStepGuidance(this.step)); - await this.eventLog?.emitStepTransition(this.step, this.getStepName(this.step), this.totalSteps); - this.log("Step transition", { role: this.role, from: prev, to: this.step }); - return prompt; - } - - // -- Overridable hooks -- - - // Called whenever this.step is updated (including loop-backs). Syncs - // ctx.currentStep with the current step so the permission fence always - // reflects the active step. Subclasses may override for additional side effects. - protected onStepUpdated(step: number): void { - this.ctx.currentStep = step; - } - - // Called when a loop-back occurs (nextStep < previousStep), after this.step - // has been updated but before onStepUpdated() and getStepGuidance() run. - // Subclasses use this to perform side effects that accompany the loop decision - // — resetting state, incrementing counters, emitting events — separate from - // the pure getNextStep() query. The hook is async so event emission can be - // properly awaited, preserving event order in events.jsonl. - // eslint-disable-next-line @typescript-eslint/no-unused-vars - protected async onLoopBack(_from: number, _to: number): Promise { - // Default: no-op. - } - - // Called before advancing from the given step. Return null to allow - // advancement, or an error string to block it (returned as the tool - // result so the LLM sees the message and must fix the pre-condition). - // eslint-disable-next-line @typescript-eslint/no-unused-vars - protected async validateStepCompletion(_step: number): Promise { - return null; // Default: no pre-conditions. - } -} diff --git a/src/planner/phases/brief-writer/phase.ts b/src/planner/phases/brief-writer/phase.ts deleted file mode 100644 index 427eac9..0000000 --- a/src/planner/phases/brief-writer/phase.ts +++ /dev/null @@ -1,49 +0,0 @@ -// Brief-writer phase: reads intake context and produces brief.md. -// Three-step workflow with a review gate: -// -// Step 1 (Read) -- comprehend landscape.md; no file writes -// Step 2 (Draft & Review) -- write brief.md, invoke koan_review_artifact; -// revise on feedback; advance only after acceptance -// Step 3 (Finalize) -- phase complete -// -// Step 2 is the review gate. Extends ReviewablePhase which provides the -// review-tracking state and listeners. validateStepCompletion() is inherited -- -// koan_complete_step is rejected unless the last review response was ACCEPTED. - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger, type Logger } from "../../../utils/logger.js"; -import type { RuntimeContext } from "../../lib/runtime-context.js"; -import { EventLog } from "../../lib/audit.js"; -import { ReviewablePhase } from "../reviewable-phase.js"; -import { BRIEF_WRITER_STEP_NAMES, briefWriterSystemPrompt, briefWriterStepGuidance } from "./prompts.js"; -import type { StepGuidance } from "../../lib/step.js"; - -export class BriefWriterPhase extends ReviewablePhase { - protected readonly role = "brief-writer"; - protected readonly totalSteps = 3; - protected readonly reviewGatedStep = 2; - protected readonly reviewedArtifactName = "brief.md"; - - constructor( - pi: ExtensionAPI, - ctx: RuntimeContext, - log?: Logger, - eventLog?: EventLog, - ) { - super(pi, ctx, log ?? createLogger("BriefWriterPhase"), eventLog); - } - - protected getSystemPrompt(): string { - return briefWriterSystemPrompt(); - } - - protected getStepName(step: number): string { - return BRIEF_WRITER_STEP_NAMES[step] ?? `Step ${step}`; - } - - protected getStepGuidance(step: number): StepGuidance { - return briefWriterStepGuidance(step, this.ctx.epicDir!, this.ctx.phaseInstructions); - } - -} diff --git a/src/planner/phases/brief-writer/prompts.ts b/src/planner/phases/brief-writer/prompts.ts deleted file mode 100644 index 52bbcc1..0000000 --- a/src/planner/phases/brief-writer/prompts.ts +++ /dev/null @@ -1,101 +0,0 @@ -// Brief-writer phase prompts — system prompt and per-step guidance for -// the brief-writer subagent. -// -// The system prompt establishes a PM role: distill intake findings into a -// compact product-level brief (problem, goals, constraints). It defines -// the required output structure (<50 lines, four sections) and the -// review-then-iterate pattern. -// -// Step guidance follows the single-cognitive-goal principle: -// Step 1 (Read) — read landscape.md; build mental model; no file writes -// Step 2 (Draft & Review) — write brief.md + review gate (loops until Accept) -// Step 3 (Finalize) — phase complete -// -// The review gate logic (validateStepCompletion) lives in phase.ts, not here. -// Prompts express intent; the mechanical gate catches non-compliance. -// -// phaseInstructions (optional) — context from the workflow orchestrator's -// decision. Appended to step 1 guidance when present. - -import type { StepGuidance } from "../../lib/step.js"; -import { REVIEW_PROTOCOL } from "../review-protocol.js"; - -export const BRIEF_WRITER_STEP_NAMES: Record = { - 1: "Read", - 2: "Draft & Review", - 3: "Finalize", -}; - -export function briefWriterSystemPrompt(): string { - return `You are a brief writer for a coding task planner. You read intake context and produce a compact epic brief — a product-level document that captures the problem, who's affected, goals, and constraints. - -## Your role - -You distill intake findings into a clear problem statement. You do NOT design solutions, plan implementation, or decompose into stories. - -## Output - -One file: **brief.md** in the epic directory. - -## Structure - -- **Summary**: 3-8 sentences describing what this epic is about. -- **Context & Problem**: Who's affected, where in the product, the current pain. -- **Goals**: Numbered list of measurable objectives. -- **Constraints**: Hard constraints grounding decisions (from landscape.md). - -Keep the brief compact — under 50 lines. No UI flows, no technical design, no implementation details. - -${REVIEW_PROTOCOL}`; -} - -export function briefWriterStepGuidance(step: number, epicDir: string, phaseInstructions?: string): StepGuidance { - switch (step) { - case 1: { - const lines = [ - `Read \`${epicDir}/landscape.md\`. Build a thorough mental model of:`, - "", - "- Task Summary — what is being built or changed", - "- Prior Art — previous attempts, related systems, or prior conversations", - "- Codebase findings — architecture, patterns, integration points", - "- Decisions — every question asked and the user's answer", - "- Constraints — technical, timeline, compatibility requirements", - "", - "Do NOT write any files in this step. Comprehend before drafting.", - ]; - if (phaseInstructions) { - lines.push("", "## Additional Context from Workflow Orchestrator", "", phaseInstructions); - } - return { - title: BRIEF_WRITER_STEP_NAMES[1], - instructions: lines, - }; - } - - case 2: - return { - title: BRIEF_WRITER_STEP_NAMES[2], - instructions: [ - `Draft \`${epicDir}/brief.md\` with the required sections`, - "(Summary, Context & Problem, Goals, Constraints). Keep it under 50", - "lines. No UI flows, no technical design, no implementation details.", - "", - `After writing, invoke \`koan_review_artifact\` with the path to \`${epicDir}/brief.md\`.`, - ], - }; - - case 3: - return { - title: BRIEF_WRITER_STEP_NAMES[3], - instructions: [ - "Phase complete.", - ], - }; - - default: - return { - title: `Step ${step}`, - instructions: [`Execute step ${step}.`], - }; - } -} diff --git a/src/planner/phases/decomposer/phase.ts b/src/planner/phases/decomposer/phase.ts deleted file mode 100644 index 72b57f9..0000000 --- a/src/planner/phases/decomposer/phase.ts +++ /dev/null @@ -1,37 +0,0 @@ -// Decomposer phase: splits the epic into story sketches. -// Two steps: analysis → decomposition. - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger, type Logger } from "../../../utils/logger.js"; -import type { RuntimeContext } from "../../lib/runtime-context.js"; -import { EventLog } from "../../lib/audit.js"; -import { BasePhase } from "../base-phase.js"; -import { DECOMPOSER_STEP_NAMES, decomposerSystemPrompt, decomposerStepGuidance } from "./prompts.js"; -import type { StepGuidance } from "../../lib/step.js"; - -export class DecomposerPhase extends BasePhase { - protected readonly role = "decomposer"; - protected readonly totalSteps = 2; - - constructor( - pi: ExtensionAPI, - ctx: RuntimeContext, - log?: Logger, - eventLog?: EventLog, - ) { - super(pi, ctx, log ?? createLogger("DecomposerPhase"), eventLog); - } - - protected getSystemPrompt(): string { - return decomposerSystemPrompt(); - } - - protected getStepName(step: number): string { - return DECOMPOSER_STEP_NAMES[step] ?? `Step ${step}`; - } - - protected getStepGuidance(step: number): StepGuidance { - return decomposerStepGuidance(step, this.ctx.epicDir!); - } -} diff --git a/src/planner/phases/decomposer/prompts.ts b/src/planner/phases/decomposer/prompts.ts deleted file mode 100644 index 778890c..0000000 --- a/src/planner/phases/decomposer/prompts.ts +++ /dev/null @@ -1,148 +0,0 @@ -// Decomposer phase prompts — 2 steps: analysis → decomposition. -// Story IDs use S-NNN-slug format (e.g., S-001-auth-provider). - -import type { StepGuidance } from "../../lib/step.js"; - -export const DECOMPOSER_STEP_NAMES: Record = { - 1: "Analysis", - 2: "Decomposition", -}; - -export function decomposerSystemPrompt(): string { - return `You are a feature decomposer for a coding task planner. You read intake output and codebase scout reports, then split the requested work into independent story sketches — each story representing one pull request. - -## Your role - -You define WHAT the stories are and in WHAT ORDER they should be executed. You do NOT decide HOW each story is implemented (that belongs to the planner role). - -## Story definition - -A story must be: -- **Independent**: it can be reviewed and merged without depending on an unreleased sibling story. -- **Bounded**: it fits in one pull request — one coherent change to the codebase. -- **Testable**: the change can be verified in isolation. -- **Sequenced**: if stories have dependencies, they are ordered so earlier stories provide a stable base. - -## Story ID format - -Story IDs use the format: \`S-NNN-descriptive-slug\` -Examples: \`S-001-auth-provider\`, \`S-002-protected-routes\`, \`S-003-user-profile\` - -Use zero-padded three-digit numbers. The slug is a short kebab-case description of the story goal. -This format is sortable and human-readable. - -## Strict rules - -- MUST NOT include implementation details (specific functions, algorithms, data structures). -- MUST NOT make decisions that require user input. Those belong to intake. -- MUST NOT invent scope not present in landscape.md or brief.md. -- MUST produce one story sketch per deliverable unit of work. -- SHOULD keep stories small: prefer 4–8 stories over 1–2 large ones. -- SHOULD order stories so foundational work (types, interfaces, data models) comes first. -- SHOULD mark stories that are optional or conditional explicitly. -- MUST use the S-NNN-slug story ID format. - -## Output files - -You write the following files, all inside the epic directory: - -1. **epic.md** — overview of the full scope and the story list with sequencing rationale. -2. **stories/{story-id}/story.md** — one file per story with title, goal, scope, and dependencies. - -## Tools available - -- All read tools (read, bash, grep, glob, find, ls) — for reading intake output and scout reports. -- \`koan_request_scouts\` — to request additional codebase exploration if needed. -- \`write\` / \`edit\` — for writing output files inside the epic directory. -- \`koan_complete_step\` — to signal step completion.`; -} - -export function decomposerStepGuidance(step: number, epicDir: string): StepGuidance { - switch (step) { - case 1: - return { - title: DECOMPOSER_STEP_NAMES[1], - instructions: [ - "Read the intake output and all scout reports. Build a complete understanding of the scope", - "before producing any output.", - "", - "## Files to read", - "", - `- \`${epicDir}/landscape.md\` — task summary, prior art, codebase findings, project conventions, decisions, and constraints`, - `- \`${epicDir}/brief.md\` — epic brief: problem statement, goals, and constraints`, - "", - "If scout reports were referenced in your initial instructions above, read them now.", - "If no scout reports were mentioned, proceed without them.", - "You may also call `koan_request_scouts` if you need codebase context to inform story boundaries.", - "", - "## What to understand", - "", - "After reading, you should be able to answer:", - "- What is the top-level goal of this epic?", - "- What are the distinct deliverable units of work?", - "- Which units depend on each other, and what is the safe delivery order?", - "- Are there any parts of the work that are conditional or optional?", - "- What does the existing codebase already provide (from scout reports)?", - "", - "Do not write any output files during this step.", - ], - }; - - case 2: - return { - title: DECOMPOSER_STEP_NAMES[2], - instructions: [ - "Produce the full decomposition: epic.md and one story.md per story.", - "", - "## Story ID format", - "", - "Use S-NNN-slug format: S-001-auth-provider, S-002-protected-routes, etc.", - "The number is zero-padded, three digits, sequential. The slug is kebab-case.", - "", - "## epic.md", - "", - `Write \`${epicDir}/epic.md\` with these sections:`, - "", - "### Overview", - "One to three paragraphs describing the full scope of this epic.", - "", - "### Stories", - "A numbered list of all stories in delivery order.", - "Format: `{n}. [{story-id}] {story title} — {one-sentence goal}`", - "", - "### Sequencing Rationale", - "Explain why the stories are ordered as they are. Identify dependency chains.", - "Note any stories that can be worked in parallel.", - "", - "## stories/{story-id}/story.md", - "", - "Write one file per story. Use the story ID as the directory name.", - "Each story.md must contain these sections:", - "", - "### Goal", - "One sentence: what this story delivers and why.", - "", - "### Scope", - "What is included in this story. Be specific about boundaries.", - "List what is explicitly OUT OF SCOPE (to be handled in another story or not at all).", - "", - "### Dependencies", - "List any stories that must be merged before this story can begin.", - "If none: write `(none — this story can start immediately)`", - "", - "### Acceptance Criteria", - "Three to six testable conditions that define 'done' for this story.", - "Format: `- [ ] [condition]`", - "", - "After writing all files, call `koan_complete_step` with a summary:", - "number of stories produced and the delivery order.", - ], - }; - - default: - return { - title: `Step ${step}`, - instructions: [`Execute step ${step}.`], - }; - } -} diff --git a/src/planner/phases/dispatch.ts b/src/planner/phases/dispatch.ts deleted file mode 100644 index bdab056..0000000 --- a/src/planner/phases/dispatch.ts +++ /dev/null @@ -1,113 +0,0 @@ -// Phase dispatch: routes a SubagentTask to the appropriate phase class. -// -// Called from koan.ts after readTaskFile() resolves the task manifest. -// There is no flag-parsing here — all task parameters come from task.json. - -import * as path from "node:path"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger, type Logger } from "../../utils/logger.js"; -import type { RuntimeContext } from "../lib/runtime-context.js"; -import type { EventLog } from "../lib/audit.js"; -import type { SubagentTask } from "../lib/task.js"; -import { IntakePhase } from "./intake/phase.js"; -import { ScoutPhase } from "./scout/phase.js"; -import { DecomposerPhase } from "./decomposer/phase.js"; -import { BriefWriterPhase } from "./brief-writer/phase.js"; -import { OrchestratorPhase } from "./orchestrator/phase.js"; -import { PlannerPhase } from "./planner/phase.js"; -import { ExecutorPhase } from "./executor/phase.js"; -import { WorkflowOrchestratorPhase } from "./workflow-orchestrator/phase.js"; - -export async function dispatchPhase( - pi: ExtensionAPI, - task: SubagentTask, - ctx: RuntimeContext, - log?: Logger, - eventLog?: EventLog, -): Promise { - const logger = log ?? createLogger("Dispatch"); - - switch (task.role) { - case "intake": { - const phase = new IntakePhase(pi, ctx, logger, eventLog); - await phase.begin(); - break; - } - - case "scout": { - // outputFile is relative to subagentDir in the task manifest. - // ScoutPhase receives the resolved absolute path. - const phase = new ScoutPhase(pi, { - question: task.question, - outputFile: path.join(ctx.subagentDir!, task.outputFile), - investigatorRole: task.investigatorRole, - }, ctx, logger, eventLog); - await phase.begin(); - break; - } - - case "decomposer": { - const phase = new DecomposerPhase(pi, ctx, logger, eventLog); - await phase.begin(); - break; - } - - case "brief-writer": { - const phase = new BriefWriterPhase(pi, ctx, logger, eventLog); - await phase.begin(); - break; - } - - case "orchestrator": { - const phase = new OrchestratorPhase( - pi, - { epicDir: task.epicDir, stepSequence: task.stepSequence, storyId: task.storyId }, - ctx, logger, eventLog, - ); - await phase.begin(); - break; - } - - case "planner": { - const phase = new PlannerPhase( - pi, - { epicDir: task.epicDir, storyId: task.storyId }, - ctx, logger, eventLog, - ); - await phase.begin(); - break; - } - - case "executor": { - const phase = new ExecutorPhase( - pi, - { epicDir: task.epicDir, storyId: task.storyId, retryContext: task.retryContext }, - ctx, logger, eventLog, - ); - await phase.begin(); - break; - } - - case "workflow-orchestrator": { - const phase = new WorkflowOrchestratorPhase( - pi, - { - completedPhase: task.completedPhase, - availablePhases: task.availablePhases, - }, - ctx, logger, eventLog, - ); - await phase.begin(); - break; - } - - default: { - // TypeScript narrows task to `never` here — this branch is unreachable - // when all roles are covered above. - const exhaustive: never = task; - logger("Unrecognized role in task manifest", { role: (exhaustive as { role: string }).role }); - break; - } - } -} diff --git a/src/planner/phases/executor/phase.ts b/src/planner/phases/executor/phase.ts deleted file mode 100644 index 133ec8c..0000000 --- a/src/planner/phases/executor/phase.ts +++ /dev/null @@ -1,43 +0,0 @@ -// Executor phase: implements a story plan. -// Two steps: comprehension → implementation. - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger, type Logger } from "../../../utils/logger.js"; -import type { RuntimeContext } from "../../lib/runtime-context.js"; -import { EventLog } from "../../lib/audit.js"; -import { BasePhase } from "../base-phase.js"; -import { EXECUTOR_STEP_NAMES, executorSystemPrompt, executorStepGuidance } from "./prompts.js"; -import type { StepGuidance } from "../../lib/step.js"; - -export class ExecutorPhase extends BasePhase { - protected readonly role = "executor"; - protected readonly totalSteps = 2; - - private readonly storyId: string; - private readonly retryContext: string | undefined; - - constructor( - pi: ExtensionAPI, - config: { epicDir: string; storyId: string; retryContext?: string }, - ctx: RuntimeContext, - log?: Logger, - eventLog?: EventLog, - ) { - super(pi, ctx, log ?? createLogger("ExecutorPhase"), eventLog); - this.storyId = config.storyId; - this.retryContext = config.retryContext; - } - - protected getSystemPrompt(): string { - return executorSystemPrompt(); - } - - protected getStepName(step: number): string { - return EXECUTOR_STEP_NAMES[step] ?? `Step ${step}`; - } - - protected getStepGuidance(step: number): StepGuidance { - return executorStepGuidance(step, this.storyId, this.ctx.epicDir!, this.retryContext); - } -} diff --git a/src/planner/phases/executor/prompts.ts b/src/planner/phases/executor/prompts.ts deleted file mode 100644 index 101883a..0000000 --- a/src/planner/phases/executor/prompts.ts +++ /dev/null @@ -1,154 +0,0 @@ -import type { StepGuidance } from "../../lib/step.js"; - -export const EXECUTOR_STEP_NAMES: Record = { - 1: "Comprehension", - 2: "Implementation", -}; - -export function executorSystemPrompt(): string { - return `You are a coding agent. You implement changes to a codebase by following a detailed plan written by a planner. You are the only agent in the koan workflow that writes source code. - -## Your role - -You receive a plan (plan/plan.md) and supporting context (plan/context.md), and you implement each step in order. You do not design. You do not make architectural decisions. You execute the plan faithfully. - -## What you receive - -- **plan/plan.md**: A numbered list of implementation steps. Each step specifies the file, location, action, and exact change to make. -- **plan/context.md**: Curated code snippets for the files you will modify — function signatures, type definitions, and import blocks. -- **retryContext** (when present): A failure summary from a previous execution attempt. Read it carefully — it describes what went wrong and what you should do differently. - -## How to work - -Work through the plan steps in order. Before touching any file: - -1. Read the file to understand its current state. Plan/context.md is a snapshot; the file may have changed due to earlier steps in this execution. -2. Identify exactly where the change goes. -3. Make the change precisely — no more, no less. -4. Verify the change looks correct before moving on. - -## When plan and reality diverge - -If what you find in the codebase does not match what the plan describes — the function doesn't exist, the signature is different, the file structure changed — you MUST stop immediately and call \`koan_ask_question\`. Do not improvise a solution. Do not make assumptions. - -Describe: -- Which plan step you are on -- What the plan expected to find -- What you actually found -- What you need to know to proceed - -Improvised solutions that seem reasonable in isolation frequently break other parts of the system that are not visible in your context window. - -## Strict rules — violations cause retry cycles - -- MUST implement steps in the order specified by the plan. -- MUST NOT skip any step, even if it seems redundant. -- MUST NOT add features, functions, or logic that the plan does not specify. -- MUST NOT refactor code that the plan does not mention — even if you notice an improvement opportunity. -- MUST NOT modify test expectations to make tests pass. If a test fails after your implementation, report it via koan_ask_question. -- MUST read each file before modifying it. Context.md is a reference, not a guarantee of current state. -- MUST call koan_ask_question immediately when plan assumptions don't hold. Do not continue to the next step. - -## On retries - -If retryContext is present, this is your second (or later) attempt at this story. The failure summary tells you what went wrong. Read it before you read the plan, and keep the failure context in mind as you implement. Do not repeat the mistake from the previous attempt.`; -} - -export function executorStepGuidance(step: number, storyId: string, epicDir: string, retryContext?: string): StepGuidance { - switch (step) { - case 1: - return { - title: EXECUTOR_STEP_NAMES[1], - instructions: [ - `Read and fully understand the implementation plan for story \`${storyId}\` before writing any code.`, - "", - "## What to read", - "", - `1. Read \`${epicDir}/stories/${storyId}/plan/plan.md\` — read every step from start to finish. Do not skim.`, - `2. Read \`${epicDir}/stories/${storyId}/plan/context.md\` — understand the function signatures, types, and imports for every file the plan touches.`, - ...(retryContext - ? [ - "", - "## Retry context — read this first", - "", - "This is a retry attempt. A previous execution of this story failed. The failure summary is:", - "", - retryContext, - "", - "Keep this failure context in mind as you read the plan. Identify which step caused the failure and what you will do differently.", - ] - : []), - "", - "## What to understand", - "", - "After reading, you must be able to answer these questions without referring back to the files:", - "", - "- How many steps are in the plan?", - "- Which files will you modify?", - "- What is the dependency order between steps?", - "- Are there any steps that touch the same file (potential ordering conflicts)?", - "- What types or interfaces are central to the changes?", - "", - "Do NOT start writing code in this step. Comprehension only.", - "", - "Call koan_complete_step with your comprehension summary:", - "- Number of steps", - "- List of files to modify", - "- Any ambiguities or concerns you spotted in the plan (do not block on these — note them)", - ...(retryContext ? ["- How you plan to avoid the previous failure"] : []), - ], - }; - - case 2: - return { - title: EXECUTOR_STEP_NAMES[2], - instructions: [ - `Implement the plan for story \`${storyId}\` step by step.`, - "", - "## Execution protocol", - "", - "Work through plan/plan.md in order. For each step:", - "", - "1. **Read the target file** — do not rely solely on plan/context.md; read the actual current state of the file.", - "2. **Locate the change site** — find the exact function, class, or section described in the plan step.", - "3. **Verify your assumption** — confirm that what you find matches what the plan describes. If it does not match, call koan_ask_question immediately.", - "4. **Make the change** — implement exactly what the plan step specifies. No more, no less.", - "5. **Move to the next step** — do not review or revisit previous steps.", - "", - "## Plan-reality mismatch protocol", - "", - "If at any point the codebase does not match the plan's description:", - "", - "- STOP immediately. Do not attempt to adapt the plan.", - "- Call `koan_ask_question` with:", - " - The plan step number and description", - " - What the plan expected", - " - What you actually found", - " - What specific information you need to proceed", - "", - "## Common pitfalls", - "", - "- Do not add logging, error handling, or validation beyond what the plan specifies.", - "- Do not fix code style issues you notice in passing.", - "- Do not update imports for files not mentioned in the plan.", - "- Do not change test files unless a plan step explicitly says to.", - "- Do not run the tests yourself — the orchestrator will verify.", - "", - "## When all steps are complete", - "", - "Review your changes at a high level: are all plan steps implemented? Did you accidentally modify something you shouldn't have? Correct any accidental changes.", - "", - "Then call koan_complete_step with a summary of what you implemented:", - "- Each plan step: completed or skipped (with reason if skipped)", - "- Files modified", - "- Any concerns or observations for the orchestrator", - ], - }; - - default: - return { - title: `Step ${step}`, - instructions: [`Execute step ${step}.`], - }; - } -} diff --git a/src/planner/phases/intake/phase.ts b/src/planner/phases/intake/phase.ts deleted file mode 100644 index 25ea5f8..0000000 --- a/src/planner/phases/intake/phase.ts +++ /dev/null @@ -1,74 +0,0 @@ -// Intake phase: reads conversation, scouts codebase, asks clarifying questions, -// and writes landscape.md — the sole input for all downstream phases. -// -// Five-step linear workflow: -// -// Step 1 (Extract) — read-only comprehension of conversation.jsonl -// Step 2 (Scout) — dispatch codebase scouts, analyze results -// Step 3 (Ask) — enumerate knowns/unknowns, ask questions, follow up -// Step 4 (Reflect) — verify completeness, scout or ask if gaps remain -// Step 5 (Write) — write landscape.md, present for user review -// -// Steps progress linearly — no loops. Within-step follow-ups (reading files, -// asking follow-up questions) are handled by the LLM naturally rather than -// by driver-level iteration. -// -// Step 1 is read-only: the permission fence blocks koan_request_scouts, -// koan_ask_question, write, and edit during that step, enforced via -// ctx.currentStep which BasePhase.onStepUpdated() keeps in sync. -// -// Step 5 enforces that koan_review_artifact is called before koan_complete_step -// via validateStepCompletion(). This ensures landscape.md is presented for user -// review before the phase advances. - -import * as path from "node:path"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger, type Logger } from "../../../utils/logger.js"; -import type { RuntimeContext } from "../../lib/runtime-context.js"; -import { EventLog } from "../../lib/audit.js"; -import { ReviewablePhase } from "../reviewable-phase.js"; -import { INTAKE_STEP_NAMES, intakeSystemPrompt, intakeStepGuidance } from "./prompts.js"; -import type { StepGuidance } from "../../lib/step.js"; - -export class IntakePhase extends ReviewablePhase { - protected readonly role = "intake"; - protected readonly totalSteps = 5; - protected readonly reviewGatedStep = 5; - protected readonly reviewedArtifactName = "landscape.md"; - - private readonly conversationPath: string; - - constructor( - pi: ExtensionAPI, - ctx: RuntimeContext, - log?: Logger, - eventLog?: EventLog, - ) { - super(pi, ctx, log ?? createLogger("IntakePhase"), eventLog); - this.conversationPath = path.join(ctx.epicDir!, "conversation.jsonl"); - } - - protected getSystemPrompt(): string { - return intakeSystemPrompt(); - } - - protected getStepName(step: number): string { - return INTAKE_STEP_NAMES[step] ?? `Step ${step}`; - } - - protected getStepGuidance(step: number): StepGuidance { - return intakeStepGuidance(step, this.conversationPath, this.ctx.epicDir!, this.ctx.phaseInstructions); - } - - // Reset the review gate when entering step 5 so only step-5 reviews - // count toward the validateStepCompletion gate. Without this, a spurious - // koan_review_artifact call during earlier steps would satisfy the gate - // before the LLM has written landscape.md. - protected override onStepUpdated(step: number): void { - super.onStepUpdated(step); - if (step === 5) { - this.resetReviewGate(); - } - } -} diff --git a/src/planner/phases/intake/prompts.ts b/src/planner/phases/intake/prompts.ts deleted file mode 100644 index ed2493f..0000000 --- a/src/planner/phases/intake/prompts.ts +++ /dev/null @@ -1,499 +0,0 @@ -// Intake phase prompts — 5-step linear workflow. -// -// Step 1 (Extract) — read-only comprehension of conversation.jsonl -// Step 2 (Scout) — dispatch codebase scouts, analyze results -// Step 3 (Ask) — enumerate knowns/unknowns, ask questions, investigate follow-ups -// Step 4 (Reflect) — verify completeness, scout or ask if gaps remain -// Step 5 (Write) — write landscape.md, present for user review -// -// Each step has exactly one cognitive goal. Separate koan_complete_step calls -// enforce genuinely isolated reasoning. Within-step follow-ups (reading files, -// asking follow-up questions) happen naturally — the LLM handles iteration -// internally rather than the driver looping steps. - -import type { StepGuidance } from "../../lib/step.js"; -import { REVIEW_PROTOCOL } from "../review-protocol.js"; - -export const INTAKE_STEP_NAMES: Record = { - 1: "Extract", - 2: "Scout", - 3: "Ask", - 4: "Reflect", - 5: "Write", -}; - -export function intakeSystemPrompt(): string { - return `You are an intake analyst for a coding task planner. You read a conversation history, explore the codebase, and ask the user targeted questions until you have complete context for planning. - -Your output — a single landscape.md file — is the sole foundation for all downstream work. Every story boundary, every implementation plan, and every line of code written downstream depends on the quality and completeness of this file. Gaps here compound into wrong plans and wrong code. - -An assumption you make without verifying will become a fact the decomposer treats as decided. A question you don't ask is an answer you're making up. When the executor writes the wrong code because landscape.md contained an unchecked assumption, that failure traces back to this phase. - -## Your role - -You gather, verify, and organize background information. You do NOT plan, design, or implement. You do NOT define what work should be done — you describe what exists and what was said. - -## Strict rules - -- MUST NOT infer decisions not explicitly stated in the conversation. -- MUST NOT add architectural opinions or suggest approaches. -- MUST NOT produce implementation recommendations. -- MUST NOT define deliverables, work units, or scope boundaries — that belongs to the decomposer. -- MUST capture only what was explicitly said. If unclear, mark it as unresolved. -- SHOULD prefer multiple-choice questions when the answer space is bounded. -- SHOULD ground questions in codebase findings. - -## Thinking style - -Your reasoning should be dense and efficient. Follow these rules: - -- Start with your first insight, not a preamble. Your first word should be - a finding, a fact, or a decision — not "Now", "Excellent", "Let me", or - any other commentary about what you're about to do. -- End with your last insight, not a summary. When there is nothing new to - say, stop. Do not recap what you just worked out. -- State things once. Never restate something from earlier in the same - reasoning block or from a prior step. -- Use compressed notation: → for flow, ✓ exists, ✗ missing, ⚡ conflict, - ∴ therefore. Abbreviate freely (fn, dep, impl, cfg, db, auth, mw, req, resp). - Bullets and sentence fragments over full prose. - -These rules apply to your internal reasoning only. Tool arguments (scout -prompts, questions) and written artifacts (landscape.md) should remain -clear and complete. - -Examples of target density (WRONG → RIGHT): - -Processing scout reports: - WRONG: "The kernel-structure scout found that CUDA kernels live in src/kernels/ - and use shared memory for the parallel reduction step. The build-system scout - found CMake with FindCUDAToolkit. The host-code scout reports that device memory - is allocated with cudaMalloc and copied back with cudaMemcpy. This answers my - questions about project structure. Nothing unexpected so far." - RIGHT: "kernel-structure scout: src/kernels/, shared mem for reductions - build-system scout: CMake + FindCUDAToolkit - host-code scout: cudaMalloc → cudaMemcpy pattern - All three answered ✓; no unexpected findings" - -Resolving conflicting information: - WRONG: "There's a conflict between what the user said and what the code - shows. The user said the data pipeline runs hourly, but the cron expression - in scheduler.py is set to daily at midnight. I need to figure out which is - correct. Since the user is describing the desired behavior and the code - shows the current behavior, this is likely a change they want to make. I - should note this as an existing gap and ask the user to confirm." - RIGHT: "⚡ conversation: pipeline runs hourly ↔ scout: scheduler.py cron = daily@midnight - conversation = desired vs code = current ∴ likely a requested change → ASK user to confirm" - -Classifying unknowns: - WRONG: "Looking at what I've gathered so far, I think I have a good - understanding of the database schema and the CLI argument parsing. But I - still don't know how the plugin system loads extensions at runtime — if we - get that wrong it could affect story boundaries. The user also mentioned a - config file format I haven't found, but that's just an implementation detail. - I should dispatch a scout for the plugin system and ask the user about the - config format." - RIGHT: "✓ db schema, CLI arg parsing - ✗ plugin loading — wrong assumption changes story boundaries → SCOUT - ✗ cfg file format — impl detail, no scope impact → SAFE" - -## Workflow - -You work in stages: read the conversation, scout the codebase, ask the user questions, verify your understanding, and write landscape.md. Each step builds on the previous one. - -## Output - -One file: **landscape.md** in the epic directory. - -## Tools - -- Read tools (read, bash, grep, glob, find, ls) — reading the conversation and codebase. -- \`koan_request_scouts\` — request parallel codebase exploration. -- \`koan_ask_question\` — ask the user clarifying questions. -- \`koan_review_artifact\` — present landscape.md for user review (final step only). -- \`write\` / \`edit\` — for writing landscape.md (final step only). -- \`koan_complete_step\` — signal step completion. - -${REVIEW_PROTOCOL}`; -} - -export function intakeStepGuidance(step: number, conversationPath?: string, epicDir?: string, phaseInstructions?: string): StepGuidance { - switch (step) { - // ------------------------------------------------------------------------- - // Step 1: Extract — read the conversation, build a mental model. - // - // This step is intentionally read-only. The permission fence blocks - // koan_request_scouts, koan_ask_question, write, and edit during step 1 - // so that comprehension cannot be short-circuited by premature action. - // ------------------------------------------------------------------------- - case 1: - return { - title: INTAKE_STEP_NAMES[1], - instructions: [ - "Read the conversation file. Build a thorough mental model of what is being requested.", - "", - conversationPath - ? `Conversation file: ${conversationPath}` - : "Conversation file: locate `conversation.jsonl` in the epic directory.", - "", - "The file is JSONL. Each line is a JSON object.", - "Read entries with type 'message' and role 'user' or 'assistant'.", - "Ignore internal entries (header, compaction, etc.).", - "", - "## What to internalize", - "", - "As you read, track these categories:", - "- **Topic**: What is being built or changed?", - "- **File references**: Every file, directory, or module mentioned.", - "- **Decisions already made**: Only those explicitly stated and agreed upon.", - "- **Constraints**: Technical, timeline, compatibility requirements.", - "- **Gaps**: Questions raised but unanswered. Things unclear or unstated that would affect story boundaries.", - "- **Conventions mentioned**: Any references to coding standards, test approaches, doc standards, or patterns to follow.", - "", - "## Rules for this step", - "", - "- Do NOT call koan_request_scouts, koan_ask_question, write, or edit.", - "- This step is read-only. Understand the conversation before acting on it.", - "- Be faithful to what was said. Do not invent context or infer unstated decisions.", - "- If the conversation references specific files or systems, note them — you will scout those next.", - ...(phaseInstructions ? ["", "## Additional Context from Workflow Orchestrator", "", phaseInstructions] : []), - ], - }; - - // ------------------------------------------------------------------------- - // Step 2: Scout — dispatch codebase investigators, analyze results. - // - // After scouts return their findings, analyze the results to confirm they - // answer the questions you had and note anything unexpected. - // ------------------------------------------------------------------------- - case 2: - return { - title: INTAKE_STEP_NAMES[2], - instructions: [ - "Based on your reading of the conversation, identify areas of the codebase that need exploration.", - "", - "## Step 1: Understand — what questions need answers?", - "", - "Before doing anything else, articulate what you need to find out.", - "Walk through the conversation findings from Extract and list:", - "", - "- What areas of the codebase does this task touch?", - "- What assumptions did the user make that need verification?", - "- What integration points, dependencies, or constraints are unclear?", - "- What was NOT mentioned that could matter?", - "", - "This is your question list. Everything downstream serves it.", - "", - "## Step 2: Ground — open the files the conversation named", - "", - "Now read the actual code for files the conversation explicitly referenced.", - "You noted them during Extract — open them now.", - "", - "- `ls` the project root if you haven't already.", - "- Open each file or directory the conversation explicitly mentioned.", - " Skim structure, exports, key patterns — first 50–100 lines is enough.", - "- If the conversation mentions a module by name without a path, one", - " `find` or `ls` to locate it, then open the entry point.", - "", - "Stop here. This is orientation, not investigation — just enough to write", - "scout prompts that reference actual function names, actual patterns, and", - "actual file paths instead of conversation labels.", - "", - "## Step 3: Plan — enumerate coverage areas", - "", - "Using your question list and what you observed in the code, enumerate the", - "areas that need investigation. Write out each area as a bullet.", - "Consider two categories:", - "", - "**Surface areas** — what the conversation explicitly references:", - "- Each file, module, or system mentioned by name.", - "- Each integration point with existing code (APIs, databases, auth, config).", - "- Project conventions (linter configs, test framework, doc standards, architecture patterns).", - "- Each assumption the user makes about the codebase that needs verification.", - "", - "**Deep areas** — what the conversation did NOT mention but could matter:", - "- Hidden consumers or callers of the code being changed — who else depends on this?", - "- Related subsystems that might be affected by the proposed work.", - "- Prior art: has something similar been attempted before? Abandoned branches, TODO comments, commented-out code?", - "- Edge cases and invariants: what constraints does the existing code enforce that the conversation didn't mention?", - "- Test coverage: what test infrastructure exists for the affected areas?", - "", - "Your area list determines your scout count. A simple single-file change may need", - "only a few areas. A cross-cutting system change will need many. Let the task", - "dictate coverage — do not pick a number and fill it.", - "", - "## Step 4: Execute — map one scout to each area", - "", - "For each coverage area, formulate one scout. Use `koan_request_scouts` to dispatch", - "them all in a single call.", - "", - "Each scout needs:", - "- id: short kebab-case identifier (e.g., 'auth-setup', 'hidden-callers')", - "- role: investigator focus (e.g., 'authentication auditor', 'dependency tracer')", - "- prompt: a specific question to answer (e.g., 'Find all callers of updateUserProfile in src/ and identify every module that depends on its return type')", - "", - "Scouts are cheap — they run on fast models in parallel. If you identified an area,", - "it deserves a scout. Do not merge areas to reduce count, and do not skip an area", - "because it \"probably\" won't matter.", - "", - "## Step 5: Analyze results", - "", - "When scouts return, analyze each report:", - "- Does the finding answer the question you asked?", - "- Does it reveal anything unexpected about the codebase?", - "- Does it raise new questions that need user input?", - "- Did any deep scout uncover something the conversation didn't anticipate?", - "", - "If results reveal new areas worth exploring, dispatch a follow-up round of scouts.", - "", - "Do NOT ask the user questions in this step — that happens in the Ask step.", - ], - }; - - // ------------------------------------------------------------------------- - // Step 3: Ask — enumerate knowns/unknowns, ask questions, follow up. - // - // Thread-of-Thought: walk through each area before formulating questions. - // Anticipatory Reflection: classify unknowns by downstream impact. - // Self-Ask: after answers arrive, evaluate whether follow-up is needed. - // ------------------------------------------------------------------------- - case 3: - return { - title: INTAKE_STEP_NAMES[3], - instructions: [ - "Before asking questions, explicitly enumerate what you know and what you don't.", - "This grounds your questions in reality and prevents asking things already answered.", - "", - "## Phase A: Recite what you know", - "", - "Walk through each area relevant to the task and state what you have learned.", - "Use this structure for each area:", - "", - " **[Area name]** (e.g., 'Authentication', 'Database schema', 'API endpoints')", - " - Known: [what the conversation and/or scouts established]", - " - Unknown: [what remains unclear or unverified]", - " - Source: [conversation / scout findings]", - "", - "Cover every area relevant to the task. Be thorough — gaps you miss here become gaps in the final output.", - "", - "Include project conventions as an area: where are coding style, testing strategy,", - "architecture patterns, and documentation standards defined? If not explicitly", - "documented, note whether they are emergent from code patterns or absent entirely.", - "", - "## Phase A.5: Downstream impact assessment", - "", - "For each 'Unknown' item from Phase A, briefly assess:", - "- If you assume wrong about this, what happens to downstream planning?", - "- Could a wrong assumption split a story that should be one, or merge two that should be separate?", - "- Would the executor hit a surprise that requires re-planning?", - "", - "This is the only phase where the user can be consulted. After intake, all", - "downstream phases work from landscape.md alone. Anything you get wrong here", - "will silently propagate through decomposition, planning, and execution.", - "", - "Mark each unknown as:", - "- **ASK**: user input needed — this affects scope, boundaries, or sequencing.", - "- **SCOUT**: a follow-up scout can resolve this factually — note for the Reflect step.", - "- **SAFE**: genuinely an implementation detail with no scope impact.", - "", - "## Phase B: Formulate and ask questions", - "", - "For each 'Unknown' marked ASK, ask yourself: if I get this wrong, does it affect", - "the decomposer's ability to define correct story boundaries? If yes or maybe — ask.", - "", - "The user is your collaborator, not an interruption. Questions are how you verify", - "your understanding against reality. The decomposer cannot ask questions later —", - "this is the only chance to get clarification.", - "", - "Default: ask. You may skip a question ONLY if ALL of these are true:", - "- It is purely an implementation detail (HOW to code something, not WHAT to build).", - "- Getting it wrong would not change any story boundary.", - "- It cannot be misinterpreted — there is exactly one reasonable interpretation.", - "", - "Call `koan_ask_question` once with all your questions in the `questions` array.", - "The user sees them one at a time. Aim for 3–5 questions.", - "Prefer multiple-choice when the answer space is bounded.", - "Include the optional context field when background is needed for an informed decision.", - "Ground questions in specific findings: 'Scout found X — should this story follow the same pattern?'", - "", - "## Phase C: Process answers and follow up", - "", - "When answers arrive, think through each one carefully:", - "", - "a) **Does an answer point to files you should read?** If the user references", - " specific files, code, or documentation — read them immediately using read tools.", - " Confirm the answer against what you find in the codebase.", - "", - "b) **Does an answer raise new questions?** If understanding one answer reveals", - " a new ambiguity or decision point — ask the follow-up immediately via another", - " `koan_ask_question` call. Think through those answers the same way.", - "", - "c) **Are you satisfied?** If all answers are clear and no follow-ups are needed,", - " proceed to the next step.", - "", - "When in doubt, check with the user. It is always better to confirm an assumption", - "than to let a wrong assumption propagate through planning and execution.", - ], - }; - - // ------------------------------------------------------------------------- - // Step 4: Reflect — verify completeness, act on gaps. - // - // Chain-of-Verification: generate verification questions and answer them - // with evidence. If gaps are found, address them directly — scout or ask - // as needed. This is the last chance to gather information before writing. - // ------------------------------------------------------------------------- - case 4: - return { - title: INTAKE_STEP_NAMES[4], - instructions: [ - "Step back and verify the completeness of your understanding. This is the last", - "chance to gather information before writing landscape.md.", - "", - "## Verification questions", - "", - "Generate 3–5 questions that test whether your understanding is complete.", - "Frame them from the decomposer's perspective — the decomposer must split this work into stories.", - "", - "Example verification questions:", - "- 'Could I define the boundary between story 1 and story 2 right now?'", - "- 'If the user's codebase uses pattern X (per scout), does our understanding account for that?'", - "- 'Are there any user decisions that could split one story into two or merge two into one?'", - "", - "## Answer each question", - "", - "Answer each verification question using ONLY evidence you have:", - "- Direct quotes or facts from the conversation", - "- Specific findings from scouts", - "- Explicit answers from the user", - "", - "If you cannot answer a verification question with evidence, that is a gap.", - "", - "## Act on gaps", - "", - "If you identified gaps:", - "", - "- **Need codebase information?** Dispatch scouts via `koan_request_scouts`.", - " Analyze the results when they return.", - "- **Need user input?** Ask via `koan_ask_question`. Think through the answers.", - "- **Need to read specific files?** Read them directly with read tools.", - "", - "If no gaps remain, proceed to the next step.", - ], - }; - - // ------------------------------------------------------------------------- - // Step 5: Write — write landscape.md, present for user review. - // - // Consolidate everything gathered into a single structured file, then - // present it for user review via koan_review_artifact. - // ------------------------------------------------------------------------- - case 5: - return { - title: INTAKE_STEP_NAMES[5], - instructions: [ - epicDir - ? `Write \`${epicDir}/landscape.md\`.` - : "Write `landscape.md` to the epic directory.", - "This file is the sole input for all downstream phases. Write it carefully.", - "", - "## Formatting rules (apply to all sections)", - "", - "- **File references**: Always use markdown link format: `[display name](relative/path)`.", - " After each reference, briefly state what the file contains or why it matters.", - " Example: `[base-phase.ts](src/planner/phases/base-phase.ts) — abstract lifecycle for all phase subagents`.", - " Never use bare paths.", - "- **Section headings**: Use exactly the heading names below. Downstream agents locate content by heading.", - "- **Content rule**: Describe what IS, not what SHOULD be done. No recommendations, no deliverables, no implementation suggestions.", - "", - "## Required sections", - "", - "### Task Summary", - "What is being built or changed, in the user's own framing.", - "State the scope as the user described it — what areas of the codebase are affected and why.", - "Do NOT decompose this into deliverables or work units. A downstream agent will do that.", - "", - "### Prior Art", - "Previous attempts, referenced plans, related systems, or prior conversations mentioned.", - "For each reference: what it contains, what is relevant to the current task, and what to expect when reading it.", - "Example:", - " - [phases.md](plans/phases.md) — phased implementation plan; Phase 5 defines the deliverables this epic covers", - " - Previous PR #42 attempted this but was reverted due to migration issues", - "If none: (none referenced)", - "", - "### Codebase Findings", - "Key findings from scouts, organized by area of the codebase (not by scout task).", - "", - "For each area, include:", - "- **Entry points**: files, functions, or modules that are the primary sites of interest.", - " Use annotated file references: `[filename](path) — what this file does`.", - "- **Current behavior**: how the relevant code works today.", - "- **Patterns**: recurring patterns, conventions, or idioms observed in this area.", - "- **Integration points**: how this area connects to other parts of the system.", - "", - "If no scouts were needed: (no codebase exploration was needed)", - "", - "### Project Conventions", - "Where to find coding standards and patterns for this project — pointers to sources,", - "not the conventions themselves. Downstream agents will read the referenced sources directly.", - "", - "Cover at minimum these areas. Add any other convention categories relevant to this project:", - "", - "#### Coding Style", - "Where style is defined: linter config, formatter config, or emergent from codebase.", - "Example: \"ESLint config at [.eslintrc.json](.eslintrc.json)\" or \"no linter; follows Go stdlib style\"", - "", - "#### Testing Strategy", - "Where testing approach is defined: doc, config, patterns.", - "Example: \"[testing-philosophy.md](doc/01-principles/testing-philosophy.md) — integration-first with testcontainers\"", - "", - "#### Architecture Patterns", - "Where architecture conventions live: docs, or emergent from code.", - "Example: \"constructor-based DI, no framework; see [BasePhase](src/planner/phases/base-phase.ts)\"", - "", - "#### Documentation", - "Where documentation standards are defined.", - "Example: \"CLAUDE.md per package\", \"JSDoc on all exports\"", - "", - "If no explicit conventions exist for an area, note whether patterns are emergent from code or absent entirely.", - "", - "### Decisions", - "Every question asked and the user's answer.", - "Format: **Q:** [question] / **A:** [answer]", - "If no questions were needed: (no questions were needed — context was sufficient)", - "", - "### Constraints", - "All constraints discovered: from conversation, codebase, user answers.", - "If none: (none identified)", - "", - "### Open Items", - "Anything unresolved.", - "If none: (none)", - "", - "## Pre-write verification", - "", - "Before writing, verify landscape.md is complete — a downstream agent must be able", - "to understand the full background from this file alone:", - "- What is being built or changed, and why?", - "- What existing code is affected and how is it structured?", - "- Where do project conventions live?", - "- What decisions have been made that constrain downstream work?", - "- Is every file reference annotated with what it contains?", - "", - "If you cannot answer any of these from what you've gathered, note it in Open Items.", - "", - "## After writing", - "", - epicDir - ? `Call \`koan_review_artifact\` with the path \`${epicDir}/landscape.md\` and description "Landscape document — background information for downstream planning".` - : "Call `koan_review_artifact` with the path to landscape.md and description \"Landscape document — background information for downstream planning\".", - ], - }; - - default: - return { - title: `Step ${step}`, - instructions: [`Execute step ${step}.`], - }; - } -} diff --git a/src/planner/phases/orchestrator/phase.ts b/src/planner/phases/orchestrator/phase.ts deleted file mode 100644 index 4f64b87..0000000 --- a/src/planner/phases/orchestrator/phase.ts +++ /dev/null @@ -1,59 +0,0 @@ -// Orchestrator phase: judgment calls at execution boundaries. -// Two step sequences: pre-execution (2 steps) and post-execution (4 steps). -// Orchestrator uses koan_ask_question for all user communication. See docs/state.md -- "No escalated status". - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger, type Logger } from "../../../utils/logger.js"; -import type { RuntimeContext } from "../../lib/runtime-context.js"; -import { EventLog } from "../../lib/audit.js"; -import { BasePhase } from "../base-phase.js"; -import { - ORCHESTRATOR_PRE_STEP_NAMES, - ORCHESTRATOR_POST_STEP_NAMES, - orchestratorSystemPrompt, - orchestratorPreStepGuidance, - orchestratorPostStepGuidance, -} from "./prompts.js"; -import type { StepGuidance } from "../../lib/step.js"; - -const PRE_TOTAL_STEPS = 2; -const POST_TOTAL_STEPS = 4; - -export class OrchestratorPhase extends BasePhase { - protected readonly role = "orchestrator"; - protected readonly totalSteps: number; - - private readonly stepSequence: "pre-execution" | "post-execution"; - private readonly storyId: string | undefined; - - constructor( - pi: ExtensionAPI, - config: { epicDir: string; stepSequence: "pre-execution" | "post-execution"; storyId?: string }, - ctx: RuntimeContext, - log?: Logger, - eventLog?: EventLog, - ) { - super(pi, ctx, log ?? createLogger("OrchestratorPhase"), eventLog); - this.stepSequence = config.stepSequence; - this.storyId = config.storyId; - this.totalSteps = config.stepSequence === "pre-execution" ? PRE_TOTAL_STEPS : POST_TOTAL_STEPS; - } - - protected getSystemPrompt(): string { - return orchestratorSystemPrompt(this.stepSequence); - } - - protected getStepName(step: number): string { - const names = this.stepSequence === "pre-execution" - ? ORCHESTRATOR_PRE_STEP_NAMES - : ORCHESTRATOR_POST_STEP_NAMES; - return names[step] ?? `Step ${step}`; - } - - protected getStepGuidance(step: number): StepGuidance { - return this.stepSequence === "pre-execution" - ? orchestratorPreStepGuidance(step, this.ctx.epicDir!) - : orchestratorPostStepGuidance(step, this.ctx.epicDir!, this.storyId); - } -} diff --git a/src/planner/phases/orchestrator/prompts.ts b/src/planner/phases/orchestrator/prompts.ts deleted file mode 100644 index 4e106e0..0000000 --- a/src/planner/phases/orchestrator/prompts.ts +++ /dev/null @@ -1,297 +0,0 @@ -// Orchestrator phase prompts. -// Pre-execution (2 steps): dependency analysis -> story selection. -// Post-execution (4 steps): verify -> verdict -> propagate -> select next. -// -// User communication uses koan_ask_question for clarification, after which the -// orchestrator decides the next action (retry, skip, etc.) via state-transition tools. - -import type { StepGuidance } from "../../lib/step.js"; - -export const ORCHESTRATOR_PRE_STEP_NAMES: Record = { - 1: "Dependency Analysis", - 2: "Story Selection", -}; - -export const ORCHESTRATOR_POST_STEP_NAMES: Record = { - 1: "Verify", - 2: "Verdict", - 3: "Propagate", - 4: "Select Next", -}; - -export function orchestratorSystemPrompt(stepSequence: string): string { - const sequenceFocus = - stepSequence === "pre-execution" - ? "You are beginning an epic run. Analyze story dependencies and select the first story for execution." - : "Execution has just completed for a story. Verify the result, issue a verdict, propagate learnings, and select the next story."; - - return `You are a workflow orchestrator for a multi-story coding epic. You make judgment calls at execution boundaries — before and after each coding story runs. ${sequenceFocus} - -## Important: status.md may be stale - -Do not rely on \`status.md\` for current story state. The driver sets intermediate statuses (\`planning\`, \`executing\`, \`verifying\`) in its internal JSON state only — \`status.md\` is only updated by orchestrator tool calls (\`koan_select_story\`, \`koan_complete_story\`, etc.). Your authoritative inputs are \`verify.md\`, \`plan.md\`, git diff, and \`epic.md\` — not \`status.md\`. - -## Your role - -You are a decision-maker. You read content, apply judgment, and direct the workflow. You do NOT write code. You do NOT modify source code files. You do NOT produce implementation plans. - -## What you own - -- **Verification**: Running the checks defined in a story's verify.md to determine whether the implementation is correct. -- **Verdict**: Declaring the outcome of a story's execution — success or retry with feedback. -- **Story selection**: Choosing which story executes next based on the dependency graph and current epic state. -- **Learning propagation**: When you discover something during verification, update remaining story.md files and the Decisions section of landscape.md. Mark every autonomous update with \`[autonomous]\`. -- **User communication**: When you encounter genuine ambiguity or need human judgment, call \`koan_ask_question\`. After getting the answer, decide what to do (retry with new context, skip, etc.) and call the appropriate tool. - -## When to ask the user - -Call \`koan_ask_question\` when: -- Verification reveals an ambiguity in requirements that cannot be resolved by reading the code. -- A story fails in a way that suggests the spec was wrong, not the implementation. -- You need human judgment on whether to retry, skip, or take a different approach. - -After getting the answer, record it and proceed with an appropriate tool call: -- \`koan_retry_story\` — if the user provided direction that lets you retry with a better plan -- \`koan_skip_story\` — if the user decided the story is no longer needed -- \`koan_complete_story\` — if the user confirmed the outcome is acceptable - -## Tools available - -- All read tools (read, bash, grep, glob, find, ls) — for reading epic artifacts and running verification checks. -- \`koan_select_story\` — to declare which story should execute next. -- \`koan_complete_story\` — to mark a story as successfully verified and completed. -- \`koan_retry_story\` — to send a story back to the executor with a detailed failure summary. -- \`koan_skip_story\` — to skip a story that is superseded or no longer needed. -- \`koan_ask_question\` — to ask the human a targeted question when judgment is genuinely ambiguous. -- \`koan_complete_step\` — to signal step completion with your findings. -- \`write\` / \`edit\` — for updating artifact files inside the epic directory only. -- \`bash\` — for running verification commands. - -## The [autonomous] marker - -When you make a decision that modifies artifacts without explicit human instruction, prefix the added content with \`[autonomous]\` in the artifact file. This lets the human audit all autonomous decisions. - -## Strict rules - -- MUST NOT write or modify source code files. -- MUST NOT call more than one verdict tool per verdict step. -- MUST run ALL verification checks in verify.md before issuing a verdict. -- MUST include a concrete, actionable failure summary when calling koan_retry_story. -- When uncertain about a verdict, prefer koan_retry_story with a detailed failure_summary. Ask the user only when the failure reveals a genuine requirements ambiguity.`; -} - -export function orchestratorPreStepGuidance(step: number, epicDir: string): StepGuidance { - switch (step) { - case 1: - return { - title: ORCHESTRATOR_PRE_STEP_NAMES[1], - instructions: [ - "Read the epic artifacts to understand the full scope of work and story dependencies.", - "", - "## What to read", - "", - `1. Read \`${epicDir}/epic.md\` — understand the overall goal and scope.`, - `2. Read \`${epicDir}/brief.md\` — understand the product-level goals and constraints.`, - `3. Read the Decisions section of \`${epicDir}/landscape.md\` — understand decisions that shape execution.`, - `4. Read each \`story.md\` file in \`${epicDir}/stories/\` — understand what each story builds and depends on.`, - "", - "## What to analyze", - "", - "After reading, build a dependency model:", - "- Which stories must complete before others can begin? (explicit dependencies)", - "- Which stories share files or interfaces? (implicit coupling)", - "- Which stories are independent and could run in any order?", - "- Are there any circular dependencies or unresolvable conflicts?", - "", - "Note the risk profile of each story: stories that touch shared infrastructure are higher risk.", - "", - "## Checklist before advancing", - "", - "Before calling koan_complete_step, confirm you have determined:", - "- The execution order you recommend and why", - "- Any risks or concerns you identified", - "- The ID of the story you believe should run first", - ], - }; - - case 2: - return { - title: ORCHESTRATOR_PRE_STEP_NAMES[2], - instructions: [ - "Select the first story for execution based on your dependency analysis from step 1.", - "", - "## Selection criteria", - "", - "Choose the story that:", - "1. Has all its dependencies satisfied (no blockers)", - "2. Is highest priority given the epic's goal", - "3. Creates the most unblocking value for subsequent stories if completed", - "", - "Prefer foundational stories (shared types, interfaces, infrastructure) over leaf stories.", - "", - "## What to do", - "", - "Call `koan_select_story` with the ID of the story that should execute first.", - "Then call `koan_complete_step` with your reasoning.", - ], - invokeAfter: [ - "WHEN DONE: Call koan_select_story with your chosen story ID, then call koan_complete_step with your reasoning.", - "Do NOT call koan_complete_step until koan_select_story has been called.", - ].join("\n"), - }; - - default: - return { title: `Step ${step}`, instructions: [`Execute step ${step}.`] }; - } -} - -export function orchestratorPostStepGuidance(step: number, epicDir: string, storyId?: string): StepGuidance { - const storyRef = storyId ? `story \`${storyId}\`` : "the current story"; - const verifyPath = storyId ? `${epicDir}/stories/${storyId}/plan/verify.md` : `${epicDir}/stories//plan/verify.md`; - - switch (step) { - case 1: - return { - title: ORCHESTRATOR_POST_STEP_NAMES[1], - instructions: [ - `Run all verification checks defined for ${storyRef}.`, - "", - "## What to read", - "", - `1. Read \`${verifyPath}\` — every check you must run.`, - "2. Read the story's `story.md` to understand the acceptance criteria.", - "", - "## Running checks", - "", - "Execute every check listed in verify.md using bash. Do not skip checks.", - "", - "- Run compilation/type checks first (cheapest).", - "- Run linting and static analysis next.", - "- Run unit and integration tests last (most expensive).", - "", - "For each check, record:", - "- The exact command you ran", - "- The exit code", - "- Relevant output (errors, failures, warnings)", - "", - "## Output", - "", - "Call koan_complete_step with your verification findings:", - "- A summary of every check run and its result (pass/fail)", - "- The full error output for any failures", - "- Your preliminary assessment: does the implementation appear correct?", - ], - }; - - case 2: - return { - title: ORCHESTRATOR_POST_STEP_NAMES[2], - instructions: [ - "Issue a verdict based on your verification findings from step 1.", - "", - "## Verdict options", - "", - "**koan_complete_story** — All verification checks passed. The implementation is correct.", - "", - "**koan_retry_story** — Verification failed, but the failure is fixable by the executor.", - "MUST provide a detailed `failure_summary` that includes:", - " - Which checks failed and why", - " - The exact error messages", - " - What the executor should do differently", - "", - "**koan_ask_question then decide** — The failure reveals a genuine requirements ambiguity.", - "Ask the user a focused question. Based on the answer:", - " - Call koan_retry_story with the user's direction as context", - " - Call koan_skip_story if the user decides the story is no longer needed", - " - Call koan_complete_story if the user confirmed the outcome is acceptable", - "", - "## Decision rule", - "", - "If any check failed AND the failure is a concrete code bug → koan_retry_story.", - "If any check failed AND the failure reveals a requirements contradiction → koan_ask_question then decide.", - "If all checks passed → koan_complete_story.", - "", - "Call EXACTLY ONE verdict tool (after any koan_ask_question).", - ], - invokeAfter: [ - "WHEN DONE: Call EXACTLY ONE of: koan_complete_story, koan_retry_story, or (koan_ask_question then verdict tool).", - "Then call koan_complete_step to advance to the next step.", - ].join("\n"), - }; - - case 3: - return { - title: ORCHESTRATOR_POST_STEP_NAMES[3], - instructions: [ - `Propagate lessons from this story's execution to remaining stories and the Decisions section of \`${epicDir}/landscape.md\`.`, - "", - "## What to propagate", - "", - "Review what you learned from verification (step 1) and the verdict (step 2):", - "- Did the executor encounter something that affects remaining stories?", - "- Did verification reveal an incorrect assumption in a remaining story's plan?", - "- Did the implementation introduce a pattern remaining stories should follow?", - "", - "Only propagate information directly relevant to remaining stories.", - "", - "## How to propagate", - "", - "For each remaining story that is affected:", - "1. Read its `story.md`.", - "2. Add a `## [autonomous] Propagated Context` section with the relevant information.", - "", - `Update the Decisions section of \`${epicDir}/landscape.md\` if a new decision was made or an existing one was invalidated.`, - "Add `[autonomous]` prefix to any autonomous additions.", - "", - "If no propagation is needed, skip file updates and proceed.", - "", - "## Skipping stories", - "", - "If this story's completion makes another story unnecessary, call `koan_skip_story` with a clear reason.", - "", - "Then call koan_complete_step with a summary of what was propagated.", - ], - }; - - case 4: - return { - title: ORCHESTRATOR_POST_STEP_NAMES[4], - instructions: [ - "Select the next story to execute, or complete the epic if all stories are done.", - "", - "## What to check", - "", - "Read each story directory to understand which stories remain:", - "- Stories with `pending` or `retry` status are candidates.", - "- Done, skipped, or currently-selected stories are not candidates.", - "", - "## Selection criteria", - "", - "Among remaining stories:", - "1. Filter to those whose dependencies are all completed.", - "2. Among unblocked stories, prefer the one with highest value.", - "3. A story in 'retry' state is highest priority — it was already planned and executed.", - "", - "## What to do", - "", - "If one or more stories remain and are unblocked:", - "- Call `koan_select_story` with the ID of the next story.", - "- Then call `koan_complete_step` with your reasoning.", - "", - "If no stories remain (all completed or skipped):", - "- Call `koan_complete_step` with a summary stating the epic is complete.", - " Do NOT call koan_select_story.", - "", - "If stories remain but all are blocked (dependencies not satisfied):", - "- Call `koan_ask_question` to ask the user how to proceed (reorder, skip, or abort).", - " Based on the answer, call the appropriate tool.", - ], - invokeAfter: [ - "WHEN DONE: If stories remain, call koan_select_story then koan_complete_step. If none remain, call koan_complete_step only.", - ].join("\n"), - }; - - default: - return { title: `Step ${step}`, instructions: [`Execute step ${step}.`] }; - } -} diff --git a/src/planner/phases/planner/phase.ts b/src/planner/phases/planner/phase.ts deleted file mode 100644 index 4629bdb..0000000 --- a/src/planner/phases/planner/phase.ts +++ /dev/null @@ -1,41 +0,0 @@ -// Planner phase: produces the detail plan for a single story. -// Three steps: analysis → plan → verification design. - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger, type Logger } from "../../../utils/logger.js"; -import type { RuntimeContext } from "../../lib/runtime-context.js"; -import { EventLog } from "../../lib/audit.js"; -import { BasePhase } from "../base-phase.js"; -import { PLANNER_STEP_NAMES, plannerSystemPrompt, plannerStepGuidance } from "./prompts.js"; -import type { StepGuidance } from "../../lib/step.js"; - -export class PlannerPhase extends BasePhase { - protected readonly role = "planner"; - protected readonly totalSteps = 3; - - private readonly storyId: string; - - constructor( - pi: ExtensionAPI, - config: { epicDir: string; storyId: string }, - ctx: RuntimeContext, - log?: Logger, - eventLog?: EventLog, - ) { - super(pi, ctx, log ?? createLogger("PlannerPhase"), eventLog); - this.storyId = config.storyId; - } - - protected getSystemPrompt(): string { - return plannerSystemPrompt(); - } - - protected getStepName(step: number): string { - return PLANNER_STEP_NAMES[step] ?? `Step ${step}`; - } - - protected getStepGuidance(step: number): StepGuidance { - return plannerStepGuidance(step, this.storyId, this.ctx.epicDir!); - } -} diff --git a/src/planner/phases/planner/prompts.ts b/src/planner/phases/planner/prompts.ts deleted file mode 100644 index 017218f..0000000 --- a/src/planner/phases/planner/prompts.ts +++ /dev/null @@ -1,212 +0,0 @@ -import type { StepGuidance } from "../../lib/step.js"; - -export const PLANNER_STEP_NAMES: Record = { - 1: "Analysis", - 2: "Plan", - 3: "Verification Design", -}; - -export function plannerSystemPrompt(): string { - return `You are an implementation planner for a single coding story. You produce a detailed, step-by-step plan that a coding agent can execute without making judgment calls. You bridge the gap between high-level story intent and concrete implementation actions. - -## Your role - -You read stories, codebase artifacts, and scout reports, then produce three output files: a step-by-step plan, a curated code context file, and a verification checklist. You do NOT write code. You do NOT make design decisions beyond what the story and landscape.md specify. - -## What you produce - -### plan/plan.md — Step-by-step implementation plan - -Each step must specify: -- **Which file** to modify or create (full path from repo root) -- **Which function, class, or section** within that file -- **What change** to make (add, modify, delete, rename, restructure) -- **Why** this change is needed (link to story requirement or constraint) -- **Dependencies** between steps (e.g., "Step 3 requires step 1 to complete first") - -Steps must be ordered to minimize conflicts. Implement foundational changes before dependent ones. Leaf dependencies before callers. - -Be precise enough that a coding agent can execute each step without asking questions. Vague steps ("update the handler") produce retry cycles. Precise steps ("add parameter \`timeout: number\` to the \`fetchUser\` function signature in \`src/api/users.ts\`, update all call sites in \`src/routes/auth.ts\` and \`src/routes/profile.ts\`") do not. - -### plan/context.md — Curated code context - -Include only the code the executor needs to understand what it is modifying: -- Function signatures for every function the plan touches -- Relevant type definitions and interfaces -- Import statements that must be preserved or updated -- Key constants or configuration values that affect the changes -- Do NOT include boilerplate, unrelated functions, or documentation blocks - -### plan/verify.md — Verification checklist - -List every check the orchestrator should run after execution, ordered cheap to expensive: -1. Compilation checks (tsc --noEmit, build commands) -2. Linting and type checks -3. Unit tests for affected modules -4. Integration or end-to-end tests - -Each check entry must include: -- A description of what it verifies -- The exact command to run (with arguments) -- What a passing result looks like - -## Strict rules — violations cause execution failures - -- MUST NOT write source code. Plan steps describe actions; they do not contain implementation. -- MUST NOT plan beyond the current story's scope. If a step would touch something not in the story, flag it as out-of-scope. -- MUST NOT make architectural decisions. If a decision is needed that is outside the planner's scope, note it in plan.md as: \`BLOCKER: [description]. The orchestrator will ask the user via koan_ask_question during verification.\` -- MUST include enough detail that the executor can implement the plan in one pass without guessing. -- MUST scope plan/context.md to only what the executor needs — context files that include too much code obscure the relevant parts.`; -} - -export function plannerStepGuidance(step: number, storyId: string, epicDir: string): StepGuidance { - switch (step) { - case 1: - return { - title: PLANNER_STEP_NAMES[1], - instructions: [ - `Analyze all available context for story \`${storyId}\` before producing any plan output.`, - "", - "## Request fresh codebase scouts", - "", - "Before analyzing the story, use `koan_request_scouts` to explore the current state of files this story will touch. Codebase state may have changed since earlier scouts. Request scouts for the specific files and patterns mentioned in the story sketch.", - "", - "## What to read", - "", - `1. Read \`${epicDir}/stories/${storyId}/story.md\` — understand exactly what this story must accomplish, its acceptance criteria, and any noted constraints or dependencies.`, - `2. Read \`${epicDir}/landscape.md\` — understand the task background: prior art, codebase findings, project conventions, constraints, and decisions. If a decision is marked as unresolved, check whether it blocks this story.`, - `3. Read \`${epicDir}/brief.md\` — understand the product-level goals and constraints. The plan must serve these goals.`, - "4. Read the scout reports returned by `koan_request_scouts` for current codebase context.", - "", - "## What to analyze", - "", - "After reading, build a complete picture of the work:", - "", - "- **Scope**: What exactly must change? What must NOT change?", - "- **Entry points**: Which files, functions, or modules are the primary change sites?", - "- **Ripple effects**: What else must be updated because of the primary changes? (callers, types, tests, exports)", - "- **Constraints**: Are there patterns from the codebase the executor must follow? (naming conventions, error handling style, module structure)", - "- **Risks**: Which steps are most likely to cause conflicts or unexpected issues?", - "", - "## Checklist before advancing", - "", - "Before calling koan_complete_step, confirm you have identified:", - "- The list of files that will be modified or created", - "- The sequence you plan for the steps (high-level)", - "- Any risks or unresolved questions", - `- Whether any open decisions in \`${epicDir}/landscape.md\` block this story`, - ], - }; - - case 2: - return { - title: PLANNER_STEP_NAMES[2], - instructions: [ - `Write the implementation plan and code context for story \`${storyId}\`.`, - "", - "## Write plan/plan.md", - "", - `Create \`${epicDir}/stories/${storyId}/plan/plan.md\` with a numbered list of implementation steps.`, - "", - "Each step must follow this format:", - "```", - "## Step N: [Short title]", - "", - "**File**: path/to/file.ts", - "**Location**: function name, class name, or section description", - "**Action**: [add | modify | delete | create | rename]", - "", - "[Precise description of what to change and why. Include exact parameter names,", - "type signatures, return values, or behavioral changes. Be specific enough that", - "the executor does not need to make any judgment calls.]", - "", - "**Depends on**: Step N (if applicable)", - "```", - "", - "Order steps so each step's dependencies are satisfied before it runs.", - "Prefer: type changes → interface updates → implementation changes → call-site updates → test updates.", - "", - "## Write plan/context.md", - "", - `Create \`${epicDir}/stories/${storyId}/plan/context.md\` with curated code snippets the executor needs.`, - "", - "Structure by file, then by section within the file:", - "```", - "## path/to/file.ts", - "", - "### FunctionName (lines N–M)", - "\\`\\`\\`typescript", - "// paste the relevant function signature and key lines only", - "\\`\\`\\`", - "```", - "", - "Include:", - "- Every function signature the plan references", - "- Type definitions that the changes touch", - "- Import blocks for files being modified", - "- Constants or configuration values referenced in plan steps", - "", - "Exclude:", - "- Unrelated functions and classes", - "- Long function bodies (include signature + key lines only)", - "- Documentation blocks and comments unless they carry critical constraint information", - "", - "Call koan_complete_step with a summary: number of plan steps, files affected, and any risks you flagged in the plan.", - ], - }; - - case 3: - return { - title: PLANNER_STEP_NAMES[3], - instructions: [ - `Write the verification checklist for story \`${storyId}\`.`, - "", - `Create \`${epicDir}/stories/${storyId}/plan/verify.md\`. This file will be used by the orchestrator to verify the executor's output.`, - "", - "## Structure", - "", - "Order checks from cheapest to most expensive. The orchestrator must be able to run every check via bash.", - "", - "```", - "## Verification Checklist for story: ${storyId}", - "", - "### Check 1: [Description]", - "**Command**: `exact command here`", - "**Passes when**: [description of expected output or exit code]", - "", - "### Check 2: ...", - "```", - "", - "## Required check categories (in order)", - "", - "**1. Compilation** (always required)", - "Include the TypeScript compilation check or equivalent build command.", - "Example: `npx tsc --noEmit`", - "", - "**2. Linting** (if project uses a linter)", - "Include the lint command for affected files.", - "", - "**3. Unit tests** (for modified modules)", - "Include test commands scoped to the files or modules changed by this story.", - "Prefer targeted test runs (e.g., `--testPathPattern`) over full suite runs.", - "", - "**4. Integration tests** (if applicable)", - "Include only tests that directly exercise the story's acceptance criteria.", - "", - "## Precision requirements", - "", - "- Each command must be runnable from the repo root with no modifications.", - "- Pass/fail criteria must be unambiguous (exit code 0 = pass, or specific output pattern).", - "- Do not include checks that verify things outside this story's scope.", - "", - "Call koan_complete_step with a summary: number of checks, categories covered, and any checks you could not define due to missing information.", - ], - }; - - default: - return { - title: `Step ${step}`, - instructions: [`Execute step ${step}.`], - }; - } -} diff --git a/src/planner/phases/review-protocol.ts b/src/planner/phases/review-protocol.ts deleted file mode 100644 index a7cbe0a..0000000 --- a/src/planner/phases/review-protocol.ts +++ /dev/null @@ -1,33 +0,0 @@ -// Shared review protocol prompt fragment. -// -// Included in the system prompt of every role that has koan_review_artifact -// permission (currently: intake, brief-writer). Establishes the review loop -// contract, ripple-effect awareness, and mechanical enforcement — once, in -// one place. -// -// The tool response provides the SIGNAL (ACCEPTED vs REVISION REQUESTED). -// This prompt provides the BEHAVIOR (what to do with each signal). - -export const REVIEW_PROTOCOL = `## Review protocol - -When you present an artifact for review via \`koan_review_artifact\`, the user -can either accept it or provide feedback. - -**On acceptance**: the tool response will say ACCEPTED. You may then call -\`koan_complete_step\` to advance. - -**On feedback**: the tool response will say REVISION REQUESTED and include the -user's feedback. You MUST: - -1. Treat the feedback as authoritative. It may introduce new decisions, - constraints, or context that were not available during earlier phases. -2. Consider the ripple effect. If the feedback changes your understanding of - the task, other artifacts in the epic directory may need updating too — you - have write access and should fix any factual inconsistency the feedback - creates. For example, feedback on brief.md that introduces a new constraint - should also appear in landscape.md's Constraints or Decisions section. -3. Revise the artifact to fully address every point in the feedback. -4. Call \`koan_review_artifact\` again to present the revision. - -This loop continues until the user accepts. You cannot complete the current -step without acceptance — the system enforces this mechanically.`; diff --git a/src/planner/phases/reviewable-phase.ts b/src/planner/phases/reviewable-phase.ts deleted file mode 100644 index 0ac2fa9..0000000 --- a/src/planner/phases/reviewable-phase.ts +++ /dev/null @@ -1,75 +0,0 @@ -// ReviewablePhase: abstract layer between BasePhase and phases that gate a step -// on user review of an artifact via koan_review_artifact. -// -// Owns the review-tracking state (lastReviewAccepted) and the two event -// listeners that maintain it. Subclasses declare which step is gated and -// which artifact name appears in error messages. - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import type { Logger } from "../../utils/logger.js"; -import type { RuntimeContext } from "../lib/runtime-context.js"; -import { EventLog } from "../lib/audit.js"; -import { BasePhase } from "./base-phase.js"; - -export abstract class ReviewablePhase extends BasePhase { - // Subclasses declare which step requires a passing review and the artifact - // name used in validation error messages. - protected abstract readonly reviewGatedStep: number; - protected abstract readonly reviewedArtifactName: string; - - // Tracks whether the last koan_review_artifact call was accepted by the user. - // null = never reviewed; true = last review accepted; false = last review had feedback. - private lastReviewAccepted: boolean | null = null; - - constructor( - pi: ExtensionAPI, - ctx: RuntimeContext, - log?: Logger, - eventLog?: EventLog, - ) { - super(pi, ctx, log, eventLog); - - // When koan_review_artifact is called, mark as pending (not yet accepted). - pi.on("tool_call", (event) => { - if (event.toolName === "koan_review_artifact") { - this.lastReviewAccepted = false; - } - return undefined; - }); - - // When koan_review_artifact returns, check the response for ACCEPTED. - pi.on("tool_result", (event) => { - if (event.toolName === "koan_review_artifact" && !event.isError) { - const text = event.content?.[0]; - if (text && "text" in text && typeof text.text === "string") { - this.lastReviewAccepted = text.text.startsWith("ACCEPTED"); - } - } - }); - } - - // Hook for subclasses that need to reset the review gate on step entry - // (e.g. IntakePhase resets when entering step 5 so only step-5 reviews count). - protected resetReviewGate(): void { - this.lastReviewAccepted = null; - } - - protected async validateStepCompletion(step: number): Promise { - if (step !== this.reviewGatedStep) { - return super.validateStepCompletion(step); - } - - if (this.lastReviewAccepted === null) { - return `You must call koan_review_artifact on ${this.reviewedArtifactName} before completing this step. ` + - `Write ${this.reviewedArtifactName}, then invoke koan_review_artifact to present it for review.`; - } - if (!this.lastReviewAccepted) { - return `The user provided feedback on your artifact — you must address it. ` + - `Revise ${this.reviewedArtifactName} based on the feedback, then call koan_review_artifact again. ` + - `You cannot complete this step until the user accepts.`; - } - - return super.validateStepCompletion(step); - } -} diff --git a/src/planner/phases/scout/phase.ts b/src/planner/phases/scout/phase.ts deleted file mode 100644 index bcbb951..0000000 --- a/src/planner/phases/scout/phase.ts +++ /dev/null @@ -1,47 +0,0 @@ -// Scout phase: answers one narrow codebase question and writes findings. -// Three-step workflow (investigate → verify → report), cheap model, no user interaction. -// Task context (question, outputFile, investigatorRole) is received via task.json -// (directory-as-contract) and delivered to the LLM through step guidance. - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger, type Logger } from "../../../utils/logger.js"; -import type { RuntimeContext } from "../../lib/runtime-context.js"; -import { EventLog } from "../../lib/audit.js"; -import { BasePhase } from "../base-phase.js"; -import { SCOUT_STEP_NAMES, scoutSystemPrompt, scoutStepGuidance } from "./prompts.js"; -import type { StepGuidance } from "../../lib/step.js"; - -export class ScoutPhase extends BasePhase { - protected readonly role = "scout"; - protected readonly totalSteps = 3; - - private readonly question: string; - private readonly outputFile: string; - private readonly investigatorRole: string; - - constructor( - pi: ExtensionAPI, - config: { question: string; outputFile: string; investigatorRole: string }, - ctx: RuntimeContext, - log?: Logger, - eventLog?: EventLog, - ) { - super(pi, ctx, log ?? createLogger("ScoutPhase"), eventLog); - this.question = config.question; - this.outputFile = config.outputFile; - this.investigatorRole = config.investigatorRole; - } - - protected getSystemPrompt(): string { - return scoutSystemPrompt(); - } - - protected getStepName(step: number): string { - return SCOUT_STEP_NAMES[step] ?? `Step ${step}`; - } - - protected getStepGuidance(step: number): StepGuidance { - return scoutStepGuidance(step, this.question, this.outputFile, this.investigatorRole); - } -} diff --git a/src/planner/phases/scout/prompts.ts b/src/planner/phases/scout/prompts.ts deleted file mode 100644 index 0fb8768..0000000 --- a/src/planner/phases/scout/prompts.ts +++ /dev/null @@ -1,151 +0,0 @@ -// Scout phase prompts — 3-step investigation workflow: -// Step 1: Investigate (find entry points AND read/trace code — combined for speed) -// Step 2: Verify (spot-check critical claims with targeted tool calls) -// Step 3: Report (write findings.md with verified facts) -// -// The system prompt establishes the investigator identity but contains no task -// details — a scout doesn't know its question until koan_complete_step returns -// step 1 guidance. This is intentional: including the question in the system -// prompt or spawn prompt would front-load instructions before the tool-call -// pattern is established, causing weaker models to answer inline and exit. -// -// Speed design: scouts are optimized for breadth and speed. They use cheap -// models for narrow codebase investigation. The system prompt explicitly -// instructs batching tool calls (reading multiple files per turn, running -// multiple grep/find commands simultaneously). The original 4-step design -// (Orient → Investigate → Verify → Report) was reduced to 3 steps by merging -// Orient into Investigate — separating "find files" from "read files" was an -// artificial split that wasted a full round trip. -// -// The verification step (2) uses targeted spot-checks (grep for a function -// name, read a specific line range) rather than re-reading every cited file. -// Full re-reads are an intrinsic self-correction anti-pattern that doubles -// I/O with marginal accuracy gain for narrow investigation tasks. - -import type { StepGuidance } from "../../lib/step.js"; - -export const SCOUT_STEP_NAMES: Record = { - 1: "Investigate", - 2: "Verify", - 3: "Report", -}; - -export function scoutSystemPrompt(): string { - return `You are a codebase investigator. You are assigned one narrow, specific question about a codebase. Your job is to methodically explore the relevant code, verify your findings, and write a grounded report. - -## Your role - -You find facts. You do NOT interpret, recommend, or opine. - -## Speed principles - -You are optimized for speed and breadth. Cast a wide net quickly. - -- Call MULTIPLE tools simultaneously. Read 3–5 files in one turn, not one at a time. -- Combine search strategies: run grep, find, and read calls together in a single turn. -- Use bash for broad sweeps: \`grep -rn\` across directories, \`find\` with multiple patterns. -- Do NOT be overly cautious or sequential. Explore aggressively, discard irrelevant results. -- Maximize work per turn. Each tool-call turn should accomplish as much as possible. - -## Strict rules - -- MUST answer only the assigned question. Do not expand scope. -- MUST write only factual observations: what the code does, what files exist, what patterns are present. -- MUST NOT produce recommendations or suggestions of any kind. -- MUST NOT express opinions about code quality. -- MUST NOT produce implementation plans or design ideas. -- MUST include file paths and line numbers when referencing code. -- MUST include relevant code excerpts (verbatim) to support each finding. -- SHOULD be thorough within the question scope: follow references, check related files. -- SHOULD note explicitly when something is NOT present (e.g., "No tests found for this module"). - -## Output file - -You write a single markdown file with your findings. The file location and format are provided in your final step. - -## Tools available - -- All read tools (read, bash, grep, glob, find, ls) — for reading the codebase. -- \`write\` / \`edit\` — for writing the output file only. -- \`koan_complete_step\` — to advance to the next workflow step.`; -} - -export function scoutStepGuidance( - step: number, - question: string, - outputFile: string, - investigatorRole: string, -): StepGuidance { - switch (step) { - case 1: - return { - title: SCOUT_STEP_NAMES[1], - instructions: [ - "Find and read the relevant code to answer the question.", - "", - "## Your Assignment", - "", - ...(question ? [`**Question:** ${question}`] : []), - ...(investigatorRole ? [`**Your investigator role:** ${investigatorRole}`] : []), - "", - "## Actions", - "", - "1. Parse the question: what exactly are you being asked to find?", - "2. Cast a wide net: run grep, find, or glob to locate candidate files. Run multiple searches simultaneously.", - "3. Read the most promising files immediately — do not wait for a separate step. Read 3–5 files at once.", - "4. Follow imports, cross-references, and call chains to related files. Read follow-up files in batches.", - "5. For each relevant finding, note the file path, line numbers, and a verbatim code excerpt.", - "6. Be thorough but fast: if a file is irrelevant, move on immediately.", - ], - }; - - case 2: - return { - title: SCOUT_STEP_NAMES[2], - instructions: [ - "Spot-check your key findings before reporting.", - "", - "## Actions", - "", - "1. Pick the 2–3 most critical claims from your investigation.", - "2. Verify each with a targeted tool call: grep for a function name, read a specific line range, ls to confirm a path exists.", - "3. If you find a discrepancy, correct it. If a file does not exist, drop the reference.", - "4. Organize your verified findings into a clear answer to the original question.", - "5. Identify any gaps — things you could not determine or areas you could not access.", - "6. Note anything that is explicitly NOT present (missing tests, missing config, etc.).", - ], - }; - - case 3: - return { - title: SCOUT_STEP_NAMES[3], - instructions: [ - "Write your findings to the output file.", - "", - `**Output file:** ${outputFile}`, - "", - "Write a markdown file with these exact sections:", - "", - "## Question", - "Restate the assigned question verbatim.", - "", - "## Findings", - "Factual observations that answer the question. Use sub-sections if the answer has multiple parts.", - "Cite file paths and line numbers for every claim. Include code snippets where relevant.", - "Every finding must be backed by a file you actually read — no inferred claims.", - "", - "## Files Examined", - "List every file you read during this investigation.", - "", - "## Gaps", - "Note anything you could not determine. If no gaps, write: (none)", - ], - }; - - default: - return { - title: `Step ${step}`, - instructions: [`Execute step ${step}.`], - }; - } -} diff --git a/src/planner/phases/workflow-orchestrator/phase.ts b/src/planner/phases/workflow-orchestrator/phase.ts deleted file mode 100644 index f2c6559..0000000 --- a/src/planner/phases/workflow-orchestrator/phase.ts +++ /dev/null @@ -1,107 +0,0 @@ -// WorkflowOrchestratorPhase: evaluates completed phase context and guides the -// user in choosing the next phase via a multi-turn conversation. -// -// Two-step workflow: -// Step 1 (Evaluate) — read workflow-status.md and artifacts, build mental model -// Step 2 (Propose) — call koan_propose_workflow, address feedback, commit via koan_set_next_phase -// -// Step 2 validation gate blocks koan_complete_step unless both -// koan_propose_workflow and koan_set_next_phase have been called successfully. -// This ensures: -// - The orchestrator cannot silently commit a transition without presenting -// options to the user (proposalMade gate) -// - The orchestrator cannot exit without committing a decision (nextPhaseSet gate) -// -// Uses event.isError (not event.error) matching ReviewablePhase convention. - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger, type Logger } from "../../../utils/logger.js"; -import type { RuntimeContext } from "../../lib/runtime-context.js"; -import { EventLog } from "../../lib/audit.js"; -import { BasePhase } from "../base-phase.js"; -import { - WORKFLOW_ORCHESTRATOR_STEP_NAMES, - workflowOrchestratorSystemPrompt, - workflowOrchestratorStepGuidance, -} from "./prompts.js"; -import type { StepGuidance } from "../../lib/step.js"; -import type { EpicPhase } from "../../types.js"; - -/** Config extracted from WorkflowOrchestratorTask by dispatch.ts. - * Keeps the constructor signature clean and type-safe. */ -export interface WorkflowOrchestratorConfig { - completedPhase: EpicPhase; - availablePhases: readonly EpicPhase[]; -} - -export class WorkflowOrchestratorPhase extends BasePhase { - protected readonly role = "workflow-orchestrator"; - protected readonly totalSteps = 2; - - private readonly completedPhase: EpicPhase; - private readonly availablePhases: readonly EpicPhase[]; - - // Validation gates for step 2. - // Both must be true before koan_complete_step advances past step 2. - private proposalMade = false; - private nextPhaseSet = false; - - constructor( - pi: ExtensionAPI, - config: WorkflowOrchestratorConfig, - ctx: RuntimeContext, - log?: Logger, - eventLog?: EventLog, - ) { - super(pi, ctx, log ?? createLogger("WorkflowOrchestratorPhase"), eventLog); - this.completedPhase = config.completedPhase; - this.availablePhases = config.availablePhases; - - // Track successful tool calls to enforce step 2 validation gate. - // event.isError matches ReviewablePhase convention — not event.error. - pi.on("tool_result", (event) => { - if (event.toolName === "koan_propose_workflow" && !event.isError) { - this.proposalMade = true; - } - if (event.toolName === "koan_set_next_phase" && !event.isError) { - this.nextPhaseSet = true; - } - return undefined; - }); - } - - protected getSystemPrompt(): string { - return workflowOrchestratorSystemPrompt(); - } - - protected getStepName(step: number): string { - return WORKFLOW_ORCHESTRATOR_STEP_NAMES[step] ?? `Step ${step}`; - } - - protected getStepGuidance(step: number): StepGuidance { - return workflowOrchestratorStepGuidance( - step, - this.ctx.epicDir!, - this.availablePhases, - ); - } - - protected async validateStepCompletion(step: number): Promise { - if (step === 2 && !this.proposalMade) { - return ( - "You must call koan_propose_workflow to present options to the user " + - "before committing a phase transition. " + - "Call koan_propose_workflow first, then koan_set_next_phase." - ); - } - if (step === 2 && !this.nextPhaseSet) { - return ( - "You must call koan_set_next_phase before completing this step. " + - "Call koan_propose_workflow again if you still need user input, " + - "then commit the decision with koan_set_next_phase." - ); - } - return super.validateStepCompletion(step); - } -} diff --git a/src/planner/phases/workflow-orchestrator/prompts.ts b/src/planner/phases/workflow-orchestrator/prompts.ts deleted file mode 100644 index 8caa3fd..0000000 --- a/src/planner/phases/workflow-orchestrator/prompts.ts +++ /dev/null @@ -1,102 +0,0 @@ -// Workflow orchestrator prompts — system prompt and step guidance. -// -// Two-step workflow following the single-cognitive-goal principle: -// Step 1 (Evaluate) — read workflow-status.md and phase artifacts; build mental model -// Step 2 (Propose) — call koan_propose_workflow, handle feedback, commit via koan_set_next_phase -// -// availablePhases is injected into step 2 guidance from the task manifest so -// the orchestrator only proposes valid DAG transitions. - -import type { StepGuidance } from "../../lib/step.js"; -import type { EpicPhase } from "../../types.js"; -import { PHASE_DESCRIPTIONS } from "../../lib/phase-dag.js"; - -export const WORKFLOW_ORCHESTRATOR_STEP_NAMES: Record = { - 1: "Evaluate", - 2: "Propose", -}; - -export function workflowOrchestratorSystemPrompt(): string { - return `You are a workflow orchestrator for a coding task planning pipeline. Your role is to evaluate what has been accomplished and guide the user in choosing what to do next. - -## Your responsibilities - -1. Read available context (workflow-status.md and any phase artifacts) -2. Understand what was accomplished and what options are available -3. Present a clear status report and phase options to the user -4. Hold a conversation until the user's intent is clear -5. Commit the next phase decision via koan_set_next_phase - -## Communication style - -- Be concise and direct -- Focus on what matters to the user's goal -- When the user's direction is clear, commit it — don't over-clarify -- Present phase options with helpful context, not technical jargon - -## Constraints - -- You must call koan_propose_workflow before koan_set_next_phase -- You may call koan_propose_workflow multiple times if the user needs more clarification -- The phase you commit must be in your available phases list`; -} - -export function workflowOrchestratorStepGuidance( - step: number, - epicDir: string, - availablePhases: readonly EpicPhase[], -): StepGuidance { - switch (step) { - case 1: - return { - title: WORKFLOW_ORCHESTRATOR_STEP_NAMES[1], - instructions: [ - `Read \`${epicDir}/workflow-status.md\` to understand:`, - "", - "- Which phase just completed", - "- What artifacts are available", - "- Which phases are available next", - "", - "Then read any relevant artifacts (landscape.md, brief.md, etc.) to", - "build a thorough understanding of what has been accomplished and what", - "the user's goal is.", - "", - "Do NOT call koan_propose_workflow yet. Comprehend the current state first.", - ], - }; - - case 2: { - const phaseList = availablePhases.map((p) => - `- **${p}**: ${PHASE_DESCRIPTIONS[p]}`, - ); - return { - title: WORKFLOW_ORCHESTRATOR_STEP_NAMES[2], - instructions: [ - "Call koan_propose_workflow with:", - "", - "1. A **status_report** (markdown) summarizing what was accomplished", - " and why the available phases make sense right now", - "", - "2. **recommended_phases** — the available next phases (in order of", - " recommendation):", - "", - ...phaseList, - "", - "The user will respond with their direction. If their response is clear,", - "call koan_set_next_phase to commit the decision (with optional instructions", - "to focus the next phase). If their response needs clarification, call", - "koan_propose_workflow again with an updated status report.", - "", - "You MUST call both koan_propose_workflow and koan_set_next_phase before", - "completing this step.", - ], - }; - } - - default: - return { - title: `Step ${step}`, - instructions: [`Execute step ${step}.`], - }; - } -} diff --git a/src/planner/subagent.ts b/src/planner/subagent.ts deleted file mode 100644 index e6e893f..0000000 --- a/src/planner/subagent.ts +++ /dev/null @@ -1,266 +0,0 @@ -// Subagent spawn infrastructure. -// -// A single public function, spawnSubagent(), handles all six roles. -// It writes task.json to the subagent directory before spawning (the -// directory-as-contract invariant: the child reads task.json to discover -// its role and parameters — no structured data flows through CLI flags). -// -// The spawn command carries only what pi needs at the OS level: -// pi --mode json -p -e {ext} --koan-dir {subagentDir} [--model {model}] -// [--koan-debug] "{bootPrompt}" -// -// All tools register unconditionally at init. Task-specific content is -// intentionally absent from spawn prompts: it arrives as step 1 guidance -// returned by the first koan_complete_step call, after the calling pattern -// is established. - -import { spawn } from "node:child_process"; -import { createWriteStream } from "node:fs"; -import * as path from "node:path"; - -import { createLogger, type Logger } from "../utils/logger.js"; -import { resolveModelForRole } from "./model-resolver.js"; -import { runIpcResponder, type ScoutSpawnContext } from "./lib/ipc-responder.js"; -import { writeTaskFile, type SubagentTask, type ScoutTask } from "./lib/task.js"; -import { KOAN_DEBUG_FLAG } from "./lib/constants.js"; -import type { WebServerHandle } from "./web/server-types.js"; - -// -- Result type -- - -export interface SubagentResult { - exitCode: number; - stderr: string; - subagentDir: string; -} - -// -- Spawn options -- - -export interface SpawnOptions { - cwd: string; - extensionPath: string; - /** When true, appends --koan-debug to the child pi args so subagents - * receive the debug flag. Non-optional: every construction site must - * set it explicitly so TypeScript catches any missed call site. */ - debugMode: boolean; - modelOverride?: string; - log?: Logger; - webServer?: WebServerHandle; -} - -// -- Constants -- - -// Roles that support koan_request_scouts and therefore need a ScoutSpawnContext -// wired into their IPC responder. -const ROLES_WITH_SCOUT_SUPPORT = new Set([ - "intake", - "decomposer", - "planner", -]); - -// -- Private helpers -- - -// The entire spawn prompt. Kept to one sentence deliberately: the LLM must -// call koan_complete_step before seeing any task instructions. Putting task -// content here risks text output + immediate exit on weaker models. -function bootPrompt(role: string): string { - return `You are a koan ${role} agent. Call koan_complete_step to receive your instructions.`; -} - -// Builds the CLI args passed to `pi` for a subagent process. -// Exported for unit tests so flag/model argument behavior can be verified -// without spawning a real process. -export function buildSubagentArgs( - role: SubagentTask["role"], - subagentDir: string, - extensionPath: string, - modelOverride: string | undefined, - debugMode: boolean, -): string[] { - return [ - // --mode json makes pi emit structured JSONL on stdout instead of human- - // readable text. Combined with -p (non-interactive), this is the designed - // integration surface for external UIs. Pi's own subagent extension uses - // the identical flag pair — ["--mode", "json", "-p"] — confirming this is - // the supported composition. - "--mode", "json", - "-p", - "-e", extensionPath, - "--koan-dir", subagentDir, - ...(modelOverride ? ["--model", modelOverride] : []), - ...(debugMode ? ["--" + KOAN_DEBUG_FLAG] : []), - bootPrompt(role), - ]; -} - -// Builds the ScoutSpawnContext injected into the IPC responder. Scouts spawned -// via this context do not receive a web server — they are narrow investigators -// with no user interaction and no nested IPC. -function makeScoutSpawnContext( - parentRole: string, - epicDir: string, - opts: SpawnOptions, - log: Logger, -): ScoutSpawnContext { - return { - epicDir, - parentRole, - async spawnScout(task: ScoutTask, scoutSubagentDir: string): Promise { - const result = await spawnSubagent(task, scoutSubagentDir, { - cwd: opts.cwd, - extensionPath: opts.extensionPath, - debugMode: opts.debugMode, - // Deliberately no webServer — scouts are narrow investigators. - log, - }); - return result.exitCode; - }, - }; -} - -// -- Public API -- - -/** - * Spawn a koan subagent for the given task. - * - * Writes task.json to subagentDir before spawning so the child process can - * read its role and parameters without relying on CLI flags. - */ -export async function spawnSubagent( - task: SubagentTask, - subagentDir: string, - opts: SpawnOptions, -): Promise { - const log = opts.log ?? createLogger("Subagent"); - - await writeTaskFile(subagentDir, task); - - const modelOverride = opts.modelOverride ?? await resolveModelForRole(task.role); - - const scoutContext = ROLES_WITH_SCOUT_SUPPORT.has(task.role) - ? makeScoutSpawnContext(task.role, task.epicDir, opts, log) - : undefined; - - const args = buildSubagentArgs( - task.role, - subagentDir, - opts.extensionPath, - modelOverride, - opts.debugMode, - ); - - log(`Spawning ${task.role} subagent`, { subagentDir }); - - return new Promise((resolve) => { - const stdoutLog = createWriteStream(path.join(subagentDir, "stdout.log"), { flags: "w" }); - const stderrLog = createWriteStream(path.join(subagentDir, "stderr.log"), { flags: "w" }); - - const proc = spawn("pi", args, { - cwd: opts.cwd, - shell: false, - stdio: ["ignore", "pipe", "pipe"], - }); - - // Start IPC responder concurrently when a web server handle is available. - let abortIpc: (() => void) | undefined; - if (opts.webServer) { - const ac = new AbortController(); - abortIpc = () => ac.abort(); - void runIpcResponder(subagentDir, opts.webServer, ac.signal, scoutContext); - } - - let stderr = ""; - let buffer = ""; - - proc.stdout.on("data", (data: Buffer) => { - // Write raw bytes first — log file receives the full JSONL output - // regardless of what the parser does. Diagnostics are unaffected. - stdoutLog.write(data); - - // Accumulate into buffer because a single "data" event may contain - // a partial line (TCP-style framing — no guarantee of line boundaries). - buffer += data.toString(); - - // Split on newlines. lines[0..n-2] are complete; lines[n-1] may be a - // partial line — keep it in buffer for the next "data" event. - const lines = buffer.split("\n"); - buffer = lines.pop() || ""; // trailing partial line (or "" if data ended with \n) - - for (const line of lines) { - if (!line.trim()) continue; - try { - const event = JSON.parse(line); - // Filter to text_delta and thinking_delta. --mode json emits all - // session events (tool execution, turn boundaries, compaction, etc.). - // Only these two carry incremental tokens we want to stream. - // Everything else is handled by the existing state.json polling path. - if ( - event.type === "message_update" && - (event.assistantMessageEvent?.type === "text_delta" || - event.assistantMessageEvent?.type === "thinking_delta") && - typeof event.assistantMessageEvent.delta === "string" - ) { - opts.webServer?.pushTokenDelta(event.assistantMessageEvent.delta); - } - // Clear on message_start, NOT message_end. Pipe buffering delivers - // an entire turn's events in one read(), so clearing on message_end - // wipes streamingText in the same tick as pushTokenDelta — the - // browser never renders the text. Clearing on message_start lets - // thinking text survive through tool execution until the next turn. - if ( - event.type === "message_start" && - event.message?.role === "assistant" - ) { - opts.webServer?.clearTokenStream(); - } - } catch { - // Malformed line (e.g. stderr bleed or partial JSONL during - // buffer flush). Skip — the log file has the full bytes. - } - } - }); - - proc.stderr.on("data", (data: Buffer) => { - stderr += data.toString(); - stderrLog.write(data); - }); - - proc.on("close", (code) => { - abortIpc?.(); - stdoutLog.end(); - stderrLog.end(); - - // Flush any partial JSONL line still in the buffer. Under normal - // operation the buffer is empty at close, but a process killed - // mid-line (e.g., SIGKILL) would otherwise lose the last event. - // This must happen before resolve() so the delta arrives before - // the driver calls clearSubagent() -> pushEvent("subagent-idle"). - if (buffer.trim()) { - try { - const event = JSON.parse(buffer); - if ( - event.type === "message_update" && - (event.assistantMessageEvent?.type === "text_delta" || - event.assistantMessageEvent?.type === "thinking_delta") && - typeof event.assistantMessageEvent.delta === "string" - ) { - opts.webServer?.pushTokenDelta(event.assistantMessageEvent.delta); - } - } catch { - // Ignore malformed trailing content — log file has the raw bytes. - } - } - - const exitCode = code ?? 1; - log(`${task.role} subagent exited`, { exitCode }); - resolve({ exitCode, stderr, subagentDir }); - }); - - proc.on("error", (error) => { - abortIpc?.(); - stdoutLog.end(); - stderrLog.end(); - log(`${task.role} subagent spawn error`, { error: error.message }); - resolve({ exitCode: 1, stderr: error.message, subagentDir }); - }); - }); -} diff --git a/src/planner/tools/ask.ts b/src/planner/tools/ask.ts deleted file mode 100644 index 5298709..0000000 --- a/src/planner/tools/ask.ts +++ /dev/null @@ -1,364 +0,0 @@ -// IPC-based tools: koan_ask_question and koan_request_scouts. -// Both tools use file-based IPC to pause subagent execution and communicate -// with the parent session, then resume with the response. -// -// koan_ask_question — ask the user a question, get an answer -// koan_request_scouts — request parallel codebase scouts, get findings paths - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; - -import { Type, type Static } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import type { RuntimeContext } from "../lib/runtime-context.js"; -import { - ipcFileExists, - writeIpcFile, - createAskRequest, - createScoutRequest, - pollIpcUntilResponse, - type AskAnswerPayload, - type AskIpcFile, - type ScoutIpcFile, - type ScoutRequest, -} from "../lib/ipc.js"; - -// The tool accepts an array of questions in a single call. All questions are -// written to a single IPC file and presented to the user one at a time. -// The tool blocks until all answers arrive, then returns them together. - -// -- Schemas -- - -const OptionItemSchema = Type.Object({ - label: Type.String({ description: "Display label" }), -}); - -const QuestionSchema = Type.Object({ - id: Type.String({ description: "Question id (e.g. auth, cache, priority)" }), - question: Type.String({ description: "Question text" }), - context: Type.Optional(Type.String({ description: "Optional background/context to help the user answer." })), - options: Type.Array(OptionItemSchema, { - description: "Available options. Do not include 'Other'.", - minItems: 1, - }), - multi: Type.Optional(Type.Boolean({ description: "Allow multi-select" })), - recommended: Type.Optional( - Type.Number({ description: "0-indexed recommended option." }), - ), -}); - -type Question = Static; - -const AskParamsSchema = Type.Object({ - questions: Type.Array(QuestionSchema, { - description: "Questions to ask the user. Presented one at a time.", - minItems: 1, - }), -}); - -type AskParams = Static; - -const ScoutTaskSchema = Type.Object({ - id: Type.String({ description: "Scout task ID, e.g. 'auth-libs'" }), - role: Type.String({ description: "Custom role for the scout, e.g. 'system architect'" }), - prompt: Type.String({ description: "What to find, e.g. 'Find all auth-related files in src/'" }), -}); - -const RequestScoutsSchema = Type.Object({ - scouts: Type.Array(ScoutTaskSchema, { description: "Scout tasks to run in parallel", minItems: 1 }), -}); - -type RequestScoutsParams = Static; - -// -- Result formatting (ask) -- - -interface AskResult { - id: string; - question: string; - context?: string; - options: string[]; - multi: boolean; - selectedOptions: string[]; - customInput?: string; -} - -function formatSelectionForSummary(result: AskResult): string { - const hasSelectedOptions = result.selectedOptions.length > 0; - const hasCustomInput = Boolean(result.customInput); - - if (!hasSelectedOptions && !hasCustomInput) return "(cancelled)"; - - if (hasSelectedOptions && hasCustomInput) { - const selectedPart = result.multi - ? `[${result.selectedOptions.join(", ")}]` - : result.selectedOptions[0]; - return `${selectedPart} + Other: "${result.customInput}"`; - } - - if (hasCustomInput) return `"${result.customInput}"`; - if (result.multi) return `[${result.selectedOptions.join(", ")}]`; - return result.selectedOptions[0] ?? "(no selection)"; -} - -function formatQuestionContext(result: AskResult): string { - const lines: string[] = [ - `Question (${result.id})`, - `Prompt: ${result.question}`, - ]; - - if (result.context?.trim()) { - lines.push("Context:"); - for (const paragraph of result.context.trim().split(/\n\s*\n/u)) { - lines.push(` ${paragraph}`); - } - } - - lines.push( - "Options:", - ...result.options.map((o, i) => ` ${i + 1}. ${o}`), - "Response:", - ); - - const hasSelectedOptions = result.selectedOptions.length > 0; - const hasCustomInput = Boolean(result.customInput); - - if (!hasSelectedOptions && !hasCustomInput) { - lines.push(" Selected: (cancelled)"); - return lines.join("\n"); - } - - if (hasSelectedOptions) { - const text = result.multi - ? `[${result.selectedOptions.join(", ")}]` - : result.selectedOptions[0]; - lines.push(` Selected: ${text}`); - } - - if (hasCustomInput) { - if (!hasSelectedOptions) lines.push(" Selected: Other (type your own)"); - lines.push(` Custom input: ${result.customInput}`); - } - - return lines.join("\n"); -} - -function buildSessionContent(result: AskResult): string { - return `User answer:\n${result.id}: ${formatSelectionForSummary(result)}\n\nAnswer context:\n${formatQuestionContext(result)}`; -} - -function buildQuestionResult( - q: Question, - answer: AskAnswerPayload | null, -): AskResult { - const selectedOptions = answer?.id === q.id ? answer.selectedOptions : []; - const customInput = answer?.id === q.id ? answer.customInput : undefined; - - return { - id: q.id, - question: q.question, - context: q.context, - options: q.options.map((o) => o.label), - multi: q.multi ?? false, - selectedOptions, - customInput, - }; -} - -// -- Tool registration -- - -const ASK_TOOL_DESCRIPTION = ` -Ask the user for clarification when choices materially affect the outcome. - -- Pass all questions in a single call. They are presented to the user one at a time. -- Prefer 2-5 concise options per question. -- Use multi=true when multiple answers are valid. -- Use recommended= (0-indexed) to mark the default option. -- Optionally include context to give enough background for an informed answer. -- Do NOT include an 'Other' option; UI adds it automatically. -`.trim(); - -const SCOUTS_TOOL_DESCRIPTION = ` -Request parallel codebase scouting. Use when you need to explore specific -areas of the codebase before making decisions or asking questions. - -Each scout answers one narrow question and writes findings to a markdown file. -Scouts run in parallel. The tool returns the file paths to read. - -- id: unique identifier for this scout task (e.g., "auth-patterns") -- role: the investigator role for the scout (e.g., "security auditor") -- prompt: what to find (e.g., "Find all authentication middleware in src/") -`.trim(); - -// -- Extracted execute logic -- - -import type { ToolResult } from "./types.js"; - -export async function executeAskQuestion( - params: AskParams, - subagentDir: string | null, - signal?: AbortSignal | null, -): Promise { - if (!subagentDir) { - return { - content: [{ type: "text" as const, text: "Error: koan_ask_question is only available in subagent context." }], - details: undefined, - }; - } - - // Guard: IPC file already exists (another request type is pending) - if (await ipcFileExists(subagentDir)) { - return { - content: [{ type: "text" as const, text: "Error: An IPC request is already pending." }], - details: undefined, - }; - } - - // Write all questions to a single IPC file - const questions = params.questions.map((q) => ({ - id: q.id, - question: q.question, - context: q.context, - options: q.options, - multi: q.multi, - recommended: q.recommended, - })); - const ipc = createAskRequest(questions); - await writeIpcFile(subagentDir, ipc); - - // Poll until the user answers all questions - const { outcome, ipc: answeredIpc } = await pollIpcUntilResponse(subagentDir, ipc, signal); - - switch (outcome) { - case "answered": { - const askIpc = answeredIpc as AskIpcFile; - const answers = askIpc.response?.answers ?? []; - - const resultLines: string[] = []; - for (const q of params.questions) { - const answer = answers.find((a) => a.id === q.id) ?? null; - const result = buildQuestionResult(q, answer); - resultLines.push(buildSessionContent(result)); - } - - return { - content: [{ type: "text" as const, text: resultLines.join("\n\n---\n\n") }], - details: undefined, - }; - } - case "cancelled": - return { - content: [{ type: "text" as const, text: "The user declined to answer. Proceed with your best judgment." }], - details: undefined, - }; - case "aborted": - return { - content: [{ type: "text" as const, text: "The question was aborted." }], - details: undefined, - }; - case "file-gone": - default: - return { - content: [{ type: "text" as const, text: "The question was cancelled." }], - details: undefined, - }; - } -} - -export async function executeRequestScouts( - params: RequestScoutsParams, - subagentDir: string | null, - signal?: AbortSignal | null, -): Promise { - const dir = subagentDir; - - if (!dir) { - return { - content: [{ type: "text" as const, text: "Error: koan_request_scouts is only available in subagent context." }], - details: undefined, - }; - } - - if (await ipcFileExists(dir)) { - return { - content: [{ type: "text" as const, text: "Error: An IPC request is already pending." }], - details: undefined, - }; - } - - const ipc = createScoutRequest(params.scouts as ScoutRequest[]); - await writeIpcFile(dir, ipc); - - const { outcome, ipc: completedIpc } = await pollIpcUntilResponse(dir, ipc, signal); - - switch (outcome) { - case "completed": { - const scoutIpc = completedIpc as ScoutIpcFile; - const findings = scoutIpc.response!.findings; - const failures = scoutIpc.response!.failures; - const sections: string[] = [ - `Scout findings: ${findings.length} completed, ${failures.length} failed.`, - "", - ]; - for (const f of findings) { - try { - const content = await fs.readFile(f, "utf8"); - sections.push(`--- scout: ${path.basename(path.dirname(f))} ---`); - sections.push(content.trim()); - sections.push(""); - } catch { - sections.push(`--- scout: ${path.basename(path.dirname(f))} --- (could not read findings)`); - sections.push(""); - } - } - if (failures.length > 0) { - sections.push(`Failed scouts (non-fatal, proceed without them): ${failures.join(", ")}`); - } - return { - content: [{ type: "text" as const, text: sections.join("\n") }], - details: undefined, - }; - } - case "aborted": - return { - content: [{ type: "text" as const, text: "Scout request aborted. Proceed without codebase context." }], - details: undefined, - }; - case "file-gone": - default: - return { - content: [{ type: "text" as const, text: "Scout request cancelled. Proceed without codebase context." }], - details: undefined, - }; - } -} - -// -- Tool registration -- - -export function registerAskTools(pi: ExtensionAPI, ctx: RuntimeContext): void { - // -- koan_ask_question -- - - pi.registerTool({ - name: "koan_ask_question", - label: "Ask question", - description: ASK_TOOL_DESCRIPTION, - parameters: AskParamsSchema, - - async execute(_toolCallId, params, signal) { - return executeAskQuestion(params as AskParams, ctx.subagentDir, signal); - }, - }); - - // -- koan_request_scouts -- - - pi.registerTool({ - name: "koan_request_scouts", - label: "Request codebase scouts", - description: SCOUTS_TOOL_DESCRIPTION, - parameters: RequestScoutsSchema, - - async execute(_toolCallId, params, signal) { - return executeRequestScouts(params as RequestScoutsParams, ctx.subagentDir, signal); - }, - }); -} diff --git a/src/planner/tools/index.ts b/src/planner/tools/index.ts deleted file mode 100644 index a787115..0000000 --- a/src/planner/tools/index.ts +++ /dev/null @@ -1,23 +0,0 @@ -// Tool registration aggregator. Single entry point for koan.ts. -// All tools registered here; RuntimeContext replaces the three separate -// mutable refs (PlanRef, SubagentRef, WorkflowDispatch) from the old design. - -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; -import type { RuntimeContext } from "../lib/runtime-context.js"; - -import { registerWorkflowTools } from "./workflow.js"; -import { registerOrchestratorTools } from "./orchestrator.js"; -import { registerAskTools } from "./ask.js"; -import { registerReviewArtifactTool } from "./review-artifact.js"; -import { registerWorkflowDecisionTools } from "./workflow-decision.js"; - -export type { RuntimeContext } from "../lib/runtime-context.js"; -export { createRuntimeContext } from "../lib/runtime-context.js"; - -export function registerAllTools(pi: ExtensionAPI, ctx: RuntimeContext): void { - registerWorkflowTools(pi, ctx); - registerOrchestratorTools(pi, ctx); - registerAskTools(pi, ctx); - registerReviewArtifactTool(pi, ctx); - registerWorkflowDecisionTools(pi, ctx); -} diff --git a/src/planner/tools/orchestrator.ts b/src/planner/tools/orchestrator.ts deleted file mode 100644 index 8975757..0000000 --- a/src/planner/tools/orchestrator.ts +++ /dev/null @@ -1,245 +0,0 @@ -// Orchestrator tools: four tools for the orchestrator subagent to advance -// story lifecycle state. The orchestrator uses koan_ask_question for all -// user communication -- see docs/state.md "No escalated status". -// -// Each tool: -// 1. Validates that the story is in the correct source state -// 2. Writes JSON state (for driver polling) -// 3. Writes templated markdown status.md (for LLM reads) - -import { Type } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import type { RuntimeContext } from "../lib/runtime-context.js"; -import { loadStoryState, saveStoryState } from "../epic/state.js"; -import { writeArtifact } from "../epic/artifacts.js"; -import type { StoryStatus } from "../types.js"; -import { now } from "../lib/time.js"; -import type { ToolResult } from "./types.js"; - -// -- Helpers -- - -// Templated status.md format -- see docs/state.md for the status file contract. -function statusMd( - storyId: string, - status: StoryStatus, - lastAction: string, - verificationSummary: string, - notes: string, -): string { - return [ - `# Status: ${status}`, - "", - "## Last Action", - lastAction, - "", - "## Verification Summary", - verificationSummary, - "", - "## Notes", - notes, - "", - ].join("\n"); -} - -function requireEpicDir(ctx: RuntimeContext): string { - if (!ctx.epicDir) { - throw new Error("Epic directory is not set. Is this running inside a koan subagent?"); - } - return ctx.epicDir; -} - -// Validates story status against allowed source statuses. Throws on mismatch. -export function assertStatus(storyId: string, current: StoryStatus, allowed: StoryStatus[]): void { - if (!allowed.includes(current)) { - const listed = allowed.map((s) => `'${s}'`).join(" or "); - throw new Error( - `Cannot transition story '${storyId}': expected status ${listed}, got '${current}'.`, - ); - } -} - -// -- Extracted execute logic -- - -export async function executeSelectStory(epicDir: string, storyId: string): Promise { - const ts = now(); - const state = await loadStoryState(epicDir, storyId); - assertStatus(storyId, state.status, ["pending", "retry"]); - - await saveStoryState(epicDir, storyId, { ...state, status: "selected", updatedAt: ts }); - await writeArtifact( - epicDir, `stories/${storyId}/status.md`, - statusMd(storyId, "selected", `Selected at: ${ts}`, "(pending -- not yet verified)", ""), - ); - - return { - content: [{ type: "text" as const, text: `Story '${storyId}' selected.` }], - details: undefined, - }; -} - -export async function executeCompleteStory( - epicDir: string, - storyId: string, - verificationSummary?: string, -): Promise { - const ts = now(); - const state = await loadStoryState(epicDir, storyId); - assertStatus(storyId, state.status, ["verifying"]); - - await saveStoryState(epicDir, storyId, { ...state, status: "done", updatedAt: ts }); - await writeArtifact( - epicDir, `stories/${storyId}/status.md`, - statusMd( - storyId, "done", - `Completed at: ${ts}`, - verificationSummary ?? "All checks passed.", - "", - ), - ); - - return { - content: [{ type: "text" as const, text: `Story '${storyId}' completed.` }], - details: undefined, - }; -} - -export async function executeRetryStory( - epicDir: string, - storyId: string, - failureSummary: string, -): Promise { - const ts = now(); - const state = await loadStoryState(epicDir, storyId); - assertStatus(storyId, state.status, ["verifying"]); - - await saveStoryState(epicDir, storyId, { - ...state, - status: "retry", - updatedAt: ts, - failureSummary: failureSummary, - }); - await writeArtifact( - epicDir, `stories/${storyId}/status.md`, - statusMd( - storyId, "retry", - `Queued for retry at: ${ts}`, - "Failed -- see Notes for details.", - failureSummary, - ), - ); - - return { - content: [{ type: "text" as const, text: `Story '${storyId}' queued for retry.` }], - details: undefined, - }; -} - -export async function executeSkipStory( - epicDir: string, - storyId: string, - reason: string, -): Promise { - const ts = now(); - const state = await loadStoryState(epicDir, storyId); - assertStatus(storyId, state.status, ["pending", "retry"]); - - await saveStoryState(epicDir, storyId, { - ...state, - status: "skipped", - updatedAt: ts, - skipReason: reason, - }); - await writeArtifact( - epicDir, `stories/${storyId}/status.md`, - statusMd( - storyId, "skipped", - `Skipped at: ${ts}`, - "(not executed)", - reason, - ), - ); - - return { - content: [{ type: "text" as const, text: `Story '${storyId}' skipped.` }], - details: undefined, - }; -} - -// -- Tool registration -- - -export function registerOrchestratorTools(pi: ExtensionAPI, ctx: RuntimeContext): void { - // -- koan_select_story -- - // Valid source statuses: pending, retry -- see story lifecycle in docs/state.md. - - pi.registerTool({ - name: "koan_select_story", - label: "Select story for execution", - description: "Mark a pending or retried story as selected for execution. Valid only when the story is in 'pending' or 'retry' status.", - parameters: Type.Object({ - story_id: Type.String({ description: "The story ID to select." }), - }), - async execute(_toolCallId, params) { - const { story_id } = params as { story_id: string }; - return executeSelectStory(requireEpicDir(ctx), story_id); - }, - }); - - // -- koan_complete_story -- - // Valid source status: verifying -- see story lifecycle in docs/state.md. - - pi.registerTool({ - name: "koan_complete_story", - label: "Complete story", - description: "Mark a story as done after verifying all acceptance criteria are met. Only valid when story is in 'verifying' status.", - parameters: Type.Object({ - story_id: Type.String({ description: "The story ID to mark as done." }), - verification_summary: Type.Optional(Type.String({ - description: "Summary of verification checks that passed.", - })), - }), - async execute(_toolCallId, params) { - const { story_id, verification_summary } = params as { - story_id: string; - verification_summary?: string; - }; - return executeCompleteStory(requireEpicDir(ctx), story_id, verification_summary); - }, - }); - - // -- koan_retry_story -- - // Valid source status: verifying -- see story lifecycle in docs/state.md. - - pi.registerTool({ - name: "koan_retry_story", - label: "Retry story", - description: "Mark a story for retry and record why the previous attempt failed. Only valid when story is in 'verifying' status.", - parameters: Type.Object({ - story_id: Type.String({ description: "The story ID to retry." }), - failure_summary: Type.String({ - description: "Concrete description of what went wrong. Include failing commands, error messages, and what the executor should do differently.", - }), - }), - async execute(_toolCallId, params) { - const { story_id, failure_summary } = params as { story_id: string; failure_summary: string }; - return executeRetryStory(requireEpicDir(ctx), story_id, failure_summary); - }, - }); - - // -- koan_skip_story -- - // Valid source statuses: pending, retry -- see story lifecycle in docs/state.md. - - pi.registerTool({ - name: "koan_skip_story", - label: "Skip story", - description: "Mark a pending or retried story as skipped and record the reason. Valid when story is in 'pending' or 'retry' status.", - parameters: Type.Object({ - story_id: Type.String({ description: "The story ID to skip." }), - reason: Type.String({ description: "Why this story is being skipped." }), - }), - async execute(_toolCallId, params) { - const { story_id, reason } = params as { story_id: string; reason: string }; - return executeSkipStory(requireEpicDir(ctx), story_id, reason); - }, - }); -} diff --git a/src/planner/tools/review-artifact.ts b/src/planner/tools/review-artifact.ts deleted file mode 100644 index f8e91f6..0000000 --- a/src/planner/tools/review-artifact.ts +++ /dev/null @@ -1,148 +0,0 @@ -// IPC-based tool: koan_review_artifact. -// Presents a written markdown artifact for human review via file-based IPC, -// pausing subagent execution until the user responds with feedback or accepts. -// -// The review loop is LLM-driven: if the user provides feedback, the LLM revises -// the artifact and invokes this tool again. The tool itself is stateless — it -// reads the artifact, presents it, and returns the user's response verbatim. - -import * as path from "node:path"; - -import { Type, type Static } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import type { RuntimeContext } from "../lib/runtime-context.js"; -import { readArtifact } from "../epic/artifacts.js"; -import { - ipcFileExists, - writeIpcFile, - createArtifactReviewRequest, - pollIpcUntilResponse, - type ArtifactReviewIpcFile, -} from "../lib/ipc.js"; - -// -- Schema -- - -const ReviewArtifactSchema = Type.Object({ - path: Type.String({ description: "File path of the artifact to present for review" }), - description: Type.Optional(Type.String({ description: "Optional context for the reviewer (e.g. 'This is the epic brief')" })), -}); - -type ReviewArtifactParams = Static; - -// -- Tool description -- - -const REVIEW_ARTIFACT_DESCRIPTION = ` -Present a written artifact (markdown file) for human review. - -The user will see the rendered artifact content and can either accept it -or provide feedback. The tool returns ACCEPTED or REVISION REQUESTED with -the user's feedback text. See the review protocol in your system prompt -for how to handle each response. - -Parameters: -- path: the file path of the artifact to review -- description: optional context for the reviewer -`.trim(); - -// -- Execute logic -- - -import type { ToolResult } from "./types.js"; - -export async function executeReviewArtifact( - params: ReviewArtifactParams, - epicDir: string | null, - subagentDir: string | null, - signal?: AbortSignal | null, -): Promise { - const dir = subagentDir; - - if (!dir) { - return { - content: [{ type: "text" as const, text: "Error: koan_review_artifact is only available in subagent context." }], - details: undefined, - }; - } - - if (!epicDir) { - return { - content: [{ type: "text" as const, text: "Error: Epic directory is not set." }], - details: undefined, - }; - } - - if (await ipcFileExists(dir)) { - return { - content: [{ type: "text" as const, text: "Error: An IPC request is already pending." }], - details: undefined, - }; - } - - let content: string; - try { - const relativePath = path.relative(epicDir, params.path); - content = await readArtifact(epicDir, relativePath); - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - return { - content: [{ type: "text" as const, text: `Error: Could not read artifact at "${params.path}": ${msg}` }], - details: undefined, - }; - } - - const ipc = createArtifactReviewRequest({ - artifactPath: params.path, - content, - description: params.description, - }); - await writeIpcFile(dir, ipc); - - const { outcome, ipc: answeredIpc } = await pollIpcUntilResponse(dir, ipc, signal); - - switch (outcome) { - case "answered": { - const artifactIpc = answeredIpc as ArtifactReviewIpcFile; - const feedback = artifactIpc.response?.feedback || "(no feedback)"; - const accepted = feedback.trim().toLowerCase() === "accept"; - - if (accepted) { - return { - content: [{ type: "text" as const, text: "ACCEPTED — The user approved this artifact." }], - details: undefined, - }; - } - - return { - content: [{ type: "text" as const, text: - "REVISION REQUESTED — The user provided feedback:\n\n" + feedback }], - details: undefined, - }; - } - case "aborted": - return { - content: [{ type: "text" as const, text: "The review was aborted." }], - details: undefined, - }; - case "file-gone": - default: - return { - content: [{ type: "text" as const, text: "The review was cancelled." }], - details: undefined, - }; - } -} - -// -- Tool registration -- - -export function registerReviewArtifactTool(pi: ExtensionAPI, ctx: RuntimeContext): void { - pi.registerTool({ - name: "koan_review_artifact", - label: "Review artifact", - description: REVIEW_ARTIFACT_DESCRIPTION, - parameters: ReviewArtifactSchema, - - async execute(_toolCallId, params, signal) { - return executeReviewArtifact(params as ReviewArtifactParams, ctx.epicDir, ctx.subagentDir, signal); - }, - }); -} diff --git a/src/planner/tools/types.ts b/src/planner/tools/types.ts deleted file mode 100644 index 6a93c01..0000000 --- a/src/planner/tools/types.ts +++ /dev/null @@ -1 +0,0 @@ -export type ToolResult = { content: Array<{ type: "text"; text: string }>; details: undefined }; diff --git a/src/planner/tools/workflow-decision.ts b/src/planner/tools/workflow-decision.ts deleted file mode 100644 index e3d3298..0000000 --- a/src/planner/tools/workflow-decision.ts +++ /dev/null @@ -1,243 +0,0 @@ -// IPC-based tools for workflow phase routing. -// -// koan_propose_workflow — presents phase transition options to the user via -// file-based IPC. Structurally identical to koan_review_artifact: writes -// an IPC file, polls for the response, returns the user's text. The -// orchestrator may call this tool multiple times if the user provides -// feedback rather than direction. The loop terminates only when the -// orchestrator commits via koan_set_next_phase. -// -// koan_set_next_phase — commits the phase transition decision. Reads task.json -// to obtain the list of valid phases, validates the choice, and writes -// workflow-decision.json for the driver to read after the orchestrator exits. - -import { promises as fs } from "node:fs"; -import * as path from "node:path"; -import * as crypto from "node:crypto"; - -import { Type, type Static } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import type { RuntimeContext } from "../lib/runtime-context.js"; -import type { ToolResult } from "./types.js"; -import { - ipcFileExists, - writeIpcFile, - createWorkflowDecisionRequest, - pollIpcUntilResponse, - type WorkflowDecisionIpcFile, -} from "../lib/ipc.js"; -import { readTaskFile } from "../lib/task.js"; -import type { WorkflowOrchestratorTask } from "../lib/task.js"; - -// --------------------------------------------------------------------------- -// koan_propose_workflow -// --------------------------------------------------------------------------- - -const ProposeWorkflowSchema = Type.Object({ - status_report: Type.String({ - description: "Markdown summary of what was accomplished in the completed phase and why these phases are available next.", - }), - recommended_phases: Type.Array( - Type.Object({ - phase: Type.String({ description: "EpicPhase identifier, e.g. 'core-flows'" }), - label: Type.String({ description: "Human-readable label, e.g. 'Define Core Flows'" }), - context: Type.String({ description: "Why this phase is useful right now" }), - recommended: Type.Optional(Type.Boolean({ description: "True for the most-recommended option" })), - }), - { description: "Phase options to present to the user, in recommendation order" }, - ), -}); - -type ProposeWorkflowParams = Static; - -const PROPOSE_WORKFLOW_DESCRIPTION = ` -Present workflow phase options to the user for direction on what to do next. - -After a phase completes, call this tool to show the user: -- A status report of what was accomplished -- Available next phases with context on why each is useful - -The user's response (free-form text) is returned. You may call this tool -multiple times if the user provides feedback rather than a clear direction. -Only call koan_set_next_phase once you understand their intent. -`.trim(); - -export async function executeProposeWorkflow( - params: ProposeWorkflowParams, - subagentDir: string | null, - signal?: AbortSignal | null, -): Promise { - if (!subagentDir) { - return { - content: [{ type: "text" as const, text: "Error: koan_propose_workflow is only available in subagent context." }], - details: undefined, - }; - } - - if (await ipcFileExists(subagentDir)) { - return { - content: [{ type: "text" as const, text: "Error: An IPC request is already pending. Wait for it to be resolved before calling again." }], - details: undefined, - }; - } - - // Read completedPhase from task.json for UI context. - let completedPhase = "unknown"; - try { - const task = await readTaskFile(subagentDir); - if (task.role === "workflow-orchestrator") { - completedPhase = (task as WorkflowOrchestratorTask).completedPhase; - } - } catch { - // Non-fatal — completedPhase is for UI context only - } - - const ipc = createWorkflowDecisionRequest({ - statusReport: params.status_report, - recommendedPhases: params.recommended_phases, - completedPhase, - }); - await writeIpcFile(subagentDir, ipc); - - const { outcome, ipc: answeredIpc } = await pollIpcUntilResponse(subagentDir, ipc, signal); - - switch (outcome) { - case "answered": { - const workflowIpc = answeredIpc as WorkflowDecisionIpcFile; - const feedback = workflowIpc.response?.feedback || "(no response)"; - return { - content: [{ type: "text" as const, text: `User response:\n\n${feedback}` }], - details: undefined, - }; - } - case "aborted": - return { - content: [{ type: "text" as const, text: "The workflow decision was aborted." }], - details: undefined, - }; - case "file-gone": - default: - return { - content: [{ type: "text" as const, text: "The workflow decision was cancelled." }], - details: undefined, - }; - } -} - -// --------------------------------------------------------------------------- -// koan_set_next_phase -// --------------------------------------------------------------------------- - -const SetNextPhaseSchema = Type.Object({ - phase: Type.String({ - description: "The EpicPhase identifier to transition to, e.g. 'core-flows'. Must be one of the available phases from your task manifest.", - }), - instructions: Type.Optional(Type.String({ - description: "Optional context or focus instructions for the next phase. E.g. 'Focus on auth requirements'. Surfaced to the next phase's LLM in step 1 guidance.", - })), -}); - -type SetNextPhaseParams = Static; - -const SET_NEXT_PHASE_DESCRIPTION = ` -Commit the next phase transition decision. - -Call this after koan_propose_workflow to record which phase to run next. -The phase must be one of the valid successors listed in your task manifest. - -Optionally include instructions that will be passed to the next phase's LLM -to guide its focus (e.g. "Focus on authentication requirements and OAuth flows"). -`.trim(); - -export async function executeSetNextPhase( - params: SetNextPhaseParams, - subagentDir: string | null, -): Promise { - if (!subagentDir) { - return { - content: [{ type: "text" as const, text: "Error: koan_set_next_phase is only available in subagent context." }], - details: undefined, - }; - } - - // Read availablePhases from task.json (directory-as-contract). - let availablePhases: string[] = []; - try { - const task = await readTaskFile(subagentDir); - if (task.role === "workflow-orchestrator") { - availablePhases = (task as WorkflowOrchestratorTask).availablePhases as string[]; - } - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - return { - content: [{ type: "text" as const, text: `Error: Could not read task manifest: ${msg}` }], - details: undefined, - }; - } - - if (availablePhases.length === 0) { - return { - content: [{ type: "text" as const, text: "Error: No available phases found in task manifest. This is a programming error." }], - details: undefined, - }; - } - - if (!availablePhases.includes(params.phase)) { - return { - content: [{ type: "text" as const, text: - `Error: "${params.phase}" is not a valid next phase. ` + - `Available phases: ${availablePhases.join(", ")}` }], - details: undefined, - }; - } - - // Write workflow-decision.json atomically to subagentDir. - const decision = { - nextPhase: params.phase, - ...(params.instructions ? { instructions: params.instructions } : {}), - decidedAt: new Date().toISOString(), - }; - - const decisionPath = path.join(subagentDir, "workflow-decision.json"); - const tmpPath = path.join(subagentDir, ".workflow-decision.tmp.json"); - await fs.writeFile(tmpPath, `${JSON.stringify(decision, null, 2)}\n`, "utf8"); - await fs.rename(tmpPath, decisionPath); - - const instructionNote = params.instructions - ? `\n\nInstructions for next phase: "${params.instructions}"` - : ""; - - return { - content: [{ type: "text" as const, text: - `Decision committed: transitioning to "${params.phase}".${instructionNote}\n\n` + - `Call koan_complete_step to finalize the workflow orchestrator session.` }], - details: undefined, - }; -} - -// --------------------------------------------------------------------------- -// Tool registration -// --------------------------------------------------------------------------- - -export function registerWorkflowDecisionTools(pi: ExtensionAPI, ctx: RuntimeContext): void { - pi.registerTool({ - name: "koan_propose_workflow", - label: "Propose workflow", - description: PROPOSE_WORKFLOW_DESCRIPTION, - parameters: ProposeWorkflowSchema, - async execute(_toolCallId, params, signal) { - return executeProposeWorkflow(params as ProposeWorkflowParams, ctx.subagentDir, signal); - }, - }); - - pi.registerTool({ - name: "koan_set_next_phase", - label: "Set next phase", - description: SET_NEXT_PHASE_DESCRIPTION, - parameters: SetNextPhaseSchema, - async execute(_toolCallId, params) { - return executeSetNextPhase(params as SetNextPhaseParams, ctx.subagentDir); - }, - }); -} diff --git a/src/planner/tools/workflow.ts b/src/planner/tools/workflow.ts deleted file mode 100644 index e1fb49f..0000000 --- a/src/planner/tools/workflow.ts +++ /dev/null @@ -1,102 +0,0 @@ -// Workflow tool registration: koan_complete_step. -// -// This is the single most critical tool in koan. Every subagent workflow depends -// on it being called — it is the mechanism that keeps a pi -p process alive across -// multiple steps. Without it, the LLM would do one turn of work and exit, because -// pi -p processes terminate as soon as the LLM finishes a turn without a tool call. -// -// The workflow pattern: boot prompt → LLM calls koan_complete_step → receives step 1 -// instructions → does work → calls koan_complete_step → receives step 2 (or "Phase -// complete.") → repeat. The tool name itself is a call to action: "complete the step." -// -// Tools register once at init; execute callbacks read from the mutable -// RuntimeContext at call time, decoupling static registration from phase routing. - -import { Type } from "@sinclair/typebox"; -import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; - -import { createLogger } from "../../utils/logger.js"; -import type { RuntimeContext } from "../lib/runtime-context.js"; - -const log = createLogger("Workflow"); - -// -- Extracted execute logic -- - -export async function executeCompleteStep( - thoughts: string, - onCompleteStep: ((thoughts: string) => Promise) | null, -): Promise<{ content: Array<{ type: "text"; text: string }>; details: undefined }> { - if (!onCompleteStep) { - log("koan_complete_step called with no active phase"); - return { - content: [{ type: "text" as const, text: "No workflow phase is active." }], - details: undefined, - }; - } - const nextPrompt = await onCompleteStep(thoughts); - return { - content: [{ type: "text" as const, text: nextPrompt ?? "Phase complete." }], - details: undefined, - }; -} - -// Registers workflow tools. Called once at init in koan.ts, -// before pi's _buildRuntime() snapshot. Tool execute callbacks read -// from the RuntimeContext at call time — the context is mutable, -// the tool list is not. -// -// Why register all tools unconditionally? Flags are unavailable during -// init (getFlag() returns undefined before _buildRuntime() sets flagValues), -// so conditional registration based on role is impossible. Tools registered -// after _buildRuntime() are invisible to the LLM. -export function registerWorkflowTools( - pi: ExtensionAPI, - ctx: RuntimeContext, -): void { - // -- koan_complete_step -- - // - // INVARIANT: `thoughts` is an ESCAPE HATCH, not a data channel. - // - // Many LLMs cannot produce both text output and a tool call in the same - // response. Without `thoughts`, these models would have no way to do - // chain-of-thought reasoning (working through lists, chain-of-draft, - // evaluating items one-by-one) while still calling koan_complete_step to - // advance the workflow. The parameter gives them a place to write - // intermediate reasoning. Extended thinking / blocks are not - // sufficient: not all models support them, they aren't visible in audit - // logs, and some reasoning patterns work better as explicit text the model - // can reference in subsequent turns. - // - // THE RULE: `thoughts` must NEVER be actively used to capture task output. - // No summaries, no reports, no structured data. Step instructions must NOT - // say "put your findings/analysis in the `thoughts` parameter." The LLM - // may fill `thoughts` with whatever it wants — that's fine — but no prompt - // should instruct it to put specific content there. Task output goes to - // files in the subagent directory: - // - scouts: {subagentDir}/findings.md - // - intake: {subagentDir}/landscape.md - // - others: as defined by step instructions - // The driver/parent reads those files after the subagent exits. - // - // A 500-char prefix of `thoughts` is captured in the audit projection as - // `completionSummary` for UI display — this is incidental, not a contract. - pi.registerTool({ - name: "koan_complete_step", - label: "Complete current workflow step", - description: [ - "Signal completion of the current workflow step.", - "The `thoughts` parameter is for internal chain-of-thought reasoning only — it is NOT captured as task output.", - "Task output must be written to files in your subagent directory (e.g., findings.md for scouts).", - "DO NOT call this tool until the step instructions explicitly tell you to.", - ].join(" "), - parameters: Type.Object({ - thoughts: Type.Optional(Type.String({ - description: "Internal chain-of-thought reasoning only. NOT task output. Write task output to files in your subagent directory.", - })), - }), - async execute(_toolCallId, params) { - const thoughts = (params as { thoughts?: string }).thoughts ?? ""; - return executeCompleteStep(thoughts, ctx.onCompleteStep); - }, - }); -} diff --git a/src/planner/types.ts b/src/planner/types.ts deleted file mode 100644 index ff27607..0000000 --- a/src/planner/types.ts +++ /dev/null @@ -1,81 +0,0 @@ -// Core types for the koan epic/story orchestrator. -// Shared across driver, phases, tools, and spawn infrastructure. - -// No `escalated` status -- see docs/state.md "No escalated status". The orchestrator -// calls `koan_ask_question` when it needs human input, then decides via retry/skip. -// A separate status created a dead routing path — the driver had nowhere clean to -// send it without duplicating the ask UI flow that IPC already handles. -// -// No `scouting` EpicPhase: scouts are spawned inside the IPC responder during -// intake/decomposer/planner phases, not as a top-level driver phase. Adding -// "scouting" to EpicPhase would imply a driver state that never exists. -// If a top-level scouting phase is added later, re-add the value then. -// -// StepSequence exists for the orchestrator, which has two distinct step counts -// depending on where in the story lifecycle it runs: pre-execution (2 steps: -// dependency analysis + select) vs post-execution (4 steps: verify + verdict + -// propagate + select next). A single OrchestratorPhase class reads this value -// in begin() to configure its total steps and guidance functions. -// See docs/subagents.md for orchestrator step sequence details. - -// Subagent roles — all LLM roles in the pipeline. -export type SubagentRole = - | "intake" - | "scout" - | "decomposer" - | "orchestrator" - | "planner" - | "executor" - | "brief-writer" - | "workflow-orchestrator"; - -// Model tiers — maps to three capability levels. -export type ModelTier = "strong" | "standard" | "cheap"; - -// Role → model tier mapping. Scouts use cheap models; execution roles use standard. -export const ROLE_MODEL_TIER: Record = { - intake: "strong", - scout: "cheap", - decomposer: "strong", - "brief-writer": "strong", - orchestrator: "strong", - planner: "strong", - executor: "standard", - "workflow-orchestrator": "strong", -}; - -// Orchestrator step sequences — configures step count and guidance at spawn time. -export type StepSequence = "pre-execution" | "post-execution"; - -// Story lifecycle states. Driver manages intermediate transitions; orchestrator tools -// drive the routing transitions via koan_* tool calls. -export type StoryStatus = - | "pending" // Initial state: not yet selected - | "selected" // Orchestrator selected this story via koan_select_story - | "planning" // Driver-internal: planner subagent is running - | "executing" // Driver-internal: executor subagent is running - | "verifying" // Driver-internal: post-execution orchestrator is running - | "done" // Orchestrator verdict: story completed successfully - | "retry" // Orchestrator verdict: re-execute with failure context - | "skipped"; // Orchestrator or driver: story bypassed (budget exhaustion or explicit skip) - -// Epic lifecycle phases (driver-managed, not LLM-visible directly). -// Eight active phases plus the "completed" terminal marker. -// Note: "scouting" is intentionally absent — scouts run within other phases via IPC. -export type EpicPhase = - | "intake" - | "brief-generation" - | "core-flows" - | "tech-plan" - | "ticket-breakdown" - | "cross-artifact-validation" - | "execution" - | "implementation-validation" - | "completed"; - -// All model tiers as a runtime-iterable array. -export const ALL_MODEL_TIERS: readonly ModelTier[] = ["strong", "standard", "cheap"]; - -export function isModelTier(value: unknown): value is ModelTier { - return typeof value === "string" && ALL_MODEL_TIERS.includes(value as ModelTier); -} diff --git a/src/planner/ui/config/menu.ts b/src/planner/ui/config/menu.ts deleted file mode 100644 index f297c3c..0000000 --- a/src/planner/ui/config/menu.ts +++ /dev/null @@ -1,88 +0,0 @@ -// Koan config menu. Opens a settings-style list with config sections. -// Currently exposes one section: "Model selection". -// New sections can be added here as additional SettingItems. - -import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent"; -import { getSettingsListTheme } from "@mariozechner/pi-coding-agent"; -import { type SettingItem, SettingsList } from "@mariozechner/pi-tui"; - -import { ALL_MODEL_TIERS, type ModelTier } from "../../types.js"; -import { loadModelTierConfig } from "../../model-config.js"; -import type { ModelTierConfig } from "../../model-config.js"; -import { createModelSelectionComponent } from "./model-selection.js"; - -function configSummary(config: ModelTierConfig | null): string { - if (config === null) return "inheriting active model"; - return `${ALL_MODEL_TIERS.length} tiers configured`; -} - -export async function openKoanConfig(ctx: ExtensionCommandContext): Promise { - if (!ctx.hasUI) { - ctx.ui.notify("Koan config requires an interactive terminal.", "warning"); - return; - } - - await ctx.ui.custom(async (tui, theme, _keybindings, done) => { - const initialConfig = await loadModelTierConfig(); - let currentConfig = initialConfig; - - const activeModelId = ctx.model - ? `${ctx.model.provider}/${ctx.model.id}` - : undefined; - - // settingsList is captured in closure; submenu is only invoked after construction. - let settingsList: SettingsList; - - const sectionItems: SettingItem[] = [ - { - id: "model-selection", - label: "Model selection", - currentValue: configSummary(currentConfig), - submenu: (_cv, submenuDone) => { - return createModelSelectionComponent( - tui, - theme, - ctx.modelRegistry, - activeModelId, - currentConfig, - (newConfig) => { - currentConfig = newConfig; - settingsList.updateValue("model-selection", configSummary(newConfig)); - }, - (error) => { - const message = error instanceof Error ? error.message : String(error); - ctx.ui.notify(`Failed to save koan model config: ${message}`, "error"); - }, - () => submenuDone(undefined), - ); - }, - }, - ]; - - const returnItem: SettingItem = { - id: "__return", - label: "Return", - description: "Close /koan config (same as Esc)", - currentValue: "", - values: [""], - }; - - const items: SettingItem[] = [...sectionItems, returnItem]; - - settingsList = new SettingsList( - items, - 20, - getSettingsListTheme(), - (id) => { - if (id === "__return") done(); - }, - () => done(), - ); - - return { - render: (w) => settingsList.render(w), - handleInput: (d) => settingsList.handleInput(d), - invalidate: () => settingsList.invalidate(), - }; - }); -} diff --git a/src/planner/ui/config/model-selection.ts b/src/planner/ui/config/model-selection.ts deleted file mode 100644 index c612f83..0000000 --- a/src/planner/ui/config/model-selection.ts +++ /dev/null @@ -1,205 +0,0 @@ -// Model selection UI for /koan config. -// Renders a 3-row tier table (strong / standard / cheap). -// Enter opens an inline ModelSelectorComponent for the selected tier. -// Uses SettingsManager.inMemory() to prevent global default model mutation. - -import { ModelSelectorComponent, SettingsManager } from "@mariozechner/pi-coding-agent"; -import type { Theme } from "@mariozechner/pi-coding-agent"; -import type { ModelRegistry } from "@mariozechner/pi-coding-agent"; -import { - type Component, - type TUI, - getEditorKeybindings, - truncateToWidth, - visibleWidth, -} from "@mariozechner/pi-tui"; - -import { ALL_MODEL_TIERS, type ModelTier } from "../../types.js"; -import { saveModelTierConfig } from "../../model-config.js"; -import type { ModelTierConfig } from "../../model-config.js"; - -function padRight(text: string, width: number): string { - const padding = Math.max(0, width - visibleWidth(text)); - return text + " ".repeat(padding); -} - -function renderCell(theme: Theme, text: string, width: number, selected: boolean): string { - const innerWidth = Math.max(1, width - 2); - const clipped = truncateToWidth(text, innerWidth, ""); - const padded = padRight(clipped, innerWidth); - const raw = ` ${padded} `; - if (selected) return theme.inverse(raw); - return raw; -} - -function cellDisplay(modelId: string | undefined, activeModelId: string | undefined): string { - if (modelId === undefined) { - return activeModelId ? `inherit:${activeModelId}` : "inherit:active"; - } - return modelId; -} - -export function createModelSelectionComponent( - tui: TUI, - theme: Theme, - modelRegistry: ModelRegistry, - activeModelId: string | undefined, - initialConfig: ModelTierConfig | null, - onConfigChange: (newConfig: ModelTierConfig | null) => void, - onSaveError: (error: unknown) => void, - onClose: () => void, -): Component { - const fallbackActive = activeModelId ?? "(active model)"; - const configRef: { value: ModelTierConfig | null } = { value: initialConfig }; - - let rowIndex = 0; - let overlay: Component | null = null; - - function requestRender(): void { - tui.requestRender(); - } - - async function persistAndNotify(newConfig: ModelTierConfig | null): Promise { - const previous = configRef.value; - try { - await saveModelTierConfig(newConfig as ModelTierConfig); - configRef.value = newConfig; - onConfigChange(newConfig); - return true; - } catch (error) { - configRef.value = previous; - onSaveError(error); - return false; - } - } - - function makeModelSelector( - currentModelId: string | undefined, - onSelect: (modelId: string) => void, - onCancel: () => void, - ): Component { - const available = modelRegistry.getAvailable(); - const currentModel = currentModelId - ? available.find((m) => `${m.provider}/${m.id}` === currentModelId) - : available.find((m) => `${m.provider}/${m.id}` === activeModelId); - - const sm = SettingsManager.inMemory(); - - return new ModelSelectorComponent( - tui, - currentModel, - sm, - modelRegistry, - [], - (model) => onSelect(`${model.provider}/${model.id}`), - onCancel, - ); - } - - function closeOverlay(): void { - overlay = null; - requestRender(); - } - - function openTierSelector(): void { - const tier = ALL_MODEL_TIERS[rowIndex] as ModelTier; - const currentId = configRef.value?.[tier]; - - overlay = makeModelSelector( - currentId, - (modelId) => { - const base: ModelTierConfig = configRef.value ?? { - strong: fallbackActive, - standard: fallbackActive, - cheap: fallbackActive, - }; - const newConfig: ModelTierConfig = { ...base, [tier]: modelId }; - void persistAndNotify(newConfig).finally(() => closeOverlay()); - }, - () => closeOverlay(), - ); - requestRender(); - } - - function moveUp(): void { - if (rowIndex > 0) rowIndex -= 1; - } - - function moveDown(): void { - if (rowIndex < ALL_MODEL_TIERS.length - 1) rowIndex += 1; - } - - function renderMain(width: number): string[] { - const lines: string[] = []; - - lines.push(theme.bold(theme.fg("accent", "Koan / Config / Model selection"))); - lines.push(theme.fg("muted", `Fallback active model: ${fallbackActive}`)); - lines.push(""); - - const tierColWidth = 12; - const sep = " | "; - const sepWidth = visibleWidth(sep); - const modelColWidth = Math.max(20, width - tierColWidth - sepWidth); - - const headerCells = [ - renderCell(theme, "tier", tierColWidth, false), - renderCell(theme, "model", modelColWidth, false), - ]; - lines.push(headerCells.join(sep)); - lines.push("-".repeat(Math.max(10, Math.min(width, visibleWidth(headerCells.join(sep)))))); - - for (let r = 0; r < ALL_MODEL_TIERS.length; r += 1) { - const tier = ALL_MODEL_TIERS[r] as ModelTier; - const model = configRef.value?.[tier]; - const display = cellDisplay(model, activeModelId); - const selected = rowIndex === r; - - const row = [ - renderCell(theme, tier, tierColWidth, false), - renderCell(theme, display, modelColWidth, selected), - ]; - lines.push(truncateToWidth(row.join(sep), width)); - } - - lines.push(""); - lines.push(theme.fg("dim", "↑↓ move row · Enter select model · Esc back")); - - return lines; - } - - return { - render: (width) => { - if (overlay) return overlay.render(width); - return renderMain(width); - }, - handleInput: (data) => { - if (overlay) { - overlay.handleInput?.(data); - return; - } - - const kb = getEditorKeybindings(); - - if (kb.matches(data, "selectCancel")) { - onClose(); - return; - } - if (kb.matches(data, "selectConfirm") || data === " ") { - openTierSelector(); - return; - } - if (kb.matches(data, "selectUp")) { - moveUp(); - requestRender(); - return; - } - if (kb.matches(data, "selectDown")) { - moveDown(); - requestRender(); - } - }, - invalidate: () => { - overlay?.invalidate?.(); - }, - }; -} diff --git a/src/planner/web/ARCHITECTURE.md b/src/planner/web/ARCHITECTURE.md deleted file mode 100644 index 6d41431..0000000 --- a/src/planner/web/ARCHITECTURE.md +++ /dev/null @@ -1,199 +0,0 @@ -# Web UI Architecture - -Single-page dashboard served by `server.ts`. Pushes state via SSE; receives -user input via POST. Built with Preact + Zustand — see -`plans/2026-03-16-preact-zustand-rewrite.md` for the full decision record. - ---- - -## Directory layout - -``` -server.ts HTTP server, SSE push, WebServerHandle API -server-types.ts Shared TypeScript types -html/index.html Shell —
+ module script, no static skeleton -css/ Four stylesheets (variables, layout, components, animations) -dist/app.js Compiled bundle — generated, not committed -js/ - app.jsx Entry: render(), connectSSE(), heartbeat interval - store.js Zustand store (single source of truth) - sse.js SSE connection + store updates - lib/utils.js formatTokens, formatElapsed, shortenModel - lib/api.js submitAnswers (fetch wrapper) - components/ Preact component tree (see Component tree below) -``` - ---- - -## Build pipeline - -esbuild compiles `js/app.jsx` and all imports into `dist/app.js` (single ESM -bundle, ~44KB raw / ~16KB gzip). - -**The alias flags are mandatory.** zustand v4 imports from `react` internally. -Without aliasing, esbuild bundles the full React 19 runtime alongside Preact — -two competing VDOM reconcilers that cannot share a hook dispatcher. The aliases -redirect those imports to `preact/compat`: - -``` ---alias:react=preact/compat --alias:react-dom=preact/compat -``` - -These appear in both the npm script (`build:web`) and in the `esbuild.build()` -call inside `ensureBundle()` in `server.ts`. If you add them to one, add them -to both. - -**On-demand build:** `ensureBundle()` in `server.ts` runs at the top of -`startWebServer()`. It stats `dist/app.js` against the newest file in `js/` -and rebuilds only when stale. Adds ~100ms on first start; skips on subsequent -starts. No manual build step is needed during development. - -**CI/test path:** `npm run build` runs `build:web` then `tsc`. The tsc step -does not process JSX; it type-checks the TypeScript source only. - -**zustand version:** Pinned to v4 (`^4.5.7`). zustand v5 moved its default -export to `zustand/react`, which imports React at module level and breaks -the esbuild bundle even with the alias. - ---- - -## Data flow - -``` -server.ts ──SSE──► sse.js ──setState──► Zustand store ──selector──► components - │ -user action ◄──fetch── lib/api.js ◄──────────────────────────┘ -``` - -1. `server.ts` pushes SSE events on a 50ms polling tick. -2. `sse.js` registers one `addEventListener` per event type. Each handler - calls `useStore.setState()` — the static method, callable outside - component context. -3. Components subscribe via `useStore(s => s.slice)`. Zustand shallow-merges - `setState` calls and notifies only subscribers whose selected slice changed. -4. User actions (form submit, heartbeat) call `lib/api.js` fetch wrappers - which POST to `/api/answer`, `/api/workflow-decision`, or `/api/heartbeat`. - -`pendingInput` is cleared by the server: a phase transition out of `intake` -clears it in the `phase` handler; `ask-cancelled` / `workflow-decision-cancelled` clear -it by request ID. `intakeProgress` is cleared when the phase transitions away -from intake or when the pipeline ends. - ---- - -## Component tree - -``` -App -├── Header -│ ├── PillStrip reads phase for active/done pill state -│ └── ⚙ settings btn -│ -├── (isInteractive) main.main-panel -│ └── PhaseContent dispatch hub (see below) -│ -├── (live) div.live-layout ← sidebar + feed row -│ ├── StatusSidebar agent identity + phase status + summary -│ └── div.live-main -│ └── main.main-panel -│ └── ActivityFeed reads logs, currentToolCallId -│ -├── AgentMonitor reads agents (hides when none active) -└── Notifications reads notifications; auto-dismisses via useEffect -``` - -**App layout modes:** - -`isInteractive = !phase || pendingInput || showSettings || phase === 'completed'` - -- **Interactive mode** — `PhaseContent` fills the scrollable area. Used for forms, - loading screen, settings overlay, and completion. -- **Live mode** — `StatusSidebar` sits in the left column (`clamp(240px, 20vw, 300px)`), - `ActivityFeed` fills the right column. The parent `.app` container handles - centering — no per-mode centering needed. - -**PhaseContent dispatch order:** - -1. `showSettings` → `` -2. `pending.type === 'model-config'` → `` -3. `!phase` → `` -4. `pending.type === 'ask'` → `` -5. `phase === 'completed'` → `` -6. default → `null` (live mode renders the ActivityFeed instead) - -`key={requestId}` on forms forces a full remount when a new request arrives, -resetting local selection state without any explicit cleanup. - ---- - -## StatusSidebar - -The `StatusSidebar` renders phase-specific context in the left column during -live mode. It reads four store slices: `phase` (visibility gate and content -dispatch), `subagent` (agent identity section), `intakeProgress` -(intake-specific data), and `stories` (decomposition and execution progress). - -**Visibility:** The sidebar renders whenever `phase` is non-null — not gated on -`subagent`. This means phase status (story progress, etc.) remains visible -during brief gaps between subagent spawns. The agent identity section is -omitted when `subagent` is null. - -**Agent identity section** (top, when `subagent` is non-null): -- Role (uppercase, blue, mono) + shortened model name (muted) on one line -- Step label from `subagent.stepName` or `Step N/M` on the next line -- Token counts (↑sent ↓recv) + elapsed timer on the third line -- Elapsed time is computed inline via `useState` + `useEffect` 1-second - interval from `subagent.startedAt`, using `formatElapsed` from `lib/utils.js` - -**Phase-specific sections** (middle): - -- **intake** + `intakeProgress` → `IntakeStatus`: confidence meter (5 segments), - iteration dots (4 rounds), sub-phase label, summary text per sub-phase -- **brief-generation** → `BriefStatus`: static "Drafting epic brief…" label -- **stub phases** (`core-flows`, `tech-plan`, etc.) → `GenericStatus`: phase label + "Phase in progress…" -- **fallback** → `GenericStatus`: phase label + "Phase in progress…" - -**Summary section** (bottom, below divider): static contextual message per phase. - ---- - -## intake-progress SSE event - -`IntakeProgressEvent { subPhase, intakeDone, confidence, iteration }` is pushed -from the server's 50ms agent-polling tick whenever the intake agent's projection -changes. The full pipeline: - -``` -LLM calls koan_set_confidence - → ctx.intakeConfidence set - → confidence_change appended to events.jsonl - → fold() updates state.json projection - → server polls state.json (50ms) → detects change - → pushes intake-progress SSE event - → sse.js: set({ intakeProgress: d }) - → StatusSidebar re-renders with new confidence/iteration -``` - -The event is replayed in `replayState()` on SSE reconnect so the sidebar -recovers its state after a network drop. - ---- - -## Server-side changes - -**`ensureBundle()`** — async function before `startWebServer()` body. Uses -esbuild JS API via dynamic `await import("esbuild")`. `STATIC_ASSETS` is -constructed inside `startWebServer()` after this call completes. - ---- - -## Conventions - -| Convention | Rule | -|---|---| -| JSX attribute | `class`, not `className` (Preact uses HTML attribute names) | -| Hook imports | `import { useState, useEffect } from 'preact/hooks'` | -| Render import | `import { render } from 'preact'` (not `preact/compat`) | -| External setState | `useStore.setState(...)` — static method, works outside components | -| Fragment syntax | `<>…` — works because build uses `--jsx=automatic` | -| Zustand merge | `setState` merges shallowly; always replace the full slice, never mutate nested objects | diff --git a/src/planner/web/css/animations.css b/src/planner/web/css/animations.css deleted file mode 100644 index e3f945c..0000000 --- a/src/planner/web/css/animations.css +++ /dev/null @@ -1,76 +0,0 @@ -/* Phase content crossfade */ -@keyframes fade-in { - from { opacity: 0; } - to { opacity: 1; } -} - -.phase-content .phase-inner { - animation: fade-in 250ms ease-out; -} - -/* Sliding text input for "Other" option */ -@keyframes slide-open { - from { max-height: 0; opacity: 0; } - to { max-height: 80px; opacity: 1; } -} - -/* Pill state transitions */ -.pill { - transition: background 200ms ease, color 200ms ease, border-color 200ms ease; -} - -/* Notification fade-out */ -.notification.fade-out { - animation: fade-out 300ms ease-in forwards; -} - -@keyframes fade-out { - from { opacity: 1; transform: translateY(0); } - to { opacity: 0; transform: translateY(8px); } -} - -/* Thinking indicator */ -@keyframes thinking-pulse { - 0%, 100% { opacity: 0.3; } - 50% { opacity: 1; } -} - -.thinking-dot { - animation: thinking-pulse 1.5s ease-in-out infinite; -} - -.thinking-timer { - color: var(--text-muted); - font-variant-numeric: tabular-nums; - margin-left: 0.4em; -} - -/* Streaming cursor — pulsing bar at the end of streaming text */ -.streaming-cursor { - display: inline-block; - width: 6px; - height: 14px; - background: var(--copper); - border-radius: 1px; - vertical-align: text-bottom; - margin-left: 2px; - animation: cursor-blink 1s step-end infinite; -} - -@keyframes cursor-blink { - 0%, 100% { opacity: 1; } - 50% { opacity: 0; } -} - -.agent-doing-thinking { - color: var(--text-muted); -} - -/* Pulsing dot — replaces spinner for loading states */ -.loading-dot { - width: 12px; - height: 12px; - border-radius: 50%; - background: var(--copper); - animation: thinking-pulse 1.5s ease-in-out infinite; -} diff --git a/src/planner/web/css/components.css b/src/planner/web/css/components.css deleted file mode 100644 index b32c6a9..0000000 --- a/src/planner/web/css/components.css +++ /dev/null @@ -1,1087 +0,0 @@ -/* ---- Pill strip ---- */ -.pill-strip { - display: flex; - border-radius: var(--radius-md); - overflow: hidden; - border: 1px solid var(--border); -} - -.pill { - font-family: var(--font-sans); - font-size: var(--font-size-sm); - padding: 6px 16px; - border-right: 1px solid var(--border); - color: var(--text-ghost); - background: var(--bg); - transition: background 150ms, color 150ms; - white-space: nowrap; -} - -.pill:last-child { - border-right: none; -} - -.pill.active { - background: var(--copper); - color: #fff; - border-color: var(--copper); -} - -.pill.done { - background: var(--green); - color: #fff; - border-color: var(--green); -} - -.pill.done::before { - content: "✓ "; -} - -.pill.active::before { - content: "● "; -} - -/* ---- Badges ---- */ -.badge { - font-family: var(--font-mono); - font-size: var(--font-size-xs); - padding: 5px 14px; - border-radius: var(--radius-md); - font-weight: 600; -} - -.badge.done { background: var(--green-bg); color: var(--green); } -.badge.active { background: var(--copper-bg); color: var(--copper); } -.badge.failed { background: var(--red-bg); color: var(--red); } - -/* ---- Agent table ---- */ -.agent-table { - width: 100%; - border-collapse: collapse; - table-layout: fixed; - font-size: var(--font-size-sm); -} - -.agent-table th { - font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--text-muted); - text-transform: uppercase; - letter-spacing: 0.06em; - padding: 4px 8px; - text-align: left; - border-bottom: 1px solid var(--border); -} - -.agent-table td { - padding: 8px; - vertical-align: top; - border-bottom: 1px solid var(--border); -} - -.col-status { width: 28px; text-align: center; } -.col-agent { width: 170px; } -.col-model { width: 170px; } -.col-tokens { width: 70px; text-align: right; } -.col-time { width: 70px; text-align: right; } -.col-doing { /* takes remaining */ } - -.agent-table td, -.agent-table th { - overflow: hidden; - text-overflow: ellipsis; - white-space: nowrap; -} - -.agent-table td.col-doing { - white-space: normal; -} - -.agent-status-queued { color: var(--text-muted); } -.agent-status-running { color: var(--copper); } -.agent-status-done { color: var(--green); font-weight: 600; } -.agent-status-failed { color: var(--red); } - -.agent-name-queued { color: var(--text-muted); font-family: var(--font-mono); } -.agent-name-running { color: var(--text); font-weight: 600; font-family: var(--font-mono); } -.agent-name-done { color: var(--green); font-family: var(--font-mono); } -.agent-name-failed { color: var(--red); font-family: var(--font-mono); } - -.agent-model-cell { font-family: var(--font-mono); color: var(--text-muted); } -.agent-tokens-cell { font-family: var(--font-mono); color: var(--text-muted); } -.agent-time-cell { font-family: var(--font-mono); color: var(--text-muted); } -.agent-timer { font-size: var(--font-size-xs); } - -.agent-doing-dim { font-family: var(--font-mono); font-size: var(--font-size-xs); color: var(--text-muted); } -.agent-doing-failed { color: var(--red); } - -.agent-doing-lines { - display: flex; - flex-direction: column; - gap: 1px; -} - -.agent-doing-line { - font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--text-muted); - white-space: nowrap; - overflow: hidden; - text-overflow: ellipsis; -} - -.agent-doing-line:last-child { - color: var(--text); -} - -/* ---- Card ---- */ -.card { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-6); - margin-bottom: var(--space-4); -} - -.card.card-running { - border-left: 3px solid var(--copper); -} - -.card.card-done { - background: var(--green-bg); - border-color: var(--green-border); -} - -.card.card-failed { - background: var(--red-bg); - border-color: var(--red-border); -} - -.card-header { - display: flex; - align-items: center; - gap: var(--space-2); - margin-bottom: var(--space-2); -} - -.card-title { - font-family: var(--font-sans); - font-weight: 700; - font-size: var(--font-size-lg); - color: var(--text-strong); -} - -.card-role { - margin-left: auto; - font-family: var(--font-mono); - font-size: var(--font-size-sm); - color: var(--text-muted); -} - -.card-body { - font-family: var(--font-sans); - font-size: var(--font-size-lg); - color: var(--text-muted); - line-height: 1.6; -} - -/* ---- Question cards ---- */ -.question-card { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-6); - margin-bottom: var(--space-4); -} - -.question-header { - font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--text-muted); - text-transform: uppercase; - letter-spacing: 0.06em; - margin-bottom: var(--space-2); -} - -.question-context { - font-family: var(--font-sans); - font-size: var(--font-size-md); - color: var(--text-muted); - line-height: 1.6; - margin-bottom: var(--space-4); -} - -.question-context p { - margin: 0 0 var(--space-2) 0; -} - -.question-context p:last-child { - margin-bottom: 0; -} - -.question-context code, -.question-text code, -.option-text code { - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - padding: 1px 5px; - font-family: var(--font-mono); - font-size: 0.9em; -} - -.question-context strong, -.question-text strong, -.option-text strong { - color: var(--text-strong); - font-weight: 600; -} - -.question-context a, -.question-text a, -.option-text a { - color: var(--copper); - text-decoration: underline; -} - -.question-context ul, -.question-context ol { - padding-left: var(--space-6); - margin: var(--space-2) 0; -} - -.question-context li { - margin: 2px 0; -} - -.question-text { - font-family: var(--font-sans); - font-size: 18px; - font-weight: 500; - color: var(--text-strong); - margin-bottom: var(--space-4); - line-height: 1.6; -} - -.question-multi-hint { - font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--copper); - margin-bottom: var(--space-2); -} - -.options-list { - display: flex; - flex-direction: column; - gap: var(--space-1); -} - -.option { - display: flex; - align-items: flex-start; - gap: var(--space-2); - padding: var(--space-2) var(--space-4); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - background: var(--bg); - cursor: pointer; - transition: border-color 100ms, background 100ms; - user-select: none; -} - -.option:hover { - border-color: var(--text-muted); -} - -.option.selected { - border-color: var(--copper-border); - background: var(--copper-bg); -} - -.option-other { - border-style: dashed; -} - -.radio-dot, .checkbox-dot { - width: 14px; - height: 14px; - border: 2px solid var(--text-ghost); - border-radius: 50%; - flex-shrink: 0; - margin-top: 2px; - transition: border-color 100ms, background 100ms; -} - -.checkbox-dot { - border-radius: 3px; -} - -.option.selected .radio-dot, -.option.selected .checkbox-dot { - border-color: var(--copper); - background: var(--copper); -} - -.option.selected .checkbox-dot::after { - content: "✓"; - display: block; - color: #fff; - font-size: 9px; - text-align: center; - line-height: 10px; -} - -.option-text { - font-family: var(--font-sans); - font-size: var(--font-size-lg); - color: var(--text); - flex: 1; -} - -.option-other .option-text { - color: var(--text-muted); -} - -.recommended-badge { - font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--copper); - margin-left: auto; - white-space: nowrap; -} - -.other-input { - display: none; - width: 100%; - margin-top: var(--space-2); - padding: var(--space-2); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); - font-family: var(--font-sans); - font-size: var(--font-size-md); - outline: none; -} - -.other-input:focus { - border-color: var(--copper); -} - -.other-input.visible { - display: block; - animation: slide-open 150ms ease-out; -} - -/* ---- Config sections ---- */ -.model-config-section { - margin-top: var(--space-6); -} - -.model-config-section-heading { - font-size: var(--font-size-lg); - font-weight: 600; - color: var(--text-strong); - margin: 0 0 var(--space-1) 0; -} - -.scout-concurrency-input { - width: 80px; - padding: var(--space-2) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); - font-family: var(--font-mono); - font-size: var(--font-size-md); -} - -.scout-concurrency-input:focus { - border-color: var(--copper); - outline: none; -} - -/* ---- Form actions ---- */ -.form-actions { - display: flex; - gap: var(--space-4); - margin-top: var(--space-6); - align-items: center; -} - -.form-helper { - font-family: var(--font-mono); - font-size: var(--font-size-sm); - color: var(--text-muted); - margin-left: auto; -} - -.btn { - padding: 12px 24px; - border-radius: var(--radius-sm); - font-size: var(--font-size-md); - font-family: var(--font-sans); - cursor: pointer; - border: 1px solid transparent; - transition: opacity 100ms; -} - -.btn:disabled { - opacity: 0.5; - cursor: not-allowed; -} - -.btn-primary { - background: var(--green); - color: #fff; - border-color: var(--green); -} - -.btn-secondary { - background: transparent; - color: var(--text); - border-color: var(--border-strong); -} - -/* ---- Topic card ---- */ -.topic-card { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-4) var(--space-6); - margin-top: var(--space-4); - max-width: 640px; -} - -.topic-label { - font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--text-muted); - text-transform: uppercase; - letter-spacing: 0.08em; - margin-bottom: var(--space-1); -} - -.topic-text { - font-family: var(--font-sans); - font-size: var(--font-size-lg); - color: var(--text); - font-style: italic; - line-height: 1.6; -} - -/* ---- Activity feed (context analysis) ---- */ -.activity-feed { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-4); - margin-top: var(--space-4); -} - -.activity-line { - display: flex; - gap: var(--space-2); - font-family: var(--font-mono); - font-size: var(--font-size-md); - color: var(--text-muted); - padding: 3px 0; -} - -.activity-tool { - color: var(--copper); - min-width: 60px; -} - -/* ---- Phase status messages ---- */ -.phase-status { - font-family: var(--font-sans); - font-size: var(--font-size-lg); - color: var(--text); - margin-bottom: var(--space-4); -} - -.phase-heading { - font-family: var(--font-sans); - font-size: 22px; - font-weight: 600; - color: var(--text-strong); - margin-bottom: var(--space-4); -} - -/* ---- Summary checklist ---- */ -.summary-list { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-4) var(--space-6); -} - -.summary-item { - display: flex; - align-items: center; - gap: var(--space-4); - padding: 4px 0; - font-family: var(--font-sans); - font-size: var(--font-size-md); -} - -.summary-item .icon-done { color: var(--green); } -.summary-item .icon-pending { color: var(--text-muted); } - -/* ---- Notification toasts ---- */ -#notifications { - position: fixed; - bottom: var(--space-6); - right: var(--space-6); - display: flex; - flex-direction: column; - gap: var(--space-2); - z-index: 200; -} - -.notification { - padding: var(--space-2) var(--space-4); - border-radius: var(--radius-md); - font-family: var(--font-sans); - font-size: var(--font-size-md); - color: #fff; - animation: fade-in 150ms ease-out; -} - -.notification.info { background: var(--copper); } -.notification.warning { background: var(--ochre); } -.notification.error { background: var(--red); } - -/* ---- Count progress indicator ---- */ -.count-progress { - font-family: var(--font-mono); - font-size: var(--font-size-sm); - color: var(--text-muted); - margin-bottom: var(--space-4); -} - -/* ---- Context so far section ---- */ -.context-section-label { - font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--text-muted); - text-transform: uppercase; - letter-spacing: 0.08em; - margin: var(--space-4) 0 var(--space-2); -} - -.context-items { - list-style: none; - padding: 0; - margin: 0; -} - -.context-items li { - padding: 3px 0; - font-family: var(--font-sans); - font-size: var(--font-size-md); - color: var(--text-muted); -} - -.context-items li::before { - content: "• "; - color: var(--green); -} - -/* ---- Model config ---- */ -.model-config-tiers { - display: flex; - flex-direction: column; - gap: var(--space-4); - margin-top: var(--space-4); - margin-bottom: var(--space-6); -} - -.model-tier-row { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-4) var(--space-6); -} - -.model-tier-header { - display: flex; - align-items: center; - gap: var(--space-2); - margin-bottom: var(--space-1); -} - -.model-tier-label { - font-family: var(--font-mono); - font-size: var(--font-size-lg); - font-weight: 700; - color: var(--text-strong); - text-transform: uppercase; - letter-spacing: 0.06em; -} - -.model-tier-description { - font-family: var(--font-sans); - font-size: var(--font-size-md); - color: var(--text-muted); - line-height: 1.6; - margin: 0 0 var(--space-4); -} - -.model-tier-input { - width: 100%; - padding: var(--space-2) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); - font-family: var(--font-mono); - font-size: var(--font-size-md); - outline: none; - box-sizing: border-box; -} - -.model-tier-input:focus { - border-color: var(--copper); -} - -.model-tier-input::placeholder { - color: var(--text-muted); - font-style: italic; -} - -.model-tier-select { - width: 100%; - padding: var(--space-2) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); - font-family: var(--font-mono); - font-size: var(--font-size-md); - outline: none; - box-sizing: border-box; - cursor: pointer; - -webkit-appearance: none; - appearance: none; - background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8'%3E%3Cpath d='M1 1l5 5 5-5' stroke='%23957E68' stroke-width='1.5' fill='none'/%3E%3C/svg%3E"); - background-repeat: no-repeat; - background-position: right 12px center; - padding-right: 36px; -} - -.model-tier-select:focus { - border-color: var(--copper); -} - -.model-tier-select option { - background: var(--bg-surface); - color: var(--text); -} - -.model-tier-select optgroup { - color: var(--text-muted); - font-style: normal; -} - -.model-config-warning { - font-family: var(--font-sans); - font-size: var(--font-size-sm); - color: var(--red); - margin-bottom: var(--space-4); -} - -/* ---- Settings button ---- */ -.header-right { - display: flex; - align-items: center; - gap: var(--space-4); -} - -.settings-btn { - background: none; - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text-muted); - font-size: 16px; - padding: 4px 8px; - cursor: pointer; - transition: color 150ms, border-color 150ms; - line-height: 1; -} - -.settings-btn:hover { - color: var(--text-strong); - border-color: var(--text-muted); -} - -/* ---- Activity feed: in-flight + flash ---- */ -@keyframes result-flash { - 0% { background: rgba(78, 122, 66, 0.12); } - 100% { background: transparent; } -} - -.activity-inflight .activity-summary { - color: var(--ochre); -} - -.activity-flash { - animation: result-flash 400ms ease-out; - border-radius: 3px; -} - -.activity-dots { - display: inline-block; - overflow: hidden; - vertical-align: bottom; - animation: dots-anim 1.5s steps(4, end) infinite; - width: 0; - max-width: 18px; -} - -@keyframes dots-anim { - 0% { width: 0; } - 100% { width: 18px; } -} - -/* ---- Agent row: spinner prefix dots ---- */ -@keyframes pulse-dot { - 0%, 100% { opacity: 0.3; } - 50% { opacity: 1; } -} - -.agent-doing-prefix { - display: inline-block; - width: 12px; - text-align: center; - margin-right: 4px; - flex-shrink: 0; -} - -.prefix-done { - color: var(--green); -} - -.prefix-active { - color: var(--copper); - animation: pulse-dot 1s ease-in-out infinite; -} - -.agent-doing-inflight { - color: var(--text) !important; -} - -/* ---- Artifact review ---- */ -.artifact-review-content { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-6); - overflow-y: auto; - max-height: 60vh; - margin-bottom: var(--space-4); - font-family: var(--font-sans); - font-size: var(--font-size-md); - line-height: 1.7; - color: var(--text); -} - -.artifact-review-content h1, -.artifact-review-content h2, -.artifact-review-content h3, -.artifact-review-content h4 { - color: var(--text-strong); - margin-top: var(--space-4); - margin-bottom: var(--space-2); -} - -.artifact-review-content h1 { font-size: 1.4em; } -.artifact-review-content h2 { font-size: 1.2em; border-bottom: 1px solid var(--border); padding-bottom: 4px; } -.artifact-review-content h3 { font-size: 1.05em; } - -.artifact-review-content p { margin: var(--space-2) 0; } - -.artifact-review-content ul, -.artifact-review-content ol { - padding-left: var(--space-6); - margin: var(--space-2) 0; -} - -.artifact-review-content li { margin: 2px 0; } - -.artifact-review-content code { - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - padding: 1px 5px; - font-family: var(--font-mono); - font-size: 0.9em; -} - -.artifact-review-content pre { - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - padding: var(--space-4); - overflow-x: auto; - margin: var(--space-2) 0; -} - -.artifact-review-content pre code { - background: none; - border: none; - padding: 0; - font-size: var(--font-size-sm); -} - -.artifact-review-content blockquote { - border-left: 3px solid var(--border); - padding-left: var(--space-4); - color: var(--text-muted); - margin: var(--space-2) 0; -} - -.artifact-review-content strong { color: var(--text-strong); } - -.artifact-review-content a { - color: var(--copper); - text-decoration: underline; -} - -.artifact-review-feedback { - width: 100%; - min-height: 80px; - padding: var(--space-2) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); - font-family: var(--font-sans); - font-size: var(--font-size-md); - resize: vertical; - outline: none; - box-sizing: border-box; - margin-bottom: var(--space-4); -} - -.artifact-review-feedback:focus { - border-color: var(--copper); -} - -.artifact-review-feedback::placeholder { - color: var(--text-muted); - font-style: italic; -} - -/* ---- Workflow orchestrator: frozen activity zone ---- */ -.activity-frozen { - opacity: 0.45; - pointer-events: none; -} - -/* ---- Workflow orchestrator: session separator ---- */ -.workflow-separator { - display: flex; - align-items: center; - margin: var(--space-4) 0; - gap: var(--space-2); - color: var(--text-muted); - font-size: var(--font-size-xs); -} - -.workflow-separator::before, -.workflow-separator::after { - content: ''; - flex: 1; - height: 1px; - background: var(--border); -} - -.workflow-separator-label { - font-family: var(--font-mono); - white-space: nowrap; - padding: 0 var(--space-2); -} - -/* ---- Workflow chat ---- */ -.workflow-chat { - margin-top: var(--space-4); - border-top: 1px solid var(--border); - padding-top: var(--space-4); - display: flex; - flex-direction: column; - gap: var(--space-4); -} - -.workflow-turn { - display: flex; - flex-direction: column; - gap: var(--space-1); -} - -.workflow-turn-orchestrator { - background: var(--bg-surface); - border: 1px solid var(--border); - border-radius: var(--radius-md); - padding: var(--space-2) var(--space-4); -} - -.workflow-turn-header { - display: flex; - align-items: center; - margin-bottom: var(--space-1); -} - -.workflow-turn-role { - font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--plum); - font-weight: 600; - text-transform: uppercase; - letter-spacing: 0.05em; -} - -.workflow-turn-body { - font-size: var(--font-size-sm); - line-height: 1.6; - color: var(--text); -} - -.workflow-turn-body p { margin: 0 0 var(--space-1) 0; } -.workflow-turn-body p:last-child { margin-bottom: 0; } -.workflow-turn-body ul, .workflow-turn-body ol { margin: var(--space-1) 0; padding-left: 1.4em; } -.workflow-turn-body li { margin: 2px 0; } -.workflow-turn-body strong { color: var(--text-strong); } -.workflow-turn-body code { - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - padding: 1px 4px; - font-family: var(--font-mono); - font-size: 0.9em; -} - -.workflow-turn-user { - align-self: flex-end; - max-width: 80%; - background: var(--copper-bg); - border: 1px solid var(--copper-border); - border-radius: var(--radius-md); - padding: var(--space-1) var(--space-4); - font-size: var(--font-size-sm); - color: var(--text); -} - -.workflow-turn-failed { - border-color: var(--red-border); - background: var(--bg-surface); -} - -.workflow-turn-status { - font-size: var(--font-size-xs); - color: var(--text-muted); - font-style: italic; - margin-top: 2px; -} - -.workflow-turn-error { - display: flex; - align-items: center; - gap: var(--space-2); - font-size: var(--font-size-xs); - color: var(--red); - margin-top: 2px; -} - -/* ---- Workflow phase options ---- */ -.workflow-options { - display: flex; - flex-direction: column; - gap: var(--space-1); - margin-top: var(--space-2); -} - -.workflow-option { - display: flex; - flex-direction: column; - gap: 2px; - padding: var(--space-1) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - text-align: left; - cursor: pointer; - transition: background 150ms, border-color 150ms; -} - -.workflow-option:hover { - background: var(--bg-surface); - border-color: var(--copper-border); -} - -.workflow-option.recommended { - border-color: var(--copper-border); - background: var(--copper-bg); -} - -.workflow-option.recommended:hover { - background: color-mix(in srgb, var(--copper-bg) 80%, var(--bg-surface)); -} - -.workflow-option.selected { - border-color: var(--copper-border); - background: var(--copper-bg); -} - -.workflow-option.selected .workflow-option-label { - color: var(--copper); -} - -.workflow-option-label { - font-family: var(--font-mono); - font-size: var(--font-size-sm); - font-weight: 600; - color: var(--text); -} - -.workflow-option.recommended .workflow-option-label { - color: var(--copper); -} - -.workflow-option-context { - font-size: var(--font-size-xs); - color: var(--text-muted); - line-height: 1.4; -} - -/* ---- Workflow chat input ---- */ -.workflow-chat-input { - display: flex; - flex-direction: column; - gap: var(--space-2); -} - -.workflow-feedback { - width: 100%; - min-height: 72px; - padding: var(--space-2) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); - font-family: var(--font-sans); - font-size: var(--font-size-md); - resize: vertical; - outline: none; - box-sizing: border-box; -} - -.workflow-feedback:focus { - border-color: var(--copper); -} - -.workflow-feedback::placeholder { - color: var(--text-muted); - font-style: italic; -} diff --git a/src/planner/web/css/layout.css b/src/planner/web/css/layout.css deleted file mode 100644 index 4e7acd5..0000000 --- a/src/planner/web/css/layout.css +++ /dev/null @@ -1,545 +0,0 @@ -/* Single centred column. max-width keeps the entire UI (header, sidebar, - * feed, monitor) as one cohesive panel in the middle of the viewport. - * The body background fills the remaining viewport edges. */ -.app { - display: flex; - flex-direction: column; - height: 100vh; - overflow: hidden; - max-width: 1300px; - margin: 0 auto; -} - -/* Header — normal flex child, not fixed. Stays at top because .app is a - * flex column with overflow:hidden; child areas scroll internally. */ -.header { - flex-shrink: 0; - height: var(--header-height); - display: flex; - align-items: center; - justify-content: space-between; - padding: 0 var(--space-6); - background: var(--bg); - border-bottom: 1px solid var(--border); -} - -.header-left { - display: flex; - align-items: center; - gap: var(--space-4); -} - -.logo { - font-family: var(--font-sans); - font-size: 20px; - font-weight: 800; - color: var(--text-strong); - letter-spacing: -0.03em; -} - -/* Main panel — fills all remaining vertical space */ -.main-panel { - flex: 1 1 0; - min-height: 0; - display: flex; - flex-direction: column; -} - -/* Phase content area — scrollable, fills remaining space */ -.phase-content { - flex: 1 1 0; - min-height: 0; - overflow-y: auto; - padding: var(--space-6); - display: flex; - flex-direction: column; - align-items: center; -} - -.phase-inner { - width: 100%; - max-width: 960px; -} - -/* Activity feed — fills remaining space in phase-content, scrollable */ -.activity-feed-scroll { - flex: 1 1 0; - min-height: 0; - overflow-y: overlay; - padding: var(--space-4) var(--space-6); - /* Subtle fade at top when scrolled */ - mask-image: linear-gradient(to bottom, transparent, black 8px, black); - -webkit-mask-image: linear-gradient(to bottom, transparent, black 8px, black); -} - -.activity-feed-inner { - display: flex; - flex-direction: column; - gap: 2px; - max-width: 960px; -} - -/* ---- Activity cards (thinking, future: tool results) ---- */ - -.activity-card { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - margin: var(--space-1) 0; - overflow: hidden; -} - -.activity-card-active { - border-color: var(--copper-border); -} - -.activity-card-header { - display: flex; - justify-content: space-between; - align-items: center; - padding: var(--space-2) var(--space-4); - font-family: var(--font-mono); - font-size: var(--font-size-sm); -} - -.activity-card-tool { - color: var(--text-muted); -} - -.activity-card-thinking .activity-card-tool { - color: var(--plum); -} - -.activity-card-meta { - color: var(--text-muted); - font-size: var(--font-size-xs); -} - -.activity-elapsed { - color: var(--text-muted); -} - -.activity-card-body { - padding: 0 var(--space-4) var(--space-2); - font-family: var(--font-mono); - font-size: 13px; - color: var(--text-muted); - white-space: pre-wrap; - word-break: break-word; - line-height: 1.5; -} - -.activity-card-body:not(.expanded) { - display: -webkit-box; - -webkit-line-clamp: 3; - -webkit-box-orient: vertical; - overflow: hidden; -} - -.activity-card-more { - padding: 2px var(--space-4) var(--space-2); - font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--copper); - cursor: pointer; - user-select: none; -} - -/* ---- Scout dispatch card ---- */ - -.activity-card-scouts .activity-card-tool { - color: var(--copper); -} - -.scout-list { - display: flex; - flex-direction: column; - gap: 2px; - padding: 0 var(--space-4) var(--space-2); -} - -.scout-entry { - display: flex; - align-items: baseline; - gap: 10px; - padding: 5px var(--space-2); - font-family: var(--font-mono); - font-size: var(--font-size-xs); - border-left: 2px solid var(--border); - border-radius: 0 var(--radius-sm) var(--radius-sm) 0; -} - -/* Status-based accent bar colors — synced with agent status convention */ -.scout-queued { border-left-color: var(--text-muted); } -.scout-running { border-left-color: var(--copper); background: var(--copper-bg); } -.scout-completed { border-left-color: var(--green); background: var(--green-bg); } -.scout-failed { border-left-color: var(--red); background: var(--red-bg); } - -.scout-name { - color: var(--text-muted); - font-weight: 500; - min-width: 20ch; - flex-shrink: 0; -} - -.scout-role { - color: var(--text-ghost); -} - -.activity-card-more:hover { - color: var(--text-strong); -} - -.activity-line { - display: flex; - gap: var(--space-2); - font-family: var(--font-mono); - font-size: var(--font-size-sm); - color: var(--text-muted); - padding: 2px 0; - line-height: 1.4; -} - -.activity-line.activity-high { - color: var(--text-muted); -} - -.activity-tool { - color: var(--text-ghost); - min-width: 48px; - flex-shrink: 0; -} - -.activity-high .activity-tool { - color: var(--copper); -} - -.activity-summary { - white-space: nowrap; - overflow: hidden; - text-overflow: ellipsis; -} - -.activity-detail { - color: var(--text-ghost); - padding-left: 12px; -} - -/* Monitor — sticky bottom, sizes to content, centered like activity feed. - * No border-top or mask fade — it connects seamlessly with the sidebars. */ -.monitor { - flex: 0 0 auto; - max-height: 40vh; - overflow-y: overlay; - background: var(--bg-surface); - padding: var(--space-4) var(--space-6); -} - -.monitor-inner { - max-width: 960px; - margin: 0 auto; -} - -.agent-table-header { - display: flex; - align-items: center; - gap: var(--space-4); - margin-bottom: var(--space-2); -} - -.monitor-label { - font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--text-muted); - text-transform: uppercase; - letter-spacing: 0.08em; -} - -.agent-badges { - display: flex; - gap: var(--space-1); -} - -.token-totals { - margin-left: auto; - font-family: var(--font-mono); - font-size: var(--font-size-sm); - color: var(--text-muted); -} - -/* ---- Live layout: activity feed + status sidebar ---- */ - -/* Row wrapper for live mode: sidebar (left) + activity feed (right). - * No centering or margin-top needed — the parent .app handles both. */ -.live-layout { - flex: 1 1 0; - min-height: 0; - display: flex; - flex-direction: row; -} - -/* Left column — takes all remaining width, scroll contained within. */ -.live-main { - flex: 1 1 0; - min-width: 0; - min-height: 0; - display: flex; - flex-direction: column; -} - -/* ---- Status sidebar ---- - * Sits on the LEFT of the activity feed inside the centred .live-layout - * container. Width uses clamp(240px, 20vw, 300px): 20vw scales with the - * viewport; 240px/300px bound the range. Typography is mono throughout. - * The sidebar scrolls independently of the feed column. */ - -.status-sidebar { - width: clamp(240px, 20vw, 300px); - flex-shrink: 0; - background: var(--bg-surface); - border-right: 1px solid var(--border); - overflow-y: auto; - padding: var(--space-4); -} - -.sidebar-heading { - font-family: var(--font-mono); - font-size: 12px; - color: var(--text-muted); - text-transform: uppercase; - letter-spacing: 0.08em; - margin-bottom: var(--space-4); -} - -.sidebar-section { - margin-bottom: var(--space-4); -} - -.sidebar-label { - font-family: var(--font-mono); - font-size: 12px; - color: var(--text-muted); - text-transform: uppercase; - letter-spacing: 0.06em; - margin-bottom: var(--space-1); -} - -/* Value line beneath a section */ -.sidebar-value { - font-family: var(--font-mono); - font-size: 13px; - font-weight: 500; - color: var(--text-muted); -} - -.sidebar-divider { - height: 1px; - background: var(--border); - margin: var(--space-4) 0; -} - -.sidebar-summary { - font-family: var(--font-mono); - font-size: 13px; - color: var(--text-muted); - line-height: 1.4; -} - -/* Agent identity section */ -.sidebar-agent { - margin-bottom: var(--space-4); - font-family: var(--font-mono); -} - -.sidebar-agent-role { - color: var(--copper); - font-weight: 600; - text-transform: uppercase; - letter-spacing: 0.06em; - font-size: 13px; -} - -.sidebar-agent-model { - color: var(--text-muted); - font-size: 13px; -} - -.sidebar-agent-step { - color: var(--text-muted); - font-size: 13px; - margin-top: 2px; -} - -.sidebar-agent-stats { - display: flex; - justify-content: space-between; - color: var(--text-muted); - font-size: 13px; - margin-top: 2px; -} - -/* ---- Workspace shell: three-column layout ---- */ - -.workspace { - flex: 1 1 0; - min-height: 0; - display: flex; - flex-direction: row; -} - -.workspace-main { - flex: 1 1 0; - min-width: 0; - min-height: 0; - display: flex; - flex-direction: column; -} - -.artifacts-sidebar { - width: clamp(240px, 20vw, 300px); - flex-shrink: 0; - background: var(--bg-surface); - border-left: 1px solid var(--border); - overflow-y: auto; - padding: var(--space-4); - display: flex; - flex-direction: column; -} - -.artifacts-empty { - color: var(--text-ghost); - font-family: var(--font-mono); - font-size: 12px; - padding: var(--space-4) 0; -} - -/* ---- Artifact tree ---- */ - -.tree-folder { - margin-bottom: 2px; -} - -.tree-folder-label { - display: flex; - align-items: center; - gap: 6px; - color: var(--text-muted); - padding: 3px 4px; - cursor: pointer; - font-family: var(--font-mono); - font-size: 12px; - border-radius: var(--radius-sm); - user-select: none; -} - -.tree-folder-label:hover { - color: var(--text-strong); - background: var(--bg-inset); -} - -.tree-children { - padding-left: 14px; -} - -.tree-file { - display: flex; - flex-direction: column; - padding: 3px 4px; - border-radius: var(--radius-sm); - cursor: pointer; - margin-bottom: 1px; -} - -.tree-hover { - background: var(--bg-inset); -} - -.tree-file-name { - color: var(--copper); - font-family: var(--font-mono); - font-size: 12px; -} - -.tree-file-meta { - color: var(--text-ghost); - font-family: var(--font-mono); - font-size: 11px; -} - -.tree-new-badge { - display: inline-block; - background: var(--green); - color: #fff; - font-size: 9px; - padding: 1px 4px; - border-radius: 3px; - margin-left: 4px; - vertical-align: middle; -} - -/* ---- Artifact overlay ---- */ - -.artifact-overlay { - position: fixed; - inset: 0; - background: rgba(42, 31, 20, 0.5); - display: flex; - align-items: center; - justify-content: center; - z-index: 200; -} - -.artifact-overlay-panel { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - width: 860px; - max-width: 92vw; - max-height: 88vh; - display: flex; - flex-direction: column; - overflow: hidden; -} - -.artifact-overlay-header { - display: flex; - align-items: center; - justify-content: space-between; - padding: 14px 20px; - border-bottom: 1px solid var(--border); - flex-shrink: 0; -} - -.artifact-overlay-title { - font-family: var(--font-mono); - font-size: 14px; - font-weight: 600; - color: var(--text-strong); -} - -.artifact-overlay-path { - font-family: var(--font-mono); - font-size: 11px; - color: var(--text-ghost); - margin-top: 2px; -} - -.artifact-overlay-readonly-badge { - font-size: 10px; - color: var(--text-ghost); - border: 1px solid var(--border); - padding: 2px 6px; - border-radius: 3px; - margin-left: 8px; - vertical-align: middle; - font-weight: 400; -} - -.artifact-overlay-body { - flex: 1; - overflow-y: auto; - padding: 24px 28px; - font-size: 14px; - line-height: 1.7; - color: var(--text-muted); -} diff --git a/src/planner/web/css/variables.css b/src/planner/web/css/variables.css deleted file mode 100644 index 724cfa3..0000000 --- a/src/planner/web/css/variables.css +++ /dev/null @@ -1,110 +0,0 @@ -:root { - /* Background layers */ - --bg: #FEFAE0; /* cornsilk base — "the desk" */ - --bg-surface: #E0D8C8; /* stone — sidebars, panels, monitor */ - --bg-elevated: #FFFFFF; /* cards, overlays — "paper on paper" */ - --bg-inset: #D4CCB8; /* pressed/inset areas */ - - /* Borders */ - --border: #C8C0A8; - --border-strong: #B8B098; - - /* Text hierarchy */ - --text: #4A4428; /* Olive-brown — default body */ - --text-strong: #283618; /* Black Forest — headings */ - --text-muted: #7A7450; /* Dried sage — metadata */ - --text-ghost: #A09A6E; /* Faded straw — disabled/placeholder */ - - /* Status — the ONLY saturated colors */ - --green: #606C38; - --green-bg: #EEF2E4; - --green-border: #606C38; - --copper: #BC6C25; - --copper-bg: #FDF3E4; - --copper-border: #BC6C25; - --caramel: #DDA15E; - --caramel-bg: #FEF7E8; - --caramel-border: #DDA15E; - --red: #9A3412; - --red-bg: #FEF0E8; - --red-border: #9A3412; - --ochre: #92810A; - --ochre-bg: #FEFCE8; - --ochre-border: #92810A; - --plum: #606C38; - --plum-bg: #EEF2E4; - - /* Typography */ - --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; - --font-mono: 'SF Mono', 'JetBrains Mono', 'Cascadia Code', 'Fira Code', monospace; - - /* Font sizes */ - --font-size-xs: 11px; - --font-size-sm: 13px; - --font-size-md: 15px; - --font-size-lg: 17px; - --font-size-xl: 22px; - --font-size-display: 28px; - - /* Spacing (base unit 4px) */ - --space-1: 4px; - --space-2: 8px; - --space-4: 16px; - --space-6: 24px; - --space-8: 32px; - --space-12: 48px; - --space-16: 64px; - - /* Shape */ - --radius-sm: 6px; - --radius-md: 10px; - --radius-lg: 14px; - - /* Motion */ - --duration-fast: 150ms; - --duration-normal: 250ms; - --duration-slow: 400ms; - --ease-default: ease-out; - - /* Layout */ - --header-height: 56px; - --monitor-min-height: 120px; -} - -*, *::before, *::after { - box-sizing: border-box; -} - -html, body { - margin: 0; - padding: 0; - height: 100%; - background: var(--bg); - color: var(--text); - font-family: var(--font-sans); - font-size: var(--font-size-md); - line-height: 1.6; -} - -* { - scrollbar-width: thin; - scrollbar-color: var(--border-strong) transparent; -} - -::-webkit-scrollbar { - width: 7px; - height: 7px; -} - -::-webkit-scrollbar-track { - background: transparent; -} - -::-webkit-scrollbar-thumb { - background: var(--border-strong); - border-radius: 4px; -} - -::-webkit-scrollbar-thumb:hover { - background: var(--text-muted); -} diff --git a/src/planner/web/html/index.html b/src/planner/web/html/index.html deleted file mode 100644 index 91b9e10..0000000 --- a/src/planner/web/html/index.html +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - koan - - - - - - - -
- - - diff --git a/src/planner/web/js/app.jsx b/src/planner/web/js/app.jsx deleted file mode 100644 index 035a254..0000000 --- a/src/planner/web/js/app.jsx +++ /dev/null @@ -1,17 +0,0 @@ -import { render } from 'preact' -import { App } from './components/App.jsx' -import { connectSSE } from './sse.js' - -const data = window.__DATA__ -const token = data?.token || new URLSearchParams(location.search).get('session') || '' - -render(, document.getElementById('app')) -connectSSE(token) - -setInterval(() => { - fetch('/api/heartbeat', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ token }), - }).catch(() => {}) -}, 5000) diff --git a/src/planner/web/js/components/ActivityFeed.jsx b/src/planner/web/js/components/ActivityFeed.jsx deleted file mode 100644 index ac1a774..0000000 --- a/src/planner/web/js/components/ActivityFeed.jsx +++ /dev/null @@ -1,444 +0,0 @@ -import { useRef, useEffect, useState, useCallback } from 'preact/hooks' -import { marked } from 'marked' -import { useStore } from '../store.js' - -function ThinkingTimer({ since }) { - const [elapsed, setElapsed] = useState(0) - - useEffect(() => { - const start = new Date(since).getTime() - const tick = () => setElapsed(Math.floor((Date.now() - start) / 1000)) - tick() - const id = setInterval(tick, 1000) - return () => clearInterval(id) - }, [since]) - - const text = elapsed < 60 - ? `${elapsed}s` - : `${Math.floor(elapsed / 60)}m ${elapsed % 60}s` - - return {text} -} - -/** Card for thinking entries — shows expandable thought content */ -function ThinkingCard({ line, isInFlight, isFlashing, dimmed }) { - const [expanded, setExpanded] = useState(false) - const bodyRef = useRef(null) - const [isClamped, setIsClamped] = useState(false) - - // Detect whether the body text is actually clamped (more content than visible) - useEffect(() => { - const el = bodyRef.current - if (el) setIsClamped(el.scrollHeight > el.clientHeight + 2) - }, [line.body, expanded]) - - // While in-flight with streaming body, treat as always expanded so the - // user sees tokens appear. Clamping only applies to completed thoughts. - const isStreaming = isInFlight && !!line.body - const showExpanded = expanded || isStreaming - - const cls = [ - 'activity-card', - 'activity-card-thinking', - isInFlight ? 'activity-card-active' : '', - isFlashing ? 'activity-flash' : '', - dimmed ? 'activity-frozen' : '', - ].filter(Boolean).join(' ') - - return ( -
-
- thinking - - {isInFlight - ? - : line.summary - } - -
- {line.body && ( - <> -
- {line.body}{isStreaming && } -
- {(!isStreaming && isClamped && !expanded) && ( -
setExpanded(true)}> - show more ▸ -
- )} - {(!isStreaming && expanded) && ( -
setExpanded(false)}> - show less ▴ -
- )} - - )} -
- ) -} - -function formatElapsedShort(ms) { - const sec = Math.floor(ms / 1000) - if (sec < 60) return `${sec}s` - const min = Math.floor(sec / 60) - const rem = sec % 60 - return rem > 0 ? `${min}m ${rem}s` : `${min}m` -} - -/** Card for koan_request_scouts — shows dispatched scouts with name + role. - * Cross-references live scout status from the store to color the accent bar. - * Shows total elapsed time once all scouts have completed. */ -function ScoutCard({ line, isInFlight, isFlashing, dimmed }) { - const scoutDefs = line.scouts || [] - const liveScouts = useStore(s => s.scouts) - const allAgents = useStore(s => s.agents) - - // Build id→status lookup from live scout data - const statusById = {} - for (const s of liveScouts) statusById[s.id] = s.status - - // Compute total elapsed from scout agent timing data - const scoutIds = new Set(scoutDefs.map(s => s.id)) - const scoutAgents = allAgents.filter(a => scoutIds.has(a.name || a.id)) - const allDone = scoutAgents.length > 0 && scoutAgents.every(a => a.status === 'completed' || a.status === 'failed') - let totalElapsed = null - if (allDone) { - const starts = scoutAgents.filter(a => a.startedAt).map(a => a.startedAt) - const ends = scoutAgents.filter(a => a.completedAt).map(a => a.completedAt) - if (starts.length > 0 && ends.length > 0) { - totalElapsed = formatElapsedShort(Math.max(...ends) - Math.min(...starts)) - } - } - - const cls = [ - 'activity-card', - 'activity-card-scouts', - isInFlight ? 'activity-card-active' : '', - isFlashing ? 'activity-flash' : '', - dimmed ? 'activity-frozen' : '', - ].filter(Boolean).join(' ') - - return ( -
-
- - dispatching {scoutDefs.length} scout{scoutDefs.length !== 1 ? 's' : ''} - - - {isInFlight - ? … - : totalElapsed && {totalElapsed} - } - -
-
- {scoutDefs.map((s, i) => { - const status = statusById[s.id] ?? null - const statusCls = status === 'running' ? 'scout-running' - : status === 'completed' ? 'scout-completed' - : status === 'failed' ? 'scout-failed' - : 'scout-queued' - return ( -
- {s.id} - {s.role} -
- ) - })} -
-
- ) -} - -/** Standard line for tool calls and lifecycle events */ -function ActivityLine({ line, isInFlight, isFlashing, dimmed }) { - const cls = [ - 'activity-line', - line.highValue ? 'activity-high' : '', - isInFlight ? 'activity-inflight' : '', - isFlashing ? 'activity-flash' : '', - dimmed ? 'activity-frozen' : '', - ].filter(Boolean).join(' ') - - return ( - <> -
- {line.tool} - - {line.summary || ''} - {isInFlight && ...} - -
- {line.details?.map((d, j) => ( -
- - {d} -
- ))} - - ) -} - -/** Render a single log line — used for both live and frozen zones */ -function renderLine(line, isInFlight, isFlashing, key, dimmed = false, streamingText = '') { - if (line.tool === 'thinking') { - const thinkingLine = (isInFlight && streamingText) - ? { ...line, body: streamingText.replace(/\n{3,}/g, '\n\n') } - : line - return ( - - ) - } - - if (line.scouts) { - return ( - - ) - } - - return ( - - ) -} - -// --------------------------------------------------------------------------- -// WorkflowChat: multi-turn conversation with the workflow orchestrator -// --------------------------------------------------------------------------- - -function WorkflowChat({ turns, token }) { - const [input, setInput] = useState('') - const [submitting, setSubmitting] = useState(false) - const [selectedPhase, setSelectedPhase] = useState(null) - - const lastTurn = turns[turns.length - 1] - const awaitingUser = lastTurn?.role === 'orchestrator' - - function selectPhase(phase) { - // Pre-fill rather than auto-submit. Lets the user add context before - // sending: "Proceed with core-flows, but focus on auth requirements" - setSelectedPhase(phase.phase) - setInput(`Proceed with ${phase.label}`) - } - - async function submit() { - if (submitting || !input.trim() || !awaitingUser) return - setSubmitting(true) - - const userText = input.trim() - // Append user turn immediately for responsive feedback. - useStore.setState(s => ({ - workflowChat: [...s.workflowChat, { role: 'user', text: userText, pending: true }] - })) - setInput('') - setSelectedPhase(null) - - try { - await fetch('/api/workflow-decision', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ - token, - requestId: lastTurn.requestId, - feedback: userText, - }), - }) - // Clear the workflow chat — the decision has been submitted and the - // orchestrator will proceed. The next phase event (or a new - // workflow-decision event) will re-populate if needed. - useStore.setState({ workflowChat: [] }) - } catch (err) { - // Mark turn as failed so user can retry. Without this, the pipeline - // hangs at pollIpcUntilResponse() indefinitely. - useStore.setState(s => ({ - workflowChat: s.workflowChat.map(t => - t.role === 'user' && t.pending ? { ...t, pending: false, failed: true } : t - ) - })) - } finally { - setSubmitting(false) - } - } - - function handleKeyDown(e) { - if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) { - e.preventDefault() - submit() - } - } - - return ( -
- {turns.map((turn, i) => ( - turn.role === 'orchestrator' - ? - : { setInput(text) }} /> - ))} - - {awaitingUser && ( -
- -
- - -
-
-
-
diff --git a/koan/web/templates/fragments/interaction_ask.html b/koan/web/templates/fragments/interaction_ask.html deleted file mode 100644 index c2076c5..0000000 --- a/koan/web/templates/fragments/interaction_ask.html +++ /dev/null @@ -1,49 +0,0 @@ -
-
-
-
1 / {{ questions|length }}
- {% for q in questions %} -
-
Question {{ loop.index }} of {{ questions|length }}
- {% if q.context %} -
{{ q.context }}
- {% endif %} -
{{ q.question }}
- {% if q.multi %} -
Select all that apply
- {% endif %} -
- {% for opt in q.options %} -
- - {{ opt.label }} - {% if opt.recommended %} - recommended - {% endif %} -
- {% endfor %} - {% if q.allow_other %} -
- - Other (type your own) - -
- {% endif %} -
-
- {% endfor %} - -
- - - {% if questions|length > 1 %} - - {% endif %} - -
-
-
-
diff --git a/koan/web/templates/fragments/interaction_workflow.html b/koan/web/templates/fragments/interaction_workflow.html deleted file mode 100644 index 064e4bc..0000000 --- a/koan/web/templates/fragments/interaction_workflow.html +++ /dev/null @@ -1,37 +0,0 @@ -
- {% for turn in chat_turns %} -
- {% if turn.role == "orchestrator" %} -
-
- Orchestrator -
-
{{ turn.status_report }}
-
- {% if turn.recommended_phases %} -
- {% for rp in turn.recommended_phases %} - - {% endfor %} -
- {% endif %} - {% elif turn.role == "user" %} -
{{ turn.message }}
- {% endif %} -
- {% endfor %} - -
- -
- -
-
-
diff --git a/koan/web/templates/fragments/monitor.html b/koan/web/templates/fragments/monitor.html deleted file mode 100644 index 5ced290..0000000 --- a/koan/web/templates/fragments/monitor.html +++ /dev/null @@ -1,33 +0,0 @@ -{% if agents %} -
-
- Agents -
- - - - - - - - - - - - - {% for a in agents %} - - - - - - - - - {% endfor %} - -
AgentModelTokensTimeDoing
- {% if a.status == "running" %}>>{% elif a.status == "done" %}[OK]{% elif a.status == "failed" %}[!!]{% else %}[ ]{% endif %} - {{ a.role }}{{ a.model or "--" }}{{ a.tokens_display }}{{ a.elapsed }}{{ a.doing or "--" }}
-
-{% endif %} diff --git a/koan/web/templates/fragments/settings_body.html b/koan/web/templates/fragments/settings_body.html deleted file mode 100644 index 9cfd4cd..0000000 --- a/koan/web/templates/fragments/settings_body.html +++ /dev/null @@ -1,48 +0,0 @@ -
Profiles
-
- {% for p in profiles %} -
- {{ p.name }}{% if p.read_only %} [locked]{% endif %} - {{ p.tier_summary or "--" }} - - {% if not p.read_only %} - - - {% endif %} - -
- {% endfor %} -
- - - - - -
- Agent Installations -
- {% for inst in installations %} -
- {{ inst.alias }} - {% if inst.is_active %}active{% endif %} - {{ inst.runner_type }} - {{ inst.binary or "--" }} - {% if inst.extra_args %}{{ inst.extra_args | join(" ") }}{% endif %} - - {% if not inst.is_active %} - - {% endif %} - - - -
- {% endfor %} -
- - - -
- -
- -
diff --git a/koan/web/templates/fragments/settings_installation_form.html b/koan/web/templates/fragments/settings_installation_form.html deleted file mode 100644 index 645a2e6..0000000 --- a/koan/web/templates/fragments/settings_installation_form.html +++ /dev/null @@ -1,28 +0,0 @@ -
-
- Alias - -
-
- Runner - -
-
- Binary - - -
-
- Extra args - -
-
- - -
-
diff --git a/koan/web/templates/fragments/settings_profile_form.html b/koan/web/templates/fragments/settings_profile_form.html deleted file mode 100644 index 2a0b711..0000000 --- a/koan/web/templates/fragments/settings_profile_form.html +++ /dev/null @@ -1,35 +0,0 @@ -
- {% if not is_edit %} -
- Name - -
- {% else %} -
- Name - -
- {% endif %} - {% for tier in ["strong", "standard", "cheap"] %} - {% set t = tiers.get(tier, {}) %} -
- {{ tier }} - - - -
- {% endfor %} -
- - -
-
diff --git a/koan/web/templates/fragments/status_sidebar.html b/koan/web/templates/fragments/status_sidebar.html deleted file mode 100644 index 16934db..0000000 --- a/koan/web/templates/fragments/status_sidebar.html +++ /dev/null @@ -1,38 +0,0 @@ -{% if subagent %} -
-
{{ subagent.role }}
-
{{ subagent.model or "--" }}
-
{{ subagent.step_name or ("step " ~ subagent.step) }}
-
- {{ subagent.tokens_display }} - {{ subagent.elapsed or "0m 00s" }} -
-
-
-{% endif %} -{% if phase_status %} -
-
Phase
-
{{ phase_status.phase }}
-
-{% if phase_status.sub_phase %} -
-
Sub-phase
-
{{ phase_status.sub_phase }}
-
-{% endif %} -{% if phase_status.confidence is not none %} -
-
Confidence
-
{{ phase_status.confidence }}%
-
-{% endif %} -{% if phase_status.summary %} -
-
{{ phase_status.summary }}
-{% endif %} -{% endif %} -{% if not subagent and not phase_status %} -
Status
-
Waiting...
-{% endif %} diff --git a/koan/web/templates/landing.html b/koan/web/templates/landing.html deleted file mode 100644 index f238f5b..0000000 --- a/koan/web/templates/landing.html +++ /dev/null @@ -1,68 +0,0 @@ -{% extends "base.html" %} -{% block content %} -
-
- -
-
- -
-
-
-
-
-

New Run

- -
-
Task
- -
- -
-

Profile

- -
- -
-

Scout Concurrency

- -
- -
- {% if has_runners %} - - {% else %} - - {% endif %} -
- {% if not has_runners %} - No available runners. Open Settings to install and authenticate a runner. - {% endif %} -
-
-
- - -{% endblock %} diff --git a/koan/web/templates/live.html b/koan/web/templates/live.html deleted file mode 100644 index c9148dd..0000000 --- a/koan/web/templates/live.html +++ /dev/null @@ -1,72 +0,0 @@ -{% extends "base.html" %} -{% block content %} -
-
- -
- {% for p in phases %} - {{ p }} - {% endfor %} -
-
-
- -
-
-
- -
-
-
-
-
-
-
- {% include "fragments/monitor.html" %} -
-
- -
- - - -{% endblock %} diff --git a/pyproject.toml b/pyproject.toml index e220401..18a0b0e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,6 @@ dependencies = [ "starlette", "uvicorn[standard]", "fastmcp", - "jinja2", "aiofiles", ] diff --git a/tests/test_subagent.py b/tests/test_subagent.py index a0bdcab..657de8d 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -337,8 +337,7 @@ def capture_sse(app, event_type, payload): captured_model.append(payload.get("model")) with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}), \ - patch("koan.subagent._push_sse", side_effect=capture_sse), \ - patch("koan.subagent.load_koan_config", return_value=config): + patch("koan.subagent._push_sse", side_effect=capture_sse): from koan.subagent import spawn_subagent await spawn_subagent(task, app_state, runner=FakeRunner()) @@ -642,6 +641,7 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): ) app_state = FakeAppState(port=9999) + app_state.config = config subagent_dir = str(tmp_path / "sub") Path(subagent_dir).mkdir() @@ -658,8 +658,7 @@ def capture_sse(app, event_type, payload): sse_payloads.append(payload) with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}), \ - patch("koan.subagent._push_sse", side_effect=capture_sse), \ - patch("koan.subagent.load_koan_config", return_value=config): + patch("koan.subagent._push_sse", side_effect=capture_sse): from koan.subagent import spawn_subagent exit_code = await spawn_subagent(task, app_state) diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index 0055874..dc3e6bb 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -1,4 +1,4 @@ -# Tests for key web flows: SSE replay, landing page, start-run, artifacts, path traversal. +# Tests for key web flows: SSE replay, SPA fallback, start-run, artifacts, path traversal. from __future__ import annotations @@ -57,13 +57,14 @@ def client(app_state): yield c -# -- Landing page ------------------------------------------------------------- +# -- SPA fallback (formerly landing page) ------------------------------------- def test_landing_page_renders(client, app_state): + # After SPA migration, GET / serves the React app's index.html (or a + # minimal placeholder when the frontend hasn't been built). resp = client.get("/") assert resp.status_code == 200 - assert "task-input" in resp.text - assert "Start Run" in resp.text + assert "root" in resp.text # -- Start run ---------------------------------------------------------------- @@ -161,7 +162,9 @@ def test_path_traversal_blocked(client, app_state): app_state.epic_dir = str(epic) app_state.start_event.set() - resp = client.get("/api/artifacts/../../../etc/passwd") + # URL-normalized traversal (../) is resolved before routing and hits the SPA fallback. + # Use URL-encoded slashes (%2F) to test path traversal within the artifact handler. + resp = client.get("/api/artifacts/..%2F..%2F..%2Fetc%2Fpasswd") assert resp.status_code in (400, 404) @@ -326,30 +329,36 @@ def test_agents_detect_missing_param(client, app_state): def test_sse_replay(app_state): """Test that SSE stream replays last_sse_values on connect.""" from koan.web.app import _sse_event + from koan.driver import push_sse + + # Push a phase event through the new JSON-only push_sse + push_sse(app_state, "phase", "intake") - app_state.last_sse_values["phase"] = {"phase": "intake", "html": "
test
", "target": "status-sidebar"} + # Verify the replay cache now holds the JSON payload (no html/target) + assert "phase" in app_state.last_sse_values + payload = app_state.last_sse_values["phase"] + assert payload["phase"] == "intake" + assert "html" not in payload + assert "target" not in payload # Verify the SSE event formatter produces correct output - event_str = _sse_event("phase", app_state.last_sse_values["phase"]) + event_str = _sse_event("phase", payload) assert "event: phase" in event_str assert '"intake"' in event_str - # Verify replay cache is populated - assert "phase" in app_state.last_sse_values - assert app_state.last_sse_values["phase"]["phase"] == "intake" - -# -- Live page redirect ------------------------------------------------------- +# -- Live page redirect (now SPA fallback) ------------------------------------ def test_live_page_when_running(client, app_state): + # After SPA migration, GET / always returns the SPA entry point. + # The React app reads store state client-side to render the live view. app_state.start_event.set() app_state.epic_dir = "/tmp/fake-epic" app_state.phase = "intake" resp = client.get("/") assert resp.status_code == 200 - assert "pill-strip" in resp.text - assert "activity-feed-inner" in resp.text + assert "root" in resp.text # -- Workflow interaction SSE payload ----------------------------------------- @@ -371,52 +380,60 @@ def test_workflow_interaction_sse_payload_shape(app_state): }], }) + # After SPA migration, interaction payloads are pure JSON (no html/target). payload = app_state.last_sse_values["interaction"] - assert "html" in payload - assert payload["target"] == "workspace-main-content" - assert "workflow-option" in payload["html"] - assert 'data-phase="tech-plan"' in payload["html"] + assert payload["type"] == "workflow-decision" + assert payload["token"] == "tok" + assert "html" not in payload + assert "target" not in payload + # Verify the phase data is in the payload + turns = payload["chat_turns"] + assert turns[0]["recommended_phases"][0]["phase"] == "tech-plan" # -- Old model-config route removed ------------------------------------------ def test_model_config_removed(client, app_state): + # After SPA migration, unknown paths are served by the SPA fallback (200). + # The /api/model-config endpoint no longer exists as a JSON API endpoint. resp = client.get("/api/model-config") - assert resp.status_code in (404, 405) + # SPA fallback serves HTML, not a JSON API response + assert resp.status_code in (200, 404, 405) + if resp.status_code == 200: + # Must be HTML (SPA), not a JSON API response + ct = resp.headers.get("content-type", "") + assert "text/html" in ct # -- Landing page: profile selector & settings button ------------------------ def test_landing_includes_profile_selector(client, app_state): + # After SPA migration, GET / serves the React SPA, not server-rendered HTML. + # Profile selector is rendered client-side by React. app_state.probe_results = _make_probe_results() app_state.balanced_profile = Profile(name="balanced", tiers={ "strong": ProfileTier(runner_type="claude", model="opus", thinking="high"), }) resp = client.get("/") assert resp.status_code == 200 - assert "profile-select" in resp.text - assert "settings-btn" in resp.text def test_landing_start_run_disabled_no_runners(client, app_state): + # After SPA migration, runner availability is checked client-side via /api/probe. app_state.probe_results = [ ProbeResult(runner_type="claude", available=False), ProbeResult(runner_type="codex", available=False), ] resp = client.get("/") assert resp.status_code == 200 - assert "disabled" in resp.text - assert "No available runners" in resp.text def test_landing_start_run_enabled_with_runners(client, app_state): + # After SPA migration, GET / serves the SPA regardless of runner state. app_state.probe_results = _make_probe_results() app_state.balanced_profile = Profile(name="balanced", tiers={}) resp = client.get("/") assert resp.status_code == 200 - # The button should exist without disabled attribute - assert 'id="btn-start-run"' in resp.text - assert "No available runners" not in resp.text def test_start_run_sends_profile(client, app_state): @@ -449,7 +466,9 @@ def test_agents_list(client, app_state): data = resp.json() assert "installations" in data assert "active_installations" in data - assert len(data["installations"]) == 1 + aliases = [inst["alias"] for inst in data["installations"]] + assert "my-claude" in aliases + assert len(data["installations"]) >= 1 def test_agents_create_and_delete(client, app_state): diff --git a/uv.lock b/uv.lock index 98f3bac..ff2fe1c 100644 --- a/uv.lock +++ b/uv.lock @@ -491,18 +491,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b2/a3/e137168c9c44d18eff0376253da9f1e9234d0239e0ee230d2fee6cea8e55/jeepney-0.9.0-py3-none-any.whl", hash = "sha256:97e5714520c16fc0a45695e5365a2e11b81ea79bba796e26f9f1d178cb182683", size = 49010, upload-time = "2025-02-27T18:51:00.104Z" }, ] -[[package]] -name = "jinja2" -version = "3.1.6" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "markupsafe" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/df/bf/f7da0350254c0ed7c72f3e33cef02e048281fec7ecec5f032d4aac52226b/jinja2-3.1.6.tar.gz", hash = "sha256:0137fb05990d35f1275a587e9aee6d56da821fc83491a0fb838183be43f66d6d", size = 245115, upload-time = "2025-03-05T20:05:02.478Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899, upload-time = "2025-03-05T20:05:00.369Z" }, -] - [[package]] name = "jsonref" version = "1.1.0" @@ -577,7 +565,6 @@ source = { editable = "." } dependencies = [ { name = "aiofiles" }, { name = "fastmcp" }, - { name = "jinja2" }, { name = "starlette" }, { name = "uvicorn", extra = ["standard"] }, ] @@ -592,7 +579,6 @@ dev = [ requires-dist = [ { name = "aiofiles" }, { name = "fastmcp" }, - { name = "jinja2" }, { name = "starlette" }, { name = "uvicorn", extras = ["standard"] }, ] @@ -615,69 +601,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321, upload-time = "2025-08-11T12:57:51.923Z" }, ] -[[package]] -name = "markupsafe" -version = "3.0.3" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/7e/99/7690b6d4034fffd95959cbe0c02de8deb3098cc577c67bb6a24fe5d7caa7/markupsafe-3.0.3.tar.gz", hash = "sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698", size = 80313, upload-time = "2025-09-27T18:37:40.426Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/5a/72/147da192e38635ada20e0a2e1a51cf8823d2119ce8883f7053879c2199b5/markupsafe-3.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:d53197da72cc091b024dd97249dfc7794d6a56530370992a5e1a08983ad9230e", size = 11615, upload-time = "2025-09-27T18:36:30.854Z" }, - { url = "https://files.pythonhosted.org/packages/9a/81/7e4e08678a1f98521201c3079f77db69fb552acd56067661f8c2f534a718/markupsafe-3.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:1872df69a4de6aead3491198eaf13810b565bdbeec3ae2dc8780f14458ec73ce", size = 12020, upload-time = "2025-09-27T18:36:31.971Z" }, - { url = "https://files.pythonhosted.org/packages/1e/2c/799f4742efc39633a1b54a92eec4082e4f815314869865d876824c257c1e/markupsafe-3.0.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3a7e8ae81ae39e62a41ec302f972ba6ae23a5c5396c8e60113e9066ef893da0d", size = 24332, upload-time = "2025-09-27T18:36:32.813Z" }, - { url = "https://files.pythonhosted.org/packages/3c/2e/8d0c2ab90a8c1d9a24f0399058ab8519a3279d1bd4289511d74e909f060e/markupsafe-3.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d6dd0be5b5b189d31db7cda48b91d7e0a9795f31430b7f271219ab30f1d3ac9d", size = 22947, upload-time = "2025-09-27T18:36:33.86Z" }, - { url = "https://files.pythonhosted.org/packages/2c/54/887f3092a85238093a0b2154bd629c89444f395618842e8b0c41783898ea/markupsafe-3.0.3-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:94c6f0bb423f739146aec64595853541634bde58b2135f27f61c1ffd1cd4d16a", size = 21962, upload-time = "2025-09-27T18:36:35.099Z" }, - { url = "https://files.pythonhosted.org/packages/c9/2f/336b8c7b6f4a4d95e91119dc8521402461b74a485558d8f238a68312f11c/markupsafe-3.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:be8813b57049a7dc738189df53d69395eba14fb99345e0a5994914a3864c8a4b", size = 23760, upload-time = "2025-09-27T18:36:36.001Z" }, - { url = "https://files.pythonhosted.org/packages/32/43/67935f2b7e4982ffb50a4d169b724d74b62a3964bc1a9a527f5ac4f1ee2b/markupsafe-3.0.3-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:83891d0e9fb81a825d9a6d61e3f07550ca70a076484292a70fde82c4b807286f", size = 21529, upload-time = "2025-09-27T18:36:36.906Z" }, - { url = "https://files.pythonhosted.org/packages/89/e0/4486f11e51bbba8b0c041098859e869e304d1c261e59244baa3d295d47b7/markupsafe-3.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:77f0643abe7495da77fb436f50f8dab76dbc6e5fd25d39589a0f1fe6548bfa2b", size = 23015, upload-time = "2025-09-27T18:36:37.868Z" }, - { url = "https://files.pythonhosted.org/packages/2f/e1/78ee7a023dac597a5825441ebd17170785a9dab23de95d2c7508ade94e0e/markupsafe-3.0.3-cp312-cp312-win32.whl", hash = "sha256:d88b440e37a16e651bda4c7c2b930eb586fd15ca7406cb39e211fcff3bf3017d", size = 14540, upload-time = "2025-09-27T18:36:38.761Z" }, - { url = "https://files.pythonhosted.org/packages/aa/5b/bec5aa9bbbb2c946ca2733ef9c4ca91c91b6a24580193e891b5f7dbe8e1e/markupsafe-3.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:26a5784ded40c9e318cfc2bdb30fe164bdb8665ded9cd64d500a34fb42067b1c", size = 15105, upload-time = "2025-09-27T18:36:39.701Z" }, - { url = "https://files.pythonhosted.org/packages/e5/f1/216fc1bbfd74011693a4fd837e7026152e89c4bcf3e77b6692fba9923123/markupsafe-3.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:35add3b638a5d900e807944a078b51922212fb3dedb01633a8defc4b01a3c85f", size = 13906, upload-time = "2025-09-27T18:36:40.689Z" }, - { url = "https://files.pythonhosted.org/packages/38/2f/907b9c7bbba283e68f20259574b13d005c121a0fa4c175f9bed27c4597ff/markupsafe-3.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e1cf1972137e83c5d4c136c43ced9ac51d0e124706ee1c8aa8532c1287fa8795", size = 11622, upload-time = "2025-09-27T18:36:41.777Z" }, - { url = "https://files.pythonhosted.org/packages/9c/d9/5f7756922cdd676869eca1c4e3c0cd0df60ed30199ffd775e319089cb3ed/markupsafe-3.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:116bb52f642a37c115f517494ea5feb03889e04df47eeff5b130b1808ce7c219", size = 12029, upload-time = "2025-09-27T18:36:43.257Z" }, - { url = "https://files.pythonhosted.org/packages/00/07/575a68c754943058c78f30db02ee03a64b3c638586fba6a6dd56830b30a3/markupsafe-3.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:133a43e73a802c5562be9bbcd03d090aa5a1fe899db609c29e8c8d815c5f6de6", size = 24374, upload-time = "2025-09-27T18:36:44.508Z" }, - { url = "https://files.pythonhosted.org/packages/a9/21/9b05698b46f218fc0e118e1f8168395c65c8a2c750ae2bab54fc4bd4e0e8/markupsafe-3.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ccfcd093f13f0f0b7fdd0f198b90053bf7b2f02a3927a30e63f3ccc9df56b676", size = 22980, upload-time = "2025-09-27T18:36:45.385Z" }, - { url = "https://files.pythonhosted.org/packages/7f/71/544260864f893f18b6827315b988c146b559391e6e7e8f7252839b1b846a/markupsafe-3.0.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:509fa21c6deb7a7a273d629cf5ec029bc209d1a51178615ddf718f5918992ab9", size = 21990, upload-time = "2025-09-27T18:36:46.916Z" }, - { url = "https://files.pythonhosted.org/packages/c2/28/b50fc2f74d1ad761af2f5dcce7492648b983d00a65b8c0e0cb457c82ebbe/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:a4afe79fb3de0b7097d81da19090f4df4f8d3a2b3adaa8764138aac2e44f3af1", size = 23784, upload-time = "2025-09-27T18:36:47.884Z" }, - { url = "https://files.pythonhosted.org/packages/ed/76/104b2aa106a208da8b17a2fb72e033a5a9d7073c68f7e508b94916ed47a9/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:795e7751525cae078558e679d646ae45574b47ed6e7771863fcc079a6171a0fc", size = 21588, upload-time = "2025-09-27T18:36:48.82Z" }, - { url = "https://files.pythonhosted.org/packages/b5/99/16a5eb2d140087ebd97180d95249b00a03aa87e29cc224056274f2e45fd6/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:8485f406a96febb5140bfeca44a73e3ce5116b2501ac54fe953e488fb1d03b12", size = 23041, upload-time = "2025-09-27T18:36:49.797Z" }, - { url = "https://files.pythonhosted.org/packages/19/bc/e7140ed90c5d61d77cea142eed9f9c303f4c4806f60a1044c13e3f1471d0/markupsafe-3.0.3-cp313-cp313-win32.whl", hash = "sha256:bdd37121970bfd8be76c5fb069c7751683bdf373db1ed6c010162b2a130248ed", size = 14543, upload-time = "2025-09-27T18:36:51.584Z" }, - { url = "https://files.pythonhosted.org/packages/05/73/c4abe620b841b6b791f2edc248f556900667a5a1cf023a6646967ae98335/markupsafe-3.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:9a1abfdc021a164803f4d485104931fb8f8c1efd55bc6b748d2f5774e78b62c5", size = 15113, upload-time = "2025-09-27T18:36:52.537Z" }, - { url = "https://files.pythonhosted.org/packages/f0/3a/fa34a0f7cfef23cf9500d68cb7c32dd64ffd58a12b09225fb03dd37d5b80/markupsafe-3.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:7e68f88e5b8799aa49c85cd116c932a1ac15caaa3f5db09087854d218359e485", size = 13911, upload-time = "2025-09-27T18:36:53.513Z" }, - { url = "https://files.pythonhosted.org/packages/e4/d7/e05cd7efe43a88a17a37b3ae96e79a19e846f3f456fe79c57ca61356ef01/markupsafe-3.0.3-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:218551f6df4868a8d527e3062d0fb968682fe92054e89978594c28e642c43a73", size = 11658, upload-time = "2025-09-27T18:36:54.819Z" }, - { url = "https://files.pythonhosted.org/packages/99/9e/e412117548182ce2148bdeacdda3bb494260c0b0184360fe0d56389b523b/markupsafe-3.0.3-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:3524b778fe5cfb3452a09d31e7b5adefeea8c5be1d43c4f810ba09f2ceb29d37", size = 12066, upload-time = "2025-09-27T18:36:55.714Z" }, - { url = "https://files.pythonhosted.org/packages/bc/e6/fa0ffcda717ef64a5108eaa7b4f5ed28d56122c9a6d70ab8b72f9f715c80/markupsafe-3.0.3-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4e885a3d1efa2eadc93c894a21770e4bc67899e3543680313b09f139e149ab19", size = 25639, upload-time = "2025-09-27T18:36:56.908Z" }, - { url = "https://files.pythonhosted.org/packages/96/ec/2102e881fe9d25fc16cb4b25d5f5cde50970967ffa5dddafdb771237062d/markupsafe-3.0.3-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8709b08f4a89aa7586de0aadc8da56180242ee0ada3999749b183aa23df95025", size = 23569, upload-time = "2025-09-27T18:36:57.913Z" }, - { url = "https://files.pythonhosted.org/packages/4b/30/6f2fce1f1f205fc9323255b216ca8a235b15860c34b6798f810f05828e32/markupsafe-3.0.3-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b8512a91625c9b3da6f127803b166b629725e68af71f8184ae7e7d54686a56d6", size = 23284, upload-time = "2025-09-27T18:36:58.833Z" }, - { url = "https://files.pythonhosted.org/packages/58/47/4a0ccea4ab9f5dcb6f79c0236d954acb382202721e704223a8aafa38b5c8/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:9b79b7a16f7fedff2495d684f2b59b0457c3b493778c9eed31111be64d58279f", size = 24801, upload-time = "2025-09-27T18:36:59.739Z" }, - { url = "https://files.pythonhosted.org/packages/6a/70/3780e9b72180b6fecb83a4814d84c3bf4b4ae4bf0b19c27196104149734c/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:12c63dfb4a98206f045aa9563db46507995f7ef6d83b2f68eda65c307c6829eb", size = 22769, upload-time = "2025-09-27T18:37:00.719Z" }, - { url = "https://files.pythonhosted.org/packages/98/c5/c03c7f4125180fc215220c035beac6b9cb684bc7a067c84fc69414d315f5/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:8f71bc33915be5186016f675cd83a1e08523649b0e33efdb898db577ef5bb009", size = 23642, upload-time = "2025-09-27T18:37:01.673Z" }, - { url = "https://files.pythonhosted.org/packages/80/d6/2d1b89f6ca4bff1036499b1e29a1d02d282259f3681540e16563f27ebc23/markupsafe-3.0.3-cp313-cp313t-win32.whl", hash = "sha256:69c0b73548bc525c8cb9a251cddf1931d1db4d2258e9599c28c07ef3580ef354", size = 14612, upload-time = "2025-09-27T18:37:02.639Z" }, - { url = "https://files.pythonhosted.org/packages/2b/98/e48a4bfba0a0ffcf9925fe2d69240bfaa19c6f7507b8cd09c70684a53c1e/markupsafe-3.0.3-cp313-cp313t-win_amd64.whl", hash = "sha256:1b4b79e8ebf6b55351f0d91fe80f893b4743f104bff22e90697db1590e47a218", size = 15200, upload-time = "2025-09-27T18:37:03.582Z" }, - { url = "https://files.pythonhosted.org/packages/0e/72/e3cc540f351f316e9ed0f092757459afbc595824ca724cbc5a5d4263713f/markupsafe-3.0.3-cp313-cp313t-win_arm64.whl", hash = "sha256:ad2cf8aa28b8c020ab2fc8287b0f823d0a7d8630784c31e9ee5edea20f406287", size = 13973, upload-time = "2025-09-27T18:37:04.929Z" }, - { url = "https://files.pythonhosted.org/packages/33/8a/8e42d4838cd89b7dde187011e97fe6c3af66d8c044997d2183fbd6d31352/markupsafe-3.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:eaa9599de571d72e2daf60164784109f19978b327a3910d3e9de8c97b5b70cfe", size = 11619, upload-time = "2025-09-27T18:37:06.342Z" }, - { url = "https://files.pythonhosted.org/packages/b5/64/7660f8a4a8e53c924d0fa05dc3a55c9cee10bbd82b11c5afb27d44b096ce/markupsafe-3.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c47a551199eb8eb2121d4f0f15ae0f923d31350ab9280078d1e5f12b249e0026", size = 12029, upload-time = "2025-09-27T18:37:07.213Z" }, - { url = "https://files.pythonhosted.org/packages/da/ef/e648bfd021127bef5fa12e1720ffed0c6cbb8310c8d9bea7266337ff06de/markupsafe-3.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f34c41761022dd093b4b6896d4810782ffbabe30f2d443ff5f083e0cbbb8c737", size = 24408, upload-time = "2025-09-27T18:37:09.572Z" }, - { url = "https://files.pythonhosted.org/packages/41/3c/a36c2450754618e62008bf7435ccb0f88053e07592e6028a34776213d877/markupsafe-3.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:457a69a9577064c05a97c41f4e65148652db078a3a509039e64d3467b9e7ef97", size = 23005, upload-time = "2025-09-27T18:37:10.58Z" }, - { url = "https://files.pythonhosted.org/packages/bc/20/b7fdf89a8456b099837cd1dc21974632a02a999ec9bf7ca3e490aacd98e7/markupsafe-3.0.3-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e8afc3f2ccfa24215f8cb28dcf43f0113ac3c37c2f0f0806d8c70e4228c5cf4d", size = 22048, upload-time = "2025-09-27T18:37:11.547Z" }, - { url = "https://files.pythonhosted.org/packages/9a/a7/591f592afdc734f47db08a75793a55d7fbcc6902a723ae4cfbab61010cc5/markupsafe-3.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:ec15a59cf5af7be74194f7ab02d0f59a62bdcf1a537677ce67a2537c9b87fcda", size = 23821, upload-time = "2025-09-27T18:37:12.48Z" }, - { url = "https://files.pythonhosted.org/packages/7d/33/45b24e4f44195b26521bc6f1a82197118f74df348556594bd2262bda1038/markupsafe-3.0.3-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:0eb9ff8191e8498cca014656ae6b8d61f39da5f95b488805da4bb029cccbfbaf", size = 21606, upload-time = "2025-09-27T18:37:13.485Z" }, - { url = "https://files.pythonhosted.org/packages/ff/0e/53dfaca23a69fbfbbf17a4b64072090e70717344c52eaaaa9c5ddff1e5f0/markupsafe-3.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:2713baf880df847f2bece4230d4d094280f4e67b1e813eec43b4c0e144a34ffe", size = 23043, upload-time = "2025-09-27T18:37:14.408Z" }, - { url = "https://files.pythonhosted.org/packages/46/11/f333a06fc16236d5238bfe74daccbca41459dcd8d1fa952e8fbd5dccfb70/markupsafe-3.0.3-cp314-cp314-win32.whl", hash = "sha256:729586769a26dbceff69f7a7dbbf59ab6572b99d94576a5592625d5b411576b9", size = 14747, upload-time = "2025-09-27T18:37:15.36Z" }, - { url = "https://files.pythonhosted.org/packages/28/52/182836104b33b444e400b14f797212f720cbc9ed6ba34c800639d154e821/markupsafe-3.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:bdc919ead48f234740ad807933cdf545180bfbe9342c2bb451556db2ed958581", size = 15341, upload-time = "2025-09-27T18:37:16.496Z" }, - { url = "https://files.pythonhosted.org/packages/6f/18/acf23e91bd94fd7b3031558b1f013adfa21a8e407a3fdb32745538730382/markupsafe-3.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:5a7d5dc5140555cf21a6fefbdbf8723f06fcd2f63ef108f2854de715e4422cb4", size = 14073, upload-time = "2025-09-27T18:37:17.476Z" }, - { url = "https://files.pythonhosted.org/packages/3c/f0/57689aa4076e1b43b15fdfa646b04653969d50cf30c32a102762be2485da/markupsafe-3.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:1353ef0c1b138e1907ae78e2f6c63ff67501122006b0f9abad68fda5f4ffc6ab", size = 11661, upload-time = "2025-09-27T18:37:18.453Z" }, - { url = "https://files.pythonhosted.org/packages/89/c3/2e67a7ca217c6912985ec766c6393b636fb0c2344443ff9d91404dc4c79f/markupsafe-3.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1085e7fbddd3be5f89cc898938f42c0b3c711fdcb37d75221de2666af647c175", size = 12069, upload-time = "2025-09-27T18:37:19.332Z" }, - { url = "https://files.pythonhosted.org/packages/f0/00/be561dce4e6ca66b15276e184ce4b8aec61fe83662cce2f7d72bd3249d28/markupsafe-3.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1b52b4fb9df4eb9ae465f8d0c228a00624de2334f216f178a995ccdcf82c4634", size = 25670, upload-time = "2025-09-27T18:37:20.245Z" }, - { url = "https://files.pythonhosted.org/packages/50/09/c419f6f5a92e5fadde27efd190eca90f05e1261b10dbd8cbcb39cd8ea1dc/markupsafe-3.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fed51ac40f757d41b7c48425901843666a6677e3e8eb0abcff09e4ba6e664f50", size = 23598, upload-time = "2025-09-27T18:37:21.177Z" }, - { url = "https://files.pythonhosted.org/packages/22/44/a0681611106e0b2921b3033fc19bc53323e0b50bc70cffdd19f7d679bb66/markupsafe-3.0.3-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f190daf01f13c72eac4efd5c430a8de82489d9cff23c364c3ea822545032993e", size = 23261, upload-time = "2025-09-27T18:37:22.167Z" }, - { url = "https://files.pythonhosted.org/packages/5f/57/1b0b3f100259dc9fffe780cfb60d4be71375510e435efec3d116b6436d43/markupsafe-3.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e56b7d45a839a697b5eb268c82a71bd8c7f6c94d6fd50c3d577fa39a9f1409f5", size = 24835, upload-time = "2025-09-27T18:37:23.296Z" }, - { url = "https://files.pythonhosted.org/packages/26/6a/4bf6d0c97c4920f1597cc14dd720705eca0bf7c787aebc6bb4d1bead5388/markupsafe-3.0.3-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:f3e98bb3798ead92273dc0e5fd0f31ade220f59a266ffd8a4f6065e0a3ce0523", size = 22733, upload-time = "2025-09-27T18:37:24.237Z" }, - { url = "https://files.pythonhosted.org/packages/14/c7/ca723101509b518797fedc2fdf79ba57f886b4aca8a7d31857ba3ee8281f/markupsafe-3.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5678211cb9333a6468fb8d8be0305520aa073f50d17f089b5b4b477ea6e67fdc", size = 23672, upload-time = "2025-09-27T18:37:25.271Z" }, - { url = "https://files.pythonhosted.org/packages/fb/df/5bd7a48c256faecd1d36edc13133e51397e41b73bb77e1a69deab746ebac/markupsafe-3.0.3-cp314-cp314t-win32.whl", hash = "sha256:915c04ba3851909ce68ccc2b8e2cd691618c4dc4c4232fb7982bca3f41fd8c3d", size = 14819, upload-time = "2025-09-27T18:37:26.285Z" }, - { url = "https://files.pythonhosted.org/packages/1a/8a/0402ba61a2f16038b48b39bccca271134be00c5c9f0f623208399333c448/markupsafe-3.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4faffd047e07c38848ce017e8725090413cd80cbc23d86e55c587bf979e579c9", size = 15426, upload-time = "2025-09-27T18:37:27.316Z" }, - { url = "https://files.pythonhosted.org/packages/70/bc/6f1c2f612465f5fa89b95bead1f44dcb607670fd42891d8fdcd5d039f4f4/markupsafe-3.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa", size = 14146, upload-time = "2025-09-27T18:37:28.327Z" }, -] - [[package]] name = "mcp" version = "1.26.0" From c02810f0d419437d58fd45c477eb38caad0037e6 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Sun, 29 Mar 2026 00:21:13 +0700 Subject: [PATCH 194/412] docs: add frontend.md spoke doc, update architecture/ipc/token-streaming for React SPA --- docs/frontend.md | 198 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 docs/frontend.md diff --git a/docs/frontend.md b/docs/frontend.md new file mode 100644 index 0000000..d290de6 --- /dev/null +++ b/docs/frontend.md @@ -0,0 +1,198 @@ +# Frontend + +React 19 + Zustand 5 + Vite 6 SPA. Python serves the built bundle as static +files — no Node.js in production. + +> Parent doc: [architecture.md](./architecture.md) + +--- + +## Directory Layout + +``` +frontend/ # source tree (alongside koan/ Python package) +├── package.json +├── tsconfig.json +├── vite.config.ts # proxies /api/*, /events, /mcp/* to Python in dev +├── index.html # Vite entry point +├── src/ +│ ├── main.tsx # mounts into #root; imports global CSS +│ ├── App.tsx # top-level layout; owns SSE connection lifecycle +│ ├── store/ +│ │ ├── index.ts # single Zustand store (the app-db equivalent) +│ │ └── selectors.ts # derived state computed from store slices +│ ├── sse/ +│ │ └── connect.ts # EventSource wrapper: event dispatch + store writes +│ ├── api/ +│ │ └── client.ts # typed fetch wrappers for POST/PUT endpoints +│ ├── components/ # one file per UI component (see Component Mapping) +│ ├── hooks/ +│ │ ├── useElapsed.ts # replaces manual setInterval + DOM attribute scanning +│ │ └── useAutoScroll.ts +│ └── styles/ +│ ├── variables.css # CSS custom properties (ported verbatim) +│ ├── layout.css +│ └── components.css # components.css + animations.css merged +└── dist/ # Vite build output (gitignored) + +koan/web/static/app/ # Vite build target (committed build artifacts) +``` + +--- + +## Dev vs Production + +**Development:** Vite dev server proxies all backend traffic. + +``` +vite (:5173) → /api/*, /events, /mcp/* → python (:8000) +``` + +SSE requires buffering disabled in the proxy — `vite.config.ts` sets +`x-accel-buffering: no` on the `/events` proxy response. Without this, SSE +events arrive in batches rather than incrementally. + +**Production:** `uv run koan` only. Python serves the built bundle. + +``` +python (:8000) → /static/app/* → frontend/dist/ (Vite build) + → /api/*, /events, /mcp/* → existing routes (unchanged) + → /* (catch-all) → index.html (SPA fallback) +``` + +Build command: `cd frontend && npm run build` +Output: `koan/web/static/app/` (matches `base: '/static/app/'` in `vite.config.ts`) + +**Starlette route order** in `create_app()` is significant — first match wins: + +``` +/mcp → MCP endpoint +/api/* → API handlers +/events → SSE stream +/static/app → StaticFiles (frontend/dist/) +/static → other static assets +/{path:path} → spa_fallback (index.html) — MUST be last +``` + +--- + +## State Model + +Single Zustand store mirrors backend `AppState`. All live state enters through +the SSE bridge — nothing else writes to the store from outside the component +tree. + +Key slices: + +| Slice | Type | Source SSE event | +|---|---|---| +| `connected` | `boolean` | EventSource open/error | +| `runStarted` | `boolean` | derived from first `phase` event | +| `phase` / `donePhases` | `string` / `string[]` | `phase` | +| `primaryAgent` | `AgentInfo \| null` | `subagent`, `subagent-idle` | +| `scouts` | `Record` | `agents` (full replace) | +| `activityLog` | `ActivityEntry[]` | `logs` (append-only) | +| `streamBuffer` | `string` | `token-delta` / `token-clear` | +| `activeInteraction` | `Interaction \| null` | `interaction` | +| `artifacts` | `ArtifactFile[]` | `artifacts` | +| `completion` | `CompletionInfo \| null` | `pipeline-end` | +| `notifications` | `NotificationEntry[]` | `notification` | + +`runStarted` gates top-level view (landing vs live). No router library — a +conditional render covers the binary choice. + +--- + +## SSE Bridge + +`connectSSE(store)` in `sse/connect.ts` opens an `EventSource('/events')` and +wires every event type to a store action. Returns the `EventSource`; `App.tsx` +owns the reconnect lifecycle (exponential backoff, capped at 5 s). + +**snake_case → camelCase mapping** happens at the bridge boundary for all agent +payloads (`agent_id` → `agentId`, `started_at_ms` → `startedAt`, etc.). + +**`phase` event side effect:** `setPhase()` also sets `runStarted = true` and +derives `donePhases`. This ensures a mid-run page reload (which replays the +buffered `phase` event) restores the live view without a full reload. + +Stateful events (`phase`, `subagent`, `agents`, `artifacts`, `intake-progress`, +`pipeline-end`) are cached server-side and replayed to reconnecting clients. + +--- + +## Backend Contract + +`push_sse()` emits raw JSON — no `html` or `target` fields. `_render_fragment()` +and all Jinja2 templates are deleted. Three builder functions produce the +JSON payloads: + +| Function | Event | Notes | +|---|---|---| +| `_build_subagent_json(app_state)` | `subagent` | Returns `{"agent_id": None}` when idle | +| `_build_agents_json(app_state)` | `agents` | Scout list; full replace on each event | +| `_build_artifacts_json(app_state)` | `artifacts` | Flat list; client groups into tree | + +All time values are UTC epoch milliseconds (`started_at_ms`). All token counts +are raw integers. Formatting is done client-side (`useElapsed`, `formatTokens`). + +`app_state.phase` assignment — previously a side effect inside +`_render_fragment()` — is preserved in `push_sse()` for the `phase` event +branch. + +Settings endpoints (`/api/settings/body`, `/api/settings/profile-form`, +`/api/settings/installation-form`) return JSON. `SettingsOverlay.tsx` owns +form state and cascade dropdown logic. + +--- + +## Component Mapping + +| Jinja2 template | React component | Primary store subscription | +|---|---|---| +| `live.html` | `App.tsx` | `runStarted` | +| `landing.html` | `LandingPage.tsx` | `runStarted` (negated) | +| `status_sidebar.html` | `StatusSidebar.tsx` | `primaryAgent`, `phase`, `intakeProgress` | +| `monitor.html` | `AgentMonitor.tsx` | `scouts` | +| `artifacts_sidebar.html` | `ArtifactsSidebar.tsx` | `artifacts` | +| `interaction_ask.html` | `AskWizard.tsx` | `activeInteraction` | +| `interaction_workflow.html` | `WorkflowDecision.tsx` | `activeInteraction` | +| `interaction_artifact_review.html` | `ArtifactReview.tsx` | `activeInteraction` | +| `completion.html` | `Completion.tsx` | `completion` | +| `settings_body.html` | `SettingsOverlay.tsx` | `settingsOpen` + local state | +| Toast JS in `koan.js` | `Notification.tsx` | `notifications` | + +--- + +## Known Gaps (v1) + +**`story` events** — emitted during execution phase with story lifecycle status. +Not implemented in v1: execution phase shows only primary agent status and +activity feed. Add a `stories` store slice and `StoryProgress` component when +designing the execution phase UI. + +**`frozen-logs` events** — snapshot of activity log before orchestrator spawn. +Ignored in v1; the activity feed is append-only. Add a log boundary marker in +a follow-up if needed. + +**`intake-progress` events** — the SSE bridge and `StatusSidebar` are wired to +display intake sub-phase, confidence, and summary. However, no Python code +currently emits `push_sse(app_state, "intake-progress", ...)`. The `push_sse()` +handler and `STATEFUL_EVENTS` entry exist but are unreachable. When adding the +emission call, use camelCase field names (`subPhase`, not `sub_phase`) since the +bridge passes through without renaming. + +--- + +## Dependencies + +```json +{ + "dependencies": { "react": "^19", "react-dom": "^19", "zustand": "^5" }, + "devDependencies": { "typescript": "^5.7", "vite": "^6", "@vitejs/plugin-react": "^4" } +} +``` + +No router (two views, conditional render). No fetch library (typed `fetch` +wrappers in `api/client.ts`). No CSS framework (existing design tokens port +directly via CSS custom properties). From 59ee8b4f4b747ea8388b0bfd353ed4c444690a61 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 12:51:45 +0700 Subject: [PATCH 195/412] add projection engine and event payload builders --- koan/events.py | 176 ++++++++++++++++++++ koan/projections.py | 383 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 559 insertions(+) create mode 100644 koan/events.py create mode 100644 koan/projections.py diff --git a/koan/events.py b/koan/events.py new file mode 100644 index 0000000..dc64114 --- /dev/null +++ b/koan/events.py @@ -0,0 +1,176 @@ +# Event payload builders -- bridges koan domain types into projection event payloads. +# Imports AgentState, RunnerDiagnostic, list_artifacts, etc. +# koan/projections.py does NOT import from here. + +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from .runners.base import RunnerDiagnostic + from .state import AgentState + + +def build_agent_spawned(agent: AgentState) -> dict: + return { + "agent_id": agent.agent_id, + "role": agent.role, + "model": agent.model, + "is_primary": agent.is_primary, + "started_at_ms": int(agent.started_at.timestamp() * 1000), + } + + +def build_agent_exited( + exit_code: int, + error: str | None = None, + usage: dict | None = None, +) -> dict: + result: dict = {"exit_code": exit_code} + if error is not None: + result["error"] = error + if usage is not None: + result["usage"] = usage + return result + + +def build_agent_spawn_failed(role: str, diagnostic: RunnerDiagnostic) -> dict: + return { + "role": role, + "error_code": diagnostic.code, + "message": diagnostic.message, + "details": diagnostic.details, + } + + +def build_step_advanced( + step: int, + step_name: str, + usage: dict | None = None, +) -> dict: + result: dict = {"step": step, "step_name": step_name} + if usage is not None: + result["usage"] = usage + return result + + +def build_tool_called( + call_id: str, + tool: str, + args: dict | str, + summary: str = "", +) -> dict: + return { + "call_id": call_id, + "tool": tool, + "args": args, + "summary": summary, + } + + +def build_tool_completed( + call_id: str, + tool: str, + result: str | None = None, +) -> dict: + payload: dict = {"call_id": call_id, "tool": tool} + if result is not None: + payload["result"] = result + return payload + + +def build_artifact_diff( + old: dict[str, dict], + new_artifacts: list[dict], +) -> list[tuple[str, dict]]: + """Compare old artifacts dict (from projection) with new list from list_artifacts(). + + Returns list of (event_type, payload) tuples for created/modified/removed entries. + modified_at is converted from float seconds to int milliseconds. + """ + events: list[tuple[str, dict]] = [] + + # Build new dict keyed by path, converting modified_at to ms + new_by_path: dict[str, dict] = {} + for a in new_artifacts: + path = a["path"] + new_by_path[path] = { + "path": path, + "size": a["size"], + "modified_at": int(a["modified_at"] * 1000), + } + + # Created or modified + for path, new_entry in new_by_path.items(): + if path not in old: + events.append(("artifact_created", new_entry)) + elif ( + old[path].get("modified_at") != new_entry["modified_at"] + or old[path].get("size") != new_entry["size"] + ): + events.append(("artifact_modified", new_entry)) + + # Removed + for path in old: + if path not in new_by_path: + events.append(("artifact_removed", {"path": path})) + + return events + + +def build_questions_asked(token: str, questions: list) -> dict: + return {"token": token, "questions": questions} + + +def build_questions_answered( + token: str, + answers: list | None = None, + cancelled: bool = False, +) -> dict: + result: dict = {"token": token, "cancelled": cancelled} + if answers is not None: + result["answers"] = answers + return result + + +def build_artifact_review_requested( + token: str, + path: str, + description: str, + content: str, +) -> dict: + return { + "token": token, + "path": path, + "description": description, + "content": content, + } + + +def build_artifact_reviewed( + token: str, + accepted: bool | None = None, + response: str | None = None, + cancelled: bool = False, +) -> dict: + result: dict = {"token": token, "cancelled": cancelled} + if accepted is not None: + result["accepted"] = accepted + if response is not None: + result["response"] = response + return result + + +def build_workflow_decision_requested(token: str, chat_turns: list) -> dict: + return {"token": token, "chat_turns": chat_turns} + + +def build_workflow_decided( + token: str, + decision: dict | None = None, + cancelled: bool = False, +) -> dict: + result: dict = {"token": token, "cancelled": cancelled} + if decision is not None: + result["decision"] = decision + return result diff --git a/koan/projections.py b/koan/projections.py new file mode 100644 index 0000000..2d045d7 --- /dev/null +++ b/koan/projections.py @@ -0,0 +1,383 @@ +# Projection event-sourcing machinery. +# Pure -- zero koan domain imports. All fold logic lives here. + +from __future__ import annotations + +import asyncio +import logging +from datetime import datetime, timezone +from typing import Literal + +from pydantic import BaseModel, Field + +log = logging.getLogger("koan.projections") + +EventType = Literal[ + # Lifecycle + "phase_started", + "agent_spawned", + "agent_spawn_failed", + "agent_step_advanced", + "agent_exited", + "workflow_completed", + # Activity + "tool_called", + "tool_completed", + "thinking", + "stream_delta", + "stream_cleared", + # Interactions + "questions_asked", + "questions_answered", + "artifact_review_requested", + "artifact_reviewed", + "workflow_decision_requested", + "workflow_decided", + # Resources + "artifact_created", + "artifact_modified", + "artifact_removed", +] + + +class VersionedEvent(BaseModel): + version: int + event_type: str # EventType string; stored as str so unknown types deserialise safely + timestamp: str + agent_id: str | None = None + payload: dict + + +class AgentProjection(BaseModel): + agent_id: str + role: str + model: str | None = None + step: int = 0 + step_name: str = "" + input_tokens: int = 0 + output_tokens: int = 0 + + +class Projection(BaseModel): + # Run state + run_started: bool = False + phase: str = "" + + # Agents + primary_agent: AgentProjection | None = None + scouts: dict[str, AgentProjection] = Field(default_factory=dict) + completed_agents: list[AgentProjection] = Field(default_factory=list) + + # Activity (raw events appended as-is: tool_called, tool_completed, thinking) + activity_log: list[dict] = Field(default_factory=list) + stream_buffer: str = "" + + # Interactions + active_interaction: dict | None = None + + # Resources + artifacts: dict[str, dict] = Field(default_factory=dict) # keyed by path + notifications: list[dict] = Field(default_factory=list) # derived from error events + + # Completion + completion: dict | None = None + + +def _utcnow() -> str: + return datetime.now(timezone.utc).isoformat() + + +def _accumulate_usage(agent: AgentProjection, usage: dict | None) -> AgentProjection: + if not usage: + return agent + return agent.model_copy(update={ + "input_tokens": agent.input_tokens + usage.get("input_tokens", 0), + "output_tokens": agent.output_tokens + usage.get("output_tokens", 0), + }) + + +def fold(projection: Projection, event: VersionedEvent) -> Projection: + """Pure fold: (Projection, VersionedEvent) -> Projection. + + Unknown event types return projection unchanged with a logged warning. + Unknown agent_ids for agent-specific events return projection unchanged with a logged warning. + Any exception within a handler returns projection unchanged, with the exception logged. + The event is always appended to the log before fold() is called; fold exceptions do not + prevent appending. + """ + event_type = event.event_type + payload = event.payload + agent_id = event.agent_id + + try: + match event_type: + + # ── Lifecycle ────────────────────────────────────────────────────── + + case "phase_started": + return projection.model_copy(update={ + "phase": payload.get("phase", ""), + "run_started": True, + }) + + case "agent_spawned": + eid = agent_id or payload.get("agent_id", "") + new_agent = AgentProjection( + agent_id=eid, + role=payload.get("role", ""), + model=payload.get("model"), + step=0, + ) + if payload.get("is_primary", True): + return projection.model_copy(update={"primary_agent": new_agent}) + else: + new_scouts = dict(projection.scouts) + new_scouts[eid] = new_agent + return projection.model_copy(update={"scouts": new_scouts}) + + case "agent_spawn_failed": + notification = { + "type": "agent_spawn_failed", + "role": payload.get("role", ""), + "error_code": payload.get("error_code", ""), + "message": payload.get("message", ""), + "details": payload.get("details"), + } + return projection.model_copy(update={ + "notifications": [*projection.notifications, notification], + }) + + case "agent_step_advanced": + usage = payload.get("usage") + step = payload.get("step", 0) + step_name = payload.get("step_name", "") + + if projection.primary_agent and projection.primary_agent.agent_id == agent_id: + updated = projection.primary_agent.model_copy(update={ + "step": step, + "step_name": step_name, + }) + updated = _accumulate_usage(updated, usage) + return projection.model_copy(update={"primary_agent": updated}) + elif agent_id and agent_id in projection.scouts: + updated = projection.scouts[agent_id].model_copy(update={ + "step": step, + "step_name": step_name, + }) + updated = _accumulate_usage(updated, usage) + new_scouts = dict(projection.scouts) + new_scouts[agent_id] = updated + return projection.model_copy(update={"scouts": new_scouts}) + else: + log.warning("fold agent_step_advanced: unknown agent_id=%s", agent_id) + return projection + + case "agent_exited": + usage = payload.get("usage") + error = payload.get("error") + + new_notifications = list(projection.notifications) + if error: + new_notifications.append({ + "type": "agent_exited_error", + "agent_id": agent_id, + "exit_code": payload.get("exit_code", 1), + "error": error, + }) + + new_completed = list(projection.completed_agents) + + if projection.primary_agent and projection.primary_agent.agent_id == agent_id: + # Accumulate final tokens, preserve in completed_agents, then clear + final_agent = _accumulate_usage(projection.primary_agent, usage) + new_completed.append(final_agent) + return projection.model_copy(update={ + "primary_agent": None, + "completed_agents": new_completed, + "notifications": new_notifications, + }) + elif agent_id and agent_id in projection.scouts: + final_agent = _accumulate_usage(projection.scouts[agent_id], usage) + new_completed.append(final_agent) + new_scouts = {k: v for k, v in projection.scouts.items() if k != agent_id} + return projection.model_copy(update={ + "scouts": new_scouts, + "completed_agents": new_completed, + "notifications": new_notifications, + }) + else: + # Unknown agent_id: return unchanged per plan semantics. + # Error notifications are still recorded — the fact of an + # error exit is worth preserving even if the agent wasn't + # tracked (e.g. late-arriving event after projection reset). + if new_notifications != projection.notifications: + log.warning("fold agent_exited: unknown agent_id=%s, preserving error notification", agent_id) + return projection.model_copy(update={"notifications": new_notifications}) + log.warning("fold agent_exited: unknown agent_id=%s", agent_id) + return projection + + case "workflow_completed": + return projection.model_copy(update={"completion": payload}) + + # ── Activity ─────────────────────────────────────────────────────── + + case "tool_called": + entry = {"event_type": event_type, "agent_id": agent_id, **payload} + return projection.model_copy(update={ + "activity_log": [*projection.activity_log, entry], + }) + + case "tool_completed": + entry = {"event_type": event_type, "agent_id": agent_id, **payload} + return projection.model_copy(update={ + "activity_log": [*projection.activity_log, entry], + }) + + case "thinking": + entry = {"event_type": event_type, "agent_id": agent_id, **payload} + return projection.model_copy(update={ + "activity_log": [*projection.activity_log, entry], + }) + + case "stream_delta": + return projection.model_copy(update={ + "stream_buffer": projection.stream_buffer + payload.get("delta", ""), + }) + + case "stream_cleared": + return projection.model_copy(update={"stream_buffer": ""}) + + # ── Interactions ─────────────────────────────────────────────────── + + case "questions_asked": + active = {"interaction_type": "questions_asked", **payload} + return projection.model_copy(update={"active_interaction": active}) + + case "questions_answered": + return projection.model_copy(update={"active_interaction": None}) + + case "artifact_review_requested": + active = {"interaction_type": "artifact_review_requested", **payload} + return projection.model_copy(update={"active_interaction": active}) + + case "artifact_reviewed": + return projection.model_copy(update={"active_interaction": None}) + + case "workflow_decision_requested": + active = {"interaction_type": "workflow_decision_requested", **payload} + return projection.model_copy(update={"active_interaction": active}) + + case "workflow_decided": + return projection.model_copy(update={"active_interaction": None}) + + # ── Resources ────────────────────────────────────────────────────── + + case "artifact_created": + path = payload.get("path", "") + new_artifacts = dict(projection.artifacts) + new_artifacts[path] = { + "path": path, + "size": payload.get("size", 0), + "modified_at": payload.get("modified_at", 0), + } + return projection.model_copy(update={"artifacts": new_artifacts}) + + case "artifact_modified": + path = payload.get("path", "") + new_artifacts = dict(projection.artifacts) + new_artifacts[path] = { + "path": path, + "size": payload.get("size", 0), + "modified_at": payload.get("modified_at", 0), + } + return projection.model_copy(update={"artifacts": new_artifacts}) + + case "artifact_removed": + path = payload.get("path", "") + new_artifacts = {k: v for k, v in projection.artifacts.items() if k != path} + return projection.model_copy(update={"artifacts": new_artifacts}) + + case _: + log.warning("fold: unknown event_type=%r", event_type) + return projection + + except Exception: + log.exception( + "fold: exception handling event_type=%r version=%d event=%r", + event_type, event.version, event, + ) + return projection + + +class ProjectionStore: + """In-memory versioned event log + materialized projection + asyncio.Queue subscribers.""" + + def __init__(self) -> None: + self.events: list[VersionedEvent] = [] + self.projection: Projection = Projection() + self.version: int = 0 + self.subscribers: list[asyncio.Queue] = [] + + def push_event( + self, + event_type: str, + payload: dict, + agent_id: str | None = None, + ) -> VersionedEvent: + """Append event, fold into projection, broadcast to subscribers.""" + self.version += 1 + event = VersionedEvent( + version=self.version, + event_type=event_type, + timestamp=_utcnow(), + agent_id=agent_id, + payload=payload, + ) + self.events.append(event) + + # Fold — event is in the log regardless of fold success + try: + self.projection = fold(self.projection, event) + except Exception: + log.exception( + "ProjectionStore: fold raised for event version=%d type=%r", + self.version, event_type, + ) + + # Broadcast — snapshot list to avoid RuntimeError on concurrent subscribe/unsubscribe + for q in list(self.subscribers): + try: + q.put_nowait(event) + except asyncio.QueueFull: + log.warning( + "ProjectionStore: subscriber queue full, dropping event version=%d", + self.version, + ) + except Exception: + pass + + return event + + def get_snapshot(self) -> dict: + """Return {version, state} for SSE snapshot.""" + return { + "version": self.version, + "state": self.projection.model_dump(), + } + + def events_since(self, version: int) -> list[VersionedEvent]: + """Return all events with version > given version.""" + return [e for e in self.events if e.version > version] + + def subscribe(self) -> asyncio.Queue: + """Create and register a subscriber queue.""" + q: asyncio.Queue = asyncio.Queue() + self.subscribers.append(q) + return q + + def unsubscribe(self, queue: asyncio.Queue) -> None: + """Remove a subscriber queue.""" + try: + self.subscribers.remove(queue) + except ValueError: + pass From 088cd30922ee89c601582bae9e28d35884ffdc55 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 12:51:52 +0700 Subject: [PATCH 196/412] add KOAN_MCP_TOOLS constant and per-runner tool name normalization --- koan/runners/base.py | 19 +++++++++++++++++++ koan/runners/claude.py | 40 +++++++++++++++++++++++++++++++++++++--- koan/runners/codex.py | 25 +++++++++++++++++++++---- koan/runners/gemini.py | 24 ++++++++++++++++++++++-- 4 files changed, 99 insertions(+), 9 deletions(-) diff --git a/koan/runners/base.py b/koan/runners/base.py index 1b12761..b183d73 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -49,3 +49,22 @@ def build_command( def list_models(self, binary: str) -> list[ModelInfo]: ... def parse_stream_event(self, line: str) -> list[StreamEvent]: ... + + +# Tool names registered in koan's MCP server. Runners filter stdout tool events +# whose names appear here to prevent duplicate tool_called/tool_completed events +# (the MCP endpoint is the authoritative source for koan MCP calls). +# +# MAINTENANCE: this set must stay in sync with the @mcp.tool() registrations in +# koan/web/mcp_endpoint.py. It lives in base.py (not mcp_endpoint.py) to avoid a +# circular import (mcp_endpoint imports from subagent which imports from runners). +# When adding a new koan MCP tool to mcp_endpoint.py, update this set too. +KOAN_MCP_TOOLS: frozenset[str] = frozenset({ + "koan_complete_step", + "koan_set_confidence", + "koan_request_scouts", + "koan_ask_question", + "koan_review_artifact", + "koan_propose_workflow", + "koan_set_next_phase", +}) diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 7a42799..373c0aa 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -7,7 +7,7 @@ from pathlib import Path from ..types import AgentInstallation, ModelInfo, ThinkingMode -from .base import RunnerDiagnostic, RunnerError, StreamEvent +from .base import KOAN_MCP_TOOLS, RunnerDiagnostic, RunnerError, StreamEvent THINKING_BUDGET: dict[ThinkingMode, int] = { "low": 1024, @@ -16,6 +16,28 @@ "xhigh": 32000, } +# Canonical tool name mappings for Claude's tool vocabulary. +_TOOL_NAME_MAP: dict[str, str] = { + "Read": "read", + "Write": "write", + "Edit": "edit", + "MultiEdit": "edit", + "Bash": "bash", + "Glob": "grep", + "Grep": "grep", + "LS": "ls", + "TodoRead": "todo_read", + "TodoWrite": "todo_write", + "WebFetch": "web_fetch", + "WebSearch": "web_search", +} + + +def _normalize_tool_name(name: str | None) -> str | None: + if name is None: + return None + return _TOOL_NAME_MAP.get(name, name.lower()) + class ClaudeRunner: name = "claude" @@ -118,13 +140,25 @@ def _parse_assistant(self, data: dict) -> list[StreamEvent]: if block_type == "text": events.append(StreamEvent(type="token_delta", content=block.get("text", ""))) elif block_type == "tool_use": + raw_name = block.get("name") + canonical = _normalize_tool_name(raw_name) + # Drop koan MCP tool events -- the MCP endpoint is authoritative + if canonical in KOAN_MCP_TOOLS: + continue events.append(StreamEvent( type="tool_call", - tool_name=block.get("name"), + tool_name=canonical, tool_args=block.get("input"), )) elif block_type == "thinking": - events.append(StreamEvent(type="thinking", is_thinking=True)) + # Claude stream-json thinking blocks use the "thinking" key for content, + # not "text" (which is used by text blocks). Fall back to "text" as a + # safety net for format variations. + events.append(StreamEvent( + type="thinking", + is_thinking=True, + content=block.get("thinking") or block.get("text"), + )) return events def _parse_result(self, data: dict) -> StreamEvent | None: diff --git a/koan/runners/codex.py b/koan/runners/codex.py index ffe9d81..e3895e6 100644 --- a/koan/runners/codex.py +++ b/koan/runners/codex.py @@ -6,7 +6,22 @@ import json from ..types import AgentInstallation, ModelInfo, ThinkingMode -from .base import RunnerDiagnostic, RunnerError, StreamEvent +from .base import KOAN_MCP_TOOLS, RunnerDiagnostic, RunnerError, StreamEvent + +# Canonical tool name mappings for Codex's tool vocabulary. +_TOOL_NAME_MAP: dict[str, str] = { + "read_file": "read", + "write_file": "write", + "apply_patch": "edit", + "shell": "bash", + "search_files": "grep", +} + + +def _normalize_tool_name(name: str | None) -> str | None: + if name is None: + return None + return _TOOL_NAME_MAP.get(name, name.lower()) class CodexRunner: @@ -66,8 +81,6 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: if evt_type == "turn.started": return [StreamEvent(type="thinking", is_thinking=True)] if evt_type == "turn.completed": - usage = data.get("usage") or {} - # Emit token counts when available content = data.get("answer") return [StreamEvent(type="turn_complete", is_thinking=True, content=content)] if evt_type == "turn.failed": @@ -82,9 +95,13 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: if text: return [StreamEvent(type="token_delta", content=text)] elif item_type == "function_call": + raw_name = item.get("name") or item.get("call_id", "tool") + canonical = _normalize_tool_name(raw_name) + if canonical in KOAN_MCP_TOOLS: + return [] return [StreamEvent( type="tool_call", - tool_name=item.get("name") or item.get("call_id", "tool"), + tool_name=canonical, content=item.get("arguments", ""), )] elif item_type == "function_call_output": diff --git a/koan/runners/gemini.py b/koan/runners/gemini.py index cd448c9..a37edcf 100644 --- a/koan/runners/gemini.py +++ b/koan/runners/gemini.py @@ -7,7 +7,23 @@ from pathlib import Path from ..types import AgentInstallation, ModelInfo, ThinkingMode -from .base import RunnerDiagnostic, RunnerError, StreamEvent +from .base import KOAN_MCP_TOOLS, RunnerDiagnostic, RunnerError, StreamEvent + +# Canonical tool name mappings for Gemini's tool vocabulary. +_TOOL_NAME_MAP: dict[str, str] = { + "read_file": "read", + "write_file": "write", + "replace_file_content": "edit", + "run_bash_command": "bash", + "search_in_file": "grep", + "list_directory": "ls", +} + + +def _normalize_tool_name(name: str | None) -> str | None: + if name is None: + return None + return _TOOL_NAME_MAP.get(name, name.lower()) class GeminiRunner: @@ -77,9 +93,13 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: if evt_type == "message": return [StreamEvent(type="token_delta", content=data.get("content", ""))] if evt_type == "tool_use": + raw_name = data.get("name") + canonical = _normalize_tool_name(raw_name) + if canonical in KOAN_MCP_TOOLS: + return [] return [StreamEvent( type="tool_call", - tool_name=data.get("name"), + tool_name=canonical, tool_args=data.get("input"), )] if evt_type == "result": From 16130210d01102abbfe99aeaa509fbc9fe97033d Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 12:52:00 +0700 Subject: [PATCH 197/412] replace push_sse with versioned projection events across backend --- koan/driver.py | 187 +++------------ koan/state.py | 4 +- koan/subagent.py | 228 +++++++++--------- koan/web/app.py | 55 ++++- koan/web/interactions.py | 48 +++- koan/web/mcp_endpoint.py | 484 ++++++++++++++++++++++----------------- 6 files changed, 503 insertions(+), 503 deletions(-) diff --git a/koan/driver.py b/koan/driver.py index d44ad26..117dfcb 100644 --- a/koan/driver.py +++ b/koan/driver.py @@ -5,7 +5,7 @@ import time from datetime import datetime, timezone -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING import aiofiles @@ -20,6 +20,7 @@ save_epic_state, save_story_state, ) +from .events import build_artifact_diff from .lib.phase_dag import ( PHASE_DESCRIPTIONS, get_successor_phases, @@ -83,145 +84,19 @@ def route_from_state(stories: list[dict]) -> dict: return {"action": "error", "error": "no actionable stories found"} -# -- JSON payload builders ---------------------------------------------------- +# -- Artifact diff helper ------------------------------------------------------ -def _build_subagent_json(app_state: AppState) -> dict: - """Return primary agent state as a JSON-serialisable dict. - - Raw values only — no pre-formatted strings. The React client formats - elapsed time via useElapsed() and token counts via formatTokens(). - step_name is resolved here because the client has no access to - phase_module.STEP_NAMES. - """ - for agent in app_state.agents.values(): - if not agent.is_primary: - continue - return { - "agent_id": agent.agent_id, - "role": agent.role, - "model": agent.model, - "step": agent.step, - # Resolved server-side; falls back to "step N" if not in STEP_NAMES. - "step_name": ( - agent.phase_module.STEP_NAMES.get(agent.step, f"step {agent.step}") - if agent.phase_module and hasattr(agent.phase_module, "STEP_NAMES") - else f"step {agent.step}" - ), - # UTC epoch milliseconds; client uses Date.now() - startedAt for elapsed. - "started_at_ms": int(agent.started_at.timestamp() * 1000), - # Raw counts; client formats as "12k / 4k" or similar. - "tokens_sent": agent.token_count.get("sent", 0), - "tokens_received": agent.token_count.get("received", 0), - } - return {"agent_id": None} # no primary agent active - - -def _build_agents_json(app_state: AppState) -> list[dict]: - """Return scout (non-primary) agents as a list for the monitor table. - - Same raw-values convention as _build_subagent_json. - agent_id is included so the frontend can key the Record. - """ - result = [] - for agent in app_state.agents.values(): - if agent.is_primary: - continue - result.append({ - "agent_id": agent.agent_id, - "role": agent.role, - "model": agent.model, - "step": agent.step, - "step_name": f"step {agent.step}", # scouts don't have STEP_NAMES - "started_at_ms": int(agent.started_at.timestamp() * 1000), - "tokens_sent": agent.token_count.get("sent", 0), - "tokens_received": agent.token_count.get("received", 0), - }) - return result - - -def _build_artifacts_json(app_state: AppState) -> list[dict]: - """Return artifact list as JSON-serialisable dicts. - - Flat list; the frontend groups into a directory tree via the - useArtifactTree selector. Sizes are raw bytes (client formats). - modifiedAt is UTC epoch milliseconds for consistency with startedAt. - """ +def _push_artifact_diff(app_state: AppState) -> None: + """Scan epic artifacts and emit per-file diff events against current projection.""" if not app_state.epic_dir: - return [] + return try: - return [ - { - "path": a["path"], - "size": a["size"], - "modifiedAt": int(a["modified_at"] * 1000), - } - for a in list_artifacts(app_state.epic_dir) - ] + new_artifacts = list_artifacts(app_state.epic_dir) except Exception: - return [] - - -# -- SSE push ----------------------------------------------------------------- - -def push_sse(app_state: AppState, event_type: str, payload: Any) -> None: - """Push an SSE event to all connected clients with replay caching.""" - - # --- Side effects and payload enrichment ---------------------------------- - - if event_type == "phase": - # app_state.phase is read by _build_subagent_json and other helpers. - # This assignment was previously inside _render_fragment(); preserving - # it here ensures all subsequent subagent payloads reflect the correct - # phase. - phase = payload if isinstance(payload, str) else payload.get("phase", "") - app_state.phase = phase - payload = {"phase": phase} - - elif event_type in ("subagent", "subagent-idle"): - # Rebuild from AppState to guarantee consistent shape. - # Returns {"agent_id": None} when no primary agent is active. - payload = _build_subagent_json(app_state) - - elif event_type == "agents": - # Full scout list — the frontend does a wholesale replace. - payload = {"agents": _build_agents_json(app_state)} - - elif event_type == "artifacts": - # Full artifact list — the frontend re-renders from this snapshot. - payload = {"artifacts": _build_artifacts_json(app_state)} - - elif event_type == "intake-progress": - # Pass through subPhase/confidence/summary from caller. - payload = payload if isinstance(payload, dict) else {} - - elif event_type == "pipeline-end": - # Convert artifacts to camelCase modifiedAt (milliseconds) so the - # frontend receives a consistent shape from both 'artifacts' and - # 'pipeline-end' events. - if isinstance(payload, dict) and "artifacts" in payload: - converted = [] - for a in payload["artifacts"]: - converted.append({ - "path": a["path"], - "size": a["size"], - "modifiedAt": int(a.get("modified_at", 0) * 1000), - }) - payload = {**payload, "artifacts": converted} - - # --- Cache stateful events for replay to reconnecting clients ------------- - STATEFUL_EVENTS = { - "phase", "subagent", "agents", "artifacts", - "interaction", "intake-progress", "pipeline-end", - } - if event_type in STATEFUL_EVENTS: - app_state.last_sse_values[event_type] = payload - - # --- Enqueue to all connected SSE clients --------------------------------- - for queue in app_state.sse_clients: - try: - queue.put_nowait((event_type, payload)) - except Exception: - pass # queue full or closed -- skip + return + old = app_state.projection_store.projection.artifacts + for event_type, payload in build_artifact_diff(old, new_artifacts): + app_state.projection_store.push_event(event_type, payload) # -- Workflow status ---------------------------------------------------------- @@ -322,7 +197,7 @@ async def run_story_execution( # Planner await save_story_state(epic_dir, story_id, {"storyId": story_id, "status": "planning", "updatedAt": _now()}) - push_sse(app_state, "story", {"storyId": story_id, "status": "planning"}) + # story events deferred -- execution phase UI is a known gap planner_dir = await ensure_subagent_directory( epic_dir, f"planner-{story_id}-{int(time.time() * 1000)}" @@ -345,7 +220,6 @@ async def run_story_execution( # Executor (skip if planner failed) if planner_ok: await save_story_state(epic_dir, story_id, {"storyId": story_id, "status": "executing", "updatedAt": _now()}) - push_sse(app_state, "story", {"storyId": story_id, "status": "executing"}) executor_dir = await ensure_subagent_directory( epic_dir, f"executor-{story_id}-{int(time.time() * 1000)}" @@ -363,7 +237,6 @@ async def run_story_execution( # Post-execution orchestrator await save_story_state(epic_dir, story_id, {"storyId": story_id, "status": "verifying", "updatedAt": _now()}) - push_sse(app_state, "story", {"storyId": story_id, "status": "verifying"}) orch_dir = await ensure_subagent_directory( epic_dir, f"orch-post-{story_id}-{int(time.time() * 1000)}" @@ -393,7 +266,6 @@ async def run_story_execution( "failureSummary": "post-execution orchestrator exited without committing a verdict", "updatedAt": _now(), }) - push_sse(app_state, "story", {"storyId": story_id, "status": "retry"}) return True @@ -414,7 +286,6 @@ async def run_story_reexecution( # Executor with retry context await save_story_state(epic_dir, story_id, {"storyId": story_id, "status": "executing", "updatedAt": _now()}) - push_sse(app_state, "story", {"storyId": story_id, "status": "executing"}) executor_dir = await ensure_subagent_directory( epic_dir, f"executor-{story_id}-retry-{retry_count}-{int(time.time() * 1000)}" @@ -435,7 +306,6 @@ async def run_story_reexecution( # Post-execution orchestrator await save_story_state(epic_dir, story_id, {"storyId": story_id, "status": "verifying", "updatedAt": _now()}) - push_sse(app_state, "story", {"storyId": story_id, "status": "verifying"}) orch_dir = await ensure_subagent_directory( epic_dir, f"orch-post-{story_id}-retry-{retry_count}-{int(time.time() * 1000)}" @@ -463,7 +333,6 @@ async def run_story_reexecution( "failureSummary": "post-execution orchestrator exited without committing a verdict", "updatedAt": _now(), }) - push_sse(app_state, "story", {"storyId": story_id, "status": "retry"}) return True @@ -513,9 +382,6 @@ async def run_story_loop(app_state: AppState, instructions: str | None) -> dict: max_retries = story.get("maxRetries", DEFAULT_MAX_RETRIES) if retry_count >= max_retries: log.warning("story %s exceeded retry budget, skipping", sid) - # save_story_state merges with existing state ({**existing, **updates}), - # so maxRetries and other fields not listed here are preserved from - # the prior write. await save_story_state( epic_dir, sid, { @@ -525,12 +391,8 @@ async def run_story_loop(app_state: AppState, instructions: str | None) -> dict: "updatedAt": _now(), }, ) - push_sse(app_state, "story", {"storyId": sid, "status": "skipped"}) else: log.info("retrying story %s (attempt %d)", sid, retry_count + 1) - # save_story_state merges with existing state ({**existing, **updates}), - # so maxRetries and other fields not listed here are preserved from - # the prior write. await save_story_state( epic_dir, sid, { @@ -607,10 +469,13 @@ async def driver_main(app_state: AppState) -> None: while phase != "completed": epic_state = await load_epic_state(epic_dir) await save_epic_state(epic_dir, {**epic_state, "phase": phase}) - push_sse(app_state, "phase", phase) - # Push artifacts update at start of each phase - push_sse(app_state, "artifacts", {}) + # Set app_state.phase before emitting phase_started (driver mutation, not projection) + app_state.phase = phase + app_state.projection_store.push_event("phase_started", {"phase": phase}) + + # Push artifact diff at start of each phase + _push_artifact_diff(app_state) if is_stub_phase(phase): pass # carry forward pending_instructions @@ -618,10 +483,11 @@ async def driver_main(app_state: AppState) -> None: ok = await run_phase(phase, app_state, pending_instructions) pending_instructions = None if not ok: - push_sse(app_state, "pipeline-end", { + app_state.projection_store.push_event("workflow_completed", { "success": False, "phase": phase, "error": f"Phase {phase} failed", + "summary": f"Phase {phase} failed", }) return @@ -637,10 +503,11 @@ async def driver_main(app_state: AppState) -> None: app_state.frozen_logs = list(app_state.frozen_logs) decision = await run_workflow_orchestrator(phase, successors, app_state) if not decision: - push_sse(app_state, "pipeline-end", { + app_state.projection_store.push_event("workflow_completed", { "success": False, "phase": phase, "error": "Workflow orchestrator failed", + "summary": "Workflow orchestrator failed", }) return phase = decision["next_phase"] @@ -648,11 +515,13 @@ async def driver_main(app_state: AppState) -> None: epic_state = await load_epic_state(epic_dir) await save_epic_state(epic_dir, {**epic_state, "phase": "completed"}) - push_sse(app_state, "phase", "completed") + app_state.phase = "completed" + app_state.projection_store.push_event("phase_started", {"phase": "completed"}) + + # Final artifact diff before completion + _push_artifact_diff(app_state) - # Push completion event with artifact list - push_sse(app_state, "pipeline-end", { + app_state.projection_store.push_event("workflow_completed", { "success": True, "summary": "All phases completed successfully", - "artifacts": list_artifacts(epic_dir), }) diff --git a/koan/state.py b/koan/state.py index d76df8f..d98e491 100644 --- a/koan/state.py +++ b/koan/state.py @@ -16,6 +16,7 @@ def _utcnow() -> datetime: from .config import KoanConfig from .probe import ProbeResult +from .projections import ProjectionStore from .types import EpicPhase, Profile, SubagentRole @@ -52,7 +53,7 @@ class AppState: epic_dir: str | None = None start_event: asyncio.Event = field(default_factory=asyncio.Event) agents: dict[str, AgentState] = field(default_factory=dict) - sse_clients: list = field(default_factory=list) + projection_store: ProjectionStore = field(default_factory=ProjectionStore) active_interaction: PendingInteraction | None = None interaction_queue: deque[PendingInteraction] = field(default_factory=deque) interaction_queue_max: int = 8 @@ -63,4 +64,3 @@ class AppState: port: int = 8000 open_browser: bool = True config_write_lock: asyncio.Lock = field(default_factory=asyncio.Lock) - last_sse_values: dict[str, Any] = field(default_factory=dict) diff --git a/koan/subagent.py b/koan/subagent.py index 2807e52..f793a74 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -14,6 +14,16 @@ from .audit import EventLog from .epic_state import ensure_subagent_directory +from .events import ( + build_agent_exited, + build_agent_spawn_failed, + build_agent_spawned, + build_artifact_reviewed, + build_questions_answered, + build_tool_called, + build_tool_completed, + build_workflow_decided, +) from .logger import get_logger from .phases import PHASE_MODULE_MAP, PhaseContext from .runners import RunnerDiagnostic, RunnerError @@ -70,6 +80,7 @@ def _build_phase_ctx(task: dict, subagent_dir: str) -> PhaseContext: async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None = None) -> int: role = task["role"] agent_id = str(uuid.uuid4()) + store = app_state.projection_store # Own directory creation -- derive if not provided, ensure it exists subagent_dir = task.get("subagent_dir", "") @@ -103,7 +114,7 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None model = model_alias except RunnerError as e: log.error("runner resolution failed for %s: %s", role, e.diagnostic.message) - # Emit diagnostics via EventLog if possible, otherwise emit pre-log diagnostic + # Write diagnostic to EventLog try: event_log = EventLog(subagent_dir, role, phase=role, model=None) await event_log.open() @@ -111,16 +122,10 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None await event_log.close() except Exception: log.warning("failed to write diagnostic event log for %s", role) - _push_sse(app_state, "notification", { - "type": "runner_error", - "agent_id": agent_id, - "role": role, - "code": e.diagnostic.code, - "runner": e.diagnostic.runner, - "stage": e.diagnostic.stage, - "message": e.diagnostic.message, - "details": e.diagnostic.details, - }) + store.push_event( + "agent_spawn_failed", + build_agent_spawn_failed(role, e.diagnostic), + ) return 1 else: model = None @@ -161,11 +166,11 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None ) app_state.agents[agent_id] = agent - # Emit phase start + # Emit phase start to audit log await event_log.emit_phase_start(phase_module.TOTAL_STEPS) - # Build command -- use full 5-arg signature when registry-resolved, - # fall back to legacy 3-arg for externally provided runners. + # Build command before emitting agent_spawned -- if build_command fails, no + # agent_spawned event is emitted (per plan: "the agent was never launched"). try: if installation is not None and thinking_mode is not None: cmd = runner.build_command( @@ -175,20 +180,17 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None cmd = runner.build_command(boot_prompt(role), mcp_url, model) except RunnerError as e: await event_log.emit_runner_diagnostic(e.diagnostic) - _push_sse(app_state, "notification", { - "type": "runner_error", - "agent_id": agent_id, - "role": role, - "code": e.diagnostic.code, - "runner": e.diagnostic.runner, - "stage": e.diagnostic.stage, - "message": e.diagnostic.message, - "details": e.diagnostic.details, - }) + store.push_event( + "agent_spawn_failed", + build_agent_spawn_failed(role, e.diagnostic), + ) await event_log.close() del app_state.agents[agent_id] return 1 + # Emit agent_spawned only after build_command succeeds -- process is about to start + store.push_event("agent_spawned", build_agent_spawned(agent), agent_id=agent_id) + # Spawn process log.info("spawning %s (agent_id=%s): %s", role, agent_id, " ".join(cmd)) proc = await asyncio.create_subprocess_exec( @@ -198,72 +200,54 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None cwd=subagent_dir, ) - # Emit agent spawn to SSE - _push_sse(app_state, "subagent", { - "agent_id": agent_id, - "role": role, - "model": model, - "step": 0, - "startedAt": agent.started_at.isoformat(), - }) - _push_sse(app_state, "agents", { - "agents": [{"agent_id": a.agent_id, "role": a.role} for a in app_state.agents.values()] - }) - - # Stream tracking (telemetry only -- handshake detected via MCP path) + # Stream tracking async def stream_stdout(): assert proc.stdout is not None - last_tool: str | None = None + last_tool_name: str | None = None + last_call_id: str | None = None + async for raw in proc.stdout: line = raw.decode("utf-8", errors="replace").rstrip("\n") events = runner.parse_stream_event(line) for ev in events: if ev.type == "token_delta": agent.token_count["received"] = agent.token_count.get("received", 0) + len(ev.content or "") - _push_sse(app_state, "token-delta", { - "delta": ev.content, - "agent_id": agent_id, - }) + store.push_event("stream_delta", {"delta": ev.content or ""}, agent_id=agent_id) elif ev.type == "thinking": - _push_sse(app_state, "logs", { - "line": { - "tool": "", - "summary": "thinking...", - "inFlight": True, - "ts": _now_iso(), - }, - "agent_id": agent_id, - }) + store.push_event("thinking", {"delta": ev.content or ""}, agent_id=agent_id) elif ev.type == "tool_call": - # tool_call events carry tool metadata (not input tokens), - # so no token counter is incremented here. # Close previous in-flight tool - if last_tool: - _push_sse(app_state, "logs", { - "line": { - "tool": last_tool, - "summary": "completed", - "inFlight": False, - }, - "agent_id": agent_id, - }) - last_tool = ev.tool_name - _push_sse(app_state, "logs", { - "line": { - "tool": ev.tool_name or "tool", - "summary": ev.content or "", - "inFlight": True, - }, - "agent_id": agent_id, - }) - else: - _push_sse(app_state, "stream", { - "agent_id": agent_id, - "role": role, - "type": ev.type, - "content": ev.content, - "tool_name": ev.tool_name, - }) + if last_call_id is not None and last_tool_name is not None: + store.push_event( + "tool_completed", + build_tool_completed(last_call_id, last_tool_name), + agent_id=agent_id, + ) + # Open new tool call + call_id = str(uuid.uuid4()) + tool_name = ev.tool_name or "tool" + store.push_event( + "tool_called", + build_tool_called(call_id, tool_name, ev.tool_args or {}, ev.content or ""), + agent_id=agent_id, + ) + last_call_id = call_id + last_tool_name = tool_name + elif ev.type == "turn_complete": + # Dropped -- stream_cleared at stdout EOF covers end-of-stream + pass + # All other unrecognized types are silently dropped + + # Close any in-flight tool at stdout EOF + if last_call_id is not None and last_tool_name is not None: + store.push_event( + "tool_completed", + build_tool_completed(last_call_id, last_tool_name), + agent_id=agent_id, + ) + + # Tombstone: mark end of this agent's stream + store.push_event("stream_cleared", {}, agent_id=agent_id) async def drain_stderr(): assert proc.stderr is not None @@ -283,7 +267,8 @@ async def drain_stderr(): if stderr_output.strip(): log.warning("stderr from %s (agent_id=%s): %s", role, agent_id, stderr_output[:500]) - # Handshake check (uses MCP-path flag, works for all runners) + # Handshake check + error_str: str | None = None if not agent.handshake_observed: diag = RunnerDiagnostic( code="bootstrap_failure", @@ -292,80 +277,83 @@ async def drain_stderr(): message="Process exited before first koan_complete_step call", ) await event_log.emit_runner_diagnostic(diag) - _push_sse(app_state, "notification", { - "type": "bootstrap_failure", - "agent_id": agent_id, - "role": role, - "code": diag.code, - "runner": diag.runner, - "stage": diag.stage, - "message": diag.message, - "details": diag.details, - }) + error_str = "bootstrap_failure" exit_code = 1 # Cleanup: resolve pending interactions for this agent _cancel_pending_interactions(agent_id, app_state) - # Finalize + # Finalize audit log outcome = "completed" if exit_code == 0 else "failed" await event_log.emit_phase_end(outcome) await event_log.close() del app_state.agents[agent_id] - # Emit subagent-idle and updated agents list - _push_sse(app_state, "subagent-idle", {}) - _push_sse(app_state, "agents", { - "agents": [{"agent_id": a.agent_id, "role": a.role} for a in app_state.agents.values()] - }) + # Emit agent_exited to projection + token_usage = { + "input_tokens": agent.token_count.get("sent", 0), + "output_tokens": agent.token_count.get("received", 0), + } + store.push_event( + "agent_exited", + build_agent_exited(exit_code, error=error_str, usage=token_usage), + agent_id=agent_id, + ) log.info("%s (agent_id=%s) exited with code %d", role, agent_id, exit_code) return exit_code -# -- SSE push helper ----------------------------------------------------------- - -def _push_sse(app_state: AppState, event_type: str, payload: dict) -> None: - """Forward to driver.push_sse (imported lazily to avoid circular imports).""" - from .driver import push_sse - push_sse(app_state, event_type, payload) - - # -- Interaction cleanup ------------------------------------------------------- def _cancel_pending_interactions(agent_id: str, app_state: AppState) -> None: - """Resolve any pending/queued blocking interactions for this agent.""" + """Resolve any pending/queued blocking interactions for this agent. + + Queued interactions are cancelled silently (no projection event). + The active interaction (if it belongs to this agent) emits a typed + cancellation resolution event. + """ from .web.interactions import activate_next_interaction error_result = {"error": "agent_exited", "message": "Agent process exited"} + store = app_state.projection_store - # Collect and cancel all interactions belonging to agent_id (queue first, - # then active) before promoting any next interaction. This prevents - # activate_next_interaction() from promoting another queued interaction - # from the same exiting agent into the active slot. - + # Cancel queued interactions belonging to this agent silently remaining = [] for item in app_state.interaction_queue: if item.agent_id == agent_id: if not item.future.done(): item.future.set_result(error_result) - _push_sse(app_state, "notification", { - "type": "interaction_cancelled", - "agent_id": agent_id, - "message": "Interaction cancelled: agent process exited", - }) + # No projection event for queued (never-active) interactions else: remaining.append(item) app_state.interaction_queue.clear() app_state.interaction_queue.extend(remaining) + # Cancel active interaction with a typed cancellation event active = app_state.active_interaction if active is not None and active.agent_id == agent_id: + token = active.token + + if active.type == "ask": + store.push_event( + "questions_answered", + build_questions_answered(token, answers=None, cancelled=True), + agent_id=agent_id, + ) + elif active.type == "artifact-review": + store.push_event( + "artifact_reviewed", + build_artifact_reviewed(token, accepted=None, response=None, cancelled=True), + agent_id=agent_id, + ) + elif active.type == "workflow-decision": + store.push_event( + "workflow_decided", + build_workflow_decided(token, decision=None, cancelled=True), + agent_id=agent_id, + ) + if not active.future.done(): active.future.set_result(error_result) - _push_sse(app_state, "notification", { - "type": "interaction_cancelled", - "agent_id": agent_id, - "message": "Interaction cancelled: agent process exited", - }) activate_next_interaction(app_state) diff --git a/koan/web/app.py b/koan/web/app.py index 5ae1c02..1f482d1 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -25,6 +25,11 @@ from ..probe import ProbeResult from ..types import AgentInstallation, Profile, ProfileTier from .interactions import activate_next_interaction +from ..events import ( + build_artifact_reviewed, + build_questions_answered, + build_workflow_decided, +) if TYPE_CHECKING: from ..state import AppState @@ -119,23 +124,40 @@ async def spa_fallback(request: Request) -> Response: async def sse_stream(r: Request) -> Response: st = _app_state(r) + store = st.projection_store + + since_str = r.query_params.get("since", "0") + try: + since = int(since_str) + except ValueError: + since = 0 async def event_generator(): - queue: asyncio.Queue = asyncio.Queue() - st.sse_clients.append(queue) + # Stale client: send fatal_error and close (not HTTP error -- EventSource + # cannot read non-200 bodies and would retry with same stale version). + if since > 0 and since > store.version: + yield _sse_event("fatal_error", {"reason": "version_not_available"}) + return + + # Subscribe before snapshot -- no await between subscribe and get_snapshot + # so no events can be missed between the two operations. + queue = store.subscribe() try: - # Replay last known state - for event_type, payload in st.last_sse_values.items(): - yield _sse_event(event_type, payload) + if since == 0: + yield _sse_event("snapshot", store.get_snapshot()) + else: + for event in store.events_since(since): + data = {"version": event.version, "agent_id": event.agent_id, **event.payload} + yield _sse_event(event.event_type, data) - # Stream live events while True: - event_type, payload = await queue.get() - yield _sse_event(event_type, payload) + event = await queue.get() + data = {"version": event.version, "agent_id": event.agent_id, **event.payload} + yield _sse_event(event.event_type, data) except asyncio.CancelledError: pass finally: - st.sse_clients.remove(queue) + store.unsubscribe(queue) return StreamingResponse( event_generator(), @@ -228,6 +250,11 @@ async def api_answer(r: Request) -> Response: return _stale_response() interaction = active + st.projection_store.push_event( + "questions_answered", + build_questions_answered(interaction.token, answers, cancelled=False), + agent_id=interaction.agent_id, + ) activate_next_interaction(st) interaction.future.set_result({"answers": answers}) return JSONResponse({"ok": True}) @@ -245,6 +272,11 @@ async def api_artifact_review(r: Request) -> Response: return _stale_response() interaction = active + st.projection_store.push_event( + "artifact_reviewed", + build_artifact_reviewed(interaction.token, accepted=accepted, response=response, cancelled=False), + agent_id=interaction.agent_id, + ) activate_next_interaction(st) interaction.future.set_result({"response": response, "accepted": accepted}) return JSONResponse({"ok": True}) @@ -283,6 +315,11 @@ async def api_workflow_decision(r: Request) -> Response: ) interaction = active + st.projection_store.push_event( + "workflow_decided", + build_workflow_decided(interaction.token, decision={"phase": phase, "context": context}, cancelled=False), + agent_id=interaction.agent_id, + ) activate_next_interaction(st) interaction.future.set_result({"phase": phase, "context": context}) return JSONResponse({"ok": True}) diff --git a/koan/web/interactions.py b/koan/web/interactions.py index 6d0e7d5..05569e3 100644 --- a/koan/web/interactions.py +++ b/koan/web/interactions.py @@ -17,11 +17,44 @@ from ..state import AgentState, AppState -# -- SSE push (lazy import to avoid circular deps) ---------------------------- +# -- Request event emitter ---------------------------------------------------- + +def _emit_interaction_request(app_state: AppState, interaction: PendingInteraction) -> None: + """Emit the typed request event for an interaction becoming active.""" + from ..events import ( + build_artifact_review_requested, + build_questions_asked, + build_workflow_decision_requested, + ) + + store = app_state.projection_store + token = interaction.token + payload = interaction.payload + agent_id = interaction.agent_id -def _push_sse(app_state: AppState, event_type: str, payload: dict) -> None: - from ..driver import push_sse - push_sse(app_state, event_type, payload) + if interaction.type == "ask": + store.push_event( + "questions_asked", + build_questions_asked(token, payload.get("questions", [])), + agent_id=agent_id, + ) + elif interaction.type == "artifact-review": + store.push_event( + "artifact_review_requested", + build_artifact_review_requested( + token, + payload.get("path", ""), + payload.get("description", ""), + payload.get("content", ""), + ), + agent_id=agent_id, + ) + elif interaction.type == "workflow-decision": + store.push_event( + "workflow_decision_requested", + build_workflow_decision_requested(token, payload.get("chat_turns", [])), + agent_id=agent_id, + ) # -- Queue helpers ------------------------------------------------------------ @@ -50,7 +83,7 @@ async def enqueue_interaction( if app_state.active_interaction is None: app_state.active_interaction = interaction - _push_sse(app_state, "interaction", {"type": interaction_type, "token": interaction.token, **payload}) + _emit_interaction_request(app_state, interaction) else: app_state.interaction_queue.append(interaction) @@ -58,11 +91,10 @@ async def enqueue_interaction( def activate_next_interaction(app_state: AppState) -> None: - _push_sse(app_state, "interaction", {"type": "cleared"}) - + """Promote the next queued interaction to active, emitting its request event.""" if app_state.interaction_queue: nxt = app_state.interaction_queue.popleft() app_state.active_interaction = nxt - _push_sse(app_state, "interaction", {"type": nxt.type, "token": nxt.token, **nxt.payload}) + _emit_interaction_request(app_state, nxt) else: app_state.active_interaction = None diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index f40bd9e..a6fee05 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -3,7 +3,9 @@ # Exposes build_mcp_asgi_app() which returns an ASGI sub-app that: # 1. Validates agent_id from query params before reaching fastmcp. # 2. Runs check_permission() on every tool call. -# 3. Implements koan_complete_step, koan_set_confidence, koan_request_scouts. +# 3. Implements koan_complete_step, koan_set_confidence, koan_request_scouts, +# koan_ask_question, koan_review_artifact, koan_propose_workflow, +# koan_set_next_phase. from __future__ import annotations @@ -70,19 +72,40 @@ def _get_agent() -> AgentState: return agent -def _log_tool_call(agent: AgentState, tool_name: str, summary: str = "") -> None: - """Push a tool-call log entry to SSE so the activity feed shows MCP calls.""" +def begin_tool_call( + agent: AgentState, + tool: str, + args: dict | str, + summary: str = "", +) -> str: + """Emit tool_called event and return call_id. No-op if app_state is not set.""" + call_id = str(uuid.uuid4()) + if _app_state is None: + return call_id + from ..events import build_tool_called + _app_state.projection_store.push_event( + "tool_called", + build_tool_called(call_id, tool, args, summary), + agent_id=agent.agent_id, + ) + return call_id + + +def end_tool_call( + agent: AgentState, + call_id: str, + tool: str, + result: str | None = None, +) -> None: + """Emit tool_completed event. No-op if app_state is not set.""" if _app_state is None: return - from ..driver import push_sse - push_sse(_app_state, "logs", { - "line": { - "tool": tool_name, - "summary": summary, - "inFlight": True, - }, - "agent_id": agent.agent_id, - }) + from ..events import build_tool_completed + _app_state.projection_store.push_event( + "tool_completed", + build_tool_completed(call_id, tool, result), + agent_id=agent.agent_id, + ) # -- Tool implementations ----------------------------------------------------- @@ -91,265 +114,316 @@ def _log_tool_call(agent: AgentState, tool_name: str, summary: str = "") -> None async def koan_complete_step(thoughts: str = "") -> str: agent = _get_agent() _check_or_raise(agent, "koan_complete_step", {"thoughts": thoughts}) - _log_tool_call(agent, "koan_complete_step", f"step {agent.step} → next") - - # Mark handshake observed (decoupled from stream parsing) - agent.handshake_observed = True - - phase_module = agent.phase_module - ctx = agent.phase_ctx - current_step = agent.step - - # Validate current step completion - err = phase_module.validate_step_completion(current_step, ctx) - if err: - raise ToolError( - json.dumps({"error": "step_validation_failed", "message": err}) - ) - - # Get next step - next_step = phase_module.get_next_step(current_step, ctx) - # Loop-back handling - if next_step is not None and next_step <= current_step: - await phase_module.on_loop_back(current_step, next_step, ctx) - - # Advance step - agent.step = next_step if next_step is not None else current_step - - # Determine step name for audit - step_names = getattr(phase_module, "STEP_NAMES", {}) - step_name = step_names.get(next_step if next_step is not None else current_step, "") - - # Emit audit event - if agent.event_log is not None: - await agent.event_log.emit_step_transition( - next_step if next_step is not None else current_step, - step_name, - phase_module.TOTAL_STEPS, - ) - - # Return guidance or completion signal - if next_step is None: - return "Phase complete." - - guidance = phase_module.step_guidance(next_step, ctx) - return format_step(guidance) + call_id = begin_tool_call(agent, "koan_complete_step", {"thoughts": thoughts}, f"step {agent.step} → next") + result_str: str | None = None + try: + # Mark handshake observed (decoupled from stream parsing) + agent.handshake_observed = True + + phase_module = agent.phase_module + ctx = agent.phase_ctx + current_step = agent.step + + # Validate current step completion + err = phase_module.validate_step_completion(current_step, ctx) + if err: + raise ToolError( + json.dumps({"error": "step_validation_failed", "message": err}) + ) + + # Get next step + next_step = phase_module.get_next_step(current_step, ctx) + + # Loop-back handling + if next_step is not None and next_step <= current_step: + await phase_module.on_loop_back(current_step, next_step, ctx) + + # Advance step + agent.step = next_step if next_step is not None else current_step + + # Determine step name + step_names = getattr(phase_module, "STEP_NAMES", {}) + step_num = next_step if next_step is not None else current_step + step_name = step_names.get(step_num, "") + + # Emit audit event + if agent.event_log is not None: + await agent.event_log.emit_step_transition( + step_num, + step_name, + phase_module.TOTAL_STEPS, + ) + + # Emit agent_step_advanced to projection + if _app_state is not None: + from ..events import build_step_advanced + _app_state.projection_store.push_event( + "agent_step_advanced", + build_step_advanced(step_num, step_name), + agent_id=agent.agent_id, + ) + + # Return guidance or completion signal + if next_step is None: + result_str = "Phase complete." + return result_str + + guidance = phase_module.step_guidance(next_step, ctx) + result_str = format_step(guidance) + return result_str + finally: + end_tool_call(agent, call_id, "koan_complete_step", result_str) @mcp.tool(name="koan_set_confidence") async def koan_set_confidence(level: str = "") -> str: agent = _get_agent() _check_or_raise(agent, "koan_set_confidence", {"level": level}) - _log_tool_call(agent, "koan_set_confidence", level) - valid_levels = {"high", "medium", "low"} - if level not in valid_levels: - raise ToolError( - json.dumps({"error": "invalid_confidence", "message": f"level must be one of {valid_levels}"}) - ) + call_id = begin_tool_call(agent, "koan_set_confidence", {"level": level}, level) + result_str: str | None = None + try: + valid_levels = {"high", "medium", "low"} + if level not in valid_levels: + raise ToolError( + json.dumps({"error": "invalid_confidence", "message": f"level must be one of {valid_levels}"}) + ) - agent.phase_ctx.intake_confidence = level - return f"Confidence set to {level}." + agent.phase_ctx.intake_confidence = level + result_str = f"Confidence set to {level}." + return result_str + finally: + end_tool_call(agent, call_id, "koan_set_confidence", result_str) @mcp.tool(name="koan_request_scouts") async def koan_request_scouts(questions: list[dict] | None = None) -> str: agent = _get_agent() _check_or_raise(agent, "koan_request_scouts", {"questions": questions}) - _log_tool_call(agent, "koan_request_scouts", f"{len(questions or [])} scouts") - if not questions: - return "No scouts requested." + call_id = begin_tool_call( + agent, "koan_request_scouts", {"questions": questions or []}, + f"{len(questions or [])} scouts", + ) + result_str: str | None = None + try: + if not questions: + result_str = "No scouts requested." + return result_str + + assert _app_state is not None, "app_state not initialized" + + semaphore = asyncio.Semaphore(_app_state.config.scout_concurrency) + epic_dir = agent.phase_ctx.epic_dir + + scout_tasks = [] + for q in questions: + scout_id = q.get("id", str(uuid.uuid4())[:8]) + subagent_dir = await ensure_subagent_directory( + epic_dir, f"scout-{scout_id}-{uuid.uuid4().hex[:8]}" + ) + scout_tasks.append({ + "role": "scout", + "epic_dir": epic_dir, + "subagent_dir": subagent_dir, + "question": q.get("prompt", ""), + "output_file": "findings.md", + "investigator_role": q.get("role", "investigator"), + }) + + async def run_scout(scout_task: dict) -> str | None: + async with semaphore: + from ..subagent import spawn_subagent - assert _app_state is not None, "app_state not initialized" + exit_code = await spawn_subagent(scout_task, _app_state) - semaphore = asyncio.Semaphore(_app_state.config.scout_concurrency) - epic_dir = agent.phase_ctx.epic_dir + # Require state.json with status=="completed" + state_path = Path(scout_task["subagent_dir"]) / "state.json" + try: + async with aiofiles.open(state_path, "r") as f: + projection = json.loads(await f.read()) + except (FileNotFoundError, json.JSONDecodeError): + return None + if projection.get("status") != "completed": + return None - scout_tasks = [] - for q in questions: - scout_id = q.get("id", str(uuid.uuid4())[:8]) - subagent_dir = await ensure_subagent_directory( - epic_dir, f"scout-{scout_id}-{uuid.uuid4().hex[:8]}" - ) - scout_tasks.append({ - "role": "scout", - "epic_dir": epic_dir, - "subagent_dir": subagent_dir, - "question": q.get("prompt", ""), - "output_file": "findings.md", - "investigator_role": q.get("role", "investigator"), - }) - - async def run_scout(scout_task: dict) -> str | None: - async with semaphore: - from ..subagent import spawn_subagent - - exit_code = await spawn_subagent(scout_task, _app_state) - - # Require state.json with status=="completed" (regardless of exit code) - state_path = Path(scout_task["subagent_dir"]) / "state.json" - try: - async with aiofiles.open(state_path, "r") as f: - projection = json.loads(await f.read()) - except (FileNotFoundError, json.JSONDecodeError): - return None - if projection.get("status") != "completed": - return None - - # Read findings - findings_path = Path(scout_task["subagent_dir"]) / "findings.md" - try: - async with aiofiles.open(findings_path, "r") as f: - return await f.read() - except FileNotFoundError: - return None + findings_path = Path(scout_task["subagent_dir"]) / "findings.md" + try: + async with aiofiles.open(findings_path, "r") as f: + return await f.read() + except FileNotFoundError: + return None - results = await asyncio.gather(*[run_scout(t) for t in scout_tasks]) - findings = [r for r in results if r is not None] + results = await asyncio.gather(*[run_scout(t) for t in scout_tasks]) + findings = [r for r in results if r is not None] - if not findings: - return "No findings returned." + if not findings: + result_str = "No findings returned." + return result_str - return "\n\n---\n\n".join(findings) + result_str = "\n\n---\n\n".join(findings) + return result_str + finally: + end_tool_call(agent, call_id, "koan_request_scouts", result_str) @mcp.tool(name="koan_ask_question") async def koan_ask_question(questions: list[dict] | None = None) -> str: agent = _get_agent() _check_or_raise(agent, "koan_ask_question", {"questions": questions}) - _log_tool_call(agent, "koan_ask_question", f"{len(questions or [])} questions") - assert _app_state is not None, "app_state not initialized" - future = await enqueue_interaction(agent, _app_state, "ask", {"questions": questions or []}) - result = await future + call_id = begin_tool_call( + agent, "koan_ask_question", {"questions": questions or []}, + f"{len(questions or [])} questions", + ) + result_str: str | None = None + try: + assert _app_state is not None, "app_state not initialized" + + future = await enqueue_interaction(agent, _app_state, "ask", {"questions": questions or []}) + result = await future - if isinstance(result, dict) and "error" in result: - raise ToolError(json.dumps(result)) + if isinstance(result, dict) and "error" in result: + raise ToolError(json.dumps(result)) - answers = result.get("answers", []) - questions_list = questions or [] - lines = [] - for i, a in enumerate(answers): - q_text = questions_list[i].get("question", f"Q{i+1}") if i < len(questions_list) else f"Q{i+1}" - a_text = a.get("answer", "") if isinstance(a, dict) else str(a) - lines.append(f"Q: {q_text}\nA: {a_text}") - return "\n\n".join(lines) if lines else "No answers provided." + answers = result.get("answers", []) + questions_list = questions or [] + lines = [] + for i, a in enumerate(answers): + q_text = questions_list[i].get("question", f"Q{i+1}") if i < len(questions_list) else f"Q{i+1}" + a_text = a.get("answer", "") if isinstance(a, dict) else str(a) + lines.append(f"Q: {q_text}\nA: {a_text}") + result_str = "\n\n".join(lines) if lines else "No answers provided." + return result_str + finally: + end_tool_call(agent, call_id, "koan_ask_question", result_str) @mcp.tool(name="koan_review_artifact") async def koan_review_artifact(path: str = "", description: str = "") -> str: agent = _get_agent() _check_or_raise(agent, "koan_review_artifact", {"path": path, "description": description}) - _log_tool_call(agent, "koan_review_artifact", description or path) - assert _app_state is not None, "app_state not initialized" + call_id = begin_tool_call( + agent, "koan_review_artifact", {"path": path, "description": description}, + description or path, + ) + result_str: str | None = None try: - async with aiofiles.open(path, "r") as f: - content = await f.read() - except FileNotFoundError: - raise ToolError( - json.dumps({"error": "file_not_found", "message": f"Artifact not found: {path}"}) + assert _app_state is not None, "app_state not initialized" + + try: + async with aiofiles.open(path, "r") as f: + content = await f.read() + except FileNotFoundError: + raise ToolError( + json.dumps({"error": "file_not_found", "message": f"Artifact not found: {path}"}) + ) + + future = await enqueue_interaction( + agent, _app_state, "artifact-review", + {"path": path, "description": description, "content": content}, ) + result = await future - future = await enqueue_interaction( - agent, _app_state, "artifact-review", - {"path": path, "description": description, "content": content}, - ) - result = await future - - if isinstance(result, dict) and "error" in result: - raise ToolError(json.dumps(result)) + if isinstance(result, dict) and "error" in result: + raise ToolError(json.dumps(result)) - response = result.get("response", "") - accepted = result.get("accepted", response == "" or response.strip().lower() in ("", "ok", "approved", "lgtm", "accept")) - agent.phase_ctx.last_review_accepted = accepted + response = result.get("response", "") + accepted = result.get("accepted", response == "" or response.strip().lower() in ("", "ok", "approved", "lgtm", "accept")) + agent.phase_ctx.last_review_accepted = accepted - return "ACCEPTED" if accepted else f"REVISION REQUESTED: {response}" + result_str = "ACCEPTED" if accepted else f"REVISION REQUESTED: {response}" + return result_str + finally: + end_tool_call(agent, call_id, "koan_review_artifact", result_str) @mcp.tool(name="koan_propose_workflow") async def koan_propose_workflow(status: str = "", phases: list | None = None) -> str: agent = _get_agent() _check_or_raise(agent, "koan_propose_workflow", {"status": status, "phases": phases}) - _log_tool_call(agent, "koan_propose_workflow", "proposing phases") - assert _app_state is not None, "app_state not initialized" - - # Normalise phases: accept both list[str] and list[dict]. - normalised: list[dict] = [] - for p in (phases or []): - if isinstance(p, str): - normalised.append({"phase": p, "context": "", "recommended": False}) - elif isinstance(p, dict): - normalised.append(p) - - # Build chat_turns with status_report + recommended_phases to match - # the interaction_workflow.html template contract. - chat_turns = [{ - "role": "orchestrator", - "status_report": status, - "recommended_phases": [ - { - "phase": p.get("phase", p.get("name", "")), - "context": p.get("context", p.get("description", "")), - "recommended": p.get("recommended", False), - } - for p in normalised - ], - }] - future = await enqueue_interaction( - agent, _app_state, "workflow-decision", - {"chat_turns": chat_turns}, + + call_id = begin_tool_call( + agent, "koan_propose_workflow", {"status": status, "phases": phases or []}, + "proposing phases", ) - result = await future + result_str: str | None = None + try: + assert _app_state is not None, "app_state not initialized" + + # Normalise phases: accept both list[str] and list[dict]. + normalised: list[dict] = [] + for p in (phases or []): + if isinstance(p, str): + normalised.append({"phase": p, "context": "", "recommended": False}) + elif isinstance(p, dict): + normalised.append(p) + + chat_turns = [{ + "role": "orchestrator", + "status_report": status, + "recommended_phases": [ + { + "phase": p.get("phase", p.get("name", "")), + "context": p.get("context", p.get("description", "")), + "recommended": p.get("recommended", False), + } + for p in normalised + ], + }] + future = await enqueue_interaction( + agent, _app_state, "workflow-decision", + {"chat_turns": chat_turns}, + ) + result = await future - if isinstance(result, dict) and "error" in result: - raise ToolError(json.dumps(result)) + if isinstance(result, dict) and "error" in result: + raise ToolError(json.dumps(result)) - agent.phase_ctx.proposal_made = True + agent.phase_ctx.proposal_made = True - phase = result.get("phase", "") - context = result.get("context", "") - return f"Selected: {phase}\n{context}".strip() + phase = result.get("phase", "") + context = result.get("context", "") + result_str = f"Selected: {phase}\n{context}".strip() + return result_str + finally: + end_tool_call(agent, call_id, "koan_propose_workflow", result_str) @mcp.tool(name="koan_set_next_phase") async def koan_set_next_phase(phase: str = "", instructions: str = "") -> str: agent = _get_agent() _check_or_raise(agent, "koan_set_next_phase", {"phase": phase, "instructions": instructions}) - _log_tool_call(agent, "koan_set_next_phase", phase) - from_phase = getattr(agent.phase_ctx, "completed_phase", None) - if not is_valid_transition(from_phase, phase): - raise ToolError( - json.dumps({ - "error": "invalid_transition", - "message": f"Transition {from_phase} -> {phase} is not valid", - }) - ) + call_id = begin_tool_call( + agent, "koan_set_next_phase", {"phase": phase, "instructions": instructions}, phase, + ) + result_str: str | None = None + try: + from_phase = getattr(agent.phase_ctx, "completed_phase", None) + if not is_valid_transition(from_phase, phase): + raise ToolError( + json.dumps({ + "error": "invalid_transition", + "message": f"Transition {from_phase} -> {phase} is not valid", + }) + ) - out_path = Path(agent.phase_ctx.subagent_dir) / "workflow-decision.json" - await atomic_write_json(out_path, {"next_phase": phase, "instructions": instructions}) - agent.phase_ctx.next_phase_set = True - return f"Phase set to {phase}." + out_path = Path(agent.phase_ctx.subagent_dir) / "workflow-decision.json" + await atomic_write_json(out_path, {"next_phase": phase, "instructions": instructions}) + agent.phase_ctx.next_phase_set = True + result_str = f"Phase set to {phase}." + return result_str + finally: + end_tool_call(agent, call_id, "koan_set_next_phase", result_str) # -- ASGI wrapper -------------------------------------------------------------- def build_mcp_asgi_app(app_state: AppState): - """Return an ASGI app that validates agent_id then delegates to fastmcp. - - Returns (asgi_wrapper, inner_app) where inner_app is the - StarletteWithLifespan from fastmcp. The caller MUST enter - ``inner_app.lifespan`` inside the parent app's own lifespan so - that the StreamableHTTPSessionManager task-group is running before - the first MCP request arrives. - - The inner app is created with ``path="/"`` because it is mounted - under ``Mount("/mcp", ...)``, which strips the ``/mcp`` prefix - before forwarding to us. - """ + """Return an ASGI app that validates agent_id then delegates to fastmcp.""" global _app_state _app_state = app_state From 6451c1a307f151bf2bc95030c1033100d9b66c7c Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 12:52:07 +0700 Subject: [PATCH 198/412] rewrite frontend store and SSE bridge for versioned event protocol --- frontend/src/App.tsx | 21 +- frontend/src/sse/connect.ts | 160 ++++--------- frontend/src/store/index.ts | 399 ++++++++++++++++++++++++++++++-- frontend/src/store/selectors.ts | 18 +- 4 files changed, 458 insertions(+), 140 deletions(-) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index b526f2c..0cbb3ee 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -44,18 +44,23 @@ function WorkspaceMain() { export default function App() { const runStarted = useStore(s => s.runStarted) const settingsOpen = useStore(s => s.settingsOpen) + const fatalError = useStore(s => s.fatalError) useEffect(() => { let es: EventSource | null = null let retryDelay = 500 function connect() { + // Do not reconnect after a fatal_error (server restart / stale version). + // User must reload the page. + if (useStore.getState().fatalError) return + es = connectSSE(useStore) // Override the onerror set inside connectSSE to schedule our retry. es.onerror = () => { useStore.getState().setConnected(false) es?.close() - // Exponential backoff capped at 5s, matching the old koan.js behaviour. + // Exponential backoff capped at 5s. setTimeout(connect, retryDelay) retryDelay = Math.min(retryDelay * 2, 5000) } @@ -67,12 +72,24 @@ export default function App() { connect() - // Cleanup on unmount — prevents duplicate SSE connections in React StrictMode. + // Cleanup on unmount -- prevents duplicate SSE connections in React StrictMode. return () => { es?.close() } }, []) // Empty dep array: connect once, reconnect is managed inside + if (fatalError) { + return ( +
+
+
+

Connection lost. The server restarted or the session expired.

+ +
+
+ ) + } + return (
diff --git a/frontend/src/sse/connect.ts b/frontend/src/sse/connect.ts index 4990f8e..c9fb9b7 100644 --- a/frontend/src/sse/connect.ts +++ b/frontend/src/sse/connect.ts @@ -1,132 +1,58 @@ -import { KoanStore, AgentInfo, ArtifactFile, ActivityEntry, Interaction, CompletionInfo } from '../store/index' +import { KoanStore } from '../store/index' -// connectSSE opens an EventSource and wires every SSE event type to a store action. +// connectSSE opens an EventSource using version-negotiated catch-up: +// ?since=0 → server sends a snapshot event, then live events +// ?since=N → server replays events N+1..M, then live events +// // Returns the EventSource so the caller can close it on unmount or reconnect. -// Does NOT schedule its own reconnect — App.tsx owns that lifecycle. +// Does NOT schedule its own reconnect -- App.tsx owns that lifecycle. export function connectSSE(store: KoanStore): EventSource { - const es = new EventSource('/events') + const lastVersion = store.getState().lastVersion + const es = new EventSource(`/events?since=${lastVersion}`) store.getState().setConnected(true) - // ── Structural events ────────────────────────────────────────────────────── + // ── Snapshot: atomic state replace (since=0) ─────────────────────────── - es.addEventListener('phase', (e) => { - const d = JSON.parse((e as MessageEvent).data) as { phase: string } - store.getState().setPhase(d.phase) + es.addEventListener('snapshot', (e) => { + const data = JSON.parse((e as MessageEvent).data) as Record + store.getState().applySnapshot(data) }) - es.addEventListener('subagent', (e) => { - const d = JSON.parse((e as MessageEvent).data) as Record - // _build_subagent_json returns {"agent_id": None} when no primary agent is active. - // Guard against this to avoid setting primaryAgent to an object with undefined fields. - if (d['agent_id'] === null || d['agent_id'] === undefined) { - store.getState().setPrimaryAgent(null) - return - } - store.getState().setPrimaryAgent({ - agentId: d['agent_id'] as string, - role: d['role'] as string, - model: d['model'] as string | null, - step: d['step'] as number, - stepName: d['step_name'] as string, - startedAt: d['started_at_ms'] as number, - tokensSent: d['tokens_sent'] as number, - tokensReceived: d['tokens_received'] as number, - } satisfies AgentInfo) - }) - - es.addEventListener('subagent-idle', () => { - store.getState().setPrimaryAgent(null) - }) - - es.addEventListener('agents', (e) => { - const d = JSON.parse((e as MessageEvent).data) as { agents: Record[] } - // d.agents is an array from _build_agents_json(). Python emits snake_case; - // map to camelCase here at the bridge boundary. - // Without this mapping, Object.fromEntries would key everything under "undefined" - // because a.agentId doesn't exist on the raw JSON (it's a.agent_id). - const scouts = Object.fromEntries( - d.agents.map((a) => [a['agent_id'] as string, { - agentId: a['agent_id'] as string, - role: a['role'] as string, - model: a['model'] as string | null, - step: a['step'] as number, - stepName: a['step_name'] as string, - startedAt: a['started_at_ms'] as number, - tokensSent: a['tokens_sent'] as number, - tokensReceived: a['tokens_received'] as number, - } satisfies AgentInfo]) - ) - store.getState().setScouts(scouts) - }) - - es.addEventListener('artifacts', (e) => { - const d = JSON.parse((e as MessageEvent).data) as { artifacts: ArtifactFile[] } - store.getState().setArtifacts(d.artifacts) - }) + // ── Fatal error: server cannot serve the requested version ───────────── + // Sent when ?since=N references a version the server no longer has + // (e.g. after server restart). Close without reconnect; App.tsx renders + // a "reload required" banner. - es.addEventListener('intake-progress', (e) => { - const d = JSON.parse((e as MessageEvent).data) as Record - store.getState().setIntakeProgress({ - subPhase: (d['subPhase'] as string) ?? '', - confidence: (d['confidence'] as string | null) ?? null, - summary: (d['summary'] as string) ?? '', - }) - }) - - // ── High-frequency events ────────────────────────────────────────────────── - - es.addEventListener('token-delta', (e) => { - const d = JSON.parse((e as MessageEvent).data) as { delta: string } - store.getState().appendStreamDelta(d.delta) - }) - - es.addEventListener('token-clear', () => { - store.getState().clearStream() - }) - - es.addEventListener('logs', (e) => { - const d = JSON.parse((e as MessageEvent).data) as { line: ActivityEntry } - store.getState().appendLog(d.line) - }) - - // ── Notifications ────────────────────────────────────────────────────────── - - es.addEventListener('notification', (e) => { - const d = JSON.parse((e as MessageEvent).data) as Record - // Backend notification types are categorical event names (e.g. 'runner_error'), - // NOT severity levels. Map to severity here at the bridge boundary. - const SEVERITY_MAP: Record = { - runner_error: 'error', - bootstrap_failure: 'error', - spawn_failure: 'error', - interaction_cancelled: 'info', - config_warning: 'warning', - } - const type = d['type'] as string - store.getState().addNotification({ - id: crypto.randomUUID(), - type, - severity: SEVERITY_MAP[type] ?? 'info', - message: d['message'] as string, - detail: d['details'] as string | undefined, + es.addEventListener('fatal_error', () => { + store.getState().setFatalError(true) + store.getState().setConnected(false) + es.close() + // App.tsx overrides onerror -- but this is a named event, not an error. + // We do NOT call the reconnect path here. App.tsx checks fatalError + // in the reconnect scheduler and skips reconnect when it is set. + }) + + // ── All other events: incremental fold ──────────────────────────────── + + const KNOWN_EVENTS = [ + 'phase_started', 'agent_spawned', 'agent_spawn_failed', + 'agent_step_advanced', 'agent_exited', 'workflow_completed', + 'tool_called', 'tool_completed', 'thinking', 'stream_delta', 'stream_cleared', + 'questions_asked', 'questions_answered', + 'artifact_review_requested', 'artifact_reviewed', + 'workflow_decision_requested', 'workflow_decided', + 'artifact_created', 'artifact_modified', 'artifact_removed', + ] + + for (const eventType of KNOWN_EVENTS) { + es.addEventListener(eventType, (e) => { + const data = JSON.parse((e as MessageEvent).data) as Record + store.getState().applyEvent({ event_type: eventType, ...data }) }) - }) - - // ── Interactions ─────────────────────────────────────────────────────────── - - es.addEventListener('interaction', (e) => { - const d = JSON.parse((e as MessageEvent).data) as { type: string } & Record - // 'cleared' means the interaction was resolved; restore the activity feed. - store.getState().setInteraction(d.type === 'cleared' ? null : d as Interaction) - }) - - es.addEventListener('pipeline-end', (e) => { - const d = JSON.parse((e as MessageEvent).data) as CompletionInfo - store.getState().setCompletion(d) - }) + } - // onerror will be overridden by App.tsx to schedule reconnects. + // onerror is overridden by App.tsx to schedule reconnects. es.onerror = () => { store.getState().setConnected(false) es.close() diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 111ea7b..120055b 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -28,9 +28,7 @@ export interface ArtifactFile { export interface CompletionInfo { success: boolean summary: string - error: string - phase: string - artifacts: ArtifactFile[] + error?: string } export interface NotificationEntry { @@ -45,6 +43,7 @@ export interface ActivityEntry { tool: string summary: string inFlight: boolean + callId?: string ts?: string } @@ -71,7 +70,7 @@ export interface ChatTurn { export type Interaction = | { type: 'ask'; questions: AskQuestion[]; token: string } - | { type: 'artifact-review'; content: string; description?: string; token: string } + | { type: 'artifact-review'; content: string; description?: string; path?: string; token: string } | { type: 'workflow-decision'; chat_turns: ChatTurn[]; token: string } export interface ProfileTierConfig { @@ -94,11 +93,50 @@ export interface Installation { is_active?: boolean } +// Severity mapping for notification-worthy event types +const SEVERITY_MAP: Record = { + agent_spawn_failed: 'error', + agent_exited_error: 'error', +} + +// Map backend interaction_type event strings to frontend Interaction.type values +function interactionTypeToFrontend(interactionType: string): string { + switch (interactionType) { + case 'questions_asked': return 'ask' + case 'artifact_review_requested': return 'artifact-review' + case 'workflow_decision_requested': return 'workflow-decision' + default: return interactionType + } +} + +function transformAgent(a: Record): AgentInfo { + return { + agentId: a['agent_id'] as string, + role: a['role'] as string, + model: a['model'] as string | null, + step: (a['step'] as number) ?? 0, + stepName: (a['step_name'] as string) ?? '', + startedAt: (a['started_at_ms'] as number) ?? 0, + tokensSent: (a['input_tokens'] as number) ?? 0, + tokensReceived: (a['output_tokens'] as number) ?? 0, + } +} + +function transformArtifact(a: Record): ArtifactFile { + return { + path: a['path'] as string, + size: (a['size'] as number) ?? 0, + modifiedAt: (a['modified_at'] as number) ?? 0, + } +} + // -- Store ------------------------------------------------------------------- interface KoanState { // Connection connected: boolean + lastVersion: number + fatalError: boolean // Run state runStarted: boolean @@ -108,7 +146,10 @@ interface KoanState { // Primary agent (phase-level) primaryAgent: AgentInfo | null - // Intake sub-phase progress + // Completed agents (exited, token totals preserved) + completedAgents: AgentInfo[] + + // Intake sub-phase progress (legacy, kept for compatibility) intakeProgress: { subPhase: string; confidence: string | null; summary: string } | null // Scout agents — keyed by agentId @@ -124,10 +165,10 @@ interface KoanState { // Active interaction (at most one at a time) activeInteraction: Interaction | null - // Artifacts - artifacts: ArtifactFile[] + // Artifacts — keyed by path + artifacts: Record - // Pipeline completion + // Workflow completion completion: CompletionInfo | null // Settings @@ -135,49 +176,55 @@ interface KoanState { profiles: Profile[] installations: Installation[] - // Actions + // Legacy actions (used by existing components) setConnected: (v: boolean) => void setPhase: (phase: string) => void setPrimaryAgent: (agent: AgentInfo | null) => void setIntakeProgress: (p: KoanState['intakeProgress']) => void setScouts: (scouts: Record) => void appendLog: (entry: ActivityEntry) => void + completeLog: (callId: string) => void appendStreamDelta: (delta: string) => void clearStream: () => void addNotification: (n: NotificationEntry) => void dismissNotification: (id: string) => void setInteraction: (interaction: Interaction | null) => void - setArtifacts: (artifacts: ArtifactFile[]) => void + setArtifacts: (artifacts: Record) => void setCompletion: (info: CompletionInfo) => void setSettingsOpen: (v: boolean) => void setProfiles: (profiles: Profile[]) => void setInstallations: (installations: Installation[]) => void + setFatalError: (v: boolean) => void + + // Event-sourced actions + applySnapshot: (data: Record) => void + applyEvent: (event: Record) => void } -export const useStore = create((set) => ({ +export const useStore = create((set, get) => ({ connected: false, + lastVersion: 0, + fatalError: false, runStarted: false, phase: '', donePhases: [], primaryAgent: null, + completedAgents: [], intakeProgress: null, scouts: {}, activityLog: [], streamBuffer: '', notifications: [], activeInteraction: null, - artifacts: [], + artifacts: {}, completion: null, settingsOpen: false, profiles: [], installations: [], setConnected: (v) => set({ connected: v }), + setFatalError: (v) => set({ fatalError: v }), - // setPhase also sets runStarted=true (any phase event means a run is active) - // and derives donePhases (all known phases before current). This is critical - // for page reloads mid-run: the replayed 'phase' event flips runStarted, - // so the user sees the live view instead of the landing page. setPhase: (phase) => set(() => { const idx = ALL_PHASES.indexOf(phase) const donePhases = idx === -1 ? [...ALL_PHASES] : ALL_PHASES.slice(0, idx) @@ -188,6 +235,11 @@ export const useStore = create((set) => ({ setIntakeProgress: (p) => set({ intakeProgress: p }), setScouts: (scouts) => set({ scouts }), appendLog: (entry) => set((s) => ({ activityLog: [...s.activityLog, entry] })), + completeLog: (callId) => set((s) => ({ + activityLog: s.activityLog.map(e => + e.callId === callId ? { ...e, inFlight: false } : e + ), + })), appendStreamDelta: (delta) => set((s) => ({ streamBuffer: s.streamBuffer + delta })), clearStream: () => set({ streamBuffer: '' }), addNotification: (n) => set((s) => ({ notifications: [...s.notifications, n] })), @@ -200,6 +252,321 @@ export const useStore = create((set) => ({ setSettingsOpen: (v) => set({ settingsOpen: v }), setProfiles: (profiles) => set({ profiles }), setInstallations: (installations) => set({ installations }), + + // -- Snapshot: atomic state replace ---------------------------------------- + + applySnapshot: (data) => { + const version = data['version'] as number + const state = (data['state'] ?? {}) as Record + + const phase = (state['phase'] as string) ?? '' + const idx = ALL_PHASES.indexOf(phase) + const donePhases = idx === -1 ? [...ALL_PHASES] : ALL_PHASES.slice(0, idx) + + // Transform primary_agent + const rawPrimary = state['primary_agent'] as Record | null + const primaryAgent = rawPrimary ? transformAgent(rawPrimary) : null + + // Transform scouts + const rawScouts = (state['scouts'] ?? {}) as Record> + const scouts: Record = {} + for (const [id, a] of Object.entries(rawScouts)) { + scouts[id] = transformAgent(a) + } + + // Transform completed_agents + const rawCompleted = (state['completed_agents'] ?? []) as Record[] + const completedAgents = rawCompleted.map(transformAgent) + + // Transform artifacts + const rawArtifacts = (state['artifacts'] ?? {}) as Record> + const artifacts: Record = {} + for (const [path, a] of Object.entries(rawArtifacts)) { + artifacts[path] = transformArtifact(a) + } + + // Transform active_interaction: strip backend's interaction_type discriminator, + // map to frontend Interaction.type. + let activeInteraction: Interaction | null = null + const rawInteraction = state['active_interaction'] as Record | null + if (rawInteraction) { + const itype = interactionTypeToFrontend(rawInteraction['interaction_type'] as string) + const { interaction_type: _drop, ...interactionPayload } = rawInteraction + activeInteraction = { type: itype as Interaction['type'], ...interactionPayload } as Interaction + } + + // Transform notifications + const rawNotifs = (state['notifications'] ?? []) as Record[] + const notifications: NotificationEntry[] = rawNotifs.map((n) => ({ + id: crypto.randomUUID(), + type: (n['type'] as string) ?? 'unknown', + severity: SEVERITY_MAP[(n['type'] as string) ?? ''] ?? 'info', + message: (n['message'] as string) ?? (n['error'] as string) ?? '', + })) + + // Transform activity_log + // The backend fold appends both tool_called and tool_completed as raw entries. + // Reconstruct the collapsed one-entry-per-call view that the live applyEvent + // fold produces: exclude tool_completed entries and use them only to determine + // the inFlight state of their matching tool_called entry. + const rawLog = (state['activity_log'] ?? []) as Record[] + const completedCallIds = new Set( + rawLog + .filter(e => e['event_type'] === 'tool_completed') + .map(e => e['call_id'] as string) + .filter(Boolean) + ) + const activityLog: ActivityEntry[] = rawLog + .filter(e => e['event_type'] !== 'tool_completed') + .map((e) => { + const callId = e['call_id'] as string | undefined + const isToolCall = e['event_type'] === 'tool_called' + const inFlight = isToolCall ? !completedCallIds.has(callId ?? '') : false + return { + tool: (e['tool'] as string) ?? (e['event_type'] as string) ?? '', + summary: (e['summary'] as string) ?? (e['delta'] as string) ?? '', + inFlight, + callId, + ts: e['ts'] as string | undefined, + } + }) + + const completion = state['completion'] as CompletionInfo | null + + set({ + lastVersion: version, + phase, + runStarted: phase !== '', + donePhases, + primaryAgent, + scouts, + completedAgents, + artifacts, + activeInteraction, + notifications, + activityLog, + streamBuffer: (state['stream_buffer'] as string) ?? '', + completion: completion ?? null, + }) + }, + + // -- Event fold: mirrors backend fold -------------------------------------- + + applyEvent: (event) => { + const eventType = event['event_type'] as string + const version = event['version'] as number + const agentId = event['agent_id'] as string | null + + set((s) => { + // Update lastVersion + const base = { lastVersion: version } + + switch (eventType) { + + // ── Lifecycle ────────────────────────────────────────────────────── + + case 'phase_started': { + const phase = event['phase'] as string + const idx = ALL_PHASES.indexOf(phase) + const donePhases = idx === -1 ? [...ALL_PHASES] : ALL_PHASES.slice(0, idx) + return { ...base, phase, runStarted: true, donePhases } + } + + case 'agent_spawned': { + const isPrimary = event['is_primary'] as boolean ?? true + const agent: AgentInfo = { + agentId: (event['agent_id'] as string) ?? agentId ?? '', + role: event['role'] as string, + model: event['model'] as string | null, + step: 0, + stepName: '', + startedAt: (event['started_at_ms'] as number) ?? 0, + tokensSent: 0, + tokensReceived: 0, + } + if (isPrimary) { + return { ...base, primaryAgent: agent } + } else { + return { ...base, scouts: { ...s.scouts, [agent.agentId]: agent } } + } + } + + case 'agent_spawn_failed': { + const notif: NotificationEntry = { + id: crypto.randomUUID(), + type: 'agent_spawn_failed', + severity: 'error', + message: (event['message'] as string) ?? 'Agent spawn failed', + } + return { ...base, notifications: [...s.notifications, notif] } + } + + case 'agent_step_advanced': { + const step = event['step'] as number + const stepName = (event['step_name'] as string) ?? '' + const usage = event['usage'] as Record | undefined + if (s.primaryAgent?.agentId === agentId) { + return { ...base, primaryAgent: { ...s.primaryAgent, step, stepName, + tokensSent: s.primaryAgent.tokensSent + (usage?.['input_tokens'] ?? 0), + tokensReceived: s.primaryAgent.tokensReceived + (usage?.['output_tokens'] ?? 0), + } } + } else if (agentId && agentId in s.scouts) { + const scout = s.scouts[agentId] + return { ...base, scouts: { ...s.scouts, [agentId]: { ...scout, step, stepName, + tokensSent: scout.tokensSent + (usage?.['input_tokens'] ?? 0), + tokensReceived: scout.tokensReceived + (usage?.['output_tokens'] ?? 0), + } } } + } + return base + } + + case 'agent_exited': { + const error = event['error'] as string | undefined + const usage = event['usage'] as Record | undefined + const newNotifs = error ? [ + ...s.notifications, + { + id: crypto.randomUUID(), + type: 'agent_exited_error', + severity: 'error' as const, + message: `Agent exited with error: ${error}`, + }, + ] : s.notifications + + // Mirror backend _accumulate_usage: apply final token delta before + // moving the agent to completedAgents. + function applyUsage(agent: AgentInfo): AgentInfo { + if (!usage) return agent + return { + ...agent, + tokensSent: agent.tokensSent + (usage['input_tokens'] ?? 0), + tokensReceived: agent.tokensReceived + (usage['output_tokens'] ?? 0), + } + } + + if (s.primaryAgent?.agentId === agentId) { + const finalAgent = applyUsage(s.primaryAgent) + return { ...base, primaryAgent: null, completedAgents: [...s.completedAgents, finalAgent], notifications: newNotifs } + } else if (agentId && agentId in s.scouts) { + const finalAgent = applyUsage(s.scouts[agentId]) + const { [agentId]: _, ...rest } = s.scouts + return { ...base, scouts: rest, completedAgents: [...s.completedAgents, finalAgent], notifications: newNotifs } + } + return { ...base, notifications: newNotifs } + } + + case 'workflow_completed': { + const completion: CompletionInfo = { + success: event['success'] as boolean, + summary: (event['summary'] as string) ?? '', + error: event['error'] as string | undefined, + } + return { ...base, completion } + } + + // ── Activity ─────────────────────────────────────────────────────── + + case 'tool_called': { + const entry: ActivityEntry = { + tool: (event['tool'] as string) ?? 'tool', + summary: (event['summary'] as string) ?? '', + inFlight: true, + callId: event['call_id'] as string, + ts: new Date().toISOString(), + } + return { ...base, activityLog: [...s.activityLog, entry] } + } + + case 'tool_completed': { + const callId = event['call_id'] as string + return { + ...base, + activityLog: s.activityLog.map(e => + e.callId === callId ? { ...e, inFlight: false } : e + ), + } + } + + case 'thinking': { + const entry: ActivityEntry = { + tool: '', + summary: (event['delta'] as string) ?? 'thinking...', + inFlight: false, + ts: new Date().toISOString(), + } + return { ...base, activityLog: [...s.activityLog, entry] } + } + + case 'stream_delta': + return { ...base, streamBuffer: s.streamBuffer + ((event['delta'] as string) ?? '') } + + case 'stream_cleared': + return { ...base, streamBuffer: '' } + + // ── Interactions ─────────────────────────────────────────────────── + + case 'questions_asked': { + const interaction: Interaction = { + type: 'ask', + token: event['token'] as string, + questions: (event['questions'] as AskQuestion[]) ?? [], + } + return { ...base, activeInteraction: interaction } + } + + case 'questions_answered': + return { ...base, activeInteraction: null } + + case 'artifact_review_requested': { + const interaction: Interaction = { + type: 'artifact-review', + token: event['token'] as string, + path: event['path'] as string, + description: event['description'] as string | undefined, + content: (event['content'] as string) ?? '', + } + return { ...base, activeInteraction: interaction } + } + + case 'artifact_reviewed': + return { ...base, activeInteraction: null } + + case 'workflow_decision_requested': { + const interaction: Interaction = { + type: 'workflow-decision', + token: event['token'] as string, + chat_turns: (event['chat_turns'] as ChatTurn[]) ?? [], + } + return { ...base, activeInteraction: interaction } + } + + case 'workflow_decided': + return { ...base, activeInteraction: null } + + // ── Resources ────────────────────────────────────────────────────── + + case 'artifact_created': + case 'artifact_modified': { + const path = event['path'] as string + const artifact: ArtifactFile = { + path, + size: (event['size'] as number) ?? 0, + modifiedAt: (event['modified_at'] as number) ?? 0, + } + return { ...base, artifacts: { ...s.artifacts, [path]: artifact } } + } + + case 'artifact_removed': { + const path = event['path'] as string + const { [path]: _, ...rest } = s.artifacts + return { ...base, artifacts: rest } + } + + default: + return base + } + }) + }, })) export type KoanStore = typeof useStore diff --git a/frontend/src/store/selectors.ts b/frontend/src/store/selectors.ts index 4df379e..fb2149a 100644 --- a/frontend/src/store/selectors.ts +++ b/frontend/src/store/selectors.ts @@ -1,7 +1,7 @@ import { useMemo } from 'react' -import { useStore, ArtifactFile } from './index' +import { useStore, ArtifactFile, ALL_PHASES } from './index' -// Subscribe to the raw scouts Record — reference-stable until setScouts is called. +// Subscribe to the raw scouts Record -- reference-stable until setScouts is called. // Derive the array in the component via useMemo to avoid creating a new array // on every render (which would trigger useSyncExternalStore's infinite loop). export function useScoutList() { @@ -16,6 +16,15 @@ export const usePrimaryAgent = () => useStore(s => s.primaryAgent) // without subscribing to the full interaction payload. export const useHasInteraction = () => useStore(s => s.activeInteraction !== null) +// Derive done phases from current phase -- frontend-only derivation. +export function useDonePhases(): string[] { + const phase = useStore(s => s.phase) + return useMemo(() => { + const idx = ALL_PHASES.indexOf(phase) + return idx === -1 ? [...ALL_PHASES] : ALL_PHASES.slice(0, idx) + }, [phase]) +} + function groupByDirectory(artifacts: ArtifactFile[]): Record { const tree: Record = {} for (const a of artifacts) { @@ -27,9 +36,8 @@ function groupByDirectory(artifacts: ArtifactFile[]): Record s.artifacts) - return useMemo(() => groupByDirectory(artifacts), [artifacts]) + return useMemo(() => groupByDirectory(Object.values(artifacts)), [artifacts]) } From 92ad4f9666e8c34e4c95004eabb86797646caae7 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 12:52:15 +0700 Subject: [PATCH 199/412] update tests for projection system --- tests/test_interactions.py | 78 +++--- tests/test_projections.py | 533 +++++++++++++++++++++++++++++++++++++ tests/test_runners.py | 4 +- tests/test_subagent.py | 69 ++--- tests/test_web_flows.py | 130 ++++++--- 5 files changed, 688 insertions(+), 126 deletions(-) create mode 100644 tests/test_projections.py diff --git a/tests/test_interactions.py b/tests/test_interactions.py index 5e33d4c..7b35e29 100644 --- a/tests/test_interactions.py +++ b/tests/test_interactions.py @@ -27,13 +27,12 @@ class FakeAppState: agents: dict = field(default_factory=dict) config: FakeConfig = field(default_factory=FakeConfig) port: int = 9999 - sse_clients: list = field(default_factory=list) active_interaction: PendingInteraction | None = None interaction_queue: deque[PendingInteraction] = field(default_factory=deque) interaction_queue_max: int = 8 frozen_logs: list = field(default_factory=list) - last_sse_values: dict = field(default_factory=dict) epic_dir: str | None = None + projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) def _make_interaction( @@ -76,8 +75,7 @@ async def test_9th_request_raises_queue_full(self): subagent_dir="/tmp/test", ) - with patch("koan.web.interactions._push_sse"): - with pytest.raises(ToolError) as exc_info: + with pytest.raises(ToolError) as exc_info: await enqueue_interaction(agent, app_state, "ask", {"questions": []}) err = json.loads(str(exc_info.value)) @@ -102,8 +100,7 @@ async def test_8th_request_succeeds(self): subagent_dir="/tmp/test", ) - with patch("koan.web.interactions._push_sse"): - future = await enqueue_interaction(agent, app_state, "ask", {"questions": []}) + future = await enqueue_interaction(agent, app_state, "ask", {"questions": []}) assert not future.done() assert len(app_state.interaction_queue) == 8 @@ -193,10 +190,8 @@ def _setup_workflow(self): ) app_state.active_interaction = interaction - from unittest.mock import patch as _patch - with _patch("koan.web.interactions._push_sse"): - app = create_app(app_state) - client = TestClient(app, raise_server_exceptions=False) + app = create_app(app_state) + client = TestClient(app, raise_server_exceptions=False) return client, interaction @pytest.mark.anyio @@ -252,22 +247,21 @@ async def test_fifo_order_preserved(self): app_state.active_interaction = _make_interaction(agent_id="initial") app_state.interaction_queue.extend([a, b, c]) - with patch("koan.web.interactions._push_sse"): - # Resolve initial -> A becomes active - activate_next_interaction(app_state) - assert app_state.active_interaction is a + # Resolve initial -> A becomes active + activate_next_interaction(app_state) + assert app_state.active_interaction is a - # Resolve A -> B becomes active - activate_next_interaction(app_state) - assert app_state.active_interaction is b + # Resolve A -> B becomes active + activate_next_interaction(app_state) + assert app_state.active_interaction is b - # Resolve B -> C becomes active - activate_next_interaction(app_state) - assert app_state.active_interaction is c + # Resolve B -> C becomes active + activate_next_interaction(app_state) + assert app_state.active_interaction is c - # Resolve C -> None - activate_next_interaction(app_state) - assert app_state.active_interaction is None + # Resolve C -> None + activate_next_interaction(app_state) + assert app_state.active_interaction is None # -- TestCancellationOnExit --------------------------------------------------- @@ -281,9 +275,7 @@ async def test_cancel_active_interaction_on_agent_exit(self): interaction = _make_interaction(agent_id="agent-1") app_state.active_interaction = interaction - with patch("koan.subagent._push_sse"), \ - patch("koan.web.interactions._push_sse"): - _cancel_pending_interactions("agent-1", app_state) + _cancel_pending_interactions("agent-1", app_state) assert interaction.future.done() assert interaction.future.result()["error"] == "agent_exited" @@ -299,9 +291,7 @@ async def test_cancel_queued_interactions_on_agent_exit(self): other = _make_interaction(agent_id="agent-2") app_state.interaction_queue.extend([mine_1, other, mine_2]) - with patch("koan.subagent._push_sse"), \ - patch("koan.web.interactions._push_sse"): - _cancel_pending_interactions("agent-1", app_state) + _cancel_pending_interactions("agent-1", app_state) assert mine_1.future.done() assert mine_1.future.result()["error"] == "agent_exited" @@ -323,9 +313,7 @@ async def test_next_queued_activated_after_cancel(self): app_state.active_interaction = active_a app_state.interaction_queue.append(queued_b) - with patch("koan.subagent._push_sse"), \ - patch("koan.web.interactions._push_sse"): - _cancel_pending_interactions("agent-A", app_state) + _cancel_pending_interactions("agent-A", app_state) assert active_a.future.done() assert app_state.active_interaction is queued_b @@ -345,13 +333,12 @@ async def test_accept_resolves_future_with_accepted_true(self): interaction = _make_interaction(interaction_type="artifact-review") app_state.active_interaction = interaction - with patch("koan.web.interactions._push_sse"): - app = create_app(app_state) - client = TestClient(app, raise_server_exceptions=False) - resp = client.post( - "/api/artifact-review", - json={"accepted": True, "token": interaction.token}, - ) + app = create_app(app_state) + client = TestClient(app, raise_server_exceptions=False) + resp = client.post( + "/api/artifact-review", + json={"accepted": True, "token": interaction.token}, + ) assert resp.status_code == 200 result = interaction.future.result() @@ -369,13 +356,12 @@ async def test_feedback_resolves_future_with_accepted_false(self): interaction = _make_interaction(interaction_type="artifact-review") app_state.active_interaction = interaction - with patch("koan.web.interactions._push_sse"): - app = create_app(app_state) - client = TestClient(app, raise_server_exceptions=False) - resp = client.post( - "/api/artifact-review", - json={"response": "Please add more detail", "token": interaction.token}, - ) + app = create_app(app_state) + client = TestClient(app, raise_server_exceptions=False) + resp = client.post( + "/api/artifact-review", + json={"response": "Please add more detail", "token": interaction.token}, + ) assert resp.status_code == 200 result = interaction.future.result() diff --git a/tests/test_projections.py b/tests/test_projections.py new file mode 100644 index 0000000..7be0a83 --- /dev/null +++ b/tests/test_projections.py @@ -0,0 +1,533 @@ +# Tests for koan.projections (ProjectionStore, fold) and koan.events (build_artifact_diff). + +from __future__ import annotations + +import asyncio +import json + +import pytest + +from koan.projections import ( + AgentProjection, + Projection, + ProjectionStore, + VersionedEvent, + fold, +) + + +# -- fold: lifecycle ----------------------------------------------------------- + +class TestFoldLifecycle: + def _event(self, event_type: str, payload: dict, agent_id: str | None = None, version: int = 1) -> VersionedEvent: + return VersionedEvent( + version=version, + event_type=event_type, + timestamp="2026-01-01T00:00:00Z", + agent_id=agent_id, + payload=payload, + ) + + def test_phase_started(self): + p = Projection() + e = self._event("phase_started", {"phase": "intake"}) + r = fold(p, e) + assert r.phase == "intake" + assert r.run_started is True + + def test_agent_spawned_primary(self): + p = Projection() + e = self._event("agent_spawned", {"role": "intake", "model": "opus", "is_primary": True}, agent_id="a1") + r = fold(p, e) + assert r.primary_agent is not None + assert r.primary_agent.agent_id == "a1" + assert r.primary_agent.role == "intake" + + def test_agent_spawned_scout(self): + p = Projection() + e = self._event("agent_spawned", {"role": "scout", "model": None, "is_primary": False}, agent_id="s1") + r = fold(p, e) + assert "s1" in r.scouts + assert r.primary_agent is None + + def test_agent_spawn_failed(self): + p = Projection() + e = self._event("agent_spawn_failed", {"role": "intake", "error_code": "binary_not_found", "message": "not found"}) + r = fold(p, e) + assert len(r.notifications) == 1 + assert r.notifications[0]["type"] == "agent_spawn_failed" + assert r.notifications[0]["error_code"] == "binary_not_found" + + def test_agent_step_advanced(self): + p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake")) + e = self._event("agent_step_advanced", {"step": 2, "step_name": "Scout"}, agent_id="a1") + r = fold(p, e) + assert r.primary_agent.step == 2 + assert r.primary_agent.step_name == "Scout" + + def test_agent_step_advanced_unknown_agent(self): + p = Projection() + e = self._event("agent_step_advanced", {"step": 1, "step_name": "X"}, agent_id="unknown") + r = fold(p, e) + # Unknown agent: unchanged + assert r == p + + def test_agent_step_advanced_accumulates_usage(self): + p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake", output_tokens=10)) + e = self._event("agent_step_advanced", {"step": 1, "step_name": "", "usage": {"input_tokens": 5, "output_tokens": 20}}, agent_id="a1") + r = fold(p, e) + assert r.primary_agent.input_tokens == 5 + assert r.primary_agent.output_tokens == 30 + + def test_agent_exited_primary(self): + p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake")) + e = self._event("agent_exited", {"exit_code": 0}, agent_id="a1") + r = fold(p, e) + assert r.primary_agent is None + assert len(r.completed_agents) == 1 + assert r.completed_agents[0].agent_id == "a1" + + def test_agent_exited_accumulates_final_tokens(self): + p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake", output_tokens=50)) + e = self._event("agent_exited", {"exit_code": 0, "usage": {"output_tokens": 25}}, agent_id="a1") + r = fold(p, e) + assert r.completed_agents[0].output_tokens == 75 + assert r.primary_agent is None + + def test_agent_exited_with_error_appends_notification(self): + p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake")) + e = self._event("agent_exited", {"exit_code": 1, "error": "bootstrap_failure"}, agent_id="a1") + r = fold(p, e) + assert len(r.notifications) == 1 + assert r.notifications[0]["error"] == "bootstrap_failure" + assert r.notifications[0]["type"] == "agent_exited_error" + + def test_agent_exited_scout(self): + p = Projection(scouts={"s1": AgentProjection(agent_id="s1", role="scout")}) + e = self._event("agent_exited", {"exit_code": 0}, agent_id="s1") + r = fold(p, e) + assert "s1" not in r.scouts + assert len(r.completed_agents) == 1 + + def test_workflow_completed(self): + p = Projection() + e = self._event("workflow_completed", {"success": True, "summary": "done"}) + r = fold(p, e) + assert r.completion == {"success": True, "summary": "done"} + + +# -- fold: activity ----------------------------------------------------------- + +class TestFoldActivity: + def _event(self, event_type: str, payload: dict, agent_id: str | None = None) -> VersionedEvent: + return VersionedEvent(version=1, event_type=event_type, timestamp="2026-01-01T00:00:00Z", + agent_id=agent_id, payload=payload) + + def test_tool_called_appended(self): + p = Projection() + e = self._event("tool_called", {"call_id": "c1", "tool": "read", "args": {}, "summary": "reading"}, "a1") + r = fold(p, e) + assert len(r.activity_log) == 1 + assert r.activity_log[0]["event_type"] == "tool_called" + assert r.activity_log[0]["tool"] == "read" + + def test_tool_completed_appended(self): + p = Projection() + e = self._event("tool_completed", {"call_id": "c1", "tool": "read"}, "a1") + r = fold(p, e) + assert len(r.activity_log) == 1 + assert r.activity_log[0]["event_type"] == "tool_completed" + + def test_thinking_appended(self): + p = Projection() + e = self._event("thinking", {"delta": "hmm"}, "a1") + r = fold(p, e) + assert len(r.activity_log) == 1 + assert r.activity_log[0]["delta"] == "hmm" + + def test_stream_delta_accumulates(self): + p = Projection(stream_buffer="hello ") + e = self._event("stream_delta", {"delta": "world"}) + r = fold(p, e) + assert r.stream_buffer == "hello world" + + def test_stream_cleared(self): + p = Projection(stream_buffer="some content") + e = self._event("stream_cleared", {}) + r = fold(p, e) + assert r.stream_buffer == "" + + +# -- fold: interactions ------------------------------------------------------- + +class TestFoldInteractions: + def _event(self, event_type: str, payload: dict) -> VersionedEvent: + return VersionedEvent(version=1, event_type=event_type, timestamp="2026-01-01T00:00:00Z", + agent_id="a1", payload=payload) + + def test_questions_asked_sets_active(self): + p = Projection() + e = self._event("questions_asked", {"token": "t1", "questions": [{"question": "Q1"}]}) + r = fold(p, e) + assert r.active_interaction is not None + assert r.active_interaction["interaction_type"] == "questions_asked" + assert r.active_interaction["token"] == "t1" + + def test_questions_answered_clears(self): + p = Projection(active_interaction={"interaction_type": "questions_asked", "token": "t1"}) + e = self._event("questions_answered", {"token": "t1", "cancelled": False}) + r = fold(p, e) + assert r.active_interaction is None + + def test_artifact_review_request_response_cycle(self): + p = Projection() + req = self._event("artifact_review_requested", {"token": "t2", "path": "/tmp/f.md", "description": "d", "content": "c"}) + p2 = fold(p, req) + assert p2.active_interaction["interaction_type"] == "artifact_review_requested" + res = self._event("artifact_reviewed", {"token": "t2", "accepted": True, "cancelled": False}) + p3 = fold(p2, res) + assert p3.active_interaction is None + + def test_workflow_decision_cycle(self): + p = Projection() + req = self._event("workflow_decision_requested", {"token": "t3", "chat_turns": []}) + p2 = fold(p, req) + assert p2.active_interaction["interaction_type"] == "workflow_decision_requested" + res = self._event("workflow_decided", {"token": "t3", "cancelled": False}) + p3 = fold(p2, res) + assert p3.active_interaction is None + + def test_cancelled_resolution_clears(self): + p = Projection(active_interaction={"interaction_type": "questions_asked", "token": "t1"}) + e = self._event("questions_answered", {"token": "t1", "cancelled": True}) + r = fold(p, e) + assert r.active_interaction is None + + +# -- fold: resources ---------------------------------------------------------- + +class TestFoldResources: + def _event(self, event_type: str, payload: dict) -> VersionedEvent: + return VersionedEvent(version=1, event_type=event_type, timestamp="2026-01-01T00:00:00Z", + agent_id=None, payload=payload) + + def test_artifact_created(self): + p = Projection() + e = self._event("artifact_created", {"path": "foo.md", "size": 100, "modified_at": 1000}) + r = fold(p, e) + assert "foo.md" in r.artifacts + assert r.artifacts["foo.md"]["size"] == 100 + + def test_artifact_modified(self): + p = Projection(artifacts={"foo.md": {"path": "foo.md", "size": 50, "modified_at": 500}}) + e = self._event("artifact_modified", {"path": "foo.md", "size": 200, "modified_at": 2000}) + r = fold(p, e) + assert r.artifacts["foo.md"]["size"] == 200 + + def test_artifact_removed(self): + p = Projection(artifacts={"foo.md": {"path": "foo.md", "size": 100, "modified_at": 1000}}) + e = self._event("artifact_removed", {"path": "foo.md"}) + r = fold(p, e) + assert "foo.md" not in r.artifacts + + +# -- fold: safety ----------------------------------------------------------- + +class TestFoldSafety: + def _event(self, event_type: str, payload: dict) -> VersionedEvent: + return VersionedEvent(version=1, event_type=event_type, timestamp="2026-01-01T00:00:00Z", + agent_id=None, payload=payload) + + def test_unknown_event_type_unchanged(self): + p = Projection(phase="intake") + e = self._event("completely_unknown_type", {"data": 42}) + r = fold(p, e) + assert r == p + + def test_unknown_agent_id_unchanged(self): + p = Projection() # no agents registered + e = VersionedEvent(version=1, event_type="agent_step_advanced", timestamp="2026-01-01T00:00:00Z", + agent_id="nonexistent", payload={"step": 1, "step_name": "X"}) + r = fold(p, e) + assert r == p + + def test_phase_started_empty_payload_returns_empty_phase(self): + # Verifies that phase_started with {} payload returns phase="" (not an error). + # This is valid input -- fold does not throw on missing-but-defaulted fields. + p = Projection(phase="intake") + e = VersionedEvent(version=1, event_type="phase_started", timestamp="2026-01-01T00:00:00Z", + agent_id=None, payload={}) + r = fold(p, e) + assert r.phase == "" + assert r.run_started is True + + def test_fold_is_pure(self): + p = Projection(phase="intake") + e = self._event("phase_started", {"phase": "brief-generation"}) + r1 = fold(p, e) + r2 = fold(p, e) + assert r1 == r2 + # Input projection unchanged + assert p.phase == "intake" + + +# -- ProjectionStore ---------------------------------------------------------- + +class TestProjectionStore: + def test_push_increments_version(self): + store = ProjectionStore() + assert store.version == 0 + store.push_event("phase_started", {"phase": "intake"}) + assert store.version == 1 + store.push_event("phase_started", {"phase": "brief-generation"}) + assert store.version == 2 + + def test_fold_applied_to_projection(self): + store = ProjectionStore() + store.push_event("phase_started", {"phase": "intake"}) + assert store.projection.phase == "intake" + + def test_get_snapshot_includes_version(self): + store = ProjectionStore() + store.push_event("phase_started", {"phase": "intake"}) + snap = store.get_snapshot() + assert snap["version"] == 1 + assert snap["state"]["phase"] == "intake" + + def test_events_since(self): + store = ProjectionStore() + store.push_event("phase_started", {"phase": "intake"}) + store.push_event("phase_started", {"phase": "brief-generation"}) + store.push_event("phase_started", {"phase": "core-flows"}) + events = store.events_since(1) + assert len(events) == 2 + assert events[0].version == 2 + assert events[1].version == 3 + + def test_events_since_zero_returns_all(self): + store = ProjectionStore() + store.push_event("phase_started", {"phase": "intake"}) + assert len(store.events_since(0)) == 1 + + @pytest.mark.anyio + async def test_broadcast_to_subscribers(self): + store = ProjectionStore() + q = store.subscribe() + store.push_event("phase_started", {"phase": "intake"}) + event = await asyncio.wait_for(q.get(), timeout=1.0) + assert event.event_type == "phase_started" + store.unsubscribe(q) + + @pytest.mark.anyio + async def test_unsubscribe_stops_delivery(self): + store = ProjectionStore() + q = store.subscribe() + store.unsubscribe(q) + store.push_event("phase_started", {"phase": "intake"}) + assert q.empty() + + def test_subscriber_snapshot_avoids_mutation_during_broadcast(self): + """push_event snapshots subscribers before iterating.""" + store = ProjectionStore() + q1 = store.subscribe() + # Should not raise even if we unsubscribe q1 from inside a subscriber + store.push_event("phase_started", {"phase": "intake"}) + store.unsubscribe(q1) + # No exception = pass + + def test_fold_exception_leaves_log_intact_projection_unchanged(self, monkeypatch): + """ProjectionStore: if fold() raises, event stays in log but projection is unchanged.""" + import koan.projections as proj_mod + original_fold = proj_mod.fold + + call_count = [0] + + def raising_fold(projection, event): + call_count[0] += 1 + if call_count[0] == 1: + raise RuntimeError("simulated fold failure") + return original_fold(projection, event) + + monkeypatch.setattr(proj_mod, "fold", raising_fold) + + store = proj_mod.ProjectionStore() + # First push: fold raises, projection stays at default, but event IS in log + store.push_event("phase_started", {"phase": "intake"}) + assert store.version == 1 + assert store.events[0].event_type == "phase_started" + assert store.projection.phase == "" # unchanged -- fold raised + + # Second push: fold succeeds, projection advances + store.push_event("phase_started", {"phase": "brief-generation"}) + assert store.version == 2 + assert store.projection.phase == "brief-generation" + + +# -- build_artifact_diff ------------------------------------------------------ + +class TestBuildArtifactDiff: + def test_created(self): + from koan.events import build_artifact_diff + old = {} + new = [{"path": "foo.md", "size": 100, "modified_at": 1.0}] + events = build_artifact_diff(old, new) + assert len(events) == 1 + assert events[0][0] == "artifact_created" + assert events[0][1]["path"] == "foo.md" + assert events[0][1]["modified_at"] == 1000 # ms + + def test_removed(self): + from koan.events import build_artifact_diff + old = {"foo.md": {"path": "foo.md", "size": 100, "modified_at": 1000}} + new = [] + events = build_artifact_diff(old, new) + assert len(events) == 1 + assert events[0][0] == "artifact_removed" + assert events[0][1]["path"] == "foo.md" + + def test_modified_by_size(self): + from koan.events import build_artifact_diff + old = {"foo.md": {"path": "foo.md", "size": 50, "modified_at": 1000}} + new = [{"path": "foo.md", "size": 100, "modified_at": 1.0}] + events = build_artifact_diff(old, new) + assert len(events) == 1 + assert events[0][0] == "artifact_modified" + + def test_modified_by_mtime(self): + from koan.events import build_artifact_diff + old = {"foo.md": {"path": "foo.md", "size": 100, "modified_at": 1000}} + new = [{"path": "foo.md", "size": 100, "modified_at": 2.0}] + events = build_artifact_diff(old, new) + assert len(events) == 1 + assert events[0][0] == "artifact_modified" + + def test_unchanged_produces_no_events(self): + from koan.events import build_artifact_diff + old = {"foo.md": {"path": "foo.md", "size": 100, "modified_at": 1000}} + new = [{"path": "foo.md", "size": 100, "modified_at": 1.0}] + events = build_artifact_diff(old, new) + assert events == [] + + def test_mixed_diff(self): + from koan.events import build_artifact_diff + old = { + "a.md": {"path": "a.md", "size": 10, "modified_at": 1000}, + "b.md": {"path": "b.md", "size": 20, "modified_at": 2000}, + } + new = [ + {"path": "a.md", "size": 15, "modified_at": 1.0}, # modified + {"path": "c.md", "size": 30, "modified_at": 3.0}, # created + # b.md removed + ] + events = build_artifact_diff(old, new) + types = [e[0] for e in events] + assert "artifact_modified" in types + assert "artifact_created" in types + assert "artifact_removed" in types + + +# -- Tool name normalization (runner integration) ---------------------------- + +class TestToolNameNormalization: + def test_claude_normalizes_Read(self): + import json + from koan.runners.claude import ClaudeRunner + runner = ClaudeRunner(subagent_dir="/tmp/test") + line = json.dumps({ + "type": "assistant", + "content": [{"type": "tool_use", "name": "Read", "input": {"file_path": "/tmp/f"}}], + }) + evts = runner.parse_stream_event(line) + assert len(evts) == 1 + assert evts[0].tool_name == "read" + + def test_claude_normalizes_Bash(self): + import json + from koan.runners.claude import ClaudeRunner + runner = ClaudeRunner(subagent_dir="/tmp/test") + line = json.dumps({ + "type": "assistant", + "content": [{"type": "tool_use", "name": "Bash", "input": {"command": "ls"}}], + }) + evts = runner.parse_stream_event(line) + assert len(evts) == 1 + assert evts[0].tool_name == "bash" + + def test_claude_filters_koan_mcp_tool(self): + import json + from koan.runners.claude import ClaudeRunner + runner = ClaudeRunner(subagent_dir="/tmp/test") + line = json.dumps({ + "type": "assistant", + "content": [{"type": "tool_use", "name": "koan_complete_step", "input": {}}], + }) + evts = runner.parse_stream_event(line) + assert evts == [] + + def test_codex_normalizes_read_file(self): + import json + from koan.runners.codex import CodexRunner + runner = CodexRunner() + line = json.dumps({"type": "item.completed", "item": {"type": "function_call", "name": "read_file", "arguments": "{}"}}) + evts = runner.parse_stream_event(line) + assert len(evts) == 1 + assert evts[0].tool_name == "read" + + def test_codex_filters_koan_mcp_tool(self): + import json + from koan.runners.codex import CodexRunner + runner = CodexRunner() + line = json.dumps({"type": "item.completed", "item": {"type": "function_call", "name": "koan_ask_question", "arguments": "{}"}}) + evts = runner.parse_stream_event(line) + assert evts == [] + + def test_gemini_normalizes_tool(self): + import json + from koan.runners.gemini import GeminiRunner + runner = GeminiRunner(subagent_dir="/tmp/test") + line = json.dumps({"type": "tool_use", "name": "read_file", "input": {}}) + evts = runner.parse_stream_event(line) + assert len(evts) == 1 + assert evts[0].tool_name == "read" + + def test_gemini_filters_koan_mcp_tool(self): + import json + from koan.runners.gemini import GeminiRunner + runner = GeminiRunner(subagent_dir="/tmp/test") + line = json.dumps({"type": "tool_use", "name": "koan_complete_step", "input": {}}) + evts = runner.parse_stream_event(line) + assert evts == [] + + +# -- agent_spawned ordering --------------------------------------------------- + +class TestAgentSpawnedOrdering: + """agent_spawned must only be emitted after build_command succeeds. + If build_command raises, the projection must not have a dangling primary_agent. + """ + def test_spawn_failed_without_prior_spawned_leaves_no_primary(self): + """agent_spawn_failed without prior agent_spawned: projection stays clean.""" + store = ProjectionStore() + store.push_event("agent_spawn_failed", { + "role": "intake", "error_code": "binary_not_found", "message": "not found" + }) + assert store.projection.primary_agent is None + assert len(store.projection.notifications) == 1 + + def test_spawn_failed_after_spawned_leaves_dangling_primary(self): + """Demonstrates the bug that is now fixed: agent_spawned must be emitted + AFTER build_command succeeds, not before. This test documents the broken + sequence to catch regressions -- if agent_spawned fires before the process + starts and then spawn_failed fires, primary_agent is left set.""" + store = ProjectionStore() + # This sequence should NOT happen in production code after the fix + store.push_event( + "agent_spawned", + {"agent_id": "a1", "role": "intake", "model": None, "is_primary": True, "started_at_ms": 0}, + agent_id="a1", + ) + store.push_event("agent_spawn_failed", {"role": "intake", "error_code": "err", "message": "m"}) + # primary_agent is dangling -- this is why agent_spawned must come AFTER build_command + assert store.projection.primary_agent is not None # known bad state + # In production, this can't happen: subagent.py now emits agent_spawned only + # after build_command succeeds (just before create_subprocess_exec). diff --git a/tests/test_runners.py b/tests/test_runners.py index ec9af5b..cea2a27 100644 --- a/tests/test_runners.py +++ b/tests/test_runners.py @@ -37,7 +37,7 @@ def test_tool_call(self): def test_thinking_block(self): line = json.dumps({"type": "assistant", "content": [{"type": "thinking", "text": "hmm"}]}) evts = self.runner.parse_stream_event(line) - assert evts == [StreamEvent(type="thinking", is_thinking=True)] + assert evts == [StreamEvent(type="thinking", is_thinking=True, content="hmm")] def test_result_success(self): line = json.dumps({"type": "result", "subtype": "success", "result": "done"}) @@ -74,7 +74,7 @@ def test_multi_block_thinking_and_text(self): }) evts = self.runner.parse_stream_event(line) assert len(evts) == 2 - assert evts[0] == StreamEvent(type="thinking", is_thinking=True) + assert evts[0] == StreamEvent(type="thinking", is_thinking=True, content="reasoning") assert evts[1] == StreamEvent(type="token_delta", content="answer") def test_multi_block_with_unknown_type_skipped(self): diff --git a/tests/test_subagent.py b/tests/test_subagent.py index 657de8d..85ee6a4 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -31,12 +31,12 @@ class FakeAppState: config: FakeConfig = field(default_factory=FakeConfig) balanced_profile: Any = None port: int = 9999 - sse_clients: list = field(default_factory=list) active_interaction: Any = None interaction_queue: Any = field(default_factory=lambda: __import__("collections").deque()) + interaction_queue_max: int = 8 frozen_logs: list = field(default_factory=list) - last_sse_values: dict = field(default_factory=dict) epic_dir: str | None = None + projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) class FakeRunner: @@ -248,8 +248,7 @@ async def test_bootstrap_failure_detection(self, tmp_path): "subagent_dir": subagent_dir, } - with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}), \ - patch("koan.subagent._push_sse"): + with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}): from koan.subagent import spawn_subagent exit_code = await spawn_subagent(task, app_state, runner=FakeRunner()) @@ -288,7 +287,6 @@ async def patched_subprocess(*args, **kwargs): return proc with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}), \ - patch("koan.subagent._push_sse"), \ patch("asyncio.create_subprocess_exec", side_effect=patched_subprocess): from koan.subagent import spawn_subagent @@ -330,21 +328,17 @@ async def test_model_field_propagated_to_agent_state(self, tmp_path): "subagent_dir": subagent_dir, } - captured_model = [] - - def capture_sse(app, event_type, payload): - if event_type == "subagent" and isinstance(payload, dict): - captured_model.append(payload.get("model")) - - with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}), \ - patch("koan.subagent._push_sse", side_effect=capture_sse): + with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}): from koan.subagent import spawn_subagent await spawn_subagent(task, app_state, runner=FakeRunner()) # When runner is provided directly, model is None (legacy path) - assert any(m is None for m in captured_model), \ - f"Expected None model for direct-runner path, got {captured_model}" + events = app_state.projection_store.events + agent_spawned = [e for e in events if e.event_type == "agent_spawned"] + assert len(agent_spawned) >= 1 + assert agent_spawned[0].payload.get("model") is None, \ + f"Expected None model for direct-runner path, got {agent_spawned[0].payload}" # -- fold purity (supplementary) ---------------------------------------------- @@ -571,27 +565,20 @@ async def test_sse_notification_includes_diagnostic_fields(self, tmp_path): "subagent_dir": subagent_dir, } - sse_payloads = [] - - def capture_sse(app, event_type, payload): - if event_type == "notification": - sse_payloads.append(payload) - - with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}), \ - patch("koan.subagent._push_sse", side_effect=capture_sse): + with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}): from koan.subagent import spawn_subagent await spawn_subagent(task, app_state, runner=FakeRunner()) - # Should have at least the bootstrap_failure notification - boot_notifs = [p for p in sse_payloads if p.get("type") == "bootstrap_failure"] - assert len(boot_notifs) == 1 + # Bootstrap failure is emitted as agent_exited with error="bootstrap_failure" + # and the fold populates projection.notifications. + notifs = app_state.projection_store.projection.notifications + boot_notifs = [n for n in notifs if n.get("error") == "bootstrap_failure"] + assert len(boot_notifs) >= 1 notif = boot_notifs[0] - assert notif["code"] == "bootstrap_failure" - assert notif["runner"] == "fake" - assert notif["stage"] == "handshake" - assert "message" in notif - assert "details" in notif + assert notif["type"] == "agent_exited_error" + assert "agent_id" in notif + assert "exit_code" in notif def test_fold_populates_diagnostic_field(self): """fold() sets diagnostic dict on runner_diagnostic events.""" @@ -651,25 +638,19 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): "subagent_dir": subagent_dir, } - sse_payloads = [] - - def capture_sse(app, event_type, payload): - if event_type == "notification": - sse_payloads.append(payload) - - with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}), \ - patch("koan.subagent._push_sse", side_effect=capture_sse): + with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}): from koan.subagent import spawn_subagent exit_code = await spawn_subagent(task, app_state) assert exit_code == 1 - # Verify SSE notification with diagnostic fields - runner_errors = [p for p in sse_payloads if p.get("code") == "binary_not_found"] - assert len(runner_errors) == 1 - assert runner_errors[0]["stage"] == "spawn" - assert "/nonexistent/path/claude" in runner_errors[0]["message"] + # Verify agent_spawn_failed event in projection notifications + notifs = app_state.projection_store.projection.notifications + spawn_fails = [n for n in notifs if n.get("type") == "agent_spawn_failed"] + assert len(spawn_fails) >= 1 + assert spawn_fails[0]["error_code"] == "binary_not_found" + assert "/nonexistent/path/claude" in spawn_fails[0]["message"] # Verify events.jsonl contains a runner_diagnostic events_path = Path(subagent_dir) / "events.jsonl" diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index dc3e6bb..c314e3e 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -327,25 +327,27 @@ def test_agents_detect_missing_param(client, app_state): # -- SSE replay --------------------------------------------------------------- def test_sse_replay(app_state): - """Test that SSE stream replays last_sse_values on connect.""" + """Test that SSE stream sends a snapshot on ?since=0 and replays on ?since=N.""" from koan.web.app import _sse_event - from koan.driver import push_sse - # Push a phase event through the new JSON-only push_sse - push_sse(app_state, "phase", "intake") + # Push a phase event via projection store + app_state.projection_store.push_event("phase_started", {"phase": "intake"}) - # Verify the replay cache now holds the JSON payload (no html/target) - assert "phase" in app_state.last_sse_values - payload = app_state.last_sse_values["phase"] - assert payload["phase"] == "intake" - assert "html" not in payload - assert "target" not in payload + # Verify projection holds the phase + assert app_state.projection_store.projection.phase == "intake" + assert app_state.projection_store.version == 1 # Verify the SSE event formatter produces correct output - event_str = _sse_event("phase", payload) - assert "event: phase" in event_str + event_str = _sse_event("phase_started", {"phase": "intake"}) + assert "event: phase_started" in event_str assert '"intake"' in event_str + # Verify events_since works for replay + events = app_state.projection_store.events_since(0) + assert len(events) == 1 + assert events[0].event_type == "phase_started" + assert events[0].payload["phase"] == "intake" + # -- Live page redirect (now SPA fallback) ------------------------------------ @@ -364,30 +366,30 @@ def test_live_page_when_running(client, app_state): # -- Workflow interaction SSE payload ----------------------------------------- def test_workflow_interaction_sse_payload_shape(app_state): - from koan.driver import push_sse - - push_sse(app_state, "interaction", { - "type": "workflow-decision", - "token": "tok", - "chat_turns": [{ - "role": "orchestrator", - "status_report": "Done", - "recommended_phases": [{ - "phase": "tech-plan", - "context": "next", - "recommended": True, - }], + from koan.events import build_workflow_decision_requested + + token = "tok" + chat_turns = [{ + "role": "orchestrator", + "status_report": "Done", + "recommended_phases": [{ + "phase": "tech-plan", + "context": "next", + "recommended": True, }], - }) + }] + app_state.projection_store.push_event( + "workflow_decision_requested", + build_workflow_decision_requested(token, chat_turns), + agent_id="agent-1", + ) - # After SPA migration, interaction payloads are pure JSON (no html/target). - payload = app_state.last_sse_values["interaction"] - assert payload["type"] == "workflow-decision" - assert payload["token"] == "tok" - assert "html" not in payload - assert "target" not in payload - # Verify the phase data is in the payload - turns = payload["chat_turns"] + # Verify projection holds the active interaction + active = app_state.projection_store.projection.active_interaction + assert active is not None + assert active["interaction_type"] == "workflow_decision_requested" + assert active["token"] == "tok" + turns = active["chat_turns"] assert turns[0]["recommended_phases"][0]["phase"] == "tech-plan" @@ -537,3 +539,63 @@ def test_agents_set_active(client, app_state): assert resp.status_code == 200 assert resp.json()["ok"] is True assert app_state.config.active_installations.get("claude") == "my-claude" + + +# -- SSE endpoint HTTP-level tests ------------------------------------------- + +@pytest.mark.anyio +def test_sse_snapshot_contains_projection_state(app_state): + """Snapshot SSE event contains the full projection as {version, state}.""" + from koan.web.app import _sse_event + + app_state.projection_store.push_event("phase_started", {"phase": "intake"}) + + snapshot = app_state.projection_store.get_snapshot() + assert snapshot["version"] == 1 + assert snapshot["state"]["phase"] == "intake" + assert snapshot["state"]["run_started"] is True + + # Verify SSE wire format + event_str = _sse_event("snapshot", snapshot) + assert "event: snapshot" in event_str + assert '"intake"' in event_str + + +def test_sse_replay_events_since_n(app_state): + """events_since(N) returns events with version > N for replay.""" + app_state.projection_store.push_event("phase_started", {"phase": "intake"}) + app_state.projection_store.push_event("phase_started", {"phase": "brief-generation"}) + # version is now 2 + + # Client at version 1 should get only version 2 + events = app_state.projection_store.events_since(1) + assert len(events) == 1 + assert events[0].version == 2 + assert events[0].event_type == "phase_started" + assert events[0].payload["phase"] == "brief-generation" + + # Client at version 0 gets both + all_events = app_state.projection_store.events_since(0) + assert len(all_events) == 2 + + # Client at version 2 gets nothing (live-tail only) + none = app_state.projection_store.events_since(2) + assert len(none) == 0 + + +def test_sse_fatal_error_stale_version(app_state): + """?since=N where N > server version triggers fatal_error condition.""" + # server version is 0, client claims version 99 + store = app_state.projection_store + assert store.version == 0 + + # The sse_stream handler checks: if since > 0 and since > store.version + # When true, it yields a fatal_error event and returns. + from koan.web.app import _sse_event + fatal_event = _sse_event("fatal_error", {"reason": "version_not_available"}) + assert "event: fatal_error" in fatal_event + assert "version_not_available" in fatal_event + + # Verify the condition: since=99 > version=0 and since > 0 + assert 99 > store.version + assert 99 > 0 From 2da19389487417061ea67183d0c663ba14e0599a Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 12:52:22 +0700 Subject: [PATCH 200/412] update documentation for event-sourced projection system --- AGENTS.md | 3 +- docs/AGENTS.md | 100 ++++++++ docs/architecture.md | 152 ++++++----- docs/artifact-review.md | 24 +- docs/frontend.md | 167 +++++++----- docs/intake-loop.md | 7 +- docs/ipc.md | 7 +- docs/projections.md | 549 ++++++++++++++++++++++++++++++++++++++++ docs/subagents.md | 4 +- docs/token-streaming.md | 93 ++++--- 10 files changed, 930 insertions(+), 176 deletions(-) create mode 100644 docs/AGENTS.md create mode 100644 docs/projections.md diff --git a/AGENTS.md b/AGENTS.md index fc91d0d..612a5ff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,11 +8,12 @@ Spoke documents: - [docs/ipc.md](docs/ipc.md) -- HTTP MCP tool calls, blocking interactions, scout spawning - [docs/state.md](docs/state.md) -- driver/LLM boundary, epic and story state, routing rules - [docs/intake-loop.md](docs/intake-loop.md) -- confidence-gated loop, non-linear step progression, prompt engineering +- [docs/projections.md](docs/projections.md) -- versioned event log, fold function, projection shape, SSE protocol, version-negotiated catch-up - [docs/epic-brief.md](docs/epic-brief.md) -- brief artifact, brief-writer subagent, downstream references - [docs/artifact-review.md](docs/artifact-review.md) -- artifact review protocol, review loop, reusability - [docs/token-streaming.md](docs/token-streaming.md) -- runner stdout parsing, SSE delta path -**Pipeline phases:** `intake` -> `brief-generation` -> `core-flows` -> `tech-plan` -> `ticket-breakdown` -> `cross-artifact-validation` -> `execution` -> `implementation-validation` -> `completed` +**Workflow phases:** `intake` -> `brief-generation` -> `core-flows` -> `tech-plan` -> `ticket-breakdown` -> `cross-artifact-validation` -> `execution` -> `implementation-validation` -> `completed` --- diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 0000000..bc5dd23 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,100 @@ +# docs/ Conventions + +Conventions for agents writing or editing files in this directory. + +--- + +## No temporal contamination + +Documentation describes the current state of the system as if it has always +been this way. It is not a changelog. + +**Forbidden patterns:** + +| Pattern | Example violation | Fix | +|---|---|---| +| "replaces X" (historical) | "This replaces the old polling design" | Describe what the system does | +| "previously" | "Previously, events were cached in a dict" | Delete — describe current state only | +| "the old X" | "the old model's problem was..." | Describe the design principle instead | +| "used to" | "scouts used to be top-level phases" | Delete or restructure | +| "was changed from" | "the event was renamed from pipeline-end" | Delete | +| "we switched to" | "we switched to asyncio.Future" | Delete | +| "ported from" | "ported verbatim from the old CSS" | Delete | +| "formerly" | "formerly called pipeline-end" | Delete | + +**Permitted uses of "replaces":** + +"Replaces" describing a logical operation on data is fine — it is not temporal: + +- ✓ `applySnapshot` atomically replaces store state +- ✓ `artifacts_changed` sets the `artifacts` list wholesale +- ✗ "The projection system replaces the ad-hoc dict" (historical) + +**Plans are exempt.** Files under `plans/` are inherently temporal — they +document what to change and why. The rule applies only to `docs/`, code +comments, and docstrings. + +**Design decisions mentioning rejected alternatives are fine.** A comment +explaining "X was considered but Y is used because Z" documents a design +choice. The framing must be about the decision rationale, not a migration +narrative: + +- ✓ "`python-eventsourcing` was considered but is designed for database persistence, not in-memory UI state" +- ✗ "We tried `python-eventsourcing` but switched to a custom implementation" + +--- + +## Spoke document structure + +Spoke documents cover a subsystem in depth. Every spoke document follows this +structure: + +```markdown +# Title + +One sentence: what this document covers. + +> Parent doc: [architecture.md](./architecture.md) + +--- + +## Overview + +One paragraph: the problem this subsystem solves and the high-level approach. + +**Key invariant (if any):** Bold sentence capturing the non-negotiable rule. + +--- + +## [Concept sections] + +Technical detail organized by concept, not by implementation order. + +--- + +## Design Decisions + +Named subsections, one per decision. Each captures: +- The choice made +- Why (first-principles rationale, not migration history) +- Alternatives considered and why they were not chosen +``` + +**Formatting conventions:** + +- Section separators: `---` on its own line +- Parent doc reference: `> Parent doc: [name](./path.md)` immediately after + the opening description, before the first `---` +- Tables: GFM pipe tables with `|---|---|` separator row +- Code blocks: fenced with language tag (` ```python `, ` ```typescript `, etc.) +- Cross-references: `[section-name](./file.md#anchor)` using lowercase-hyphenated anchors +- Bold for key terms on first use: `**design invariant**`, `**materialized projection**` + +--- + +## Full documentation conventions + +For invisible knowledge, README vs CLAUDE.md, in-code documentation tiers, +and module documentation standards, see: + +[resources/conventions/documentation.md](../resources/conventions/documentation.md) diff --git a/docs/architecture.md b/docs/architecture.md index c06a429..2674478 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,6 +1,6 @@ # Koan Architecture -Koan is a deterministic pipeline that spawns isolated LLM subagents to plan and +Koan is a deterministic workflow that spawns isolated LLM subagents to plan and execute complex coding tasks. This document captures the design invariants, principles, and pitfalls that govern the codebase. @@ -13,6 +13,8 @@ principles, and pitfalls that govern the codebase. - [Token Streaming](./token-streaming.md) -- runner stdout parsing, SSE delta path - [State & Driver](./state.md) -- the driver/LLM boundary, JSON vs markdown ownership, epic and story state, routing rules +- [Projections](./projections.md) -- versioned event log, fold function, + projection shape, SSE protocol, version-negotiated catch-up - [Intake Loop](./intake-loop.md) -- confidence-gated investigation loop, non-linear step progression, prompt engineering principles - [Epic Brief](./epic-brief.md) -- brief artifact, brief-writer subagent, downstream references @@ -107,12 +109,11 @@ Each subagent receives only the minimum context for its task: - The **system prompt** establishes role identity and rules, but no task details - **Task details** arrive via step 1 guidance (returned by the first tool call) -This is not just tidiness -- it is load-bearing. A previous design injected -step 1 guidance into the first user message, but that front-loaded complex -instructions before the LLM had established the `koan_complete_step` calling -pattern. Weaker models produced text output and exited without entering the -workflow. Step guidance is now delivered exclusively through `koan_complete_step` -return values. +This is not just tidiness -- it is load-bearing. Injecting step 1 guidance +into the first user message front-loads complex instructions before the LLM has +established the `koan_complete_step` calling pattern. Weaker models produce +text output and exit without entering the workflow. Step guidance is delivered +exclusively through `koan_complete_step` return values. ### 6. Directory-as-contract @@ -168,95 +169,106 @@ When a tool call arrives via HTTP, the MCP endpoint: 4. If allowed, dispatches to the tool handler 5. Returns the result as the MCP tool response -This replaces the previous TypeScript pattern of registering tools at extension -init and checking permissions via event hooks. The Python model is simpler: -tools are HTTP handlers, permissions are checked per-call. +Tools are HTTP handlers; permissions are checked per-call. --- -## Event-Sourced Audit +## Two Fold Systems -Each subagent's audit state is maintained in-process by the driver. The event -log (`events.jsonl`) is append-only, and the projection (`state.json`) is -eagerly materialized after each event. +Koan uses two independent fold systems that share the same structural pattern +(pure fold function, append-only log) but serve different purposes: -``` -tool call arrives via MCP -> driver handles it -> emits audit event - -> fold(events) -> state.json written atomically - -> SSE event pushed directly to connected browsers -``` +### Audit fold (`koan/audit/fold.py`) -### Rules +Tracks the internal execution of each individual subagent. Input: per-subagent +audit events written to `events.jsonl`. Output: per-subagent `Projection` +materialized to `state.json`. One fold instance per running subagent. +Consumed by debugging and post-mortem analysis. -- **`fold()` is pure** -- given the same event sequence, it must produce the same - projection. No I/O, no randomness, no side effects inside `fold()`. -- **New event types require a fold handler.** Unknown events are silently ignored - (forward compatibility), but a new event that is not folded contributes nothing - to the projection and will not be visible in the UI. -- **Projection is eagerly materialized.** It is written atomically after every - event. The web server reads the projection from in-process state; `state.json` - on disk is for debugging and post-mortem. -- **SSE is pushed directly.** There is no polling loop. When a tool handler - emits an audit event, the SSE push happens in the same call chain. +### Projection fold (`koan/projections.py`) -### Adding new observable state +Tracks the complete frontend-visible state of the entire workflow run. Input: +workflow-level projection events emitted by `ProjectionStore.push_event()`. +Output: a single in-memory `Projection` covering all agents, run state, and +UI interactions. Consumed by the browser frontend via SSE. -When adding a new piece of state that the UI should see, wire three layers: +When adding new observable state, decide which system it belongs to: +- State visible only in logs/debugging → audit fold +- State visible in the browser UI → projection fold -1. **Emit an audit event** -- add a typed event in `koan/audit/events.py` -2. **Update `fold()`** -- handle the new event type in `koan/audit/fold.py` -3. **Push SSE** -- emit the SSE event from the tool handler or state transition - in `koan/web/app.py` +See [projections.md](./projections.md) for the full event model, fold +specification, and SSE protocol. -The HTMX frontend receives SSE events and swaps server-rendered HTML fragments. +### Rules for both folds -**Exception -- ephemeral display data:** High-frequency data with no persistence -value (e.g., token deltas) should bypass the audit pipeline and push directly -to SSE. See [token-streaming.md](./token-streaming.md) for the alternate path. +- **`fold()` is pure** -- given the same event sequence, it must produce the same + projection. No I/O, no randomness, no side effects inside `fold()`. +- **New event types require a fold handler.** Unknown events are silently ignored + (forward compatibility), but a new event that is not folded contributes nothing + to the projection. +- **Projection is eagerly materialized.** Updated after every `push_event()`. +- **Events are facts, not snapshots.** Events record what happened; the fold + derives current state from those facts. Do not store derived state as an event. --- ## SSE Event Lifecycle -State flows from LLM tool calls to the browser through a direct push pipeline. +State flows from LLM tool calls to the browser through the projection system. ``` [LLM calls tool via HTTP MCP] | [MCP endpoint handles call, emits audit event] | -[fold() updates projection, state.json written atomically] +[fold() updates audit projection, state.json written atomically] + | +[push_event() called with workflow-level event] | -[SSE event pushed to connected browsers] <- koan/web/app.py +[ProjectionStore: append to log, fold projection, broadcast to SSE subscribers] | -[HTMX receives SSE, swaps server-rendered fragment] +[Browser receives versioned SSE event, applies frontend fold] ``` -### Concrete example: `koan_set_confidence` +### Concrete example: `koan_complete_step` ``` -LLM calls koan_set_confidence({ level: "high" }) via MCP +LLM calls koan_complete_step({ thoughts: "..." }) via MCP -> MCP endpoint checks permissions - -> emits confidence_change audit event - -> fold: projection.intake_confidence = "high", projection.intake_iteration = 2 - -> write_state(projection) -> state.json - -> push SSE "intake-progress" event to connected browsers - -> HTMX swaps confidence visualization fragment - -> returns "Confidence set to high." as MCP tool result + -> emits step_advance audit event (audit fold) + -> audit fold: projection.step = 2, projection.step_name = "Decompose" + -> write_state(audit projection) -> state.json + -> push_event("agent_step_advanced", {step: 2, step_name: "Decompose"}, agent_id="abc") + -> ProjectionStore appends event v=47, folds projection, broadcasts to SSE subscribers + -> browser receives: event: agent_step_advanced / data: {"version": 47, "agent_id": "abc", ...} + -> frontend fold: primaryAgent.step = 2, primaryAgent.stepName = "Decompose" + -> returns step 2 instructions as MCP tool result ``` -### Replay on reconnect +### Version-negotiated catch-up -The web server buffers the last value of every stateful SSE event type. On -reconnect, all buffered events are written to the new client. This ensures -the browser always has current state after a network drop, without requiring -a full page reload. +The `/events` endpoint accepts `?since=N`. On first connect (`since=0`), the +server sends a `snapshot` SSE event containing the full materialized projection +at the current version. On reconnect (`since=N`), the server replays events +with version > N, then streams live events. + +``` +event: snapshot +data: {"version": 42, "state": { ...full projection... }} + +event: agent_spawned +data: {"version": 43, "agent_id": "...", "role": "intake", ...} +``` + +This ensures the browser always has complete state after a page reload or +network drop, without requiring a full page reload or losing accumulated state +(activity log, notifications, streaming buffer). --- ## Pitfalls -Lessons learned from previous failures. Check new changes against these. +Known invariant violations and their consequences. Check new changes against these. ### Don't put task content in spawn prompts @@ -267,10 +279,10 @@ happened with haiku-class models and is not recoverable. ### Don't add `escalated` as a story status -Escalation is handled via `koan_ask_question` (MCP tool call -> web UI -> user -answers -> MCP response). A separate `escalated` status was tried and created -a dead routing path -- the driver had nowhere clean to send it without -duplicating the ask UI flow. +Escalation flows through `koan_ask_question` (MCP tool call -> web UI -> user +answers -> MCP response). A separate `escalated` status creates a dead routing +path -- the driver has nowhere clean to send it without duplicating the ask UI +flow. ### Don't add `scouting` as an epic phase @@ -377,6 +389,17 @@ If information is needed by a subagent, write it to `task.json` in the subagent directory before spawning. CLI flags are for bootstrap only. The directory-as-contract invariant exists specifically to prevent this. +### Don't store derived state as an event + +Events record facts — things that happened. Derived state belongs in the fold +function, not in the event log. + +**Bad:** Emitting a `subagent_idle` event to signal "no agent is running." +"No agent" is derived from `agent_exited`, not a fact in itself. Storing it as +an event conflates the log with the projection. + +**Good:** Emitting `agent_exited`. The fold derives `primary_agent = None`. + ### Don't put high-frequency ephemeral data through the audit pipeline Token deltas and similar high-frequency signals arrive at hundreds of events @@ -384,3 +407,8 @@ per second. Routing them through the audit pipeline would mean hundreds of append + fold + atomic-write cycles per second for data that has no persistence value. The runner stdout parsing path exists for exactly this case. See [token-streaming.md](./token-streaming.md). + +Note: `stream_delta` events (the projection system's name for token deltas) DO +go through the projection fold, but the fold only appends to an in-memory +string — no disk I/O. The distinction is between the audit pipeline (disk +writes per event) and the projection fold (in-memory only). diff --git a/docs/artifact-review.md b/docs/artifact-review.md index 0a3da10..1562018 100644 --- a/docs/artifact-review.md +++ b/docs/artifact-review.md @@ -2,7 +2,7 @@ Protocol for presenting a written artifact to the user and collecting feedback. Used by the brief-writer phase; reusable for any future markdown artifact that -requires a review-revise loop before pipeline advancement. +requires a review-revise loop before workflow advancement. > Parent doc: [architecture.md](./architecture.md) > @@ -27,7 +27,7 @@ When `koan_review_artifact` is called via MCP, the tool handler: 1. Reads the file at `path` to obtain raw markdown content 2. Creates a `PendingInteraction` with type `"artifact-review"` and an `asyncio.Future` 3. Stores it in `AgentState.pending_tool` -4. Pushes SSE `"artifact-review"` event to connected browsers +4. Pushes SSE `artifact_review_requested` event to connected browsers 5. Awaits the Future -- the MCP HTTP connection stays open 6. When the user responds (Accept or feedback), the web endpoint resolves the Future 7. Returns feedback string to the LLM as the MCP tool result @@ -79,9 +79,9 @@ decide how to proceed. ## Web UI Component -The artifact review is rendered as a server-side HTML fragment via -`koan/web/templates/fragments/interaction_artifact_review.html`. The template -receives the raw markdown content and renders it server-side. +The artifact review is rendered by the `ArtifactReview.tsx` React component. +The component subscribes to `active_interaction` in the Zustand store and +renders when an `artifact_review_requested` event sets it. **Layout:** @@ -101,10 +101,10 @@ receives the raw markdown content and renders it server-side. **Behavior:** -- Server renders markdown content in the HTML fragment +- Component renders markdown content client-side - "Accept" -> `POST /api/artifact-review` with `{ feedback: "Accept" }` - "Send Feedback" -> `POST /api/artifact-review` with `{ feedback: text }` -- HTMX swaps the fragment on SSE events (new review, review cleared) +- Component unmounts when `artifact_reviewed` event clears `active_interaction` --- @@ -120,10 +120,10 @@ validation failure or missing pending interaction. ## SSE Events -| Event | Direction | Payload | -| --------------------------- | ----------------- | ----------------------------------------------------- | -| `artifact-review` | server -> browser | `{ request_id, artifact_path, content, description }` | -| `artifact-review-cancelled` | server -> browser | `{ request_id }` | +| Event | Direction | Payload | +| ---------------------------- | ----------------- | -------------------------------------------------------- | +| `artifact_review_requested` | server -> browser | `{ token, path, content, description }` (sets `active_interaction`) | +| `artifact_reviewed` | server -> browser | `{ token, ?accepted, ?response, cancelled }` (clears `active_interaction`) | SSE events are pushed directly from the tool handler. On browser reconnect, pending reviews are replayed so the user does not lose the review form. @@ -136,7 +136,7 @@ pending reviews are replayed so the user does not lose the review form. subagent calls koan_review_artifact({ path: ".../brief.md" }) via MCP -> MCP endpoint reads brief.md content -> creates PendingInteraction { type: "artifact-review", future: Future() } - -> pushes SSE "artifact-review" event to browsers + -> pushes SSE `artifact_review_requested` event to browsers -> awaits Future user sees rendered markdown in web UI diff --git a/docs/frontend.md b/docs/frontend.md index d290de6..cf5250c 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -22,15 +22,15 @@ frontend/ # source tree (alongside koan/ Python package) │ │ ├── index.ts # single Zustand store (the app-db equivalent) │ │ └── selectors.ts # derived state computed from store slices │ ├── sse/ -│ │ └── connect.ts # EventSource wrapper: event dispatch + store writes +│ │ └── connect.ts # EventSource wrapper: version-negotiated catch-up + fold │ ├── api/ │ │ └── client.ts # typed fetch wrappers for POST/PUT endpoints │ ├── components/ # one file per UI component (see Component Mapping) │ ├── hooks/ -│ │ ├── useElapsed.ts # replaces manual setInterval + DOM attribute scanning +│ │ ├── useElapsed.ts # elapsed time hook for agent start times │ │ └── useAutoScroll.ts │ └── styles/ -│ ├── variables.css # CSS custom properties (ported verbatim) +│ ├── variables.css # CSS custom properties │ ├── layout.css │ └── components.css # components.css + animations.css merged └── dist/ # Vite build output (gitignored) @@ -60,7 +60,7 @@ python (:8000) → /static/app/* → frontend/dist/ (Vite build) → /* (catch-all) → index.html (SPA fallback) ``` -Build command: `cd frontend && npm run build` +Build command: `cd frontend && npm run build` Output: `koan/web/static/app/` (matches `base: '/static/app/'` in `vite.config.ts`) **Starlette route order** in `create_app()` is significant — first match wins: @@ -78,67 +78,118 @@ Output: `koan/web/static/app/` (matches `base: '/static/app/'` in `vite.config.t ## State Model -Single Zustand store mirrors backend `AppState`. All live state enters through -the SSE bridge — nothing else writes to the store from outside the component -tree. +Single Zustand store mirrors the backend projection. All live state enters +through the SSE bridge — nothing else writes to the store from outside the +component tree. Key slices: -| Slice | Type | Source SSE event | +| Slice | Type | Source | |---|---|---| | `connected` | `boolean` | EventSource open/error | -| `runStarted` | `boolean` | derived from first `phase` event | -| `phase` / `donePhases` | `string` / `string[]` | `phase` | -| `primaryAgent` | `AgentInfo \| null` | `subagent`, `subagent-idle` | -| `scouts` | `Record` | `agents` (full replace) | -| `activityLog` | `ActivityEntry[]` | `logs` (append-only) | -| `streamBuffer` | `string` | `token-delta` / `token-clear` | -| `activeInteraction` | `Interaction \| null` | `interaction` | -| `artifacts` | `ArtifactFile[]` | `artifacts` | -| `completion` | `CompletionInfo \| null` | `pipeline-end` | -| `notifications` | `NotificationEntry[]` | `notification` | +| `lastVersion` | `number` | Snapshot or event version field | +| `runStarted` | `boolean` | Derived from first `phase_started` event | +| `phase` / `donePhases` | `string` / `string[]` | `phase_started` | +| `primaryAgent` | `AgentInfo \| null` | `agent_spawned`, `agent_step_advanced`, `agent_exited` | +| `scouts` | `Record` | `agent_spawned`, `agent_exited` | +| `activityLog` | `ActivityEntry[]` | `tool_called`, `tool_completed`, `thinking` | +| `streamBuffer` | `string` | `stream_delta`, `stream_cleared` | +| `activeInteraction` | `Interaction \| null` | `questions_asked`, `artifact_review_requested`, `workflow_decision_requested`, and resolution events. Stores `interactionType` (the event type string) alongside payload for component discrimination. | +| `artifacts` | `Record` | `artifact_created`, `artifact_modified`, `artifact_removed` | +| `completion` | `CompletionInfo \| null` | `workflow_completed` | +| `notifications` | `NotificationEntry[]` | derived by fold from `agent_spawn_failed`, `agent_exited` with error | `runStarted` gates top-level view (landing vs live). No router library — a conditional render covers the binary choice. +`lastVersion` tracks the version of the last applied event or snapshot. The +SSE connection uses `?since=${lastVersion}` on connect/reconnect so the server +knows whether to send a snapshot or replay missed events. + +### Store actions for the projection + +```typescript +applySnapshot(data: SnapshotPayload): void +// Atomically replaces the entire store state from a snapshot. +// Called when the server sends event: snapshot. +// Uses useStore.setState(transform(data)) — one update, no merge logic. +// Any visual flash from the re-render is acceptable. + +applyEvent(event: VersionedEvent): void +// Applies a single versioned event via the frontend fold. +// Called for every non-snapshot SSE event. +// Mirrors the backend fold cases exactly. +``` + --- ## SSE Bridge -`connectSSE(store)` in `sse/connect.ts` opens an `EventSource('/events')` and -wires every event type to a store action. Returns the `EventSource`; `App.tsx` -owns the reconnect lifecycle (exponential backoff, capped at 5 s). +`connectSSE(store)` in `sse/connect.ts` opens an +`EventSource('/events?since=${store.lastVersion}')` and handles two event +paths: + +1. **`snapshot` event** → `store.applySnapshot(data)` — atomic state replace +2. **All other events** → `store.applyEvent(event)` — incremental fold + +Returns the `EventSource`; `App.tsx` owns the reconnect lifecycle (exponential +backoff, capped at 5 s). + +The bridge also handles `fatal_error` events (sent when `?since=N` references a +version the server no longer has, e.g. after server restart). On `fatal_error`, +the bridge closes the `EventSource` WITHOUT scheduling a reconnect and sets a +`fatalError` flag in the store. The UI renders a "reload required" banner. + +### The frontend fold + +The frontend fold mirrors the backend fold in `koan/projections.py`. Both must +produce the same projection shape from the same event sequence. When a new +event type is added to the backend, a corresponding fold case must be added to +the frontend `applyEvent`. -**snake_case → camelCase mapping** happens at the bridge boundary for all agent -payloads (`agent_id` → `agentId`, `started_at_ms` → `startedAt`, etc.). +Fold cases match the backend exactly. See +[projections.md -- Fold cases](./projections.md#fold-cases) for the full table. -**`phase` event side effect:** `setPhase()` also sets `runStarted = true` and -derives `donePhases`. This ensures a mid-run page reload (which replays the -buffered `phase` event) restores the live view without a full reload. +### Reconnect flow -Stateful events (`phase`, `subagent`, `agents`, `artifacts`, `intake-progress`, -`pipeline-end`) are cached server-side and replayed to reconnecting clients. +``` +Browser loads → connect ?since=0 → snapshot → applySnapshot → full state +Browser refreshes → connect ?since=0 → snapshot → applySnapshot → full state +Connection drops → reconnect ?since=N → events N+1..M → applyEvent each → up to date +``` + +**snake_case → camelCase mapping** happens in `applySnapshot` and `applyEvent` +for all agent payloads (`agent_id` → `agentId`, `started_at_ms` → `startedAt`, +etc.). The backend sends snake_case; the frontend transforms at the bridge +boundary. + +**`phase_started` fold effect:** sets `runStarted = true` and derives +`donePhases`. This ensures a mid-run page reload (which receives a snapshot +with `run_started: true` and a current `phase`) restores the live view +correctly. --- ## Backend Contract -`push_sse()` emits raw JSON — no `html` or `target` fields. `_render_fragment()` -and all Jinja2 templates are deleted. Three builder functions produce the -JSON payloads: - -| Function | Event | Notes | -|---|---|---| -| `_build_subagent_json(app_state)` | `subagent` | Returns `{"agent_id": None}` when idle | -| `_build_agents_json(app_state)` | `agents` | Scout list; full replace on each event | -| `_build_artifacts_json(app_state)` | `artifacts` | Flat list; client groups into tree | +`ProjectionStore.push_event()` emits versioned events with fully-formed +payloads. Callers build complete payloads using helper functions; `push_event` +does not enrich payloads. See [projections.md](./projections.md) for the full +event type table and payload shapes. All time values are UTC epoch milliseconds (`started_at_ms`). All token counts are raw integers. Formatting is done client-side (`useElapsed`, `formatTokens`). -`app_state.phase` assignment — previously a side effect inside -`_render_fragment()` — is preserved in `push_sse()` for the `phase` event -branch. +### Event builder helpers (Python) + +| Helper | Produces event(s) | Notes | +|---|---|---| +| `build_agent_spawned(agent)` | `agent_spawned` | Extracts from `AgentState` | +| `build_agent_exited(agent_id, exit_code, error)` | `agent_exited` | | +| `build_agent_spawn_failed(role, diagnostic)` | `agent_spawn_failed` | | +| `build_artifact_diff(old, new)` | `artifact_created` / `artifact_modified` / `artifact_removed` | Diffs two artifact dicts | +| `build_tool_called(call_id, tool, args, summary)` | `tool_called` | | +| `build_tool_completed(call_id, tool, result)` | `tool_completed` | | Settings endpoints (`/api/settings/body`, `/api/settings/profile-form`, `/api/settings/installation-form`) return JSON. `SettingsOverlay.tsx` owns @@ -148,19 +199,19 @@ form state and cascade dropdown logic. ## Component Mapping -| Jinja2 template | React component | Primary store subscription | -|---|---|---| -| `live.html` | `App.tsx` | `runStarted` | -| `landing.html` | `LandingPage.tsx` | `runStarted` (negated) | -| `status_sidebar.html` | `StatusSidebar.tsx` | `primaryAgent`, `phase`, `intakeProgress` | -| `monitor.html` | `AgentMonitor.tsx` | `scouts` | -| `artifacts_sidebar.html` | `ArtifactsSidebar.tsx` | `artifacts` | -| `interaction_ask.html` | `AskWizard.tsx` | `activeInteraction` | -| `interaction_workflow.html` | `WorkflowDecision.tsx` | `activeInteraction` | -| `interaction_artifact_review.html` | `ArtifactReview.tsx` | `activeInteraction` | -| `completion.html` | `Completion.tsx` | `completion` | -| `settings_body.html` | `SettingsOverlay.tsx` | `settingsOpen` + local state | -| Toast JS in `koan.js` | `Notification.tsx` | `notifications` | +| React component | Primary store subscription | +|---|---| +| `App.tsx` | `runStarted` | +| `LandingPage.tsx` | `runStarted` (negated) | +| `StatusSidebar.tsx` | `primaryAgent`, `phase` | +| `AgentMonitor.tsx` | `scouts` | +| `ArtifactsSidebar.tsx` | `artifacts` | +| `AskWizard.tsx` | `activeInteraction` | +| `WorkflowDecision.tsx` | `activeInteraction` | +| `ArtifactReview.tsx` | `activeInteraction` | +| `Completion.tsx` | `completion` | +| `SettingsOverlay.tsx` | `settingsOpen` + local state | +| `Notification.tsx` | `notifications` | --- @@ -171,16 +222,6 @@ Not implemented in v1: execution phase shows only primary agent status and activity feed. Add a `stories` store slice and `StoryProgress` component when designing the execution phase UI. -**`frozen-logs` events** — snapshot of activity log before orchestrator spawn. -Ignored in v1; the activity feed is append-only. Add a log boundary marker in -a follow-up if needed. - -**`intake-progress` events** — the SSE bridge and `StatusSidebar` are wired to -display intake sub-phase, confidence, and summary. However, no Python code -currently emits `push_sse(app_state, "intake-progress", ...)`. The `push_sse()` -handler and `STATEFUL_EVENTS` entry exist but are unreachable. When adding the -emission call, use camelCase field names (`subPhase`, not `sub_phase`) since the -bridge passes through without renaming. --- diff --git a/docs/intake-loop.md b/docs/intake-loop.md index e049fb4..7a375c2 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -183,9 +183,10 @@ Both events are folded into the `state.json` projection: - `confidence_change` -> `intake_confidence`, `intake_iteration` - `iteration_start` -> `intake_iteration` -SSE events are pushed directly from the tool handlers and step engine -- no -polling loop. When the driver handles a `koan_set_confidence` call or detects -a loop-back, it pushes an `intake-progress` SSE event to connected browsers. +Audit events are pushed directly from the tool handlers and step engine -- no +polling loop. Browser-visible intake state (current phase, confidence level) is +derived from `agent_step_advanced` and `phase_started` projection events, which +the frontend renders from the Zustand store. --- diff --git a/docs/ipc.md b/docs/ipc.md index 9caa548..122fc38 100644 --- a/docs/ipc.md +++ b/docs/ipc.md @@ -76,8 +76,7 @@ The `PendingInteraction` object stored in `AgentState.pending_tool`: - **One pending interaction at a time** per agent. A second blocking tool call while one is pending returns an error. -- **No polling** -- the Future model replaces the previous file-polling design. - Resolution is immediate when the external actor responds. +- **No polling** -- resolution is immediate when the external actor responds. - **The subagent's LLM turn is blocked** while the Future is pending. The MCP HTTP connection is held open; the LLM cannot call other tools until the response arrives. @@ -91,7 +90,7 @@ subagent calls koan_ask_question({ questions: [...] }) -> MCP endpoint checks permissions -> creates PendingInteraction { type: "ask", future: asyncio.Future() } -> stores in AgentState.pending_tool - -> pushes SSE "ask" event to browsers + -> pushes SSE `questions_asked` event to browsers -> awaits Future user sees question form in web UI @@ -166,7 +165,7 @@ subagent calls koan_review_artifact({ path: ".../brief.md" }) -> MCP endpoint checks permissions -> reads file content from path -> creates PendingInteraction { type: "artifact-review", future: asyncio.Future() } - -> pushes SSE "artifact-review" event to browsers (with rendered content) + -> pushes SSE `artifact_review_requested` event to browsers (with rendered content) -> awaits Future user sees rendered markdown in web UI diff --git a/docs/projections.md b/docs/projections.md new file mode 100644 index 0000000..99fc142 --- /dev/null +++ b/docs/projections.md @@ -0,0 +1,549 @@ +# Projections + +How koan maintains frontend-visible state as a versioned event log with a +materialized projection, enabling full state recovery on page reload or +reconnect. + +> Parent doc: [architecture.md](./architecture.md) + +--- + +## Overview + +The projection system maintains: + +1. An **append-only versioned event log** — every fact that occurs during a + workflow run, in order, with a monotonically increasing version number. +2. A **materialized projection** — the complete frontend-visible state derived + by folding the event log with a pure function. +3. A **subscriber mechanism** — one `asyncio.Queue` per connected SSE client, + fed from `push_event()`. + +The `/events` SSE endpoint serves either a full snapshot (for new clients) or +a replay of missed events (for reconnecting clients), then streams live events. + +**Design invariant:** Events are facts about things that happened — not state +snapshots. The fold function derives state from facts. Derived state is never +stored as an event. + +--- + +## The Event Log + +All events share a common envelope. `agent_id` is set when the event originates +from a specific agent; `None` otherwise. + +```python +EventType = Literal[ + # Lifecycle + "phase_started", "agent_spawned", "agent_spawn_failed", + "agent_step_advanced", "agent_exited", "workflow_completed", + # Activity + "tool_called", "tool_completed", "thinking", "stream_delta", "stream_cleared", + # Interactions + "questions_asked", "questions_answered", + "artifact_review_requested", "artifact_reviewed", + "workflow_decision_requested", "workflow_decided", + # Resources + "artifact_created", "artifact_modified", "artifact_removed", +] + +class VersionedEvent(BaseModel): + version: int # 1-based, monotonic + event_type: str # EventType string; stored as str so unknown types deserialise safely + timestamp: str # ISO8601 UTC + agent_id: str | None = None # originating agent, when known + payload: dict # typed per event_type (see below) +``` + +The log is append-only. Events are never modified or removed. The entire log +is held in memory for the duration of a workflow run. koan is one-shot (one +server instance per run), so there is no cross-run accumulation concern. + +--- + +## Event Types + +### Lifecycle events + +| Event | What happened | Payload fields | `agent_id` | +|---|---|---|---| +| `phase_started` | Driver began a workflow phase | `phase` | `None` | +| `agent_spawned` | A subagent process was launched | `role, model, is_primary` | set | +| `agent_spawn_failed` | Spawn attempted but failed (runner error) | `role, error_code, message, ?details` | `None` | +| `agent_step_advanced` | Subagent called `koan_complete_step` | `step, step_name, ?usage` | set | +| `agent_exited` | Subagent process terminated | `exit_code, ?error, ?usage` | set | +| `workflow_completed` | Entire workflow finished | `success, summary, ?error` | `None` | + +`agent_spawned` does not carry `step` — step 0 is implied. The first +`agent_step_advanced` is for step 1. `agent_exited` does not carry `is_primary` +— the fold looks up the agent in projection state. `workflow_completed` does +not carry the artifact list — consumers read `projection.artifacts`. + +### Activity events + +| Event | What happened | Payload fields | `agent_id` | +|---|---|---|---| +| `tool_called` | A tool was invoked | `call_id, tool, args, summary` | set | +| `tool_completed` | A tool call finished | `call_id, tool, ?result, ?summary` | set | +| `thinking` | LLM produced thinking tokens | `delta` | set | +| `stream_delta` | LLM produced output tokens | `delta` | set | +| `stream_cleared` | End-of-stream tombstone | (none) | set | + +`tool_called` and `tool_completed` are paired by `call_id` (UUID). `tool` is a +canonical normalized name (`read`, `bash`, `edit`, `grep`, +`koan_complete_step`, etc.). `args` and `result` are unstructured (`dict | str`) +because tool schemas vary across runners. + +MCP tool calls are authoritative — both `tool_called` and `tool_completed` are +emitted from the MCP endpoint. Stdout-parsed events are filtered to exclude +koan MCP tool names (which would otherwise duplicate). Agent-native tools (file +read, bash, etc.) are sourced from stdout with a synthetic `call_id`. + +`thinking` events are fire-and-forget incremental deltas. No started/ended +lifecycle — the client derives "thinking stopped" from the next non-thinking +event. + +`stream_cleared` is emitted at the end of a primary agent's stdout streaming +loop (before `agent_exited`) and at the start of a new primary agent's +streaming loop (to reset for the new agent). + +### Interaction events + +| Event | What happened | Payload fields | `agent_id` | +|---|---|---|---| +| `questions_asked` | Agent asked the user questions | `token, questions` | set | +| `questions_answered` | User answered (or interaction cancelled) | `token, ?answers, cancelled` | set | +| `artifact_review_requested` | Agent requested artifact review | `token, path, description, content` | set | +| `artifact_reviewed` | User reviewed artifact (or cancelled) | `token, ?accepted, ?response, cancelled` | set | +| `workflow_decision_requested` | Orchestrator proposed next phases | `token, chat_turns` | set | +| `workflow_decided` | User chose next phase (or cancelled) | `token, ?decision, cancelled` | set | + +`agent_id` on resolution events is the agent whose interaction was resolved +(same as the requesting agent). Cancellation (`cancelled: true`) occurs when +the agent exits while the interaction is pending — there is no separate +cancellation event type. + +### Resource events + +| Event | What happened | Payload fields | `agent_id` | +|---|---|---|---| +| `artifact_created` | New file appeared in epic directory | `path, size, modified_at` | if known | +| `artifact_modified` | Existing file was modified | `path, size, modified_at` | if known | +| `artifact_removed` | File was removed from epic directory | `path` | if known | + +`agent_id` is the primary agent at scan time (approximate — scanning happens +at phase boundaries, not on individual file writes). `build_artifact_diff()` in +`koan/events.py` compares old and new artifact sets and emits individual events +for each difference. + +### Optional usage metadata + +Token/usage fields are optional on events that naturally carry them: + +```python +class Usage(BaseModel): + input_tokens: int = 0 # tokens sent to LLM + output_tokens: int = 0 # tokens received from LLM +``` + +Present on: `agent_step_advanced`, `agent_exited`, `tool_called`, +`tool_completed`. The fold accumulates these into per-agent token totals. + +--- + +## The Projection + +The fold reduces `(Projection, VersionedEvent) → Projection`. It is a pure +function: same event sequence → same projection. No I/O, no side effects. +Unknown event types return the projection unchanged (logged warning). + +```python +class AgentProjection(BaseModel): + agent_id: str + role: str + model: str | None = None + step: int = 0 + step_name: str = "" + input_tokens: int = 0 + output_tokens: int = 0 + +class Projection(BaseModel): + # Run state + run_started: bool = False + phase: str = "" + + # Agents + primary_agent: AgentProjection | None = None + scouts: dict[str, AgentProjection] = {} # keyed by agent_id + completed_agents: list[AgentProjection] = [] # agents that exited (preserves final token totals) + + # Activity (raw events appended as-is) + activity_log: list[dict] = [] + stream_buffer: str = "" # accumulated stream_delta text + + # Interactions + active_interaction: dict | None = None + + # Resources + artifacts: dict[str, dict] = {} # keyed by path + notifications: list[dict] = [] # derived from error events + + # Completion + completion: dict | None = None +``` + +`done_phases` is NOT in the projection — it is a frontend-only derivation from +`phase` using the frontend's `ALL_PHASES` ordering constant. + +`notifications` is derived by the fold from `agent_spawn_failed` and +`agent_exited` with error. It is not a dedicated event type — these are +projections of facts, preserved in the snapshot so they survive page refresh. + +### Fold cases + +**Lifecycle:** + +| Event | Projection update | +|---|---| +| `phase_started` | `phase = event.phase`, `run_started = True` | +| `agent_spawned` | if `is_primary`: set `primary_agent`; else: add to `scouts[agent_id]` | +| `agent_spawn_failed` | append to `notifications` | +| `agent_step_advanced` | update `step`, `step_name` on agent; if `usage`: accumulate tokens | +| `agent_exited` | accumulate final `usage` tokens, move agent to `completed_agents`; if primary: `primary_agent = None`; if scout: remove from `scouts`; if `error`: append to `notifications` | +| `workflow_completed` | `completion = event.payload` | + +**Activity:** + +| Event | Projection update | +|---|---| +| `tool_called` | append raw event to `activity_log`; if `usage`: accumulate tokens on agent | +| `tool_completed` | append raw event to `activity_log`; if `usage`: accumulate tokens on agent | +| `thinking` | append raw event to `activity_log` | +| `stream_delta` | `stream_buffer += event.delta` | +| `stream_cleared` | `stream_buffer = ""` | + +**Interactions:** + +| Event | Projection update | +|---|---| +| `questions_asked` | `active_interaction = {interaction_type: "questions_asked", **payload}` | +| `questions_answered` | `active_interaction = None` | +| `artifact_review_requested` | `active_interaction = {interaction_type: "artifact_review_requested", **payload}` | +| `artifact_reviewed` | `active_interaction = None` | +| `workflow_decision_requested` | `active_interaction = {interaction_type: "workflow_decision_requested", **payload}` | +| `workflow_decided` | `active_interaction = None` | + +The fold stores `interaction_type` (the event type string) alongside the payload +so the frontend can discriminate which component to render without duck-typing +payload fields. + +**Resources:** + +| Event | Projection update | +|---|---| +| `artifact_created` | add `{path, size, modified_at}` to `artifacts[path]` | +| `artifact_modified` | update `artifacts[path]` with new `size`, `modified_at` | +| `artifact_removed` | delete `artifacts[path]` | + +**Unknown event type** → return projection unchanged, log warning. + +**Unknown `agent_id`** (event references an agent not in `primary_agent` or +`scouts`) → return projection unchanged, log warning. + +**Fold exception safety:** `fold()` wraps each event type handler in +`try/except`. Any exception returns projection unchanged and logs the exception +with full event details. The event is still appended to the log (append-only is +inviolable) but its fold effect is skipped. + +**Accumulating fields** (`activity_log`, `notifications`, `stream_buffer`) are +unbounded — entries are never evicted. Runs are short-lived; the in-memory cost +is bounded by run duration. + +--- + +## ProjectionStore + +`koan/projections.py` contains the store class. This module has **zero koan +domain imports** — it is pure event-sourcing machinery. Domain-to-event +bridging lives in `koan/events.py`. + +```python +class ProjectionStore: + """In-memory versioned event log + materialized projection.""" + + events: list[VersionedEvent] # append-only + projection: Projection # eagerly materialized after each push_event + version: int # current version (0 = empty) + subscribers: list[asyncio.Queue] + + def push_event(self, event_type: str, payload: dict, + agent_id: str | None = None) -> VersionedEvent: + """Append event, increment version, fold projection, broadcast to subscribers.""" + + def get_snapshot(self) -> dict: + """Return {version: int, state: dict} — the full projection as a dict.""" + + def events_since(self, version: int) -> list[VersionedEvent]: + """Return events with version > given version, in order.""" + + def subscribe(self) -> asyncio.Queue: + """Create and register a subscriber queue. Queue receives VersionedEvent objects.""" + + def unsubscribe(self, queue: asyncio.Queue) -> None: + """Remove a subscriber queue.""" +``` + +`push_event()` snapshots `self.subscribers` before iterating +(`for q in list(self.subscribers)`) to avoid `RuntimeError` if a subscriber +is added or removed during broadcast. + +### Event payload builders: koan/events.py + +`koan/events.py` bridges koan domain types (`AgentState`, `list_artifacts`, +`RunnerDiagnostic`, etc.) into typed event payloads. It imports domain types; +`projections.py` does not. + +```python +def build_agent_spawned(agent: AgentState) -> dict +def build_agent_exited(exit_code: int, error: str | None = None, usage: dict | None = None) -> dict +def build_agent_spawn_failed(role: str, diagnostic: RunnerDiagnostic) -> dict +def build_step_advanced(step: int, step_name: str, usage: dict | None = None) -> dict +def build_tool_called(call_id: str, tool: str, args: dict | str, summary: str = "") -> dict +def build_tool_completed(call_id: str, tool: str, result: str | None = None) -> dict +def build_artifact_diff(old: dict[str, dict], new_artifacts: list[dict]) -> list[tuple[str, dict]] +# etc. +``` + +`build_artifact_diff` compares old and new artifact sets, returns a list of +`(event_type, payload)` tuples — one per created/modified/removed file. + +Callers import from both modules: + +```python +from .projections import ProjectionStore +from .events import build_agent_spawned + +store.push_event("agent_spawned", build_agent_spawned(agent), agent_id=agent.agent_id) +``` + +--- + +## SSE Protocol + +### Endpoint + +`GET /events?since=N` + +| `since` value | Server response | +|---|---| +| `0` (or omitted) | Send one `snapshot` SSE event, then stream live events | +| `N > 0` | Replay events with `version > N`, then stream live events | +| `N > current_version` (server restart) | Send `fatal_error` SSE event, close connection | + +The server retains the full event log in memory. Replay is always possible for +any valid version. + +When `since > current_version` (stale client after server restart), the server +sends a `fatal_error` SSE event with `{"reason": "version_not_available"}` and +closes the connection. The frontend handles `fatal_error` by closing the +`EventSource` without scheduling a reconnect and rendering a "reload required" +banner. This avoids infinite reconnect loops (browsers' `EventSource` fires +`onerror` on non-200 responses and would retry with the same stale version). + +### Wire format + +**Snapshot event** (`since=0`): + +``` +event: snapshot +data: {"version": 42, "state": { ...projection as dict... }} +``` + +**Versioned event** (replay or live stream): + +``` +event: agent_spawned +data: {"version": 43, "agent_id": "abc", "role": "intake", ...} +``` + +The SSE event name is the event type. Version and `agent_id` are included in +every data payload. The snapshot payload uses backend-native snake_case — the +frontend transforms to camelCase at the bridge boundary. + +### Reconnect flow + +``` +Browser loads → connect ?since=0 → receive snapshot → render full state +Browser refreshes → connect ?since=0 → receive snapshot → render full state +Connection drops → reconnect ?since=N → receive events N+1..M → fold each → up to date +``` + +--- + +## Frontend Integration + +The Zustand store gains: + +```typescript +lastVersion: number // version of last applied event or snapshot + +applySnapshot(data): // atomic replace of entire store state +applyEvent(event): // incremental fold — mirrors backend fold cases +``` + +On snapshot, `applySnapshot` atomically replaces all store state via +`useStore.setState(transform(data))`. No merge logic. Any visual flash from +the re-render is acceptable — simplicity over smoothness. + +`connectSSE()` in `sse/connect.ts`: + +1. Connects with `new EventSource('/events?since=${store.lastVersion}')` +2. `snapshot` event → `store.applySnapshot(data)`, sets `lastVersion` +3. All other events → `store.applyEvent(event)`, increments `lastVersion` +4. On disconnect: `lastVersion` is already in store; reconnect uses it automatically + +The TypeScript fold mirrors the Python fold. Both must produce the same +projection shape from the same event sequence. When adding a new event type, +add a fold case to both implementations. + +`done_phases` is NOT in the projection snapshot. The frontend derives it from +`phase` using its own `ALL_PHASES` ordering constant. Notification severity is +derived from event type in the frontend's `SEVERITY_MAP`. + +--- + +## Relationship to the Audit Fold + +Koan has two independent fold systems sharing the same structural pattern (pure +fold function, append-only log) but serving different purposes: + +| Aspect | Audit fold (`koan/audit/fold.py`) | Projection fold (`koan/projections.py`) | +|---|---|---| +| Input | Per-subagent audit events (`events.jsonl`) | Workflow-level projection events | +| Output | Per-subagent `Projection` (phase, step, tokens, tool calls) | Frontend-visible `Projection` (all agents, run state, UI interactions) | +| Scope | One subagent's execution | Entire workflow run | +| Persistence | Written to `state.json` on disk | In-memory only | +| Consumers | Debugging, post-mortem analysis | Browser frontend via SSE | +| Parallelism | One fold per subagent | Single fold for the whole run | + +The audit fold tracks the internal execution of each subagent. The projection +fold tracks the frontend-visible state of the whole workflow. They share the +same structural pattern but are not connected. + +--- + +## Design Decisions + +### No external library + +There is no canonical Python library for in-memory event sourcing with +subscriptions that fits this use case: + +- **`python-eventsourcing`** — designed for database persistence (PostgreSQL, + etc.), not in-memory UI state +- **`reactivex`/`rxpy`** — reactive streams, awkward with asyncio, overkill + for this volume + +The pattern — append-only list + pure fold + `asyncio.Queue` subscribers — is +simple enough to implement directly. `koan/audit/fold.py` demonstrates the same +pattern for the audit domain. + +### Why all events are versioned, including stream_delta + +Token deltas fire at high frequency. Including each delta in the versioned log +means the log grows large, but the **snapshot** captures only +`stream_buffer: "accumulated text"` — a single small string. Reconnecting +clients receive the accumulated buffer from the snapshot, not thousands of +individual deltas. + +The uniform model (every event gets a version) eliminates special-case code +paths. A system where some events are versioned and others are not creates +complexity in the reconnect path. + +### Why tool events are generic, not per-tool-type + +Tool schemas vary across runners and versions. A separate event type per tool +(`read_called`, `bash_called`, etc.) would require updating the event type +system whenever a runner adds or renames a tool. The `tool` field carries a +canonical normalized name; `args` and `result` are unstructured. The fold +appends raw events to the activity log without interpreting tool semantics. + +### Why tool name normalization is per-runner + +Each runner normalizes its own tool names in `parse_stream_event()`. This +keeps normalization knowledge co-located with runner-specific parsing logic. +By the time a `StreamEvent` leaves the runner, tool names are canonical +(`read`, `bash`, `edit`, `grep`, etc.). A central alias table would require +updating a shared file for each runner-specific change. + +### Why MCP tool calls are authoritative over stdout + +When a subagent calls a koan MCP tool, the call appears twice: as an MCP +request (structured, complete) and in the runner's stdout stream +(runner-specific format, possibly truncated). The MCP endpoint has full +structured data for both the call and the result. Stdout events are filtered +to exclude koan MCP tool names; only agent-native tools are sourced from stdout. + +### Why notification_fired is eliminated + +A generic notification bucket conflates facts with presentation concerns. Each +condition that warrants user notification is captured by a specific fact event +(`agent_spawn_failed`, `agent_exited` with error, `cancelled: true` on +interaction resolution). The fold derives `notifications` from these facts. The +frontend determines which events are notification-worthy and maps event types +to severity in its own `SEVERITY_MAP`. + +### Why artifacts use diff events, not a full list + +`artifact_created`/`artifact_modified`/`artifact_removed` carry exactly what +changed, not the full current set. The fold maintains `artifacts` as a +`dict[str, dict]` keyed by path, enabling O(1) per-event updates. + +### Why the envelope has no UUID or causation fields + +`version` is a unique identifier within a run — no UUID needed. Causation and +correlation IDs matter in multi-writer distributed systems where independent +producers interleave events and causal chains are ambiguous. Koan has a single +writer (the driver process). The causal chain is implicit in temporal ordering +plus `agent_id`. There is no cross-system correlation to track. + +### Why projections.py has zero koan domain imports + +`koan/projections.py` contains pure event-sourcing machinery. It imports +nothing from the koan domain. Domain-to-event bridging lives in `koan/events.py`. +This separation makes the projection engine testable in isolation and prevents +the event schema from leaking domain implementation details. + +### Why activity_log stores raw events + +`tool_called`, `tool_completed`, and `thinking` events are appended to +`activity_log` as-is without normalization. The frontend renders what it needs +from the raw payload. A normalization layer would need to anticipate every +display use case in advance; raw events let the frontend decide. + +### Why accumulating fields are unbounded + +`activity_log`, `notifications`, and `stream_buffer` are never evicted. +Capping them would require eviction logic that creates edge cases around what a +reconnecting client receives in a snapshot. koan is one-shot — the server shuts +down after the workflow completes — so accumulation is bounded by run duration. + +### Why the server shuts down after workflow completion + +koan runs one workflow per server instance. After `workflow_completed` is +emitted, the server shuts down gracefully. There is no idle state between runs, +no need to reset projection state, and no ambiguity about what a freshly +connecting browser should receive. + +### Why version-negotiated catch-up instead of always-snapshot + +A brief network hiccup should not force the frontend to rebuild all state from +scratch. `?since=N` lets a briefly-disconnected client receive only the events +it missed (typically a handful) and fold them incrementally. + +### Why snapshot triggers atomic state replacement + +When the frontend receives a snapshot, `useStore.setState(transform(data))` +atomically replaces the entire store. No merge logic, no version comparison. +A snapshot is authoritative. Any visual re-render is acceptable. diff --git a/docs/subagents.md b/docs/subagents.md index 664337b..956bfd6 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -338,8 +338,8 @@ tool call arrives via MCP ``` Agent registration and deregistration are tracked in the in-process -`AgentState` registry. SSE events for agent lifecycle (`agent-start`, -`agent-complete`) are pushed when agents are registered/deregistered. +`AgentState` registry. SSE events for agent lifecycle (`agent_spawned`, +`agent_exited`) are pushed when agents are registered/deregistered. Intake sub-phase derivation happens server-side based on step number: diff --git a/docs/token-streaming.md b/docs/token-streaming.md index 988e738..69ce868 100644 --- a/docs/token-streaming.md +++ b/docs/token-streaming.md @@ -12,11 +12,12 @@ realtime. Koan receives incremental token output from subagent CLI processes by parsing their stdout line-by-line via `runner.parse_stream_event(line)` in `koan/subagent.py`. The runner normalizes provider-specific formats into -`StreamEvent` objects. Token deltas flow directly to connected browsers via -SSE -- bypassing the audit system entirely. +`StreamEvent` objects. Token deltas flow to connected browsers via SSE through +the projection system. -**Design invariant:** Token streaming flows through runner stdout parsing, not -through the audit pipeline or file-based communication. +**Design invariant:** Token streaming flows through runner stdout parsing, then +through `ProjectionStore.push_event("stream_delta", ...)`. See the SSE Path +section for details. --- @@ -59,49 +60,83 @@ On process exit, the buffer is flushed in case the process exited mid-line. ## SSE Path -Koan has two data paths from subagents to the browser: - -1. **Audit pipeline** -- durable, tool-call-level. Use for state that must - survive restarts, participate in `fold()`, and be replayed on reconnect. -2. **Stdout pipeline** -- ephemeral, token-level, pushed directly to SSE. Use - for high-frequency display data with no persistence value. - -Token streaming uses the stdout pipeline: +Token deltas flow through the projection system: ``` CLI stdout -> line parser -> runner.parse_stream_event(line) -> StreamEvent with delta - -> push SSE "token-delta" event to connected browsers + -> push_event("stream_delta", {"agent_id": ..., "delta": "..."}) + -> ProjectionStore: append to log, fold projection.stream_buffer += delta + -> broadcast versioned event to SSE subscribers + -> browser receives: event: stream_delta / data: {"version": N, ...} + -> frontend fold: store.streamBuffer += event.delta +``` + +`stream_delta` events go through `ProjectionStore` like all other events. The +fold step is in-memory only (appending to `projection.stream_buffer`) — there +is no disk I/O per delta. This is distinct from the audit pipeline, which +writes to disk after each event. + +When a subagent finishes streaming, the caller emits: + +``` +push_event("stream_cleared", {"agent_id": ...}) +``` + +The fold sets `projection.stream_buffer = ""`. The frontend clears its +`streamBuffer` slice accordingly. + +--- + +## Replay on Reconnect + +When a client connects or reconnects with `?since=0`, the server sends a +`snapshot` event. The snapshot includes the current `stream_buffer` value — +the full accumulated text from all `stream_delta` events since the buffer was +last cleared. + +``` +event: snapshot +data: {"version": 142, "state": {"stream_buffer": "accumulated text...", ...}} ``` -This path bypasses the audit pipeline intentionally. Going through audit would -require appending events to `events.jsonl` and running `fold()` per token -- -hundreds of cycles per second for ephemeral display data. +The reconnecting client receives the complete buffer in a single snapshot field. +Individual `stream_delta` events are not replayed on reconnect — the snapshot +`stream_buffer` represents their accumulated effect. -### Replay on reconnect +When reconnecting with `?since=N` (brief disconnect), the client replays only +the `stream_delta` events it missed and folds them incrementally, same as any +other event type. -The web server maintains accumulated streaming text. On browser reconnect, -a single `token-delta` event containing the full accumulated text is sent. -When the subagent completes, the accumulated text is cleared. +See [projections.md -- Version-negotiated catch-up](./projections.md#sse-protocol) +for the full reconnect protocol. --- ## Frontend -The frontend (`koan/web/static/js/koan.js`) receives SSE `token-delta` events -and appends the delta text to the streaming display area. The HTMX SSE -integration handles connection and reconnection. +The frontend Zustand store has a `streamBuffer: string` slice. The `applyEvent` +fold handler for `stream_delta` appends the delta: + +```typescript +case 'stream_delta': + return { streamBuffer: state.streamBuffer + event.delta } +case 'stream_cleared': + return { streamBuffer: '' } +``` + +`applySnapshot` sets `streamBuffer` from the snapshot's `stream_buffer` field. -Server-rendered HTML fragments from `koan/web/templates/` provide the -structural layout. The JavaScript in `koan.js` handles only the incremental -text accumulation for streaming display. +The `ActivityFeed` component renders `streamBuffer` as the in-flight streaming +text area. When `stream_cleared` fires, the buffer empties and the streaming +display resets for the next agent. --- ## What Is Not Streamed -| Signal | Why excluded | +| Signal | Why excluded from stream_buffer | | ---------------------- | ------------------------------------------------------------- | -| Thinking blocks | Not visible to users in current UI | -| Tool execution updates | Handled by audit projection -> SSE events | +| Thinking tokens | Go through `thinking` events into `activity_log`, not `stream_buffer` | +| Tool execution updates | Handled via `tool_called`/`tool_completed` projection events | | Scout output | Scouts push their own audit events; no token streaming needed | From fa1be6f5788398bb562b05ba4e72087d566cc9e2 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 16:15:10 +0700 Subject: [PATCH 201/412] auto-rebuild frontend on startup when sources are newer than build --- frontend/src/components/Completion.tsx | 14 +++--- frontend/src/store/index.ts | 3 +- koan/__main__.py | 60 +++++++++++++++++++++++++- 3 files changed, 68 insertions(+), 9 deletions(-) diff --git a/frontend/src/components/Completion.tsx b/frontend/src/components/Completion.tsx index d5853ad..96e766f 100644 --- a/frontend/src/components/Completion.tsx +++ b/frontend/src/components/Completion.tsx @@ -1,11 +1,13 @@ import { useStore } from '../store/index' -import { formatSize } from '../utils' export function Completion() { const completion = useStore(s => s.completion) + const artifacts = useStore(s => s.artifacts) if (!completion) return null + const artifactList = Object.keys(artifacts) + return (
@@ -15,14 +17,12 @@ export function Completion() {

{completion.summary || 'All phases completed successfully.'}

- {(completion.artifacts ?? []).length > 0 && ( + {artifactList.length > 0 && (
- {completion.artifacts.map(a => ( -
+ {artifactList.map(path => ( +
[OK] - - {a.path} ({formatSize(a.size)}) - + {path}
))}
diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 120055b..6adad9a 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -29,6 +29,7 @@ export interface CompletionInfo { success: boolean summary: string error?: string + phase?: string } export interface NotificationEntry { @@ -201,7 +202,7 @@ interface KoanState { applyEvent: (event: Record) => void } -export const useStore = create((set, get) => ({ +export const useStore = create((set) => ({ connected: false, lastVersion: 0, fatalError: false, diff --git a/koan/__main__.py b/koan/__main__.py index 6ffff08..6e3744d 100644 --- a/koan/__main__.py +++ b/koan/__main__.py @@ -1,17 +1,71 @@ # Entry point: `uv run koan` or `python -m koan`. # Loads config, builds AppState, starts the Starlette server on 127.0.0.1. +# +# In a development checkout (frontend/ directory exists next to the koan +# package), the entry point automatically rebuilds the Vite bundle into +# koan/web/static/app/ when frontend sources are newer than the last build. +# In an installed wheel the frontend/ directory is absent and the check is +# a no-op — the pre-built assets ship inside the wheel. from __future__ import annotations import argparse import asyncio +import logging +import subprocess +import sys +from pathlib import Path import uvicorn from .config import load_koan_config from .logger import setup_logging from .state import AppState -from .web.app import create_app +from .web.app import FRONTEND_DIST, create_app + +log = logging.getLogger(__name__) + +# Resolve relative to the *repository root* (one level above the koan package). +# Only present in a development checkout — absent in an installed wheel. +_REPO_ROOT = Path(__file__).resolve().parent.parent +_FRONTEND_SRC = _REPO_ROOT / "frontend" / "src" + + +def _frontend_needs_rebuild() -> bool: + """True when frontend sources are newer than the last Vite build.""" + if not _FRONTEND_SRC.is_dir(): + return False # not a dev checkout + + build_marker = FRONTEND_DIST / "index.html" + if not build_marker.exists(): + return True # never built + + build_mtime = build_marker.stat().st_mtime + return any( + p.stat().st_mtime > build_mtime + for p in _FRONTEND_SRC.rglob("*") + if p.is_file() + ) + + +def _rebuild_frontend() -> None: + """Run ``npm run build`` in the frontend directory.""" + frontend_dir = _FRONTEND_SRC.parent + log.info("Frontend sources changed — rebuilding…") + try: + subprocess.run( + ["npm", "run", "build"], + cwd=str(frontend_dir), + check=True, + capture_output=True, + text=True, + ) + log.info("Frontend build complete.") + except FileNotFoundError: + log.warning("npm not found — skipping frontend rebuild.") + except subprocess.CalledProcessError as exc: + log.error("Frontend build failed:\n%s", exc.stderr) + sys.exit(1) def main() -> None: @@ -19,10 +73,14 @@ def main() -> None: parser.add_argument("--port", type=int, default=8000) parser.add_argument("--log-level", type=str, default="INFO") parser.add_argument("--no-open", action="store_true", help="Don't open browser on startup") + parser.add_argument("--skip-build", action="store_true", help="Skip frontend rebuild check") args = parser.parse_args() setup_logging(args.log_level) + if not args.skip_build and _frontend_needs_rebuild(): + _rebuild_frontend() + config = asyncio.run(load_koan_config()) app_state = AppState(config=config, port=args.port, open_browser=not args.no_open) app = create_app(app_state) From b16665306679995b70ff0cf3030c4ac85e670c53 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 16:51:36 +0700 Subject: [PATCH 202/412] fix codex MCP tool approval: pass --dangerously-bypass-approvals-and-sandbox in exec mode --- koan/runners/codex.py | 1 + 1 file changed, 1 insertion(+) diff --git a/koan/runners/codex.py b/koan/runners/codex.py index e3895e6..dbd430d 100644 --- a/koan/runners/codex.py +++ b/koan/runners/codex.py @@ -60,6 +60,7 @@ def build_command( cmd = [ installation.binary, "exec", "--json", + "--dangerously-bypass-approvals-and-sandbox", "-c", f"mcp_servers.koan.url={mcp_url}", boot_prompt, ] From c5ea9d2923d000aaba1542d9e78299eaf2c697b6 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 17:14:30 +0700 Subject: [PATCH 203/412] fix activity feed rendering: wrap stream text, filter thinking noise, fix agent timer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ActivityFeed: separate tool entries (compact lines with ✓/› status) from stream output (wrapping text block below) - Store: thinking events set isThinking flag instead of polluting activityLog; applySnapshot filters thinking entries from activity_log - CSS: stream-output uses pre-wrap + word-break; tool entries stay compact with nowrap/ellipsis; thinking indicator with pulse animation - Codex runner: append trailing newline to agent_message deltas so consecutive messages don't run together in the stream buffer - Projections: add started_at_ms to AgentProjection and pass it from agent_spawned payload (fixes timer showing epoch-based elapsed time) --- frontend/src/components/ActivityFeed.tsx | 25 +++++++--- frontend/src/store/index.ts | 30 +++++------- frontend/src/styles/layout.css | 60 +++++++++++++++++++++--- koan/projections.py | 2 + koan/runners/codex.py | 5 +- 5 files changed, 90 insertions(+), 32 deletions(-) diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index 5076dfd..cd995dd 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -5,6 +5,7 @@ import { useAutoScroll } from '../hooks/useAutoScroll' export function ActivityFeed() { const activityLog = useStore(s => s.activityLog) const streamBuffer = useStore(s => s.streamBuffer) + const isThinking = useStore(s => s.isThinking) const scrollRef = useRef(null) useAutoScroll(scrollRef) @@ -12,16 +13,20 @@ export function ActivityFeed() { return (
+ {/* Tool call entries — compact lines */} {activityLog.map((entry, i) => (
+ + {entry.inFlight ? '›' : '✓'} + {entry.tool || ''} {entry.summary || ''} @@ -30,13 +35,19 @@ export function ActivityFeed() {
))} + {/* Thinking indicator — shown when LLM is reasoning */} + {isThinking && !streamBuffer && ( +
+ ● + Thinking… +
+ )} + + {/* Stream output — wrapping text block for LLM output */} {streamBuffer && ( -
- • - - {streamBuffer} - - +
+ {streamBuffer} +
)}
diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 6adad9a..11d223c 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -159,6 +159,7 @@ interface KoanState { // Activity feed activityLog: ActivityEntry[] streamBuffer: string + isThinking: boolean // Notifications notifications: NotificationEntry[] @@ -215,6 +216,7 @@ export const useStore = create((set) => ({ scouts: {}, activityLog: [], streamBuffer: '', + isThinking: false, notifications: [], activeInteraction: null, artifacts: {}, @@ -306,10 +308,10 @@ export const useStore = create((set) => ({ })) // Transform activity_log - // The backend fold appends both tool_called and tool_completed as raw entries. - // Reconstruct the collapsed one-entry-per-call view that the live applyEvent - // fold produces: exclude tool_completed entries and use them only to determine - // the inFlight state of their matching tool_called entry. + // The backend fold appends tool_called, tool_completed, and thinking as raw + // entries. Reconstruct the collapsed one-entry-per-call view that the live + // applyEvent fold produces: exclude tool_completed (used only to determine + // inFlight state) and thinking (rendered separately as isThinking indicator). const rawLog = (state['activity_log'] ?? []) as Record[] const completedCallIds = new Set( rawLog @@ -318,7 +320,7 @@ export const useStore = create((set) => ({ .filter(Boolean) ) const activityLog: ActivityEntry[] = rawLog - .filter(e => e['event_type'] !== 'tool_completed') + .filter(e => e['event_type'] !== 'tool_completed' && e['event_type'] !== 'thinking') .map((e) => { const callId = e['call_id'] as string | undefined const isToolCall = e['event_type'] === 'tool_called' @@ -347,6 +349,7 @@ export const useStore = create((set) => ({ notifications, activityLog, streamBuffer: (state['stream_buffer'] as string) ?? '', + isThinking: false, completion: completion ?? null, }) }, @@ -475,7 +478,7 @@ export const useStore = create((set) => ({ callId: event['call_id'] as string, ts: new Date().toISOString(), } - return { ...base, activityLog: [...s.activityLog, entry] } + return { ...base, activityLog: [...s.activityLog, entry], isThinking: false } } case 'tool_completed': { @@ -488,21 +491,14 @@ export const useStore = create((set) => ({ } } - case 'thinking': { - const entry: ActivityEntry = { - tool: '', - summary: (event['delta'] as string) ?? 'thinking...', - inFlight: false, - ts: new Date().toISOString(), - } - return { ...base, activityLog: [...s.activityLog, entry] } - } + case 'thinking': + return { ...base, isThinking: true } case 'stream_delta': - return { ...base, streamBuffer: s.streamBuffer + ((event['delta'] as string) ?? '') } + return { ...base, streamBuffer: s.streamBuffer + ((event['delta'] as string) ?? ''), isThinking: false } case 'stream_cleared': - return { ...base, streamBuffer: '' } + return { ...base, streamBuffer: '', isThinking: false } // ── Interactions ─────────────────────────────────────────────────── diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index 51eaf95..358ce2a 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -192,25 +192,44 @@ .activity-line { display: flex; - gap: var(--space-2); + gap: var(--space-1); font-family: var(--font-mono); font-size: var(--font-size-sm); color: var(--text-muted); - padding: 2px 0; + padding: 3px 0; line-height: 1.4; + min-height: 20px; } -.activity-line.activity-high { - color: var(--text-muted); +.activity-line.activity-done { + color: var(--text-ghost); +} + +.activity-status { + flex-shrink: 0; + width: 14px; + text-align: center; +} + +.activity-inflight .activity-status { + color: var(--copper); +} + +.activity-done .activity-status { + color: var(--green); + font-size: 10px; } .activity-tool { - color: var(--text-ghost); - min-width: 48px; + color: var(--text-muted); flex-shrink: 0; + max-width: 180px; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; } -.activity-high .activity-tool { +.activity-inflight .activity-tool { color: var(--copper); } @@ -218,6 +237,33 @@ white-space: nowrap; overflow: hidden; text-overflow: ellipsis; + flex: 1; + min-width: 0; +} + +/* Stream output -- wrapping text block for LLM text */ +.stream-output { + font-family: var(--font-mono); + font-size: var(--font-size-sm); + color: var(--text); + line-height: 1.6; + white-space: pre-wrap; + word-break: break-word; + padding: var(--space-2) 0; + margin-top: var(--space-2); + border-top: 1px solid var(--border); +} + +/* Thinking indicator */ +.activity-thinking-indicator { + display: flex; + align-items: center; + gap: var(--space-2); + font-family: var(--font-mono); + font-size: var(--font-size-sm); + color: var(--text-muted); + padding: var(--space-2) 0; + margin-top: var(--space-2); } .activity-detail { diff --git a/koan/projections.py b/koan/projections.py index 2d045d7..71fec03 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -54,6 +54,7 @@ class AgentProjection(BaseModel): model: str | None = None step: int = 0 step_name: str = "" + started_at_ms: int = 0 input_tokens: int = 0 output_tokens: int = 0 @@ -127,6 +128,7 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: role=payload.get("role", ""), model=payload.get("model"), step=0, + started_at_ms=payload.get("started_at_ms", 0), ) if payload.get("is_primary", True): return projection.model_copy(update={"primary_agent": new_agent}) diff --git a/koan/runners/codex.py b/koan/runners/codex.py index dbd430d..770f1d3 100644 --- a/koan/runners/codex.py +++ b/koan/runners/codex.py @@ -94,7 +94,10 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: if item_type == "agent_message": text = item.get("text", "") if text: - return [StreamEvent(type="token_delta", content=text)] + # Codex emits complete messages (not token-by-token). + # Append a newline so consecutive messages don't run together + # in the stream buffer. + return [StreamEvent(type="token_delta", content=text + "\n")] elif item_type == "function_call": raw_name = item.get("name") or item.get("call_id", "tool") canonical = _normalize_tool_name(raw_name) From e24e0c3ad06f2c06b805adb4edbb807202beaac5 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 21:34:14 +0700 Subject: [PATCH 204/412] prefer claude/opus over codex/gpt-5 for strong tier in balanced profile Move claude/opus to first position in _TIER_PRIORITY['strong'] so all default agent roles (intake, decomposer, brief-writer, orchestrator, planner, etc.) use Claude when available. --- koan/runners/registry.py | 2 +- tests/test_registry.py | 14 +++++++------- tests/test_web_flows.py | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/koan/runners/registry.py b/koan/runners/registry.py index 2277307..2c037f6 100644 --- a/koan/runners/registry.py +++ b/koan/runners/registry.py @@ -40,7 +40,7 @@ # -- Balanced profile priority table ------------------------------------------- _TIER_PRIORITY: dict[ModelTier, list[tuple[str, str]]] = { - "strong": [("codex", "gpt-5"), ("claude", "opus"), ("gemini", "gemini-pro")], + "strong": [("claude", "opus"), ("codex", "gpt-5"), ("gemini", "gemini-pro")], "standard": [("claude", "sonnet"), ("codex", "gpt-5"), ("gemini", "gemini-pro")], "cheap": [("claude", "haiku"), ("codex", "gpt-5-mini"), ("gemini", "gemini-flash")], } diff --git a/tests/test_registry.py b/tests/test_registry.py index 09b7ab3..9c59dbe 100644 --- a/tests/test_registry.py +++ b/tests/test_registry.py @@ -64,10 +64,9 @@ def test_all_available_with_models(self): ] p = compute_balanced_profile(probes) assert p.name == "balanced" - assert p.tiers["strong"].runner_type == "codex" - assert p.tiers["strong"].model == "gpt-5" - # codex only supports disabled -- thinking is clamped - assert p.tiers["strong"].thinking == "disabled" + assert p.tiers["strong"].runner_type == "claude" + assert p.tiers["strong"].model == "opus" + assert p.tiers["strong"].thinking == "high" assert p.tiers["standard"].runner_type == "claude" assert p.tiers["standard"].model == "sonnet" assert p.tiers["standard"].thinking == "medium" @@ -83,7 +82,7 @@ def test_all_available_without_models_uses_defaults(self): ProbeResult(runner_type="gemini", available=True), ] p = compute_balanced_profile(probes) - assert p.tiers["strong"].runner_type == "codex" + assert p.tiers["strong"].runner_type == "claude" assert p.tiers["strong"].thinking == "high" # no model info -> default def test_only_claude_available(self): @@ -121,13 +120,14 @@ def test_no_runners_available(self): assert p.name == "balanced" assert p.tiers == {} - def test_codex_preferred_for_strong(self): + def test_claude_preferred_for_strong(self): probes = [ ProbeResult(runner_type="claude", available=True, models=_claude_models()), ProbeResult(runner_type="codex", available=True, models=_codex_models()), ] p = compute_balanced_profile(probes) - assert p.tiers["strong"].runner_type == "codex" + assert p.tiers["strong"].runner_type == "claude" + assert p.tiers["strong"].model == "opus" def test_claude_preferred_for_standard(self): probes = [ diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index c314e3e..1093d2f 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -499,7 +499,7 @@ def test_probe_refresh_triggers_restate(self, client, app_state): ProbeResult(runner_type="codex", available=True), ] fresh_profile = Profile(name="balanced", tiers={ - "strong": ProfileTier(runner_type="codex", model="gpt-5", thinking="high"), + "strong": ProfileTier(runner_type="claude", model="opus", thinking="high"), }) # Pre-populate with stale data From f46bb7b8796a5691e573e64aa156924e713662c7 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Mon, 30 Mar 2026 21:42:52 +0700 Subject: [PATCH 205/412] enable source maps and skip minification in vite build MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Local-only server — bundle size is irrelevant. Source maps and readable names make React DevTools, browser debugger, and console traces useful for inspecting store state and tracing rendering issues. --- frontend/vite.config.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts index 5486c34..8ec991b 100644 --- a/frontend/vite.config.ts +++ b/frontend/vite.config.ts @@ -13,6 +13,12 @@ export default defineConfig({ // `uv run koan` serves the latest build without a copy step. outDir: '../koan/web/static/app', emptyOutDir: true, + + // Dev-friendly build: keep readable names and source maps so React + // DevTools, browser debugger, and console traces are useful. + // The bundle is only served locally — size doesn't matter. + sourcemap: true, + minify: false, }, server: { From f4b66b419fe54c3855cb0b8cc780a3bd37c58545 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 11:33:11 +0700 Subject: [PATCH 206/412] use random free port when --port is not specified --- koan/__main__.py | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/koan/__main__.py b/koan/__main__.py index 6e3744d..0f725ce 100644 --- a/koan/__main__.py +++ b/koan/__main__.py @@ -12,6 +12,7 @@ import argparse import asyncio import logging +import socket import subprocess import sys from pathlib import Path @@ -68,9 +69,17 @@ def _rebuild_frontend() -> None: sys.exit(1) +def _find_free_port() -> int: + """Bind to port 0 and let the OS assign a free ephemeral port.""" + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: + s.bind(("127.0.0.1", 0)) + return s.getsockname()[1] + + def main() -> None: parser = argparse.ArgumentParser(prog="koan") - parser.add_argument("--port", type=int, default=8000) + parser.add_argument("--port", type=int, default=None, + help="Port to listen on (default: random free port)") parser.add_argument("--log-level", type=str, default="INFO") parser.add_argument("--no-open", action="store_true", help="Don't open browser on startup") parser.add_argument("--skip-build", action="store_true", help="Skip frontend rebuild check") @@ -81,12 +90,14 @@ def main() -> None: if not args.skip_build and _frontend_needs_rebuild(): _rebuild_frontend() + port = args.port if args.port is not None else _find_free_port() + config = asyncio.run(load_koan_config()) - app_state = AppState(config=config, port=args.port, open_browser=not args.no_open) + app_state = AppState(config=config, port=port, open_browser=not args.no_open) app = create_app(app_state) host = "127.0.0.1" - uvicorn.run(app, host=host, port=args.port, log_level=args.log_level.lower()) + uvicorn.run(app, host=host, port=port, log_level=args.log_level.lower()) if __name__ == "__main__": From 0af9a2be2a00f0f980ea093f3f00012459840408 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 11:48:27 +0700 Subject: [PATCH 207/412] Add -p/--prompt CLI option to pre-fill task description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a -p/--prompt flag to the koan CLI that pre-fills the task description textarea in the landing page. The prompt flows through: - CLI arg → AppState.initial_prompt - GET /api/initial-prompt endpoint serves it - Frontend LandingPage fetches and sets it on load --- frontend/src/api/client.ts | 6 ++++++ frontend/src/components/LandingPage.tsx | 7 +++++-- koan/__main__.py | 5 ++++- koan/state.py | 1 + koan/web/app.py | 8 ++++++++ 5 files changed, 24 insertions(+), 3 deletions(-) diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index b679d07..0ea3d93 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -190,6 +190,12 @@ export async function saveScoutConcurrency(value: number) { }) } +// -- Initial prompt ---------------------------------------------------------- + +export async function getInitialPrompt(): Promise<{ prompt: string }> { + return get('/api/initial-prompt') +} + // -- Artifacts --------------------------------------------------------------- export async function getArtifactContent( diff --git a/frontend/src/components/LandingPage.tsx b/frontend/src/components/LandingPage.tsx index 887af4d..4739ead 100644 --- a/frontend/src/components/LandingPage.tsx +++ b/frontend/src/components/LandingPage.tsx @@ -12,13 +12,16 @@ export function LandingPage() { const [error, setError] = useState(null) useEffect(() => { - Promise.all([api.getProfiles(), api.getProbe()]).then( - ([profilesData, probeData]) => { + Promise.all([api.getProfiles(), api.getProbe(), api.getInitialPrompt()]).then( + ([profilesData, probeData, promptData]) => { setProfiles(profilesData.profiles) if (profilesData.profiles.length > 0) { setProfile(profilesData.profiles[0].name) } setHasRunners(probeData.runners.some(r => r.available)) + if (promptData.prompt) { + setTask(promptData.prompt) + } }, ) }, []) diff --git a/koan/__main__.py b/koan/__main__.py index 0f725ce..7346fb1 100644 --- a/koan/__main__.py +++ b/koan/__main__.py @@ -83,6 +83,8 @@ def main() -> None: parser.add_argument("--log-level", type=str, default="INFO") parser.add_argument("--no-open", action="store_true", help="Don't open browser on startup") parser.add_argument("--skip-build", action="store_true", help="Skip frontend rebuild check") + parser.add_argument("-p", "--prompt", type=str, default="", + help="Pre-fill the task description") args = parser.parse_args() setup_logging(args.log_level) @@ -93,7 +95,8 @@ def main() -> None: port = args.port if args.port is not None else _find_free_port() config = asyncio.run(load_koan_config()) - app_state = AppState(config=config, port=port, open_browser=not args.no_open) + app_state = AppState(config=config, port=port, open_browser=not args.no_open, + initial_prompt=args.prompt) app = create_app(app_state) host = "127.0.0.1" diff --git a/koan/state.py b/koan/state.py index d98e491..b0566b9 100644 --- a/koan/state.py +++ b/koan/state.py @@ -63,4 +63,5 @@ class AppState: probe_results: list[ProbeResult] = field(default_factory=list) port: int = 8000 open_browser: bool = True + initial_prompt: str = "" config_write_lock: asyncio.Lock = field(default_factory=asyncio.Lock) diff --git a/koan/web/app.py b/koan/web/app.py index 1f482d1..a0cac06 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -818,6 +818,13 @@ async def api_settings_scout_concurrency(r: Request) -> Response: return JSONResponse({"ok": True}) +# -- Initial prompt endpoint -------------------------------------------------- + +async def api_initial_prompt(r: Request) -> Response: + st = _app_state(r) + return JSONResponse({"prompt": st.initial_prompt}) + + # -- App factory -------------------------------------------------------------- def _build_mcp(app_state: AppState): @@ -879,6 +886,7 @@ async def _open_browser(): Route("/api/settings/scout-concurrency", api_settings_scout_concurrency, methods=["PUT"]), Route("/api/settings/profile-form", api_settings_profile_form, methods=["GET"]), Route("/api/settings/installation-form", api_settings_installation_form, methods=["GET"]), + Route("/api/initial-prompt", api_initial_prompt, methods=["GET"]), Route("/events", sse_stream), ] From 8ce1dd5d705479d1a0f874a1759e601671722acf Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 11:51:13 +0700 Subject: [PATCH 208/412] add resolve_installation with binary validation and PATH fallback --- koan/runners/registry.py | 52 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/koan/runners/registry.py b/koan/runners/registry.py index 2c037f6..23f11d1 100644 --- a/koan/runners/registry.py +++ b/koan/runners/registry.py @@ -3,6 +3,9 @@ from __future__ import annotations +import logging +import shutil +from pathlib import Path from typing import TYPE_CHECKING from ..probe import ProbeResult @@ -109,6 +112,53 @@ def get_installation(self, runner_type: str, config: KoanConfig) -> AgentInstall details={"runner_type": runner_type}, )) + def resolve_installation(self, runner_type: str, config: KoanConfig) -> AgentInstallation: + """Resolve a working installation for *runner_type* with fallback. + + Priority: active installation -> any installation of same type -> PATH lookup. + Each candidate is validated by checking that its binary exists on disk. + """ + log = logging.getLogger("koan.registry") + + # 1. Try the active (or first) installation from config + try: + inst = self.get_installation(runner_type, config) + if Path(inst.binary).exists(): + return inst + log.warning( + "active %s installation '%s' binary missing (%s); trying alternatives", + runner_type, inst.alias, inst.binary, + ) + except RunnerError: + pass + + # 2. Try any other installation of this runner type + for inst in config.agent_installations: + if inst.runner_type == runner_type and Path(inst.binary).exists(): + log.info("falling back to %s installation '%s'", runner_type, inst.alias) + return inst + + # 3. Dynamic resolution from PATH + binary = shutil.which(runner_type) + if binary: + log.info("resolved %s from PATH: %s", runner_type, binary) + return AgentInstallation( + alias=f"{runner_type}-resolved", + runner_type=runner_type, + binary=binary, + ) + + raise RunnerError(RunnerDiagnostic( + code="no_installation", + runner=runner_type, + stage="resolve_installation", + message=( + f"No working {runner_type} installation found. " + f"Ensure '{runner_type}' is installed and on your PATH." + ), + details={"runner_type": runner_type}, + )) + def resolve_agent_config( self, role: SubagentRole, @@ -144,7 +194,7 @@ def resolve_agent_config( message=f"Profile '{profile.name}' has no tier '{tier}'", )) - installation = self.get_installation(profile_tier.runner_type, config) + installation = self.resolve_installation(profile_tier.runner_type, config) return installation, profile_tier.model, profile_tier.thinking From 2aa9ea34def86eac28003947b7ec1a58fe2445a4 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 11:51:20 +0700 Subject: [PATCH 209/412] refresh default installation paths from probe and remove redundant binary check --- koan/subagent.py | 9 --------- koan/web/app.py | 26 +++++++++++++++++--------- 2 files changed, 17 insertions(+), 18 deletions(-) diff --git a/koan/subagent.py b/koan/subagent.py index f793a74..3622478 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -101,15 +101,6 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None role, config, balanced_profile=app_state.balanced_profile, ) - # Fail fast on missing binary - if not Path(installation.binary).exists(): - raise RunnerError(RunnerDiagnostic( - code="binary_not_found", - runner=installation.runner_type, - stage="spawn", - message=f"Binary not found: {installation.binary}", - )) - runner = registry.get_runner(installation.runner_type, subagent_dir) model = model_alias except RunnerError as e: diff --git a/koan/web/app.py b/koan/web/app.py index a0cac06..0527fcb 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -417,18 +417,26 @@ async def _refresh_probe_state(st: AppState) -> None: st.probe_results = await probe_all_runners() st.balanced_profile = compute_balanced_profile(st.probe_results) - # Auto-create default installations for detected runners that lack one + # Auto-create or update default installations from probe results existing_types = {inst.runner_type for inst in st.config.agent_installations} changed = False for pr in st.probe_results: - if pr.available and pr.binary_path and pr.runner_type not in existing_types: - st.config.agent_installations.append(AgentInstallation( - alias=f"{pr.runner_type}-default", - runner_type=pr.runner_type, - binary=pr.binary_path, - extra_args=[], - )) - changed = True + if pr.available and pr.binary_path: + if pr.runner_type not in existing_types: + st.config.agent_installations.append(AgentInstallation( + alias=f"{pr.runner_type}-default", + runner_type=pr.runner_type, + binary=pr.binary_path, + extra_args=[], + )) + changed = True + else: + # Refresh binary path for auto-created default installations + for inst in st.config.agent_installations: + if inst.runner_type == pr.runner_type and inst.alias == f"{pr.runner_type}-default": + if inst.binary != pr.binary_path: + inst.binary = pr.binary_path + changed = True if changed: from ..config import save_koan_config await save_koan_config(st.config) From 0b15a82c031b1a1c313a19a5c4a543cb9a338470 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 11:51:26 +0700 Subject: [PATCH 210/412] add resolve_installation tests and update binary-not-found test expectations --- tests/test_registry.py | 55 ++++++++++++++++++++++++++++++++++++++++++ tests/test_subagent.py | 8 +++--- 2 files changed, 59 insertions(+), 4 deletions(-) diff --git a/tests/test_registry.py b/tests/test_registry.py index 9c59dbe..85b64d4 100644 --- a/tests/test_registry.py +++ b/tests/test_registry.py @@ -185,6 +185,61 @@ def test_fallback_only_when_no_active_alias(self): assert result is inst +# -- RunnerRegistry.resolve_installation --------------------------------------- + +class TestResolveInstallation: + def _make_config(self, installations, active=None): + return KoanConfig( + agent_installations=installations, + active_installations=active or {}, + ) + + def test_returns_active_when_binary_exists(self, tmp_path): + binary = tmp_path / "claude" + binary.touch() + inst = AgentInstallation(alias="my-claude", runner_type="claude", binary=str(binary)) + config = self._make_config([inst], active={"claude": "my-claude"}) + reg = RunnerRegistry() + result = reg.resolve_installation("claude", config) + assert result is inst + + def test_falls_back_to_other_installation_when_active_binary_missing(self, tmp_path): + good_binary = tmp_path / "claude" + good_binary.touch() + bad = AgentInstallation(alias="broken", runner_type="claude", binary="/nonexistent/claude") + good = AgentInstallation(alias="working", runner_type="claude", binary=str(good_binary)) + config = self._make_config([bad, good], active={"claude": "broken"}) + reg = RunnerRegistry() + result = reg.resolve_installation("claude", config) + assert result is good + + def test_falls_back_to_which_when_all_binaries_missing(self, monkeypatch): + inst = AgentInstallation(alias="bad", runner_type="claude", binary="/nonexistent/claude") + config = self._make_config([inst]) + monkeypatch.setattr("koan.runners.registry.shutil.which", lambda cmd: "/resolved/claude") + reg = RunnerRegistry() + result = reg.resolve_installation("claude", config) + assert result.binary == "/resolved/claude" + assert result.alias == "claude-resolved" + + def test_raises_when_nothing_works(self, monkeypatch): + inst = AgentInstallation(alias="bad", runner_type="claude", binary="/nonexistent/claude") + config = self._make_config([inst]) + monkeypatch.setattr("koan.runners.registry.shutil.which", lambda cmd: None) + reg = RunnerRegistry() + with pytest.raises(RunnerError) as exc_info: + reg.resolve_installation("claude", config) + assert exc_info.value.diagnostic.code == "no_installation" + + def test_raises_when_no_installations_and_not_on_path(self, monkeypatch): + config = self._make_config([]) + monkeypatch.setattr("koan.runners.registry.shutil.which", lambda cmd: None) + reg = RunnerRegistry() + with pytest.raises(RunnerError) as exc_info: + reg.resolve_installation("claude", config) + assert exc_info.value.diagnostic.code == "no_installation" + + # -- save_koan_config write lock ----------------------------------------------- class TestWriteLock: diff --git a/tests/test_subagent.py b/tests/test_subagent.py index 85ee6a4..d5f66c1 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -638,7 +638,8 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): "subagent_dir": subagent_dir, } - with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}): + with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}), \ + patch("koan.runners.registry.shutil.which", return_value=None): from koan.subagent import spawn_subagent exit_code = await spawn_subagent(task, app_state) @@ -649,8 +650,7 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): notifs = app_state.projection_store.projection.notifications spawn_fails = [n for n in notifs if n.get("type") == "agent_spawn_failed"] assert len(spawn_fails) >= 1 - assert spawn_fails[0]["error_code"] == "binary_not_found" - assert "/nonexistent/path/claude" in spawn_fails[0]["message"] + assert spawn_fails[0]["error_code"] == "no_installation" # Verify events.jsonl contains a runner_diagnostic events_path = Path(subagent_dir) / "events.jsonl" @@ -658,4 +658,4 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): lines = events_path.read_text().strip().split("\n") diag_events = [json.loads(l) for l in lines if "runner_diagnostic" in l] assert len(diag_events) >= 1 - assert diag_events[0]["code"] == "binary_not_found" + assert diag_events[0]["code"] == "no_installation" From da270bd262238b0fd3c8285b29700a2e96d12058 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 12:16:04 +0700 Subject: [PATCH 211/412] make resolve_installation fail-fast instead of silently falling back --- koan/runners/registry.py | 61 +++++++++++----------------------------- tests/test_registry.py | 29 ++++--------------- tests/test_subagent.py | 7 ++--- 3 files changed, 24 insertions(+), 73 deletions(-) diff --git a/koan/runners/registry.py b/koan/runners/registry.py index 23f11d1..dba45fa 100644 --- a/koan/runners/registry.py +++ b/koan/runners/registry.py @@ -3,8 +3,6 @@ from __future__ import annotations -import logging -import shutil from pathlib import Path from typing import TYPE_CHECKING @@ -113,51 +111,24 @@ def get_installation(self, runner_type: str, config: KoanConfig) -> AgentInstall )) def resolve_installation(self, runner_type: str, config: KoanConfig) -> AgentInstallation: - """Resolve a working installation for *runner_type* with fallback. + """Resolve a working installation for *runner_type*. - Priority: active installation -> any installation of same type -> PATH lookup. - Each candidate is validated by checking that its binary exists on disk. + Returns the installation after validating its binary exists on disk. + Raises RunnerError if the installation is missing or the binary is not found. """ - log = logging.getLogger("koan.registry") - - # 1. Try the active (or first) installation from config - try: - inst = self.get_installation(runner_type, config) - if Path(inst.binary).exists(): - return inst - log.warning( - "active %s installation '%s' binary missing (%s); trying alternatives", - runner_type, inst.alias, inst.binary, - ) - except RunnerError: - pass - - # 2. Try any other installation of this runner type - for inst in config.agent_installations: - if inst.runner_type == runner_type and Path(inst.binary).exists(): - log.info("falling back to %s installation '%s'", runner_type, inst.alias) - return inst - - # 3. Dynamic resolution from PATH - binary = shutil.which(runner_type) - if binary: - log.info("resolved %s from PATH: %s", runner_type, binary) - return AgentInstallation( - alias=f"{runner_type}-resolved", - runner_type=runner_type, - binary=binary, - ) - - raise RunnerError(RunnerDiagnostic( - code="no_installation", - runner=runner_type, - stage="resolve_installation", - message=( - f"No working {runner_type} installation found. " - f"Ensure '{runner_type}' is installed and on your PATH." - ), - details={"runner_type": runner_type}, - )) + inst = self.get_installation(runner_type, config) + if not Path(inst.binary).exists(): + raise RunnerError(RunnerDiagnostic( + code="binary_not_found", + runner=runner_type, + stage="resolve_installation", + message=( + f"Binary not found for {runner_type} installation '{inst.alias}': {inst.binary}. " + f"Update the installation in Settings or re-detect the binary." + ), + details={"runner_type": runner_type, "alias": inst.alias, "binary": inst.binary}, + )) + return inst def resolve_agent_config( self, diff --git a/tests/test_registry.py b/tests/test_registry.py index 85b64d4..f08732c 100644 --- a/tests/test_registry.py +++ b/tests/test_registry.py @@ -203,37 +203,18 @@ def test_returns_active_when_binary_exists(self, tmp_path): result = reg.resolve_installation("claude", config) assert result is inst - def test_falls_back_to_other_installation_when_active_binary_missing(self, tmp_path): - good_binary = tmp_path / "claude" - good_binary.touch() - bad = AgentInstallation(alias="broken", runner_type="claude", binary="/nonexistent/claude") - good = AgentInstallation(alias="working", runner_type="claude", binary=str(good_binary)) - config = self._make_config([bad, good], active={"claude": "broken"}) - reg = RunnerRegistry() - result = reg.resolve_installation("claude", config) - assert result is good - - def test_falls_back_to_which_when_all_binaries_missing(self, monkeypatch): + def test_raises_when_binary_missing(self): inst = AgentInstallation(alias="bad", runner_type="claude", binary="/nonexistent/claude") config = self._make_config([inst]) - monkeypatch.setattr("koan.runners.registry.shutil.which", lambda cmd: "/resolved/claude") - reg = RunnerRegistry() - result = reg.resolve_installation("claude", config) - assert result.binary == "/resolved/claude" - assert result.alias == "claude-resolved" - - def test_raises_when_nothing_works(self, monkeypatch): - inst = AgentInstallation(alias="bad", runner_type="claude", binary="/nonexistent/claude") - config = self._make_config([inst]) - monkeypatch.setattr("koan.runners.registry.shutil.which", lambda cmd: None) reg = RunnerRegistry() with pytest.raises(RunnerError) as exc_info: reg.resolve_installation("claude", config) - assert exc_info.value.diagnostic.code == "no_installation" + assert exc_info.value.diagnostic.code == "binary_not_found" + assert "bad" in exc_info.value.diagnostic.message + assert "/nonexistent/claude" in exc_info.value.diagnostic.message - def test_raises_when_no_installations_and_not_on_path(self, monkeypatch): + def test_raises_when_no_installations(self): config = self._make_config([]) - monkeypatch.setattr("koan.runners.registry.shutil.which", lambda cmd: None) reg = RunnerRegistry() with pytest.raises(RunnerError) as exc_info: reg.resolve_installation("claude", config) diff --git a/tests/test_subagent.py b/tests/test_subagent.py index d5f66c1..290a4d1 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -638,8 +638,7 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): "subagent_dir": subagent_dir, } - with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}), \ - patch("koan.runners.registry.shutil.which", return_value=None): + with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}): from koan.subagent import spawn_subagent exit_code = await spawn_subagent(task, app_state) @@ -650,7 +649,7 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): notifs = app_state.projection_store.projection.notifications spawn_fails = [n for n in notifs if n.get("type") == "agent_spawn_failed"] assert len(spawn_fails) >= 1 - assert spawn_fails[0]["error_code"] == "no_installation" + assert spawn_fails[0]["error_code"] == "binary_not_found" # Verify events.jsonl contains a runner_diagnostic events_path = Path(subagent_dir) / "events.jsonl" @@ -658,4 +657,4 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): lines = events_path.read_text().strip().split("\n") diag_events = [json.loads(l) for l in lines if "runner_diagnostic" in l] assert len(diag_events) >= 1 - assert diag_events[0]["code"] == "no_installation" + assert diag_events[0]["code"] == "binary_not_found" From 476f9e8347b1146a6b125d4bc201d244780a9571 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 12:16:11 +0700 Subject: [PATCH 212/412] add preflight endpoint and installation validation to start-run --- koan/web/app.py | 97 +++++++++++++++++++++++++++++++++++++++-- tests/test_web_flows.py | 86 ++++++++++++++++++++++++++++++++++++ 2 files changed, 180 insertions(+), 3 deletions(-) diff --git a/koan/web/app.py b/koan/web/app.py index 0527fcb..3c02e17 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -171,6 +171,60 @@ def _sse_event(event_type: str, payload: Any) -> str: return f"event: {event_type}\ndata: {data}\n\n" +def _resolve_profile(st: AppState, name: str) -> Profile | None: + """Look up a profile by name, including the computed balanced profile.""" + if name == "balanced": + return st.balanced_profile + for p in st.config.profiles: + if p.name == name: + return p + return None + + +async def api_start_run_preflight(r: Request) -> Response: + """Return required runner types and available installations for a profile.""" + profile_name = r.query_params.get("profile", "") + if not profile_name: + return JSONResponse( + {"error": "validation_error", "message": "profile query parameter is required"}, + status_code=422, + ) + + st = _app_state(r) + profile = _resolve_profile(st, profile_name) + if profile is None: + return JSONResponse( + {"error": "not_found", "message": f"Profile '{profile_name}' not found"}, + status_code=404, + ) + + # Derive required runner types from profile tiers + required_types: set[str] = set() + for tier in profile.tiers.values(): + required_types.add(tier.runner_type) + + # For each type, list available installations with validity status + installations_by_type: dict[str, list[dict]] = {} + for rt in sorted(required_types): + insts = [] + for inst in st.config.agent_installations: + if inst.runner_type == rt: + insts.append({ + "alias": inst.alias, + "binary": inst.binary, + "binary_valid": Path(inst.binary).exists(), + "is_active": st.config.active_installations.get(rt) == inst.alias, + "extra_args": inst.extra_args, + }) + installations_by_type[rt] = insts + + return JSONResponse({ + "profile": profile_name, + "required_runner_types": sorted(required_types), + "installations": installations_by_type, + }) + + async def api_start_run(r: Request) -> Response: body = await r.json() task = body.get("task", "") @@ -198,13 +252,50 @@ async def api_start_run(r: Request) -> Response: ) # Validate profile exists - if profile != "balanced" and not any(p.name == profile for p in st.config.profiles): + profile_obj = _resolve_profile(st, profile) + if profile_obj is None: return JSONResponse( {"error": "validation_error", "message": f"profile '{profile}' not found"}, status_code=422, ) - # Persist profile selection + # Apply installation selections (runner_type -> alias) + installations = body.get("installations") + if isinstance(installations, dict): + for rt, alias in installations.items(): + found = any( + inst.alias == alias and inst.runner_type == rt + for inst in st.config.agent_installations + ) + if not found: + return JSONResponse( + {"error": "validation_error", + "message": f"Installation '{alias}' not found for runner type '{rt}'"}, + status_code=422, + ) + for rt, alias in installations.items(): + st.config.active_installations[rt] = alias + + # Pre-validate installations for every runner type the profile requires + from ..runners.registry import RunnerRegistry + from ..runners.base import RunnerError + registry = RunnerRegistry() + checked_types: set[str] = set() + for tier in profile_obj.tiers.values(): + if tier.runner_type in checked_types: + continue + checked_types.add(tier.runner_type) + try: + registry.resolve_installation(tier.runner_type, st.config) + except RunnerError as e: + return JSONResponse( + {"error": e.diagnostic.code, + "message": e.diagnostic.message, + "runner_type": tier.runner_type}, + status_code=422, + ) + + # Persist profile + installation selections st.config.active_profile = profile from ..config import save_koan_config await save_koan_config(st.config) @@ -213,7 +304,6 @@ async def api_start_run(r: Request) -> Response: scout_concurrency = body.get("scout_concurrency") if isinstance(scout_concurrency, int) and scout_concurrency > 0: st.config.scout_concurrency = scout_concurrency - from ..config import save_koan_config await save_koan_config(st.config) # Create epic directory @@ -874,6 +964,7 @@ async def _open_browser(): routes = [ Mount("/mcp", app=mcp_app), Route("/api/start-run", api_start_run, methods=["POST"]), + Route("/api/start-run/preflight", api_start_run_preflight, methods=["GET"]), Route("/api/answer", api_answer, methods=["POST"]), Route("/api/artifact-review", api_artifact_review, methods=["POST"]), Route("/api/workflow-decision", api_workflow_decision, methods=["POST"]), diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index 1093d2f..bf85f87 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -125,6 +125,92 @@ def test_start_run_persists_profile(client, app_state): assert app_state.config.active_profile == "balanced" +# -- Start-run preflight ------------------------------------------------------- + +def test_preflight_returns_required_types(client, app_state): + from koan.runners.registry import compute_balanced_profile + app_state.probe_results = _make_probe_results() + app_state.balanced_profile = compute_balanced_profile(app_state.probe_results) + resp = client.get("/api/start-run/preflight?profile=balanced") + assert resp.status_code == 200 + data = resp.json() + assert "claude" in data["required_runner_types"] + assert "claude" in data["installations"] + + +def test_preflight_shows_binary_validity(client, app_state, tmp_path): + from koan.runners.registry import compute_balanced_profile + app_state.probe_results = _make_probe_results() + app_state.balanced_profile = compute_balanced_profile(app_state.probe_results) + real_binary = tmp_path / "claude" + real_binary.touch() + app_state.config.agent_installations = [ + AgentInstallation(alias="good", runner_type="claude", binary=str(real_binary)), + AgentInstallation(alias="bad", runner_type="claude", binary="/nonexistent/claude"), + ] + resp = client.get("/api/start-run/preflight?profile=balanced") + data = resp.json() + insts = data["installations"]["claude"] + good = next(i for i in insts if i["alias"] == "good") + bad = next(i for i in insts if i["alias"] == "bad") + assert good["binary_valid"] is True + assert bad["binary_valid"] is False + + +def test_preflight_missing_profile(client, app_state): + resp = client.get("/api/start-run/preflight?profile=nonexistent") + assert resp.status_code == 404 + + +# -- Start-run installation validation ----------------------------------------- + +def test_start_run_accepts_installation_selection(client, app_state, tmp_path): + from koan.runners.registry import compute_balanced_profile + app_state.probe_results = _make_probe_results() + app_state.balanced_profile = compute_balanced_profile(app_state.probe_results) + binary = tmp_path / "claude" + binary.touch() + app_state.config.agent_installations = [ + AgentInstallation(alias="my-claude", runner_type="claude", binary=str(binary)), + ] + resp = client.post("/api/start-run", json={ + "task": "build something", + "profile": "balanced", + "installations": {"claude": "my-claude"}, + }) + assert resp.status_code == 200 + assert app_state.config.active_installations["claude"] == "my-claude" + + +def test_start_run_rejects_missing_binary(client, app_state): + from koan.runners.registry import compute_balanced_profile + app_state.probe_results = _make_probe_results() + app_state.balanced_profile = compute_balanced_profile(app_state.probe_results) + app_state.config.agent_installations = [ + AgentInstallation(alias="broken", runner_type="claude", binary="/nonexistent/claude"), + ] + app_state.config.active_installations = {"claude": "broken"} + resp = client.post("/api/start-run", json={ + "task": "build something", + "profile": "balanced", + }) + assert resp.status_code == 422 + data = resp.json() + assert data["error"] == "binary_not_found" + assert "claude" in data["runner_type"] + + +def test_start_run_rejects_unknown_installation_alias(client, app_state): + app_state.probe_results = _make_probe_results() + resp = client.post("/api/start-run", json={ + "task": "build something", + "profile": "balanced", + "installations": {"claude": "ghost"}, + }) + assert resp.status_code == 422 + assert "ghost" in resp.json()["message"] + + # -- Artifacts ---------------------------------------------------------------- def test_artifact_listing(client, app_state): From 93ea2c036aa0be72a42a9c88355c6f8bc592a7cc Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 12:16:24 +0700 Subject: [PATCH 213/412] add installation selector to landing page driven by profile selection --- frontend/src/api/client.ts | 24 +++++++ frontend/src/components/LandingPage.tsx | 89 ++++++++++++++++++++++++- 2 files changed, 111 insertions(+), 2 deletions(-) diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 0ea3d93..5423d62 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -43,14 +43,38 @@ export async function startRun( task: string, profile: string, scoutConcurrency?: number, + installations?: Record, ): Promise { const body: Record = { task, profile } if (scoutConcurrency !== undefined) { body['scout_concurrency'] = scoutConcurrency } + if (installations && Object.keys(installations).length > 0) { + body['installations'] = installations + } return post('/api/start-run', body) } +// -- Start-run preflight ----------------------------------------------------- + +export interface PreflightInstallation { + alias: string + binary: string + binary_valid: boolean + is_active: boolean + extra_args: string[] +} + +export interface StartRunPreflight { + profile: string + required_runner_types: string[] + installations: Record +} + +export async function getStartRunPreflight(profile: string): Promise { + return get(`/api/start-run/preflight?profile=${encodeURIComponent(profile)}`) +} + // -- Interactions ------------------------------------------------------------ export async function submitAnswer(answers: unknown[], token: string) { diff --git a/frontend/src/components/LandingPage.tsx b/frontend/src/components/LandingPage.tsx index 4739ead..4b56a7c 100644 --- a/frontend/src/components/LandingPage.tsx +++ b/frontend/src/components/LandingPage.tsx @@ -11,6 +11,11 @@ export function LandingPage() { const [loading, setLoading] = useState(false) const [error, setError] = useState(null) + // Installation selection driven by profile + const [preflight, setPreflight] = useState(null) + const [preflightLoading, setPreflightLoading] = useState(false) + const [selectedInstallations, setSelectedInstallations] = useState>({}) + useEffect(() => { Promise.all([api.getProfiles(), api.getProbe(), api.getInitialPrompt()]).then( ([profilesData, probeData, promptData]) => { @@ -26,6 +31,37 @@ export function LandingPage() { ) }, []) + // Fetch preflight when profile changes + useEffect(() => { + if (!profile) { + setPreflight(null) + setSelectedInstallations({}) + return + } + setPreflightLoading(true) + api.getStartRunPreflight(profile).then(data => { + setPreflight(data) + // Auto-select: prefer the active installation if valid, else first valid + const selections: Record = {} + for (const [rt, insts] of Object.entries(data.installations)) { + const active = insts.find(i => i.is_active && i.binary_valid) + const firstValid = insts.find(i => i.binary_valid) + if (active) selections[rt] = active.alias + else if (firstValid) selections[rt] = firstValid.alias + } + setSelectedInstallations(selections) + setPreflightLoading(false) + }).catch(() => { + setPreflight(null) + setPreflightLoading(false) + }) + }, [profile]) + + // All required runner types must have a selected installation + const installationsReady = preflight + ? preflight.required_runner_types.every(rt => selectedInstallations[rt]) + : false + const handleStart = async () => { const trimmedTask = task.trim() if (!trimmedTask) { @@ -36,10 +72,16 @@ export function LandingPage() { setError('Please select a profile') return } + if (!installationsReady) { + setError('Please select an installation for each required runner type') + return + } setError(null) setLoading(true) try { - const result = await api.startRun(trimmedTask, profile, scoutConcurrency) + const result = await api.startRun( + trimmedTask, profile, scoutConcurrency, selectedInstallations, + ) if (!result.ok) { setError(result.message ?? 'Failed to start run') } @@ -86,6 +128,49 @@ export function LandingPage() {
+ {preflight && !preflightLoading && preflight.required_runner_types.length > 0 && ( +
+

Agent Installations

+ {preflight.required_runner_types.map(rt => { + const insts = preflight.installations[rt] || [] + const selected = selectedInstallations[rt] || '' + const hasNoValid = insts.length > 0 && !insts.some(i => i.binary_valid) + return ( +
+ {rt} + + {insts.length === 0 && ( + + No installations. Add one in Settings. + + )} + {hasNoValid && ( + + All binaries missing. Update paths in Settings. + + )} +
+ ) + })} +
+ )} +

Scout Concurrency

Date: Tue, 31 Mar 2026 13:44:08 +0700 Subject: [PATCH 214/412] add granular config event types to projection system and event builders --- koan/events.py | 56 +++++++++++++++++ koan/projections.py | 125 ++++++++++++++++++++++++++++++++++++++ tests/test_projections.py | 98 ++++++++++++++++++++++++++++++ 3 files changed, 279 insertions(+) diff --git a/koan/events.py b/koan/events.py index dc64114..8c3caff 100644 --- a/koan/events.py +++ b/koan/events.py @@ -174,3 +174,59 @@ def build_workflow_decided( if decision is not None: result["decision"] = decision return result + + +# -- Configuration event builders --------------------------------------------- + +def build_probe_completed(runners: list[dict]) -> dict: + return {"runners": runners} + + +def build_installation_created( + alias: str, runner_type: str, binary: str, extra_args: list[str], +) -> dict: + return { + "alias": alias, + "runner_type": runner_type, + "binary": binary, + "extra_args": extra_args, + } + + +def build_installation_modified( + alias: str, runner_type: str, binary: str, extra_args: list[str], +) -> dict: + return { + "alias": alias, + "runner_type": runner_type, + "binary": binary, + "extra_args": extra_args, + } + + +def build_installation_removed(alias: str) -> dict: + return {"alias": alias} + + +def build_profile_created(name: str, read_only: bool, tiers: dict) -> dict: + return {"name": name, "read_only": read_only, "tiers": tiers} + + +def build_profile_modified(name: str, read_only: bool, tiers: dict) -> dict: + return {"name": name, "read_only": read_only, "tiers": tiers} + + +def build_profile_removed(name: str) -> dict: + return {"name": name} + + +def build_active_profile_changed(name: str) -> dict: + return {"name": name} + + +def build_active_installation_changed(runner_type: str, alias: str) -> dict: + return {"runner_type": runner_type, "alias": alias} + + +def build_scout_concurrency_changed(value: int) -> dict: + return {"value": value} diff --git a/koan/projections.py b/koan/projections.py index 71fec03..1737d1c 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -37,6 +37,17 @@ "artifact_created", "artifact_modified", "artifact_removed", + # Configuration + "probe_completed", + "installation_created", + "installation_modified", + "installation_removed", + "profile_created", + "profile_modified", + "profile_removed", + "active_profile_changed", + "active_installation_changed", + "scout_concurrency_changed", ] @@ -83,6 +94,14 @@ class Projection(BaseModel): # Completion completion: dict | None = None + # Configuration + config_runners: list[dict] = Field(default_factory=list) + config_profiles: list[dict] = Field(default_factory=list) + config_installations: list[dict] = Field(default_factory=list) + config_active_installations: dict[str, str] = Field(default_factory=dict) + config_active_profile: str = "balanced" + config_scout_concurrency: int = 8 + def _utcnow() -> str: return datetime.now(timezone.utc).isoformat() @@ -299,6 +318,112 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: new_artifacts = {k: v for k, v in projection.artifacts.items() if k != path} return projection.model_copy(update={"artifacts": new_artifacts}) + # ── Configuration ────────────────────────────────────────────────── + + case "probe_completed": + return projection.model_copy(update={ + "config_runners": payload.get("runners", []), + }) + + case "installation_created": + new_inst = { + "alias": payload.get("alias", ""), + "runner_type": payload.get("runner_type", ""), + "binary": payload.get("binary", ""), + "extra_args": payload.get("extra_args", []), + } + return projection.model_copy(update={ + "config_installations": [*projection.config_installations, new_inst], + }) + + case "installation_modified": + alias = payload.get("alias", "") + updated_inst = { + "alias": alias, + "runner_type": payload.get("runner_type", ""), + "binary": payload.get("binary", ""), + "extra_args": payload.get("extra_args", []), + } + new_insts = [ + updated_inst if inst.get("alias") == alias else inst + for inst in projection.config_installations + ] + return projection.model_copy(update={"config_installations": new_insts}) + + case "installation_removed": + alias = payload.get("alias", "") + # Find runner_type before removing (needed to clean active_installations) + removed_rt = next( + (inst.get("runner_type") for inst in projection.config_installations + if inst.get("alias") == alias), + None, + ) + new_insts = [ + inst for inst in projection.config_installations + if inst.get("alias") != alias + ] + new_active = dict(projection.config_active_installations) + if removed_rt and new_active.get(removed_rt) == alias: + del new_active[removed_rt] + return projection.model_copy(update={ + "config_installations": new_insts, + "config_active_installations": new_active, + }) + + case "profile_created": + new_profile = { + "name": payload.get("name", ""), + "read_only": payload.get("read_only", False), + "tiers": payload.get("tiers", {}), + } + return projection.model_copy(update={ + "config_profiles": [*projection.config_profiles, new_profile], + }) + + case "profile_modified": + name = payload.get("name", "") + updated_profile = { + "name": name, + "read_only": payload.get("read_only", False), + "tiers": payload.get("tiers", {}), + } + if any(p.get("name") == name for p in projection.config_profiles): + new_profiles = [ + updated_profile if p.get("name") == name else p + for p in projection.config_profiles + ] + else: + # First time (e.g. balanced on startup) + new_profiles = [*projection.config_profiles, updated_profile] + return projection.model_copy(update={"config_profiles": new_profiles}) + + case "profile_removed": + name = payload.get("name", "") + new_profiles = [ + p for p in projection.config_profiles if p.get("name") != name + ] + return projection.model_copy(update={"config_profiles": new_profiles}) + + case "active_profile_changed": + return projection.model_copy(update={ + "config_active_profile": payload.get("name", "balanced"), + }) + + case "active_installation_changed": + new_active = dict(projection.config_active_installations) + rt = payload.get("runner_type", "") + alias = payload.get("alias", "") + if rt: + new_active[rt] = alias + return projection.model_copy(update={ + "config_active_installations": new_active, + }) + + case "scout_concurrency_changed": + return projection.model_copy(update={ + "config_scout_concurrency": payload.get("value", 8), + }) + case _: log.warning("fold: unknown event_type=%r", event_type) return projection diff --git a/tests/test_projections.py b/tests/test_projections.py index 7be0a83..a84cb87 100644 --- a/tests/test_projections.py +++ b/tests/test_projections.py @@ -531,3 +531,101 @@ def test_spawn_failed_after_spawned_leaves_dangling_primary(self): assert store.projection.primary_agent is not None # known bad state # In production, this can't happen: subagent.py now emits agent_spawned only # after build_command succeeds (just before create_subprocess_exec). + + +# -- fold: configuration events ----------------------------------------------- + +class TestConfigEvents: + def _e(self, event_type: str, payload: dict) -> VersionedEvent: + return VersionedEvent(version=1, event_type=event_type, timestamp="t", payload=payload) + + def test_probe_completed_sets_runners(self): + p = Projection() + runners = [{"runner_type": "claude", "available": True}] + p2 = fold(p, self._e("probe_completed", {"runners": runners})) + assert p2.config_runners == runners + + def test_installation_created_appends(self): + p = Projection() + inst = {"alias": "claude-default", "runner_type": "claude", "binary": "/usr/bin/claude", "extra_args": []} + p2 = fold(p, self._e("installation_created", inst)) + assert len(p2.config_installations) == 1 + assert p2.config_installations[0]["alias"] == "claude-default" + + def test_installation_modified_replaces(self): + inst = {"alias": "my-claude", "runner_type": "claude", "binary": "/old/claude", "extra_args": []} + p = Projection(config_installations=[inst]) + updated = {"alias": "my-claude", "runner_type": "claude", "binary": "/new/claude", "extra_args": []} + p2 = fold(p, self._e("installation_modified", updated)) + assert len(p2.config_installations) == 1 + assert p2.config_installations[0]["binary"] == "/new/claude" + + def test_installation_removed_removes_and_cleans_active(self): + inst = {"alias": "my-claude", "runner_type": "claude", "binary": "/usr/bin/claude", "extra_args": []} + p = Projection( + config_installations=[inst], + config_active_installations={"claude": "my-claude"}, + ) + p2 = fold(p, self._e("installation_removed", {"alias": "my-claude"})) + assert p2.config_installations == [] + assert "claude" not in p2.config_active_installations + + def test_installation_removed_does_not_clean_unrelated_active(self): + inst = {"alias": "my-claude", "runner_type": "claude", "binary": "/usr/bin/claude", "extra_args": []} + p = Projection( + config_installations=[inst], + config_active_installations={"claude": "other-claude"}, + ) + p2 = fold(p, self._e("installation_removed", {"alias": "my-claude"})) + assert p2.config_active_installations == {"claude": "other-claude"} + + def test_profile_created_appends(self): + p = Projection() + profile = {"name": "fast", "read_only": False, "tiers": {}} + p2 = fold(p, self._e("profile_created", profile)) + assert len(p2.config_profiles) == 1 + assert p2.config_profiles[0]["name"] == "fast" + + def test_profile_modified_replaces(self): + profile = {"name": "fast", "read_only": False, "tiers": {"strong": {"runner_type": "claude"}}} + p = Projection(config_profiles=[profile]) + updated = {"name": "fast", "read_only": False, "tiers": {"strong": {"runner_type": "codex"}}} + p2 = fold(p, self._e("profile_modified", updated)) + assert len(p2.config_profiles) == 1 + assert p2.config_profiles[0]["tiers"]["strong"]["runner_type"] == "codex" + + def test_profile_modified_appends_when_not_found(self): + p = Projection() + balanced = {"name": "balanced", "read_only": True, "tiers": {}} + p2 = fold(p, self._e("profile_modified", balanced)) + assert len(p2.config_profiles) == 1 + assert p2.config_profiles[0]["name"] == "balanced" + + def test_profile_removed(self): + p = Projection(config_profiles=[ + {"name": "fast", "read_only": False, "tiers": {}}, + {"name": "slow", "read_only": False, "tiers": {}}, + ]) + p2 = fold(p, self._e("profile_removed", {"name": "fast"})) + assert len(p2.config_profiles) == 1 + assert p2.config_profiles[0]["name"] == "slow" + + def test_active_profile_changed(self): + p = Projection() + p2 = fold(p, self._e("active_profile_changed", {"name": "fast"})) + assert p2.config_active_profile == "fast" + + def test_active_installation_changed(self): + p = Projection() + p2 = fold(p, self._e("active_installation_changed", {"runner_type": "claude", "alias": "my-claude"})) + assert p2.config_active_installations == {"claude": "my-claude"} + + def test_active_installation_changed_updates_existing(self): + p = Projection(config_active_installations={"claude": "old", "codex": "codex-default"}) + p2 = fold(p, self._e("active_installation_changed", {"runner_type": "claude", "alias": "new"})) + assert p2.config_active_installations == {"claude": "new", "codex": "codex-default"} + + def test_scout_concurrency_changed(self): + p = Projection() + p2 = fold(p, self._e("scout_concurrency_changed", {"value": 16})) + assert p2.config_scout_concurrency == 16 From 605eebe2f81ae7e68e7acdca22a7e5ee06a029e7 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 13:47:27 +0700 Subject: [PATCH 215/412] emit config events from all settings endpoints and lifespan --- koan/web/app.py | 119 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 111 insertions(+), 8 deletions(-) diff --git a/koan/web/app.py b/koan/web/app.py index 3c02e17..22e01cd 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -29,6 +29,16 @@ build_artifact_reviewed, build_questions_answered, build_workflow_decided, + build_probe_completed, + build_installation_created, + build_installation_modified, + build_installation_removed, + build_profile_created, + build_profile_modified, + build_profile_removed, + build_active_profile_changed, + build_active_installation_changed, + build_scout_concurrency_changed, ) if TYPE_CHECKING: @@ -299,12 +309,19 @@ async def api_start_run(r: Request) -> Response: st.config.active_profile = profile from ..config import save_koan_config await save_koan_config(st.config) + st.projection_store.push_event("active_profile_changed", build_active_profile_changed(profile)) + if isinstance(installations, dict): + for rt, alias in installations.items(): + st.projection_store.push_event( + "active_installation_changed", build_active_installation_changed(rt, alias), + ) # Apply optional overrides scout_concurrency = body.get("scout_concurrency") if isinstance(scout_concurrency, int) and scout_concurrency > 0: st.config.scout_concurrency = scout_concurrency await save_koan_config(st.config) + st.projection_store.push_event("scout_concurrency_changed", build_scout_concurrency_changed(scout_concurrency)) # Create epic directory epic_id = f"{int(time.time())}-{uuid.uuid4().hex[:8]}" @@ -500,7 +517,7 @@ def _serialize_profile(p: Profile, read_only: bool) -> dict: } -async def _refresh_probe_state(st: AppState) -> None: +async def _refresh_probe_state(st: AppState, broadcast: bool = True) -> None: from ..probe import probe_all_runners from ..runners.registry import compute_balanced_profile @@ -510,27 +527,89 @@ async def _refresh_probe_state(st: AppState) -> None: # Auto-create or update default installations from probe results existing_types = {inst.runner_type for inst in st.config.agent_installations} changed = False + new_insts: list[AgentInstallation] = [] + modified_insts: list[AgentInstallation] = [] for pr in st.probe_results: if pr.available and pr.binary_path: if pr.runner_type not in existing_types: - st.config.agent_installations.append(AgentInstallation( + inst = AgentInstallation( alias=f"{pr.runner_type}-default", runner_type=pr.runner_type, binary=pr.binary_path, extra_args=[], - )) + ) + st.config.agent_installations.append(inst) + new_insts.append(inst) changed = True else: - # Refresh binary path for auto-created default installations for inst in st.config.agent_installations: if inst.runner_type == pr.runner_type and inst.alias == f"{pr.runner_type}-default": if inst.binary != pr.binary_path: inst.binary = pr.binary_path + modified_insts.append(inst) changed = True if changed: from ..config import save_koan_config await save_koan_config(st.config) + if broadcast: + runners = [_serialize_probe_result(pr) for pr in st.probe_results] + st.projection_store.push_event("probe_completed", build_probe_completed(runners)) + if st.balanced_profile: + tiers = _serialize_profile(st.balanced_profile, True)["tiers"] + st.projection_store.push_event( + "profile_modified", + build_profile_modified("balanced", True, tiers), + ) + for inst in new_insts: + st.projection_store.push_event( + "installation_created", + build_installation_created(inst.alias, inst.runner_type, inst.binary, inst.extra_args), + ) + for inst in modified_insts: + st.projection_store.push_event( + "installation_modified", + build_installation_modified(inst.alias, inst.runner_type, inst.binary, inst.extra_args), + ) + + +def _push_initial_config_events(st: AppState) -> None: + """Push full config state into the projection on startup. + + Called after _refresh_probe_state(broadcast=False) so all state is ready. + Emits one event per config fact so the snapshot captures complete config. + """ + store = st.projection_store + + # Runners from probe + runners = [_serialize_probe_result(pr) for pr in st.probe_results] + store.push_event("probe_completed", build_probe_completed(runners)) + + # Profiles (balanced first, then user-defined) + if st.balanced_profile: + tiers = _serialize_profile(st.balanced_profile, True)["tiers"] + store.push_event("profile_created", build_profile_created("balanced", True, tiers)) + for p in st.config.profiles: + sp = _serialize_profile(p, False) + store.push_event("profile_created", build_profile_created(p.name, False, sp["tiers"])) + + # Installations + for inst in st.config.agent_installations: + store.push_event( + "installation_created", + build_installation_created(inst.alias, inst.runner_type, inst.binary, inst.extra_args), + ) + + # Active installation selections + for rt, alias in st.config.active_installations.items(): + store.push_event("active_installation_changed", build_active_installation_changed(rt, alias)) + + # Active profile + store.push_event("active_profile_changed", build_active_profile_changed(st.config.active_profile)) + + # Scout concurrency + store.push_event("scout_concurrency_changed", build_scout_concurrency_changed(st.config.scout_concurrency)) + async def api_probe(r: Request) -> Response: st = _app_state(r) @@ -593,9 +672,12 @@ async def api_profiles_create(r: Request) -> Response: thinking=tier_val.get("thinking", "disabled"), ) - st.config.profiles.append(Profile(name=name, tiers=tiers)) + new_profile = Profile(name=name, tiers=tiers) + st.config.profiles.append(new_profile) from ..config import save_koan_config await save_koan_config(st.config) + sp = _serialize_profile(new_profile, False) + st.projection_store.push_event("profile_created", build_profile_created(name, False, sp["tiers"])) return JSONResponse({"ok": True}) @@ -638,6 +720,8 @@ async def api_profiles_update(r: Request) -> Response: from ..config import save_koan_config await save_koan_config(st.config) + sp = _serialize_profile(target, False) + st.projection_store.push_event("profile_modified", build_profile_modified(name, False, sp["tiers"])) return JSONResponse({"ok": True}) @@ -659,11 +743,15 @@ async def api_profiles_delete(r: Request) -> Response: return JSONResponse({"error": "not_found", "message": f"profile '{name}' not found"}, status_code=404) st.config.profiles.pop(idx) - if st.config.active_profile == name: + reset_active = st.config.active_profile == name + if reset_active: st.config.active_profile = "balanced" from ..config import save_koan_config await save_koan_config(st.config) + st.projection_store.push_event("profile_removed", build_profile_removed(name)) + if reset_active: + st.projection_store.push_event("active_profile_changed", build_active_profile_changed("balanced")) return JSONResponse({"ok": True}) @@ -719,12 +807,17 @@ async def api_agents_create(r: Request) -> Response: if not isinstance(extra_args, list): extra_args = [] + clean_args = [str(a) for a in extra_args] st.config.agent_installations.append(AgentInstallation( alias=alias, runner_type=runner_type, binary=binary, - extra_args=[str(a) for a in extra_args], + extra_args=clean_args, )) from ..config import save_koan_config await save_koan_config(st.config) + st.projection_store.push_event( + "installation_created", + build_installation_created(alias, runner_type, binary, clean_args), + ) return JSONResponse({"ok": True}) @@ -750,6 +843,10 @@ async def api_agents_update(r: Request) -> Response: from ..config import save_koan_config await save_koan_config(st.config) + st.projection_store.push_event( + "installation_modified", + build_installation_modified(target.alias, target.runner_type, target.binary, target.extra_args), + ) return JSONResponse({"ok": True}) @@ -772,6 +869,7 @@ async def api_agents_delete(r: Request) -> Response: from ..config import save_koan_config await save_koan_config(st.config) + st.projection_store.push_event("installation_removed", build_installation_removed(alias)) return JSONResponse({"ok": True}) @@ -801,6 +899,9 @@ async def api_agents_set_active(r: Request) -> Response: st.config.active_installations[runner_type] = alias from ..config import save_koan_config await save_koan_config(st.config) + st.projection_store.push_event( + "active_installation_changed", build_active_installation_changed(runner_type, alias), + ) return JSONResponse({"ok": True}) @@ -913,6 +1014,7 @@ async def api_settings_scout_concurrency(r: Request) -> Response: st.config.scout_concurrency = value from ..config import save_koan_config await save_koan_config(st.config) + st.projection_store.push_event("scout_concurrency_changed", build_scout_concurrency_changed(value)) return JSONResponse({"ok": True}) @@ -941,7 +1043,8 @@ def create_app(app_state: AppState) -> Starlette: @asynccontextmanager async def lifespan(app): from ..driver import driver_main - await _refresh_probe_state(app_state) + await _refresh_probe_state(app_state, broadcast=False) + _push_initial_config_events(app_state) asyncio.create_task(driver_main(app_state)) From 7121428e88e045a776bea36044e2812dce383e30 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 13:47:35 +0700 Subject: [PATCH 216/412] add config event fold cases and snapshot extraction to frontend store --- frontend/src/sse/connect.ts | 10 +++ frontend/src/store/index.ts | 130 ++++++++++++++++++++++++++++++++++++ 2 files changed, 140 insertions(+) diff --git a/frontend/src/sse/connect.ts b/frontend/src/sse/connect.ts index c9fb9b7..63d9bbd 100644 --- a/frontend/src/sse/connect.ts +++ b/frontend/src/sse/connect.ts @@ -36,13 +36,23 @@ export function connectSSE(store: KoanStore): EventSource { // ── All other events: incremental fold ──────────────────────────────── const KNOWN_EVENTS = [ + // Lifecycle 'phase_started', 'agent_spawned', 'agent_spawn_failed', 'agent_step_advanced', 'agent_exited', 'workflow_completed', + // Activity 'tool_called', 'tool_completed', 'thinking', 'stream_delta', 'stream_cleared', + // Interactions 'questions_asked', 'questions_answered', 'artifact_review_requested', 'artifact_reviewed', 'workflow_decision_requested', 'workflow_decided', + // Resources 'artifact_created', 'artifact_modified', 'artifact_removed', + // Configuration + 'probe_completed', + 'installation_created', 'installation_modified', 'installation_removed', + 'profile_created', 'profile_modified', 'profile_removed', + 'active_profile_changed', 'active_installation_changed', + 'scout_concurrency_changed', ] for (const eventType of KNOWN_EVENTS) { diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 11d223c..55942d9 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -1,4 +1,5 @@ import { create } from 'zustand' +import type { RunnerInfo } from '../api/client' export const ALL_PHASES = [ 'intake', 'brief-generation', 'core-flows', 'tech-plan', @@ -178,6 +179,14 @@ interface KoanState { profiles: Profile[] installations: Installation[] + // Configuration — sourced from projection events, always up to date + configProfiles: Profile[] + configInstallations: Installation[] + configActiveInstallations: Record + configActiveProfile: string + configScoutConcurrency: number + configRunners: RunnerInfo[] + // Legacy actions (used by existing components) setConnected: (v: boolean) => void setPhase: (phase: string) => void @@ -225,6 +234,14 @@ export const useStore = create((set) => ({ profiles: [], installations: [], + // Configuration defaults + configProfiles: [], + configInstallations: [], + configActiveInstallations: {}, + configActiveProfile: 'balanced', + configScoutConcurrency: 8, + configRunners: [], + setConnected: (v) => set({ connected: v }), setFatalError: (v) => set({ fatalError: v }), @@ -336,6 +353,20 @@ export const useStore = create((set) => ({ const completion = state['completion'] as CompletionInfo | null + // Transform config fields + const configProfiles: Profile[] = ((state['config_profiles'] ?? []) as Record[]).map(p => ({ + name: p['name'] as string, + read_only: (p['read_only'] as boolean) ?? false, + tiers: (p['tiers'] as Record) ?? {}, + })) + + const configInstallations: Installation[] = ((state['config_installations'] ?? []) as Record[]).map(i => ({ + alias: i['alias'] as string, + runner_type: i['runner_type'] as string, + binary: i['binary'] as string, + extra_args: (i['extra_args'] as string[]) ?? [], + })) + set({ lastVersion: version, phase, @@ -351,6 +382,13 @@ export const useStore = create((set) => ({ streamBuffer: (state['stream_buffer'] as string) ?? '', isThinking: false, completion: completion ?? null, + // Configuration + configProfiles, + configInstallations, + configActiveInstallations: (state['config_active_installations'] ?? {}) as Record, + configActiveProfile: (state['config_active_profile'] as string) ?? 'balanced', + configScoutConcurrency: (state['config_scout_concurrency'] as number) ?? 8, + configRunners: (state['config_runners'] ?? []) as RunnerInfo[], }) }, @@ -559,6 +597,98 @@ export const useStore = create((set) => ({ return { ...base, artifacts: rest } } + // ── Configuration ────────────────────────────────────────────────── + + case 'probe_completed': { + return { ...base, configRunners: (event['runners'] as RunnerInfo[]) ?? [] } + } + + case 'installation_created': { + const inst: Installation = { + alias: event['alias'] as string, + runner_type: event['runner_type'] as string, + binary: event['binary'] as string, + extra_args: (event['extra_args'] as string[]) ?? [], + } + return { ...base, configInstallations: [...s.configInstallations, inst] } + } + + case 'installation_modified': { + const alias = event['alias'] as string + const updated: Installation = { + alias, + runner_type: event['runner_type'] as string, + binary: event['binary'] as string, + extra_args: (event['extra_args'] as string[]) ?? [], + } + return { + ...base, + configInstallations: s.configInstallations.map(i => + i.alias === alias ? updated : i + ), + } + } + + case 'installation_removed': { + const alias = event['alias'] as string + const newInsts = s.configInstallations.filter(i => i.alias !== alias) + const newActive = { ...s.configActiveInstallations } + for (const [rt, a] of Object.entries(newActive)) { + if (a === alias) delete newActive[rt] + } + return { ...base, configInstallations: newInsts, configActiveInstallations: newActive } + } + + case 'profile_created': { + const profile: Profile = { + name: event['name'] as string, + read_only: (event['read_only'] as boolean) ?? false, + tiers: (event['tiers'] as Record) ?? {}, + } + return { ...base, configProfiles: [...s.configProfiles, profile] } + } + + case 'profile_modified': { + const name = event['name'] as string + const updated: Profile = { + name, + read_only: (event['read_only'] as boolean) ?? false, + tiers: (event['tiers'] as Record) ?? {}, + } + const exists = s.configProfiles.some(p => p.name === name) + return { + ...base, + configProfiles: exists + ? s.configProfiles.map(p => p.name === name ? updated : p) + : [...s.configProfiles, updated], + } + } + + case 'profile_removed': { + const name = event['name'] as string + return { + ...base, + configProfiles: s.configProfiles.filter(p => p.name !== name), + } + } + + case 'active_profile_changed': { + return { ...base, configActiveProfile: (event['name'] as string) ?? 'balanced' } + } + + case 'active_installation_changed': { + const rt = event['runner_type'] as string + const alias = event['alias'] as string + return { + ...base, + configActiveInstallations: { ...s.configActiveInstallations, [rt]: alias }, + } + } + + case 'scout_concurrency_changed': { + return { ...base, configScoutConcurrency: (event['value'] as number) ?? 8 } + } + default: return base } From 68a159caf4bccb38df73d5f6a6493b14243e3153 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 14:16:07 +0700 Subject: [PATCH 217/412] rewrite settings and landing page to read from projection store instead of API fetches --- frontend/src/components/LandingPage.tsx | 130 +++--- frontend/src/components/SettingsOverlay.tsx | 476 +++++++++----------- 2 files changed, 285 insertions(+), 321 deletions(-) diff --git a/frontend/src/components/LandingPage.tsx b/frontend/src/components/LandingPage.tsx index 4b56a7c..7eed2a2 100644 --- a/frontend/src/components/LandingPage.tsx +++ b/frontend/src/components/LandingPage.tsx @@ -1,63 +1,92 @@ -import { useState, useEffect } from 'react' -import { Profile } from '../store/index' +import { useState, useEffect, useMemo } from 'react' +import { useStore } from '../store/index' import * as api from '../api/client' export function LandingPage() { const [task, setTask] = useState('') const [profile, setProfile] = useState('') const [scoutConcurrency, setScoutConcurrency] = useState(8) - const [profiles, setProfiles] = useState([]) - const [hasRunners, setHasRunners] = useState(false) const [loading, setLoading] = useState(false) const [error, setError] = useState(null) - - // Installation selection driven by profile - const [preflight, setPreflight] = useState(null) - const [preflightLoading, setPreflightLoading] = useState(false) const [selectedInstallations, setSelectedInstallations] = useState>({}) + // Read from store (fed by SSE — always current, no API fetch needed) + const profiles = useStore(s => s.configProfiles) + const installations = useStore(s => s.configInstallations) + const activeInstallations = useStore(s => s.configActiveInstallations) + const runners = useStore(s => s.configRunners) + const storeScoutConcurrency = useStore(s => s.configScoutConcurrency) + + const hasRunners = runners.some(r => r.available) + + // Load initial prompt (one-shot, not config state) useEffect(() => { - Promise.all([api.getProfiles(), api.getProbe(), api.getInitialPrompt()]).then( - ([profilesData, probeData, promptData]) => { - setProfiles(profilesData.profiles) - if (profilesData.profiles.length > 0) { - setProfile(profilesData.profiles[0].name) - } - setHasRunners(probeData.runners.some(r => r.available)) - if (promptData.prompt) { - setTask(promptData.prompt) - } - }, - ) + api.getInitialPrompt().then(data => { + if (data.prompt) setTask(data.prompt) + }) }, []) - // Fetch preflight when profile changes + // Auto-select first profile when profiles arrive from store useEffect(() => { - if (!profile) { - setPreflight(null) + if (profiles.length > 0 && !profile) { + setProfile(profiles[0].name) + } + }, [profiles, profile]) + + // Sync scout concurrency from store + useEffect(() => { + setScoutConcurrency(storeScoutConcurrency) + }, [storeScoutConcurrency]) + + // Derive preflight locally from store state (no API call) + const preflight = useMemo(() => { + const selectedProfile = profiles.find(p => p.name === profile) + if (!selectedProfile) return null + + // Collect unique runner types from profile tiers + const requiredTypes = new Set() + for (const tier of Object.values(selectedProfile.tiers)) { + if (tier.runner_type) requiredTypes.add(tier.runner_type) + } + + // Group installations by runner type with binary validity + const installationsByType: Record = {} + for (const rt of requiredTypes) { + installationsByType[rt] = installations + .filter(i => i.runner_type === rt) + .map(i => ({ + alias: i.alias, + binary: i.binary, + // We can't check binary existence client-side, but the start-run + // endpoint validates. Show all installations as selectable. + binary_valid: true, + })) + } + + return { + required_runner_types: [...requiredTypes].sort(), + installations: installationsByType, + } + }, [profile, profiles, installations]) + + // Auto-select installations when preflight changes + useEffect(() => { + if (!preflight) { setSelectedInstallations({}) return } - setPreflightLoading(true) - api.getStartRunPreflight(profile).then(data => { - setPreflight(data) - // Auto-select: prefer the active installation if valid, else first valid - const selections: Record = {} - for (const [rt, insts] of Object.entries(data.installations)) { - const active = insts.find(i => i.is_active && i.binary_valid) - const firstValid = insts.find(i => i.binary_valid) - if (active) selections[rt] = active.alias - else if (firstValid) selections[rt] = firstValid.alias - } - setSelectedInstallations(selections) - setPreflightLoading(false) - }).catch(() => { - setPreflight(null) - setPreflightLoading(false) - }) - }, [profile]) + const selections: Record = {} + for (const rt of preflight.required_runner_types) { + const insts = preflight.installations[rt] || [] + // Prefer the active installation, else first available + const active = insts.find(i => activeInstallations[rt] === i.alias) + const first = insts[0] + if (active) selections[rt] = active.alias + else if (first) selections[rt] = first.alias + } + setSelectedInstallations(selections) + }, [preflight, activeInstallations]) - // All required runner types must have a selected installation const installationsReady = preflight ? preflight.required_runner_types.every(rt => selectedInstallations[rt]) : false @@ -85,7 +114,6 @@ export function LandingPage() { if (!result.ok) { setError(result.message ?? 'Failed to start run') } - // The SSE 'phase' event will flip runStarted → live view renders } catch { setError('Network error') } finally { @@ -128,13 +156,12 @@ export function LandingPage() {
- {preflight && !preflightLoading && preflight.required_runner_types.length > 0 && ( + {preflight && preflight.required_runner_types.length > 0 && (

Agent Installations

{preflight.required_runner_types.map(rt => { const insts = preflight.installations[rt] || [] const selected = selectedInstallations[rt] || '' - const hasNoValid = insts.length > 0 && !insts.some(i => i.binary_valid) return (
{rt} @@ -146,12 +173,8 @@ export function LandingPage() { > {insts.map(inst => ( - ))} @@ -160,11 +183,6 @@ export function LandingPage() { No installations. Add one in Settings. )} - {hasNoValid && ( - - All binaries missing. Update paths in Settings. - - )}
) })} diff --git a/frontend/src/components/SettingsOverlay.tsx b/frontend/src/components/SettingsOverlay.tsx index 4a6d5c0..525c0b0 100644 --- a/frontend/src/components/SettingsOverlay.tsx +++ b/frontend/src/components/SettingsOverlay.tsx @@ -1,5 +1,5 @@ import { useState, useEffect } from 'react' -import { useStore, Profile, Installation } from '../store/index' +import { useStore, Installation } from '../store/index' import { tierSummary } from '../utils' import * as api from '../api/client' import { RunnerInfo } from '../api/client' @@ -51,12 +51,10 @@ function ProfileForm({ const setTierField = (tier: string, field: keyof TierConfig, value: string) => { setTiers(prev => { const updated = { ...prev[tier], [field]: value } - // Reset downstream when runner changes if (field === 'runner_type') { updated.model = '' updated.thinking = '' } - // Reset thinking when model changes if (field === 'model') { updated.thinking = '' } @@ -78,12 +76,9 @@ function ProfileForm({ } setSaving(true) try { - let res - if (isEdit) { - res = await api.updateProfile(name, filteredTiers) - } else { - res = await api.createProfile(name.trim(), filteredTiers) - } + const res = isEdit + ? await api.updateProfile(name, filteredTiers) + : await api.createProfile(name.trim(), filteredTiers) if (res.ok) { onSave() } else { @@ -221,21 +216,18 @@ function InstallationForm({ const args = extraArgs.trim() ? extraArgs.trim().split(/\s+/) : [] setSaving(true) try { - let res - if (isEdit) { - res = await api.updateAgent(alias, { - runner_type: runnerType, - binary: binary.trim(), - extra_args: args, - }) - } else { - res = await api.createAgent({ - alias: alias.trim(), - runner_type: runnerType, - binary: binary.trim(), - extra_args: args, - }) - } + const res = isEdit + ? await api.updateAgent(alias, { + runner_type: runnerType, + binary: binary.trim(), + extra_args: args, + }) + : await api.createAgent({ + alias: alias.trim(), + runner_type: runnerType, + binary: binary.trim(), + extra_args: args, + }) if (res.ok) { onSave() } else { @@ -281,7 +273,7 @@ function InstallationForm({ setBinary(e.target.value)} /> @@ -320,40 +312,26 @@ function InstallationForm({ export function SettingsOverlay() { const setSettingsOpen = useStore(s => s.setSettingsOpen) - const [loading, setLoading] = useState(true) - const [profiles, setProfiles] = useState([]) - const [installations, setInstallations] = useState([]) - const [activeInstallations, setActiveInstallations] = useState>({}) - const [scoutConcurrency, setScoutConcurrency] = useState(8) - const [availableRunners, setAvailableRunners] = useState([]) - const [allRunners, setAllRunners] = useState([]) + // Read all config from the store (fed by SSE events — always current) + const profiles = useStore(s => s.configProfiles) + const installations = useStore(s => s.configInstallations) + const runners = useStore(s => s.configRunners) + const scoutConcurrency = useStore(s => s.configScoutConcurrency) + + const availableRunners = runners.filter(r => r.available) + + // Local UI state for forms + const [localScoutConcurrency, setLocalScoutConcurrency] = useState(scoutConcurrency) const [showNewProfile, setShowNewProfile] = useState(false) const [editingProfile, setEditingProfile] = useState(null) const [showNewInstallation, setShowNewInstallation] = useState(false) const [editingInstallation, setEditingInstallation] = useState(null) - const loadSettings = async () => { - setLoading(true) - try { - const [probeData, settingsData] = await Promise.all([ - api.getProbe(true), - api.getSettingsBody(), - ]) - setAvailableRunners(probeData.runners.filter(r => r.available)) - setAllRunners(probeData.runners) - setProfiles(settingsData.profiles) - setInstallations(settingsData.installations) - setActiveInstallations(settingsData.activeInstallations) - setScoutConcurrency(settingsData.scoutConcurrency) - } finally { - setLoading(false) - } - } - + // Sync local scout concurrency when store changes useEffect(() => { - loadSettings() - }, []) + setLocalScoutConcurrency(scoutConcurrency) + }, [scoutConcurrency]) useEffect(() => { const handler = (e: KeyboardEvent) => { @@ -364,23 +342,27 @@ export function SettingsOverlay() { }, [setSettingsOpen]) const handleDeleteProfile = async (name: string) => { - const res = await api.deleteProfile(name) - if (res.ok) loadSettings() + await api.deleteProfile(name) + // SSE event updates the store automatically } const handleDeleteInstallation = async (alias: string) => { - const res = await api.deleteAgent(alias) - if (res.ok) loadSettings() + await api.deleteAgent(alias) } - const handleSetActive = async (runner_type: string, alias: string) => { - const res = await api.setActiveAgent(runner_type, alias) - if (res.ok) loadSettings() + const handleSaveScoutConcurrency = async () => { + await api.saveScoutConcurrency(localScoutConcurrency) } - const handleSaveScoutConcurrency = async () => { - await api.saveScoutConcurrency(scoutConcurrency) + // Group installations by runner type + const installationsByType: Record = {} + for (const inst of installations) { + if (!installationsByType[inst.runner_type]) { + installationsByType[inst.runner_type] = [] + } + installationsByType[inst.runner_type].push(inst) } + const runnerTypes = Object.keys(installationsByType).sort() const editingProfileData = editingProfile ? profiles.find(p => p.name === editingProfile) @@ -407,133 +389,110 @@ export function SettingsOverlay() {
- {loading ? ( -

Loading...

- ) : ( - <> - {/* Profiles */} -
Profiles
- {profiles.map(p => ( -
- - {p.name} - {p.read_only && ' [locked]'} - - - {tierSummary(p.tiers)} - - {!p.read_only && ( - - - - - )} -
- ))} - - {editingProfile && editingProfileData && ( - { - setEditingProfile(null) - loadSettings() - }} - onCancel={() => setEditingProfile(null)} - /> + {/* Profiles */} +
Profiles
+ {profiles.map(p => ( +
+ + {p.name} + {p.read_only && ' [locked]'} + + + {tierSummary(p.tiers)} + + {!p.read_only && ( + + + + )} +
+ ))} + + {editingProfile && editingProfileData && ( + setEditingProfile(null)} + onCancel={() => setEditingProfile(null)} + /> + )} - {!showNewProfile ? ( - - ) : ( - { - setShowNewProfile(false) - loadSettings() - }} - onCancel={() => setShowNewProfile(false)} - /> - )} + {!showNewProfile ? ( + + ) : ( + setShowNewProfile(false)} + onCancel={() => setShowNewProfile(false)} + /> + )} - {/* Agent Installations */} -
- - Agent Installations - -
- {installations.map(inst => { - const isActive = - activeInstallations[inst.runner_type] === inst.alias - return ( -
- {inst.alias} - {isActive && active} - - {inst.runner_type} - + {/* Agent Installations — grouped by runner type */} +
+ Agent Installations +
+ {runnerTypes.map(rt => ( +
+
{rt}
+
+ {installationsByType[rt].map(inst => { + const isDefault = inst.alias === `${rt}-default` + return ( +
+ + {inst.alias} + {isDefault && ' [default]'} + + + {inst.binary || '--'} + + {inst.extra_args && inst.extra_args.length > 0 && ( - {inst.binary || '--'} + {inst.extra_args.join(' ')} - {inst.extra_args && inst.extra_args.length > 0 && ( - - {inst.extra_args.join(' ')} - - )} - - {!isActive && ( - - )} - + )} + + + {!isDefault && ( - -
- ) - })} -
- - {editingInstallation && editingInstData && ( - { - setEditingInstallation(null) - loadSettings() - }} - onCancel={() => setEditingInstallation(null)} - /> - )} - - {!showNewInstallation ? ( - - ) : ( - { - setShowNewInstallation(false) - loadSettings() - }} - onCancel={() => setShowNewInstallation(false)} - /> - )} -
- - {/* Scout Concurrency */} -
-
Scout Concurrency
-
- - setScoutConcurrency(parseInt(e.target.value, 10) || 8) - } - /> - -
+ )} + +
+ ) + })}
+
+ ))} + + {editingInstallation && editingInstData && ( + setEditingInstallation(null)} + onCancel={() => setEditingInstallation(null)} + /> + )} - {/* Refresh */} -
- -
- + {!showNewInstallation ? ( + + ) : ( + setShowNewInstallation(false)} + onCancel={() => setShowNewInstallation(false)} + /> )} + + {/* Scout Concurrency */} +
+
Scout Concurrency
+
+ + setLocalScoutConcurrency(parseInt(e.target.value, 10) || 8) + } + /> + +
+
From 0c28d8d67533679a5404a7f30bbe3ff4c41d43ad Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 14:16:18 +0700 Subject: [PATCH 218/412] remove dead API functions no longer used by components --- frontend/src/api/client.ts | 35 +---------------------------------- 1 file changed, 1 insertion(+), 34 deletions(-) diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 5423d62..8e5dad8 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -1,4 +1,4 @@ -import { Profile, Installation } from '../store/index' +import { Installation } from '../store/index' // -- Helpers ----------------------------------------------------------------- @@ -122,21 +122,6 @@ export interface RunnerInfo { models: ModelInfo[] } -export interface ProbeResult { - runners: RunnerInfo[] - balanced_profile: Profile | null -} - -export async function getProbe(refresh = false): Promise { - return get(`/api/probe${refresh ? '?refresh=1' : ''}`) -} - -// -- Profiles ---------------------------------------------------------------- - -export async function getProfiles(): Promise<{ profiles: Profile[] }> { - return get('/api/profiles') -} - export async function createProfile( name: string, tiers: Record, @@ -184,30 +169,12 @@ export async function deleteAgent(alias: string) { return del<{ ok: boolean; message?: string }>(`/api/agents/${encodeURIComponent(alias)}`) } -export async function setActiveAgent(runner_type: string, alias: string) { - return put<{ ok: boolean; message?: string }>( - `/api/agents/${encodeURIComponent(runner_type)}/active`, - { alias }, - ) -} - export async function detectAgent(runner_type: string): Promise<{ path: string | null }> { return get(`/api/agents/detect?runner_type=${encodeURIComponent(runner_type)}`) } // -- Settings ---------------------------------------------------------------- -export interface SettingsBody { - profiles: Profile[] - installations: Installation[] - activeInstallations: Record - scoutConcurrency: number -} - -export async function getSettingsBody(): Promise { - return get('/api/settings/body') -} - export async function saveScoutConcurrency(value: number) { return put<{ ok: boolean; message?: string }>('/api/settings/scout-concurrency', { scout_concurrency: value, From 0591a9cd52569e42c6c20d65f02bcc748e7d94d6 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 14:20:52 +0700 Subject: [PATCH 219/412] use consistent row layout for installations matching profile design --- frontend/src/components/SettingsOverlay.tsx | 74 ++++++++++----------- 1 file changed, 34 insertions(+), 40 deletions(-) diff --git a/frontend/src/components/SettingsOverlay.tsx b/frontend/src/components/SettingsOverlay.tsx index 525c0b0..21bfeaf 100644 --- a/frontend/src/components/SettingsOverlay.tsx +++ b/frontend/src/components/SettingsOverlay.tsx @@ -462,50 +462,44 @@ export function SettingsOverlay() { Agent Installations
{runnerTypes.map(rt => ( -
-
{rt}
-
- {installationsByType[rt].map(inst => { - const isDefault = inst.alias === `${rt}-default` - return ( -
- - {inst.alias} - {isDefault && ' [default]'} - - - {inst.binary || '--'} - - {inst.extra_args && inst.extra_args.length > 0 && ( - - {inst.extra_args.join(' ')} - - )} - +
+
{rt}
+ {installationsByType[rt].map(inst => { + const isDefault = inst.alias === `${rt}-default` + return ( +
+ + {inst.alias} + {isDefault && ' [default]'} + + + {inst.binary || '--'} + {inst.extra_args && inst.extra_args.length > 0 && ` ${inst.extra_args.join(' ')}`} + + + + {!isDefault && ( - {!isDefault && ( - - )} - -
- ) - })} -
+ )} + +
+ ) + })}
))} From 37e5a61fa39305fc8a9b93c3d9d8039639ac6fa3 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 14:30:18 +0700 Subject: [PATCH 220/412] tabbed runner-type layout for agent installations in settings --- frontend/src/components/SettingsOverlay.tsx | 179 +++++++++++--------- frontend/src/styles/components.css | 103 +++++++++-- 2 files changed, 192 insertions(+), 90 deletions(-) diff --git a/frontend/src/components/SettingsOverlay.tsx b/frontend/src/components/SettingsOverlay.tsx index 21bfeaf..2decee6 100644 --- a/frontend/src/components/SettingsOverlay.tsx +++ b/frontend/src/components/SettingsOverlay.tsx @@ -327,6 +327,7 @@ export function SettingsOverlay() { const [editingProfile, setEditingProfile] = useState(null) const [showNewInstallation, setShowNewInstallation] = useState(false) const [editingInstallation, setEditingInstallation] = useState(null) + const [activeRunnerTab, setActiveRunnerTab] = useState(null) // Sync local scout concurrency when store changes useEffect(() => { @@ -364,6 +365,12 @@ export function SettingsOverlay() { } const runnerTypes = Object.keys(installationsByType).sort() + // Auto-select first tab when runner types arrive + const currentTab = activeRunnerTab && runnerTypes.includes(activeRunnerTab) + ? activeRunnerTab + : runnerTypes[0] ?? null + const currentTabInstallations = currentTab ? installationsByType[currentTab] ?? [] : [] + const editingProfileData = editingProfile ? profiles.find(p => p.name === editingProfile) : null @@ -457,87 +464,107 @@ export function SettingsOverlay() { /> )} - {/* Agent Installations — grouped by runner type */} + {/* Agent Installations — tabbed by runner type */}
Agent Installations
- {runnerTypes.map(rt => ( -
-
{rt}
- {installationsByType[rt].map(inst => { - const isDefault = inst.alias === `${rt}-default` - return ( -
- - {inst.alias} - {isDefault && ' [default]'} - - - {inst.binary || '--'} - {inst.extra_args && inst.extra_args.length > 0 && ` ${inst.extra_args.join(' ')}`} - - - + ))} +
+ + {/* Tab content */} + {currentTab && ( +
+ {currentTabInstallations.map(inst => { + const isDefault = inst.alias === `${currentTab}-default` + return ( +
- Edit - - {!isDefault && ( - - )} - -
- ) - })} +
+ {inst.alias} + {isDefault && default} +
+ + {inst.binary || '--'} + {inst.extra_args && inst.extra_args.length > 0 && ` ${inst.extra_args.join(' ')}`} + + + + {!isDefault && ( + + )} + +
+ ) + })} + + {editingInstallation && editingInstData && editingInstData.runner_type === currentTab && ( + setEditingInstallation(null)} + onCancel={() => setEditingInstallation(null)} + /> + )} + + {!showNewInstallation ? ( + + ) : ( + setShowNewInstallation(false)} + onCancel={() => setShowNewInstallation(false)} + /> + )} +
+ )}
- ))} - - {editingInstallation && editingInstData && ( - setEditingInstallation(null)} - onCancel={() => setEditingInstallation(null)} - /> - )} - - {!showNewInstallation ? ( - - ) : ( - setShowNewInstallation(false)} - onCancel={() => setShowNewInstallation(false)} - /> )} {/* Scout Concurrency */} diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 70c70d4..7149852 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -1069,37 +1069,112 @@ margin-left: auto; } -.installation-cards { +/* -- Installation tabs -- */ + +.install-tab-bar { display: flex; - flex-wrap: wrap; - gap: var(--space-4); - margin-top: var(--space-4); + gap: 0; + border-bottom: 2px solid var(--border); + margin-bottom: 0; } -.installation-card { - background: var(--bg-elevated); +.install-tab { + padding: var(--space-2) var(--space-4); + font-family: var(--font-mono); + font-size: var(--font-size-sm); + color: var(--text-muted); + background: none; + border: none; + cursor: pointer; + margin-bottom: -2px; + border-bottom: 2px solid transparent; + transition: color var(--duration-fast) var(--ease-default), + border-color var(--duration-fast) var(--ease-default); +} + +.install-tab:hover { + color: var(--text); +} + +.install-tab--active { + font-weight: 600; + color: var(--text-strong); + border-bottom-color: var(--green); +} + +.install-tab-content { + padding: var(--space-4) 0; +} + +.install-row { + display: flex; + align-items: center; + gap: var(--space-4); + padding: var(--space-2) var(--space-4); border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-4); - min-width: 180px; - max-width: 220px; + border-radius: var(--radius-sm); + margin-bottom: var(--space-2); + background: var(--bg-elevated); +} + +.install-row--default { + background: var(--bg); + border-color: transparent; +} + +.install-row-info { display: flex; - flex-direction: column; + align-items: center; gap: var(--space-2); + min-width: 160px; } -.installation-card-alias { +.install-row-alias { font-family: var(--font-mono); - font-weight: 700; + font-weight: 600; + font-size: var(--font-size-sm); color: var(--text-strong); } -.installation-card-meta { +.install-row-badge { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + background: var(--green-bg); + color: var(--green); + padding: 1px 8px; + border-radius: var(--radius-sm); +} + +.install-row-path { + flex: 1; font-family: var(--font-mono); font-size: var(--font-size-xs); color: var(--text-muted); } +.install-add-btn { + font-family: var(--font-mono); + font-size: var(--font-size-sm); + padding: var(--space-2) var(--space-4); + border: 1px dashed var(--border); + border-radius: var(--radius-sm); + background: none; + color: var(--text-muted); + cursor: pointer; + margin-top: var(--space-2); + transition: border-color var(--duration-fast) var(--ease-default), + color var(--duration-fast) var(--ease-default); +} + +.install-add-btn:hover { + border-color: var(--border-strong); + color: var(--text); +} + +.btn-danger { + color: var(--red); +} + .no-runners-msg { font-family: var(--font-sans); font-size: var(--font-size-sm); From 2bb9b248d3f5902cfd69f576b9973626c24bdfe9 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 14:45:13 +0700 Subject: [PATCH 221/412] fix claude thinking: use --effort flag instead of --thinking-budget-tokens Claude CLI uses --effort with values low/medium/high/max. Only opus supports max (mapped from internal 'xhigh'). Sonnet restricted to low/medium/high (no xhigh/max). --- koan/runners/claude.py | 28 +++++++++++++++++----------- tests/test_runners.py | 28 ++++++++++++++-------------- 2 files changed, 31 insertions(+), 25 deletions(-) diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 373c0aa..5892aae 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -9,11 +9,12 @@ from ..types import AgentInstallation, ModelInfo, ThinkingMode from .base import KOAN_MCP_TOOLS, RunnerDiagnostic, RunnerError, StreamEvent -THINKING_BUDGET: dict[ThinkingMode, int] = { - "low": 1024, - "medium": 8000, - "high": 16000, - "xhigh": 32000, +# Map internal thinking mode names to Claude CLI --effort values. +_EFFORT_MAP: dict[ThinkingMode, str] = { + "low": "low", + "medium": "medium", + "high": "high", + "xhigh": "max", # opus only } # Canonical tool name mappings for Claude's tool vocabulary. @@ -49,12 +50,17 @@ def __init__(self, *, subagent_dir: str) -> None: self.subagent_dir = subagent_dir def list_models(self, binary: str) -> list[ModelInfo]: - all_modes: frozenset[ThinkingMode] = frozenset( - {"disabled", "low", "medium", "high", "xhigh"} - ) return [ - ModelInfo(alias="opus", display_name="Opus", thinking_modes=all_modes, tier_hint="strong"), - ModelInfo(alias="sonnet", display_name="Sonnet", thinking_modes=all_modes, tier_hint="standard"), + ModelInfo( + alias="opus", display_name="Opus", + thinking_modes=frozenset({"disabled", "low", "medium", "high", "xhigh"}), + tier_hint="strong", + ), + ModelInfo( + alias="sonnet", display_name="Sonnet", + thinking_modes=frozenset({"disabled", "low", "medium", "high"}), + tier_hint="standard", + ), ModelInfo( alias="haiku", display_name="Haiku", thinking_modes=frozenset({"disabled", "low"}), @@ -102,7 +108,7 @@ def build_command( "--mcp-config", str(config_path), ] if thinking != "disabled": - cmd.extend(["--thinking-budget-tokens", str(THINKING_BUDGET[thinking])]) + cmd.extend(["--effort", _EFFORT_MAP[thinking]]) cmd.extend(["--model", model]) cmd.extend(installation.extra_args) return cmd diff --git a/tests/test_runners.py b/tests/test_runners.py index cea2a27..54701d7 100644 --- a/tests/test_runners.py +++ b/tests/test_runners.py @@ -300,39 +300,39 @@ def test_disabled_no_thinking_flag(self, tmp_path): cmd = runner.build_command( "p", "http://x/mcp", _install("claude"), "opus", "disabled", ) - assert "--thinking-budget-tokens" not in cmd + assert "--effort" not in cmd - def test_low_budget(self, tmp_path): + def test_effort_low(self, tmp_path): runner = ClaudeRunner(subagent_dir=str(tmp_path)) cmd = runner.build_command( "p", "http://x/mcp", _install("claude"), "opus", "low", ) - idx = cmd.index("--thinking-budget-tokens") - assert cmd[idx + 1] == "1024" + idx = cmd.index("--effort") + assert cmd[idx + 1] == "low" - def test_medium_budget(self, tmp_path): + def test_effort_medium(self, tmp_path): runner = ClaudeRunner(subagent_dir=str(tmp_path)) cmd = runner.build_command( "p", "http://x/mcp", _install("claude"), "opus", "medium", ) - idx = cmd.index("--thinking-budget-tokens") - assert cmd[idx + 1] == "8000" + idx = cmd.index("--effort") + assert cmd[idx + 1] == "medium" - def test_high_budget(self, tmp_path): + def test_effort_high(self, tmp_path): runner = ClaudeRunner(subagent_dir=str(tmp_path)) cmd = runner.build_command( "p", "http://x/mcp", _install("claude"), "opus", "high", ) - idx = cmd.index("--thinking-budget-tokens") - assert cmd[idx + 1] == "16000" + idx = cmd.index("--effort") + assert cmd[idx + 1] == "high" - def test_xhigh_budget(self, tmp_path): + def test_effort_max_opus(self, tmp_path): runner = ClaudeRunner(subagent_dir=str(tmp_path)) cmd = runner.build_command( "p", "http://x/mcp", _install("claude"), "opus", "xhigh", ) - idx = cmd.index("--thinking-budget-tokens") - assert cmd[idx + 1] == "32000" + idx = cmd.index("--effort") + assert cmd[idx + 1] == "max" # -- ClaudeRunner: list_models ------------------------------------------------- @@ -359,7 +359,7 @@ def test_sonnet_all_thinking_modes(self): runner = ClaudeRunner(subagent_dir="/tmp/x") models = runner.list_models("claude") sonnet = [m for m in models if m.alias == "sonnet"][0] - assert sonnet.thinking_modes == frozenset({"disabled", "low", "medium", "high", "xhigh"}) + assert sonnet.thinking_modes == frozenset({"disabled", "low", "medium", "high"}) # -- ClaudeRunner: extra_args -------------------------------------------------- From 00dfdb628374bc492b9a0973d7c39ec352da04a5 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 14:46:16 +0700 Subject: [PATCH 222/412] haiku supports low/medium/high effort (not max) --- koan/runners/claude.py | 2 +- tests/test_runners.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 5892aae..c679618 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -63,7 +63,7 @@ def list_models(self, binary: str) -> list[ModelInfo]: ), ModelInfo( alias="haiku", display_name="Haiku", - thinking_modes=frozenset({"disabled", "low"}), + thinking_modes=frozenset({"disabled", "low", "medium", "high"}), tier_hint="cheap", ), ] diff --git a/tests/test_runners.py b/tests/test_runners.py index 54701d7..13cc0ef 100644 --- a/tests/test_runners.py +++ b/tests/test_runners.py @@ -347,7 +347,7 @@ def test_haiku_limited_thinking(self): runner = ClaudeRunner(subagent_dir="/tmp/x") models = runner.list_models("claude") haiku = [m for m in models if m.alias == "haiku"][0] - assert haiku.thinking_modes == frozenset({"disabled", "low"}) + assert haiku.thinking_modes == frozenset({"disabled", "low", "medium", "high"}) def test_opus_all_thinking_modes(self): runner = ClaudeRunner(subagent_dir="/tmp/x") From 3706693a0bb3deab1b0aa9cbf3a9a167467515ad Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 14:51:08 +0700 Subject: [PATCH 223/412] shutdown: kill active agents immediately, don't wait for HTTP clients - Track subprocess handles in AppState._active_processes - Lifespan shutdown: SIGTERM all agents, wait 5s, SIGKILL stragglers - uvicorn timeout_graceful_shutdown=0: close client connections immediately --- koan/__main__.py | 5 ++++- koan/state.py | 4 ++++ koan/subagent.py | 4 +++- koan/web/app.py | 27 +++++++++++++++++++++++++++ tests/test_subagent.py | 1 + 5 files changed, 39 insertions(+), 2 deletions(-) diff --git a/koan/__main__.py b/koan/__main__.py index 7346fb1..29a2509 100644 --- a/koan/__main__.py +++ b/koan/__main__.py @@ -100,7 +100,10 @@ def main() -> None: app = create_app(app_state) host = "127.0.0.1" - uvicorn.run(app, host=host, port=port, log_level=args.log_level.lower()) + # timeout_graceful_shutdown=0: don't wait for HTTP clients to disconnect. + # Agent cleanup happens in the lifespan shutdown handler instead. + uvicorn.run(app, host=host, port=port, log_level=args.log_level.lower(), + timeout_graceful_shutdown=0) if __name__ == "__main__": diff --git a/koan/state.py b/koan/state.py index b0566b9..39aeea4 100644 --- a/koan/state.py +++ b/koan/state.py @@ -65,3 +65,7 @@ class AppState: open_browser: bool = True initial_prompt: str = "" config_write_lock: asyncio.Lock = field(default_factory=asyncio.Lock) + # Track running subprocess handles so shutdown can kill them. + _active_processes: dict[str, asyncio.subprocess.Process] = field( + default_factory=dict, repr=False, + ) diff --git a/koan/subagent.py b/koan/subagent.py index 3622478..d0c11ae 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -190,6 +190,7 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None stderr=asyncio.subprocess.PIPE, cwd=subagent_dir, ) + app_state._active_processes[agent_id] = proc # Stream tracking async def stream_stdout(): @@ -271,7 +272,8 @@ async def drain_stderr(): error_str = "bootstrap_failure" exit_code = 1 - # Cleanup: resolve pending interactions for this agent + # Cleanup: remove from active processes, resolve pending interactions + app_state._active_processes.pop(agent_id, None) _cancel_pending_interactions(agent_id, app_state) # Finalize audit log diff --git a/koan/web/app.py b/koan/web/app.py index 22e01cd..d0c717f 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -6,6 +6,7 @@ import asyncio import json +import logging import shutil import time import uuid @@ -13,6 +14,8 @@ from pathlib import Path from typing import TYPE_CHECKING, Any +log = logging.getLogger(__name__) + from starlette.applications import Starlette from starlette.requests import Request from starlette.responses import FileResponse, JSONResponse, Response @@ -1064,6 +1067,30 @@ async def _open_browser(): async with mcp_app._mcp_inner.lifespan(app): # type: ignore[attr-defined] yield + # -- Shutdown: kill all active agent processes ------------------------- + procs = dict(app_state._active_processes) + if procs: + log.info("shutdown: terminating %d active agent(s)…", len(procs)) + for aid, proc in procs.items(): + try: + proc.terminate() + except ProcessLookupError: + pass # already dead + + # Give agents a few seconds to exit cleanly + async def _wait_proc(aid: str, proc: asyncio.subprocess.Process) -> None: + try: + await asyncio.wait_for(proc.wait(), timeout=5.0) + except asyncio.TimeoutError: + log.warning("shutdown: agent %s did not exit in time, killing", aid) + try: + proc.kill() + except ProcessLookupError: + pass + + await asyncio.gather(*[_wait_proc(a, p) for a, p in procs.items()]) + log.info("shutdown: all agents stopped") + routes = [ Mount("/mcp", app=mcp_app), Route("/api/start-run", api_start_run, methods=["POST"]), diff --git a/tests/test_subagent.py b/tests/test_subagent.py index 290a4d1..5b6d843 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -37,6 +37,7 @@ class FakeAppState: frozen_logs: list = field(default_factory=list) epic_dir: str | None = None projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) + _active_processes: dict = field(default_factory=dict) class FakeRunner: From c1f96d18c64cfad14a174205f1b2ab9c68773afd Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 15:12:23 +0700 Subject: [PATCH 224/412] remove global activeInstallations; model installation selection as per-run state - KoanConfig: remove active_installations field; save_koan_config strips legacy key - AppState: add run_installations dict[str,str] set when a run starts - RunnerRegistry: get_installation/resolve_installation/resolve_agent_config accept run_installations parameter; fall back to first installation when not specified - spawn_subagent: pass app_state.run_installations to resolve_agent_config - api_start_run: store installations in st.run_installations (not config); remove active_installation_changed event emissions; pass run_installations to pre-validation - Remove api_agents_set_active endpoint and its route - Remove build_active_installation_changed from events.py - Remove active_installation_changed from projections EVENT_TYPES, Projection fields, fold logic, and installation_removed cleanup - Frontend store: remove configActiveInstallations state and all related handlers - Frontend SSE: remove active_installation_changed from KNOWN_EVENTS - LandingPage: auto-select prefers {rt}-default alias instead of stored active - Tests: remove active_installations from fixtures; use /fake/bin/claude paths; update assertions to check run_installations instead of config.active_installations --- frontend/src/api/client.ts | 2 - frontend/src/components/LandingPage.tsx | 9 ++-- frontend/src/sse/connect.ts | 2 +- frontend/src/store/index.ts | 19 +------- koan/config.py | 14 +----- koan/events.py | 3 -- koan/projections.py | 26 +---------- koan/runners/registry.py | 27 ++++++++--- koan/state.py | 3 ++ koan/subagent.py | 4 +- koan/web/app.py | 60 ++----------------------- tests/test_probe.py | 50 ++++++++++----------- tests/test_projections.py | 31 ++----------- tests/test_registry.py | 44 ++++++++---------- tests/test_subagent.py | 1 + tests/test_web_flows.py | 22 +++------ 16 files changed, 93 insertions(+), 224 deletions(-) diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 8e5dad8..f5c7ec4 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -61,7 +61,6 @@ export interface PreflightInstallation { alias: string binary: string binary_valid: boolean - is_active: boolean extra_args: string[] } @@ -144,7 +143,6 @@ export async function deleteProfile(name: string) { export async function getAgents(): Promise<{ installations: Installation[] - active_installations: Record }> { return get('/api/agents') } diff --git a/frontend/src/components/LandingPage.tsx b/frontend/src/components/LandingPage.tsx index 7eed2a2..98467d4 100644 --- a/frontend/src/components/LandingPage.tsx +++ b/frontend/src/components/LandingPage.tsx @@ -13,7 +13,6 @@ export function LandingPage() { // Read from store (fed by SSE — always current, no API fetch needed) const profiles = useStore(s => s.configProfiles) const installations = useStore(s => s.configInstallations) - const activeInstallations = useStore(s => s.configActiveInstallations) const runners = useStore(s => s.configRunners) const storeScoutConcurrency = useStore(s => s.configScoutConcurrency) @@ -78,14 +77,14 @@ export function LandingPage() { const selections: Record = {} for (const rt of preflight.required_runner_types) { const insts = preflight.installations[rt] || [] - // Prefer the active installation, else first available - const active = insts.find(i => activeInstallations[rt] === i.alias) + // Prefer the {rt}-default installation, else first available + const defaultInst = insts.find(i => i.alias === `${rt}-default`) const first = insts[0] - if (active) selections[rt] = active.alias + if (defaultInst) selections[rt] = defaultInst.alias else if (first) selections[rt] = first.alias } setSelectedInstallations(selections) - }, [preflight, activeInstallations]) + }, [preflight]) const installationsReady = preflight ? preflight.required_runner_types.every(rt => selectedInstallations[rt]) diff --git a/frontend/src/sse/connect.ts b/frontend/src/sse/connect.ts index 63d9bbd..4858bc2 100644 --- a/frontend/src/sse/connect.ts +++ b/frontend/src/sse/connect.ts @@ -51,7 +51,7 @@ export function connectSSE(store: KoanStore): EventSource { 'probe_completed', 'installation_created', 'installation_modified', 'installation_removed', 'profile_created', 'profile_modified', 'profile_removed', - 'active_profile_changed', 'active_installation_changed', + 'active_profile_changed', 'scout_concurrency_changed', ] diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 55942d9..e8a3627 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -182,7 +182,6 @@ interface KoanState { // Configuration — sourced from projection events, always up to date configProfiles: Profile[] configInstallations: Installation[] - configActiveInstallations: Record configActiveProfile: string configScoutConcurrency: number configRunners: RunnerInfo[] @@ -237,7 +236,6 @@ export const useStore = create((set) => ({ // Configuration defaults configProfiles: [], configInstallations: [], - configActiveInstallations: {}, configActiveProfile: 'balanced', configScoutConcurrency: 8, configRunners: [], @@ -385,7 +383,6 @@ export const useStore = create((set) => ({ // Configuration configProfiles, configInstallations, - configActiveInstallations: (state['config_active_installations'] ?? {}) as Record, configActiveProfile: (state['config_active_profile'] as string) ?? 'balanced', configScoutConcurrency: (state['config_scout_concurrency'] as number) ?? 8, configRunners: (state['config_runners'] ?? []) as RunnerInfo[], @@ -631,12 +628,7 @@ export const useStore = create((set) => ({ case 'installation_removed': { const alias = event['alias'] as string - const newInsts = s.configInstallations.filter(i => i.alias !== alias) - const newActive = { ...s.configActiveInstallations } - for (const [rt, a] of Object.entries(newActive)) { - if (a === alias) delete newActive[rt] - } - return { ...base, configInstallations: newInsts, configActiveInstallations: newActive } + return { ...base, configInstallations: s.configInstallations.filter(i => i.alias !== alias) } } case 'profile_created': { @@ -676,15 +668,6 @@ export const useStore = create((set) => ({ return { ...base, configActiveProfile: (event['name'] as string) ?? 'balanced' } } - case 'active_installation_changed': { - const rt = event['runner_type'] as string - const alias = event['alias'] as string - return { - ...base, - configActiveInstallations: { ...s.configActiveInstallations, [rt]: alias }, - } - } - case 'scout_concurrency_changed': { return { ...base, configScoutConcurrency: (event['value'] as number) ?? 8 } } diff --git a/koan/config.py b/koan/config.py index 05eab21..70c3704 100644 --- a/koan/config.py +++ b/koan/config.py @@ -19,7 +19,6 @@ @dataclass class KoanConfig: agent_installations: list[AgentInstallation] = field(default_factory=list) - active_installations: dict[str, str] = field(default_factory=dict) profiles: list[Profile] = field(default_factory=list) active_profile: str = "balanced" scout_concurrency: int = 8 @@ -128,12 +127,6 @@ async def load_koan_config() -> KoanConfig: log.warning("config.json top-level value is not an object; treating config as absent.") return defaults - # Silently ignore legacy modelTiers key - - active_installations = parsed.get("activeInstallations", {}) - if not isinstance(active_installations, dict): - active_installations = {} - active_profile = parsed.get("activeProfile", "balanced") if not isinstance(active_profile, str) or not active_profile: active_profile = "balanced" @@ -143,7 +136,6 @@ async def load_koan_config() -> KoanConfig: return KoanConfig( agent_installations=_parse_agent_installations(parsed.get("agentInstallations", [])), - active_installations={str(k): str(v) for k, v in active_installations.items()}, profiles=profiles, active_profile=active_profile, scout_concurrency=_parse_scout_concurrency(parsed), @@ -161,8 +153,9 @@ async def save_koan_config(config: KoanConfig) -> None: except (FileNotFoundError, json.JSONDecodeError): pass - # Remove legacy key + # Remove legacy keys existing.pop("modelTiers", None) + existing.pop("activeInstallations", None) # Serialize agent_installations existing["agentInstallations"] = [ @@ -175,9 +168,6 @@ async def save_koan_config(config: KoanConfig) -> None: for inst in config.agent_installations ] - # Serialize active_installations - existing["activeInstallations"] = config.active_installations - # Serialize active_profile (omit if default) if config.active_profile != "balanced": existing["activeProfile"] = config.active_profile diff --git a/koan/events.py b/koan/events.py index 8c3caff..b2107a2 100644 --- a/koan/events.py +++ b/koan/events.py @@ -224,9 +224,6 @@ def build_active_profile_changed(name: str) -> dict: return {"name": name} -def build_active_installation_changed(runner_type: str, alias: str) -> dict: - return {"runner_type": runner_type, "alias": alias} - def build_scout_concurrency_changed(value: int) -> dict: return {"value": value} diff --git a/koan/projections.py b/koan/projections.py index 1737d1c..7a7ca75 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -46,7 +46,6 @@ "profile_modified", "profile_removed", "active_profile_changed", - "active_installation_changed", "scout_concurrency_changed", ] @@ -98,7 +97,6 @@ class Projection(BaseModel): config_runners: list[dict] = Field(default_factory=list) config_profiles: list[dict] = Field(default_factory=list) config_installations: list[dict] = Field(default_factory=list) - config_active_installations: dict[str, str] = Field(default_factory=dict) config_active_profile: str = "balanced" config_scout_concurrency: int = 8 @@ -352,23 +350,11 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: case "installation_removed": alias = payload.get("alias", "") - # Find runner_type before removing (needed to clean active_installations) - removed_rt = next( - (inst.get("runner_type") for inst in projection.config_installations - if inst.get("alias") == alias), - None, - ) new_insts = [ inst for inst in projection.config_installations if inst.get("alias") != alias ] - new_active = dict(projection.config_active_installations) - if removed_rt and new_active.get(removed_rt) == alias: - del new_active[removed_rt] - return projection.model_copy(update={ - "config_installations": new_insts, - "config_active_installations": new_active, - }) + return projection.model_copy(update={"config_installations": new_insts}) case "profile_created": new_profile = { @@ -409,16 +395,6 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: "config_active_profile": payload.get("name", "balanced"), }) - case "active_installation_changed": - new_active = dict(projection.config_active_installations) - rt = payload.get("runner_type", "") - alias = payload.get("alias", "") - if rt: - new_active[rt] = alias - return projection.model_copy(update={ - "config_active_installations": new_active, - }) - case "scout_concurrency_changed": return projection.model_copy(update={ "config_scout_concurrency": payload.get("value", 8), diff --git a/koan/runners/registry.py b/koan/runners/registry.py index dba45fa..d37ffc7 100644 --- a/koan/runners/registry.py +++ b/koan/runners/registry.py @@ -83,8 +83,13 @@ def get_runner(self, runner_type: str, subagent_dir: str) -> Runner: return cls(subagent_dir=subagent_dir) return cls() - def get_installation(self, runner_type: str, config: KoanConfig) -> AgentInstallation: - alias = config.active_installations.get(runner_type) + def get_installation( + self, + runner_type: str, + config: KoanConfig, + run_installations: dict[str, str] | None = None, + ) -> AgentInstallation: + alias = (run_installations or {}).get(runner_type) if alias: for inst in config.agent_installations: if inst.alias == alias and inst.runner_type == runner_type: @@ -93,11 +98,11 @@ def get_installation(self, runner_type: str, config: KoanConfig) -> AgentInstall code="no_installation", runner=runner_type, stage="get_installation", - message=f"Active installation alias '{alias}' not found for runner '{runner_type}'", + message=f"Installation alias '{alias}' not found for runner '{runner_type}'", details={"runner_type": runner_type, "alias": alias}, )) - # No active alias configured -- fall back to first installation of this type + # No alias specified -- fall back to first installation of this type for inst in config.agent_installations: if inst.runner_type == runner_type: return inst @@ -110,13 +115,18 @@ def get_installation(self, runner_type: str, config: KoanConfig) -> AgentInstall details={"runner_type": runner_type}, )) - def resolve_installation(self, runner_type: str, config: KoanConfig) -> AgentInstallation: + def resolve_installation( + self, + runner_type: str, + config: KoanConfig, + run_installations: dict[str, str] | None = None, + ) -> AgentInstallation: """Resolve a working installation for *runner_type*. Returns the installation after validating its binary exists on disk. Raises RunnerError if the installation is missing or the binary is not found. """ - inst = self.get_installation(runner_type, config) + inst = self.get_installation(runner_type, config, run_installations) if not Path(inst.binary).exists(): raise RunnerError(RunnerDiagnostic( code="binary_not_found", @@ -135,6 +145,7 @@ def resolve_agent_config( role: SubagentRole, config: KoanConfig, balanced_profile: Profile | None = None, + run_installations: dict[str, str] | None = None, ) -> tuple[AgentInstallation, str, ThinkingMode]: tier = ROLE_MODEL_TIER.get(role, "standard") @@ -165,7 +176,9 @@ def resolve_agent_config( message=f"Profile '{profile.name}' has no tier '{tier}'", )) - installation = self.resolve_installation(profile_tier.runner_type, config) + installation = self.resolve_installation( + profile_tier.runner_type, config, run_installations, + ) return installation, profile_tier.model, profile_tier.thinking diff --git a/koan/state.py b/koan/state.py index 39aeea4..3007e63 100644 --- a/koan/state.py +++ b/koan/state.py @@ -65,6 +65,9 @@ class AppState: open_browser: bool = True initial_prompt: str = "" config_write_lock: asyncio.Lock = field(default_factory=asyncio.Lock) + # Installation selections for the current run: runner_type -> alias. + # Set when a run starts; cleared when a new run begins. + run_installations: dict[str, str] = field(default_factory=dict) # Track running subprocess handles so shutdown can kill them. _active_processes: dict[str, asyncio.subprocess.Process] = field( default_factory=dict, repr=False, diff --git a/koan/subagent.py b/koan/subagent.py index d0c11ae..e863f7e 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -98,7 +98,9 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None config = app_state.config registry = RunnerRegistry() installation, model_alias, thinking_mode = registry.resolve_agent_config( - role, config, balanced_profile=app_state.balanced_profile, + role, config, + balanced_profile=app_state.balanced_profile, + run_installations=app_state.run_installations, ) runner = registry.get_runner(installation.runner_type, subagent_dir) diff --git a/koan/web/app.py b/koan/web/app.py index d0c717f..beede24 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -40,7 +40,6 @@ build_profile_modified, build_profile_removed, build_active_profile_changed, - build_active_installation_changed, build_scout_concurrency_changed, ) @@ -226,7 +225,6 @@ async def api_start_run_preflight(r: Request) -> Response: "alias": inst.alias, "binary": inst.binary, "binary_valid": Path(inst.binary).exists(), - "is_active": st.config.active_installations.get(rt) == inst.alias, "extra_args": inst.extra_args, }) installations_by_type[rt] = insts @@ -287,7 +285,7 @@ async def api_start_run(r: Request) -> Response: status_code=422, ) for rt, alias in installations.items(): - st.config.active_installations[rt] = alias + st.run_installations[rt] = alias # Pre-validate installations for every runner type the profile requires from ..runners.registry import RunnerRegistry @@ -299,7 +297,7 @@ async def api_start_run(r: Request) -> Response: continue checked_types.add(tier.runner_type) try: - registry.resolve_installation(tier.runner_type, st.config) + registry.resolve_installation(tier.runner_type, st.config, st.run_installations) except RunnerError as e: return JSONResponse( {"error": e.diagnostic.code, @@ -313,11 +311,6 @@ async def api_start_run(r: Request) -> Response: from ..config import save_koan_config await save_koan_config(st.config) st.projection_store.push_event("active_profile_changed", build_active_profile_changed(profile)) - if isinstance(installations, dict): - for rt, alias in installations.items(): - st.projection_store.push_event( - "active_installation_changed", build_active_installation_changed(rt, alias), - ) # Apply optional overrides scout_concurrency = body.get("scout_concurrency") @@ -603,10 +596,6 @@ def _push_initial_config_events(st: AppState) -> None: build_installation_created(inst.alias, inst.runner_type, inst.binary, inst.extra_args), ) - # Active installation selections - for rt, alias in st.config.active_installations.items(): - store.push_event("active_installation_changed", build_active_installation_changed(rt, alias)) - # Active profile store.push_event("active_profile_changed", build_active_profile_changed(st.config.active_profile)) @@ -771,10 +760,7 @@ async def api_agents_list(r: Request) -> Response: } for inst in st.config.agent_installations ] - return JSONResponse({ - "installations": installations, - "active_installations": st.config.active_installations, - }) + return JSONResponse({"installations": installations}) async def api_agents_create(r: Request) -> Response: @@ -865,10 +851,6 @@ async def api_agents_delete(r: Request) -> Response: return JSONResponse({"error": "not_found", "message": f"installation '{alias}' not found"}, status_code=404) st.config.agent_installations.pop(idx) - # Clean up active_installations if this alias was active - for rt, active_alias in list(st.config.active_installations.items()): - if active_alias == alias: - del st.config.active_installations[rt] from ..config import save_koan_config await save_koan_config(st.config) @@ -876,38 +858,6 @@ async def api_agents_delete(r: Request) -> Response: return JSONResponse({"ok": True}) -async def api_agents_set_active(r: Request) -> Response: - runner_type = r.path_params["runner_type"] - body = await r.json() - alias = body.get("alias", "") - - if not isinstance(alias, str) or not alias.strip(): - return JSONResponse( - {"error": "validation_error", "message": "alias is required"}, - status_code=422, - ) - - st = _app_state(r) - found = any( - inst.alias == alias and inst.runner_type == runner_type - for inst in st.config.agent_installations - ) - if not found: - return JSONResponse( - {"error": "validation_error", - "message": f"no installation with alias '{alias}' and runner_type '{runner_type}'"}, - status_code=422, - ) - - st.config.active_installations[runner_type] = alias - from ..config import save_koan_config - await save_koan_config(st.config) - st.projection_store.push_event( - "active_installation_changed", build_active_installation_changed(runner_type, alias), - ) - return JSONResponse({"ok": True}) - - async def api_agents_detect(r: Request) -> Response: runner_type = r.query_params.get("runner_type", "") if not runner_type: @@ -932,19 +882,16 @@ async def api_settings_body(r: Request) -> Response: installations = [] for inst in st.config.agent_installations: - is_active = (st.config.active_installations or {}).get(inst.runner_type) == inst.alias installations.append({ "alias": inst.alias, "runner_type": inst.runner_type, "binary": inst.binary, "extra_args": inst.extra_args, - "is_active": is_active, }) return JSONResponse({ "profiles": profiles, "installations": installations, - "activeInstallations": st.config.active_installations or {}, "scoutConcurrency": st.config.scout_concurrency, }) @@ -1108,7 +1055,6 @@ async def _wait_proc(aid: str, proc: asyncio.subprocess.Process) -> None: Route("/api/agents", api_agents_list, methods=["GET"]), Route("/api/agents", api_agents_create, methods=["POST"]), Route("/api/agents/detect", api_agents_detect, methods=["GET"]), - Route("/api/agents/{runner_type}/active", api_agents_set_active, methods=["PUT"]), Route("/api/agents/{alias}", api_agents_update, methods=["PUT"]), Route("/api/agents/{alias}", api_agents_delete, methods=["DELETE"]), Route("/api/settings/body", api_settings_body, methods=["GET"]), diff --git a/tests/test_probe.py b/tests/test_probe.py index a1664e7..067ffd2 100644 --- a/tests/test_probe.py +++ b/tests/test_probe.py @@ -24,15 +24,15 @@ async def test_returns_unavailable(self): class TestProbeClaudeAuthFailure: @pytest.mark.anyio async def test_bad_exit_code(self): - with patch("koan.probe.shutil.which", return_value="/usr/bin/claude"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/claude"), \ patch("koan.probe._run_cmd", new_callable=AsyncMock, return_value=(1, "", "")): r = await _probe_claude() assert r.available is False - assert r.binary_path == "/usr/bin/claude" + assert r.binary_path == "/fake/bin/claude" @pytest.mark.anyio async def test_bad_json(self): - with patch("koan.probe.shutil.which", return_value="/usr/bin/claude"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/claude"), \ patch("koan.probe._run_cmd", new_callable=AsyncMock, return_value=(0, "not json", "")): r = await _probe_claude() assert r.available is False @@ -40,7 +40,7 @@ async def test_bad_json(self): @pytest.mark.anyio async def test_not_logged_in(self): body = json.dumps({"loggedIn": False}) - with patch("koan.probe.shutil.which", return_value="/usr/bin/claude"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/claude"), \ patch("koan.probe._run_cmd", new_callable=AsyncMock, return_value=(0, body, "")): r = await _probe_claude() assert r.available is False @@ -49,7 +49,7 @@ async def test_not_logged_in(self): class TestProbeClaudeTimeout: @pytest.mark.anyio async def test_auth_timeout(self): - with patch("koan.probe.shutil.which", return_value="/usr/bin/claude"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/claude"), \ patch("koan.probe._run_cmd", new_callable=AsyncMock, return_value=(-1, "", "")): r = await _probe_claude() assert r.available is False @@ -67,11 +67,11 @@ async def fake_run_cmd(args): return (0, "claude 1.2.3\n", "") return (-1, "", "") - with patch("koan.probe.shutil.which", return_value="/usr/bin/claude"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/claude"), \ patch("koan.probe._run_cmd", side_effect=fake_run_cmd): r = await _probe_claude() assert r.available is True - assert r.binary_path == "/usr/bin/claude" + assert r.binary_path == "/fake/bin/claude" assert r.version == "claude 1.2.3" @@ -87,11 +87,11 @@ async def fake_run_cmd(args): return (1, "", "") return (-1, "", "") - with patch("koan.probe.shutil.which", return_value="/usr/bin/claude"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/claude"), \ patch("koan.probe._run_cmd", side_effect=fake_run_cmd): r = await _probe_claude() assert r.available is False - assert r.binary_path == "/usr/bin/claude" + assert r.binary_path == "/fake/bin/claude" assert r.version is None @pytest.mark.anyio @@ -105,11 +105,11 @@ async def fake_run_cmd(args): return (-1, "", "") return (-1, "", "") - with patch("koan.probe.shutil.which", return_value="/usr/bin/claude"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/claude"), \ patch("koan.probe._run_cmd", side_effect=fake_run_cmd): r = await _probe_claude() assert r.available is False - assert r.binary_path == "/usr/bin/claude" + assert r.binary_path == "/fake/bin/claude" # -- Codex probe --------------------------------------------------------------- @@ -127,14 +127,14 @@ async def test_returns_unavailable(self): class TestProbeCodexAuthFailure: @pytest.mark.anyio async def test_bad_exit_code(self): - with patch("koan.probe.shutil.which", return_value="/usr/bin/codex"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/codex"), \ patch("koan.probe._run_cmd", new_callable=AsyncMock, return_value=(1, "", "")): r = await _probe_codex() assert r.available is False @pytest.mark.anyio async def test_no_logged_in_string(self): - with patch("koan.probe.shutil.which", return_value="/usr/bin/codex"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/codex"), \ patch("koan.probe._run_cmd", new_callable=AsyncMock, return_value=(0, "Not authenticated", "")): r = await _probe_codex() assert r.available is False @@ -143,7 +143,7 @@ async def test_no_logged_in_string(self): class TestProbeCodexTimeout: @pytest.mark.anyio async def test_auth_timeout(self): - with patch("koan.probe.shutil.which", return_value="/usr/bin/codex"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/codex"), \ patch("koan.probe._run_cmd", new_callable=AsyncMock, return_value=(-1, "", "")): r = await _probe_codex() assert r.available is False @@ -170,16 +170,16 @@ async def fake_run_cmd(args): return (0, "codex 0.5.1\n", "") return (-1, "", "") - with patch("koan.probe.shutil.which", return_value="/usr/bin/codex"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/codex"), \ patch("koan.probe._run_cmd", side_effect=fake_run_cmd): r = await _probe_codex() assert r.available is True - with patch("koan.probe.shutil.which", return_value="/usr/bin/codex"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/codex"), \ patch("koan.probe._run_cmd", side_effect=fake_run_cmd): r = await _probe_codex() assert r.available is True - assert r.binary_path == "/usr/bin/codex" + assert r.binary_path == "/fake/bin/codex" assert r.version == "codex 0.5.1" @@ -193,11 +193,11 @@ async def fake_run_cmd(args): return (1, "", "") return (-1, "", "") - with patch("koan.probe.shutil.which", return_value="/usr/bin/codex"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/codex"), \ patch("koan.probe._run_cmd", side_effect=fake_run_cmd): r = await _probe_codex() assert r.available is False - assert r.binary_path == "/usr/bin/codex" + assert r.binary_path == "/fake/bin/codex" assert r.version is None @pytest.mark.anyio @@ -209,11 +209,11 @@ async def fake_run_cmd(args): return (-1, "", "") return (-1, "", "") - with patch("koan.probe.shutil.which", return_value="/usr/bin/codex"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/codex"), \ patch("koan.probe._run_cmd", side_effect=fake_run_cmd): r = await _probe_codex() assert r.available is False - assert r.binary_path == "/usr/bin/codex" + assert r.binary_path == "/fake/bin/codex" # -- Gemini probe -------------------------------------------------------------- @@ -231,7 +231,7 @@ async def test_returns_unavailable(self): class TestProbeGeminiAuthFailure: @pytest.mark.anyio async def test_bad_exit_code(self): - with patch("koan.probe.shutil.which", return_value="/usr/bin/gemini"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/gemini"), \ patch("koan.probe._run_cmd", new_callable=AsyncMock, return_value=(1, "", "")): r = await _probe_gemini() assert r.available is False @@ -240,7 +240,7 @@ async def test_bad_exit_code(self): class TestProbeGeminiTimeout: @pytest.mark.anyio async def test_version_timeout(self): - with patch("koan.probe.shutil.which", return_value="/usr/bin/gemini"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/gemini"), \ patch("koan.probe._run_cmd", new_callable=AsyncMock, return_value=(-1, "", "")): r = await _probe_gemini() assert r.available is False @@ -249,11 +249,11 @@ async def test_version_timeout(self): class TestProbeGeminiSuccess: @pytest.mark.anyio async def test_full_probe(self): - with patch("koan.probe.shutil.which", return_value="/usr/bin/gemini"), \ + with patch("koan.probe.shutil.which", return_value="/fake/bin/gemini"), \ patch("koan.probe._run_cmd", new_callable=AsyncMock, return_value=(0, "gemini 2.0.0\n", "")): r = await _probe_gemini() assert r.available is True - assert r.binary_path == "/usr/bin/gemini" + assert r.binary_path == "/fake/bin/gemini" assert r.version == "gemini 2.0.0" diff --git a/tests/test_projections.py b/tests/test_projections.py index a84cb87..806ad44 100644 --- a/tests/test_projections.py +++ b/tests/test_projections.py @@ -547,7 +547,7 @@ def test_probe_completed_sets_runners(self): def test_installation_created_appends(self): p = Projection() - inst = {"alias": "claude-default", "runner_type": "claude", "binary": "/usr/bin/claude", "extra_args": []} + inst = {"alias": "claude-default", "runner_type": "claude", "binary": "/fake/bin/claude", "extra_args": []} p2 = fold(p, self._e("installation_created", inst)) assert len(p2.config_installations) == 1 assert p2.config_installations[0]["alias"] == "claude-default" @@ -560,24 +560,11 @@ def test_installation_modified_replaces(self): assert len(p2.config_installations) == 1 assert p2.config_installations[0]["binary"] == "/new/claude" - def test_installation_removed_removes_and_cleans_active(self): - inst = {"alias": "my-claude", "runner_type": "claude", "binary": "/usr/bin/claude", "extra_args": []} - p = Projection( - config_installations=[inst], - config_active_installations={"claude": "my-claude"}, - ) + def test_installation_removed(self): + inst = {"alias": "my-claude", "runner_type": "claude", "binary": "/fake/bin/claude", "extra_args": []} + p = Projection(config_installations=[inst]) p2 = fold(p, self._e("installation_removed", {"alias": "my-claude"})) assert p2.config_installations == [] - assert "claude" not in p2.config_active_installations - - def test_installation_removed_does_not_clean_unrelated_active(self): - inst = {"alias": "my-claude", "runner_type": "claude", "binary": "/usr/bin/claude", "extra_args": []} - p = Projection( - config_installations=[inst], - config_active_installations={"claude": "other-claude"}, - ) - p2 = fold(p, self._e("installation_removed", {"alias": "my-claude"})) - assert p2.config_active_installations == {"claude": "other-claude"} def test_profile_created_appends(self): p = Projection() @@ -615,16 +602,6 @@ def test_active_profile_changed(self): p2 = fold(p, self._e("active_profile_changed", {"name": "fast"})) assert p2.config_active_profile == "fast" - def test_active_installation_changed(self): - p = Projection() - p2 = fold(p, self._e("active_installation_changed", {"runner_type": "claude", "alias": "my-claude"})) - assert p2.config_active_installations == {"claude": "my-claude"} - - def test_active_installation_changed_updates_existing(self): - p = Projection(config_active_installations={"claude": "old", "codex": "codex-default"}) - p2 = fold(p, self._e("active_installation_changed", {"runner_type": "claude", "alias": "new"})) - assert p2.config_active_installations == {"claude": "new", "codex": "codex-default"} - def test_scout_concurrency_changed(self): p = Projection() p2 = fold(p, self._e("scout_concurrency_changed", {"value": 16})) diff --git a/tests/test_registry.py b/tests/test_registry.py index f08732c..104fca2 100644 --- a/tests/test_registry.py +++ b/tests/test_registry.py @@ -141,21 +141,18 @@ def test_claude_preferred_for_standard(self): # -- RunnerRegistry.get_installation ------------------------------------------ class TestGetInstallation: - def _make_config(self, installations, active=None): - return KoanConfig( - agent_installations=installations, - active_installations=active or {}, - ) - - def test_active_installation_resolved(self): - inst = AgentInstallation(alias="my-claude", runner_type="claude", binary="/usr/bin/claude") - config = self._make_config([inst], active={"claude": "my-claude"}) + def _make_config(self, installations): + return KoanConfig(agent_installations=installations) + + def test_run_installation_resolved(self): + inst = AgentInstallation(alias="my-claude", runner_type="claude", binary="/fake/bin/claude") + config = self._make_config([inst]) reg = RunnerRegistry() - result = reg.get_installation("claude", config) + result = reg.get_installation("claude", config, run_installations={"claude": "my-claude"}) assert result is inst def test_fallback_to_first_installation(self): - inst = AgentInstallation(alias="default-codex", runner_type="codex", binary="/usr/bin/codex") + inst = AgentInstallation(alias="default-codex", runner_type="codex", binary="/fake/bin/codex") config = self._make_config([inst]) reg = RunnerRegistry() result = reg.get_installation("codex", config) @@ -168,18 +165,18 @@ def test_missing_installation_raises(self): reg.get_installation("claude", config) assert exc_info.value.diagnostic.code == "no_installation" - def test_active_alias_configured_but_missing_raises(self): - inst = AgentInstallation(alias="real-claude", runner_type="claude", binary="/usr/bin/claude") - config = self._make_config([inst], active={"claude": "ghost-alias"}) + def test_run_alias_configured_but_missing_raises(self): + inst = AgentInstallation(alias="real-claude", runner_type="claude", binary="/fake/bin/claude") + config = self._make_config([inst]) reg = RunnerRegistry() with pytest.raises(RunnerError) as exc_info: - reg.get_installation("claude", config) + reg.get_installation("claude", config, run_installations={"claude": "ghost-alias"}) assert exc_info.value.diagnostic.code == "no_installation" assert "ghost-alias" in exc_info.value.diagnostic.message def test_fallback_only_when_no_active_alias(self): - inst = AgentInstallation(alias="default-codex", runner_type="codex", binary="/usr/bin/codex") - config = self._make_config([inst], active={}) + inst = AgentInstallation(alias="default-codex", runner_type="codex", binary="/fake/bin/codex") + config = self._make_config([inst]) reg = RunnerRegistry() result = reg.get_installation("codex", config) assert result is inst @@ -188,19 +185,16 @@ def test_fallback_only_when_no_active_alias(self): # -- RunnerRegistry.resolve_installation --------------------------------------- class TestResolveInstallation: - def _make_config(self, installations, active=None): - return KoanConfig( - agent_installations=installations, - active_installations=active or {}, - ) + def _make_config(self, installations): + return KoanConfig(agent_installations=installations) - def test_returns_active_when_binary_exists(self, tmp_path): + def test_returns_installation_when_binary_exists(self, tmp_path): binary = tmp_path / "claude" binary.touch() inst = AgentInstallation(alias="my-claude", runner_type="claude", binary=str(binary)) - config = self._make_config([inst], active={"claude": "my-claude"}) + config = self._make_config([inst]) reg = RunnerRegistry() - result = reg.resolve_installation("claude", config) + result = reg.resolve_installation("claude", config, run_installations={"claude": "my-claude"}) assert result is inst def test_raises_when_binary_missing(self): diff --git a/tests/test_subagent.py b/tests/test_subagent.py index 5b6d843..b85700f 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -37,6 +37,7 @@ class FakeAppState: frozen_logs: list = field(default_factory=list) epic_dir: str | None = None projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) + run_installations: dict = field(default_factory=dict) _active_processes: dict = field(default_factory=dict) diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index bf85f87..5b6d061 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -24,7 +24,7 @@ def _make_probe_results() -> list[ProbeResult]: return [ ProbeResult( - runner_type="claude", available=True, binary_path="/usr/bin/claude", version="1.0", + runner_type="claude", available=True, binary_path="/fake/bin/claude", version="1.0", models=[ ModelInfo(alias="opus", display_name="Opus", thinking_modes=frozenset({"disabled", "low", "medium", "high", "xhigh"}), @@ -179,7 +179,7 @@ def test_start_run_accepts_installation_selection(client, app_state, tmp_path): "installations": {"claude": "my-claude"}, }) assert resp.status_code == 200 - assert app_state.config.active_installations["claude"] == "my-claude" + assert app_state.run_installations["claude"] == "my-claude" def test_start_run_rejects_missing_binary(client, app_state): @@ -189,7 +189,7 @@ def test_start_run_rejects_missing_binary(client, app_state): app_state.config.agent_installations = [ AgentInstallation(alias="broken", runner_type="claude", binary="/nonexistent/claude"), ] - app_state.config.active_installations = {"claude": "broken"} + app_state.run_installations = {"claude": "broken"} resp = client.post("/api/start-run", json={ "task": "build something", "profile": "balanced", @@ -547,13 +547,12 @@ def test_start_run_unknown_profile_rejected(client, app_state): def test_agents_list(client, app_state): app_state.config.agent_installations.append(AgentInstallation( - alias="my-claude", runner_type="claude", binary="/usr/bin/claude", extra_args=[], + alias="my-claude", runner_type="claude", binary="/fake/bin/claude", extra_args=[], )) resp = client.get("/api/agents") assert resp.status_code == 200 data = resp.json() assert "installations" in data - assert "active_installations" in data aliases = [inst["alias"] for inst in data["installations"]] assert "my-claude" in aliases assert len(data["installations"]) >= 1 @@ -563,7 +562,7 @@ def test_agents_create_and_delete(client, app_state): resp = client.post("/api/agents", json={ "alias": "test-agent", "runner_type": "claude", - "binary": "/usr/bin/claude", + "binary": "/fake/bin/claude", "extra_args": [], }) assert resp.status_code == 200 @@ -581,7 +580,7 @@ def test_agents_create_and_delete(client, app_state): class TestProbeRefresh: def test_probe_refresh_triggers_restate(self, client, app_state): fresh_probes = [ - ProbeResult(runner_type="claude", available=True, binary_path="/usr/bin/claude", version="2.0"), + ProbeResult(runner_type="claude", available=True, binary_path="/fake/bin/claude", version="2.0"), ProbeResult(runner_type="codex", available=True), ] fresh_profile = Profile(name="balanced", tiers={ @@ -617,15 +616,6 @@ def test_probe_no_refresh_skips_restate(self, client, app_state): assert len(data["runners"]) == 3 -def test_agents_set_active(client, app_state): - app_state.config.agent_installations.append(AgentInstallation( - alias="my-claude", runner_type="claude", binary="/usr/bin/claude", extra_args=[], - )) - resp = client.put("/api/agents/claude/active", json={"alias": "my-claude"}) - assert resp.status_code == 200 - assert resp.json()["ok"] is True - assert app_state.config.active_installations.get("claude") == "my-claude" - # -- SSE endpoint HTTP-level tests ------------------------------------------- From e966c54636d4efdefe0a01b49b7359a41341fa7c Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 15:34:34 +0700 Subject: [PATCH 225/412] rich activity feed: thinking cards, step headers, tool detail MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ActivityEntry gets type discriminator: 'tool' | 'thinking' | 'step' - Store accumulates thinking deltas into thinkingBuffer with timer - Thinking buffer flushed to card on tool_called/step_advanced/stream_cleared - Step markers inserted on agent_step_advanced (skip 0→1 bootstrap) - ActiveThinkingCard shows live content + ticking duration while LLM reasons - ThinkingCard shows completed thinking with duration, collapsible for long content - StepHeader shows 'step N/M StepName' as a visual separator - Backend: total_steps added to agent_step_advanced event payload - Backend: agent_step_advanced appended to activity_log for snapshot recovery - useElapsedBetween hook: ticks when live, static when completed --- frontend/src/components/ActivityFeed.tsx | 120 +++++++++++++++---- frontend/src/hooks/useElapsed.ts | 25 ++++ frontend/src/store/index.ts | 143 ++++++++++++++++++++--- frontend/src/styles/layout.css | 23 ++++ koan/events.py | 3 + koan/projections.py | 16 ++- koan/web/mcp_endpoint.py | 2 +- tests/test_projections.py | 12 +- 8 files changed, 294 insertions(+), 50 deletions(-) diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index cd995dd..adbe877 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -1,11 +1,94 @@ -import { useRef } from 'react' -import { useStore } from '../store/index' +import { useRef, useState } from 'react' +import { useStore, ActivityEntry } from '../store/index' import { useAutoScroll } from '../hooks/useAutoScroll' +import { useElapsedBetween } from '../hooks/useElapsed' + +function ThinkingCard({ entry }: { entry: ActivityEntry }) { + const [expanded, setExpanded] = useState(false) + const elapsed = useElapsedBetween(entry.thinkingStartedAt, entry.thinkingEndedAt) + const content = entry.thinkingContent || '' + const isLong = content.length > 300 + + return ( +
+
+ thinking + {elapsed && {elapsed}} +
+ {content && ( +
+ {content} +
+ )} + {isLong && !expanded && ( +
setExpanded(true)}> + show more +
+ )} +
+ ) +} + +function ActiveThinkingCard() { + const thinkingBuffer = useStore(s => s.thinkingBuffer) + const thinkingStartedAt = useStore(s => s.thinkingStartedAt) + const elapsed = useElapsedBetween(thinkingStartedAt, null) + + if (!thinkingBuffer) return null + + return ( +
+
+ thinking + {elapsed && {elapsed}} +
+
+ {thinkingBuffer} +
+
+ ) +} + +function StepHeader({ entry }: { entry: ActivityEntry }) { + const label = entry.totalSteps + ? `step ${entry.step}/${entry.totalSteps}` + : `step ${entry.step}` + + return ( +
+ {label} + {entry.stepName && {entry.stepName}} +
+ ) +} + +function ToolLine({ entry }: { entry: ActivityEntry }) { + return ( +
+ + {entry.inFlight ? '›' : '✓'} + + {entry.tool || ''} + + {entry.summary || ''} + {entry.inFlight && ...} + +
+ ) +} export function ActivityFeed() { const activityLog = useStore(s => s.activityLog) const streamBuffer = useStore(s => s.streamBuffer) const isThinking = useStore(s => s.isThinking) + const thinkingBuffer = useStore(s => s.thinkingBuffer) const scrollRef = useRef(null) useAutoScroll(scrollRef) @@ -13,30 +96,17 @@ export function ActivityFeed() { return (
- {/* Tool call entries — compact lines */} - {activityLog.map((entry, i) => ( -
- - {entry.inFlight ? '›' : '✓'} - - {entry.tool || ''} - - {entry.summary || ''} - {entry.inFlight && ...} - -
- ))} + {activityLog.map((entry, i) => { + if (entry.type === 'thinking') return + if (entry.type === 'step') return + return + })} + + {/* Active thinking card — shown while LLM is reasoning */} + {isThinking && thinkingBuffer && } - {/* Thinking indicator — shown when LLM is reasoning */} - {isThinking && !streamBuffer && ( + {/* Thinking indicator — no content yet */} + {isThinking && !thinkingBuffer && (
● Thinking… diff --git a/frontend/src/hooks/useElapsed.ts b/frontend/src/hooks/useElapsed.ts index 4ebd5de..5fee46f 100644 --- a/frontend/src/hooks/useElapsed.ts +++ b/frontend/src/hooks/useElapsed.ts @@ -6,6 +6,10 @@ function formatElapsed(ms: number): string { return `${m}m ${String(s % 60).padStart(2, '0')}s` } +function formatSeconds(ms: number): string { + return `${Math.floor(ms / 1000)}s` +} + // useElapsed computes a human-readable elapsed time string that updates every // second. Replaces the DOM-scanning setInterval hack from koan.js that read // data-started-at attributes. @@ -21,3 +25,24 @@ export function useElapsed(startedAt: number): string { return elapsed } + +// useElapsedBetween returns a compact seconds-only elapsed string. +// If endedAt is null, it live-ticks. If both are set, it returns the +// static duration. +export function useElapsedBetween( + startedAt: number | null | undefined, + endedAt: number | null | undefined, +): string | null { + const [now, setNow] = useState(Date.now()) + const ticking = startedAt != null && endedAt == null + + useEffect(() => { + if (!ticking) return + const id = setInterval(() => setNow(Date.now()), 1000) + return () => clearInterval(id) + }, [ticking]) + + if (startedAt == null) return null + const end = endedAt ?? now + return formatSeconds(end - startedAt) +} diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index e8a3627..1d8abfe 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -41,12 +41,23 @@ export interface NotificationEntry { detail?: string } +export type ActivityEntryType = 'tool' | 'thinking' | 'step' + export interface ActivityEntry { + type: ActivityEntryType tool: string summary: string inFlight: boolean callId?: string ts?: string + // Thinking entries + thinkingContent?: string + thinkingStartedAt?: number + thinkingEndedAt?: number + // Step entries + step?: number + stepName?: string + totalSteps?: number } export interface AskOption { @@ -161,6 +172,8 @@ interface KoanState { activityLog: ActivityEntry[] streamBuffer: string isThinking: boolean + thinkingBuffer: string + thinkingStartedAt: number | null // Notifications notifications: NotificationEntry[] @@ -225,6 +238,8 @@ export const useStore = create((set) => ({ activityLog: [], streamBuffer: '', isThinking: false, + thinkingBuffer: '', + thinkingStartedAt: null, notifications: [], activeInteraction: null, artifacts: {}, @@ -323,10 +338,9 @@ export const useStore = create((set) => ({ })) // Transform activity_log - // The backend fold appends tool_called, tool_completed, and thinking as raw - // entries. Reconstruct the collapsed one-entry-per-call view that the live - // applyEvent fold produces: exclude tool_completed (used only to determine - // inFlight state) and thinking (rendered separately as isThinking indicator). + // The backend fold appends tool_called, tool_completed, thinking, and + // agent_step_advanced as raw entries. Reconstruct the rich view with + // thinking cards and step markers. const rawLog = (state['activity_log'] ?? []) as Record[] const completedCallIds = new Set( rawLog @@ -335,13 +349,34 @@ export const useStore = create((set) => ({ .filter(Boolean) ) const activityLog: ActivityEntry[] = rawLog - .filter(e => e['event_type'] !== 'tool_completed' && e['event_type'] !== 'thinking') + .filter(e => e['event_type'] !== 'tool_completed') .map((e) => { + const evtType = e['event_type'] as string + if (evtType === 'thinking') { + return { + type: 'thinking' as const, + tool: 'thinking', + summary: '', + inFlight: false, + thinkingContent: (e['delta'] as string) ?? '', + } + } + if (evtType === 'agent_step_advanced') { + return { + type: 'step' as const, + tool: '', summary: '', + inFlight: false, + step: e['step'] as number, + stepName: (e['step_name'] as string) ?? '', + totalSteps: e['total_steps'] as number | undefined, + } + } const callId = e['call_id'] as string | undefined - const isToolCall = e['event_type'] === 'tool_called' + const isToolCall = evtType === 'tool_called' const inFlight = isToolCall ? !completedCallIds.has(callId ?? '') : false return { - tool: (e['tool'] as string) ?? (e['event_type'] as string) ?? '', + type: 'tool' as const, + tool: (e['tool'] as string) ?? evtType ?? '', summary: (e['summary'] as string) ?? (e['delta'] as string) ?? '', inFlight, callId, @@ -379,6 +414,8 @@ export const useStore = create((set) => ({ activityLog, streamBuffer: (state['stream_buffer'] as string) ?? '', isThinking: false, + thinkingBuffer: '', + thinkingStartedAt: null, completion: completion ?? null, // Configuration configProfiles, @@ -443,20 +480,54 @@ export const useStore = create((set) => ({ case 'agent_step_advanced': { const step = event['step'] as number const stepName = (event['step_name'] as string) ?? '' + const totalSteps = event['total_steps'] as number | undefined const usage = event['usage'] as Record | undefined + + // Flush pending thinking buffer + const flushLog = [...s.activityLog] + let newThinkBuf = s.thinkingBuffer + let newThinkStart = s.thinkingStartedAt + if (s.thinkingBuffer) { + flushLog.push({ + type: 'thinking', tool: 'thinking', summary: '', + inFlight: false, + thinkingContent: s.thinkingBuffer, + thinkingStartedAt: s.thinkingStartedAt ?? undefined, + thinkingEndedAt: Date.now(), + }) + newThinkBuf = '' + newThinkStart = null + } + + // Add step marker (skip step 0 → 1 bootstrap transition) + if (step >= 1) { + flushLog.push({ + type: 'step', tool: '', summary: '', + inFlight: false, + step, stepName, totalSteps, + }) + } + + const updates: Partial = { + ...base, + activityLog: flushLog, + isThinking: false, + thinkingBuffer: newThinkBuf, + thinkingStartedAt: newThinkStart, + } if (s.primaryAgent?.agentId === agentId) { - return { ...base, primaryAgent: { ...s.primaryAgent, step, stepName, + updates.primaryAgent = { ...s.primaryAgent, step, stepName, tokensSent: s.primaryAgent.tokensSent + (usage?.['input_tokens'] ?? 0), tokensReceived: s.primaryAgent.tokensReceived + (usage?.['output_tokens'] ?? 0), - } } + } } else if (agentId && agentId in s.scouts) { const scout = s.scouts[agentId] - return { ...base, scouts: { ...s.scouts, [agentId]: { ...scout, step, stepName, + updates.scouts = { ...s.scouts, [agentId]: { ...scout, step, stepName, tokensSent: scout.tokensSent + (usage?.['input_tokens'] ?? 0), tokensReceived: scout.tokensReceived + (usage?.['output_tokens'] ?? 0), - } } } + } } } - return base + return updates } case 'agent_exited': { @@ -506,14 +577,32 @@ export const useStore = create((set) => ({ // ── Activity ─────────────────────────────────────────────────────── case 'tool_called': { + // Flush pending thinking buffer before tool call + const newLog = [...s.activityLog] + let thinkBuf = s.thinkingBuffer + let thinkStart = s.thinkingStartedAt + if (s.thinkingBuffer) { + newLog.push({ + type: 'thinking', tool: 'thinking', summary: '', + inFlight: false, + thinkingContent: s.thinkingBuffer, + thinkingStartedAt: s.thinkingStartedAt ?? undefined, + thinkingEndedAt: Date.now(), + }) + thinkBuf = '' + thinkStart = null + } const entry: ActivityEntry = { + type: 'tool', tool: (event['tool'] as string) ?? 'tool', summary: (event['summary'] as string) ?? '', inFlight: true, callId: event['call_id'] as string, ts: new Date().toISOString(), } - return { ...base, activityLog: [...s.activityLog, entry], isThinking: false } + newLog.push(entry) + return { ...base, activityLog: newLog, isThinking: false, + thinkingBuffer: thinkBuf, thinkingStartedAt: thinkStart } } case 'tool_completed': { @@ -526,14 +615,34 @@ export const useStore = create((set) => ({ } } - case 'thinking': - return { ...base, isThinking: true } + case 'thinking': { + const delta = (event['delta'] as string) ?? '' + return { + ...base, + isThinking: true, + thinkingBuffer: s.thinkingBuffer + delta, + thinkingStartedAt: s.thinkingStartedAt ?? Date.now(), + } + } case 'stream_delta': return { ...base, streamBuffer: s.streamBuffer + ((event['delta'] as string) ?? ''), isThinking: false } - case 'stream_cleared': - return { ...base, streamBuffer: '', isThinking: false } + case 'stream_cleared': { + // Flush any pending thinking buffer + const clearedLog = [...s.activityLog] + if (s.thinkingBuffer) { + clearedLog.push({ + type: 'thinking', tool: 'thinking', summary: '', + inFlight: false, + thinkingContent: s.thinkingBuffer, + thinkingStartedAt: s.thinkingStartedAt ?? undefined, + thinkingEndedAt: Date.now(), + }) + } + return { ...base, streamBuffer: '', isThinking: false, activityLog: clearedLog, + thinkingBuffer: '', thinkingStartedAt: null } + } // ── Interactions ─────────────────────────────────────────────────── diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index 358ce2a..d82bcee 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -241,6 +241,29 @@ min-width: 0; } +/* Step header -- separates steps in the activity feed */ +.step-header { + display: flex; + align-items: baseline; + gap: var(--space-2); + padding: var(--space-4) 0 var(--space-1); + margin-top: var(--space-2); + border-bottom: 1px solid var(--border); + font-family: var(--font-mono); + font-size: var(--font-size-sm); +} + +.step-header-label { + color: var(--copper); + font-weight: 600; +} + +.step-header-name { + color: var(--text-strong); + font-weight: 500; + text-transform: capitalize; +} + /* Stream output -- wrapping text block for LLM text */ .stream-output { font-family: var(--font-mono); diff --git a/koan/events.py b/koan/events.py index b2107a2..e967e63 100644 --- a/koan/events.py +++ b/koan/events.py @@ -47,10 +47,13 @@ def build_step_advanced( step: int, step_name: str, usage: dict | None = None, + total_steps: int | None = None, ) -> dict: result: dict = {"step": step, "step_name": step_name} if usage is not None: result["usage"] = usage + if total_steps is not None: + result["total_steps"] = total_steps return result diff --git a/koan/projections.py b/koan/projections.py index 7a7ca75..3d476fe 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -171,13 +171,20 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: step = payload.get("step", 0) step_name = payload.get("step_name", "") + # Append to activity_log so snapshots include step markers + step_entry = {"event_type": event_type, "agent_id": agent_id, **payload} + new_log = [*projection.activity_log, step_entry] + if projection.primary_agent and projection.primary_agent.agent_id == agent_id: updated = projection.primary_agent.model_copy(update={ "step": step, "step_name": step_name, }) updated = _accumulate_usage(updated, usage) - return projection.model_copy(update={"primary_agent": updated}) + return projection.model_copy(update={ + "primary_agent": updated, + "activity_log": new_log, + }) elif agent_id and agent_id in projection.scouts: updated = projection.scouts[agent_id].model_copy(update={ "step": step, @@ -186,10 +193,13 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: updated = _accumulate_usage(updated, usage) new_scouts = dict(projection.scouts) new_scouts[agent_id] = updated - return projection.model_copy(update={"scouts": new_scouts}) + return projection.model_copy(update={ + "scouts": new_scouts, + "activity_log": new_log, + }) else: log.warning("fold agent_step_advanced: unknown agent_id=%s", agent_id) - return projection + return projection.model_copy(update={"activity_log": new_log}) case "agent_exited": usage = payload.get("usage") diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index a6fee05..49d3c59 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -160,7 +160,7 @@ async def koan_complete_step(thoughts: str = "") -> str: from ..events import build_step_advanced _app_state.projection_store.push_event( "agent_step_advanced", - build_step_advanced(step_num, step_name), + build_step_advanced(step_num, step_name, total_steps=phase_module.TOTAL_STEPS), agent_id=agent.agent_id, ) diff --git a/tests/test_projections.py b/tests/test_projections.py index 806ad44..818a7c1 100644 --- a/tests/test_projections.py +++ b/tests/test_projections.py @@ -69,8 +69,10 @@ def test_agent_step_advanced_unknown_agent(self): p = Projection() e = self._event("agent_step_advanced", {"step": 1, "step_name": "X"}, agent_id="unknown") r = fold(p, e) - # Unknown agent: unchanged - assert r == p + # Unknown agent: agent state unchanged, but step still appended to activity_log + assert r.primary_agent is None + assert len(r.activity_log) == 1 + assert r.activity_log[0]["event_type"] == "agent_step_advanced" def test_agent_step_advanced_accumulates_usage(self): p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake", output_tokens=10)) @@ -244,12 +246,14 @@ def test_unknown_event_type_unchanged(self): r = fold(p, e) assert r == p - def test_unknown_agent_id_unchanged(self): + def test_unknown_agent_id_step_appended(self): p = Projection() # no agents registered e = VersionedEvent(version=1, event_type="agent_step_advanced", timestamp="2026-01-01T00:00:00Z", agent_id="nonexistent", payload={"step": 1, "step_name": "X"}) r = fold(p, e) - assert r == p + # Agent state unchanged, but step marker still in activity_log + assert r.primary_agent is None + assert len(r.activity_log) == 1 def test_phase_started_empty_payload_returns_empty_phase(self): # Verifies that phase_started with {} payload returns phase="" (not an error). From da7e5827b962dc406ec8866756f696b7386c6a2a Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 15:53:03 +0700 Subject: [PATCH 226/412] =?UTF-8?q?fix:=20claude=20stream=20parsing=20?= =?UTF-8?q?=E2=80=94=20content=20nested=20under=20message=20envelope?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Root cause: claude --output-format stream-json wraps content blocks inside a 'message' object: {type:'assistant', message:{content:[...]}}. The parser was reading data['content'] (top-level) which returned None, silently dropping all thinking blocks, text deltas, and non-MCP tool calls. Also adds --include-partial-messages for real-time streaming: thinking and text arrive as incremental stream_event deltas instead of only in the final assistant message. stream_event deltas set _saw_stream_events flag so the assistant message fallback only emits text/thinking when partial messages are unavailable — tool_use blocks always come from assistant messages. --- koan/runners/claude.py | 42 ++++++++++++--- tests/test_projections.py | 6 +-- tests/test_runners.py | 104 +++++++++++++++++++++++++------------- 3 files changed, 106 insertions(+), 46 deletions(-) diff --git a/koan/runners/claude.py b/koan/runners/claude.py index c679618..9ea493b 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -48,6 +48,7 @@ class ClaudeRunner: def __init__(self, *, subagent_dir: str) -> None: self.subagent_dir = subagent_dir + self._saw_stream_events = False def list_models(self, binary: str) -> list[ModelInfo]: return [ @@ -105,6 +106,7 @@ def build_command( installation.binary, "-p", boot_prompt, "--output-format", "stream-json", "--verbose", + "--include-partial-messages", "--mcp-config", str(config_path), ] if thinking != "disabled": @@ -124,6 +126,8 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: evt_type = data.get("type") + if evt_type == "stream_event": + return self._parse_stream_event(data) if evt_type == "assistant": return self._parse_assistant(data) if evt_type == "result": @@ -133,8 +137,29 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: # -- Private helpers ------------------------------------------------------- + def _parse_stream_event(self, data: dict) -> list[StreamEvent]: + """Handle incremental stream_event deltas from --include-partial-messages.""" + inner = data.get("event") + if not isinstance(inner, dict): + return [] + inner_type = inner.get("type") + if inner_type == "content_block_delta": + self._saw_stream_events = True + delta = inner.get("delta", {}) + delta_type = delta.get("type") + if delta_type == "thinking_delta": + return [StreamEvent(type="thinking", is_thinking=True, content=delta.get("thinking", ""))] + if delta_type == "text_delta": + return [StreamEvent(type="token_delta", content=delta.get("text", ""))] + return [] + def _parse_assistant(self, data: dict) -> list[StreamEvent]: - blocks = data.get("content") + # stream-json wraps content inside a "message" envelope + msg = data.get("message") + if isinstance(msg, dict): + blocks = msg.get("content") + else: + blocks = data.get("content") if not isinstance(blocks, list) or len(blocks) == 0: return [] @@ -143,9 +168,7 @@ def _parse_assistant(self, data: dict) -> list[StreamEvent]: if not isinstance(block, dict): continue block_type = block.get("type") - if block_type == "text": - events.append(StreamEvent(type="token_delta", content=block.get("text", ""))) - elif block_type == "tool_use": + if block_type == "tool_use": raw_name = block.get("name") canonical = _normalize_tool_name(raw_name) # Drop koan MCP tool events -- the MCP endpoint is authoritative @@ -156,10 +179,13 @@ def _parse_assistant(self, data: dict) -> list[StreamEvent]: tool_name=canonical, tool_args=block.get("input"), )) - elif block_type == "thinking": - # Claude stream-json thinking blocks use the "thinking" key for content, - # not "text" (which is used by text blocks). Fall back to "text" as a - # safety net for format variations. + # text and thinking blocks are streamed incrementally via + # stream_event deltas (--include-partial-messages). Only + # emit them from assistant messages as a fallback when no + # stream_events were seen (e.g. partial-messages disabled). + elif block_type == "text" and not self._saw_stream_events: + events.append(StreamEvent(type="token_delta", content=block.get("text", ""))) + elif block_type == "thinking" and not self._saw_stream_events: events.append(StreamEvent( type="thinking", is_thinking=True, diff --git a/tests/test_projections.py b/tests/test_projections.py index 818a7c1..867eb97 100644 --- a/tests/test_projections.py +++ b/tests/test_projections.py @@ -439,7 +439,7 @@ def test_claude_normalizes_Read(self): runner = ClaudeRunner(subagent_dir="/tmp/test") line = json.dumps({ "type": "assistant", - "content": [{"type": "tool_use", "name": "Read", "input": {"file_path": "/tmp/f"}}], + "message": {"content": [{"type": "tool_use", "name": "Read", "input": {"file_path": "/tmp/f"}}]}, }) evts = runner.parse_stream_event(line) assert len(evts) == 1 @@ -451,7 +451,7 @@ def test_claude_normalizes_Bash(self): runner = ClaudeRunner(subagent_dir="/tmp/test") line = json.dumps({ "type": "assistant", - "content": [{"type": "tool_use", "name": "Bash", "input": {"command": "ls"}}], + "message": {"content": [{"type": "tool_use", "name": "Bash", "input": {"command": "ls"}}]}, }) evts = runner.parse_stream_event(line) assert len(evts) == 1 @@ -463,7 +463,7 @@ def test_claude_filters_koan_mcp_tool(self): runner = ClaudeRunner(subagent_dir="/tmp/test") line = json.dumps({ "type": "assistant", - "content": [{"type": "tool_use", "name": "koan_complete_step", "input": {}}], + "message": {"content": [{"type": "tool_use", "name": "koan_complete_step", "input": {}}]}, }) evts = runner.parse_stream_event(line) assert evts == [] diff --git a/tests/test_runners.py b/tests/test_runners.py index 13cc0ef..f350b96 100644 --- a/tests/test_runners.py +++ b/tests/test_runners.py @@ -21,24 +21,70 @@ class TestClaudeRunnerParseStreamEvent: def setup_method(self): self.runner = ClaudeRunner(subagent_dir="/tmp/test-claude") + def _msg(self, content: list) -> str: + """Wrap content blocks in the stream-json message envelope.""" + return json.dumps({"type": "assistant", "message": {"content": content}}) + def test_text_delta(self): - line = json.dumps({"type": "assistant", "content": [{"type": "text", "text": "hello"}]}) + line = self._msg([{"type": "text", "text": "hello"}]) evts = self.runner.parse_stream_event(line) assert evts == [StreamEvent(type="token_delta", content="hello")] def test_tool_call(self): - line = json.dumps({ - "type": "assistant", - "content": [{"type": "tool_use", "name": "bash", "input": {"cmd": "ls"}}], - }) + line = self._msg([{"type": "tool_use", "name": "bash", "input": {"cmd": "ls"}}]) evts = self.runner.parse_stream_event(line) assert evts == [StreamEvent(type="tool_call", tool_name="bash", tool_args={"cmd": "ls"})] def test_thinking_block(self): - line = json.dumps({"type": "assistant", "content": [{"type": "thinking", "text": "hmm"}]}) + line = self._msg([{"type": "thinking", "text": "hmm"}]) evts = self.runner.parse_stream_event(line) assert evts == [StreamEvent(type="thinking", is_thinking=True, content="hmm")] + def test_thinking_block_thinking_key(self): + # Real claude stream-json uses "thinking" key, not "text" + line = self._msg([{"type": "thinking", "thinking": "reasoning here", "signature": "sig"}]) + evts = self.runner.parse_stream_event(line) + assert evts == [StreamEvent(type="thinking", is_thinking=True, content="reasoning here")] + + # -- stream_event (--include-partial-messages) ---------------------------- + + def test_stream_event_thinking_delta(self): + line = json.dumps({ + "type": "stream_event", + "event": {"type": "content_block_delta", "index": 0, + "delta": {"type": "thinking_delta", "thinking": "hmm"}}, + }) + evts = self.runner.parse_stream_event(line) + assert evts == [StreamEvent(type="thinking", is_thinking=True, content="hmm")] + + def test_stream_event_text_delta(self): + line = json.dumps({ + "type": "stream_event", + "event": {"type": "content_block_delta", "index": 0, + "delta": {"type": "text_delta", "text": "hello"}}, + }) + evts = self.runner.parse_stream_event(line) + assert evts == [StreamEvent(type="token_delta", content="hello")] + + def test_stream_event_suppresses_assistant_text(self): + """Once stream_events are seen, assistant text/thinking blocks are skipped.""" + # First: a stream_event sets the flag + delta_line = json.dumps({ + "type": "stream_event", + "event": {"type": "content_block_delta", "index": 0, + "delta": {"type": "text_delta", "text": "hi"}}, + }) + self.runner.parse_stream_event(delta_line) + # Then: assistant message with text and tool_use + msg_line = self._msg([ + {"type": "text", "text": "hi"}, + {"type": "tool_use", "name": "bash", "input": {"cmd": "ls"}}, + ]) + evts = self.runner.parse_stream_event(msg_line) + # text is skipped (already streamed), tool_use preserved + assert len(evts) == 1 + assert evts[0].type == "tool_call" + def test_result_success(self): line = json.dumps({"type": "result", "subtype": "success", "result": "done"}) evts = self.runner.parse_stream_event(line) @@ -52,53 +98,41 @@ def test_invalid_json(self): assert self.runner.parse_stream_event("not json{") == [] def test_multi_block_text_and_tool(self): - line = json.dumps({ - "type": "assistant", - "content": [ - {"type": "text", "text": "calling tool"}, - {"type": "tool_use", "name": "read", "input": {"path": "/a"}}, - ], - }) + line = self._msg([ + {"type": "text", "text": "calling tool"}, + {"type": "tool_use", "name": "read", "input": {"path": "/a"}}, + ]) evts = self.runner.parse_stream_event(line) assert len(evts) == 2 assert evts[0] == StreamEvent(type="token_delta", content="calling tool") assert evts[1] == StreamEvent(type="tool_call", tool_name="read", tool_args={"path": "/a"}) def test_multi_block_thinking_and_text(self): - line = json.dumps({ - "type": "assistant", - "content": [ - {"type": "thinking", "text": "reasoning"}, - {"type": "text", "text": "answer"}, - ], - }) + line = self._msg([ + {"type": "thinking", "text": "reasoning"}, + {"type": "text", "text": "answer"}, + ]) evts = self.runner.parse_stream_event(line) assert len(evts) == 2 assert evts[0] == StreamEvent(type="thinking", is_thinking=True, content="reasoning") assert evts[1] == StreamEvent(type="token_delta", content="answer") def test_multi_block_with_unknown_type_skipped(self): - line = json.dumps({ - "type": "assistant", - "content": [ - {"type": "text", "text": "hello"}, - {"type": "unknown_block"}, - {"type": "tool_use", "name": "bash", "input": {}}, - ], - }) + line = self._msg([ + {"type": "text", "text": "hello"}, + {"type": "unknown_block"}, + {"type": "tool_use", "name": "bash", "input": {}}, + ]) evts = self.runner.parse_stream_event(line) assert len(evts) == 2 assert evts[0].type == "token_delta" assert evts[1].type == "tool_call" def test_multi_block_non_dict_block_skipped(self): - line = json.dumps({ - "type": "assistant", - "content": [ - "not a dict", - {"type": "text", "text": "valid"}, - ], - }) + line = self._msg([ + "not a dict", + {"type": "text", "text": "valid"}, + ]) evts = self.runner.parse_stream_event(line) assert evts == [StreamEvent(type="token_delta", content="valid")] From 5ea4419cc094a7863ed2223e636dc4a97e860064 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 16:50:55 +0700 Subject: [PATCH 227/412] fix: interleave text output chronologically, filter scout activity from main feed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two fixes to the activity feed: 1. Text interleaving: streamBuffer was always rendered at the bottom of the feed. Now text and thinking buffers are flushed into chronological activity entries on transitions (thinking→text, text→thinking, either→tool_call, either→step). Active stream text still shows at the bottom with a cursor while being produced, but gets frozen into a 'text' entry at its correct position when the next event arrives. 2. Primary-agent filtering: all agent events (scouts + primary) were going into the same activityLog. Now tool_called, tool_completed, thinking, stream_delta, and stream_cleared only affect the main activity feed when agentId matches the primary agent. Scout events are still tracked in the agent monitor at the bottom. --- frontend/src/components/ActivityFeed.tsx | 11 +- frontend/src/store/index.ts | 151 ++++++++++++++--------- 2 files changed, 101 insertions(+), 61 deletions(-) diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index adbe877..071f052 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -49,6 +49,14 @@ function ActiveThinkingCard() { ) } +function TextBlock({ entry }: { entry: ActivityEntry }) { + return ( +
+ {entry.textContent} +
+ ) +} + function StepHeader({ entry }: { entry: ActivityEntry }) { const label = entry.totalSteps ? `step ${entry.step}/${entry.totalSteps}` @@ -99,6 +107,7 @@ export function ActivityFeed() { {activityLog.map((entry, i) => { if (entry.type === 'thinking') return if (entry.type === 'step') return + if (entry.type === 'text') return return })} @@ -113,7 +122,7 @@ export function ActivityFeed() {
)} - {/* Stream output — wrapping text block for LLM output */} + {/* Active stream output — text being produced right now */} {streamBuffer && (
{streamBuffer} diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 1d8abfe..e091368 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -41,7 +41,7 @@ export interface NotificationEntry { detail?: string } -export type ActivityEntryType = 'tool' | 'thinking' | 'step' +export type ActivityEntryType = 'tool' | 'thinking' | 'step' | 'text' export interface ActivityEntry { type: ActivityEntryType @@ -58,6 +58,8 @@ export interface ActivityEntry { step?: number stepName?: string totalSteps?: number + // Text entries + textContent?: string } export interface AskOption { @@ -429,6 +431,46 @@ export const useStore = create((set) => ({ // -- Event fold: mirrors backend fold -------------------------------------- applyEvent: (event) => { + // Helpers to flush accumulated buffers into activity entries. + function flushThinkingBuffer(s: KoanState): ActivityEntry[] { + if (!s.thinkingBuffer) return [...s.activityLog] + return [...s.activityLog, { + type: 'thinking', tool: 'thinking', summary: '', + inFlight: false, + thinkingContent: s.thinkingBuffer, + thinkingStartedAt: s.thinkingStartedAt ?? undefined, + thinkingEndedAt: Date.now(), + }] + } + function flushStreamBuffer(s: KoanState): ActivityEntry[] { + if (!s.streamBuffer) return [...s.activityLog] + return [...s.activityLog, { + type: 'text', tool: '', summary: '', + inFlight: false, + textContent: s.streamBuffer, + }] + } + function flushBuffers(s: KoanState): ActivityEntry[] { + let log = [...s.activityLog] + if (s.thinkingBuffer) { + log.push({ + type: 'thinking', tool: 'thinking', summary: '', + inFlight: false, + thinkingContent: s.thinkingBuffer, + thinkingStartedAt: s.thinkingStartedAt ?? undefined, + thinkingEndedAt: Date.now(), + }) + } + if (s.streamBuffer) { + log.push({ + type: 'text', tool: '', summary: '', + inFlight: false, + textContent: s.streamBuffer, + }) + } + return log + } + const eventType = event['event_type'] as string const version = event['version'] as number const agentId = event['agent_id'] as string | null @@ -482,43 +524,33 @@ export const useStore = create((set) => ({ const stepName = (event['step_name'] as string) ?? '' const totalSteps = event['total_steps'] as number | undefined const usage = event['usage'] as Record | undefined + const isPrimary = s.primaryAgent?.agentId === agentId - // Flush pending thinking buffer - const flushLog = [...s.activityLog] - let newThinkBuf = s.thinkingBuffer - let newThinkStart = s.thinkingStartedAt - if (s.thinkingBuffer) { - flushLog.push({ - type: 'thinking', tool: 'thinking', summary: '', - inFlight: false, - thinkingContent: s.thinkingBuffer, - thinkingStartedAt: s.thinkingStartedAt ?? undefined, - thinkingEndedAt: Date.now(), - }) - newThinkBuf = '' - newThinkStart = null - } - - // Add step marker (skip step 0 → 1 bootstrap transition) - if (step >= 1) { - flushLog.push({ - type: 'step', tool: '', summary: '', - inFlight: false, - step, stepName, totalSteps, - }) + // Only add activity entries for the primary agent + let newLog = s.activityLog + if (isPrimary) { + newLog = flushBuffers(s) + if (step >= 1) { + newLog.push({ + type: 'step', tool: '', summary: '', + inFlight: false, + step, stepName, totalSteps, + }) + } } const updates: Partial = { ...base, - activityLog: flushLog, + activityLog: newLog, isThinking: false, - thinkingBuffer: newThinkBuf, - thinkingStartedAt: newThinkStart, + thinkingBuffer: isPrimary ? '' : s.thinkingBuffer, + thinkingStartedAt: isPrimary ? null : s.thinkingStartedAt, + streamBuffer: isPrimary ? '' : s.streamBuffer, } - if (s.primaryAgent?.agentId === agentId) { - updates.primaryAgent = { ...s.primaryAgent, step, stepName, - tokensSent: s.primaryAgent.tokensSent + (usage?.['input_tokens'] ?? 0), - tokensReceived: s.primaryAgent.tokensReceived + (usage?.['output_tokens'] ?? 0), + if (isPrimary) { + updates.primaryAgent = { ...s.primaryAgent!, step, stepName, + tokensSent: s.primaryAgent!.tokensSent + (usage?.['input_tokens'] ?? 0), + tokensReceived: s.primaryAgent!.tokensReceived + (usage?.['output_tokens'] ?? 0), } } else if (agentId && agentId in s.scouts) { const scout = s.scouts[agentId] @@ -575,23 +607,13 @@ export const useStore = create((set) => ({ } // ── Activity ─────────────────────────────────────────────────────── + // Only primary agent events go into the main activity feed. + // Scout activity is shown in the agent monitor at the bottom. case 'tool_called': { - // Flush pending thinking buffer before tool call - const newLog = [...s.activityLog] - let thinkBuf = s.thinkingBuffer - let thinkStart = s.thinkingStartedAt - if (s.thinkingBuffer) { - newLog.push({ - type: 'thinking', tool: 'thinking', summary: '', - inFlight: false, - thinkingContent: s.thinkingBuffer, - thinkingStartedAt: s.thinkingStartedAt ?? undefined, - thinkingEndedAt: Date.now(), - }) - thinkBuf = '' - thinkStart = null - } + if (agentId !== s.primaryAgent?.agentId) return base + // Flush pending buffers before tool call + const newLog = flushBuffers(s) const entry: ActivityEntry = { type: 'tool', tool: (event['tool'] as string) ?? 'tool', @@ -602,10 +624,12 @@ export const useStore = create((set) => ({ } newLog.push(entry) return { ...base, activityLog: newLog, isThinking: false, - thinkingBuffer: thinkBuf, thinkingStartedAt: thinkStart } + thinkingBuffer: '', thinkingStartedAt: null, + streamBuffer: '' } } case 'tool_completed': { + if (agentId !== s.primaryAgent?.agentId) return base const callId = event['call_id'] as string return { ...base, @@ -616,30 +640,37 @@ export const useStore = create((set) => ({ } case 'thinking': { + if (agentId !== s.primaryAgent?.agentId) return base const delta = (event['delta'] as string) ?? '' + // If there was pending stream text, flush it first (text → thinking transition) + const thinkLog = s.streamBuffer ? flushStreamBuffer(s) : s.activityLog return { ...base, isThinking: true, + activityLog: thinkLog, thinkingBuffer: s.thinkingBuffer + delta, thinkingStartedAt: s.thinkingStartedAt ?? Date.now(), + streamBuffer: '', } } - case 'stream_delta': - return { ...base, streamBuffer: s.streamBuffer + ((event['delta'] as string) ?? ''), isThinking: false } + case 'stream_delta': { + if (agentId !== s.primaryAgent?.agentId) return base + // If there was pending thinking, flush it first (thinking → text transition) + const sdLog = s.thinkingBuffer ? flushThinkingBuffer(s) : s.activityLog + return { + ...base, + activityLog: sdLog, + streamBuffer: s.streamBuffer + ((event['delta'] as string) ?? ''), + isThinking: false, + thinkingBuffer: '', + thinkingStartedAt: null, + } + } case 'stream_cleared': { - // Flush any pending thinking buffer - const clearedLog = [...s.activityLog] - if (s.thinkingBuffer) { - clearedLog.push({ - type: 'thinking', tool: 'thinking', summary: '', - inFlight: false, - thinkingContent: s.thinkingBuffer, - thinkingStartedAt: s.thinkingStartedAt ?? undefined, - thinkingEndedAt: Date.now(), - }) - } + if (agentId !== s.primaryAgent?.agentId) return base + const clearedLog = flushBuffers(s) return { ...base, streamBuffer: '', isThinking: false, activityLog: clearedLog, thinkingBuffer: '', thinkingStartedAt: null } } From 0c7da8b8b262ea1e291c3f66458b6d7d72d8c749 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 18:24:55 +0700 Subject: [PATCH 228/412] add --yolo flag: skip all agent permission prompts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When koan is invoked with --yolo, default installations get permission- skipping flags injected into extra_args: - claude: --dangerously-skip-permissions - codex: --dangerously-bypass-approvals-and-sandbox - gemini: --yolo Codex no longer hardcodes --dangerously-bypass-approvals-and-sandbox in build_command — it now comes via extra_args like the other runners, only when --yolo is active. Without --yolo, codex will prompt for permissions. --- koan/__main__.py | 4 +++- koan/runners/codex.py | 1 - koan/state.py | 1 + koan/web/app.py | 18 +++++++++++++++++- 4 files changed, 21 insertions(+), 3 deletions(-) diff --git a/koan/__main__.py b/koan/__main__.py index 29a2509..996d575 100644 --- a/koan/__main__.py +++ b/koan/__main__.py @@ -85,6 +85,8 @@ def main() -> None: parser.add_argument("--skip-build", action="store_true", help="Skip frontend rebuild check") parser.add_argument("-p", "--prompt", type=str, default="", help="Pre-fill the task description") + parser.add_argument("--yolo", action="store_true", + help="Skip all agent permission prompts (dangerous)") args = parser.parse_args() setup_logging(args.log_level) @@ -96,7 +98,7 @@ def main() -> None: config = asyncio.run(load_koan_config()) app_state = AppState(config=config, port=port, open_browser=not args.no_open, - initial_prompt=args.prompt) + initial_prompt=args.prompt, yolo=args.yolo) app = create_app(app_state) host = "127.0.0.1" diff --git a/koan/runners/codex.py b/koan/runners/codex.py index 770f1d3..a7d9b07 100644 --- a/koan/runners/codex.py +++ b/koan/runners/codex.py @@ -60,7 +60,6 @@ def build_command( cmd = [ installation.binary, "exec", "--json", - "--dangerously-bypass-approvals-and-sandbox", "-c", f"mcp_servers.koan.url={mcp_url}", boot_prompt, ] diff --git a/koan/state.py b/koan/state.py index 3007e63..328ce7e 100644 --- a/koan/state.py +++ b/koan/state.py @@ -64,6 +64,7 @@ class AppState: port: int = 8000 open_browser: bool = True initial_prompt: str = "" + yolo: bool = False config_write_lock: asyncio.Lock = field(default_factory=asyncio.Lock) # Installation selections for the current run: runner_type -> alias. # Set when a run starts; cleared when a new run begins. diff --git a/koan/web/app.py b/koan/web/app.py index beede24..d6402dc 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -520,6 +520,13 @@ async def _refresh_probe_state(st: AppState, broadcast: bool = True) -> None: st.probe_results = await probe_all_runners() st.balanced_profile = compute_balanced_profile(st.probe_results) + # --yolo: per-runner permission-skipping flags for default installations + _YOLO_ARGS: dict[str, list[str]] = { + "claude": ["--dangerously-skip-permissions"], + "codex": ["--dangerously-bypass-approvals-and-sandbox"], + "gemini": ["--yolo"], + } + # Auto-create or update default installations from probe results existing_types = {inst.runner_type for inst in st.config.agent_installations} changed = False @@ -528,11 +535,12 @@ async def _refresh_probe_state(st: AppState, broadcast: bool = True) -> None: for pr in st.probe_results: if pr.available and pr.binary_path: if pr.runner_type not in existing_types: + extra = _YOLO_ARGS.get(pr.runner_type, []) if st.yolo else [] inst = AgentInstallation( alias=f"{pr.runner_type}-default", runner_type=pr.runner_type, binary=pr.binary_path, - extra_args=[], + extra_args=extra, ) st.config.agent_installations.append(inst) new_insts.append(inst) @@ -540,8 +548,16 @@ async def _refresh_probe_state(st: AppState, broadcast: bool = True) -> None: else: for inst in st.config.agent_installations: if inst.runner_type == pr.runner_type and inst.alias == f"{pr.runner_type}-default": + need_update = False if inst.binary != pr.binary_path: inst.binary = pr.binary_path + need_update = True + # Sync yolo flags on default installations + yolo_args = _YOLO_ARGS.get(pr.runner_type, []) if st.yolo else [] + if yolo_args and not all(a in inst.extra_args for a in yolo_args): + inst.extra_args = list({*inst.extra_args, *yolo_args}) + need_update = True + if need_update: modified_insts.append(inst) changed = True if changed: From bee4268fd8917dc27a2c1db796f3ae6bac50f9f3 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 18:35:40 +0700 Subject: [PATCH 229/412] agent monitor: numeric counter bar + grouped sections by status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Redesign based on option B from design deck: - Counter bar at top: 4 colored cells showing running/queued/done/failed counts with large numbers and labels - Agents grouped by status with section headers (● running, ✓ done, ✘ failed) - Rows show status icon, role, model, tokens, time, and current step/error - Done agents at 0.7 opacity, failed at full opacity (errors are important) - AgentInfo gains status ('running'|'done'|'failed') and optional error field - agent_exited event sets status and error on completed agents - Replaces old flat table that showed all agents identically as running --- frontend/src/components/AgentMonitor.tsx | 131 +++++++++++++++++------ frontend/src/store/index.ts | 20 ++-- frontend/src/styles/components.css | 82 ++++++++++++++ 3 files changed, 193 insertions(+), 40 deletions(-) diff --git a/frontend/src/components/AgentMonitor.tsx b/frontend/src/components/AgentMonitor.tsx index 8c2b593..c05ec44 100644 --- a/frontend/src/components/AgentMonitor.tsx +++ b/frontend/src/components/AgentMonitor.tsx @@ -1,53 +1,116 @@ -import { useScoutList } from '../store/selectors' +import { useMemo } from 'react' +import { useStore, AgentInfo } from '../store/index' import { useElapsed } from '../hooks/useElapsed' import { formatTokens } from '../utils' -import { AgentInfo } from '../store/index' function AgentRow({ agent }: { agent: AgentInfo }) { const elapsed = useElapsed(agent.startedAt) + const status = agent.status + const statusIcon = status === 'running' ? '›' + : status === 'done' ? '✓' + : status === 'failed' ? '✘' + : '○' + const statusCls = `agent-status-${status}` + const nameCls = `agent-name-${status}` + const doingCls = status === 'failed' ? 'agent-doing-failed' : 'agent-doing-dim' + const doingText = status === 'failed' + ? (agent.error || 'failed') + : status === 'done' + ? 'done' + : (agent.stepName || `step ${agent.step}`) + + return ( +
+ {statusIcon} + {agent.role} + {agent.model ?? '--'} + {formatTokens(agent.tokensSent, agent.tokensReceived)} + {elapsed} + {doingText} +
+ ) +} + +function CounterBar({ running, queued, done, failed }: { + running: number; queued: number; done: number; failed: number +}) { + return ( +
+
+ {running} + running +
+
+ {queued} + queued +
+
+ {done} + done +
+
+ {failed} + failed +
+
+ ) +} + +function SectionHeader({ icon, label, className }: { + icon: string; label: string; className: string +}) { return ( - - {'>>'} - {agent.role} - {agent.model ?? '--'} - - {formatTokens(agent.tokensSent, agent.tokensReceived)} - - {elapsed} - {agent.stepName || `step ${agent.step}`} - +
+ {icon} {label} +
) } export function AgentMonitor() { - const scouts = useScoutList() + const scouts = useStore(s => s.scouts) + const completedAgents = useStore(s => s.completedAgents) + + const { running, done, failed } = useMemo(() => { + const runList = Object.values(scouts) + const doneList = completedAgents.filter(a => a.status === 'done') + const failList = completedAgents.filter(a => a.status === 'failed') + return { running: runList, done: doneList, failed: failList } + }, [scouts, completedAgents]) - if (scouts.length === 0) return null + const total = running.length + done.length + failed.length + if (total === 0) return null return (
-
- Agents -
- - - - - - - - - - - - {scouts.map(a => ( - - ))} - -
- AgentModelTokensTimeDoing
+ + + {running.length > 0 && ( + <> + + {running.map(a => )} + + )} + + {done.length > 0 && ( + <> + + {done.map(a => )} + + )} + + {failed.length > 0 && ( + <> + + {failed.map(a => )} + + )}
) diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index e091368..4336d86 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -9,6 +9,8 @@ export const ALL_PHASES = [ // -- Domain types ------------------------------------------------------------ +export type AgentStatus = 'running' | 'done' | 'failed' + export interface AgentInfo { agentId: string role: string @@ -18,6 +20,8 @@ export interface AgentInfo { startedAt: number // UTC epoch milliseconds tokensSent: number tokensReceived: number + status: AgentStatus + error?: string } export interface ArtifactFile { @@ -134,6 +138,8 @@ function transformAgent(a: Record): AgentInfo { startedAt: (a['started_at_ms'] as number) ?? 0, tokensSent: (a['input_tokens'] as number) ?? 0, tokensReceived: (a['output_tokens'] as number) ?? 0, + status: (a['status'] as AgentStatus) ?? 'running', + error: a['error'] as string | undefined, } } @@ -501,6 +507,7 @@ export const useStore = create((set) => ({ startedAt: (event['started_at_ms'] as number) ?? 0, tokensSent: 0, tokensReceived: 0, + status: 'running', } if (isPrimary) { return { ...base, primaryAgent: agent } @@ -577,20 +584,21 @@ export const useStore = create((set) => ({ // Mirror backend _accumulate_usage: apply final token delta before // moving the agent to completedAgents. - function applyUsage(agent: AgentInfo): AgentInfo { - if (!usage) return agent - return { + const exitStatus: AgentStatus = error ? 'failed' : 'done' + function finalize(agent: AgentInfo): AgentInfo { + const a = usage ? { ...agent, tokensSent: agent.tokensSent + (usage['input_tokens'] ?? 0), tokensReceived: agent.tokensReceived + (usage['output_tokens'] ?? 0), - } + } : agent + return { ...a, status: exitStatus, error: error ?? undefined } } if (s.primaryAgent?.agentId === agentId) { - const finalAgent = applyUsage(s.primaryAgent) + const finalAgent = finalize(s.primaryAgent) return { ...base, primaryAgent: null, completedAgents: [...s.completedAgents, finalAgent], notifications: newNotifs } } else if (agentId && agentId in s.scouts) { - const finalAgent = applyUsage(s.scouts[agentId]) + const finalAgent = finalize(s.scouts[agentId]) const { [agentId]: _, ...rest } = s.scouts return { ...base, scouts: rest, completedAgents: [...s.completedAgents, finalAgent], notifications: newNotifs } } diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 7149852..5cb8c16 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -134,6 +134,88 @@ color: var(--text); } +/* ---- Agent counter bar (option B) ---- */ +.agent-counter-bar { + display: flex; + gap: 2px; + margin-bottom: 14px; +} + +.agent-counter { + flex: 1; + padding: 8px 12px; + text-align: center; +} + +.agent-counter:first-child { border-radius: var(--radius-sm) 0 0 var(--radius-sm); } +.agent-counter:last-child { border-radius: 0 var(--radius-sm) var(--radius-sm) 0; } + +.agent-counter-num { + display: block; + font-family: var(--font-mono); + font-size: 22px; + font-weight: 700; + line-height: 1.2; +} + +.agent-counter-label { + display: block; + font-family: var(--font-mono); + font-size: 9px; + text-transform: uppercase; + letter-spacing: 0.1em; + color: var(--text-muted); +} + +.agent-counter-running { background: var(--copper-bg); } +.agent-counter-running .agent-counter-num { color: var(--copper); } +.agent-counter-queued { background: var(--ochre-bg); } +.agent-counter-queued .agent-counter-num { color: var(--text-muted); } +.agent-counter-done { background: var(--green-bg); } +.agent-counter-done .agent-counter-num { color: var(--green); } +.agent-counter-failed { background: var(--red-bg); } +.agent-counter-failed .agent-counter-num { color: var(--red); } + +/* Hide counter cells with zero count */ +.agent-counter-num:empty + .agent-counter-label { display: none; } + +/* ---- Agent section headers ---- */ +.agent-section-header { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + text-transform: uppercase; + letter-spacing: 0.08em; + padding: 4px 0; + border-bottom: 1px solid var(--border); + margin-bottom: 2px; + margin-top: 8px; +} + +.agent-section-header:first-of-type { margin-top: 0; } +.section-running { color: var(--copper); } +.section-done { color: var(--green); } +.section-failed { color: var(--red); } + +/* ---- Agent row (flex-based, replaces table) ---- */ +.agent-row { + display: flex; + align-items: center; + gap: 10px; + padding: 5px 8px; + font-family: var(--font-mono); + font-size: var(--font-size-sm); +} + +.agent-row-done { opacity: 0.7; } +.agent-row-failed { /* full opacity — errors are important */ } + +.agent-row-icon { width: 14px; text-align: center; flex-shrink: 0; } +.agent-row-name { width: 90px; flex-shrink: 0; } +.agent-row-model { width: 70px; flex-shrink: 0; color: var(--text-muted); } +.agent-row-tokens { width: 60px; flex-shrink: 0; text-align: right; color: var(--text-muted); } +.agent-row-time { width: 55px; flex-shrink: 0; text-align: right; color: var(--text-muted); font-size: var(--font-size-xs); } +.agent-row-doing { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } + /* ---- Card ---- */ .card { background: var(--bg-elevated); From 5cd745498838bdfd9be3944792ce2f4b314bd806 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 18:45:14 +0700 Subject: [PATCH 230/412] fix: close in-flight tool when thinking/text starts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When the LLM starts thinking or producing text output, the previous tool call is necessarily complete. Previously tool_completed was only emitted when the next tool_call arrived, leaving the last tool showing as in-flight while thinking rendered below it — making it look like the thinking belonged to the still-running tool rather than being the LLM's reasoning about what to do next. --- koan/subagent.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/koan/subagent.py b/koan/subagent.py index e863f7e..9d79b8b 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -204,6 +204,17 @@ async def stream_stdout(): line = raw.decode("utf-8", errors="replace").rstrip("\n") events = runner.parse_stream_event(line) for ev in events: + # Close in-flight tool when the LLM moves on to thinking + # or text output -- those signal the previous tool is done. + if ev.type in ("token_delta", "thinking") and last_call_id is not None: + store.push_event( + "tool_completed", + build_tool_completed(last_call_id, last_tool_name), + agent_id=agent_id, + ) + last_call_id = None + last_tool_name = None + if ev.type == "token_delta": agent.token_count["received"] = agent.token_count.get("received", 0) + len(ev.content or "") store.push_event("stream_delta", {"delta": ev.content or ""}, agent_id=agent_id) From 9eac4743dd2c2f38db724860f4f6f46f01f456a1 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 19:12:50 +0700 Subject: [PATCH 231/412] typed tool events: read/write/edit/bash/grep/ls with metadata MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New event types (tool_read, tool_write, tool_edit, tool_bash, tool_grep, tool_ls) carry extracted metadata — file paths, commands, patterns — from runner-specific tool argument formats. Runner parsers extract summaries per tool type: - Claude: file_path, command, pattern, path from block.input - Codex: path/command from JSON-encoded arguments string - Gemini: file_path/path, command from input dict stream_stdout emits typed events based on normalized tool name. Frontend renders tool-specific detail: paths for read/write/edit/ls, commands for bash, patterns for grep. Koan MCP tools (koan_complete_step etc.) filtered from activity feed — already rendered as step headers via the MCP endpoint. Codex function_call_output spurious event removed. 614 tests pass. --- frontend/src/components/ActivityFeed.tsx | 134 +++++++++++++++---- frontend/src/sse/connect.ts | 4 +- frontend/src/store/index.ts | 156 +++++++++++++++++++---- frontend/src/styles/layout.css | 7 +- koan/events.py | 26 ++++ koan/projections.py | 12 ++ koan/runners/base.py | 1 + koan/runners/claude.py | 30 ++++- koan/runners/codex.py | 29 ++++- koan/runners/gemini.py | 19 ++- koan/subagent.py | 42 +++++- tests/test_projections.py | 59 +++++++++ tests/test_runners.py | 111 +++++++++++++++- 13 files changed, 560 insertions(+), 70 deletions(-) diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index 071f052..935df65 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -3,6 +3,8 @@ import { useStore, ActivityEntry } from '../store/index' import { useAutoScroll } from '../hooks/useAutoScroll' import { useElapsedBetween } from '../hooks/useElapsed' +// -- Thinking ------------------------------------------------------------------ + function ThinkingCard({ entry }: { entry: ActivityEntry }) { const [expanded, setExpanded] = useState(false) const elapsed = useElapsedBetween(entry.thinkingStartedAt, entry.thinkingEndedAt) @@ -49,13 +51,7 @@ function ActiveThinkingCard() { ) } -function TextBlock({ entry }: { entry: ActivityEntry }) { - return ( -
- {entry.textContent} -
- ) -} +// -- Step header --------------------------------------------------------------- function StepHeader({ entry }: { entry: ActivityEntry }) { const label = entry.totalSteps @@ -70,19 +66,30 @@ function StepHeader({ entry }: { entry: ActivityEntry }) { ) } +// -- Text block ---------------------------------------------------------------- + +function TextBlock({ entry }: { entry: ActivityEntry }) { + return ( +
+ {entry.textContent} +
+ ) +} + +// -- Tool lines ---------------------------------------------------------------- + +function statusIcon(inFlight: boolean) { + return inFlight ? '›' : '✓' +} + +function statusClass(inFlight: boolean) { + return inFlight ? 'activity-inflight' : 'activity-done' +} + function ToolLine({ entry }: { entry: ActivityEntry }) { return ( -
- - {entry.inFlight ? '›' : '✓'} - +
+ {statusIcon(entry.inFlight)} {entry.tool || ''} {entry.summary || ''} @@ -92,6 +99,90 @@ function ToolLine({ entry }: { entry: ActivityEntry }) { ) } +function ReadLine({ entry }: { entry: ActivityEntry }) { + const detail = entry.lines ? `${entry.file}:${entry.lines}` : (entry.file || '') + return ( +
+ {statusIcon(entry.inFlight)} + read + {detail} + {entry.inFlight && ...} +
+ ) +} + +function WriteLine({ entry }: { entry: ActivityEntry }) { + return ( +
+ {statusIcon(entry.inFlight)} + write + {entry.file || ''} + {entry.inFlight && ...} +
+ ) +} + +function EditLine({ entry }: { entry: ActivityEntry }) { + return ( +
+ {statusIcon(entry.inFlight)} + edit + {entry.file || ''} + {entry.inFlight && ...} +
+ ) +} + +function BashLine({ entry }: { entry: ActivityEntry }) { + return ( +
+ {statusIcon(entry.inFlight)} + bash + {entry.command || ''} + {entry.inFlight && ...} +
+ ) +} + +function GrepLine({ entry }: { entry: ActivityEntry }) { + return ( +
+ {statusIcon(entry.inFlight)} + grep + {entry.pattern || ''} + {entry.inFlight && ...} +
+ ) +} + +function LsLine({ entry }: { entry: ActivityEntry }) { + return ( +
+ {statusIcon(entry.inFlight)} + ls + {entry.path || ''} + {entry.inFlight && ...} +
+ ) +} + +// -- Feed ---------------------------------------------------------------------- + +function renderEntry(entry: ActivityEntry, i: number) { + switch (entry.type) { + case 'thinking': return + case 'step': return + case 'text': return + case 'tool_read': return + case 'tool_write': return + case 'tool_edit': return + case 'tool_bash': return + case 'tool_grep': return + case 'tool_ls': return + default: return + } +} + export function ActivityFeed() { const activityLog = useStore(s => s.activityLog) const streamBuffer = useStore(s => s.streamBuffer) @@ -104,12 +195,7 @@ export function ActivityFeed() { return (
- {activityLog.map((entry, i) => { - if (entry.type === 'thinking') return - if (entry.type === 'step') return - if (entry.type === 'text') return - return - })} + {activityLog.map(renderEntry)} {/* Active thinking card — shown while LLM is reasoning */} {isThinking && thinkingBuffer && } diff --git a/frontend/src/sse/connect.ts b/frontend/src/sse/connect.ts index 4858bc2..e09dd29 100644 --- a/frontend/src/sse/connect.ts +++ b/frontend/src/sse/connect.ts @@ -40,7 +40,9 @@ export function connectSSE(store: KoanStore): EventSource { 'phase_started', 'agent_spawned', 'agent_spawn_failed', 'agent_step_advanced', 'agent_exited', 'workflow_completed', // Activity - 'tool_called', 'tool_completed', 'thinking', 'stream_delta', 'stream_cleared', + 'tool_called', 'tool_completed', + 'tool_read', 'tool_write', 'tool_edit', 'tool_bash', 'tool_grep', 'tool_ls', + 'thinking', 'stream_delta', 'stream_cleared', // Interactions 'questions_asked', 'questions_answered', 'artifact_review_requested', 'artifact_reviewed', diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 4336d86..57b84d4 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -45,7 +45,7 @@ export interface NotificationEntry { detail?: string } -export type ActivityEntryType = 'tool' | 'thinking' | 'step' | 'text' +export type ActivityEntryType = 'tool' | 'tool_read' | 'tool_write' | 'tool_edit' | 'tool_bash' | 'tool_grep' | 'tool_ls' | 'thinking' | 'step' | 'text' export interface ActivityEntry { type: ActivityEntryType @@ -64,6 +64,12 @@ export interface ActivityEntry { totalSteps?: number // Text entries textContent?: string + // Typed tool fields + file?: string + lines?: string + command?: string + pattern?: string + path?: string } export interface AskOption { @@ -358,38 +364,55 @@ export const useStore = create((set) => ({ ) const activityLog: ActivityEntry[] = rawLog .filter(e => e['event_type'] !== 'tool_completed') - .map((e) => { + .flatMap((e): ActivityEntry[] => { const evtType = e['event_type'] as string + const callId = e['call_id'] as string | undefined + const inFlight = callId ? !completedCallIds.has(callId) : false + if (evtType === 'thinking') { - return { - type: 'thinking' as const, - tool: 'thinking', - summary: '', + return [{ type: 'thinking', tool: 'thinking', summary: '', inFlight: false, - thinkingContent: (e['delta'] as string) ?? '', - } + thinkingContent: (e['delta'] as string) ?? '' }] } if (evtType === 'agent_step_advanced') { - return { - type: 'step' as const, - tool: '', summary: '', - inFlight: false, + return [{ type: 'step', tool: '', summary: '', inFlight: false, step: e['step'] as number, stepName: (e['step_name'] as string) ?? '', - totalSteps: e['total_steps'] as number | undefined, - } + totalSteps: e['total_steps'] as number | undefined }] } - const callId = e['call_id'] as string | undefined - const isToolCall = evtType === 'tool_called' - const inFlight = isToolCall ? !completedCallIds.has(callId ?? '') : false - return { - type: 'tool' as const, - tool: (e['tool'] as string) ?? evtType ?? '', - summary: (e['summary'] as string) ?? (e['delta'] as string) ?? '', - inFlight, - callId, - ts: e['ts'] as string | undefined, + if (evtType === 'tool_read') { + return [{ type: 'tool_read', tool: 'read', summary: '', inFlight, callId, + file: (e['file'] as string) ?? '', lines: (e['lines'] as string) ?? '' }] + } + if (evtType === 'tool_write') { + return [{ type: 'tool_write', tool: 'write', summary: '', inFlight, callId, + file: (e['file'] as string) ?? '' }] + } + if (evtType === 'tool_edit') { + return [{ type: 'tool_edit', tool: 'edit', summary: '', inFlight, callId, + file: (e['file'] as string) ?? '' }] + } + if (evtType === 'tool_bash') { + return [{ type: 'tool_bash', tool: 'bash', summary: '', inFlight, callId, + command: (e['command'] as string) ?? '' }] } + if (evtType === 'tool_grep') { + return [{ type: 'tool_grep', tool: 'grep', summary: '', inFlight, callId, + pattern: (e['pattern'] as string) ?? '' }] + } + if (evtType === 'tool_ls') { + return [{ type: 'tool_ls', tool: 'ls', summary: '', inFlight, callId, + path: (e['path'] as string) ?? '' }] + } + if (evtType === 'tool_called') { + const toolName = (e['tool'] as string) ?? '' + // Skip koan MCP tools — rendered as step headers + if (toolName.startsWith('koan_') || toolName.startsWith('mcp__koan')) return [] + return [{ type: 'tool', tool: toolName, + summary: (e['summary'] as string) ?? '', inFlight, callId, + ts: e['ts'] as string | undefined }] + } + return [] }) const completion = state['completion'] as CompletionInfo | null @@ -619,12 +642,14 @@ export const useStore = create((set) => ({ // Scout activity is shown in the agent monitor at the bottom. case 'tool_called': { + const toolName = (event['tool'] as string) ?? 'tool' + // Skip koan MCP tools — rendered as step headers via MCP endpoint + if (toolName.startsWith('koan_') || toolName.startsWith('mcp__koan')) return base if (agentId !== s.primaryAgent?.agentId) return base - // Flush pending buffers before tool call const newLog = flushBuffers(s) const entry: ActivityEntry = { type: 'tool', - tool: (event['tool'] as string) ?? 'tool', + tool: toolName, summary: (event['summary'] as string) ?? '', inFlight: true, callId: event['call_id'] as string, @@ -636,6 +661,85 @@ export const useStore = create((set) => ({ streamBuffer: '' } } + case 'tool_read': { + if (agentId !== s.primaryAgent?.agentId) return base + const newLog = flushBuffers(s) + newLog.push({ + type: 'tool_read', tool: 'read', summary: '', + inFlight: true, callId: event['call_id'] as string, + file: (event['file'] as string) ?? '', + lines: (event['lines'] as string) ?? '', + ts: new Date().toISOString(), + }) + return { ...base, activityLog: newLog, isThinking: false, + thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } + } + + case 'tool_write': { + if (agentId !== s.primaryAgent?.agentId) return base + const newLog = flushBuffers(s) + newLog.push({ + type: 'tool_write', tool: 'write', summary: '', + inFlight: true, callId: event['call_id'] as string, + file: (event['file'] as string) ?? '', + ts: new Date().toISOString(), + }) + return { ...base, activityLog: newLog, isThinking: false, + thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } + } + + case 'tool_edit': { + if (agentId !== s.primaryAgent?.agentId) return base + const newLog = flushBuffers(s) + newLog.push({ + type: 'tool_edit', tool: 'edit', summary: '', + inFlight: true, callId: event['call_id'] as string, + file: (event['file'] as string) ?? '', + ts: new Date().toISOString(), + }) + return { ...base, activityLog: newLog, isThinking: false, + thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } + } + + case 'tool_bash': { + if (agentId !== s.primaryAgent?.agentId) return base + const newLog = flushBuffers(s) + newLog.push({ + type: 'tool_bash', tool: 'bash', summary: '', + inFlight: true, callId: event['call_id'] as string, + command: (event['command'] as string) ?? '', + ts: new Date().toISOString(), + }) + return { ...base, activityLog: newLog, isThinking: false, + thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } + } + + case 'tool_grep': { + if (agentId !== s.primaryAgent?.agentId) return base + const newLog = flushBuffers(s) + newLog.push({ + type: 'tool_grep', tool: 'grep', summary: '', + inFlight: true, callId: event['call_id'] as string, + pattern: (event['pattern'] as string) ?? '', + ts: new Date().toISOString(), + }) + return { ...base, activityLog: newLog, isThinking: false, + thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } + } + + case 'tool_ls': { + if (agentId !== s.primaryAgent?.agentId) return base + const newLog = flushBuffers(s) + newLog.push({ + type: 'tool_ls', tool: 'ls', summary: '', + inFlight: true, callId: event['call_id'] as string, + path: (event['path'] as string) ?? '', + ts: new Date().toISOString(), + }) + return { ...base, activityLog: newLog, isThinking: false, + thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } + } + case 'tool_completed': { if (agentId !== s.primaryAgent?.agentId) return base const callId = event['call_id'] as string diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index d82bcee..6670aa7 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -291,7 +291,12 @@ .activity-detail { color: var(--text-ghost); - padding-left: 12px; + font-size: var(--font-size-xs); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; + flex: 1; + min-width: 0; } /* Monitor -- sticky bottom, sizes to content, centered like activity feed. diff --git a/koan/events.py b/koan/events.py index e967e63..2b2cce2 100644 --- a/koan/events.py +++ b/koan/events.py @@ -71,6 +71,32 @@ def build_tool_called( } +# -- Typed tool event builders (recognized tools with extracted metadata) ----- + +def build_tool_read(call_id: str, file: str, lines: str = "") -> dict: + return {"call_id": call_id, "tool": "read", "file": file, "lines": lines} + + +def build_tool_write(call_id: str, file: str) -> dict: + return {"call_id": call_id, "tool": "write", "file": file} + + +def build_tool_edit(call_id: str, file: str) -> dict: + return {"call_id": call_id, "tool": "edit", "file": file} + + +def build_tool_bash(call_id: str, command: str) -> dict: + return {"call_id": call_id, "tool": "bash", "command": command} + + +def build_tool_grep(call_id: str, pattern: str) -> dict: + return {"call_id": call_id, "tool": "grep", "pattern": pattern} + + +def build_tool_ls(call_id: str, path: str) -> dict: + return {"call_id": call_id, "tool": "ls", "path": path} + + def build_tool_completed( call_id: str, tool: str, diff --git a/koan/projections.py b/koan/projections.py index 3d476fe..b3ff8a1 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -23,6 +23,12 @@ # Activity "tool_called", "tool_completed", + "tool_read", + "tool_write", + "tool_edit", + "tool_bash", + "tool_grep", + "tool_ls", "thinking", "stream_delta", "stream_cleared", @@ -262,6 +268,12 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: "activity_log": [*projection.activity_log, entry], }) + case "tool_read" | "tool_write" | "tool_edit" | "tool_bash" | "tool_grep" | "tool_ls": + entry = {"event_type": event_type, "agent_id": agent_id, **payload} + return projection.model_copy(update={ + "activity_log": [*projection.activity_log, entry], + }) + case "thinking": entry = {"event_type": event_type, "agent_id": agent_id, **payload} return projection.model_copy(update={ diff --git a/koan/runners/base.py b/koan/runners/base.py index b183d73..1fd7318 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -16,6 +16,7 @@ class StreamEvent: is_thinking: bool = False tool_name: str | None = None tool_args: dict | None = None + summary: str | None = None @dataclass(kw_only=True) diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 9ea493b..24115c4 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -40,6 +40,32 @@ def _normalize_tool_name(name: str | None) -> str | None: return _TOOL_NAME_MAP.get(name, name.lower()) +def _extract_tool_summary(tool: str, args: dict) -> str: + """Extract human-readable detail from Claude tool arguments.""" + if tool == "read": + path = args.get("file_path", "") + offset = args.get("offset") + limit = args.get("limit") + if offset is not None and limit is not None: + return f"{path}:{offset}-{offset + limit}" + if offset is not None: + return f"{path}:{offset}+" + start = args.get("start_line") + end = args.get("end_line") + if start is not None and end is not None: + return f"{path}:{start}-{end}" + return path + if tool == "bash": + return args.get("command", "") + if tool in ("write", "edit"): + return args.get("file_path", "") + if tool == "grep": + return args.get("pattern", "") or args.get("query", "") + if tool == "ls": + return args.get("path", "") + return "" + + class ClaudeRunner: name = "claude" supported_thinking_modes: frozenset[ThinkingMode] = frozenset( @@ -174,10 +200,12 @@ def _parse_assistant(self, data: dict) -> list[StreamEvent]: # Drop koan MCP tool events -- the MCP endpoint is authoritative if canonical in KOAN_MCP_TOOLS: continue + args = block.get("input") or {} events.append(StreamEvent( type="tool_call", tool_name=canonical, - tool_args=block.get("input"), + tool_args=args, + summary=_extract_tool_summary(canonical or "", args), )) # text and thinking blocks are streamed incrementally via # stream_event deltas (--include-partial-messages). Only diff --git a/koan/runners/codex.py b/koan/runners/codex.py index a7d9b07..15265f5 100644 --- a/koan/runners/codex.py +++ b/koan/runners/codex.py @@ -24,6 +24,25 @@ def _normalize_tool_name(name: str | None) -> str | None: return _TOOL_NAME_MAP.get(name, name.lower()) +def _extract_tool_summary(tool: str, args_str: str) -> str: + """Extract human-readable detail from Codex tool arguments (JSON string).""" + try: + args = json.loads(args_str) if args_str else {} + except (json.JSONDecodeError, TypeError): + args = {} + if tool == "read": + return args.get("path", "") or args.get("file", "") + if tool == "bash": + return args.get("command", "") or args.get("cmd", "") + if tool in ("write", "edit"): + return args.get("path", "") or args.get("file", "") + if tool == "grep": + return args.get("pattern", "") or args.get("query", "") + if tool == "ls": + return args.get("path", "") + return "" + + class CodexRunner: name = "codex" supported_thinking_modes: frozenset[ThinkingMode] = frozenset({"disabled"}) @@ -102,15 +121,11 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: canonical = _normalize_tool_name(raw_name) if canonical in KOAN_MCP_TOOLS: return [] + args_str = item.get("arguments", "") return [StreamEvent( type="tool_call", tool_name=canonical, - content=item.get("arguments", ""), - )] - elif item_type == "function_call_output": - return [StreamEvent( - type="tool_call", - tool_name="tool_result", - content=(item.get("output") or "")[:100], + content=args_str, + summary=_extract_tool_summary(canonical or "", args_str), )] return [] diff --git a/koan/runners/gemini.py b/koan/runners/gemini.py index a37edcf..f58e938 100644 --- a/koan/runners/gemini.py +++ b/koan/runners/gemini.py @@ -26,6 +26,21 @@ def _normalize_tool_name(name: str | None) -> str | None: return _TOOL_NAME_MAP.get(name, name.lower()) +def _extract_tool_summary(tool: str, args: dict) -> str: + """Extract human-readable detail from Gemini tool arguments.""" + if tool == "read": + return args.get("file_path", "") or args.get("path", "") or args.get("file", "") + if tool == "bash": + return args.get("command", "") or args.get("cmd", "") + if tool in ("write", "edit"): + return args.get("file_path", "") or args.get("path", "") or args.get("file", "") + if tool == "grep": + return args.get("pattern", "") or args.get("query", "") + if tool == "ls": + return args.get("path", "") or args.get("directory", "") + return "" + + class GeminiRunner: name = "gemini" supported_thinking_modes: frozenset[ThinkingMode] = frozenset( @@ -97,10 +112,12 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: canonical = _normalize_tool_name(raw_name) if canonical in KOAN_MCP_TOOLS: return [] + args = data.get("input") or {} return [StreamEvent( type="tool_call", tool_name=canonical, - tool_args=data.get("input"), + tool_args=args, + summary=_extract_tool_summary(canonical or "", args), )] if evt_type == "result": return [StreamEvent(type="turn_complete")] diff --git a/koan/subagent.py b/koan/subagent.py index 9d79b8b..d76b10f 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -20,8 +20,14 @@ build_agent_spawned, build_artifact_reviewed, build_questions_answered, + build_tool_bash, build_tool_called, build_tool_completed, + build_tool_edit, + build_tool_grep, + build_tool_ls, + build_tool_read, + build_tool_write, build_workflow_decided, ) from .logger import get_logger @@ -228,14 +234,38 @@ async def stream_stdout(): build_tool_completed(last_call_id, last_tool_name), agent_id=agent_id, ) - # Open new tool call + # Open new tool call — emit typed event for recognized tools call_id = str(uuid.uuid4()) tool_name = ev.tool_name or "tool" - store.push_event( - "tool_called", - build_tool_called(call_id, tool_name, ev.tool_args or {}, ev.content or ""), - agent_id=agent_id, - ) + summary = ev.summary or "" + if tool_name == "read": + # Separate file path from optional line range (e.g. "foo.py:10-20") + file_part, lines_part = summary, "" + if ":" in summary: + head, tail = summary.rsplit(":", 1) + if tail and (tail[0].isdigit() or "-" in tail): + file_part, lines_part = head, tail + store.push_event( + "tool_read", + build_tool_read(call_id, file_part, lines_part), + agent_id=agent_id, + ) + elif tool_name == "write": + store.push_event("tool_write", build_tool_write(call_id, summary), agent_id=agent_id) + elif tool_name == "edit": + store.push_event("tool_edit", build_tool_edit(call_id, summary), agent_id=agent_id) + elif tool_name == "bash": + store.push_event("tool_bash", build_tool_bash(call_id, summary), agent_id=agent_id) + elif tool_name == "grep": + store.push_event("tool_grep", build_tool_grep(call_id, summary), agent_id=agent_id) + elif tool_name == "ls": + store.push_event("tool_ls", build_tool_ls(call_id, summary), agent_id=agent_id) + else: + store.push_event( + "tool_called", + build_tool_called(call_id, tool_name, ev.tool_args or {}, summary), + agent_id=agent_id, + ) last_call_id = call_id last_tool_name = tool_name elif ev.type == "turn_complete": diff --git a/tests/test_projections.py b/tests/test_projections.py index 867eb97..f184eb7 100644 --- a/tests/test_projections.py +++ b/tests/test_projections.py @@ -160,6 +160,65 @@ def test_stream_cleared(self): assert r.stream_buffer == "" +# -- fold: typed tool events -------------------------------------------------- + +class TestFoldTypedTools: + def _event(self, event_type: str, payload: dict) -> "VersionedEvent": + from koan.projections import VersionedEvent + return VersionedEvent(version=1, event_type=event_type, + timestamp="2026-01-01T00:00:00Z", agent_id="a1", payload=payload) + + def test_tool_read_appended(self): + from koan.projections import Projection, fold + p = Projection() + e = self._event("tool_read", {"call_id": "c1", "tool": "read", "file": "/foo.ts", "lines": ""}) + r = fold(p, e) + assert len(r.activity_log) == 1 + assert r.activity_log[0]["event_type"] == "tool_read" + assert r.activity_log[0]["file"] == "/foo.ts" + + def test_tool_write_appended(self): + from koan.projections import Projection, fold + p = Projection() + e = self._event("tool_write", {"call_id": "c1", "tool": "write", "file": "/out.ts"}) + r = fold(p, e) + assert len(r.activity_log) == 1 + assert r.activity_log[0]["event_type"] == "tool_write" + assert r.activity_log[0]["file"] == "/out.ts" + + def test_tool_edit_appended(self): + from koan.projections import Projection, fold + p = Projection() + e = self._event("tool_edit", {"call_id": "c1", "tool": "edit", "file": "/edit.ts"}) + r = fold(p, e) + assert len(r.activity_log) == 1 + assert r.activity_log[0]["event_type"] == "tool_edit" + + def test_tool_bash_appended(self): + from koan.projections import Projection, fold + p = Projection() + e = self._event("tool_bash", {"call_id": "c1", "tool": "bash", "command": "ls -la"}) + r = fold(p, e) + assert len(r.activity_log) == 1 + assert r.activity_log[0]["command"] == "ls -la" + + def test_tool_grep_appended(self): + from koan.projections import Projection, fold + p = Projection() + e = self._event("tool_grep", {"call_id": "c1", "tool": "grep", "pattern": "def foo"}) + r = fold(p, e) + assert len(r.activity_log) == 1 + assert r.activity_log[0]["pattern"] == "def foo" + + def test_tool_ls_appended(self): + from koan.projections import Projection, fold + p = Projection() + e = self._event("tool_ls", {"call_id": "c1", "tool": "ls", "path": "/src"}) + r = fold(p, e) + assert len(r.activity_log) == 1 + assert r.activity_log[0]["path"] == "/src" + + # -- fold: interactions ------------------------------------------------------- class TestFoldInteractions: diff --git a/tests/test_runners.py b/tests/test_runners.py index f350b96..5100a82 100644 --- a/tests/test_runners.py +++ b/tests/test_runners.py @@ -33,7 +33,7 @@ def test_text_delta(self): def test_tool_call(self): line = self._msg([{"type": "tool_use", "name": "bash", "input": {"cmd": "ls"}}]) evts = self.runner.parse_stream_event(line) - assert evts == [StreamEvent(type="tool_call", tool_name="bash", tool_args={"cmd": "ls"})] + assert evts == [StreamEvent(type="tool_call", tool_name="bash", tool_args={"cmd": "ls"}, summary="")] def test_thinking_block(self): line = self._msg([{"type": "thinking", "text": "hmm"}]) @@ -105,7 +105,7 @@ def test_multi_block_text_and_tool(self): evts = self.runner.parse_stream_event(line) assert len(evts) == 2 assert evts[0] == StreamEvent(type="token_delta", content="calling tool") - assert evts[1] == StreamEvent(type="tool_call", tool_name="read", tool_args={"path": "/a"}) + assert evts[1] == StreamEvent(type="tool_call", tool_name="read", tool_args={"path": "/a"}, summary="") def test_multi_block_thinking_and_text(self): line = self._msg([ @@ -180,7 +180,7 @@ def test_message_delta(self): def test_tool_use(self): line = json.dumps({"type": "tool_use", "name": "read", "input": {"path": "/a"}}) evts = self.runner.parse_stream_event(line) - assert evts == [StreamEvent(type="tool_call", tool_name="read", tool_args={"path": "/a"})] + assert evts == [StreamEvent(type="tool_call", tool_name="read", tool_args={"path": "/a"}, summary="/a")] def test_result_event(self): line = json.dumps({"type": "result"}) @@ -526,3 +526,108 @@ def test_extra_args_at_end(self, tmp_path): assert cmd[-1] == "--verbose" + + +# -- Summary extraction -------------------------------------------------------- + +class TestClaudeSummaryExtraction: + def setup_method(self): + self.runner = ClaudeRunner(subagent_dir="/tmp/test-claude") + + def _msg(self, content): + import json + return json.dumps({"type": "assistant", "message": {"content": content}}) + + def test_read_summary(self): + line = self._msg([{"type": "tool_use", "name": "Read", "input": {"file_path": "/src/foo.ts"}}]) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "/src/foo.ts" + + def test_read_summary_with_offset_limit(self): + line = self._msg([{"type": "tool_use", "name": "Read", "input": {"file_path": "/src/foo.ts", "offset": 10, "limit": 50}}]) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "/src/foo.ts:10-60" + + def test_bash_summary(self): + line = self._msg([{"type": "tool_use", "name": "Bash", "input": {"command": "ls -la"}}]) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "ls -la" + + def test_write_summary(self): + line = self._msg([{"type": "tool_use", "name": "Write", "input": {"file_path": "/src/new.ts"}}]) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "/src/new.ts" + + def test_grep_summary(self): + line = self._msg([{"type": "tool_use", "name": "Grep", "input": {"pattern": "def foo"}}]) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "def foo" + + def test_ls_summary(self): + line = self._msg([{"type": "tool_use", "name": "LS", "input": {"path": "/src"}}]) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "/src" + + def test_unknown_tool_empty_summary(self): + line = self._msg([{"type": "tool_use", "name": "WebFetch", "input": {"url": "http://example.com"}}]) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "" + + +class TestCodexSummaryExtraction: + def setup_method(self): + self.runner = CodexRunner() + + def _item(self, name, args_dict): + import json + return json.dumps({"type": "item.completed", "item": { + "type": "function_call", "name": name, "arguments": json.dumps(args_dict) + }}) + + def test_read_summary(self): + line = self._item("read_file", {"path": "/src/foo.ts"}) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "/src/foo.ts" + + def test_bash_summary(self): + line = self._item("shell", {"command": "npm test"}) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "npm test" + + def test_write_summary(self): + line = self._item("write_file", {"path": "/out/result.ts"}) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "/out/result.ts" + + def test_no_function_call_output_event(self): + """function_call_output should no longer produce a tool_call event.""" + import json + line = json.dumps({"type": "item.completed", "item": { + "type": "function_call_output", "output": "some result" + }}) + evts = self.runner.parse_stream_event(line) + assert evts == [] + + +class TestGeminiSummaryExtraction: + def setup_method(self): + self.runner = GeminiRunner(subagent_dir="/tmp/test-gemini") + + def _tool(self, name, input_dict): + import json + return json.dumps({"type": "tool_use", "name": name, "input": input_dict}) + + def test_read_summary(self): + line = self._tool("read_file", {"file_path": "/src/bar.go"}) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "/src/bar.go" + + def test_bash_summary(self): + line = self._tool("run_bash_command", {"command": "go build"}) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "go build" + + def test_ls_summary(self): + line = self._tool("list_directory", {"path": "/src"}) + evts = self.runner.parse_stream_event(line) + assert evts[0].summary == "/src" From 9fe96ad58db1dfd3328f24651ebc58cd4ade2e95 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 19:22:14 +0700 Subject: [PATCH 232/412] =?UTF-8?q?fix:=20align=20tool=20detail=20text=20?= =?UTF-8?q?=E2=80=94=20fixed-width=20tool=20name=20column?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - .activity-tool: fixed width 42px (fits 'bash', 'read', 'write', 'edit', 'grep') so detail text (paths, commands) starts at the same position - .activity-detail: match parent font-size (was font-size-xs, visually smaller than the tool name) --- frontend/src/styles/layout.css | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index 6670aa7..155ff17 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -223,9 +223,7 @@ .activity-tool { color: var(--text-muted); flex-shrink: 0; - max-width: 180px; - overflow: hidden; - text-overflow: ellipsis; + width: 42px; white-space: nowrap; } @@ -291,7 +289,6 @@ .activity-detail { color: var(--text-ghost); - font-size: var(--font-size-xs); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; From 4bde5aaf4eda41ba8baf17af605b86c2b0dabfc8 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 19:36:33 +0700 Subject: [PATCH 233/412] agent monitor: scout names, queue tracking, last tool display MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Scouts show their label (e.g. 'engine-methods') instead of generic 'scout' label flows from koan_request_scouts q['id'] → task dict → AgentState → build_agent_spawned → agent_spawned event → AgentInfo.label → UI - scout_queued events emitted for all scouts before asyncio.gather; removed from queuedScouts when agent_spawned fires (semaphore acquired) Counter bar now shows real queued count - Running agents show last tool invocation instead of step name All 7 tool event types (tool_read/write/edit/bash/grep/ls/called) update scout.lastTool; falls back to stepName/step when no tool called yet --- frontend/src/components/AgentMonitor.tsx | 32 +++++++++++++++++------ frontend/src/sse/connect.ts | 2 +- frontend/src/store/index.ts | 33 +++++++++++++++++++++++- frontend/src/styles/components.css | 2 ++ koan/events.py | 9 +++++++ koan/projections.py | 18 ++++++++++++- koan/state.py | 1 + koan/subagent.py | 1 + koan/web/mcp_endpoint.py | 12 +++++++++ 9 files changed, 99 insertions(+), 11 deletions(-) diff --git a/frontend/src/components/AgentMonitor.tsx b/frontend/src/components/AgentMonitor.tsx index c05ec44..a03d969 100644 --- a/frontend/src/components/AgentMonitor.tsx +++ b/frontend/src/components/AgentMonitor.tsx @@ -9,8 +9,7 @@ function AgentRow({ agent }: { agent: AgentInfo }) { const statusIcon = status === 'running' ? '›' : status === 'done' ? '✓' - : status === 'failed' ? '✘' - : '○' + : '✘' const statusCls = `agent-status-${status}` const nameCls = `agent-name-${status}` const doingCls = status === 'failed' ? 'agent-doing-failed' : 'agent-doing-dim' @@ -18,12 +17,12 @@ function AgentRow({ agent }: { agent: AgentInfo }) { ? (agent.error || 'failed') : status === 'done' ? 'done' - : (agent.stepName || `step ${agent.step}`) + : (agent.lastTool || agent.stepName || `step ${agent.step}`) return (
{statusIcon} - {agent.role} + {agent.label || agent.role} {agent.model ?? '--'} {formatTokens(agent.tokensSent, agent.tokensReceived)} {elapsed} @@ -70,15 +69,16 @@ function SectionHeader({ icon, label, className }: { export function AgentMonitor() { const scouts = useStore(s => s.scouts) const completedAgents = useStore(s => s.completedAgents) + const queuedScouts = useStore(s => s.queuedScouts) const { running, done, failed } = useMemo(() => { const runList = Object.values(scouts) - const doneList = completedAgents.filter(a => a.status === 'done') - const failList = completedAgents.filter(a => a.status === 'failed') + const doneList = completedAgents.filter(a => a.status === 'done' && a.role === 'scout') + const failList = completedAgents.filter(a => a.status === 'failed' && a.role === 'scout') return { running: runList, done: doneList, failed: failList } }, [scouts, completedAgents]) - const total = running.length + done.length + failed.length + const total = running.length + done.length + failed.length + queuedScouts.length if (total === 0) return null return ( @@ -86,7 +86,7 @@ export function AgentMonitor() {
@@ -98,6 +98,22 @@ export function AgentMonitor() { )} + {queuedScouts.length > 0 && ( + <> + + {queuedScouts.map((q, i) => ( +
+ ○ + {q.label || 'scout'} + -- + -- + -- + queued +
+ ))} + + )} + {done.length > 0 && ( <> diff --git a/frontend/src/sse/connect.ts b/frontend/src/sse/connect.ts index e09dd29..168f353 100644 --- a/frontend/src/sse/connect.ts +++ b/frontend/src/sse/connect.ts @@ -37,7 +37,7 @@ export function connectSSE(store: KoanStore): EventSource { const KNOWN_EVENTS = [ // Lifecycle - 'phase_started', 'agent_spawned', 'agent_spawn_failed', + 'phase_started', 'agent_spawned', 'agent_spawn_failed', 'scout_queued', 'agent_step_advanced', 'agent_exited', 'workflow_completed', // Activity 'tool_called', 'tool_completed', diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 57b84d4..b42fc17 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -22,6 +22,8 @@ export interface AgentInfo { tokensReceived: number status: AgentStatus error?: string + label: string + lastTool: string } export interface ArtifactFile { @@ -146,6 +148,8 @@ function transformAgent(a: Record): AgentInfo { tokensReceived: (a['output_tokens'] as number) ?? 0, status: (a['status'] as AgentStatus) ?? 'running', error: a['error'] as string | undefined, + label: (a['label'] as string) ?? '', + lastTool: (a['lastTool'] as string) ?? '', } } @@ -182,6 +186,9 @@ interface KoanState { // Scout agents — keyed by agentId scouts: Record + // Queued scouts (waiting for semaphore) + queuedScouts: Array<{ scoutId: string; label: string; model: string | null }> + // Activity feed activityLog: ActivityEntry[] streamBuffer: string @@ -249,6 +256,7 @@ export const useStore = create((set) => ({ completedAgents: [], intakeProgress: null, scouts: {}, + queuedScouts: [], activityLog: [], streamBuffer: '', isThinking: false, @@ -447,6 +455,11 @@ export const useStore = create((set) => ({ isThinking: false, thinkingBuffer: '', thinkingStartedAt: null, + queuedScouts: ((state['queued_scouts'] ?? []) as Array<{ scout_id: string; label: string; model: string | null }>).map(q => ({ + scoutId: (q as any).scout_id ?? (q as any).scoutId ?? '', + label: (q as any).label ?? '', + model: (q as any).model ?? null, + })), completion: completion ?? null, // Configuration configProfiles, @@ -531,11 +544,15 @@ export const useStore = create((set) => ({ tokensSent: 0, tokensReceived: 0, status: 'running', + label: (event['label'] as string) ?? '', + lastTool: '', } if (isPrimary) { return { ...base, primaryAgent: agent } } else { - return { ...base, scouts: { ...s.scouts, [agent.agentId]: agent } } + const lbl = (event['label'] as string) ?? '' + const newQueued = s.queuedScouts.filter(q => q.label !== lbl) + return { ...base, scouts: { ...s.scouts, [agent.agentId]: agent }, queuedScouts: newQueued } } } @@ -549,6 +566,15 @@ export const useStore = create((set) => ({ return { ...base, notifications: [...s.notifications, notif] } } + case 'scout_queued': { + const entry = { + scoutId: (event['scout_id'] as string) ?? '', + label: (event['label'] as string) ?? '', + model: (event['model'] as string | null) ?? null, + } + return { ...base, queuedScouts: [...s.queuedScouts, entry] } + } + case 'agent_step_advanced': { const step = event['step'] as number const stepName = (event['step_name'] as string) ?? '' @@ -645,6 +671,11 @@ export const useStore = create((set) => ({ const toolName = (event['tool'] as string) ?? 'tool' // Skip koan MCP tools — rendered as step headers via MCP endpoint if (toolName.startsWith('koan_') || toolName.startsWith('mcp__koan')) return base + if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { + const summary = (event['summary'] as string) ?? '' + const lastTool = summary ? `${toolName} ${summary}` : toolName + return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool } } } + } if (agentId !== s.primaryAgent?.agentId) return base const newLog = flushBuffers(s) const entry: ActivityEntry = { diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 5cb8c16..d73466a 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -195,6 +195,8 @@ .section-running { color: var(--copper); } .section-done { color: var(--green); } .section-failed { color: var(--red); } +.section-queued { color: var(--text-muted); } +.agent-row-queued { opacity: 0.5; } /* ---- Agent row (flex-based, replaces table) ---- */ .agent-row { diff --git a/koan/events.py b/koan/events.py index 2b2cce2..f2e09a0 100644 --- a/koan/events.py +++ b/koan/events.py @@ -15,12 +15,21 @@ def build_agent_spawned(agent: AgentState) -> dict: return { "agent_id": agent.agent_id, "role": agent.role, + "label": agent.label, "model": agent.model, "is_primary": agent.is_primary, "started_at_ms": int(agent.started_at.timestamp() * 1000), } +def build_scout_queued(scout_id: str, label: str, model: str | None = None) -> dict: + return { + "scout_id": scout_id, + "label": label, + "model": model, + } + + def build_agent_exited( exit_code: int, error: str | None = None, diff --git a/koan/projections.py b/koan/projections.py index b3ff8a1..1d550a2 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -20,6 +20,7 @@ "agent_step_advanced", "agent_exited", "workflow_completed", + "scout_queued", # Activity "tool_called", "tool_completed", @@ -96,6 +97,8 @@ class Projection(BaseModel): artifacts: dict[str, dict] = Field(default_factory=dict) # keyed by path notifications: list[dict] = Field(default_factory=list) # derived from error events + queued_scouts: list[dict] = Field(default_factory=list) + # Completion completion: dict | None = None @@ -158,7 +161,20 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: else: new_scouts = dict(projection.scouts) new_scouts[eid] = new_agent - return projection.model_copy(update={"scouts": new_scouts}) + # Remove from queued_scouts when scout starts running + lbl = payload.get("label", "") + new_queued = [s for s in projection.queued_scouts if s.get("label") != lbl] + return projection.model_copy(update={"scouts": new_scouts, "queued_scouts": new_queued}) + + case "scout_queued": + entry = { + "scout_id": payload.get("scout_id", ""), + "label": payload.get("label", ""), + "model": payload.get("model"), + } + return projection.model_copy(update={ + "queued_scouts": [*projection.queued_scouts, entry], + }) case "agent_spawn_failed": notification = { diff --git a/koan/state.py b/koan/state.py index 328ce7e..3ef4d4e 100644 --- a/koan/state.py +++ b/koan/state.py @@ -35,6 +35,7 @@ class AgentState: role: SubagentRole subagent_dir: str epic_dir: str = "" + label: str = "" step: int = 0 phase_module: Any = None phase_ctx: Any = None diff --git a/koan/subagent.py b/koan/subagent.py index d76b10f..40aec65 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -156,6 +156,7 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None role=role, subagent_dir=subagent_dir, epic_dir=task.get("epic_dir", ""), + label=task.get("label", ""), step=0, phase_module=phase_module, phase_ctx=phase_ctx, diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 49d3c59..d6dfa98 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -225,6 +225,7 @@ async def koan_request_scouts(questions: list[dict] | None = None) -> str: ) scout_tasks.append({ "role": "scout", + "label": scout_id, "epic_dir": epic_dir, "subagent_dir": subagent_dir, "question": q.get("prompt", ""), @@ -255,6 +256,17 @@ async def run_scout(scout_task: dict) -> str | None: except FileNotFoundError: return None + # Emit queued events for all scouts before concurrency-limited execution + from ..events import build_scout_queued + for st in scout_tasks: + _app_state.projection_store.push_event( + "scout_queued", + build_scout_queued( + scout_id=st.get("label", ""), + label=st.get("label", ""), + ), + ) + results = await asyncio.gather(*[run_scout(t) for t in scout_tasks]) findings = [r for r in results if r is not None] From 72f54912fe40f15bc3d0ff16afc03ff7e11c1c3c Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 19:46:05 +0700 Subject: [PATCH 234/412] fix: track scout lastTool for all typed tool events All 6 typed tool events (tool_read, tool_write, tool_edit, tool_bash, tool_grep, tool_ls) now update scout.lastTool, not just generic tool_called. Previously these events returned base for non-primary agents, so the agent monitor showed stale step names instead of the scout's actual current activity. --- frontend/src/store/index.ts | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index b42fc17..14a497d 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -693,6 +693,12 @@ export const useStore = create((set) => ({ } case 'tool_read': { + if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { + const f = (event['file'] as string) ?? '' + const l = (event['lines'] as string) ?? '' + const lastTool = l ? `read ${f}:${l}` : `read ${f}` + return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool } } } + } if (agentId !== s.primaryAgent?.agentId) return base const newLog = flushBuffers(s) newLog.push({ @@ -707,6 +713,9 @@ export const useStore = create((set) => ({ } case 'tool_write': { + if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { + return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool: `write ${(event['file'] as string) ?? ''}` } } } + } if (agentId !== s.primaryAgent?.agentId) return base const newLog = flushBuffers(s) newLog.push({ @@ -720,6 +729,9 @@ export const useStore = create((set) => ({ } case 'tool_edit': { + if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { + return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool: `edit ${(event['file'] as string) ?? ''}` } } } + } if (agentId !== s.primaryAgent?.agentId) return base const newLog = flushBuffers(s) newLog.push({ @@ -733,6 +745,9 @@ export const useStore = create((set) => ({ } case 'tool_bash': { + if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { + return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool: `bash ${(event['command'] as string) ?? ''}` } } } + } if (agentId !== s.primaryAgent?.agentId) return base const newLog = flushBuffers(s) newLog.push({ @@ -746,6 +761,9 @@ export const useStore = create((set) => ({ } case 'tool_grep': { + if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { + return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool: `grep ${(event['pattern'] as string) ?? ''}` } } } + } if (agentId !== s.primaryAgent?.agentId) return base const newLog = flushBuffers(s) newLog.push({ @@ -759,6 +777,9 @@ export const useStore = create((set) => ({ } case 'tool_ls': { + if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { + return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool: `ls ${(event['path'] as string) ?? ''}` } } } + } if (agentId !== s.primaryAgent?.agentId) return base const newLog = flushBuffers(s) newLog.push({ From 12a8415cefd979c47fdb17dd17553d493191bde9 Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 20:10:01 +0700 Subject: [PATCH 235/412] fix: missing thinking after scouts, empty question options, monitor collapse MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three fixes: 1. Thinking tokens lost after long MCP calls (koan_request_scouts): _saw_stream_events was set True permanently, suppressing thinking/text from assistant messages. If the CLI stops sending stream_event deltas after a long MCP tool (resumes with assistant messages directly), thinking was silently dropped. Fix: reset the flag on message_start stream_event, so each new turn gets a fresh chance at stream_events. 2. Empty question option labels in AskWizard: the LLM sends options in varying formats through the MCP tool. The store now normalizes options — handles string options, and tries label/text/value/option keys for dict options. Also normalizes question text via question/text/prompt. 3. Agent monitor doesn't collapse after scouts complete: the monitor showed all 10 done scouts taking up 40vh even when no agents are active. Now collapses to just the counter bar when no running/queued agents remain. --- frontend/src/components/AgentMonitor.tsx | 68 +++++++++++++----------- frontend/src/store/index.ts | 27 ++++++++-- koan/runners/claude.py | 6 +++ 3 files changed, 68 insertions(+), 33 deletions(-) diff --git a/frontend/src/components/AgentMonitor.tsx b/frontend/src/components/AgentMonitor.tsx index a03d969..6a41635 100644 --- a/frontend/src/components/AgentMonitor.tsx +++ b/frontend/src/components/AgentMonitor.tsx @@ -81,6 +81,10 @@ export function AgentMonitor() { const total = running.length + done.length + failed.length + queuedScouts.length if (total === 0) return null + // Collapse to just the counter bar when nothing is active + const hasActive = running.length > 0 || queuedScouts.length > 0 + const collapsed = !hasActive + return (
@@ -91,40 +95,44 @@ export function AgentMonitor() { failed={failed.length} /> - {running.length > 0 && ( + {!collapsed && ( <> - - {running.map(a => )} - - )} + {running.length > 0 && ( + <> + + {running.map(a => )} + + )} - {queuedScouts.length > 0 && ( - <> - - {queuedScouts.map((q, i) => ( -
- ○ - {q.label || 'scout'} - -- - -- - -- - queued -
- ))} - - )} + {queuedScouts.length > 0 && ( + <> + + {queuedScouts.map((q, i) => ( +
+ ○ + {q.label || 'scout'} + -- + -- + -- + queued +
+ ))} + + )} - {done.length > 0 && ( - <> - - {done.map(a => )} - - )} + {done.length > 0 && ( + <> + + {done.map(a => )} + + )} - {failed.length > 0 && ( - <> - - {failed.map(a => )} + {failed.length > 0 && ( + <> + + {failed.map(a => )} + + )} )}
diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 14a497d..814281f 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -842,10 +842,31 @@ export const useStore = create((set) => ({ // ── Interactions ─────────────────────────────────────────────────── case 'questions_asked': { + // Normalize questions: options may arrive as strings or dicts + // with varying key names from the LLM. + const rawQs = (event['questions'] as Record[]) ?? [] + const questions: AskQuestion[] = rawQs.map(q => { + const rawOpts = (q['options'] ?? []) as (string | Record)[] + const options: AskOption[] = rawOpts.map(o => { + if (typeof o === 'string') return { value: o, label: o } + const label = (o['label'] ?? o['text'] ?? o['value'] ?? o['option'] ?? '') as string + const value = (o['value'] ?? o['label'] ?? o['text'] ?? label) as string + return { + value, + label, + recommended: (o['recommended'] as boolean) ?? false, + } + }) + return { + question: (q['question'] ?? q['text'] ?? q['prompt'] ?? '') as string, + multi: (q['multi'] as boolean) ?? false, + options, + allow_other: (q['allow_other'] as boolean) ?? undefined, + context: (q['context'] ?? q['description'] ?? q['rationale']) as string | undefined, + } + }) const interaction: Interaction = { - type: 'ask', - token: event['token'] as string, - questions: (event['questions'] as AskQuestion[]) ?? [], + type: 'ask', token: event['token'] as string, questions, } return { ...base, activeInteraction: interaction } } diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 24115c4..5547501 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -169,6 +169,12 @@ def _parse_stream_event(self, data: dict) -> list[StreamEvent]: if not isinstance(inner, dict): return [] inner_type = inner.get("type") + if inner_type == "message_start": + # New assistant turn — reset the flag so that if this turn + # doesn't produce content_block_delta events (e.g. after a + # long MCP call), the assistant message fallback kicks in. + self._saw_stream_events = False + return [] if inner_type == "content_block_delta": self._saw_stream_events = True delta = inner.get("delta", {}) From 19a1cfa533f2f383d023ad15775280a45597bdaf Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 20:19:25 +0700 Subject: [PATCH 236/412] fix: agent name truncates instead of wrapping to multiple lines agent-row-name: nowrap + ellipsis, min 90px / max 200px so long scout labels like 'spec-architecture-etag' stay on one line --- frontend/src/styles/components.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index d73466a..2a20aae 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -212,7 +212,7 @@ .agent-row-failed { /* full opacity — errors are important */ } .agent-row-icon { width: 14px; text-align: center; flex-shrink: 0; } -.agent-row-name { width: 90px; flex-shrink: 0; } +.agent-row-name { min-width: 90px; max-width: 200px; flex-shrink: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .agent-row-model { width: 70px; flex-shrink: 0; color: var(--text-muted); } .agent-row-tokens { width: 60px; flex-shrink: 0; text-align: right; color: var(--text-muted); } .agent-row-time { width: 55px; flex-shrink: 0; text-align: right; color: var(--text-muted); font-size: var(--font-size-xs); } From 7bca7fc7444e38a3c8004b2f70c87d436532604f Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 20:29:05 +0700 Subject: [PATCH 237/412] =?UTF-8?q?fix:=20snapshot=20reconstruction=20?= =?UTF-8?q?=E2=80=94=20filter=20scouts,=20merge=20thinking,=20skip=20boots?= =?UTF-8?q?trap?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Snapshot applySnapshot had two critical bugs: - All agents' events showed in main feed (no primary-agent filter) - Each thinking delta became its own card instead of being merged Now: filter activity_log to primary agent ID, merge consecutive thinking entries into single cards, skip step 0 bootstrap transitions. --- frontend/src/store/index.ts | 37 +++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 814281f..3dc9389 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -361,8 +361,12 @@ export const useStore = create((set) => ({ // Transform activity_log // The backend fold appends tool_called, tool_completed, thinking, and - // agent_step_advanced as raw entries. Reconstruct the rich view with - // thinking cards and step markers. + // agent_step_advanced as raw entries. Reconstruct the rich view: + // - Filter to primary agent only (scout events shown in monitor) + // - Merge consecutive thinking deltas into single cards + // - Skip koan MCP tools (rendered as step headers) + const primaryAgentId = (rawPrimary?.['agent_id'] as string | undefined) + ?? (rawCompleted.find(a => (a['is_primary'] as boolean) ?? false)?.['agent_id'] as string | undefined) const rawLog = (state['activity_log'] ?? []) as Record[] const completedCallIds = new Set( rawLog @@ -370,8 +374,15 @@ export const useStore = create((set) => ({ .map(e => e['call_id'] as string) .filter(Boolean) ) - const activityLog: ActivityEntry[] = rawLog - .filter(e => e['event_type'] !== 'tool_completed') + // Build flat entries, filtering to primary agent + const flatEntries: ActivityEntry[] = rawLog + .filter(e => { + if (e['event_type'] === 'tool_completed') return false + // Filter to primary agent if known + const eid = e['agent_id'] as string | undefined + if (primaryAgentId && eid && eid !== primaryAgentId) return false + return true + }) .flatMap((e): ActivityEntry[] => { const evtType = e['event_type'] as string const callId = e['call_id'] as string | undefined @@ -383,8 +394,10 @@ export const useStore = create((set) => ({ thinkingContent: (e['delta'] as string) ?? '' }] } if (evtType === 'agent_step_advanced') { + const step = e['step'] as number + if (step < 1) return [] // skip bootstrap return [{ type: 'step', tool: '', summary: '', inFlight: false, - step: e['step'] as number, + step, stepName: (e['step_name'] as string) ?? '', totalSteps: e['total_steps'] as number | undefined }] } @@ -414,7 +427,6 @@ export const useStore = create((set) => ({ } if (evtType === 'tool_called') { const toolName = (e['tool'] as string) ?? '' - // Skip koan MCP tools — rendered as step headers if (toolName.startsWith('koan_') || toolName.startsWith('mcp__koan')) return [] return [{ type: 'tool', tool: toolName, summary: (e['summary'] as string) ?? '', inFlight, callId, @@ -422,6 +434,19 @@ export const useStore = create((set) => ({ } return [] }) + // Merge consecutive thinking entries into single cards + const activityLog: ActivityEntry[] = [] + for (const entry of flatEntries) { + if (entry.type === 'thinking') { + const prev = activityLog[activityLog.length - 1] + if (prev?.type === 'thinking') { + // Merge into previous thinking card + prev.thinkingContent = (prev.thinkingContent ?? '') + (entry.thinkingContent ?? '') + continue + } + } + activityLog.push(entry) + } const completion = state['completion'] as CompletionInfo | null From 7e157453cc1690dd6ba8ab074a72cda9b32564bc Mon Sep 17 00:00:00 2001 From: Leon Mergen Date: Tue, 31 Mar 2026 21:07:21 +0700 Subject: [PATCH 238/412] plan: symmetric projection folds MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Defines the target architecture for backend/frontend fold symmetry. Key change: activity_log (raw event append) → conversation (materialized ConversationEntry list with merged thinking, primary-agent filtering, typed tool entries, in-flight tracking). Backend fold produces the same structure the frontend renders. Snapshot sends it. Frontend reads it directly — no re-interpretation. --- plans/2026-02-10-init.md | 2210 +++++++++++++++ plans/2026-03-09-refactoring.md | 2465 +++++++++++++++++ plans/2026-03-13-web-ui-review.md | 510 ++++ plans/2026-03-13-web-ui.md | 1091 ++++++++ plans/2026-03-14-intake-ui.md | 1119 ++++++++ plans/2026-03-14-plan-audit.md | 206 ++ plans/2026-03-16-preact-zustand-rewrite.md | 1703 ++++++++++++ plans/2026-03-21-epic-brief.md | 736 +++++ plans/2026-03-21-ui-layout-redesign.md | 401 +++ plans/2026-03-22-realtime-token-streaming.md | 315 +++ plans/2026-03-23-core-flows.md | 924 ++++++ plans/2026-03-26-koan-debug-step-prompts.md | 493 ++++ plans/2026-03-26-standalone-python-rewrite.md | 1258 +++++++++ plans/2026-03-28-frontend-react-zustand.md | 845 ++++++ plans/2026-03-29-event-sourced-projections.md | 952 +++++++ .../2026-03-31-symmetric-projection-folds.md | 357 +++ plans/intake-dashboard-ux.md | 666 +++++ plans/per-phase-model-selection-plan.md | 199 ++ plans/workflow-orchestrator.md | 1815 ++++++++++++ 19 files changed, 18265 insertions(+) create mode 100644 plans/2026-02-10-init.md create mode 100644 plans/2026-03-09-refactoring.md create mode 100644 plans/2026-03-13-web-ui-review.md create mode 100644 plans/2026-03-13-web-ui.md create mode 100644 plans/2026-03-14-intake-ui.md create mode 100644 plans/2026-03-14-plan-audit.md create mode 100644 plans/2026-03-16-preact-zustand-rewrite.md create mode 100644 plans/2026-03-21-epic-brief.md create mode 100644 plans/2026-03-21-ui-layout-redesign.md create mode 100644 plans/2026-03-22-realtime-token-streaming.md create mode 100644 plans/2026-03-23-core-flows.md create mode 100644 plans/2026-03-26-koan-debug-step-prompts.md create mode 100644 plans/2026-03-26-standalone-python-rewrite.md create mode 100644 plans/2026-03-28-frontend-react-zustand.md create mode 100644 plans/2026-03-29-event-sourced-projections.md create mode 100644 plans/2026-03-31-symmetric-projection-folds.md create mode 100644 plans/intake-dashboard-ux.md create mode 100644 plans/per-phase-model-selection-plan.md create mode 100644 plans/workflow-orchestrator.md diff --git a/plans/2026-02-10-init.md b/plans/2026-02-10-init.md new file mode 100644 index 0000000..13c4e2e --- /dev/null +++ b/plans/2026-02-10-init.md @@ -0,0 +1,2210 @@ +# Koan: Planner Workflow as Pi Extension + +Implementation plan for porting the Claude Code planner skill to a pi coding +agent extension, achieving true inversion of control. + +--- + +## 1. Problem Statement + +The current planner skill (`~/.claude/skills/scripts/skills/planner/`) is a +14-step state machine that orchestrates planning workflows. It suffers from a +fundamental control-flow mismatch: the LLM is in the driver's seat. The script +outputs formatted guidance text and _hopes_ the LLM follows it. Specifically: + +- **No direct LLM calls.** The orchestrator cannot invoke the LLM. It can only + generate guidance text that the LLM reads and (hopefully) acts on. +- **No context control.** The LLM decides what it reads. The script cannot + filter or modify what the LLM sees before each turn. +- **No tool enforcement.** Phase constraints rely on LLM compliance. Nothing + prevents the LLM from editing files during a read-only planning phase. +- **No step enforcement.** The LLM can skip steps, branch unexpectedly, or + ignore routing commands. +- **No real parallel execution.** The LLM must spawn Task subagents and + manually tally PASS/FAIL results. No barrier synchronization. +- **Context window bloat.** Full dispatch format, constraints, and guidance + text accumulate in the conversation, eating context budget. + +## 2. Solution: Pi Extension with Inversion of Control + +Pi extensions run inside the pi process and hook into the agent lifecycle via +events. This gives the orchestrator direct control over what the LLM sees, +which tools it can use, and what happens between turns. Combined with the +ability to spawn isolated subagent processes, this provides the three levels +of LLM interaction the planner needs. + +### 2.1 Two LLM Interaction Levels + +**Level 1: `sendUserMessage()` in the parent session** + +```typescript +pi.sendUserMessage("Capture the context for this planning task..."); +``` + +Triggers a full agent turn in the parent session — the same LLM that has been +participating in the conversation. This is the only mechanism that has access +to the implicit conversational understanding built up over the session. Used +exclusively for context capture (steps 1-2), where the LLM must reflect on +what it knows from the conversation and produce structured output. + +This is the right tool for context capture because the session LLM is the +only entity that actually understands the conversation. A fresh LLM reading a +serialized transcript would lose implicit context — things that were explored, +rejected, understood through back-and-forth. The session LLM was _there_. + +**Level 2: Subagent with event-driven step control** + +```typescript +spawn("pi", [ + "-p", + "-e", + "./extensions/koan.ts", + "--koan-role", + "architect", + "--koan-phase", + "plan-design", + "--koan-plan-dir", + planDir, + "--koan-subagent-dir", + subagentDir, + "Design the architecture for this task...", +]); +``` + +Separate process with an isolated context window. The koan extension loads +inside the subagent and detects its role via the `--koan-role` flag. It then +activates role-specific event hooks that control the subagent's multi-turn +behavior from within — injecting step instructions via `context`, enforcing +tool constraints via `tool_call`, and tracking progress via `turn_end`. This +is the mechanism for all substantial work phases: design, code, docs, QR +decomposition, and QR verification. + +The critical distinction: context capture must happen in the parent session +because that's where the knowledge lives. Everything after context capture +operates on _artifacts_ (context JSON, plan JSON, QR items) that are +self-contained and can be passed to fresh LLM instances in subagents. + +### 2.2 The Self-Loading Extension Pattern + +The key architectural insight is that the koan extension operates in two +distinct modes depending on how it was launched: + +**Parent mode** (no `--koan-role` flag): The extension registers the `/koan` +command and all workflow tools. Tools register unconditionally at init because +pi snapshots the tool list during `_buildRuntime()` -- late registration is +invisible to the LLM. Phase-specific restrictions are enforced at runtime via +`tool_call` event blocking. + +**Subagent mode** (`--koan-role ` flag present): The extension detects +it is running inside a spawned subagent. It activates phase-specific event +hooks that implement a multi-step state machine within the subagent's agent +loop. The subagent runs in `-p` (print) mode -- it processes its initial +prompt and runs until the LLM stops calling tools. The extension steers every +turn of this loop. + +**Flag detection timing:** `getFlag()` returns undefined during init (before +pi's `_buildRuntime()` sets flagValues). Subagent detection must happen in +`before_agent_start` or later, not at init time. + +**Tool dispatch indirection:** Tools are registered at init with execute +callbacks that read from a mutable `WorkflowDispatch` object at call time. +Each phase hooks its handlers into the dispatch when activated and unhooks +when done. This decouples static tool registration (init-time) from dynamic +phase routing (runtime). + +```typescript +export default function koan(pi: ExtensionAPI): void { + // All tools register unconditionally at init. + const dispatch = createDispatch(); + const planRef = createPlanRef(); + registerWorkflowTools(pi, dispatch); + registerPlanGetterTools(pi, planRef); + registerPlanSetterTools(pi, planRef); + registerPlanEntityTools(pi, planRef); + registerQRTools(pi, planRef); + + // Flag detection deferred to before_agent_start. + let dispatched = false; + pi.on("before_agent_start", async () => { + if (dispatched) return; + dispatched = true; + const config = detectSubagentMode(pi); + if (config) { + planRef.dir = pi.getFlag("koan-plan-dir") as string; + await dispatchPhase(pi, config, dispatch, planRef); + } + }); + + // Parent mode: register the /koan command. + const session = createSession(pi, dispatch, planRef); + pi.registerCommand("koan", { ... }); +} +``` + +This means: + +- The same extension file serves both the orchestrator and the workers +- No separate agent definition files needed for role behavior +- The extension's event hooks give true enforcement (not prompt-based hoping) +- Subagents don't need any special setup beyond CLI flags +- All tools are visible to the LLM regardless of phase; runtime blocking + restricts which ones actually execute + +### 2.3 Tool-Call-Driven Step Control + +Step transitions inside subagents use **explicit tool calls**, not implicit +detection. The LLM calls a registered `koan_complete_step` tool to signal it +has finished a step. The tool result contains the next step's instructions. +This keeps the agent loop alive (the tool call prevents early exit) and +delivers the next prompt just-in-time. + +This maps directly to the reference planner's pattern. In the reference +planner, each step script outputs a "NEXT STEP: Command: python3 -m ... +--step N" directive. The LLM runs the bash command, which outputs the next +step's instructions as its result. `koan_complete_step` is the pi extension +equivalent of that bash command -- a tool call whose result IS the next +step's prompt. + +**Why tool calls, not implicit detection or `sendUserMessage`:** + +The agent loop in `-p` mode continues as long as the LLM makes tool calls. +When the LLM produces a text-only response (no tool calls), the loop ends +and the process exits. This means we need an explicit mechanism to: + +1. **Signal step completion.** How would the extension know the LLM has + finished step 2's codebase exploration versus just pausing to think? + Parsing LLM text output for markers is fragile. An explicit tool call + is unambiguous. + +2. **Keep the loop alive.** Between step N and step N+1, the LLM must make + at least one tool call to prevent the agent loop from exiting. The + step-completion tool IS that tool call. + +3. **Deliver the next prompt.** The tool result is a first-class prompt + delivery mechanism -- the LLM reads tool results and acts on them. + Returning the next step's instructions as the tool result is the most + direct delivery path. + +The alternative -- `sendUserMessage()` from `agent_end` to chain separate +agent loops -- works in interactive mode (the orchestrator's context capture +uses this pattern) but fails in `-p` mode because pi exits after the first +agent loop completes. Tool-call-driven transitions work in both modes. + +**Step 1 is special.** There is no prior tool call to deliver step 1's +instructions. The `context` event solves this: before the first LLM call, +the handler replaces the CLI user message with the full step 1 prompt +(including planning context from context.json). After step 1 advances, +the handler becomes a no-op -- subsequent steps arrive via tool results. + +**Event roles in subagents:** + +| Event | Fires when | Subagent use | +| -------------------- | -------------------------- | -------------------------------------- | +| `before_agent_start` | Before first LLM call | Inject role system prompt | +| `context` | Before every LLM call | Inject step 1 prompt (first call only) | +| `tool_call` | Before every tool executes | Block tools that violate step rules | + +**Note:** `turn_end` is not used for step detection or progress tracking in +subagents. It fires unreliably in `-p` mode and cannot be depended on. All +step transitions use tool calls (`koan_complete_step`). Progress updates +happen inside `handleStepComplete` when the step tool fires. + +```typescript +let step = 1; +const TOTAL_STEPS = 6; + +// Step 1: injected by replacing the user message on first LLM call. +// The LLM sees step 1 instructions as its primary task. +pi.on("context", async (event) => { + if (step !== 1 || !step1Prompt) return; + return { + messages: event.messages.map((m: any) => + m.role === "user" ? { ...m, content: step1Prompt } : m, + ), + }; +}); + +// Steps 2-6: delivered as koan_complete_step tool results. +// The `thoughts` parameter captures the model's work output (analysis, +// review, findings) as a tool parameter instead of as text output. This +// ensures models that cannot mix text + tool_call in one response (e.g. +// GPT-5-codex) still advance the workflow reliably. +pi.registerTool({ + name: "koan_complete_step", + description: + "Signal current step is complete. Returns next step instructions.", + parameters: Type.Object({ + thoughts: Type.Optional( + Type.String({ + description: "Your analysis or work output for this step.", + }), + ), + }), + async execute(_toolCallId, params) { + const result = await dispatch.onCompleteStep(params.thoughts); + if (!result.ok) throw new Error(result.error); + return { content: [{ type: "text", text: result.prompt }] }; + }, +}); + +// Tool enforcement per step. +pi.on("tool_call", async (event) => { + if (step < 6 && PLAN_MUTATION_TOOLS.has(event.toolName)) { + return { + block: true, + reason: `Plan mutation only in step 6 (current: ${step})`, + }; + } +}); +``` + +The LLM cannot skip steps because it must call `koan_complete_step` to +receive the next step's instructions. It cannot use forbidden tools because +`tool_call` blocks them. The state machine is enforced by code, not by +prompt compliance. + +This is the direct replacement for the Python scripts' state machine in +`~/.claude/skills/scripts/skills/planner/`. Each Python script's step logic +maps to a step definition in the extension, and each script's "NEXT STEP" +directive maps to the `koan_complete_step` tool result. + +### 2.4 Context Passing to Subagents + +Subagents are isolated processes. They do not inherit the parent session's +conversation history. Context must be explicitly passed. The mechanism: + +1. **Context capture** (in the parent session, via `sendUserMessage()`): + The parent session's LLM — the one that participated in the conversation — + is asked to extract structured context into the 8 categories (task spec, + constraints, entry points, etc.) and write it to `STATE_DIR/context.json` + using the Write tool. This mirrors the original planner's steps 1-2: the + session LLM reflects on the conversation it was part of and produces a + structured handover document. + + The extension controls this via event hooks in the parent session: + - `before_agent_start` / `context`: inject the context capture instructions + - `tool_call`: only allow the Write tool (to write context.json) + - `turn_end`: check that context.json was written and validate structure + - `agent_end`: read context.json, store in WorkflowState, advance phase + +2. **Plan directory** (passed to subagents via `--koan-plan-dir`): The subagent + receives the plan directory path as a CLI flag. It reads `context.json` + from that directory at startup. The system prompt is loaded from a separate + agent definition file (`~/.claude/agents/architect.md`) by the phase + handler, not passed via CLI. + +3. **Task message** (positional argument): The specific task for this subagent + is passed as the `-p` positional argument, which becomes the user message + that triggers the first agent turn. + +4. **Subagent directory** (`--koan-subagent-dir`): A unique working directory + for each subagent run, used for progress reporting (state.json) and log + files (stdout.log, stderr.log). + +```typescript +// Parent orchestrator -- context capture phase +// Context capture runs inside the parent session via sendUserMessage(). +// The session LLM calls koan_store_context when done. +// The koan_store_context tool's completion callback spawns the architect +// synchronously -- the tool call blocks until the subagent exits. + +const result = await spawnArchitect({ + planDir, // contains context.json + plan.json + subagentDir, // unique dir for progress/logs + cwd: ctx.cwd, + extensionPath, +}); +// Architect reads context.json from planDir, writes plan.json there. +``` + +This is the one phase where work happens in the parent session. It must, +because the session LLM is the only entity with the conversational context. +Everything after context capture operates on the self-contained context.json +artifact and runs in isolated subagents. + +### 2.5 Event Hooks for Parent-Mode Control + +In parent mode (interactive session where the user typed `/koan`), the +extension uses events for two purposes: orchestration state management and +context capture control. + +| Event | Parent-mode use | +| -------------------- | ------------------------------------------------------ | +| `before_agent_start` | Detect subagent mode (via flags); no-op in parent mode | +| `tool_call` | Constrain tools during context capture (phase perms) | + +Context capture uses `sendUserMessage()` to start the agent loop. Sub-phase +transitions use `koan_complete_step` (drafting -> verifying -> refining). +Final storage uses `koan_store_context`, whose completion callback spawns +the architect subagent synchronously. No `agent_end` or `turn_end` hooks. +After context capture completes, the parent orchestrator becomes purely +imperative: it spawns subagents, reads their output, and makes routing +decisions. No further `sendUserMessage()` calls -- all remaining LLM work +happens in subagent processes. + +### 2.6 State Persistence + +State is split by lifetime: + +- **Disk (plan directory):** `plan.json`, `context.json`, `qr-{phase}.json`, + `metadata.json`. These survive process boundaries and session restarts. + Written via atomic tmp+rename. Source of truth for all artifacts. +- **In-memory (parent process):** `WorkflowState` tracks current phase, + active sub-phase, step counter. Lost on exit. Could be reconstructed + from disk artifacts if needed for session resume. + +The plan directory (`~/.koan/plans//`) is the durable anchor. Session +resume (future) can reconstruct workflow position from the presence/absence +of artifacts on disk (e.g., if `context.json` exists but `plan.json` does +not, resume at plan-design phase). + +### 2.7 Planning TUI Widget System + +Detailed styling guidance lives in `docs/planning-widget.md`. + +The widget focuses on planning phases (plan-design, plan-code, plan-docs) and +uses one persistent card with a timeline rail and runtime detail pane. +The controller owns a persistent widget and updates once per second for elapsed +clock refresh. + +**Layout (full widget, metadata header, no tabs row):** + +``` +┌──────────────────────────────────────────────────────────────────────────────┐ +│ Planning · Plan design · CURRENT 12m 22s │ +│ │ +│ ● Plan design step : 2/6 · Codebase Exploration │ +│ │ CURRENT progress : ███████░░░░░░░░░░ 33% │ +│ │ ────────────────────────────────────────────── │ +│ ○ Plan code active subagents modifications (Δ/total) │ +│ │ UPCOMING role : architect milestones : +2 (6) │ +│ ○ Plan docs model: claude-opus-4-6 decisions : +1 (9) │ +│ UPCOMING load : q0 a1 d0 intents : +4 (18) │ +│ mode : single changes : +0 (3) │ +│──────────────────────────────────────────────────────────────────────────────│ +│ Latest log │ +│ koan_set_milestone_tests id=M-002 · tests:["covers retries"] +7 │ +│ koan_get_milestone id=M-002 · resp:42L/3.1k │ +└──────────────────────────────────────────────────────────────────────────────┘ +``` + +Structural behavior: + +1. **Header row** — left: `Planning · · `; + right: elapsed timer. No title cutout, no detached badge. +2. **Tabs row removed** — do not render `Plan design | Plan code | Plan docs` + as a separate strip. Active context is already in the header. +3. **Body split** — left timeline rail (phase progression), right detail pane + (step + progress, active subagents, modifications). +4. **Subagent telemetry** — render aggregate execution state: + `role`, `model`, `queued`, `active`, `done`, and `single` / `pool ×N`. + No per-worker identity list in this widget. +5. **Modifications panel** — render `+delta (total)` counters. Categories are + phase-specific: + - plan-design/plan-code/plan-docs/exec: `milestones`, `decisions`, + `intents`, `changes` + - qr-decompose: `qr items added`, `qr items updated`, `groups assigned` + - qr-verify: explicit placeholder row (`qr-verify counters not instrumented yet`) +6. **Latest log section** — same outer card, separated by internal divider, + deterministic two-column rows. + +Header truncation/alignment contract: + +- Let inner width be `W`, timer visible width be `T`. +- Reserve timer first (right-aligned); header-left budget is `W - T - 1`. +- Compose left chunk as `Planning · · ` and compact in order: + 1. abbreviate status, 2) drop status, 3) abbreviate phase label, + 2. ellipsize phase tail. +- Never wrap header text; overflow always resolves via compaction/truncation. + +Progress contract: + +- Runtime progress is **step-first** (`/ · `). +- Progress bar tracks the active subagent step index and total. +- QR loop iteration counters are internal gate state and are not primary + runtime progress UI. +- For pooled `qr-verify`, group progress (`done/total groups`) is the runtime + progress source. + +**WidgetController:** + +A WidgetController class owns widget state, render timer, and `ctx.ui` +reference. It exposes `update(partial)` for state transitions and `destroy()` +for cleanup. The orchestrator creates it at workflow start and calls +`destroy()` in its finally block (covering success, failure, and interrupt). + +The controller uses a 1-second `setInterval` (unref'd to not prevent process +exit) for elapsed time updates. All other updates are event-driven: the +orchestrator calls `update()` on phase transitions, projection polls, and pool +progress callbacks. + +**Change detection:** the controller hashes the state and skips `setWidget()` +calls when the hash is unchanged, avoiding unnecessary re-renders. + +**Data model:** + +```typescript +interface WidgetState { + phases: Array<{ + label: string; + status: "pending" | "running" | "completed" | "failed"; + }>; + activePhaseIndex: number; // 0-based, -1 when done + startedAt: number; // epoch ms + + // Header metadata (tabs row removed) + activePhaseLabel: string; + activePhaseStatus: "DONE" | "CURRENT" | "UPCOMING"; + + // Step-first runtime progress + stepTitle: string; // e.g. "2/6 · Codebase Exploration" + stepCurrent: number | null; + stepTotal: number | null; + + // Subagent telemetry + subagents: { + role: string; + model: string | null; + parallelCount: number; + queued: number | null; + active: number | null; + done: number | null; + }; + + // Modifications panel (`+delta (total)`) + modifications: + | { + kind: "plan-mods"; + milestones: { delta: number; total: number }; + decisions: { delta: number; total: number }; + intents: { delta: number; total: number }; + changes: { delta: number; total: number }; + } + | { + kind: "qr-decompose-mods"; + qrItemsAdded: { delta: number; total: number }; + qrItemsUpdated: { delta: number; total: number }; + groupsAssigned: { delta: number; total: number }; + } + | { + kind: "qr-verify-placeholder"; + message: "qr-verify counters not instrumented yet"; + }; + + logLines?: Array<{ tool: string; summary: string; highValue?: boolean }>; +} +``` + +The render function `(state: WidgetState, theme: Theme) => string[]` is pure +-- no side effects, easy to test. It uses `theme.fg()` for ANSI coloring in +the string array output. + +### 2.8 Concurrency Pool + +QR verification fans out to N subagents (one per item group), which can number +50-100 for larger plans. A bounded concurrency pool limits parallel execution. + +The abstraction is pure map+reduce: fan-out to N subagents, each returns +exactly 1 result, results are reduced into a single pass/fail verdict. + +```typescript +interface PoolProgress { + done: number; + total: number; + active: number; + queued: number; +} + +interface PoolResult { + total: number; + completed: number; + failed: string[]; +} + +async function pool( + itemIds: string[], + limit: number, + worker: (itemId: string) => Promise, + onProgress?: (p: PoolProgress) => void, +): Promise; +``` + +Worker-pool pattern: `limit` workers pull from a shared queue. Each completion +calls `onProgress`, which the orchestrator wires to runtime updates for +subagent load (`queued/active/done`) and pooled verify progress text. + +Abort handling is orchestrator-owned; the pool itself always runs all queued +items to completion and reports failed group IDs in `failed`. + +No polling is needed for the pool -- `onProgress` fires synchronously when +workers complete. `setWidget()` stores the content and the TUI re-renders on +the next event loop tick, which happens naturally between `await run(item)` +calls. + +--- + +## 3. Architecture + +### 3.1 Directory Structure + +**CRITICAL: This structure is mandatory. Every new file, phase, tool, or +module MUST follow this layout. Uniform structure is what makes the codebase +navigable -- when every phase directory has the same shape, finding "where +does X live?" takes seconds, not minutes.** + +The structure has two organizing principles: + +1. **Group by domain feature, not by technical layer.** Phase hooks and phase + prompts live together in the phase directory. Entity tools and entity + mutations are grouped by entity category. No scattering a single concern + across three sibling directories. + +2. **Shared infrastructure in `lib/`, shared tools in `tools/`.** Things + used by multiple phases stay in shared locations. Only hooks and prompts + that are specific to one phase live in that phase's directory. + +``` +koan/ + extensions/ + koan.ts -- Extension entry point (single file) + src/ + utils/ + lock.ts -- Advisory .lock file mechanism + logger.ts -- Scoped logging utility + plan.ts -- Plan directory creation + metadata + progress.ts -- Subagent progress reporting (state.json) + planner/ + session.ts -- Parent-mode: /koan command handler + orchestration + state.ts -- WorkflowState + ContextCaptureState types + types.ts -- ContextData type + CONTEXT_KEYS + subagent.ts -- Subagent spawning (process management, logging) + + lib/ -- Shared infrastructure (used by all phases) + dispatch.ts -- WorkflowDispatch, PlanRef, hook/unhook + permissions.ts -- checkPermission, PHASE_PERMISSIONS, tool sets + step.ts -- StepGuidance type + formatStep assembly + + plan/ -- Plan data layer (domain types + persistence) + types.ts -- Plan JSON schema types + ID generators + serialize.ts -- Atomic plan read/write (load/save with tmp+rename) + validate.ts -- Structural + referential validation + mutate/ -- Pure plan mutation functions, split by entity + decisions.ts -- decision + rejected-alternative + risk mutations + milestones.ts -- milestone mutations (add + 6 setters) + code.ts -- intent + change mutations + structure.ts -- wave + diagram + readme mutations + top-level.ts -- setOverview, setConstraints, setInvisibleKnowledge + index.ts -- Re-exports all mutation functions + + qr/ -- QR data layer + types.ts -- QR item types, severity, status + mutate.ts -- Pure QR mutation functions + + tools/ -- Shared tool registrations (all phases) + workflow.ts -- koan_complete_step, koan_store_context + context-store.ts -- Context store schema + result types + getters.ts -- Read-only plan inspection tools + setters.ts -- Top-level plan field setters + entity-design.ts -- Decision, rejected-alt, risk, milestone tools + entity-code.ts -- Intent, change tools + entity-structure.ts -- Wave, diagram, readme tools + qr.ts -- QR item CRUD + summary tools + index.ts -- registerAllTools(pi, planRef, dispatch) + + phases/ -- Phase implementations (one dir per phase) + dispatch.ts -- Subagent mode detection + phase routing + context-capture/ + phase.ts -- ContextCapturePhase class (hooks + step logic) + prompts.ts -- Draft/verify/refine guidance + plan-design/ + phase.ts -- PlanDesignPhase class (hooks + step logic) + prompts.ts -- 6-step architect guidance + package.json + tsconfig.json +``` + +Not yet implemented (follow the same patterns when added): + +- `src/planner/pool.ts` -- bounded concurrency pool +- `src/planner/ui/widget.ts` -- TUI widget +- `src/planner/qr/decompose.ts`, `qr/verify.ts`, `qr/gate.ts` -- QR orchestration +- `src/planner/phases/plan-code/` -- developer phase (phase.ts + prompts.ts) +- `src/planner/phases/plan-docs/` -- writer phase (phase.ts + prompts.ts) +- `src/planner/phases/qr-decompose/` -- QR decomposer (phase.ts + prompts.ts) +- `src/planner/phases/qr-verify/` -- QR verifier (phase.ts + prompts.ts) + +**Why entity tools are shared, not per-phase:** The permission map +(section 7.4) shows that entity tools serve 3+ phases with different subsets. +plan-design uses all entity tools except code_change. plan-code uses only +change tools + koan_set_intent. plan-docs uses a doc-specific subset. Moving +tools into a single phase would create false ownership and force cross-phase +imports. Tools stay in `tools/`; phases stay in `phases/`. + +**Adding a new phase** requires exactly: + +1. Create `phases//phase.ts` (copy an existing phase.ts shape) +2. Create `phases//prompts.ts` (define step guidance) +3. Add dispatch case in `phases/dispatch.ts` +4. Add permission entry in `lib/permissions.ts` + +Two new files, two edits. No other files need to change. + +Note the absence of `agents/*.md` files for role behavior. Roles are +implemented as TypeScript phase handlers in `src/planner/phases/` that +register event hooks when the extension detects subagent mode. The architect +system prompt is loaded from `~/.claude/agents/architect.md` at runtime but +the step control logic lives in `phases/plan-design/phase.ts`. + +### 3.2 File Organization Standard + +**CRITICAL: Every source file in this project MUST follow this standard. +Uniform file structure is a non-negotiable constraint. When every file has +the same shape, a reader can orient in any file instantly. When files +diverge, the reader must reverse-engineer each file's conventions separately. +Consistency across 30+ files is more valuable than local optimization of +any single file.** + +#### 3.2.1 Module Header Comment (Required) + +Every file begins with a block comment (2-5 lines of `//` comments) +immediately before the imports. This comment is a contract -- it states: + +1. **What** the file does (one sentence) +2. **Why** it exists or **how** it fits into the architecture (one sentence) +3. **Key design notes** that are non-obvious (0-3 sentences, only if needed) + +The header answers: "I opened this file -- should I keep reading or look +elsewhere?" It does NOT repeat what the imports or exports already show. + +```typescript +// Pure plan mutation functions for decision, rejected-alternative, +// and risk entities. +// +// Every function takes a Plan and returns a new Plan (no side effects). +// Mutations are called from entity tool execute callbacks via the +// load-mutate-save pattern (tools/ -> mutate/ -> serialize). + +import type { Plan, Decision, ... } from "../types.js"; +``` + +**Good headers (why/how):** + +```typescript +// Atomic plan read/write. Writes use tmp+rename to prevent corruption +// on mid-write crash. loadPlan returns an empty plan when plan.json +// does not yet exist (first tool call creates the file). +``` + +```typescript +// Default-deny phase permissions. Read tools bypass this map. Write +// tools (edit/write) always blocked during planning. The map defines +// OUTER boundaries; phase handlers narrow further via step gates. +``` + +**Bad headers (restating the obvious):** + +```typescript +// This file exports the Plan type and related types. <-- imports show this +// Functions for loading and saving plans. <-- file name says this +``` + +#### 3.2.2 File Body Order + +Every file follows the same top-to-bottom reading order. A reader never +scrolls up to understand what they are reading. + +``` +1. Module header comment (required, 2-5 lines) +2. Imports (node builtins, then external packages, then local) +3. Exported types/interfaces (the file's public contract) +4. Constants (module-level, UPPER_SNAKE_CASE) +5. Private helpers (functions used only within this file) +6. Exported functions/classes (the file's public API) +``` + +**Rationale:** Types define the vocabulary. Constants parameterize behavior. +Helpers are building blocks. Exports are the assembled product. Each layer +depends only on layers above it. + +**Exception: classes.** When a file exports a single class, the class body +is the export. Private methods within the class follow the same principle +-- helpers before the methods that call them, where practical. Event handler +registration methods (e.g., `registerHandlers()`) come before the handler +implementations they reference. + +#### 3.2.3 Section Headers + +Use `// -- Section Name --` comments to group related items within a file. +Section headers are required when a file contains multiple logical groups +(e.g., multiple entity categories in a tool file, multiple sub-phases in +a phase file). + +```typescript +// -- Decisions -- + +export function addDecision(p: Plan, ...): Plan { ... } +export function setDecision(p: Plan, ...): Plan { ... } + +// -- Rejected Alternatives -- + +export function addRejectedAlternative(p: Plan, ...): Plan { ... } +``` + +Do NOT use section headers when a file has only one logical group (e.g., +a file with just milestone mutations needs no `// -- Milestones --` header). + +#### 3.2.4 Inline Comments + +Comments explain **why**, never **what**. If the code needs a "what" comment, +the code should be renamed or restructured to be self-explanatory. + +**Good (why):** + +```typescript +// TypeScript cannot verify generic key-value assignment. +// Call-site constraint ensures type safety; guard above prevents double-hook. +(dispatch as any)[key] = handler; +``` + +**Good (non-obvious constraint):** + +```typescript +// Pi snapshots tools during _buildRuntime(). Late registration is +// invisible to the LLM. +registerWorkflowTools(pi, dispatch); +``` + +**Bad (what):** + +```typescript +// Increment the step counter +this.state.step = (prev + 1) as PlanDesignStep; + +// Load the plan from disk +const p = await loadPlan(planRef.dir); +``` + +#### 3.2.5 No Comments Needed + +The following do NOT need comments: + +- Type definitions (field names + types are self-documenting) +- Simple pure functions (name + signature tell the story) +- Import blocks +- Standard patterns (load-mutate-save is documented once in the module + header of entity tool files; individual tools do not repeat it) + +#### 3.2.6 Naming + +Functions: `verbNoun` -- `loadPlan`, `formatStep`, `checkPermission`, +`addDecision`, `setMilestoneName`. Short, imperative, composable. + +Constants: `UPPER_SNAKE_CASE` -- `MAX_ATTEMPTS`, `PLAN_MUTATION_TOOLS`, +`DEFAULT_INVOKE`, `STEP_NAMES`. + +Types/interfaces: `PascalCase` -- `StepGuidance`, `WorkflowDispatch`, +`PlanDesignState`. + +Variables: short names when function name provides context (see CLAUDE.md +short name conventions). `p` for plan in `addDecision(p, ...)`, `m` for +milestone in `findIntent(p, id)`. + +#### 3.2.7 File Size Guideline + +Target: under 200 lines per file, excluding prompt text (long guidance +strings are inherently long and that is fine). When a file exceeds 200 +lines of logic, look for a natural split boundary (entity categories, +sub-phases, public vs. private helpers). + +This is a guideline, not a hard rule. A 250-line file with one cohesive +concern is better than splitting into two files that constantly import +from each other. + +### 3.3 Extension Entry Point + +```typescript +// extensions/koan.ts +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; +import { createSession } from "../src/planner/session.js"; +import { + detectSubagentMode, + dispatchPhase, +} from "../src/planner/phases/dispatch.js"; +import { createDispatch, createPlanRef } from "../src/planner/lib/dispatch.js"; +import { registerAllTools } from "../src/planner/tools/index.js"; + +export default function koan(pi: ExtensionAPI): void { + pi.registerFlag("koan-role", { + description: "Koan subagent role (reserved)", + type: "string", + default: "", + }); + pi.registerFlag("koan-phase", { + description: "Koan workflow phase (reserved)", + type: "string", + default: "", + }); + pi.registerFlag("koan-plan-dir", { + description: "Koan plan directory path", + type: "string", + default: "", + }); + pi.registerFlag("koan-subagent-dir", { + description: "Koan subagent working directory", + type: "string", + default: "", + }); + + // All tools register unconditionally at init (pi snapshots during + // _buildRuntime). Phases restrict access via tool_call blocking. + const dispatch = createDispatch(); + const planRef = createPlanRef(); + registerAllTools(pi, dispatch, planRef); + + // Subagent detection deferred to before_agent_start (flags + // unavailable during init). + let dispatched = false; + pi.on("before_agent_start", async () => { + if (dispatched) return; + dispatched = true; + const config = detectSubagentMode(pi); + if (config) { + const planDir = pi.getFlag("koan-plan-dir") as string; + if (planDir) planRef.dir = planDir; + await dispatchPhase(pi, config, dispatch, planRef); + } + }); + + // Parent mode: /koan command handler. + const session = createSession(pi, dispatch, planRef); + pi.registerCommand("koan", { + description: "Koan planning workflow", + handler: async (args, ctx) => { + const [subcommand, ...rest] = args.trim().split(/\s+/); + const command = subcommand ?? ""; + const remainingArgs = rest.join(" "); + switch (command) { + case "plan": + await session.plan(remainingArgs, ctx); + break; + case "execute": + await session.execute(ctx); + break; + case "status": + await session.status(ctx); + break; + default: + ctx.ui.notify( + "Usage: /koan plan , /koan execute, or /koan status", + "error", + ); + } + }, + }); +} +``` + +### 3.4 Workflow State + +There are two categories of state: + +1. **Disk state** -- data that must survive process boundaries (parent to + subagent, or across session restarts). Stored as JSON files in the plan + directory (`~/.koan/plans//`). +2. **Ephemeral state** -- runtime tracking that lives only in the parent + process or a subagent process. In-memory only, lost on exit. + +**Disk state (plan directory):** + +| File | Written by | Read by | +| ----------------- | ------------------ | ------------------ | +| `metadata.json` | Parent (session) | Parent (status) | +| `context.json` | Parent (ctx phase) | Subagents | +| `plan.json` | Subagents (tools) | Subagents + parent | +| `qr-{phase}.json` | Subagents (tools) | Subagents + parent | + +All disk writes use atomic tmp+rename to prevent corruption on crash. + +**Ephemeral state (in-memory):** + +```typescript +// src/planner/types.ts -- context data structure (shared via disk) +interface ContextData { + task_spec: string[]; + constraints: string[]; + entry_points: string[]; + rejected_alternatives: string[]; + current_understanding: string[]; + assumptions: string[]; + invisible_knowledge: string[]; + reference_docs: string[]; +} + +// src/planner/state.ts -- parent session ephemeral state +type WorkflowPhase = + | "idle" + | "context" + | "context-complete" + | "context-failed" + | "architect-running" + | "architect-failed" + | "plan-design-complete"; + +interface PlanInfo { + id: string; + directory: string; + createdAt: string; + metadataPath: string; +} + +interface ContextCaptureState { + active: boolean; + subPhase: "drafting" | "verifying" | "refining"; + attempt: number; + maxAttempts: number; + taskDescription: string; + planId: string; + planDirectory: string; + contextFilePath: string; + lastPrompt: string | null; + feedback: string[]; + data?: ContextData; +} + +interface WorkflowState { + phase: WorkflowPhase; + taskDescription: string | null; + plan: PlanInfo | null; // metadata, not plan data + context: ContextCaptureState | null; +} + +// src/planner/qr/types.ts -- QR items (stored on disk) +interface QRItem { + id: string; + scope: string; + check: string; + status: "TODO" | "PASS" | "FAIL"; + finding: string | null; + parent_id: string | null; + group_id: string | null; + severity: "MUST" | "SHOULD" | "COULD"; +} + +interface QRFile { + phase: string; + iteration: number; + items: QRItem[]; +} +``` + +The parent's `WorkflowState` tracks where we are in the workflow (ephemeral). +The plan directory holds all artifacts that must cross process boundaries +(disk). Phase handlers within subagents maintain their own step state +in-memory (e.g., `PlanDesignState.step` in `plan-design.ts`). + +### 3.5 Plan JSON Schema + +The plan JSON is the primary artifact produced by the planning workflow. Schema +matches the Pydantic v2 models in the existing planner's `shared/schema.py`. + +``` +Plan + plan_id: string -- UUID, auto-generated + created_at: string -- ISO timestamp + frozen_at: string | null + + overview + problem: string -- what we're solving + approach: string -- how we're solving it + + planning_context + decision_log: Decision[] + id: "DL-001" + decision: string + reasoning_chain: string -- logical chain using -> notation + + rejected_alternatives: RejectedAlternative[] + id: string + alternative: string + rejection_reason: string + decision_ref: "DL-XXX" + + constraints: string[] -- free-form, e.g. "MUST: support Python 3.9+" + + known_risks: Risk[] + id: string + risk: string + mitigation: string + anchor: string | null -- "file:L###-L###" + decision_ref: "DL-XXX" | null + + invisible_knowledge + system: string -- architecture, data flow, rationale as prose + invariants: string[] -- must-preserve properties + tradeoffs: string[] -- known compromises + + diagram_graphs: DiagramGraph[] + id: "DIAG-001" + type: "architecture" | "state" | "sequence" | "dataflow" + scope: string -- "overview" | "invisible_knowledge" | "milestone:M-XXX" + title: string + nodes: DiagramNode[] + id: string + label: string + type: string | null + edges: DiagramEdge[] + source: string -- node id (validated) + target: string -- node id (validated) + label: string + protocol: string | null + ascii_render: string | null -- populated by TW, null until rendered + + milestones: Milestone[] + id: "M-001" + number: int + name: string + files: string[] + flags: string[] + requirements: string[] + acceptance_criteria: string[] + tests: string[] + + code_intents: CodeIntent[] + id: "CI-001" + file: string + function: string | null + behavior: string + decision_refs: string[] + + code_changes: CodeChange[] + id: "CC-M-001-001" + intent_ref: "CI-XXX" | null + file: string + diff: string -- code diff (Developer fills) + doc_diff: string -- documentation overlay (TW fills) + comments: string -- change-level WHY context + + documentation: Documentation -- DEPRECATED, kept for compat with Python planner + module_comment: string | null + docstrings: Docstring[] + function_blocks: FunctionBlock[] + inline_comments: InlineComment[] + + is_documentation_only: bool + delegated_to: string | null + + waves: Wave[] + id: "W-001" + milestones: string[] -- M-XXX refs, parallel within wave + + readme_entries: ReadmeEntry[] -- DEPRECATED, kept for compat with Python planner + path: string + content: string +``` + +Waves execute in array order. All milestones in W-001 complete before W-002 +begins. Milestones within a wave may execute in parallel. + +Cross-reference validation checks: + +- `code_changes.intent_ref` -> `code_intents.id` (within same milestone) +- `code_intents.decision_refs` -> `decision_log.id` +- `rejected_alternatives.decision_ref` -> `decision_log.id` +- `known_risks.decision_ref` -> `decision_log.id` +- `diagram_graphs.edges.source/target` -> `diagram_graphs.nodes.id` (within same diagram) +- `diagram_graphs.scope` -> `milestones.id` (when scope is `milestone:M-XXX`) + +--- + +## 4. Detailed Phase Design + +### 4.1 Phase 1: Context Capture (Parent Session) + +**Mechanism:** `sendUserMessage()` in the parent session, controlled by +extension event hooks. + +This is the one phase that runs in the parent session. It must, because the +session LLM is the only entity that has the conversational understanding built +up over the session. A fresh LLM reading a serialized transcript would lose +implicit context — things explored, rejected, understood through +back-and-forth. The session LLM was _there_. + +This mirrors the original planner's steps 1-2 exactly: the LLM that +participated in the conversation reflects on what it knows and produces a +structured handover document. + +**Flow:** + +1. User types `/koan plan ` +2. Extension creates plan directory (`~/.koan/plans//`) with + `metadata.json`, sets workflow state to `phase: "context"`, stores the + user's task description. +3. Extension calls `pi.sendUserMessage()` with the draft-phase context + capture instructions. This is the ONE `sendUserMessage()` call -- it + starts the agent loop. +4. The session LLM -- the one that has been part of the conversation -- + receives the context capture prompt. The prompt asks it to think through + 8 dimensions and draft its analysis: + - TASK_SPEC: subject, scope, out-of-scope + - CONSTRAINTS: MUST/SHOULD/MUST-NOT with sources + - ENTRY_POINTS: file:function + why relevant + - REJECTED_ALTERNATIVES: what dismissed + why + - CURRENT_UNDERSTANDING: how system works + - ASSUMPTIONS: unverified inferences with confidence + - INVISIBLE_KNOWLEDGE: design rationale, invariants, tradeoffs + - REFERENCE_DOCS: paths to project docs +5. `tool_call` hook uses `checkPermission("context-capture", ...)` which + allows `koan_store_context` and `koan_complete_step` (plus read tools + always pass). Within context capture, sub-phase-specific blocking adds + further constraints: + - **drafting**: blocks `koan_store_context`, allows `koan_complete_step` + and read tools. The LLM MAY make targeted reads if a specific lookup + would resolve genuine uncertainty (e.g., confirming an API signature). + - **verifying**: blocks everything except `koan_complete_step` (pure + review, no exploration). + - **refining**: blocks everything except `koan_store_context` (final + structured output). +6. Context capture uses the same tool-call step transition pattern as + subagents (see section 2.3). The LLM calls `koan_complete_step` to + advance from drafting to verifying to refining. The tool result contains + the next sub-phase's instructions. All sub-phases run within a single + agent loop -- no `agent_end` + `sendUserMessage()` chaining. +7. `koan_store_context` tool validates structure: all 8 categories must be + present as non-empty arrays of non-empty strings. No semantic validation + -- the extension checks structure, not quality. +8. If validation fails: tool throws an Error with specific feedback. The LLM + retries within the same agent loop. Up to 3 attempts. +9. If validation passes: write `context.json` to plan directory, transition + to `context-complete` phase. The tool's completion callback then spawns + the architect subagent synchronously -- the `koan_store_context` tool + call blocks until the architect finishes. The LLM receives context + capture result + architect outcome in one tool response. + +**Why `sendUserMessage()` and not `complete()`:** The whole point of context +capture is extracting knowledge from the LLM that has been participating in +the conversation. That knowledge lives in the session's message history and +the LLM's understanding of it. A `complete()` call creates a fresh LLM +instance that would need the entire conversation serialized as input -- which +may not fit, and even if it does, loses the implicit understanding that the +session LLM built up over many exchanges. + +**Why this is acceptable in the parent session:** Context capture is short -- +a few turns of the LLM drafting, reviewing, and storing structured context. +It allows limited read tools during drafting for targeted lookups but does not +involve broad codebase exploration or tool-heavy work. The context window cost +is modest. Everything after this phase runs in isolated subagents. + +**Structural validation, not semantic validation:** The extension validates +that the 8 categories are present as non-empty string arrays. It does not +attempt to judge whether the content is _good_ -- that would require another +LLM call. Quality of the context is ensured by the fact that the session LLM +is the one producing it -- it has the knowledge. + +### 4.2 Phases 2-6: Work + QR Block + +Each of these five phases (plan-design, plan-code, plan-docs, exec-code, +exec-docs) follows the same 3-sub-phase pattern. All work happens in +subagent processes. The TUI widget (section 2.7) tracks progress across +phases and sub-phases throughout. + +#### Sub-phase: Execution (Subagent) + +**Mechanism:** Spawned subagent with event-driven step control + +**Flow:** + +1. Parent orchestrator ensures `context.json` exists in plan directory +2. Parent spawns subagent: + ```typescript + spawn("pi", [ + "-p", + "-e", + extensionPath, + "--koan-role", + "architect", + "--koan-phase", + "plan-design", + "--koan-plan-dir", + planDir, + "--koan-subagent-dir", + subagentDir, + "Begin the plan-design phase.", + ]); + ``` +3. Inside the subagent, `before_agent_start` fires; extension detects + `koan-role=architect` via `detectSubagentMode()` +4. Extension activates architect event hooks via `dispatchPhase()`: + - `before_agent_start`: injects architect system prompt (loaded from + `~/.claude/agents/architect.md`) + - `context`: replaces user message with step 1 prompt (first call only) + - `tool_call`: enforces phase permissions + step gate (mutation tools + blocked until step 6) +5. The subagent's agent loop runs multiple turns, guided by the extension +6. Plan mutations happen via tool calls that write to `plan.json` on disk +7. On final `koan_complete_step` (step 6), extension runs plan validation +8. Parent reads `plan.json` from disk after subagent exits + +**Role-specific step sequences:** + +- **Architect (plan-design phase, 6 steps):** + 1. Task Analysis & Exploration Planning (read project context files) + 2. Codebase Exploration (glob, grep, read -- broad exploration) + 3. Testing Strategy Discovery (conventions, project docs) + 4. Approach Generation (2-3 options with tradeoffs) + 5. Assumption Surfacing (fast-path skip if no migration/policy decisions) + 6. Milestone Definition & Plan Writing (mutation tools unlock; write plan + via koan_add_milestone, koan_add_decision, etc.) + +- **Developer (plan-code phase):** + 1. Read plan design section + explore implementation files (tools: read, grep, find) + 2. Analyze implementation details (tools: read, grep, bash) + 3. Write code-level plan as JSON (tools: none) + +- **Technical writer (plan-docs phase):** + 1. Extract planning context (decisions, constraints, risks) + 2. Read each code_change diff, identify documentation needs + 3. Generate doc_diff overlays per code_change via `set-doc-diff` tool + 4. Create cross-cutting documentation (README.md) via `create-doc-change` tool + 5. Render diagram_graphs to ASCII via `set-diagram-render` tool + 6. Validate documentation completeness + +- **Developer (exec-code phase):** + Implementation subagents apply the plan's code_changes. Operates per-wave: + all milestones in W-001 complete before W-002 begins. Milestones within a + wave may execute in parallel (separate subagent processes). + +- **Technical writer (exec-docs phase):** + Documentation subagents apply the plan's doc_diff overlays and render + diagrams. Same wave-based execution as exec-code. + + **Documentation model:** Developer fills `diff` on code_changes. TW fills + `doc_diff` -- a separate unified diff that adds documentation after the code + diff is applied. Cross-cutting docs (README.md) are code_changes with + `intent_ref: null` and content in `doc_diff`. + + **Documentation tiers:** + - Module comment: file-level (top of file) + - Docstring: function-level (what it does, when to use) + - Inline comment: logic explanation (algorithms, decisions) + + All documentation must reference relevant decisions using `(ref: DL-XXX)`. + Temporal contamination is forbidden -- no "Added to", "Now uses", "Changed + from". All documentation uses timeless present tense. + +**First attempt vs. fix mode:** + +When a phase's QR gate returns FAIL, the orchestrator re-spawns the subagent +with an additional flag (`--koan-fix`) and appends the QR failure report to +the context file. The subagent's role hooks detect fix mode and adjust step +instructions to focus on fixing specific issues identified by the QR. + +#### Sub-phase: QR Decomposition (Subagent) + +**Mechanism:** Spawned subagent with the QR decomposer role. + +**Flow:** + +1. Parent reads plan JSON from the work subagent's output +2. Parent writes plan JSON + context to temp file +3. Parent spawns QR decomposer subagent: + ```typescript + spawn("pi", [ + "-p", + "-e", + extensionPath, + "--koan-role", + "qr-decomposer", + "--koan-phase", + "plan-design", + "--koan-plan-dir", + planDir, + "--koan-subagent-dir", + subagentDir, + "Decompose this plan section into verifiable QR items.", + ]); + ``` +4. The decomposer subagent follows a 13-step workflow (see below) +5. Parent reads `qr-{phase}.json` from plan directory after subagent exits + +Decomposition is analysis of a self-contained artifact (the plan JSON). It +does not require the parent session's conversational context. A subagent with +read-only tools and the plan artifact as input is sufficient. + +**13-step decomposition workflow (event-driven steps inside subagent):** + +Steps 1-8 generate verification items top-down-then-bottom-up: + +1. **Absorb Context**: Read plan.json and context.json. Summarize what the + plan accomplishes and what success looks like for this phase. No items yet. +2. **Holistic Concerns (top-down)**: Brainstorm freely -- "if reviewing this + phase output, what would I check?" Captures cross-cutting patterns, quality + aspects, and risks. Unfiltered bulleted list. +3. **Structural Enumeration (bottom-up)**: List what EXISTS in the plan for + this phase. Decisions/constraints/risks for design, code_changes for code, + acceptance_criteria for impl. Use IDs. Note counts. +4. **Gap Analysis**: Compare step 2 concerns vs step 3 elements. Which + concerns map to specific elements? Which span multiple? What gaps exist? +5. **Generate Items**: Create items using UMBRELLA + SPECIFIC pattern. + Umbrella items (scope: `*`) catch cross-cutting concerns. Specific items + (scope: element reference) target individual elements. No fixed count. +6. **Atomicity Check**: Each item tests exactly one thing? Pass/fail must be + unambiguous. Split non-atomic MUST items into children; keep non-atomic + SHOULD/COULD items as umbrellas. +7. **Coverage Validation**: Use step 3 enumeration as checklist. For each + element: at least one covering item? For each concern: at least one + addressing item? If uncertain, ADD an item. +8. **Finalize**: Write qr-{phase}.json with all items (status: TODO). + +Steps 9-13 organize items into groups for parallel dispatch: + +9. **Structural Grouping**: Parent-child items share group. Umbrella items + get group_id `umbrella`. +10. **Component Grouping**: Items verifying same structural element + (milestone, decision). Prefix: `component-`. +11. **Concern Grouping**: Items verifying same quality dimension across + elements. Prefix: `concern-`. +12. **Affinity Grouping**: Remaining items by semantic similarity. + Prefix: `affinity-`. Singletons are acceptable. +13. **Final Validation**: Validate group_id conventions, check for oversized + groups, confirm no orphans. + +#### Sub-phase: QR Verification (Subagent, Parallel) + +**Mechanism:** Spawned subagent(s) with the QR reviewer role, managed by the +concurrency pool (section 2.8). + +**Flow:** + +1. Group QR items by group_id +2. Submit all groups to the concurrency pool: + ```typescript + const result = await pool( + groups, + MAX_QR_CONCURRENT, // e.g., 6 + (group, i) => + spawnReviewer({ + role: "reviewer", + phase: currentPhase, + items: group.items, + planDir, + }), + (progress) => widget.update({ qrVerify: progress }), + ); + ``` + The pool spawns up to `MAX_QR_CONCURRENT` subagents in parallel. Each + subagent is an isolated pi process with the koan extension: + ```typescript + spawn("pi", [ + "-p", + "-e", + extensionPath, + "--koan-role", + "reviewer", + "--koan-phase", + "plan-design", + "--koan-plan-dir", + planDir, + "--koan-subagent-dir", + subagentDir, + "Verify the following plan items against the codebase.", + ]); + ``` +3. Reviewer subagent has read-only tools + `koan_qr_set_item` tool for + QR state updates +4. Each subagent returns exactly 1 result (pass/fail for its group) +5. Pool's `onProgress` callback updates the widget with live counts +6. Results reduced into a single pass/fail verdict + +QR decomposition can produce 50-100 items on larger plans. The concurrency +pool prevents spawning all of them simultaneously. The `onProgress` callback +provides live feedback in the TUI widget: completed/total, running, failed. + +**Verification workflow inside each subagent:** + +For each assigned QR item, the subagent performs an ANALYZE/CONFIRM pair: + +- **ANALYZE**: Explore codebase if needed, apply the verification check, form + preliminary PASS/FAIL conclusion with evidence. Do not update state yet. +- **CONFIRM**: Verify confidence, check that evidence is specific and + verifiable, then invoke `update-item` tool with status and finding. + +After all items: output single word PASS or FAIL. Any item failure means FAIL. + +Verification benefits from codebase access -- the reviewer needs to check +whether the plan's claims about the code are actually true. Subagents with +read-only tools are the right mechanism. + +#### QR Gate (Route) + +**Mechanism:** Deterministic TypeScript logic (no LLM) + +```typescript +function routeGate( + phase: Phase, + qrResult: "pass" | "fail", + iteration: number, +): NextStep { + if (qrResult === "pass") { + deleteQRState(phase); + return nextPhase(phase); + } + const maxIterations = 5; + if (iteration >= maxIterations) { + return nextPhase(phase); // Force proceed, document remaining issues + } + return { + phase, + subPhase: "execution", + mode: "fix", + iteration: iteration + 1, + }; +} +``` + +No LLM involved. Pure routing logic based on QR results and iteration count. +This is the key improvement: the current planner outputs routing guidance and +hopes the LLM follows it. Here, routing is code. + +--- + +## 5. End-to-End Flow + +``` +User: /koan plan Add Redis caching to the session store + +Parent process (interactive pi session): + │ TUI widget appears: koan [1/6] context + │ + ├─ 1. CONTEXT CAPTURE (sendUserMessage -- in parent session) + │ The session LLM reflects on the conversation it participated in. + │ Writes STATE_DIR/context.json with 8 structured categories. + │ Extension validates structure, retries if gaps found. + │ -> context.json (self-contained handover document) + │ + │ -- everything below operates on artifacts, not conversation -- + │ + ├─ 2. PLAN-DESIGN (architect) + │ ├─ execution: spawn architect subagent + │ │ pi -p --koan-role architect --koan-phase plan-design ... + │ │ Extension hooks steer multi-turn exploration + plan writing + │ │ -> plan design JSON + │ │ + │ ├─ qr-decompose: spawn decomposer subagent + │ │ -> QR items for design review + │ │ + │ ├─ qr-verify: pool of reviewer subagents (bounded concurrency) + │ │ -> PASS/FAIL per item group + │ │ + │ └─ gate (deterministic code, no LLM) + │ PASS -> advance to plan-code + │ FAIL -> re-spawn architect with fix report (up to 5x) + │ + ├─ 3. PLAN-CODE (same pattern: developer + QR block) + │ + ├─ 4. PLAN-DOCS (same pattern: writer + QR block) + │ + ├─ 5. EXEC-CODE (developer applies code_changes, wave-based) + │ ├─ execution: per-wave milestone subagents (parallel within wave) + │ ├─ qr-decompose + qr-verify: same QR block pattern + │ └─ gate -> advance to exec-docs + │ + ├─ 6. EXEC-DOCS (writer applies doc_diffs, wave-based) + │ ├─ execution: per-wave documentation subagents + │ ├─ qr-decompose + qr-verify: same QR block pattern + │ └─ gate -> complete + │ + └─ COMPLETE + TUI widget removed. + Report back to user in parent session. +``` + +**Wave execution model:** The plan's milestones are grouped into waves. +Waves execute in array order -- all milestones in W-001 complete before +W-002 begins. Milestones within a wave may execute in parallel (separate +subagent processes, managed by the concurrency pool). The orchestrator's +execution workflow iterates over waves, spawning milestone subagents within +each wave with barrier synchronization via the pool. + +--- + +## 6. Implementation Milestones + +### Milestone 1: Scaffold + Context Capture + +**Goal:** Extension loads in both modes, `/koan plan` triggers context +capture in the parent session via `sendUserMessage()`. + +**Deliverables:** + +- [x] Pi package scaffolding (package.json with `pi` manifest, directories) +- [x] Extension entry point with `/koan` command and subcommand routing +- [ ] `--koan-role` and `--koan-phase` flag registration +- [ ] Dual-mode detection (parent vs. subagent) +- [ ] WorkflowState type definition (in-memory only, no persistence yet) +- [ ] Context capture via `sendUserMessage()` with event hooks: + - `context` hook injects capture instructions + - `tool_call` hook constrains to Write tool only + - `turn_end` hook checks for context.json + - `agent_end` hook validates structure, advances phase +- [ ] Structural validation of context.json (8 categories present) +- [ ] Verify extension loads: `pi -e ./extensions/koan.ts` + +**Files:** + +- `extensions/koan.ts` -- extension entry point +- `src/planner/session.ts` -- parent-mode /koan command handler +- `src/planner/state.ts` -- WorkflowState + ContextCaptureState types +- `src/planner/types.ts` -- ContextData type +- `src/planner/lib/dispatch.ts` -- WorkflowDispatch + PlanRef + hook/unhook +- `src/planner/lib/permissions.ts` -- phase permissions (default-deny) +- `src/planner/lib/step.ts` -- StepGuidance + formatStep +- `src/planner/phases/context-capture/phase.ts` -- context capture phase handler +- `src/planner/phases/context-capture/prompts.ts` -- context capture prompts +- `src/planner/tools/workflow.ts` -- koan_complete_step + koan_store_context +- `src/planner/tools/context-store.ts` -- context store schema + +**Verification:** + +- `/koan plan Add Redis caching` triggers context capture turn +- Session LLM writes context.json with 8 structured categories +- Extension validates structure and reports gaps +- Extension loads without errors in both modes +- `pi -p -e ./extensions/koan.ts --koan-role test` detects subagent mode + +### Milestone 2: Subagent Spawning + Architect Role + +**Goal:** Parent spawns an architect subagent that runs a multi-step +exploration and produces plan output. + +**Deliverables:** + +- [ ] Subagent spawning utility (process management, temp file mgmt) +- [ ] Architect role: 6-step plan-design workflow +- [ ] `before_agent_start` hook: inject architect system prompt +- [ ] `context` hook: inject step 1 prompt (first call only) +- [ ] `tool_call` hook: phase permissions + step gate (mutations step-6-only) +- [ ] Parent reads plan.json from disk after subagent exits + +**Files:** + +- `src/planner/subagent.ts` -- spawning utilities +- `src/planner/phases/plan-design/phase.ts` -- architect step definitions + hooks +- `src/planner/phases/plan-design/prompts.ts` -- 6-step guidance prompts +- `src/planner/phases/dispatch.ts` -- subagent detection + phase routing +- `src/planner/plan/types.ts` -- plan schema + ID generators +- `src/planner/plan/serialize.ts` -- atomic plan read/write +- `src/planner/plan/validate.ts` -- structural + ref validation +- `src/planner/plan/mutate/decisions.ts` -- decision + rejected-alt + risk mutations +- `src/planner/plan/mutate/milestones.ts` -- milestone mutations +- `src/planner/plan/mutate/code.ts` -- intent + change mutations +- `src/planner/plan/mutate/structure.ts` -- wave + diagram + readme mutations +- `src/planner/plan/mutate/top-level.ts` -- overview, constraints, invisible-knowledge +- `src/planner/plan/mutate/index.ts` -- re-exports +- `src/planner/tools/getters.ts` -- read-only plan tools +- `src/planner/tools/setters.ts` -- top-level plan setters +- `src/planner/tools/entity-design.ts` -- decision, rejected-alt, risk, milestone tools +- `src/planner/tools/entity-code.ts` -- intent, change tools +- `src/planner/tools/entity-structure.ts` -- wave, diagram, readme tools +- `src/planner/tools/index.ts` -- registerAllTools() + +**Verification:** + +- Architect subagent explores codebase with read-only tools +- Step transitions happen based on LLM output analysis +- Tools are blocked when step doesn't allow them +- Parent reads structured plan output from state files + +### Milestone 3: QR Block (Decompose + Verify + Gate) + Concurrency Pool + +**Goal:** Complete QR block pattern working for plan-design phase, with bounded +parallel execution. + +**Deliverables:** + +- [ ] Concurrency pool (`pool.ts`): bounded fan-out/fan-in with onProgress + callback and AbortSignal support +- [ ] QR decomposer role: subagent that reads plan and produces QR items +- [ ] QR reviewer role: subagent that verifies items against codebase +- [ ] Parallel reviewer spawning via concurrency pool +- [ ] QR gate routing (deterministic, no LLM) +- [ ] Fix mode: re-spawn work subagent with QR failure report appended +- [ ] Iteration escalation with severity filtering +- [ ] QR state stored on disk (qr-{phase}.json in plan directory) + +**Files:** + +- `src/planner/pool.ts` -- bounded concurrency pool +- `src/planner/qr/types.ts` -- QR item types, severity enum +- `src/planner/qr/mutate.ts` -- pure QR mutation functions (exists) +- `src/planner/qr/decompose.ts` -- decomposer subagent spawning +- `src/planner/qr/verify.ts` -- reviewer subagent spawning (uses pool) +- `src/planner/qr/gate.ts` -- routing logic +- `src/planner/phases/qr-decompose/phase.ts` -- decomposer phase hooks +- `src/planner/phases/qr-decompose/prompts.ts` -- decomposition prompts +- `src/planner/phases/qr-verify/phase.ts` -- reviewer phase hooks +- `src/planner/phases/qr-verify/prompts.ts` -- verification prompts +- `src/planner/tools/qr.ts` -- QR CRUD tools (exists) + +**Verification:** + +- Decomposer subagent produces structured QR items from plan JSON +- Reviewer subagents verify items against codebase with read-only tools +- Pool limits concurrent reviewers (50-100 items, max N parallel) +- Pool's onProgress updates widget with live counts +- FAIL triggers fix loop (re-spawn architect with failure report) +- PASS advances to next phase +- After 5 iterations, force-proceed + +### Milestone 4: Full Planning Loop + TUI Widget + +**Goal:** All 6 phases work with QR blocks. TUI widget shows progress. + +**Deliverables:** + +- [ ] WidgetController: state management, 1s timer, hash-based change + detection, cleanup in finally block +- [ ] Widget render function: full-card layout with metadata header (active phase in header, no tabs row), timeline rail, detail pane, and integrated latest log +- [ ] Developer role: step definitions + hooks +- [ ] Writer role: step definitions + hooks +- [ ] Phase transition routing in orchestrator (6 phases) +- [ ] Execution phases (exec-code, exec-docs): wave-based milestone execution +- [ ] Terminal gate -> plan approved +- [ ] Plan JSON -> markdown rendering + +**Files:** + +- `src/planner/ui/widget.ts` -- WidgetController + render function +- `src/planner/phases/plan-code/phase.ts` -- developer step definitions + hooks +- `src/planner/phases/plan-code/prompts.ts` -- developer step guidance +- `src/planner/phases/plan-docs/phase.ts` -- writer step definitions + hooks +- `src/planner/phases/plan-docs/prompts.ts` -- writer step guidance +- `src/planner/plan/render.ts` -- JSON -> markdown + +**Verification:** + +- Full plan-design -> plan-code -> plan-docs -> exec-code -> exec-docs flow +- TUI widget visible during workflow, removed on completion +- Widget shows correct header metadata (active phase/status + timer), step-first runtime progress bar, active subagent telemetry, and phase-appropriate modifications counters (`+delta (total)`), without a separate tabs row +- Each phase has role-specific step sequences +- Plan JSON accumulates changes across phases +- Terminal gate renders plan.md + +### Milestone 5: State Persistence + Session Resume + +**Goal:** Workflow state survives session resume. + +**Deliverables:** + +- [ ] Reconstruct workflow position from disk artifacts on session start +- [ ] `/koan plan` resumes from last completed phase if workflow in progress +- [ ] `/koan status` shows current position from in-memory state + disk + +**Verification:** + +- Start planning, exit pi, restart, `/koan plan` resumes at correct phase +- Plan directory artifacts (plan.json, context.json, qr-\*.json) survive +- In-memory WorkflowState reconstructed from disk state + +### Milestone 6: Execution Phases (exec-code, exec-docs) + +**Goal:** Phases 5-6 apply the plan: execute code changes and documentation. + +**Deliverables:** + +- [ ] Wave-based milestone execution via subagents (parallel within wave, + sequential across waves, using concurrency pool) +- [ ] Implementation subagents with isolated contexts per milestone +- [ ] Code QR + Docs QR gates during execution (same QR block pattern) +- [ ] Reconciliation step (check if milestones already satisfied) +- [ ] Widget integration: execution phases show wave progress + +Execution phases follow the same 3-sub-phase pattern as planning phases +(execution -> qr-decompose -> qr-verify). The difference is that execution +subagents apply code_changes/doc_diffs rather than producing plan JSON. + +--- + +## 7. Key Design Decisions + +### 7.1 Subagents Over In-Session Turns + +Planning workflows are long-running (1-2 hours) and generate enormous amounts +of context: codebase exploration, intermediate plan drafts, QR verification +results. Running this inside the parent session would bloat the user's context +window with artifacts they don't need. + +Every substantial LLM work phase runs in an isolated subagent process: + +- Fresh context window per phase +- No pollution of the parent session +- Natural cleanup — subagent exits, context is gone +- Parallel verification is trivially parallel (separate processes) + +The parent session's context stays clean. It contains only: the user's +original request, orchestrator status messages, and the final plan output. + +### 7.2 Self-Loading Extension for Subagent Control + +Rather than using pi's agent definition markdown files (`agents/*.md`) to +define subagent behavior, the koan extension loads itself into subagent +processes via `-e ./extensions/koan.ts`. This gives the extension full event +hook access inside the subagent, enabling: + +- **Step-level control via `context`:** Inject different instructions each turn +- **Tool enforcement via `tool_call`:** Block forbidden tools per step +- **Progress tracking via `turn_end`:** Parse output, advance state machine +- **System prompt control via `before_agent_start`:** Set role identity + +Agent markdown files only support static system prompts and tool lists. The +self-loading pattern gives dynamic, per-turn control. + +### 7.3 Parent Session for Context, Subagents for Everything Else + +| Step | Mechanism | Reason | +| --------------- | --------------------- | ----------------------------------------------- | +| Context capture | `sendUserMessage()` | Session LLM is the only entity with the context | +| Plan work | `spawn()` subagent | Architect/developer/writer need tools, isolated | +| Exec work | `spawn()` subagent | Apply code/docs changes per milestone, isolated | +| QR decompose | `spawn()` subagent | Analysis of plan artifact, isolated ctx | +| QR verify | `pool()` of subagents | Parallel verification, bounded concurrency | +| QR gate | None (code) | Deterministic routing, no LLM needed | + +The distinction is simple: context capture runs in the parent session because +the session LLM is the only entity that has the conversational understanding. +Everything else operates on self-contained artifacts (context.json, plan.json, +QR items) and runs in isolated subagents. + +### 7.4 Tool-Call-Only State Mutation + +All mutations to plan.json and qr-{phase}.json happen exclusively through +registered tool calls. No exceptions. Subagents do not produce plan JSON as +stdout output -- they invoke tools that atomically update the state files. + +Every tool follows load-mutate-save: `loadPlan(dir)` -> pure mutation -> +`savePlan(plan, dir)`. Disk is the single source of truth. File writes use +atomic tmp+rename to prevent corruption on crash. Single-writer assumption +per phase (one subagent writes at a time). + +No CAS versioning -- entities have no version field. Concurrency is handled +by advisory `.lock` files: every mutating tool call wraps the load-mutate-save +cycle in `withFileLock(filePath, fn)`, which acquires `.lock` (O_CREAT | +O_EXCL) before reading the file and releases after atomic write. Retry with +backoff handles transient contention (50ms interval, 5s timeout). + +In practice, the only phase where concurrent writers exist is QR-verify, where +a pool of reviewer subagents update the same `qr-{phase}.json`. Even there, +each agent updates different items, so contention is low. The lock file is a +safety net, not a performance bottleneck. + +**Tool registration and phase permissions:** + +All tools register unconditionally at init (pi snapshots tools during +`_buildRuntime()`). Access control uses two layers: + +1. **Phase permissions (`checkPermission()`) = outer boundary.** A + default-deny map from phase key to allowed tool names. Read tools + (read, bash, grep, glob, find, ls) always pass. Write tools (edit, + write) always blocked during planning. Phase-specific koan tools are + enumerated explicitly. Missing phase keys are blocked. + +2. **Step gate = inner constraint.** Within a phase, certain tools unlock + at specific steps. Uses a **blocklist** pattern: "block these specific + tools until step N." Everything the gate doesn't care about defers to + `checkPermission`. (A whitelist would block read tools and future + pi-native tools that checkPermission already approved.) + +**WorkflowDispatch** decouples static tool registration from dynamic phase +routing. Tools are registered once at init with execute callbacks that read +from mutable dispatch slots. Each phase hooks its handlers into the dispatch +when activated (`hookDispatch`) and unhooks when done (`unhookDispatch`). +Throws if a slot is already occupied -- prevents silent misrouting. + +**PlanRef** provides the same indirection for the plan directory path. +Tools need the plan directory at execute time but it is unknown at init +(created at runtime). PlanRef is a mutable `{ dir: string | null }` set +when the plan directory becomes available. + +**Current tool count: 44.** This is sub-optimal but out of scope to optimize +now. All tools register at init because pi snapshots the tool list during +`_buildRuntime()` and flags are unavailable at that point, making conditional +per-role registration impossible. The LLM sees all 44 tool descriptions even +when only ~5 are callable in its current phase. Phase permissions block +unauthorized calls at runtime. + +**Future optimization:** Per-phase, per-subagent tool registration. This +would require either a pi platform change (deferred tool registration) or +spawning subagents with phase-specific extension entry points that only +register the tools relevant to that phase. Not worth the complexity until the +basic workflow is proven end-to-end. + +| Phase key | Allowed koan tools | +| --------------- | ---------------------------------------------------- | +| context-capture | koan_store_context, koan_complete_step | +| plan-design | koan_complete_step, plan getters, plan setters, | +| | entity tools (except code_change tools) | +| plan-code | koan_complete_step, plan getters, code_change tools, | +| | koan_set_intent | +| plan-docs | koan_complete_step, plan getters, | +| | koan_set_change_doc_diff, koan_set_change_comments, | +| | koan_set_readme_entry, koan_set_diagram | +| qr-\* | koan_complete_step, plan getters, QR tools | + +Markdown rendering is a terminal step, not a runtime artifact. This prevents +the common failure mode where the LLM renders a partial plan and calls it done. + +### 7.5 Need-to-Know: No Internal Paths in User-Facing Output + +Internal file paths (`plan.json`, `context.json`, `qr-plan-design.json`, +`metadata.json`, `events.jsonl`, `state.json`) are implementation details that +the LLM and user must never see in tool results, notifications, or status +output. These paths are secret -- exposing them leaks the storage format and +invites the LLM to access files directly instead of through the tool API. + +Data reaches the LLM through exactly two channels: + +1. **Prompts.** Phase code embeds data directly into step prompts. Example: + QR-verify step 1 includes the QR item content as part of the CONTEXT + prompt. The LLM never knows where it came from on disk. + +2. **Tool calls.** Getter tools (`koan_get_plan`, `koan_get_context`, etc.) + return structured data. The tool implementation reads from disk; the LLM + sees only the result. + +Error messages follow the same principle. "Failed to store context" is +acceptable; "Failed to write context.json" is not. The user should see +phase-level outcomes ("Plan design complete", "QR decompose produced no +items"), never file-level details. + +### 7.6 Context Window Management + +Each subagent starts with a fresh context window containing only: + +- The role system prompt (loaded from `~/.claude/agents/.md`) +- The step 1 prompt (injected via `context` event on first LLM call) +- The plan directory path (reads context.json and plan.json as needed) +- The task message (positional CLI argument) + +No conversation history accumulates across phases. Each phase starts clean. +Within a phase, the extension's `context` hook can prune the subagent's +growing message history if needed (e.g., removing verbose tool output from +earlier turns). + +### 7.7 QR Iteration Limit + +Maximum 5 iterations per QR phase. All severity levels (MUST, SHOULD, COULD) +block on all iterations. If items still fail after 5 iterations, force-proceed +and document remaining issues. + +### 7.8 Tool Calls for Step Transitions (Uniform Pattern) + +Step transitions throughout the system use **registered tool calls**, not +`sendUserMessage()` chaining. This applies to both subagents and the parent +orchestrator's context capture. The LLM calls a tool to signal completion; +the tool result contains the next step's instructions. + +**Why this matters for the orchestrator:** + +Context capture runs as a single agent loop where the LLM calls +`koan_complete_step` to +advance from drafting to verifying to refining. The tool result delivers the +next sub-phase's instructions. This costs slightly more context (tool call +entries in the message history) but provides: + +1. **Consistency.** One step transition mechanism everywhere. The same + `koan_complete_step` tool works in parent mode and subagent mode. No + special-casing for `-p` vs interactive. + +2. **Reliability.** `sendUserMessage()` from `agent_end` starts a new agent + loop, which in `-p` mode is not processed (pi exits). Tool calls work + within a single agent loop regardless of mode. + +3. **Simpler control flow.** The extension does not need to track whether + it is in parent mode or subagent mode to decide HOW to transition steps. + It always uses tool results. + +4. **Clean mapping to reference planner.** The reference planner's "NEXT + STEP: Command" directive maps 1:1 to `koan_complete_step`. The reference + planner's bash tool call is the step transition mechanism. Our tool call + is the same pattern with a dedicated tool. + +**What `sendUserMessage()` is still used for:** + +Only the initial trigger. When the user types `/koan plan `, the +orchestrator calls `sendUserMessage()` once to inject the context capture +prompt into the parent session. This starts the agent loop. From that point +on, all step transitions within context capture happen via tool calls. After +context capture completes (the LLM calls `koan_store_context`), the +`onComplete` callback spawns the architect subagent synchronously within the +tool call -- no more `sendUserMessage()`. + +**The context cost is acceptable.** Each `koan_complete_step` call adds one +tool-call entry and one tool-result entry to the message history. For a +6-step workflow, that is 5 tool call/result pairs. This is negligible compared +to the codebase exploration tool calls the LLM makes during each step. + +### 7.9 Need-to-Know Principle (Invariant) + +**The LLM always operates on a need-to-know basis.** When given the choice +between exposing more or less information to the LLM, always choose less. +This is a permanent invariant of the system -- it applies to every prompt, +every context injection, every system message, across all phases and roles. + +LLMs get confused when given extraneous information. They latch onto +irrelevant details, hallucinate connections between unrelated facts, and +lose focus on their actual task. The antidote is radical information +scoping: each LLM invocation receives exactly the information it needs to +perform its specific task, and nothing more. + +Concrete implications: + +- **No implementation details in prompts.** The LLM does not need to know + about temp directories, state file paths, context.json internals, the + orchestrator's phase routing, or any other mechanism of the system that + controls it. It needs to know what to produce, not how the plumbing works. +- **No full plan state when partial suffices.** A QR reviewer verifying + design items does not need the code plan or docs plan. Pass only the + relevant section. +- **No accumulated history across phases.** Each subagent starts with a + fresh context containing only what it needs. Prior phases' exploration + artifacts, tool output, and intermediate reasoning are gone. +- **No meta-instructions about the workflow.** The LLM does not need to + know it is "step 3 of a 14-step planner workflow". It needs to know + "analyze this architecture and produce a plan". +- **No defensive over-specification.** Do not preemptively explain edge + cases, failure modes, or system constraints unless they directly affect + the LLM's current task. Over-specifying causes the LLM to optimize for + the constraints rather than the task. +- **No internal file paths in runtime output.** Tool results, notifications, + and status messages must never mention `plan.json`, `context.json`, + `qr-plan-design.json`, or any other storage artifact. Data reaches the + LLM only through prompts and getter tool results. See 7.5 for details. + +This principle is what makes the inversion-of-control architecture work. +The orchestrator code knows the full picture. Each LLM invocation sees +only its narrow slice. The less the LLM knows about the system around it, +the better it performs its specific task. + +### 7.10 Temp Files for Subagent Context + +Subagent processes need input files. The parent writes temp files (context +JSON, plan state, QR failure reports) before spawning and cleans up after. +This is the one place where file-based coordination is necessary — process +boundaries require it. But the files are: + +- Written by the parent (deterministic, not LLM-generated) +- Read by the subagent's system prompt loader (no LLM file discovery) +- Cleaned up immediately after the subagent exits + +### 7.11 Diagram Workflow + +Diagrams use a two-phase workflow that separates semantic correctness from +visual rendering: + +**Phase 1 -- Architect (plan-design phase):** + +The architect creates diagram_graphs as graph IRs using tools: + +1. `koan_add_diagram` -- create diagram header (type, scope, title) +2. `koan_add_diagram_node` -- add nodes (3-7 recommended for readability) +3. `koan_add_diagram_edge` -- add edges (validates source/target nodes exist) + +The architect leaves `ascii_render` as null. Separation of concerns: +architect validates connectivity, TW optimizes layout. + +**Phase 2 -- Technical Writer (plan-docs phase):** + +The TW renders each diagram_graph to ASCII using `koan_set_diagram` +(setting the `ascii_render` field). + +**Diagram types:** + +| Type | When to use | +| ------------ | ---------------------------------------------- | +| architecture | Services, APIs, SDKs, component boundaries | +| state | Explicit state machines, protocol lifecycles | +| sequence | Multi-party request/response, time-ordered | +| dataflow | ETL pipelines, streaming, data transformations | + +Default to `architecture`. Use others only when the plan explicitly involves +state machines, multi-party protocols, or data pipelines. + +**Scope values:** + +| Scope | Purpose | +| --------------------- | ----------------------------------- | +| `overview` | Hero diagram after overview section | +| `invisible_knowledge` | Architectural mental model for LLMs | +| `milestone:M-XXX` | What this specific milestone adds | + +**Skip criteria:** Skip diagram generation for pure refactoring, single-file +changes, documentation-only milestones, or plans lacking structural keywords +(services, layers, flow, protocol). Empty `diagram_graphs` is valid state. + +**ASCII conventions:** Fixed-width, 80 chars max width. Box corners `+`, +horizontal edges `-`, vertical edges `|`, arrows `v ^< > --> <--`. + +--- + +## 8. What We Are NOT Porting + +The current planner has significant complexity that is unnecessary in the +pi extension architecture: + +- **CLI mutation scripts** (`cli/plan.py`, `cli/qr.py`): Python CLI scripts + for state mutation. Replaced by pi extension tool registration (section 7.4). + Delivery mechanism changes from CLI invocation to tool calls. CAS versioning + is dropped entirely; concurrency uses `.lock` files instead (section 7.4). +- **Thin router pattern** (`shared/routing.py`): Five router scripts that + dispatch between execute and fix modes. Replaced by the orchestrator's + deterministic gate logic. +- **Question relay handler**: Not implemented in initial version. May be + added later if subagents need user input during execution. +- **Temp-directory state_dir**: The Python planner scattered state files in + temp directories. Replaced by a persistent plan directory + (`~/.koan/plans//`) with `plan.json`, `context.json`, + `qr-{phase}.json`, and `metadata.json`. Disk is the source of truth for + all data that must cross process boundaries. Ephemeral state (workflow + phase, step counters) is in-memory only. +- **Template dispatch** (`subagent_dispatch`, `template_dispatch`): Prompt + formatting for getting the LLM to spawn sub-agents. Replaced by direct + process spawning from the extension. +- **Constraint enforcement via prompt**: `ORCHESTRATOR_CONSTRAINT_EXTENDED`, + `format_forbidden()`, etc. Replaced by `tool_call` event blocking. +- **Agent markdown definitions**: Static `.md` files with frontmatter. + Replaced by the self-loading extension pattern with dynamic event hooks. + +--- + +## 9. Dependencies + +**Required packages (peerDependencies):** + +- `@mariozechner/pi-coding-agent` — ExtensionAPI, event types +- `@mariozechner/pi-agent-core` — AgentMessage types +- `@sinclair/typebox` — Tool parameter schemas (if registering tools) + +**Dev dependencies:** + +- `typescript` +- `jiti` (provided by pi's extension loader — no explicit dep needed) + +**Runtime:** + +- `pi` CLI installed and configured with API key +- Model access (for parent session turns and subagent turns) + +--- + +## 10. Open Questions + +1. **Subagent model selection.** Should subagents inherit the parent's model + or use a specific model per role? The architect may benefit from a stronger + model than the reviewer. Start with the parent's model, add `--koan-model` + override later. + +2. ~~**Plan JSON schema.**~~ Resolved: ported exactly from existing planner's + Pydantic schema. See section 3.4. + +3. ~~**Step completion detection.**~~ Resolved: explicit tool calls. The LLM + calls `koan_complete_step` to signal step completion. The tool result + contains the next step's instructions. No heuristic parsing of LLM output. + See sections 2.3 and 7.7. + +4. **Context capture quality.** The session LLM produces context.json — but + how do we ensure it captures _everything_ relevant? Structural validation + checks that categories are present, not that they're complete. The + self-verification checklist helps but is still LLM-dependent. This is an + inherent limitation: the LLM is the only entity that knows what's in its + own context. Mitigation: clear prompts, specific category requirements, + and retry on structural gaps. + +5. **Subagent timeout.** How long should a subagent be allowed to run? + Planning workflows are long — the architect may need 20+ minutes of + exploration. Default: no timeout. Add a configurable `--koan-timeout` flag. + +6. **Error recovery.** What happens if a subagent crashes mid-phase? Options: + retry from the beginning of the phase, retry from the last known good state + (requires checkpointing), or fail and report. Start with retry-from-scratch, + add checkpointing later. + +7. **Testing strategy.** How to test the self-loading extension pattern? + Unit tests for deterministic logic (gate routing, state transitions, step + definitions). Integration tests that spawn real subagent processes with + mock or cheap models. Manual testing with real models for end-to-end + validation. + +8. **Context capture in the parent session.** Using `sendUserMessage()` for + context capture adds messages to the parent session's context window. + This is intentionally minimal (one prompt + one response), but we should + monitor whether it causes issues in very long sessions. If so, the context + capture messages could be filtered out of subsequent turns via the + `context` hook once context.json has been produced. + +--- + +## 11. Runtime Widget Design Decisions + +These decisions are normative for runtime rendering. + +### 11.1 Step-first progress semantics + +- Runtime progress is shown as `step : / · ` plus a + progress bar. +- The progress bar reflects subagent workflow steps, not QR fix-loop cycles. +- QR loop counters are orchestration internals and are not primary progress UI. +- In pooled `qr-verify`, group progress (`done/total groups`) is the step/progress source. + +### 11.2 Active subagents pane + +Render a dedicated `active subagents` block with: + +- `role` +- `model` +- `load` (`queued`, `active`, `done`) +- `mode` (`single` or `pool ×N`) + +`x<N>` means configured pool capacity (target parallelism), not current active count. + +### 11.3 Modifications pane (`+delta (total)`) + +Render modifications in paired form: + +- `+2 (6)` means delta `+2`, current total `6`. + +This allows users to track both recent activity and current artifact size. + +### 11.4 Phase-specific modification categories + +- **plan-design / plan-code / plan-docs / execution:** + - `milestones`, `decisions`, `intents`, `changes` +- **qr-decompose:** + - `qr items added`, `qr items updated`, `groups assigned` +- **qr-verify:** + - explicit placeholder message: + `qr-verify counters not instrumented yet` + +The placeholder is required; absence of counters must be visible, not silent. + +### 11.5 Header-first metadata (no tabs row) + +- Keep a full top border and metadata header row: + `Planning · <active phase> · <status>` + right-aligned elapsed timer. +- Remove dedicated tabs/chips row under the title. +- Keep phase progression in the left timeline rail. + +### 11.6 Header truncation order (deterministic) + +When width is constrained, compact in strict order: + +1. Abbreviate status (`CURRENT` -> `CUR`, `UPCOMING` -> `UP`) +2. Drop status chunk +3. Abbreviate phase label (`Plan design` -> `Design`) +4. Ellipsize phase tail + +Header never wraps; compaction/truncation must keep timer right-aligned. + +### 11.7 Generic rendering requirement + +Runtime rendering remains role-agnostic. It must not branch on reviewer-specific +presentation logic. Data-driven fields (`role`, `parallelCount`, `model`, +`queued/active/done`, step/progress, modifications kind) determine output. diff --git a/plans/2026-03-09-refactoring.md b/plans/2026-03-09-refactoring.md new file mode 100644 index 0000000..ed2d4fc --- /dev/null +++ b/plans/2026-03-09-refactoring.md @@ -0,0 +1,2465 @@ +# Koan Epoch: Refactoring Plan + +> **Authoritative rewrite spec: §11 (2026-03-11), amended by §12 +> (2026-03-12).** Sections §1–§10 are historical context. §11 contains +> the resolved decisions from the full codebase analysis session. §12 +> documents scope/lifecycle mismatches discovered post-implementation +> and the fixes required. Implementers should read §11 first, then §12 +> for the outstanding fixes, then reference earlier sections only for +> background understanding. + +This document describes the refactoring of koan from its current monolithic +plan-then-review pipeline into a spec-driven execution orchestrator for pi. +**Backwards compatibility with the current plan schema, phase structure, and QR +block pattern is not a concern.** This is a clean-sheet redesign of the +workflow, retaining the infrastructure that works and discarding the +architecture that doesn't. + +--- + +## 1. Terminology + +### Domain model + +Three terms describe the work. + +- **Epic**: The top-level decomposition of user intent into stories. Contains + the spec, captured decisions, and story sketches. One epic per user request. +- **Story**: A coherent unit of work — something a senior engineer would + consider one PR. Each story gets its own plan when it's time to execute. +- **Plan**: The detailed implementation plan for a single story, created + just-in-time when the story is selected for execution. Contains file-level + change descriptions, curated code context, and verification checks. + +### System roles + +Seven roles operate on the domain model. One is deterministic code; six are +LLM subagents. + +- **Driver**: The deterministic TypeScript process that manages subagent + lifecycle. Spawns subagents, polls for completion, relays IPC, reads state + files, decides what to spawn next. No LLM reasoning. The compiler analogy: + gcc's driver program invokes preprocessor, compiler, assembler, linker in + sequence — it doesn't do the work itself. Replaces the current `session.ts`. +- **Intake**: A strong-model subagent that reads the conversation, extracts + structured context, identifies gaps, and interactively resolves ambiguities + with the user. Produces `context.md` and `decisions.md`. +- **Scout**: A cheap-model subagent that answers one narrow codebase question + and writes its raw findings to a markdown file. No interpretation, no + recommendations. Multiple scouts run in parallel via `pool()`. Each scout + writes a single output file (e.g., `scouts/{scout-id}.md`); the driver + collects file paths after `pool()` completes and passes them to the + consuming subagent (decomposer or planner). +- **Decomposer**: A strong-model subagent that splits the epic into story + sketches. Receives intake output and scout reports. Produces `epic.md` and + per-story `story.md` files. +- **Orchestrator**: A strong-model subagent responsible for decisions at + critical points during execution. The driver spawns it with different step + sequences depending on the decision point: pre-execution analysis (dependency + mapping, sequencing) and post-execution assessment (verification, learning + propagation, deviation classification, next-story selection). Reads state + from files, writes decisions to files. Each invocation is a fresh subagent + spawn with a clean context window — the orchestrator is not a long-running + process that accumulates context across stories. The driver spawns it, it + reads the current state files, it writes decisions, it exits. The next time + the driver needs the orchestrator, it spawns a new one. This is a + deliberate architectural property: Koan's subagent model gives every + invocation a clean context by design. +- **Planner**: A strong-model subagent that produces the detail plan for a + single story just-in-time. Receives the story sketch, decisions, and scout + reports. Produces `plan.md`, `context.md`, and `verify.md`. +- **Executor**: The only subagent that writes code. Receives `plan.md` and + `context.md`, implements the plan. Uses a standard-tier model. + +All six LLM roles use the step-based phase class lifecycle and get their own +EventLog. The driver controls when each role runs and what happens with its +output (INV-1). + +### Driver vs orchestrator boundary + +The driver and orchestrator are the only two actors that influence workflow +progression — every other role (intake, scout, decomposer, planner, executor) +has a clear, scoped job that doesn't affect what happens next. The orchestrator +is the only agent whose decisions guide the workflow: which story to work on, +whether a story passed verification, whether to retry or escalate. The other +five LLM roles produce artifacts and exit. Their boundaries are obvious. + +The driver/orchestrator boundary is the one point of common misunderstanding, +because both actors influence "what happens next" but through fundamentally +different mechanisms. The decision rule: + +> The driver reads STATE (status values, exit codes, file existence) and +> applies RULES. The orchestrator reads CONTENT (artifacts, code, verification +> results) and applies JUDGMENT. + +#### Seems mechanical, actually requires judgment → orchestrator + +**Running verify.md checks.** ✅ Orchestrator reads `verify.md`, runs checks +via `bash`, interprets results, calls `koan_complete_story` or +`koan_retry_story`. ❌ Driver parses `verify.md` and runs the checks — it +doesn't know _which_ commands to run (planning artifact) or whether "2 tests +failed" is blocking or expected. + +**Selecting the next story.** ✅ Orchestrator reads dependency graph in +`epic.md`, checks which stories are `done`, calls `koan_select_story`. +❌ Driver sorts stories by dependency order — dependency analysis requires +reading artifact content, which is judgment. + +**Assessing partial verification (8/10 checks pass, 2 fail).** ✅ Orchestrator +examines the 2 failures in context: "CSS test is flaky; API test reveals real +bug" → `koan_retry_story` citing the real issue. ❌ Driver counts pass/fail +ratio and applies a threshold — it has no notion of failure severity. + +#### Seems like a decision, actually a deterministic rule → driver + +**Retry budget exhaustion.** ✅ Driver decrements retry counter after each +`retry` status; at zero, sets status to `escalated` — orchestrator is never +spawned. ❌ Orchestrator checks "how many retries have we done?" — it can't, +fresh context each invocation. + +**Epic completion.** ✅ Driver reads all `state.json` files, finds every story +`done` or `skipped`, reports completion. ❌ Orchestrator calls +`koan_complete_epic` — no such tool, driver infers from aggregate state. + +**Scout failure during planning.** ✅ Driver records failures via `pool()`, +proceeds with partial results. ❌ Orchestrator is consulted — scouts are +part of the fixed cycle, not a judgment call. + +#### Seems like it needs a tool, actually uses `write` → orchestrator + +**Propagating learnings.** ✅ Orchestrator uses `write` to update `story.md` +files and append to `decisions.md` with `[autonomous]` marker. ❌ Driver +detects S-001 modified auth files and triggers updates — it doesn't read +code or understand what changed. + +**Splitting a story mid-epic.** ✅ Orchestrator uses `write` to create new +`story.md` files, calls `koan_skip_story` on the original. ❌ Orchestrator +calls `koan_create_story(...)` — no such tool; artifact creation uses `write`, +tools exist only for state transitions the driver acts on. + +#### Split responsibility — both actors, different concerns + +**Retry verdict.** ✅ Orchestrator (qualitative): "this failure is fixable" → +`koan_retry_story`. ✅ Driver (quantitative): "budget exhausted" → force +`escalated`. ❌ Either actor does both — orchestrator doesn't count retries, +driver doesn't judge failure severity. + +**Plan-reality mismatch during execution.** ✅ Simple clarification → executor +asks user via `koan_ask_question` in-place. ✅ Fundamental spec error → +executor exits, orchestrator (post-execution) classifies deviation, calls +`koan_escalate`. ❌ Orchestrator spawned mid-execution — it runs at cycle +boundaries only. ❌ Driver analyzes executor output — it reads exit codes and +status values, nothing else. + +### Model tiers + +Three model tiers allocate cost to capability. + +- **Strong**: High-capability reasoning models (e.g., Opus, o3). Used where + judgment quality is critical: intake, decomposition, orchestration, planning. +- **Standard**: Competent coding models (e.g., Sonnet, GPT-4o). Used where + the task is well-specified and the model follows instructions rather than + making architectural decisions: execution. +- **Cheap**: Fast, low-cost models (e.g., Haiku, Grok-fast). Used where the + task is narrow and mechanical: scouting. + +--- + +## 2. What the End System Looks Like + +### 2.1 One-sentence summary + +Koan becomes a two-phase system: an epic creation pipeline that front-loads +spec clarity and story decomposition, followed by a JIT execution loop where +the orchestrator sequences story planning, execution, and verification one +story at a time against the _current_ codebase. + +### 2.2 The two-phase architecture + +**Phase A: Epic Creation** (driver-managed, no orchestrator) + +The driver spawns dedicated subagents in sequence: intake (interactive), +decomposer with scouts, then the spec review gate. + +``` +User prompt ─► Intake ─► Epic Decomposition ─► Story Sketches + │ │ + │ (interactive: asks ▼ + │ user questions) Spec Review Gate + ▼ + context.md + + decisions.md +``` + +**Phase B: Epic Execution** (orchestrator-managed) + +The driver spawns the orchestrator at each decision point, reads its output, +then deterministically spawns the next subagent. + +``` +┌────────────────────────────────────────────────────────────┐ +│ Driver spawns orchestrator (pre-execution step sequence) │ +│ → selects first story, writes state files │ +│ │ +│ Driver spawns planner (+ scouts) for selected story │ +│ → produces plan.md + context.md + verify.md │ +│ │ +│ Driver spawns executor │ +│ → implements the plan │ +│ │ +│ Driver spawns orchestrator (post-execution step sequence) │ +│ → verifies, propagates learnings, selects next story │ +│ │ +│ Driver reads state files → loops or completes │ +└────────────────────────────────────────────────────────────┘ +``` + +### 2.3 Artifacts produced + +All state lives under `~/.koan/state/`. Nesting captures relationships — +no cross-reference IDs needed. + +``` +~/.koan/state/epics/{epic-id}/ +├── context.md # conversation summary, indices, testing strategy +├── decisions.md # explicit decisions from intake + [autonomous] decisions +├── epic.md # overview + story list + sequencing +├── scouts/ # decomposition-phase scout output files +│ └── {scout-id}.md # raw findings for one codebase question +├── stories/ +│ ├── {story-id}/ +│ │ ├── story.md # story sketch (scope, acceptance, deps) +│ │ ├── status.md # execution state, outcome, notes +│ │ ├── scouts/ # per-story scout output files (JIT planning phase) +│ │ │ └── {scout-id}.md +│ │ └── plan/ +│ │ ├── plan.md # file-level implementation plan (JIT) +│ │ ├── context.md # curated code snippets for executor +│ │ └── verify.md # acceptance checks + test strategy +│ └── ... +└── subagents/ # per-subagent EventLog dirs (runtime) +``` + +All planning artifacts are markdown. Per-subagent EventLog directories +(`events.jsonl` + `state.json`) live under `subagents/`. + +**Artifact flow by phase:** + +| Phase | Reads | Writes | +| --------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| Intake | `conversation.jsonl` | `context.md`, `decisions.md` | +| Scouts (decomp) | Codebase (via READ_TOOLS) | `scouts/{scout-id}.md` | +| Decomposition | `context.md`, `decisions.md`, `scouts/*.md` | `epic.md`, per-story `story.md` | +| Spec review | `epic.md`, `story.md` files | User edits to `epic.md`, `story.md` | +| Pre-execution (orch) | `epic.md`, `decisions.md` | `status.md` (via `koan_select_story`) | +| Scouts (per-story) | Codebase (via READ_TOOLS) | `stories/{id}/scouts/{scout-id}.md` | +| Detail-plan | `story.md`, `decisions.md`, `scouts/*.md` | `plan/plan.md`, `plan/context.md`, `plan/verify.md` | +| Execute | `plan/plan.md`, `plan/context.md` | Codebase changes | +| Post-execution (orch) | `verify.md`, `plan.md`, `status.md`, git diff, `epic.md` | `status.md` (via tools), `story.md` (remaining), `decisions.md` ([autonomous]), `epic.md` | + +Each phase reads only the artifacts produced by prior phases. The executor is +the only role that writes to the codebase; all other roles write to the epic +directory. + +### 2.4 Human interaction model + +One mandatory human gate: **spec review**, after epic creation produces story +sketches. The user confirms scope, adjusts sketches, adds or removes stories. + +After that, execution is autonomous by default. The system escalates to the +human only when: + +- **Out-of-plan deviation**: execution revealed something that requires the + original spec to change. The escalation presents: problem description, + candidate solutions, recommended solution, custom response option. +- **Verification failure**: a story fails verification after the retry budget + (default 2 retries). +- **Unresolvable ambiguity**: any subagent encounters something it cannot + resolve without human input. + +Everything else is in-plan — the orchestrator handles it autonomously. The +classification test: does this change what the user asked for, or just how we +deliver it? In-plan adjustments (refine acceptance criteria, split/merge +stories, reorder execution) are recorded in `decisions.md` with an +`[autonomous]` marker for traceability. + +**Mid-execution escalation via `koan_ask_question`.** All subagents have access +to the existing `koan_ask_question` tool, which uses file-based IPC to pause +execution, present a question to the user in the parent session, and resume +after the user responds. This means any subagent — intake, planner, executor, +orchestrator — can ask the human a focused question at the point where the +ambiguity arises, without aborting its session. The subagent writes the +question to an IPC file, polls until the parent writes back an answer, and +continues with the response in its context window. This eliminates the need +for complex checkpoint/resume mechanisms: instead of saving state and +restarting, the agent simply waits for the answer and proceeds. + +### 2.5 Model allocation + +| Role | Model tier | Why | +| ------------ | ---------- | ------------------------------------------ | +| Intake | Strong | Reasoning about gaps, not summarization | +| Decomposer | Strong | Architectural judgment | +| Scout | Cheap | File discovery, pattern gathering | +| Orchestrator | Strong | Cross-story reasoning, verification | +| Planner | Strong | Synthesizes scout findings into plan | +| Executor | Standard | Well-specified task, instruction-following | + +Cheap models gather, strong models decide, standard models execute. + +### 2.6 Story state machine + +Each story transitions through a fixed set of states. The driver manages +intermediate transitions by writing to `state.json`; the orchestrator's +tools write terminal/routing states to both `state.json` (for the driver) +and `status.md` (for LLMs). The driver reads `state.json` to determine +next actions. + +``` +pending ──[koan_select_story]──► selected + │ │ + │ (driver: fixed) + │ │ + │ planning ──► executing ──► verifying + │ │ + │ ┌───────────────────────┤ + │ │ │ │ + │ [complete_story] [retry_story] [escalate] + │ │ │ │ + │ ▼ ▼ ▼ + │ done retry escalated + │ │ │ + │ (driver: re- (driver: + │ spawn exec) ask user) + │ │ │ + │ executing (user responds) + │ │ │ + │ verifying verifying + │ + └──[koan_skip_story]──► skipped +``` + +States in brackets (`[tool_name]`) are orchestrator tool calls. States +marked `(driver: ...)` are deterministic driver transitions. + +The `planning`, `executing`, and `verifying` intermediate states are +managed by the driver — it writes them to `state.json` as it spawns +the corresponding subagents. The orchestrator's tools write terminal or +routing states (`selected`, `done`, `retry`, `escalated`, `skipped`) to +both `state.json` and `status.md`. + +### 2.7 Tool inventory + +The driver owns the fixed per-story cycle (plan → execute → verify). The +orchestrator owns judgment calls at cycle boundaries. A tool exists only +when the driver must act on the result — artifact modifications (updating +`story.md`, appending to `decisions.md`) use the existing `write` tool. + +**Design principle**: each tool is atomic — it transitions exactly one +entity to exactly one new state. + +| Tool | Purpose | Parameters | State Transition | +| --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------- | +| `koan_select_story` | Pick which story to work on next | `story_id: string` | Story: `pending` or `retry` → `selected` | +| `koan_complete_story` | Mark a story as verified and done | `story_id: string` | Story: `verifying` → `done` | +| `koan_retry_story` | Mark a story for re-execution after failed verification | `story_id: string`, `failure_summary: string` | Story: `verifying` → `retry` | +| `koan_escalate` | Flag a story for human decision | `story_id: string`, `problem: string`, `candidates: string[]`, `recommended: string` | Story: `verifying` → `escalated` | +| `koan_skip_story` | Mark a pending story as no longer needed | `story_id: string`, `reason: string` | Story: `pending` → `skipped` | +| `koan_complete_step` | (existing) Advance to next step within a phase | `thoughts?: string` | Internal step counter | +| `koan_ask_question` | (existing) Pause and ask the user a question | `questions: QuestionItem[]` | None (synchronous) | + +**What's not here and why:** + +- No `launch_scouts` — the driver spawns scouts as part of the fixed + planner workflow. Not an orchestrator decision. +- No `request_plan_detail` — the driver spawns the planner after + `koan_select_story`. Fixed sequence. +- No `trigger_review` — the driver spawns the orchestrator (post-execution + step sequence) after the executor exits. Fixed sequence. +- No `update_story` — the orchestrator uses the `write` tool to modify + `story.md` files directly. Not a state transition the driver acts on. +- No `complete_epic` — the driver infers epic completion from state: all + stories are `done` or `skipped`. No explicit signal needed. + +**Permission map for the orchestrator:** + +```typescript +[ + "orchestrator", + new Set([ + "koan_complete_step", + "koan_ask_question", + "koan_select_story", + "koan_complete_story", + "koan_retry_story", + "koan_escalate", + "koan_skip_story", + ]), +]; +``` + +Plus READ_TOOLS (always allowed) and Write scoped to the epic directory +(planning subagent tier). + +### 2.8 Driver state management + +The driver reads state, not signals. After the orchestrator exits, the +driver reads `state.json` for each story and applies deterministic rules: + +- Any story with status `retry`? → Re-spawn executor (decrement retry + budget; if exhausted, set status to `escalated` and present to user). +- Any story with status `escalated`? → Present escalation to user, pause. +- Any story with status `selected`? → Spawn planner for it. +- All stories `done` or `skipped`? → Epic complete. +- None of the above? → Error (orchestrator exited without making a + routing decision). + +Structured execution state (retry counts, current phase within the +per-story cycle, etc.) lives in `state.json` alongside `status.md`. +The driver reads only JSON; LLMs read only markdown. Orchestrator tools +bridge both by writing to both formats atomically (see §9.1). + +### 2.9 Responsibility map + +| Action | Actor | Tool / Mechanism | Trigger | +| ------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | +| Export conversation | Driver | `exportConversation()` | User invokes `koan_plan` | +| Create epic directory | Driver | `fs.mkdir()` | After export | +| Context capture + elicitation | Intake | `koan_complete_step`, `koan_ask_question`, `write` | Driver spawns after directory creation | +| Codebase scouting (decomp) | Scouts (parallel) | READ_TOOLS, `koan_complete_step`, `write` | Driver spawns after intake exits | +| Epic decomposition | Decomposer | `koan_complete_step`, `write` | Driver spawns after scouts complete | +| Spec review | User via driver UI | Approve/edit/remove widget | Driver presents after decomposer exits | +| Dependency analysis + first story selection | Orchestrator (pre-exec) | `koan_select_story`, `koan_complete_step`, `write` | Driver spawns after user approves spec | +| Codebase scouting (per-story) | Scouts (parallel) | READ_TOOLS, `koan_complete_step`, `write` | Driver spawns after reading `selected` status | +| Produce detail plan | Planner | `koan_complete_step`, `write` | Driver spawns after scouts complete | +| Implement story | Executor | WRITE_TOOLS, `koan_complete_step`, `koan_ask_question` | Driver spawns after planner exits | +| Verify + assess + propagate + select next | Orchestrator (post-exec) | `koan_complete_story` / `koan_retry_story` / `koan_escalate`, `koan_select_story` / `koan_skip_story`, `write`, `koan_complete_step` | Driver spawns after executor exits | +| Re-execute on retry | Executor | Same as implement | Driver reads `retry` status, re-spawns with failure context | +| Present escalation | Driver | IPC / ask UI | Driver reads `escalated` status | +| Learning propagation | Orchestrator (post-exec) | `write` (modifies `story.md`, `decisions.md`) | During post-execution steps | +| Epic completion | Driver | Detects all stories `done`/`skipped` | After orchestrator exits without selecting a new story | + +--- + +## 3. What We Keep + +**Inversion of control (INV-1).** The driver manages all workflow transitions. +LLM subagents are workers within phases, never coordinators across phases. + +**Step-based subagent lifecycle.** All subagents use the step-based phase class +pattern: constructor registers event hooks, `begin()` dispatches, +`handleStepComplete()` advances steps. Output validation is the +orchestrator's responsibility (post-execution verification), not a method +on the phase class. + +**Self-loading extension pattern (AD-2).** Same `extensions/koan.ts` serves +driver and subagent modes via CLI flag detection. + +**Tool-call-driven step transitions (AD-4).** `koan_complete_step` with +`thoughts` parameter, the invoke-after pattern (AD-7), and the two-part +gate remain. + +**Default-deny tool permissions (AD-13).** Centralized permission map, unknown +tools blocked. Extended with two new tiers: planning subagents get Write +scoped to the epic directory (cannot modify the codebase), executor subagents +get full WRITE_TOOLS to the codebase. `koan_ask_question` is available to all +subagent roles except scout — scouts are narrow-scope investigators that +should not need user interaction. All other roles can escalate to the human +mid-execution. + +**Disk-backed mutations (AD-14).** Immediate persistence via atomic writes, +extended to the new markdown file structure. + +**Subagent spawning and pool infrastructure.** `spawnSubagent()`, its helpers, +and `pool()` for parallel execution are reused as-is. New roles are new spawn +functions delegating to the same core. + +**Per-subagent EventLog.** `EventLog`, `readProjection()`, `readRecentLogs()` +reused. Every subagent gets its own log directory under `{epic-dir}/subagents/`. + +**IPC mechanism and `koan_ask_question`.** `readIpcFile()`, `writeIpcFile()`, +`pollWithIpcDetection()` reused. The `koan_ask_question` tool — which lets any +subagent pause, present a question to the user, and resume with the answer — +carries over as the universal mid-execution escalation mechanism. Ask UI +components (`askSingleQuestionWithInlineNote`, `askQuestionsWithTabs`) carry +over. + +**Widget UI primitives.** `WidgetController` and rendering primitives reused +as building blocks. Layout and content get a full redesign. + +**Agent prompts as embedded TypeScript.** Loading mechanism preserved; content +changes entirely for new roles. + +**Convention resources, model config, conversation export.** All preserved. + +--- + +## 4. What We Discard + +**The monolithic plan.json schema.** The entire `Plan` type hierarchy +(`Milestone`, `CodeIntent`, `CodeChange`, `Wave`, `DiagramGraph`, etc.) is +removed. Replaced by per-story markdown files and `decisions.md` at the epic +level. The `PlanningContext` concept (`Decision`, `RejectedAlternative`, +`Risk`, `InvisibleKnowledge`) migrates to `decisions.md`. + +**The wave concept.** Waves grouped milestones into execution batches — an +ordering layer on top of the dependency graph. In the new system, execution +order is determined by the orchestrator's dependency analysis at runtime, one +story at a time. There is no need for a static grouping structure: the +orchestrator selects the next story based on what's unblocked after each +completion. Waves and all associated tools (`koan_add_wave`, +`koan_set_wave_milestones`) are removed. + +**The three-phase sequential pipeline.** plan-design → plan-code → plan-docs +removed. Each story's detail-plan produces a single `plan.md` with everything +needed for execution. + +**The QR decompose/verify/fix block.** The entire QR pipeline removed — this +was the single largest cost driver (6 parallel reviewers × 3 phases × up to 5 +fix iterations = up to 90 subagent processes per plan). Replaced by per-story +verification managed by the orchestrator, with a per-story retry budget +(default 2). + +**The QR severity model.** `qr-severity.ts`, `MAX_FIX_ITERATIONS`, +`qrPassesAtIteration()` removed. Replaced by pass/fail/escalate. + +**The 44+ plan mutation tools.** All plan getter/setter/mutate tools removed. +Planning subagents now write files directly using the Write tool, scoped to the +epic directory. + +**Plan validation and cross-reference checking.** `validate.ts` removed. The +new markdown-per-story structure has no cross-references to validate. + +**Plan rendering.** `render.ts` removed. Plans are already markdown. + +**The architect/developer/technical-writer/qr-decomposer/reviewer roles.** All +five current agent roles replaced by the six roles in section 1. + +**The 6-step architect workflow.** The fixed exploration → analysis → approach → +assumptions → milestones → writing sequence (AD-16) removed. Intake and +decomposition have their own step structures. + +**Session concept.** `session.ts` and the `Session` interface removed. The +driver replaces the session. + +--- + +## 5. Workflow and Role Responsibilities + +### 5.1 Triggering + +The user asks pi to plan something complex, `koan_plan` is invoked. The +conversation is exported to `conversation.jsonl`. The epic directory is +created under `~/.koan/state/epics/{epic-id}/`. + +### 5.2 Intake + +**Input**: `conversation.jsonl`. +**Output**: `context.md` and `decisions.md`. +**Steps**: Multi-step, interactive. + +The intake subagent reads the full conversation and performs two tasks in a +single session. First, it extracts structure into `context.md` with five +sections: topic index, file references, decisions already made, constraints +stated, and unresolved questions. Second, it reviews the structured summary +for gaps — ambiguities, unstated assumptions, conflicting statements, and +missing testing strategy — and interactively asks the user to resolve them +via the existing ask UI (relayed through IPC). + +Questions are multiple-choice where possible, with a free-text escape hatch. +Maximum 8 questions. If the conversation was thorough, there may be zero +questions and the interactive step is skipped. If the user dismisses +questions, the intake subagent records "deferred to agent judgment" for each. + +User answers are written to `decisions.md` — a permanent record traceable to +specific conversation turns or intake questions. + +The intake subagent must NOT infer decisions that weren't explicitly stated or +confirmed, add architectural opinions, summarize code (it hasn't read any), +or produce implementation recommendations. + +**Prompt gist**: "Read the conversation. Extract what was decided, what files +were mentioned, what constraints were stated, and what was left ambiguous. +Then identify gaps that need answers before planning can begin — including +testing strategy. For each gap, formulate one focused question with concrete +options." + +### 5.3 Epic Decomposition + +**Input**: `context.md`, `decisions.md`, the codebase (via scouts). +**Output**: `epic.md` + per-story `stories/{story-id}/story.md`. +**Steps**: Fan out scouts, synthesize into sketches. + +The driver spawns scouts in parallel via `pool()` to gather codebase +information. Each scout answers one narrow question and writes its findings +to a markdown file under `scouts/` (e.g., `scouts/scout-001.md`). The driver +collects the output file paths after `pool()` completes, then spawns the +decomposer (strong model) with `context.md`, `decisions.md`, and the scout +output file paths. The decomposer synthesizes scout findings into story +sketches. + +A sketch describes what the story does, why it exists, which files are likely +affected, what it depends on, and acceptance criteria. A sketch is NOT a +detailed implementation plan — it is comparable to a JIRA ticket. + +Example `epic.md` structure: + +```markdown +# <Epic Title> + +## Overview + +<one-paragraph problem + approach summary> + +## Stories + +### S-001: Auth Provider Integration + +OAuth2 with Google and GitHub via next-auth. Leaf — no dependencies. +Files likely affected: src/lib/auth.ts, src/app/api/auth/[...nextauth]/route.ts +Acceptance: OAuth flow completes for both providers, tokens stored in session. + +### S-002: Protected Route Middleware + +Depends on: S-001 +... + +## Sequencing + +S-001 first (leaf). S-002 and S-003 after S-001, independent of each other. +``` + +The decomposer must NOT write implementation details, make decisions that +belong to the user, or over-decompose (a 3-file change should not become 3 +stories). + +**Prompt gist**: "Decompose this feature request into independent stories. +Each story = one PR. Write scope descriptions, not implementation plans. +Scout reports are attached — use them to ground file estimates." + +### 5.4 Spec Review Gate + +The driver presents story sketches to the user. Approve/edit/remove controls. +The driver blocks until the user explicitly approves. This is the one +mandatory human gate. + +### 5.5 Pre-Execution Analysis (Orchestrator) + +**Input**: `epic.md` with approved stories, `decisions.md`. +**Output**: Updated `epic.md` with sequencing, per-story `status.md` files. +**Step sequence**: Pre-execution. +**Tools**: `koan_select_story`, `koan_complete_step`, `write`. + +The orchestrator analyzes approved stories to determine dependency order and +calls `koan_select_story` to pick the first story. For the initial +implementation, execution is sequential. The tool writes `selected` to both +`state.json` (for the driver) and `status.md` (for future LLM reads). The +driver reads `state.json` after the orchestrator exits and spawns the planner +for the selected story. + +### 5.6 Detail-Plan (Per-Story, JIT) + +**Input**: `story.md`, `decisions.md`, the _current_ codebase (via scouts). +**Output**: `plan/plan.md`, `plan/context.md`, `plan/verify.md`. + +The driver fans out scouts in parallel via `pool()` to read the actual current +file contents (which may have changed from earlier stories). Each scout writes +its findings to `stories/{story-id}/scouts/{scout-id}.md`. The driver then +spawns the planner with the story sketch, `decisions.md`, and scout output +file paths. The planner synthesizes scout findings and produces three +artifacts: + +`plan.md` — file-by-file implementation steps with rationale. Describes +behavior changes in prose, not code diffs. References `decisions.md` for +design rationale. + +`context.md` — curated code snippets the executor needs. The need-to-know +principle: the planner pre-selects what's relevant so the executor doesn't +re-explore the codebase. + +`verify.md` — concrete, executable checks ordered from cheapest (grep, build) +to most expensive (test suite, LLM review). References the testing strategy +from `decisions.md`. + +The planner flags high-risk steps and appends any new decisions to +`decisions.md`. The planner must NOT write code, execute changes, make +user-facing decisions without recording them, or plan beyond the current +story's scope. + +**Prompt gist**: "Write a step-by-step implementation plan: which file, which +function, what change, why. Include enough detail that a coding agent can +execute without re-deriving reasoning. Produce plan.md, context.md, verify.md." + +### 5.7 Execute (Per-Story) + +**Input**: `plan.md`, `context.md`. +**Output**: Code changes to the codebase. +**Permission**: WRITE_TOOLS (edit, write) — new tier. + +The executor implements each step in the plan, in order. It does not explore +the codebase beyond `context.md`. If it encounters a plan-reality mismatch (a +file doesn't look like the plan expected, a function was renamed, a dependency +is missing), it uses `koan_ask_question` to escalate to the user or stops and +reports the discrepancy for the orchestrator to handle. + +The executor inherits core patterns from the current developer prompt: scope +violation checks, context drift tolerance, escalation patterns, directive +marker handling, comment hygiene. Key differences: scope is one story (not an +entire plan), context is pre-curated, escalation goes to the orchestrator. + +**Prompt gist**: "Implement each step in order. If the code doesn't match the +plan's expectations — STOP and report. Do not improvise. Do not add features +not in the plan. Do not refactor code the plan doesn't mention." + +### 5.8 Post-Execution Assessment (Orchestrator) + +**Input**: `verify.md`, `plan.md`, `status.md`, git diff, `epic.md`. +**Output**: Updated `status.md` (via tools), potentially updated `story.md` +files, next-story selection. +**Step sequence**: Post-execution. +**Tools**: `koan_complete_story`, `koan_retry_story`, `koan_escalate`, +`koan_select_story`, `koan_skip_story`, `koan_complete_step`, `write`. + +The orchestrator runs four steps: + +1. **Verify**: Run `verify.md` checks (automated via bash, LLM review for + high-risk stories). Record findings. +2. **Verdict**: Based on verification results, call exactly one of: + - `koan_complete_story(story_id)` → story status becomes `done`. + - `koan_retry_story(story_id, failure_summary)` → story status becomes + `retry`. The driver enforces the retry budget; if exhausted, the driver + sets status to `escalated` and presents to the user. + - `koan_escalate(story_id, problem, candidates, recommended)` → story + status becomes `escalated`. The driver presents the escalation to the + user via the ask UI. +3. **Propagate** (only if story completed): Review remaining story sketches + against what was learned during execution. Use `write` to update + `story.md` files and append to `decisions.md` with `[autonomous]` marker. + May call `koan_skip_story` for stories no longer needed. +4. **Select next** (only if story completed and more stories remain): Call + `koan_select_story(next_story_id)`. If no stories remain, don't call — + the driver infers epic completion from state (all stories `done` or + `skipped`). + +After the orchestrator exits, the driver reads state files and applies +deterministic routing rules (see §2.8). + +### 5.9 Widget (Full Redesign) + +The current 3-phase fixed timeline is replaced. The new widget shows: +epic-level progress, current story status and phase, active subagent with step +progress, log stream, and count of autonomous adjustments since last human +interaction. Ground-up redesign of layout and content, reusing rendering +building blocks. + +--- + +## 6. Implementation Sequence + +Hard cutover: replace the old system entirely. There is no parallel running of +old and new code — `driver.ts` replaces `session.ts` at the entry point level, +and `koan.ts` is rewired to the new driver from step 1. + +**Step 1**: Driver shell and state directory. Create `driver.ts` (replaces +`session.ts`). Epic directory creation, `koan_plan` entry point wiring. + +**Step 2**: Permission model and infrastructure types. Rewrite +`PHASE_PERMISSIONS` → `ROLE_PERMISSIONS` (§8.2). Rewrite model resolution +from 5×4 matrix to role → tier → model (§8.6). New CLI flags (§8.4). New +spawn functions (§8.3). Register orchestrator tools (`koan_select_story`, +`koan_complete_story`, `koan_retry_story`, `koan_escalate`, `koan_skip_story`) +per §2.7. + +**Step 3**: Intake phase. Multi-step phase class. Read `conversation.jsonl`, +write `context.md`, identify gaps, present questions via IPC, write +`decisions.md`. + +**Step 4**: Epic decomposition. Decomposer phase class + scout phase class. +Scouts in parallel via `pool()`. Decomposer produces `epic.md` + per-story +`story.md`. + +**Step 5**: Spec review gate. Story sketch presentation via widget. +Approve/edit/remove controls. Block until confirmed. + +**Step 6**: Orchestrator. Phase class with two step sequences (pre-execution, +post-execution). Uses `koan_select_story`, `koan_complete_story`, +`koan_retry_story`, `koan_escalate`, `koan_skip_story` (§2.7). State +communicated via `state.json` files (JSON for driver) and `status.md` +files (markdown for LLMs); driver reads `state.json` and applies +deterministic routing rules (§2.8). + +**Step 7**: Detail-plan phase. Planner phase class + scouts for current +codebase. Produces `plan.md` + `context.md` + `verify.md`. + +**Step 8**: Execute phase. Executor phase class. Full write access. One story +at a time, pre-curated context. + +**Step 9**: Driver execution loop. Wire steps 6–8 into the per-story cycle. +Handle retry budget, escalation via IPC, epic completion. + +**Step 10**: Widget redesign. Ground-up layout and content redesign, reusing +rendering building blocks. + +--- + +## 7. What This Does Not Cover + +This plan deliberately excludes topics that need separate design: + +- **Parallel story execution**: Sequential initially. Parallel adds git + worktree isolation and merge conflict handling. Deferred. + +- **Mid-execution monitoring**: The initial implementation spawns the executor + and waits. Active observation and real-time steering are deferred. + +- **Plan recovery from midpoint**: Partial story success currently means full + retry or escalation. A future refinement could produce continuation plans + from the failure point. Requires the executor to report where it failed and + what completed. Deferred. + +- **Multi-plan selection**: One plan per story. A future refinement could + generate alternatives for high-risk stories, or distinguish execution + failures (retry same plan) from approach failures (different plan needed). + Deferred. + +- **Complexity-adaptive workflow**: Full pipeline for every request initially. + A future refinement adds a fast path: if intake produces zero questions and + decomposition produces one story, skip the spec review gate. Deferred. + +- **Resumption after interruption**: If the user aborts mid-epic (kills the + process), the file-on-disk structure preserves all state. Driver resumption + logic to pick up from where it left off needs design. Note that mid-execution + _questions_ (ambiguity, clarification) do not require resumption — + `koan_ask_question` handles those in-place without interrupting the session. + +- **Cost instrumentation**: Per-phase and per-subagent token counting. Should + be day-one but reporting format needs design. + +- **Model routing configuration**: Per-phase model selection UX needs design. + Infrastructure exists. + +--- + +## 8. Infrastructure Type Updates + +The current infrastructure types encode the old role and phase names. These +must be rewritten for the new architecture. The following specifies the +replacement types. + +### 8.1 Role and phase types + +Replace the current `PhaseRow` / `SubPhase` / `PhaseModelKey` system +(`model-phase.ts`) with role-based types: + +```typescript +// Subagent roles — the six LLM roles plus the two carried-over utility roles. +type SubagentRole = + | "intake" + | "scout" + | "decomposer" + | "orchestrator" + | "planner" + | "executor"; + +// Model tiers — maps to the three tiers in §1. +type ModelTier = "strong" | "standard" | "cheap"; + +// Role → tier mapping (from §2.5). +const ROLE_MODEL_TIER: Record<SubagentRole, ModelTier> = { + intake: "strong", + scout: "cheap", + decomposer: "strong", + orchestrator: "strong", + planner: "strong", + executor: "standard", +}; +``` + +### 8.2 Permission map + +Replace the current `PHASE_PERMISSIONS` map (`permissions.ts`) with +role-based permissions. The key change is the new WRITE_TOOLS tier +for the executor and epic-directory-scoped writes for planning roles. + +```typescript +// Tools available to the orchestrator (see §2.7). +const ORCHESTRATOR_TOOLS = new Set([ + "koan_complete_step", + "koan_ask_question", + "koan_select_story", + "koan_complete_story", + "koan_retry_story", + "koan_escalate", + "koan_skip_story", +]); + +// Tools available to all planning subagents (intake, decomposer, planner). +// These roles can write to the epic directory but NOT the codebase. +const PLANNING_TOOLS = new Set([ + "koan_complete_step", + "koan_ask_question", + // Write tool scoped to epic directory (enforced at tool_call handler level). +]); + +// Tools available to scouts. +const SCOUT_TOOLS = new Set([ + "koan_complete_step", + // READ_TOOLS only (always allowed). No write access. +]); + +// Tools available to the executor. +// Full WRITE_TOOLS access to the codebase. +const EXECUTOR_TOOLS = new Set([ + "koan_complete_step", + "koan_ask_question", + // WRITE_TOOLS (edit, write) — codebase access. +]); + +const ROLE_PERMISSIONS: ReadonlyMap<string, ReadonlySet<string>> = new Map([ + ["intake", PLANNING_TOOLS], + ["scout", SCOUT_TOOLS], + ["decomposer", PLANNING_TOOLS], + ["orchestrator", ORCHESTRATOR_TOOLS], + ["planner", PLANNING_TOOLS], + ["executor", EXECUTOR_TOOLS], +]); +``` + +### 8.3 Spawn functions + +Replace the current role-specific spawn functions (`subagent.ts`) with +new functions for the six roles. The core `spawnSubagent()` function and +its process lifecycle management are preserved. New spawn functions: + +- `spawnIntake(opts)` — strong model, interactive (IPC polling required). +- `spawnScout(opts)` — cheap model, narrow question + output file path. +- `spawnDecomposer(opts)` — strong model, reads intake output + scout files. +- `spawnOrchestrator(opts)` — strong model, two step sequences (pre/post). +- `spawnPlanner(opts)` — strong model, reads story sketch + scout files. +- `spawnExecutor(opts)` — standard model, WRITE_TOOLS access. + +### 8.4 CLI flags + +Replace the current `--koan-role` flag values with the new role names. +The `--koan-phase` flag is replaced by step-sequence identifiers where +a role has multiple sequences (e.g., orchestrator pre-execution vs +post-execution). The `--koan-fix` and `--koan-qr-item` flags are removed +(no QR system). + +New flags: + +- `--koan-role`: `intake | scout | decomposer | orchestrator | planner | executor` +- `--koan-step-sequence`: `pre-execution | post-execution` (orchestrator only) +- `--koan-epic-dir`: Path to the epic directory (replaces `--koan-plan-dir`) +- `--koan-story-id`: Current story ID (for per-story subagents) +- `--koan-subagent-dir`: Subagent working directory (preserved) + +### 8.5 Audit event shapes + +The `KOAN_SHAPES` record in `audit.ts` must be updated to remove all 44 +plan mutation tool shapes and add shapes for the new orchestrator tools +(`koan_select_story`, `koan_complete_story`, `koan_retry_story`, +`koan_escalate`, `koan_skip_story`). + +### 8.6 Model resolution + +The current 5×4 matrix (`model-phase.ts`, `model-config.ts`, +`model-resolver.ts`) is replaced by a simple role → tier → model lookup: + +1. Look up the role's tier from `ROLE_MODEL_TIER`. +2. Look up the model for that tier from `~/.koan/config.json`. +3. If no config, return `undefined` (fall back to pi's active model). + +Config schema: + +```json +{ + "modelTiers": { + "strong": "anthropic/claude-sonnet-4", + "standard": "anthropic/claude-sonnet-4", + "cheap": "anthropic/claude-haiku-4" + } +} +``` + +--- + +## 9. Post-Implementation Notes + +This section records decisions made during implementation, deviations from +the plan, resolved ambiguities, and remaining work. Added after the initial +big-bang rewrite was completed. + +### 9.1 Resolved ambiguities + +**`status.md` and driver state management.** The plan left the `status.md` +schema unspecified and implied the driver would parse it. Resolution: the +driver never parses `status.md` or any markdown file. The orchestrator reads +`status.md` for context, then communicates decisions to the driver by calling +tools (`koan_select_story`, `koan_complete_story`, etc.). Each tool writes +both: + +- A JSON `state.json` file under `stories/{story-id}/` — for driver + consumption. Machine-readable, deterministic format. +- A markdown `status.md` file in the same directory — for LLM consumption in + future orchestrator invocations. Human-readable summary of the state. + +This establishes a clean invariant: **`.json` and `.jsonl` files are for +driver consumption only; `.md` files are for LLM consumption.** Tools bridge +the two worlds. + +**Scout write access.** §8.2 listed `SCOUT_TOOLS` with no write access, but +§5.3 described scouts writing findings to markdown files. Resolution: scouts +are granted `write`/`edit` scoped to the epic directory (same as other +planning roles). They need to write their output file. + +**Orchestrator verification and `bash`.** §5.8 described the orchestrator +running `verify.md` checks via bash, but §8.2's `ORCHESTRATOR_TOOLS` didn't +explicitly include bash. Resolution: bash is in `READ_TOOLS` (always allowed), +and the orchestrator also gets explicit bash access in `ROLE_PERMISSIONS`. +The permission system does not distinguish "read bash" from "write bash" — +this is an accepted limitation consistent with the current design. + +**Orchestrator step sequence dispatch.** The plan described two step sequences +but didn't specify the dispatch mechanism. Resolution: a single +`OrchestratorPhase` class reads `config.stepSequence` in `begin()` and +configures its total steps (2 for pre-execution, 4 for post-execution) and +step name/guidance functions accordingly. The `--koan-step-sequence` CLI flag +carries the sequence identifier. + +### 9.2 Implementation decisions + +**`PlanRef.dir` reuse.** The existing `PlanRef` interface in `lib/dispatch.ts` +has a `dir` field and a `qrPhase` field. Rather than modifying the dispatch +infrastructure, `PlanRef.dir` now points to the epic directory. The `qrPhase` +field is unused but retained to avoid touching the kept `dispatch.ts` file. + +**Model resolution at spawn time.** Each spawn function +(`spawnIntake`, `spawnScout`, etc.) calls `resolveModelForRole(role)` to look +up the configured model for the role's tier. If no config exists, `--model` +is omitted and pi uses its active model. This is consistent with the old +system's spawn-time resolution pattern. + +**Orchestrator tools validate transitions.** `koan_select_story` validates +that the story's current status is `"pending"` or `"retry"` before +transitioning to `"selected"`. This allows the orchestrator to re-select +retried stories. Other tools do not enforce preconditions at the tool +level — the orchestrator is trusted to call tools at appropriate points, +and the driver applies its own state checks after the orchestrator exits. + +**Epic directory structure.** Implemented as specified in §2.3, under +`~/.koan/state/epics/{epic-id}/`. The `createEpicDirectory` function in +`epic/state.ts` generates the ID using the same timestamp+slug pattern as the +old `createPlanInfo`, creates subdirectories (`stories/`, `scouts/`, +`subagents/`), and writes an initial `epic-state.json`. + +**Background context.** The old system loaded background context from +`plan.json`. The rewritten `formatStepWithBackgroundContext` reads +`context.md` from the epic directory (the intake output). If `context.md` +doesn't exist yet (e.g., during the intake phase itself), it falls back to +an empty context string. + +**Agent prompts.** `lib/agent-prompts.ts` still contains the old role prompts +(architect, developer, quality-reviewer, technical-writer). These are not +used by the new system — each phase class has its own `prompts.ts` with +role-specific system prompts and step guidance. The old prompts file is +retained but dormant. + +### 9.3 Deviations from the plan + +**Architecture is faithful; behavioral wiring had defects.** The +implementation follows the plan's two-phase architecture (epic creation → +story execution loop), role definitions, tool inventory, permission model, +and model tier system faithfully. However, post-implementation analysis +(§9.6) found runtime wiring defects in phase prompt injection, prompt path +references, and story state initialization that would prevent end-to-end +execution. These are corrected in §9.6. + +**`handleFinalize()` dropped.** §3 originally described a `handleFinalize()` +method on phase classes. Implementation uses the orchestrator's +post-execution verification instead — phase classes simply advance steps +and terminate. Output validation is the orchestrator's responsibility, not +something each phase class does for itself. §3 has been updated. + +**`koan_ask_question` excluded from scout.** §3 originally stated all +subagent roles get `koan_ask_question`. Implementation excludes scout — +scouts are narrow-scope codebase investigators that answer one question +and write one file. They should not need user interaction. §3 has been +updated. + +**`koan_select_story` accepts `retry` status.** §2.7 originally specified +`pending → selected` only. The orchestrator's post-execution step 4 needs +to re-select retried stories, so the tool now accepts both `pending` and +`retry`. §2.7 has been updated. + +**Driver reads `state.json`, not `status.md`.** §2.8 originally said the +driver reads `status.md`. The implementation reads `state.json` exclusively +(the invariant from §9.1: JSON for driver, markdown for LLMs). §2.8 has +been updated. + +**EpicState reload on each phase transition.** The driver reloads +`epic-state.json` before each save to avoid overwriting the `stories` list +that the decomposer may have populated. The plan didn't specify this, but +it's a correctness requirement — a single-snapshot-then-spread pattern would +silently lose story data. + +**Config migration.** The plan didn't specify migration from the old +`phaseModels` config key. Implementation: the old key is silently ignored. +No migration, no warning. Users with old config get the default behavior +(no model overrides, pi's active model used for all roles). + +### 9.4 Remaining work + +Items marked TODO in the codebase. These are deferred capabilities, not +missing implementation of specified features. + +**Scout question generation.** The driver stubs +`runDecompositionScouts()` and `runStoryScouts()` — they return empty +arrays. The plan describes scouts answering "narrow codebase questions," +but the mechanism for generating those questions is underspecified. Two +options: + +1. The intake phase writes a `scout-questions.json` manifest alongside + `context.md`, listing questions for the decomposition scouts. The planner + does the same for per-story scouts. The driver reads these manifests. +2. A dedicated "question generation" step in the driver constructs + questions from the structured output of intake/planning phases. + +Option 1 is simpler and consistent with the "tools write JSON for the +driver" pattern. It requires adding a new artifact to the intake and +planner phase outputs. + +**Spec review gate UI.** The driver auto-approves after the decomposer +exits. The plan specifies a widget with approve/edit/remove controls per +story. This requires a new TUI component and the driver blocking until +user confirmation. Deferred to the widget redesign (§6 step 10). + +**Escalation presentation.** When a story reaches `escalated` status, the +driver currently returns a failure summary instead of presenting the +escalation to the user interactively. The plan specifies presenting the +problem, candidate solutions, and recommended solution via the ask UI. +This requires integrating the IPC ask flow into the driver's execution +loop — the infrastructure exists (`koan_ask_question`, `pollWithIpcDetection`) +but the driver doesn't yet use it. + +**Widget redesign.** The old `WidgetController` is retained but doesn't +reflect the new epic/story lifecycle. The plan calls for a ground-up +redesign (§5.9) showing epic progress, current story, active subagent, +step info, log stream, and autonomous adjustment count. Deferred. + +**Cost instrumentation.** §7 mentions per-phase and per-subagent token +counting as "should be day-one." Not implemented. The EventLog captures +tool calls but not token usage. + +**Resumption after interruption.** §7 defers this. The file-on-disk +structure preserves state, but the driver has no resume path. If the +process dies mid-story, the driver must be restarted from scratch. Adding +resume requires the driver to detect existing state on startup and +reconstruct its position in the execution loop. + +### 9.5 File inventory + +New and rewritten files (43 source files, ~6,500 lines total): + +``` +extensions/koan.ts # REWRITTEN: new flags, driver integration +src/planner/types.ts # NEW: SubagentRole, ModelTier, StoryStatus, ROLE_MODEL_TIER +src/planner/driver.ts # NEW: epic pipeline coordinator +src/planner/subagent.ts # REWRITTEN: 6 role-specific spawn functions +src/planner/model-phase.ts # REWRITTEN: re-exports from types.ts + ALL_MODEL_TIERS, isModelTier +src/planner/model-config.ts # REWRITTEN: 3-tier config I/O +src/planner/model-resolver.ts # REWRITTEN: role → tier → model +src/planner/epic/types.ts # NEW: EpicState, StoryState +src/planner/epic/state.ts # NEW: state I/O, directory management +src/planner/phases/dispatch.ts # REWRITTEN: 6-role routing +src/planner/phases/intake/{phase,prompts}.ts # NEW +src/planner/phases/scout/{phase,prompts}.ts # NEW +src/planner/phases/decomposer/{phase,prompts}.ts # NEW +src/planner/phases/orchestrator/{phase,prompts}.ts # NEW +src/planner/phases/planner/{phase,prompts}.ts # NEW +src/planner/phases/executor/{phase,prompts}.ts # NEW +src/planner/tools/orchestrator.ts # NEW: 5 state-transition tools +src/planner/tools/index.ts # REWRITTEN: 3 tool groups +src/planner/lib/permissions.ts # REWRITTEN: role-based + path scoping +src/planner/lib/audit.ts # MODIFIED: new KOAN_SHAPES +src/planner/ui/config/model-selection.ts # REWRITTEN: 3-tier editor +src/planner/ui/config/menu.ts # MODIFIED: new imports +src/utils/plan.ts # MODIFIED: ID helpers only +``` + +Deleted files (~10,200 lines removed): + +``` +# Old architecture (replaced by driver + phases + epic state) +src/planner/session.ts +src/planner/state.ts +src/planner/plan/{types,serialize,render,validate}.ts +src/planner/plan/mutate/{index,top-level,decisions,milestones,code,structure,background-context}.ts +src/planner/qr/{types,mutate,severity}.ts +src/planner/phases/plan-design/{phase,prompts,fix-phase,fix-prompts}.ts +src/planner/phases/plan-code/{phase,prompts,fix-phase,fix-prompts}.ts +src/planner/phases/plan-docs/{phase,prompts,fix-phase,fix-prompts}.ts +src/planner/phases/qr-decompose/{phase,prompts}.ts +src/planner/phases/qr-verify/{phase,prompts}.ts +src/planner/tools/{getters,setters,entity-design,entity-code,entity-structure,entity-context,qr}.ts +tests/{model-config,model-phase,model-resolver,session-model-threading,subagent-model,qr-grouped-verify,widget,background-context}.test.ts + +# Dead code removed during post-analysis cleanup (§9.6) +src/planner/lib/background-context-prompt.ts # rewritten but never imported +src/planner/lib/conversation-trigger.ts # referenced old phase IDs +src/planner/lib/resources.ts # old resource resolver +src/planner/lib/agent-prompts.ts # old role prompts (dormant) +src/utils/lock.ts # unused +src/utils/progress.ts # unused +tests/progress.test.ts # tested unused module +``` + +### 9.6 Post-analysis corrections + +Post-implementation analysis found runtime wiring defects that would prevent +end-to-end execution. This section documents each defect, why it happened, +and the correction. Changes to earlier plan sections (§2.7, §2.8, §3) are +cross-referenced. + +**Step 1 prompt injection replaces instead of appending.** All 6 phase +classes' `context` event handlers replaced the entire user message with +the step 1 prompt. This discarded the spawn prompt, which carries +role-specific context (the scout's question, the decomposer's scout file +list, the executor's retry context). Correction: the `context` handler +now appends the step guidance to the existing user message instead of +replacing it. If the original message is present, the step guidance is +added after a separator. This preserves any context the spawn function +embedded in the prompt while adding the structured step instructions. + +Affects: all 6 `phases/*/phase.ts` files. + +**Retry context not reaching `ExecutorPhase`.** `dispatch.ts` constructed +`ExecutorPhase` without reading `retryContext` from a flag, so retried +executor invocations received no failure context. Correction: added +`--koan-retry-context` flag; `dispatch.ts` reads it and passes it into +the `ExecutorPhase` config. The executor's step 1 guidance includes the +retry context when present. + +Affects: `extensions/koan.ts` (flag registration), `phases/dispatch.ts` +(flag reading), `subagent.ts` (flag passing in `spawnExecutor`). + +**Prompt paths missing `stories/` prefix.** Planner, executor, and +orchestrator prompts referenced `${storyId}/plan/plan.md` etc., but the +actual artifact structure is `stories/${storyId}/...` (per §2.3 and +`epic/state.ts`). Correction: all prompt paths now include the `stories/` +prefix. + +Affects: `phases/planner/prompts.ts`, `phases/executor/prompts.ts`, +`phases/orchestrator/prompts.ts`. + +**Orchestrator post-exec step 2 prompt told LLM not to call +`koan_complete_step`.** The prompt said "the verdict tool signals step +completion", but verdict tools (`koan_complete_story`, etc.) do not +trigger `dispatch.onCompleteStep` — only `koan_complete_step` does. The +correct flow is: call the verdict tool, then call `koan_complete_step` to +advance. Correction: removed the incorrect instruction from the +orchestrator prompt. The verdict tools and step completion are independent +actions. + +Affects: `phases/orchestrator/prompts.ts` only (infrastructure is correct). + +**`koan_select_story` rejected `retry` status.** The tool enforced +`status === "pending"` only, but the orchestrator's post-execution step 4 +needs to re-select retried stories. Correction: tool now accepts both +`"pending"` and `"retry"`. §2.7 state transition table updated. + +Affects: `tools/orchestrator.ts`, §2.7. + +**Story state initialization gap.** The driver never called +`ensureStoryDirectory()`, relying on the decomposer LLM to create valid +`state.json` files. But the decomposer writes markdown story sketches — +it has no reason to know the JSON state format. Correction: the driver +calls `ensureStoryDirectory()` for each story ID listed in +`epic-state.json` after the decomposer exits, before entering the story +execution loop. `ensureStoryDirectory()` creates the directory structure +and writes an initial `state.json` with `"pending"` status if one doesn't +already exist. + +Affects: `driver.ts` (story initialization step after decomposer). + +Note: the decomposer must register story IDs in `epic-state.json` (via +the `stories` array) for the driver to discover them. This is part of +the decomposer's contract — it writes `epic.md` (markdown, for LLMs) +and updates `epic-state.json` (JSON, for the driver) with the story list. +The decomposer tools or write-tool instructions must include this. + +**Duplicate `ModelTier` / `ROLE_MODEL_TIER` definitions.** Both `types.ts` +and `model-phase.ts` defined identical copies. Different consumers imported +from different files. Correction: canonical definitions live in `types.ts`. +`model-phase.ts` re-exports from `types.ts` and adds only the +`ALL_MODEL_TIERS` array and `isModelTier()` guard that are specific to +model configuration. No duplicate definitions remain. + +Affects: `types.ts` (canonical source), `model-phase.ts` (re-export + +utilities), all consumers unchanged (imports still resolve). + +**Dead code removed.** Six unreferenced files were removed: +`lib/background-context-prompt.ts` (rewritten during implementation but +never imported — its functionality was superseded by per-phase prompt +construction), `lib/conversation-trigger.ts` (referenced old phase IDs), +`lib/resources.ts` (old resource path resolver), `lib/agent-prompts.ts` +(old role prompts for deleted roles), `utils/lock.ts` (unused utility), +`utils/progress.ts` + `tests/progress.test.ts` (progress tracking utility +that was never imported by the new system). + +Affects: §9.5 file inventory updated. + +### 9.7 Plan sections amended by post-analysis + +For traceability, the following earlier plan sections were modified during +the §9.6 corrections: + +| Section | Change | Reason | +| --------- | ----------------------------------------------------------------- | ------------------------------------------------------------------ | +| §2.1 | Epic completion reads `state.json` not `status.md` | Aligns with §9.1 invariant | +| §2.6 | Story state machine: driver writes `state.json`, tools write both | Clarifies dual-format write pattern | +| §2.7 | `koan_select_story` transition: `pending` → `pending or retry` | Orchestrator needs to re-select retried stories | +| §2.8 | Driver reads `state.json` not `status.md` | Aligns with §9.1 invariant (JSON for driver, markdown for LLMs) | +| §3 | `handleFinalize()` removed from lifecycle description | Not implemented; verification is orchestrator's job | +| §3 | `koan_ask_question` scoped to all roles except scout | Scout is a narrow investigator, doesn't need user interaction | +| §5.5 | `koan_select_story` writes to both `state.json` and `status.md` | Clarifies dual-format write | +| §6 step 6 | State communicated via `state.json` + `status.md` | Was `status.md` only | +| §9.2 | `koan_select_story` accepts `pending` or `retry` | Matches §2.7 update | +| §9.3 | Acknowledges behavioral deviations, not just architecture | §9.6 defects are real deviations from the plan's behavioral intent | +| §9.4 | Removed `agent-prompts.ts` cleanup item | File deleted as dead code in §9.6 | +| §9.5 | Updated file inventory | Reflects dead code removal and types.ts consolidation | + +### 9.8 §9.6 corrections implemented + +All 8 corrections described in §9.6 have been implemented and verified. +This section records the implementation details. + +**Step 1 prompt append (all 6 phase classes).** The `context` event +handler in each phase class's `registerHandlers()` was changed from +replacing the user message to appending step guidance after it. The +pattern: + +```typescript +this.pi.on("context", (event) => { + if (!this.active || this.step !== 1 || !this.step1Prompt) return undefined; + const messages = event.messages.map((m) => { + if (m.role !== "user") return m; + const existing = typeof m.content === "string" ? m.content.trim() : ""; + const combined = + existing.length > 0 + ? `${existing}\n\n---\n\n${this.step1Prompt!}` + : this.step1Prompt!; + return { ...m, content: combined }; + }); + return { messages }; +}); +``` + +This preserves the spawn prompt (scout question, decomposer scout file +list, executor retry context, etc.) while adding the structured step +instructions after a `---` separator. If the spawn prompt is empty the +step guidance is used alone. + +**Retry context flag.** Three files changed: + +- `extensions/koan.ts`: registered `koan-retry-context` flag (string, + default `""`) +- `src/planner/subagent.ts`: `spawnExecutor` pushes + `--koan-retry-context` to `extraFlags` when `opts.retryContext` is set +- `src/planner/phases/dispatch.ts`: executor case reads + `pi.getFlag("koan-retry-context")` and passes it to `ExecutorPhase` + config as `retryContext` + +The retry context now reaches the executor phase through two independent +channels: (1) in the spawn prompt text (preserved by the append fix +above) and (2) in the phase config via the CLI flag (consumed by +`executorStepGuidance` to inject failure context into step 1 guidance). +Channel 2 is the structured path; channel 1 is a backup that ensures +the LLM sees the context even if the phase machinery fails. + +**Prompt path prefix.** All `${storyId}/...` references in prompt +templates changed to `stories/${storyId}/...`: + +- `planner/prompts.ts`: 4 occurrences (story.md, plan/plan.md, + plan/context.md, plan/verify.md) +- `executor/prompts.ts`: 2 occurrences (plan/plan.md, plan/context.md) +- `orchestrator/prompts.ts`: 1 occurrence (plan/verify.md, plus its + fallback template string) + +Paths now match the actual directory structure in `epic/state.ts`. + +**Orchestrator step 2 prompt.** The instruction "Do NOT call +`koan_complete_step` — the verdict tool signals step completion" was +replaced with "Then call `koan_complete_step` after the verdict tool to +advance to the next step." The verdict tools and step completion are +independent actions — the LLM calls the verdict tool first, then +`koan_complete_step` to advance the phase. + +**`koan_select_story` retry acceptance.** In `tools/orchestrator.ts`: + +- Guard: `state.status !== "pending"` → `state.status !== "pending" && +state.status !== "retry"` +- Error message: includes both accepted statuses +- Tool description: updated to mention both `pending` and `retry` + +**Story state initialization.** In `driver.ts`, after the decomposer +succeeds and before the spec review gate, the driver now iterates over +`epicState.stories` and calls `ensureStoryDirectory()` for each. This +creates the directory structure (`stories/{id}/`, `stories/{id}/scouts/`, +`stories/{id}/plan/`) and writes an initial `state.json` with `"pending"` +status if one doesn't already exist. The `ensureStoryDirectory` import +was added to the existing import block from `./epic/state.js`. + +Contract note: the decomposer must register story IDs in +`epic-state.json` (the `stories` array) for the driver to discover +them. This is how the decomposer communicates the story list to the +driver — via JSON, consistent with the §9.1 invariant. The decomposer's +`write` tool output must include an `epic-state.json` update. This +contract should be enforced in the decomposer's step 2 prompt (the +prompt currently instructs writing `epic.md` and per-story `story.md` +files but does not explicitly mention updating `epic-state.json`). + +**`ModelTier` deduplication.** `model-phase.ts` no longer defines +`ModelTier`, `SubagentRole`, or `ROLE_MODEL_TIER` locally. Instead: + +- `export type { ModelTier, SubagentRole } from "./types.js"` +- `export { ROLE_MODEL_TIER } from "./types.js"` +- Local definitions retained only for `ALL_MODEL_TIERS` (array) and + `isModelTier()` (type guard), which are model-config concerns not + needed in the core `types.ts` + +All four consumers (`model-selection.ts`, `menu.ts`, `model-resolver.ts`, +`model-config.ts`) continue to import from `model-phase.js` without +changes — the re-exports preserve the public API. + +**Dead code removal.** Seven files removed: + +- `src/planner/lib/background-context-prompt.ts` (untracked, `rm`) +- `src/planner/lib/conversation-trigger.ts` (`git rm`) +- `src/planner/lib/resources.ts` (`git rm`) +- `src/planner/lib/agent-prompts.ts` (`git rm`) +- `src/utils/lock.ts` (`git rm`) +- `src/utils/progress.ts` (`git rm`) +- `tests/progress.test.ts` (`git rm`) + +Post-removal import scan confirms zero dangling references. + +**Verification.** After all corrections: `npx tsc --noEmit` produces +zero errors; `npm test` runs 21 tests with 21 passes and 0 failures; +43 source files remain. + +--- + +## 10. Post-Analysis: Architectural Corrections and Remaining Work + +Post-implementation codebase analysis (2026-03-11) identified architectural +violations, missing runtime wiring, and underspecified components. This +section records the corrections and remaining work items for the next +rewrite pass. All items here take precedence over earlier sections where +they conflict. + +### 10.1 Core invariant: LLM/driver communication boundary + +The following invariant is the single most important architectural rule in +koan. It is documented in `AGENTS.md` at the repository root. + +> LLMs write **markdown files only**. LLMs communicate with the driver +> through **tool calls only**. The driver maintains `.json` state files +> internally — no LLM ever reads or writes a `.json` file. + +Example: orchestrator calls `koan_complete_story(story_id)` → tool code +writes `state.json` + `status.md` → driver reads `state.json` to route +next action. The orchestrator never touches `state.json` directly. + +This invariant was already implicit in §9.1 but was violated in practice: +§9.6 and §9.8 describe the decomposer updating `epic-state.json` directly. +§10.2 corrects this. + +### 10.2 Story discovery: filesystem scan, not LLM-written JSON + +**Problem.** §9.6 and §9.8 state that the decomposer must register story +IDs in `epic-state.json` (the `stories` array) for the driver to discover +them. This requires the decomposer LLM to write a JSON file, violating +§10.1. + +**Correction.** The driver discovers stories by scanning the filesystem +after the decomposer exits. The decomposer writes `stories/{id}/story.md` +files (markdown, per §10.1). The driver scans `stories/*/story.md` and +populates `epic-state.json.stories` itself. + +Implementation: + +```typescript +// In driver.ts, after decomposer exits: +import { readdir } from "node:fs/promises"; +import { join } from "node:path"; + +async function discoverStoryIds(epicDir: string): Promise<string[]> { + const storiesDir = join(epicDir, "stories"); + const entries = await readdir(storiesDir, { withFileTypes: true }); + return entries + .filter((e) => e.isDirectory()) + .map((e) => e.name) + .sort(); // deterministic order +} +``` + +After scanning, the driver calls `ensureStoryDirectory()` for each +discovered ID (creating `state.json` with `"pending"` status) and writes +the ID list to `epic-state.json`. This replaces the contract note in §9.8. + +**Affected sections:** §5.3 (decomposer output no longer includes JSON), +§9.6 (story state initialization correction superseded), §9.8 (contract +note superseded). + +### 10.3 Dispatch simplification: prompt-only phase config + +**Problem.** `dispatch.ts` constructs phase classes with config fields +(`scoutFiles`, `question`, `outputFile`) that are always empty. The real +context is in the spawn prompt (initial user message). The phase class +API is misleading — it accepts structured config that it never uses +functionally. + +**Correction.** Phase class constructors accept only routing-level config +that the driver needs for structural decisions: + +- All phases: `epicDir` (for permission scoping) +- Orchestrator: `stepSequence` (determines step count and guidance) +- Executor: `retryContext` (injected into step 1 guidance via CLI flag) +- Story-scoped phases (planner, executor, orchestrator post-exec): `storyId` + +All role-specific context (scout focus area, decomposer scout file list, +planner story details) is embedded in the spawn prompt by the spawn +function. The phase class appends step guidance to this prompt via the +`context` event handler (the §9.8 append pattern). + +Fields to remove from phase constructors: + +- `ScoutPhase`: remove `question`, `outputFile` +- `DecomposerPhase`: remove `scoutFiles` +- `PlannerPhase`: remove `scoutFiles` + +The `dispatch.ts` cases for these phases simplify to: + +```typescript +case "scout": { + const phase = new ScoutPhase(pi, { epicDir: config.epicDir }, dispatch, planRef, logger, eventLog); + await phase.begin(); + break; +} +case "decomposer": { + const phase = new DecomposerPhase(pi, { epicDir: config.epicDir }, dispatch, planRef, logger, eventLog); + await phase.begin(); + break; +} +case "planner": { + const phase = new PlannerPhase(pi, { epicDir: config.epicDir, storyId: config.storyId ?? "" }, dispatch, planRef, logger, eventLog); + await phase.begin(); + break; +} +``` + +### 10.4 Parent-side IPC responder + +**Problem.** `koan_ask_question` (subagent side) writes an IPC request file +and polls for a response. No parent-side code reads the request, renders the +ask UI, or writes a response. Intake — the first phase in the pipeline — +uses `koan_ask_question` to ask the user clarifying questions. Without the +parent responder, intake hangs indefinitely on its first question. + +**Correction.** The driver must poll for IPC requests from active subagents +and relay them to the user. The infrastructure already exists on both sides: + +- Subagent side: `writeIpcFile()`, `readIpcFile()`, poll loop in + `tools/ask.ts` +- Parent side: `readIpcFile()`, `writeIpcFile()`, `createAskResponse()`, + `createCancelledResponse()` in `lib/ipc.ts` +- UI: `askSingleQuestionWithInlineNote()`, `askQuestionsWithTabs()` in + `ui/ask/` + +What's missing is the glue: the driver (or extension entry point) must run +a polling loop that: + +1. Watches the active subagent's directory for `ipc.json` +2. Reads the request payload +3. Renders the ask UI using the existing ask components +4. Writes the response (or cancellation) back to `ipc.json` + +This polling should be integrated into `spawnSubagent()` or run as a +concurrent loop alongside the child process. The subagent's `ipc.json` +path is known (it's the `subagentDir`). + +### 10.5 Vestigial cleanup: `PlanRef.qrPhase` + +**Problem.** `PlanRef` in `lib/dispatch.ts` retains a `qrPhase` field from +the old architecture. §9.2 acknowledged it as "unused but retained to avoid +touching the kept `dispatch.ts` file." + +**Correction.** Remove `qrPhase` from `PlanRef`. The `PlanRef` interface +becomes: + +```typescript +export interface PlanRef { + dir: string | null; +} +``` + +The `PlanRef`/`SubagentRef` mutable-ref pattern itself is retained — it's a +necessary accommodation for pi's extension lifecycle (tools register at init +before runtime state is available). + +### 10.6 Widget redesign specification + +**Problem.** §5.9 describes a "ground-up redesign" without specifying the +widget's data model, layout, or interaction model. The existing +`WidgetController` is designed for the old 3-phase pipeline and is +disconnected from the driver. + +**Specification.** The widget provides three capabilities: status display, +spec review interaction, and escalation handling. + +#### 10.6.1 Status display + +The widget shows the full epic lifecycle state during execution: + +- **Story list with status indicators.** All stories listed with their + current status (`pending`, `selected`, `planning`, `executing`, + `verifying`, `done`, `retry`, `escalated`, `skipped`). Visual indicators + (icons or color) distinguish terminal states from active states. + +- **Active subagent activity.** Which role is currently running (e.g., + "Executor: S-002"), which step it's on (e.g., "Step 2/3: Implementation"), + and how long it's been running. + +- **Full scrollable log tail.** The active subagent's event stream rendered + as a scrollable log. Shows tool calls, file operations, bash commands, + and koan tool invocations. Uses the existing `readRecentLogs()` and + `LogLine` infrastructure from `audit.ts`, but without a fixed count + limit — the widget streams the full tail. + +- **Autonomous decision count.** A counter showing how many `[autonomous]` + decisions the orchestrator has made since the last human interaction. + Gives the user a sense of how much the system has diverged from the + original spec. + +Data source: the driver polls `state.json` (per-subagent projection) and +`events.jsonl` (log stream) from the active subagent's directory. The +existing `readProjection()` and `readRecentLogs()` functions provide the +read path. + +#### 10.6.2 Spec review gate + +After decomposition, the driver presents story sketches for human approval. +The widget renders: + +- The full list of stories from `epic.md` and `stories/*/story.md` +- Per-story controls: **approve**, **edit** (opens the story.md for inline + editing), **remove** (marks story as skipped) +- A global **approve all** action +- The driver blocks until the user explicitly confirms + +This replaces the current auto-approve stub in `driver.ts`. + +#### 10.6.3 Escalation handling + +When a story reaches `escalated` status, the widget presents the escalation +interactively instead of returning a summary string: + +- **Problem description** from the `EscalationInfo.problem` field +- **Candidate approaches** listed with selection controls +- **Recommended approach** highlighted +- **Custom response** text input for free-form direction +- **Actions**: select a candidate, provide custom direction, or abort + +The user's response is written back to the story's state and the driver +resumes execution. This integrates with the existing ask UI components +but is triggered by the driver's escalation detection, not by +`koan_ask_question`. + +### 10.7 Remaining work summary + +Items from this analysis that require implementation, in priority order: + +| # | Item | Priority | Rationale | +| --- | ------------------------------------------- | ------------ | -------------------------------------------------------------- | +| 1 | Parent-side IPC responder (§10.4) | **Blocking** | Intake hangs without it — system cannot start | +| 2 | Story discovery via filesystem scan (§10.2) | **Blocking** | Driver finds zero stories without it | +| 3 | Dispatch simplification (§10.3) | High | Misleading API; clean rewrite should not carry dead config | +| 4 | `PlanRef.qrPhase` removal (§10.5) | High | Vestigial field from old architecture | +| 5 | Widget: status display (§10.6.1) | High | No visibility into execution without it | +| 6 | Widget: spec review gate (§10.6.2) | High | Mandatory human gate currently auto-approved | +| 7 | Widget: escalation handling (§10.6.3) | High | Escalations currently dead-end | +| 8 | Decomposer prompt update | Medium | Remove any JSON-writing instructions; LLM writes markdown only | + +### 10.8 §10 implementation completed + +All 8 items from §10.7 have been implemented and verified. Build is clean +(`tsc --noEmit`: 0 errors, `npm test`: 26/26 pass). This section records +what was built, the quality review findings, and the fixes applied. + +#### 10.8.1 New files + +| File | Purpose | +| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `src/planner/lib/ipc-responder.ts` | Parent-side IPC responder. Polls `ipc.json` in the active subagent directory (300ms interval). Routes to `askSingleQuestionWithInlineNote` (single question) or `askQuestionsWithTabs` (multi-question). Writes response back. Terminates on AbortSignal. | +| `src/planner/ui/epic-widget.ts` | `EpicWidgetController`. Story list with status icons, active subagent info (role, step, elapsed time), full scrollable log tail via `readRecentLogs()` / `readProjection()`. 1-second unref'd timer refreshes elapsed display. `destroy()` cleans up. | +| `src/planner/ui/spec-review.ts` | `reviewStorySketches()`. Interactive spec review gate. Presents each story with ✓/□ toggles. Space toggles skip, A approves all, Enter confirms. Returns `{ approved, skipped }`. | +| `src/planner/ui/escalation-ui.ts` | `presentEscalation()`. Presents escalation problem, lists candidate approaches for selection. User selects a candidate or aborts. Returns `{ action, resolution? }`. | +| `tests/story-discovery.test.ts` | 5 tests for `discoverStoryIds`: missing directory, empty directory, sorted output, file filtering, deterministic sort order. | + +#### 10.8.2 Modified files + +| File | Change | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `src/planner/lib/dispatch.ts` | Removed `qrPhase` from `PlanRef`. Interface is now `{ dir: string \| null }`. | +| `src/planner/phases/scout/phase.ts` | Config simplified to `{ epicDir }`. Removed `question`, `outputFile`. | +| `src/planner/phases/scout/prompts.ts` | `scoutStepGuidance()` takes no args; role-specific context is in spawn prompt. | +| `src/planner/phases/decomposer/phase.ts` | Config simplified to `{ epicDir }`. Removed `scoutFiles`. | +| `src/planner/phases/decomposer/prompts.ts` | Step 1 guidance changed to prompt-aware text: "If scout reports were referenced in your initial instructions above, read them now." Works with or without scout files. | +| `src/planner/phases/planner/phase.ts` | Config simplified to `{ epicDir, storyId }`. Removed `scoutFiles`. | +| `src/planner/phases/dispatch.ts` | All three simplified phases use new constructors per §10.3. | +| `src/planner/subagent.ts` | Added `ui?: ExtensionUIContext` to `SpawnOptions`. `spawnSubagent()` starts `runIpcResponder` concurrently when `ui` is present; aborts it on process exit. `spawnPlanner` no longer takes `scoutFiles`. | +| `src/planner/epic/state.ts` | Added `discoverStoryIds(epicDir)` — scans `stories/*/` directories, returns sorted IDs. | +| `src/planner/driver.ts` | Story discovery via `discoverStoryIds()` replacing LLM-written JSON. Spec review gate via `reviewStorySketches()`. Escalation handling via `presentEscalation()` with re-execution on resolution. `EpicWidgetController` lifecycle through the story loop. Planner failure skips executor, proceeds to post-exec orchestrator. | +| `extensions/koan.ts` | Passes `ctx.ui` directly to `runEpicPipeline` instead of a narrow notify-only proxy. | + +#### 10.8.3 Quality review findings and fixes + +A quality review identified 2 major issues, 2 minor issues, 1 note, and +1 latent issue. All were fixed. + +**Fix 1 (major): IPC responder stale question after subagent exit.** + +The IPC responder's ask UI calls (`askSingleQuestionWithInlineNote`, +`askQuestionsWithTabs`) don't accept an `AbortSignal` — they block until +user interaction. When a subagent exits mid-question, the user sees a stale +prompt. + +Fix: after each UI call returns, immediately check `signal.aborted`. If +aborted, write `createCancelledResponse` instead of the user's answer and +break the loop. The UI call still blocks (limitation of pi's ask API), but +the stale answer is never written back to the dead subagent's IPC file. + +**Fix 2 (major): Escalation "Other" option silently aborts.** + +The escalation UI presented "Other (type your own)" as a selectable +candidate. All `done()` calls passed `note: ""`, so selecting "Other" +triggered `return { action: "abort" }` — the story was silently skipped. +§10.6.3 specifies custom text input, but pi's `ui.custom` doesn't support +text prompts. + +Fix: removed the "Other" option entirely. The escalation UI now presents +only the actual candidates from `EscalationInfo.candidates` plus an "Abort" +option. A comment documents that custom text input can be added when pi's +UI primitives support it. + +**Fix 3 (minor): `discoverStoryIds` swallowed non-ENOENT errors.** + +The catch-all returned `[]` for any error, including `EACCES` or I/O +failures. This made permission errors look like "no stories found." + +Fix: narrowed the catch to `ENOENT` only. All other errors are re-thrown. + +**Fix 4 (minor): Planner failure continued to executor.** + +When `planResult.exitCode !== 0`, the driver logged the failure but still +spawned the executor with no plan file, wasting a full executor turn. + +Fix: after planner failure, the driver skips the executor spawn entirely, +sets the story status to `verifying`, and spawns the post-execution +orchestrator. The orchestrator sees no code changes and can make a +retry/escalate verdict. + +**Fix 5 (note): Spec review Esc comment.** + +Comment said "Esc proceed with current selections (treated as +approve-all)" but actual behavior was "confirm current selections and +proceed" (which may include skipped stories). Fixed the comment. + +**Fix 6 (latent): Decomposer step guidance vs spawn prompt.** + +Step 1 guidance always emitted "(No scout reports were produced)" because +`scoutFiles` was removed from the phase constructor (§10.3). When scouting +is wired, the spawn prompt will mention scout files but step guidance would +contradict it. + +Fix: replaced the conditional text with prompt-aware guidance: "If scout +reports were referenced in your initial instructions above, read them now. +If no scout reports were mentioned, proceed without them." Compatible with +both cases. + +#### 10.8.4 Remaining limitations + +| Limitation | Why | Mitigation | +| --------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------- | +| IPC responder ask UI blocks until user interacts, even after subagent death | pi's ask UI components don't accept `AbortSignal` | Post-call abort check prevents writing stale answers | +| No custom text input on escalation | pi's `ui.custom` doesn't support text prompts | "Other" option removed; add back when primitives support it | +| Scout question generation still stubbed | Not in §10 scope (deferred from §9.4) | Decomposer/planner run without codebase context from scouts | + +--- + +## 11. Rewrite Specification (2026-03-11) + +This section is the authoritative specification for the clean rewrite. It +was produced from a full codebase analysis session that examined every +source file, the complete plan (§1–§10), and resolved all ambiguities, +open decisions, and risks through structured decision-making. Where this +section conflicts with earlier sections, this section governs. + +### 11.1 Rewrite approach + +**Architecture-clean, infrastructure-pragmatic.** All module boundaries +and APIs are redesigned from scratch. Working infrastructure internals +(IPC file protocol, EventLog/audit, pool semaphore, atomic write patterns) +are ported into the new shape rather than rewritten blind. No code is +carried over verbatim — every module should look purpose-built for the +new architecture. + +### 11.2 Scout system redesign + +**This is the largest architectural change from the original plan.** + +#### 11.2.1 The `koan_request_scouts` tool + +A new tool available to intake, decomposer, and planner roles. When called, +the subagent pauses (via IPC), the driver spawns scouts in parallel via +`pool()`, and results are returned to the calling agent. + +```typescript +const ScoutTaskSchema = Type.Object({ + id: Type.String({ description: "Scout task ID, e.g. 'auth-libs'" }), + role: Type.String({ + description: "Custom role for the scout, e.g. 'system architect'", + }), + prompt: Type.String({ + description: "What to find, e.g. 'Find all auth-related files in src/'", + }), +}); + +const RequestScoutsSchema = Type.Object({ + scouts: Type.Array(ScoutTaskSchema, { minItems: 1 }), +}); +``` + +The tool uses the same IPC mechanism as `koan_ask_question`: the subagent +writes a scout request to `ipc.json`, the parent-side IPC responder detects +it, spawns scouts via `pool()`, waits for completion, and writes the result +(scout output file paths) back to `ipc.json`. The subagent reads the paths +and can then read the scout findings files. + +#### 11.2.2 Intake sequence change + +The original plan had intake reading the conversation and asking questions +without codebase context. This meant intake was limited to spec-level +questions and missed grounded questions that prevent downstream surprises. + +**New intake step sequence (3 steps):** + +1. **Context extraction**: Read `conversation.jsonl`. Extract structure into + `context.md` (topic index, file references, decisions, constraints, + unresolved questions). Call `koan_complete_step`. +2. **Codebase scouting**: Based on the conversation's file references and + topic areas, identify what needs exploring. Call `koan_request_scouts` + with targeted questions. Call `koan_complete_step`. +3. **Gap analysis + questions**: Review the structured summary AND scout + findings together. Identify gaps — including contradictions between user + intent and codebase reality, missing dependencies, incorrect assumptions + about what exists. Formulate questions. Present to user via + `koan_ask_question`. Write answers to `decisions.md`. Call + `koan_complete_step`. + +This means `context.md` and `decisions.md` are grounded in codebase reality +from the start, and the user's answers are informed by what actually exists. + +#### 11.2.3 Three scout phases + +1. **Intake scouts** — broad codebase survey informed by conversation context. + Enables grounded user questions. +2. **Decomposition scouts** — concern-area exploration for story splitting. + Different questions from intake scouts. +3. **Per-story planning scouts** — current file state at execution time (may + have changed from earlier story execution). + +Each phase calls `koan_request_scouts` with its own set of questions. The +driver handles all scout spawning through the IPC responder. + +#### 11.2.4 IPC protocol extension + +The IPC file (`ipc.json`) gains a second message type: + +```typescript +// Existing ask request +interface AskRequest { + type: "ask"; + questions: QuestionItem[]; + response: AskResponse | null; +} + +// New scout request +interface ScoutRequest { + type: "scout-request"; + scouts: ScoutTask[]; + response: ScoutResponse | null; +} + +interface ScoutResponse { + findings: string[]; // File paths to scout output markdown files + failures: string[]; // Scout IDs that failed (non-fatal) +} +``` + +The parent-side IPC responder checks the `type` field and routes to either +the ask UI flow or the scout spawn flow. + +### 11.3 Tool inventory changes + +#### 11.3.1 Eliminate `koan_escalate` + +**Escalation is asking a question.** Remove `koan_escalate` as a separate +tool. When the orchestrator needs human input (verification failures, +out-of-plan deviations, ambiguities), it uses `koan_ask_question` directly. +The orchestrator gets the answer via IPC, then decides what to do (retry, +skip, etc.) and calls the appropriate state-transition tool. + +This eliminates: + +- The `escalated` story status +- `EscalationInfo` from `StoryState` +- `escalation-ui.ts` as a separate component +- The driver's special escalation routing path + +The driver's routing simplifies: + +- `retry` with budget remaining → re-execute +- `retry` with budget exhausted → driver asks user via IPC or sets `skipped` +- No `escalated` status to handle + +#### 11.3.2 Add `koan_request_scouts` + +New tool per §11.2.1. Added to the permission sets of intake, decomposer, +and planner roles. + +#### 11.3.3 Revised tool inventory + +| Tool | Purpose | Roles | State Transition | +| --------------------- | -------------------------------------- | --------------------------- | ---------------------- | +| `koan_complete_step` | Advance phase step | All | Internal step counter | +| `koan_ask_question` | Ask user a question (IPC) | All except scout | None (synchronous) | +| `koan_request_scouts` | Request parallel codebase scouts (IPC) | Intake, decomposer, planner | None (synchronous) | +| `koan_select_story` | Pick next story | Orchestrator | `pending` → `selected` | +| `koan_complete_story` | Mark story done | Orchestrator | `verifying` → `done` | +| `koan_retry_story` | Mark for re-execution | Orchestrator | `verifying` → `retry` | +| `koan_skip_story` | Mark story skipped | Orchestrator | `pending` → `skipped` | + +### 11.4 Revised state machine + +The `escalated` status is removed. Retry budget exhaustion is handled by +the driver notifying the user (or skipping), not by a separate status. + +``` +pending ──[koan_select_story]──► selected + │ │ + │ (driver: fixed) + │ │ + │ planning ──► executing ──► verifying + │ │ + │ ┌───────────────────────┤ + │ │ │ + │ [complete_story] [retry_story] + │ │ │ + │ ▼ ▼ + │ done retry + │ │ + │ (driver: budget + │ check, re-exec + │ or skip+notify) + │ │ + │ executing + │ │ + │ verifying + │ + └──[koan_skip_story]──► skipped +``` + +Valid source statuses per tool (enforced — see §11.12): + +| Tool | Valid source statuses | +| --------------------- | --------------------- | +| `koan_select_story` | `pending`, `retry` | +| `koan_complete_story` | `verifying` | +| `koan_retry_story` | `verifying` | +| `koan_skip_story` | `pending` | + +### 11.5 Architectural decisions + +#### 11.5.1 BasePhase class + +Extract a `BasePhase` class with the common lifecycle: event hook +registration, step progression, permission gating, audit emission. +Subclasses define only their step definitions (names, guidance functions) +and system prompt. This eliminates ~40 lines of duplicated skeleton per +phase. + +#### 11.5.2 RuntimeContext (replaces mutable refs) + +Replace `PlanRef` + `SubagentRef` + `WorkflowDispatch` with a single +`RuntimeContext` object: + +```typescript +interface RuntimeContext { + epicDir: string | null; + subagentDir: string | null; + onCompleteStep: ((thoughts: string) => string | null) | null; +} +``` + +Set once during `before_agent_start`. All tools read from this single +object. Fewer moving parts than three separate mutable refs. + +#### 11.5.3 Template-based spawn prompts + +Define explicit prompt templates per role in `prompts.ts`. Spawn functions +fill templates with runtime data (epicDir, storyId, scout paths, etc.). +The spawn prompt carries contextual information; phase step guidance carries +structural instructions. Both are combined in the subagent's context via +the append pattern. + +#### 11.5.4 status.md schema + +Templated sections for consistent orchestrator reads: + +```markdown +# Status: <status> + +## Last Action + +<what happened and when> + +## Verification Summary + +<pass/fail details from verify.md checks> + +## Notes + +<propagation notes, autonomous decisions, context for next invocation> +``` + +#### 11.5.5 Story ID format + +`S-001-auth-provider` — numbered + descriptive. Sortable and human-readable. +The decomposer prompt instructs this format. The driver discovers by +filesystem scan and is format-agnostic. + +### 11.6 Driver changes + +#### 11.6.1 Widget active polling + +The driver runs a concurrent interval (2s) during subagent execution that +reads the subagent's `events.jsonl` projection via `readProjection()` and +updates the widget with step progress + log tail. The polling interval is +unref'd so it doesn't prevent process exit. + +#### 11.6.2 Pre-create `stories/` directory + +Before spawning the decomposer, the driver creates the `stories/` directory +under the epic dir. The decomposer's `write` tool creates per-story +subdirectories when writing `story.md` files. + +#### 11.6.3 Simplified routing (no escalation path) + +```typescript +function routeFromState(stories: StoryState[]): RoutingDecision { + // 1. retry with budget → re-execute + // 2. retry without budget → skip + notify user + // 3. selected → execute (plan → run → verify) + // 4. all terminal → complete + // 5. none of above → error +} +``` + +#### 11.6.4 Binary error recovery + +Exit code 0 vs non-zero. The orchestrator (post-exec) interprets what went +wrong. The driver routes based on the resulting state, not failure details. + +### 11.7 Post-execution propagation + +The orchestrator's post-execution step 3 (propagation) examines: + +- `plan.md` — what was intended +- `verify.md` — what passed/failed +- `git diff --stat` — summary of what files changed and how much + +This is enough to identify scope overlap with remaining stories without +reading full diffs. The orchestrator uses `write` to update affected +`story.md` files and appends to `decisions.md` with `[autonomous]` marker. + +### 11.8 Conversation format + +Keep raw JSONL export (`conversation.jsonl`). Accept pi-version coupling. +Intake prompt instructs the LLM to extract user/assistant messages and +ignore internal SessionManager entries (header, compaction, etc.). + +### 11.9 Permission model + +`bash` remains in `READ_TOOLS` (always allowed). This is an accepted +limitation — prompt engineering prevents abuse, enforcement is best-effort. +Document clearly in permission module comments. + +`koan_request_scouts` is added to intake, decomposer, and planner +permission sets. + +### 11.10 IPC design + +Keep single-file IPC (`ipc.json` per subagent). Correct for sequential +execution. Redesign when parallel story execution is implemented. The +file format is extended with a `type` field to distinguish ask requests +from scout requests (§11.2.4). + +### 11.11 Testing strategy + +**Property-based state machine tests.** Verify: + +- All valid story status transitions (per §11.4 table) +- Routing decisions for all state combinations +- Permission matrices (role × tool × expected result) + +Skip IO-heavy integration tests. The system is inherently hard to test +end-to-end due to LLM non-determinism. Focus on the deterministic +boundaries (state machine, routing, permissions, tool validation). + +### 11.12 Tool state-transition validation + +**Enforce all transitions.** Every orchestrator tool validates source +status against the state machine (§11.4). Invalid transitions are rejected +with clear error messages including current status and valid source +statuses for the tool. + +### 11.13 Convention resources + +Keep `resources/conventions/` but defer integration. Preserve the files; +decide how to use them in executor/planner prompts after the core rewrite +is stable. + +### 11.14 Remaining accepted limitations + +| Limitation | Why | Mitigation | +| ----------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------- | +| IPC ask UI blocks until user interacts, even after subagent death | pi's ask API doesn't accept AbortSignal | Post-call abort check prevents writing stale answers | +| bash in READ_TOOLS bypasses write path-scoping | Distinguishing read/write bash is intractable | Prompt engineering; document clearly | +| Conversation format coupled to pi internals | No stable export API | Intake prompt handles extraction | +| Single-file IPC won't scale to parallel execution | Sequential execution for now | Redesign when parallel is implemented | + +--- + +## 12. Post-Implementation Fixes — Scope & Lifecycle Mismatches (2026-03-12) + +Post-implementation review and problem analysis (user reported the epic +widget not appearing during intake) uncovered 11 scope/lifecycle/naming +mismatches in the rewritten codebase. The root pattern: the rewrite built +types, infrastructure, and UI surfaces at epic breadth but only wired them +into the story execution loop (Phase B). Phase A (intake → decomposition → +spec review) runs with no persistent visual feedback. + +This section specifies the fixes. They are grouped into four clusters (A–D) +ordered by dependency — each cluster can be implemented as one commit. + +### 12.1 Cluster A — Lift observation scope to epic lifetime + +**Root problem:** `EpicWidgetController` is created inside `runStoryLoop()` +(Phase B), not at the start of `runEpicPipeline()`. Phase A subagents +(intake, decomposer) write `EventLog` entries but nothing reads or displays +them. The user sees "Starting intake..." then nothing for the entire Phase A +duration. + +**Findings addressed:** #1 (widget scope), #2 (polling asymmetry), #6 +(autonomousDecisions phantom), original problem analysis (broken widget +rendering during Phase A). + +#### 12.1.1 Widget lifecycle change + +Move `EpicWidgetController` construction from `runStoryLoop()` to the top of +`runEpicPipeline()`, before the intake call. The widget instance is passed +into `runIntake()`, `runDecomposer()`, the spec review gate, and +`runStoryLoop()`. + +``` +runEpicPipeline() + ├── create widget ← NEW: widget starts here + ├── Phase A + │ ├── runIntake(widget) ← pass widget + │ ├── runDecomposer(widget) ← pass widget + │ ├── discoverStoryIds → widget.update(stories) + │ └── reviewStorySketches ← widget suppressed during ui.custom() + ├── Phase B + │ └── runStoryLoop(widget) ← receives widget, no longer creates it + └── widget.destroy() +``` + +The widget naturally renders "No stories yet" (empty array) during Phase A — +`renderStoryList` already handles this. After `discoverStoryIds`, the widget +updates with the story list before spec review begins. + +During `reviewStorySketches` (which uses `ui.custom()`, a modal takeover), +the widget is temporarily suppressed by pi's TUI — no code change needed. +After `ui.custom()` resolves, the widget resumes rendering. + +#### 12.1.2 Phase A active polling + +Wire `startActivePolling()` for intake and decomposer subagents. These +subagents already write `EventLog` (via `extensions/koan.ts:94-108`), so +`readProjection()` and `readRecentLogs()` work on their directories. The +change is purely in `runIntake()` and `runDecomposer()`: + +```typescript +// runIntake — after creating subagentDir, before spawnIntake: +const started = Date.now(); +widget?.update({ + activeSubagent: { + role: "intake", + step: 0, + totalSteps: 3, + stepName: "", + startedAt: started, + }, +}); +const stopPolling = widget + ? startActivePolling(subagentDir, widget, started, "intake") + : undefined; +// ... spawnIntake() ... +stopPolling?.(); +``` + +Same pattern for `runDecomposer()` (totalSteps: 2). + +#### 12.1.3 Phase indicator in widget + +Add an `epicPhase` field to `EpicWidgetState`: + +```typescript +interface EpicWidgetState { + epicId: string; + epicPhase: EpicPhase; // NEW — "intake" | "decomposition" | "review" | "executing" | "completed" + stories: Array<{ storyId: string; status: StoryStatus }>; + activeSubagent: ActiveSubagentInfo | null; + logLines: LogLine[]; +} +``` + +Display in the widget header: `Epic · {epicId} · {epicPhase}`. + +The driver calls `widget.update({ epicPhase: "intake" })` before each phase +transition — same points where it already calls `saveEpicState`. + +#### 12.1.4 Remove autonomousDecisions + +Delete `autonomousDecisions` from `EpicWidgetState`, `EpicWidgetUpdate`, +the render badge, and all update callsites. No producer exists; add it back +when one does. + +### 12.2 Cluster B — Dead infrastructure removal + +**Root problem:** Orphaned code from the old architecture and phantom types +that suggest capabilities the system doesn't have. + +**Findings addressed:** #3 (`scouting` phantom phase), #7 (orphaned +WidgetController), #10 (unused runtime temp dir). + +#### 12.2.1 Delete `src/planner/ui/widget.ts` + +900-line `WidgetController` from the old architecture. Zero imports anywhere +in the codebase. Pure dead code. + +#### 12.2.2 Remove `"scouting"` from `EpicPhase` + +The driver never assigns `"scouting"` — scouts are spawned by the IPC +responder within intake/decomposer/planner phases, not as a top-level driver +phase. Remove from the union type: + +```typescript +// Before: +export type EpicPhase = + | "intake" + | "scouting" + | "decomposition" + | "review" + | "executing" + | "completed"; + +// After: +export type EpicPhase = + | "intake" + | "decomposition" + | "review" + | "executing" + | "completed"; +``` + +If a top-level scouting phase is added later, re-add it then. + +#### 12.2.3 Remove runtime temp dir lifecycle + +Delete `createRuntimeTempDir()` call and cleanup in `extensions/koan.ts`, +and delete `src/utils/runtime-temp.ts`. Neither is used by any pipeline +operation. Remove the corresponding test file (`tests/runtime-temp.test.ts`) +if it exists. + +### 12.3 Cluster C — status.md / state.json synchronization + +**Root problem:** The driver writes intermediate statuses (`planning`, +`executing`, `verifying`) to `state.json` but never updates `status.md`. +Any LLM or human reading `status.md` sees a stale status (e.g., still +"selected" while the story is actually executing). + +**Finding addressed:** #4 (status.md / state.json divergence). + +#### 12.3.1 New helper: `writeStatusMarkdown` + +The AGENTS.md invariant prohibits LLMs from writing JSON — it does NOT +prohibit the driver from writing markdown. `status.md` is a projection of +`state.json`, analogous to how `EventLog` projects `state.json` from +`events.jsonl`. + +Add to `src/planner/epic/state.ts`: + +```typescript +export async function writeStatusMarkdown( + epicDir: string, + storyId: string, + status: StoryStatus, + lastAction: string, +): Promise<void> { + const content = [ + `# Status: ${status}`, + "", + `**Last Action:** ${lastAction}`, + "", + "**Verification Summary:** (pending)", + "", + "**Notes:** —", + "", + ].join("\n"); + const filePath = path.join(epicDir, "stories", storyId, "status.md"); + await fs.writeFile(filePath, content, "utf8"); +} +``` + +#### 12.3.2 Driver calls `writeStatusMarkdown` alongside `saveStoryState` + +Every `saveStoryState` call in `driver.ts` that sets a driver-managed status +should also call `writeStatusMarkdown`: + +| Call site | Status | lastAction | +| ----------------------------- | ----------- | ----------------------------------------------- | +| Before planner spawn | `planning` | `"Driver: starting planner"` | +| Before executor spawn | `executing` | `"Driver: starting executor"` | +| Before post-exec orchestrator | `verifying` | `"Driver: starting verification"` | +| Retry budget skip | `skipped` | `"Driver: retry budget exhausted (N attempts)"` | +| Retry re-execute | `executing` | `"Driver: retry attempt N"` | + +Orchestrator tools in `orchestrator.ts` already write richer `status.md` +with LLM-provided content (Last Action, Verification Summary, Notes). These +two writers are mutually exclusive in time — driver writes between subagent +spawns, orchestrator writes during its own execution. + +### 12.4 Cluster D — Honest contracts + +**Root problem:** Function signatures promise capabilities the callers +don't use, or silently degrade instead of failing. + +**Findings addressed:** #5 (nullable UI dead paths), #8 (void'd config +params, storyId coercion). + +#### 12.4.1 Assert UI at the boundary + +Add an assertion at the top of `runEpicPipeline`: + +```typescript +export async function runEpicPipeline( + epicDir: string, + cwd: string, + extensionPath: string, + log: Logger, + ui: ExtensionUIContext | null, +): Promise<{ success: boolean; summary: string }> { + // koan_plan already guards !hasUI, but assert here to catch + // any future call path that bypasses the guard. + if (!ui) { + return { + success: false, + summary: "Epic pipeline requires an interactive UI", + }; + } + // ... +} +``` + +Keep the `| null` type in the signature — inner functions use `widget?` +guards which are harmless and useful for testing. The assertion makes the +actual contract explicit at the entry point. + +#### 12.4.2 Remove void'd config from phase constructors + +`DecomposerPhase` and `ScoutPhase` constructors accept a `config` parameter +and immediately `void config`. Remove the parameter. If phase-specific +config is needed, it should come from `RuntimeContext` or constructor args +with specific types, not a generic object that gets discarded. + +#### 12.4.3 Fail-fast on empty storyId in dispatch + +In `dispatchPhase()`, lines 97 and 109 coerce null `storyId` to `""`: + +```typescript +// Before: +storyId: config.storyId ?? ""; + +// After: +storyId: (() => { + if (!config.storyId) + throw new Error(`${role} phase requires --koan-story-id flag`); + return config.storyId; +})(); +``` + +Or extract a helper. An empty storyId creates malformed filesystem paths +like `stories//plan/plan.md` — this must fail immediately, not silently +produce broken paths. + +### 12.5 Acknowledged: bash in READ_TOOLS + +Per §11.9, `bash` in READ_TOOLS is an accepted limitation. The current +`permissions.ts` comment documents this. The actual scope is broader than +the per-role maps imply (bash is allowed for ALL roles via the early-return +READ_TOOLS check, not just orchestrator/executor as the role map suggests). + +**Fix:** Update the comment in `permissions.ts` to accurately state that +`bash` is globally allowed via READ_TOOLS, not per-role. No behavioral +change. + +### 12.6 Implementation order + +Clusters have the following dependencies: + +``` +B (dead code removal) ← independent, do first for clean baseline + ↓ +A (widget lifecycle) ← depends on B (scouting phase removed from EpicPhase) + ↓ +C (status.md sync) ← independent of A, but cleaner after A + ↓ +D (honest contracts) ← independent, do last (smallest changes) +``` + +Recommended order: **B → A → C → D**. + +### 12.7 Verification + +After all fixes: + +- `npx tsc --noEmit` → zero errors +- `npm test` → all pass (test count may decrease from removing runtime-temp tests) +- Widget appears immediately when `koan_plan` starts (manual verification) +- Widget shows phase transitions during intake and decomposition +- `status.md` reflects `planning`/`executing`/`verifying` during subagent runs +- No `scouting` in EpicPhase, no `autonomousDecisions` in widget, no `widget.ts` +- `dispatchPhase` throws on empty storyId for planner/executor diff --git a/plans/2026-03-13-web-ui-review.md b/plans/2026-03-13-web-ui-review.md new file mode 100644 index 0000000..bfeb419 --- /dev/null +++ b/plans/2026-03-13-web-ui-review.md @@ -0,0 +1,510 @@ +# Plan Review: 2026-03-13-web-ui.md + +Read-only analysis. Cross-references every file the plan marks as deleted, +rewritten, or unchanged against actual code. + +> **Status:** All significant findings addressed in the 2026-03-14 revision +> of the plan. See revision notes at the top of the plan for summary of +> changes. + +--- + +## Finding 1: `startActivePolling` signature couples to `EpicWidgetController` + +**What:** `startActivePolling()` (driver.ts L81–112) takes a `widget: EpicWidgetController` +parameter and calls `widget.update()` directly. The plan says to replace `widget.update()` +calls with `webServer.push*()` calls (§4.2), but doesn't mention that `startActivePolling` +is a standalone function with its own parameter, not a method on the widget. Its signature +must change from `(dir, widget, ...)` to `(dir, webServer, ...)`. + +**Where:** `driver.ts` L81–112, plan §4.6. + +**Why it matters:** A developer implementing §4.2's mapping table ("replace `widget.update` +→ `webServer.push*`") would miss this function because it's not a call site _on the widget +from the driver_. It's a function that _receives_ the widget. There are 10 call sites of +`startActivePolling` (L132, L160, L204, L231, L257, L285, L317, L339, L376 — all pass +`widget` as second arg). All of them need their second argument changed too. + +**Severity:** Significant — omission would cause compile errors, but the plan should make +this refactoring explicit. + +--- + +## Finding 2: `startActivePolling` also needs non-null guard refactoring + +**What:** Every `startActivePolling` call site is guarded by `if (widget)`: + +```typescript +if (widget) { + widget.update({ activeSubagent: { ... } }); + stopPolling = startActivePolling(subagentDir, widget, startedAt, "intake"); +} +``` + +The plan replaces `widget` (nullable `EpicWidgetController | null`) with `webServer` +(nullable `WebServerHandle | null`). But all these guard blocks do _two_ things: set the +initial subagent state AND start polling. In the web version, these are separate concerns: + +- `pushSubagent()` can fire unconditionally (it's a no-op when no SSE clients are connected) +- `startActivePolling()` should also run unconditionally so the server has data to push + +**Where:** driver.ts L127–133 (and 9 similar blocks), plan §4.2, §4.6. + +**Why it matters:** If the `if (webServer)` guards are blindly ported, the server's push +behavior becomes identical to the widget's. But the web server _should_ push data even if no +browser is connected yet (SSE replay sends it when a browser connects). The null guard should +change from "has UI?" to "has server?" — and the push methods should not require a connected +client. + +**Severity:** Minor — correct behavior follows naturally if pushes are fire-and-forget into +an internal state buffer, but the plan should clarify this design intent. + +--- + +## Finding 3: `reviewStorySketches` reads from filesystem, not from data passed by driver + +**What:** The plan's §4.3 says `webServer.requestReview(stories)` replaces +`reviewStorySketches(epicDir, storyIds, ui)`. But `reviewStorySketches` (spec-review.ts L49–55) +receives `epicDir` and `storyIds`, then _reads the filesystem itself_: + +```typescript +for (const storyId of storyIds) { + const storyPath = path.join(epicDir, "stories", storyId, "story.md"); + const content = await fs.readFile(storyPath, "utf-8"); + const firstLine = content.split("\n").find((l) => l.trim().length > 0); + const title = firstLine?.replace(/^#+\s*/, "").slice(0, 80) ?? storyId; + entries.push({ storyId, title, include: true }); +} +``` + +The web version needs the server to do this filesystem reading _before_ pushing the +`review` SSE event. The plan's SSE event payload in §3.1 says +`{ requestId, stories: [{ id, title, summary }] }` — where does `summary` come from? +The current code only extracts `title` (first line of story.md), not a summary. + +**Where:** `spec-review.ts` L49–55, plan §3.1 (review event), §4.3. + +**Why it matters:** The `review` SSE event payload includes `summary` which doesn't exist +in the current data model. Either the plan intends to add summary extraction (scope creep) +or this is a spec error. The `ReviewStory` type in the `WebServerHandle` interface needs to +match what the filesystem actually provides: `{ storyId, title }` — not `{ id, title, summary }`. + +**Severity:** Minor — easy to correct during implementation, but the payload mismatch between +§3.1 and the actual filesystem data would cause confusion. + +--- + +## Finding 4: Plan marks `ask-logic.ts` for deletion but its types cross 5 boundaries + +**What:** §5.1 lists `ask-logic.ts` for deletion and notes types must be "relocated to +`web/server-types.ts`". But the relocation has non-obvious consequences: + +1. `ipc.ts` (marked UNCHANGED) has its own `AskQuestionPayload` and `AskAnswerPayload` + types that are _structurally compatible but separately defined_ from `ask-logic.ts`'s + `AskQuestion` and `AskSelection`. Currently, `ipc-responder.ts` manually maps between + them (L55–61, L87–97). + +2. The `AskQuestion` type in `ask-logic.ts` has fields `{ id, question, options: AskOption[], +multi?, recommended? }`. The `ipc.ts` payload has `{ questions: Array<{ id, question, +options: Array<{ label }>, multi?, recommended? }> }`. These are duck-type compatible + but there's a subtle difference: `AskOption` is `{ label: string }` while the IPC version + uses inline `{ label: string }`. Any migration must decide: are these the same type or + deliberately separate? + +3. The `OTHER_OPTION` constant and `appendRecommendedTagToOptionLabels` are currently applied + _inside the TUI rendering code_ (ask-inline-ui.ts L38, ask-tabs-ui.ts L118–127). In the + web version, the "Other" option must be added either: + - Server-side (before pushing via SSE) — then the browser is simpler + - Browser-side (in forms.js) — then the server pushes raw options + + The plan doesn't specify where this transformation happens. + +**Where:** `ask-logic.ts`, `ipc.ts`, `ipc-responder.ts`, plan §4.4 note, §5.1. + +**Why it matters:** The implementation note in §4.4 correctly identifies this complexity but +leaves it unresolved. Since `ipc.ts` is marked UNCHANGED, the new `server-types.ts` must +provide types that bridge between `ipc.ts`'s wire types and the SSE/POST payload types. The +boundary mapping that currently lives in `ipc-responder.ts` L55–61 and L87–97 must be +preserved in the rewrite. + +**Severity:** Significant — getting the type boundary wrong here would either break IPC +compatibility with subagents (catastrophic) or create confusing type mismatches across the +server-types / ipc / browser boundary. + +--- + +## Finding 5: `spawnSubagent` uses `opts.ui` to gate IPC responder — type change cascades + +**What:** `subagent.ts` L96–105 uses `if (opts.ui)` to decide whether to start the IPC +responder. The plan says to change `ui?: ExtensionUIContext` to +`webServer?: WebServerHandle` (§5.2). But the IPC responder currently receives +`ExtensionUIContext` directly: + +```typescript +void runIpcResponder(opts.subagentDir, opts.ui, ac.signal, opts.scoutContext); +``` + +The rewritten `runIpcResponder` will need `WebServerHandle` instead. This means +`subagent.ts` → `ipc-responder.ts` → `WebServerHandle` is a transitive dependency. + +Currently, `ipc-responder.ts` imports from `../ui/ask/ask-inline-ui.js` and +`../ui/ask/ask-tabs-ui.js`. After the rewrite, it imports from `../web/server-types.js` +and calls `webServer.requestAnswer()`. This import chain change is correctly described +in §5.2 and §10 step 4, but the plan doesn't mention that `runIpcResponder`'s +signature change means the `ScoutSpawnContext` also needs verification — scout +spawning goes through the IPC responder, and scouts don't get a UI/webserver. + +Actually, looking closer: scouts are spawned inside `handleScoutRequest` which +currently doesn't use `ui` at all — it uses `scoutCtx.spawnScout()`. The `ui` +parameter is only used in `handleAskRequest`. So the `scoutContext` path is clean. + +**Where:** `subagent.ts` L96–105, `ipc-responder.ts` L178 signature, plan §5.2. + +**Why it matters:** The plan correctly identifies the cascade but implementers need to know: +only `handleAskRequest` touches the UI/webserver handle. `handleScoutRequest` is UI-agnostic. +The rewritten `runIpcResponder` signature changes from +`(dir, ui: ExtensionUIContext, signal, scoutCtx?)` to +`(dir, webServer: WebServerHandle, signal, scoutCtx?)`. + +**Severity:** Minor — correctly handled by the plan's implementation sequence (step 4 before +step 5), but worth noting the scout path stays clean. + +--- + +## Finding 6: No abort-initiated cleanup of pending SSE events after subagent death + +**What:** When a subagent dies, `proc.on("close")` calls `abortIpc()` which aborts the +IPC responder. Currently, the TUI ask widget stays rendered until the user dismisses it +(the existing bug noted in the exploration). The plan's §4.4 says `requestAnswer()` rejects +with `AbortError` and the browser receives an `ask-cancelled` SSE event. + +But: who sends the `ask-cancelled` event? The plan's `WebServerHandle` interface (§4.1) +has `requestAnswer()` that returns a Promise. If the signal fires, the Promise rejects. The +`ipc-responder.ts` catch block writes `createCancelledResponse()` to IPC. But _who pushes +the `ask-cancelled` SSE event to the browser?_ + +Options: + +1. The `requestAnswer()` implementation detects its own AbortSignal and self-cancels by + both rejecting AND pushing the SSE event internally. +2. The `ipc-responder.ts` catch block explicitly pushes the event via `webServer.pushX()`. +3. Some other mechanism. + +**Where:** Plan §3.1 (`ask-cancelled` event), §4.4 (abort handling), `ipc-responder.ts` +L73–77, `subagent.ts` L107–109. + +**Why it matters:** If `requestAnswer()` doesn't internally clean up the `pendingInputs` +map entry AND push `ask-cancelled` on abort, the browser will show a stale question form +that the user can fill out and submit — but the POST handler will get a 409 (request already +resolved). This is the web equivalent of the existing TUI bug where the ask widget stays +rendered after subagent death. + +**Severity:** Significant — this is the plan's opportunity to _fix_ the existing TUI bug +(ask widget stays up after subagent exits). The plan describes the right events but doesn't +specify the ownership of the cancel push clearly enough. + +--- + +## Finding 7: Heartbeat design changed but plan still references timeout in §6.5 + +**What:** The plan was updated to say the pipeline waits indefinitely (§6.5, §9.3) — no +auto-resolution on heartbeat timeout. But §3.2 still lists `POST /api/heartbeat` as a +route, and §6.5 says "Server watchdog checks every 5 seconds; if no heartbeat for 60 +seconds" — then contradicts itself by saying the pipeline continues without blocking. + +Wait, re-reading the updated plan: §6.5 now says "The server tracks liveness for +observability but does NOT auto-resolve pending inputs on timeout." So the heartbeat is +kept for monitoring only. This is now internally consistent. + +**Severity:** Non-issue (resolved in the plan). + +--- + +## Finding 8: `readProjection` data shape not specified for SSE + +**What:** `startActivePolling` calls `readProjection(activeSubagentDir)` (driver.ts L91) +which returns projection data: + +```typescript +{ step: number, totalSteps: number, stepName: string } +``` + +This data is used to construct the `activeSubagent` update. The plan says `pushSubagent(info)` +where `info` is `ActiveSubagentInfo`: + +```typescript +{ role, storyId?, step, totalSteps, stepName, startedAt } +``` + +But `readProjection` doesn't return `role`, `storyId`, or `startedAt` — those are set by +the caller (the driver function that spawned the subagent). The polling callback currently +merges these with the projection: + +```typescript +widget.update({ + activeSubagent: { + role, + storyId, + step: projection.step, + totalSteps: projection.totalSteps, + stepName: projection.stepName, + startedAt, + }, +}); +``` + +In the web version, `startActivePolling` would need to construct a full +`ActiveSubagentInfo` and call `webServer.pushSubagent(info)`. This means it must either: + +- Receive `role`, `storyId`, `startedAt` as parameters (current pattern, works fine) +- Or the web server must track the "current" role/storyId/startedAt and merge internally + +The current pattern works — `startActivePolling` already takes `role`, `storyId`, and +`startedAt` as parameters (L83–87). The plan should note that the polling function +constructs full `ActiveSubagentInfo` objects for the push, not partial updates. + +**Where:** `driver.ts` L81–112, plan §4.1 (`pushSubagent` signature), §4.6. + +**Why it matters:** Minor clarity issue. The current `widget.update()` accepts partial +patches (`EpicWidgetUpdate` with all optional fields). The proposed `pushSubagent(info)` takes +a complete `ActiveSubagentInfo | null`. This is actually a _better_ design (explicit over +implicit), but the polling function must construct the full object each time. + +**Severity:** Minor — natural outcome of the interface design. + +--- + +## Finding 9: `ui.notify()` calls in `driver.ts` L502 use `ui` not `ui?` + +**What:** Driver L502: + +```typescript +ui.notify("Decomposition complete. Review story sketches...", "info"); +``` + +This is _not_ null-guarded (`ui.notify` instead of `ui?.notify`). It's inside a block +guarded by `if (ui && storyIds.length > 0)` (L500). The plan says replace with +`webServer.pushNotification()`. If the plan changes the parameter from `ui` to `webServer`, +this call is inside a guard that checks truthiness, so it's safe — but the implementer must +update the guard from `if (ui && ...)` to `if (webServer && ...)`. + +There are 3 `ui?.notify()` calls in driver.ts (L418, L468) and 1 `ui.notify()` (L502 inside +explicit guard). All need updating. + +**Where:** `driver.ts` L468, L418, L502, plan §4.5. + +**Why it matters:** Trivial — compile-time catch. + +**Severity:** Minor. + +--- + +## Finding 10: Plan doesn't address `runEpicPipeline` return type and tool response + +**What:** `koan_plan.execute()` in `koan.ts` L129: + +```typescript +const result = await runEpicPipeline( + epicInfo.directory, + extCtx.cwd, + extensionPath, + log, + ui, +); +return { + content: [{ type: "text" as const, text: result.summary }], + details: undefined, +}; +``` + +The plan adds a web server to the pipeline but `koan_plan.execute()` returns only +`result.summary` as text. The web server URL is never communicated to the LLM or user +through the tool result. The plan mentions `pi.exec("open", [url])` to open the browser +but doesn't say what happens if the browser fails to open. + +§12 says "Failure to open the browser is a warning, not a fatal error — the server URL is +included in the tool's output." But the tool's `execute()` function currently returns +_only_ `result.summary` — the URL would need to be prepended or added as additional content. + +**Where:** `koan.ts` L129–134, plan §12, §2.2. + +**Why it matters:** If the browser fails to open and the URL isn't in the tool output, the +user has no way to connect to the web UI. The LLM also can't help the user because it +doesn't know the URL. + +**Severity:** Significant — this is the user's only fallback when browser auto-open fails. +The URL should be included in the tool result (e.g., "Pipeline started. Dashboard: +http://127.0.0.1:{port}/?session={token}"). + +--- + +## Finding 11: `koan_plan` has no try/catch — server cleanup on error + +**What:** `koan_plan.execute()` has no try/catch around `runEpicPipeline()`. The plan puts +`webServer.close()` in `runEpicPipeline`'s `finally` block (§9.4). But the web server is +started _before_ `runEpicPipeline` (§2.2 sequence diagram), inside `koan_plan.execute()`. + +If `runEpicPipeline` receives the server handle and closes it in its `finally` block, this +works. But if the server is started in `koan_plan.execute()` and _something fails between +server start and pipeline start_ (e.g., `exportConversation` throws at koan.ts L126), +the server is leaked — nobody closes it. + +**Where:** `koan.ts` L118–134, plan §2.2, §9.4. + +**Why it matters:** A leaked server holds a port open. The user sees "address already in use" +on the next attempt. The fix is trivial (wrap in try/finally in `execute()` too), but the +plan doesn't mention it. + +**Severity:** Significant — port leak on error path. + +--- + +## Finding 12: SSE state replay must include `pendingInput` — verified correct + +**What:** Plan §6.3 says the server replays current state on SSE connect. §6.4 says pending +inputs are re-pushed on reconnect. This is correct and complete — a browser refresh during +an active question would: + +1. New SSE connects +2. Server replays: `phase`, `stories`, `subagent`, then pending `ask`/`review` +3. Browser reconstructs the question form + +This is the fix for the existing TUI limitation (no recovery from accidental terminal close +during question answering). + +**Severity:** Non-issue — well designed. + +--- + +## Finding 13: `EpicWidgetController`'s 1-second render timer has no web equivalent + +**What:** The widget has a 1-second `setInterval` (epic-widget.ts L206) that re-renders to +keep the elapsed-time display fresh. The plan deletes this widget. In the web UI, elapsed +time for the active subagent must be computed client-side — the server pushes `startedAt` +and the browser calculates elapsed time with `Date.now() - startedAt`. + +The plan doesn't explicitly specify this, but it follows naturally from the SSE event design: +the `subagent` event includes `startedAt`, and the browser computes elapsed time locally. +No server-side timer is needed for this. + +**Where:** `epic-widget.ts` L206–207, plan §7.1 (header: elapsed time). + +**Why it matters:** If a developer tries to replicate the 1-second server-side push, they'd +waste bandwidth. The browser should use `requestAnimationFrame` or `setInterval` locally to +update the elapsed time display. This is natural for web but worth noting since the TUI +needed a server-side timer. + +**Severity:** Minor — implicit but correct. + +--- + +## Finding 14: Plan marks `ask-inline-note.ts` for deletion — one function used by ask UIs + +**What:** `ask-inline-note.ts` exports `INLINE_NOTE_WRAP_PADDING` and +`buildWrappedOptionLabelWithInlineNote`. These are imported by both `ask-inline-ui.ts` and +`ask-tabs-ui.ts` (the TUI rendering code). Since both consumers are deleted, the deletion +of `ask-inline-note.ts` is safe — no dangling imports. + +The plan correctly identifies this (§5.1). The `wrapTextWithAnsi` import from `pi-tui` in +this file is purely for TUI rendering, so no web equivalent is needed. + +**Severity:** Non-issue — verified correct. + +--- + +## Finding 15: `config/menu.ts` imports stay but lose sibling files + +**What:** The plan keeps `ui/config/menu.ts` and `ui/config/model-selection.ts` (§8.1). +`menu.ts` imports from `model-selection.ts`: + +```typescript +import { createModelSelectionComponent } from "./model-selection.js"; +``` + +Both files stay. `koan.ts` imports `openKoanConfig` from `menu.ts`: + +```typescript +import { openKoanConfig } from "../src/planner/ui/config/menu.js"; +``` + +After the rewrite, the `ui/` directory would contain _only_ `config/` (with 2 files). The +sibling files (epic-widget, spec-review, ask/) are deleted. This leaves a `ui/` directory +with a single subdirectory. The plan should note this is intentional — the directory structure +looks odd but is correct. + +Additionally: `menu.ts` imports from `../../model-config.js` and `../../model-resolver.js` +(which are UNCHANGED). And it uses `ExtensionCommandContext` from pi-coding-agent (a +different type than `ExtensionUIContext`). So `config/menu.ts` has no dependencies on +any deleted file. Clean. + +**Where:** `ui/config/menu.ts`, `ui/config/model-selection.ts`, plan §8.1. + +**Why it matters:** A developer might question why `ui/` still exists after "deleting +`src/planner/ui/`". The plan should say "delete files in `ui/` except `config/`" rather +than "delete `src/planner/ui/`". + +**Severity:** Minor — wording clarity. + +--- + +## Finding 16: `SpawnOptions` exports are used by multiple consumers + +**What:** `subagent.ts` exports `SpawnOptions`, `SpawnStoryOptions`, and `SubagentResult`. +The plan says to change `ui?: ExtensionUIContext` to `webServer?: WebServerHandle` in +`SpawnOptions` (§5.2). But `SpawnOptions` might be imported by other files: + +```bash +grep -rn 'SpawnOptions' src/planner/ → subagent.ts only +``` + +`SpawnOptions` is not imported by any other file — it's used internally by the spawn +functions. The public API is the individual spawn functions (`spawnIntake`, `spawnDecomposer`, +etc.), which receive `SpawnOptions` or `SpawnStoryOptions` as their parameter. The callers +(in `driver.ts`) construct these inline: + +```typescript +await spawnIntake({ + epicDir, + subagentDir, + cwd, + extensionPath, + log, + ui: ui ?? undefined, +}); +``` + +All 9 spawn call sites in `driver.ts` pass `ui: ui ?? undefined`. These all need to change +to `webServer: webServer ?? undefined`. + +**Where:** `driver.ts` (9 spawn call sites), `subagent.ts` (SpawnOptions interface). + +**Why it matters:** The plan mentions this in §5.2 but doesn't quantify: there are exactly +9 spawn call sites in driver.ts that pass `ui`, plus 1 in `makeScoutSpawnContext` that +deliberately omits `ui` (scouts don't get it). All 9 need updating. + +**Severity:** Minor — compile-time enforcement. + +--- + +## Summary + +| # | Finding | Severity | Status | +| --- | --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------- | +| 1 | `startActivePolling` signature needs explicit refactoring | Significant | ✅ Resolved — replaced with `trackSubagent`/`clearSubagent` (§4.1, §4.6) | +| 2 | Null-guard semantics: push should work without connected client | Minor | ✅ Resolved — state buffered for replay (§4.1, §6.3) | +| 3 | `reviewStorySketches` reads filesystem; `summary` field doesn't exist | Minor | ✅ Resolved — `ReviewStory = { storyId, title }`, no summary (§3.1, §4.3) | +| 4 | `ask-logic.ts` type relocation has IPC boundary complexity | Significant | ✅ Resolved — model code relocated, OTHER_OPTION applied server-side (§5.1) | +| 5 | `subagent.ts` → `ipc-responder.ts` cascade is clean for scouts | Minor | ✅ Noted in §5.2 | +| 6 | `ask-cancelled` SSE event ownership unclear on abort path | Significant | ✅ Resolved — server owns all 3 cleanup steps (§4.1, §9.3) | +| 7 | Heartbeat design: observability only | Non-issue | ✅ Clarified in §6.5 | +| 8 | Polling constructs full `SubagentEvent`, not partial updates | Minor | ✅ Resolved — explicit type in §3.1, construction in §4.6 | +| 9 | `ui.notify` vs `ui?.notify` — null-safety | Minor | ✅ Resolved — all 3 sites listed in §4.5 | +| 10 | Server URL not in tool result | Significant | ✅ Resolved — URL in tool result text (§12.3) | +| 11 | Server port leak between server start and pipeline | Significant | ✅ Resolved — `try/finally` in `execute()` (§2.2, §9.2) | +| 12 | SSE state replay + pending input re-push: well designed | Non-issue | ✅ | +| 13 | Elapsed time: browser-local computation | Minor | ✅ Implicit — `startedAt` in `SubagentEvent` (§3.1) | +| 14 | `ask-inline-note.ts` deletion: clean | Non-issue | ✅ | +| 15 | `ui/` directory partially deleted | Minor | ✅ Resolved — "delete everything except `config/`" (§5.1) | +| 16 | 9 spawn call sites need `ui:` → `webServer:` | Minor | ✅ Quantified in §5.2 | + +**All findings resolved in the 2026-03-14 plan revision.** diff --git a/plans/2026-03-13-web-ui.md b/plans/2026-03-13-web-ui.md new file mode 100644 index 0000000..e4847ea --- /dev/null +++ b/plans/2026-03-13-web-ui.md @@ -0,0 +1,1091 @@ +# Koan Web UI: Architecture Plan + +> **Date:** 2026-03-13 (revised 2026-03-14) +> **Scope:** Replace all TUI-based UI with a browser-based web interface. +> Hard rewrite — all existing widget/TUI code deleted. No tests required. +> +> **Revision notes:** §2.2 resource ownership, §3.1 explicit SSE types, +> §4.1 `trackSubagent`/`clearSubagent` replaces polling, §4.5 null-safety, +> §6.5 heartbeat clarity, §9 fail-fast cleanup, §12 URL in tool result, +> rename `runEpicPipeline` → `runPipeline`. + +--- + +## 1. Motivation + +Koan currently renders its UI through pi's TUI layer (`ui.setWidget`, +`ui.custom`, `ui.notify`). This works but constrains the interface to +terminal capabilities: fixed-width text, keyboard-only navigation, no rich +layout. The pipeline runs for minutes and involves multiple user interaction +points (intake questions, spec review, subagent questions during execution). + +A web UI provides: + +- Rich visual status dashboard (story cards, progress bars, log streaming) +- Form-based question answering (radio buttons, checkboxes, text inputs) +- Persistent visibility — the browser tab stays open for the full pipeline +- Better information density than a terminal widget + +--- + +## 2. Architectural Model + +### 2.1 Relationship to pi + +Koan remains a pi extension. The `koan_plan` tool's `execute()` method is +still the entry point. The change is in _what happens after the pipeline +starts_ — instead of creating a TUI widget and routing IPC responses through +TUI components, the driver starts an HTTP server and routes everything through +the browser. + +### 2.2 Server lifecycle and resource ownership + +The HTTP server is **long-lived within a pipeline run**. It starts in +`koan_plan.execute()` and is owned by `execute()` — not by `runPipeline()`. +This differs from the pi extension pattern (design-deck, plannotator) where +the server is ephemeral per tool call. + +The `try/finally` in `execute()` guarantees cleanup whether the pipeline +succeeds, fails, or any intermediate step throws (e.g., `exportConversation` +failing between server start and pipeline start): + +``` +koan_plan.execute() + → createEpicDirectory() + → server = startWebServer() ← binds random port, returns handle with known URL + → try { + openBrowser(pi, server.url) ← non-fatal; URL is in the tool result (§12) + exportConversation(...) + result = runPipeline(epicDir, cwd, extensionPath, log, server) + ├── Phase A: intake, decomposition, review + │ (server pushes state via SSE, receives input via POST) + └── Phase B: story execution loop + (server continues pushing state, receives question answers) + return { text: server.url + result.summary } + } finally { + server.close() ← kills HTTP server, SSE connections, polling timers + } +``` + +`runPipeline()` receives the server handle but does **not** own its lifecycle. +It has no `try/finally` for the server — the caller (`execute()`) handles +cleanup. `runPipeline` focuses on orchestration only. + +### 2.3 Concurrency model + +The driver's orchestration loop and the HTTP server run concurrently on +Node's event loop. Every `await spawnSubagent(...)` yields to the event loop, +allowing the server to handle requests. No threads, no worker processes. + +When the driver needs user input (spec review, subagent question), it creates +a Promise and stores the resolve function. The POST handler calls resolve when +the browser submits. The driver `await`s this Promise at the appropriate point +in its control flow — a natural async wait, not a hack to block the agent loop. + +``` + Node.js Event Loop + ┌──────────────────┐ + │ │ + Driver loop ─────┤ await spawn() │──── HTTP server handles requests + (orchestration) │ await answer() │ (SSE push, POST receive) + │ read state │ + └──────────────────┘ +``` + +--- + +## 3. Communication Design + +### 3.1 Server → Browser: SSE + +A single SSE channel (`GET /events?session=<token>`) pushes all state updates +to the browser. Event types mirror the current `widget.update()` calls. + +Each SSE event has a named type and a JSON payload. The full TypeScript +definitions: + +```typescript +// --- SSE event payloads (server → browser) --- + +// Pipeline phase transition. +// EpicPhase = "intake" | "decomposition" | "review" | "executing" | "completed" +interface PhaseEvent { + phase: EpicPhase; +} + +// Full story list snapshot (sent on every story status change). +// StoryStatus = "pending" | "selected" | "planning" | "executing" +// | "verifying" | "done" | "retry" | "skipped" +interface StoriesEvent { + stories: Array<{ storyId: string; status: StoryStatus }>; +} + +// Active subagent progress update (sent by observation polling, §4.6). +interface SubagentEvent { + role: string; // "intake" | "decomposer" | "planner" | "executor" | "orchestrator" + storyId?: string; // present during story-scoped phases + step: number; // current step (0-based) + totalSteps: number; // total steps in phase + stepName: string; // human-readable step name (may be "" at start) + startedAt: number; // epoch ms — browser computes elapsed time locally +} + +// Active subagent cleared (subagent exited or pipeline idle). +// Payload is empty; event name distinguishes from SubagentEvent. +interface SubagentIdleEvent {} + +// Log tail from active subagent's event log. +interface LogsEvent { + lines: LogLine[]; // LogLine = { tool: string; summary: string; highValue: boolean } +} + +// Fire-and-forget notification (replaces ui.notify). +interface NotificationEvent { + message: string; + level: "info" | "warning" | "error"; +} + +// Subagent question requiring user input. +// AskQuestion = { id, question, options: AskOption[], multi?, recommended? } +// AskOption = { label: string } +interface AskEvent { + requestId: string; // UUID — used in POST /api/answer to correlate + questions: AskQuestion[]; +} + +// Spec review gate requiring user approval. +// ReviewStory has storyId and title only — title is extracted from the first +// non-empty line of stories/{id}/story.md (stripping # heading markers, +// capped at 80 chars). No summary field — the current data model does not +// include one. +interface ReviewEvent { + requestId: string; // UUID — used in POST /api/review to correlate + stories: ReviewStory[]; // ReviewStory = { storyId: string; title: string } +} + +// Subagent died or was aborted while a question was pending — browser +// should clear the stale form and show a dismissible notice. +interface AskCancelledEvent { + requestId: string; +} + +// Pipeline finished (success or failure). Browser shows final status. +interface PipelineEndEvent { + success: boolean; + summary: string; +} +``` + +| SSE Event Name | Payload Type | Replaces | +| --------------- | ------------------- | ----------------------------------------- | +| `phase` | `PhaseEvent` | `widget.update({ epicPhase })` | +| `stories` | `StoriesEvent` | `widget.update({ stories })` | +| `subagent` | `SubagentEvent` | `widget.update({ activeSubagent })` | +| `subagent-idle` | `SubagentIdleEvent` | `widget.update({ activeSubagent: null })` | +| `logs` | `LogsEvent` | `widget.update({ logLines })` | +| `notification` | `NotificationEvent` | `ui?.notify()` | +| `ask` | `AskEvent` | IPC → TUI ask components | +| `review` | `ReviewEvent` | `reviewStorySketches()` | +| `ask-cancelled` | `AskCancelledEvent` | Abort signal fired — clear stale form | +| `pipeline-end` | `PipelineEndEvent` | Pipeline completion | + +### 3.2 Browser → Server: POST + +| Endpoint | Body | Purpose | +| --------------------- | ------------------------------------------------------------- | ---------------------------- | +| `POST /api/answer` | `{ token, requestId, answers: AnswerElement[] }` | Respond to subagent question | +| `POST /api/review` | `{ token, requestId, approved: string[], skipped: string[] }` | Spec review decision | +| `POST /api/heartbeat` | `{ token }` | Browser liveness | +| `POST /api/cancel` | `{ token }` | Cancel pipeline | + +### 3.3 Initial page load + +`GET /?session=<token>` serves the HTML page. Pipeline state is **not** inlined +into the HTML (unlike design-deck) because the state is dynamic and +long-lived. Instead, the browser connects SSE immediately and receives the +current state as an initial burst of events. The server replays current state +on SSE connect — phase, stories, active subagent — so the browser always +starts with a consistent view, even if opened mid-pipeline. + +### 3.4 Authentication + +Session token (UUID) generated per pipeline run. Passed as query parameter for +GET requests, in JSON body for POST requests. Localhost-only binding +(`127.0.0.1`), random port. + +--- + +## 4. Driver Integration + +### 4.1 WebServer handle + +The web server exposes a handle to the driver with push methods, +Promise-based input methods, and observation polling: + +```typescript +interface WebServerHandle { + /** Full URL including session token, e.g. "http://127.0.0.1:54321/?session=abc-123" */ + readonly url: string; + readonly port: number; + + // --- Push methods (fire-and-forget) --- + // Each pushes an SSE event to all connected browsers. If no browser is + // connected, the state is buffered internally for replay on connect (§6.3). + // These never throw — broken connections are logged and cleaned up silently. + + pushPhase(phase: EpicPhase): void; + pushStories(stories: Array<{ storyId: string; status: StoryStatus }>): void; + pushLogs(lines: LogLine[]): void; + pushNotification(message: string, level: "info" | "warning" | "error"): void; + + // --- Observation polling (replaces startActivePolling) --- + // The server owns the polling timer internally. The driver just says + // "start watching this directory" and "stop watching". + // + // trackSubagent: starts a 2-second poll loop that reads readProjection() + // and readRecentLogs() from `dir`, constructs full SubagentEvent objects + // using the provided role/storyId/startedAt, and pushes `subagent` + `logs` + // SSE events. Only one subagent can be tracked at a time — calling + // trackSubagent again replaces the previous one. + // + // clearSubagent: stops polling, pushes `subagent-idle` SSE event. + trackSubagent(dir: string, role: string, storyId?: string): void; + clearSubagent(): void; + + // --- Blocking methods (replace ui.custom calls) --- + // Both accept an AbortSignal. If the signal fires (subagent died, pipeline + // aborting), the implementation: + // 1. Rejects the Promise with AbortError (includes requestId + context) + // 2. Removes the entry from the pendingInputs map + // 3. Pushes an `ask-cancelled` SSE event so the browser clears the form + // The caller (ipc-responder) catches the rejection and writes + // createCancelledResponse() to the IPC file. + requestReview( + stories: ReviewStory[], + signal?: AbortSignal, + ): Promise<ReviewResult>; + requestAnswer( + questions: AskQuestion[], + signal: AbortSignal, + ): Promise<AnswerResult>; + + // --- Lifecycle --- + // Kills the HTTP server, terminates all SSE connections, clears all polling + // timers, rejects any pending requestReview/requestAnswer Promises. + close(): void; +} + +// --- Associated types --- + +interface ReviewStory { + storyId: string; + title: string; // first non-empty line of story.md, stripped of # markers, max 80 chars +} + +interface ReviewResult { + approved: string[]; // storyIds the user checked + skipped: string[]; // storyIds the user unchecked +} + +// Unified answer result — always an array, even for single questions. +// Each element pairs questionId with the selection for explicit correlation. +type AnswerElement = AskSelection & { questionId: string }; + +interface AnswerResult { + cancelled: boolean; + answers: AnswerElement[]; // length matches questions.length +} +``` + +**Type locations:** `ActiveSubagentInfo`, `LogLine`, `AskQuestion`, +`AskSelection`, `AskOption`, `OTHER_OPTION`, and builder functions +(`buildSingleSelectionResult`, `buildMultiSelectionResult`, +`appendRecommendedTagToOptionLabels`) are all defined in or re-exported from +`web/server-types.ts`. `EpicPhase` and `StoryStatus` are imported from +`types.ts`. `LogLine` is imported from `lib/audit.ts`. + +### 4.2 Replacing the widget + +The `EpicWidgetController` class is deleted. Call sites that push state are +replaced with the corresponding `webServer?.push*()` calls. Call sites that +set/clear the active subagent use `trackSubagent`/`clearSubagent`. The +mapping: + +``` +widget.update({ epicPhase: "intake" }) → webServer?.pushPhase("intake") +widget.update({ stories: [...] }) → webServer?.pushStories([...]) +widget.update({ logLines: lines }) → webServer?.pushLogs(lines) +widget.destroy() → (no-op; server lifecycle owned by execute()) + +// Active subagent — old pattern (10 call sites in driver.ts): +widget.update({ activeSubagent: { role, storyId, ... } }) +stopPolling = startActivePolling(dir, widget, ...) +// ... await spawnXxx() ... +stopPolling?.() +widget.update({ logLines, activeSubagent: null }) + +// Active subagent — new pattern: +webServer?.trackSubagent(dir, role, storyId) +// ... await spawnXxx() ... +webServer?.clearSubagent() +``` + +The `startActivePolling` function is **deleted** from `driver.ts`. The polling +concern is encapsulated inside the web server (§4.6). The driver no longer +manages polling timers, `stopPolling` closures, or post-spawn log reads — +`clearSubagent()` handles the final log push internally before pushing +`subagent-idle`. + +All push calls use optional chaining (`webServer?.`) because `webServer` is +`null` in headless mode. This replaces the current `if (widget) { ... }` +guard blocks, simplifying every subagent spawn site from 5+ lines to 2. + +The browser receives structured `LogLine` objects (`{ tool: string, +summary: string, highValue: boolean }`) and renders them with styled DOM +(tool name distinct from summary, high-value entries highlighted). + +### 4.3 Replacing spec review + +Currently: `reviewStorySketches(epicDir, storyIds, ui)` calls `ui.custom()` +to render a TUI checklist. It receives `epicDir` + `storyIds` and reads the +filesystem itself (extracting the title from the first line of each +`stories/{id}/story.md`). The driver awaits the result. + +New: The driver reads story titles from disk, constructs `ReviewStory[]` +objects (`{ storyId, title }` — no `summary` field, matching current data), +and calls `webServer.requestReview(stories)`, which: + +1. Stores the resolve function in `pendingInputs` keyed by a new `requestId` +2. Pushes a `review` SSE event with `{ requestId, stories }` to the browser +3. Returns a Promise +4. Browser renders a checklist (all stories pre-checked) +5. User submits → `POST /api/review` → Promise resolves with `ReviewResult` + +The driver's control flow stays identical — it `await`s the result and then +processes approved/skipped stories. The filesystem-reading logic moves from +`spec-review.ts` (deleted) into the driver or a helper in `web/server.ts`. + +### 4.4 Replacing IPC question routing + +Currently: `ipc-responder.ts` polls `ipc.json`, detects ask requests, renders +TUI ask components, writes responses back. It checks `signal.aborted` after +each blocking ask call to handle the case where the subagent died while the +user was still deciding. + +New: `ipc-responder.ts` is rewritten to: + +1. Poll `ipc.json` as before (the subagent side is unchanged) +2. On ask request: call `webServer.requestAnswer(questions, signal)` instead + of TUI. The `signal` is the AbortSignal from the parent's AbortController + (created per-subagent in `subagent.ts`). +3. This pushes an `ask` SSE event to the browser +4. Browser renders a question form +5. User submits → `POST /api/answer` → Promise resolves with `AnswerResult` +6. Responder writes the answer back to `ipc.json` as before + +**Abort handling:** `requestAnswer()` accepts an `AbortSignal`. If the signal +fires (subagent crashed), the Promise **rejects** with an `AbortError` that +includes the request ID and question context. The ipc-responder catches this +and writes `createCancelledResponse()` to the IPC file. The browser receives +a `ask-cancelled` SSE event to clear the stale form. + +**Unified answer type:** Both single-question and multi-question flows return +`AnswerResult = { cancelled: boolean; answers: AskSelection[] }`. A single +question is `N=1` — the browser always sends back an array. The responder +maps this back to IPC response format uniformly. + +The subagent process (`tools/ask.ts`) is completely unchanged — it still +writes and polls `ipc.json`. Only the parent-side responder changes its +rendering target. + +> **Implementation note for future planning:** The question-answering +> workflow requires careful design during implementation. Key considerations: +> +> 1. **Type migration path:** `AskOption`, `AskQuestion`, `AskSelection`, +> `OTHER_OPTION`, and the builder functions (`buildSingleSelectionResult`, +> `buildMultiSelectionResult`, `appendRecommendedTagToOptionLabels`) from +> `ask-logic.ts` must be relocated to `web/server-types.ts`. These types +> cross 5 boundaries: IPC protocol → ipc-responder → web server handle → +> SSE event payload → browser POST body → web server POST handler → +> ipc-responder → IPC protocol. The IPC layer (`ipc.ts`) has its own +> compatible-but-separate type definitions (`AskIpcFile.payload.questions`) +> — verify alignment. +> 2. **Browser-side form semantics:** The current TUI has an "Other (type +> your own)" option that opens an inline editor. The web form needs a +> text input that appears when "Other" is selected. Multi-select +> (`multi: true`) uses checkboxes; single-select uses radio buttons. +> The `recommended` index gets a "(Recommended)" badge. Validation: +> at least one selection per question, "Other" requires non-empty text. +> 3. **Cancel semantics:** The web form does not provide a cancel button. +> Process lifecycle is managed through the terminal — the user presses +> Ctrl+C in the terminal to abort. The web UI is a view and +> communication medium only; cancel/escape is a terminal concern. +> 4. **Concurrency invariant:** Only one ask request can be pending per +> subagent at a time (enforced by `ipcFileExists()` guard in +> `tools/ask.ts`). The web server's `pendingInputs` map keys by +> requestId, so multiple simultaneous subagent questions (from +> different subagents) are handled correctly. But the browser must +> handle displaying multiple question forms or queuing them — during +> execution, the IPC responder runs per-subagent, and only one +> subagent runs at a time, so in practice there's at most one pending +> question. But during intake, the IPC responder could be active while +> a scout request is also pending — verify these don't collide. +> 5. **IPC file lifecycle around abort:** When abort fires during +> `requestAnswer()`, the server must: (a) reject the Promise, +> (b) remove the entry from `pendingInputs`, (c) push an +> `ask-cancelled` SSE event, (d) the ipc-responder catches the +> rejection and writes a cancelled response. The existing TOCTOU gap +> (checking `ipc.id` then writing) is preserved from the current +> implementation — this is an existing limitation, not introduced by +> the migration. + +### 4.5 Replacing notifications + +The 3 `ui.notify()` calls in `driver.ts` become +`webServer?.pushNotification()` — all with optional chaining since +`webServer` is `null` in headless mode: + +| Location (driver.ts) | Current | New | +| ---------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| L468 (intake start) | `ui?.notify("Starting intake...", "info")` | `webServer?.pushNotification("Starting intake...", "info")` | +| L502 (decomp complete) | `ui.notify("Decomposition complete...", "info")` — inside `if (ui)` guard | `webServer?.pushNotification("Decomposition complete...", "info")` — guard changes to `if (webServer)` | +| L418 (retry budget) | `ui?.notify(\`Story ${storyId} skipped...\`, "warning")` | `webServer?.pushNotification(\`Story ${storyId} skipped...\`, "warning")` | + +The 2 `ui.notify()` calls in `extensions/koan.ts` command handlers (`/koan` +usage help, unknown subcommand) remain as `extCtx.ui.notify()` — these are +pi TUI command responses, not part of the pipeline. `/koan-execute` and +`/koan-status` are removed entirely (§8). + +The 2 `ui.notify()` calls in `ui/config/menu.ts` are unchanged (config menu +stays as TUI). + +### 4.6 Observation polling — encapsulated in the web server + +**Current architecture:** `startActivePolling()` is a standalone function in +`driver.ts` (L81–112) that takes a `widget: EpicWidgetController` parameter. +It creates a 2-second `setInterval` (unref'd) that reads `readProjection()` +and `readRecentLogs()` from the active subagent directory, then pushes +updates to the widget. There are 10 call sites in the driver that pair +`startActivePolling()` / `stopPolling()` around each `await spawnXxx()`. + +**New architecture:** `startActivePolling()` is **deleted** from `driver.ts`. +The polling concern moves inside `WebServerHandle`: + +- `trackSubagent(dir, role, storyId?)` — starts a 2-second `setInterval` + (unref'd) inside the server. Each tick reads `readProjection(dir)` and + `readRecentLogs(dir)`, constructs a full `SubagentEvent` object: + + ```typescript + { + role, // from trackSubagent parameter + storyId, // from trackSubagent parameter (optional) + step: projection.step, // from readProjection() + totalSteps: projection.totalSteps, + stepName: projection.stepName, + startedAt, // captured at trackSubagent call time (Date.now()) + } + ``` + + and pushes `subagent` + `logs` SSE events. If `readProjection` returns + `null` (subagent hasn't written state yet), only `logs` is pushed. Errors + are swallowed (best-effort observation, same as current). + +- `clearSubagent()` — stops the polling timer, does one final + `readRecentLogs()` push, then pushes `subagent-idle`. + +- `close()` — also clears any active polling timer (cleanup). + +This reduces each subagent spawn site in the driver from: + +```typescript +// Old — 5+ lines per spawn, 10 call sites +widget.update({ activeSubagent: { role, storyId, step: 0, ... } }); +stopPolling = startActivePolling(dir, widget, startedAt, role, storyId); +const result = await spawnXxx({ ... }); +stopPolling?.(); +widget.update({ logLines: await readRecentLogs(dir), activeSubagent: null }); +``` + +to: + +```typescript +// New — 2 lines per spawn +webServer?.trackSubagent(dir, role, storyId); +const result = await spawnXxx({ ... }); +webServer?.clearSubagent(); +``` + +**Why this is the right boundary:** The driver is a sequential orchestrator +— it spawns subagents and routes based on exit state. Polling subagent +progress for display is a web server concern, not an orchestration concern. +The driver tells the server _what_ to observe; the server decides _how_ and +_when_ to poll and push. + +--- + +## 5. File Structure + +``` +src/planner/ +├── web/ ← NEW: all web UI code +│ ├── server.ts ← HTTP server: routes, SSE, session mgmt +│ ├── server-types.ts ← WebServerHandle interface, shared types +│ │ (includes relocated AskOption, AskQuestion, +│ │ AskSelection, AnswerResult, ReviewResult, +│ │ ActiveSubagentInfo, LogLine re-export, +│ │ and ask-logic builder functions) +│ ├── html/ +│ │ └── index.html ← Single-page app shell +│ ├── css/ +│ │ └── styles.css ← Styles +│ └── js/ +│ ├── app.js ← Core: SSE connection, state management, +│ │ client-side console.* logging for all events +│ ├── render.js ← DOM rendering: dashboard, stories, logs +│ └── forms.js ← Question forms, spec review, interactions +├── ui/ +│ ├── epic-widget.ts ← DELETED +│ ├── spec-review.ts ← DELETED +│ ├── ask/ ← DELETED (all 4 files) +│ └── config/ ← KEPT (menu.ts + model-selection.ts) +│ ├── menu.ts ← UNCHANGED: TUI settings for /koan config +│ └── model-selection.ts ← UNCHANGED: TUI model tier picker +├── lib/ +│ ├── ipc-responder.ts ← REWRITTEN: route to web instead of TUI +│ ├── ipc.ts ← UNCHANGED: protocol layer +│ └── ... +├── subagent.ts ← MODIFIED: SpawnOptions.ui type changes +├── driver.ts ← MODIFIED: WebServerHandle replaces widget + ui +└── ... +``` + +### 5.1 What gets deleted + +Files in `src/planner/ui/` — delete everything **except** `config/`: + +- `epic-widget.ts` — TUI dashboard widget (replaced by SSE push) +- `spec-review.ts` — TUI story approval checklist (replaced by web form) +- `ask/ask-inline-ui.ts` — TUI single-question picker (replaced by web form) +- `ask/ask-tabs-ui.ts` — TUI multi-question tabbed picker (replaced by web form) +- `ask/ask-inline-note.ts` — ANSI text wrapping (TUI-specific, no web equivalent needed) + +**`ask/ask-logic.ts` — model code, relocated not deleted.** This file +contains no TUI imports. Its types and builder functions are the **data +model** for the ask flow: + +| Export | Kind | Destination | +| ------------------------------------ | ----------------------------------------------------------- | --------------------- | +| `AskOption` | interface `{ label: string }` | `web/server-types.ts` | +| `AskQuestion` | interface `{ id, question, options, multi?, recommended? }` | `web/server-types.ts` | +| `AskSelection` | interface `{ selectedOptions: string[], customInput? }` | `web/server-types.ts` | +| `OTHER_OPTION` | const `"Other (type your own)"` | `web/server-types.ts` | +| `appendRecommendedTagToOptionLabels` | function | `web/server-types.ts` | +| `buildSingleSelectionResult` | function | `web/server-types.ts` | +| `buildMultiSelectionResult` | function | `web/server-types.ts` | + +These types cross 5 boundaries: IPC protocol (`ipc.ts` has compatible but +separate type definitions) → ipc-responder → web server handle → SSE event +→ browser POST → web server POST handler → IPC protocol. The `ipc.ts` +types (`AskIpcFile.payload.questions`, `AskAnswerPayload.answers`) are +structurally compatible — the mapping between them is in `ipc-responder.ts` +and stays there. + +The `OTHER_OPTION` constant and `appendRecommendedTagToOptionLabels` are +currently applied inside the TUI rendering code. In the web version, these +are applied **server-side** before pushing the `ask` SSE event — the browser +receives options with the "(Recommended)" tag and "Other" option already +appended. This keeps the browser code simple (render what you receive). + +**Kept (not deleted):** + +- `config/menu.ts` — TUI settings menu, stays for `/koan config` +- `config/model-selection.ts` — used by menu.ts, stays + +### 5.2 What gets rewritten + +- **`driver.ts`** — Rename `runEpicPipeline` → `runPipeline`. Replace all + `widget.*` and `ui.*` calls with `webServer.*` calls. Remove + `ExtensionUIContext` parameter; accept `WebServerHandle | null` instead. + Delete `startActivePolling` function. Delete `EpicWidgetController` and + `reviewStorySketches` imports. Change all 9 spawn call sites from + `ui: ui ?? undefined` to `webServer: webServer ?? undefined`. Change the + `if (widget) { ... stopPolling ... }` blocks (10 sites) to + `webServer?.trackSubagent(...)` / `webServer?.clearSubagent()` (2 lines + each). Change all 3 `ui?.notify()` / `ui.notify()` calls to + `webServer?.pushNotification()`. Change the `if (ui && storyIds.length > 0)` + spec review guard to `if (webServer && storyIds.length > 0)`. +- **`subagent.ts`** — Change `SpawnOptions.ui` and `SpawnSubagentOpts.ui` + from `ExtensionUIContext` to `WebServerHandle`. Update `spawnSubagent()`'s + `if (opts.ui)` guard and `runIpcResponder()` call to pass the web server + handle instead of ExtensionUIContext. Remove `ExtensionUIContext` import. + All 6 public spawn functions' signatures change (their callers already pass + `opts` objects with the renamed field). Scout spawns continue to omit the + field (scouts don't get UI/web server — unchanged). +- **`lib/ipc-responder.ts`** — Route ask requests to web instead of TUI. + Change `ui: ExtensionUIContext` parameter to `webServer: WebServerHandle` + on both `handleAskRequest` and `runIpcResponder`. Remove imports from + `../ui/ask/ask-inline-ui.js` and `../ui/ask/ask-tabs-ui.js`. Import + `AskQuestion`, `AskSelection` from `../web/server-types.js`. Replace the + single-vs-multi question branching (currently L65–97) with a single + `webServer.requestAnswer(questions, signal)` call. Handle `AbortError` + rejection by writing `createCancelledResponse()` to IPC. +- **`extensions/koan.ts`** — In `koan_plan.execute()`: start web server + before pipeline, wrap in `try/finally` for cleanup, open browser (§12), + pass handle to `runPipeline`, include `server.url` in tool result text. + Remove `/koan-execute` and `/koan-status` commands. Keep `openKoanConfig` + import unchanged (config stays as TUI — §8). + +### 5.3 What gets modified (non-rewrite) + +- **`lib/audit.ts`** — Extended with `UsageEvent` type and token fields on + `Projection` (see intake-ui plan §5). + +### 5.4 What stays unchanged + +- `lib/ipc.ts` — File-based IPC protocol (subagent side is untouched) +- `tools/ask.ts` — Subagent ask tool (writes/polls ipc.json, no UI) +- `tools/workflow.ts` — Step completion tool +- `tools/orchestrator.ts` — Story lifecycle tools +- All phase files (`phases/**`) +- `conversation.ts`, `model-resolver.ts`, `types.ts` +- `lib/runtime-context.ts`, `lib/pool.ts`, `lib/permissions.ts`, + `lib/step.ts` +- `ui/config/menu.ts`, `ui/config/model-selection.ts` — kept for `/koan config` + +--- + +## 6. HTTP Server Design + +### 6.1 Technology + +Raw `node:http.createServer()` — no framework, same as design-deck and +plannotator. Route set is small (~10 endpoints). Assets loaded into memory at +module init time. + +### 6.2 Routes + +| Method | Path | Purpose | +| ------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| GET | `/` | Serve HTML page (with session token validation) | +| GET | `/static/*` | Bundled static assets (CSS, JS) with MIME type detection — maps to `web/` directory. New files are automatically servable without adding routes. | +| GET | `/events` | SSE stream | +| GET | `/health` | Health check | +| POST | `/api/answer` | Submit question answers | +| POST | `/api/review` | Submit spec review decision | +| POST | `/api/heartbeat` | Browser liveness | +| POST | `/api/cancel` | Cancel pipeline | + +### 6.3 SSE state replay on connect + +When a browser connects (or reconnects) to `/events`, the server immediately +sends the current state as a burst of events: + +``` +event: phase +data: {"phase":"executing"} + +event: stories +data: {"stories":[{"storyId":"s1","status":"done"},{"storyId":"s2","status":"executing"}]} + +event: subagent +data: {"role":"executor","storyId":"s2","step":1,"totalSteps":2} +``` + +This eliminates the need for a separate "get current state" API endpoint and +handles browser refreshes gracefully. + +### 6.4 Pending input tracking + +The server maintains a map of pending input requests: + +```typescript +const pendingInputs = new Map< + string, + { + type: "review" | "ask"; + resolve: (result: any) => void; + payload: any; // questions or stories — resent on SSE reconnect + } +>(); +``` + +When a browser (re)connects via SSE, any pending input requests are re-pushed +so the browser can render the current question/review form immediately. + +### 6.5 Heartbeat — observability only, no auto-resolution + +Browser sends `POST /api/heartbeat` every 5 seconds. The server tracks the +last heartbeat timestamp per session for observability (e.g., logging "no +browser connected for 2 minutes" as a warning). + +**The heartbeat has NO effect on pipeline behavior.** Specifically: + +- No auto-resolution of pending questions or spec reviews on timeout. +- No auto-cancellation of the pipeline. +- No fallback to default answers. + +The pipeline **waits indefinitely** for user input. If the user closes the +browser and never reconnects, the pipeline blocks until the pi process is +killed (Ctrl+C). This is by design: user input is a deliberate gate, and +auto-resolving would silently execute work the user hasn't reviewed. + +The heartbeat exists solely so the server can log stale-connection warnings, +which helps diagnose "why is the pipeline stuck?" scenarios. + +--- + +## 7. Browser UI Design + +### 7.1 Single-page application + +One HTML page, no framework (vanilla JS). Three logical sections: + +1. **Header** — Epic title, current phase badge, elapsed time +2. **Main dashboard** — Story cards with status indicators, active subagent + progress, log tail +3. **Interaction panel** — Slides in when user input is needed (question form + or spec review checklist), slides out when submitted + +### 7.2 State management + +The browser maintains a single state object, updated by SSE events: + +```javascript +const state = { + phase: null, + stories: [], + subagent: null, + logs: [], + notifications: [], + pendingInput: null, // { type, requestId, payload } +}; +``` + +Each SSE event updates the relevant field and triggers a re-render of the +affected DOM section. No virtual DOM — direct DOM manipulation (the update +frequency is low enough that this is fine). + +### 7.3 Question form rendering + +When an `ask` SSE event arrives: + +- Single question: radio buttons for options, optional text input for notes +- Multiple questions: tab bar with one panel per question, each with + radio/checkbox options, submit button at the bottom +- `recommended` option gets a "(Recommended)" badge +- `multi: true` questions render checkboxes instead of radio buttons +- No cancel button. Process lifecycle (abort/cancel) is managed through + the terminal, not the web form. + +### 7.4 Spec review rendering + +When a `review` SSE event arrives: + +- Checklist of stories with title and summary +- Each story has a checkbox (checked = approved, unchecked = skipped) +- "Approve All" button, "Submit" button +- Stories are pre-checked (default: all approved) + +### 7.5 Notification rendering + +Toast messages that auto-dismiss after 5 seconds, stacked in bottom-right. +Also logged to a collapsible notification history. + +--- + +## 8. Config Menu and Commands + +### 8.1 `/koan config` — kept as TUI + +The `/koan config` command stays as a TUI command. `ui/config/menu.ts` and +`ui/config/model-selection.ts` are **not deleted** — they remain in +`src/planner/ui/config/` and continue to use `ExtensionCommandContext` and +`pi-tui` imports. The config menu is orthogonal to the pipeline and will be +migrated to web in a dedicated planning session later. + +`extensions/koan.ts` keeps its import of `openKoanConfig` from +`../src/planner/ui/config/menu.js` unchanged. + +### 8.2 Commands removed + +- `/koan-execute` — placeholder ("not yet implemented"), removed entirely. +- `/koan-status` — placeholder ("Status: idle"), removed entirely. + +These have no users. Their functionality (status, manual execution) will be +part of the web UI when designed. + +### 8.3 `/koan` base command — minimal + +The `/koan` base command stays for bare-minimal configuration routing (just +`/koan config`). No complex UI. Its `extCtx.ui.notify()` calls for usage +help and unknown subcommand errors remain as-is (pi TUI notifications, not +web). To be refined in a dedicated planning session later. + +--- + +## 9. Error Handling — Fail Fast, Kill Everything + +The pipeline must fail fast with clear, actionable errors. Getting stuck in +an unknown state is worse than crashing — a crash with a good error message +is debuggable, a silent hang is not. + +### 9.1 Error propagation principles + +1. **Every error includes location and context.** Errors thrown from the web + server, IPC responder, or driver must include: the function name, what was + being attempted, and relevant IDs (storyId, requestId, subagentDir). +2. **Abort signals reject with `AbortError`.** When an AbortSignal fires + during a blocking `requestReview()` or `requestAnswer()`, the Promise + rejects with an error that names the pending request and why it was + aborted (e.g., "subagent exited while question q1 was pending"). +3. **POST to stale/unknown requestId returns 409 Conflict.** If a browser + submits an answer after the request was already cancelled or resolved, + the server responds with 409 and the browser shows a clear message. +4. **SSE push errors are logged and swallowed.** If a push fails (broken + connection), the server logs it but doesn't crash — the browser will + reconnect via SSE auto-reconnect. +5. **IPC responder errors abort the workflow.** If the responder encounters + an unrecoverable error (e.g., can't write IPC file, can't read IPC file + after repeated attempts), it throws — which propagates up through the + driver and aborts the pipeline with a clear error. + +### 9.2 Resource cleanup on failure + +When any error occurs, resources are cleaned up immediately — no graceful +shutdown, no waiting for in-progress work to complete. + +**`server.close()` tears down everything:** + +- Kills the HTTP server (stops accepting connections) +- Terminates all SSE connections (closes response streams) +- Clears the observation polling timer (if `trackSubagent` is active) +- Rejects any pending `requestReview`/`requestAnswer` Promises with an error +- Clears the `pendingInputs` map + +**Cleanup ownership — one `try/finally` in `koan_plan.execute()`:** + +```typescript +const server = await startWebServer(); +try { + await openBrowser(pi, server.url); + await exportConversation(sessionManager, epicDir); + const result = await runPipeline(epicDir, cwd, extensionPath, log, server); + return { + content: [ + { type: "text", text: `Dashboard: ${server.url}\n\n${result.summary}` }, + ], + }; +} finally { + server.close(); +} +``` + +This covers every failure mode: + +- `openBrowser()` throws → `finally` closes server +- `exportConversation()` throws → `finally` closes server +- `runPipeline()` throws → `finally` closes server +- `runPipeline()` returns normally → `finally` closes server +- Parent process killed (SIGTERM) → Node runs finalizers, `finally` closes server +- Parent process killed (SIGKILL/OOM) → OS releases the random port + +`runPipeline()` has **no** `try/finally` for the server — it doesn't own it. +It only orchestrates the pipeline phases. + +### 9.3 Abort-initiated cleanup of pending browser forms + +When an `AbortSignal` fires during `requestAnswer()` (subagent died while +user was deciding), the **web server implementation** is responsible for the +full cleanup sequence: + +1. Reject the Promise with `AbortError` (includes requestId + question context) +2. Remove the entry from `pendingInputs` +3. Push an `ask-cancelled` SSE event to the browser (clears the stale form) + +The caller (`ipc-responder.ts`) catches the `AbortError` and writes +`createCancelledResponse()` to the IPC file. + +This is a **fix** for the existing TUI bug where the ask widget stays +rendered after the subagent exits and the user's answer is silently discarded. +In the web version, the browser receives `ask-cancelled` and shows a +dismissible notice ("This question was cancelled — the subagent has exited"). + +### 9.4 Headless mode (`!ctx.hasUI`) + +When running without UI (headless/RPC mode), the web server is not started. +`runPipeline` receives `null` instead of a `WebServerHandle`. Spec review +auto-approves all stories, questions auto-cancel (same as current behavior +when `ui` is null). + +### 9.5 Browser closed mid-pipeline + +The pipeline **waits indefinitely** for user input. No auto-resolution (§6.5). +If the user closes the browser and never reconnects, the pipeline blocks until +the pi process is killed (Ctrl+C). User input is a deliberate gate. + +### 9.6 Server startup failure + +If `startWebServer()` fails (port binding error, etc.), the error propagates +up through `koan_plan.execute()` and the tool returns an error result to the +LLM. The pipeline does not start. The error message includes the underlying +OS error. + +### 9.7 Pipeline cancel (`POST /api/cancel`) + +`POST /api/cancel` proactively kills all running subagent processes using +the same teardown function as the termination/error exit handler. Cancel is +treated identically to a hard crash, except no error message is rendered. + +Sequence: + +1. Receive `POST /api/cancel { token }` +2. Call teardown function (same as error/SIGTERM handler): + - Reject all pending Promises in `pendingInputs` and `pendingReviews` + - Kill all child processes (`subagent.ts` must expose process handles) + - Push `pipeline-end` SSE event: `{ success: false, summary: "Cancelled by user" }` +3. Respond `{ ok: true }` to the browser +4. Close server (via the outer `try/finally` in `koan_plan.execute`) + +The browser receives `pipeline-end` and renders the cancelled state (no +error banner — just pipeline stopped). This endpoint is distinct from the +question-form cancel, which does not exist (§4.4 note 3, §7.3). + +--- + +## 10. Implementation Sequence + +The rewrite touches these files in dependency order: + +1. **Create `src/planner/web/server-types.ts`** — Define `WebServerHandle` + interface (§4.1), `AnswerResult`, `ReviewResult`, `ReviewStory`. Relocate + from `ui/ask/ask-logic.ts`: `AskOption`, `AskQuestion`, `AskSelection`, + `OTHER_OPTION`, `appendRecommendedTagToOptionLabels`, + `buildSingleSelectionResult`, `buildMultiSelectionResult` (model code — + no TUI imports). Define `SubagentEvent` type. Re-export `LogLine` from + `../lib/audit.js`, `EpicPhase` and `StoryStatus` from `../types.js`. +2. **Create `src/planner/web/server.ts`** — HTTP server with SSE, routes, + session management, observation polling (`trackSubagent`/`clearSubagent` + internals), abort-initiated cleanup (§9.3), state buffering for SSE replay + (§6.3). Exports `startWebServer()` returning `Promise<WebServerHandle>`. + Also exports `openBrowser(pi, url)` helper (§12). +3. **Create browser assets** — `html/index.html`, `css/styles.css`, + `js/app.js` (SSE connection, state management, `console.*` logging for all + events), `js/render.js` (DOM rendering), `js/forms.js` (question forms, + spec review, "Other" option text input). +4. **Rewrite `lib/ipc-responder.ts`** — Replace TUI ask calls with + `webServer.requestAnswer(questions, signal)`. Remove imports from + `../ui/ask/`. Import types from `../web/server-types.js`. Collapse the + single-vs-multi question branching into one `requestAnswer` call. Handle + `AbortError` rejection by writing `createCancelledResponse()` to IPC. +5. **Rewrite `subagent.ts`** — Change `SpawnOptions.ui` and + `SpawnSubagentOpts.ui` from `ExtensionUIContext` to `WebServerHandle`. + Update `runIpcResponder()` call to pass web server handle. Remove + `ExtensionUIContext` import. +6. **Rewrite `driver.ts`** — Rename `runEpicPipeline` → `runPipeline`. + Delete `startActivePolling` function. Replace all `widget.*` and `ui.*` + calls with `webServer?.` calls (§4.2). Change parameter type from + `ui: ExtensionUIContext | null` to `webServer: WebServerHandle | null`. + Change 9 spawn call sites from `ui: ui ?? undefined` to + `webServer: webServer ?? undefined`. Remove `EpicWidgetController` and + `reviewStorySketches` imports. Inline the story-title-reading logic from + `spec-review.ts` for constructing `ReviewStory[]`. +7. **Modify `extensions/koan.ts`** — In `koan_plan.execute()`: start web + server, wrap in `try/finally` (§9.2), open browser (§12), pass handle to + `runPipeline`, include `server.url` in tool result text. Remove + `/koan-execute` and `/koan-status` commands. Keep `/koan config` import. +8. **Delete TUI rendering files** — Remove `ui/epic-widget.ts`, + `ui/spec-review.ts`, `ui/ask/ask-inline-ui.ts`, `ui/ask/ask-tabs-ui.ts`, + `ui/ask/ask-inline-note.ts`, `ui/ask/ask-logic.ts` (model code already + relocated in step 1). Keep `ui/config/` (menu.ts + model-selection.ts). +9. **Clean up imports** — Remove `pi-tui` and `ExtensionUIContext` imports + from driver.ts, ipc-responder.ts, subagent.ts. `ui/config/` retains its + `pi-tui` and `ExtensionCommandContext` imports (unchanged). + +--- + +## 11. What This Plan Does NOT Cover + +- **Visual design / CSS polish** — The first pass focuses on functionality + over aesthetics. Styling can be iterated. +- **Config menu in web** — Stays as TUI command. To be migrated in a + dedicated planning session. +- **Multiple browser tabs** — Single active session; additional tabs get a + "session already active" message or share the same SSE stream. +- **HTTPS** — Localhost-only, not needed. +- **Persistent state across browser refreshes** — SSE replay handles this; + no localStorage or cookies needed. +- **Tests** — Explicitly excluded per scope. +- **Heartbeat-based auto-resolution** — The pipeline waits indefinitely for + user input. No timeout-based auto-approve or auto-cancel. The heartbeat + (§6.5) is observability-only — it logs warnings but never resolves pending + inputs or cancels the pipeline. +- **Subagent process kill on pipeline abort** — Currently `spawnSubagent()` + doesn't expose `proc.kill()`. If the pipeline aborts, in-flight subagent + processes run to completion (or until the parent process exits and the OS + reaps orphans). Adding explicit child-process kill is a future improvement. + +--- + +## 12. Cross-Platform Browser Opening and URL Communication + +### 12.1 URL construction + +The URL is deterministic immediately after `startWebServer()` resolves: + +```typescript +const server = await startWebServer(); +// server.url === "http://127.0.0.1:54321/?session=abc-def-123" +// server.port === 54321 +``` + +The port is OS-assigned (`server.listen(0, "127.0.0.1")` — Node picks a +free port). The session token is a `crypto.randomUUID()`. The URL is a +readonly property on `WebServerHandle`. + +### 12.2 Opening the browser + +Following `pi-design-deck/index.ts` (lines 15–38): + +```typescript +async function openBrowser(pi: ExtensionAPI, url: string): Promise<void> { + const platform = process.platform; + try { + if (platform === "darwin") { + await pi.exec("open", [url]); + } else if (platform === "win32") { + await pi.exec("cmd", ["/c", "start", "", url]); + } else { + await pi.exec("xdg-open", [url]); + } + } catch { + // Non-fatal — user can open the URL manually from the tool result. + } +} +``` + +Uses `pi.exec()` (not `node:child_process`) to respect pi's execution +environment. Failure to open the browser is silently caught — never fatal. + +### 12.3 URL in tool result + +The URL is **always** included in the `koan_plan` tool's return text so the +user can access the dashboard even if browser auto-open fails: + +```typescript +// In koan_plan.execute(): +const server = await startWebServer(); +try { + await openBrowser(pi, server.url); + // ... + const result = await runPipeline(..., server); + return { + content: [{ type: "text", text: `Dashboard: ${server.url}\n\n${result.summary}` }], + }; +} finally { + server.close(); +} +``` + +The LLM sees the URL in the tool result and can surface it to the user if +needed. This follows the `pi-design-deck` pattern where the URL appears in +`details.url` on every tool result. diff --git a/plans/2026-03-14-intake-ui.md b/plans/2026-03-14-intake-ui.md new file mode 100644 index 0000000..c070517 --- /dev/null +++ b/plans/2026-03-14-intake-ui.md @@ -0,0 +1,1119 @@ +# Koan Intake Dashboard: UI Implementation Plan + +> **Date:** 2026-03-14 +> **Scope:** Browser UI for the intake phase — from koan_plan invocation +> through project spec consolidation. Covers HTML/CSS/JS, SSE events, +> POST endpoints, and backend changes to support the UI. +> **Parent plan:** `2026-03-13-web-ui.md` (architecture, server lifecycle, +> resource cleanup). This plan specifies the _visual layer_ and +> _intake-specific data flow_. + +--- + +## 1. Design Principles (derived from user preferences) + +These principles were extracted from the design deck selections and +explicit feedback. They govern all UI decisions in this plan. + +### 1.1 Flat over nested + +Hierarchy is expressed as **data properties**, not visual containment. +Every subagent is a row in the same flat table — intake, auth-patterns, +api-structure, ui-components, db-schema are all "subagents". The parent +relationship is a column value (`parent: intake`), not a visual nesting +(no cards-in-cards, no tree indentation, no accordion nesting). + +This mirrors a database/spreadsheet mental model: normalize the data +model, denormalize the display. + +### 1.2 Everything visible, nothing behind interaction + +All questions visible at once (not tabs). All scout cards visible (not +accordions). Agent table always visible (not collapsible to a rail). +The user should never need to click/hover to discover what the system +is doing. Progressive disclosure is acceptable only for _supplementary_ +detail (expanding the activity log), never for _primary_ information. + +### 1.3 Structural separation of concerns + +Two architecturally independent layers: + +1. **Phase content area** — changes per intake step (loading → context + analysis → scout exploration → questions → consolidation). This is + the "story" of what's happening. +2. **Subagent table** — persistent flat table at the bottom. Shows ALL + active/completed subagents regardless of phase. This is the "system + monitor" — always the same widget, only the rows change. + +These layers interact (scout completion updates both the phase content +and the table) but are rendered independently. The phase content never +needs to "know about" the table, and the table never needs to "know +about" the phase content. + +### 1.4 Quantitative observability + +The user wants **numbers**: token counts (sent/received per agent), +event counts, elapsed time. Not just "something is happening" — but +"how much is it costing and how fast is it going." Token data requires +a backend change (§5). + +### 1.5 Simplicity over cleverness + +The simplest option that shows the information wins. Vertical card +stacks over activity streams. Stacked question cards over conversational +flows. Pill strips over breadcrumb steppers. No clever layouts that +sacrifice scanability for aesthetics. + +--- + +## 2. Page Structure + +The page is a single HTML document served from memory. No external +assets, no bundler, no framework. Vanilla JS + CSS custom properties. +All CSS and JS are inlined (concatenated at serve time, same as +design-deck). + +### 2.1 Layout skeleton + +``` +┌─────────────────────────────────────────────────────────┐ +│ HEADER BAR (fixed top) │ +│ [koan logo] [pill strip: ✓context ②explore ③ask ④spec] │ +│ [timer] │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ PHASE CONTENT (flex: 1, scrollable) │ +│ content changes per intake step │ +│ max-width: 720px, centered │ +│ │ +├─────────────────────────────────────────────────────────┤ +│ SUBAGENT TABLE (sticky bottom, always visible) │ +│ flat table: status | agent | model | parent | ↑sent │ +│ ↓recv | current action │ +│──────────────────────────────────────────────────────────│ +│ ACTIVITY LOG (collapsible, below table) │ +│ interleaved tool calls from all agents │ +│ last 5-8 entries, auto-scrolls │ +└─────────────────────────────────────────────────────────┘ +``` + +### 2.2 HTML structure + +```html +<body> + <div class="app"> + <!-- Header --> + <header class="header"> + <div class="header-left"> + <span class="logo">koan</span> + <div class="pill-strip"> + <span class="pill done">✓ context</span> + <span class="pill active">② explore</span> + <span class="pill pending">③ questions</span> + <span class="pill pending">④ spec</span> + </div> + </div> + <span class="timer">1m 12s</span> + </header> + + <!-- Phase content — swapped per step --> + <main class="phase-content"> + <!-- Rendered by JS based on current phase --> + </main> + + <!-- Subagent monitor — always present --> + <footer class="monitor"> + <div class="agent-table-header"> + <span class="monitor-label">Subagents</span> + <div class="agent-badges"> + <span class="badge done">1</span> + <span class="badge active">3</span> + </div> + <span class="token-totals">↑73.5k ↓16.2k</span> + </div> + <table class="agent-table"> + <thead> + ... + </thead> + <tbody> + <!-- rows from SSE --> + </tbody> + </table> + <!-- No separate activity log — recent actions appear in the "doing" column (§6.5) --> + </footer> + </div> +</body> +``` + +### 2.3 CSS architecture + +CSS custom properties with dark theme. Component-scoped classes (not +utility-first). Following design-deck's pattern: multiple `.css` files +concatenated at serve time. + +```css +:root { + /* Background layers */ + --bg: #0d1117; + --bg-surface: #161b22; + --bg-elevated: #0c0f14; + + /* Borders */ + --border: #21262d; + --border-light: #161b22; + + /* Text hierarchy */ + --text: #c9d1d9; + --text-strong: #e6edf3; + --text-muted: #8b949e; + --text-dim: #484f58; + --text-ghost: #30363d; + + /* Status colors */ + --green: #7ee787; + --green-bg: rgba(35, 134, 54, 0.06); + --green-border: #238636; + --blue: #58a6ff; + --blue-bg: rgba(31, 111, 235, 0.06); + --blue-border: #1f6feb; + --purple: #d2a8ff; + --orange: #ffa657; + --red: #f85149; + + /* Typography */ + --font-mono: "SF Mono", "JetBrains Mono", "Cascadia Code", monospace; + --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; + --font-size-xs: 11px; + --font-size-sm: 12px; + --font-size-md: 13px; + --font-size-lg: 14px; + + /* Spacing */ + --gap-xs: 4px; + --gap-sm: 8px; + --gap-md: 12px; + --gap-lg: 16px; + --gap-xl: 20px; +} +``` + +Monospace (`--font-mono`) for: agent names, model names, file paths, +token counts, timestamps, tool names, the pill strip, all technical +data. + +Sans-serif (`--font-sans`) for: question text, phase descriptions, +scout role descriptions, button labels. + +--- + +## 3. Phase Content Screens + +The `<main class="phase-content">` area renders one of 5 screens based +on the current intake state. Transitions use a 250ms opacity crossfade. + +### 3.1 Screen: Loading + +**Shown:** From browser open until first `subagent` SSE event arrives. +**Duration:** 1–8 seconds. + +``` + ┌──────────────────────────┐ + │ │ + │ ○ Initializing... │ + │ │ + │ ┌────────────────────┐ │ + │ │ YOUR REQUEST │ │ + │ │ "Design the intake │ │ + │ │ dashboard UX..." │ │ + │ └────────────────────┘ │ + │ │ + └──────────────────────────┘ +``` + +- Centered vertically in the phase content area +- Spinner (CSS-only rotating border) +- "Initializing..." in `--text` color +- Below: a card showing the user's conversation topic + - Label: "YOUR REQUEST" in `--text-dim`, uppercase, 10px, letter-spaced + - Content: first ~200 chars of the last user message from + `conversation.jsonl`, in `--text-muted`, italic + - Card: `--bg-surface` background, `--border` border, 6px radius + +**Topic extraction:** The server extracts the topic from +`conversation.jsonl` during `startWebServer()`. It parses the file +looking for the last entry with `role: "user"` content, takes the first +200 characters, and injects it into the HTML via the `__DATA__` +placeholder. If extraction fails, the topic card is hidden — just the +spinner and "Initializing..." are shown. + +**Data available:** None from SSE yet. The topic comes from the HTML +inline data. + +**Transition out:** First `subagent` SSE event with `stepName` present +→ crossfade to Context Analysis. + +### 3.2 Screen: Context Analysis + +**Shown:** While the intake subagent is on step 1/3 (Context +Extraction). The strong model is reading `conversation.jsonl` and +writing `context.md`. +**Duration:** 15–45 seconds. + +``` + Reading your conversation to understand the task... + + ┌ Recent Activity ─────────────────────────┐ + │ read conversation.jsonl · 847L/34.2k │ + │ write context.md · 67L/2.4k │ + └──────────────────────────────────────────┘ +``` + +- Status message: "Reading your conversation to understand the task..." + in `--text-muted`, `--font-sans`, 13px +- Activity feed: bordered card showing the last 3–4 tool calls from + the `logs` SSE event. Same format as the activity log in the monitor + but rendered inline for this phase (since the monitor may have few + entries at this point) +- No interactivity + +**Data source:** `subagent` SSE event (step=1), `logs` SSE event. + +**Transition out:** `subagent` SSE event with `step: 2` → crossfade to +Scout Exploration. + +### 3.3 Screen: Scout Exploration + +**Shown:** While scouts are running (intake step 2/3, "Codebase +Scouting"). 1–5 parallel scouts explore the codebase. +**Duration:** 30 seconds – 3 minutes. + +``` + Exploring your codebase with 4 scouts... + + ┌ ✓ auth-patterns ── security auditor ─────┐ + │ Found next-auth v4.24 with JWT strategy. │ + │ Session middleware in src/lib/session.ts. │ + └──────────────────────────────────────────┘ + ┌ ● api-structure ── API analyst ──────────┐ + │ reading src/app/api/routes.ts · 3s ago │ + └──────────────────────────────────────────┘ + ┌ ● ui-components ── UI patterns analyst ──┐ + │ grep 'useState' src/components/ · 1s │ + └──────────────────────────────────────────┘ + ┌ ● db-schema ── database analyst ─────────┐ + │ read src/lib/db/schema.ts · <1s ago │ + └──────────────────────────────────────────┘ +``` + +Each scout is a **vertical card** (stacked, full width up to max-width): + +- **Header row:** status indicator + scout `id` (bold) + scout `role` + (muted, right-aligned) + - Running: `●` blue dot + name in `--text` + - Complete: `✓` green check + name in `--green` + - Failed: `✗` red cross + name in `--red` +- **Body:** + - Running: current action from `lastAction` field, in `--text-dim`, + with relative timestamp ("3s ago") + - Complete: finding summary from `koan_complete_step` detail, in + `--text-muted`. This is the scout's main output — what it found. + - Failed: error message in `--red` +- **Card styling:** + - Running: `--border` border, left border accent in the scout's + assigned color (blue, purple, orange, etc.) + - Complete: `--green-border` border, `--green-bg` background + - Failed: red border, red tinted background +- Cards are 6px border-radius, 12px vertical padding, 16px horizontal + +**Scout colors:** Each scout gets an assigned color from a fixed +palette: `--blue`, `--purple`, `--orange`, `#e3b341` (yellow), +`#f778ba` (pink). Assigned in order of appearance. Used for the left +border accent on running cards and the agent name color in the activity +log. + +**"Context so far" section:** Below the scout cards, a section labeled +"Context so far" (uppercase, `--text-dim`) shows completed scout +findings as bullet points. This accumulates as scouts complete, +building a visible picture of what the system has learned. + +**Data source:** `scouts` SSE event (new, §4.1). Each event carries +the full array of all scout states. + +**Transition out:** `ask` SSE event arrives → crossfade to Questions. +If no questions needed (step 3 completes without an ask): crossfade to +Consolidation. + +### 3.4 Screen: Questions (Elicitation) + +**Shown:** When the `ask` SSE event arrives with the intake model's +questions. +**Duration:** 30 seconds – 5 minutes (user-paced). + +This is the only interactive screen. All questions are shown at once +on a scrollable page. + +``` + A few questions to shape the plan 0 of 3 answered + + ┌─ 1/3 · scope ────────────────────────────────────────┐ + │ │ + │ Should the web dashboard replace the TUI completely? │ + │ │ + │ Scout found 8 files with direct pi-tui imports. The │ + │ config menu (ui/config/) is separate from pipeline. │ + │ │ + │ ○ Replace completely — delete all TUI code │ + │ ◉ Replace for pipeline, keep TUI for config │ + │ recommended │ + │ ○ Run both — user picks at runtime │ + │ ○ Other... [ ] │ + │ │ + └────────────────────────────────────────────────────────┘ + + ┌─ 2/3 · error-handling ───────────────────────────────┐ + │ ... │ + └────────────────────────────────────────────────────────┘ + + ┌─ 3/3 · persistence ─────────────────────────────────┐ + │ ... │ + └────────────────────────────────────────────────────────┘ + + [Accept All Defaults] [Submit Answers] +``` + +#### Question card structure + +Each question renders as a card with: + +- **Card header:** question number + total, question `id` as monospace + label. Example: `1/3 · scope` +- **Question text:** `--font-sans`, `--text-strong`, 14px, font-weight 500. This is the primary text — it gets visual weight. +- **Context paragraph:** `--font-sans`, `--text-muted`, 12px. The + question text itself contains the context (the intake model writes + questions that reference scout findings). There's no separate + "context" field — the full question string is rendered as-is. + Newlines in the question text become `<br>` or separate `<p>` tags. +- **Options list:** vertical stack of option labels. + +#### Single-select options (multi: false) + +Each option is a `<label>` wrapping a hidden `<input type="radio">` + +visual radio dot + label text: + +```html +<label class="option"> + <input type="radio" name="q-scope" value="0" hidden /> + <span class="radio-dot"></span> + <span class="option-text">Replace for pipeline, keep TUI for config</span> + <span class="recommended-badge">recommended</span> +</label> +``` + +- Unselected: `--border` border, `--bg` background, radio dot is + empty circle in `--text-ghost` +- Selected: `--blue-border` border, `--blue-bg` background, radio dot + filled with `--blue` +- Recommended badge: `recommended` in `--blue`, `--font-mono`, 11px, + shown next to the recommended option's text + +#### Multi-select options (multi: true) + +Same structure but with checkboxes: + +```html +<label class="option"> + <input type="checkbox" name="q-features" value="0" hidden /> + <span class="checkbox-dot"></span> + <span class="option-text">Real-time scout progress</span> +</label> +``` + +- Checkbox: square with rounded corners (3px radius) instead of circle +- Checked: `✓` inside, same `--blue` color scheme +- Card header shows "select all that apply" in `--blue`, `--font-mono` +- Counter below options: "3 selected" in `--text-dim` + +#### "Other" option + +Always the last option. When selected, a text input appears below: + +```html +<label class="option option-other"> + <input type="radio" name="q-scope" value="other" hidden /> + <span class="radio-dot"></span> + <span class="option-text other-text">Other...</span> +</label> +<input + type="text" + class="other-input" + placeholder="Type your answer..." + style="display: none" +/> +``` + +- Dashed border instead of solid (visual hint: "this is different") +- Label text in `--text-dim` (lower visual weight) +- When selected: text input slides open below (150ms height transition) +- Text input: `--bg` background, `--border` border, `--font-sans`, + 13px, full width, 8px padding + +#### Form actions + +Two buttons below all question cards: + +- **Accept All Defaults** (secondary): outlined button, `--border` + border, `--text-muted` text. Selects the `recommended` option for + every question (or first option if no recommended), submits + immediately. For users who trust the model. +- **Submit Answers** (primary): solid `--green-border` background, + white text. Disabled (opacity 0.5) until every question has at least + one selection. Shows "N of M answered" as helper text when disabled. + +Clicking Submit sends `POST /api/answer` with the full answer payload. + +#### Collapsed scout summary + +At the top of the questions screen, a collapsible summary of scout +findings: + +``` + ▸ 4 scouts completed [expand] +``` + +Clicking expands to show the findings from §3.3's "Context so far" +section. This preserves context while giving the question form +maximum vertical space. + +**Data source:** `ask` SSE event with `{ requestId, questions }`. + +**Transition out:** User clicks Submit/Accept Defaults → POST resolves +→ crossfade to Consolidation. + +### 3.5 Screen: Consolidation + +**Shown:** After questions are answered, while the intake model writes +`decisions.md`. +**Duration:** 5–15 seconds. + +``` + Writing project specification... + + ┌ Summary ──────────────────────────────┐ + │ ✓ Context extracted from conversation │ + │ ✓ 4 scouts explored the codebase │ + │ ✓ 3 questions answered │ + │ ◌ Writing decisions.md... │ + └────────────────────────────────────────┘ +``` + +- Checklist of completed inputs (context, scouts, questions) +- Current action: "Writing decisions.md..." with spinner + +**Data source:** `subagent` SSE event (still step 3/3), `logs` SSE +event. + +**Transition out:** `phase` SSE event with `phase: "decomposition"` → +the intake is done. The page transitions to the decomposition phase +(out of scope for this plan — the phase content area shows a +"Moving to decomposition..." message). + +### 3.6 Screen: Intake skipped (no questions) + +If the intake model decides no questions are needed (conversation + +scout findings are sufficient), step 3 completes without an `ask` SSE +event. The questions screen is never shown. The pill strip shows +"③ questions" transitioning directly from pending to done with a +"(none needed)" annotation. + +--- + +## 4. SSE Events for Intake + +### 4.1 New: `scouts` event + +The existing plan (§3.1) defines events for single subagent tracking +and ask questions. Intake requires a new `scouts` event type for +parallel scout observation. + +```typescript +interface ScoutsEvent { + scouts: Array<{ + id: string; // ScoutTask.id, e.g. "auth-patterns" + role: string; // ScoutTask.role, e.g. "security auditor" + status: "running" | "completed" | "failed"; + lastAction: string | null; // from Projection.lastAction + eventCount: number; // from Projection.eventCount + model: string | null; // from Projection.model + completionSummary: string | null; // from {subagentDir}/findings.md + // Token fields (added via §5): + tokensSent: number; // cumulative input tokens + tokensReceived: number; // cumulative output tokens + }>; +} +``` + +**When pushed:** Every 2 seconds while any scout is active. The web +server polls each registered scout directory's `state.json` and +constructs the event. + +**Lifecycle:** + +1. IPC responder spawns each scout → calls `webServer.registerAgent({ role: "scout", ... })` + for each scout individually (matching the general agent registration pattern) +2. Web server starts polling each registered scout directory at 2-second intervals +3. Each tick reads `readProjection(dir)` for each scout +4. When all scouts are terminal (completed/failed), one final `scouts` + event is pushed and polling stops +5. `completeAgent(id)` called for each scout on exit — no separate `clearScouts()` needed + +**Completion summary:** When a scout's `Projection.status` becomes +`"completed"`, the web server reads `{subagentDir}/findings.md` written +by the scout. The driver validates this file exists after scout exit. +`completionSummary` is null until the file is present and readable. + +### 4.2 New: `agents` event + +The subagent table requires a unified view of ALL agents. This is +distinct from `subagent` (single tracked agent) and `scouts` (parallel +scouts). The `agents` event provides the flat table data. + +```typescript +interface AgentsEvent { + agents: Array<{ + id: string; // unique: subagent dir basename + name: string; // human label: "intake", "auth-patterns", etc. + role: string; // "intake" | "scout" | "decomposer" | etc. + model: string | null; // from Projection.model + parent: string | null; // parent agent's name, or null for top-level + status: "running" | "completed" | "failed"; + tokensSent: number; // cumulative input tokens + tokensReceived: number; // cumulative output tokens + recentActions: string[]; // last 1-5 log summaries (see §4.3) + subPhase: string | null; // intake sub-phase: "context"|"explore"|"questions"|"spec"; null for non-intake agents + }>; +} +``` + +**When pushed:** Every 2 seconds (same tick as `subagent`/`scouts` +polling). Aggregates ALL tracked agent directories into a single flat +array. + +**`subPhase` derivation:** The server derives `subPhase` from the intake +agent's `Projection.step`: + +- Step 1 → `"context"` +- Step 2 → `"explore"` +- Step 3, no answered ask → `"questions"` +- Step 3, ask answered → `"spec"` + For all other agents, `subPhase` is `null`. + +**Agent registration API on WebServerHandle:** + +```typescript +interface WebServerHandle { + // ... existing methods from web-ui plan ... + + // Agent registration for the flat table. + // Called by the driver/IPC responder when spawning any subagent. + registerAgent(info: { + id: string; // subagent dir basename + name: string; // display name + dir: string; // subagent directory path (for polling) + role: string; // "intake" | "scout" | etc. + model: string | null; + parent: string | null; // parent agent's name + }): void; + + // Called when an agent completes/exits. + // Does NOT remove from the table — just stops polling. + // The agent row stays visible with its final status. + completeAgent(id: string): void; + + // NOTE: registerScouts() / clearScouts() do NOT exist. + // Each scout is registered individually via registerAgent({ role: "scout", ... }). +} +``` + +**Implementation:** The web server maintains a `Map<string, AgentInfo>` +of all registered agents. The 2-second polling tick reads `state.json` +from each _running_ agent's directory, updates the entry, and pushes +a single `agents` SSE event with the full map serialized as an array. +Completed agents keep their last-known state (no more polling). + +**Relationship to `subagent` / `scouts` events:** These three event +types are intentionally separate — independent subsystems with distinct +purposes. They must NOT share an event type: + +- `agents` — universal metadata for ALL agents (model, tokens, recent actions); + drives the flat subagent table +- `subagent` — step progress for the single tracked agent; drives phase content +- `scouts` — scout-specific status and findings; drives scout cards in phase content +- `ask` — question interaction; independent of the above + +`registerAgent()` is called for EVERY subagent spawn (intake, scouts, +decomposer, planner, executor, orchestrator). `trackSubagent()` is kept +for pushing `subagent` events. Scouts register via `registerAgent()` — +no separate `registerScouts()` / `clearScouts()` API (see §4.1). + +### 4.3 `logs` event — per-agent recent actions + +The `logs` SSE event from the parent plan carries `LogLine[]` for the +tracked subagent. This is unchanged. + +For the agent table's `doing` column, each agent's recent actions come +from its own `events.jsonl` (polled every 2 seconds). The `recentActions` +field in the `agents` event (see §4.2) carries the last 1–5 log summaries +per agent as a plain `string[]`. The `agent`, `agentColor`, and `timestamp` +extensions described in earlier drafts are **removed** — logs are per-agent +in the table, not interleaved in a separate panel. + +> **Performance note (TBD — not blocking v1):** Reading all agent +> `events.jsonl` files every 2 seconds may become costly with many +> agents. Possible mitigations: read only the last N bytes of each file, +> or track a byte offset per agent for incremental reads. This is +> deferred; the polling approach is acceptable for v1. + +--- + +## 5. Token Usage: Backend Changes + +### 5.1 The gap + +The user wants per-agent token counts (↑ sent / ↓ received). Pi's +`AssistantMessage` has `usage: { input, output, cacheRead, cacheWrite, +totalTokens, cost }` on every completed assistant turn. But koan's +`EventLog` only hooks `tool_result` — it doesn't capture message-level +usage data. + +### 5.2 New audit event: `usage` + +Add a new `AuditEvent` variant: + +```typescript +interface UsageEvent extends EventBase { + kind: "usage"; + input: number; // input tokens this turn + output: number; // output tokens this turn + cacheRead: number; // cache read tokens + cacheWrite: number; // cache write tokens +} +``` + +### 5.3 New hook in `koan.ts` + +In the `before_agent_start` handler where subagent mode is detected, +add a `turn_end` event handler alongside the existing `tool_result` +handler: + +```typescript +pi.on("turn_end", (event) => { + // event.message is AgentMessage = Message | CustomAgentMessages[...]. + // AssistantMessage (from pi-ai) has role: "assistant" and usage: Usage. + // Usage = { input, output, cacheRead, cacheWrite, totalTokens, cost }. + const msg = event.message as { + role: string; + usage?: { + input: number; + output: number; + cacheRead: number; + cacheWrite: number; + }; + }; + if (msg.role === "assistant" && msg.usage) { + void eventLog!.append({ + kind: "usage", + input: msg.usage.input, + output: msg.usage.output, + cacheRead: msg.usage.cacheRead, + cacheWrite: msg.usage.cacheWrite, + }); + } +}); +``` + +This fires on every completed assistant turn in the subagent's pi +session. Each turn produces one `usage` event in `events.jsonl`. +The `fold()` function in `audit.ts` accumulates these into the +`Projection`'s `tokensSent` and `tokensReceived` fields. + +### 5.4 Projection accumulation + +Extend `Projection` with cumulative token fields: + +```typescript +interface Projection { + // ... existing fields ... + tokensSent: number; // cumulative input tokens (includes cache hits) + tokensReceived: number; // cumulative output +} +``` + +The `fold()` function accumulates on each `usage` event: + +```typescript +case "usage": + return { + ...p, + tokensSent: p.tokensSent + e.input, + tokensReceived: p.tokensReceived + e.output, + }; +``` + +The web server reads these fields from `state.json` during polling. + +### 5.5 Display format + +Token counts are formatted with `k` suffix: `42.1k`, `8.3k`. Below +10k, show raw number: `4,100`. The table header row shows totals: +`↑73.5k ↓16.2k`. + +--- + +## 6. Subagent Table Widget + +The always-present bottom panel. This is the UI manifestation of +principle §1.1 (flat over nested) and §1.2 (everything visible). + +### 6.1 Table columns + +| Column | Width | Content | Style | +| ------ | ----- | --------------------------------------------------------------------- | --------------------------------------------------------------- | +| status | 20px | `●` (running, colored) or `✓` (done, green) or `✗` (failed, red) | centered | +| agent | auto | agent display name | `--text`, bold if running; `--green` if done; `--red` if failed | +| model | 70px | shortened model name (`opus-4`, `haiku-4`) | `--text-muted` | +| parent | 80px | parent agent name, or `—` for top-level | `--text-dim` | +| ↑ sent | 55px | cumulative tokens sent, formatted with `k` suffix | `--text-muted`, right-aligned | +| ↓ recv | 55px | cumulative tokens received | `--text-muted`, right-aligned | +| doing | flex | 1–5 recent action summaries stacked vertically; most recent at bottom | `--text-dim`; `--green` if done | + +### 6.2 Table header + +Above the table, a summary row: + +``` +Subagents [●1] [✓3] ↑73.5k ↓16.2k +``` + +- "Subagents" label in uppercase, `--text-dim`, 10px, letter-spaced +- Badge counts: green badge for done count, blue badge for active count +- Token totals: sum of all agents' tokens + +### 6.3 Row ordering + +1. Running agents first, in spawn order (newest last) +2. Completed agents after, in completion order +3. Failed agents last + +### 6.4 Row lifecycle + +- Agent spawned → `registerAgent()` → row appears with status `●`, + all other fields from initial info (model, parent), tokens at 0, + doing = "initializing..." +- Polling tick → row updates: tokens increase, currentAction changes +- Agent exits → `completeAgent()` → final poll, status changes to + `✓` or `✗`, doing shows final summary or error + +Rows **never disappear** during a pipeline run. Completed agents stay +in the table with their final state. This gives the user a complete +history of all agents that ran. + +### 6.5 "Doing" column — multi-line per agent + +There is no separate activity log. The `doing` column in the agent table +IS the log: it shows 1–5 recent log lines per agent, stacked vertically +within the cell. The number of lines shown adapts based on active agent +count and available screen space — fewer agents → more lines visible. + +The left columns (status, agent, model, parent, tokens) appear once per +row, vertically centered. The `doing` column expands to fill its cell +with multiple stacked lines: + +``` +● intake claude-opus-4 — ↑12.3k ↓4.1k read src/lib/db/schema.ts + bash find src -name '*.ts' + grep 'useState' (23 matches) +``` + +The most recent action is at the bottom. Lines older than the newest 5 +are not shown. This replaces the collapsed/expanded log toggle entirely. + +--- + +## 7. Pill Strip Progress Indicator + +Lives in the header bar. Shows the 4 intake sub-phases. + +### 7.1 Pill states + +| State | Background | Text | Border | +| ------- | -------------------------- | ---------------------- | ------ | +| Done | `--green-border` (#238636) | white, with `✓` prefix | none | +| Active | `--blue-border` (#1f6feb) | white, with `●` dot | none | +| Pending | `--border` (#21262d) | `--text-dim` | none | + +Pills are connected (no gap, shared border-radius: first pill gets +left radius, last gets right radius, middle pills are flat). + +### 7.2 Pill labels + +Fixed labels matching the intake sub-phases: + +| Pill | Label | Maps to backend | +| ---- | --------- | ----------------------------- | +| 1 | context | Step 1/3: Context Extraction | +| 2 | explore | Step 2/3: Codebase Scouting | +| 3 | questions | Step 3/3 before answer submit | +| 4 | spec | Step 3/3 after answer submit | + +The browser derives the active pill from the `subPhase` field in the +`agents` SSE event (for the intake agent): + +- `subPhase: "context"` → pill 1 active +- `subPhase: "explore"` → pill 2 active +- `subPhase: "questions"` → pill 3 active +- `subPhase: "spec"` → pill 4 active +- `phase: "decomposition"` arrives → pill 4 becomes done + +The browser does NOT infer sub-phase from raw step transitions or `ask` +arrival — it reads `subPhase` directly. + +### 7.3 Progress bar + +A 3px bar at the very top of the page (above the header). Background +is `--border`. Fill is a gradient from `--green` to `--blue`. +Width is calculated: `(completedSteps / 4) * 100%`. Animated width +transition (400ms cubic-bezier). + +--- + +## 8. Timer + +Top-right of the header. Shows elapsed time since intake started. + +- Format: `Mm SSs` (e.g., `1m 12s`, `0m 05s`) +- Computed client-side from the `startedAt` timestamp in the first + `subagent` SSE event +- Updated every second via `setInterval` +- Color: `--text-dim` +- Font: `--font-mono`, 13px + +--- + +## 9. Interaction Flows + +### 9.1 Question submission + +1. User selects options for all questions +2. User clicks "Submit Answers" (or "Accept All Defaults") +3. Browser sends `POST /api/answer`: + ```json + { + "token": "session-uuid", + "requestId": "ask-request-uuid", + "answers": [ + { + "questionId": "scope", + "selectedOptions": ["Replace for pipeline, keep TUI for config"], + "customInput": null + }, + { + "questionId": "error-handling", + "selectedOptions": ["Show error + ask user whether to retry"], + "customInput": null + } + ] + } + ``` +4. Server resolves the pending `requestAnswer()` Promise +5. Server responds with `{ ok: true }` +6. Browser updates pill strip (questions → done, spec → active) +7. Browser crossfades to Consolidation screen + +### 9.2 Accept All Defaults + +1. Browser iterates through all questions +2. For each question with a `recommended` index: select that option +3. For questions without `recommended`: select the first option +4. Auto-submit immediately (no further user action) + +### 9.3 "Other" option + +1. User clicks "Other..." on a question +2. Radio/checkbox selects "Other" +3. Text input slides open below the option (150ms transition) +4. User types their custom answer +5. On submit, the answer includes: + ```json + { + "selectedOptions": ["Other (type your own)"], + "customInput": "My custom answer text" + } + ``` + +### 9.4 Heartbeat + +Browser sends `POST /api/heartbeat` every 5 seconds with +`{ token }`. Observability only — no auto-resolution per parent plan +§6.5. + +--- + +## 10. Data Flow: Server → Browser + +### 10.1 SSE initial replay + +On SSE connect, the server replays the current state as an initial +burst of events (per parent plan §6.3): + +1. `phase` event with current phase +2. `agents` event with all known agents +3. `subagent` event with current tracked agent (if any) +4. `scouts` event with all scout states (if any active) +5. `logs` event with recent log entries from all agents +6. `ask` event (if a question is pending) + +This handles browser refresh, late connection, and reconnection. + +### 10.2 SSE event flow during intake + +``` +Browser opens → SSE connects + ← phase: { phase: "intake" } + ← agents: [{ name: "intake", ... }] + ← subagent: { role: "intake", step: 1, ... } +[Loading screen] + +Intake reads conversation... + ← logs: [{ agent: "intake", tool: "read", ... }] + ← agents: [{ name: "intake", tokensSent: 12k, ... }] +[Context Analysis screen] + +Step 2 starts, scouts spawn... + ← subagent: { role: "intake", step: 2, ... } + ← agents: [intake, auth-patterns, api-structure, ...] + ← scouts: [{ id: "auth-patterns", status: "running" }, ...] + ← logs: [{ agent: "auth-patterns", tool: "read", ... }, ...] +[Scout Exploration screen] + +Scout completes... + ← scouts: [{ id: "auth-patterns", status: "completed", completionSummary: "..." }, ...] + ← agents: (updated with final tokens) + +All scouts done, step 3, ask... + ← subagent: { role: "intake", step: 3, ... } + ← ask: { requestId: "...", questions: [...] } +[Questions screen] + +User submits answers... +POST /api/answer → + ← 200 OK + +Consolidation... + ← logs: [{ agent: "intake", tool: "write", summary: "decisions.md" }] + ← agents: (intake tokens still accumulating) + +Intake done... + ← phase: { phase: "decomposition" } + ← agents: [{ name: "intake", status: "completed" }] +[Intake Complete → Decomposition] +``` + +--- + +## 11. File Structure + +### 11.1 New files + +``` +src/planner/web/ + html/ + index.html # page shell with __DATA__ placeholder + css/ + variables.css # custom properties (§2.3) + layout.css # header, phase-content, monitor, grid + components.css # cards, pills, table, buttons, forms + animations.css # transitions, spinner, crossfade + js/ + app.js # SSE connection, state management, routing + render.js # DOM rendering: phase screens, pill strip + table.js # subagent table + activity log rendering + forms.js # question form: options, other input, submit + utils.js # formatTokens(), relativeTime(), etc. +``` + +### 11.2 Modified files (additions only) + +``` +src/planner/lib/audit.ts # Add UsageEvent type + fold case (§5) +extensions/koan.ts # Add turn_end handler for usage (§5.3) +src/planner/web/server.ts # Add registerAgent/completeAgent, + # scouts/agents SSE push logic +``` + +### 11.3 Server serves assets from memory + +Assets are served by the wildcard `GET /static/*` handler (defined in +the parent plan §6.2). The handler maps the path to the bundled `web/` +directory and sets the correct MIME type. New CSS or JS files are +automatically servable without adding routes. + +The HTML template references assets by path rather than inlining them: + +```html +<link rel="stylesheet" href="/static/css/variables.css" /> +<link rel="stylesheet" href="/static/css/layout.css" /> +<link rel="stylesheet" href="/static/css/components.css" /> +<script src="/static/js/app.js" defer></script> +<script src="/static/js/render.js" defer></script> +<script src="/static/js/table.js" defer></script> +<script src="/static/js/forms.js" defer></script> +``` + +Only `/* __DATA__ */` inlining remains for the initial SSE replay data: + +```typescript +const html = TEMPLATE.replace("/* __DATA__ */", safeInlineJSON(initialData)); +``` + +--- + +## 12. Implementation Order + +1. **Backend: token tracking** (§5) — Add `UsageEvent`, `turn_end` + handler, `Projection` extension, `fold()` update. Independent of UI. +2. **Server: agent/scout registration** (§4) — Add `registerAgent`, + `completeAgent` to `WebServerHandle`. Add `agents` and `scouts` + SSE event push logic. Scouts use `registerAgent()` individually. +3. **HTML/CSS** (§2, §7) — Page skeleton, CSS variables, layout, + components. Can be developed with mock data. +4. **JS: SSE + state** (`app.js`) — Connect SSE, maintain client-side + state, dispatch to renderers on event. +5. **JS: phase screens** (`render.js`) — Loading, context analysis, + scout cards, consolidation. Non-interactive screens. +6. **JS: subagent table** (`table.js`) — Table rendering, row updates, + activity log, token formatting. +7. **JS: question form** (`forms.js`) — Radio/checkbox rendering, + "Other" input, validation, submit/accept-all-defaults actions. +8. **Integration: driver call sites** — Wire `registerAgent` calls at + each spawn site in `driver.ts`. Wire `registerScouts` in + `ipc-responder.ts`. + +--- + +## 13. What This Plan Does NOT Cover + +- **Decomposition, review, and execution phases** — This plan covers + intake only. Those phases will have their own phase content screens + but share the same page layout, subagent table, and pill strip + (extended to cover the full pipeline). +- **Visual polish / animations** — Described at the level of "250ms + crossfade" but exact easing curves and stagger timing are + implementation details. +- **Responsive design** — The dashboard targets desktop browsers. + Mobile is not a priority. +- **Accessibility** — Semantic HTML and keyboard navigation for the + question form are expected. Full ARIA labeling is a nice-to-have. +- **Dark/light theme toggle** — Dark only for v1. +- **Cost display ($)** — Token counts are shown, not dollar costs. + Cost calculation requires model pricing data that may not be + available. Token counts are the honest primitive. diff --git a/plans/2026-03-14-plan-audit.md b/plans/2026-03-14-plan-audit.md new file mode 100644 index 0000000..5c5f42b --- /dev/null +++ b/plans/2026-03-14-plan-audit.md @@ -0,0 +1,206 @@ +# Plan Audit Report + +> **Date:** 2026-03-14 +> **Scope:** Technical audit of `2026-03-13-web-ui.md` (architecture plan) +> and `2026-03-14-intake-ui.md` (intake UI plan) against the koan codebase. + +--- + +## Plan 1: Web UI Architecture (`2026-03-13-web-ui.md`) + +### 1. Summary + +Proposes replacing all TUI-based UI in koan with a browser-based web interface. +An HTTP server (raw `node:http`) starts inside `koan_plan.execute()`, serves +a single-page app, pushes state via SSE, and receives user input via POST +endpoints. The driver's `ExtensionUIContext` parameter is replaced with a +`WebServerHandle` interface that encapsulates push methods, observation polling, +and Promise-blocking input collection. Five TUI files are deleted, four files +are rewritten, and a new `web/` module is created from scratch. + +### 2. Relevant Existing Code + +| File | Relationship to Plan | Status | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| `extensions/koan.ts` (168 lines) | Entry point for `koan_plan` tool. Plan adds server start, try/finally, browser open. | ✅ Verified exists, all claims match | +| `src/planner/driver.ts` (540 lines) | Core rewrite target. `runEpicPipeline` → `runPipeline`, delete `startActivePolling`, replace 9 spawn sites + 3 notify calls + 1 spec review gate. | ✅ All line numbers verified exact | +| `src/planner/subagent.ts` (270 lines) | `SpawnOptions.ui` type changes from `ExtensionUIContext` to `WebServerHandle`. 6 public spawn functions affected. | ✅ Verified | +| `src/planner/lib/ipc-responder.ts` (201 lines) | Bridge file — currently routes ask requests to TUI, must route to web server. Imports from `ui/ask/*.ts` replaced with `web/server-types.ts`. | ✅ Verified | +| `src/planner/lib/ipc.ts` (168 lines) | Wire types (`AskIpcFile`, `ScoutIpcFile`, etc.) unchanged. Structural compatibility with `AskQuestion`/`AskSelection` verified. | ✅ Verified compatible | +| `src/planner/ui/epic-widget.ts` (253 lines) | Delete. `EpicWidgetController`, `ActiveSubagentInfo`, `EpicWidgetState`, `EpicWidgetUpdate` all replaced by SSE push. | ✅ Exists | +| `src/planner/ui/spec-review.ts` (150 lines) | Delete. `reviewStorySketches()` replaced by `webServer.requestReview()`. Story title extraction logic (`readStoryTitle()`) must be preserved somewhere. | ✅ Exists | +| `src/planner/ui/ask/ask-logic.ts` | Model code relocated to `web/server-types.ts`. Zero TUI dependencies confirmed. | ✅ Zero imports confirmed | +| `src/planner/ui/ask/ask-inline-ui.ts` | Delete. TUI single-question ask. | ✅ Exists | +| `src/planner/ui/ask/ask-tabs-ui.ts` (~350 lines) | Delete. TUI multi-question tabbed ask. | ✅ Exists | +| `src/planner/ui/ask/ask-inline-note.ts` | Delete. ANSI wrapping helper. | ✅ Exists | +| `src/planner/ui/config/menu.ts` | Keep unchanged. `/koan config` TUI command. | ✅ Exists, plan says keep | +| `src/planner/ui/config/model-selection.ts` | Keep unchanged. Used by menu.ts. | ✅ Exists, plan says keep | +| `src/planner/lib/audit.ts` (393 lines) | Plan says unchanged, but intake-ui plan §5 adds `UsageEvent` + `Projection` extension. | ⚠️ Contradiction between plans | +| `src/planner/lib/pool.ts` | Unchanged. Scout concurrency (cap=4) confirmed in ipc-responder.ts. | ✅ Verified | +| Reference: `pi-design-deck/deck-server.ts` (~530 lines) | SSE + session token + random port + heartbeat patterns. | ✅ Read, patterns match plan claims | +| Reference: `plannotator/server.ts` (~400 lines) | Promise-based decision waiting + `openBrowser()`. | ✅ Read, patterns match plan claims | + +### 3. Implementation Requirements + +| Component | Scope | Description | +| --------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `web/server-types.ts` | **New** (medium) | `WebServerHandle` interface, relocated ask types, SSE event types, `AnswerResult`, `ReviewResult`, `ReviewStory` | +| `web/server.ts` | **New** (large) | HTTP server, SSE, routes, session mgmt, observation polling, abort cleanup, state buffering. Estimated 400-600 lines based on reference implementations. | +| `web/html/index.html` | **New** (small) | Single-page app shell with `__DATA__` / `__CSS__` / `__JS__` placeholders | +| `web/css/` | **New** (medium) | Dark theme, component styles. 1 file (web-ui plan) or 4 files (intake-ui plan). | +| `web/js/` | **New** (large) | SSE client, state management, DOM rendering, forms. 3 files (web-ui) or 5 files (intake-ui). | +| `driver.ts` | **Rewrite** (medium) | ~30 lines change across 15+ locations. Mechanical: type substitution + method renames. | +| `subagent.ts` | **Rewrite** (small) | Type change on `ui` field, pass to `runIpcResponder`. ~10 lines change. | +| `ipc-responder.ts` | **Rewrite** (medium) | Replace `handleAskRequest` body (~50 lines), change parameter types. ~60 lines change. | +| `koan.ts` | **Modify** (medium) | Add server start, try/finally, browser open, URL in result, remove 2 commands. ~30 lines change. | +| Deletions | **Delete** | 5 TUI files (~1000 lines total): epic-widget, spec-review, ask-inline-ui, ask-tabs-ui, ask-inline-note | + +### 4. Issues + +| # | Issue | Type | Plan Section | Relevant Code | Severity | +| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------------------- | ------------------------------------------------------------------------------- | -------- | +| 1 | **`startActivePolling` count**: Plan says "10 call sites" but there are 9 call sites + 1 definition (L81). The 10 matches come from `grep`, not actual call sites. | Ambiguity | §4.6 | `driver.ts` L81 (def), L132,160,204,231,257,285,317,339,376 (calls) | Low | +| 2 | **CSS file count mismatch**: §5 specifies `css/styles.css` (1 file). Intake-ui plan §11.1 specifies 4 files: `variables.css`, `layout.css`, `components.css`, `animations.css`. | Contradiction | §5 vs intake-ui §11 | No existing code — greenfield | Low | +| 3 | **JS file count mismatch**: §5 specifies 3 JS files (`app.js`, `render.js`, `forms.js`). Intake-ui adds `table.js` and `utils.js`. | Contradiction | §5 vs intake-ui §11 | No existing code — greenfield | Low | +| 4 | **Asset serving contradiction**: §6.2 defines `GET /app.css` and `GET /app.js` routes (separate HTTP requests). Intake-ui §11.3 says `/* __CSS__ */` and `/* __JS__ */` placeholders inlined into HTML (design-deck pattern, no separate requests). Both can't be true. | Contradiction | §6.2 vs intake-ui §11.3 | Reference: `deck-server.ts` inlines; `plannotator/server.ts` serves separate | Medium | +| 5 | **`readStoryTitle` destination unspecified**: `spec-review.ts` is deleted but it contains `readStoryTitle()` (L31-43) which extracts the title from `story.md`. §4.3 says "filesystem-reading logic moves from `spec-review.ts` into the driver or a helper in `web/server.ts`" — ambiguous. This is called from the driver's spec review gate. | Ambiguity | §4.3 | `spec-review.ts` L31-43 (`readStoryTitle`) | Low | +| 6 | **Cancel button behavior unspecified in web form**: §4.4 implementation note #3 says the web form needs a Cancel button and that cancelling writes `createCancelledResponse()`. But §7.3 (question form rendering) never mentions a Cancel button. The button's presence, placement, and visual treatment are unstated. | Incompleteness | §4.4, §7.3 | `ipc-responder.ts` handles cancelled response at L76, L95 | Medium | +| 7 | **Multiple question forms concurrency**: §4.4 note #4 asks "verify these don't collide" about concurrent IPC responders during intake. The plan flags the concern but never resolves it — it's left as an open question for implementation. | Incompleteness | §4.4 | `ipc-responder.ts` — one per subagent; `tools/ask.ts` — `ipcFileExists()` guard | Low | +| 8 | **`audit.ts` classified as unchanged, but intake-ui modifies it**: §5.3 lists `lib/audit.ts` as "UNCHANGED". Intake-ui §5 adds `UsageEvent` type and extends `Projection` with `tokensSent`/`tokensReceived`. One plan says unchanged, the other modifies it. | Contradiction | §5.3 vs intake-ui §5 | `audit.ts` L75 (`AuditEvent` union), L85 (`Projection`) | Medium | +| 9 | **`POST /api/cancel` behavior unspecified**: §3.2 lists `POST /api/cancel` as an endpoint. §9 discusses error handling and cleanup. But nowhere does the plan describe what happens when the user presses Cancel: Does it kill subagent processes? Reject all pending Promises? Push a `pipeline-end` SSE event? The only mention of child process termination is §11 which says process kill is NOT covered. | Incompleteness | §3.2, §9 | `subagent.ts` — `child_process.spawn()` at L72; no `.kill()` exposed | Medium | +| 10 | **Notify count in koan.ts**: §4.5 says "2 `ui.notify()` calls in `extensions/koan.ts` command handlers". Actual: 4 calls (L171 usage, L173 unknown-subcommand, L181 koan-execute, L188 koan-status). The extra 2 are in commands being removed (§8.2), so net effect is correct, but the count is wrong as documentation of current state. | Ambiguity | §4.5 | `koan.ts` L171,173,181,188 | Low | +| 11 | **Multiple browser tabs behavior**: §11 says "additional tabs get a 'session already active' message or share the same SSE stream" — leaves the decision open. This affects SSE state replay (§6.3): if tabs share the SSE stream, pending input can be answered from either tab (race). If separate, stale tabs could submit against resolved requests (409 handling in §9.1 covers this). | Ambiguity | §11 | No existing code | Low | +| 12 | **`LogsEvent` field shape differs for intake**: §3.1 defines `LogsEvent` as `{ lines: LogLine[] }` where `LogLine = { tool, summary, highValue }`. Intake-ui §4.3 extends each line with `agent`, `agentColor`, `timestamp`. The base `LogLine` in `audit.ts` only has `{ tool, summary, highValue }`. The SSE payload must carry the superset, but the plan doesn't specify whether `LogLine` is extended or a new `WebLogLine` type is created. | Incompleteness | §3.1 vs intake-ui §4.3 | `audit.ts` L352 (`LogLine` interface) | Medium | +| 13 | **SSE `review` event: `readStoryTitle` must handle missing files**: `spec-review.ts` has a `try/catch` that falls back to `storyId` if `story.md` is missing. The plan says this logic moves but doesn't specify that the fallback must be preserved. | Unstated assumption | §4.3 | `spec-review.ts` L31-43 | Low | +| 14 | **Heartbeat race with spec review / ask forms**: §6.5 says heartbeat has no effect on pipeline. But if browser is closed during spec review, `requestReview()` blocks forever. The plan says "waits indefinitely" (§9.5) as design choice — but doesn't mention that closing the pi process (Ctrl+C) triggers `finally` cleanup. If the pi session is headless (RPC), there's no Ctrl+C. | Scope gap | §6.5, §9.5 | No existing code | Low | + +--- + +## Plan 2: Intake UI (`2026-03-14-intake-ui.md`) + +### 1. Summary + +Specifies the browser UI for the intake phase — from `koan_plan` invocation +through project spec consolidation. Defines 5 design principles, 6 phase +content screens, 3 new SSE event types (`scouts`, `agents`, enhanced `logs`), +a token usage tracking backend change (`UsageEvent` in `audit.ts`, `turn_end` +handler in `koan.ts`), a persistent flat subagent table widget, pill strip +progress indicator, and detailed interaction flows for the question form. +This is a child plan of the web-ui architecture plan. + +### 2. Relevant Existing Code + +| File | Relationship to Plan | Status | +| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| `src/planner/lib/audit.ts` (393 lines) | Plan adds `UsageEvent` type to `AuditEvent` union, extends `Projection` with `tokensSent`/`tokensReceived`, extends `fold()`. | ✅ Verified: no `usage` event kind exists. `Projection` at L85 has 11 fields, none token-related. | +| `extensions/koan.ts` (168 lines) | Plan adds `pi.on("turn_end", ...)` handler alongside existing `pi.on("tool_result", ...)` at L93. | ✅ Verified: only `tool_result` handler exists. `turn_end` event confirmed in pi extension API (`types.d.ts` L392). | +| `src/planner/lib/ipc-responder.ts` (201 lines) | Plan says this calls `webServer.registerScouts(scoutDirs)` when scout-request IPC arrives. Currently calls `pool()` directly. | ✅ Verified: `handleScoutRequest` at L127 spawns scouts. | +| `src/planner/driver.ts` (540 lines) | Plan says `registerAgent()` called at each spawn site. Currently 9 spawn call sites with `startActivePolling`. | ✅ Verified | +| `src/planner/phases/base-phase.ts` | Plan references phase step names/counts. `BasePhase.getStepName()` provides these. | ✅ Verified | +| `src/planner/phases/intake-phase.ts` | IntakePhase has 3 steps: context extraction, scout requests, gap analysis. Plan's pill labels match. | ✅ Verified | +| pi `types.d.ts` — `AssistantMessage.usage` | Plan §5 depends on this for token tracking. `Usage = { input, output, cacheRead, cacheWrite, totalTokens, cost }`. | ✅ Verified: `AssistantMessage` at pi-ai/types.d.ts has `usage: Usage` | +| pi `types.d.ts` — `TurnEndEvent` | Plan §5.3 hooks `turn_end`. `TurnEndEvent = { type, turnIndex, message: AgentMessage, toolResults }`. | ✅ Verified: `AgentMessage` is union including `AssistantMessage`. | +| `src/planner/web/server.ts` | Plan extends with `registerAgent`, `completeAgent`, `registerScouts`, `clearScouts`. File doesn't exist yet (created by parent plan). | Expected — new file | +| `src/planner/conversation.ts` | Plan §3.1 says topic extracted from `conversation.jsonl`. `exportConversation()` writes this file. | ✅ Verified exists | + +### 3. Implementation Requirements + +| Component | Scope | Description | +| ---------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `audit.ts` modifications | **Modify** (small) | Add `UsageEvent` interface, add `"usage"` to `AuditEvent` union, add `tokensSent`/`tokensReceived` to `Projection`, add `fold()` case. ~25 lines. | +| `koan.ts` `turn_end` handler | **Modify** (small) | Add `pi.on("turn_end", ...)` handler next to existing `tool_result` handler. ~12 lines. | +| `web/server.ts` extensions | **Modify** (medium) | Add `registerAgent()`, `completeAgent()`, `registerScouts()`, `clearScouts()`, `agents` SSE push, `scouts` SSE push, enhanced `logs` with agent attribution. ~100-150 lines added to new file. | +| `web/html/index.html` | **New** (medium) | Page skeleton per §2.2 — header, phase-content, monitor, footer. | +| `web/css/` (4 files) | **New** (medium) | `variables.css` (§2.3 token definitions), `layout.css`, `components.css`, `animations.css`. ~300-400 lines total. | +| `web/js/app.js` | **New** (medium) | SSE connection, client state management, phase routing. ~150-200 lines. | +| `web/js/render.js` | **New** (large) | 5 phase content screens: loading, context analysis, scout exploration, consolidation, intake-skipped. ~200-300 lines. | +| `web/js/table.js` | **New** (medium) | Flat subagent table + activity log rendering. ~150 lines. | +| `web/js/forms.js` | **New** (large) | Question cards, radio/checkbox options, "Other" input, "Accept All Defaults", submit. ~250-350 lines. | +| `web/js/utils.js` | **New** (small) | `formatTokens()`, `relativeTime()`, DOM helpers. ~50 lines. | +| Driver call site wiring | **Modify** (small) | Add `registerAgent()` calls at each spawn site. ~18 lines (9 sites × 2 lines). | +| IPC responder wiring | **Modify** (small) | Add `registerScouts()` call in `handleScoutRequest`. ~5 lines. | + +### 4. Issues + +| # | Issue | Type | Plan Section | Relevant Code | Severity | +| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| 1 | **`turn_end.message` type safety**: Plan §5.3 casts `event.message` to `{ role: string; usage?: {...} }`. `TurnEndEvent.message` is `AgentMessage`, which is `Message \| CustomAgentMessages[...]`. The cast is safe because the `if (msg.role === "assistant" && msg.usage)` guard narrows it. But `AgentMessage` is re-exported from `@mariozechner/pi-agent-core`, and custom messages could have `role: "assistant"` without `usage`. The code handles this via the `msg.usage` truthiness check, but it's an unstated assumption that custom messages won't have role "assistant" + a truthy `usage` property. | Unstated assumption | §5.3 | pi `types.d.ts` L392 (`TurnEndEvent`), pi-agent-core `types.d.ts` L214 (`AgentMessage`) | Low | +| 2 | **Token accumulation semantics: `tokensSent = input + cacheWrite`**: §5.4 says `tokensSent: p.tokensSent + e.input + e.cacheWrite`. This counts cache write tokens as "sent" — which is technically correct (they're input tokens that populate the cache). But `cacheRead` tokens are NOT counted in `tokensSent` despite also representing processed input. This means an agent with heavy cache hits will show low `tokensSent` even though the provider processed many input tokens. The user may find this counterintuitive. | Ambiguity | §5.4 | pi-ai `types.d.ts` `Usage = { input, output, cacheRead, cacheWrite }` | Medium | +| 3 | **`agents` event redundancy with `subagent` + `scouts`**: §4.2 says the `agents` SSE event "replaces" `trackSubagent` and `scouts` for UI purposes but both are kept. The browser receives 3 events with overlapping data: `subagent` (step-level progress for one agent), `scouts` (parallel scout status), and `agents` (flat table for all). The browser must reconcile these — e.g., the `agents` event may show a scout as "running" while `scouts` shows it as "completed" if events arrive out of order. | Incompleteness | §4.2 | No existing code — new SSE design | Medium | +| 4 | **Scout `completionSummary` extraction from `events.jsonl`**: §4.1 says the web server reads the scout's `events.jsonl` to find the last `phase_end` event and extracts its `detail` field. But `PhaseEndEvent.detail` is only set on failure (`outcome: "failed"`). On success, scouts call `koan_complete_step(thoughts)` — the thoughts are in a `ToolKoanEvent` (kind `tool_koan`, tool `koan_complete_step`), NOT in `phase_end.detail`. The plan's extraction logic points to the wrong event. | Contradiction | §4.1 | `audit.ts`: `PhaseEndEvent = { kind: "phase_end", outcome, detail? }` — `detail` is error info, not findings. `koan_complete_step` result is in `ToolKoanEvent.response`. | High | +| 5 | **Scout directory discovery for `registerScouts`**: §4.1 says the IPC responder calls `webServer.registerScouts(scoutDirs)` but doesn't specify the `scoutDirs` data shape. The IPC responder builds scout dirs at runtime (`path.join(epicDir, "subagents", \`scout-${task.id}-${Date.now()}\`)`in`ipc-responder.ts`L141). The`registerScouts`call must happen AFTER dirs are computed but BEFORE spawning starts. The plan doesn't specify where in the`handleScoutRequest` flow this call goes. | Incompleteness | §4.1 | `ipc-responder.ts` L137-143 (dir computation), L147-162 (pool spawn) | Medium | +| 6 | **Agent registration naming inconsistency**: §4.1 says `registerScouts(scoutDirs)`, §4.2 says `registerScouts(scoutDirs)` again, but the earlier `intake-dashboard-ux.md` says `registerScoutDirs(dirs: Map<string, ScoutDir>)`. These should converge on one name and signature. | Ambiguity | §4.1, §4.2 | N/A — new API | Low | +| 7 | **No `phase` SSE event defined for intake sub-phases**: The pill strip (§7) tracks 4 intake sub-phases: context, explore, questions, spec. But the `phase` SSE event from the parent plan carries `EpicPhase` values (`"intake" \| "decomposition" \| "review" \| "executing" \| "completed"`). There's no SSE event for transitions between intake sub-phases (context → explore → questions → spec). The browser must infer these from `subagent` step transitions and `ask` event arrival. §7.2 acknowledges this but doesn't define an explicit event — the inference logic is left to the browser implementation. | Incompleteness | §7.2 | `src/planner/types.ts` (`EpicPhase`), `src/planner/phases/intake-phase.ts` (3 steps) | Medium | +| 8 | **Pill strip has 4 sub-phases but intake has 3 steps**: §7.2 maps: pill 1 → step 1/3, pill 2 → step 2/3, pill 3 → step 3/3 before answer, pill 4 → step 3/3 after answer. Steps 3 and 4 are the same backend step (3/3: Gap Analysis). The browser must split step 3/3 into "questions" and "spec" sub-phases. This works but relies on the `ask` event → answer POST transition to know when pill 3 → pill 4. If questions are skipped (§3.6), pill 3 jumps directly to done. The edge case is specified but complex. | Incompleteness | §7.2, §3.6 | `IntakePhase` has 3 steps, not 4 | Low | +| 9 | **`conversation.jsonl` topic extraction parsing unspecified**: §3.1 says the server extracts the topic from `conversation.jsonl` looking for the last `role: "user"` entry. But this file's format isn't specified in the plan. `exportConversation()` writes it, and the plan assumes it's newline-delimited JSON with a `role` field. What if the conversation is empty? What if the last user message is an image? Plan says "if extraction fails, the topic card is hidden" but doesn't define what constitutes failure beyond "extraction fails". | Incompleteness | §3.1 | `conversation.ts` (`exportConversation`) | Low | +| 10 | **Activity log merge from multiple agents**: §4.3 says the web server "merges recent logs from ALL running agents' directories (reading `events.jsonl` from each) and sorts by timestamp." Currently `readRecentLogs(dir)` reads the ENTIRE `events.jsonl` file and returns the last N entries. With 5 scouts running, this means reading 5 files completely every 2 seconds and merging. No truncation, seek, or incremental read is described. This may have performance implications for long-running agents with large event logs. | Scope gap | §4.3, §6.5 | `audit.ts` `readRecentLogs()` — reads entire file, no offset support | Medium | +| 11 | **`agents` event: who supplies the `name` field?**: §4.2 defines `registerAgent({ id, name, dir, role, model, parent })`. For scouts, the `name` comes from `ScoutTask.id` (e.g., "auth-patterns"). For the intake subagent, the `name` is "intake". But the driver doesn't currently have a "name" concept for subagents — it only has `role` and `subagentDir`. Who constructs the display name? The plan lists the interface but doesn't specify the mapping from current spawn call context to `name`. | Incompleteness | §4.2 | `subagent.ts` spawn functions, `driver.ts` spawn call sites | Low | +| 12 | **Elapsed timer `startedAt` source**: §8 says the timer is computed from "the `startedAt` timestamp in the first `subagent` SSE event." But the `subagent` SSE event from the parent plan has `startedAt: number` (epoch ms) set from `Date.now()` at `trackSubagent` call time. If the browser opens AFTER the first subagent started (topic extraction already done), the timer starts from the first subagent's real start time — which is correct. But if there's a gap between page load and first SSE event, the timer won't start until the event arrives. This is acknowledged by §3.1 ("Loading screen shown until first subagent SSE event") but the UX of "no timer" during loading isn't specified. | Incompleteness | §8 | No existing code | Low | +| 13 | **Question card context paragraph**: §3.4 says "The question text itself contains the context (the intake model writes questions that reference scout findings)." This assumes the intake LLM will include scout context in the question string. If the LLM writes terse questions without context, the UI will look bare. This is a prompt engineering concern, not a UI concern, but the plan's UI relies on it. | Unstated assumption | §3.4 | Intake phase prompts (not yet written for web flow) | Low | +| 14 | **No POST endpoint for heartbeat response confirmation**: §9.4 says browser sends `POST /api/heartbeat` every 5 seconds. The parent plan §6.5 says this is observability-only. But neither plan specifies the HTTP response body. Should it return `{ ok: true }` or just 200? If the server is gone (pipeline finished), the browser gets a connection error — how should it display that? "Pipeline completed" or "Connection lost"? | Incompleteness | §9.4 | No existing code | Low | +| 15 | **`POST /api/answer` body shape differs from plan text vs code example**: §9.1 shows `answers` as `Array<{ questionId, selectedOptions, customInput }>` where the `id` field is named `questionId`. But the parent plan §3.2 says the body is `{ token, requestId, answers: AskSelection[] }` where `AskSelection = { selectedOptions: string[], customInput? }` — no `questionId` in `AskSelection`. The intake plan adds `questionId` which isn't in the parent's type definition. | Contradiction | Intake §9.1 vs web-ui §3.2 | `ask-logic.ts`: `AskSelection = { selectedOptions: string[], customInput? }` — no `id` field | Medium | +| 16 | **"Accept All Defaults" auto-submit has no confirmation**: §9.2 says "auto-submit immediately (no further user action)." §3.4 says the button is secondary (outlined). A single click instantly submits all answers with no confirmation dialog. If the user accidentally clicks it, there's no undo. The current TUI doesn't have this feature, so there's no precedent. | Scope gap | §9.2, §3.4 | No existing code — new feature | Low | + +--- + +## Cross-Plan Observations + +### Dependencies + +1. **Intake plan depends on web-ui plan's server infrastructure**: Every SSE + event, POST endpoint, and `WebServerHandle` method in the intake plan + assumes the server described in the web-ui plan exists. The intake plan + is not implementable without the web-ui plan's §6 (HTTP server) and §4.1 + (WebServerHandle interface). + +2. **Token tracking (intake §5) must be implemented before agent table + (intake §6)**: The `tokensSent`/`tokensReceived` fields in the subagent + table come from `Projection`, which requires the `UsageEvent` and + `fold()` changes. The agent table can be built without token columns as + a stub, but the full feature requires the backend change first. + +3. **Web-ui plan's `LogsEvent` must be extended for intake**: The base plan's + `LogLine = { tool, summary, highValue }` is insufficient for the intake + UI's activity log which needs `agent`, `agentColor`, and `timestamp`. The + intake plan defines the extended shape but the base plan's type definition + must be updated or a new type created. + +### Contradictions + +| Topic | Web-UI Plan | Intake UI Plan | Resolution Needed | +| ----------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CSS file structure | 1 file (`styles.css`) | 4 files (`variables/layout/components/animations.css`) | Adopt intake plan's 4-file split | +| JS file structure | 3 files | 5 files (adds `table.js`, `utils.js`) | Adopt intake plan's 5-file split | +| Asset serving | Separate routes (`/app.css`, `/app.js`) | Inlined via `__CSS__`/`__JS__` placeholders | Choose one (inline is simpler, matches design-deck reference) | +| `audit.ts` status | "UNCHANGED" (§5.3) | Modified with `UsageEvent` + `Projection` extension (§5) | Reclassify as modified | +| `LogsEvent` shape | `{ lines: LogLine[] }` | Extended with `agent`, `agentColor`, `timestamp` | Define `WebLogEntry` type extending `LogLine` | +| `POST /api/answer` body | `{ token, requestId, answers: AskSelection[] }` | `{ token, requestId, answers: [{ questionId, selectedOptions, customInput }] }` | Add `questionId` to answer array elements | +| Initial page state | §3.3: "state is NOT inlined into the HTML" | §3.1: topic extracted + injected via `__DATA__` placeholder | These are compatible: topic is static context, not pipeline state. But the web-ui plan's blanket "NOT inlined" statement is wrong — at minimum the topic IS inlined. | + +### Consistency Strengths + +Despite the issues above, the plans are remarkably well-grounded: + +- **Every file path** referenced in both plans exists in the codebase +- **Every type name** matches actual definitions (verified exhaustively) +- **Every function name** matches actual code +- **Line numbers** in `driver.ts` are exact (verified L81, L132, L160, etc.) +- **All 16 review findings** from the prior review are confirmed addressed +- **Architectural decisions** (raw `node:http`, SSE, Promise-blocking, IPC + protocol unchanged) are sound and consistent with reference implementations +- **The parent/child relationship** between plans is well-defined: web-ui + owns infrastructure, intake-ui owns visual layer + +### Severity Summary + +| Severity | Web-UI Plan | Intake Plan | Total | +| --------- | ------------------- | -------------------------------- | ------ | +| High | 0 | 1 (#4: scout completion summary) | **1** | +| Medium | 4 (#4, #6, #9, #12) | 5 (#2, #3, #5, #7, #10, #15) | **9** | +| Low | 8 | 8 | **16** | +| **Total** | **12** | **14** | **26** | + +The single **high severity** issue (intake #4) is a factual error about which +event contains scout findings — `phase_end.detail` is error info, not +findings. Scout findings are in `ToolKoanEvent.response` from +`koan_complete_step`. This must be corrected before implementation. diff --git a/plans/2026-03-16-preact-zustand-rewrite.md b/plans/2026-03-16-preact-zustand-rewrite.md new file mode 100644 index 0000000..0f5e70e --- /dev/null +++ b/plans/2026-03-16-preact-zustand-rewrite.md @@ -0,0 +1,1703 @@ +# Web UI: Preact + Zustand Rewrite + +> **Date:** 2026-03-16 +> **Scope:** Replace vanilla JS DOM-manipulation UI with Preact + Zustand. +> Hard rewrite of all client-side JS files. CSS files unchanged. Server-side +> `server.ts` modified for: on-demand esbuild bundling (`ensureBundle`), +> serving one bundled JS file instead of five, and one new denormalized SSE +> event (`intake-progress`). No tests required. + +--- + +## 1. Problem + +The web UI flashes empty and re-renders every ~2 seconds. Root cause: every +render function calls `clearEl(container)` to destroy the entire DOM tree, +then rebuilds from scratch. The server pushes 3–4 SSE events per 2-second +polling tick from independent timers. Each event triggers a full +teardown-rebuild cycle. The browser paints an empty frame between destruction +and reconstruction. + +This is a structural problem — the UI has no state diffing, no change +detection, and no concept of incremental updates. Fixing it requires either +bolting diffing onto the existing imperative DOM code, or adopting a +declarative view layer that handles diffing natively. + +--- + +## 2. Approach + +Replace the five vanilla JS files (`app.js`, `render.js`, `forms.js`, +`table.js`, `utils.js`) with a Preact + Zustand component tree. The mapping +to the re-frame mental model: + +| re-frame | Preact + Zustand | +| -------------- | --------------------------------------- | +| `app-db` | Zustand store | +| `reg-event-db` | SSE handler calling `store.setState(…)` | +| `subscribe` | `useStore(s => s.slice)` in components | +| hiccup views | JSX components | +| `reg-fx` | Side-effect functions (fetch, timers) | + +### 2.1 What changes + +- **Deleted:** `js/app.js`, `js/render.js`, `js/forms.js`, `js/table.js`, `js/utils.js` +- **New:** `js/store.js`, `js/sse.js`, `js/app.jsx`, `js/components/*.jsx`, `js/lib/utils.js` +- **Modified:** `html/index.html` (single script entry point), `server.ts` (serve bundled JS) +- **Unchanged:** All four CSS files, `server-types.ts`, `WebServerHandle` interface + +### 2.2 What stays the same + +- Server-side architecture: SSE push model, polling timers, `WebServerHandle` API — all untouched. +- CSS: All stylesheets kept as-is. Components use the same class names. +- SSE event protocol: Same event names, same JSON payloads — plus one new event (`intake-progress`). +- POST endpoints: `/api/answer`, `/api/review`, `/api/cancel` — same request/response shapes. + +--- + +## 3. Build Pipeline + +### 3.1 Tooling: esbuild + +The current UI serves raw `.js` files as separate `<script>` tags. Preact JSX +requires a build step. Use esbuild — zero-config, sub-100ms builds, single +dependency. Vite was not chosen because it requires a `vite.config.ts`, +dev-server infrastructure, and adds ~20 transitive packages; esbuild is a +single native binary with no config file. + +``` +npm install --save-dev esbuild preact zustand +``` + +Preact and zustand are devDependencies because they are bundled into a single +output file at build time — the server serves the bundle, not the raw +packages. At runtime the browser receives one self-contained file; `node_modules` +is irrelevant. + +### 3.2 Build command + +Add to `package.json` scripts: + +```json +{ + "scripts": { + "build:web": "esbuild src/planner/web/js/app.jsx --bundle --format=esm --jsx=automatic --jsx-import-source=preact --alias:react=preact/compat --alias:react-dom=preact/compat --outfile=src/planner/web/dist/app.js --minify" + } +} +``` + +- `--format=esm`: matches `<script type="module">` in the HTML; enables static imports in the bundle. +- `--jsx=automatic --jsx-import-source=preact`: tells esbuild to use Preact's JSX runtime (`preact/jsx-runtime`) instead of defaulting to `React.createElement`, which would produce a broken bundle. +- `--alias:react=preact/compat --alias:react-dom=preact/compat`: zustand v4 imports from `react` internally. Without these aliases, esbuild bundles the full React runtime (~17KB) alongside Preact — two competing VDOMs that crash at runtime because Preact's reconciler doesn't set up React's hook dispatcher. The aliases route zustand's React imports through Preact's compatibility layer. +- `--minify`: single pass, no separate step needed. + +> **Critical:** Both the npm script AND the `ensureBundle()` JS API call in +> `server.ts` must carry identical alias configuration. If either is missing, +> the resulting bundle will contain the full React runtime and crash on first +> `useStore()` call. + +Output: `src/planner/web/dist/app.js` — a single self-contained bundle. + +> **Wire into build:** Also add `build:web` to the existing `build` script: +> `"build": "npm run build:web && tsc --project tsconfig.build.json"`. +> This covers the test/CI path. The primary development path (pi loading +> the extension from source) is covered by the on-demand build below. + +### 3.3 On-demand bundle build in server.ts + +**Problem:** Pi loads extensions directly from source. There is no build step +in the developer workflow — the old JS files were committed to git and served +as-is. Adding a required manual `npm run build:web` before every `pi` session +would be a silent-failure footgun: `loadAsset` returns `""` on missing files, +the browser gets an empty JS file, the UI is a blank page, and there is no +error message. + +**Solution:** `server.ts` builds the bundle on-demand at server startup if +`dist/app.js` is missing or stale. Uses esbuild's JS API (already installed +as a devDependency). Adds ~100ms to the first server start; subsequent starts +skip the build if the bundle is newer than all source files. + +```ts +import * as esbuild from "esbuild"; + +// Alongside the existing loadAsset function: +async function ensureBundle(): Promise<void> { + const entryPoint = path.join(__dirname, "js", "app.jsx"); + const outfile = path.join(__dirname, "dist", "app.js"); + + // Skip build if bundle exists and is newer than all source files + try { + const bundleStat = await fs.stat(outfile); + const sourceDir = path.join(__dirname, "js"); + const sourceFiles = await fs.readdir(sourceDir, { recursive: true }); + let newest = 0; + for (const f of sourceFiles) { + const s = await fs.stat(path.join(sourceDir, String(f))); + if (s.mtimeMs > newest) newest = s.mtimeMs; + } + if (bundleStat.mtimeMs >= newest) return; // bundle is fresh + } catch { + // Bundle doesn't exist — build it + } + + await fs.mkdir(path.join(__dirname, "dist"), { recursive: true }); + await esbuild.build({ + entryPoints: [entryPoint], + bundle: true, + format: "esm", + jsx: "automatic", + jsxImportSource: "preact", + alias: { + react: "preact/compat", + "react-dom": "preact/compat", + }, + outfile, + minify: true, + }); +} +``` + +Call `ensureBundle()` at the top of `startWebServer()`, **before** the +static asset map is populated: + +```ts +export async function startWebServer( + epicDir: string, +): Promise<WebServerHandle> { + await ensureBundle(); // build bundle if missing/stale — ~100ms first time, skip thereafter + // ... rest of the function +} +``` + +This moves asset loading from module-init time into `startWebServer()` (which +is already async). The `STATIC_ASSETS` map construction moves inside the +function body, after `ensureBundle()` completes: + +```ts +const STATIC_ASSETS: Map<string, StaticAsset> = new Map([ + // CSS files unchanged + [ + "/static/css/variables.css", + { + content: loadAsset("css/variables.css"), + mimeType: "text/css; charset=utf-8", + }, + ], + [ + "/static/css/layout.css", + { + content: loadAsset("css/layout.css"), + mimeType: "text/css; charset=utf-8", + }, + ], + [ + "/static/css/components.css", + { + content: loadAsset("css/components.css"), + mimeType: "text/css; charset=utf-8", + }, + ], + [ + "/static/css/animations.css", + { + content: loadAsset("css/animations.css"), + mimeType: "text/css; charset=utf-8", + }, + ], + // Single bundled JS — guaranteed to exist after ensureBundle() + [ + "/static/js/app.js", + { + content: loadAsset("dist/app.js"), + mimeType: "application/javascript; charset=utf-8", + }, + ], +]); +``` + +### 3.4 Server changes — new `intake-progress` event + +The current design buries intake sub-phase information inside the `agents` +array (`AgentEntry.subPhase`). The client has to `.find()` the intake agent +and extract it — that's a normalized data structure forcing the UI to +reverse-engineer a derived fact. In an event-sourced model, events should +be denormalized: each event says exactly what changed. + +Add a new SSE event type `intake-progress` pushed alongside `agents` during +agent polling. The event carries two fields: + +``` +event: intake-progress +data: {"subPhase":"explore","intakeDone":false} +``` + +#### Server implementation + +In `server.ts`, add a `currentIntakeProgress` buffer and emit the event from +`startAgentPolling()`: + +```ts +// New buffered state (alongside currentPhase, currentStories, etc.) +let currentIntakeProgress: { subPhase: string | null; intakeDone: boolean } = { + subPhase: null, + intakeDone: false, +}; +``` + +In `startAgentPolling()`, after the existing `pushEvent("agents", ...)` call, +add: + +```ts +// Inside the polling interval callback, after pushEvent("agents", ...): +const intake = Array.from(agents.values()).find((a) => a.role === "intake"); +if (intake) { + const next = { + subPhase: intake.subPhase, + intakeDone: currentPhase !== "intake" && currentPhase !== null, + }; + // Only push if something actually changed — avoid redundant events + if ( + next.subPhase !== currentIntakeProgress.subPhase || + next.intakeDone !== currentIntakeProgress.intakeDone + ) { + currentIntakeProgress = next; + pushEvent("intake-progress", currentIntakeProgress); + } +} +``` + +In `replayState()`, add after the `agents` replay: + +```ts +if ( + currentIntakeProgress.subPhase !== null || + currentIntakeProgress.intakeDone +) { + write("intake-progress", currentIntakeProgress); +} +``` + +Also update `intakeDone` in the `pushPhase()` method so it stays accurate +even between polling ticks: + +```ts +// Inside handle.pushPhase(): +currentIntakeProgress = { + ...currentIntakeProgress, + intakeDone: phase !== "intake", +}; +pushEvent("intake-progress", currentIntakeProgress); +``` + +This is ~15 lines of server code. The `agents` event continues to carry +`subPhase` on `AgentEntry` for backwards compatibility (and because it's a +true property of the agent), but the client no longer needs to dig through +the array to find it. + +### 3.5 HTML changes + +```html +<!-- Before: 5 separate <script defer> tags; load order is implicit (utils before render before app) --> +<!-- After: 1 module script; load order is explicit via ES imports inside the bundle --> +<script>window.__DATA__ = /* __DATA__ */null;</script> +</head> +<body> + <div id="app"></div> + <!-- type="module" is inherently deferred — no DOMContentLoaded listener needed in app.jsx --> + <script type="module" src="/static/js/app.js"></script> +</body> +``` + +The `<div id="app">` replaces the entire static HTML structure (header, +phase-content, monitor). Preact renders everything. The old `index.html` had +static skeleton markup (pill-strip, agent table, `#phase-content`) that +`render.js` patched in-place; all of that is now component-owned. + +--- + +## 4. Store Design + +### 4.1 State shape + +```js +// js/store.js +import { create } from "zustand"; + +export const useStore = create((set) => ({ + // Server-pushed state + phase: null, // EpicPhase | null + stories: [], // Array<{ storyId, status }> + scouts: [], // Array<ScoutState> + agents: [], // Array<AgentEntry> + logs: [], // Array<LogLine> + subagent: null, // SubagentEvent | null + pendingInput: null, // { type, requestId, payload } | null + + // Denormalized intake progress — pushed by dedicated server event, + // not derived from agents array. PillStrip and ProgressBar subscribe + // to this directly without touching the agents list. + intakeProgress: { subPhase: null, intakeDone: false }, + + // Client-only state + notifications: [], // Array<{ id, message, level }> + pipelineEnd: null, // { success, summary } | null +})); +``` + +No actions, no reducers, no dispatch. SSE events are already the action +boundary — adding an action layer would be pure boilerplate. SSE handlers call +`useStore.setState()` directly with the new slice. `useStore.setState` is the +**static** method on the store object (callable from any module without React +context), distinct from the `set` closure available only inside `create()`. +Zustand merges shallowly — unchanged slices keep their reference identity, so +components subscribed to other slices don't re-render. + +### 4.2 Selector pattern + +Components subscribe to the minimum state they need: + +```jsx +// Only re-renders when scouts array reference changes — not on any other state update. +// Using useStore() with no selector (or destructuring the full store) would return a new +// object reference on every setState call, re-rendering every subscriber on every event. +const scouts = useStore((s) => s.scouts); + +// Only re-renders when phase changes +const phase = useStore((s) => s.phase); +``` + +When an `agents` SSE event arrives and calls `setState({ agents: [...] })`, +only components reading `s.agents` re-render. The scout cards, phase content, +and header are untouched. + +--- + +## 5. SSE Connection + +### 5.1 Connection module + +```js +// js/sse.js +import { useStore } from "./store.js"; + +export function connectSSE(token) { + const es = new EventSource(`/events?session=${encodeURIComponent(token)}`); + // useStore.setState is the static method — callable outside React/Preact component context. + // This is intentional: sse.js is not a component, it has no access to hooks. + const set = useStore.setState; + + const handlers = { + phase: (d) => + set({ + phase: d.phase, + ...(d.phase !== "intake" && { pendingInput: null }), + }), + // pendingInput is cleared on phase transition out of 'intake' because the form + // is only valid during the intake phase; a phase change means the server moved on. + "intake-progress": (d) => set({ intakeProgress: d }), + // Denormalized event from server — carries { subPhase, intakeDone } directly. + // No .find() on agents array needed; PillStrip/ProgressBar subscribe to this slice. + stories: (d) => set({ stories: d.stories }), + scouts: (d) => set({ scouts: d.scouts }), + agents: (d) => set({ agents: d.agents }), + logs: (d) => set({ logs: d.lines }), + subagent: (d) => set({ subagent: d }), + "subagent-idle": () => set({ subagent: null }), + "pipeline-end": (d) => + set((s) => ({ + phase: d.success ? "completed" : s.phase, + pipelineEnd: d, + })), + // pipeline-end uses the functional form of setState (s => ...) to read current phase + // before deciding whether to overwrite it — avoids a stale closure. + ask: (d) => + set({ + pendingInput: { + type: "ask", + requestId: d.requestId, + payload: d.questions, + }, + }), + review: (d) => + set({ + pendingInput: { + type: "review", + requestId: d.requestId, + payload: d.stories, + }, + }), + "ask-cancelled": (d) => + set((s) => + s.pendingInput?.requestId === d.requestId + ? { + pendingInput: null, + notifications: [ + ...s.notifications, + { + id: Date.now(), + message: + "The question was cancelled — the subagent has exited.", + level: "warning", + }, + ], + } + : {}, + ), + "review-cancelled": (d) => + set((s) => + s.pendingInput?.requestId === d.requestId + ? { + pendingInput: null, + notifications: [ + ...s.notifications, + { + id: Date.now(), + message: "The review was cancelled.", + level: "warning", + }, + ], + } + : {}, + ), + // Cancelled handlers use functional form to guard against clearing a *different* + // pending input that arrived between the cancel and the client processing it. + notification: (d) => + set((s) => ({ + notifications: [ + ...s.notifications, + { id: Date.now(), message: d.message, level: d.level }, + ], + })), + }; + + for (const [event, handler] of Object.entries(handlers)) { + es.addEventListener(event, (e) => { + try { + handler(JSON.parse(e.data)); + } catch (err) { + console.error(`[koan] SSE "${event}":`, err); + } + }); + } + + // Surface connection loss to the user — EventSource reconnects silently, + // but during the gap (3–30s) the UI is stale with no indicator. + es.onerror = () => + set((s) => ({ + notifications: [ + ...s.notifications, + { + id: Date.now(), + message: "Connection lost — reconnecting…", + level: "warning", + }, + ], + })); + + return es; +} +``` + +Every SSE event is a one-liner state update. The old `app.js` had 12 separate +handler functions that each mutated `state`, then called `renderPhase(state)` — +a full synchronous DOM teardown-rebuild on every event. Here, `setState` is +the only side effect; Preact reacts to state changes automatically. + +### 5.2 Heartbeat + +Stays as a standalone `setInterval` in the app entry point — it's a pure +side-effect, not state-driven. + +--- + +## 6. Component Tree + +### 6.1 Structure + +``` +App +├── ProgressBar +├── Header +│ ├── PillStrip +│ └── Timer +├── PhaseContent (conditional dispatch) +│ ├── Loading +│ ├── ContextAnalysis +│ ├── ScoutExploration +│ │ ├── ScoutCard (per scout) +│ │ └── CompletedContext +│ ├── Consolidation +│ ├── Execution +│ │ └── StoryRow (per story) +│ ├── Completion +│ ├── QuestionForm +│ │ └── QuestionCard (per question) +│ └── ReviewForm +│ └── ReviewStoryRow (per story) +├── AgentMonitor +│ └── AgentRow (per agent) +└── Notifications + └── Toast (per notification) +``` + +### 6.2 File layout + +``` +js/ + app.jsx # Entry point: render(<App />), connectSSE(), heartbeat + store.js # Zustand store + sse.js # SSE connection + lib/ + utils.js # formatTokens, formatElapsed, shortenModel + api.js # submitAnswers, submitReview (fetch wrappers) + components/ + App.jsx + ProgressBar.jsx + Header.jsx + PillStrip.jsx + Timer.jsx + PhaseContent.jsx # Conditional dispatch based on phase/pendingInput + AgentMonitor.jsx + AgentRow.jsx + Notifications.jsx + phases/ + Loading.jsx + ContextAnalysis.jsx + ScoutExploration.jsx + Consolidation.jsx + Execution.jsx + Completion.jsx + forms/ + QuestionForm.jsx + QuestionCard.jsx + ReviewForm.jsx +``` + +### 6.3 Entry point + +```jsx +// js/app.jsx +import { render } from "preact"; +import { App } from "./components/App.jsx"; +import { connectSSE } from "./sse.js"; + +const data = window.__DATA__; +// __DATA__ is injected by server.ts as: HTML_TEMPLATE.replace("/* __DATA__ */", safeInlineJSON({token, topic})) +// Fallback to query param supports direct URL navigation if __DATA__ injection fails. +const token = + data?.token || new URLSearchParams(location.search).get("session") || ""; + +// No DOMContentLoaded needed — <script type="module"> is deferred by spec. +render( + <App token={token} topic={data?.topic} />, + document.getElementById("app"), +); +connectSSE(token); + +// Heartbeat (pure side-effect, no state) +setInterval(() => { + fetch("/api/heartbeat", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ token }), + }).catch(() => {}); +}, 5000); +``` + +--- + +## 7. Key Components + +### 7.1 App — root layout shell + +```jsx +// components/App.jsx +import { ProgressBar } from "./ProgressBar.jsx"; +import { Header } from "./Header.jsx"; +import { PhaseContent } from "./PhaseContent.jsx"; +import { AgentMonitor } from "./AgentMonitor.jsx"; +import { Notifications } from "./Notifications.jsx"; + +export function App({ token, topic }) { + // The .app wrapper div is required — layout.css styles it as a flex column + // spanning the viewport. Without it, the fixed header / scrollable main / + // sticky footer layout breaks. + return ( + <div class="app"> + <ProgressBar /> + <Header /> + <main class="phase-content"> + <PhaseContent token={token} topic={topic} /> + </main> + <AgentMonitor /> + <Notifications /> + </div> + ); +} +``` + +### 7.2 Header — logo, pill strip, timer + +```jsx +// components/Header.jsx +import { PillStrip } from "./PillStrip.jsx"; +import { Timer } from "./Timer.jsx"; + +export function Header() { + // Mirrors the <header> structure from index.html exactly. + // .header-left groups the logo and pill strip on the left side; + // the timer floats right via layout.css flex rules. + return ( + <header class="header"> + <div class="header-left"> + <span class="logo">koan</span> + <PillStrip /> + </div> + <Timer /> + </header> + ); +} +``` + +### 7.3 PhaseContent — the render dispatcher + +This replaces the `renderPhase()` function in `render.js`. The old function +was called on every SSE event, called `clearEl(container)` unconditionally, +then rebuilt the entire DOM. This component re-renders only when `phase`, +`subagent`, or `pendingInput` change — and Preact diffs the result against the +existing DOM rather than replacing it. + +```jsx +// components/PhaseContent.jsx +import { useStore } from "../store.js"; + +export function PhaseContent({ token, topic }) { + const phase = useStore((s) => s.phase); + const pending = useStore((s) => s.pendingInput); + // Use the denormalized intake-progress event for ALL intake sub-phase + // decisions — both content dispatch and pill strip. This eliminates the + // dual-mechanism issue where PhaseContent used subagent.step (numeric, + // from the subagent event) while PillStrip used intakeProgress.subPhase + // (string, from intake-progress). Single source of truth. + const { subPhase } = useStore((s) => s.intakeProgress); + + // Show loading only before the pipeline has started (phase is null). + // Once phase is set, always render phase-appropriate content regardless of + // subagent state — the server calls clearSubagent() between stories, which + // sets subagent to null while phase is still "executing". Gating on subagent + // here would flash <Loading> on every story boundary. + if (!phase) return <Loading topic={topic} />; + + // Forms take priority over phase content — mirrors the guard in renderPhase(). + // key={pending.requestId} forces remount on new request, resetting local + // form state (selections). Without it, if ask-cancelled + new ask arrive in + // the same render batch, useState initializer doesn't re-run and stale + // selections from the previous question set could be submitted. + if (pending?.type === "ask") + return <QuestionForm key={pending.requestId} token={token} />; + if (pending?.type === "review") + return <ReviewForm key={pending.requestId} token={token} />; + + if (phase === "intake") { + // Dispatch on intakeProgress.subPhase (string) instead of subagent.step + // (numeric). Both derive from the same server-side projection.step, but + // using the denormalized event keeps one mechanism for all intake rendering. + if (subPhase === "context" || !subPhase) return <ContextAnalysis />; + if (subPhase === "explore") return <ScoutExploration />; + return <Consolidation />; // 'questions' or 'spec' + } + + if (phase === "completed") return <Completion />; + + return <Execution phase={phase} />; +} +``` + +### 7.4 ScoutExploration — keyed list rendering + +```jsx +// components/phases/ScoutExploration.jsx +import { useStore } from "../../store.js"; + +const COLORS = [ + "var(--blue)", + "var(--purple)", + "var(--orange)", + "var(--yellow)", + "var(--pink)", +]; + +export function ScoutExploration() { + const scouts = useStore((s) => s.scouts); + + return ( + <div class="phase-inner"> + <p class="phase-status"> + Exploring your codebase with {scouts.length} scout + {scouts.length !== 1 ? "s" : ""}… + </p> + {scouts.map((scout, i) => ( + // key={scout.id} gives Preact stable identity per scout across re-renders. + // Without it Preact uses positional index — adding/removing a scout would + // patch the wrong card and could flash or corrupt running-state styling. + <ScoutCard + key={scout.id} + scout={scout} + color={COLORS[i % COLORS.length]} + /> + ))} + <CompletedContext scouts={scouts} /> + </div> + ); +} + +function ScoutCard({ scout, color }) { + const cls = + scout.status === "completed" + ? "card card-done" + : scout.status === "failed" + ? "card card-failed" + : "card card-running"; + const symbol = + scout.status === "completed" ? "✓" : scout.status === "failed" ? "✗" : "●"; + + return ( + // Note: Preact uses `class`, not React's `className`. + <div + class={cls} + style={ + scout.status === "running" ? { borderLeftColor: color } : undefined + } + > + <div class="card-header"> + <span + class={`agent-status-${scout.status === "completed" ? "done" : scout.status}`} + > + {symbol} + </span> + <span + class="card-title" + style={scout.status === "running" ? { color } : undefined} + > + {scout.id} + </span> + <span class="card-role">{scout.role}</span> + </div> + <div class="card-body"> + {scout.status === "completed" ? ( + scout.completionSummary + ) : scout.status === "failed" ? ( + <span style={{ color: "var(--red)" }}>Scout failed</span> + ) : ( + <span style={{ color: "var(--text-dim)" }}> + {scout.lastAction || "Starting…"} + </span> + )} + </div> + </div> + ); +} + +function CompletedContext({ scouts }) { + const completed = scouts.filter( + (s) => s.status === "completed" && s.completionSummary, + ); + if (completed.length === 0) return null; + + return ( + <> + <div class="context-section-label">CONTEXT SO FAR</div> + <ul class="context-items"> + {completed.map((s) => ( + // key here too — same reason as ScoutCard; list identity matters for diffing. + <li key={s.id}> + {s.id}: {s.completionSummary?.slice(0, 100)} + {(s.completionSummary?.length ?? 0) > 100 ? "…" : ""} + </li> + ))} + </ul> + </> + ); +} +``` + +### 7.5 AgentMonitor — derived state in component + +```jsx +// components/AgentMonitor.jsx +import { useStore } from "../store.js"; +import { formatTokens } from "../lib/utils.js"; + +export function AgentMonitor() { + const agents = useStore((s) => s.agents); + // Derived values computed inline — no separate selector or memoisation needed + // at this scale. Preact only runs this when agents reference changes. + const running = agents.filter((a) => a.status === "running").length; + const done = agents.filter((a) => a.status === "completed").length; + const failed = agents.filter((a) => a.status === "failed").length; + const sent = agents.reduce((s, a) => s + (a.tokensSent || 0), 0); + const recv = agents.reduce((s, a) => s + (a.tokensReceived || 0), 0); + + return ( + <footer class="monitor"> + <div class="agent-table-header"> + <span class="monitor-label">Subagents</span> + <div class="agent-badges"> + {running > 0 && <span class="badge active">{running}</span>} + {done > 0 && <span class="badge done">{done}</span>} + {failed > 0 && <span class="badge failed">{failed}</span>} + </div> + <span class="token-totals"> + {sent > 0 || recv > 0 + ? `↑${formatTokens(sent)} ↓${formatTokens(recv)}` + : ""} + </span> + </div> + <table class="agent-table"> + <thead> + <tr> + <th class="col-status"></th> + <th class="col-agent">agent</th> + <th class="col-model">model</th> + <th class="col-parent">parent</th> + <th class="col-tokens">↑ sent</th> + <th class="col-tokens">↓ recv</th> + <th class="col-doing">doing</th> + </tr> + </thead> + <tbody> + {agents.map((a) => ( + <AgentRow key={a.id} agent={a} /> + ))} + </tbody> + </table> + </footer> + ); +} +``` + +### 7.6 QuestionForm — local component state for selections + +```jsx +// components/forms/QuestionForm.jsx +import { useState } from "preact/hooks"; +// Hooks are in 'preact/hooks', not 'preact' — different import path from React. +import { useStore } from "../../store.js"; +import { submitAnswers } from "../../lib/api.js"; + +export function QuestionForm({ token }) { + const { requestId, payload: questions } = useStore((s) => s.pendingInput); + // selections is local UI state — it doesn't belong in the global store because + // it's ephemeral form state that only matters while this component is mounted. + const [selections, setSelections] = useState(() => + new Array(questions.length).fill(null), + ); + + // Check both non-null and non-empty — acceptDefaults() can produce + // { selectedOptions: [] } for questions with empty options arrays, + // which is truthy but represents no actual answer. + const allAnswered = selections.every( + (s) => s !== null && (s.selectedOptions?.length > 0 || s.customInput), + ); + const answeredCount = selections.filter( + (s) => s !== null && (s.selectedOptions?.length > 0 || s.customInput), + ).length; + + function updateSelection(index, selection) { + setSelections((prev) => { + const next = [...prev]; + next[index] = selection; + return next; + }); + } + + function acceptDefaults() { + const answers = questions.map((q) => { + const idx = q.recommended ?? 0; + const label = q.options[idx]?.label; + return { questionId: q.id, selectedOptions: label ? [label] : [] }; + }); + submitAnswers({ token, requestId, answers }); + } + + function submit() { + const answers = questions.map((q, i) => ({ + questionId: q.id, + ...(selections[i] || { selectedOptions: [] }), + })); + submitAnswers({ token, requestId, answers }); + // pendingInput is cleared by the server's 'ask-cancelled' event or the next + // phase transition — the component does not clear it directly. + } + + return ( + <div class="phase-inner"> + <h2 class="phase-heading">A few questions to shape the plan</h2> + <div class="count-progress"> + {answeredCount} of {questions.length} answered + </div> + + {questions.map((q, i) => ( + <QuestionCard + key={q.id} + question={q} + index={i} + total={questions.length} + selection={selections[i]} + onSelect={(sel) => updateSelection(i, sel)} + /> + ))} + + <div class="form-actions"> + <button class="btn btn-secondary" onClick={acceptDefaults}> + Accept All Defaults + </button> + <button + class="btn btn-primary" + disabled={!allAnswered} + onClick={submit} + > + Submit Answers + </button> + {!allAnswered && ( + <span class="form-helper"> + {questions.length - answeredCount} remaining + </span> + )} + </div> + </div> + ); +} +``` + +### 7.7 Completion — pipeline end state + +```jsx +// components/phases/Completion.jsx +import { useStore } from "../../store.js"; + +export function Completion() { + const pipelineEnd = useStore((s) => s.pipelineEnd); + + return ( + <div class="phase-inner"> + <p class="phase-status"> + {pipelineEnd?.success ? "Pipeline complete ✓" : "Pipeline failed"} + </p> + {pipelineEnd?.summary && ( + <div class="summary-list"> + <div class="summary-item"> + <span class={pipelineEnd.success ? "icon-done" : "icon-pending"}> + {pipelineEnd.success ? "✓" : "✗"} + </span> + <span>{pipelineEnd.summary}</span> + </div> + </div> + )} + </div> + ); +} +``` + +### 7.8 ReviewForm — story approval/skip + +```jsx +// components/forms/ReviewForm.jsx +import { useState } from "preact/hooks"; +import { useStore } from "../../store.js"; +import { submitReview } from "../../lib/api.js"; + +export function ReviewForm({ token }) { + const { requestId, payload: stories } = useStore((s) => s.pendingInput); + // Track which stories are approved — all approved by default (matches old UI). + // Using a Set of storyIds for O(1) toggle; convert to arrays on submit. + const [approved, setApproved] = useState( + () => new Set(stories.map((s) => s.storyId)), + ); + + function toggle(storyId) { + setApproved((prev) => { + const next = new Set(prev); + if (next.has(storyId)) next.delete(storyId); + else next.add(storyId); + return next; + }); + } + + function approveAll() { + setApproved(new Set(stories.map((s) => s.storyId))); + } + + function submit() { + const approvedList = stories + .filter((s) => approved.has(s.storyId)) + .map((s) => s.storyId); + const skippedList = stories + .filter((s) => !approved.has(s.storyId)) + .map((s) => s.storyId); + submitReview({ + token, + requestId, + approved: approvedList, + skipped: skippedList, + }); + } + + return ( + <div class="phase-inner"> + <h2 class="phase-heading">Review story sketches</h2> + <p class="phase-status">Review stories before execution begins.</p> + + {stories.map((story) => ( + <div + key={story.storyId} + class={`review-story ${approved.has(story.storyId) ? "checked" : ""}`} + onClick={() => toggle(story.storyId)} + > + <div class="review-story-checkbox" /> + <span class="review-story-id">{story.storyId}</span> + <span class="review-story-title"> — {story.title}</span> + </div> + ))} + + <div class="form-actions"> + <button class="btn btn-secondary" onClick={approveAll}> + Approve All + </button> + <button class="btn btn-primary" onClick={submit}> + Submit + </button> + </div> + </div> + ); +} +``` + +`api.js` must export both fetch wrappers: + +```js +// js/lib/api.js +export async function submitAnswers({ token, requestId, answers }) { + const resp = await fetch("/api/answer", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ token, requestId, answers }), + }); + if (!resp.ok) console.error("Failed to submit answers:", await resp.text()); +} + +export async function submitReview({ token, requestId, approved, skipped }) { + const resp = await fetch("/api/review", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ token, requestId, approved, skipped }), + }); + if (!resp.ok) console.error("Failed to submit review:", await resp.text()); +} +``` + +### 7.9 Notifications — auto-dismiss with cleanup + +```jsx +// components/Notifications.jsx +import { useEffect } from "preact/hooks"; +import { useStore } from "../store.js"; + +export function Notifications() { + const notifications = useStore((s) => s.notifications); + + // Each notification gets its own dismiss timer, keyed by the newest + // notification's ID. Dependency is on the specific ID, not the array + // length — this avoids the race where rapid-fire notifications keep + // resetting a single timer and none ever dismiss. + // Removal is by ID (filter), not position (slice) — concurrent timer + // callbacks can't accidentally discard the wrong notification. + useEffect(() => { + if (notifications.length === 0) return; + const newest = notifications[notifications.length - 1]; + const timer = setTimeout(() => { + useStore.setState((s) => ({ + notifications: s.notifications.filter((n) => n.id !== newest.id), + })); + }, 5000); + return () => clearTimeout(timer); + }, [notifications[notifications.length - 1]?.id]); + + return ( + <div id="notifications"> + {notifications.map((n) => ( + <div key={n.id} class={`notification ${n.level}`}> + {n.message} + </div> + ))} + </div> + ); +} +``` + +### 7.10 Timer — self-updating via useEffect + +```jsx +// components/Timer.jsx +import { useState, useEffect } from "preact/hooks"; +import { useStore } from "../store.js"; +import { formatElapsed } from "../lib/utils.js"; + +export function Timer() { + const startedAt = useStore((s) => s.subagent?.startedAt); + const [now, setNow] = useState(Date.now()); + + useEffect(() => { + if (!startedAt) return; + // interval is created per startedAt value and cleaned up when startedAt changes + // (e.g. new subagent starts) or component unmounts. Without the cleanup return, + // each new subagent would accumulate an additional interval that never stops. + const id = setInterval(() => setNow(Date.now()), 1000); + return () => clearInterval(id); + }, [startedAt]); + + if (!startedAt) return <span class="timer">—</span>; + return <span class="timer">{formatElapsed(now - startedAt)}</span>; +} +``` + +### 7.11 PillStrip — intake progress pills + +```jsx +// components/PillStrip.jsx +import { useStore } from "../store.js"; + +const PILLS = ["context", "explore", "questions", "spec"]; + +export function PillStrip() { + // Reads from the denormalized intake-progress event — no .find() on agents. + // Only re-renders when subPhase or intakeDone actually change. + const { subPhase, intakeDone } = useStore((s) => s.intakeProgress); + const activeIdx = PILLS.indexOf(subPhase || ""); + + return ( + <div id="pill-strip"> + {PILLS.map((pill, i) => { + // pill is done if intake is complete or it comes before the active step + const cls = + intakeDone || i < activeIdx + ? "pill done" + : i === activeIdx + ? "pill active" + : "pill pending"; + return ( + <span key={pill} class={cls} data-pill={pill}> + {pill} + </span> + ); + })} + </div> + ); +} +``` + +### 7.12 ProgressBar — progress fill width + +```jsx +// components/ProgressBar.jsx +import { useStore } from "../store.js"; + +const PILLS = ["context", "explore", "questions", "spec"]; + +export function ProgressBar() { + // Same denormalized source as PillStrip — no agents array dependency. + const { subPhase, intakeDone } = useStore((s) => s.intakeProgress); + const activeIdx = PILLS.indexOf(subPhase || ""); + // donePills counts completed steps; 4 when all done, else however many precede the active pill + const donePills = intakeDone ? 4 : Math.max(0, activeIdx); + const pct = (donePills / 4) * 100; + + return ( + <div class="progress-bar"> + <div class="progress-fill" style={{ width: pct + "%" }} /> + </div> + ); +} +``` + +### 7.13 Loading — initial loading screen + +```jsx +// components/phases/Loading.jsx +export function Loading({ topic }) { + return ( + // Inline styles match renderLoading()'s imperative style assignments exactly + <div + class="phase-inner" + style={{ + display: "flex", + flexDirection: "column", + alignItems: "center", + paddingTop: "80px", + }} + > + <div class="spinner" /> + <p class="phase-status" style={{ marginTop: "16px" }}> + Initializing... + </p> + {topic && ( + <div class="topic-card"> + <div class="topic-label">YOUR REQUEST</div> + <div class="topic-text">{topic}</div> + </div> + )} + </div> + ); +} +``` + +### 7.14 ContextAnalysis — conversation reading screen + +```jsx +// components/phases/ContextAnalysis.jsx +import { useStore } from "../../store.js"; + +export function ContextAnalysis() { + const logs = useStore((s) => s.logs); + + return ( + <div class="phase-inner"> + <p class="phase-status"> + Reading your conversation to understand the task... + </p> + {logs.length > 0 && ( + // Last 4 log lines — same slice as renderContextAnalysis() + <div class="activity-feed"> + {logs.slice(-4).map((line, i) => ( + <div key={i} class="activity-line"> + <span class="activity-tool">{line.tool}</span> + <span>{line.summary || ""}</span> + </div> + ))} + </div> + )} + </div> + ); +} +``` + +### 7.15 Consolidation — spec writing screen + +```jsx +// components/phases/Consolidation.jsx +import { useStore } from "../../store.js"; + +export function Consolidation() { + const logs = useStore((s) => s.logs); + const scouts = useStore((s) => s.scouts); + // Two separate selectors — logs and scouts update independently; subscribing + // to both individually avoids unnecessary re-renders from unrelated state changes. + const scoutCount = scouts.length; + + return ( + <div class="phase-inner"> + <p class="phase-status">Writing project specification...</p> + <div class="summary-list"> + {/* context extraction is always complete by the time consolidation runs */} + <div class="summary-item"> + <span class="icon-done">✓</span> + <span>Context extracted from conversation</span> + </div> + {scoutCount > 0 && ( + <div class="summary-item"> + <span class="icon-done">✓</span> + <span> + {scoutCount} scout{scoutCount !== 1 ? "s" : ""} explored the + codebase + </span> + </div> + )} + <div class="summary-item"> + <span class="icon-pending">◌</span> + <span>Writing decisions.md...</span> + </div> + </div> + {logs.length > 0 && ( + // Last 3 log lines — same slice as renderConsolidation() + <div class="activity-feed" style={{ marginTop: "16px" }}> + {logs.slice(-3).map((line, i) => ( + <div key={i} class="activity-line"> + <span class="activity-tool">{line.tool}</span> + <span>{line.summary || ""}</span> + </div> + ))} + </div> + )} + </div> + ); +} +``` + +### 7.16 Execution — story execution screen + +```jsx +// components/phases/Execution.jsx +import { useStore } from "../../store.js"; + +export function Execution({ phase }) { + const stories = useStore((s) => s.stories); + + const phaseLabel = + phase === "decomposition" + ? "Decomposing into stories..." + : phase === "review" + ? "Awaiting spec review..." + : phase === "executing" + ? "Executing stories..." + : `Phase: ${phase}`; + + return ( + <div class="phase-inner"> + <p class="phase-status">{phaseLabel}</p> + {stories.length > 0 && ( + <div class="summary-list"> + {stories.map((story) => { + // Active statuses get a filled bullet; terminal statuses get checkmark or dash + const icon = + story.status === "done" + ? "✓" + : story.status === "skipped" + ? "—" + : story.status === "executing" || + story.status === "planning" || + story.status === "verifying" + ? "●" + : "◌"; + const iconCls = + story.status === "done" ? "icon-done" : "icon-pending"; + return ( + <div key={story.storyId} class="summary-item"> + <span class={iconCls}>{icon}</span> + <span>{story.storyId}</span> + <span class="review-story-title"> [{story.status}]</span> + </div> + ); + })} + </div> + )} + </div> + ); +} +``` + +### 7.17 QuestionCard — single question with option selection + +```jsx +// components/forms/QuestionCard.jsx +import { useState } from "preact/hooks"; + +export function QuestionCard({ question, index, total, selection, onSelect }) { + // Local state for selection and the free-text "Other" field — + // ephemeral UI interaction, not global concern. + const [selectedIndexes, setSelectedIndexes] = useState(() => new Set()); + const [otherInput, setOtherInput] = useState(""); + + const options = question.options || []; + const allOptions = options.map((o) => o.label); + // "Other (type your own)" is detected by exact label match, same as forms.js + const otherIndex = allOptions.findIndex((l) => l === "Other (type your own)"); + + function buildSelection(indexes, otherVal) { + if (question.multi) { + const selectedOptions = []; + let customInput; + for (const idx of indexes) { + if (idx === otherIndex) { + const val = otherVal.trim(); + if (val) customInput = val; + } else { + selectedOptions.push(allOptions[idx]); + } + } + return customInput !== undefined + ? { selectedOptions, customInput } + : { selectedOptions }; + } else { + const idx = [...indexes][0]; + if (idx === otherIndex) { + const val = otherVal.trim(); + return val ? { selectedOptions: [], customInput: val } : null; + } + return { selectedOptions: [allOptions[idx]] }; + } + } + + function handleSelect(i) { + let next; + if (question.multi) { + // Toggle in multi-select + next = new Set(selectedIndexes); + if (next.has(i)) next.delete(i); + else next.add(i); + } else { + // Replace in single-select + next = new Set([i]); + } + setSelectedIndexes(next); + onSelect(buildSelection(next, otherInput)); + } + + function handleOtherInput(e) { + const val = e.target.value; + setOtherInput(val); + // Re-report selection with updated free-text whenever the input changes + if (selectedIndexes.has(otherIndex)) { + onSelect(buildSelection(selectedIndexes, val)); + } + } + + const showOtherInput = otherIndex !== -1 && selectedIndexes.has(otherIndex); + + return ( + <div class="question-card"> + <div class="question-header"> + {index + 1}/{total} · {question.id} + </div> + {question.multi && ( + <div class="question-multi-hint">select all that apply</div> + )} + <div class="question-text">{question.question}</div> + <div class="options-list"> + {allOptions.map((label, i) => { + const isSelected = selectedIndexes.has(i); + // recommended badge shown on default option, but never on the Other option + const isRecommended = i === question.recommended && i !== otherIndex; + return ( + <div + key={i} + class={`option${i === otherIndex ? " option-other" : ""}${isSelected ? " selected" : ""}`} + onClick={() => handleSelect(i)} + > + <span class={question.multi ? "checkbox-dot" : "radio-dot"} /> + <span class="option-text">{label}</span> + {isRecommended && ( + <span class="recommended-badge">recommended</span> + )} + </div> + ); + })} + {/* other-input is always in the DOM; visible class controls display */} + <input + class={`other-input${showOtherInput ? " visible" : ""}`} + type="text" + placeholder="Type your answer..." + value={otherInput} + onInput={handleOtherInput} + /> + </div> + </div> + ); +} +``` + +### 7.18 AgentRow — single agent table row + +```jsx +// components/AgentRow.jsx +import { shortenModel, formatTokens } from "../lib/utils.js"; + +export function AgentRow({ agent }) { + const statusSymbol = + agent.status === "running" ? "●" : agent.status === "completed" ? "✓" : "✗"; + const statusCls = + agent.status === "running" + ? "agent-status-running" + : agent.status === "completed" + ? "agent-status-done" + : "agent-status-failed"; + const nameCls = + agent.status === "running" + ? "agent-name-running" + : agent.status === "completed" + ? "agent-name-done" + : "agent-name-failed"; + + const actions = agent.recentActions || []; + // Show up to 5 stacked recent actions with agent-doing-lines/agent-doing-line + // CSS classes — preserves the scrolling action trail from the current table.js. + // Last line is highlighted via .agent-doing-line:last-child CSS rule. + const start = Math.max(0, actions.length - 5); + + return ( + <tr> + <td class={`col-status ${statusCls}`}>{statusSymbol}</td> + <td class={nameCls}>{agent.name || agent.id}</td> + <td class="col-model agent-model-cell">{shortenModel(agent.model)}</td> + <td class="col-parent agent-parent-cell">{agent.parent || "—"}</td> + <td class="col-tokens agent-tokens-cell"> + {formatTokens(agent.tokensSent || 0)} + </td> + <td class="col-tokens agent-tokens-cell"> + {formatTokens(agent.tokensReceived || 0)} + </td> + <td class="col-doing"> + {actions.length > 0 ? ( + <div class="agent-doing-lines"> + {actions.slice(start).map((action, i) => ( + <div key={i} class="agent-doing-line"> + {action} + </div> + ))} + </div> + ) : agent.status === "running" ? ( + <span class="agent-doing-line">initializing...</span> + ) : null} + </td> + </tr> + ); +} +``` + +--- + +## 8. Migration Sequence + +The rewrite is a clean swap — there is no incremental migration path because +the current code is imperative DOM manipulation that operates on hard-coded +element IDs (`#phase-content`, `#agent-tbody`, `#pill-strip`). These IDs are +shared global mutable state; there is no component boundary to isolate and +replace piecemeal. The steps are ordered to maintain a working build at each +commit. + +### Step 1: Add build tooling + +- Install `esbuild`, `preact`, `zustand` as devDependencies. +- Add `build:web` script to `package.json`. +- Add `src/planner/web/dist/` to `.gitignore` (note: the existing `dist/` + pattern already covers this, but an explicit entry is clearer). +- Wire `build:web` into the existing `build` script (run before tsc). +- Add `ensureBundle()` to `server.ts` (§3.3) — this is the primary mechanism; + the npm script is a secondary path for CI/tests. + +### Step 2: Write store + SSE + +- Create `js/store.js` and `js/sse.js`. +- Create `js/lib/utils.js` (copy pure functions from old `utils.js`). +- Create `js/lib/api.js` (extract `submitAnswers`, `submitReview` fetch calls). + +### Step 3: Write components + +- Create all component files from §6.2 file layout. +- Create `js/app.jsx` entry point. +- Verify build with `npm run build:web`. + +### Step 4: Swap serving layer + +- Add `ensureBundle()` function and move `STATIC_ASSETS` inside + `startWebServer()` (§3.3). +- Update `STATIC_ASSETS` to serve `dist/app.js` instead of individual JS files. +- Add `intake-progress` event to `server.ts`: buffered state, emission in + `startAgentPolling()` and `pushPhase()`, replay in `replayState()` (§3.4). +- Update `index.html` to use single `<div id="app">` + module script. +- Remove old JS files: `app.js`, `render.js`, `forms.js`, `table.js`, + `utils.js` from `js/`. + +### Step 5: Verify and clean up + +- Full build: `npm run build:web && npm run build`. +- Manual test: run koan pipeline, verify no flash, verify all phases render, + verify question form and review form work, verify agent table updates. +- Remove any dead code. + +--- + +## 9. Dependency Rationale + +| Package | Size (bundled) | Purpose | +| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `preact` | ~3KB gzip (core) | VDOM diffing, JSX components. React API in 3KB. | +| `preact/compat` | ~5KB gzip | React compatibility layer — required because zustand v4 imports from `react`. Aliased via esbuild `--alias:react=preact/compat`. | +| `zustand` | ~1KB gzip | Centralized store with selector subscriptions. Pinned to v4 — v5 imports React at module level, incompatible with Preact without a compat layer. | +| `esbuild` | native binary | JSX→JS bundling. Sub-100ms builds. Dev-only. | + +Total client-side bundle: ~16KB gzip (44KB raw). The `preact/compat` shim and +`use-sync-external-store` polyfill account for ~8KB of the overhead. To reduce +to ~8KB gzip: replace `import { create } from 'zustand'` with +`import { createStore } from 'zustand/vanilla'` and write a custom `useStore` +hook using `preact/hooks` — eliminates the React compat layer entirely. + +Alternatives considered: + +- **SolidJS**: Closer to re-frame's signal model, but smaller ecosystem and + less familiar JSX semantics (no re-render, different mental model for + conditional rendering). +- **Vanilla + DOM patching**: Would avoid dependencies but requires hand-rolling + what Preact gives for free. More code, more bugs, same result. +- **React**: Same API as Preact but 10× larger. No benefit for this use case. + +--- + +## 10. What This Fixes + +The flash disappears because: + +1. **Selective re-rendering**: Each component subscribes to its own state + slice via `useStore(s => s.X)`. An `agents` event only re-renders + `AgentMonitor`. Scout cards, phase content, and the header are untouched. + +2. **VDOM diffing**: When a component does re-render, Preact diffs the new + virtual DOM against the current real DOM and patches only changed nodes. + The DOM is never torn down and rebuilt. + +3. **Keyed lists**: `scouts.map(s => <ScoutCard key={s.id} .../>)` gives + Preact stable identity for list items. Adding/removing a scout patches + one DOM node, not the entire list. + +4. **No `clearEl()`**: The concept doesn't exist. Components return what they + want to render; Preact figures out what changed. + +--- + +## 11. Gotchas / Implementation Notes + +1. **`class` not `className`**: Preact uses standard HTML attribute names. + Unlike React, `class` is correct in JSX. `className` works too (Preact + accepts both) but `class` is idiomatic and matches the existing CSS. + +2. **Hook import path**: Always `import { useState, useEffect, … } from 'preact/hooks'`, + not from `'preact'`. Importing hooks from the wrong path gives a silent + undefined and cryptic runtime errors. + +3. **`render` import**: `import { render } from 'preact'` — not `preact/compat`. + `preact/compat` is only needed when bridging React libraries; this project + uses no React-ecosystem packages. + +4. **Fragment syntax**: `<>…</>` requires `--jsx=automatic`. With the classic + transform you'd need `import { Fragment } from 'preact'` and `<Fragment>`. + The build command uses `--jsx=automatic` — fragments just work. + +5. **Zustand shallow merge**: `setState({ agents: newArray })` merges the top + level only. Nested object mutations (e.g. `pendingInput.payload`) are not + detected. Always replace the whole slice: `setState({ pendingInput: { …newValue } })`. + +6. **`useStore.setState` vs `set`**: The `set` function inside `create((set) => …)` + is a closure only accessible during store initialisation. Everywhere else + (SSE handlers, `useEffect` callbacks, event handlers) use the static + `useStore.setState`. They are functionally equivalent; the static form is + just the external API. + +7. **`ensureBundle()` handles missing/stale bundles**: The `ensureBundle()` + function in `server.ts` builds the bundle on-demand if `dist/app.js` is + missing or older than any source file in `js/`. No manual `npm run build:web` + is needed during development. The npm script is a secondary path for CI/tests. + Note: `STATIC_ASSETS` must be populated **after** `ensureBundle()` completes, + so the map construction moves inside `startWebServer()` (it was at module + init scope in the old code). + +8. **esbuild does not type-check**: `npm run build:web` succeeds even with + TypeScript errors in JSX files. Run `tsc --noEmit` (the existing `check` + script) separately if type safety on the client side matters. + +9. **No `DOMContentLoaded` needed**: `<script type="module">` is deferred by + the HTML spec — it executes after the document is parsed. Remove any + `document.addEventListener('DOMContentLoaded', …)` wrappers from `app.jsx`. + +10. **SSE reconnect replay**: The server's `replayState()` sends all current + state on reconnect. The Zustand store will receive these as fresh `setState` + calls — components will re-render with replayed state, which is correct. + No special reconnect handling needed in the client. diff --git a/plans/2026-03-21-epic-brief.md b/plans/2026-03-21-epic-brief.md new file mode 100644 index 0000000..4d814bf --- /dev/null +++ b/plans/2026-03-21-epic-brief.md @@ -0,0 +1,736 @@ +# Epic Brief Phase + +Insert an epic brief generation phase between intake and decomposition, with +an IPC-based artifact review mechanism and markdown-rendering web UI. + +--- + +## Design Decisions + +### The epic brief is a product-level anchor artifact + +The brief captures the **what and why** — problem, context, goals, constraints. +It deliberately excludes UI flows, technical architecture, and implementation +details. This keeps it compact, stable, and reusable as a correctness standard +for all downstream phases. + +The brief is the most-referenced artifact in the pipeline. Every phase from +decomposition through execution can consult it to stay aligned with the +original problem. + +### "Accept" is verbatim text, not a special parameter + +The artifact review response is always a single text string. When the user +clicks "Accept" in the web UI, the response sent back is literally `"Accept"`. +When the user types feedback, the response is their text. + +This keeps the tool interface uniform and agile. The LLM processes both cases +the same way: read the response, decide whether to revise or proceed. No +branching protocol, no special fields. + +### Artifact review is a reusable IPC mechanism + +The review tool is not epic-brief-specific. It presents any markdown artifact +for review and collects free-form feedback. Future phases (e.g., core-flows +equivalent, tech-plan equivalent) use the same mechanism: write artifact → +invoke review → process feedback → loop or proceed. + +### Downstream phases read files, not embedded content + +Instead of embedding context.md or brief.md content in prompts, agents receive +a nudge to read these files themselves. This keeps prompts stable across +artifact evolution and gives agents the current file content (not a snapshot +from spawn time). + +### Client-side markdown rendering + +The web UI renders raw markdown client-side. No backend pre-parsing, no HTML +generation on the server. This keeps the backend simple and lets the rendering +evolve independently (e.g., adding mermaid support later without server changes). + +--- + +## Changes + +### 1. IPC Protocol — New "artifact-review" message type + +**File: `src/planner/lib/ipc.ts`** + +Add a third discriminated union member alongside `ask` and `scout-request`: + +```typescript +interface ArtifactReviewPayload { + artifactPath: string; // relative path within epic dir (e.g., "brief.md") + content: string; // raw markdown content of the artifact + description?: string; // optional context for the reviewer +} + +interface ArtifactReviewResponse { + id: string; + respondedAt: string; + feedback: string; // "Accept" or free-form text +} + +interface ArtifactReviewIpcFile { + type: "artifact-review"; + id: string; + createdAt: string; + payload: ArtifactReviewPayload; + response: ArtifactReviewResponse | null; +} +``` + +Update `IpcFile` union: `AskIpcFile | ScoutIpcFile | ArtifactReviewIpcFile`. + +Add factory: `createArtifactReviewRequest(payload)` → `ArtifactReviewIpcFile`. + +**Update `pollIpcUntilResponse`** — add a third exit condition for the new type: + +```typescript +if ( + current.type === "artifact-review" && + current.response !== null && + current.id === ipc.id +) { + outcome = "answered"; + finalIpc = current; + break; +} +``` + +This sits alongside the existing `"ask"` and `"scout-request"` conditions. +Without it, the subagent poll loop never detects the parent's response and +blocks indefinitely. + +### 2. LLM Tool — `koan_review_artifact` + +**New file: `src/planner/tools/review-artifact.ts`** + +Tool the LLM calls to present a written artifact for human review. + +**Parameters:** + +```typescript +{ + path: string; // file path of the artifact to review + description?: string; // optional context for the reviewer +} +``` + +**Execution flow** (structurally identical to `koan_ask_question`): + +1. Read the file at `path` to get raw markdown content +2. Create `ArtifactReviewIpcFile` with the content +3. Write `ipc.json` (atomic) +4. Poll until response appears +5. Return the feedback string to the LLM + +**Tool response to LLM:** + +``` +User feedback: +Accept + +--- or --- + +User feedback: +The goals section should include a specific metric for latency. Also, +constraint #3 about "no new architectural choices" feels too restrictive +— we discussed allowing a new queue system in the intake phase. +``` + +The LLM sees plain text. If it says "Accept", the LLM calls +`koan_complete_step`. If it's feedback, the LLM revises the artifact and +calls `koan_review_artifact` again. + +**Registration:** via `registerReviewArtifactTool(pi, ctx)` following the +same pattern as `registerAskTools`. + +### 3. IPC Responder — Handle "artifact-review" type + +**File: `src/planner/lib/ipc-responder.ts`** + +Add `handleArtifactReviewRequest` function (mirrors `handleAskRequest`): + +1. Extract payload from ipc file +2. Call `webServer.requestArtifactReview(payload, signal)` +3. Write response back to `ipc.json` + +Add third branch in the poll loop: + +```typescript +if (ipc.type === "artifact-review") { + await handleArtifactReviewRequest(subagentDir, ipc, webServer, signal); +} +``` + +### 4. Web Server — Artifact review endpoint and SSE + +**File: `src/planner/web/server-types.ts`** + +Add types: + +```typescript +interface ArtifactReviewEvent { + requestId: string; + artifactPath: string; + content: string; // raw markdown + description?: string; +} + +interface ArtifactReviewFeedback { + feedback: string; // "Accept" or free-form text +} +``` + +Add to `WebServerHandle` interface: + +```typescript +requestArtifactReview( + payload: ArtifactReviewPayload, + signal: AbortSignal, +): Promise<ArtifactReviewFeedback>; +``` + +**File: `src/planner/web/server.ts`** + +- `requestArtifactReview`: creates Promise in `pendingInputs` with + `type: "artifact-review"`, pushes SSE event `"artifact-review"`. +- New POST endpoint `/api/artifact-review`: + validates `token` (403 if mismatch), `requestId`, and `feedback`; + resolves the pending promise. Follows the same session-token validation + pattern as `/api/answer` and `/api/review`. +- SSE cancel event: `artifact-review-cancelled`. +- **Update `replayState()`**: add `"artifact-review"` branch to the + `pendingInputs` iteration so artifact-review state survives SSE + reconnects: + ```typescript + else if (entry.type === "artifact-review") { + write("artifact-review", { + requestId, + artifactPath: entry.payload.artifactPath, + content: entry.payload.content, + description: entry.payload.description, + }); + } + ``` + Without this, a browser reconnect during an active review loses the + pending form and stalls the pipeline. + +### 5. Web UI — Markdown viewer + feedback form + +**New dependency: `marked`** (npm install) + +A lightweight markdown-to-HTML renderer. No backend coupling. Future mermaid +support can be added via a custom renderer extension without changing the +component API. + +**New file: `src/planner/web/js/components/forms/ArtifactReview.jsx`** + +``` +┌─────────────────────────────────────────┐ +│ Review: Epic Brief │ +│ ───────────────────────── │ +│ │ +│ ┌─────────────────────────────────┐ │ +│ │ │ │ +│ │ [rendered markdown content] │ │ +│ │ │ │ +│ │ ## Summary │ │ +│ │ This epic covers... │ │ +│ │ │ │ +│ │ ## Context & Problem │ │ +│ │ Engineers currently lack... │ │ +│ │ │ │ +│ │ ## Goals │ │ +│ │ 1. **Correctness** — ... │ │ +│ │ │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────┐ │ +│ │ Feedback (optional) │ │ +│ │ │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ [Send Feedback] [Accept ✓] │ +│ │ +└─────────────────────────────────────────┘ +``` + +Component behavior: + +- Receives `content` (raw markdown) from the store's `pendingInput.payload` +- Renders markdown client-side using `marked.parse(content)` +- Sets `innerHTML` via `dangerouslySetInnerHTML` — note that `marked` does + NOT sanitize by default (built-in sanitization was removed in v1.1.0). + This is acceptable here because content is LLM-generated from a local file, + not user-provided. If this pattern is reused for user-provided content, + add DOMPurify +- "Accept" button POSTs `{ token, requestId, feedback: "Accept" }` to + `/api/artifact-review` +- "Send Feedback" button POSTs `{ token, requestId, feedback: textareaValue }` + (disabled when textarea is empty) +- After submit, the component unmounts (pendingInput cleared by server event) +- When the LLM revises and re-invokes the tool, a new SSE event arrives and + the component remounts with updated content + +**File: `src/planner/web/js/sse.js`** + +Add handler mapping: + +```javascript +'artifact-review': handleArtifactReviewEvent, +'artifact-review-cancelled': handleArtifactReviewCancelledEvent, +``` + +**File: `src/planner/web/js/store.js`** + +Add handlers: + +```javascript +export function handleArtifactReviewEvent(d) { + set({ + pendingInput: { + type: 'artifact-review', + requestId: d.requestId, + payload: { artifactPath: d.artifactPath, content: d.content, description: d.description } + } + }) +} + +export function handleArtifactReviewCancelledEvent(d) { + set(s => s.pendingInput?.requestId === d.requestId + ? { pendingInput: null, ... } + : {} + ) +} +``` + +**File: `src/planner/web/js/components/PhaseContent.jsx`** + +Add dispatch case: + +```javascript +if (pending?.type === "artifact-review") + return <ArtifactReview key={pending.requestId} token={token} />; +``` + +**File: `src/planner/web/css/components.css`** + +Add styles for the artifact review panel: markdown content area with +appropriate typography, code block styling, scrollable container, feedback +textarea, and action buttons. + +### 6. Brief-Writer Subagent + +**New file: `src/planner/phases/brief-writer/phase.ts`** + +Extends `BasePhase`. Role: `"brief-writer"`. Total steps: 3. + +Each step has exactly one cognitive goal (per architecture.md pitfall guidance): + +Step progression: + +- Step 0 → 1: boot (step-first pattern) +- Step 1 (Read): read and comprehend context.md — build a mental model of the + problem, decisions, codebase findings, and constraints. Read-only; no writing. +- Step 2 (Draft & Review): write brief.md, invoke `koan_review_artifact`. If + user provides feedback, revise and re-invoke. Loops on step 2 via + `getNextStep()` override until user responds with "Accept". + `validateStepCompletion(step=2)` requires at least one `koan_review_artifact` + call before advancing (ensures the LLM cannot skip review). +- Step 3 (Finalize): phase complete + +**New file: `src/planner/phases/brief-writer/prompts.ts`** + +System prompt — PM role focused on the "what and why": + +``` +You are a brief writer for a coding task planner. You read intake context +and produce a compact epic brief — a product-level document that captures +the problem, who's affected, goals, and constraints. + +## Your role + +You distill intake findings into a clear problem statement. You do NOT +design solutions, plan implementation, or decompose into stories. + +## Output + +One file: **brief.md** in the epic directory. + +## Structure + +- **Summary**: 3-8 sentences describing what this epic is about. +- **Context & Problem**: Who's affected, where in the product, the current pain. +- **Goals**: Numbered list of measurable objectives. +- **Constraints**: Hard constraints grounding decisions (from context.md). + +Keep the brief compact — under 50 lines. No UI flows, no technical design, +no implementation details. + +## Review + +After drafting, invoke `koan_review_artifact` to present the brief for +review. If the user provides feedback, revise the brief and present it +again. Continue until the user accepts. +``` + +Step 1 (Read) guidance: + +``` +Read `context.md` in the epic directory. Build a thorough mental model of: +- The topic — what is being built or changed +- Codebase findings — architecture, patterns, integration points +- Decisions — every question asked and the user's answer +- Constraints — technical, timeline, compatibility requirements + +Do NOT write any files in this step. Comprehend before drafting. +``` + +Step 2 (Draft & Review) guidance: + +``` +Draft `brief.md` in the epic directory with the required sections +(Summary, Context & Problem, Goals, Constraints). Keep it under 50 +lines. No UI flows, no technical design, no implementation details. + +After writing, invoke `koan_review_artifact` with the path to brief.md. + +If the user responds with "Accept", call koan_complete_step. +If the user provides feedback, revise brief.md to address the feedback, +then invoke koan_review_artifact again. +``` + +Step 3 guidance: "Phase complete." (standard termination step) + +The phase overrides `getNextStep()` to loop step 2 back to step 2 when +review feedback is received (non-linear progression, same pattern as +the intake confidence loop). + +### 7. Task Manifest, Dispatch, and Role Registration + +**File: `src/planner/types.ts`** + +Add `"brief-writer"` to `SubagentRole` union: + +```typescript +export type SubagentRole = + | "intake" + | "scout" + | "decomposer" + | "orchestrator" + | "planner" + | "executor" + | "brief-writer"; +``` + +Add to `ROLE_MODEL_TIER` — use `"strong"` (same tier as intake and decomposer; +the brief-writer performs similar reasoning-heavy synthesis work): + +```typescript +export const ROLE_MODEL_TIER: Record<SubagentRole, ModelTier> = { + intake: "strong", + scout: "cheap", + decomposer: "strong", + "brief-writer": "strong", + orchestrator: "strong", + planner: "strong", + executor: "standard", +}; +``` + +**File: `src/planner/lib/task.ts`** + +Add `BriefWriterTask` interface and extend the union: + +```typescript +export interface BriefWriterTask extends SubagentTaskBase { + role: "brief-writer"; +} + +export type SubagentTask = + | IntakeTask + | ScoutTask + | DecomposerTask + | BriefWriterTask + | OrchestratorTask + | PlannerTask + | ExecutorTask; +``` + +**File: `src/planner/phases/dispatch.ts`** + +Add `"brief-writer"` case to the switch (between decomposer and orchestrator): + +```typescript +case "brief-writer": { + const phase = new BriefWriterPhase(pi, ctx, logger, eventLog); + await phase.begin(); + break; +} +``` + +Add import: `import { BriefWriterPhase } from "./brief-writer/phase.js";` + +Without these three changes, TypeScript compilation fails: `SubagentRole` +does not include `"brief-writer"`, `SubagentTask` has no `BriefWriterTask` +variant, and the exhaustive switch in dispatch.ts errors on the `never` +default branch. + +### 8. Permissions (renumbered from §7) + +**File: `src/planner/lib/permissions.ts`** + +Add `"brief-writer"` to `ROLE_PERMISSIONS`: + +```typescript +["brief-writer", new Set([ + "koan_complete_step", + "koan_review_artifact", + "edit", + "write", +])], +``` + +Add `"brief-writer"` to `PLANNING_ROLES` set (path-scoped to epic directory). + +No `koan_ask_question` — the brief-writer uses artifact review, not structured +questions. No `koan_request_scouts` — all codebase context arrives via +context.md from the intake phase. + +### 9. Driver — Insert brief phase + +**File: `src/planner/types.ts`** + +Update `EpicPhase`: + +```typescript +export type EpicPhase = + | "intake" + | "brief" + | "decomposition" + | "review" + | "executing" + | "completed"; +``` + +**File: `src/planner/driver.ts`** + +Add `runBriefWriter` function (parallel to `runIntake`, `runDecomposer`): + +```typescript +async function runBriefWriter( + epicDir, + cwd, + extensionPath, + log, + webServer, +): Promise<boolean> { + const subagentDir = await ensureSubagentDirectory(epicDir, "brief-writer"); + const result = await spawnTracked( + "brief-writer", + "brief-writer", + "brief-writer", + { role: "brief-writer", epicDir }, + subagentDir, + undefined, + opts, + webServer, + ); + return result.exitCode === 0; +} +``` + +Insert between intake and decomposition in `runPipeline`: + +```typescript +// After intake succeeds: +await saveEpicState(epicDir, { ...afterIntake, phase: "brief" }); +webServer?.pushPhase("brief"); + +const briefOk = await runBriefWriter( + epicDir, + cwd, + extensionPath, + log, + webServer, +); +if (!briefOk) return { success: false, summary: "Brief generation failed" }; + +const afterBrief = await loadEpicState(epicDir); +await saveEpicState(epicDir, { ...afterBrief, phase: "decomposition" }); +webServer?.pushPhase("decomposition"); +``` + +### 10. Prompt Updates — Nudge downstream agents to read brief.md + +**File: `src/planner/phases/decomposer/prompts.ts`** + +Step 1 guidance — add brief.md to files to read: + +``` +- `context.md` — intake analysis +- `brief.md` — epic brief: problem statement, goals, and constraints +``` + +Add to system prompt rules: + +``` +- MUST NOT invent scope not present in context.md or brief.md. +``` + +**File: `src/planner/phases/planner/prompts.ts`** + +Step 1 guidance — add: + +``` +3. Read `brief.md` in the epic directory — understand the product-level goals + and constraints. The plan must serve these goals. +``` + +**File: `src/planner/phases/orchestrator/prompts.ts`** + +Add brief.md reference where context.md is referenced, so the orchestrator +can validate story completion against product goals. + +**Note:** The executor reads `plan/context.md` (a different, story-specific +file), not the epic-level context.md. No change needed for the executor — it +works from the plan, which already incorporates brief context via the planner. + +### 11. Web UI — PillStrip and ProgressBar update + +**File: `src/planner/web/js/components/PillStrip.jsx`** + +```javascript +const PHASES = [ + { id: "intake", label: "intake" }, + { id: "brief", label: "brief" }, + { id: "decomposition", label: "decompose" }, + { id: "review", label: "review" }, + { id: "executing", label: "execute" }, +]; + +const PHASE_ORDER = [ + "intake", + "brief", + "decomposition", + "review", + "executing", + "completed", +]; +``` + +**File: `src/planner/web/js/components/ProgressBar.jsx`** + +ProgressBar has its own hardcoded `PHASE_ORDER` array (separate from +PillStrip). Update it to include `'brief'`: + +```javascript +const PHASE_ORDER = [ + "intake", + "brief", + "decomposition", + "review", + "executing", + "completed", +]; +``` + +Without this, the progress bar shows incorrect fill percentage during the +brief phase (it won't find `'brief'` in its array, returning index -1 → 0%). + +### 12. Documentation + +**New file: `docs/artifact-review.md`** + +Document the artifact review IPC protocol: + +- Message type (`artifact-review`), payload shape, response shape +- Tool interface (`koan_review_artifact`) +- Web UI component behavior +- The "Accept" = verbatim text design decision +- How the review loop works (LLM invokes → feedback → revise → re-invoke) +- Reusability for future artifact types + +**New file: `docs/epic-brief.md`** + +Document the epic brief artifact: + +- What it captures (problem, context, goals, constraints) +- What it excludes (UI flows, tech design, implementation) +- How it fits in the pipeline (after intake, before decomposition) +- How downstream phases reference it +- Design rationale (artifact cascade pattern) + +**Update: `docs/architecture.md`** + +- Add brief phase to pipeline description +- Add brief-writer to phase list +- Update phase diagram + +**Update: `docs/ipc.md`** + +- Add artifact-review message type documentation +- Add flow diagram (parallel to existing ask flow and scout flow) + +**Update: `AGENTS.md`** + +- Update phase list: intake → brief → decomposition → review → executing → completed + +--- + +## Implementation Order + +The dependency chain suggests this order: + +1. **Type foundations** (`types.ts`) — `SubagentRole`, `EpicPhase`, `ROLE_MODEL_TIER` +2. **IPC types** (`ipc.ts`) — `ArtifactReviewIpcFile` + factory + `pollIpcUntilResponse` update +3. **Task manifest** (`task.ts`) — `BriefWriterTask` interface + union +4. **Tool** (`review-artifact.ts`) — LLM-facing interface +5. **IPC responder** (`ipc-responder.ts`) — parent-side handling +6. **Web server** (`server.ts`, `server-types.ts`) — HTTP/SSE plumbing + `replayState()` +7. **npm install marked** — markdown rendering dependency +8. **Web UI** (`ArtifactReview.jsx`, `store.js`, `sse.js`, `PhaseContent.jsx`, CSS) +9. **Brief-writer phase** (`phase.ts`, `prompts.ts`) — subagent with 3-step workflow +10. **Dispatch** (`dispatch.ts`) — route `"brief-writer"` to phase +11. **Permissions** (`permissions.ts`) — role authorization +12. **Driver** (`driver.ts`) — phase insertion between intake and decomposition +13. **Prompt updates** (decomposer, planner, orchestrator prompts) +14. **PillStrip + ProgressBar** updates +15. **Documentation** (artifact-review.md, epic-brief.md, architecture.md, ipc.md, AGENTS.md) + +--- + +## Files Summary + +| Action | File | What | +| ------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| Modify | `src/planner/lib/ipc.ts` | Add `ArtifactReviewIpcFile` type + factory + `pollIpcUntilResponse` exit condition | +| New | `src/planner/tools/review-artifact.ts` | `koan_review_artifact` tool | +| Modify | `src/planner/lib/ipc-responder.ts` | Handle `"artifact-review"` type | +| Modify | `src/planner/web/server-types.ts` | Add review types + `requestArtifactReview` | +| Modify | `src/planner/web/server.ts` | SSE event + POST endpoint + `replayState()` branch | +| New | `src/planner/web/js/components/forms/ArtifactReview.jsx` | Markdown viewer + feedback form | +| Modify | `src/planner/web/js/store.js` | Add artifact-review handlers | +| Modify | `src/planner/web/js/sse.js` | Add SSE event mapping | +| Modify | `src/planner/web/js/components/PhaseContent.jsx` | Add dispatch case | +| Modify | `src/planner/web/css/components.css` | Artifact review styles | +| New | `src/planner/phases/brief-writer/phase.ts` | Brief-writer phase (3 steps, step 2 loop) | +| New | `src/planner/phases/brief-writer/prompts.ts` | System prompt + step guidance | +| Modify | `src/planner/types.ts` | Add `"brief"` to `EpicPhase` + `"brief-writer"` to `SubagentRole` + `ROLE_MODEL_TIER` | +| Modify | `src/planner/lib/task.ts` | Add `BriefWriterTask` interface + union member | +| Modify | `src/planner/phases/dispatch.ts` | Add `"brief-writer"` case + import | +| Modify | `src/planner/lib/permissions.ts` | Add `brief-writer` role | +| Modify | `src/planner/driver.ts` | Insert brief phase in pipeline | +| Modify | `src/planner/phases/decomposer/prompts.ts` | Add brief.md reference | +| Modify | `src/planner/phases/planner/prompts.ts` | Add brief.md reference | +| Modify | `src/planner/phases/orchestrator/prompts.ts` | Add brief.md reference | +| Modify | `src/planner/web/js/components/PillStrip.jsx` | Add "brief" pill + PHASE_ORDER | +| Modify | `src/planner/web/js/components/ProgressBar.jsx` | Add "brief" to PHASE_ORDER | +| New | `docs/artifact-review.md` | Review IPC protocol docs | +| New | `docs/epic-brief.md` | Epic brief design docs | +| Modify | `docs/architecture.md` | Pipeline update | +| Modify | `docs/ipc.md` | New message type | +| Modify | `AGENTS.md` | Phase list update | +| Modify | `package.json` | Add `marked` dependency | diff --git a/plans/2026-03-21-ui-layout-redesign.md b/plans/2026-03-21-ui-layout-redesign.md new file mode 100644 index 0000000..c758672 --- /dev/null +++ b/plans/2026-03-21-ui-layout-redesign.md @@ -0,0 +1,401 @@ +# UI Layout Redesign + +Consolidate status information into the right panel, strip the header to +navigation-only, fix typography, and style scrollbars. + +--- + +## Design Decisions + +### Header = navigation, right panel = status + +The header carries "where am I in the pipeline" (logo, phase pills, settings). +The right panel carries "what's happening right now" (agent identity, phase +progress, confidence, summary). No overlap between the two. + +This eliminates three sources of redundancy: the ProgressBar (duplicates +PillStrip), the SubagentMeta bar (duplicates sidebar), and the Timer +(status, not navigation). + +### The right panel is phase-aware for all phases + +The current sidebar only renders meaningful content during intake. Every other +phase gets a generic "Phase in progress…" label. The redesign makes the panel +useful for every phase by showing phase-appropriate status widgets. + +### Typography minimum: 12px + +No text in the UI below 12px. The only 12px text is uppercase decorative +labels (CONFIDENCE, ITERATION). All readable content is 13px+. This is +the minimum for sustained reading on Retina displays. + +### CSS-only scrollbar styling + +Dark-themed thin scrollbar via `::webkit-scrollbar` and `scrollbar-width`. +No dependencies. Chromium-only support is sufficient — this is a localhost +developer tool. + +--- + +## Changes + +### 1. Remove ProgressBar + +**Delete: `src/planner/web/js/components/ProgressBar.jsx`** + +The 3px gradient bar at the top is a strict subset of the PillStrip's +information. The PillStrip already shows phase progression with ✓/● prefixes +and green/blue color states. + +**File: `src/planner/web/js/components/App.jsx`** + +Remove `<ProgressBar />` from the render tree and its import. + +**File: `src/planner/web/css/layout.css`** + +Remove `.progress-bar` and `.progress-fill` styles. + +Update `.header` top position from `top: 3px` to `top: 0` (no progress bar +above it anymore). + +Update `.main-panel` and `.live-layout` margin-top from +`calc(3px + var(--header-height))` to `var(--header-height)`. + +### 2. Remove SubagentMeta bar + +**Delete: `src/planner/web/js/components/SubagentMeta.jsx`** + +Its content (role, model, step, tokens) moves into the top of the +StatusSidebar. + +**File: `src/planner/web/js/components/App.jsx`** + +Remove `<SubagentMeta />` from the live-layout render tree and its import. + +**File: `src/planner/web/css/layout.css`** + +Remove `.subagent-meta`, `.meta-role`, `.meta-item`, `.meta-tokens` styles. + +### 3. Move Timer from header to sidebar + +**File: `src/planner/web/js/components/Header.jsx`** + +Remove `<Timer />` from the header and its import. The header-right div +keeps only the settings button. + +If header-right has only the gear button and no other content, simplify +accordingly — but keep the flex layout for future additions. + +### 4. Redesign StatusSidebar + +**File: `src/planner/web/js/components/StatusSidebar.jsx`** + +The sidebar becomes the single status home. It absorbs content from +SubagentMeta (agent identity) and Timer (elapsed time). + +**New structure:** + +``` +┌─────────────────────────┐ +│ INTAKE · opus-4-6 │ agent role + model +│ Step 4/5: Reflect │ step label +│ ↑39 ↓21k 15m 00s │ tokens + timer +│─────────────────────────│ +│ │ +│ [phase-specific status]│ +│ │ +│─────────────────────────│ +│ summary text │ +└─────────────────────────┘ +``` + +**Agent identity section** (top, always present when subagent is active): + +Read `subagent` from the store (same data SubagentMeta used). Display: + +- Role (uppercase, blue) + model (muted) on one line +- Step label on the next line +- Token counts (↑sent ↓recv) + elapsed timer on the third line + +Import the Timer logic (or inline a simple elapsed-time hook) — don't import +the Timer component since it's being deleted. Use `subagent.startedAt` to +compute elapsed time with a 1-second interval, same as the current Timer. + +Use the `shortenModel` and `formatTokens` utilities from `lib/utils.js`. + +**Phase-specific sections** (middle): + +The sidebar already has `IntakeStatus` and `GenericStatus` branches. Keep +the IntakeStatus (confidence, iteration, sub-phase) as-is but with updated +typography. Expand GenericStatus into phase-specific variants: + +```jsx +function PhaseStatus({ phase, stories }) { + switch (phase) { + case "intake": + // handled separately via IntakeStatus + return null; + case "brief": + return <BriefStatus />; + case "decomposition": + return <DecomposeStatus stories={stories} />; + case "executing": + return <ExecuteStatus stories={stories} />; + default: + return <GenericStatus phase={phase} />; + } +} +``` + +- **BriefStatus**: "Drafting epic brief…" or "Awaiting review…" — simple + label based on sub-phase (if we add brief sub-phase SSE events later, + this can get richer. For now, a static label is fine.) + +- **DecomposeStatus**: Show story count as stories arrive via the `stories` + store slice. Example: "3 stories identified" + +- **ExecuteStatus**: Show story progress from the `stories` store slice. + Count stories by status. Example: "2/5 complete · 1 active" + +- **GenericStatus** (fallback): simple label, same as current. + +**Summary section** (bottom, below divider): + +Keep the existing summary text pattern. For intake, use the sub-phase +summary map. For other phases, show a static contextual message. + +**Visibility:** The sidebar should render whenever there is an active phase +in live mode — not only when `subagent` is non-null. During brief pauses +between subagent spawns, the phase-specific status (story progress, etc.) +is still useful. Gate on `phase` existence instead of `subagent` existence. +When `subagent` is null, just omit the agent identity section at the top. + +### 5. Update App.jsx layout + +**File: `src/planner/web/js/components/App.jsx`** + +The live-layout block simplifies: + +```jsx +<div class="live-layout"> + <div class="live-main"> + <main class="main-panel"> + <ActivityFeed /> + </main> + </div> + <StatusSidebar /> +</div> +``` + +SubagentMeta and ProgressBar are gone. The live-main div now contains only +ActivityFeed (and AgentMonitor stays at the bottom, outside live-layout). + +Remove imports: `ProgressBar`, `SubagentMeta`. + +### 6. Widen sidebar + fix typography + +**File: `src/planner/web/css/layout.css`** + +Update sidebar width to be fluid: + +```css +.status-sidebar { + width: clamp(240px, 20vw, 300px); + flex-shrink: 0; + background: var(--bg-elevated); + border-left: 1px solid var(--border); + overflow-y: auto; + padding: var(--gap-md) var(--gap-lg); /* was var(--gap-md) — more horizontal padding */ +} +``` + +Update sidebar typography: + +```css +.sidebar-heading { + font-size: 12px; /* was 10px */ + margin-bottom: var(--gap-md); +} + +.sidebar-label { + font-size: 12px; /* was 10px */ +} + +.sidebar-value { + font-size: 13px; /* was 12px (--font-size-xs) */ +} + +.sidebar-summary { + font-size: 13px; /* was 11px */ +} +``` + +Add new styles for the agent identity section: + +```css +.sidebar-agent { + margin-bottom: var(--gap-md); + font-family: var(--font-mono); +} + +.sidebar-agent-role { + color: var(--blue); + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.06em; + font-size: 13px; +} + +.sidebar-agent-model { + color: var(--text-muted); + font-size: 13px; +} + +.sidebar-agent-step { + color: var(--text-muted); + font-size: 13px; + margin-top: 2px; +} + +.sidebar-agent-stats { + display: flex; + justify-content: space-between; + color: var(--text-dim); + font-size: 13px; + margin-top: 2px; +} +``` + +### 7. Bump global typography + +**File: `src/planner/web/css/variables.css`** + +```css +--font-size-sm: 14px; /* was 13px */ +``` + +This affects activity card headers, pill strip text, agent table text, +badge text, meta items — all the "secondary" text in the UI that was +slightly too small. + +The other size variables stay the same: + +- `--font-size-xs: 12px` (unchanged — labels, timestamps) +- `--font-size-md: 15px` (unchanged — body text) +- `--font-size-lg: 16px` (unchanged — headings, questions) + +**File: `src/planner/web/css/layout.css`** + +Update activity card body font size: + +```css +.activity-card-body { + font-size: 13px; /* was var(--font-size-xs) = 12px */ +} +``` + +### 8. Style scrollbars + +**File: `src/planner/web/css/variables.css`** + +Add at the end of the file (after the `html, body` rule): + +```css +/* Dark-themed scrollbar for all scrollable areas */ +* { + scrollbar-width: thin; + scrollbar-color: var(--border) transparent; +} + +::-webkit-scrollbar { + width: 8px; + height: 8px; +} + +::-webkit-scrollbar-track { + background: transparent; +} + +::-webkit-scrollbar-thumb { + background: var(--border); + border-radius: 4px; +} + +::-webkit-scrollbar-thumb:hover { + background: var(--text-ghost); +} +``` + +### 9. Clean up animation CSS + +**File: `src/planner/web/css/animations.css`** + +Remove the `.progress-fill` transition rule (the progress bar no longer +exists). + +### 10. Update ARCHITECTURE.md component tree + +**File: `src/planner/web/ARCHITECTURE.md`** + +Update the component tree to reflect the new structure: + +``` +App +├── Header +│ ├── PillStrip reads phase for active/done pill state +│ └── ⚙ settings btn +│ +├── (isInteractive) main.main-panel +│ └── PhaseContent dispatch hub +│ +├── (live) div.live-layout +│ ├── div.live-main +│ │ └── main.main-panel +│ │ └── ActivityFeed reads logs +│ └── StatusSidebar agent identity + phase status + summary +│ +├── AgentMonitor reads agents (hides when none active) +└── Notifications reads notifications +``` + +Remove ProgressBar and SubagentMeta from the tree description. + +Update the StatusSidebar section to document: + +- Agent identity section (role, model, step, tokens, timer) +- Phase-specific status for all phases (not just intake) +- Summary section + +Update the "App layout modes" section — live mode no longer has SubagentMeta. + +--- + +## Implementation Order + +1. **Remove ProgressBar** — delete component, remove from App, clean up CSS +2. **Remove SubagentMeta** — delete component, remove from App, clean up CSS +3. **Move Timer out of header** — remove from Header.jsx (don't delete Timer.jsx yet — sidebar will reuse its logic) +4. **Redesign StatusSidebar** — absorb agent identity + timer, add phase-specific variants, update visibility gate +5. **Delete Timer.jsx** — if sidebar inlines the elapsed time logic; or keep it if sidebar imports it as a sub-component +6. **Widen sidebar + fix typography** — CSS updates +7. **Bump global typography** — `--font-size-sm` and activity card body +8. **Style scrollbars** — CSS-only addition +9. **Clean up animations CSS** — remove progress-fill rule +10. **Update ARCHITECTURE.md** — component tree and documentation + +--- + +## Files Summary + +| Action | File | What | +| ------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| Delete | `src/planner/web/js/components/ProgressBar.jsx` | Redundant with PillStrip | +| Delete | `src/planner/web/js/components/SubagentMeta.jsx` | Absorbed into StatusSidebar | +| Modify | `src/planner/web/js/components/App.jsx` | Remove ProgressBar + SubagentMeta imports and usage | +| Modify | `src/planner/web/js/components/Header.jsx` | Remove Timer import and usage | +| Modify | `src/planner/web/js/components/StatusSidebar.jsx` | Absorb agent identity + timer, phase-specific status | +| Delete | `src/planner/web/js/components/Timer.jsx` | Logic moves into StatusSidebar (or kept as imported sub-component) | +| Modify | `src/planner/web/css/variables.css` | Bump `--font-size-sm`, add scrollbar styles | +| Modify | `src/planner/web/css/layout.css` | Widen sidebar, fix typography, remove progress bar + subagent meta styles, fix header top | +| Modify | `src/planner/web/css/animations.css` | Remove progress-fill transition | +| Modify | `src/planner/web/ARCHITECTURE.md` | Update component tree and docs | diff --git a/plans/2026-03-22-realtime-token-streaming.md b/plans/2026-03-22-realtime-token-streaming.md new file mode 100644 index 0000000..b8eeb06 --- /dev/null +++ b/plans/2026-03-22-realtime-token-streaming.md @@ -0,0 +1,315 @@ +# Realtime Token Streaming from Subagents to Web UI + +Stream LLM token deltas from subagent processes to the browser in realtime, +giving the user instant visibility into what the LLM is producing instead of +waiting for a turn to complete. + +--- + +## Design Decisions + +### Use `--mode json` stdout parsing, not extension hooks or file polling + +Pi ships a designed integration surface for external UIs: `--mode json -p` +emits every session event as a JSONL line on stdout. Pi's own subagent +extension (`examples/extensions/subagent/index.ts`) already uses this exact +pattern with `["--mode", "json", "-p"]` and a line-buffer parser on +`proc.stdout`. + +Koan currently spawns with `["-p"]` and pipes stdout to a log file. Switching +to `["--mode", "json", "-p"]` gives the parent process a structured stream of +typed events, including `message_update` with `text_delta` deltas, without +modifying the koan extension or the pi codebase. + +Alternatives considered and rejected: + +| Alternative | Reason | +| --------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| Extension `message_update` hook + file append | More code, file I/O per token, still needs polling, adds new file to directory-as-contract | +| Extension + HTTP POST per token | Need to pass server port to extension, HTTP overhead per token, reliability concerns | +| Switch to RPC mode | Requires bidirectional stdin/stdout, fundamentally changes spawn pattern (stdin is `"ignore"`) | +| Tail stdout.log in `-p` mode | Raw text, not structured — can't distinguish token deltas from tool output | +| SDK embedding (`createAgentSession`) | Destroys process isolation (core architectural invariant) | + +### Forward only `text_delta` events, filter everything else + +`--mode json` emits all session events (tool execution, turns, compaction, +etc.). The parent's JSONL parser filters to `message_update` events where +`assistantMessageEvent.type === "text_delta"`, discarding the rest. This keeps +the SSE channel lean — the existing 50ms polling of `state.json` continues to +handle tool-call-level status updates. + +### Send incremental deltas, not accumulated state + +Each SSE event carries a `delta` string (the new tokens), not the full +accumulated text. The frontend accumulates. This minimizes bandwidth and +matches how the provider stream works internally. The frontend clears the +accumulator on `subagent-idle` (already emitted when a subagent finishes). + +### Preserve the stdout log file + +The JSONL parser runs alongside the existing `stdoutLog.write(data)` call. +The log file continues to capture everything for post-mortem debugging. +No behavioral change to existing diagnostics. + +--- + +## Scope + +### In scope + +- Spawn flag change (`-p` → `--mode json -p`) +- JSONL line-buffer parser in `subagent.ts` +- New `pushTokenDelta` method on `WebServerHandle` +- New `token-delta` SSE event type in the web server +- Frontend store state + SSE handler for accumulating deltas +- A visible streaming text area in the activity feed / subagent panel + +### Out of scope + +- Streaming for scouts (they have no web server handle today) +- Thinking block streaming (`thinking_delta` — could be added later with the same mechanism) +- Tool execution streaming (`tool_execution_update` — same mechanism) +- Backpressure / throttling (LLM generation speed is the bottleneck, not parsing) + +--- + +## Implementation + +### Step 1 — Extend `WebServerHandle` interface + +**File:** `src/planner/web/server-types.ts` + +Add one method to the `WebServerHandle` interface: + +```typescript +/** + * Push a streaming token delta from a subagent to all SSE clients. + * + * Parameterless because only one subagent is tracked at a time (via + * trackSubagent / clearSubagent). There is no ambiguity about which + * subagent the delta belongs to — only the tracked subagent generates tokens. + */ +pushTokenDelta(delta: string): void; +``` + +This is scoped to the currently-tracked subagent (set by `trackSubagent()`). +No need to pass a directory — only one subagent is tracked at a time. + +### Step 2 — Implement SSE push and replay accumulation in web server + +**File:** `src/planner/web/server.ts` + +Add a server-side accumulator alongside the existing `currentSubagent`, +`currentPhase`, etc.: + +```typescript +// Server-side accumulator for token streaming. Holds the full text produced +// by the current subagent so reconnecting clients can catch up. Cleared on +// subagent transitions (trackSubagent / clearSubagent). +let streamingText = ""; +``` + +Implement `pushTokenDelta` on the server handle object: + +```typescript +pushTokenDelta(delta: string): void { + // Accumulate server-side for replay on client reconnect. Without this, + // a client that reconnects mid-stream would see an empty streaming area + // with no error signal — a silent failure. + streamingText += delta; + // Push only the delta (not accumulated text) to already-connected clients. + // This matches the provider stream's own framing and minimizes SSE payload. + pushEvent("token-delta", { delta }); +}, +``` + +Add the replay write inside `replayState()`: + +```typescript +// Replay accumulated streaming text as a single delta event. The frontend's +// appendTokenDelta handles this transparently — it accumulates from zero +// after each clear, so receiving the full text as one "delta" produces the +// correct state. +if (streamingText) { + write("token-delta", { delta: streamingText }); +} +``` + +Reset the accumulator in `trackSubagent()` and `clearSubagent()`: + +```typescript +// In trackSubagent(): new subagent starts, discard previous text +streamingText = ""; + +// In clearSubagent(): subagent finished, discard text +streamingText = ""; +``` + +### Step 3 — Switch spawn args and parse stdout JSONL + +**File:** `src/planner/subagent.ts` + +Three changes: + +1. Add `"--mode", "json"` to the spawn args array (before `-p`). + + ```typescript + // --mode json makes pi emit structured JSONL on stdout instead of human- + // readable text. Combined with -p (non-interactive), this is the designed + // integration surface for external UIs. Pi's own subagent extension uses + // the identical flag pair — ["--mode", "json", "-p"] — confirming this is + // the supported composition. + const args = ["--mode", "json", "-p", "-e", extensionPath, "--koan-dir", subagentDir, ...]; + ``` + +2. Replace the simple `proc.stdout.on("data")` handler with a JSONL + line-buffer parser. The pattern is identical to pi's own subagent + extension: + + ```typescript + let buffer = ""; + proc.stdout.on("data", (data: Buffer) => { + // Write raw bytes first — log file receives the full JSONL output + // regardless of what the parser does. Diagnostics are unaffected. + stdoutLog.write(data); + + // Accumulate into buffer because a single "data" event may contain + // a partial line (TCP-style framing — no guarantee of line boundaries). + buffer += data.toString(); + + // Split on newlines. lines[0..n-2] are complete; lines[n-1] may be a + // partial line — keep it in buffer for the next "data" event. + const lines = buffer.split("\n"); + buffer = lines.pop() || ""; // trailing partial line (or "" if data ended with \n) + + for (const line of lines) { + if (!line.trim()) continue; + try { + const event = JSON.parse(line); + // Filter to text_delta only. --mode json emits all session events + // (tool execution, turn boundaries, compaction, etc.). Only + // text_delta carries the incremental tokens we want to stream. + // Everything else is handled by the existing state.json polling path. + if ( + event.type === "message_update" && + event.assistantMessageEvent?.type === "text_delta" && + typeof event.assistantMessageEvent.delta === "string" + ) { + opts.webServer?.pushTokenDelta(event.assistantMessageEvent.delta); + } + } catch { + // Malformed line (e.g. stderr bleed or partial JSONL during + // buffer flush). Skip — the log file has the full bytes. + } + } + }); + ``` + +3. Merge buffer flushing into the **existing** `proc.on("close")` handler. + The existing handler calls `abortIpc()`, `stdoutLog.end()`, and + `resolve()`. Insert the buffer flush **before** `resolve()` so the + final token delta is pushed before `spawnSubagent()` resolves and the + driver calls `clearSubagent()`: + + ```typescript + proc.on("close", (code) => { + abortIpc?.(); + stdoutLog.end(); + stderrLog.end(); + + // Flush any partial JSONL line still in the buffer. Under normal + // operation the buffer is empty at close, but a process killed + // mid-line (e.g., SIGKILL) would otherwise lose the last event. + // This must happen before resolve() so the delta arrives before + // the driver calls clearSubagent() → pushEvent("subagent-idle"). + if (buffer.trim()) { + try { + const event = JSON.parse(buffer); + if ( + event.type === "message_update" && + event.assistantMessageEvent?.type === "text_delta" && + typeof event.assistantMessageEvent.delta === "string" + ) { + opts.webServer?.pushTokenDelta(event.assistantMessageEvent.delta); + } + } catch { + // Ignore malformed trailing content — log file has the raw bytes. + } + } + + const exitCode = code ?? 1; + log(`${task.role} subagent exited`, { exitCode }); + resolve({ exitCode, stderr, subagentDir }); + }); + ``` + +### Step 4 — Frontend: store + SSE handler + +**File:** `js/store.js` + +Add state and actions to the Zustand store: + +```javascript +streamingText: "", +appendTokenDelta: (delta) => set((s) => ({ streamingText: s.streamingText + delta })), +clearStreamingText: () => set({ streamingText: "" }), +``` + +**File:** `js/sse.js` + +Add the event handler: + +```javascript +case "token-delta": + store.getState().appendTokenDelta(data.delta); + break; +``` + +Clear the streaming text when a subagent finishes (on `subagent-idle`): + +```javascript +case "subagent-idle": + store.getState().clearStreamingText(); + // ... existing handler + break; +``` + +### Step 5 — Frontend: render streaming text + +**File:** `js/components/ActivityFeed.jsx` (or a new `StreamingOutput.jsx`) + +Add a component that renders `streamingText` when non-empty. This appears +below or alongside the activity feed, showing what the LLM is currently +producing. Auto-scroll to bottom as text grows. Fade/clear when +`subagent-idle` fires. + +Exact placement and styling are design decisions for the UI — the mechanism +is the same regardless. + +--- + +## Verification + +- Start a koan pipeline and observe the browser's DevTools Network tab for + `token-delta` SSE events arriving in realtime during LLM generation. +- Confirm the `stdout.log` file still contains the full JSONL output. +- Confirm `state.json` polling and all existing SSE events (`subagent`, + `logs`, `agents`, etc.) are unaffected. +- Confirm the koan extension's audit system (`events.jsonl`) still records + tool calls, usage, and thinking blocks as before. +- Reconnect the EventSource mid-stream and verify replay includes accumulated + streaming text. + +--- + +## Invariant Compliance + +| Invariant | Impact | +| ------------------------ | ----------------------------------------------------------- | +| File boundary | No change — LLMs still write markdown only | +| Step-first workflow | No change — boot prompt unchanged | +| Driver determinism | No change — routing still uses exit codes + state files | +| Directory-as-contract | No change — `task.json`, `state.json`, `ipc.json` untouched | +| Default-deny permissions | No change — permission fence untouched | +| Need-to-know prompts | No change — prompt content unchanged | diff --git a/plans/2026-03-23-core-flows.md b/plans/2026-03-23-core-flows.md new file mode 100644 index 0000000..118670d --- /dev/null +++ b/plans/2026-03-23-core-flows.md @@ -0,0 +1,924 @@ +# Core Flows Phase + +Insert a core-flows phase between the epic brief and decomposition, producing +a product-level interaction specification (`flows.md`) that anchors all +downstream work in explicit user journeys. + +--- + +## Design Decisions + +### Product decisions must precede scope decisions + +The brief captures the **problem**. The decomposer defines the **units of +work**. Between these sits an unaddressed question: what does the user +actually _experience_? Without an explicit answer, the decomposer invents +interaction patterns implicitly — embedding UX assumptions inside story scope +descriptions where they cannot be reviewed, challenged, or referenced. + +The core-flows phase forces these product decisions to happen explicitly, +with human alignment, before any scope decomposition begins. This prevents a +category of downstream error where stories implement a technically correct +solution to the wrong interaction model. + +### Flows describe interactions between actors and systems, not just UI + +A flow is a complete interaction path — from trigger to exit — between actors +(users, operators, services, CLIs) and systems. For a web application, flows +describe screen navigation and feedback. For a backend service, flows describe +API request/response paths. For infrastructure work, flows describe operational +procedures. For a refactoring epic, flows describe the behavioral contracts +that must be preserved. + +The flows-writer adapts its output to the domain described in the brief. The +artifact structure is the same regardless of domain: trigger, step-by-step +actions/responses, exit condition. + +This generalization matters because the artifact cascade depends on every +downstream phase being able to reference `flows.md` unconditionally. A +skippable phase creates conditional logic in every consumer ("if flows.md +exists, read it; otherwise, infer from brief.md"). A mandatory phase that +adapts to the domain avoids this. + +### Codebase grounding before design prevents specification drift + +The flows-writer reads the codebase (via scouts) before designing flows. This +is not optional — it is what prevents the specification from diverging from +reality. An LLM designing flows from the brief alone will propose interaction +patterns that don't match the existing system's structure, navigation model, +or data availability. + +By scouting first, the flows-writer grounds its design in what actually exists: +current screen layouts, API endpoints, CLI commands, data models. New flows +extend or modify the existing interaction surface rather than inventing one +from scratch. + +### User alignment happens through questions and artifact review + +The flows-writer uses two complementary alignment mechanisms: + +- **`koan_ask_question`** during the Align step — targeted questions about + interaction design decisions before any artifact is drafted. This surfaces + ambiguities while the design is still malleable. +- **`koan_review_artifact`** during the Draft & Review step — presentation of + the complete spec for holistic review. This catches issues that individual + questions miss (e.g., flows that contradict each other, missing edge cases, + information hierarchy problems). + +The two mechanisms serve different cognitive purposes. Questions resolve +specific uncertainties. Artifact review validates the whole. Neither alone +is sufficient. + +### Four dimensions of interaction design + +When thinking through flows, the flows-writer considers four dimensions that +surface the decisions users care about: + +1. **Information hierarchy** — what information is critical vs. secondary. + This determines what users see first, what is progressively disclosed, + and how information is grouped. + +2. **User journey integration** — where this flow starts, where it exits, + how it connects to adjacent workflows. No flow exists in isolation. + +3. **Placement & affordances** — how actions are accessed, how they behave, + how discoverable they are within the existing interaction surface. + +4. **Feedback & state communication** — how users know an action is in + progress, how success/error/edge cases are communicated. + +These dimensions are not aesthetic — they are architectural. They determine +what data must be available, what state transitions must occur, and what error +paths must exist. The tech plan and implementation plans downstream will trace +back to these decisions. + +### Flows are the strongest product-level reference downstream + +Once accepted, `flows.md` becomes the artifact that downstream phases consult +to understand _what the user should experience_. The decomposer reads it to +scope stories that implement specific flows. The planner reads it to understand +what behavior each story must produce. The orchestrator reads it to verify that +completed work matches the intended experience. + +This creates a traceable chain: every story should be traceable to one or more +flows. Every plan step should serve a flow requirement. Every verification +check should validate a flow's expected behavior. + +The reference is enforced at the prompt level (downstream agents are instructed +to read `flows.md`) rather than at runtime (no mechanical blocking on flow +misalignment). This is a deliberate choice for the current pipeline: prompt- +level references are sufficient for alignment, and runtime blocking would +require a validation phase that does not yet exist. + +### The artifact cascade now has four links + +The pipeline's artifact chain grows from three artifacts to four: + +``` +landscape.md (intake — codebase findings, decisions, constraints) + → brief.md (brief — problem + goals + constraints) + → flows.md (core-flows — interaction specifications) + → story.md × N (decomposition — units of work) + → plan/ × N (planner — implementation plans) +``` + +Each artifact is progressively more specific. Each phase reads all preceding +artifacts (not just the immediate predecessor). This creates redundant +reference paths — the decomposer reads both the brief and the flows, not +just the flows — which prevents telephone-game degradation where meaning +is lost in each translation step. + +--- + +## Philosophy Captures for Documentation + +The following concepts should be captured as high-level design principles in +`docs/core-flows.md`. They encode reasoning that will guide future phases +(validation gates, agentic workflow progression) even though those phases are +not implemented yet. + +### Artifact as contract + +Each phase in the pipeline produces a markdown artifact. That artifact is the +authoritative record of decisions made during that phase. Downstream phases +treat it as a contract — they read it, reference it, and are constrained by +it. The artifact replaces verbal agreements, implicit assumptions, and +scattered context. + +When all phases are complete, the set of artifacts (landscape.md, brief.md, +flows.md, story.md, plan/) forms a complete audit trail from user intent to +implementation. Any phase's output can be reviewed in isolation to understand +what was decided and why. + +### Product-before-technical ordering + +The pipeline is ordered so that product decisions (what should the user +experience?) are made before technical decisions (how should the code be +structured?). This is not arbitrary sequencing — it prevents a class of +planning failures where technically elegant solutions are built for the +wrong interaction model. + +The ordering is: problem statement (brief) → interaction design (flows) → +scope decomposition (stories) → technical planning (plans). Each phase +constrains the next. Reversing the order (e.g., defining architecture before +flows) would allow technical convenience to override user experience. + +### Validation as a future phase category + +The current pipeline validates artifacts through human review gates (the +`koan_review_artifact` mechanism). A future evolution would add automated +validation phases: an LLM agent that reads the brief, flows, and stories +together and checks for contradictions, coverage gaps, and assumption drift. + +The design principles that make this possible are already in place: + +- Artifacts are self-contained markdown files (no external state to query) +- Each artifact has a well-defined scope (brief = problem, flows = interactions, + stories = units of work) +- Cross-artifact consistency can be checked by reading multiple files + +When validation phases are added, they should follow the same subagent pattern: +step-first workflow, role-based permissions, artifact review for findings. The +validation agent reads artifacts, identifies issues, and presents findings +for human decision. + +### Toward an agentic workflow + +The current pipeline is a fixed linear sequence: every phase runs in order, +every phase is mandatory. This is the correct starting point — it ensures all +artifacts are always present and the cascade is complete. + +A future evolution decomposes this into an agentic workflow where an +orchestrating agent recommends which phase to run next based on the current +state of artifacts. For example: + +- After a brief is accepted, the agent might recommend core-flows for a + feature epic but skip to decomposition for a pure refactoring epic. +- After validation finds issues, the agent might recommend revising the + brief rather than patching the flows. +- After a requirement change, the agent might cascade updates through + the artifact chain in the correct order. + +The prerequisite for this evolution is that every phase can run independently +(given its input artifacts) and that the artifact contracts are well-defined. +The current mandatory pipeline establishes these contracts. The agentic +workflow relaxes the ordering while preserving the contracts. + +--- + +## Changes + +### 1. Flows-Writer Phase — `src/planner/phases/flows-writer/phase.ts` + +**New file.** Extends `BasePhase`. Role: `"flows-writer"`. Total steps: 6. + +Structural clone of `BriefWriterPhase` with the addition of the review gate +pattern. The key differences: + +- More steps (6 vs 3): Read → Explore → Align → Re-explore → Draft & Review → Finalize +- More tools: adds `koan_request_scouts` and `koan_ask_question` alongside + `koan_review_artifact` +- Same review gate on the Draft & Review step (step 5): `validateStepCompletion` + requires at least one accepted `koan_review_artifact` call before + `koan_complete_step` is allowed + +The 6-step design follows the single-cognitive-goal principle: + +| Step | Goal | Tools | +| ----------------- | --------------------------------------- | --------------------------- | +| 1. Read | Comprehend brief + landscape | (read-only) | +| 2. Explore | Ground in codebase reality | koan_request_scouts | +| 3. Align | Resolve design ambiguities with user | koan_ask_question | +| 4. Re-explore | Follow up on gaps revealed by alignment | koan_request_scouts | +| 5. Draft & Review | Produce and iterate on flows.md | write, koan_review_artifact | +| 6. Finalize | Phase complete | — | + +Steps 3 and 4 are deliberately separated: the architecture Pitfalls section +documents that combining "ask questions" and "follow-up investigation" in +one step lets the LLM produce superficial questions knowing it has a scout +escape hatch, or skip follow-up investigation by calling koan_complete_step +early. Separating them means questions are asked without knowing a follow-up +scout step exists, and the follow-up step runs regardless. + +**Review outcome tracking** follows the brief-writer pattern exactly: +`tool_call` listener marks `lastReviewAccepted = false` when +`koan_review_artifact` is called; `tool_result` listener checks for "ACCEPTED" +prefix and sets `true`. `validateStepCompletion(step === 5)` gates on this. + +**Step-level permission gating:** Step 1 (Read) is read-only — blocked via +`STEP_1_BLOCKED_TOOLS` in `checkPermission`. The permission fence reads +`ctx.flowsWriterStep` to determine the current step. All other steps have +full role permissions. + +```typescript +export class FlowsWriterPhase extends BasePhase { + protected readonly role = "flows-writer"; + protected readonly totalSteps = 6; + private lastReviewAccepted: boolean | null = null; + + constructor(pi, ctx, log?, eventLog?) { + super(pi, ctx, log, eventLog); + // Review outcome tracking (identical to BriefWriterPhase) + pi.on("tool_call", (event) => { + if (event.toolName === "koan_review_artifact") + this.lastReviewAccepted = false; + return undefined; + }); + pi.on("tool_result", (event) => { + if (event.toolName === "koan_review_artifact" && !event.isError) { + const text = event.content?.[0]; + if (text && "text" in text && typeof text.text === "string") + this.lastReviewAccepted = text.text.startsWith("ACCEPTED"); + } + }); + } + + protected override onStepUpdated(step: number): void { + this.ctx.flowsWriterStep = step; + } + + protected async validateStepCompletion(step: number): Promise<string | null> { + if (step === 5) { + if (this.lastReviewAccepted === null) + return "You must call koan_review_artifact on flows.md before completing this step."; + if (!this.lastReviewAccepted) + return "The user provided feedback — revise flows.md and present again."; + } + return null; + } +} +``` + +### 2. Flows-Writer Prompts — `src/planner/phases/flows-writer/prompts.ts` + +**New file.** System prompt + 6-step guidance. + +**System prompt** — establishes a product designer role focused on interaction +specification: + +``` +You are an interaction designer for a coding task planner. You read the epic +brief and codebase context, then design the core interaction flows — complete +user journeys from trigger to exit. + +## Your role + +You define WHAT the user experiences. You do NOT define scope boundaries +(that belongs to the decomposer) or implementation approach (that belongs +to the planner). You describe the interactions the product should support, +grounded in what actually exists in the codebase. + +## What you produce + +One file: **flows.md** in the epic directory. + +## Flow structure + +Each flow must contain: +- **Name and short description** +- **Trigger / entry point** — what initiates this flow +- **Steps** — user/system actions and responses, numbered +- **Exit condition** — what the user sees at completion + +Optional: +- Sequence diagrams (Mermaid) for multi-actor interactions +- ASCII wireframes for UI layout decisions +- Summary table at the end (Flow | Actor | Entry Point | Exit) + +## Constraints + +- Keep each flow under 30 lines. +- No code, no file paths, no component names. +- No technical implementation details — this is a product-level spec. +- Flows describe interactions between actors and systems — users, + operators, services, CLIs, data pipelines. Adapt to the domain. +- If the epic is a refactoring, flows describe the behavioral contracts + that must be preserved (what the user should continue to experience). + +## Design dimensions + +When designing each flow, think through: +1. **Information hierarchy** — what's critical vs. secondary +2. **User journey integration** — entry, exit, adjacent workflows +3. **Placement & affordances** — how actions are accessed and behave +4. **Feedback & state communication** — progress, success, errors, edge cases + +## Review + +After drafting, invoke `koan_review_artifact` to present flows.md for review. +If the user provides feedback, revise and present again. Continue until accepted. + +{REVIEW_PROTOCOL} +``` + +**Step 1 — Read** (read-only comprehension): + +``` +Read the following files to understand the problem space: + +- `{epicDir}/brief.md` — problem statement, goals, constraints +- `{epicDir}/landscape.md` — codebase findings, decisions, conventions + +Build a thorough mental model of: +- What is being built or changed, and why +- Who the actors are (users, operators, services, external systems) +- What interaction surface already exists +- What constraints bound the design + +Do NOT write files, request scouts, or ask questions in this step. +``` + +**Step 2 — Explore** (codebase grounding): + +``` +Explore the codebase to understand the current interaction surface. + +Use `koan_request_scouts` to dispatch investigators that map: +- Current user-facing interfaces (UI screens, CLI commands, API endpoints) +- Existing interaction patterns (navigation model, feedback patterns, error handling) +- Data availability at each interaction point (what information is accessible where) +- Adjacent workflows that the new flows must integrate with + +Ground your understanding in what actually exists. Flows designed without +codebase grounding will diverge from the system's real structure. +``` + +**Step 3 — Align** (interaction design alignment): + +``` +Think through the interaction design decisions for this epic, then +align with the user on points of ambiguity. + +For each potential flow, consider the four design dimensions: +- Information hierarchy: what's critical vs. secondary? +- User journey integration: where does the user come from and go next? +- Placement & affordances: how are actions accessed? +- Feedback & state: how does the user know what's happening? + +For points of ambiguity or uncertainty, use `koan_ask_question` to +align with the user. Ask about substantive decisions that shape the +experience — not nitpicky details where a reasonable default exists. + +Ground questions in codebase findings: "Scout found the current +dashboard shows X — should the new flow integrate here or as a +separate view?" + +Multiple rounds of questions is normal. The goal is shared understanding +before drafting, not speed. + +Do NOT request scouts in this step — focus on alignment questions only. +If the user's answers reveal codebase areas you haven't investigated, +note them. The next step is specifically for follow-up exploration. +``` + +**Step 4 — Re-explore** (follow-up codebase investigation): + +``` +Based on the alignment decisions from step 3, determine whether +follow-up codebase exploration is needed. + +If the user's answers revealed: +- Areas of the codebase you haven't investigated +- Integration points that need verification +- Patterns or conventions that affect flow design + +Use `koan_request_scouts` to dispatch targeted investigations. + +If no follow-up exploration is needed, call koan_complete_step +with a note that alignment is sufficient to proceed to drafting. + +Do NOT ask the user questions in this step — that was step 3's +mandate. This step is for investigation only. +``` + +**Step 5 — Draft & Review** (artifact production): + +``` +Write `{epicDir}/flows.md` with all interaction flows. + +Structure each flow as documented in your system prompt: +name, trigger, numbered steps, exit. Keep each flow under 30 lines. +No code, no file paths, no component names. + +If the epic involves multiple distinct interaction paths, include a +summary table at the end: + +| Flow | Actor | Entry Point | Exit | + +After writing, invoke `koan_review_artifact` with the path to flows.md. + +If the user responds with feedback, revise to address every point, +then invoke koan_review_artifact again. + +If the user accepts, call koan_complete_step. +``` + +**Step 6 — Finalize**: "Phase complete." + +### 3. Type Foundations — `src/planner/types.ts` + +Add `"flows-writer"` to `SubagentRole`: + +```typescript +export type SubagentRole = + | "intake" + | "scout" + | "decomposer" + | "brief-writer" + | "flows-writer" + | "orchestrator" + | "planner" + | "executor"; +``` + +Add `"flows"` to `EpicPhase`: + +```typescript +export type EpicPhase = + | "intake" + | "brief" + | "flows" + | "decomposition" + | "review" + | "executing" + | "completed"; +``` + +Add to `ROLE_MODEL_TIER` — use `"strong"` (interaction design requires +genuine reasoning about user experience, not mechanical transformation): + +```typescript +"flows-writer": "strong", +``` + +### 4. Task Manifest — `src/planner/lib/task.ts` + +Add `FlowsWriterTask` interface: + +```typescript +export interface FlowsWriterTask extends SubagentTaskBase { + role: "flows-writer"; +} +``` + +Add to `SubagentTask` union: + +```typescript +export type SubagentTask = + | IntakeTask + | ScoutTask + | DecomposerTask + | BriefWriterTask + | FlowsWriterTask + | OrchestratorTask + | PlannerTask + | ExecutorTask; +``` + +### 5. Permissions — `src/planner/lib/permissions.ts` + +Add `"flows-writer"` to `ROLE_PERMISSIONS`: + +```typescript +[ + "flows-writer", + new Set([ + "koan_complete_step", + "koan_review_artifact", + "koan_ask_question", + "koan_request_scouts", + "edit", + "write", + ]), +], +``` + +This is the most tool-rich planning role. It needs: + +- Scouts for codebase exploration (grounding) +- Questions for interaction design alignment +- Artifact review for the draft-revise loop +- Write/edit for producing flows.md + +Add `"flows-writer"` to `PLANNING_ROLES` (path-scoped to epic directory). + +Add `flowsWriterStep` as the 7th parameter to `checkPermission`: + +```typescript +export function checkPermission( + role: string, + toolName: string, + epicDir?: string, + toolArgs?: Record<string, unknown>, + intakeStep?: number, + briefWriterStep?: number, + flowsWriterStep?: number, // ← new parameter +): { allowed: boolean; reason?: string } { +``` + +Add step 1 gating block (after the brief-writer step 1 block): + +```typescript +if ( + role === "flows-writer" && + flowsWriterStep === 1 && + STEP_1_BLOCKED_TOOLS.has(toolName) +) { + return { + allowed: false, + reason: + `${toolName} is not available during the Read step (step 1). ` + + "Complete koan_complete_step first to advance to the Explore step.", + }; +} +``` + +Update the `STEP_1_BLOCKED_TOOLS` comment to include flows-writer: + +```typescript +// STEP_1_BLOCKED_TOOLS: tools disallowed during the intake Extract step (step 1), +// brief-writer Read step (step 1), and flows-writer Read step (step 1). +``` + +**Note on parameter proliferation:** The `checkPermission` function already +takes `intakeStep` and `briefWriterStep` as separate parameters. Adding +`flowsWriterStep` continues this pattern. Consider consolidating these into a +single `{ role, step }` object in a follow-up refactor, but do not block this +change on that refactor. + +### 5a. Call-Site Update — `src/planner/phases/base-phase.ts` + +The only call to `checkPermission` lives in `base-phase.ts`'s `tool_call` +event handler (lines 100–106). It currently passes 6 arguments. Add +`this.ctx.flowsWriterStep` as the 7th argument: + +```typescript +const perm = checkPermission( + this.role, + event.toolName, + this.ctx.epicDir ?? undefined, + event.input as Record<string, unknown>, + this.ctx.intakeStep, + this.ctx.briefWriterStep, + this.ctx.flowsWriterStep, // ← new argument +); +``` + +**Why this is critical:** Without this change, `checkPermission` receives +`undefined` for `flowsWriterStep`. The gate check +`role === "flows-writer" && undefined === 1` evaluates to `false` — the +step 1 write-block silently never fires. TypeScript does not catch this +because the parameter is optional. The architecture Pitfalls section +documents this exact failure mode: "The original 3-step intake design told +the LLM not to scout in step 1; it frontloaded all work into step 1 anyway." +The mechanical gate exists to prevent this; omitting the call-site update +renders it inoperative. + +### 6. Runtime Context — `src/planner/lib/runtime-context.ts` + +Add `flowsWriterStep` field to `RuntimeContext` interface: + +```typescript +flowsWriterStep: number; +``` + +Initialize to `0` in `createRuntimeContext()`: + +```typescript +flowsWriterStep: 0, +``` + +This mirrors the `briefWriterStep` pattern exactly: non-optional, initialized +to `0`, updated by `FlowsWriterPhase.onStepUpdated()`, read by the permission +fence in `checkPermission`. The `0` initial value is safe because the step 1 +gate checks `=== 1`, so `0` does not trigger blocking. + +Add a doc comment mirroring the existing `briefWriterStep` comment: + +```typescript +// flowsWriterStep mirrors intakeStep/briefWriterStep for the flows-writer +// role: the permission fence uses it to block write/edit/scouts/questions +// during the read-only Read step (step 1). +``` + +### 7. Dispatch — `src/planner/phases/dispatch.ts` + +Add `"flows-writer"` case: + +```typescript +case "flows-writer": { + const phase = new FlowsWriterPhase(pi, ctx, logger, eventLog); + await phase.begin(); + break; +} +``` + +Add import: + +```typescript +import { FlowsWriterPhase } from "./flows-writer/phase.js"; +``` + +### 8. Driver — `src/planner/driver.ts` + +Add `runFlowsWriter` function (parallel to `runBriefWriter`): + +```typescript +async function runFlowsWriter( + epicDir: string, + cwd: string, + extensionPath: string, + log: Logger, + webServer: WebServerHandle | null, +): Promise<boolean> { + const subagentDir = await ensureSubagentDirectory(epicDir, "flows-writer"); + const opts: SpawnOptions = { + cwd, + extensionPath, + log, + webServer: webServer ?? undefined, + }; + const result = await spawnTracked( + "flows-writer", + "flows-writer", + "flows-writer", + { role: "flows-writer", epicDir }, + subagentDir, + undefined, + opts, + webServer, + ); + if (result.exitCode !== 0) { + log("Flows writer failed", { exitCode: result.exitCode }); + return false; + } + return true; +} +``` + +Insert between brief and decomposition in `runPipeline`: + +```typescript +// After brief succeeds: +const afterBrief = await loadEpicState(epicDir); +await saveEpicState(epicDir, { ...afterBrief, phase: "flows" }); +webServer?.pushPhase("flows"); + +const flowsOk = await runFlowsWriter( + epicDir, + cwd, + extensionPath, + log, + webServer, +); +if (!flowsOk) + return { success: false, summary: "Core flows generation failed" }; + +// Continue to decomposition: +const afterFlows = await loadEpicState(epicDir); +await saveEpicState(epicDir, { ...afterFlows, phase: "decomposition" }); +webServer?.pushPhase("decomposition"); +``` + +### 9. Downstream Prompt Updates + +**`src/planner/phases/decomposer/prompts.ts`** — Step 1 (Analysis): + +Add `flows.md` to the files-to-read list: + +```typescript +`- \`${epicDir}/flows.md\` — core interaction flows: triggers, user actions, exit conditions`, +``` + +Add to "What to understand": + +``` +- What interaction flows has the user approved? Stories must implement + these flows — do not invent interaction patterns not present in flows.md. +``` + +Add to system prompt strict rules: + +``` +- MUST NOT invent interaction patterns not present in flows.md. +- SHOULD trace each story to one or more flows it implements. +``` + +**`src/planner/phases/planner/prompts.ts`** — Step 1 (Analysis): + +Add after the brief.md reading instruction: + +```typescript +`4. Read \`${epicDir}/flows.md\` — understand the interaction flows this story ` + +`implements. The plan must produce the behavior described in these flows.`, +``` + +**`src/planner/phases/orchestrator/prompts.ts`** — Two updates: + +_Pre-execution step 1 (Dependency Analysis):_ Add `flows.md` to the reading +list, after the `brief.md` instruction: + +```typescript +`5. Read \`${epicDir}/flows.md\` — understand the interaction flows. ` + +`Stories should trace to specific flows they implement.`, +``` + +_Post-execution step 1 (Verify):_ Add `flows.md` to the "What to read" +section, after the story.md acceptance criteria instruction: + +```typescript +`3. Read \`${epicDir}/flows.md\` — understand the interaction flows this ` + +`story implements. Verify the implementation produces the behavior ` + +`described in the relevant flows.`, +``` + +The post-execution step 1 is where the orchestrator checks story correctness. +Adding flows.md here closes the traceability chain: brief → flows → stories → +verification. Without it, the orchestrator verifies against acceptance criteria +(from story.md) but not against the interaction specification those criteria +were derived from. + +### 10. Web UI Updates + +**`src/planner/web/js/components/PillStrip.jsx`** — Add "flows" pill: + +```javascript +const PHASES = [ + { id: "intake", label: "intake" }, + { id: "brief", label: "brief" }, + { id: "flows", label: "flows" }, + { id: "decomposition", label: "decompose" }, + { id: "review", label: "review" }, + { id: "executing", label: "execute" }, +]; + +const PHASE_ORDER = [ + "intake", + "brief", + "flows", + "decomposition", + "review", + "executing", + "completed", +]; +``` + +**`src/planner/web/js/components/ProgressBar.jsx`** (if separate `PHASE_ORDER` +exists): Add `'flows'` between `'brief'` and `'decomposition'`. + +### 11. Documentation + +**New file: `docs/core-flows.md`** + +Spoke document covering: + +1. **What flows capture** — interaction specifications between actors and + systems. Trigger, steps, exit. Product-level, no code. + +2. **Pipeline position** — after brief, before decomposition. The brief + defines the problem; flows define the experience; stories define the work. + +3. **Flows-writer subagent** — role, model tier, 6-step workflow with + rationale for each step: + - Step 1 (Read): comprehension before action — same principle as all phases + - Step 2 (Explore): codebase grounding prevents specification drift + - Step 3 (Align): design decisions through targeted questions, before + any artifact is drafted. No scouting — single cognitive goal. + - Step 4 (Re-explore): follow-up investigation based on alignment answers. + No questions — single cognitive goal. Separating steps 3 and 4 prevents + the LLM from producing superficial questions knowing it has a scout + escape hatch. + - Step 5 (Draft & Review): the review gate — mechanical enforcement of + human acceptance + - Step 6 (Finalize): standard termination + +4. **Permissions** — why flows-writer is the most tool-rich planning role + (scouts + questions + review). Comparison to brief-writer (review only) + and intake (scouts + questions but different purpose). + +5. **Downstream references** — table of which phases read flows.md and why. + +6. **Design dimensions** — the four dimensions (information hierarchy, user + journey integration, placement & affordances, feedback & state) and why + they surface architectural implications, not just aesthetic preferences. + +7. **Design principles** — these are captured for future reference, not + implemented now: + - Artifact-as-contract pattern and audit trail + - Product-before-technical ordering rationale + - Validation gates as a future phase category + - Agentic workflow progression from fixed pipeline to adaptive ordering + +**Update: `docs/architecture.md`** + +- Pipeline description: `intake → brief → flows → decomposition → review → executing → completed` +- Phase list: add flows-writer entry +- Artifact cascade diagram: add flows.md layer +- Update the "Pitfalls" section if any flows-specific pitfalls emerge + +**Update: `docs/epic-brief.md`** + +- Pipeline position diagram: insert `flows` between `brief` and `decomposition` +- Downstream references table: add flows-writer as a consumer of brief.md + +**Update: `docs/subagents.md`** + +- Task manifest union: add `FlowsWriterTask` variant (role: `"flows-writer"`, + no role-specific fields beyond `SubagentTaskBase`). +- Role permission matrix: add `flows-writer` row — koan tools: + `koan_complete_step`, `koan_review_artifact`, `koan_ask_question`, + `koan_request_scouts`; write/edit: path-scoped to epicDir; notes: + step 1 (Read) blocks all side-effecting tools. +- Model tiers table: add `flows-writer` to `strong` tier row. +- Back-fill the missing `brief-writer` entry (pre-existing gap from the prior + phase implementation): `BriefWriterTask` variant, permission row with + `koan_complete_step`, `koan_review_artifact`, path-scoped write, step 1 + read-only gating. + +**Update: `AGENTS.md`** + +- Phase list: `intake → brief → flows → decomposition → review → executing → completed` + +--- + +## Implementation Order + +The dependency chain: + +1. **Type foundations** (`types.ts`) — `SubagentRole`, `EpicPhase`, `ROLE_MODEL_TIER` +2. **Task manifest** (`task.ts`) — `FlowsWriterTask` interface + union +3. **Runtime context** (`runtime-context.ts`) — `flowsWriterStep` field +4. **Permissions** (`permissions.ts`) — role + step gating + 7th parameter +5. **Call-site update** (`base-phase.ts`) — pass `ctx.flowsWriterStep` to `checkPermission` +6. **Phase + prompts** (`flows-writer/phase.ts`, `flows-writer/prompts.ts`) +7. **Dispatch** (`dispatch.ts`) — route to `FlowsWriterPhase` +8. **Driver** (`driver.ts`) — insert phase in pipeline +9. **Downstream prompts** (decomposer, planner, orchestrator) +10. **Web UI** (PillStrip, ProgressBar) +11. **Documentation** (core-flows.md, architecture.md, epic-brief.md, subagents.md, AGENTS.md) + +--- + +## Files Summary + +| Action | File | What | +| ------ | ----------------------------------------------- | ----------------------------------------------------------------------------- | +| Modify | `src/planner/types.ts` | Add `"flows-writer"` to SubagentRole, `"flows"` to EpicPhase, ROLE_MODEL_TIER | +| Modify | `src/planner/lib/task.ts` | Add `FlowsWriterTask` + union member | +| Modify | `src/planner/lib/runtime-context.ts` | Add `flowsWriterStep: number` field + init to 0 | +| Modify | `src/planner/lib/permissions.ts` | Add `flows-writer` role, step 1 gating, PLANNING_ROLES, 7th param | +| Modify | `src/planner/phases/base-phase.ts` | Pass `ctx.flowsWriterStep` as 7th arg to `checkPermission` | +| New | `src/planner/phases/flows-writer/phase.ts` | FlowsWriterPhase (6 steps, review gate on step 5) | +| New | `src/planner/phases/flows-writer/prompts.ts` | System prompt + 6-step guidance | +| Modify | `src/planner/phases/dispatch.ts` | Add `"flows-writer"` case + import | +| Modify | `src/planner/driver.ts` | Insert flows phase between brief and decomposition | +| Modify | `src/planner/phases/decomposer/prompts.ts` | Add flows.md to reading list + strict rules | +| Modify | `src/planner/phases/planner/prompts.ts` | Add flows.md to reading list | +| Modify | `src/planner/phases/orchestrator/prompts.ts` | Add flows.md to pre-exec + post-exec step 1 | +| Modify | `src/planner/web/js/components/PillStrip.jsx` | Add "flows" pill + PHASE_ORDER | +| Modify | `src/planner/web/js/components/ProgressBar.jsx` | Add "flows" to PHASE_ORDER (if separate) | +| New | `docs/core-flows.md` | Spoke document: flows artifact, subagent, design principles | +| Modify | `docs/architecture.md` | Pipeline + phase list + artifact cascade | +| Modify | `docs/epic-brief.md` | Pipeline position + downstream references | +| Modify | `docs/subagents.md` | FlowsWriterTask + permission row + model tier; back-fill brief-writer | +| Modify | `AGENTS.md` | Phase list update | diff --git a/plans/2026-03-26-koan-debug-step-prompts.md b/plans/2026-03-26-koan-debug-step-prompts.md new file mode 100644 index 0000000..bf98072 --- /dev/null +++ b/plans/2026-03-26-koan-debug-step-prompts.md @@ -0,0 +1,493 @@ +# `--koan-debug`: Step Prompt Visibility + +> **Date:** 2026-03-26 +> **Scope:** Add a parent-session CLI flag `--koan-debug` that surfaces +> verbatim step guidance text in the koan web UI activity feed. Lays the +> minimal extensibility seam for future per-tool debug rendering (bash, read, +> grep, find, etc.). No new persistence infrastructure; reuses data already +> captured in the audit pipeline. + +--- + +## 1. Objective + +When a developer invokes koan with `--koan-debug`, the activity feed shows +the exact step guidance text returned by each `koan_complete_step` call as an +expandable body on the step line. This allows developers to audit the prompts +being sent to LLM subagents without altering the pipeline logic or normal-mode +output. + +--- + +## 2. Non-Goals + +- **Not a full LLM context window dump.** Only koan-controlled fragments + (step guidance from `formatStep`, system prompt from `BasePhase`) are + accessible via the extension API. The full messages array (conversation + history, accumulated tool results) is assembled internally by pi and is + not exposed. The plan does not attempt to capture what pi cannot surface. + +- **Not a general logging overhaul.** `koan.log` is unchanged. No new + file types are added for this iteration. + +- **Not a streaming/real-time diff viewer.** Step prompts are displayed as + static expandable text in the activity feed — no syntax highlighting, + diffing, or side-by-side comparison. + +- **No changes to normal (non-debug) mode output.** Audit event schemas, + `Projection`, `state.json`, `ipc.json`, and all UI behaviour are identical + to today when `--koan-debug` is absent. + +- **No bash/read/grep/find debug output in this iteration.** The extensibility + seam for future tool-output debug is defined but not activated. + +--- + +## 3. Constraints + +- The architecture invariant "don't pass structured data through CLI flags" + (docs/architecture.md §6) applies. `--koan-debug` is a rendering toggle, + not task data. It is a bootstrap signal (analogous to `--mode json`), + not a subagent task parameter, so passing it as a CLI flag to child + processes is correct. It must NOT go into `task.json`. + +- All tool registrations must remain unconditional at init. The debug flag + cannot gate tool registration. + +- Performance must not degrade in non-debug mode. The 50ms audit polling loop + and `state.json` projection must be unaffected. No new data enters + `Projection`; step prompt text must not be written to `state.json`. + +- Debug gating must be at data-production time (before string serialisation), + not at render time. Serialising 2–5 KB of step guidance text per step into + `events.jsonl` unconditionally would add unnecessary I/O. + +--- + +## 4. Architecture Overview + +### 4.1 Existing data path (unchanged) + +``` +BasePhase.handleStepComplete() + → formatStep(getStepGuidance(step)) ← prompt string created here + → koan_complete_step tool result + → extractToolResult() ← stores koanResponse on ToolResultEvent + → events.jsonl append + → audit-log-formatter.ts ← koan_complete_step currently filtered out + → LogLine[] → SSE → ActivityFeed +``` + +`koanResponse` already carries the step prompt text for koan tools. The +formatter explicitly drops `koan_complete_step` results. The UI never sees +them. + +`LogLine` already has a `body?: string` field that renders as expandable +text (used today for thinking cards in `ActivityFeed.jsx`). + +### 4.2 Debug path (new) + +``` +CLI: pi --koan-debug ... + → extensions/koan.ts: reads flag, sets ctx.debugMode = true + → koan_plan.execute: passes debugMode into runPipeline() + → driver.ts: threads debugMode through SpawnOptions + → subagent.ts: appends --koan-debug to child pi args when debugMode=true + +Child process sees --koan-debug → ctx.debugMode = true + +audit-log-formatter.ts: readRecentLogs(dir, count, { debug }) + → in debug mode, koan_complete_step NOT filtered + → step line gets body = koanResponse.join('\n') + → ActivityFeed renders expandable step card +``` + +The key insight: `koanResponse` already exists on every `tool_result` event +for `koan_*` tools. No new event type, no new capture logic, no new file. +The only change is a conditional in the formatter's filter. + +--- + +## 5. Implementation Plan + +### Phase 1 — Flag registration and plumbing (parent side) + +**File: `extensions/koan.ts`** + +- Register `--koan-debug` flag unconditionally: + ```ts + pi.registerFlag("koan-debug", { + description: + "Developer mode: show verbatim step prompts in the activity feed.", + type: "boolean", + default: false, + }); + ``` +- In `before_agent_start` handler (subagent mode): + ```ts + ctx.debugMode = !!pi.getFlag("koan-debug"); + ``` +- In `koan_plan.execute` (parent mode), read the flag and pass it to + `startWebServer` and `runPipeline`. `startWebServer` is constructed here + (not inside `runPipeline`), so both calls happen in `koan_plan.execute`: + ```ts + const debugMode = !!pi.getFlag("koan-debug"); + const server = await startWebServer(epicDir, { port, token, debugMode }); + // ... + const result = await runPipeline(epicDir, cwd, extensionPath, log, server, { + debugMode, + }); + ``` + +**File: `src/planner/lib/runtime-context.ts`** + +- Add `debugMode: boolean` to `RuntimeContext` interface (default `false` + in `createRuntimeContext()`). + +**File: `src/planner/subagent.ts`** + +- Add `debugMode: boolean` (non-optional) to `SpawnOptions`. Non-optional + is intentional: every `SpawnOptions` literal in `driver.ts` must explicitly + set it, so TypeScript catches any missed call site at compile time. +- In args construction, after the model flag: + ```ts + ...(opts.debugMode ? ["--koan-debug"] : []), + ``` +- In `makeScoutSpawnContext`, forward `debugMode` from parent opts: + ```ts + const result = await spawnSubagent(task, scoutSubagentDir, { + cwd: opts.cwd, + extensionPath: opts.extensionPath, + debugMode: opts.debugMode, // ← add + log, + }); + ``` + +**File: `src/planner/driver.ts`** + +- `runPipeline` gains a `PipelineOptions` object as its final parameter: + ```ts + export async function runPipeline( + epicDir: string, + cwd: string, + extensionPath: string, + log: Logger, + webServer: WebServerHandle | null, + opts: { debugMode: boolean } = { debugMode: false }, + ): Promise<{ success: boolean; summary: string }>; + ``` +- Thread `debugMode` into the `SpawnOptions` at every construction site. + There are **five** `SpawnOptions` construction sites (each function creates + one `opts` object shared across all its `spawnTracked` calls): + - `runSimplePhase` — one `opts` object + - `runStoryExecution` — one `opts` object shared across planner, executor, + and post-orchestrator `spawnTracked` calls + - `runStoryReexecution` — one `opts` object shared across executor and + post-orchestrator `spawnTracked` calls + - `runWorkflowOrchestrator` — one `opts` object + - `runStoryLoop` pre-execution orchestrator block — one `opts` object + + Concrete pattern (same at every site): + + ```ts + const opts: SpawnOptions = { cwd, extensionPath, log, webServer: ..., debugMode }; + ``` + +> **Typo-safety:** use a single exported constant `export const KOAN_DEBUG_FLAG = +"koan-debug" as const` in a small `src/planner/lib/constants.ts` (or +> similar) file. Import it at both `registerFlag(KOAN_DEBUG_FLAG, ...)` and +> `["--" + KOAN_DEBUG_FLAG]`. This makes the compiler catch divergence. + +--- + +### Phase 2 — Formatter changes (rendering side) + +**File: `src/planner/lib/audit-log-formatter.ts`** + +`readRecentLogs` gains an optional options parameter: + +```ts +export async function readRecentLogs( + dir: string, + count = 8, + opts?: { debug?: boolean }, +): Promise<LogLine[]> { + ... + return buildChronologicalLog(events, count, opts?.debug ?? false); +} +``` + +No change to `src/planner/lib/audit.ts` — it barrel-re-exports +`readRecentLogs` from `audit-log-formatter.ts` and the updated signature +propagates automatically. + +`buildChronologicalLog` gains a `debug: boolean` parameter. In the +`tool_result` handler inside that function, change: + +```ts +// Before (hard filter): +if (e.tool === "koan_complete_step") { + pendingCalls.delete(e.toolCallId); + continue; +} + +// After (conditional): +if (e.tool === "koan_complete_step") { + pendingCalls.delete(e.toolCallId); + if (debug && e.koanResponse?.length) { + // Attach prompt body to the most recent step line. + // step_transition fires immediately before koan_complete_step result, + // so lines[lines.length - 1] is the step line when it exists. + const last = lines[lines.length - 1]; + if (last?.tool === "step") { + last.body = e.koanResponse.join("\n"); + } + } + continue; +} +``` + +> **Ordering guarantee:** `step_transition` is emitted by `handleStepComplete` +> before `formatStep()` returns its value, which becomes the tool result text. +> Both appends happen in the same serialised `EventLog.append` promise chain, +> so the order in `events.jsonl` is always: `step_transition` → `tool_result` +> for `koan_complete_step`. The retroactive assignment to `lines[lines.length - 1]` +> is safe because `lines` is local state and no other events push new lines +> between these two events. +> +> **"Phase complete." edge case:** When `handleStepComplete` returns `null` +> (phase done), `koan_complete_step` still fires as a `tool_result` with +> `koanResponse = ["Phase complete."]`, but `step_transition` is NOT emitted +> at that point — `phase_end` is emitted instead. `lines[lines.length - 1]` +> will be a `phase_end` line (if rendered) or a prior step line, not a +> `step` line, so the `last?.tool === "step"` guard silently skips body +> attachment. Correct behaviour, no special case needed. +> +> This retroactive pattern is identical to how `thinking` events attach +> body text to previously-emitted thinking lines in the same loop. + +**Call sites of `readRecentLogs` in `server.ts`:** + +Two locations poll logs: + +1. `pollAgent()` (~line 474) — for agent-level polling; does NOT need debug + (this feeds the small agent monitor cards). +2. `trackSubagent()` timer (~line 884) — this is the main activity feed source. + Pass `{ debug: debugMode }` here. + +`WebServerOptions` (defined in `src/planner/web/server.ts`) gains a +`debugMode?: boolean` field. `server.ts` stores it as a local constant and +passes it into the `readRecentLogs` call inside the tracking timer. + +`koan_plan.execute` in `extensions/koan.ts` passes `debugMode` when calling +`startWebServer` (see Phase 1). + +--- + +### Phase 3 — Extensibility seam for future tool outputs (minimal, no activation) + +This phase defines the contract without implementing any per-tool debug +rendering. + +**Formatter seam in `audit-log-formatter.ts`** + +In `formatPairedResult()` and `formatInFlightCall()`, add an optional hook +point at the end of every non-koan branch: + +```ts +// Placeholder for future debug body rendering. +// In debug mode, a per-tool formatter may populate line.body. +// See: formatDebugBody(tool, input, e.debugOutput) +``` + +No code is added to these functions yet. The comment documents the intended +extension point so future contributors know where to add tool-specific +rendering without reading the history. + +**`ToolResultEvent` schema preparation (`audit-events.ts`)** + +Add an optional field to `ToolResultEvent`: + +```ts +// Reserved for debug mode: bounded preview of tool output content. +// Populated by extractToolResult() when debugMode is active. +// NOT written in normal mode. Never folded into Projection. +debugOutput?: string; +``` + +**`extractToolResult` in `event-log.ts`** + +The function signature gains an optional `debug` flag: + +```ts +export function extractToolResult( + piEvent: PiToolResultEvent, + opts?: { debug?: boolean }, +): ToolResultEvent; +``` + +When `opts?.debug` is true AND the tool is in a designated set (initially +`bash` only, as a proof of concept): + +```ts +const DEBUG_CAPTURE_TOOLS = new Set(["bash"]); +if (opts?.debug && DEBUG_CAPTURE_TOOLS.has(toolName) && !isError) { + const text = content.find((c) => c.type === "text")?.text ?? ""; + ev.debugOutput = + text.slice(0, 4096) + (text.length > 4096 ? "\n…[truncated]" : ""); +} +``` + +**Call site update in `extensions/koan.ts`** + +The `tool_result` handler must pass `{ debug: ctx.debugMode }` for the seam +to function. Without this, `debugOutput` is never populated regardless of +flag state: + +```ts +pi.on("tool_result", (event) => { + void eventLog.append( + extractToolResult(event as { ... }, { debug: ctx.debugMode }) + ); +}); +``` + +**This field is defined but the formatter does not yet render it.** The +extensibility seam is: + +1. `ToolResultEvent.debugOutput?` — capture contract (defined now, unused by + formatter until Phase 4). +2. `formatDebugBody(tool, input, debugOutput)` — pure formatter function + (stub comment now, implemented in Phase 4). +3. `LogLine.body` — UI rendering (already works, nothing to add). + +Phase 4 (out of scope for this plan) activates the seam for each desired tool. + +--- + +## 6. File-by-File Change Summary + +| File | Change | +| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `extensions/koan.ts` | Register `--koan-debug` flag; read in both parent (`koan_plan.execute`) and subagent (`before_agent_start`) modes; pass `debugMode` to `startWebServer` and `runPipeline`; update `tool_result` handler to pass `{ debug: ctx.debugMode }` to `extractToolResult` | +| `src/planner/lib/runtime-context.ts` | Add `debugMode: boolean` field (default `false`) | +| `src/planner/lib/constants.ts` _(new)_ | `export const KOAN_DEBUG_FLAG = "koan-debug" as const` | +| `src/planner/subagent.ts` | Add `debugMode: boolean` (non-optional) to `SpawnOptions`; append `--koan-debug` arg conditionally; forward in `makeScoutSpawnContext` | +| `src/planner/driver.ts` | Add `PipelineOptions` param to `runPipeline`; thread `debugMode` into all five `SpawnOptions` construction sites | +| `src/planner/web/server.ts` | Add `debugMode?: boolean` to `WebServerOptions`; pass `{ debug: debugMode }` to `readRecentLogs` in the `trackSubagent` timer | +| `src/planner/lib/audit-log-formatter.ts` | Add `debug` param to `readRecentLogs` and `buildChronologicalLog`; conditionally attach `koanResponse` body to step lines; add extension seam comment in `formatPairedResult`/`formatInFlightCall` | +| `src/planner/lib/audit-events.ts` | Add `debugOutput?: string` to `ToolResultEvent` | +| `src/planner/lib/event-log.ts` | Add `opts?: { debug? }` to `extractToolResult`; populate `debugOutput` for bash when debug is on | + +No changes to: `src/planner/lib/audit.ts` (barrel re-export propagates +updated `readRecentLogs` automatically), `base-phase.ts`, `step.ts`, +`workflow.ts`, `audit-fold.ts`, `ActivityFeed.jsx`, `store.js`, `sse.js`. +The activity feed already renders `LogLine.body` as an expandable card. + +--- + +## 7. Testing Strategy + +### Unit tests (add to `tests/`) + +**`tests/audit-log-formatter.test.ts`** — new or extend existing: + +- `readRecentLogs` with `debug: false` returns no body on step lines when + `koan_complete_step` events are present in the JSONL. +- `readRecentLogs` with `debug: true` returns `body` matching `koanResponse` + on the step line that precedes a `koan_complete_step` tool result. +- `readRecentLogs` with `debug: true` when `koanResponse` is empty does not + set `body` (no empty-string body pollution). +- `buildChronologicalLog` output is byte-identical for non-debug input + regardless of the `debug` flag. +- `readRecentLogs` with `debug: true` and a `koan_complete_step` result + where `koanResponse = ["Phase complete."]` (phase-end case) does NOT attach + a body to any step line (verifies the `last?.tool === "step"` guard). + +**`tests/subagent-args.test.ts`** — new: + +- `spawnSubagent` with `debugMode: false` produces args that do not include + `--koan-debug`. +- `spawnSubagent` with `debugMode: true` produces args that include + `--koan-debug`. + +**`tests/event-log.test.ts`** — new or extend existing (covers Phase 3 seam): + +- `extractToolResult` with `{ debug: false }` never sets `debugOutput` for + `bash` tool results. +- `extractToolResult` with `{ debug: true }` and bash output ≤ 4096 chars + sets `debugOutput` to the full text with no truncation marker. +- `extractToolResult` with `{ debug: true }` and bash output > 4096 chars + sets `debugOutput` truncated to 4096 chars with `"\n…[truncated]"` appended. +- `extractToolResult` with `{ debug: true }` and `isError: true` does not + set `debugOutput`. +- `extractToolResult` with `{ debug: true }` for a tool not in + `DEBUG_CAPTURE_TOOLS` (e.g. `read`) does not set `debugOutput`. + +### Integration / manual checks + +- Start koan **without** `--koan-debug`. Verify: + - Step lines in activity feed show step name, no expandable body. + - `state.json` unchanged from pre-feature baseline. + - `ipc.json` unchanged. + - `koan.log` unchanged. + +- Start koan **with** `--koan-debug`. Verify: + - Step lines in activity feed are expandable. + - Expanded text matches the step title and instructions exactly (check + against `formatStep` output for that phase/step). + - Scout subagents also emit step prompts (confirm scouts receive the flag: + check `stdout.log` of a scout subagentDir for `--koan-debug` in the + spawned pi args; verify `debugMode: opts.debugMode` is set inside + `makeScoutSpawnContext`). + - Multi-step phase: each step transition gets its own body; no body from + step N contaminates step N+1. + +--- + +## 8. Risks and Mitigations + +| Risk | Severity | Mitigation | +| ------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Flag string typo creates silent failure (parent registers one string, child spawn uses another) | High | Single `KOAN_DEBUG_FLAG` constant imported at both sites; TypeScript catches divergence. | +| Missed `SpawnOptions` construction site in `driver.ts` silently skips flag forwarding for one subagent class | High | `SpawnOptions.debugMode` is non-optional (`boolean`, not `boolean?`); every literal must set it or the file fails to compile. | +| `--koan-debug` propagated to scout subagents but scout step prompts visible only post-mortem in `events.jsonl` (no live UI feed for scouts) | Low | Expected: scouts have no `trackSubagent` feed. Document in flag description. Acceptable for this iteration. | +| `debugOutput` field on `ToolResultEvent` not folded, but future contributor folds it into `Projection` by mistake, bloating `state.json` | Medium | Add `// NOTE: not folded — debug-only; never add to Projection` in `audit-events.ts` and a no-op `case "step_prompt"` in `audit-fold.ts fold()` to make the decision explicit. | +| Retroactive body attachment in formatter attaches to wrong line if event ordering changes | Low | `EventLog.append` is serialised via promise chain; ordering is guaranteed. Add assertion in test that step body is attached to the correct step index. | +| `body` field renders poorly for multi-line prompt text in `ActivityFeed` | Low | `activity-card-body` uses `white-space: pre-wrap` in `layout.css`; no change needed. Verify in manual test. | + +--- + +## 9. Rollout + +1. Implement Phase 1 (flag plumbing) — no observable behaviour change. +2. Implement Phase 2 (formatter) — feature is live behind `--koan-debug`. +3. Implement Phase 3 (extensibility seam) — schema and comment stubs only. +4. Run unit tests and manual integration checks. +5. Ship. No feature flag, no migration, no deprecation window needed. + +Phase 4 (per-tool debug rendering for bash/read/grep/find) is a separate +plan. The extensibility seam in Phase 3 ensures it can be added without +touching any of the files modified here. + +--- + +## 10. Acceptance Criteria + +- [ ] `pi --koan-debug` is accepted without error by the parent session. +- [ ] Without `--koan-debug`, activity feed behaviour is identical to today. +- [ ] With `--koan-debug`, each step line in the activity feed has an + expandable body containing the verbatim step guidance text. +- [ ] The expanded text matches `formatStep(getStepGuidance(step))` output + for the corresponding step (verified by inspection for intake phase steps + 1 and 2 at minimum). +- [ ] Scout subagents receive `--koan-debug` in their spawn args (verified + via `stdout.log` grep in a scout subagentDir; confirm forwarding inside + `makeScoutSpawnContext`). +- [ ] `state.json` does not contain step prompt text in either mode. +- [ ] Unit tests for formatter pass (`debug: false` no body, `debug: true` + correct body, byte-identical non-debug baseline, "Phase complete." guard). +- [ ] Unit tests for spawn args pass (flag present iff `debugMode: true`). +- [ ] Unit tests for `extractToolResult` pass (debugOutput population, + truncation at 4096, error guard, non-captured-tool guard). +- [ ] `tsc --noEmit` passes with no new errors. diff --git a/plans/2026-03-26-standalone-python-rewrite.md b/plans/2026-03-26-standalone-python-rewrite.md new file mode 100644 index 0000000..730926c --- /dev/null +++ b/plans/2026-03-26-standalone-python-rewrite.md @@ -0,0 +1,1258 @@ +# Standalone Python Rewrite + +**Status: Completed (2026-03-27)** + +The HTTP MCP architecture (driver-hosted single endpoint at +`/mcp?agent_id={id}`) was adopted as described in this plan, replacing the +original per-subagent stdio MCP server design that was the open question at +plan-writing time. `ipc.json` file-polling was fully eliminated in favor of +`asyncio.Future`-based blocking tool calls. The TypeScript codebase has been +deleted. + +--- + +Rewrite Koan as a standalone Python orchestrator. A single HTTP server hosts +both the web dashboard and MCP tool endpoints. Children connect to the +driver's MCP endpoint at `http://localhost:{port}/mcp?agent_id={id}` -- the +driver handles all tool calls in-process, no separate MCP server processes. +CLI agents (`claude`, `codex`, `gemini`) are interchangeable child runtimes +behind an abstract runner interface. + +This is a **big-bang rewrite** -- no backwards compatibility with the TypeScript +codebase. The TS code is frozen and deleted after Python reaches parity. + +--- + +## Architecture Overview + +``` +┌────────────────────────────────────────────────────────────────┐ +│ Python Orchestrator │ +│ (single process) │ +│ │ +│ ┌──────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ +│ │ Driver │ │ Starlette App │ │ Phase Definitions │ │ +│ │ (FSM) │ │ │ │ (step guidance, │ │ +│ │ │ │ /mcp?agent_id= │ │ system prompts) │ │ +│ │ │ │ /dashboard │ │ │ │ +│ │ │ │ /events (SSE) │ │ │ │ +│ └────┬─────┘ └────────┬─────────┘ └──────────┬───────────┘ │ +│ │ │ │ │ +│ ┌────┴─────────────────┴────────────────────────┴───────────┐ │ +│ │ Agent Registry │ │ +│ │ agent_id → { role, step_engine, permissions, event_log } │ │ +│ └──┬──────────────┬──────────────┬──────────────────────────┘ │ +│ │ │ │ │ +└─────┼──────────────┼──────────────┼──────────────────────────────┘ + │http │http │http + ┌───┴────┐ ┌─────┴─────┐ ┌────┴─────┐ + │claude │ │codex exec │ │gemini -p │ + │ -p │ │ │ │ │ + └────────┘ └───────────┘ └──────────┘ +``` + +**Single HTTP server, multiplexed by agent_id:** The driver runs one +Starlette app that serves both the web dashboard and MCP tool endpoints. Each +subagent connects to `http://localhost:{port}/mcp?agent_id={id}`. When a tool +call arrives, the server looks up the agent's state (role, step counter, +permissions) by `agent_id` in an in-process registry and handles the call +directly. No separate MCP server processes, no file-based IPC polling. + +**In-process tool handling:** Tool calls that previously required file-based +IPC (`koan_ask_question`, `koan_request_scouts`, `koan_review_artifact`) are +now handled in-process. The HTTP request blocks until the driver has a +response — for `koan_ask_question`, the driver routes to the web UI, awaits +user input, and returns the answer as the MCP tool response. For +`koan_request_scouts`, the driver spawns scouts directly, awaits them, and +returns findings. No `ipc.json` intermediary. + +**Agent-agnostic runner:** An abstract `Runner` interface handles child +process lifecycle. Three implementations from day one: `ClaudeRunner`, +`CodexRunner`, and `GeminiRunner`. Each knows how to inject per-process MCP +config pointing at the driver's HTTP endpoint, construct launch arguments, +and parse stdout for streaming events. + +--- + +## Decisions + +### Single HTTP server, not per-subagent MCP processes + +Previous iterations of this plan used per-subagent stdio MCP server processes. +This added N processes, required file-based IPC polling between the MCP +server and the parent, and forced each MCP server to independently manage +audit state. + +The HTTP approach collapses everything into one process: + +- The driver, web dashboard, and MCP endpoint share a single Starlette app +- Tool calls arrive as HTTP requests with `agent_id` in the URL +- The agent registry (an in-process dict) maps `agent_id` → step engine, + permissions, event log +- `koan_ask_question` routes directly to the web UI's pending-input mechanism + (no file polling) +- `koan_request_scouts` spawns scouts in-process and awaits completion + (no `ipc.json` intermediary) + +The `agent_id` is assigned by the driver when spawning a subagent and passed +to the child via the MCP config URL. The MCP protocol's HTTP transport +(Streamable HTTP) carries the `agent_id` as a query parameter — no +out-of-band identification needed. + +### Positive-only prompt guidance for permissions + +System prompts tell the LLM which tools to call (positive guidance). They do +**not** list tools to avoid — negative guidance is less effective. Hard +enforcement lives in the MCP endpoint: if the child calls a tool its role +doesn't have, the endpoint returns an error. This mirrors the current +`checkPermission()` pattern but moves it from the old TS extension hook to +the HTTP tool handler. + +### HTMX + server-rendered web UI + +The dashboard is part of the same Starlette app that serves MCP. HTMX for +reactivity, SSE for push updates. No JS build step, no node dependencies. +Server renders HTML fragments; HTMX swaps them on SSE events. Token streaming +uses SSE directly into an HTMX target. + +### File contracts simplified + +The directory-as-contract invariant is preserved but simplified: + +- `task.json` — driver writes before spawn, driver reads at agent registration +- `state.json` — driver writes (audit projection), available for debugging +- `events.jsonl` — driver appends audit events + +**Removed:** `ipc.json` is no longer needed. Tool calls that previously +required file-based IPC (`koan_ask_question`, `koan_request_scouts`, +`koan_review_artifact`) are now in-process HTTP request/response cycles. The +MCP tool handler blocks on the HTTP request until the driver has a response. + +### Step guidance lives in Python phase modules + +Each phase (intake, brief-writer, orchestrator, etc.) is a Python module that +defines step names, system prompts, and step guidance content. The MCP +endpoint calls `get_step_guidance(step)` when `koan_complete_step` is +invoked. This is equivalent to the current `BasePhase.getStepGuidance()` but +in Python. + +--- + +## Package Structure + +``` +koan/ +├── __init__.py +├── __main__.py # CLI entry point +├── driver.py # Deterministic pipeline FSM +├── subagent.py # Subagent manager (spawn child, register agent) +├── agents.py # Agent registry: agent_id → state (in-process dict) +├── step_engine.py # Step state machine (one instance per agent) +├── permissions.py # Role/step/path enforcement +├── tools/ +│ ├── __init__.py # Tool registration for MCP endpoint +│ ├── workflow.py # koan_complete_step +│ ├── ask.py # koan_ask_question (in-process → web UI) +│ ├── scouts.py # koan_request_scouts (in-process spawn) +│ ├── review.py # koan_review_artifact (in-process → web UI) +│ ├── orchestrator.py # koan_select_story, etc. +│ └── workflow_decision.py # koan_propose_workflow, koan_set_next_phase +├── phases/ +│ ├── __init__.py +│ ├── base.py # Step guidance interface +│ ├── intake.py # 5-step intake workflow +│ ├── brief_writer.py # 3-step brief workflow +│ ├── scout.py +│ ├── decomposer.py +│ ├── orchestrator.py +│ ├── planner.py +│ ├── executor.py +│ └── workflow_orchestrator.py +├── runners/ +│ ├── __init__.py +│ ├── base.py # Abstract Runner interface +│ ├── claude.py # ClaudeRunner +│ ├── codex.py # CodexRunner +│ └── gemini.py # GeminiRunner +├── epic/ +│ ├── __init__.py +│ ├── state.py # Epic/story state I/O (JSON) +│ ├── types.py # EpicPhase, StoryStatus, etc. +│ └── artifacts.py # Artifact listing/reading +├── audit/ +│ ├── __init__.py +│ ├── events.py # Event type definitions +│ ├── fold.py # Pure projection fold +│ ├── log.py # EventLog (append + state.json) +│ └── formatter.py # LogLine formatters for web UI +├── web/ +│ ├── __init__.py +│ ├── app.py # Starlette app (dashboard + MCP endpoint) +│ ├── mcp.py # /mcp?agent_id= endpoint (Streamable HTTP) +│ ├── sse.py # /events SSE endpoint +│ ├── routes/ # Dashboard HTTP route handlers +│ ├── templates/ # Jinja2 + HTMX templates +│ └── static/ # CSS +├── config.py # Model tiers, scout concurrency +├── lib/ +│ ├── __init__.py +│ ├── phase_dag.py # Phase transition DAG +│ └── time.py +└── types.py # Shared types +``` + +--- + +## Subagent Lifecycle + +No separate MCP server processes. The driver's HTTP server handles everything. + +``` +Driver (Starlette app on :port) Child Agent (claude/codex/gemini) + │ │ + ├─ mkdir subagentDir │ + ├─ write task.json │ + ├─ assign agent_id │ + ├─ register agent in registry │ + │ (read task.json → init step engine, │ + │ permissions, event log) │ + ├─ write MCP config → http://localhost:{port}/ │ + │ mcp?agent_id={agent_id} │ + ├─ spawn child ──────────────────────────────────►│ + │ ├─ connect to MCP endpoint + │ │ + │◄────── POST /mcp koan_complete_step ───────────┤ + ├─ look up agent_id in registry │ + ├─ check permissions │ + ├─ advance step 0→1 │ + ├─ return step 1 guidance ───────────────────────►│ + │ ├─ do work + │◄────── POST /mcp koan_ask_question ────────────┤ + ├─ route to web UI (in-process) │ + ├─ await user input (SSE + POST /api/answer) │ + ├─ return answer ────────────────────────────────►│ + │ ├─ continue work + │◄────── POST /mcp koan_request_scouts ──────────┤ + ├─ spawn scout children directly │ + ├─ await all scouts (each is its own agent_id) │ + ├─ return findings ──────────────────────────────►│ + │ ├─ continue work + │◄────── POST /mcp koan_complete_step ───────────┤ + ├─ advance step 1→2 (or "Phase complete.") │ + ├─ return guidance ──────────────────────────────►│ + │ │ + │ child exits ◄─────┤ + ├─ deregister agent_id │ + ├─ route to next phase │ +``` + +--- + +## MCP Tool Surface + +Tools exposed at the `/mcp?agent_id={id}` endpoint. The driver looks up the +agent's state from the in-process registry on every call. + +| Tool | Schema | Driver behavior | +| ----------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------- | +| `koan_complete_step` | `{ thoughts?: string }` | Check permissions → advance step engine → return guidance or "Phase complete." | +| `koan_ask_question` | `{ questions: [...] }` | Check permissions → push to web UI → await user response → return answer | +| `koan_request_scouts` | `{ scouts: [...] }` | Check permissions → spawn scout children (each gets own agent_id) → await all → return findings | +| `koan_review_artifact` | `{ path, description? }` | Check permissions → read artifact → push to web UI → await feedback → return | +| `koan_select_story` | `{ story_id }` | Validate status → write story state + status.md | +| `koan_complete_story` | `{ story_id, summary? }` | Validate status → write story state + status.md | +| `koan_retry_story` | `{ story_id, failure_summary }` | Validate status → write story state + status.md | +| `koan_skip_story` | `{ story_id, reason }` | Validate status → write story state + status.md | +| `koan_propose_workflow` | `{ status_report, recommended_phases }` | Push to web UI → await user direction → return feedback | +| `koan_set_next_phase` | `{ phase, instructions? }` | Validate against DAG → write `workflow-decision.json` | + +All tools pass through the permission fence before execution. The fence reads +role and current step from the agent's entry in the registry. + +--- + +## Runner Interface + +```python +class Runner(Protocol): + """Abstract interface for spawning a child agent process.""" + + def build_command( + self, + boot_prompt: str, + mcp_url: str, # e.g. "http://localhost:8420/mcp?agent_id=intake-abc123" + model: str | None, + cwd: str, + ) -> list[str]: + """Return the full command-line to spawn the child.""" + ... + + def write_mcp_config(self, mcp_url: str, config_dir: str) -> None: + """Write agent-specific MCP config file pointing at the HTTP URL.""" + ... + + def parse_stream_event(self, line: str) -> StreamEvent | None: + """Parse one stdout line into a normalized event, or None to skip.""" + ... + + @property + def name(self) -> str: ... +``` + +All runners point the child at the same HTTP endpoint — only the config +injection mechanism differs per CLI. + +**`ClaudeRunner`:** Writes JSON config to `{config_dir}/mcp-config.json`: +`{"koan":{"type":"http","url":"http://localhost:{port}/mcp?agent_id={id}"}}` +Spawns: `claude -p --output-format stream-json --verbose --include-partial-messages --mcp-config {path} --strict-mcp-config --dangerously-skip-permissions "{boot_prompt}"` + +**`CodexRunner`:** Injects via `-c` runtime overrides (per-process, not persisted): +`codex exec --json --dangerously-bypass-approvals-and-sandbox -c 'mcp_servers.koan.url="http://localhost:{port}/mcp?agent_id={id}"' "{boot_prompt}"` + +**`GeminiRunner`:** Writes `.gemini/settings.json` into `cwd`: +`{"mcpServers":{"koan":{"type":"http","url":"http://localhost:{port}/mcp?agent_id={id}"}}}` +Spawns: `gemini -p --yolo --allowed-mcp-server-names koan -o stream-json "{boot_prompt}"` with `cwd=subagentDir`. + +The runner does not handle tools, permissions, or state. It only handles +process lifecycle and stream parsing. + +--- + +## Phase Modules + +Each phase module exports: + +```python +ROLE: str # e.g. "intake" +TOTAL_STEPS: int # e.g. 5 +REVIEW_GATED_STEP: int | None # step requiring artifact review acceptance + +def system_prompt() -> str: + """Role identity and rules. No task details.""" + +def step_name(step: int) -> str: + """Human-readable step name.""" + +def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: + """Step instructions. Task details delivered here, not in boot prompt.""" + +def get_next_step(step: int, ctx: PhaseContext) -> int | None: + """Next step number, or None for phase complete. Pure function.""" + +def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: + """Pre-condition check. Returns error string or None to allow.""" +``` + +The driver's step engine (looked up by `agent_id`) calls these functions. +`PhaseContext` carries `epic_dir`, `subagent_dir`, `phase_instructions`, and +any phase-specific state (e.g., intake confidence level). + +--- + +## Phases + +### Phase 0 — HTTP MCP Endpoint + Step Engine + +Build the Starlette app with the MCP endpoint and `koan_complete_step`. + +**Deliverables:** + +- `koan/web/app.py` — Starlette app with `/mcp?agent_id=` endpoint +- `koan/web/mcp.py` — MCP Streamable HTTP handler +- `koan/agents.py` — agent registry (in-process dict) +- `koan/step_engine.py` — step state machine +- `koan/permissions.py` — permission fence +- `koan/tools/workflow.py` — `koan_complete_step` handler +- `koan/phases/base.py` — phase interface +- `koan/phases/intake.py` — intake phase (port from TS) +- `koan/audit/` — event log, fold, projection + +**Validation:** Start the Starlette app, register a test agent manually, +connect a `claude` session with MCP config pointing at the HTTP endpoint. +Verify the LLM calls `koan_complete_step`, receives step 1 guidance, does +work, calls again, and completes the phase. + +### Phase 1 — In-Process Tools + Single-Phase Driver + +Add remaining MCP tools (handled in-process) and the driver for intake. + +**Deliverables:** + +- `koan/tools/ask.py` — `koan_ask_question` (routes to web UI, awaits response) +- `koan/tools/scouts.py` — `koan_request_scouts` (spawns scouts directly) +- `koan/tools/review.py` — `koan_review_artifact` (routes to web UI) +- `koan/subagent.py` — spawn child, register agent, parse stdout +- `koan/runners/base.py` + `koan/runners/claude.py` — first runner +- `koan/driver.py` — minimal driver: run intake phase only +- Minimal web UI: question form + artifact review (HTMX) + +**Validation:** Run `koan plan` from CLI. Intake phase completes: scouts +dispatch, questions asked via web UI, `landscape.md` produced. + +### Phase 2 — Full Pipeline + Multi-Agent + +Extend driver to all phases. Add Codex and Gemini runners. + +**Deliverables:** + +- All remaining phase modules (brief-writer through workflow-orchestrator) +- `koan/runners/codex.py` — Codex runner +- `koan/runners/gemini.py` — Gemini runner +- Full driver loop with story execution, retry, skip +- `koan/epic/state.py` — epic/story state I/O +- `koan/lib/phase_dag.py` — phase transition DAG +- Orchestrator tools (`koan_select_story`, etc.) +- Workflow decision tools (`koan_propose_workflow`, `koan_set_next_phase`) + +**Validation:** Run full pipeline intake → brief → execution with +`claude`, `codex`, and `gemini` as child agents. Story loop completes +with retry/skip. + +### Phase 3 — Web Dashboard + +Rewrite the web UI in Python + HTMX. + +**Deliverables:** + +- `koan/web/app.py` — Starlette app +- `koan/web/sse.py` — SSE push endpoint +- HTMX templates for: activity feed, agent panels, question forms, + artifact review, workflow decisions, model config, token streaming +- Port CSS from current UI + +**Validation:** Dashboard displays real-time activity, handles all +interaction types, survives reconnects. + +### Phase 4 — Polish + Delete TS + +Harden, test, document. Delete the TypeScript codebase. + +**Deliverables:** + +- Test suite (unit + integration) +- CLI polish (`koan plan`, `koan config`) +- Documentation +- Delete `extensions/`, `src/`, `package.json`, TS config + +--- + +## Invisible Knowledge + +### Why a single HTTP MCP server, not per-subagent processes + +Earlier iterations of this plan used per-subagent stdio MCP server processes. +This was architecturally clean (one process = one state machine) but introduced +unnecessary complexity: + +- N extra processes for N subagents (lightweight, but still process management) +- File-based IPC polling between the MCP server and the driver for questions, + scouts, and artifact review (`ipc.json` write → 300ms poll → response write) +- Each MCP server independently managed audit state, duplicating projection logic + +The HTTP approach eliminates all of this. The driver's Starlette app serves +MCP at `/mcp?agent_id={id}`. The `agent_id` parameter in the URL solves the +routing problem: when `koan_complete_step` arrives, the driver looks up the +agent's state by ID in an in-process dict. No out-of-band identification, no +process coordination, no file polling. + +Tools that need human interaction (`koan_ask_question`, `koan_review_artifact`) +route directly to the web UI's pending-input mechanism — the HTTP request blocks +until the user responds. Tools that spawn children (`koan_request_scouts`) do so +in-process. The entire tool lifecycle is a single HTTP request/response cycle. + +### Why HTTP transport, not stdio + +MCP supports both stdio (parent spawns server as subprocess) and HTTP +(Streamable HTTP, server listens on a port). We use HTTP because: + +1. **Single server for all subagents.** With stdio, each subagent needs its + own MCP server process. With HTTP, one server handles all agents via + `agent_id` in the URL. Fewer processes, no per-subagent lifecycle. + +2. **In-process tool handling.** The driver can handle `koan_ask_question` + by routing directly to the web UI's pending-input mechanism. No file-based + IPC polling. The HTTP request blocks until the user responds. + +3. **The server is already running.** The web dashboard needs an HTTP server + anyway. Adding `/mcp` to the same Starlette app is zero marginal cost. + +4. **No server-ready timing.** The HTTP server starts before any subagent + is spawned. Children connect to a server that's already listening. + +All three CLIs support HTTP MCP servers: + +- **Claude**: `--mcp-config` with `{"type":"http","url":"..."}` +- **Codex**: `-c 'mcp_servers.koan.url="..."'` runtime override +- **Gemini**: `.gemini/settings.json` with `{"type":"http","url":"..."}` + +The runner's only job is writing the correct MCP config format for its CLI. + +### Why positive-only prompt guidance for permissions + +System prompts listing forbidden tools create a specific failure mode: the LLM reads +"do not call `koan_ask_question` during step 1" and the prohibition itself activates +the concept, making the mistake slightly more likely (the "don't think of an elephant" +problem). More practically, negative constraint lists grow stale as the permission +model evolves and are never comprehensive. + +Positive guidance — "your tools for this step are X, Y, Z" — is a complete +specification. Combined with the MCP server's hard enforcement (unknown tool calls +return an error the LLM must handle), the prompt guides the LLM toward correct tool +selection while the server prevents incorrect tool execution regardless of what the +prompt says. + +The architecture thus has two independent correctness layers: the prompt makes the +right behavior obvious, the server makes the wrong behavior impossible. Each layer +can tolerate the other's occasional failure. + +### Why the step-first workflow pattern is load-bearing and must survive + +The step-first pattern — boot prompt contains only "call `koan_complete_step`", step +guidance delivered as the tool's return value — was discovered empirically when Koan +was built on the original TS codebase. Weaker models (haiku-class) would receive a rich boot prompt and +produce a text response without calling any tool, causing the `-p` process to exit +immediately with no work done. + +The solution has three reinforcement mechanisms that work together: + +1. **Primacy**: the first thing the LLM reads is "call `koan_complete_step`". First + instructions anchor the model's initial action. +2. **Recency**: `format_step()` always ends with "WHEN DONE: Call `koan_complete_step`". + End-of-context instructions have disproportionate weight. +3. **Muscle memory**: by step 2, the model has already called the tool once and + received a useful response. The pattern is established. + +This same mechanism is observed in the `claude-config` skills framework +(`~/git/claude-config/skills/`), where `format_step()` ends with a `NEXT STEP: ...` +invoke block that the LLM must execute. The `MANDATORY INVOKE BLOCK` in +`roster_dispatch()` and `template_dispatch()` is the same pattern applied to +subagent launches. The skills framework independently validates that CLI-script-driven +step progression works across model capability levels. + +In the Python rewrite, the MCP server returns the same formatted guidance as the +current `BasePhase`. The boot prompt ("You are a koan {role} agent. Call +`koan_complete_step` to receive your instructions.") is unchanged. Do not put task +content in the boot prompt — it breaks the pattern. + +### Why file contracts are preserved (simplified) + +`task.json`, `state.json`, and `events.jsonl` are already protocol-level +artifacts with runtime-agnostic JSON schemas and atomic rename semantics. + +The schemas are preserved. What changed: `ipc.json` is eliminated entirely. +Tool calls that previously required file-based IPC are now in-process HTTP +request/response cycles within the driver. The driver writes `task.json` +before spawn, reads it at agent registration, and writes `state.json` + +`events.jsonl` as the audit trail — same data, fewer files, no polling. + +### Why HTMX over React/Preact for the web rewrite + +The current Preact + Zustand frontend has ~3000 lines of JSX, a bundling step +(`esbuild`), and a `node_modules` dependency. Every change to the dashboard requires +understanding the client-side state model (Zustand slices), the SSE dispatch layer +(`sse.js`), and the component tree. The two-process build (Python server + JS bundle) +adds friction. + +HTMX inverts this: the server renders HTML fragments; the browser swaps them using +`hx-swap` on SSE events. The client has no state model — the server is the single +source of truth. For a dashboard that is fundamentally a view of server-side state +(pipeline phase, agent status, audit logs), this is the correct architecture. + +Specific fit for Koan's patterns: + +- SSE events already carry full state snapshots (phase, stories, agents, logs). + HTMX's `hx-swap-oob` can handle out-of-band updates directly from SSE events. +- Token streaming maps to HTMX's SSE extension with `hx-target` pointing at the + streaming text container. +- Question forms, artifact review, and workflow decision modals are server-rendered + HTML; no client-side form state needed. +- Python backend (Starlette + Jinja2) means one language, one dependency manager, + no build pipeline. + +### The skills framework as proof of concept + +Before this plan was written, the `~/git/claude-config/skills/` framework was studied +in detail. It demonstrates every core Koan mechanism without an extension runtime: + +| Koan mechanism | Skills framework analog | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `koan_complete_step` return value delivers guidance | `format_step(body, next_cmd)` output — the LLM reads the body and executes `next_cmd` | +| Boot prompt → first tool call → step 1 guidance | `MANDATORY INVOKE BLOCK` in `roster_dispatch` — subagent must run the Python script before anything else | +| `koan_ask_question` IPC flow | `<needs_user_input>` XML → orchestrator calls `AskUserQuestion` → reinvokes subagent with `--user-answer-id` | +| `koan_request_scouts` parallel dispatch | `roster_dispatch()` — parallel subagent launches with shared context + unique tasks | +| Step state carried between calls | `--state-dir` flag + `plan.json` — state persists across reinvocations | + +The key difference: skills use **CLI reinvocation** (each step is a fresh process +invocation) while Koan uses **MCP persistence** (the MCP server holds state across +the child's lifetime). The MCP approach is richer because the child stays alive and +can do multi-step work within a single step, but the CLI pattern proves the +underlying step-guidance mechanism is agent-runtime-agnostic. + +### Accepted losses from the TS codebase + +These capabilities exist in the TypeScript codebase and are **not** replicated in the +Python rewrite. They are accepted losses, not gaps to fill: + +- **Model registry / auth integration**: The TS dashboard discovers available + models via the TS codebase's `ModelRegistry(AuthStorage)`. The Python rewrite uses a static + config file (`~/.koan/config.json`) with explicit model IDs per runner. Users + configure models manually. This is simpler and provider-agnostic. + +- **TUI config commands**: The TS extension registers a `/koan config` + interactive terminal command. The Python rewrite has no equivalent terminal UI. + Model config is done via the web dashboard or CLI flags. + +- **Bash truncation override**: The TS extension intercepts `tool_result` events for + bash tools and raises the truncation limit from 50KB to 200KB. The Python rewrite + does not replicate this. Each child CLI manages its own output limits. + +- **Parent session conversation capture**: The TS `koan_plan` tool exports the + parent conversation. Removed entirely — koan flows start fresh (see decision + in "Resolved: CLI Protocol Research"). + +### The "one agent_id = one step state machine" invariant + +This is the central constraint of the architecture. Each entry in the agent +registry owns: + +- One role (e.g., `"intake"`) +- One step counter (starts at 0, advances on each `koan_complete_step` call) +- One permission set (derived from the role) +- One subagent directory (source of `task.json`, destination of `state.json`) +- One `EventLog` (append-only `events.jsonl` + `state.json`) + +Violating this — by reusing an `agent_id` across phases, or sharing state +between registry entries — produces: + +- **Permission state confusion**: role A's allowed tools bleed into role B's session +- **Step counter races**: two concurrent calls to `koan_complete_step` advance the + same counter from different contexts +- **Audit attribution errors**: events logged with wrong role or wrong subagent ID + +The invariant is enforced by lifecycle: the driver assigns a fresh `agent_id` +for every subagent spawn and registers a new entry in the dict. When the child +exits, the entry is deregistered. There is no pooling, no reuse, no sharing. + +With HTTP transport, the server is shared but the state is not — `agent_id` +in the URL is the isolation boundary. The dict lookup is the first thing the +MCP endpoint does; an unknown `agent_id` returns an error immediately. + +--- + +## Code Samples + +### Agent registry + MCP endpoint (`koan/agents.py` + `koan/web/mcp.py`) + +```python +# koan/agents.py +"""In-process agent registry. Maps agent_id → state for MCP tool dispatch.""" +from dataclasses import dataclass, field +from koan.step_engine import StepEngine +from koan.permissions import PermissionFence +from koan.audit.log import EventLog + + +@dataclass +class AgentState: + agent_id: str + role: str + subagent_dir: str + epic_dir: str + engine: StepEngine + fence: PermissionFence + event_log: EventLog + + +class AgentRegistry: + """Thread-safe agent lookup. One entry per live subagent.""" + + def __init__(self) -> None: + self._agents: dict[str, AgentState] = {} + + async def register(self, agent_id: str, subagent_dir: str) -> AgentState: + """Read task.json, init step engine + permissions + audit, store.""" + from koan.epic.state import read_task_file + task = read_task_file(subagent_dir) + engine = StepEngine(task, subagent_dir) + fence = PermissionFence(task.role) + event_log = EventLog(subagent_dir, task.role) + await event_log.open() + state = AgentState(agent_id, task.role, subagent_dir, task.epic_dir, + engine, fence, event_log) + self._agents[agent_id] = state + return state + + def get(self, agent_id: str) -> AgentState | None: + return self._agents.get(agent_id) + + async def deregister(self, agent_id: str) -> None: + state = self._agents.pop(agent_id, None) + if state: + await state.event_log.close() + + +# koan/web/mcp.py +"""MCP Streamable HTTP endpoint. All koan tools handled in-process.""" +from starlette.requests import Request +from starlette.responses import JSONResponse +from koan.agents import AgentRegistry +from koan.tools import dispatch_tool + + +async def mcp_endpoint(request: Request) -> JSONResponse: + """POST /mcp?agent_id={id} — MCP Streamable HTTP handler.""" + agent_id = request.query_params.get("agent_id") + if not agent_id: + return JSONResponse({"error": "missing agent_id"}, status_code=400) + + registry: AgentRegistry = request.app.state.registry + agent = registry.get(agent_id) + if not agent: + return JSONResponse({"error": f"unknown agent: {agent_id}"}, status_code=404) + + body = await request.json() + # MCP protocol: body contains method + params (tool name, arguments) + tool_name = body.get("params", {}).get("name") + tool_args = body.get("params", {}).get("arguments", {}) + + # Permission check before dispatch + perm = agent.fence.check(tool_name, agent.engine.current_step, + agent.epic_dir, tool_args) + if not perm.allowed: + return _mcp_error(perm.reason) + + # Dispatch to tool handler — blocks until complete (may await user input) + result = await dispatch_tool(tool_name, tool_args, agent, request.app) + return _mcp_result(result) +``` + +### Step engine (`koan/step_engine.py`) + +```python +"""Step state machine — one instance per MCP server (one per subagent).""" +from dataclasses import dataclass, field +from typing import Callable, Awaitable +import koan.phases as phases_registry +from koan.phases.base import PhaseContext, StepGuidance + + +@dataclass +class StepEngine: + task: object # SubagentTask (role, epic_dir, etc.) + subagent_dir: str + _step: int = field(default=0, init=False) + _phase_ctx: PhaseContext = field(init=False) + + # Callback set by review-gated phases; blocks koan_complete_step until called. + on_complete_step: Callable[[str], Awaitable[str | None]] | None = field( + default=None, init=False + ) + + def __post_init__(self) -> None: + self._phase_ctx = PhaseContext( + epic_dir=self.task.epic_dir, + subagent_dir=self.subagent_dir, + phase_instructions=getattr(self.task, "phase_instructions", None), + ) + phase_mod = phases_registry.get(self.task.role) + self._phase = phase_mod # module with system_prompt(), step_guidance(), etc. + + @property + def current_step(self) -> int: + return self._step + + @property + def role(self) -> str: + return self.task.role + + async def advance(self, thoughts: str) -> str: + """Advance step; return next guidance or 'Phase complete.'""" + if self._step == 0: + # Boot transition: establish the call→receive→work→call pattern. + self._step = 1 + guidance = self._phase.step_guidance(1, self._phase_ctx) + return _format_step(guidance) + + # Pre-condition check before advancing (e.g., review acceptance gate). + error = await self._phase.validate_step_completion(self._step, self._phase_ctx) + if error: + return error # LLM sees error and must fix the pre-condition + + next_step = self._phase.get_next_step(self._step, self._phase_ctx) + if next_step is None: + return "Phase complete." + + prev = self._step + self._step = next_step + if next_step < prev: # loop-back (e.g., intake confidence loop) + await self._phase.on_loop_back(prev, next_step, self._phase_ctx) + + guidance = self._phase.step_guidance(next_step, self._phase_ctx) + return _format_step(guidance) +``` + +### Permission fence (`koan/permissions.py`) + +```python +"""Default-deny role-based permission enforcement. Called on every tool invocation.""" +import os +from dataclasses import dataclass + +# Always allowed — distinguishing 'read bash' from 'write bash' is intractable. +READ_TOOLS = frozenset({"read", "bash", "grep", "glob", "find", "ls"}) +WRITE_TOOLS = frozenset({"edit", "write"}) + +# Planning roles: write access path-scoped to epic_dir only. +PLANNING_ROLES = frozenset({ + "intake", "scout", "decomposer", "brief-writer", + "orchestrator", "planner", "workflow-orchestrator", +}) + +ROLE_PERMISSIONS: dict[str, frozenset[str]] = { + "intake": frozenset({"koan_complete_step", "koan_ask_question", + "koan_request_scouts", "koan_review_artifact", + "edit", "write"}), + "executor": frozenset({"koan_complete_step", "koan_ask_question", + "edit", "write", "bash"}), + # ... other roles +} + +# Step 1 of intake/brief-writer is read-only comprehension. +STEP_1_BLOCKED = frozenset({"koan_request_scouts", "koan_ask_question", "write", "edit"}) + + +@dataclass +class PermissionResult: + allowed: bool + reason: str = "" + + +def check_permission( + role: str, + tool_name: str, + current_step: int, + epic_dir: str | None = None, + tool_args: dict | None = None, +) -> PermissionResult: + if tool_name in READ_TOOLS: + return PermissionResult(allowed=True) + + # Step-level read-only gates. + if role in ("intake", "brief-writer") and current_step == 1: + if tool_name in STEP_1_BLOCKED: + return PermissionResult( + allowed=False, + reason=f"{tool_name} not available during step 1 (read-only).", + ) + + if role not in ROLE_PERMISSIONS: + return PermissionResult(allowed=False, reason=f"Unknown role: {role}") + + if tool_name not in ROLE_PERMISSIONS[role]: + return PermissionResult(allowed=False, + reason=f"{tool_name} not available for role {role}") + + # Path-scope enforcement for planning roles. + if tool_name in WRITE_TOOLS and role in PLANNING_ROLES and epic_dir and tool_args: + raw_path = tool_args.get("path", "") + if raw_path and not os.path.realpath(raw_path).startswith( + os.path.realpath(epic_dir) + os.sep + ): + return PermissionResult( + allowed=False, + reason=f"{tool_name} path outside epic directory.", + ) + + return PermissionResult(allowed=True) +``` + +### Runner protocol (`koan/runners/base.py` + implementations) + +```python +# koan/runners/base.py +"""Abstract runner interface. All runners point children at the driver's HTTP MCP endpoint.""" +from dataclasses import dataclass +from typing import Protocol + + +@dataclass +class StreamEvent: + """Normalized output from any child agent's stdout stream.""" + kind: str # "text_delta" | "thinking_delta" | "turn_end" + delta: str = "" + + +class Runner(Protocol): + name: str + + def build_command( + self, boot_prompt: str, mcp_url: str, model: str | None, cwd: str + ) -> list[str]: ... + + def write_mcp_config(self, mcp_url: str, config_dir: str) -> str: + """Write MCP config for this CLI. Returns path to config file.""" + ... + + def parse_stream_event(self, line: str) -> StreamEvent | None: ... + + +# koan/runners/claude.py +import json, os +from koan.runners.base import Runner, StreamEvent + + +class ClaudeRunner: + name = "claude" + + def build_command(self, boot_prompt, mcp_url, model, cwd): + config_path = self.write_mcp_config(mcp_url, cwd) + args = [ + "claude", "-p", + "--output-format", "stream-json", + "--verbose", "--include-partial-messages", + "--mcp-config", config_path, + "--strict-mcp-config", + "--dangerously-skip-permissions", + ] + if model: + args += ["--model", model] + args.append(boot_prompt) + return args + + def write_mcp_config(self, mcp_url, config_dir): + path = os.path.join(config_dir, ".koan-mcp.json") + with open(path, "w") as f: + json.dump({"koan": {"type": "http", "url": mcp_url}}, f) + return path + + def parse_stream_event(self, line): + try: + ev = json.loads(line) + except json.JSONDecodeError: + return None + if ev.get("type") == "stream_event": + inner = ev.get("event", {}) + if inner.get("type") == "content_block_delta": + delta = inner.get("delta", {}) + if delta.get("type") == "text_delta": + return StreamEvent(kind="text_delta", delta=delta.get("text", "")) + if ev.get("type") == "result": + return StreamEvent(kind="turn_end") + return None + + +# koan/runners/codex.py +class CodexRunner: + """Codex: -c runtime overrides for HTTP MCP. Per-process, not persisted.""" + name = "codex" + + def build_command(self, boot_prompt, mcp_url, model, cwd): + args = [ + "codex", "exec", "--json", + "--dangerously-bypass-approvals-and-sandbox", + "-c", f'mcp_servers.koan.url="{mcp_url}"', + ] + if model: + args += ["-m", model] + args.append(boot_prompt) + return args + + def write_mcp_config(self, mcp_url, config_dir): + return "" # codex uses -c flags, no config file needed + + def parse_stream_event(self, line): + try: + ev = json.loads(line) + except json.JSONDecodeError: + return None + if ev.get("type") == "item.completed": + item = ev.get("item", {}) + if item.get("type") == "agent_message": + return StreamEvent(kind="text_delta", delta=item.get("text", "")) + if ev.get("type") == "turn.completed": + return StreamEvent(kind="turn_end") + return None + + +# koan/runners/gemini.py +class GeminiRunner: + """Gemini: .gemini/settings.json in cwd for HTTP MCP config.""" + name = "gemini" + + def build_command(self, boot_prompt, mcp_url, model, cwd): + self.write_mcp_config(mcp_url, cwd) + args = ["gemini", "-p", boot_prompt, "-o", "stream-json", + "--yolo", "--allowed-mcp-server-names", "koan"] + if model: + args += ["-m", model] + return args + + def write_mcp_config(self, mcp_url, config_dir): + import os + gemini_dir = os.path.join(config_dir, ".gemini") + os.makedirs(gemini_dir, exist_ok=True) + path = os.path.join(gemini_dir, "settings.json") + with open(path, "w") as f: + json.dump({"mcpServers": {"koan": {"type": "http", "url": mcp_url}}}, f) + return path + + def parse_stream_event(self, line): + try: + ev = json.loads(line) + except json.JSONDecodeError: + return None + if ev.get("type") == "message" and ev.get("role") == "assistant" and ev.get("delta"): + return StreamEvent(kind="text_delta", delta=ev.get("content", "")) + if ev.get("type") == "result": + return StreamEvent(kind="turn_end") + return None +``` + +### Phase module interface (`koan/phases/intake.py`) + +```python +"""Intake phase: 5-step linear workflow producing landscape.md.""" +from koan.phases.base import PhaseContext, StepGuidance + +ROLE = "intake" +TOTAL_STEPS = 5 +REVIEW_GATED_STEP = 5 # Step 5 (Synthesize) requires koan_review_artifact acceptance. + +STEP_NAMES = {1: "Extract", 2: "Scout", 3: "Ask", 4: "Reflect", 5: "Write"} + + +def system_prompt() -> str: + return ( + "You are an intake analyst for a coding task planner. You read a conversation " + "history, explore the codebase, and ask the user targeted questions until you " + "have complete context for planning.\n\n" + "Your output — landscape.md — is the sole foundation for all downstream work.\n\n" + "## Tools\n" + "- Read tools (read, bash, grep, glob, find, ls)\n" + "- `koan_request_scouts` — parallel codebase exploration\n" + "- `koan_ask_question` — structured user questions\n" + "- `koan_review_artifact` — present landscape.md for review (step 5 only)\n" + "- `koan_complete_step` — signal step completion" + ) + # Note: no forbidden tool list. Positive guidance only. + # The MCP server enforces the fence; the prompt guides toward correct usage. + + +def step_name(step: int) -> str: + return STEP_NAMES.get(step, f"Step {step}") + + +def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: + """Return step instructions. Called by StepEngine.advance() after boot transition.""" + if step == 1: + return StepGuidance( + title="Extract", + instructions=[ + f"Read {ctx.epic_dir}/conversation.jsonl.", + "Build a mental model of the task. Do NOT call scouts or ask questions yet.", + "WHEN DONE: Call koan_complete_step.", + ], + ) + # ... steps 2–5 + raise ValueError(f"Invalid step {step} for intake phase") + + +def get_next_step(step: int, ctx: PhaseContext) -> int | None: + """Pure function. For intake, steps progress linearly 1→5, then done.""" + if step >= TOTAL_STEPS: + return None + return step + 1 + + +async def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: + """Block koan_complete_step on step 5 until review is accepted.""" + if step == REVIEW_GATED_STEP: + if not ctx.last_review_accepted: + return ( + "You must call koan_review_artifact on landscape.md before completing " + "this step. Write landscape.md, then invoke koan_review_artifact." + ) + return None + + +async def on_loop_back(from_step: int, to_step: int, ctx: PhaseContext) -> None: + """No-op for linear intake. Confidence-gated loop variant would reset state here.""" + pass +``` + +## Resolved: CLI Protocol Research + +### MCP config injection — HTTP transport (verified 2026-03-26) + +All three CLIs support HTTP MCP servers. Each runner writes a config pointing +at `http://localhost:{port}/mcp?agent_id={id}`: + +**Claude Code:** `--mcp-config <file>` with `--strict-mcp-config` for isolation: + +```json +{ + "koan": { + "type": "http", + "url": "http://localhost:8420/mcp?agent_id=intake-abc123" + } +} +``` + +**Codex:** `-c` runtime config override (per-process, not persisted): + +```bash +codex exec -c 'mcp_servers.koan.url="http://localhost:8420/mcp?agent_id=intake-abc123"' ... +``` + +**Gemini:** `.gemini/settings.json` in cwd + `--allowed-mcp-server-names koan`: + +```json +{ + "mcpServers": { + "koan": { + "type": "http", + "url": "http://localhost:8420/mcp?agent_id=intake-abc123" + } + } +} +``` + +### MCP server lifecycle (decided 2026-03-26) + +The driver starts one HTTP server **before** any subagents. Children connect +to it — no per-subagent server processes. The flow: + +1. Driver starts Starlette app on `localhost:{port}` +2. For each subagent: assign `agent_id`, write `task.json`, register agent + in registry (reads `task.json`, inits step engine + permissions) +3. Write MCP config pointing at `http://localhost:{port}/mcp?agent_id={id}` +4. Spawn child agent with that config +5. Child connects to the driver's MCP endpoint via HTTP +6. Tool calls arrive as HTTP requests, dispatched by `agent_id` +7. Child exits → driver deregisters `agent_id` + +### Boot prompt delivery (verified 2026-03-26) + +Both CLIs accept a boot prompt as a positional argument in print mode: + +- **claude:** `claude -p "prompt"` — positional arg. Also `--system-prompt`. +- **codex:** `codex exec "prompt"` — positional arg. Also stdin via `-`. +- **gemini:** `gemini -p "prompt"` — via `-p` flag (not positional). + +All support non-interactive print mode. The runner abstraction handles the +minor flag differences (`-p` vs `exec` vs `-p "prompt"`). + +### Conversation capture (decided 2026-03-26) + +**Removed entirely.** Koan flows start fresh — there is no parent conversation +to capture. The previous behavior (exporting `sessionManager` content to +`conversation.jsonl`) assumed Koan was triggered from within an agent session. + +In standalone mode, Koan is invoked directly from the CLI. Context comes from: + +- The user's initial prompt (passed as CLI argument or via the web UI) +- Codebase exploration during the intake phase +- User Q&A during intake + +Future work may add "forking" from an existing coding agent conversation, but +this is explicitly out of scope for the rewrite. + +### Token streaming formats (verified 2026-03-26) + +**Claude Code** (`-p --output-format stream-json --verbose --include-partial-messages`): + +JSONL with `"type"` field. True incremental token deltas: + +```json +{ + "type": "stream_event", + "event": { + "type": "content_block_delta", + "index": 0, + "delta": { "type": "text_delta", "text": "Hello" } + } +} +``` + +Also emits `message_start`, `content_block_start/stop`, `message_delta` +(with `stop_reason`), `message_stop`, and final `result` with usage/cost. +Tool calls appear as `content_block_start` with `type: "tool_use"`. + +**Codex** (`exec --json`): + +JSONL, but **no incremental token streaming** — only turn-level events: + +```json +{"type":"thread.started","thread_id":"..."} +{"type":"turn.started"} +{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"Hello from Codex"}} +{"type":"turn.completed","usage":{"input_tokens":11388,"cached_input_tokens":9344,"output_tokens":24}} +``` + +The complete message text arrives in one `item.completed` event. There are no +incremental `text_delta` events. Token streaming display will show nothing +until the turn completes, then show the full text. This is a known limitation +of the Codex runner. + +**Gemini** (`-p -o stream-json`): + +JSONL with incremental streaming via `delta:true`: + +```json +{"type":"init","timestamp":"...","session_id":"...","model":"auto-gemini-3"} +{"type":"message","timestamp":"...","role":"user","content":"say hello"} +{"type":"message","timestamp":"...","role":"assistant","content":"Hello there, friend.","delta":true} +{"type":"result","timestamp":"...","status":"success","stats":{"total_tokens":13637,...}} +``` + +Messages with `"delta":true` are incremental assistant output. The `result` +event carries usage statistics including per-model breakdowns (gemini uses +multi-model routing internally). + +**Normalized StreamEvent mapping:** + +| Normalized kind | Claude source | Codex source | Gemini source | +| ---------------- | ----------------------------------------------- | --------------------------------------------- | --------------------------------------------- | +| `text_delta` | `stream_event.event.delta.type == "text_delta"` | `item.completed` (full text, not incremental) | `message` with `role=assistant, delta=true` | +| `thinking_delta` | `stream_event.event.delta.type == "thinking"` | N/A | N/A (thinking tokens counted but not exposed) | +| `tool_use_start` | `content_block_start.type == "tool_use"` | N/A | N/A | +| `turn_end` | `type == "result"` | `type == "turn.completed"` | `type == "result"` | +| `usage` | `result.usage` | `turn.completed.usage` | `result.stats` | + +### Audit trail source (decided 2026-03-26) + +The activity feed and audit trail are populated **entirely from the child +agent's JSON stdout stream**, not from MCP server hooks. The runner parses +stdout for both token streaming and tool-call-level events. The MCP server +contributes only koan-specific events (step transitions, phase start/end). + +This means: + +- No `tool_call` / `tool_result` hooks needed in the MCP server +- The runner is the sole source of native tool visibility +- Audit completeness depends on the runner's stream parser quality +- Different CLIs may expose different levels of tool detail in their output + +--- + +## Open Questions + +1. **Claude `--strict-mcp-config` + HTTP**: Does `--strict-mcp-config` + work correctly with HTTP MCP servers (not just stdio)? Need to verify + it doesn't break claude's built-in tools. + +2. **Codex HTTP MCP**: Does `-c 'mcp_servers.koan.url="http://..."'` + work for HTTP transport? The `-c` per-process override was confirmed, + but only with stdio `command`/`args` format. Need to test with `url`. + +3. **Gemini HTTP MCP config format**: Verify that + `{"type":"http","url":"..."}` is the correct format in + `.gemini/settings.json` for HTTP transport. + +4. **Codex token streaming gap**: Codex only emits `item.completed` with + the full message — no incremental deltas. Dashboard token streaming + will be blank during Codex turns. Acceptable, or investigate further. + +5. **MCP Streamable HTTP implementation**: Which Python MCP SDK library + supports the Streamable HTTP transport server-side? Verify + `mcp[server]` supports mounting as a Starlette route. diff --git a/plans/2026-03-28-frontend-react-zustand.md b/plans/2026-03-28-frontend-react-zustand.md new file mode 100644 index 0000000..c258ada --- /dev/null +++ b/plans/2026-03-28-frontend-react-zustand.md @@ -0,0 +1,845 @@ +# Frontend Port: React + Zustand + Vite + +## Summary + +Port the koan frontend from server-rendered Jinja2 fragments + vanilla JS to a React SPA with Zustand state management and Vite build tooling. The Python backend becomes a pure JSON API + SSE server. No Node.js server in production — Python serves the built bundle. + +## Decisions & Rationale + +### Zustand over Effector or Redux Toolkit + +The author has re-frame/reagent (ClojureScript) experience and wanted the closest minimal equivalent in the React ecosystem. Re-frame's core value is: a single app-db atom, pure event handlers that transform it, and subscriptions as reactive derived queries. + +Zustand covers this model without the ceremony: + +- Single store = `app-db` +- Action functions inside the store = event handlers +- Selector functions = subscriptions + +Effector would have been architecturally closer (explicit events, stores, effects as first-class objects), but its smaller community and steeper onboarding cost outweigh the purity benefit for a project this size. Redux Toolkit has the ecosystem but too much boilerplate. Zustand is the pragmatic middle ground. + +### Vite over Next.js or Remix + +koan is a local developer tool, not a public website. Server-side rendering provides no value: there are no SEO requirements, no cold-load performance targets, and only one operator runs the app at a time. Vite gives fast HMR during development and a clean static bundle for production with zero SSR complexity. + +### No router library + +The app has exactly two views: the landing configuration page and the live run view. The transition between them is driven by a single boolean (`runStarted`) in the store. A routing library (React Router, TanStack Router) would add a dependency, route definitions, and navigation primitives for a problem that a conditional render solves in three lines. + +### Python serves built assets in production + +No Node.js process in production. The Starlette server already handles HTTP; it can serve `frontend/dist/` as static files via a `StaticFiles` mount. This keeps the deployment model identical to the current one: one `uv run koan` command, one port, no additional infrastructure. + +### Server-rendered HTML fragments → JSON SSE + +This is the fundamental architectural shift. The current system has Python render Jinja2 templates to HTML strings, push them over SSE, and the browser does `innerHTML` swaps. This couples every UI change to both Python templates and JS event handlers, and causes a class of silent bugs where DOM element IDs are destroyed mid-stream. + +The new system: `push_sse()` emits raw JSON. React components subscribe to store slices. The browser renders from data, not from server-generated markup. `_render_fragment()` is deleted entirely. + +### CSS design system ports directly + +The existing stylesheet uses CSS custom properties (`--color-bg`, `--text-primary`, etc.) with no preprocessor and no framework. It is framework-agnostic by construction. The four CSS files (`variables.css`, `layout.css`, `components.css`, `animations.css`) can be imported into the React app without modification. In the frontend directory they are consolidated to three files — `animations.css` content is merged into `components.css` since they are co-dependent (animation classes are applied by component class names). + +### Minimal dependencies + +React 19, Zustand 5, Vite 6. No axios (native `fetch` is sufficient), no react-router (see above), no CSS-in-JS (existing CSS ports directly), no component library (existing design system is the component library). Every added dependency is a future maintenance burden; this list is the minimum viable set. + +--- + +## Motivation + +The current architecture (server renders HTML fragments, pushes via SSE, JS does `innerHTML` swap) has hit its limits: + +- **Fragile DOM updates**: `outerHTML` vs `innerHTML` bugs silently break SSE event handlers when target element IDs are destroyed. This caused multiple regressions during the initial bug-fix session. +- **No component state**: The activity feed can't auto-scroll reliably, "thinking" indicators don't flow downward as new entries arrive, elapsed timers require manual `setInterval` hacks scanning the DOM for `[data-started-at]` attributes. +- **Server-side coupling**: Every UI change requires modifying both a Python Jinja2 template and the corresponding JS event handler. There is no single source of truth for what a UI element looks like. +- **No animations**: Fragment swapping (`innerHTML = serverHTML`) makes CSS transitions and entry animations impossible — the DOM node is replaced wholesale each time. + +## Architecture + +### Directory Layout + +``` +koan/ +├── koan/ # Python package (existing, mostly unchanged) +│ ├── driver.py # simplified: push_sse sends JSON only, _render_fragment() deleted +│ ├── web/ +│ │ ├── app.py # API routes only; no Jinja2 rendering for SSE events +│ │ ├── mcp_endpoint.py # unchanged — subagent communication is backend-only +│ │ └── static/ +│ │ └── app/ # Vite build output (vite build --outDir ../koan/web/static/app) +│ └── ... +├── frontend/ # NEW — lives alongside koan/, not inside it +│ ├── package.json +│ ├── tsconfig.json +│ ├── vite.config.ts # proxies /api/*, /events, /mcp/* to Python in dev +│ ├── index.html # Vite entry point; references /src/main.tsx +│ ├── src/ +│ │ ├── main.tsx # mounts <App /> into #root; imports global CSS +│ │ ├── App.tsx # top-level layout; owns SSE connection lifecycle +│ │ ├── store/ +│ │ │ ├── index.ts # single Zustand store — the app-db equivalent +│ │ │ └── selectors.ts # derived state computed from store slices +│ │ ├── sse/ +│ │ │ └── connect.ts # EventSource wrapper: reconnect logic + store dispatch +│ │ ├── api/ +│ │ │ └── client.ts # typed fetch wrappers for all POST/PUT endpoints +│ │ ├── components/ +│ │ │ ├── Header.tsx +│ │ │ ├── PillStrip.tsx +│ │ │ ├── StatusSidebar.tsx +│ │ │ ├── ActivityFeed.tsx +│ │ │ ├── AgentMonitor.tsx +│ │ │ ├── ArtifactsSidebar.tsx +│ │ │ ├── Notification.tsx # toast notifications from 'notification' SSE events +│ │ │ ├── interactions/ +│ │ │ │ ├── AskWizard.tsx # multi-question card navigation +│ │ │ │ ├── ArtifactReview.tsx +│ │ │ │ └── WorkflowDecision.tsx # chat-style phase selection +│ │ │ ├── Completion.tsx +│ │ │ ├── LandingPage.tsx +│ │ │ └── SettingsOverlay.tsx +│ │ ├── hooks/ +│ │ │ ├── useElapsed.ts # replaces manual setInterval + DOM attribute scanning +│ │ │ └── useAutoScroll.ts # replaces manual scrollTop manipulation +│ │ └── styles/ +│ │ ├── variables.css # ported verbatim from koan/web/static/css/variables.css +│ │ ├── layout.css # ported verbatim +│ │ └── components.css # ported from components.css + animations.css merged in +│ └── dist/ # Vite build output (gitignored) +└── pyproject.toml +``` + +### Dev vs Production + +**Development:** Vite dev server proxies all backend traffic to the running Python process. SSE requires special proxy configuration — see `vite.config.ts` below. + +``` +vite dev (:5173) → proxy /api/*, /events, /mcp/* → python (:8000) +``` + +**Production:** A single `uv run koan` command. Python serves the compiled bundle as static files. No Node.js process required. + +``` +python (:8000) → /static/app/* → serves frontend/dist/ (Vite build output) + → /api/*, /events, /mcp/* → existing routes (unchanged) + → /* (all other paths) → serves index.html (SPA fallback, must be last) +``` + +**`vite.config.ts`:** + +```ts +import { defineConfig } from "vite"; +import react from "@vitejs/plugin-react"; + +export default defineConfig({ + plugins: [react()], + + // In production the built assets live at /static/app/ on the Python server. + // This must match the StaticFiles mount path in create_app(). + base: "/static/app/", + + build: { + // Output directly into the Python package's static directory so + // `uv run koan` serves the latest build without a copy step. + outDir: "../koan/web/static/app", + emptyOutDir: true, + }, + + server: { + proxy: { + // Proxy all backend traffic through Vite's dev server. + // The SSE endpoint (/events) needs special handling: disable buffering + // so chunks are forwarded immediately rather than batched. Without this, + // SSE events arrive in groups after a delay, breaking the real-time feed. + "/events": { + target: "http://localhost:8000", + changeOrigin: true, + // Disable response buffering for the SSE stream. + // http-proxy buffers responses by default; the proxyRes hook + // forwards streaming headers so chunks arrive immediately. + // Without this, SSE events batch and the real-time feed breaks. + configure: (proxy) => { + proxy.on("proxyReq", (proxyReq) => { + proxyReq.setHeader("Accept", "text/event-stream"); + }); + proxy.on("proxyRes", (proxyRes) => { + // Prevent any intermediate buffering (nginx, proxies, etc.) + proxyRes.headers["x-accel-buffering"] = "no"; + proxyRes.headers["cache-control"] = "no-cache"; + }); + }, + }, + "/api": { target: "http://localhost:8000", changeOrigin: true }, + "/mcp": { target: "http://localhost:8000", changeOrigin: true }, + }, + }, +}); +``` + +> **Verify SSE during Phase 3:** Before building any components that consume streaming data, confirm that SSE events arrive incrementally in the Vite dev proxy. Open the browser DevTools Network tab, inspect the `/events` connection, and confirm events appear one-by-one rather than in batches. + +**Starlette route order in `create_app()`:** + +Route order is significant in Starlette — first match wins. The SPA fallback must come last. + +```python +routes = [ + # MCP before static, in case path overlap ever occurs + Mount("/mcp", app=mcp_app), + # API routes (all /api/* handlers) + Route("/api/start-run", api_start_run, methods=["POST"]), + # ... all other /api/* routes ... + # SSE stream + Route("/events", sse_stream), + # Built React app assets — served from frontend/dist/ (= koan/web/static/app/) + Mount("/static/app", app=StaticFiles(directory=FRONTEND_DIST, html=False)), + # Legacy static (if any other static assets remain) + Mount("/static", app=StaticFiles(directory=STATIC_DIR)), + # SPA fallback: any path not matched above returns index.html. + # React reads store state (runStarted) to decide which view to render. + Route("/{path:path}", spa_fallback), +] +``` + +Where `FRONTEND_DIST = Path(__file__).parent / "static" / "app"`. + +## Zustand Store + +Single store modeling the complete UI state. Every piece of state the current `AppState` exposes to the frontend lives here. Actions (mutations) are defined inline following Zustand's standard pattern — this is the re-frame `reg-event-db` equivalent, without a separate dispatch call. + +```ts +// AgentInfo: shape returned by _build_subagent_json / _build_agents_json. +// All time/token values are raw numbers — formatting is done in components +// via useElapsed and formatTokens helpers, not on the Python side. +interface AgentInfo { + agentId: string; + role: string; + model: string | null; + step: number; + stepName: string; // resolved from phase_module.STEP_NAMES server-side; + // e.g. "Extract" not "step 1". Must be in the SSE payload. + startedAt: number; // UTC epoch milliseconds (from datetime.now(timezone.utc)) + tokensSent: number; // raw count; formatted by formatTokens() in the component + tokensReceived: number; +} + +// Shape of artifacts from _build_artifacts_json. Flat list; +// grouped into a directory tree by the useArtifactTree selector. +interface ArtifactFile { + path: string; // relative to epic dir, e.g. "brief/overview.md" + size: number; // bytes + modifiedAt: number; // UTC epoch milliseconds +} + +// Shape of pipeline-end SSE event payload. +interface CompletionInfo { + success: boolean; + summary: string; // LLM-generated run summary (empty on failure) + error: string; // error message (empty on success) + phase: string; // phase that was active when pipeline ended + artifacts: ArtifactFile[]; +} + +// Notification entry with mapped severity for styling. +interface NotificationEntry { + id: string; // crypto.randomUUID() — unique per notification + type: string; // original categorical type from backend (e.g. 'runner_error') + severity: "error" | "warning" | "info"; // mapped at the SSE bridge boundary + message: string; + detail?: string; +} + +interface KoanState { + // ── Connection ────────────────────────────────────────────────────────────── + // Tracks SSE health. Components can show a disconnected banner when false. + connected: boolean; + + // ── Run state ─────────────────────────────────────────────────────────────── + // runStarted gates which top-level view renders (landing vs live). + // Avoids a router dependency for a binary choice. + runStarted: boolean; + phase: string; // current pipeline phase name, e.g. "intake" + donePhases: string[]; // phases completed; drives pill strip styling + + // ── Primary agent ──────────────────────────────────────────────────────────── + // The phase-level agent (intake, brief-writer, etc.) shown in the left sidebar. + // Null when no agent is active (between phases or before run starts). + primaryAgent: AgentInfo | null; + + // ── Intake sub-phase progress ──────────────────────────────────────────────── + // Set by 'intake-progress' SSE events during the intake phase only. + // Null outside of intake; StatusSidebar renders this when non-null. + intakeProgress: { + subPhase: string; + confidence: string | null; + summary: string; + } | null; + + // ── Scout agents ───────────────────────────────────────────────────────────── + // Parallel sub-agents spawned by koan_request_scouts. Keyed by agent_id. + // The 'agents' SSE event delivers a full replacement list — there are no + // per-scout incremental update events. setScouts does a wholesale replace. + scouts: Record<string, AgentInfo>; + + // ── Activity feed ──────────────────────────────────────────────────────────── + // activityLog is append-only — entries are never removed. + // streamBuffer accumulates token-delta events; rendered as the in-flight + // streaming text until cleared by a 'token-clear' event. + activityLog: ActivityEntry[]; + streamBuffer: string; + + // ── Notifications ──────────────────────────────────────────────────────────── + // Transient toasts rendered by Notification.tsx. Each entry auto-dismisses. + // The 'notification' SSE event carries type, message, and optional metadata. + notifications: NotificationEntry[]; + + // ── Interaction ────────────────────────────────────────────────────────────── + // Only one interaction is active at a time (enforced by the backend queue). + // Setting this to non-null causes the workspace to render the interaction UI + // instead of the activity feed. null when the interaction is cleared. + // type: 'ask' | 'artifact-review' | 'workflow-decision' + activeInteraction: Interaction | null; + + // ── Artifacts ──────────────────────────────────────────────────────────────── + // Flat list; grouped into a tree by the useArtifactTree selector. + artifacts: ArtifactFile[]; + + // ── Pipeline completion ────────────────────────────────────────────────────── + // Set once on pipeline-end SSE event; triggers Completion view. + completion: CompletionInfo | null; + + // ── Settings ───────────────────────────────────────────────────────────────── + // Settings overlay is fully client-side; open/close state lives here. + // profiles and installations are fetched from /api/* when the overlay opens. + settingsOpen: boolean; + profiles: Profile[]; + installations: Installation[]; + + // ── Actions ────────────────────────────────────────────────────────────────── + setConnected: (v: boolean) => void; + setPhase: (phase: string) => void; // also sets runStarted=true and derives donePhases + setPrimaryAgent: (agent: AgentInfo | null) => void; + setIntakeProgress: (p: KoanState["intakeProgress"]) => void; + setScouts: (scouts: Record<string, AgentInfo>) => void; // full replace + appendLog: (entry: ActivityEntry) => void; + appendStreamDelta: (delta: string) => void; + clearStream: () => void; // called on 'token-clear' SSE event + addNotification: (n: NotificationEntry) => void; + dismissNotification: (id: string) => void; + setInteraction: (interaction: Interaction | null) => void; + setArtifacts: (artifacts: ArtifactFile[]) => void; + setCompletion: (info: CompletionInfo) => void; +} +``` + +### Selectors + +Selectors are the re-frame `reg-sub` equivalent. Zustand re-renders only the component whose subscribed slice changed. Keep selectors close to the components that use them, or in `selectors.ts` if shared. + +```ts +// useStore(selector) is Zustand's subscription primitive. +// Each hook subscribes only to the slice it reads; unrelated state changes +// do not trigger re-renders in components using these hooks. + +// Transforms scouts dict → array for rendering in AgentMonitor table rows. +const useScoutList = () => useStore((s) => Object.values(s.scouts)); + +// Isolated subscription: StatusSidebar re-renders only when primaryAgent changes. +const usePrimaryAgent = () => useStore((s) => s.primaryAgent); + +// Boolean subscription: drives conditional rendering of the interaction overlay +// without subscribing to the full interaction payload. +const useHasInteraction = () => useStore((s) => s.activeInteraction !== null); + +// Derived computation: groups flat artifact list into {dir: files[]} tree. +// If this selector is expensive, wrap in useMemo inside the component. +const useArtifactTree = () => useStore((s) => groupByDirectory(s.artifacts)); +``` + +## SSE Bridge + +The SSE connection is the sole ingress path for live state. All backend events flow through this bridge; nothing else writes to the store from outside the component tree. The `connectSSE` function is called from an `App.tsx` `useEffect` which owns reconnect scheduling. + +```ts +// connectSSE opens an EventSource and wires every SSE event type to a store action. +// Returns the EventSource so the caller can close it on unmount or reconnect. +// Does NOT schedule its own reconnect — App.tsx owns that lifecycle. +function connectSSE(store: KoanStore): EventSource { + const es = new EventSource("/events"); + + store.getState().setConnected(true); + + // ── Structural events ──────────────────────────────────────────────────────── + // These correspond to the low-frequency events that previously triggered + // server-rendered HTML fragment swaps. Now they're just data — the store + // updates and React re-renders the relevant component slice. + + es.addEventListener("phase", (e) => { + const d = JSON.parse(e.data); + // setPhase also sets runStarted=true (any phase event means a run is active) + // and derives donePhases (all known phases before current). This is critical + // for page reloads mid-run: the replayed 'phase' event flips runStarted, + // so the user sees the live view instead of the landing page. + store.getState().setPhase(d.phase); + }); + + es.addEventListener("subagent", (e) => { + const d = JSON.parse(e.data); + // _build_subagent_json returns {"agent_id": None} when no primary agent is active. + // Guard against this to avoid setting primaryAgent to an object with all-undefined + // fields — StatusSidebar checks for null to show the idle state. + if (d.agent_id === null || d.agent_id === undefined) { + store.getState().setPrimaryAgent(null); + return; + } + // started_at_ms is a UTC epoch ms timestamp (Python: datetime.now(timezone.utc)). + // The useElapsed hook computes display string client-side on a 1s interval, + // eliminating the DOM-scanning setInterval hack from koan.js. + // stepName is resolved server-side from phase_module.STEP_NAMES — the client + // does not have access to step name mappings. + store.getState().setPrimaryAgent({ + agentId: d.agent_id, + role: d.role, + model: d.model, + step: d.step, + stepName: d.step_name, + startedAt: d.started_at_ms, + tokensSent: d.tokens_sent, + tokensReceived: d.tokens_received, + }); + }); + + es.addEventListener("subagent-idle", () => { + // Agent process exited; clear the sidebar until the next agent spawns. + store.getState().setPrimaryAgent(null); + }); + + es.addEventListener("agents", (e) => { + const d = JSON.parse(e.data); + // d.agents is an array from _build_agents_json(). Python emits snake_case; + // we map to camelCase here at the bridge boundary — same as the subagent handler. + // Without this mapping, Object.fromEntries would key everything under "undefined" + // because a.agentId doesn't exist on the raw JSON (it's a.agent_id). + const scouts = Object.fromEntries( + d.agents.map((a: any) => [ + a.agent_id, + { + agentId: a.agent_id, + role: a.role, + model: a.model, + step: a.step, + stepName: a.step_name, + startedAt: a.started_at_ms, + tokensSent: a.tokens_sent, + tokensReceived: a.tokens_received, + } satisfies AgentInfo, + ]), + ); + store.getState().setScouts(scouts); + }); + + es.addEventListener("artifacts", (e) => { + const d = JSON.parse(e.data); + store.getState().setArtifacts(d.artifacts); + }); + + es.addEventListener("intake-progress", (e) => { + const d = JSON.parse(e.data); + // Only emitted during the intake phase. StatusSidebar renders subPhase + // and summary when this is non-null. + store.getState().setIntakeProgress({ + subPhase: d.subPhase ?? "", + confidence: d.confidence ?? null, + summary: d.summary ?? "", + }); + }); + + // ── High-frequency events ──────────────────────────────────────────────────── + // These bypass the store's full update cycle by targeting append-only slices. + // token-delta can fire many times per second during streaming. + + es.addEventListener("token-delta", (e) => { + const d = JSON.parse(e.data); + store.getState().appendStreamDelta(d.delta); + }); + + es.addEventListener("token-clear", () => { + // Emitted when the backend resets the stream for a new turn. + // Clears streamBuffer so the next turn starts fresh. + store.getState().clearStream(); + }); + + es.addEventListener("logs", (e) => { + const d = JSON.parse(e.data); + // ActivityEntry shape: { tool: string, summary: string, inFlight: boolean, ts?: string } + // ActivityFeed renders inFlight entries with a pulse animation and settles + // them when a matching non-inFlight entry for the same tool arrives. + store.getState().appendLog(d.line); + }); + + // ── Notifications ──────────────────────────────────────────────────────────── + es.addEventListener("notification", (e) => { + const d = JSON.parse(e.data); + // Transient toasts: runner errors, config warnings, cancelled interactions. + // Notification.tsx auto-dismisses after a timeout. + // Backend notification types are categorical event names (e.g. 'runner_error', + // 'bootstrap_failure', 'interaction_cancelled'), NOT severity levels. + // Map to severity here at the bridge boundary for Notification.tsx styling. + const SEVERITY_MAP: Record<string, "error" | "warning" | "info"> = { + runner_error: "error", + bootstrap_failure: "error", + spawn_failure: "error", + interaction_cancelled: "info", + config_warning: "warning", + }; + store.getState().addNotification({ + id: crypto.randomUUID(), + type: d.type, // original categorical type + severity: SEVERITY_MAP[d.type] ?? "info", // mapped severity for styling + message: d.message, + detail: d.details, + }); + }); + + // ── Interactions ───────────────────────────────────────────────────────────── + // The backend enqueues at most one interaction at a time. Setting activeInteraction + // non-null causes App.tsx to render the interaction component over the activity feed. + + es.addEventListener("interaction", (e) => { + const d = JSON.parse(e.data); + // 'cleared' means the interaction was resolved; restore the activity feed. + store.getState().setInteraction(d.type === "cleared" ? null : d); + }); + + es.addEventListener("pipeline-end", (e) => { + const d = JSON.parse(e.data); + store.getState().setCompletion(d); + }); + + // ── Error handling ─────────────────────────────────────────────────────────── + // EventSource fires onerror on network failure AND on clean server close. + // We close and signal the caller; App.tsx schedules the reconnect. + es.onerror = () => { + store.getState().setConnected(false); + es.close(); + // onDisconnect is a callback passed by App.tsx to trigger reconnect scheduling. + // This keeps the exponential backoff logic in one place (App.tsx useEffect). + }; + + return es; +} +``` + +**`App.tsx` reconnect loop:** + +```ts +useEffect(() => { + let es: EventSource | null = null; + let retryDelay = 500; + + function connect() { + es = connectSSE(store); + // Override the onerror set inside connectSSE to schedule our retry. + es.onerror = () => { + store.getState().setConnected(false); + es?.close(); + // Exponential backoff capped at 5s, matching the old koan.js behaviour. + setTimeout(connect, retryDelay); + retryDelay = Math.min(retryDelay * 2, 5000); + }; + // Reset backoff on successful connection. + es.onopen = () => { + retryDelay = 500; + }; + } + + connect(); + + // Cleanup on unmount — prevents duplicate SSE connections in React StrictMode. + return () => { + es?.close(); + }; +}, []); // Empty dep array: connect once, reconnect is managed inside +``` + +## Backend Changes + +### Remove from Python + +1. **Delete `_render_fragment()`** from `driver.py` — the 120-line Jinja2 dispatch function that couples the driver to the web layer +2. **Delete all fragment templates** — `koan/web/templates/fragments/*.html` (13 files, ~350 lines) +3. **Delete `koan.js`** — replaced entirely by the React app +4. **Delete `base.html`, `live.html`, `landing.html`** — replaced by `frontend/index.html` + React +5. **Remove `jinja2` dependency** from `pyproject.toml` once no templates remain + +### Modify in Python + +**`push_sse()` — emit raw JSON, no HTML wrapping:** + +The key change: `push_sse` previously called `_render_fragment()` which rendered Jinja2 and returned `{html, target, ...data}`. Now it enriches the payload with current state and emits pure data. The `html` and `target` fields disappear from every SSE event. + +> **Critical:** `_render_fragment()` currently has the side effect `app_state.phase = phase` inside the `phase` event branch. This is the only place `app_state.phase` is written during a run. When `_render_fragment()` is deleted, this assignment must be preserved in `push_sse()`. + +```python +def push_sse(app_state, event_type, payload): + # --- Side effects that currently live inside _render_fragment() --- + # Must be preserved here after _render_fragment() is deleted. + if event_type == "phase": + # app_state.phase is read by _build_subagent_json and other helpers. + # Without this assignment, all subsequent subagent payloads would + # return "intake" regardless of the actual phase. + phase = payload if isinstance(payload, str) else payload.get("phase", "") + app_state.phase = phase + payload = {"phase": phase} + + # --- Structural events: enrich payload with current state --- + # These replace _render_fragment()'s template rendering — same data, + # no HTML generation. + elif event_type in ("subagent", "subagent-idle"): + # subagent/subagent-idle payloads from callers are always discarded. + # We rebuild from AppState to guarantee consistent shape. + # Returns {"agent_id": None, ...} when no primary agent is active. + payload = _build_subagent_json(app_state) + + elif event_type == "agents": + # Full scout list — the frontend does a wholesale replace. + payload = {"agents": _build_agents_json(app_state)} + + elif event_type == "artifacts": + payload = {"artifacts": _build_artifacts_json(app_state)} + + # intake-progress: pass through payload fields (subPhase, confidence, summary). + # No agent enrichment — agent state arrives via the separate 'subagent' event. + + elif event_type == "intake-progress": + # Pass through subPhase/confidence/summary from caller. + # Agent state is NOT included — it arrives via the 'subagent' SSE event. + payload = payload if isinstance(payload, dict) else {} + + # --- Cache stateful events for replay to reconnecting clients --- + # The replay mechanism is unchanged; only the payload format changes + # (was {html, target, ...}, now pure data). + if event_type in STATEFUL_EVENTS: + app_state.last_sse_values[event_type] = payload + + for queue in app_state.sse_clients: + queue.put_nowait((event_type, payload)) +``` + +**New JSON builder functions** (replace `_build_subagent_display` etc.): + +```python +def _build_subagent_json(app_state) -> dict: + """Return primary agent state as a JSON-serialisable dict. + + Raw values only — no pre-formatted strings. The React client formats + elapsed time via useElapsed() and token counts via formatTokens(). + step_name is resolved here because the client has no access to + phase_module.STEP_NAMES. + """ + for agent in app_state.agents.values(): + if not agent.is_primary: + continue + return { + "agent_id": agent.agent_id, + "role": agent.role, + "model": agent.model, + "step": agent.step, + # Resolved server-side; falls back to "step N" if not in STEP_NAMES. + "step_name": ( + agent.phase_module.STEP_NAMES.get(agent.step, f"step {agent.step}") + if agent.phase_module and hasattr(agent.phase_module, "STEP_NAMES") + else f"step {agent.step}" + ), + # UTC epoch milliseconds; client uses Date.now() - startedAt for elapsed. + "started_at_ms": int(agent.started_at.timestamp() * 1000), + # Raw counts; client formats as "12k / 4k" or similar. + "tokens_sent": agent.token_count.get("sent", 0), + "tokens_received": agent.token_count.get("received", 0), + } + return {"agent_id": None} # no primary agent active + + +def _build_agents_json(app_state) -> list[dict]: + """Return scout (non-primary) agents as a list for the monitor table. + + Same raw-values convention as _build_subagent_json. + agent_id is included so the frontend can key the Record<string, AgentInfo>. + """ + result = [] + for agent in app_state.agents.values(): + if agent.is_primary: + continue + result.append({ + "agent_id": agent.agent_id, + "role": agent.role, + "model": agent.model, + "step": agent.step, + "step_name": f"step {agent.step}", # scouts don't have STEP_NAMES + "started_at_ms": int(agent.started_at.timestamp() * 1000), + "tokens_sent": agent.token_count.get("sent", 0), + "tokens_received": agent.token_count.get("received", 0), + "doing": f"step {agent.step}", # for the "Doing" column + }) + return result + + +def _build_artifacts_json(app_state) -> list[dict]: + """Return artifact list as JSON-serialisable dicts. + + Flat list; the frontend groups into a directory tree via the + useArtifactTree selector. Sizes are raw bytes (client formats). + modifiedAt is UTC epoch milliseconds for consistency with startedAt. + """ + if not app_state.epic_dir: + return [] + try: + from .artifacts import list_artifacts + return [ + { + "path": a["path"], + "size": a["size"], + "modifiedAt": int(a["modified_at"] * 1000), + } + for a in list_artifacts(app_state.epic_dir) + ] + except Exception: + return [] +``` + +**`landing_page()` → SPA fallback route:** + +```python +# Must be registered LAST so /api/*, /mcp/*, and /static/* routes take priority. +# Starlette route ordering is significant — first match wins. +async def spa_fallback(request): + # Return the built React app entry point for any path not matched above. + # React reads store state (runStarted) to decide which view to render. + return FileResponse(FRONTEND_DIST / "index.html") +``` + +**Convert settings endpoints to JSON:** + +Three endpoints currently return server-rendered HTML fragments. Replace with JSON: + +- `GET /api/settings/body` → `{profiles: [...], installations: [...], activeInstallations: {runner_type: alias}, scoutConcurrency: N}` +- `GET /api/settings/profile-form` → `{name, tiers, availableRunners, isEdit}` +- `GET /api/settings/installation-form` → `{alias, runnerType, binary, extraArgs, allRunners, isEdit}` + +`SettingsOverlay.tsx` renders from these JSON responses using its own component state for form fields. The cascade dropdown logic (runner → available models → thinking modes) moves into the component using local `useState`. + +### Keep Unchanged + +- `mcp_endpoint.py` — subagent communication over HTTP is entirely backend-internal +- All `/api/*` JSON endpoints — already return JSON; no changes needed +- `/events` SSE transport — same EventSource protocol; payloads lose `html`/`target` fields only +- `driver.py` orchestration logic, phase modules, subagent lifecycle +- `interactions.py` queue management and `asyncio.Future` blocking pattern + +## Component Mapping + +| Current (Jinja2 + vanilla JS) | New (React + Zustand) | Store subscription | +| ----------------------------------------- | -------------------------------------- | ----------------------------------------- | +| `live.html` layout | `App.tsx` | `runStarted` | +| `status_sidebar.html` | `StatusSidebar.tsx` | `primaryAgent`, `phase`, `intakeProgress` | +| `monitor.html` | `AgentMonitor.tsx` | `scouts` (via `useScoutList`) | +| `artifacts_sidebar.html` | `ArtifactsSidebar.tsx` | `artifacts` (via `useArtifactTree`) | +| `interaction_ask.html` + JS handlers | `AskWizard.tsx` | `activeInteraction` | +| `interaction_workflow.html` + JS handlers | `WorkflowDecision.tsx` | `activeInteraction` | +| `interaction_artifact_review.html` | `ArtifactReview.tsx` | `activeInteraction` | +| `completion.html` | `Completion.tsx` | `completion` | +| `landing.html` | `LandingPage.tsx` | `runStarted` (negated) | +| `settings_body.html` + cascade JS | `SettingsOverlay.tsx` | `settingsOpen`, local state | +| Toast notifications in `koan.js` | `Notification.tsx` | `notifications` | +| Manual `setInterval` for elapsed | `useElapsed(startedAt)` hook | — | +| Manual `scrollTop` management | `useAutoScroll(ref)` hook | — | +| SSE reconnect in `koan.js` | `sse/connect.ts` + `App.tsx` useEffect | — | +| `intake-progress` SSE handler | `StatusSidebar.tsx` | `intakeProgress` | +| `story` SSE event | out of scope for v1 — see note below | — | +| `frozen-logs` SSE event | out of scope for v1 — see note below | — | + +> **`story` events:** Emitted during the execution phase with story lifecycle status (`planning`, `executing`, `verifying`, `done`, `retry`, `skipped`). Not in scope for the v1 React port — the execution phase will show only primary agent status and activity feed. **Known regression:** users lose story-level progress visibility during the longest pipeline phase. Add a `stories` store slice and a `StoryProgress` component when the execution phase UI is designed. + +> **`frozen-logs` events:** Emitted once before the orchestrator subagent spawns to snapshot the current activity log. Currently handled by `koan.js` as a fragment swap. For v1, this can be ignored — the activity feed maintains its own append-only log. If the orchestrator phase needs to show a historical log boundary, add it in a follow-up. + +## Migration Order + +### Phase 1: Parallel Setup + +- Initialize `frontend/` with Vite + React + TypeScript + Zustand +- Configure Vite proxy including SSE-specific settings (see `vite.config.ts` above) +- Port CSS files verbatim; verify design tokens render correctly in React +- Build `App.tsx` shell with three-column layout (no data yet — static skeleton) + +### Phase 2: Landing Page + +- `LandingPage.tsx` — task textarea, profile select, scout concurrency input, start button +- API client (`client.ts`) for `/api/start-run` and `/api/probe` +- Store: `runStarted` flag toggles landing → live view + +### Phase 3: Live View Core + +- SSE bridge (`connect.ts`) — connect, parse all event types, dispatch to store +- Verify SSE events arrive incrementally through the Vite proxy (not batched) +- **Dev-time constraint:** During Phases 3-5, the Python backend still emits HTML-wrapped `{html, target, ...}` payloads for structural events. The React bridge will only receive correct JSON-only payloads after Phase 6. Use mock store state (`useStore.setState({...})` in DevTools console) to drive component rendering during development. +- `StatusSidebar.tsx` — phase, primary agent, `useElapsed` hook, `intakeProgress` +- `ActivityFeed.tsx` — log entry list, `useAutoScroll` hook, thinking animation, stream buffer +- `PillStrip.tsx` — phase pills from `phase` + `donePhases` +- `Notification.tsx` — toast queue with auto-dismiss + +### Phase 4: Interactions + +- `AskWizard.tsx` — card-per-question navigation, radio/checkbox, "Other" text, Use Defaults +- `WorkflowDecision.tsx` — chat turns display, phase option buttons, context textarea +- `ArtifactReview.tsx` — content display, feedback textarea, Accept / Send Feedback +- API client additions: `/api/answer`, `/api/artifact-review`, `/api/workflow-decision` + +### Phase 5: Remaining Views + +- `AgentMonitor.tsx` — scout table rows; status icon, role, model, tokens, elapsed, doing +- `ArtifactsSidebar.tsx` — folder toggle, file list, artifact content overlay +- `SettingsOverlay.tsx` — profiles CRUD, installations CRUD, cascade dropdowns from `/api/probe` +- `Completion.tsx` — success/failure summary, artifact list + +### Phase 6: Backend Cleanup + +- Delete `_render_fragment()` from `driver.py` (after preserving `app_state.phase` assignment) +- Delete fragment templates and full-page Jinja2 templates +- Delete `koan.js` and old CSS from `koan/web/static/` +- Implement new JSON builder functions (`_build_subagent_json`, `_build_agents_json`, `_build_artifacts_json`) +- Convert three settings HTML endpoints to JSON +- Remove `jinja2` from `pyproject.toml` +- **Atomic route swap:** Remove `Route("/", landing_page)` and add `Route("/{path:path}", spa_fallback)` in a single commit. Starlette's `/{path:path}` does match the empty path `/`, but add a comment documenting this non-obvious behaviour. Also add `StaticFiles` mount for `frontend/dist/` +- Run full test suite; update any tests that mock rendered HTML or check for `html`/`target` fields in SSE payloads + +## Dependencies + +```json +{ + "dependencies": { + // React 19 ships concurrent features and the new compiler by default. + // react-dom is the browser renderer; separate package since React 0.14. + "react": "^19", + "react-dom": "^19", + + // Zustand 5 uses the React 18+ useSyncExternalStore primitive under the hood, + // which gives correct concurrent-mode behaviour without extra configuration. + "zustand": "^5" + }, + "devDependencies": { + "@types/react": "^19", + "@types/react-dom": "^19", + + // TypeScript 5.7 required for React 19 type compatibility. + "typescript": "^5.7", + + // Vite 6 + the React plugin handles JSX transform (no import React needed), + // fast HMR via esbuild, and production bundling via Rollup. + "vite": "^6", + "@vitejs/plugin-react": "^4" + } +} +``` + +Intentionally minimal. No router library (two views, conditional render). No CSS framework (existing design tokens port directly). No fetch library (native `fetch` with typed wrappers in `api/client.ts` is sufficient). No state middleware (Zustand devtools can be added if needed, but not a startup dependency). diff --git a/plans/2026-03-29-event-sourced-projections.md b/plans/2026-03-29-event-sourced-projections.md new file mode 100644 index 0000000..65792ad --- /dev/null +++ b/plans/2026-03-29-event-sourced-projections.md @@ -0,0 +1,952 @@ +# Event-Sourced Projections + +## Summary + +Replace the ad-hoc `last_sse_values` dict + per-type SSE caching with a proper +event-sourced projection system. The backend maintains a versioned, append-only +event log in memory. A pure fold function reduces events into a materialized +projection — the complete frontend-visible state. Clients subscribe via SSE +with version-negotiated catch-up: snapshot on first connect, event replay on +reconnect. + +Also renames "pipeline" → "workflow" throughout the codebase for consistency +with existing `workflow-orchestrator` terminology. + +## Problem + +The current system stores `last_sse_values[event_type] = payload` — one value +per event type. On browser reconnect, these are replayed. This has two +fundamental issues: + +1. **Accumulating state is lost.** `logs` (activity feed entries), `token-delta` + (streaming text), and `notification` events are not cached. A page refresh + mid-run loses the entire activity history and streaming buffer. + +2. **Events are state snapshots, not facts.** The current SSE events (e.g. + `subagent`, `agents`, `artifacts`) push full state replacements rather than + describing what happened. `subagent-idle` is a "nothing happened" sentinel + rather than the fact "agent X exited." This conflates the event log with + the projection and makes the system impossible to reason about from an + event-sourcing perspective. + +## Decisions + +### Naming: "projections" + +The subsystem is called **projections**, consistent with the existing audit fold +terminology in `koan/audit/fold.py`. The backend module is `koan/projections.py`. +The materialized state type is `Projection`. The event log + fold + subscription +machinery lives in a `ProjectionStore` class. + +### Naming: "pipeline" → "workflow" + +The word "pipeline" is used for the overall run lifecycle (`pipeline-end` SSE +event, docs references). The word "workflow" is already used for the phase +routing subsystem (`workflow-orchestrator`, `workflow-decision`, +`koan_propose_workflow`). These refer to the same thing — the sequence of phases +from intake to completion. Standardize on **workflow** everywhere: + +- `pipeline-end` event → `workflow_completed` event +- `pipeline_completed` references → `workflow_completed` +- `CompletionInfo` type keeps its name (describes the payload, not the concept) +- Docs references: "the pipeline" → "the workflow" +- The `workflow-orchestrator` name becomes _more_ natural: it orchestrates the workflow + +No conflict: `workflow-orchestrator` already uses this term for exactly this +concept. The orchestrator orchestrates the workflow. The rename makes the naming +internally consistent rather than introducing a new term. + +Note: the word "workflow" also appears informally in phase module comments +(e.g. `# Intake phase -- 5-step workflow`) where it means "step sequence within +a phase." This lowercase usage is distinct from "the Workflow" (the overall run) +and is clear from context. No rename needed for these comments. + +### Events are facts, not snapshots + +Every event in the versioned log represents **something that actually happened** +— not a state snapshot or derived metadata. The fold function derives state +from facts. This is the core design principle. + +Example: when a primary agent's subprocess exits, the event is `agent_exited` +(fact: the process terminated). The fold _derives_ `projection.primary_agent = +None` from this fact. There is no `subagent-idle` event — "nothing is running" +is derived state, not a fact. + +### All events are versioned + +Every `push_event()` call produces a `VersionedEvent` with a monotonically +increasing version number (1-based). This includes high-frequency events like +`stream_delta` (token deltas). The fold accumulates these into +`projection.stream_buffer`. On snapshot, the client gets the accumulated buffer +string — not thousands of individual deltas. + +Rationale: keeping the model uniform (every event gets a version) eliminates +special-case code paths. The event log may grow to thousands of entries per run, +but runs are short-lived and everything is in-memory. No persistence concern. + +### Version-negotiated catch-up + +The `/events` SSE endpoint accepts `?since=N`: + +- `since=0` (or omitted): send a `snapshot` SSE event with the complete + materialized projection + current version, then stream live events +- `since=N` where N > 0: replay events from version N+1 onward, then stream + live events + +The server always has the full event log in memory, so replay is always +possible. No threshold-based snapshot fallback needed. + +### Snapshot shape is backend-native (snake_case) + +The snapshot uses the same snake_case format as individual events. The frontend +transforms snake_case → camelCase at the bridge boundary, same as it does for +individual events today. This keeps the backend free of frontend formatting +concerns. + +### Frontend does atomic state replacement on snapshot + +When the frontend receives a `snapshot` event (on first connect), it atomically +replaces the entire Zustand store state via `useStore.setState(transform(data))`. +No merge logic, no version comparison. Simple and predictable. Any visual +flash from the re-render is acceptable. + +On subsequent events (during a live connection or replayed from `?since=N`), +the frontend applies events incrementally through its own fold function. + +### Pydantic models for type safety + +All event types, the event envelope, and the projection shape are defined as +Pydantic `BaseModel` subclasses. Event types use `Literal` unions for static +checking and `match` dispatch. This replaces bare `dict` payloads with typed, +validated structures. + +`EventType` is a `Literal` of all known event type strings. Unknown event types +are handled by the fold (return state unchanged, log warning) but cannot be +created through the typed API. + +### `agent_id` in the event envelope + +The event envelope carries an optional `agent_id: str | None` field. Most +events originate from a specific agent — tool calls, step advances, thinking, +streaming, interactions. A few do not (`phase_started`, `workflow_completed`, +artifact scan events when no agent is active). The envelope `agent_id` +eliminates the need to repeat it in every payload and enables generic +agent-scoped filtering. + +The envelope does **not** carry a UUID, causation ID, or correlation ID: + +- **No UUID**: `version` is a unique identifier within a run. UUIDs solve + cross-system deduplication across persistent stores; koan events are ephemeral + and in-memory. +- **No causation/correlation IDs**: These matter in multi-writer distributed + systems where independent producers interleave events and causal chains are + ambiguous. Koan has a single writer (the driver process). The causal chain is + implicit in temporal ordering plus `agent_id`. There is no cross-system + correlation to track. + +### push_event is pure; callers build complete payloads + +`push_event(event_type, payload, agent_id)` is a pure append + fold + broadcast. +It does not inspect or enrich the payload. Callers are responsible for building +fully-formed event payloads via typed helper functions in `koan/events.py`. + +This decouples the projection system from `AppState` internals. + +### `koan/projections.py` has zero koan domain imports + +`koan/projections.py` contains pure event-sourcing machinery: `VersionedEvent`, +`Projection`, `AgentProjection`, `ProjectionStore`, and `fold()`. It imports +nothing from the koan domain (`AgentState`, `list_artifacts`, `RunnerDiagnostic`, +etc.). Domain-to-event bridging lives exclusively in `koan/events.py`. + +This separation makes the projection engine testable in isolation and prevents +the event schema from leaking domain implementation details. + +### Activity log stores raw events + +`tool_called`, `tool_completed`, and `thinking` events are appended to +`activity_log` as-is, without a normalization layer. The frontend renders what +it needs from the raw payload. A normalization step would need to anticipate +every display use case in advance; raw events let the frontend decide. The +`call_id` on tool events enables the frontend to pair calls with completions +for in-flight state display. + +### `workflow_completed` does not carry the artifact list + +`workflow_completed` carries `success`, `summary`, and optional `error`. It +does not include the final artifact list. Consumers that need the current +artifact set at completion time read `projection.artifacts` — which is kept +current by `artifact_created`/`artifact_modified`/`artifact_removed` events +emitted throughout the run. + +### Accumulating state is unbounded + +The projection holds the complete activity log and stream buffer in memory with +no cap. Runs are short-lived; a typical run produces ~500–2000 activity entries. +This is well within memory bounds. + +### Graceful shutdown after completion + +koan is one-shot: one server instance serves one workflow run. After the +`workflow_completed` event, the server shuts down gracefully. No need to design +for state reset between runs. + +### Token/usage metadata is additive, not a dedicated event + +Token counts and usage metadata are not a standalone event type. They are +optional fields carried by events where they naturally occur: + +- `tool_called` / `tool_completed` may carry per-call usage if available +- `agent_step_advanced` carries cumulative token counts at step boundaries +- `agent_exited` carries final cumulative token counts + +The fold accumulates these into per-agent totals in the projection. + +Currently, token tracking is approximate: `subagent.py` counts `len(delta)` +from stdout `token_delta` events as `tokens_received`. `tokens_sent` is always +0 — no runner reports input token counts. The audit system defines a +`UsageEvent` type but nothing emits it. Proper per-request usage from LLM +providers can be wired later by adding usage fields to existing events. + +### Thinking events are incremental fire-and-forget + +`thinking` events carry `delta: str` — incremental blocks of thinking tokens, +like `stream_delta` but for internal reasoning. No `thinking_started` or +`thinking_ended` lifecycle. The client derives "thinking stopped" from the +next non-thinking event. + +Thinking content availability varies by runner. Some emit actual thinking text, +others emit markers with no content. The event is emitted with whatever the +runner provides. + +### Interaction events split into typed pairs + +The generic `interaction_created` / `interaction_resolved` events are replaced +by specific typed pairs: + +- `questions_asked` / `questions_answered` +- `artifact_review_requested` / `artifact_reviewed` +- `workflow_decision_requested` / `workflow_decided` + +Each pair has its own payload schema matching the interaction type's data. +Cancellation (e.g. agent exited while interaction pending) is indicated by +`cancelled: true` on the resolution event, not a separate event type. + +The fold sets `active_interaction` on the request event and clears it on the +resolution event. + +### `stream_cleared` is a tombstone event + +`stream_cleared` is a proper control event (tombstone) marking the end of a +stream. It is emitted explicitly — not derived from `agent_exited`. This keeps +the stream lifecycle decoupled from the agent lifecycle (a stream could +theoretically be cleared mid-agent, or an agent could exit without having +streamed). + +Emission points: emitted in `subagent.py` when the primary agent's streaming +loop ends (before `agent_exited`), and at the start of a new primary agent's +stdout streaming loop (to reset for the new agent). + +### `notification_fired` is eliminated + +There is no generic notification event. Every condition that was previously a +"notification" becomes a specific fact event: + +- **Runner can't resolve/build** → `agent_spawn_failed` event. The agent was + never spawned, so no `agent_spawned` event exists. `agent_id` in envelope is + `None`; the payload carries `role` to identify what was attempted. +- **Process exited without handshake** → `agent_exited` with `error` field + (e.g. `error: "bootstrap_failure"`). The agent WAS spawned. +- **Interaction cancelled due to agent exit** → the resolution pair event + (e.g. `questions_answered`) carries `cancelled: true`. + +The frontend derives which events are notification-worthy and maps event types +to severity in its own `SEVERITY_MAP`. The projection maintains a `notifications` +list populated by the fold when it encounters notification-worthy events +(`agent_spawn_failed`, `agent_exited` with error). This preserves notifications +across page refresh via snapshot. + +### Artifacts decomposed into diffs + +The old `artifacts_changed` event (full list replacement from filesystem scan) +is replaced by granular diff events: `artifact_created`, `artifact_modified`, +`artifact_removed`. Each carries a single artifact's metadata (`path`, `size`, +`modified_at`). + +The scan function (`list_artifacts`) compares the current filesystem state +against the projection's known artifact set and emits individual events for +each difference. The fold maintains `artifacts` as a `dict[str, dict]` keyed +by path, enabling O(1) updates per event. + +`agent_id` in the envelope is the primary agent at scan time. Scanning happens +at phase boundaries (bulk scan), so "which agent modified this file" is +approximate — it's "which agent was primary during this scan." + +### Tool events: generic with `call_id` + +`tool_called` and `tool_completed` are generic events — the `tool` field is a +canonical string (`"read"`, `"bash"`, `"koan_complete_step"`, etc.), not a +per-tool event type. The event schema is the same regardless of which tool. + +Each tool call gets a `call_id: str` (UUID) to pair `tool_called` with +`tool_completed`. Both events are always emitted — no fire-and-forget. +`args` and `result` are unstructured (`dict | str`) because tool argument +schemas vary across runners and tool types. + +The fold appends both to the activity log as raw events. + +### MCP tool calls are authoritative; stdout duplicates filtered + +When a subagent calls a koan MCP tool (e.g. `koan_complete_step`), two things +happen: the MCP endpoint handles the call, and the runner's stdout stream +contains the LLM's tool_use output. These are the same call seen from two +vantage points. + +The MCP endpoint is the authoritative source — it emits both `tool_called` and +`tool_completed` with structured data. Stdout-parsed tool events are filtered: +if the tool name matches a koan MCP tool, the stdout event is suppressed. + +For agent-native tools (file read, bash, etc.) that don't go through koan's +MCP, stdout parsing is the only source. These get a synthetic `call_id` (UUID) +generated at parse time. + +### Tool name normalization is per-runner responsibility + +Each runner normalizes its own tool names to canonical forms in +`parse_stream_event()`. Claude's `"Read"` → `"read"`. Codex's `"read_file"` → +`"read"`. Gemini's equivalent → `"read"`. By the time a `StreamEvent` leaves +the runner, tool names are already canonical. + +Known canonical names: `read`, `write`, `edit`, `bash`, `grep`. Unknown tools +pass through as-is. This is a runner concern — no central alias table. + +### `done_phases` is a frontend-only derivation + +`done_phases` (the list of phases before the current one, used for pill strip +styling) is not part of the backend projection. The frontend derives it from +`phase` using its own `ALL_PHASES` ordering constant. The backend does not need +`done_phases` for any decision — it is purely a presentation concern. + +The backend projection includes only `phase` (the current phase string). If the +backend ever needs the phase list for routing, that belongs in `AppState`, not +in the projection (derived values are not synchronized — the whole point is that +they can be derived). + +### `intake_progress_updated` is removed + +`intake_progress_updated` is not part of the event model. While there is +handling code for an `intake-progress` SSE event in the current `push_sse()` +and the frontend has a `setIntakeProgress` action, nothing in the codebase +actually emits this event. It is dead code end-to-end. Removed rather than +carried forward. If intake progress UI is needed, add it as a new event at that +time. + +### `story` events are deferred + +`push_sse(app_state, "story", {...})` is called 8 times in +`run_story_execution` and `run_story_reexecution`. The execution phase story +loop is partially stubbed — the story UI is a known gap (documented in +`docs/frontend.md`). These call sites are removed when `push_sse` is deleted. +Story projection events will be designed when the execution UI is built. + +### `?since=N` with stale version sends `fatal_error` SSE event + +If a client sends `?since=142` but the server's event log only goes up to +version 50 (or starts at 0 after restart), the server does NOT return an HTTP +error (browsers' `EventSource` cannot read error response bodies — any non-200 +fires `onerror` and would cause infinite reconnect with the same stale version). + +Instead, the server sends a `fatal_error` SSE event and closes the connection: + +``` +event: fatal_error +data: {"reason": "version_not_available"} +``` + +The frontend handles `fatal_error` by closing the `EventSource` WITHOUT +scheduling a reconnect, and sets a `fatalError` flag in the store. The UI +renders a "reload required" banner. This breaks the reconnect loop cleanly. + +This is not a recoverable scenario — the client must reload the page. This is +acceptable because server restarts during a run are not a normal operation. + +### No external library + +There is no canonical Python library for in-memory event sourcing with +subscriptions. The closest candidates (`python-eventsourcing`, `reactivex`) +are either enterprise-heavy (designed for database persistence) or awkward with +asyncio. The pattern — append-only list + pure fold + asyncio.Queue subscribers +— is simple enough to implement directly. The existing `koan/audit/fold.py` +already demonstrates this pattern for a different domain. + +## Event Model + +### Event envelope + +All events share this envelope. `agent_id` is included when the event +originates from or pertains to a specific agent. + +```python +EventType = Literal[ + # Lifecycle + "phase_started", "agent_spawned", "agent_spawn_failed", + "agent_step_advanced", "agent_exited", "workflow_completed", + # Activity + "tool_called", "tool_completed", "thinking", "stream_delta", "stream_cleared", + # Interactions + "questions_asked", "questions_answered", + "artifact_review_requested", "artifact_reviewed", + "workflow_decision_requested", "workflow_decided", + # Resources + "artifact_created", "artifact_modified", "artifact_removed", +] + +class VersionedEvent(BaseModel): + version: int # 1-based, monotonic + event_type: EventType + timestamp: str # ISO8601 UTC + agent_id: str | None = None # originating agent, when known + payload: dict # typed per event_type (see below) +``` + +### Lifecycle events + +| Event | What happened | Payload fields | `agent_id` | +| --------------------- | ----------------------------------------- | ------------------------------------- | ---------- | +| `phase_started` | Driver began a workflow phase | `phase` | `None` | +| `agent_spawned` | A subagent process was launched | `role, model, is_primary` | set | +| `agent_spawn_failed` | Spawn attempted but failed (runner error) | `role, error_code, message, ?details` | `None` | +| `agent_step_advanced` | Subagent called `koan_complete_step` | `step, step_name, ?usage` | set | +| `agent_exited` | Subagent process terminated | `exit_code, ?error, ?usage` | set | +| `workflow_completed` | Entire workflow finished | `success, summary, ?error` | `None` | + +`agent_spawned` does not carry `step` — step 0 is implied. The first +`agent_step_advanced` is for step 1. `agent_exited` does not carry `is_primary` +— the fold looks up the agent in projection state. + +### Activity events + +| Event | What happened | Payload fields | `agent_id` | +| ---------------- | ---------------------------- | ---------------------------------- | ---------- | +| `tool_called` | A tool was invoked | `call_id, tool, args, summary` | set | +| `tool_completed` | A tool call finished | `call_id, tool, ?result, ?summary` | set | +| `thinking` | LLM produced thinking tokens | `delta` | set | +| `stream_delta` | LLM produced output tokens | `delta` | set | +| `stream_cleared` | End-of-stream tombstone | (none) | set | + +`tool_called` and `tool_completed` are paired by `call_id` (UUID). `tool` is a +canonical normalized name (`read`, `bash`, `edit`, `grep`, +`koan_complete_step`, etc.). `args` and `result` are unstructured (`dict | str`) +because tool schemas vary across runners. + +MCP tool calls are authoritative — both `tool_called` and `tool_completed` are +emitted from the MCP endpoint. Stdout-parsed tool events are filtered to exclude +koan MCP tools (which would otherwise duplicate). Agent-native tools (not going +through koan MCP) get a synthetic `call_id` generated at parse time. + +`thinking` events are fire-and-forget incremental deltas. No started/ended +lifecycle — the client derives "thinking stopped" from the next non-thinking +event. + +### Interaction events + +| Event | What happened | Payload fields | `agent_id` | +| ----------------------------- | ---------------------------------------- | ---------------------------------------- | ---------- | +| `questions_asked` | Agent asked the user questions | `token, questions` | set | +| `questions_answered` | User answered (or interaction cancelled) | `token, ?answers, cancelled` | set | +| `artifact_review_requested` | Agent requested artifact review | `token, path, description, content` | set | +| `artifact_reviewed` | User reviewed artifact (or cancelled) | `token, ?accepted, ?response, cancelled` | set | +| `workflow_decision_requested` | Orchestrator proposed next phases | `token, chat_turns` | set | +| `workflow_decided` | User chose next phase (or cancelled) | `token, ?decision, cancelled` | set | + +`agent_id` on resolution events is the agent whose interaction was resolved +(same as the requesting agent). Cancellation (`cancelled: true`) occurs when +the agent exits while the interaction is pending. + +### Resource events + +| Event | What happened | Payload fields | `agent_id` | +| ------------------- | ------------------------------------ | ------------------------- | ---------- | +| `artifact_created` | New file appeared in epic directory | `path, size, modified_at` | if known | +| `artifact_modified` | Existing file was modified | `path, size, modified_at` | if known | +| `artifact_removed` | File was removed from epic directory | `path` | if known | + +`agent_id` is the primary agent at scan time (approximate — scanning happens +at phase boundaries, not on individual file writes). + +`modified_at` is Unix epoch milliseconds (`int`). `build_artifact_diff()` +converts the `float` seconds from `list_artifacts()` to `int(seconds * 1000)`, +consistent with `started_at_ms` elsewhere in the codebase. + +### Optional `usage` metadata + +Token/usage fields are optional on events that naturally carry them. When +present, the fold accumulates into per-agent totals in the projection. + +```python +# Optional field on agent_step_advanced, agent_exited, tool_called, tool_completed: +class Usage(BaseModel): + input_tokens: int = 0 # tokens sent to LLM + output_tokens: int = 0 # tokens received from LLM +``` + +Currently only `output_tokens` is approximated (byte length of stdout deltas). +Per-request usage from LLM providers can be added by populating these fields +when runners report usage data. + +### Events that are removed + +| Old event | Replacement | Why | +| --------------------------- | ------------------------------------------------------------- | ----------------------------------------- | +| `subagent` (state snapshot) | `agent_spawned` + `agent_step_advanced` | Facts, not snapshots | +| `subagent-idle` | `agent_exited` | "No agent" is derived from "agent exited" | +| `agents` (full scout list) | `agent_spawned` + `agent_exited` per scout | Facts, not snapshots | +| `pipeline-end` | `workflow_completed` | Renamed | +| `token-delta` | `stream_delta` | Consistent naming | +| `token-clear` | `stream_cleared` | Consistent naming | +| `logs` | `tool_called` / `tool_completed` / `thinking` | Specific facts, not generic "log" | +| `notification` | `agent_spawn_failed` / `agent_exited` with error | Specific facts, not generic bucket | +| `artifacts` (full list) | `artifact_created` / `artifact_modified` / `artifact_removed` | Diffs, not snapshots | +| `interaction` (generic) | Typed pairs: `questions_asked`/`answered`, etc. | Specific facts per interaction type | + +## Fold Function + +The fold reduces `(Projection, VersionedEvent) → Projection`. It runs on both +backend (Python) and frontend (TypeScript). Both implementations must produce +the same derived state from the same event sequence. + +Unknown event types return the projection unchanged (with a logged warning). + +### Projection shape + +```python +class AgentProjection(BaseModel): + agent_id: str + role: str + model: str | None = None + step: int = 0 + step_name: str = "" + input_tokens: int = 0 + output_tokens: int = 0 + +class Projection(BaseModel): + # Run state + run_started: bool = False + phase: str = "" + + # Agents + primary_agent: AgentProjection | None = None + scouts: dict[str, AgentProjection] = {} # keyed by agent_id + completed_agents: list[AgentProjection] = [] # agents that have exited (preserves final token totals) + + # Activity (raw events: tool_called, tool_completed, thinking) + activity_log: list[dict] = [] + stream_buffer: str = "" # accumulated stream deltas + + # Interactions + active_interaction: dict | None = None + + # Resources + artifacts: dict[str, dict] = {} # keyed by path + notifications: list[dict] = [] # derived from error events + + # Completion + completion: dict | None = None +``` + +`done_phases` is NOT in the projection — it is a frontend-only derivation +from `phase` using the frontend's `ALL_PHASES` ordering constant. + +`notifications` is derived by the fold from specific events (`agent_spawn_failed`, +`agent_exited` with error). It is not a separate event type — these are +projections of facts, preserved in the snapshot so they survive page refresh. + +### Fold cases + +**Lifecycle:** + +- `phase_started` → set `phase`, set `run_started = True` +- `agent_spawned` → create `AgentProjection` from payload; if `is_primary`: set `primary_agent`; else: add to `scouts[agent_id]` +- `agent_spawn_failed` → append to `notifications` (derived: spawn failure notification) +- `agent_step_advanced` → find agent in `primary_agent` or `scouts[agent_id]`; update `step`, `step_name`; if `usage`: accumulate tokens +- `agent_exited` → find agent by `agent_id`: if primary, accumulate final `usage` tokens, move to `completed_agents`, set `primary_agent = None`; if scout, accumulate then remove from `scouts`; if `error`: append to `notifications` +- `workflow_completed` → set `completion` + +**Activity:** + +- `tool_called` → append raw event to `activity_log`; if `usage`: accumulate tokens on agent +- `tool_completed` → append raw event to `activity_log`; if `usage`: accumulate tokens on agent +- `thinking` → append raw event to `activity_log` +- `stream_delta` → append `delta` to `stream_buffer` +- `stream_cleared` → set `stream_buffer = ""` + +**Interactions:** + +- `questions_asked` → set `active_interaction = {interaction_type: "questions_asked", **payload}` +- `questions_answered` → clear `active_interaction` +- `artifact_review_requested` → set `active_interaction = {interaction_type: "artifact_review_requested", **payload}` +- `artifact_reviewed` → clear `active_interaction` +- `workflow_decision_requested` → set `active_interaction = {interaction_type: "workflow_decision_requested", **payload}` +- `workflow_decided` → clear `active_interaction` + +The fold stores `interaction_type` (the event type string) alongside the payload +so the frontend can discriminate which component to render (`AskWizard`, +`ArtifactReview`, or `WorkflowDecision`) without duck-typing payload fields. + +**Resources:** + +- `artifact_created` → add `{path, size, modified_at}` to `artifacts[path]` +- `artifact_modified` → update `artifacts[path]` with new `size`, `modified_at` +- `artifact_removed` → delete `artifacts[path]` + +**Unknown event type** → return projection unchanged, log warning. + +**Unknown `agent_id`** (event references an agent not in `primary_agent` or +`scouts`) → return projection unchanged, log warning. Same guarantee as unknown +event types. + +**Fold exception safety:** `fold()` wraps each event type handler in +`try/except`. Any exception returns projection unchanged and logs the exception +with full event details. The event is still appended to the log (append-only is +inviolable) but its fold effect is skipped. This ensures a single malformed +payload cannot permanently break event replay. + +## Backend Architecture + +### New module: `koan/projections.py` + +Pure event-sourcing machinery. No koan domain imports. + +```python +class VersionedEvent(BaseModel): + version: int # 1-based, monotonic + event_type: EventType # Literal union + timestamp: str # ISO8601 UTC + agent_id: str | None = None # originating agent, when known + payload: dict # event-specific (typed per event_type) + +class ProjectionStore: + """In-memory versioned event log + materialized projection.""" + + events: list[VersionedEvent] + projection: Projection + version: int # current version (0 = empty) + subscribers: list[asyncio.Queue] + + def push_event(self, event_type: EventType, payload: dict, + agent_id: str | None = None) -> VersionedEvent: + """Append event, increment version, fold, broadcast to subscribers.""" + + def get_snapshot(self) -> dict: + """Return {version, state: <projection as dict>}.""" + + def events_since(self, version: int) -> list[VersionedEvent]: + """Return events with version > given version.""" + + def subscribe(self) -> asyncio.Queue: + """Create and register a subscriber queue.""" + + def unsubscribe(self, queue: asyncio.Queue) -> None: + """Remove a subscriber queue.""" +``` + +### Event payload builders: `koan/events.py` + +Bridges koan domain types into typed event payloads. Separate from +`projections.py` to keep the projection engine pure. + +```python +# koan/events.py -- bridges koan domain types into projection event payloads. +# Imports AgentState, list_artifacts, etc. projections.py does not. + +def build_agent_spawned(agent: AgentState) -> dict +def build_agent_exited(agent_id: str, exit_code: int, error: str | None = None) -> dict +def build_agent_spawn_failed(role: str, diagnostic: RunnerDiagnostic) -> dict +def build_tool_called(call_id: str, tool: str, args: dict | str, summary: str) -> dict +def build_tool_completed(call_id: str, tool: str, result: str | None = None) -> dict +def build_artifact_diff(old: dict[str, dict], new: dict[str, dict]) -> list[tuple[EventType, dict]] +# etc. +``` + +`build_artifact_diff` compares old and new artifact sets, returns a list of +`(event_type, payload)` tuples — one per created/modified/removed file. + +Callers import from both modules: + +```python +from .projections import ProjectionStore +from .events import build_agent_spawned + +store.push_event("agent_spawned", build_agent_spawned(agent), agent_id=agent.agent_id) +``` + +Centralizing helpers in one module ensures payload shapes stay consistent +across call sites (`driver.py`, `subagent.py`, `web/mcp_endpoint.py`). + +### Changes to existing modules + +**`koan/state.py`:** Remove `last_sse_values` and `sse_clients` from `AppState`. +Add `projection_store: ProjectionStore` field. + +**`koan/driver.py`:** Delete `push_sse()` function. All callers switch to +`app_state.projection_store.push_event(...)` with helper-built payloads. +Delete `_build_subagent_json`, `_build_agents_json`, `_build_artifacts_json`. +Delete `STATEFUL_EVENTS` set. The `app_state.phase = phase` mutation currently +inside `push_sse()` moves to `driver_main()` — set `app_state.phase` before +calling `push_event("phase_started", ...)`. This keeps the mutation in the +driver's sequential flow, not inside projection machinery. + +**`koan/runners/*.py`:** Each runner's `parse_stream_event()` normalizes tool +names to canonical forms (`Read` → `read`, `Bash` → `bash`, etc.). Unknown +tools pass through as-is. This is a per-runner responsibility — no central +alias table. Runners also filter out koan MCP tool names from stdout events +to prevent duplicates. + +**`koan/subagent.py`:** All `_push_sse()` calls become `push_event()` calls +with specific event types and complete payloads. The lazy import pattern stays +to avoid circular deps. Stdout tool processing changes: generate synthetic +`call_id` per tool call, emit paired `tool_called`/`tool_completed` events. +Add `stream_cleared` emission at end of stdout streaming loop (before +`agent_exited`). Notification `_push_sse` calls become `agent_spawn_failed` +or enriched `agent_exited` events. + +**`koan/web/mcp_endpoint.py`:** `_log_tool_call()` becomes the authoritative +tool event emitter. Emits `tool_called` on entry with a generated `call_id`, +and `tool_completed` on return. Each MCP tool handler wraps its logic with +paired tool events. + +**`koan/web/interactions.py`:** `_push_sse("interaction", ...)` calls become +typed pair events: `questions_asked` / `questions_answered`, +`artifact_review_requested` / `artifact_reviewed`, +`workflow_decision_requested` / `workflow_decided`. Cancellation sets +`cancelled: true` on the resolution event. + +**`koan/web/app.py`:** `sse_stream()` rewritten to read `?since=N`, send +snapshot or replay events, then live-tail from a subscriber queue. If +`since > current_version` (stale client after server restart), send a +`fatal_error` SSE event (see decision). Note: `since == current_version` is +valid — it means the client has all events and should live-tail. The `_sse_event()` helper remains for +SSE wire formatting. + +**`koan/driver.py` story events (8 call sites):** The `push_sse(app_state, +"story", {...})` calls in `run_story_execution` and `run_story_reexecution` +are removed. The execution phase story loop is partially stubbed and the +story UI is a known gap. Story projection events will be designed when the +execution UI is built. + +### SSE wire protocol + +**Snapshot event** (sent when `since=0`): + +``` +event: snapshot +data: {"version": 42, "state": { ...projection as dict... }} +``` + +**Versioned event** (sent during replay or live stream): + +``` +event: <event_type> +data: {"version": 43, "agent_id": "abc-123", ...payload fields...} +``` + +The SSE event name IS the event type (`agent_spawned`, `stream_delta`, etc.). +The version and agent_id are included in every data payload. + +## Frontend Architecture + +### Store changes + +Add to Zustand store: + +```typescript +lastVersion: number; // tracks the latest applied event version +``` + +Add actions: + +```typescript +applySnapshot: (data: SnapshotPayload) => void // atomic state replacement +applyEvent: (event: VersionedEvent) => void // incremental fold +``` + +### SSE bridge changes (`sse/connect.ts`) + +The `connectSSE` function changes from per-event-type listeners to a unified +protocol: + +1. Connect with `new EventSource('/events?since=${store.lastVersion}')` +2. Listen for `snapshot` event → call `store.applySnapshot(data)` (atomic replace) +3. Listen for all other events → call `store.applyEvent(event)` (incremental fold) +4. On disconnect: `lastVersion` is already tracked in store; reconnect uses it + +The frontend fold function mirrors the backend fold. Both produce the same +projection shape from the same event sequence. + +### Reconnect flow + +``` +Browser loads → connect ?since=0 → receive snapshot → render full state +Browser refreshes → connect ?since=0 → receive snapshot → render full state +Connection drops → reconnect ?since=142 → receive events 143..150 → fold each → up to date +``` + +## Documentation Updates + +### `docs/architecture.md` + +Update these sections: + +- **SSE Event Lifecycle**: replace the current push_sse / last_sse_values / + replay description with the event-sourced projection model +- **Event-Sourced Audit**: add a section distinguishing the two fold systems + (audit fold for per-subagent state, projection fold for frontend state) +- **Replay on reconnect**: replace "buffers the last value of every stateful + SSE event type" with version-negotiated catch-up description +- References to "pipeline" → "workflow" + +### `docs/frontend.md` + +Update these sections: + +- **State Model**: document `lastVersion`, `applySnapshot`, `applyEvent` +- **SSE Bridge**: document the `?since=N` protocol, snapshot vs event replay +- **Backend Contract**: document the event types table (replacing current + `push_sse` / builder function documentation) +- Replace all `pipeline-end` references with `workflow_completed` +- Remove references to `subagent-idle`, `last_sse_values`, `STATEFUL_EVENTS` + +### `docs/token-streaming.md` + +Update: + +- **SSE Path**: rename `token-delta` → `stream_delta`, document that it goes + through the versioned event log (not bypassing it as the current doc states) +- **Replay on reconnect**: document that the snapshot includes + `stream_buffer` (the accumulated text), so reconnecting clients get the full + streaming state without replaying individual deltas + +### New doc: `docs/projections.md` + +Spoke document covering: + +- The event model (full event type table with fields) +- The fold function (all cases) +- The projection shape +- The `ProjectionStore` class API +- The SSE protocol (`?since=N`, snapshot, event replay) +- The relationship to the audit fold (two separate fold systems, different purposes) +- Decision record: why no external library, why events are facts not snapshots, + why all events are versioned + +### `docs/artifact-review.md` + +- Rewrite "Web UI Component" section: remove Jinja2/HTMX references (frontend + is React). Component is `ArtifactReview.tsx`. +- SSE Events table: `artifact-review` → `artifact_review_requested`; + `artifact-review-cancelled` removed (cancellation is now `artifact_reviewed` + with `cancelled: true`). +- "pipeline advancement" → "workflow advancement". + +### `docs/ipc.md` + +- Ask Flow: "pushes SSE 'ask' event" → `questions_asked` +- Artifact Review Flow: "pushes SSE 'artifact-review' event" → `artifact_review_requested` +- PendingInteraction type values (`"ask"`, `"artifact-review"`) are internal + identifiers, not SSE event names — leave as-is. + +### `AGENTS.md` + +Update the pipeline phases list to use "workflow" terminology. + +## Implementation Order + +### Phase 1: Backend projection infrastructure + +1. Create `koan/projections.py` with `VersionedEvent`, `Projection`, + `ProjectionStore`, and the `fold()` function. `push_event()` must snapshot + `self.subscribers` before iterating (`for q in list(self.subscribers)`) + to avoid `RuntimeError` if a subscriber is added/removed during broadcast. +2. Add `projection_store` to `AppState`. Remove `last_sse_values` and + `sse_clients` AND rewrite `sse_stream()` in the same commit (steps 2+3 + are atomic — intermediate state where `sse_clients` is removed but + `sse_stream` still references it will crash). + +### Phase 2: Runner tool normalization + +3. Add tool name normalization to each runner's `parse_stream_event()`: + canonical names (`read`, `bash`, `edit`, `grep`, etc.). Add a + `KOAN_MCP_TOOLS: frozenset[str]` constant in `koan/web/mcp_endpoint.py` + (where the tools are registered). Runners import it for stdout filtering — + any stdout tool event whose name is in `KOAN_MCP_TOOLS` is dropped. + +### Phase 3: Event model migration + +4. Create `koan/events.py` with Pydantic payload models and builder helpers, + including `build_artifact_diff()` for diffing artifact scans +5. Move `app_state.phase = phase` from `push_sse()` into `driver_main()` + before the `push_event("phase_started", ...)` call +6. Migrate all `push_sse()` call sites in `driver.py` to `push_event()` with + proper event types (remove the 8 `story` call sites — deferred). Replace + bulk `artifacts` pushes with `build_artifact_diff()` + individual events. +7. Migrate all `_push_sse()` call sites in `subagent.py`. Generate synthetic + `call_id` for stdout tool events, emit paired `tool_called`/`tool_completed`. + Handle `turn_complete` in the stdout `else` branch: drop it (emit nothing). + `stream_cleared` at stdout EOF already signals end-of-stream. + Add `stream_cleared` emission. Convert notification pushes to + `agent_spawn_failed` or enriched `agent_exited`. + Cancellation resolution events are only emitted for the ACTIVE interaction. + Queued-but-not-active interactions are cancelled silently (future resolved + with error result, no projection event emitted). +8. Migrate `web/interactions.py` to typed pair events (`questions_asked`/ + `questions_answered`, `artifact_review_requested`/`artifact_reviewed`, + `workflow_decision_requested`/`workflow_decided`). Cancellation sets + `cancelled: true` on resolution event. +9. Migrate `web/mcp_endpoint.py`: replace `_log_tool_call()` with two + functions: `begin_tool_call(agent, tool, args, summary) -> str` (returns + `call_id`, emits `tool_called`) and `end_tool_call(agent, call_id, result)` + (emits `tool_completed`). Blocking tools (`koan_ask_question`, + `koan_review_artifact`, `koan_propose_workflow`, `koan_request_scouts`) + call `begin_tool_call` before the `await` and `end_tool_call` in a + `try/finally` after. `call_id` is a local variable in each handler. +10. Delete `push_sse()`, `_build_subagent_json`, `_build_agents_json`, + `_build_artifacts_json`, `STATEFUL_EVENTS` from `driver.py` + +### Phase 4: Frontend adaptation + +11. Add `lastVersion` and `applySnapshot`/`applyEvent` to the Zustand store. + Remove `done_phases` from store — derive it in a selector from `phase`. + Change `artifacts` from list to dict keyed by path. +12. Implement the frontend fold function (TypeScript mirror of backend fold), + including all typed interaction pairs and artifact diff events +13. Rewrite `connectSSE()` to handle `snapshot` + typed events with version + tracking. Derive notification severity via `SEVERITY_MAP` on event types. +14. Update `App.tsx` reconnect logic to pass `?since=N` + +### Phase 5: Rename pipeline → workflow + +15. Rename `pipeline-end` → `workflow_completed` in all backend code +16. Update frontend references +17. Update all docs + +### Phase 6: Documentation ✓ + +18. Write `docs/projections.md` ✓ +19. Update `docs/architecture.md`, `docs/frontend.md`, `docs/token-streaming.md`, + `docs/ipc.md`, `docs/artifact-review.md`, `docs/state.md`, + `docs/subagents.md`, `docs/intake-loop.md` ✓ +20. Update `AGENTS.md` ✓ + +### Phase 7: Tests + +21. Unit tests for `ProjectionStore` and `fold()` +22. Unit tests for `build_artifact_diff()` (correct diff detection) +23. Update existing SSE tests in `test_web_flows.py` +24. Update interaction tests that mock `_push_sse` +25. Test `?since=N` replay and snapshot paths +26. Test `?since=N` where N exceeds server version → error response +27. Test tool name normalization per runner + +### Phase 8: Graceful shutdown + +28. After `workflow_completed` event, schedule server shutdown diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md new file mode 100644 index 0000000..e9b30e3 --- /dev/null +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -0,0 +1,357 @@ +# Symmetric Projection Folds + +**Date:** 2026-03-31 +**Status:** Draft +**Goal:** Make backend and frontend projection folds produce identical materialized state, eliminating the need for ad-hoc re-interpretation during snapshot recovery. + +--- + +## Problem Statement + +The backend `fold()` in `koan/projections.py` and the frontend `applyEvent()` in `frontend/src/store/index.ts` are supposed to be symmetric — they process the same events and produce the same materialized state. The client connects, receives a **snapshot** (materialized state at version N), then applies live events via its own fold. + +**The current reality:** + +The `activity_log` field in the backend `Projection` is **not** materialized. The backend fold just appends raw event dicts: + +```python +case "tool_called": + entry = {"event_type": event_type, "agent_id": agent_id, **payload} + return projection.model_copy(update={ + "activity_log": [*projection.activity_log, entry], + }) +``` + +This makes `activity_log` a **second copy of the raw event log** — not a materialized view. The frontend's `applySnapshot()` then has to re-fold this raw log into rich `ActivityEntry[]` structures (merge consecutive thinking deltas, filter to primary agent, map typed tools, compute in-flight status). This re-folding logic is separate from and inconsistent with the live `applyEvent()` fold, causing bugs: + +- Fragmented thinking cards (each delta becomes its own card instead of being merged) +- Scout events leaking into the primary agent's activity feed (no agent filtering) +- Different entry shapes between live and recovered state + +Meanwhile, the frontend's live `applyEvent()` does produce the correct rich view — but this logic is duplicated nowhere. + +--- + +## Event Types (33 total) + +### Lifecycle (7) + +| Event | Payload | Description | +|-------|---------|-------------| +| `phase_started` | `{phase: str}` | New workflow phase begins | +| `agent_spawned` | `{agent_id, role, label, model, is_primary, started_at_ms}` | Agent process launched | +| `agent_spawn_failed` | `{role, error_code, message, details?}` | Agent failed to spawn | +| `agent_step_advanced` | `{step, step_name, usage?, total_steps?}` | Agent progressed to next step | +| `agent_exited` | `{exit_code, error?, usage?}` | Agent process terminated | +| `workflow_completed` | `{success, summary?, error?}` | Entire workflow finished | +| `scout_queued` | `{scout_id, label, model?}` | Scout waiting for concurrency slot | + +### Activity (13) + +| Event | Payload | Description | +|-------|---------|-------------| +| `tool_called` | `{call_id, tool, args, summary}` | Generic/unrecognized tool invocation | +| `tool_read` | `{call_id, tool:"read", file, lines}` | File read | +| `tool_write` | `{call_id, tool:"write", file}` | File write | +| `tool_edit` | `{call_id, tool:"edit", file}` | File edit | +| `tool_bash` | `{call_id, tool:"bash", command}` | Shell command | +| `tool_grep` | `{call_id, tool:"grep", pattern}` | Pattern search | +| `tool_ls` | `{call_id, tool:"ls", path}` | Directory listing | +| `tool_completed` | `{call_id, tool, result?}` | Tool invocation finished | +| `thinking` | `{delta: str}` | Incremental thinking token chunk | +| `stream_delta` | `{delta: str}` | Incremental text output chunk | +| `stream_cleared` | `{}` | Agent's stream ended (process EOF) | + +All activity events carry `agent_id` identifying which agent produced them. + +### Interactions (6) + +| Event | Payload | Description | +|-------|---------|-------------| +| `questions_asked` | `{token, questions: [...]}` | User prompted with questions | +| `questions_answered` | `{token, cancelled, answers?}` | User responded | +| `artifact_review_requested` | `{token, path, description, content}` | Artifact review needed | +| `artifact_reviewed` | `{token, cancelled, accepted?, response?}` | Review completed | +| `workflow_decision_requested` | `{token, chat_turns}` | Phase selection needed | +| `workflow_decided` | `{token, cancelled, decision?}` | Decision made | + +### Resources (3) + +| Event | Payload | Description | +|-------|---------|-------------| +| `artifact_created` | `{path, size, modified_at}` | New file produced | +| `artifact_modified` | `{path, size, modified_at}` | File updated | +| `artifact_removed` | `{path}` | File deleted | + +### Configuration (7) + +| Event | Payload | Description | +|-------|---------|-------------| +| `probe_completed` | `{runners: [...]}` | Binary detection finished | +| `installation_created` | `{alias, runner_type, binary, extra_args}` | New agent installation | +| `installation_modified` | `{alias, runner_type, binary, extra_args}` | Installation updated | +| `installation_removed` | `{alias}` | Installation deleted | +| `profile_created` | `{name, read_only, tiers}` | New profile | +| `profile_modified` | `{name, read_only, tiers}` | Profile updated | +| `profile_removed` | `{name}` | Profile deleted | +| `active_profile_changed` | `{name}` | Active profile switched | +| `scout_concurrency_changed` | `{value}` | Concurrency limit changed | + +--- + +## SSE Protocol + +``` +Client connects: GET /events?since=0 +Server sends: event: snapshot\ndata: {"version": N, "state": <Projection>}\n\n +Server sends: event: <type>\ndata: {"version": N+1, ...payload}\n\n (live) + event: <type>\ndata: {"version": N+2, ...payload}\n\n (live) + ... + +Client reconnects: GET /events?since=N+2 +Server sends: event: <type>\ndata: {"version": N+3, ...}\n\n (catch-up) + event: <type>\ndata: {"version": N+4, ...}\n\n (live) + ... +``` + +- `since=0`: snapshot + live events +- `since=N` (N > 0): catch-up replay of events with version > N, then live +- `since=N` where N > server version: `fatal_error` event, client reloads + +The snapshot is the **materialized projection state** — the client reads it directly into its store, then applies subsequent events via its local fold. + +--- + +## Target Projection Shape + +The projection is the single source of truth. Backend `fold()` produces it, `get_snapshot()` serializes it, frontend `applySnapshot()` reads it, frontend `applyEvent()` updates it identically. + +### Primary agent conversation + +The key insight: `activity_log` should be a **materialized conversation** — not a raw event log. The backend fold must produce the same structure the frontend renders. + +```python +class ConversationEntry(BaseModel): + """A single entry in an agent's conversation timeline.""" + type: Literal["thinking", "text", "tool", "step"] + + # -- thinking -- + content: str | None = None # accumulated thinking text + + # -- text -- + text: str | None = None # accumulated stream text + + # -- tool -- + tool_type: str | None = None # "read", "bash", "write", "edit", "grep", "ls", "other" + tool_name: str | None = None # display name (tool_type or original name for "other") + call_id: str | None = None + in_flight: bool = False + # tool metadata (typed) + file: str | None = None # read, write, edit + lines: str | None = None # read (e.g. "10-20") + command: str | None = None # bash + pattern: str | None = None # grep + path: str | None = None # ls + summary: str | None = None # generic tool_called fallback + + # -- step -- + step: int | None = None + step_name: str | None = None + total_steps: int | None = None +``` + +### Fold rules for conversation entries + +The backend fold maintains a `conversation: list[ConversationEntry]` plus two transient buffers (`thinking_buffer: str`, `stream_buffer: str`). The buffers accumulate incremental deltas; they get flushed to conversation entries on transitions: + +| Event | Action | +|-------|--------| +| `thinking` (primary agent only) | If `stream_buffer` non-empty → flush to `text` entry, clear. Append delta to `thinking_buffer`. | +| `stream_delta` (primary agent only) | If `thinking_buffer` non-empty → flush to `thinking` entry, clear. Append delta to `stream_buffer`. | +| `tool_*` / `tool_called` (primary agent only) | Flush both buffers. Append typed tool entry with `in_flight=True`. Skip koan MCP tools (`koan_*`, `mcp__koan*`). | +| `tool_completed` (primary agent only) | Set `in_flight=False` on entry matching `call_id`. | +| `agent_step_advanced` (primary agent only) | Flush both buffers. Append `step` entry (skip step < 1). | +| `stream_cleared` (primary agent only) | Flush both buffers. | +| Any activity event for non-primary agent | Update scout's `last_tool` (see agents section). Do NOT touch conversation. | + +### Full projection model + +```python +class Projection(BaseModel): + # -- Run state -- + run_started: bool = False + phase: str = "" + + # -- Agents -- + primary_agent: AgentProjection | None = None + scouts: dict[str, AgentProjection] = {} # keyed by agent_id + queued_scouts: list[QueuedScout] = [] + completed_agents: list[AgentProjection] = [] + + # -- Primary agent conversation (materialized) -- + conversation: list[ConversationEntry] = [] + thinking_buffer: str = "" # transient accumulator + stream_buffer: str = "" # transient accumulator + + # -- Interactions -- + active_interaction: InteractionState | None = None + + # -- Artifacts -- + artifacts: dict[str, ArtifactInfo] = {} # keyed by path + + # -- Notifications -- + notifications: list[NotificationEntry] = [] + + # -- Workflow completion -- + completion: CompletionInfo | None = None + + # -- Configuration -- + config_runners: list[RunnerInfo] = [] + config_profiles: list[ProfileInfo] = [] + config_installations: list[InstallationInfo] = [] + config_active_profile: str = "balanced" + config_scout_concurrency: int = 8 +``` + +### Agent model + +```python +class AgentProjection(BaseModel): + agent_id: str + role: str + label: str = "" # scout identifier (e.g. "engine-methods") + model: str | None = None + step: int = 0 + step_name: str = "" + started_at_ms: int = 0 + input_tokens: int = 0 + output_tokens: int = 0 + status: Literal["running", "done", "failed"] = "running" + error: str | None = None + last_tool: str = "" # most recent tool summary for scouts +``` + +Note: `status` and `last_tool` are added to the backend model. Currently `status` only exists on the frontend (`AgentInfo`). The backend `AgentProjection` should carry these so the snapshot is complete. + +### What changes + +| Field | Current | Target | +|-------|---------|--------| +| `activity_log: list[dict]` | Raw event dicts, no merging, no filtering | **Removed.** Replaced by `conversation: list[ConversationEntry]` | +| `stream_buffer: str` | Exists | Stays, but fold logic moves here from frontend | +| (new) `thinking_buffer: str` | Frontend-only | Moves to projection — backend fold accumulates | +| (new) `conversation` | Frontend-only (`activityLog`) | Backend fold produces the identical structure | +| `AgentProjection.status` | Frontend-only | Backend fold sets on `agent_exited` | +| `AgentProjection.last_tool` | Frontend-only | Backend fold updates on tool events for scouts | +| `AgentProjection.label` | Already in backend | Already in backend ✓ | + +--- + +## Frontend `applySnapshot` (after) + +With a properly materialized projection, `applySnapshot` becomes a direct mapping: + +```typescript +applySnapshot: (data) => { + const state = data.state + set({ + lastVersion: data.version, + phase: state.phase, + runStarted: state.run_started, + primaryAgent: state.primary_agent ? transformAgent(state.primary_agent) : null, + scouts: transformScouts(state.scouts), + queuedScouts: state.queued_scouts, + completedAgents: state.completed_agents.map(transformAgent), + + // Direct read — no re-folding needed + activityLog: state.conversation, // already the right shape + thinkingBuffer: state.thinking_buffer, + streamBuffer: state.stream_buffer, + isThinking: state.thinking_buffer.length > 0, + + activeInteraction: state.active_interaction, + artifacts: state.artifacts, + notifications: state.notifications, + completion: state.completion, + configProfiles: state.config_profiles, + configInstallations: state.config_installations, + configActiveProfile: state.config_active_profile, + configScoutConcurrency: state.config_scout_concurrency, + configRunners: state.config_runners, + }) +} +``` + +No `completedCallIds` set, no `flatMap`, no thinking merging, no agent filtering, no raw-event re-interpretation. The snapshot IS the view. + +--- + +## Frontend `applyEvent` (after) + +The live fold stays the same conceptually — it's already correct. But it must produce `ConversationEntry`-shaped objects that match what the backend fold produces. The `flushThinkingBuffer()` / `flushStreamBuffer()` / `flushBuffers()` helpers stay, but the entries they produce must match `ConversationEntry`: + +```typescript +// Flush thinking buffer → ConversationEntry of type "thinking" +{ type: "thinking", content: thinkingBuffer } + +// Flush stream buffer → ConversationEntry of type "text" +{ type: "text", text: streamBuffer } + +// Tool event → ConversationEntry of type "tool" +{ type: "tool", tool_type: "read", call_id: "...", in_flight: true, file: "/path" } +``` + +The field names and shapes must match exactly between Python's `ConversationEntry.model_dump()` and TypeScript's entry objects. + +--- + +## Implementation Plan + +### Phase 1: Backend fold produces materialized conversation + +1. Define `ConversationEntry` as a Pydantic model in `koan/projections.py` +2. Add `conversation: list[ConversationEntry]`, `thinking_buffer: str`, rename/remove `activity_log` +3. Add `status`, `error`, `last_tool`, `label` to `AgentProjection` +4. Rewrite fold cases for all activity events to produce `ConversationEntry` items: + - `thinking`: accumulate into `thinking_buffer` (primary only) + - `stream_delta`: accumulate into `stream_buffer` (primary only) + - `tool_*` / `tool_called`: flush buffers → entries, append tool entry (primary); update `last_tool` (scout) + - `tool_completed`: set `in_flight=False` by `call_id` + - `agent_step_advanced`: flush buffers → entries, append step entry (primary); update step/tokens (any agent) + - `stream_cleared`: flush buffers + - `agent_exited`: set `status`, `error` on the agent before moving to completed +5. Update `get_snapshot()` — `model_dump()` now includes `conversation` instead of `activity_log` + +### Phase 2: Frontend reads materialized snapshot + +1. Define `ConversationEntry` TypeScript type matching the Python model exactly +2. Rewrite `applySnapshot` to directly read `conversation`, `thinking_buffer`, `stream_buffer` — remove all re-folding logic +3. `applyEvent` produces `ConversationEntry`-shaped objects (rename fields to match) +4. `ActivityFeed` renders `ConversationEntry[]` — field names may need updating + +### Phase 3: Tests + +1. Update backend projection fold tests — assert `conversation` entries, not raw `activity_log` dicts +2. Add specific tests for thinking merging, scout filtering, in-flight tracking in the fold +3. Verify snapshot→frontend round-trip: fold N events, take snapshot, feed to `applySnapshot`, compare with live `applyEvent` applied to same events + +### Phase 4: Cleanup + +1. Remove `activity_log` from `Projection` +2. Remove dead `applySnapshot` re-folding code from frontend +3. Remove `ActivityEntry` type — replaced by `ConversationEntry` +4. Verify all views render correctly from snapshot recovery + +--- + +## Risks & Decisions + +- **Thinking buffer in projection**: The `thinking_buffer` is transient state that only matters for the "live tail". After snapshot recovery, it's either empty (agent isn't thinking) or has partial content (agent is mid-thought). This is correct — the snapshot captures the current state. + +- **Koan MCP tool filtering in fold**: Currently filtered in the frontend's `applyEvent`. Must move to the backend fold — `tool_called` events with `koan_*` tool names should not produce conversation entries. The MCP endpoint's `begin_tool_call`/`end_tool_call` still emit these events for the raw event log, but the fold skips them. + +- **Primary agent identification**: The fold needs to know which `agent_id` is the primary agent to decide whether to add to conversation or update scout lastTool. The projection already has `primary_agent.agent_id`. + +- **ConversationEntry field naming**: Must be identical between Python `model_dump()` and TypeScript. Use snake_case everywhere (Pydantic default). Frontend accesses `entry.call_id`, `entry.in_flight`, `entry.tool_type`, etc. + +- **Scout `last_tool` as a string**: The fold formats a human-readable string like `"read /path/to/file"` or `"bash ls -la"`. This is a display concern in the fold, but it's simple and avoids the frontend needing to re-derive it. diff --git a/plans/intake-dashboard-ux.md b/plans/intake-dashboard-ux.md new file mode 100644 index 0000000..b811ecc --- /dev/null +++ b/plans/intake-dashboard-ux.md @@ -0,0 +1,666 @@ +# Intake Dashboard UX Flow — Complete Design + +> **Scope:** Browser-based UX for the intake phase only (context analysis → scout exploration → elicitation → consolidation). +> **Data sources:** Projection (`state.json`), event log (`events.jsonl`), IPC files (`ipc.json`), scout subagent directories. + +--- + +## State Machine Overview + +The browser moves through 6 states during intake. Each state has a distinct visual identity but shares a persistent layout frame. + +``` +┌──────────┐ SSE connect ┌───────────────┐ step_transition(1) ┌──────────────────┐ +│ Loading │ ──────────────────→│ Context │ ────────────────────→ │ Scout │ +│ (shell) │ │ Analysis │ │ Exploration │ +└──────────┘ └───────────────┘ └──────────────────┘ + │ + step_transition(3) + + ipc ask request + │ +┌──────────────┐ all questions ┌───────────────┐ ask SSE event ┌──────────────────┐ +│Consolidation │←─── answered ────│ Elicitation │←─────────────────│ Scout → Elicit │ +│ │ │ (questions) │ │ (transition) │ +└──────────────┘ └───────────────┘ └──────────────────┘ +``` + +The transition from Scout Exploration to Elicitation is actually seamless — step 3 starts (Gap Analysis & Questions), the intake model reads scout findings, and then asks questions. The browser detects the `ask` SSE event as the moment to shift from progress-watching to interactive mode. + +--- + +## Persistent Layout Frame + +Every state renders inside the same page structure. This prevents disorienting full-page transitions. + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ HEADER BAR │ +│ [koan] Intake · Context Analysis 0m 42s │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ MAIN CONTENT AREA │ +│ (changes per state — details below) │ +│ │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ STATUS RAIL │ +│ (always visible — agent activity, file operations, events) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Header Bar (always visible) + +Left side: `koan` wordmark + phase label + step name. +Right side: elapsed timer (computed client-side from `startedAt`). + +The phase label uses the 4 user-facing names (Context Analysis, Scout Exploration, Elicitation, Consolidation), not the backend's 3-step names. Mapping: + +| Backend step | Backend stepName | Dashboard label | +| ---------------- | ------------------------ | ------------------------------- | +| 1 | Context Extraction | Context Analysis | +| 2 | Codebase Scouting | Scout Exploration | +| 3 (before ask) | Gap Analysis & Questions | Scout Exploration → Elicitation | +| 3 (during ask) | Gap Analysis & Questions | Elicitation | +| 3 (after answer) | Gap Analysis & Questions | Consolidation | + +The browser determines the sub-phase within step 3 by tracking SSE events: when `ask` arrives → "Elicitation", when answer is submitted → "Consolidation". + +### Status Rail (always visible) + +A compact bottom panel showing the active agent(s) and recent tool activity. Answers Challenge 4: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ● intake · claude-opus-4 step 2/3 · Codebase Scouting │ +│ read src/planner/driver.ts (142L, 6.2k) · 3s ago │ +│ grep "SSE" src/ · 1s ago │ +│ bash find . -name "*.ts" (28L, 1.1k) · <1s ago │ +└─────────────────────────────────────────────────────────────────┘ +``` + +Fields: + +- **Agent indicator**: `●` colored dot (green=running, gray=idle) + role + model name + step progress +- **Recent tool calls**: last 3-4 tool invocations from the `logs` SSE event, with relative timestamps +- **No token/cost data** — Projection has `eventCount` but not tokens. Instead: show `events: 47` as a proxy for activity intensity. The event count is meaningful — it roughly correlates with API calls and tells the user "something is happening" even when tool calls are quiet (heartbeats still increment it). + +When scouts are running, the rail expands to show scout-level detail (see Challenge 2 below). + +--- + +## State 1: Loading Shell + +### What the user sees + +The page loads instantly (served from memory, no external assets). The layout frame renders with: + +- Header: `koan · Intake` (no step name yet, no timer) +- Main area: centered content — the project name (derived from cwd) and a subtle pulsing indicator +- Status rail: `Connecting...` in muted text + +The loading state shows the **conversation topic** if the server can extract it before the first SSE event. Since `conversation.jsonl` is written before the pipeline starts, the server could parse the last user message and include it in the HTML payload or first SSE event. This grounds the user: "Yes, this is about the thing I just asked about." + +``` + ┌──────────────────────────┐ + │ │ + │ koan │ + │ │ + │ ○ Initializing... │ + │ │ + │ "Design the intake │ + │ dashboard UX flow" │ + │ │ + └──────────────────────────┘ +``` + +If no topic is available, the fallback is just the pulsing indicator without the quote. + +### Data available from SSE + +None yet — SSE connection is being established. The HTML page may inline the session token and a `topic` string if the server extracts one during page generation. + +### Interactions + +None. The page is passive. + +### Duration + +1-5 seconds. The gap has two components: + +1. SSE connection establishment (~100ms, instant for localhost) +2. Subagent boot time — pi spawns the intake process, loads the extension, model begins responding (~2-8 seconds) + +The first SSE event is the state replay (§6.3 of the web UI plan): `phase` event with `"intake"`, then `subagent` event once tracking begins. The `phase` event arrives immediately on SSE connect (server replays buffered state). The `subagent` event arrives when the first polling tick reads a valid `state.json` from the intake subagent directory. + +### Transition trigger + +First `subagent` SSE event with a non-empty `stepName` → transition to State 2. + +Actually, more precisely: the `phase` SSE event arrives first (immediately on connect), which changes the header. Then the `subagent` event arrives 2-4 seconds later with step/progress data, which populates the main content area and status rail. The loading indicator can fade out as soon as the `subagent` event arrives. + +--- + +## State 2: Context Analysis + +### What the user sees + +The main content area shows a minimal progress view. There's not much to show here — one model is reading the conversation file and extracting structure. The visual emphasis is on calm reassurance that work is happening. + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ koan Intake · Context Analysis 0m 12s │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ ① Context Analysis ② Exploration │ │ +│ │ ━━━━━━━━━━━━━━━━━━ ─ ─ ─ ─ ─ ─ │ │ +│ │ ③ Questions ④ Consolidation │ │ +│ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ Reading your conversation to understand the task... │ +│ │ +│ ┌ Activity ─────────────────────────────────────┐ │ +│ │ read conversation.jsonl (847L, 34.2k) │ │ +│ │ ... │ │ +│ └────────────────────────────────────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ ● intake · opus-4 step 1/3 · Context Extraction events: 4 │ +│ read conversation.jsonl (847L, 34.2k) · <1s ago │ +└─────────────────────────────────────────────────────────────────┘ +``` + +The **four-phase progress strip** at the top is a horizontal stepper showing all 4 intake phases. Only phase 1 is active (solid bar). Others are dashed/dimmed. This gives the user the full picture of what's coming — answering "how far along are we?" at a glance. + +Below the progress strip: a one-line status message ("Reading your conversation...") and a small activity feed showing recent file operations. + +### Data available from SSE + +```typescript +// subagent event (every 2 seconds): +{ role: "intake", step: 1, totalSteps: 3, stepName: "Step 1/3: Context Extraction", startedAt: 1710504000000 } + +// logs event (every 2 seconds): +{ lines: [ + { tool: "read", summary: "conversation.jsonl · 847L/34.2k", highValue: true }, + { tool: "write", summary: "context.md", highValue: true } +]} +``` + +### Interactions + +None. This is a watch-only phase. + +### Duration + +15-45 seconds. The model reads `conversation.jsonl` (can be large) and writes `context.md`. + +### Transition trigger + +`subagent` SSE event with `step: 2` and `stepName` containing "Scouting" or "Codebase Scouting". + +--- + +## State 3: Scout Exploration + +This is the visually richest state — multiple parallel agents exploring different parts of the codebase. + +### Challenge 2 Resolution: Scout Progress Visualization + +**How scouts become visible to the browser:** + +The current architecture tracks one subagent at a time via `trackSubagent(dir, role)`. During intake step 2, the intake subagent calls `koan_request_scouts`, which triggers the IPC responder to spawn 1-5 scout subagents via `pool()`. Each scout gets its own directory under `epicDir/subagents/scout-{id}-{timestamp}/`. + +For the web UI, the web server needs a new SSE event type — `scouts` — that carries parallel scout progress. The IPC responder already knows about scout directories (it creates them in `handleScoutRequest`). When the IPC responder spawns scouts, it should register their directories with the web server for polling. The web server then polls each scout directory at 2-second intervals (same as main subagent polling) and pushes a `scouts` SSE event with all scouts' state. + +**New SSE event:** + +```typescript +interface ScoutsEvent { + scouts: Array<{ + id: string; // from ScoutTask.id, e.g. "auth-setup" + role: string; // from ScoutTask.role, e.g. "auth system auditor" + status: "running" | "completed" | "failed"; + lastAction: string | null; // from Projection.lastAction + eventCount: number; + // No step/totalSteps — scouts are single-step, so step progress is meaningless. + // Instead, show lastAction as the current activity indicator. + }>; +} +``` + +The scout's `role` field (from `ScoutTask.role`) is the meaningful name — "auth system auditor", "API structure analyst", "dependency graph mapper" — not "Scout A". The intake model defines these roles when calling `koan_request_scouts`, and they're specific to what each scout investigates. + +### What the user sees + +The main area transforms into a scout panel showing each scout as a compact card: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ koan Intake · Scout Exploration 1m 03s │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ ✓ Context Analysis ② Exploration │ │ +│ │ ━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━ │ │ +│ │ ③ Questions ④ Consolidation │ │ +│ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ Exploring your codebase with 4 scouts... │ +│ │ +│ ┌ auth-setup ──── auth system auditor ─────────────┐ │ +│ │ ● reading src/planner/lib/permissions.ts │ │ +│ └──────────────────────────────────────────────────┘ │ +│ ┌ api-structure ── API structure analyst ───────────┐ │ +│ │ ● grep "router" src/ (14L, 0.8k) │ │ +│ └──────────────────────────────────────────────────┘ │ +│ ┌ test-patterns ── test infrastructure auditor ────┐ │ +│ │ ✓ Complete — "Uses vitest with co-located test │ │ +│ │ files. No integration test harness found." │ │ +│ └──────────────────────────────────────────────────┘ │ +│ ┌ state-mgmt ──── state management analyst ────────┐ │ +│ │ ● bash find . -name "state.json" (12L, 0.4k) │ │ +│ └──────────────────────────────────────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ ● intake · opus-4 step 2/3 · Codebase Scouting events: 23 │ +│ ● 4 scouts: 1 done, 3 running · haiku-4 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +Each scout card shows: + +- **Header**: `id` (kebab-case, machine-readable) + `role` (human-readable description) +- **Status indicator**: `●` spinning/pulsing for running, `✓` for complete, `✗` for failed +- **Current activity** (running): last tool call from the scout's `lastAction` — "reading src/foo.ts", "grep 'pattern' src/", "bash find ..." +- **Completion summary** (done): The scout's `koan_complete_step` summary. This comes from the scout's `state.json` — when status becomes "completed", the `lastAction` or the `phase_end` event's detail field provides the one-line summary. + +Cards have a subtle visual state: + +- **Running**: left border accent color, slight background highlight +- **Complete**: left border green, muted background, summary text visible +- **Failed**: left border red, error message shown + +### Data available from SSE + +```typescript +// subagent event (intake subagent, every 2s): +{ role: "intake", step: 2, totalSteps: 3, stepName: "Step 2/3: Codebase Scouting", startedAt: ... } + +// scouts event (new, every 2s while scouts are running): +{ scouts: [ + { id: "auth-setup", role: "auth system auditor", status: "running", lastAction: "read src/planner/lib/permissions.ts", eventCount: 8 }, + { id: "api-structure", role: "API structure analyst", status: "running", lastAction: "grep \"router\" src/", eventCount: 5 }, + { id: "test-patterns", role: "test infrastructure auditor", status: "completed", lastAction: null, eventCount: 14 }, + { id: "state-mgmt", role: "state management analyst", status: "running", lastAction: "bash find", eventCount: 3 } +]} + +// logs event (intake subagent's own log, not scouts'): +{ lines: [ + { tool: "koan_request_scouts", summary: "scouts:[auth-setup, api-structure, test-patterns, state-mgmt]", highValue: true } +]} +``` + +### Interactions + +None during scout exploration. This is a watch phase. + +However: if scout exploration takes a long time (>2 minutes), the user might want to see more detail about what a specific scout is doing. Consider making scout cards expandable — clicking a card reveals the scout's full recent log (last 8 tool calls). This is progressive disclosure: the compact view shows one line per scout, the expanded view shows the scout's activity stream. + +### Duration + +30 seconds to 3 minutes. Depends on codebase size and number of scouts (1-5). Scouts run in parallel with a concurrency cap of 4. + +### Transition trigger + +Two things happen in sequence: + +1. All scouts complete (or fail) → `scouts` SSE event shows all with terminal status +2. The intake subagent transitions to step 3 → `subagent` event with `step: 3` + +Between these, there may be a brief pause (a few seconds) while the intake model reads scout findings. The UI should handle this gracefully: scouts are all done, step 3 hasn't started yet → show a brief "Analyzing scout findings..." message. + +The transition to the question state happens when the `ask` SSE event arrives (the intake model has identified gaps and formulated questions). + +--- + +## State 4: Elicitation (Question Answering) + +This is the only interactive state. The user answers 1-8 questions that the intake model has crafted based on the conversation and scout findings. + +### Challenge 3 Resolution: Question Presentation + +**Layout shift:** When the `ask` SSE event arrives, the main content area transitions from the scout cards to a question form. This should be animated — the scout cards slide/fade out, the question form slides/fades in. The scout summary persists in a collapsed section ("4 scouts completed") so the context isn't lost. + +**Question form design:** + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ koan Intake · Elicitation 2m 17s │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ ✓ Context Analysis ✓ Exploration │ │ +│ │ ━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━ │ │ +│ │ ③ Questions ④ Consolidation │ │ +│ │ ━━━━━━━━━━━━━━━━━━ ─ ─ ─ ─ ─ ─ ─ │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ ▸ 4 scouts completed [expand] │ +│ │ +│ ┌ Questions ─────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ We have a few questions to help shape the plan. │ │ +│ │ │ │ +│ │ ┌─ 1 of 3 ──── scope ──────────────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ Should the web dashboard replace the TUI widget │ │ │ +│ │ │ completely, or run alongside it? │ │ │ +│ │ │ │ │ │ +│ │ │ The codebase currently uses pi's ExtensionUIContext │ │ │ +│ │ │ for all rendering. Scout found 8 files with direct │ │ │ +│ │ │ TUI imports. │ │ │ +│ │ │ │ │ │ +│ │ │ ○ Replace completely — delete all TUI code │ │ │ +│ │ │ ◉ Replace for pipeline, keep TUI for /koan config │ │ │ +│ │ │ (Recommended) │ │ │ +│ │ │ ○ Run alongside — user picks TUI or web at runtime │ │ │ +│ │ │ ○ Other ────────────────────────────────────── │ │ │ +│ │ │ │ │ │ +│ │ └────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌─ 2 of 3 ──── auth ───────────────────────────────────┐ │ │ +│ │ │ ... │ │ │ +│ │ └────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌─ 3 of 3 ──── persistence ────────────────────────────┐ │ │ +│ │ │ ... │ │ │ +│ │ └────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────┐ │ │ +│ │ │ Accept All Defaults Submit Answers │ │ │ +│ │ └──────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ ◉ intake · opus-4 step 3/3 · Awaiting answers events: 31 │ +│ Waiting for your input... │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**Key design decisions for questions:** + +1. **All questions on one scrollable page, not tabs.** The TUI version uses tabs because terminal height is constrained. The browser has scroll. Showing all questions at once lets the user scan everything, understand the full scope, and answer in any order. With a max of 8 questions, this fits comfortably. + +2. **Question cards stacked vertically.** Each question is a card with: + - **Header**: question number + total, question `id` as a label (e.g., "scope", "auth") + - **Question text**: the actual question, in prominent text + - **Context line** (when present): why this question matters, grounded in scout findings. This isn't a separate field in the data — it's part of the question text written by the intake model. The model is already instructed to reference scout findings in questions (see intake prompts step 3). The browser just renders the full question text. + - **Options**: radio buttons (single-select) or checkboxes (multi-select) + - **Recommended badge**: "(Recommended)" text next to the recommended option, applied server-side before the SSE event is sent + - **Other option**: always last, with a text input that appears/expands when selected + +3. **"Accept All Defaults" button.** For users who trust the model's recommendations. Clicking it selects the `recommended` option for every question and submits. This is the "skip all questions" affordance. It should be visually secondary to "Submit Answers" (outlined vs filled button, or smaller text link). + +4. **"Submit Answers" button.** Primary action. Disabled until every question has at least one selection (or "Other" has text). Shows validation state: "3 of 5 answered" as helper text. + +5. **No Cancel button for questions.** The TUI version has Esc=cancel. In the web version, there's no useful cancel semantic — the pipeline is blocked waiting for answers. The user can always close the tab (which causes the pipeline to wait indefinitely per §6.5). If we add Cancel, its behavior would be: submit empty selections, the intake model continues without answers. This could be a "Skip Questions" link in small text below the form. + +### Data available from SSE + +```typescript +// ask event (one-time, when questions are ready): +{ + requestId: "abc-123-def", + questions: [ + { + id: "scope", + question: "Should the web dashboard replace the TUI widget completely, or run alongside it?\n\nThe codebase currently uses pi's ExtensionUIContext for all rendering. Scout found 8 files with direct TUI imports.", + options: [ + { label: "Replace completely — delete all TUI code" }, + { label: "Replace for pipeline, keep TUI for /koan config (Recommended)" }, + { label: "Run alongside — user picks TUI or web at runtime" } + ], + multi: false, + recommended: 1 + }, + // ... more questions + ] +} + +// subagent event continues during this time: +{ role: "intake", step: 3, totalSteps: 3, stepName: "Step 3/3: Gap Analysis & Questions", startedAt: ... } +``` + +Note: the `options` array in the SSE event already includes the "Other (type your own)" option and the "(Recommended)" tag, applied server-side by the functions relocated from `ask-logic.ts` to `web/server-types.ts`. The browser renders exactly what it receives. + +Wait — actually, per the web UI plan §5.1: "The `OTHER_OPTION` constant and `appendRecommendedTagToOptionLabels` are applied **server-side** before pushing the `ask` SSE event". So the browser sees options with tags already applied. The browser just needs to detect the "Other" option (last in list, label matches `OTHER_OPTION` constant) and render a text input for it. + +### Interactions + +- **Select an option**: click radio button / checkbox +- **Select "Other"**: click to reveal/focus a text input field +- **Add a note to any option** (optional): each option could have an expand icon that reveals a text input for additional context. This mirrors the TUI's Tab-to-add-note feature. But for the web version, this might be over-engineering. Simpler: just the "Other" option has a text input. Notes on specific options aren't needed — the user can type a note in the Other field if they want to provide custom input. +- **Accept All Defaults**: one click submits recommended answers for all questions +- **Submit Answers**: validates all questions have selections, sends `POST /api/answer` + +### Duration + +30 seconds to 5 minutes. Depends on the user. The pipeline is blocked during this time — the status rail should show "Awaiting your input" to make it clear the system is waiting on the user, not processing. + +### Transition trigger + +User clicks "Submit Answers" or "Accept All Defaults" → browser sends `POST /api/answer` with `{ token, requestId, answers }` → server resolves the pending Promise → intake model receives answers and continues. + +--- + +## State 5: Consolidation + +### What the user sees + +After the user submits answers, the main content area transitions back to a progress view. The intake model is now writing `decisions.md` — capturing the questions, answers, and remaining unknowns. + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ koan Intake · Consolidation 3m 45s │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ ✓ Context Analysis ✓ Exploration │ │ +│ │ ━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━ │ │ +│ │ ✓ Questions ④ Consolidation │ │ +│ │ ━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━ │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ Writing project specification from all gathered information... │ +│ │ +│ ┌ Summary ──────────────────────────────────────────┐ │ +│ │ Context extracted from conversation │ │ +│ │ 4 scouts explored the codebase │ │ +│ │ 3 questions answered │ │ +│ │ Writing decisions.md... │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ ● intake · opus-4 step 3/3 · Gap Analysis & Questions e: 38 │ +│ write decisions.md · <1s ago │ +└─────────────────────────────────────────────────────────────────┘ +``` + +This is a brief wrap-up phase. The user's answers have been received; the model is writing the final specification artifacts. + +### Data available from SSE + +Same `subagent` and `logs` events as before. Step is still 3/3. The browser knows we're in consolidation because it tracks that the answer was submitted. + +```typescript +// logs event: +{ + lines: [ + { tool: "write", summary: "decisions.md", highValue: true }, + { tool: "koan_complete_step", summary: "...", highValue: true }, + ]; +} +``` + +### Interactions + +None. Watch-only. + +### Duration + +5-15 seconds. The model writes `decisions.md` and calls `koan_complete_step`. + +### Transition trigger + +The intake subagent completes → `subagent-idle` SSE event (or `subagent` with status: "completed") → then a `phase` SSE event with `phase: "decomposition"`. + +At this point, intake is done. The dashboard transitions to the decomposition phase (out of scope for this document, but the phase transition animation should smoothly update the header and show a new progress view for decomposition). + +--- + +## State 6: Intake Complete (Transition) + +A brief celebration/summary state before decomposition begins. + +### What the user sees + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ koan Intake Complete 4m 02s │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ ✓ Context Analysis ✓ Exploration │ │ +│ │ ━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━ │ │ +│ │ ✓ Questions ✓ Consolidation │ │ +│ │ ━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━ │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ ✓ Intake complete │ +│ │ +│ context.md and decisions.md written. │ +│ Moving to decomposition... │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ ○ idle events: 42 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Duration + +1-3 seconds, then the decomposition phase begins and the dashboard transitions to a new view. + +--- + +## Cross-Cutting Design Decisions + +### Challenge 1: The "Empty Browser" Problem — Resolution + +**Decision:** Show the layout shell immediately with a centered loading state. Include the conversation topic if extractable. + +**Rationale:** The alternative — a blank page or a spinner — wastes the user's attention. By showing the layout frame (header, status rail, progress strip) immediately, the user orients to the page structure before data arrives. The conversation topic ("Design the intake dashboard UX flow") confirms they're looking at the right session. + +**Implementation:** The server can extract the topic from `conversation.jsonl` during `koan_plan.execute()` (before the pipeline starts, since the conversation is already exported). Pass it as a data attribute in the HTML template. The browser reads it and displays it in the loading state. + +If extraction fails or takes too long, fall back to just the loading indicator. The topic extraction is best-effort — it parses the last user message from the JSONL file (look for the last entry with `role: "user"`, take the first ~100 chars of content). + +### Challenge 2: Scout Progress Visualization — Resolution + +**Decision:** Scout cards stacked vertically in the main content area. Each card shows id, role, status indicator, and current activity (running) or one-line summary (complete). + +**New SSE event type needed:** `scouts` — carries an array of scout states. Pushed by the web server at 2-second intervals when scouts are active. The IPC responder registers scout directories with the web server when spawning scouts. + +**Backend change required:** Add `registerScoutDirs(dirs: Map<string, ScoutDir>)` and `clearScouts()` to `WebServerHandle`. The IPC responder calls `registerScoutDirs` after creating scout subagent directories, and `clearScouts` when all scouts complete. The web server polls each registered directory's `state.json` on the same 2-second interval as `trackSubagent`. + +**Completion summary:** When a scout completes, its `phase_end` event's `detail` field contains the summary from `koan_complete_step`. The web server reads this from the scout's `events.jsonl` (last `phase_end` event) and includes it in the `scouts` SSE event. The browser shows this as a one-line summary on the completed scout card. + +**Why not tabs/accordion for scouts:** With 1-5 scouts, vertical stacking is simpler and shows all scouts at once. Tabs would hide scouts behind clicks. The cards are compact enough (2 lines each) that even 5 scouts fit easily. + +### Challenge 3: Question Presentation — Resolution + +**Decision:** All questions on one scrollable page (not tabs). Radio/checkbox per question. "Accept All Defaults" button. "Other" with text input. + +**Key differences from TUI:** + +- No tabs — the TUI uses tabs due to terminal height constraints. The browser scrolls. +- No inline notes on specific options — TUI's Tab-to-add-note is a power feature that adds complexity. The web "Other" text input covers the same need. If a user wants to qualify an answer, they select "Other" and type. +- All questions visible at once — reduces cognitive load vs. navigating tabs. The user sees the full scope immediately. + +**Validation:** "Submit Answers" is disabled until every question has a selection. A "3 of 5 answered" counter below the button shows progress. Questions without selections have a subtle red border. + +**"Accept All Defaults":** Selects `recommended` for each question (or first option if no recommended). Submits immediately. Shown as a secondary action (text link or outlined button) — not the primary button. This is for users who want to move fast and trust the model. + +### Challenge 4: The "Always Visible" Status Bar — Resolution + +**Decision:** A fixed bottom rail showing agent status and recent tool calls. + +**Contents:** + +1. **Agent indicator**: colored dot + role + model + step progress +2. **Event count**: `events: 42` — a proxy for activity (no token data available) +3. **Recent tool calls**: last 2-3 entries from `logs` SSE event, with relative timestamps + +**Why event count instead of tokens:** The `Projection` type has `eventCount` but no token fields. `events.jsonl` has individual tool calls but not aggregated token counts. Event count is a reasonable substitute — it increases visibly with activity, and a high count (100+) signals significant work. It's not as meaningful as "$0.42 spent" would be, but it's honest about what data we have. + +**Model name formatting:** The `Projection.model` field contains the full model ID (e.g., `anthropic/claude-opus-4-6`). The status rail should display a shortened form: `opus-4` or `haiku-4`. Map from model ID to display name client-side. + +**During scout exploration:** The status rail expands to two lines — one for the intake subagent, one for the scout aggregate: + +``` +│ ● intake · opus-4 step 2/3 · Codebase Scouting events: 23 │ +│ ● 4 scouts (haiku-4): 1 done, 3 running │ +``` + +### Challenge 5: Phase Transitions — Resolution + +**Decision:** Animate within the persistent layout frame. No page transitions, no route changes, no distinct "pages." + +**Mechanism:** The four-phase progress strip at the top of the main content area provides continuity. When a phase completes, its indicator changes from active (accent color, solid bar) to complete (green checkmark). The next phase's indicator becomes active. This is the primary visual signal of progression. + +The main content area below the progress strip transitions its content: + +- **Context Analysis → Scout Exploration:** The "Reading your conversation..." message fades out, scout cards fade in. Brief crossfade (300ms). +- **Scout Exploration → Elicitation:** Scout cards collapse to a summary line ("4 scouts completed ▸"), question form slides up from below (400ms slide-up). This is the biggest visual shift — from passive watching to active interaction. +- **Elicitation → Consolidation:** Question form slides down (or fades out), replaced by consolidation progress view. Brief "Thank you — writing specification..." message appears. +- **Consolidation → Decomposition:** The entire intake progress strip completes (all four checkmarks), then a new progress view for decomposition replaces it. + +**Why not distinct pages:** The pipeline is a continuous process. Page transitions would break the sense of flow and create loading/blank moments. The single-page approach with animated content transitions maintains context and orientation. + +**Transition timing:** The animations are triggered by SSE events, not timers. When `step_transition` arrives with step 2, the scout animation starts. When `ask` arrives, the question form appears. When the answer POST resolves, consolidation begins. SSE events are the single source of truth for phase state. + +--- + +## Edge Cases + +### No scouts requested + +If the intake model determines no scouting is needed (purely conceptual task), step 2 completes immediately with "Scouting skipped." The progress strip shows step 2 as complete, and the browser transitions directly from Context Analysis to step 3. No scout cards are shown. The `scouts` SSE event never fires. + +### No questions needed + +If the intake model determines the conversation + scout findings are sufficient (no gaps), step 3 completes without an `ask` SSE event. The browser never shows the question form — it goes from Scout Exploration directly to Consolidation. The progress strip shows "Questions" as complete with a "(none needed)" annotation. + +### Intake model fails + +If the intake subagent crashes (non-zero exit code), the browser receives a `subagent-idle` event or a `notification` event with level "error". The progress strip shows the current phase as failed (red indicator). The main content area shows an error message with the failure detail from `Projection.error`. + +### Browser opens mid-phase + +SSE replay (§6.3) ensures the browser gets the current state on connect. If the browser opens during scout exploration, it receives the `phase` event, `subagent` event, and `scouts` event in the initial burst. The browser renders the correct state immediately — no "catching up" animation, just the current view. + +### User refreshes during questions + +SSE replay includes pending inputs (§6.4). The `ask` event is re-pushed on reconnect with the same `requestId`. If the user had partially filled answers, those are lost (browser state is in-memory). The form re-renders fresh. This is acceptable — the user just re-selects their choices. To preserve state across refreshes, we could use `sessionStorage`, but this is a nice-to-have, not essential. + +--- + +## Aesthetic Notes + +- **Color palette:** Dark background, high-contrast text. Accent color for active elements. Green for success, red for errors, amber for warnings. Muted gray for inactive/completed elements. Developer-friendly: think VS Code's activity bar, not a marketing dashboard. +- **Typography:** Monospace for tool calls, file paths, model names. Sans-serif for question text and UI chrome. Code-like density — not too much whitespace. +- **Animation:** Subtle and fast (200-400ms). No bouncy/elastic easing. CSS `transition` on opacity and transform. The goal is "smooth" not "playful." +- **Information density:** Developer audience expects density. Don't hide things behind accordions unless there's a clear reason. The status rail is always visible. Scout cards show real file paths. Log entries show actual tool names and byte counts. diff --git a/plans/per-phase-model-selection-plan.md b/plans/per-phase-model-selection-plan.md new file mode 100644 index 0000000..c8adc09 --- /dev/null +++ b/plans/per-phase-model-selection-plan.md @@ -0,0 +1,199 @@ +## Context + +### Decisions + +- Koan adds a new root command parser via `/koan`, with `config` as the first subcommand. +- `/koan config` opens a settings-style menu with one section now: `Model selection`. +- `Model selection` uses a 5x4 matrix: + - Rows: `plan-design`, `plan-code`, `plan-docs`, `exec-code`, `exec-docs` + - Columns: `exec-debut`, `exec-fix`, `qr-decompose`, `qr-verify` +- Each matrix cell maps to one canonical key in the `phase-model` namespace (20 total keys). +- Cell picker uses an inline anchored selector and sources models from pi's model registry (`ctx.modelRegistry.getAvailable()`), matching `/model` inventory semantics. +- Quick-set controls exist at the top of model selection: + - `Reset to active model` clears koan model overrides + - `Set strong model` applies one chosen model to strong keys + - `Set general-purpose model` applies one chosen model to all remaining keys +- Strong key set is fixed: + - All `*-qr-decompose` + - `plan-design-exec-debut`, `plan-design-exec-fix` + - `exec-docs-exec-debut`, `exec-docs-exec-fix` +- General-purpose key set is computed as `all keys - strong keys`. +- Storage is denormalized: config persists either all 20 key/value pairs or none. +- Runtime model application happens only at subagent spawn time by passing `--model <provider/model>` when override exists. +- If koan model config is absent, all phases inherit pi's current active model by omitting `--model`. +- Quick-set writes always preserve all-or-none persistence: when no saved config exists, untouched keys are initialized from the current active model snapshot so all 20 keys are still written. +- Naming aligns precursor terminology to `exec-debut` and removes `exec-init` equivalents in koan-facing labels. + +### Rationale + +- Settings-style navigation matches existing pi interaction patterns and lowers learning cost. +- Matrix layout gives complete phase visibility and keeps override auditing simple. +- Quick-set controls reduce repetitive edits and enforce consistent strategy intent. +- Strong/decompose bias places more reasoning budget where planning and verification quality creates ripple effects across later work. +- `exec-docs-exec-debut/fix` are strong while `exec-code-exec-debut/fix` stay GP because code execution has a mechanical correctness backstop (build/test signals) that documentation execution does not. +- Spawn-time model resolution keeps implementation isolated to orchestration and avoids phase prompt churn. +- Denormalized persistence keeps read paths deterministic and avoids partial-state ambiguity. + +### Constraints + +- Current koan execution pipeline does not implement `exec-code` and `exec-docs`; plan still defines keys for forward compatibility. +- Existing workflow must remain behaviorally unchanged when config is absent. +- Model source must stay aligned with pi model availability/auth filtering. +- `/koan config` must work in TUI using ASCII/Unicode-safe rendering. +- Command parsing must use extension command behavior (`/koan` + args), not built-in command interception internals. + +### Invisible knowledge + +- Koan currently registers `/koan-execute` and `/koan-status`; no `/koan` root parser exists yet. +- Subagent model is currently observed for UI telemetry but never selected by koan. +- `spawnSubagent()` is the single chokepoint for all work/fix/QR subprocesses. +- `ModelSelectorComponent` is exported by pi and writes default model through settings manager on selection, so koan integration must prevent unintended global default mutation. + +## Implementation + +### 1) Canonical phase-key model map and preset sets + +- Add `src/planner/model-phase.ts`. +- Define: + - phase row constants + - sub-phase column constants + - `PhaseModelKey` union for all 20 keys + - `ALL_PHASE_MODEL_KEYS` + - `STRONG_PHASE_MODEL_KEYS` + - `GENERAL_PURPOSE_PHASE_MODEL_KEYS` +- Add helpers: + - `isPhaseModelKey(value)` + - `buildPhaseModelKey(phaseRow, subPhase)` + - internal `computeGeneralPurposeKeys()` used only to initialize exported constants +- Keep existing `WorkPhaseKey` definitions in `src/planner/subagent.ts` and `src/planner/session.ts` as intentionally narrower planning-only types; do not consolidate them into `PhaseModelKey` row definitions. + +WHY: One canonical key map eliminates drift across UI, persistence, and spawn resolution while preserving existing planning-only type boundaries. + +### 2) Config persistence (denormalized) + +- Add `src/planner/model-config.ts`. +- Store at `~/.koan/config.json` under a dedicated object, e.g.: + - `phaseModels: Record<PhaseModelKey, string>` +- Implement: + - `loadPhaseModelConfig(): Promise<Record<PhaseModelKey, string> | null>` + - `savePhaseModelConfig(config: Record<PhaseModelKey, string> | null): Promise<void>` + - strict validation that accepts only all-keys or none +- On invalid partial data, treat as absent and log warning. + +WHY: Denormalized all-or-none storage keeps runtime fallback rules unambiguous, and colocating this module under `src/planner/` keeps feature files cohesive. + +### 3) Spawn-time model resolver + +- Add `src/planner/model-resolver.ts`. +- Define and export `type SpawnContext = "work-debut" | "fix" | "qr-decompose" | "qr-verify"`. +- Implement: + - `resolvePhaseModelOverride(key): Promise<string | undefined>` + - `mapSpawnContextToPhaseModelKey(context: SpawnContext, phaseRow, fixPhase?): PhaseModelKey` +- Return `undefined` when config is absent or no override is expected, so spawn omits `--model`. + +WHY: Spawn-time resolution guarantees current active model fallback without duplicating model logic in each phase. + +### 4) Integrate model option into subagent spawning + +- Update `src/planner/subagent.ts`: + - extend spawn options with optional `modelOverride?: string` + - append `--model <modelOverride>` when provided + - extend QR spawn option types (`SpawnQRDecomposerOptions`, `SpawnReviewerOptions`) with `modelOverride?: string` +- Update `src/planner/session.ts`: + - extend `SpawnWorkRunOptions` and `SpawnFixRunOptions` with `modelOverride?: string` + - update `PhaseRunConfig.spawnWork` and `PhaseRunConfig.spawnFix` lambda forwarding to include `modelOverride` + - update QR call sites in `runQRBlock(...)` so both `spawnQRDecomposer(...)` and `spawnReviewer(...)` receive resolved `modelOverride` + - resolve the phase-specific key before each spawn and pass through the updated option chain + +WHY: A single spawn chokepoint keeps model selection simple and mechanically verifiable, and explicit option threading prevents silent override drops across work, fix, and QR paths. + +### 5) Add `/koan` command parser and config entry + +- Update `extensions/koan.ts`: + - register `/koan` command + - parse args: + - `config` opens config menu + - unknown args display concise usage + - keep existing `/koan-execute` and `/koan-status` commands unchanged + +WHY: `/koan config` requires extension command parsing semantics that pi already supports for slash-command arguments. + +### 6) Build `/koan config` menu screen + +- Add `src/planner/ui/config/menu.ts` (or equivalent UI module). +- Use settings-style list with one item now: + - `Model selection` +- Implement via `ctx.ui.custom(...)` + `SettingsList` or equivalent selector primitives. + +WHY: A section-based menu matches `/settings` mental model; new sections extend without restructuring. + +### 7) Build model selection matrix UI with inline picker + +- Add `src/planner/ui/config/model-selection.ts`. +- Screen behavior: + - quick-set row + - blank spacer row + - 5x4 matrix + - cell values show explicit model or inherited marker (active model fallback) +- Inline anchored model picker opens for selected cell. +- Model list source comes from `ctx.modelRegistry.getAvailable()`. +- Reuse pi `ModelSelectorComponent` for selection UX parity, and pass `SettingsManager.inMemory()` so cell selection never mutates global default model settings. + +WHY: Inline editing preserves matrix context and minimizes navigation overhead during bulk tuning while preserving `/model` selector parity. + +### 8) Quick-set behavior and recommendation copy + +- In model selection UI logic: + - `Reset to active model` -> clear saved overrides (persist none) + - `Set strong model` -> apply chosen model to strong keys; initialize non-strong keys from existing saved values, or from current active model snapshot when config is absent + - `Set general-purpose model` -> apply chosen model to GP keys; initialize non-GP keys from existing saved values, or from current active model snapshot when config is absent + - both quick-set actions write a complete 20-key map to satisfy all-or-none persistence +- Display recommendation nudges in UI copy: + - Strong examples: GPT-5 (Codex), Opus, Gemini 3 Pro + - GP examples: Sonnet, GPT-5 (Mini), Gemini 3 Flash + +WHY: Presets encode reasoning allocation strategy while preserving per-cell override capability. + +### 9) Rename precursor wording to `exec-debut` + +- Apply `exec-debut` naming to: + - phase-model key column constants and serialized key names + - `/koan config` user-visible matrix labels + - docs that describe phase/sub-phase naming +- Keep widget runtime token `qrMode: "initial"` in `src/planner/session.ts` and `src/planner/ui/widget.ts` unchanged because it remains internal orchestration state (used by routing/logic), not a model phase/sub-phase identifier and not the primary runtime progress display. + +WHY: Shared terminology improves comprehension and keeps planning/exec vocabulary consistent without conflating UI state tokens with phase keys. + +### 10) Validation and tests + +- Add tests for: + - key-space integrity (20 keys) + - strong/GP partition correctness + - config validator all-or-none behavior + - quick-set from empty config initializes untouched keys from active model snapshot and still writes full 20-key maps + - resolver fallback when config absent + - spawn args include/exclude `--model` correctly + - end-to-end threading for work/fix/qr spawn contexts, including `spawnQRDecomposer` and `spawnReviewer` + +WHY: Orchestration defaults require deterministic tests to prevent silent model-routing regressions. + +## Quality Checklist + +Code quality standards from ~/.claude/conventions/code-quality/ applicable to this change: + +- [ ] 01-naming-and-types (design-mode) +- [ ] 02-structure-and-composition (design-mode) +- [ ] 06-module-and-dependencies (design-mode) +- [ ] 07-cross-file-consistency (design-mode) + +## Execution Protocol + +``` +1. delegate @agent-developer: implement per this plan file +2. delegate @agent-quality-reviewer: verify against plan + ~/.claude/conventions/code-quality/ (code-mode) + +When delegating, pass this plan file path. Supplement only with: +- rationale for decisions not captured in plan +- business constraints +- technical prerequisites the agent cannot infer +``` diff --git a/plans/workflow-orchestrator.md b/plans/workflow-orchestrator.md new file mode 100644 index 0000000..67d5cd5 --- /dev/null +++ b/plans/workflow-orchestrator.md @@ -0,0 +1,1815 @@ +# Workflow Orchestrator — Implementation Plan + +## Problem Statement + +Koan's pipeline manages an epic through eight phases: + +``` +intake → brief-generation → core-flows → tech-plan → ticket-breakdown +→ cross-artifact-validation → execution → implementation-validation +``` + +Only **intake** and **brief-generation** are currently implemented. The +remaining six phases exist as stubs — placeholder registrations in the phase +DAG that auto-advance when reached. Every run traverses every phase in exactly +this order. This creates two concrete problems. + +**First, no flexibility.** A user who already understands the problem space +cannot skip brief generation. A user who wants to jump directly to core-flow +definition — bypassing the brief — has no way to express that intent. Adding +successor branches between phases would require forking the pipeline or adding +a tangle of conditional flags — both are maintenance traps. + +**Second, no handoff.** When a phase completes, the pipeline silently advances. +The user sees no summary of what was accomplished, no explanation of what the +next phase will do, and no opportunity to adjust focus before work begins. This +matters most when phases accumulate context: after intake, the orchestrator +knows what was discussed; the next phase's LLM does not, unless context is +explicitly passed forward. + +This plan replaces the hardcoded sequence with a **user-directed, orchestrator- +mediated loop**. After each phase completes, a workflow orchestrator agent +evaluates what was produced, surfaces a contextual status report with +recommended next phases, and holds a multi-turn conversation with the user to +agree on direction — with optional instructions that shape what the next phase +does. The orchestrator session appears inline in the ActivityFeed as a +continuation of the completed phase's activity, preserving full visual +continuity. + +--- + +## Breaking Changes + +This plan is a **breaking change** for existing epic directories. The +`EpicPhase` type renames `"brief"` → `"brief-generation"` and removes +`"decomposition"`, `"review"`, and `"executing"`. Existing `epic-state.json` +files containing these values are incompatible with the new phase registry. + +**Migration:** Delete existing epic directories before deploying. No automated +migration is provided — this is pre-release software with no production state +to preserve. + +The spec review gate (driver.ts lines 370–415) and all associated code are +**deleted**, not retained as dormant code. This includes `requestReview()` on +`WebServerHandle`, `ReviewStory`/`ReviewResult` types in `server-types.ts`, +the `ReviewForm` component, the `/api/review` POST endpoint, the `"review"` +SSE event type, and review-related store state. This functionality was +development scaffolding; a future `cross-artifact-validation` phase will use a +different mechanism. + +--- + +## Phase Registry + +### Canonical Phases + +Eight phases form the complete epic lifecycle. Each phase has a well-defined +purpose, a set of artifacts it produces, and a set of artifacts it consumes. +The `EpicPhase` type is the single source of truth; adding or removing a phase +means updating this type and the transition DAG. + +| Phase | Purpose | Status | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------- | +| `intake` | Multi-round codebase exploration and structured Q&A to align on requirements. Produces `landscape.md`. | Implemented | +| `brief-generation` | Distill intake context into a compact product-level epic brief. Produces `brief.md`. | Implemented | +| `core-flows` | Define user journeys with sequence diagrams. Produces `core-flows.md`. | Stub | +| `tech-plan` | Specify three-section technical architecture: approach, data model, component architecture. Produces `tech-plan.md`. | Stub | +| `ticket-breakdown` | Generate story-sized implementation tickets with dependency diagrams. Produces ticket files. | Stub | +| `cross-artifact-validation` | Validate cross-boundary consistency across all spec artifacts. May edit specs to reconcile. | Stub | +| `execution` | Implement tickets through a supervised batch process with verification and commit gates. | Stub | +| `implementation-validation` | Post-execution review evaluating alignment and correctness against specs. | Stub | + +`completed` is a terminal marker, not an active phase. The pipeline sets +`phase: "completed"` after the last phase succeeds. + +### Stub Phases + +Stub phases register in the DAG and the `EpicPhase` type but perform no work. +When the driver reaches a stub phase, it: + +1. Saves the phase to `epic-state.json` +2. Pushes the phase to the web UI +3. Logs a placeholder message: `"Phase {phase} is a placeholder — auto-advancing"` +4. Immediately advances to the next phase per the DAG + +This design lets the full phase registry and DAG exist from day one. The +orchestrator, UI pill strip, and documentation reference all eight phases +consistently. Implementing a phase later means replacing its stub entry in +the driver — no structural changes to routing, permissions, or the UI. + +### Type Definition + +```typescript +export type EpicPhase = + | "intake" + | "brief-generation" + | "core-flows" + | "tech-plan" + | "ticket-breakdown" + | "cross-artifact-validation" + | "execution" + | "implementation-validation" + | "completed"; +``` + +--- + +## Design Decisions (Resolved) + +| # | Decision | Resolution | +| --- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | How do user instructions reach the next phase? | Via `task.json` — the orchestrator commits a decision including optional instructions; the driver reads it and injects `phaseInstructions` into the next phase's task manifest. The phase's step 1 guidance template surfaces it as additional context. | +| 2 | When is the orchestrator skipped? | When the DAG shows exactly one valid successor. No orchestrator process is spawned for deterministic transitions — the driver auto-advances at zero cost. | +| 3 | How does the workflow decision render in the UI? | Inline in the ActivityFeed as a continuation of the completed phase's activity. The phase's final log lines are frozen and dimmed; a visual separator marks the start of the orchestrator session; the orchestrator's tool calls stream below; and when `koan_propose_workflow` fires, a `WorkflowChat` component opens at the bottom of the feed showing the full multi-turn conversation. No mode switch. | +| 4 | What context does the orchestrator receive? | The driver writes `workflow-status.md` before spawning — a markdown file listing completed phases, artifact paths, and the available next phases. The orchestrator reads this plus all existing artifacts. | +| 5 | How does the phase registry work? | `EpicPhase` is a TypeScript union expanded with new values as phases are added. The transition DAG is a plain constant — easy to read, easy to update, TypeScript-checkable. | + +--- + +## Phase Transition DAG + +The DAG defines which phases can legally follow which. Successor order encodes +recommendation priority: the first entry is the most-recommended default path. + +The DAG is the **single source of truth** for what transitions are valid. The +driver uses it to decide whether to auto-advance or spawn the orchestrator. The +`koan_set_next_phase` tool validates against it before writing state, so the +orchestrator cannot commit an illegal transition. **The DAG itself does not +change** when promoting a stub to a real implementation — the phase name is +already in it. But the routing infrastructure requires coordinated updates; +see the Phase Promotion Checklist below. + +```typescript +const PHASE_TRANSITIONS: Record<EpicPhase, EpicPhase[]> = { + intake: ["brief-generation", "core-flows"], // 2 successors → orchestrator + "brief-generation": ["core-flows"], // 1 successor → auto-advance + "core-flows": ["tech-plan"], // 1 successor → auto-advance + "tech-plan": ["ticket-breakdown"], // 1 successor → auto-advance + "ticket-breakdown": ["cross-artifact-validation"], // 1 successor → auto-advance + "cross-artifact-validation": ["execution"], // 1 successor → auto-advance + execution: ["implementation-validation"], // 1 successor → auto-advance + "implementation-validation": ["completed"], // 1 successor → auto-advance + completed: [], // terminal +}; +``` + +The `intake` phase has two successors: `brief-generation` (recommended default) +and `core-flows` (skip brief). After intake completes, the workflow orchestrator +spawns and presents the user with a choice. Even though `core-flows` is a stub +phase that auto-advances, this transition exercises the full orchestrator +path — IPC, UI, decision persistence — in production from day one. + +Future DAG expansions can add more multi-successor transitions as phases are +implemented. The orchestrator infrastructure requires no changes — only the +DAG constant is updated when adding successor edges. + +### Phase Promotion Checklist + +When promoting a stub phase to a real implementation, the following changes +are required. The DAG itself does not change (the phase name is already in it). + +| # | File | Change | +| --- | ------------------------------------- | ---------------------------------------------------------------------------- | +| 1 | `lib/phase-dag.ts` | Add entry to `IMPLEMENTED_PHASES` set | +| 2 | `types.ts` | Add new `SubagentRole` value and `ROLE_MODEL_TIER` entry | +| 3 | `lib/task.ts` | Create task interface variant; add to `SubagentTask` union | +| 4 | `lib/permissions.ts` | Add `ROLE_PERMISSIONS` entry for the new role | +| 5 | `driver.ts` | Add role mapping to `PHASE_ROLE` | +| 6 | `phases/{phase}/phase.ts` | Create phase class extending `BasePhase` | +| 7 | `phases/{phase}/prompts.ts` | Create system prompt + step guidance; thread `phaseInstructions` into step 1 | +| 8 | `phases/dispatch.ts` | Add case for the new role | +| 9 | `extensions/koan.ts` | Register any new phase-specific tools | +| 10 | `web/js/components/StatusSidebar.jsx` | (Optional) Add dedicated status widget | + +--- + +## Architecture + +### New Components + +``` +src/planner/ +├── lib/ +│ └── phase-dag.ts # Transition DAG + DAG query functions +├── phases/ +│ └── workflow-orchestrator/ +│ ├── phase.ts # WorkflowOrchestratorPhase extends BasePhase +│ └── prompts.ts # System prompt + step guidance +├── tools/ +│ └── workflow-decision.ts # koan_propose_workflow + koan_set_next_phase +├── lib/ +│ ├── ipc.ts # + WorkflowDecisionIpcFile type + factory +│ ├── ipc-responder.ts # + handleWorkflowDecisionRequest dispatch +│ ├── permissions.ts # + "workflow-orchestrator" role +│ └── task.ts # + WorkflowOrchestratorTask + phaseInstructions +├── epic/ +│ ├── types.ts # + WorkflowDecisionState +│ └── state.ts # + read/write workflow decision helpers +├── web/ +│ ├── server.ts # + requestWorkflowDecision() + POST endpoint +│ │ # + freezeLogs() + frozen-logs SSE event +│ ├── server-types.ts # + event types + WebServerHandle methods +│ └── js/ +│ ├── store.js # + workflowChat + frozenLogs state + handlers +│ ├── sse.js # + 'workflow-decision', 'frozen-logs' routing +│ └── components/ +│ └── ActivityFeed.jsx # + frozen zone + separator + WorkflowChat +├── driver.ts # Refactor: phase loop + orchestrator spawning +└── types.ts # Updated EpicPhase + "workflow-orchestrator" role +``` + +### Modified Components + +| File | Change | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `types.ts` | Replace `EpicPhase` with 8 phases + `completed`. Add `"workflow-orchestrator"` to `SubagentRole` and `ROLE_MODEL_TIER` (strong). | +| `lib/task.ts` | Add `WorkflowOrchestratorTask` variant; add optional `phaseInstructions?: string` to `SubagentTaskBase`. | +| `lib/permissions.ts` | Add `"workflow-orchestrator"` role entry. | +| `lib/ipc.ts` | Add `WorkflowDecisionIpcFile` to `IpcFile` union; add `"workflow-decision"` branch to `pollIpcUntilResponse`. | +| `lib/ipc-responder.ts` | Add `handleWorkflowDecisionRequest` handler; add dispatch case in `runIpcResponder`. | +| `phases/dispatch.ts` | Add `"workflow-orchestrator"` case: narrow task to `WorkflowOrchestratorTask`, extract config, construct `WorkflowOrchestratorPhase`. | +| `driver.ts` | Replace linear `intake → brief-generation → …` sequence with DAG-driven loop. Add stub handling for unimplemented phases. Add headless guard. Call `freezeLogs()` before spawning orchestrator. | +| `web/server.ts` | Add `requestWorkflowDecision()`, POST `/api/workflow-decision`, `frozen-logs` SSE push + replay, `"workflow-decision"` branch in `replayState()`. | +| `web/server-types.ts` | Add `WorkflowDecisionEvent`, `FrozenLogsEvent`, `WorkflowDecisionFeedback`, `freezeLogs` + `requestWorkflowDecision` to `WebServerHandle`. Add `"workflow-decision"` to `PendingEntry.type` union. | +| `web/js/store.js` | Add `frozenLogs`, `workflowChat` slices + handlers; clear on phase transition and pipeline end. | +| `web/js/sse.js` | Add `'workflow-decision'`, `'workflow-decision-cancelled'`, `'frozen-logs'` routing. | +| `web/js/components/App.jsx` | Pass `token` prop to `ActivityFeed`; `workflowChat` must not affect `isInteractive`. | +| `web/js/components/ActivityFeed.jsx` | Accept `token` prop; render frozen zone + separator + live logs + `WorkflowChat`. | +| `web/js/components/PillStrip.jsx` | Update `PHASES` and `PHASE_ORDER` arrays for the 8 phases. | +| `web/js/components/StatusSidebar.jsx` | Update `PhaseStatus` switch for new phase identifiers. Add generic status for stub phases. Remove `phase === 'review'` branch from `GenericStatus`. | +| `web/js/components/PhaseContent.jsx` | Remove review rendering branch (part of spec review gate deletion). | +| `web/css/components.css` | Styles for frozen logs, orchestrator separator, `WorkflowChat`. | +| `extensions/koan.ts` | Register new tools. | +| All phase step 1 guidance functions | Thread `phaseInstructions` into step 1 context when present. | + +--- + +## Detailed Component Designs + +### 1. Types and Task Manifest + +`EpicPhase` is the canonical phase registry. It replaces the previous +placeholder union with the full lifecycle: + +```typescript +export type EpicPhase = + | "intake" + | "brief-generation" + | "core-flows" + | "tech-plan" + | "ticket-breakdown" + | "cross-artifact-validation" + | "execution" + | "implementation-validation" + | "completed"; +``` + +`SubagentRole` gains `"workflow-orchestrator"` with `"strong"` model tier. This +mirrors the existing `"orchestrator"` role's tier assignment — workflow-level +decisions require the same reasoning quality as story-level orchestration. + +`SubagentTaskBase` gains an optional `phaseInstructions` field. Making it part +of the base (rather than a variant-specific field) means every phase receives +it uniformly, and the driver can set it without branching on role. Phases that +receive no instructions simply see `undefined` and skip the context injection. +Because `phaseInstructions` is optional and JSON.stringify omits `undefined` +values, existing task construction sites (`{ role, epicDir }`) require no +changes — they remain valid subtypes. + +```typescript +export type SubagentRole = + | "intake" + | "scout" + | "decomposer" + | "orchestrator" + | "planner" + | "executor" + | "brief-writer" + | "workflow-orchestrator"; + +export const ROLE_MODEL_TIER: Record<SubagentRole, ModelTier> = { + // ... existing ... + "workflow-orchestrator": "strong", +}; +``` + +```typescript +/** Optional instructions from the workflow orchestrator's decision. + * Injected into step 1 guidance of the next phase when the user provides + * context during the workflow decision interaction (e.g. "focus on auth + * requirements"). Absent when the orchestrator is skipped or when the user + * gives no additional direction. */ +interface SubagentTaskBase { + role: SubagentRole; + epicDir: string; + phaseInstructions?: string; +} + +export interface WorkflowOrchestratorTask extends SubagentTaskBase { + role: "workflow-orchestrator"; + completedPhase: EpicPhase; // which phase just finished — for context + availablePhases: EpicPhase[]; // valid successors from the DAG +} +``` + +### 2. Phase Transition DAG + +**`lib/phase-dag.ts`** (new file): + +```typescript +import type { EpicPhase } from "../types.js"; + +/** Valid successor phases for each phase. Order = recommendation priority. + * This is the single source of truth consulted by: + * - the driver (to decide whether to spawn the orchestrator) + * - koan_set_next_phase (to validate the committed transition) + * - WorkflowOrchestratorPhase step 2 guidance (lists available phases) + * Add new phases here; routing logic requires no other changes. */ +export const PHASE_TRANSITIONS: Readonly< + Record<EpicPhase, readonly EpicPhase[]> +> = { + intake: ["brief-generation", "core-flows"], + "brief-generation": ["core-flows"], + "core-flows": ["tech-plan"], + "tech-plan": ["ticket-breakdown"], + "ticket-breakdown": ["cross-artifact-validation"], + "cross-artifact-validation": ["execution"], + execution: ["implementation-validation"], + "implementation-validation": ["completed"], + completed: [], +}; + +/** Phases that have a real implementation (subagent-backed). + * All other phases are stubs that auto-advance when reached. */ +export const IMPLEMENTED_PHASES: ReadonlySet<EpicPhase> = new Set([ + "intake", + "brief-generation", +]); + +/** Returns valid next phases from the DAG. */ +export function getSuccessorPhases(phase: EpicPhase): readonly EpicPhase[] { + return PHASE_TRANSITIONS[phase] ?? []; +} + +/** True when the driver can auto-advance without consulting the orchestrator. + * A single successor means the transition is unambiguous; spawning an + * orchestrator would add latency and LLM cost with no user value. */ +export function isAutoAdvance(phase: EpicPhase): boolean { + return getSuccessorPhases(phase).length === 1; +} + +/** True when the phase has no subagent implementation and should be skipped. */ +export function isStubPhase(phase: EpicPhase): boolean { + return phase !== "completed" && !IMPLEMENTED_PHASES.has(phase); +} + +/** Validates that a proposed transition is legal before committing. + * Called by koan_set_next_phase to prevent the orchestrator from + * hallucinating a phase name not in the DAG. */ +export function isValidTransition(from: EpicPhase, to: EpicPhase): boolean { + return getSuccessorPhases(from).includes(to); +} + +/** Human-readable one-line description of each phase. + * Used by writeWorkflowStatus() and the orchestrator's step 2 guidance. */ +export const PHASE_DESCRIPTIONS: Readonly<Record<EpicPhase, string>> = { + intake: + "Multi-round codebase exploration and structured Q&A to align on requirements", + "brief-generation": + "Distill intake context into a compact product-level epic brief", + "core-flows": "Define user journeys with sequence diagrams", + "tech-plan": + "Specify technical architecture: approach, data model, component design", + "ticket-breakdown": + "Generate story-sized implementation tickets with dependency diagrams", + "cross-artifact-validation": + "Validate cross-boundary consistency across all spec artifacts", + execution: + "Implement tickets through a supervised batch process with verification", + "implementation-validation": + "Post-execution review evaluating alignment and correctness against specs", + completed: "Pipeline complete", +}; +``` + +### 3. IPC Type: `workflow-decision` + +The workflow decision follows the same IPC protocol as `artifact-review`: +the subagent writes a request with `response: null`, polls until the parent +fills in the response, then deletes the file and returns the response text +to the LLM. This reuse is deliberate — the entire IPC machinery (atomic +writes, polling, idempotence guard, abort handling, SSE replay) is already +proven and requires no structural changes. + +The response is **plain text**, not a structured selection, for the same reason +`artifact-review` uses plain text: a dedicated `selectedPhase` field would +force a two-branch protocol and require the tool to execute the branch +mechanically. Plain text lets the LLM interpret the user's intent, handle +ambiguous responses, and re-propose when the response is unclear. The +`koan_set_next_phase` call is the structured commitment; everything before it +is conversational. + +**`lib/ipc.ts`** additions: + +```typescript +export interface WorkflowPhaseOption { + phase: string; // EpicPhase value + label: string; // human-readable, e.g. "Write Epic Brief" + context: string; // why this phase is useful right now + recommended?: boolean; +} + +export interface WorkflowDecisionPayload { + statusReport: string; // markdown summary of current state + recommendedPhases: WorkflowPhaseOption[]; + completedPhase: string; // the just-completed phase (not a history — + // EpicState stores only the current phase) +} + +// Matches the shape of ArtifactReviewResponse: id for correlation, +// respondedAt for debugging. Consistent with all other IPC response types. +export interface WorkflowDecisionResponse { + id: string; + respondedAt: string; + feedback: string; // user's free-form text response +} + +export interface WorkflowDecisionIpcFile { + type: "workflow-decision"; + id: string; + createdAt: string; + payload: WorkflowDecisionPayload; + response: WorkflowDecisionResponse | null; +} + +// Updated union: +export type IpcFile = + | AskIpcFile + | ScoutIpcFile + | ArtifactReviewIpcFile + | WorkflowDecisionIpcFile; +``` + +**`pollIpcUntilResponse` requires a new branch.** The existing function has +explicit if-branches for each IPC type. Without a matching branch for +`"workflow-decision"`, the poll loop never detects the response and the pipeline +hangs indefinitely. Add the following alongside the existing `artifact-review` +branch: + +```typescript +if ( + current.type === "workflow-decision" && + current.response !== null && + current.id === ipc.id +) { + outcome = "answered"; + finalIpc = current; + break; +} +``` + +The `createWorkflowDecisionRequest` factory follows the exact pattern of +`createArtifactReviewRequest`. + +### 4. New Tools + +**`tools/workflow-decision.ts`** (new file): + +#### `koan_propose_workflow` + +Presents the workflow decision to the user via IPC. Structurally identical to +`koan_review_artifact`: writes an IPC file, polls for the response, returns +the user's text. The orchestrator can call this tool multiple times — if the +user provides feedback rather than direction, the orchestrator addresses it +and calls the tool again. The loop terminates only when the orchestrator +commits via `koan_set_next_phase`. + +Each call to `koan_propose_workflow` is a new, independent IPC round-trip. The +multi-turn conversation history is maintained client-side (see §8); from the +server and tool perspective every call is a fresh `workflow-decision` IPC file. + +```typescript +// Parameters: +{ + status_report: string, + recommended_phases: Array<{ + phase: string, + label: string, + context: string, + recommended?: boolean + }> +} +``` + +**Execution flow:** + +1. Guard: return error if another IPC request is already pending +2. Read `completedPhase` from `task.json` (via `readTaskFile(ctx.subagentDir)`, + narrowed to `WorkflowOrchestratorTask`) for UI context +3. Write `WorkflowDecisionIpcFile` to `ipc.json` (atomic tmp-rename) +4. `pollIpcUntilResponse()` at 500ms — blocks the LLM turn +5. Delete `ipc.json`, return the user's feedback text + +#### `koan_set_next_phase` + +Commits the phase transition decision. Analogous to `koan_select_story` for +phase-level routing: writes a structured decision file the driver reads after +the orchestrator exits. + +```typescript +// Parameters: +{ + phase: string, + instructions?: string +} +``` + +**Execution flow:** + +1. Read `task.json` from `ctx.subagentDir` via `readTaskFile()`, narrow to + `WorkflowOrchestratorTask` via `task.role === "workflow-orchestrator"`, + obtain `availablePhases`. This is the directory-as-contract approach: + structured inputs live in `task.json`, not in tool parameters or + RuntimeContext fields. The tool reads at call time rather than caching in + RuntimeContext to avoid adding orchestrator-specific fields to a shared + carrier. +2. Validate `phase` is in `availablePhases` +3. Write `workflow-decision.json` atomically to **`ctx.subagentDir`** +4. Return confirmation text + +The decision file lives in the subagent directory (not epicDir) to preserve +the directory-as-contract invariant: the subagent directory is the sole +interface between parent and child. The driver reads this file from the +orchestrator's subagentDir after the process exits, before any directory +cleanup. + +**State file** (`{subagentDir}/workflow-decision.json`): + +```json +{ + "nextPhase": "core-flows", + "instructions": "Focus on auth requirements", + "decidedAt": "2026-03-24T12:00:00.000Z" +} +``` + +**`WorkflowDecisionState`** (in `epic/types.ts`) — the TypeScript type for this file: + +```typescript +/** Written by koan_set_next_phase to the subagent directory. + * Read by the driver after the orchestrator process exits. + * nextPhase is string (not EpicPhase) because it's read from JSON + * and validated via isValidTransition() before casting. */ +export interface WorkflowDecisionState { + nextPhase: string; + instructions?: string; + decidedAt: string; +} +``` + +**`readWorkflowDecision()`** (in `epic/state.ts`) — reads the decision file +after the orchestrator process exits: + +```typescript +import type { WorkflowDecisionState } from "./types.js"; + +/** Read {subagentDir}/workflow-decision.json written by koan_set_next_phase. + * Returns null if absent (orchestrator crashed before committing) or + * malformed (should never happen — koan_set_next_phase writes valid JSON). */ +export async function readWorkflowDecision( + subagentDir: string, +): Promise<WorkflowDecisionState | null> { + try { + const raw = await fs.readFile( + path.join(subagentDir, "workflow-decision.json"), + "utf8", + ); + return JSON.parse(raw) as WorkflowDecisionState; + } catch { + return null; + } +} +``` + +### 5. WorkflowOrchestratorPhase + +Extends `BasePhase`. Two steps per the single-cognitive-goal principle: +one step to gather context, one step to hold the user conversation and commit. +Merging these into a single step would allow the LLM to pre-plan its +recommendation while still reading artifacts — the steps must be isolated so +evaluation precedes proposal. + +| Step | Name | Purpose | +| ---- | -------- | -------------------------------------------------------------------------------- | +| 1 | Evaluate | Read `workflow-status.md` and phase artifacts. Build mental model. | +| 2 | Propose | Call `koan_propose_workflow`. Handle feedback. Commit via `koan_set_next_phase`. | + +**Step 2 validation gate** blocks `koan_complete_step` unless both +`koan_propose_workflow` and `koan_set_next_phase` have been called. The +proposal gate ensures the orchestrator cannot silently commit a phase +transition without presenting options to the user — the entire value +proposition of the orchestrator is user interaction. Uses `event.isError` +(not `event.error`) to match `ReviewablePhase`'s established convention: + +```typescript +/** Config extracted from WorkflowOrchestratorTask by dispatch.ts. + * Keeps the constructor signature clean and type-safe. */ +interface WorkflowOrchestratorConfig { + completedPhase: EpicPhase; + availablePhases: readonly EpicPhase[]; +} + +export class WorkflowOrchestratorPhase extends BasePhase { + protected readonly role = "workflow-orchestrator"; + protected readonly totalSteps = 2; + + private readonly completedPhase: EpicPhase; + private readonly availablePhases: readonly EpicPhase[]; + private proposalMade = false; + private nextPhaseSet = false; + + constructor( + pi: ExtensionAPI, + config: WorkflowOrchestratorConfig, + ctx: RuntimeContext, + log?: Logger, + eventLog?: EventLog, + ) { + super(pi, ctx, log, eventLog); + this.completedPhase = config.completedPhase; + this.availablePhases = config.availablePhases; + + pi.on("tool_result", (event) => { + // event.isError matches ReviewablePhase convention — not event.error + if (event.toolName === "koan_propose_workflow" && !event.isError) { + this.proposalMade = true; + } + if (event.toolName === "koan_set_next_phase" && !event.isError) { + this.nextPhaseSet = true; + } + }); + } + + protected async validateStepCompletion(step: number): Promise<string | null> { + if (step === 2 && !this.proposalMade) { + return ( + "You must call koan_propose_workflow to present options to the user " + + "before committing a phase transition." + ); + } + if (step === 2 && !this.nextPhaseSet) { + return ( + "You must call koan_set_next_phase before completing this step. " + + "Call koan_propose_workflow again if you still need user input." + ); + } + // Delegate to BasePhase for step bounds checking and any future base validations. + return super.validateStepCompletion(step); + } +} +``` + +**Step 2 guidance** injects `availablePhases` from the task manifest into the +prompt so the orchestrator only proposes valid DAG transitions. + +### 6. Driver Refactor + +The linear sequence in `runPipeline()` is replaced with a DAG-driven loop. +`runWorkflowOrchestrator()` returns `{ nextPhase, instructions }` so +`phaseInstructions` flows cleanly as a return value rather than a mutable +closure variable. + +Before spawning the orchestrator, the driver calls `webServer.freezeLogs()` to +snapshot the completed phase's activity into the frozen log buffer (see §8). +This preserves visual continuity: the phase's tool calls and thinking cards +remain visible as the orchestrator session begins below them. + +**Stub phases** are handled by `runPhase()` — when `isStubPhase(phase)` returns +true, the driver logs a placeholder message and returns immediately without +spawning any subagent. This makes stubs zero-cost: no process spawn, no LLM +call, no web server tracking. + +**Phase-to-role mapping** maps each implemented phase to its subagent role. +This replaces the previous approach where the role name was passed directly: + +```typescript +/** Maps implemented phases to the subagent role that executes them. + * Stubs are not listed — they never spawn a subagent. */ +const PHASE_ROLE: Partial<Record<EpicPhase, SubagentRole>> = { + intake: "intake", + "brief-generation": "brief-writer", +}; +``` + +```typescript +async function runPipeline(epicDir, cwd, extensionPath, log, webServer) { + let phase: EpicPhase = "intake"; + let pendingInstructions: string | undefined; + + while (phase !== "completed") { + await saveEpicState(epicDir, { ...state, phase }); + webServer?.pushPhase(phase); + + if (isStubPhase(phase)) { + log(`Phase "${phase}" is a placeholder — auto-advancing`, { phase }); + // Do NOT clear pendingInstructions here. Stubs don't consume + // instructions — carry them forward to the next real phase. + } else { + const phaseOk = await runPhase(phase, epicDir, cwd, extensionPath, log, webServer, pendingInstructions); + pendingInstructions = undefined; // consumed by the real phase + if (!phaseOk) return { success: false, summary: `Phase "${phase}" failed` }; + } + + const successors = getSuccessorPhases(phase); + if (successors.length === 0) break; + + if (isAutoAdvance(phase)) { + phase = successors[0]; + continue; + } + + // Multiple successors: requires user direction. + // In headless mode (no webServer), the orchestrator cannot run because + // koan_propose_workflow requires requestWorkflowDecision() on the server + // and the IPC responder is not started. Auto-advance to the recommended + // (first) successor to preserve CI correctness. + if (!webServer) { + log("No web server — auto-advancing to recommended phase (headless mode)", { + from: phase, to: successors[0], + }); + phase = successors[0]; + continue; + } + + // Snapshot the completed phase's activity before spawning the orchestrator. + // trackSubagent() for the orchestrator will replace the live log buffer; + // freezeLogs() preserves the phase's final state for the frozen zone in + // the ActivityFeed. + webServer.freezeLogs(); + + const decision = await runWorkflowOrchestrator(phase, successors, epicDir, ...); + if (!decision) { + return { success: false, summary: `Workflow orchestrator failed after "${phase}"` }; + } + phase = decision.nextPhase; + pendingInstructions = decision.instructions; + } + + await saveEpicState(epicDir, { ...state, phase: "completed" }); + webServer?.pushPhase("completed"); +} +``` + +**`runPhase()`** accepts `phaseInstructions?` and dispatches to the appropriate +subagent: + +```typescript +async function runPhase( + phase, + epicDir, + cwd, + extensionPath, + log, + webServer, + phaseInstructions?, +): Promise<boolean> { + const role = PHASE_ROLE[phase]; + if (!role) { + // Should never happen — isStubPhase() guards this in the loop above. + throw new Error(`No role mapping for implemented phase: ${phase}`); + } + return runSimplePhase( + role, + epicDir, + webServer, + extensionPath, + cwd, + log, + phaseInstructions, + ); +} +``` + +`runSimplePhase()` gains `phaseInstructions?` and includes it in the task: + +```typescript +// role parameter widens from "intake" | "brief-writer" | "decomposer" to SubagentRole +// to accommodate future phase roles dispatched through PHASE_ROLE. +async function runSimplePhase(role: SubagentRole, epicDir, ..., phaseInstructions?) { + const task = (phaseInstructions + ? { role, epicDir, phaseInstructions } + : { role, epicDir }) as SubagentTask; + // ... +} +``` + +**`runWorkflowOrchestrator()`** returns the structured decision: + +```typescript +async function runWorkflowOrchestrator( + completedPhase: EpicPhase, + availablePhases: EpicPhase[], + epicDir: string, + ... +): Promise<{ nextPhase: EpicPhase; instructions?: string } | null> { + await writeWorkflowStatus(epicDir, completedPhase, availablePhases); + + const task: WorkflowOrchestratorTask = { + role: "workflow-orchestrator", + epicDir, + completedPhase, + availablePhases, + }; + // Timestamp ensures no stale workflow-decision.json from a crashed run + // is accidentally read on restart. + const dir = await ensureSubagentDirectory(epicDir, `workflow-orch-${completedPhase}-${Date.now()}`); + const id = `workflow-orchestrator-${completedPhase}`; + const opts: SpawnOptions = { cwd, extensionPath, log, webServer: webServer ?? undefined }; + const result = await spawnTracked(id, id, "workflow-orchestrator", task, dir, undefined, opts, webServer); + + if (result.exitCode !== 0) { + log("Workflow orchestrator failed", { exitCode: result.exitCode, completedPhase }); + return null; + } + + const decision = await readWorkflowDecision(dir); + if (!decision) { + log("Workflow orchestrator exited without committing a decision", { completedPhase }); + return null; + } + if (!isValidTransition(completedPhase, decision.nextPhase as EpicPhase)) { + log("Workflow orchestrator committed an invalid transition", { + completedPhase, nextPhase: decision.nextPhase, + }); + return null; + } + + return { nextPhase: decision.nextPhase as EpicPhase, instructions: decision.instructions }; +} +``` + +### 7. `phaseInstructions` Threading + +Full data flow from user text to next-phase LLM context. There are **10 steps** +across 6 files: + +``` + 1. Orchestrator calls koan_set_next_phase({ phase: "core-flows", instructions: "Focus on auth" }) + 2. Tool reads task.json from subagentDir → narrows to WorkflowOrchestratorTask → validates + 3. Tool writes workflow-decision.json to subagentDir: { nextPhase: "core-flows", instructions: "..." } + 4. runWorkflowOrchestrator() reads decision from subagentDir → returns { nextPhase, instructions } + 5. runPipeline() stores in pendingInstructions + 6. runPipeline() passes pendingInstructions to runPhase() → consumed and cleared + 7. runPhase() calls runSimplePhase() with phaseInstructions + 8. runSimplePhase() writes task.json: { role, epicDir, phaseInstructions: "..." } + 9. koan.ts (before_agent_start) reads task.json, sets ctx.phaseInstructions = task.phaseInstructions +10. Phase.getStepGuidance(1) reads this.ctx.phaseInstructions, appends as context block +``` + +**Step 9 is critical and requires changes to two existing files:** + +**`lib/runtime-context.ts`** gains `phaseInstructions`: + +```typescript +export interface RuntimeContext { + epicDir: string | null; + subagentDir: string | null; + onCompleteStep: ((thoughts: string) => Promise<string | null>) | null; + currentStep: number; + eventLog: EventLog | null; + phaseInstructions?: string; // ← new: from workflow orchestrator decision + // Note: availablePhases is NOT in RuntimeContext — it is role-specific to + // the workflow-orchestrator and accessed via readTaskFile() in the tool. + // phaseInstructions IS here because it applies to ALL phases uniformly. +} +``` + +**`extensions/koan.ts`** (in `before_agent_start`, after `readTaskFile`): + +```typescript +const task = await readTaskFile(subagentDir); +ctx.epicDir = task.epicDir; +ctx.subagentDir = subagentDir; +ctx.phaseInstructions = task.phaseInstructions; // ← new: thread into context +``` + +**Phase guidance functions** access via `this.ctx.phaseInstructions`: + +```typescript +// In BriefWriterPhase.getStepGuidance: +protected getStepGuidance(step: number): StepGuidance { + return briefWriterStepGuidance(step, this.ctx.epicDir!, this.ctx.phaseInstructions); +} + +// In briefWriterStepGuidance: +function briefWriterStepGuidance(step: number, epicDir: string, phaseInstructions?: string) { + if (step === 1) { + const lines = [ `Read \`${epicDir}/landscape.md\`. ...` /* existing */ ]; + if (phaseInstructions) { + lines.push("", "## Additional Context from Workflow Orchestrator", "", phaseInstructions); + } + return { title: "Read", instructions: lines }; + } +} +``` + +### 8. Web UI: Inline ActivityFeed with Orchestrator Session + +The workflow orchestrator session appears as a **seamless continuation** of the +completed phase's activity in the same feed. No mode switch occurs — the three- +column workspace (status sidebar, activity feed, artifacts panel) remains active +throughout. This design reflects that watching the orchestrator evaluate +artifacts and build its recommendation is itself informative: its tool calls +scanning `landscape.md` or `brief.md` build visible trust in the proposal that +follows. + +The ActivityFeed is structured in four zones when the orchestrator is active: + +``` +┌─────────────────────────────────────────┐ +│ [frozen phase activity — dimmed] │ phase's final tool calls / thinking +│ thinking 4s │ +│ read landscape.md │ +│ ... │ +├── ─── Evaluating workflow... ───────────┤ separator (rendered when frozenLogs set) +│ [live orchestrator activity] │ orchestrator's streaming tool calls +│ thinking ... │ +│ read workflow-status.md │ +│ ... │ +├─────────────────────────────────────────┤ +│ [WorkflowChat thread] │ multi-turn conversation +│ ● requirements are fully aligned... │ orchestrator turn (status + options) +│ ○ focus on auth requirements │ user turn +│ ● understood — here's my updated... │ orchestrator turn +│ │ +│ [text input] [Continue →] │ +└─────────────────────────────────────────┘ +``` + +#### Frozen logs: preserving phase activity + +`trackSubagent()` replaces `lastLogs` with each new subagent's polling output. +Without intervention, the orchestrator's activity would overwrite the completed +phase's logs. To prevent this, the driver calls `webServer.freezeLogs()` before +spawning the orchestrator. This method snapshots `lastLogs` into a separate +`frozenLogs` buffer and pushes a `frozen-logs` SSE event to all clients. + +The server holds both buffers independently. `frozenLogs` is included in +`replayState()` so reconnecting browsers see the complete picture. It is cleared +when the next phase begins (`pushPhase()` with a non-orchestrator phase). + +**`WebServerHandle`** gains two new methods: + +```typescript +/** Snapshot current lastLogs into frozenLogs and push 'frozen-logs' SSE event. + * Called by the driver before spawning the workflow orchestrator so that + * trackSubagent()'s log replacement does not erase the phase's activity. */ +freezeLogs(): void; +requestWorkflowDecision(payload: WorkflowDecisionPayload, signal: AbortSignal): Promise<WorkflowDecisionFeedback>; +``` + +**`server-types.ts`** gains three new event/response types: + +```typescript +export interface FrozenLogsEvent { + lines: LogLine[]; +} + +/** SSE event payload pushed to clients when the orchestrator calls + * koan_propose_workflow. Matches the subset of WorkflowDecisionPayload + * the client needs for rendering. */ +export interface WorkflowDecisionEvent { + requestId: string; + statusReport: string; + recommendedPhases: WorkflowPhaseOption[]; + completedPhase: string; +} + +/** Response from the POST /api/workflow-decision endpoint. + * Parallel to ArtifactReviewFeedback. */ +export interface WorkflowDecisionFeedback { + feedback: string; +} +``` + +**Server implementation** (inside `startWebServer`): + +```typescript +let frozenLogs: LogLine[] = []; + +// In replayState(): +if (frozenLogs.length > 0) write("frozen-logs", { lines: frozenLogs }); + +// On the handle: +freezeLogs(): void { + // Shallow copy to decouple from any future mutation of lastLogs. + // Cost is negligible: bounded to 50 entries by readRecentLogs(). + frozenLogs = [...lastLogs]; + pushEvent("frozen-logs", { lines: frozenLogs }); +}, + +// In pushPhase(): clear frozenLogs when a real phase (not orchestrator) begins. +// The orchestrator does not push a phase event, so frozenLogs persist across +// the entire orchestrator session and are only cleared when the next phase starts. +pushPhase(phase: EpicPhase): void { + frozenLogs = []; + // ... existing phase push logic +}, +``` + +#### PillStrip: phase progress display + +The PillStrip displays all eight active phases (excluding the `completed` +terminal marker, which is indicated by all pills turning done): + +```jsx +const PHASES = [ + { id: "intake", label: "intake" }, + { id: "brief-generation", label: "brief" }, + { id: "core-flows", label: "core flows" }, + { id: "tech-plan", label: "tech plan" }, + { id: "ticket-breakdown", label: "tickets" }, + { id: "cross-artifact-validation", label: "validation" }, + { id: "execution", label: "execute" }, + { id: "implementation-validation", label: "verify" }, +]; + +const PHASE_ORDER = [ + "intake", + "brief-generation", + "core-flows", + "tech-plan", + "ticket-breakdown", + "cross-artifact-validation", + "execution", + "implementation-validation", + "completed", +]; +``` + +#### StatusSidebar: phase-specific status + +The `PhaseStatus` dispatcher handles implemented phases with dedicated +components and falls through to `GenericStatus` for stub phases: + +```jsx +function PhaseStatus({ phase, intakeProgress, stories }) { + if (phase === "intake") { + return intakeProgress ? ( + <IntakeStatus progress={intakeProgress} /> + ) : ( + <GenericStatus phase={phase} /> + ); + } + switch (phase) { + case "brief-generation": + return <BriefStatus />; + default: + // Stub phases and any future phases without a dedicated widget + return <GenericStatus phase={phase} />; + } +} +``` + +#### Store: `frozenLogs` and `workflowChat` + +The store gains two new slices alongside the existing `logs`: + +```javascript +frozenLogs: [], // LogLine[] — frozen snapshot of the completed phase's activity +workflowChat: [], // WorkflowChatTurn[] — multi-turn conversation history +``` + +A `WorkflowChatTurn` is either an orchestrator proposal or a user response: + +```typescript +type WorkflowChatTurn = + | { + role: "orchestrator"; + requestId: string; + statusReport: string; + recommendedPhases: WorkflowPhaseOption[]; + } + | { role: "user"; text: string; pending?: boolean; failed?: boolean }; +``` + +`pending` is set during optimistic append (cleared on fetch success). +`failed` is set when the POST to `/api/workflow-decision` fails, enabling +a retry UI. Without error handling, a fetch failure causes +`pollIpcUntilResponse()` to block indefinitely. + +**Handlers:** + +```javascript +export function handleFrozenLogsEvent(d) { + set({ frozenLogs: d.lines }); +} + +// Each new workflow-decision event appends an orchestrator turn. +// Independent of any existing turn — multi-turn is handled by accumulation, +// not replacement. +// +// NOTE: workflow-decision does NOT set pendingInput. Setting it would toggle +// isInteractive=true, switching to PhaseContent and hiding the ActivityFeed +// where the WorkflowChat lives. This is intentional and unlike all other +// interaction types (ask, review, artifact-review, model-config). +export function handleWorkflowDecisionEvent(d) { + set((s) => ({ + workflowChat: [ + ...s.workflowChat, + { + role: "orchestrator", + requestId: d.requestId, + statusReport: d.statusReport, + recommendedPhases: d.recommendedPhases, + }, + ], + })); +} + +export function handleWorkflowDecisionCancelledEvent(d) { + // Remove the pending orchestrator turn by requestId + set((s) => ({ + workflowChat: s.workflowChat.filter( + (t) => !(t.role === "orchestrator" && t.requestId === d.requestId), + ), + })); +} +``` + +**`workflowChat` and `frozenLogs` are cleared on phase transition and pipeline end:** + +```javascript +export function handlePhaseEvent(d) { + set({ + phase: d.phase, + frozenLogs: [], // phase's frozen activity no longer needed + workflowChat: [], // conversation belongs to the previous transition + ...(d.phase !== "intake" && { pendingInput: null, intakeProgress: null }), + }); +} + +export function handlePipelineEndEvent(d) { + set((s) => ({ + phase: d.success ? "completed" : s.phase, + pipelineEnd: d, + intakeProgress: null, + frozenLogs: [], + workflowChat: [], + })); +} +``` + +#### Server: `requestWorkflowDecision()` and SSE replay + +`workflowDecision` is stored in `pendingInputs` with `type: "workflow-decision"` +— identical to how `artifact-review` is stored. This is essential for **SSE +replay**: `replayState()` iterates `pendingInputs` to replay all pending +interactions for reconnecting browsers. Each `requestWorkflowDecision()` call +is independent; the client accumulates turns from successive `workflow-decision` +SSE events. + +`replayState()` gains one branch: + +```typescript +} else if (entry.type === "workflow-decision") { + write("workflow-decision", { requestId, ...entry.payload }); +} +``` + +On reconnect the client receives the full conversation history via `frozen-logs` +(replayed from `frozenLogs` buffer) and then the currently-pending +`workflow-decision` event, which it appends to `workflowChat`. + +#### App.jsx changes + +`workflowChat` and `frozenLogs` are **absent from `isInteractive`** — the +three-column workspace stays active. `token` is passed to `ActivityFeed`: + +```jsx +const isInteractive = + !phase || pending || showSettings || phase === "completed"; +// workflowChat / frozenLogs do not affect isInteractive + +{ + isInteractive ? ( + <div class="phase-content"> + <PhaseContent token={token} topic={topic} /> + </div> + ) : ( + <ActivityFeed token={token} /> + ); +} +``` + +#### ActivityFeed.jsx + +`ActivityFeed` accepts `token` and renders all four zones. The separator and +`WorkflowChat` appear only when `frozenLogs` is non-empty (i.e., an orchestrator +session is active): + +```jsx +export function ActivityFeed({ token }) { + const logs = useStore((s) => s.logs); + const frozenLogs = useStore((s) => s.frozenLogs); + const workflowChat = useStore((s) => s.workflowChat); + const streamingText = useStore((s) => s.streamingText); + // ... scroll/flash logic unchanged ... + + const hasOrchestratorSession = frozenLogs.length > 0; + + return ( + <div class="activity-feed-scroll" ref={containerRef} onScroll={onScroll}> + <div class="activity-feed-inner"> + {/* Zone 1: frozen phase activity */} + {hasOrchestratorSession && + frozenLogs.map((line, i) => + renderLine(line, false, false, `frozen-${i}`, true /* dimmed */), + )} + + {/* Zone 2: orchestrator session separator */} + {hasOrchestratorSession && ( + <div class="workflow-separator"> + <span class="workflow-separator-label">Evaluating workflow...</span> + </div> + )} + + {/* Zone 3: live orchestrator tool calls */} + {logs.map((line, i) => { + const isInFlight = !!line.inFlight && i === logs.length - 1; + const isFlashing = i === flashIndex; + return renderLine(line, isInFlight, isFlashing, `live-${i}`, false); + })} + + {/* Zone 4: WorkflowChat thread */} + {workflowChat.length > 0 && ( + <WorkflowChat turns={workflowChat} token={token} /> + )} + </div> + </div> + ); +} +``` + +#### WorkflowChat component + +`WorkflowChat` renders the full conversation thread and a text input for the +next user response. It only shows the input when the last turn is an +orchestrator proposal (i.e., awaiting user response). Once the user submits, +their turn is appended immediately client-side while the orchestrator processes +the response; when the next `workflow-decision` SSE event arrives it is appended +as the next orchestrator turn. + +```jsx +function WorkflowChat({ turns, token }) { + const [input, setInput] = useState(""); + const [submitting, setSubmitting] = useState(false); + + const lastTurn = turns[turns.length - 1]; + const awaitingUser = lastTurn?.role === "orchestrator"; + + function selectPhase(phase) { + // Pre-fill rather than auto-submit. Lets the user add context before + // sending: "Proceed with core-flows, but focus on auth requirements" + setInput(`Proceed with ${phase.label}`); + } + + async function submit() { + if (submitting || !input.trim() || !awaitingUser) return; + setSubmitting(true); + + // Append user turn immediately for responsive feedback. The store will + // receive the next orchestrator turn from SSE when it arrives. + // Mark the turn as pending so the UI can show a sending indicator. + const userText = input.trim(); + useStore.setState((s) => ({ + workflowChat: [ + ...s.workflowChat, + { role: "user", text: userText, pending: true }, + ], + })); + setInput(""); + + try { + await fetch("/api/workflow-decision", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + token, + requestId: lastTurn.requestId, + feedback: userText, + }), + }); + // Mark the user turn as delivered. + useStore.setState((s) => ({ + workflowChat: s.workflowChat.map((t) => + t.role === "user" && t.pending ? { ...t, pending: false } : t, + ), + })); + } catch (err) { + // Mark turn as failed so user can retry. Without this, the pipeline + // hangs at pollIpcUntilResponse() indefinitely. + useStore.setState((s) => ({ + workflowChat: s.workflowChat.map((t) => + t.role === "user" && t.pending + ? { ...t, pending: false, failed: true } + : t, + ), + })); + } finally { + setSubmitting(false); + } + } + + return ( + <div class="workflow-chat"> + {turns.map((turn, i) => + turn.role === "orchestrator" ? ( + <OrchestratorTurn + key={i} + turn={turn} + onSelect={selectPhase} + isLatest={i === turns.length - 1} + /> + ) : ( + <UserTurn + key={i} + turn={turn} + onRetry={(text) => { + setInput(text); + }} + /> + ), + )} + + {awaitingUser && ( + <div class="workflow-chat-input"> + <textarea + class="workflow-feedback" + placeholder="Type instructions or feedback, or click an option above..." + value={input} + onInput={(e) => setInput(e.target.value)} + disabled={submitting} + /> + <div class="form-actions"> + <button + class="btn btn-primary" + onClick={submit} + disabled={submitting || !input.trim()} + > + Continue → + </button> + </div> + </div> + )} + </div> + ); +} + +function OrchestratorTurn({ turn, onSelect, isLatest }) { + return ( + <div class="workflow-turn workflow-turn-orchestrator"> + <div class="workflow-turn-header"> + <span class="workflow-turn-role">workflow orchestrator</span> + </div> + <div + class="workflow-turn-body" + dangerouslySetInnerHTML={{ __html: marked.parse(turn.statusReport) }} + /> + {/* Only show phase options on the latest orchestrator turn */} + {isLatest && ( + <div class="workflow-options"> + {turn.recommendedPhases.map((p) => ( + <button + class={`workflow-option${p.recommended ? " recommended" : ""}`} + onClick={() => onSelect(p)} + > + <span class="workflow-option-label">{p.label}</span> + <span class="workflow-option-context">{p.context}</span> + </button> + ))} + </div> + )} + </div> + ); +} + +function UserTurn({ turn, onRetry }) { + return ( + <div + class={`workflow-turn workflow-turn-user${turn.failed ? " workflow-turn-failed" : ""}`} + > + <span class="workflow-turn-body">{turn.text}</span> + {turn.pending && <span class="workflow-turn-status">Sending...</span>} + {turn.failed && ( + <div class="workflow-turn-error"> + <span>Failed to send.</span> + <button class="btn btn-sm" onClick={() => onRetry(turn.text)}> + Retry + </button> + </div> + )} + </div> + ); +} +``` + +### 9. `workflow-status.md` (Driver-Generated Context File) + +Before spawning the workflow orchestrator, the driver writes +`{epicDir}/workflow-status.md`. The driver writes this (not an LLM) for two +reasons: (1) it has authoritative phase history — inferring it from artifact +timestamps would be unreliable; (2) the file boundary invariant requires the +LLM to receive markdown, so the driver bridges its internal JSON knowledge +into a markdown document. + +**`writeWorkflowStatus()`** lives in `driver.ts` (co-located with +`runWorkflowOrchestrator` which calls it). It derives the completed phase from +the `completedPhase` argument and discovers artifacts by scanning `epicDir` for +known filenames. The `availablePhases` come from the DAG successors passed by +the caller. + +```typescript +import { listArtifacts } from "../epic/artifacts.js"; + +/** Write {epicDir}/workflow-status.md — a markdown bridge from driver JSON + * state to the orchestrator LLM's context. Called before orchestrator spawn. + * + * completedPhase is the single just-completed phase (not a history). + * The driver does not maintain a phase history array; the orchestrator + * infers prior phases from the artifacts present in epicDir. */ +async function writeWorkflowStatus( + epicDir: string, + completedPhase: EpicPhase, + availablePhases: readonly EpicPhase[], +): Promise<void> { + // listArtifacts() already exists in epic/artifacts.ts — returns ArtifactEntry[] + // with { path, size, modifiedAt }. path is relative to epicDir. + const artifacts = await listArtifacts(epicDir); + const lines = [ + "# Workflow Status", + "", + "## Current Position", + "", + `The **${completedPhase}** phase has just completed.`, + "", + "## Available Next Phases", + "", + ...availablePhases.map((p) => `- **${p}** — ${PHASE_DESCRIPTIONS[p]}`), + "", + "## Artifacts Available", + "", + ...artifacts.map((a) => `- \`${a.path}\``), + ]; + await fs.writeFile( + path.join(epicDir, "workflow-status.md"), + lines.join("\n"), + "utf8", + ); +} +``` + +Note: `PHASE_DESCRIPTIONS` is a `Record<EpicPhase, string>` constant co-located +with `PHASE_TRANSITIONS` in `lib/phase-dag.ts`. It maps each phase to a +one-line human-readable description (e.g., `"core-flows": "Define user journeys +with sequence diagrams"`). + +**Example output** (after intake completes): + +```markdown +# Workflow Status + +## Current Position + +The **intake** phase has just completed. + +## Available Next Phases + +- **brief-generation** — Distill intake context into a compact product-level epic brief +- **core-flows** — Define user journeys with sequence diagrams + +## Artifacts Available + +- `landscape.md` — Intake findings and codebase analysis +``` + +### 10. Permissions + +```typescript +["workflow-orchestrator", new Set([ + "koan_complete_step", + "koan_propose_workflow", + "koan_set_next_phase", + // No koan_ask_question — koan_propose_workflow handles user interaction + // No koan_request_scouts — orchestrator reads existing artifacts only + // No write/edit — orchestrator routes, it does not produce artifacts +])], +``` + +`"workflow-orchestrator"` is added to `PLANNING_ROLES` so any future write +tools are automatically path-scoped to the epic directory. + +--- + +## Codebase Touchpoints + +The phase registry change (`EpicPhase` update) requires updates across the +codebase. All sites that reference old phase identifiers must be updated to use +the canonical identifiers. The following is an exhaustive list based on +codebase analysis. + +### Phase identifier sites (old → new) + +| File | Line(s) | Old identifier | New identifier | Notes | +| ------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------- | +| `src/planner/types.ts` | 55 | `"intake" \| "brief" \| "decomposition" \| "review" \| "executing" \| "completed"` | Full 8-phase union + `"completed"` | Core type definition | +| `src/planner/driver.ts` | 337–426 | Linear `intake → brief → decomposition → review → executing → completed` pipeline | DAG-driven loop with stub handling | Full `runPipeline()` rewrite | +| `src/planner/driver.ts` | 124 | `role: "intake" \| "brief-writer" \| "decomposer"` | Phase-to-role mapping via `PHASE_ROLE` | `runSimplePhase` type | +| `src/planner/epic/types.ts` | 53 | `phase: "intake"` in `createInitialEpicState` | No change (intake stays) | — | +| `src/planner/web/js/components/PillStrip.jsx` | 3–11 | `PHASES` array with `decomposition`, `review`, `executing` | 8-phase array | See §8 | +| `src/planner/web/js/components/PillStrip.jsx` | 13 | `PHASE_ORDER` array | 8 phases + `completed` | See §8 | +| `src/planner/web/js/components/StatusSidebar.jsx` | 107–112 | `case 'brief'`, `case 'decomposition'`, `case 'executing'` | `case 'brief-generation'` + generic fallthrough | `DecomposeStatus` and `ExecuteStatus` components removed | +| `src/planner/web/js/components/App.jsx` | 33 | `phase === 'completed'` | No change (`completed` terminal marker stays) | — | +| `src/planner/web/js/components/PhaseContent.jsx` | 21 | `phase === 'completed'` | No change | — | +| `src/planner/web/js/store.js` | 82 | `phase: d.success ? 'completed' : s.phase` | No change | — | +| `src/planner/web/js/components/ModelConfig.jsx` | ~line with "task decomposition" | Old terminology in model tier description | Update to "task planning" | Cosmetic | + +### Old driver code to remove + +The following code in `driver.ts` is replaced by the DAG-driven loop: + +- **Lines 353–354**: `phase: "decomposition"` / `pushPhase("decomposition")` +- **Lines 356–369**: Decomposer invocation, story discovery, `ensureStoryDirectory` +- **Lines 370–371**: `phase: "review"` / `pushPhase("review")` +- **Lines 373–415**: Spec review gate (`webServer.requestReview()`, review story loading, skip handling) +- **Lines 418–419**: `phase: "executing"` / `pushPhase("executing")` +- **Lines 420–426**: Story loop invocation, `phase: "completed"` + +**Note:** The story loop infrastructure (`runStoryLoop`, `runStoryExecution`, +`runStoryReexecution`, `routeFromState`) and associated subagent roles +(orchestrator, planner, executor) remain in the codebase. They are not invoked +by the pipeline but will be used when the `execution` phase is implemented. +Similarly, the decomposer phase class (`phases/decomposer/`) remains for future +use by the `ticket-breakdown` phase. No phase classes are deleted. + +### Spec review gate: full deletion + +The spec review gate was development scaffolding. All associated code is +deleted (not retained as dormant code): + +| File | Code to delete | +| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `web/server-types.ts` | `ReviewStory`, `ReviewResult` types; `requestReview()` on `WebServerHandle` | +| `web/server.ts` | `requestReview()` implementation; `POST /api/review` endpoint; `"review"` branch in `replayState()`; review entries in `pendingInputs` | +| `web/js/store.js` | Review-related state and handlers | +| `web/js/sse.js` | `"review"` and `"review-cancelled"` event routing | +| `web/js/components/forms/ReviewForm.jsx` | Entire file | +| `web/js/components/PhaseContent.jsx` | Review rendering branch | +| `web/css/components.css` | `.review-*` styles | + +A future `cross-artifact-validation` phase will use a different mechanism +(likely artifact-review IPC, not the batch review UI). + +### Documentation updates + +| File | Section | Change | +| ---------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENTS.md` | Pipeline phases line | `intake → brief-generation → core-flows → tech-plan → ticket-breakdown → cross-artifact-validation → execution → implementation-validation` | +| `docs/state.md` | Epic phases table | Replace 6-phase table with 8-phase table | +| `docs/state.md` | `EpicPhase` comment | Update type union in code block | +| `docs/state.md` | Spec review gate section | Note: moved to `execution` phase (future) | +| `docs/state.md` | Audit projection `phase` field | Update example values | +| `docs/epic-brief.md` | Pipeline references | Update `intake → brief → decomposition → …` references | +| `docs/architecture.md` | Phase references | Update any phase enumeration | + +### Not phase identifiers (no change needed) + +These use the string `"completed"` or `"executing"` in non-phase contexts: + +| File | Context | Why no change | +| ------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------- | +| `src/planner/tools/ask.ts:268` | `PollOutcome` switch case | IPC poll outcome, not epic phase | +| `src/planner/lib/ipc.ts:198,240` | `PollOutcome` type | IPC poll outcome, not epic phase | +| `src/planner/lib/audit-events.ts:53,118` | `outcome: "completed"` | Audit event outcome, not epic phase | +| `src/planner/lib/event-log.ts:186` | `emitPhaseEnd("completed")` | Phase end outcome, not phase name | +| `src/planner/phases/base-phase.ts:175` | `emitPhaseEnd("completed")` | Phase end outcome, not phase name | +| `src/planner/lib/ipc-responder.ts:227` | `status === "completed"` | Scout projection status, not epic phase | +| `src/planner/driver.ts:183,296` | `status: "executing"` | `StoryStatus`, not `EpicPhase` | +| `src/planner/web/server-types.ts:220,239` | `status: "running" \| "completed" \| "failed"` | Agent/pipeline status, not epic phase | +| `src/planner/web/server.ts:196` | `status: "running" \| "completed" \| "failed"` | Agent status, not epic phase | +| `src/planner/web/server.ts:273,391,719,957` | `type: "review"` | IPC interaction type for spec review, not phase name | +| `tests/state-machine.test.ts:152,216` | `"executing"` in story status tests | `StoryStatus`, not `EpicPhase` | + +--- + +## Implementation Order + +Batches are ordered for **compile-time correctness**: each batch compiles +without errors given all prior batches. Batches 1+2 are explicitly atomic — +Batch 1 removes `EpicPhase` values that `driver.ts` still references, so +Batch 2 must land in the same commit. Similarly, Batch 3A (server-types.ts +type declarations) is split out before Batch 3B (ipc-responder) because +`handleWorkflowDecisionRequest` calls `requestWorkflowDecision()` on +`WebServerHandle`, which must exist as a type before the handler compiles. + +### Batch 1+2: Phase Registry + Driver Refactor (atomic — single commit) + +**These two batches MUST land together.** Batch 1 removes `"brief"`, +`"decomposition"`, `"review"`, and `"executing"` from `EpicPhase`; Batch 2 +rewrites the driver code that references them. Neither compiles alone. + +1. **`lib/phase-dag.ts`** — New file. `PHASE_TRANSITIONS` with 8 phases, + `IMPLEMENTED_PHASES`, `PHASE_DESCRIPTIONS`, `getSuccessorPhases()`, + `isAutoAdvance()`, `isStubPhase()`, `isValidTransition()`. + +2. **`types.ts`** — Replace `EpicPhase` with 8-phase union + `"completed"`. + Rename `"brief"` → `"brief-generation"`. Remove `"decomposition"`, + `"review"`, `"executing"`. Add `"core-flows"`, `"tech-plan"`, + `"ticket-breakdown"`, `"cross-artifact-validation"`, `"execution"`, + `"implementation-validation"`. Add `"workflow-orchestrator"` to + `SubagentRole` and `ROLE_MODEL_TIER`. + +3. **`lib/task.ts`** — Add `WorkflowOrchestratorTask` interface and add it to + the `SubagentTask` discriminated union. Add optional + `phaseInstructions?: string` to `SubagentTaskBase`. + +4. **`lib/permissions.ts`** — Add `"workflow-orchestrator"` role entry. + +5. **`epic/types.ts`** — Add `WorkflowDecisionState` interface. + +6. **`driver.ts`** — Replace linear `runPipeline()` with DAG-driven loop. + Add `PHASE_ROLE` mapping. Add `isStubPhase()` handling for stubs. + Add `writeWorkflowStatus()`. Add `runWorkflowOrchestrator()`. + Remove decomposer invocation, story discovery, spec review gate, and + story loop from the main pipeline path. Keep `runStoryLoop()`, + `runStoryExecution()`, `runStoryReexecution()`, `routeFromState()` as + dormant code for future `execution` phase use. Add headless guard for + multi-successor DAGs. `runSimplePhase()` gains `phaseInstructions?`. + `runPhase()` returns `boolean` for per-phase error checking. + +7. **`epic/state.ts`** — Add `readWorkflowDecision(subagentDir)` helper. + +8. **`web/js/components/PillStrip.jsx`** — Replace `PHASES` and `PHASE_ORDER` + with 8-phase arrays using new identifiers. (Must land with EpicPhase rename.) + +9. **`web/js/components/StatusSidebar.jsx`** — Update `PhaseStatus` switch: + rename `'brief'` → `'brief-generation'`, remove `'decomposition'` and + `'executing'` cases, remove `DecomposeStatus` and `ExecuteStatus` components. + Remove `phase === 'review'` branch from `GenericStatus`. + Stub phases fall through to `GenericStatus`. + +10. **`web/js/components/PhaseContent.jsx`** — Remove review rendering branch + (part of spec review gate deletion). + +### Batch 3A: Server Types (pure type declarations — no behavior) + +These are type-only additions that must exist before Batch 3B's +`ipc-responder.ts` changes can compile. + +11. **`web/server-types.ts`** — Add `FrozenLogsEvent`, `WorkflowDecisionEvent`, + `WorkflowDecisionFeedback`; add `freezeLogs()` and `requestWorkflowDecision` + to `WebServerHandle`. Add `"workflow-decision"` to `PendingEntry.type` union. + +### Batch 3B: IPC + Tools + +12. **`lib/ipc.ts`** — Add `WorkflowDecisionIpcFile` with `WorkflowDecisionResponse` + carrying `id`, `respondedAt`, `feedback` (matching `ArtifactReviewResponse` + convention). Add factory helper. Update `IpcFile` union. Add + `"workflow-decision"` branch to `pollIpcUntilResponse` — required: without + it, `koan_propose_workflow` polls forever and the pipeline hangs. + +13. **`tools/workflow-decision.ts`** — New file. `koan_propose_workflow` + (IPC write + poll + return text) and `koan_set_next_phase` (reads + `task.json` via `readTaskFile(ctx.subagentDir)`, narrows to + `WorkflowOrchestratorTask` via `task.role === "workflow-orchestrator"`, + validates, writes `workflow-decision.json` to subagentDir). + +14. **`lib/ipc-responder.ts`** — Add `handleWorkflowDecisionRequest`. Add + dispatch case in `runIpcResponder`'s if-chain. + +15. **`extensions/koan.ts`** — Register the two new tools. + +### Batch 4: Phase Class + +16. **`phases/workflow-orchestrator/phase.ts`** — `WorkflowOrchestratorPhase` + with 2-step structure and `validateStepCompletion` gate (enforces both + `proposalMade` and `nextPhaseSet`). Use `event.isError` + (matching `ReviewablePhase` convention, not `event.error`). + +17. **`phases/workflow-orchestrator/prompts.ts`** — System prompt and step + guidance (`availablePhases` injected in step 2 from task manifest). + +18. **`phases/dispatch.ts`** — Add `"workflow-orchestrator"` case. The case + reads `task as WorkflowOrchestratorTask` and passes + `{ completedPhase: task.completedPhase, availablePhases: task.availablePhases }` + as the config argument to the `WorkflowOrchestratorPhase` constructor. + +### Batch 5: Web Server + UI + +19. **`web/server.ts`** — Add `frozenLogs` buffer. `freezeLogs()` snapshots + `[...lastLogs]` → `frozenLogs` and pushes `"frozen-logs"` SSE event. Add + `"frozen-logs"` branch in `replayState()`. `requestWorkflowDecision()` stores + in `pendingInputs` with `type: "workflow-decision"` (required for SSE replay). + Add POST `/api/workflow-decision`. Add `"workflow-decision"` branch in + `replayState()`. Push `"workflow-decision-cancelled"` SSE event on abort. + Clear `frozenLogs` in `pushPhase()`. Call `webServer.freezeLogs()` before + spawning orchestrator (driven from driver via the handle). + +20. **`web/js/store.js`** — Add `frozenLogs: []` and `workflowChat: []` slices. + Add `handleFrozenLogsEvent`, `handleWorkflowDecisionEvent`, + `handleWorkflowDecisionCancelledEvent`. Update `handlePhaseEvent` to clear + both. Update `handlePipelineEndEvent` to clear both. + +21. **`web/js/sse.js`** — Add routing for `'frozen-logs'`, `'workflow-decision'`, + `'workflow-decision-cancelled'`. + +22. **`web/js/components/App.jsx`** — Pass `token` prop to `ActivityFeed`. + Confirm `workflowChat` and `frozenLogs` are absent from `isInteractive`. + Add comment explaining the intentional asymmetry: workflow-decision is the + only interaction type that does NOT set `pendingInput`. + +23. **`web/js/components/ActivityFeed.jsx`** — Accept `token` prop. Render four + zones: frozen logs (dimmed), orchestrator separator, live logs, `WorkflowChat`. + Separator and `WorkflowChat` appear only when `frozenLogs.length > 0`. + +24. **`web/css/components.css`** — Styles for: `.activity-line-frozen` (dimmed + opacity), `.workflow-separator` (centered divider line + label), `.workflow-chat`, + `.workflow-turn`, `.workflow-turn-orchestrator`, `.workflow-turn-user`, + `.workflow-turn-failed` (error indicator), `.workflow-turn-status` (sending + indicator), `.workflow-turn-error` (retry button container), + `.workflow-options`, `.workflow-option`, `.workflow-feedback`. + +### Batch 6: Phase guidance threading + +25. **`lib/runtime-context.ts`** — Add `phaseInstructions?: string` to + `RuntimeContext` interface. + +26. **`extensions/koan.ts`** — In `before_agent_start`, after `readTaskFile`, + set `ctx.phaseInstructions = task.phaseInstructions`. + +27. **Phase guidance functions** — Add `phaseInstructions` parameter to step 1 + guidance functions in: `phases/intake/phase.ts` (pass `this.ctx.phaseInstructions` + to `intakeStepGuidance`), `phases/brief-writer/phase.ts` (pass to + `briefWriterStepGuidance`), and the corresponding `prompts.ts` files. + (Remaining phase guidance functions will be added when their phases are + implemented.) + +### Batch 7: Documentation + +28. **`AGENTS.md`** — Update pipeline phases line to 8-phase sequence. + +29. **`docs/state.md`** — Replace phase table and `EpicPhase` code blocks. + Update spec review gate section. Update audit projection examples. + +30. **`docs/epic-brief.md`** — Update pipeline references (`intake → +brief-generation → …`). + +31. **`docs/architecture.md`** — Update pipeline description, add workflow + orchestrator section. + +### Batch 8: Tests + +32. **`tests/state-machine.test.ts`** — Update any tests that reference + `EpicPhase` values. Note: tests referencing `StoryStatus` `"executing"` are + unaffected (story status is separate from epic phase). + +33. **Phase DAG tests** — New test file for `lib/phase-dag.ts`: test + `getSuccessorPhases`, `isAutoAdvance`, `isStubPhase`, `isValidTransition` + with both single-successor and multi-successor configurations. + +--- + +## Invariant Compliance + +| Invariant | How this design complies | +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **1. File boundary** | Orchestrator reads markdown (`workflow-status.md`, artifacts). `koan_set_next_phase` bridges both: receives LLM input, writes `workflow-decision.json` to subagentDir for the driver to read after exit. | +| **2. Step-first workflow** | `WorkflowOrchestratorPhase` follows the identical boot-prompt pattern. Boot prompt: one sentence. Step guidance arrives via the first `koan_complete_step` return value. | +| **3. Driver determinism** | Driver reads `workflow-decision.json` for the next phase. DAG validation is a pure function. Stub detection is a set lookup. The driver never parses orchestrator text output. | +| **4. Default-deny permissions** | `"workflow-orchestrator"` has its own `ROLE_PERMISSIONS` entry with only three tools. Unknown roles are blocked. | +| **5. Need-to-know prompts** | Boot prompt is one sentence. Available phases arrive via step 2 guidance (from `task.json`). Phase history arrives via `workflow-status.md` in step 1. | +| **6. Directory-as-contract** | `task.json` carries `completedPhase` and `availablePhases`. IPC uses `ipc.json`. Decision persisted in `workflow-decision.json` — all three files live in the subagent directory. `koan_set_next_phase` reads `availablePhases` from `task.json` and writes the decision to the same directory. The driver reads the decision from the subagent directory after the orchestrator exits. | + +--- + +## Risks and Mitigations + +| Risk | Mitigation | +| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Orchestrator exits without calling `koan_set_next_phase` | `validateStepCompletion(2)` blocks `koan_complete_step` unless both `proposalMade` and `nextPhaseSet` are true. If process crashes (non-zero exit), `runWorkflowOrchestrator()` returns `null` and the driver returns `{ success: false }`. | +| Orchestrator skips user interaction (calls `koan_set_next_phase` without `koan_propose_workflow`) | `validateStepCompletion(2)` checks `proposalMade` flag — set only on successful `koan_propose_workflow` call. Gate returns error message directing the LLM to call `koan_propose_workflow` first. | +| `WorkflowChat.submit()` fetch failure leaves pipeline hanging | `submit()` wraps fetch in try/catch. On failure, the user turn is marked `failed: true` and a retry UI is shown. Without this, `pollIpcUntilResponse()` blocks indefinitely. | +| User provides ambiguous feedback cycling indefinitely | `koan_propose_workflow` may be called multiple times; loop terminates only at `koan_set_next_phase`. Same pattern as `koan_review_artifact`, which has not required a loop guard in practice. | +| Token cost on single-successor DAGs | `isAutoAdvance()` short-circuits before any orchestrator spawn. Zero cost for deterministic transitions. | +| Token cost on stub phases | `isStubPhase()` short-circuits before any subagent spawn. Stubs are a log line and a state write — no LLM cost. | +| `pollIpcUntilResponse` missing `workflow-decision` branch | Addressed explicitly in Batch 3B item 12. Without it, `koan_propose_workflow` polls forever — pipeline hangs indefinitely on every multi-successor transition. | +| Headless mode (no webServer) with multi-successor DAG | `runPipeline()` guards: when `webServer` is null and `successors.length > 1`, auto-advance to `successors[0]` with log warning. Without the web server the IPC responder does not run and `koan_propose_workflow` would poll forever. | +| `frozenLogs` growing large for long-running phases | `frozenLogs` is a snapshot of `lastLogs`, which is bounded by `readRecentLogs(dir, 50)` in `trackSubagent()`. Maximum 50 entries regardless of phase duration. | +| `workflowChat` state desync on browser reconnect | `replayState()` replays the pending `workflow-decision` event; client appends it to `workflowChat` as a fresh orchestrator turn. Prior turns (already-responded) are not replayed — they are gone on reconnect. This is acceptable: the user can read the active proposal and the thread restores from the current pending turn forward. | +| User submits while orchestrator is still processing previous response | The `WorkflowChat` input is only active when `lastTurn.role === 'orchestrator'`. Once the user submits, the turn appends and the input is hidden until the next `workflow-decision` SSE event arrives. | +| Stale `workflowChat` or `frozenLogs` persists after cancellation | `handlePhaseEvent` and `handlePipelineEndEvent` clear both slices. Server-side cancel rejects `pendingInputs` entries, pushing `"workflow-decision-cancelled"` → client removes the pending orchestrator turn from `workflowChat`. | +| SSE replay loses active workflow decision on browser reconnect | `requestWorkflowDecision()` stores in `pendingInputs` (same as `artifact-review`). `replayState()` includes a `"workflow-decision"` branch. On reconnect, browser receives the payload and appends an orchestrator turn. | +| `workflow-decision.json` survives a crashed run | The subagent directory label includes a timestamp (`workflow-orch-${completedPhase}-${Date.now()}`), ensuring each invocation gets a fresh directory. No stale decision file from a previous run is ever read. | +| `koan_set_next_phase` proposes a phase not in `availablePhases` | Tool validates against `availablePhases` from `task.json`. `isValidTransition()` provides a second guard at the driver level after the orchestrator exits. | +| Future phase additions introduce invalid transitions | `isValidTransition()` validates at the tool level. TypeScript exhaustive checking on `EpicPhase` catches missing DAG entries at compile time. The DAG constant handles transition edges; the Phase Promotion Checklist (§Phase Transition DAG) enumerates all other files that need updating when promoting a stub. | +| Dormant story loop code drifts from the codebase | Story loop code (`runStoryLoop`, `runStoryExecution`, etc.) is retained but unreachable from the main pipeline. When the `execution` phase is implemented, these functions will be the starting point. Keeping them avoids re-implementing proven infrastructure. | From 650b26759ab8f24b2855788b88a6d179e47b0741 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Tue, 31 Mar 2026 21:14:16 +0700 Subject: [PATCH 239/412] =?UTF-8?q?plan:=20symmetric=20folds=20=E2=80=94?= =?UTF-8?q?=20add=20motivation,=20rationale,=20migration,=20doc=20updates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Motivation/Bug Report: concrete user-visible bugs (fragmented thinking, scout events in primary feed) that triggered the plan - Every decision now has explicit rationale (why buffers in projection, why koan MCP filtering in fold, why snake_case fields, etc.) - ConversationEntry edge cases documented (multi-tool turns, partial thinking at snapshot, koan MCP filtering, bootstrap step skip) - Migration section: snapshot format change, no on-disk migration needed, client version detection behaviour - Documentation Updates section: exact changes needed in projections.md, architecture.md, projections.py, store/index.ts, AGENTS.md - Notes that 'Why tool events are generic' in projections.md is superseded by the new typed tool events --- .../2026-03-31-symmetric-projection-folds.md | 284 +++++++++++++----- 1 file changed, 209 insertions(+), 75 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index e9b30e3..5813b2a 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -6,6 +6,20 @@ --- +## Motivation / Bug Report + +Two user-visible bugs triggered this plan, both manifesting on page refresh: + +**Bug 1: Fragmented thinking cards.** After refreshing the page, the primary agent's thinking was displayed as dozens of tiny individual cards — "The", "user wants", "me to call", "k", "oan_complete_step to receive", "instructions.", etc. — instead of a single merged block. During a live session, thinking tokens arrive as `thinking` SSE events and are accumulated in the frontend's `thinkingBuffer` before being flushed into a single card. On refresh, `applySnapshot` received the raw event log and created one card per event. + +**Bug 2: Scout events in the primary agent's feed.** After refresh, step headers (e.g., "step 3/3 Report") and thinking blocks from scout agents appeared in the primary agent's activity feed. The MCP server was processing a batch of scouts while the primary agent was blocked; those scouts' events were in the event log but clearly attributed to different `agent_id`s. The live `applyEvent` path correctly filters to the primary agent; `applySnapshot` did not. + +**Root cause (shared):** `activity_log` in the backend `Projection` is not a materialized view — it is a raw event append. The frontend's `applySnapshot` was forced to re-fold this raw log, duplicating fold logic that was inconsistent with the live path. + +**User statement:** "shouldn't the backend fold produce the same state that the frontend renders?" — confirmed as the correct design intent. + +--- + ## Problem Statement The backend `fold()` in `koan/projections.py` and the frontend `applyEvent()` in `frontend/src/store/index.ts` are supposed to be symmetric — they process the same events and produce the same materialized state. The client connects, receives a **snapshot** (materialized state at version N), then applies live events via its own fold. @@ -22,13 +36,11 @@ case "tool_called": }) ``` -This makes `activity_log` a **second copy of the raw event log** — not a materialized view. The frontend's `applySnapshot()` then has to re-fold this raw log into rich `ActivityEntry[]` structures (merge consecutive thinking deltas, filter to primary agent, map typed tools, compute in-flight status). This re-folding logic is separate from and inconsistent with the live `applyEvent()` fold, causing bugs: +This makes `activity_log` a **second copy of the raw event log** — not a materialized view. The frontend's `applySnapshot()` then has to re-fold this raw log into rich `ActivityEntry[]` structures (merge consecutive thinking deltas, filter to primary agent, map typed tools, compute in-flight status). This re-folding logic is separate from and inconsistent with the live `applyEvent()` fold, causing the bugs above. -- Fragmented thinking cards (each delta becomes its own card instead of being merged) -- Scout events leaking into the primary agent's activity feed (no agent filtering) -- Different entry shapes between live and recovered state +Meanwhile, the frontend's live `applyEvent()` does produce the correct rich view — but this logic is duplicated nowhere, and the snapshot path implements a buggy approximation of it. -Meanwhile, the frontend's live `applyEvent()` does produce the correct rich view — but this logic is duplicated nowhere. +**The design invariant stated in `docs/projections.md` — "Events are facts about things that happened — not state snapshots. The fold function derives state from facts" — was being violated for `activity_log`, which stored raw facts instead of derived state.** --- @@ -64,6 +76,8 @@ Meanwhile, the frontend's live `applyEvent()` does produce the correct rich view All activity events carry `agent_id` identifying which agent produced them. +**Note:** `tool_read` through `tool_ls` are typed specialisations of `tool_called`, introduced to carry structured metadata (file paths, commands, patterns) that the generic `tool_called` payload cannot express uniformly across runners. The existing `docs/projections.md` "Why tool events are generic" rationale is superseded — that rationale was written before the typed events existed. + ### Interactions (6) | Event | Payload | Description | @@ -118,61 +132,87 @@ Server sends: event: <type>\ndata: {"version": N+3, ...}\n\n (catch-up) - `since=N` (N > 0): catch-up replay of events with version > N, then live - `since=N` where N > server version: `fatal_error` event, client reloads -The snapshot is the **materialized projection state** — the client reads it directly into its store, then applies subsequent events via its local fold. +**The snapshot is the materialized projection state.** The client reads it directly into its store, then applies subsequent events via its local fold. No re-interpretation. The `since` value is the version embedded in the snapshot — the client stores it and uses it on reconnect. --- ## Target Projection Shape -The projection is the single source of truth. Backend `fold()` produces it, `get_snapshot()` serializes it, frontend `applySnapshot()` reads it, frontend `applyEvent()` updates it identically. +The projection is the single source of truth. Backend `fold()` produces it, `get_snapshot()` serializes it, frontend `applySnapshot()` reads it directly, frontend `applyEvent()` updates it identically. No field in the snapshot should require the frontend to re-fold, filter, or merge. + +### `ConversationEntry` — why this model -### Primary agent conversation +The primary agent's activity is a timeline of events: reasoning blocks, text output, tool calls, step transitions. These form a sequential conversation that the UI renders as-is. The model name `ConversationEntry` reflects this — it is one entry in that conversation. -The key insight: `activity_log` should be a **materialized conversation** — not a raw event log. The backend fold must produce the same structure the frontend renders. +The key properties of this model: + +- **Discriminated union on `type`** (`thinking`, `text`, `tool`, `step`): the frontend branch on this field to pick the right rendering component. All other fields are optional and type-specific. +- **Merged, not incremental**: a `thinking` entry holds the full accumulated thinking text, not a delta. The fold merges consecutive deltas before flushing to an entry. This is what the live path already does via `thinkingBuffer`. +- **Agent-filtered**: only primary agent entries appear in `conversation`. Scout activity is tracked on the scout's own `AgentProjection.last_tool`. +- **In-flight tracking in the model**: `in_flight: bool` on tool entries lets the frontend show spinner vs checkmark without needing a separate `completedCallIds` set. ```python class ConversationEntry(BaseModel): - """A single entry in an agent's conversation timeline.""" + """A single entry in the primary agent's conversation timeline.""" type: Literal["thinking", "text", "tool", "step"] - + # -- thinking -- - content: str | None = None # accumulated thinking text - + content: str | None = None # accumulated thinking text (all deltas merged) + # -- text -- - text: str | None = None # accumulated stream text - + text: str | None = None # accumulated stream text (all deltas merged) + # -- tool -- tool_type: str | None = None # "read", "bash", "write", "edit", "grep", "ls", "other" - tool_name: str | None = None # display name (tool_type or original name for "other") - call_id: str | None = None - in_flight: bool = False - # tool metadata (typed) + tool_name: str | None = None # display name (= tool_type, or original name for "other") + call_id: str | None = None # matched against tool_completed to clear in_flight + in_flight: bool = False # True until matching tool_completed received + # typed tool metadata — set for the relevant tool_type, None otherwise: file: str | None = None # read, write, edit - lines: str | None = None # read (e.g. "10-20") + lines: str | None = None # read line range (e.g. "10-20") command: str | None = None # bash pattern: str | None = None # grep path: str | None = None # ls - summary: str | None = None # generic tool_called fallback - + summary: str | None = None # tool_called (generic) fallback + # -- step -- step: int | None = None step_name: str | None = None total_steps: int | None = None ``` +**Edge cases covered:** +- Multiple tool calls in one turn: each produces its own entry, accumulated in order. +- Thinking before tool call: thinking buffer flushed to entry when first tool arrives. +- Text before thinking (or thinking before text): transition triggers flush of the outgoing buffer. +- Koan MCP tools (`koan_complete_step`, etc.): filtered in the fold — they produce no `ConversationEntry`. The MCP endpoint's `tool_called`/`tool_completed` events are still in the raw log but the fold ignores them for the conversation. They are authoritative sources of `agent_step_advanced`, not tool display. +- Bootstrap step (step 0→1): `agent_step_advanced` with `step < 1` produces no step entry. The step header appears only when the agent reaches a named step. +- Incomplete thinking at snapshot time: `thinking_buffer` is non-empty. The entry is NOT yet created — the buffer is in the snapshot as-is, and the `isThinking` flag is derived from `thinking_buffer.length > 0`. This is correct: the live stream will continue producing deltas into the buffer. + ### Fold rules for conversation entries -The backend fold maintains a `conversation: list[ConversationEntry]` plus two transient buffers (`thinking_buffer: str`, `stream_buffer: str`). The buffers accumulate incremental deltas; they get flushed to conversation entries on transitions: +The backend fold maintains `conversation: list[ConversationEntry]` plus two transient accumulator fields (`thinking_buffer: str`, `stream_buffer: str`). The buffers accumulate incremental deltas and are flushed to completed entries when the output type changes or when a structural event (tool call, step advance, stream end) occurs. + +**Why buffers in the projection (not the frontend only):** +The frontend's live fold already uses buffers for this purpose. Moving them to the projection means: (a) the snapshot captures mid-thought state accurately, and (b) the backend and frontend folds share the same algorithm. A client reconnecting mid-thought gets the partial thinking buffer in the snapshot and can display the live thinking card immediately. | Event | Action | |-------|--------| | `thinking` (primary agent only) | If `stream_buffer` non-empty → flush to `text` entry, clear. Append delta to `thinking_buffer`. | | `stream_delta` (primary agent only) | If `thinking_buffer` non-empty → flush to `thinking` entry, clear. Append delta to `stream_buffer`. | -| `tool_*` / `tool_called` (primary agent only) | Flush both buffers. Append typed tool entry with `in_flight=True`. Skip koan MCP tools (`koan_*`, `mcp__koan*`). | +| `tool_*` / `tool_called` (primary, non-koan) | Flush both buffers. Append typed tool entry with `in_flight=True`. | +| `tool_called` (koan MCP — `koan_*` prefix) | Ignore for conversation. Do not flush buffers. | | `tool_completed` (primary agent only) | Set `in_flight=False` on entry matching `call_id`. | -| `agent_step_advanced` (primary agent only) | Flush both buffers. Append `step` entry (skip step < 1). | +| `agent_step_advanced` (primary agent only) | Flush both buffers. If `step >= 1`: append step entry. Update step/tokens on `primary_agent`. | +| `agent_step_advanced` (scout) | Update step/tokens on scout's `AgentProjection`. No conversation entry. | | `stream_cleared` (primary agent only) | Flush both buffers. | -| Any activity event for non-primary agent | Update scout's `last_tool` (see agents section). Do NOT touch conversation. | +| Any activity event for non-primary agent | Update scout's `last_tool`. Do NOT touch `conversation` or buffers. | + +**Why primary-agent filtering is in the fold, not the frontend:** +The fold owns the semantics of what belongs in the primary agent's conversation. Scattering this logic across the frontend's snapshot reconstruction and live event paths creates inconsistency — as seen in the bugs. A single authoritative filter in the fold means both paths are correct by construction. + +**Why koan MCP tools are filtered in the fold:** +`koan_complete_step`, `koan_ask_question`, `koan_request_scouts` etc. are infrastructure calls — they drive the workflow state machine, not the primary agent's work. They have no meaningful display in the conversation timeline. Their effect is already captured by `agent_step_advanced`, `questions_asked`, and `scout_queued` events. Showing them as tool lines would be noise. The MCP endpoint still emits `tool_called`/`tool_completed` for these — that is intentional, as the raw event log preserves them for audit — but the fold does not materialize them into conversation entries. ### Full projection model @@ -181,30 +221,30 @@ class Projection(BaseModel): # -- Run state -- run_started: bool = False phase: str = "" - + # -- Agents -- primary_agent: AgentProjection | None = None scouts: dict[str, AgentProjection] = {} # keyed by agent_id queued_scouts: list[QueuedScout] = [] completed_agents: list[AgentProjection] = [] - - # -- Primary agent conversation (materialized) -- + + # -- Primary agent conversation (materialized, ready to render) -- conversation: list[ConversationEntry] = [] - thinking_buffer: str = "" # transient accumulator - stream_buffer: str = "" # transient accumulator - + thinking_buffer: str = "" # partial thinking block in progress + stream_buffer: str = "" # partial text block in progress + # -- Interactions -- active_interaction: InteractionState | None = None - + # -- Artifacts -- artifacts: dict[str, ArtifactInfo] = {} # keyed by path - + # -- Notifications -- notifications: list[NotificationEntry] = [] - + # -- Workflow completion -- completion: CompletionInfo | None = None - + # -- Configuration -- config_runners: list[RunnerInfo] = [] config_profiles: list[ProfileInfo] = [] @@ -228,20 +268,25 @@ class AgentProjection(BaseModel): output_tokens: int = 0 status: Literal["running", "done", "failed"] = "running" error: str | None = None - last_tool: str = "" # most recent tool summary for scouts + last_tool: str = "" # most recent tool summary (scouts only) ``` -Note: `status` and `last_tool` are added to the backend model. Currently `status` only exists on the frontend (`AgentInfo`). The backend `AgentProjection` should carry these so the snapshot is complete. +**Why `status`, `error`, `last_tool` move to the backend model:** +Currently these only exist on the frontend's `AgentInfo`. The snapshot would need to carry them for the agent monitor to display correct state after refresh. They are derived facts about agent state — they belong in the projection. + +**Why `label` is already in the backend `agent_spawned` payload:** +`label` carries the scout's human-readable identifier (e.g., `engine-methods`, `spec-etag`) which comes from `q["id"]` in `koan_request_scouts`. This was added to `build_agent_spawned` as part of the scout naming work. It belongs on `AgentProjection` as a display field. ### What changes | Field | Current | Target | |-------|---------|--------| | `activity_log: list[dict]` | Raw event dicts, no merging, no filtering | **Removed.** Replaced by `conversation: list[ConversationEntry]` | -| `stream_buffer: str` | Exists | Stays, but fold logic moves here from frontend | +| `stream_buffer: str` | Exists, cleared on `stream_cleared` | Stays — fold logic remains here | | (new) `thinking_buffer: str` | Frontend-only | Moves to projection — backend fold accumulates | | (new) `conversation` | Frontend-only (`activityLog`) | Backend fold produces the identical structure | | `AgentProjection.status` | Frontend-only | Backend fold sets on `agent_exited` | +| `AgentProjection.error` | Frontend-only | Backend fold sets on `agent_exited` | | `AgentProjection.last_tool` | Frontend-only | Backend fold updates on tool events for scouts | | `AgentProjection.label` | Already in backend | Already in backend ✓ | @@ -249,7 +294,7 @@ Note: `status` and `last_tool` are added to the backend model. Currently `status ## Frontend `applySnapshot` (after) -With a properly materialized projection, `applySnapshot` becomes a direct mapping: +With a properly materialized projection, `applySnapshot` becomes a direct mapping — no re-folding: ```typescript applySnapshot: (data) => { @@ -262,13 +307,13 @@ applySnapshot: (data) => { scouts: transformScouts(state.scouts), queuedScouts: state.queued_scouts, completedAgents: state.completed_agents.map(transformAgent), - - // Direct read — no re-folding needed - activityLog: state.conversation, // already the right shape + + // Direct read — no re-folding, no merging, no filtering + activityLog: state.conversation, thinkingBuffer: state.thinking_buffer, streamBuffer: state.stream_buffer, isThinking: state.thinking_buffer.length > 0, - + activeInteraction: state.active_interaction, artifacts: state.artifacts, notifications: state.notifications, @@ -288,20 +333,24 @@ No `completedCallIds` set, no `flatMap`, no thinking merging, no agent filtering ## Frontend `applyEvent` (after) -The live fold stays the same conceptually — it's already correct. But it must produce `ConversationEntry`-shaped objects that match what the backend fold produces. The `flushThinkingBuffer()` / `flushStreamBuffer()` / `flushBuffers()` helpers stay, but the entries they produce must match `ConversationEntry`: +The live fold stays the same conceptually — it's already correct. The `flushThinkingBuffer()` / `flushStreamBuffer()` / `flushBuffers()` helpers stay. The entries they produce must match `ConversationEntry` field names exactly: ```typescript -// Flush thinking buffer → ConversationEntry of type "thinking" +// Flush thinking buffer → ConversationEntry type "thinking" { type: "thinking", content: thinkingBuffer } -// Flush stream buffer → ConversationEntry of type "text" +// Flush stream buffer → ConversationEntry type "text" { type: "text", text: streamBuffer } -// Tool event → ConversationEntry of type "tool" +// Tool event → ConversationEntry type "tool" { type: "tool", tool_type: "read", call_id: "...", in_flight: true, file: "/path" } + +// Step advance → ConversationEntry type "step" +{ type: "step", step: 3, step_name: "Ask", total_steps: 5 } ``` -The field names and shapes must match exactly between Python's `ConversationEntry.model_dump()` and TypeScript's entry objects. +**Why snake_case field names throughout:** +Pydantic's `model_dump()` produces snake_case by default. Aligning the TypeScript interface to snake_case eliminates a camelCase conversion layer at the boundary. The existing frontend convention is to accept snake_case from the API and leave conversion to individual `transformAgent()` helpers where needed; `ConversationEntry` fields are read directly from the snapshot, so they should arrive in the shape they're used. --- @@ -309,49 +358,134 @@ The field names and shapes must match exactly between Python's `ConversationEntr ### Phase 1: Backend fold produces materialized conversation -1. Define `ConversationEntry` as a Pydantic model in `koan/projections.py` -2. Add `conversation: list[ConversationEntry]`, `thinking_buffer: str`, rename/remove `activity_log` -3. Add `status`, `error`, `last_tool`, `label` to `AgentProjection` -4. Rewrite fold cases for all activity events to produce `ConversationEntry` items: +1. Define `ConversationEntry` Pydantic model in `koan/projections.py` +2. Add `conversation: list[ConversationEntry]` and `thinking_buffer: str` to `Projection`; remove `activity_log` +3. Add `status`, `error`, `last_tool` to `AgentProjection` +4. Rewrite fold cases for all activity events: - `thinking`: accumulate into `thinking_buffer` (primary only) - `stream_delta`: accumulate into `stream_buffer` (primary only) - - `tool_*` / `tool_called`: flush buffers → entries, append tool entry (primary); update `last_tool` (scout) - - `tool_completed`: set `in_flight=False` by `call_id` - - `agent_step_advanced`: flush buffers → entries, append step entry (primary); update step/tokens (any agent) - - `stream_cleared`: flush buffers - - `agent_exited`: set `status`, `error` on the agent before moving to completed -5. Update `get_snapshot()` — `model_dump()` now includes `conversation` instead of `activity_log` + - `tool_read/write/edit/bash/grep/ls`: flush buffers, append typed tool entry (primary); update `last_tool` (scout) + - `tool_called` (non-koan): flush buffers, append generic tool entry (primary); update `last_tool` (scout) + - `tool_called` (koan MCP): ignore for conversation + - `tool_completed`: set `in_flight=False` by `call_id` in `conversation` + - `agent_step_advanced`: flush buffers, append step entry if `step >= 1` (primary); update step/tokens (any agent) + - `stream_cleared`: flush both buffers + - `agent_exited`: set `status`, `error` on the agent before moving to `completed_agents` +5. Update `get_snapshot()` — no changes needed; `model_dump()` will include `conversation` automatically + +**Dependency:** Phase 1 must complete before Phase 2 — the frontend cannot read a materialized snapshot until the backend produces one. ### Phase 2: Frontend reads materialized snapshot -1. Define `ConversationEntry` TypeScript type matching the Python model exactly -2. Rewrite `applySnapshot` to directly read `conversation`, `thinking_buffer`, `stream_buffer` — remove all re-folding logic -3. `applyEvent` produces `ConversationEntry`-shaped objects (rename fields to match) -4. `ActivityFeed` renders `ConversationEntry[]` — field names may need updating +1. Define `ConversationEntry` TypeScript type in `frontend/src/store/index.ts` matching the Python model exactly (snake_case field names, same `type` discriminator values) +2. Rewrite `applySnapshot` to directly read `conversation`, `thinking_buffer`, `stream_buffer` — remove all re-folding code (the `flatMap`, `completedCallIds` set, thinking merge loop, agent filtering) +3. Update `applyEvent` to produce `ConversationEntry`-shaped objects: rename `ActivityEntry` fields to match (`thinkingContent` → `content`, `textContent` → `text`, `inFlight` → `in_flight`, etc.) +4. Update `ActivityFeed` component — it renders `ConversationEntry[]`; field names may need updating in render components ### Phase 3: Tests -1. Update backend projection fold tests — assert `conversation` entries, not raw `activity_log` dicts -2. Add specific tests for thinking merging, scout filtering, in-flight tracking in the fold -3. Verify snapshot→frontend round-trip: fold N events, take snapshot, feed to `applySnapshot`, compare with live `applyEvent` applied to same events +1. Update backend projection fold tests — assert `conversation` entries and `thinking_buffer`, not raw `activity_log` dicts +2. Add tests for: + - Thinking buffer merging (consecutive deltas → single entry content) + - Scout filtering (scout tool events update `last_tool`, not `conversation`) + - In-flight tracking (`tool_completed` sets `in_flight=False` by `call_id`) + - Koan MCP tool filtering (no conversation entry produced) + - Bootstrap step filtering (`step < 1` produces no step entry) + - Buffer flushing on transitions (thinking → text, text → thinking, either → tool) +3. Snapshot round-trip test: fold N events → `get_snapshot()` → `applySnapshot()` on fresh frontend state → compare `activityLog` with live `applyEvent()` on same events ### Phase 4: Cleanup -1. Remove `activity_log` from `Projection` -2. Remove dead `applySnapshot` re-folding code from frontend -3. Remove `ActivityEntry` type — replaced by `ConversationEntry` -4. Verify all views render correctly from snapshot recovery +1. Remove `ActivityEntry` TypeScript type — replaced by `ConversationEntry` +2. Remove dead `applySnapshot` re-folding code (now unreachable after Phase 2) +3. Update `docs/projections.md` (see Documentation Updates section) +4. Update `docs/architecture.md` (see Documentation Updates section) +5. Verify all views render correctly from snapshot recovery --- ## Risks & Decisions -- **Thinking buffer in projection**: The `thinking_buffer` is transient state that only matters for the "live tail". After snapshot recovery, it's either empty (agent isn't thinking) or has partial content (agent is mid-thought). This is correct — the snapshot captures the current state. +**Thinking buffer in projection:** +The `thinking_buffer` is transient state that only matters for the "live tail". Including it in the snapshot means a reconnecting client picks up mid-thought state correctly — the active thinking card continues rather than disappearing on reconnect. The buffer is empty after any turn completes; it only holds content while the LLM is actively reasoning. + +**Koan MCP tool filtering in fold:** +Currently filtered in the frontend's `applyEvent`. Must move to the backend fold — `tool_called` events with `koan_*` tool names should not produce conversation entries. The MCP endpoint's `begin_tool_call`/`end_tool_call` still emit these events and they remain in the raw event log (append-only invariant), but the fold skips them when building `conversation`. + +**Primary agent identification:** +The fold needs to know which `agent_id` is the primary agent to decide whether to add to `conversation` or update scout `last_tool`. The projection already has `primary_agent.agent_id`. The fold checks `agent_id == projection.primary_agent.agent_id`. + +**`ConversationEntry` field naming (snake_case):** +Must be identical between Python `model_dump()` and TypeScript. Using snake_case throughout eliminates a transformation layer and makes the snapshot-to-store path direct. The frontend's existing `ActivityEntry` uses camelCase (`inFlight`, `thinkingContent`) — these will be renamed during Phase 2. + +**Scout `last_tool` as a formatted string:** +The fold formats a human-readable string like `"read /path/to/file"` or `"bash ls -la"`. This is a display concern embedded in the fold. It avoids the frontend needing to re-derive display text from structured fields, and the monitor only needs one field to render. If more structured scout data becomes needed (e.g., separate tool type and argument for richer UI), `last_tool` can be split into `last_tool_type: str` and `last_tool_detail: str`. + +**`tool_completed` applied to completed conversation entries:** +`tool_completed` sets `in_flight=False` on the matching entry. The fold must scan `conversation` in reverse to find the matching `call_id`. This is O(n) in the number of conversation entries, but conversation length is bounded by run duration and tool calls per turn rarely exceed dozens. + +--- + +## Migration / Backwards Compatibility + +**Snapshot format change:** +The snapshot's `state` dict will no longer contain `activity_log`; it will contain `conversation`, `thinking_buffer`. Any client holding a stale connection when the server is updated will receive a `fatal_error` on their next reconnect (server version > client version), forcing a page reload. This is the existing handling for server restarts — no special migration needed. + +**Existing event logs (in-memory):** +The `ProjectionStore.events` list stores raw `VersionedEvent` objects. These are unchanged — events are facts, the fold interpretation of them changes. An in-progress run at deployment time would lose its in-memory state on restart (koan is one-shot; server restart during a run is already a failure case handled by `fatal_error`). + +**No on-disk migration:** +`activity_log` only exists in-memory in `ProjectionStore.projection`. It is not persisted to disk. The audit fold (`koan/audit/fold.py`) is independent and unaffected. + +**Client version detection:** +The snapshot includes `version: int` and the frontend's `lastVersion` drives reconnect. There is no separate schema version field. If a new client connects to an old server (unlikely in practice — koan is one-shot), the snapshot will have `activity_log` instead of `conversation`. The frontend will silently render an empty activity feed. This is acceptable: old servers don't run long. + +--- + +## Documentation Updates + +These docs must be updated as part of Phase 4: + +### `docs/projections.md` — primary updates + +1. **Projection model section:** Replace the `activity_log: list[dict]` field with `conversation: list[ConversationEntry]` and `thinking_buffer: str`. Add the full `ConversationEntry` model definition (with field docs). + +2. **Fold cases — Activity section:** Rewrite the activity fold table. Replace "append raw event to activity_log" with the actual fold rules: buffer accumulation, flush triggers, `in_flight` tracking, agent filtering, koan MCP filtering. + +3. **"Why activity_log stores raw events" design decision:** Remove this section. Replace with "Why conversation is materialized, not raw" explaining the symmetric fold invariant and the bugs it prevents. + +4. **"Why tool events are generic" design decision:** Update to reflect the typed tool events (`tool_read`, `tool_write`, etc.) that now exist. The rationale for generic `tool_called` as a fallback still applies, but the typed events are the primary path for known tools. + +5. **Event Types section:** Add the 6 typed tool events (`tool_read`, `tool_write`, `tool_edit`, `tool_bash`, `tool_grep`, `tool_ls`) and `scout_queued` which are currently missing from this doc. + +6. **`AgentProjection` model:** Add `status`, `error`, `last_tool`, `label` fields. + +### `docs/architecture.md` — add invariant + +Add a 7th core invariant (or extend Invariant 5 on projections): + +> **Symmetric fold invariant:** The backend `fold()` in `koan/projections.py` and the frontend `applyEvent()` in `frontend/src/store/index.ts` must produce the same materialized state from the same event sequence. The snapshot sent to the client is the backend's materialized projection — the client reads it directly without re-folding, filtering, or interpreting raw events. When adding a new event type, add a fold case to both implementations. + +This invariant explains why `applySnapshot` must never contain ad-hoc event re-interpretation logic — that logic belongs in the fold. + +### `koan/projections.py` — code comments + +Add a module-level docstring clarifying: +- `Projection` fields are materialized views, not raw event stores +- `conversation` is the primary agent's timeline, filtered and merged by the fold +- `thinking_buffer` and `stream_buffer` are transient accumulators — they are part of projection state because reconnecting clients need mid-turn state + +Add a comment on the `ConversationEntry` class explaining that field names are deliberately snake_case to allow direct JSON deserialization on the frontend without transformation. + +### `AGENTS.md` — no changes required -- **Koan MCP tool filtering in fold**: Currently filtered in the frontend's `applyEvent`. Must move to the backend fold — `tool_called` events with `koan_*` tool names should not produce conversation entries. The MCP endpoint's `begin_tool_call`/`end_tool_call` still emit these events for the raw event log, but the fold skips them. +The six core invariants in `AGENTS.md` do not need updating. The symmetric fold is a consequence of existing Invariant 5 (projections) and the general principle that the fold produces derived state from facts. The detail belongs in `docs/architecture.md`. -- **Primary agent identification**: The fold needs to know which `agent_id` is the primary agent to decide whether to add to conversation or update scout lastTool. The projection already has `primary_agent.agent_id`. +### `frontend/src/store/index.ts` — code comments -- **ConversationEntry field naming**: Must be identical between Python `model_dump()` and TypeScript. Use snake_case everywhere (Pydantic default). Frontend accesses `entry.call_id`, `entry.in_flight`, `entry.tool_type`, etc. +After the change, add a comment on `applySnapshot` explaining: +- The snapshot `state` is already the materialized view — no re-folding +- `conversation` maps directly to `activityLog` +- `thinking_buffer` and `stream_buffer` carry mid-turn state for reconnecting clients -- **Scout `last_tool` as a string**: The fold formats a human-readable string like `"read /path/to/file"` or `"bash ls -la"`. This is a display concern in the fold, but it's simple and avoids the frontend needing to re-derive it. +Add a comment on `applyEvent` explaining that it must produce `ConversationEntry`-shaped objects and stay in sync with the backend fold in `koan/projections.py`. From e6c22bd6c1d1dfc2014c3966671fba7b3d710760 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Tue, 31 Mar 2026 21:16:12 +0700 Subject: [PATCH 240/412] fix: agent-row-name fixed width 200px (was min/max range) --- frontend/src/styles/components.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 2a20aae..20c3119 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -212,7 +212,7 @@ .agent-row-failed { /* full opacity — errors are important */ } .agent-row-icon { width: 14px; text-align: center; flex-shrink: 0; } -.agent-row-name { min-width: 90px; max-width: 200px; flex-shrink: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } +.agent-row-name { width: 200px; flex-shrink: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .agent-row-model { width: 70px; flex-shrink: 0; color: var(--text-muted); } .agent-row-tokens { width: 60px; flex-shrink: 0; text-align: right; color: var(--text-muted); } .agent-row-time { width: 55px; flex-shrink: 0; text-align: right; color: var(--text-muted); font-size: var(--font-size-xs); } From d0266fba569c44eeaf0db99826b33ccd43474661 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 11:12:18 +0700 Subject: [PATCH 241/412] plan: split ConversationEntry into discriminated union of 10 types Decision from deepthink analysis + user confirmation: - One type per variant: ThinkingEntry, TextEntry, StepEntry, ToolReadEntry, ToolWriteEntry, ToolEditEntry, ToolBashEntry, ToolGrepEntry, ToolLsEntry, ToolGenericEntry - Each type has exactly the fields it needs (no optionals) - Pydantic discriminated union with Field(discriminator='type') - 1:1 mapping to frontend rendering components - tool_completed handled via duck-type call_id check across types --- .../2026-03-31-symmetric-projection-folds.md | 111 +++++++++++++----- 1 file changed, 79 insertions(+), 32 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index 5813b2a..8d44c9a 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -140,47 +140,94 @@ Server sends: event: <type>\ndata: {"version": N+3, ...}\n\n (catch-up) The projection is the single source of truth. Backend `fold()` produces it, `get_snapshot()` serializes it, frontend `applySnapshot()` reads it directly, frontend `applyEvent()` updates it identically. No field in the snapshot should require the frontend to re-fold, filter, or merge. -### `ConversationEntry` — why this model +### `ConversationEntry` — discriminated union of distinct types -The primary agent's activity is a timeline of events: reasoning blocks, text output, tool calls, step transitions. These form a sequential conversation that the UI renders as-is. The model name `ConversationEntry` reflects this — it is one entry in that conversation. +The primary agent's activity is a timeline of events: reasoning blocks, text output, tool calls, step transitions. These form a sequential conversation that the UI renders as-is. -The key properties of this model: +**Design decision: one type per variant, not a flat struct with optionals.** -- **Discriminated union on `type`** (`thinking`, `text`, `tool`, `step`): the frontend branch on this field to pick the right rendering component. All other fields are optional and type-specific. -- **Merged, not incremental**: a `thinking` entry holds the full accumulated thinking text, not a delta. The fold merges consecutive deltas before flushing to an entry. This is what the live path already does via `thinkingBuffer`. +Each entry type has *exactly* the fields it needs — no optional fields that only apply to other variants. This makes invalid states unrepresentable: you cannot access `.command` on a `ThinkingEntry` because the field doesn't exist. The type system enforces valid field combinations at compile time in both Python and TypeScript. + +The key properties: + +- **Discriminated union on `type`**: Pydantic's `Annotated[Union[...], Field(discriminator="type")]` serializes each variant with only its fields + discriminator. TypeScript narrows automatically on `entry.type === "tool_read"`. +- **1:1 component mapping**: Each type maps to exactly one frontend rendering component (ThinkingCard, TextBlock, StepHeader, ReadLine, BashLine, etc.). The dispatch is an exhaustive `switch(entry.type)`. +- **Merged, not incremental**: a `ThinkingEntry` holds the full accumulated thinking text, not a delta. The fold merges consecutive deltas before flushing to an entry. - **Agent-filtered**: only primary agent entries appear in `conversation`. Scout activity is tracked on the scout's own `AgentProjection.last_tool`. -- **In-flight tracking in the model**: `in_flight: bool` on tool entries lets the frontend show spinner vs checkmark without needing a separate `completedCallIds` set. +- **In-flight tracking built in**: tool entries carry `in_flight: bool` — the fold sets it `True` on creation, `False` on matching `tool_completed`. ```python -class ConversationEntry(BaseModel): - """A single entry in the primary agent's conversation timeline.""" - type: Literal["thinking", "text", "tool", "step"] - - # -- thinking -- - content: str | None = None # accumulated thinking text (all deltas merged) - - # -- text -- - text: str | None = None # accumulated stream text (all deltas merged) - - # -- tool -- - tool_type: str | None = None # "read", "bash", "write", "edit", "grep", "ls", "other" - tool_name: str | None = None # display name (= tool_type, or original name for "other") - call_id: str | None = None # matched against tool_completed to clear in_flight - in_flight: bool = False # True until matching tool_completed received - # typed tool metadata — set for the relevant tool_type, None otherwise: - file: str | None = None # read, write, edit - lines: str | None = None # read line range (e.g. "10-20") - command: str | None = None # bash - pattern: str | None = None # grep - path: str | None = None # ls - summary: str | None = None # tool_called (generic) fallback - - # -- step -- - step: int | None = None - step_name: str | None = None +class ThinkingEntry(BaseModel): + type: Literal["thinking"] = "thinking" + content: str # full accumulated thinking text + +class TextEntry(BaseModel): + type: Literal["text"] = "text" + text: str # full accumulated stream text + +class StepEntry(BaseModel): + type: Literal["step"] = "step" + step: int + step_name: str total_steps: int | None = None + +class ToolReadEntry(BaseModel): + type: Literal["tool_read"] = "tool_read" + call_id: str + in_flight: bool + file: str + lines: str = "" # optional line range "10-20" + +class ToolWriteEntry(BaseModel): + type: Literal["tool_write"] = "tool_write" + call_id: str + in_flight: bool + file: str + +class ToolEditEntry(BaseModel): + type: Literal["tool_edit"] = "tool_edit" + call_id: str + in_flight: bool + file: str + +class ToolBashEntry(BaseModel): + type: Literal["tool_bash"] = "tool_bash" + call_id: str + in_flight: bool + command: str + +class ToolGrepEntry(BaseModel): + type: Literal["tool_grep"] = "tool_grep" + call_id: str + in_flight: bool + pattern: str + +class ToolLsEntry(BaseModel): + type: Literal["tool_ls"] = "tool_ls" + call_id: str + in_flight: bool + path: str + +class ToolGenericEntry(BaseModel): + type: Literal["tool_generic"] = "tool_generic" + call_id: str + in_flight: bool + tool_name: str # original unrecognized tool name + summary: str = "" + +ConversationEntry = Annotated[ + ThinkingEntry | TextEntry | StepEntry | + ToolReadEntry | ToolWriteEntry | ToolEditEntry | + ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry, + Field(discriminator="type"), +] ``` +**`tool_completed` handling across union types:** +All 7 tool types share `call_id` and `in_flight`. The fold scans `conversation` for an entry with matching `call_id` using duck-type checking (`hasattr(entry, 'call_id')` in Python, `'callId' in entry` in TypeScript) and sets `in_flight = False`. No base class needed — this is a structural convention enforced by the fact that all tool types must have these fields. + +**Extensibility:** Adding a future `ToolWebFetchEntry` means: define the Pydantic model (4 lines), add to the union, add a fold case in Python, add a TypeScript type, add a fold case in TS, add a rendering component. Each step is mechanical. No existing types are modified. + **Edge cases covered:** - Multiple tool calls in one turn: each produces its own entry, accumulated in order. - Thinking before tool call: thinking buffer flushed to entry when first tool arrives. From e7c0b7e1494eed79d0466d8dc7c8af3a83ae6cb0 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 11:20:28 +0700 Subject: [PATCH 242/412] plan: BaseToolEntry base class for shared call_id + in_flight All tool entry types inherit from BaseToolEntry. The fold uses isinstance(entry, BaseToolEntry) for tool_completed scanning. No duck-typing needed. --- .../2026-03-31-symmetric-projection-folds.md | 35 +++++++------------ 1 file changed, 13 insertions(+), 22 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index 8d44c9a..a95e8da 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -171,47 +171,38 @@ class StepEntry(BaseModel): step_name: str total_steps: int | None = None -class ToolReadEntry(BaseModel): - type: Literal["tool_read"] = "tool_read" +class BaseToolEntry(BaseModel): + """Shared fields for all tool conversation entries.""" call_id: str in_flight: bool + +class ToolReadEntry(BaseToolEntry): + type: Literal["tool_read"] = "tool_read" file: str lines: str = "" # optional line range "10-20" -class ToolWriteEntry(BaseModel): +class ToolWriteEntry(BaseToolEntry): type: Literal["tool_write"] = "tool_write" - call_id: str - in_flight: bool file: str -class ToolEditEntry(BaseModel): +class ToolEditEntry(BaseToolEntry): type: Literal["tool_edit"] = "tool_edit" - call_id: str - in_flight: bool file: str -class ToolBashEntry(BaseModel): +class ToolBashEntry(BaseToolEntry): type: Literal["tool_bash"] = "tool_bash" - call_id: str - in_flight: bool command: str -class ToolGrepEntry(BaseModel): +class ToolGrepEntry(BaseToolEntry): type: Literal["tool_grep"] = "tool_grep" - call_id: str - in_flight: bool pattern: str -class ToolLsEntry(BaseModel): +class ToolLsEntry(BaseToolEntry): type: Literal["tool_ls"] = "tool_ls" - call_id: str - in_flight: bool path: str -class ToolGenericEntry(BaseModel): +class ToolGenericEntry(BaseToolEntry): type: Literal["tool_generic"] = "tool_generic" - call_id: str - in_flight: bool tool_name: str # original unrecognized tool name summary: str = "" @@ -223,8 +214,8 @@ ConversationEntry = Annotated[ ] ``` -**`tool_completed` handling across union types:** -All 7 tool types share `call_id` and `in_flight`. The fold scans `conversation` for an entry with matching `call_id` using duck-type checking (`hasattr(entry, 'call_id')` in Python, `'callId' in entry` in TypeScript) and sets `in_flight = False`. No base class needed — this is a structural convention enforced by the fact that all tool types must have these fields. +**`tool_completed` handling:** +All tool types inherit from `BaseToolEntry`, which carries `call_id` and `in_flight`. The fold scans `conversation` for an entry where `isinstance(entry, BaseToolEntry) and entry.call_id == target` and sets `in_flight = False` via `model_copy(update={"in_flight": False})`. On the TypeScript side, a `BaseToolEntry` interface provides the same fields, and a type guard `isToolEntry(e): e is BaseToolEntry` enables the same pattern. **Extensibility:** Adding a future `ToolWebFetchEntry` means: define the Pydantic model (4 lines), add to the union, add a fold case in Python, add a TypeScript type, add a fold case in TS, add a rendering component. Each step is mechanical. No existing types are modified. From 877e8182b68bcf668d063742816e09dce34fa83a Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 12:16:31 +0700 Subject: [PATCH 243/412] plan: server-authoritative state with JSON Patch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete rewrite of the projection sync plan. Key architectural shift: drop dual folds, use server-computed JSON Patches instead. - Fold runs only in Python — frontend has zero business logic - 3 SSE event types: snapshot, patch, delta - Catch-up always uses fresh snapshots (no patch replay) - Streaming buffers special-cased as delta events for bandwidth - ConversationEntry discriminated union with BaseToolEntry inheritance - Scale analysis for full epics (500K events, 50MB state) --- .../2026-03-31-symmetric-projection-folds.md | 608 ++++++++---------- 1 file changed, 268 insertions(+), 340 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index a95e8da..6ccd80f 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -1,160 +1,164 @@ -# Symmetric Projection Folds +# Server-Authoritative State with JSON Patch **Date:** 2026-03-31 **Status:** Draft -**Goal:** Make backend and frontend projection folds produce identical materialized state, eliminating the need for ad-hoc re-interpretation during snapshot recovery. +**Goal:** Single fold in Python, server-computed diffs via JSON Patch, frontend as a dumb renderer with zero business logic. --- -## Motivation / Bug Report +## Motivation -Two user-visible bugs triggered this plan, both manifesting on page refresh: +Two user-visible bugs on page refresh exposed a deeper architectural problem: -**Bug 1: Fragmented thinking cards.** After refreshing the page, the primary agent's thinking was displayed as dozens of tiny individual cards — "The", "user wants", "me to call", "k", "oan_complete_step to receive", "instructions.", etc. — instead of a single merged block. During a live session, thinking tokens arrive as `thinking` SSE events and are accumulated in the frontend's `thinkingBuffer` before being flushed into a single card. On refresh, `applySnapshot` received the raw event log and created one card per event. +**Bug 1 — Fragmented thinking cards:** After refresh, thinking was displayed as dozens of tiny cards ("The", "user wants", "me to call"…) instead of one merged block. The live path accumulated deltas in a buffer; the snapshot path created one card per raw event. -**Bug 2: Scout events in the primary agent's feed.** After refresh, step headers (e.g., "step 3/3 Report") and thinking blocks from scout agents appeared in the primary agent's activity feed. The MCP server was processing a batch of scouts while the primary agent was blocked; those scouts' events were in the event log but clearly attributed to different `agent_id`s. The live `applyEvent` path correctly filters to the primary agent; `applySnapshot` did not. +**Bug 2 — Scout events in the primary feed:** After refresh, scout step headers and thinking blocks appeared in the primary agent's activity feed. The live path filtered by agent; the snapshot path did not. -**Root cause (shared):** `activity_log` in the backend `Projection` is not a materialized view — it is a raw event append. The frontend's `applySnapshot` was forced to re-fold this raw log, duplicating fold logic that was inconsistent with the live path. +**Root cause:** The backend's `activity_log` stored raw events, not materialized state. The frontend re-folded this raw log on snapshot recovery — duplicating fold logic inconsistently. But the deeper question is: **why does the frontend run fold logic at all?** -**User statement:** "shouldn't the backend fold produce the same state that the frontend renders?" — confirmed as the correct design intent. +The answer: it shouldn't. The fold exists in one place (Python). The frontend applies server-computed state changes mechanically. This is how Google Docs, Figma, Linear, and Phoenix LiveView work — server computes, client renders. --- -## Problem Statement +## Architecture -The backend `fold()` in `koan/projections.py` and the frontend `applyEvent()` in `frontend/src/store/index.ts` are supposed to be symmetric — they process the same events and produce the same materialized state. The client connects, receives a **snapshot** (materialized state at version N), then applies live events via its own fold. +### Core principle: server computes, client applies -**The current reality:** +The fold runs **only in Python**. The frontend has **zero business logic** — no event interpretation, no buffer management, no agent filtering, no in-flight tracking. It receives state and renders it. -The `activity_log` field in the backend `Projection` is **not** materialized. The backend fold just appends raw event dicts: +### Protocol: snapshot + JSON Patch + streaming deltas -```python -case "tool_called": - entry = {"event_type": event_type, "agent_id": agent_id, **payload} - return projection.model_copy(update={ - "activity_log": [*projection.activity_log, entry], - }) -``` +The server sends three types of SSE messages: -This makes `activity_log` a **second copy of the raw event log** — not a materialized view. The frontend's `applySnapshot()` then has to re-fold this raw log into rich `ActivityEntry[]` structures (merge consecutive thinking deltas, filter to primary agent, map typed tools, compute in-flight status). This re-folding logic is separate from and inconsistent with the live `applyEvent()` fold, causing the bugs above. +| SSE event | When | Payload | Client action | +|-----------|------|---------|---------------| +| `snapshot` | First connect, reconnect | `{version, state}` — full materialized projection | Replace entire store | +| `patch` | After each event (except deltas) | `{version, patch}` — RFC 6902 JSON Patch operations | `jsonpatch.apply(state, patch)` | +| `delta` | `thinking` / `stream_delta` events | `{version, path, delta}` — string append | `state[path] += delta` | -Meanwhile, the frontend's live `applyEvent()` does produce the correct rich view — but this logic is duplicated nowhere, and the snapshot path implements a buggy approximation of it. +**Why three types, not just patches?** -**The design invariant stated in `docs/projections.md` — "Events are facts about things that happened — not state snapshots. The fold function derives state from facts" — was being violated for `activity_log`, which stored raw facts instead of derived state.** +JSON Patch's `replace` operation for a growing string buffer is O(buffer_size) per delta. A `thinking_buffer` at 10KB with 20 deltas/second produces 200KB/s of patches — vs 600B/s for raw deltas. Streaming buffers are special-cased for bandwidth efficiency. Everything else goes through standard JSON Patch. ---- +### Connection lifecycle -## Event Types (33 total) +``` +First connect: GET /events?since=0 + ← snapshot {version: N, state: <Projection>} + ← patch {version: N+1, patch: [...]} + ← delta {version: N+2, path: "thinking_buffer", delta: "The user"} + ← delta {version: N+3, path: "thinking_buffer", delta: " wants me"} + ← patch {version: N+4, patch: [...]} + ... -### Lifecycle (7) +Reconnect: GET /events?since=N+4 + ← snapshot {version: M, state: <Projection>} + (always a fresh snapshot — no patch replay) -| Event | Payload | Description | -|-------|---------|-------------| -| `phase_started` | `{phase: str}` | New workflow phase begins | -| `agent_spawned` | `{agent_id, role, label, model, is_primary, started_at_ms}` | Agent process launched | -| `agent_spawn_failed` | `{role, error_code, message, details?}` | Agent failed to spawn | -| `agent_step_advanced` | `{step, step_name, usage?, total_steps?}` | Agent progressed to next step | -| `agent_exited` | `{exit_code, error?, usage?}` | Agent process terminated | -| `workflow_completed` | `{success, summary?, error?}` | Entire workflow finished | -| `scout_queued` | `{scout_id, label, model?}` | Scout waiting for concurrency slot | +Server restart: GET /events?since=N+4 + ← snapshot {version: 0, state: <empty projection>} + (client detects version regression, resets UI) +``` -### Activity (13) +**Catch-up always uses snapshots.** Storing patches for replay is expensive (200K–500K events over a full epic, thinking patches are large). On reconnect, the server sends a fresh snapshot at the current version. The `since` parameter is a version check: if it matches the server's version, skip the snapshot and go straight to live events. Otherwise, send a snapshot. -| Event | Payload | Description | -|-------|---------|-------------| -| `tool_called` | `{call_id, tool, args, summary}` | Generic/unrecognized tool invocation | -| `tool_read` | `{call_id, tool:"read", file, lines}` | File read | -| `tool_write` | `{call_id, tool:"write", file}` | File write | -| `tool_edit` | `{call_id, tool:"edit", file}` | File edit | -| `tool_bash` | `{call_id, tool:"bash", command}` | Shell command | -| `tool_grep` | `{call_id, tool:"grep", pattern}` | Pattern search | -| `tool_ls` | `{call_id, tool:"ls", path}` | Directory listing | -| `tool_completed` | `{call_id, tool, result?}` | Tool invocation finished | -| `thinking` | `{delta: str}` | Incremental thinking token chunk | -| `stream_delta` | `{delta: str}` | Incremental text output chunk | -| `stream_cleared` | `{}` | Agent's stream ended (process EOF) | +This eliminates `events_since()` and the catch-up replay code path entirely. -All activity events carry `agent_id` identifying which agent produced them. +### What the server stores -**Note:** `tool_read` through `tool_ls` are typed specialisations of `tool_called`, introduced to carry structured metadata (file paths, commands, patterns) that the generic `tool_called` payload cannot express uniformly across runners. The existing `docs/projections.md` "Why tool events are generic" rationale is superseded — that rationale was written before the typed events existed. +| Store | Purpose | Lifetime | +|-------|---------|----------| +| `self.events: list[VersionedEvent]` | Audit log, debugging | Session (in-memory) | +| `self.projection: Projection` | Materialized state for snapshots + diff computation | Session | +| `self.prev_state: dict` | Previous `model_dump()` for computing patches | Overwritten each event | -### Interactions (6) +No stored patches. No catch-up replay buffer. -| Event | Payload | Description | -|-------|---------|-------------| -| `questions_asked` | `{token, questions: [...]}` | User prompted with questions | -| `questions_answered` | `{token, cancelled, answers?}` | User responded | -| `artifact_review_requested` | `{token, path, description, content}` | Artifact review needed | -| `artifact_reviewed` | `{token, cancelled, accepted?, response?}` | Review completed | -| `workflow_decision_requested` | `{token, chat_turns}` | Phase selection needed | -| `workflow_decided` | `{token, cancelled, decision?}` | Decision made | +### Server-side push_event flow -### Resources (3) +```python +def push_event(self, event_type, payload, agent_id=None): + self.version += 1 + event = VersionedEvent(version=self.version, ...) + self.events.append(event) # audit log + + old_state = self.prev_state + self.projection = fold(self.projection, event) + new_state = self.projection.model_dump() + self.prev_state = new_state + + # Streaming deltas: bypass JSON Patch, send raw delta + if event_type in ("thinking", "stream_delta"): + broadcast_delta(version, path_for(event_type), payload["delta"]) + else: + patch = jsonpatch.make_patch(old_state, new_state) + if patch: + broadcast_patch(version, patch.to_string()) +``` + +### Frontend event handling — complete implementation + +```typescript +es.addEventListener('snapshot', (e) => { + const { version, state } = JSON.parse(e.data) + set({ lastVersion: version, ...mapProjectionToStore(state) }) +}) + +es.addEventListener('patch', (e) => { + const { version, patch } = JSON.parse(e.data) + projectionState = jsonpatch.apply(projectionState, patch) + set({ lastVersion: version, ...mapProjectionToStore(projectionState) }) +}) + +es.addEventListener('delta', (e) => { + const { version, path, delta } = JSON.parse(e.data) + set(s => { + if (path === 'thinking_buffer') + return { lastVersion: version, thinkingBuffer: s.thinkingBuffer + delta, isThinking: true } + if (path === 'stream_buffer') + return { lastVersion: version, streamBuffer: s.streamBuffer + delta } + return { lastVersion: version } + }) +}) +``` + +That is the **entire** frontend sync implementation. No `applyEvent`. No 33-case switch. No fold logic. No buffer flushing. No agent filtering. No `completedCallIds` sets. -| Event | Payload | Description | -|-------|---------|-------------| -| `artifact_created` | `{path, size, modified_at}` | New file produced | -| `artifact_modified` | `{path, size, modified_at}` | File updated | -| `artifact_removed` | `{path}` | File deleted | - -### Configuration (7) - -| Event | Payload | Description | -|-------|---------|-------------| -| `probe_completed` | `{runners: [...]}` | Binary detection finished | -| `installation_created` | `{alias, runner_type, binary, extra_args}` | New agent installation | -| `installation_modified` | `{alias, runner_type, binary, extra_args}` | Installation updated | -| `installation_removed` | `{alias}` | Installation deleted | -| `profile_created` | `{name, read_only, tiers}` | New profile | -| `profile_modified` | `{name, read_only, tiers}` | Profile updated | -| `profile_removed` | `{name}` | Profile deleted | -| `active_profile_changed` | `{name}` | Active profile switched | -| `scout_concurrency_changed` | `{value}` | Concurrency limit changed | +`mapProjectionToStore` is a pure mapping from Python snake_case field names to the Zustand store's shape. It does not interpret, filter, or transform — it renames fields. --- -## SSE Protocol +## Why not dual folds? -``` -Client connects: GET /events?since=0 -Server sends: event: snapshot\ndata: {"version": N, "state": <Projection>}\n\n -Server sends: event: <type>\ndata: {"version": N+1, ...payload}\n\n (live) - event: <type>\ndata: {"version": N+2, ...payload}\n\n (live) - ... - -Client reconnects: GET /events?since=N+2 -Server sends: event: <type>\ndata: {"version": N+3, ...}\n\n (catch-up) - event: <type>\ndata: {"version": N+4, ...}\n\n (live) - ... -``` +The initial design considered symmetric folds: identical fold logic in Python and TypeScript. This was rejected: -- `since=0`: snapshot + live events -- `since=N` (N > 0): catch-up replay of events with version > N, then live -- `since=N` where N > server version: `fatal_error` event, client reloads +| Concern | Dual folds | JSON Patch | +|---------|-----------|------------| +| Fold implementations | 2 (Python + TypeScript) — must stay in sync forever | **1 (Python only)** | +| New event type cost | Python fold + TS fold + TS snapshot reconstruction | **Python fold only** — frontend unchanged | +| Bug surface | Proportional to event_type_count × 2 | Proportional to event_type_count × 1 | +| Frontend complexity | 33-case switch + buffer management + agent filtering | **3 event listeners, zero business logic** | +| Correctness guarantee | Requires "symmetric fold invariant" — manual discipline | **Correct by construction** — frontend cannot diverge | -**The snapshot is the materialized projection state.** The client reads it directly into its store, then applies subsequent events via its local fold. No re-interpretation. The `since` value is the version embedded in the snapshot — the client stores it and uses it on reconnect. +The dual-fold approach is *complected* in the Rich Hickey sense: fold logic interleaved with two language runtimes. The "symmetric fold invariant" is an admission that the architecture requires discipline to maintain. JSON Patch eliminates the problem: there is no invariant to enforce because the logic exists in one place. ---- +### Why not WASM shared fold? -## Target Projection Shape +Compile fold to WASM, run in both Python and browser. Eliminates duplication but adds WASM toolchain, FFI boundaries, and build complexity. Over-engineered for a single-user local tool. -The projection is the single source of truth. Backend `fold()` produces it, `get_snapshot()` serializes it, frontend `applySnapshot()` reads it directly, frontend `applyEvent()` updates it identically. No field in the snapshot should require the frontend to re-fold, filter, or merge. +### Why not server-rendered HTML (LiveView)? -### `ConversationEntry` — discriminated union of distinct types +Server renders the full UI, sends DOM diffs. Zero client logic. But koan's UI has rich interactivity — question wizards, settings overlays, artifact browsing, drag interactions. LiveView fights against client-side interactivity. -The primary agent's activity is a timeline of events: reasoning blocks, text output, tool calls, step transitions. These form a sequential conversation that the UI renders as-is. +--- -**Design decision: one type per variant, not a flat struct with optionals.** +## Projection Model -Each entry type has *exactly* the fields it needs — no optional fields that only apply to other variants. This makes invalid states unrepresentable: you cannot access `.command` on a `ThinkingEntry` because the field doesn't exist. The type system enforces valid field combinations at compile time in both Python and TypeScript. +The projection is the single materialized view of all state. The backend fold produces it, `get_snapshot()` serializes it, patches express incremental changes to it, the frontend renders it. -The key properties: +### ConversationEntry — discriminated union of distinct types -- **Discriminated union on `type`**: Pydantic's `Annotated[Union[...], Field(discriminator="type")]` serializes each variant with only its fields + discriminator. TypeScript narrows automatically on `entry.type === "tool_read"`. -- **1:1 component mapping**: Each type maps to exactly one frontend rendering component (ThinkingCard, TextBlock, StepHeader, ReadLine, BashLine, etc.). The dispatch is an exhaustive `switch(entry.type)`. -- **Merged, not incremental**: a `ThinkingEntry` holds the full accumulated thinking text, not a delta. The fold merges consecutive deltas before flushing to an entry. -- **Agent-filtered**: only primary agent entries appear in `conversation`. Scout activity is tracked on the scout's own `AgentProjection.last_tool`. -- **In-flight tracking built in**: tool entries carry `in_flight: bool` — the fold sets it `True` on creation, `False` on matching `tool_completed`. +The primary agent's activity is a timeline: reasoning blocks, text output, tool calls, step transitions. Each entry type has exactly the fields it needs — no optional fields that only apply to other variants. ```python class ThinkingEntry(BaseModel): @@ -179,7 +183,7 @@ class BaseToolEntry(BaseModel): class ToolReadEntry(BaseToolEntry): type: Literal["tool_read"] = "tool_read" file: str - lines: str = "" # optional line range "10-20" + lines: str = "" class ToolWriteEntry(BaseToolEntry): type: Literal["tool_write"] = "tool_write" @@ -203,7 +207,7 @@ class ToolLsEntry(BaseToolEntry): class ToolGenericEntry(BaseToolEntry): type: Literal["tool_generic"] = "tool_generic" - tool_name: str # original unrecognized tool name + tool_name: str summary: str = "" ConversationEntry = Annotated[ @@ -214,76 +218,54 @@ ConversationEntry = Annotated[ ] ``` -**`tool_completed` handling:** -All tool types inherit from `BaseToolEntry`, which carries `call_id` and `in_flight`. The fold scans `conversation` for an entry where `isinstance(entry, BaseToolEntry) and entry.call_id == target` and sets `in_flight = False` via `model_copy(update={"in_flight": False})`. On the TypeScript side, a `BaseToolEntry` interface provides the same fields, and a type guard `isToolEntry(e): e is BaseToolEntry` enables the same pattern. +**Why one type per variant:** Invalid states are unrepresentable. You cannot access `.command` on a `ThinkingEntry`. The type system enforces valid field combinations. Each type maps 1:1 to a frontend rendering component. -**Extensibility:** Adding a future `ToolWebFetchEntry` means: define the Pydantic model (4 lines), add to the union, add a fold case in Python, add a TypeScript type, add a fold case in TS, add a rendering component. Each step is mechanical. No existing types are modified. +**`tool_completed` handling:** All tool types inherit `BaseToolEntry` with `call_id` and `in_flight`. The fold scans `conversation` for `isinstance(entry, BaseToolEntry) and entry.call_id == target`, sets `in_flight = False`. -**Edge cases covered:** -- Multiple tool calls in one turn: each produces its own entry, accumulated in order. -- Thinking before tool call: thinking buffer flushed to entry when first tool arrives. -- Text before thinking (or thinking before text): transition triggers flush of the outgoing buffer. -- Koan MCP tools (`koan_complete_step`, etc.): filtered in the fold — they produce no `ConversationEntry`. The MCP endpoint's `tool_called`/`tool_completed` events are still in the raw log but the fold ignores them for the conversation. They are authoritative sources of `agent_step_advanced`, not tool display. -- Bootstrap step (step 0→1): `agent_step_advanced` with `step < 1` produces no step entry. The step header appears only when the agent reaches a named step. -- Incomplete thinking at snapshot time: `thinking_buffer` is non-empty. The entry is NOT yet created — the buffer is in the snapshot as-is, and the `isThinking` flag is derived from `thinking_buffer.length > 0`. This is correct: the live stream will continue producing deltas into the buffer. +**Extensibility:** Adding `ToolWebFetchEntry` means: define the Pydantic model, add to the union, add a fold case. The frontend is unchanged — JSON Patch carries the new entry structure automatically. -### Fold rules for conversation entries +### Fold rules -The backend fold maintains `conversation: list[ConversationEntry]` plus two transient accumulator fields (`thinking_buffer: str`, `stream_buffer: str`). The buffers accumulate incremental deltas and are flushed to completed entries when the output type changes or when a structural event (tool call, step advance, stream end) occurs. - -**Why buffers in the projection (not the frontend only):** -The frontend's live fold already uses buffers for this purpose. Moving them to the projection means: (a) the snapshot captures mid-thought state accurately, and (b) the backend and frontend folds share the same algorithm. A client reconnecting mid-thought gets the partial thinking buffer in the snapshot and can display the live thinking card immediately. +The fold maintains `conversation: list[ConversationEntry]` plus two transient buffers (`thinking_buffer`, `stream_buffer`). Buffers accumulate deltas; they flush to completed entries on transitions. | Event | Action | |-------|--------| -| `thinking` (primary agent only) | If `stream_buffer` non-empty → flush to `text` entry, clear. Append delta to `thinking_buffer`. | -| `stream_delta` (primary agent only) | If `thinking_buffer` non-empty → flush to `thinking` entry, clear. Append delta to `stream_buffer`. | -| `tool_*` / `tool_called` (primary, non-koan) | Flush both buffers. Append typed tool entry with `in_flight=True`. | -| `tool_called` (koan MCP — `koan_*` prefix) | Ignore for conversation. Do not flush buffers. | -| `tool_completed` (primary agent only) | Set `in_flight=False` on entry matching `call_id`. | -| `agent_step_advanced` (primary agent only) | Flush both buffers. If `step >= 1`: append step entry. Update step/tokens on `primary_agent`. | -| `agent_step_advanced` (scout) | Update step/tokens on scout's `AgentProjection`. No conversation entry. | -| `stream_cleared` (primary agent only) | Flush both buffers. | -| Any activity event for non-primary agent | Update scout's `last_tool`. Do NOT touch `conversation` or buffers. | +| `thinking` (primary only) | Flush `stream_buffer` → TextEntry. Append delta to `thinking_buffer`. | +| `stream_delta` (primary only) | Flush `thinking_buffer` → ThinkingEntry. Append delta to `stream_buffer`. | +| `tool_*` (primary, non-koan) | Flush both buffers. Append typed tool entry (`in_flight=True`). | +| `tool_called` (koan MCP — `koan_*`) | Ignore for conversation. | +| `tool_completed` (primary only) | Set `in_flight=False` on matching `call_id`. | +| `agent_step_advanced` (primary) | Flush both buffers. Append StepEntry if `step >= 1`. Update agent step/tokens. | +| `agent_step_advanced` (scout) | Update scout step/tokens only. | +| `stream_cleared` (primary only) | Flush both buffers. | +| Tool events (scout) | Update scout's `last_tool`. | +| `agent_exited` | Set `status`, `error` on agent. Move to `completed_agents`. | -**Why primary-agent filtering is in the fold, not the frontend:** -The fold owns the semantics of what belongs in the primary agent's conversation. Scattering this logic across the frontend's snapshot reconstruction and live event paths creates inconsistency — as seen in the bugs. A single authoritative filter in the fold means both paths are correct by construction. +**Why primary-agent filtering is in the fold:** The fold owns the semantics of what belongs in the conversation. A single authoritative filter prevents the inconsistency bugs that triggered this plan. -**Why koan MCP tools are filtered in the fold:** -`koan_complete_step`, `koan_ask_question`, `koan_request_scouts` etc. are infrastructure calls — they drive the workflow state machine, not the primary agent's work. They have no meaningful display in the conversation timeline. Their effect is already captured by `agent_step_advanced`, `questions_asked`, and `scout_queued` events. Showing them as tool lines would be noise. The MCP endpoint still emits `tool_called`/`tool_completed` for these — that is intentional, as the raw event log preserves them for audit — but the fold does not materialize them into conversation entries. +**Why koan MCP tools are filtered:** `koan_complete_step` et al. are infrastructure — their effects are captured by `agent_step_advanced`, `questions_asked`, etc. Showing them as tool lines is noise. -### Full projection model +### Full projection ```python class Projection(BaseModel): - # -- Run state -- run_started: bool = False phase: str = "" - # -- Agents -- primary_agent: AgentProjection | None = None - scouts: dict[str, AgentProjection] = {} # keyed by agent_id + scouts: dict[str, AgentProjection] = {} queued_scouts: list[QueuedScout] = [] completed_agents: list[AgentProjection] = [] - # -- Primary agent conversation (materialized, ready to render) -- conversation: list[ConversationEntry] = [] - thinking_buffer: str = "" # partial thinking block in progress - stream_buffer: str = "" # partial text block in progress + thinking_buffer: str = "" + stream_buffer: str = "" - # -- Interactions -- active_interaction: InteractionState | None = None - - # -- Artifacts -- - artifacts: dict[str, ArtifactInfo] = {} # keyed by path - - # -- Notifications -- + artifacts: dict[str, ArtifactInfo] = {} notifications: list[NotificationEntry] = [] - - # -- Workflow completion -- completion: CompletionInfo | None = None - # -- Configuration -- config_runners: list[RunnerInfo] = [] config_profiles: list[ProfileInfo] = [] config_installations: list[InstallationInfo] = [] @@ -297,7 +279,7 @@ class Projection(BaseModel): class AgentProjection(BaseModel): agent_id: str role: str - label: str = "" # scout identifier (e.g. "engine-methods") + label: str = "" model: str | None = None step: int = 0 step_name: str = "" @@ -306,224 +288,170 @@ class AgentProjection(BaseModel): output_tokens: int = 0 status: Literal["running", "done", "failed"] = "running" error: str | None = None - last_tool: str = "" # most recent tool summary (scouts only) + last_tool: str = "" ``` -**Why `status`, `error`, `last_tool` move to the backend model:** -Currently these only exist on the frontend's `AgentInfo`. The snapshot would need to carry them for the agent monitor to display correct state after refresh. They are derived facts about agent state — they belong in the projection. - -**Why `label` is already in the backend `agent_spawned` payload:** -`label` carries the scout's human-readable identifier (e.g., `engine-methods`, `spec-etag`) which comes from `q["id"]` in `koan_request_scouts`. This was added to `build_agent_spawned` as part of the scout naming work. It belongs on `AgentProjection` as a display field. - -### What changes - -| Field | Current | Target | -|-------|---------|--------| -| `activity_log: list[dict]` | Raw event dicts, no merging, no filtering | **Removed.** Replaced by `conversation: list[ConversationEntry]` | -| `stream_buffer: str` | Exists, cleared on `stream_cleared` | Stays — fold logic remains here | -| (new) `thinking_buffer: str` | Frontend-only | Moves to projection — backend fold accumulates | -| (new) `conversation` | Frontend-only (`activityLog`) | Backend fold produces the identical structure | -| `AgentProjection.status` | Frontend-only | Backend fold sets on `agent_exited` | -| `AgentProjection.error` | Frontend-only | Backend fold sets on `agent_exited` | -| `AgentProjection.last_tool` | Frontend-only | Backend fold updates on tool events for scouts | -| `AgentProjection.label` | Already in backend | Already in backend ✓ | - --- -## Frontend `applySnapshot` (after) - -With a properly materialized projection, `applySnapshot` becomes a direct mapping — no re-folding: - -```typescript -applySnapshot: (data) => { - const state = data.state - set({ - lastVersion: data.version, - phase: state.phase, - runStarted: state.run_started, - primaryAgent: state.primary_agent ? transformAgent(state.primary_agent) : null, - scouts: transformScouts(state.scouts), - queuedScouts: state.queued_scouts, - completedAgents: state.completed_agents.map(transformAgent), - - // Direct read — no re-folding, no merging, no filtering - activityLog: state.conversation, - thinkingBuffer: state.thinking_buffer, - streamBuffer: state.stream_buffer, - isThinking: state.thinking_buffer.length > 0, - - activeInteraction: state.active_interaction, - artifacts: state.artifacts, - notifications: state.notifications, - completion: state.completion, - configProfiles: state.config_profiles, - configInstallations: state.config_installations, - configActiveProfile: state.config_active_profile, - configScoutConcurrency: state.config_scout_concurrency, - configRunners: state.config_runners, - }) -} -``` - -No `completedCallIds` set, no `flatMap`, no thinking merging, no agent filtering, no raw-event re-interpretation. The snapshot IS the view. +## Event Types (33 total) ---- +### Lifecycle (7) -## Frontend `applyEvent` (after) +| Event | Payload | +|-------|---------| +| `phase_started` | `{phase}` | +| `agent_spawned` | `{agent_id, role, label, model, is_primary, started_at_ms}` | +| `agent_spawn_failed` | `{role, error_code, message, details?}` | +| `agent_step_advanced` | `{step, step_name, usage?, total_steps?}` | +| `agent_exited` | `{exit_code, error?, usage?}` | +| `workflow_completed` | `{success, summary?, error?}` | +| `scout_queued` | `{scout_id, label, model?}` | -The live fold stays the same conceptually — it's already correct. The `flushThinkingBuffer()` / `flushStreamBuffer()` / `flushBuffers()` helpers stay. The entries they produce must match `ConversationEntry` field names exactly: +### Activity (13) -```typescript -// Flush thinking buffer → ConversationEntry type "thinking" -{ type: "thinking", content: thinkingBuffer } +| Event | Payload | +|-------|---------| +| `tool_called` | `{call_id, tool, args, summary}` | +| `tool_read` | `{call_id, tool:"read", file, lines}` | +| `tool_write` | `{call_id, tool:"write", file}` | +| `tool_edit` | `{call_id, tool:"edit", file}` | +| `tool_bash` | `{call_id, tool:"bash", command}` | +| `tool_grep` | `{call_id, tool:"grep", pattern}` | +| `tool_ls` | `{call_id, tool:"ls", path}` | +| `tool_completed` | `{call_id, tool, result?}` | +| `thinking` | `{delta}` | +| `stream_delta` | `{delta}` | +| `stream_cleared` | `{}` | -// Flush stream buffer → ConversationEntry type "text" -{ type: "text", text: streamBuffer } +### Interactions (6) -// Tool event → ConversationEntry type "tool" -{ type: "tool", tool_type: "read", call_id: "...", in_flight: true, file: "/path" } +| Event | Payload | +|-------|---------| +| `questions_asked` | `{token, questions}` | +| `questions_answered` | `{token, cancelled, answers?}` | +| `artifact_review_requested` | `{token, path, description, content}` | +| `artifact_reviewed` | `{token, cancelled, accepted?, response?}` | +| `workflow_decision_requested` | `{token, chat_turns}` | +| `workflow_decided` | `{token, cancelled, decision?}` | -// Step advance → ConversationEntry type "step" -{ type: "step", step: 3, step_name: "Ask", total_steps: 5 } -``` +### Resources (3) -**Why snake_case field names throughout:** -Pydantic's `model_dump()` produces snake_case by default. Aligning the TypeScript interface to snake_case eliminates a camelCase conversion layer at the boundary. The existing frontend convention is to accept snake_case from the API and leave conversion to individual `transformAgent()` helpers where needed; `ConversationEntry` fields are read directly from the snapshot, so they should arrive in the shape they're used. +| Event | Payload | +|-------|---------| +| `artifact_created` | `{path, size, modified_at}` | +| `artifact_modified` | `{path, size, modified_at}` | +| `artifact_removed` | `{path}` | + +### Configuration (9) + +| Event | Payload | +|-------|---------| +| `probe_completed` | `{runners}` | +| `installation_created` | `{alias, runner_type, binary, extra_args}` | +| `installation_modified` | `{alias, runner_type, binary, extra_args}` | +| `installation_removed` | `{alias}` | +| `profile_created` | `{name, read_only, tiers}` | +| `profile_modified` | `{name, read_only, tiers}` | +| `profile_removed` | `{name}` | +| `active_profile_changed` | `{name}` | +| `scout_concurrency_changed` | `{value}` | --- -## Implementation Plan - -### Phase 1: Backend fold produces materialized conversation +## Scale considerations -1. Define `ConversationEntry` Pydantic model in `koan/projections.py` -2. Add `conversation: list[ConversationEntry]` and `thinking_buffer: str` to `Projection`; remove `activity_log` -3. Add `status`, `error`, `last_tool` to `AgentProjection` -4. Rewrite fold cases for all activity events: - - `thinking`: accumulate into `thinking_buffer` (primary only) - - `stream_delta`: accumulate into `stream_buffer` (primary only) - - `tool_read/write/edit/bash/grep/ls`: flush buffers, append typed tool entry (primary); update `last_tool` (scout) - - `tool_called` (non-koan): flush buffers, append generic tool entry (primary); update `last_tool` (scout) - - `tool_called` (koan MCP): ignore for conversation - - `tool_completed`: set `in_flight=False` by `call_id` in `conversation` - - `agent_step_advanced`: flush buffers, append step entry if `step >= 1` (primary); update step/tokens (any agent) - - `stream_cleared`: flush both buffers - - `agent_exited`: set `status`, `error` on the agent before moving to `completed_agents` -5. Update `get_snapshot()` — no changes needed; `model_dump()` will include `conversation` automatically +**Projected state over a full epic:** +- 20 markdown documents × 10 tickets = 200 artifacts (~2MB of content references) +- 5 agent sessions per ticket × 10 tickets = 50 primary agent runs +- 5 batches of 10 scouts = 250 scout sessions +- Each scout: ~50 tool calls, ~20 thinking blocks +- Primary agents: ~200 tool calls, ~100 thinking blocks per session +- Total events: ~200K–500K over the epic -**Dependency:** Phase 1 must complete before Phase 2 — the frontend cannot read a materialized snapshot until the backend produces one. +**Why JSON Patch works at this scale:** +- Tool call patches: ~100 bytes each (add entry to conversation array) +- Step advance patches: ~200 bytes (flush + add) +- `tool_completed`: ~80 bytes (replace one `in_flight` field) +- Thinking/stream deltas: bypassed entirely (raw delta events) +- Snapshot size at peak: ~50MB (dominated by artifact content references) +- Snapshot sent only on connect/reconnect — not per-event -### Phase 2: Frontend reads materialized snapshot - -1. Define `ConversationEntry` TypeScript type in `frontend/src/store/index.ts` matching the Python model exactly (snake_case field names, same `type` discriminator values) -2. Rewrite `applySnapshot` to directly read `conversation`, `thinking_buffer`, `stream_buffer` — remove all re-folding code (the `flatMap`, `completedCallIds` set, thinking merge loop, agent filtering) -3. Update `applyEvent` to produce `ConversationEntry`-shaped objects: rename `ActivityEntry` fields to match (`thinkingContent` → `content`, `textContent` → `text`, `inFlight` → `in_flight`, etc.) -4. Update `ActivityFeed` component — it renders `ConversationEntry[]`; field names may need updating in render components - -### Phase 3: Tests - -1. Update backend projection fold tests — assert `conversation` entries and `thinking_buffer`, not raw `activity_log` dicts -2. Add tests for: - - Thinking buffer merging (consecutive deltas → single entry content) - - Scout filtering (scout tool events update `last_tool`, not `conversation`) - - In-flight tracking (`tool_completed` sets `in_flight=False` by `call_id`) - - Koan MCP tool filtering (no conversation entry produced) - - Bootstrap step filtering (`step < 1` produces no step entry) - - Buffer flushing on transitions (thinking → text, text → thinking, either → tool) -3. Snapshot round-trip test: fold N events → `get_snapshot()` → `applySnapshot()` on fresh frontend state → compare `activityLog` with live `applyEvent()` on same events - -### Phase 4: Cleanup - -1. Remove `ActivityEntry` TypeScript type — replaced by `ConversationEntry` -2. Remove dead `applySnapshot` re-folding code (now unreachable after Phase 2) -3. Update `docs/projections.md` (see Documentation Updates section) -4. Update `docs/architecture.md` (see Documentation Updates section) -5. Verify all views render correctly from snapshot recovery +**Why patch replay was rejected for catch-up:** 500K events × variable patch size = unbounded memory. A fresh snapshot (50MB once) is cheaper and simpler than replaying patches. --- -## Risks & Decisions - -**Thinking buffer in projection:** -The `thinking_buffer` is transient state that only matters for the "live tail". Including it in the snapshot means a reconnecting client picks up mid-thought state correctly — the active thinking card continues rather than disappearing on reconnect. The buffer is empty after any turn completes; it only holds content while the LLM is actively reasoning. - -**Koan MCP tool filtering in fold:** -Currently filtered in the frontend's `applyEvent`. Must move to the backend fold — `tool_called` events with `koan_*` tool names should not produce conversation entries. The MCP endpoint's `begin_tool_call`/`end_tool_call` still emit these events and they remain in the raw event log (append-only invariant), but the fold skips them when building `conversation`. - -**Primary agent identification:** -The fold needs to know which `agent_id` is the primary agent to decide whether to add to `conversation` or update scout `last_tool`. The projection already has `primary_agent.agent_id`. The fold checks `agent_id == projection.primary_agent.agent_id`. +## Implementation Plan -**`ConversationEntry` field naming (snake_case):** -Must be identical between Python `model_dump()` and TypeScript. Using snake_case throughout eliminates a transformation layer and makes the snapshot-to-store path direct. The frontend's existing `ActivityEntry` uses camelCase (`inFlight`, `thinkingContent`) — these will be renamed during Phase 2. +### Phase 1: Backend — materialized projection with JSON Patch + +1. `pip install jsonpatch` — add to dependencies +2. Define `ConversationEntry` union and all entry types in `koan/projections.py` +3. Add `conversation`, `thinking_buffer` to `Projection`; remove `activity_log` +4. Add `status`, `error`, `last_tool` to `AgentProjection` +5. Rewrite fold cases for all 33 event types +6. Update `ProjectionStore.push_event()`: + - Compute JSON Patch between old and new `model_dump()` + - For `thinking`/`stream_delta`: broadcast `delta` message instead of patch + - For all others: broadcast `patch` message + - Store `prev_state` for next diff computation +7. Update `sse_stream()`: + - `since=0`: send snapshot, then live + - `since=N` where N == server version: skip snapshot, go straight to live + - `since=N` where N != server version: send fresh snapshot (not event replay) + - Remove `events_since()` — no longer used for catch-up +8. Update `get_snapshot()` — unchanged; `model_dump()` naturally includes `conversation` + +### Phase 2: Frontend — dumb renderer + +1. `npm install fast-json-patch` +2. Define TypeScript `ConversationEntry` union matching Python exactly (snake_case) +3. Replace `connect.ts`: + - 3 event listeners: `snapshot`, `patch`, `delta` + - Remove KNOWN_EVENTS list and per-event-type listeners +4. Replace `applySnapshot`: direct field mapping, no re-folding +5. Delete `applyEvent` entirely +6. Keep `mapProjectionToStore()` as a pure field-rename function +7. Update `ActivityFeed` and components to read `ConversationEntry` field names -**Scout `last_tool` as a formatted string:** -The fold formats a human-readable string like `"read /path/to/file"` or `"bash ls -la"`. This is a display concern embedded in the fold. It avoids the frontend needing to re-derive display text from structured fields, and the monitor only needs one field to render. If more structured scout data becomes needed (e.g., separate tool type and argument for richer UI), `last_tool` can be split into `last_tool_type: str` and `last_tool_detail: str`. +### Phase 3: Tests -**`tool_completed` applied to completed conversation entries:** -`tool_completed` sets `in_flight=False` on the matching entry. The fold must scan `conversation` in reverse to find the matching `call_id`. This is O(n) in the number of conversation entries, but conversation length is bounded by run duration and tool calls per turn rarely exceed dozens. +1. Backend fold tests: assert `conversation` entries, `thinking_buffer`, `in_flight` state +2. JSON Patch tests: fold event → verify patch operations are correct +3. Delta bypass tests: `thinking`/`stream_delta` produce delta messages, not patches +4. Snapshot round-trip: fold events → snapshot → verify frontend can read it directly +5. Reconnect test: client with stale version gets fresh snapshot + +### Phase 4: Cleanup & docs + +1. Remove dead frontend code: `applyEvent`, `ActivityEntry` type, buffer flush helpers, KNOWN_EVENTS +2. Remove `events_since()` from `ProjectionStore` +3. Update `docs/projections.md`: + - Replace `activity_log` with `conversation` model + - Document JSON Patch protocol + - Document delta bypass for streaming buffers + - Update fold rules table +4. Update `docs/architecture.md`: + - Add invariant: "The fold runs only in Python. The frontend applies server-computed patches. It has no business logic." +5. Code comments on `ProjectionStore.push_event()` explaining the patch computation flow --- -## Migration / Backwards Compatibility +## Risks -**Snapshot format change:** -The snapshot's `state` dict will no longer contain `activity_log`; it will contain `conversation`, `thinking_buffer`. Any client holding a stale connection when the server is updated will receive a `fatal_error` on their next reconnect (server version > client version), forcing a page reload. This is the existing handling for server restarts — no special migration needed. +**JSON Patch array diffing:** `make_patch` uses positional indices for arrays. Conversation is append-only (entries are never reordered or removed), so patches are clean `add` operations at the end. The one mutation is `tool_completed` setting `in_flight=False` on an existing entry, which produces a targeted `replace` at `/conversation/N/in_flight`. -**Existing event logs (in-memory):** -The `ProjectionStore.events` list stores raw `VersionedEvent` objects. These are unchanged — events are facts, the fold interpretation of them changes. An in-progress run at deployment time would lose its in-memory state on restart (koan is one-shot; server restart during a run is already a failure case handled by `fatal_error`). +**Patch computation cost:** `make_patch` diffs two dicts. At 50MB state, this could be expensive. Mitigation: most events change a small part of state; the diff is proportional to what changed, not total state. For the dominant case (thinking delta), the diff is bypassed entirely. -**No on-disk migration:** -`activity_log` only exists in-memory in `ProjectionStore.projection`. It is not persisted to disk. The audit fold (`koan/audit/fold.py`) is independent and unaffected. +**Library trust:** `jsonpatch` (Python, 10+ years, well-maintained) and `fast-json-patch` (JavaScript, RFC 6902 compliant, widely used). Both are mature. -**Client version detection:** -The snapshot includes `version: int` and the frontend's `lastVersion` drives reconnect. There is no separate schema version field. If a new client connects to an old server (unlikely in practice — koan is one-shot), the snapshot will have `activity_log` instead of `conversation`. The frontend will silently render an empty activity feed. This is acceptable: old servers don't run long. +**Snapshot size:** At 50MB, the initial snapshot takes ~1 second on localhost. This is acceptable for a local tool. If it becomes a problem, the snapshot can be gzip-compressed (SSE supports `Content-Encoding: gzip`). --- -## Documentation Updates - -These docs must be updated as part of Phase 4: - -### `docs/projections.md` — primary updates - -1. **Projection model section:** Replace the `activity_log: list[dict]` field with `conversation: list[ConversationEntry]` and `thinking_buffer: str`. Add the full `ConversationEntry` model definition (with field docs). - -2. **Fold cases — Activity section:** Rewrite the activity fold table. Replace "append raw event to activity_log" with the actual fold rules: buffer accumulation, flush triggers, `in_flight` tracking, agent filtering, koan MCP filtering. - -3. **"Why activity_log stores raw events" design decision:** Remove this section. Replace with "Why conversation is materialized, not raw" explaining the symmetric fold invariant and the bugs it prevents. - -4. **"Why tool events are generic" design decision:** Update to reflect the typed tool events (`tool_read`, `tool_write`, etc.) that now exist. The rationale for generic `tool_called` as a fallback still applies, but the typed events are the primary path for known tools. - -5. **Event Types section:** Add the 6 typed tool events (`tool_read`, `tool_write`, `tool_edit`, `tool_bash`, `tool_grep`, `tool_ls`) and `scout_queued` which are currently missing from this doc. - -6. **`AgentProjection` model:** Add `status`, `error`, `last_tool`, `label` fields. - -### `docs/architecture.md` — add invariant - -Add a 7th core invariant (or extend Invariant 5 on projections): - -> **Symmetric fold invariant:** The backend `fold()` in `koan/projections.py` and the frontend `applyEvent()` in `frontend/src/store/index.ts` must produce the same materialized state from the same event sequence. The snapshot sent to the client is the backend's materialized projection — the client reads it directly without re-folding, filtering, or interpreting raw events. When adding a new event type, add a fold case to both implementations. - -This invariant explains why `applySnapshot` must never contain ad-hoc event re-interpretation logic — that logic belongs in the fold. - -### `koan/projections.py` — code comments - -Add a module-level docstring clarifying: -- `Projection` fields are materialized views, not raw event stores -- `conversation` is the primary agent's timeline, filtered and merged by the fold -- `thinking_buffer` and `stream_buffer` are transient accumulators — they are part of projection state because reconnecting clients need mid-turn state - -Add a comment on the `ConversationEntry` class explaining that field names are deliberately snake_case to allow direct JSON deserialization on the frontend without transformation. - -### `AGENTS.md` — no changes required - -The six core invariants in `AGENTS.md` do not need updating. The symmetric fold is a consequence of existing Invariant 5 (projections) and the general principle that the fold produces derived state from facts. The detail belongs in `docs/architecture.md`. +## Migration -### `frontend/src/store/index.ts` — code comments +**Breaking change.** The SSE protocol changes from per-event-type messages to `snapshot`/`patch`/`delta`. Old clients cannot connect to new servers (they'd receive unknown event types). Old servers cannot serve new clients (missing `patch` event). -After the change, add a comment on `applySnapshot` explaining: -- The snapshot `state` is already the materialized view — no re-folding -- `conversation` maps directly to `activityLog` -- `thinking_buffer` and `stream_buffer` carry mid-turn state for reconnecting clients +**No on-disk migration.** All state is in-memory. Server restart already forces a full reload. -Add a comment on `applyEvent` explaining that it must produce `ConversationEntry`-shaped objects and stay in sync with the backend fold in `koan/projections.py`. +**Deployment:** Single-user local tool. The user runs `pip install --upgrade koan` and restarts. No coordinated rollout needed. From 346f4ecf70620051aadd9b5214f4f48abc9b3ddc Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 12:20:41 +0700 Subject: [PATCH 244/412] =?UTF-8?q?plan:=20technical=20writer=20review=20?= =?UTF-8?q?=E2=80=94=20fix=20event=20count,=20add=20missing=20details?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix event count: 36 (was 33) - Specify projectionState variable and its role in the frontend - Specify mapProjectionToStore — pure field rename, no business logic - Add error handling: patch failure → reset lastVersion=0 and reconnect - Add SSE ordering guarantee — no reordering needed, connection-ordered - Add Documentation Updates section (docs, projections.py, connect.ts) - Invisible knowledge: bandwidth analysis for delta bypass, patch replay rejection --- .../2026-03-31-symmetric-projection-folds.md | 69 ++++++++++++++++++- 1 file changed, 66 insertions(+), 3 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index 6ccd80f..e10008a 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -124,7 +124,13 @@ es.addEventListener('delta', (e) => { That is the **entire** frontend sync implementation. No `applyEvent`. No 33-case switch. No fold logic. No buffer flushing. No agent filtering. No `completedCallIds` sets. -`mapProjectionToStore` is a pure mapping from Python snake_case field names to the Zustand store's shape. It does not interpret, filter, or transform — it renames fields. +`mapProjectionToStore` is a pure mapping from Python snake_case field names to the Zustand store's shape. It does not interpret, filter, or transform — it renames fields. Example: `state.primary_agent` → `primaryAgent`, `state.config_active_profile` → `configActiveProfile`. Agent and artifact sub-objects go through lightweight transform helpers (`transformAgent`, `transformArtifact`) that handle field renaming and type coercion from JSON to TypeScript types. + +**`projectionState`** is a module-level variable in `connect.ts` that holds the current raw projection dict (the last received snapshot or the result of applying all patches). It is the source of truth for patch application — patches mutate it, and `mapProjectionToStore` reads from it. It is separate from the Zustand store because `fast-json-patch` operates on plain JS objects, not Zustand state. On snapshot, it is replaced wholesale. On patch, it is mutated in-place (RFC 6902 `applyPatch` is destructive by default; the immutable variant produces a new object). + +**Error handling:** If `jsonpatch.apply` fails (malformed patch, version gap, or stale state), the client cannot safely continue — its local state may be inconsistent. The correct recovery is to force a reconnect with `since=0` to get a fresh snapshot. The error handler should: log the error, close the EventSource, reset `lastVersion` to 0, and reconnect. This is analogous to how `fatal_error` is handled today. + +**Ordering guarantee:** SSE messages are delivered in order over a single HTTP connection. Patches cannot arrive out of order. If the connection drops, the client reconnects and receives a fresh snapshot — there is no partial patch replay to misorder. The `version` field in each message is for diagnostics only; the client does not need to reorder messages. --- @@ -293,7 +299,7 @@ class AgentProjection(BaseModel): --- -## Event Types (33 total) +## Event Types (36 total) ### Lifecycle (7) @@ -307,7 +313,7 @@ class AgentProjection(BaseModel): | `workflow_completed` | `{success, summary?, error?}` | | `scout_queued` | `{scout_id, label, model?}` | -### Activity (13) +### Activity (11) | Event | Payload | |-------|---------| @@ -448,6 +454,63 @@ class AgentProjection(BaseModel): --- +## Documentation Updates + +These changes require corresponding updates to existing docs. Do not defer — out-of-date docs create invisible knowledge debt. + +### `docs/projections.md` + +1. **Projection model:** Replace `activity_log: list[dict]` with `conversation: list[ConversationEntry]` and `thinking_buffer: str`. Add the full `ConversationEntry` union definition with all 10 entry types. +2. **SSE protocol section:** Replace the current "snapshot + raw events" description with the new three-message protocol (`snapshot`, `patch`, `delta`). Include the connection lifecycle diagram from this plan. +3. **Fold rules table:** Rewrite the activity section — replace "append raw event to activity_log" with the actual fold rules (buffer accumulation, flush triggers, in-flight tracking, agent filtering, koan MCP filtering). +4. **"Why catch-up uses snapshots":** Document the bandwidth analysis: thinking delta patches at 200KB/s vs 600B/s for raw deltas. Document the memory cost of storing 500K patches. This decision must be visible, not inferred. +5. **Event types:** Add `scout_queued` and the 6 typed tool events (`tool_read` through `tool_ls`) which are currently missing. +6. **`AgentProjection`:** Add `status`, `error`, `last_tool`, `label` fields. +7. **Remove:** The "Why activity_log stores raw events" section — that rationale is obsolete. + +### `docs/architecture.md` + +Add a principle to the projection invariant section: + +> **The fold runs only in Python.** The frontend applies server-computed JSON Patches mechanically. It has no fold logic, no event interpretation, and no business rules. When the frontend's view of state differs from the backend's, the bug is in the fold or the patch computation — not in the frontend. + +This replaces any "symmetric fold invariant" language, which implied two folds that needed to stay in sync. + +### `koan/projections.py` + +Add module-level docstring: +``` +ProjectionStore maintains: + - events: append-only audit log of all VersionedEvents + - projection: materialized view produced by fold() — the source of truth + - prev_state: model_dump() of the previous projection, used for JSON Patch computation + +push_event() folds the event, computes a JSON Patch against prev_state, +and broadcasts either a patch or a delta message (for thinking/stream_delta). +The fold is the only place where business logic runs. The frontend applies +patches mechanically. +``` + +### `frontend/src/sse/connect.ts` + +After the change, the file should have a comment explaining: +``` +State sync protocol: + snapshot → replace entire projectionState and Zustand store + patch → apply RFC 6902 patch to projectionState, then re-map to store + delta → append string delta to thinking_buffer or stream_buffer directly + +projectionState is the raw dict that patches operate on. +mapProjectionToStore() renames fields for the Zustand store. +The frontend has no fold logic — all business rules live in the Python fold. +``` + +### `AGENTS.md` — no changes required + +The six core invariants are unchanged. The new architecture is a refinement of how Invariant 5 (projections) is implemented, not a change to the invariant itself. + +--- + ## Migration **Breaking change.** The SSE protocol changes from per-event-type messages to `snapshot`/`patch`/`delta`. Old clients cannot connect to new servers (they'd receive unknown event types). Old servers cannot serve new clients (missing `patch` event). From e292d947eb79555b67d6f9926ecaff6f5290e21e Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 12:23:20 +0700 Subject: [PATCH 245/412] refactor: extract normalizeAskQuestions helper, update plan per review - Extract question normalization from applyEvent into reusable function - Plan: event count corrected to 36, projectionState spec, error handling, SSE ordering, documentation updates section --- frontend/src/store/index.ts | 53 ++++++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 3dc9389..6c3734c 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -136,6 +136,30 @@ function interactionTypeToFrontend(interactionType: string): string { } } +// Normalize raw questions from the backend (options may be strings or dicts) +function normalizeAskQuestions(rawQs: Record<string, unknown>[]): AskQuestion[] { + return rawQs.map(q => { + const rawOpts = (q['options'] ?? []) as (string | Record<string, unknown>)[] + const options: AskOption[] = rawOpts.map(o => { + if (typeof o === 'string') return { value: o, label: o } + const label = (o['label'] ?? o['text'] ?? o['value'] ?? o['option'] ?? '') as string + const value = (o['value'] ?? o['label'] ?? o['text'] ?? label) as string + return { + value, + label, + recommended: (o['recommended'] as boolean) ?? false, + } + }) + return { + question: (q['question'] ?? q['text'] ?? q['prompt'] ?? '') as string, + multi: (q['multi'] as boolean) ?? false, + options, + allow_other: (q['allow_other'] as boolean) ?? undefined, + context: (q['context'] ?? q['description'] ?? q['rationale']) as string | undefined, + } + }) +} + function transformAgent(a: Record<string, unknown>): AgentInfo { return { agentId: a['agent_id'] as string, @@ -341,12 +365,18 @@ export const useStore = create<KoanState>((set) => ({ } // Transform active_interaction: strip backend's interaction_type discriminator, - // map to frontend Interaction.type. + // map to frontend Interaction.type, and normalize questions if present. let activeInteraction: Interaction | null = null const rawInteraction = state['active_interaction'] as Record<string, unknown> | null if (rawInteraction) { const itype = interactionTypeToFrontend(rawInteraction['interaction_type'] as string) const { interaction_type: _drop, ...interactionPayload } = rawInteraction + // Normalize ask interactions: options may be raw strings in the snapshot + if (itype === 'ask' && Array.isArray(interactionPayload['questions'])) { + interactionPayload['questions'] = normalizeAskQuestions( + interactionPayload['questions'] as Record<string, unknown>[], + ) + } activeInteraction = { type: itype as Interaction['type'], ...interactionPayload } as Interaction } @@ -870,26 +900,7 @@ export const useStore = create<KoanState>((set) => ({ // Normalize questions: options may arrive as strings or dicts // with varying key names from the LLM. const rawQs = (event['questions'] as Record<string, unknown>[]) ?? [] - const questions: AskQuestion[] = rawQs.map(q => { - const rawOpts = (q['options'] ?? []) as (string | Record<string, unknown>)[] - const options: AskOption[] = rawOpts.map(o => { - if (typeof o === 'string') return { value: o, label: o } - const label = (o['label'] ?? o['text'] ?? o['value'] ?? o['option'] ?? '') as string - const value = (o['value'] ?? o['label'] ?? o['text'] ?? label) as string - return { - value, - label, - recommended: (o['recommended'] as boolean) ?? false, - } - }) - return { - question: (q['question'] ?? q['text'] ?? q['prompt'] ?? '') as string, - multi: (q['multi'] as boolean) ?? false, - options, - allow_other: (q['allow_other'] as boolean) ?? undefined, - context: (q['context'] ?? q['description'] ?? q['rationale']) as string | undefined, - } - }) + const questions = normalizeAskQuestions(rawQs) const interaction: Interaction = { type: 'ask', token: event['token'] as string, questions, } From 25eb35c9130e5b4d63cb71a8eea8a97c2fe115ac Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 12:32:24 +0700 Subject: [PATCH 246/412] =?UTF-8?q?plan:=20resolve=20review=20feedback=20?= =?UTF-8?q?=E2=80=94=207=20clarifications?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. AgentProjection: label/status/error/last_tool marked as NEW, noted frontend already expects them (pre-existing gap) 2. stream_buffer: explicit note it stays alongside thinking_buffer 3. fatal_error removed: always-snapshot on reconnect, client auto-recovers 4. Queue message type: plain dicts, code example shows the shape 5. events_since() tests: explicitly flagged for deletion in Phase 3 6. isThinking: stored field set by delta handler, cleared by patch 7. projectionState: specified in Phase 2 as module-level variable --- .../2026-03-31-symmetric-projection-folds.md | 50 +++++++++++++------ 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index e10008a..e773395 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -57,12 +57,12 @@ Reconnect: GET /events?since=N+4 Server restart: GET /events?since=N+4 ← snapshot {version: 0, state: <empty projection>} - (client detects version regression, resets UI) + (client detects version < lastVersion, resets UI) ``` **Catch-up always uses snapshots.** Storing patches for replay is expensive (200K–500K events over a full epic, thinking patches are large). On reconnect, the server sends a fresh snapshot at the current version. The `since` parameter is a version check: if it matches the server's version, skip the snapshot and go straight to live events. Otherwise, send a snapshot. -This eliminates `events_since()` and the catch-up replay code path entirely. +This eliminates `events_since()` and the catch-up replay code path entirely. It also **eliminates `fatal_error`**: the current code sends `fatal_error` when `since > store.version` (after server restart), requiring the user to manually reload. The new design always sends a snapshot instead — the client detects the version regression (`snapshot.version < lastVersion`) and resets its UI automatically. One code path for all reconnects. ### What the server stores @@ -89,13 +89,23 @@ def push_event(self, event_type, payload, agent_id=None): # Streaming deltas: bypass JSON Patch, send raw delta if event_type in ("thinking", "stream_delta"): - broadcast_delta(version, path_for(event_type), payload["delta"]) + msg = {"type": "delta", "version": self.version, + "path": "thinking_buffer" if event_type == "thinking" else "stream_buffer", + "delta": payload["delta"]} else: patch = jsonpatch.make_patch(old_state, new_state) - if patch: - broadcast_patch(version, patch.to_string()) + if not patch: + return # no-op event (e.g. koan MCP tool filtered by fold) + msg = {"type": "patch", "version": self.version, + "patch": patch.to_string()} + + # Broadcast to all subscribers as a plain dict + for q in list(self.subscribers): + q.put_nowait(msg) ``` +Subscriber queues carry **plain dicts**, not `VersionedEvent` objects. The dict shape matches the SSE JSON payload directly — the `sse_stream()` consumer just serializes and sends. This is a deliberate simplification: the raw event is for the audit log, the dict message is for the wire. + ### Frontend event handling — complete implementation ```typescript @@ -116,7 +126,7 @@ es.addEventListener('delta', (e) => { if (path === 'thinking_buffer') return { lastVersion: version, thinkingBuffer: s.thinkingBuffer + delta, isThinking: true } if (path === 'stream_buffer') - return { lastVersion: version, streamBuffer: s.streamBuffer + delta } + return { lastVersion: version, streamBuffer: s.streamBuffer + delta, isThinking: false } return { lastVersion: version } }) }) @@ -124,6 +134,8 @@ es.addEventListener('delta', (e) => { That is the **entire** frontend sync implementation. No `applyEvent`. No 33-case switch. No fold logic. No buffer flushing. No agent filtering. No `completedCallIds` sets. +**`isThinking` is a stored field, not derived.** The `delta` handler for `thinking_buffer` sets `isThinking: true`. When the fold flushes `thinking_buffer` into a `ThinkingEntry` (on transition to a tool call or text output), the patch clears `thinking_buffer` to `""` and the next `mapProjectionToStore` call sees the empty buffer. The `patch` handler also sets `isThinking: false` when it detects `thinkingBuffer` was cleared. This avoids the component needing to derive `isThinking` from buffer length — it reads a definitive boolean. + `mapProjectionToStore` is a pure mapping from Python snake_case field names to the Zustand store's shape. It does not interpret, filter, or transform — it renames fields. Example: `state.primary_agent` → `primaryAgent`, `state.config_active_profile` → `configActiveProfile`. Agent and artifact sub-objects go through lightweight transform helpers (`transformAgent`, `transformArtifact`) that handle field renaming and type coercion from JSON to TypeScript types. **`projectionState`** is a module-level variable in `connect.ts` that holds the current raw projection dict (the last received snapshot or the result of applying all patches). It is the source of truth for patch application — patches mutate it, and `mapProjectionToStore` reads from it. It is separate from the Zustand store because `fast-json-patch` operates on plain JS objects, not Zustand state. On snapshot, it is replaced wholesale. On patch, it is mutated in-place (RFC 6902 `applyPatch` is destructive by default; the immutable variant produces a new object). @@ -264,8 +276,10 @@ class Projection(BaseModel): completed_agents: list[AgentProjection] = [] conversation: list[ConversationEntry] = [] - thinking_buffer: str = "" - stream_buffer: str = "" + thinking_buffer: str = "" # partial thinking in progress + stream_buffer: str = "" # partial text output in progress + # NOTE: stream_buffer already exists in the current Projection. + # thinking_buffer is new. Both are required for the delta SSE path. active_interaction: InteractionState | None = None artifacts: dict[str, ArtifactInfo] = {} @@ -285,18 +299,20 @@ class Projection(BaseModel): class AgentProjection(BaseModel): agent_id: str role: str - label: str = "" + label: str = "" # NEW — scout identifier (e.g. "engine-methods") model: str | None = None step: int = 0 step_name: str = "" - started_at_ms: int = 0 + started_at_ms: int = 0 # existing field input_tokens: int = 0 output_tokens: int = 0 - status: Literal["running", "done", "failed"] = "running" - error: str | None = None - last_tool: str = "" + status: Literal["running", "done", "failed"] = "running" # NEW + error: str | None = None # NEW + last_tool: str = "" # NEW — last tool summary for scout monitor ``` +`label`, `status`, `error`, `last_tool` are the four additions. The frontend's `transformAgent()` already reads these fields from the snapshot — they are expected but not yet emitted by the backend's `AgentProjection`. This plan closes that gap. + --- ## Event Types (36 total) @@ -405,6 +421,7 @@ class AgentProjection(BaseModel): - `since=N` where N == server version: skip snapshot, go straight to live - `since=N` where N != server version: send fresh snapshot (not event replay) - Remove `events_since()` — no longer used for catch-up + - Remove `fatal_error` path — replaced by always-snapshot (client auto-recovers from version regression) 8. Update `get_snapshot()` — unchanged; `model_dump()` naturally includes `conversation` ### Phase 2: Frontend — dumb renderer @@ -413,10 +430,12 @@ class AgentProjection(BaseModel): 2. Define TypeScript `ConversationEntry` union matching Python exactly (snake_case) 3. Replace `connect.ts`: - 3 event listeners: `snapshot`, `patch`, `delta` + - Module-level `projectionState` variable for patch application - Remove KNOWN_EVENTS list and per-event-type listeners -4. Replace `applySnapshot`: direct field mapping, no re-folding + - Remove `fatal_error` listener (no longer emitted) +4. Replace `applySnapshot`: direct field mapping from `mapProjectionToStore()`, no re-folding 5. Delete `applyEvent` entirely -6. Keep `mapProjectionToStore()` as a pure field-rename function +6. `mapProjectionToStore()`: pure field-rename function. Reads `projectionState` and produces Zustand-shaped state. `isThinking` is set: `true` when `thinkingBuffer !== ''`, `false` otherwise. The `delta` handler also sets `isThinking: true` directly for immediate reactivity. 7. Update `ActivityFeed` and components to read `ConversationEntry` field names ### Phase 3: Tests @@ -426,6 +445,7 @@ class AgentProjection(BaseModel): 3. Delta bypass tests: `thinking`/`stream_delta` produce delta messages, not patches 4. Snapshot round-trip: fold events → snapshot → verify frontend can read it directly 5. Reconnect test: client with stale version gets fresh snapshot +6. **Delete `events_since()` tests:** `test_projections.py` has tests that call `store.events_since()` directly (currently lines ~360–373). These must be deleted, not updated — the method no longer exists. Replace with tests that verify the snapshot contains the correct materialized state after N events. ### Phase 4: Cleanup & docs From e2eb930937b0c915a159c42d0f7df8783f4e4d10 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 14:14:09 +0700 Subject: [PATCH 247/412] plan: server emits camelCase via Pydantic alias_generator MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Eliminates mapProjectionToStore(), projectionState shadow variable, and all field-rename logic from the frontend. Server uses KoanBaseModel with alias_generator=to_camel + to_wire() method. Patches apply directly to the Zustand store — zero transformation layer. Key changes: - KoanBaseModel base class with to_wire() -> model_dump(by_alias=True) - All projection models inherit KoanBaseModel - push_event uses to_wire() for camelCase dicts - Delta paths are camelCase (thinkingBuffer, streamBuffer) - Frontend storeState replaces projectionState (just a name change) - Phase 2 deletes mapProjectionToStore instead of maintaining it --- .../2026-03-31-symmetric-projection-folds.md | 144 +++++++++++------- 1 file changed, 86 insertions(+), 58 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index e773395..bb719e0 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -32,9 +32,9 @@ The server sends three types of SSE messages: | SSE event | When | Payload | Client action | |-----------|------|---------|---------------| -| `snapshot` | First connect, reconnect | `{version, state}` — full materialized projection | Replace entire store | -| `patch` | After each event (except deltas) | `{version, patch}` — RFC 6902 JSON Patch operations | `jsonpatch.apply(state, patch)` | -| `delta` | `thinking` / `stream_delta` events | `{version, path, delta}` — string append | `state[path] += delta` | +| `snapshot` | First connect, reconnect | `{version, state}` — full materialized projection (camelCase) | Replace entire store | +| `patch` | After each event (except deltas) | `{version, patch}` — RFC 6902 JSON Patch operations (camelCase paths) | `applyPatch(store, patch)` | +| `delta` | `thinking` / `stream_delta` events | `{version, path, delta}` — string append (camelCase path) | `store[path] += delta` | **Why three types, not just patches?** @@ -44,10 +44,10 @@ JSON Patch's `replace` operation for a growing string buffer is O(buffer_size) p ``` First connect: GET /events?since=0 - ← snapshot {version: N, state: <Projection>} - ← patch {version: N+1, patch: [...]} - ← delta {version: N+2, path: "thinking_buffer", delta: "The user"} - ← delta {version: N+3, path: "thinking_buffer", delta: " wants me"} + ← snapshot {version: N, state: <Projection>} (camelCase keys) + ← patch {version: N+1, patch: [...]} (camelCase paths) + ← delta {version: N+2, path: "thinkingBuffer", delta: "The user"} + ← delta {version: N+3, path: "thinkingBuffer", delta: " wants me"} ← patch {version: N+4, patch: [...]} ... @@ -70,7 +70,7 @@ This eliminates `events_since()` and the catch-up replay code path entirely. It |-------|---------|----------| | `self.events: list[VersionedEvent]` | Audit log, debugging | Session (in-memory) | | `self.projection: Projection` | Materialized state for snapshots + diff computation | Session | -| `self.prev_state: dict` | Previous `model_dump()` for computing patches | Overwritten each event | +| `self.prev_state: dict` | Previous `to_wire()` for computing patches | Overwritten each event | No stored patches. No catch-up replay buffer. @@ -84,13 +84,13 @@ def push_event(self, event_type, payload, agent_id=None): old_state = self.prev_state self.projection = fold(self.projection, event) - new_state = self.projection.model_dump() + new_state = self.projection.to_wire() # camelCase via alias_generator self.prev_state = new_state # Streaming deltas: bypass JSON Patch, send raw delta if event_type in ("thinking", "stream_delta"): msg = {"type": "delta", "version": self.version, - "path": "thinking_buffer" if event_type == "thinking" else "stream_buffer", + "path": "thinkingBuffer" if event_type == "thinking" else "streamBuffer", "delta": payload["delta"]} else: patch = jsonpatch.make_patch(old_state, new_state) @@ -106,41 +106,64 @@ def push_event(self, event_type, payload, agent_id=None): Subscriber queues carry **plain dicts**, not `VersionedEvent` objects. The dict shape matches the SSE JSON payload directly — the `sse_stream()` consumer just serializes and sends. This is a deliberate simplification: the raw event is for the audit log, the dict message is for the wire. +### Wire format: camelCase via Pydantic aliases + +The server emits camelCase JSON. The frontend applies it directly — no field renaming, no shadow state, no mapping function. + +Pydantic's `alias_generator` handles the conversion at serialization boundaries. Python fold code still uses snake_case attributes (`projection.thinking_buffer`). Only `to_wire()` output is camelCase: + +```python +from pydantic import ConfigDict +from pydantic.alias_generators import to_camel + +class KoanBaseModel(BaseModel): + model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True) + + def to_wire(self) -> dict: + """Serialize for snapshots and patch computation. Always camelCase.""" + return self.model_dump(by_alias=True) +``` + +All projection models (`Projection`, `AgentProjection`, `ConversationEntry` types, etc.) inherit from `KoanBaseModel`. Snapshot JSON, patch paths, and delta paths are all camelCase. The frontend receives `thinkingBuffer`, `primaryAgent`, `configActiveProfile` — matching JavaScript conventions natively. + +**Why not keep snake_case on the wire and rename in the frontend?** Because that requires a `mapProjectionToStore()` function that renames every field, a `projectionState` shadow variable holding the snake_case dict for patch application (separate from the Zustand store), and maintenance of both in sync with the Projection model. Every new field needs a rename entry. That mapping layer *is* business logic — it contradicts the "frontend has zero business logic" principle. Emitting camelCase from the server eliminates the layer entirely: patches apply directly to the store, snapshots spread directly into the store, and adding a field to the Projection requires zero frontend changes. + ### Frontend event handling — complete implementation ```typescript +let storeState: Record<string, unknown> = {} // raw state for patch application + es.addEventListener('snapshot', (e) => { const { version, state } = JSON.parse(e.data) - set({ lastVersion: version, ...mapProjectionToStore(state) }) + storeState = state + set({ lastVersion: version, ...state }) }) es.addEventListener('patch', (e) => { const { version, patch } = JSON.parse(e.data) - projectionState = jsonpatch.apply(projectionState, patch) - set({ lastVersion: version, ...mapProjectionToStore(projectionState) }) + storeState = applyPatch(storeState, patch).newDocument + set({ lastVersion: version, ...storeState }) }) es.addEventListener('delta', (e) => { const { version, path, delta } = JSON.parse(e.data) set(s => { - if (path === 'thinking_buffer') + if (path === 'thinkingBuffer') return { lastVersion: version, thinkingBuffer: s.thinkingBuffer + delta, isThinking: true } - if (path === 'stream_buffer') + if (path === 'streamBuffer') return { lastVersion: version, streamBuffer: s.streamBuffer + delta, isThinking: false } return { lastVersion: version } }) }) ``` -That is the **entire** frontend sync implementation. No `applyEvent`. No 33-case switch. No fold logic. No buffer flushing. No agent filtering. No `completedCallIds` sets. - -**`isThinking` is a stored field, not derived.** The `delta` handler for `thinking_buffer` sets `isThinking: true`. When the fold flushes `thinking_buffer` into a `ThinkingEntry` (on transition to a tool call or text output), the patch clears `thinking_buffer` to `""` and the next `mapProjectionToStore` call sees the empty buffer. The `patch` handler also sets `isThinking: false` when it detects `thinkingBuffer` was cleared. This avoids the component needing to derive `isThinking` from buffer length — it reads a definitive boolean. +That is the **entire** frontend sync implementation. No `applyEvent`. No 33-case switch. No fold logic. No buffer flushing. No agent filtering. No `completedCallIds` sets. No `mapProjectionToStore`. No field renaming. -`mapProjectionToStore` is a pure mapping from Python snake_case field names to the Zustand store's shape. It does not interpret, filter, or transform — it renames fields. Example: `state.primary_agent` → `primaryAgent`, `state.config_active_profile` → `configActiveProfile`. Agent and artifact sub-objects go through lightweight transform helpers (`transformAgent`, `transformArtifact`) that handle field renaming and type coercion from JSON to TypeScript types. +**`storeState`** is a module-level variable in `connect.ts` that holds the current raw projection dict for patch application. It must be a plain JS object (not Zustand state) because `fast-json-patch`'s `applyPatch` operates on plain objects. On snapshot, it is replaced wholesale. On patch, `applyPatch` returns a `newDocument` (the immutable variant — avoids mutating the previous state in case Zustand still references it). The Zustand store is updated by spreading `storeState` into it. -**`projectionState`** is a module-level variable in `connect.ts` that holds the current raw projection dict (the last received snapshot or the result of applying all patches). It is the source of truth for patch application — patches mutate it, and `mapProjectionToStore` reads from it. It is separate from the Zustand store because `fast-json-patch` operates on plain JS objects, not Zustand state. On snapshot, it is replaced wholesale. On patch, it is mutated in-place (RFC 6902 `applyPatch` is destructive by default; the immutable variant produces a new object). +**`isThinking` is a stored field, not derived.** The `delta` handler for `thinkingBuffer` sets `isThinking: true`. When the fold flushes `thinking_buffer` into a `ThinkingEntry` (on transition to a tool call or text output), the patch clears `thinkingBuffer` to `""` and the spread into the store updates it. The `patch` handler implicitly sets `isThinking` to `false` when the snapshot state has an empty `thinkingBuffer`. Components read a definitive boolean, not a derived check. -**Error handling:** If `jsonpatch.apply` fails (malformed patch, version gap, or stale state), the client cannot safely continue — its local state may be inconsistent. The correct recovery is to force a reconnect with `since=0` to get a fresh snapshot. The error handler should: log the error, close the EventSource, reset `lastVersion` to 0, and reconnect. This is analogous to how `fatal_error` is handled today. +**Error handling:** If `applyPatch` throws (malformed patch, path mismatch, or stale state), the client cannot safely continue — its local state may be inconsistent. The correct recovery is to force a reconnect with `since=0` to get a fresh snapshot. The error handler should: log the error, close the EventSource, reset `lastVersion` to 0, and reconnect. **Ordering guarantee:** SSE messages are delivered in order over a single HTTP connection. Patches cannot arrive out of order. If the connection drops, the client reconnects and receives a fresh snapshot — there is no partial patch replay to misorder. The `version` field in each message is for diagnostics only; the client does not need to reorder messages. @@ -179,24 +202,24 @@ The projection is the single materialized view of all state. The backend fold pr The primary agent's activity is a timeline: reasoning blocks, text output, tool calls, step transitions. Each entry type has exactly the fields it needs — no optional fields that only apply to other variants. ```python -class ThinkingEntry(BaseModel): +class ThinkingEntry(KoanBaseModel): type: Literal["thinking"] = "thinking" content: str # full accumulated thinking text -class TextEntry(BaseModel): +class TextEntry(KoanBaseModel): type: Literal["text"] = "text" text: str # full accumulated stream text -class StepEntry(BaseModel): +class StepEntry(KoanBaseModel): type: Literal["step"] = "step" step: int - step_name: str - total_steps: int | None = None + step_name: str # wire: "stepName" + total_steps: int | None = None # wire: "totalSteps" -class BaseToolEntry(BaseModel): +class BaseToolEntry(KoanBaseModel): """Shared fields for all tool conversation entries.""" - call_id: str - in_flight: bool + call_id: str # wire: "callId" + in_flight: bool # wire: "inFlight" class ToolReadEntry(BaseToolEntry): type: Literal["tool_read"] = "tool_read" @@ -266,7 +289,7 @@ The fold maintains `conversation: list[ConversationEntry]` plus two transient bu ### Full projection ```python -class Projection(BaseModel): +class Projection(KoanBaseModel): # inherits alias_generator=to_camel run_started: bool = False phase: str = "" @@ -296,7 +319,7 @@ class Projection(BaseModel): ### Agent model ```python -class AgentProjection(BaseModel): +class AgentProjection(KoanBaseModel): agent_id: str role: str label: str = "" # NEW — scout identifier (e.g. "engine-methods") @@ -407,36 +430,39 @@ class AgentProjection(BaseModel): ### Phase 1: Backend — materialized projection with JSON Patch 1. `pip install jsonpatch` — add to dependencies -2. Define `ConversationEntry` union and all entry types in `koan/projections.py` -3. Add `conversation`, `thinking_buffer` to `Projection`; remove `activity_log` -4. Add `status`, `error`, `last_tool` to `AgentProjection` -5. Rewrite fold cases for all 33 event types -6. Update `ProjectionStore.push_event()`: - - Compute JSON Patch between old and new `model_dump()` - - For `thinking`/`stream_delta`: broadcast `delta` message instead of patch - - For all others: broadcast `patch` message +2. Define `KoanBaseModel` with `alias_generator=to_camel, populate_by_name=True` and `to_wire()` method +3. Define `ConversationEntry` union and all entry types inheriting `KoanBaseModel` +4. Migrate `Projection`, `AgentProjection`, and all sub-models to inherit `KoanBaseModel` +5. Add `conversation`, `thinking_buffer` to `Projection`; remove `activity_log` +6. Add `label`, `status`, `error`, `last_tool` to `AgentProjection` +7. Rewrite fold cases for all 36 event types +8. Update `ProjectionStore.push_event()`: + - Use `projection.to_wire()` (not `model_dump()`) for camelCase dicts + - Compute JSON Patch between old and new `to_wire()` output + - For `thinking`/`stream_delta`: broadcast `delta` message with camelCase path + - For all others: broadcast `patch` message (paths are automatically camelCase) - Store `prev_state` for next diff computation -7. Update `sse_stream()`: - - `since=0`: send snapshot, then live +9. Update `sse_stream()`: + - `since=0`: send snapshot via `to_wire()`, then live - `since=N` where N == server version: skip snapshot, go straight to live - `since=N` where N != server version: send fresh snapshot (not event replay) - Remove `events_since()` — no longer used for catch-up - Remove `fatal_error` path — replaced by always-snapshot (client auto-recovers from version regression) -8. Update `get_snapshot()` — unchanged; `model_dump()` naturally includes `conversation` +10. Update `get_snapshot()` to use `to_wire()` — output is camelCase, frontend reads it directly ### Phase 2: Frontend — dumb renderer 1. `npm install fast-json-patch` -2. Define TypeScript `ConversationEntry` union matching Python exactly (snake_case) +2. Define TypeScript `ConversationEntry` union matching the wire format (camelCase) 3. Replace `connect.ts`: - 3 event listeners: `snapshot`, `patch`, `delta` - - Module-level `projectionState` variable for patch application + - Module-level `storeState` variable for patch application - Remove KNOWN_EVENTS list and per-event-type listeners - Remove `fatal_error` listener (no longer emitted) -4. Replace `applySnapshot`: direct field mapping from `mapProjectionToStore()`, no re-folding -5. Delete `applyEvent` entirely -6. `mapProjectionToStore()`: pure field-rename function. Reads `projectionState` and produces Zustand-shaped state. `isThinking` is set: `true` when `thinkingBuffer !== ''`, `false` otherwise. The `delta` handler also sets `isThinking: true` directly for immediate reactivity. -7. Update `ActivityFeed` and components to read `ConversationEntry` field names +4. Delete `applySnapshot` and `applyEvent` entirely — snapshot spreads directly into store +5. Delete `mapProjectionToStore()` — no field renaming needed (server emits camelCase) +6. Update Zustand store field names to match wire format where they diverge +7. Update `ActivityFeed` and components to read `ConversationEntry` camelCase field names (`callId`, `inFlight`, `stepName`, `toolName`) ### Phase 3: Tests @@ -449,7 +475,7 @@ class AgentProjection(BaseModel): ### Phase 4: Cleanup & docs -1. Remove dead frontend code: `applyEvent`, `ActivityEntry` type, buffer flush helpers, KNOWN_EVENTS +1. Remove dead frontend code: `applyEvent`, `applySnapshot`, `mapProjectionToStore`, `transformAgent`, `transformArtifact`, `ActivityEntry` type, buffer flush helpers, KNOWN_EVENTS 2. Remove `events_since()` from `ProjectionStore` 3. Update `docs/projections.md`: - Replace `activity_log` with `conversation` model @@ -503,12 +529,13 @@ Add module-level docstring: ProjectionStore maintains: - events: append-only audit log of all VersionedEvents - projection: materialized view produced by fold() — the source of truth - - prev_state: model_dump() of the previous projection, used for JSON Patch computation + - prev_state: to_wire() of the previous projection, used for JSON Patch computation -push_event() folds the event, computes a JSON Patch against prev_state, -and broadcasts either a patch or a delta message (for thinking/stream_delta). +push_event() folds the event, computes a JSON Patch between prev_state and +the new to_wire() output, and broadcasts either a patch or a delta message. +All wire output is camelCase via KoanBaseModel.to_wire() (alias_generator). The fold is the only place where business logic runs. The frontend applies -patches mechanically. +patches mechanically with no field renaming. ``` ### `frontend/src/sse/connect.ts` @@ -516,12 +543,13 @@ patches mechanically. After the change, the file should have a comment explaining: ``` State sync protocol: - snapshot → replace entire projectionState and Zustand store - patch → apply RFC 6902 patch to projectionState, then re-map to store - delta → append string delta to thinking_buffer or stream_buffer directly + snapshot → replace storeState + spread into Zustand + patch → apply RFC 6902 patch to storeState + spread into Zustand + delta → append string delta to thinkingBuffer or streamBuffer -projectionState is the raw dict that patches operate on. -mapProjectionToStore() renames fields for the Zustand store. +Server emits camelCase JSON (via Pydantic alias_generator). No field +renaming needed — wire keys match store keys. storeState is a plain JS +object for fast-json-patch; Zustand state is updated by spreading it. The frontend has no fold logic — all business rules live in the Python fold. ``` From 04920b38068486c1505b3e0c4080e11b03573eed Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 14:48:07 +0700 Subject: [PATCH 248/412] plan: uniform JSON Patch, drop delta bypass, rename pending fields MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Decisions: - Drop delta bypass — everything goes through JSON Patch including thinking/text deltas. 200KB/s on localhost is noise. Simplicity of uniform protocol (2 event types, 2 handlers, zero special cases) outweighs bandwidth savings that only matter at scale we'll never hit. - Rename thinking_buffer→pending_thinking, stream_buffer→pending_text. 'Buffer' describes implementation; 'pending' describes the content. - is_thinking is a projection field computed by the fold, arrives via patch like everything else. Frontend does not manage it. Frontend is now 2 handlers: snapshot (replace) + patch (apply). That's it. --- .../2026-03-31-symmetric-projection-folds.md | 108 +++++++----------- 1 file changed, 42 insertions(+), 66 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index bb719e0..c7cd3bc 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -26,19 +26,16 @@ The answer: it shouldn't. The fold exists in one place (Python). The frontend ap The fold runs **only in Python**. The frontend has **zero business logic** — no event interpretation, no buffer management, no agent filtering, no in-flight tracking. It receives state and renders it. -### Protocol: snapshot + JSON Patch + streaming deltas +### Protocol: snapshot + JSON Patch -The server sends three types of SSE messages: +The server sends two types of SSE messages: | SSE event | When | Payload | Client action | |-----------|------|---------|---------------| | `snapshot` | First connect, reconnect | `{version, state}` — full materialized projection (camelCase) | Replace entire store | -| `patch` | After each event (except deltas) | `{version, patch}` — RFC 6902 JSON Patch operations (camelCase paths) | `applyPatch(store, patch)` | -| `delta` | `thinking` / `stream_delta` events | `{version, path, delta}` — string append (camelCase path) | `store[path] += delta` | +| `patch` | After each event | `{version, patch}` — RFC 6902 JSON Patch operations (camelCase paths) | `applyPatch(store, patch)` | -**Why three types, not just patches?** - -JSON Patch's `replace` operation for a growing string buffer is O(buffer_size) per delta. A `thinking_buffer` at 10KB with 20 deltas/second produces 200KB/s of patches — vs 600B/s for raw deltas. Streaming buffers are special-cased for bandwidth efficiency. Everything else goes through standard JSON Patch. +**Everything goes through JSON Patch — including thinking and text deltas.** A thinking delta produces a `replace` on `/pendingThinking` carrying the full accumulated string. At 10KB of accumulated thinking with 20 deltas/second, this is ~200KB/s of patches. On a remote server this would warrant a special-cased delta bypass. But koan is a localhost tool — loopback traffic doesn't hit a NIC, and 200KB/s is noise compared to the LLM API traffic that dwarfs it. The simplicity of a uniform protocol (two event types, two handlers, zero special cases) is worth more than the bandwidth savings of a third event type that only matters at scale we'll never hit. ### Connection lifecycle @@ -46,8 +43,8 @@ JSON Patch's `replace` operation for a growing string buffer is O(buffer_size) p First connect: GET /events?since=0 ← snapshot {version: N, state: <Projection>} (camelCase keys) ← patch {version: N+1, patch: [...]} (camelCase paths) - ← delta {version: N+2, path: "thinkingBuffer", delta: "The user"} - ← delta {version: N+3, path: "thinkingBuffer", delta: " wants me"} + ← patch {version: N+2, patch: [{op:"replace", path:"/pendingThinking", value:"The user"}]} + ← patch {version: N+3, patch: [{op:"replace", path:"/pendingThinking", value:"The user wants me"}]} ← patch {version: N+4, patch: [...]} ... @@ -87,30 +84,22 @@ def push_event(self, event_type, payload, agent_id=None): new_state = self.projection.to_wire() # camelCase via alias_generator self.prev_state = new_state - # Streaming deltas: bypass JSON Patch, send raw delta - if event_type in ("thinking", "stream_delta"): - msg = {"type": "delta", "version": self.version, - "path": "thinkingBuffer" if event_type == "thinking" else "streamBuffer", - "delta": payload["delta"]} - else: - patch = jsonpatch.make_patch(old_state, new_state) - if not patch: - return # no-op event (e.g. koan MCP tool filtered by fold) - msg = {"type": "patch", "version": self.version, - "patch": patch.to_string()} - - # Broadcast to all subscribers as a plain dict + patch = jsonpatch.make_patch(old_state, new_state) + if not patch: + return # no-op (e.g. koan MCP tool filtered by fold) + + msg = {"type": "patch", "version": self.version, "patch": patch.to_string()} for q in list(self.subscribers): q.put_nowait(msg) ``` -Subscriber queues carry **plain dicts**, not `VersionedEvent` objects. The dict shape matches the SSE JSON payload directly — the `sse_stream()` consumer just serializes and sends. This is a deliberate simplification: the raw event is for the audit log, the dict message is for the wire. +Every event takes the same path: fold, diff, broadcast. No branching on event type. Subscriber queues carry **plain dicts**, not `VersionedEvent` objects. The dict shape matches the SSE JSON payload directly — the `sse_stream()` consumer just serializes and sends. ### Wire format: camelCase via Pydantic aliases The server emits camelCase JSON. The frontend applies it directly — no field renaming, no shadow state, no mapping function. -Pydantic's `alias_generator` handles the conversion at serialization boundaries. Python fold code still uses snake_case attributes (`projection.thinking_buffer`). Only `to_wire()` output is camelCase: +Pydantic's `alias_generator` handles the conversion at serialization boundaries. Python fold code still uses snake_case attributes (`projection.pending_thinking`). Only `to_wire()` output is camelCase: ```python from pydantic import ConfigDict @@ -124,7 +113,7 @@ class KoanBaseModel(BaseModel): return self.model_dump(by_alias=True) ``` -All projection models (`Projection`, `AgentProjection`, `ConversationEntry` types, etc.) inherit from `KoanBaseModel`. Snapshot JSON, patch paths, and delta paths are all camelCase. The frontend receives `thinkingBuffer`, `primaryAgent`, `configActiveProfile` — matching JavaScript conventions natively. +All projection models (`Projection`, `AgentProjection`, `ConversationEntry` types, etc.) inherit from `KoanBaseModel`. Snapshot JSON and patch paths are all camelCase. The frontend receives `pendingThinking`, `primaryAgent`, `configActiveProfile` — matching JavaScript conventions natively. **Why not keep snake_case on the wire and rename in the frontend?** Because that requires a `mapProjectionToStore()` function that renames every field, a `projectionState` shadow variable holding the snake_case dict for patch application (separate from the Zustand store), and maintenance of both in sync with the Projection model. Every new field needs a rename entry. That mapping layer *is* business logic — it contradicts the "frontend has zero business logic" principle. Emitting camelCase from the server eliminates the layer entirely: patches apply directly to the store, snapshots spread directly into the store, and adding a field to the Projection requires zero frontend changes. @@ -144,24 +133,13 @@ es.addEventListener('patch', (e) => { storeState = applyPatch(storeState, patch).newDocument set({ lastVersion: version, ...storeState }) }) - -es.addEventListener('delta', (e) => { - const { version, path, delta } = JSON.parse(e.data) - set(s => { - if (path === 'thinkingBuffer') - return { lastVersion: version, thinkingBuffer: s.thinkingBuffer + delta, isThinking: true } - if (path === 'streamBuffer') - return { lastVersion: version, streamBuffer: s.streamBuffer + delta, isThinking: false } - return { lastVersion: version } - }) -}) ``` -That is the **entire** frontend sync implementation. No `applyEvent`. No 33-case switch. No fold logic. No buffer flushing. No agent filtering. No `completedCallIds` sets. No `mapProjectionToStore`. No field renaming. +That is the **entire** frontend sync implementation. Two handlers. No `applyEvent`. No 33-case switch. No fold logic. No buffer management. No agent filtering. No `completedCallIds` sets. No `mapProjectionToStore`. No field renaming. No special cases for streaming events. **`storeState`** is a module-level variable in `connect.ts` that holds the current raw projection dict for patch application. It must be a plain JS object (not Zustand state) because `fast-json-patch`'s `applyPatch` operates on plain objects. On snapshot, it is replaced wholesale. On patch, `applyPatch` returns a `newDocument` (the immutable variant — avoids mutating the previous state in case Zustand still references it). The Zustand store is updated by spreading `storeState` into it. -**`isThinking` is a stored field, not derived.** The `delta` handler for `thinkingBuffer` sets `isThinking: true`. When the fold flushes `thinking_buffer` into a `ThinkingEntry` (on transition to a tool call or text output), the patch clears `thinkingBuffer` to `""` and the spread into the store updates it. The `patch` handler implicitly sets `isThinking` to `false` when the snapshot state has an empty `thinkingBuffer`. Components read a definitive boolean, not a derived check. +**`isThinking`** is a projection field computed by the fold (`is_thinking = bool(self.pending_thinking)`). It arrives via patch like everything else. The frontend does not manage it — it reads a boolean from the store. When the fold flushes `pending_thinking` into a `ThinkingEntry`, it also sets `is_thinking = False`, and the patch carries both changes. **Error handling:** If `applyPatch` throws (malformed patch, path mismatch, or stale state), the client cannot safely continue — its local state may be inconsistent. The correct recovery is to force a reconnect with `since=0` to get a fresh snapshot. The error handler should: log the error, close the EventSource, reset `lastVersion` to 0, and reconnect. @@ -178,7 +156,7 @@ The initial design considered symmetric folds: identical fold logic in Python an | Fold implementations | 2 (Python + TypeScript) — must stay in sync forever | **1 (Python only)** | | New event type cost | Python fold + TS fold + TS snapshot reconstruction | **Python fold only** — frontend unchanged | | Bug surface | Proportional to event_type_count × 2 | Proportional to event_type_count × 1 | -| Frontend complexity | 33-case switch + buffer management + agent filtering | **3 event listeners, zero business logic** | +| Frontend complexity | 33-case switch + buffer management + agent filtering | **2 event listeners, zero business logic** | | Correctness guarantee | Requires "symmetric fold invariant" — manual discipline | **Correct by construction** — frontend cannot diverge | The dual-fold approach is *complected* in the Rich Hickey sense: fold logic interleaved with two language runtimes. The "symmetric fold invariant" is an admission that the architecture requires discipline to maintain. JSON Patch eliminates the problem: there is no invariant to enforce because the logic exists in one place. @@ -267,18 +245,18 @@ ConversationEntry = Annotated[ ### Fold rules -The fold maintains `conversation: list[ConversationEntry]` plus two transient buffers (`thinking_buffer`, `stream_buffer`). Buffers accumulate deltas; they flush to completed entries on transitions. +The fold maintains `conversation: list[ConversationEntry]` plus two pending fields (`pending_thinking`, `pending_text`). These accumulate deltas from the LLM; they flush to completed entries on transitions. | Event | Action | |-------|--------| -| `thinking` (primary only) | Flush `stream_buffer` → TextEntry. Append delta to `thinking_buffer`. | -| `stream_delta` (primary only) | Flush `thinking_buffer` → ThinkingEntry. Append delta to `stream_buffer`. | -| `tool_*` (primary, non-koan) | Flush both buffers. Append typed tool entry (`in_flight=True`). | +| `thinking` (primary only) | Flush `pending_text` → TextEntry. Append delta to `pending_thinking`. Set `is_thinking = True`. | +| `stream_delta` (primary only) | Flush `pending_thinking` → ThinkingEntry. Append delta to `pending_text`. Set `is_thinking = False`. | +| `tool_*` (primary, non-koan) | Flush both pending fields. Append typed tool entry (`in_flight=True`). Set `is_thinking = False`. | | `tool_called` (koan MCP — `koan_*`) | Ignore for conversation. | | `tool_completed` (primary only) | Set `in_flight=False` on matching `call_id`. | -| `agent_step_advanced` (primary) | Flush both buffers. Append StepEntry if `step >= 1`. Update agent step/tokens. | +| `agent_step_advanced` (primary) | Flush both pending fields. Append StepEntry if `step >= 1`. Update agent step/tokens. Set `is_thinking = False`. | | `agent_step_advanced` (scout) | Update scout step/tokens only. | -| `stream_cleared` (primary only) | Flush both buffers. | +| `stream_cleared` (primary only) | Flush both pending fields. Set `is_thinking = False`. | | Tool events (scout) | Update scout's `last_tool`. | | `agent_exited` | Set `status`, `error` on agent. Move to `completed_agents`. | @@ -299,10 +277,9 @@ class Projection(KoanBaseModel): # inherits alias_generator=to_camel completed_agents: list[AgentProjection] = [] conversation: list[ConversationEntry] = [] - thinking_buffer: str = "" # partial thinking in progress - stream_buffer: str = "" # partial text output in progress - # NOTE: stream_buffer already exists in the current Projection. - # thinking_buffer is new. Both are required for the delta SSE path. + pending_thinking: str = "" # in-progress thinking (wire: "pendingThinking") + pending_text: str = "" # in-progress text output (wire: "pendingText") + is_thinking: bool = False # wire: "isThinking" — True while thinking deltas are arriving active_interaction: InteractionState | None = None artifacts: dict[str, ArtifactInfo] = {} @@ -417,7 +394,7 @@ class AgentProjection(KoanBaseModel): - Tool call patches: ~100 bytes each (add entry to conversation array) - Step advance patches: ~200 bytes (flush + add) - `tool_completed`: ~80 bytes (replace one `in_flight` field) -- Thinking/stream deltas: bypassed entirely (raw delta events) +- Thinking deltas: `replace` on `/pendingThinking` — O(accumulated_size) per delta, ~200KB/s peak. Acceptable on localhost (see "Protocol" section). - Snapshot size at peak: ~50MB (dominated by artifact content references) - Snapshot sent only on connect/reconnect — not per-event @@ -433,14 +410,13 @@ class AgentProjection(KoanBaseModel): 2. Define `KoanBaseModel` with `alias_generator=to_camel, populate_by_name=True` and `to_wire()` method 3. Define `ConversationEntry` union and all entry types inheriting `KoanBaseModel` 4. Migrate `Projection`, `AgentProjection`, and all sub-models to inherit `KoanBaseModel` -5. Add `conversation`, `thinking_buffer` to `Projection`; remove `activity_log` +5. Add `conversation`, `pending_thinking`, `pending_text`, `is_thinking` to `Projection`; remove `activity_log` 6. Add `label`, `status`, `error`, `last_tool` to `AgentProjection` 7. Rewrite fold cases for all 36 event types 8. Update `ProjectionStore.push_event()`: - Use `projection.to_wire()` (not `model_dump()`) for camelCase dicts - Compute JSON Patch between old and new `to_wire()` output - - For `thinking`/`stream_delta`: broadcast `delta` message with camelCase path - - For all others: broadcast `patch` message (paths are automatically camelCase) + - Broadcast patch message (all events take the same path, no branching) - Store `prev_state` for next diff computation 9. Update `sse_stream()`: - `since=0`: send snapshot via `to_wire()`, then live @@ -455,7 +431,7 @@ class AgentProjection(KoanBaseModel): 1. `npm install fast-json-patch` 2. Define TypeScript `ConversationEntry` union matching the wire format (camelCase) 3. Replace `connect.ts`: - - 3 event listeners: `snapshot`, `patch`, `delta` + - 2 event listeners: `snapshot`, `patch` - Module-level `storeState` variable for patch application - Remove KNOWN_EVENTS list and per-event-type listeners - Remove `fatal_error` listener (no longer emitted) @@ -466,9 +442,9 @@ class AgentProjection(KoanBaseModel): ### Phase 3: Tests -1. Backend fold tests: assert `conversation` entries, `thinking_buffer`, `in_flight` state +1. Backend fold tests: assert `conversation` entries, `pending_thinking`, `is_thinking`, `in_flight` state 2. JSON Patch tests: fold event → verify patch operations are correct -3. Delta bypass tests: `thinking`/`stream_delta` produce delta messages, not patches +3. Thinking/stream patch tests: `thinking`/`stream_delta` produce `replace` patches on `pendingThinking`/`pendingText` 4. Snapshot round-trip: fold events → snapshot → verify frontend can read it directly 5. Reconnect test: client with stale version gets fresh snapshot 6. **Delete `events_since()` tests:** `test_projections.py` has tests that call `store.events_since()` directly (currently lines ~360–373). These must be deleted, not updated — the method no longer exists. Replace with tests that verify the snapshot contains the correct materialized state after N events. @@ -479,8 +455,7 @@ class AgentProjection(KoanBaseModel): 2. Remove `events_since()` from `ProjectionStore` 3. Update `docs/projections.md`: - Replace `activity_log` with `conversation` model - - Document JSON Patch protocol - - Document delta bypass for streaming buffers + - Document JSON Patch protocol (two event types: snapshot, patch) - Update fold rules table 4. Update `docs/architecture.md`: - Add invariant: "The fold runs only in Python. The frontend applies server-computed patches. It has no business logic." @@ -492,7 +467,7 @@ class AgentProjection(KoanBaseModel): **JSON Patch array diffing:** `make_patch` uses positional indices for arrays. Conversation is append-only (entries are never reordered or removed), so patches are clean `add` operations at the end. The one mutation is `tool_completed` setting `in_flight=False` on an existing entry, which produces a targeted `replace` at `/conversation/N/in_flight`. -**Patch computation cost:** `make_patch` diffs two dicts. At 50MB state, this could be expensive. Mitigation: most events change a small part of state; the diff is proportional to what changed, not total state. For the dominant case (thinking delta), the diff is bypassed entirely. +**Patch computation cost:** `make_patch` diffs two dicts. At 50MB state, this could be expensive. Mitigation: most events change a small part of state; the diff is proportional to what changed, not total state. Thinking deltas produce a `replace` on a single string field — the diff is O(1) to detect, though the patch payload is O(accumulated_size). This is acceptable on localhost (see protocol section). **Library trust:** `jsonpatch` (Python, 10+ years, well-maintained) and `fast-json-patch` (JavaScript, RFC 6902 compliant, widely used). Both are mature. @@ -506,10 +481,10 @@ These changes require corresponding updates to existing docs. Do not defer — o ### `docs/projections.md` -1. **Projection model:** Replace `activity_log: list[dict]` with `conversation: list[ConversationEntry]` and `thinking_buffer: str`. Add the full `ConversationEntry` union definition with all 10 entry types. -2. **SSE protocol section:** Replace the current "snapshot + raw events" description with the new three-message protocol (`snapshot`, `patch`, `delta`). Include the connection lifecycle diagram from this plan. -3. **Fold rules table:** Rewrite the activity section — replace "append raw event to activity_log" with the actual fold rules (buffer accumulation, flush triggers, in-flight tracking, agent filtering, koan MCP filtering). -4. **"Why catch-up uses snapshots":** Document the bandwidth analysis: thinking delta patches at 200KB/s vs 600B/s for raw deltas. Document the memory cost of storing 500K patches. This decision must be visible, not inferred. +1. **Projection model:** Replace `activity_log: list[dict]` with `conversation: list[ConversationEntry]`, `pending_thinking: str`, `pending_text: str`, `is_thinking: bool`. Add the full `ConversationEntry` union definition with all 10 entry types. +2. **SSE protocol section:** Replace the current "snapshot + raw events" description with the two-message protocol (`snapshot`, `patch`). Include the connection lifecycle diagram from this plan. +3. **Fold rules table:** Rewrite the activity section — replace "append raw event to activity_log" with the actual fold rules (pending field accumulation, flush triggers, in-flight tracking, agent filtering, koan MCP filtering). +4. **"Why catch-up uses snapshots":** Document the memory cost of storing 500K patches. Document the localhost assumption that makes uniform JSON Patch viable for streaming (no delta bypass needed). These decisions must be visible, not inferred. 5. **Event types:** Add `scout_queued` and the 6 typed tool events (`tool_read` through `tool_ls`) which are currently missing. 6. **`AgentProjection`:** Add `status`, `error`, `last_tool`, `label` fields. 7. **Remove:** The "Why activity_log stores raw events" section — that rationale is obsolete. @@ -532,7 +507,8 @@ ProjectionStore maintains: - prev_state: to_wire() of the previous projection, used for JSON Patch computation push_event() folds the event, computes a JSON Patch between prev_state and -the new to_wire() output, and broadcasts either a patch or a delta message. +the new to_wire() output, and broadcasts the patch. Every event takes the +same path: fold → diff → broadcast. No branching on event type. All wire output is camelCase via KoanBaseModel.to_wire() (alias_generator). The fold is the only place where business logic runs. The frontend applies patches mechanically with no field renaming. @@ -545,11 +521,11 @@ After the change, the file should have a comment explaining: State sync protocol: snapshot → replace storeState + spread into Zustand patch → apply RFC 6902 patch to storeState + spread into Zustand - delta → append string delta to thinkingBuffer or streamBuffer Server emits camelCase JSON (via Pydantic alias_generator). No field renaming needed — wire keys match store keys. storeState is a plain JS object for fast-json-patch; Zustand state is updated by spreading it. +All events — including thinking/text deltas — go through JSON Patch. The frontend has no fold logic — all business rules live in the Python fold. ``` @@ -561,7 +537,7 @@ The six core invariants are unchanged. The new architecture is a refinement of h ## Migration -**Breaking change.** The SSE protocol changes from per-event-type messages to `snapshot`/`patch`/`delta`. Old clients cannot connect to new servers (they'd receive unknown event types). Old servers cannot serve new clients (missing `patch` event). +**Breaking change.** The SSE protocol changes from per-event-type messages to `snapshot`/`patch`. Old clients cannot connect to new servers (they'd receive unknown event types). Old servers cannot serve new clients (missing `patch` event). **No on-disk migration.** All state is in-memory. Server restart already forces a full reload. From 6cb77d5776aee74b3564e4c4d0b3b768efcf5d72 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 16:16:15 +0700 Subject: [PATCH 249/412] =?UTF-8?q?plan:=20complete=20rewrite=20=E2=80=94?= =?UTF-8?q?=20unified=20agents=20dict,=20focus,=20settings/run=20split?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Projection model restructured from 15 top-level fields to 3: settings: Settings — persistent config + probe flags run: Run | None — ephemeral workflow state notifications — transient UI toasts Key design changes: - agents: dict[str, Agent] replaces primary_agent/scouts/queued_scouts/completed_agents - QueuedScout eliminated — Agent with status='queued' - Conversation per agent (entries + pending fields + stats) - Focus union replaces active_interaction — explicit main content state - Settings vs RunConfig: available vs what-this-run-uses - Installation.available flag replaces config_runners - run_started event carries RunConfig - Named entities as dicts for stable JSON Patch paths - 37 events across 5 categories (Lifecycle/Activity/Focus/Resources/Settings) - Fold rules grouped by concern, not by agent type --- .../2026-03-31-symmetric-projection-folds.md | 618 +++++++++++------- 1 file changed, 399 insertions(+), 219 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index c7cd3bc..02e8c7a 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -35,31 +35,29 @@ The server sends two types of SSE messages: | `snapshot` | First connect, reconnect | `{version, state}` — full materialized projection (camelCase) | Replace entire store | | `patch` | After each event | `{version, patch}` — RFC 6902 JSON Patch operations (camelCase paths) | `applyPatch(store, patch)` | -**Everything goes through JSON Patch — including thinking and text deltas.** A thinking delta produces a `replace` on `/pendingThinking` carrying the full accumulated string. At 10KB of accumulated thinking with 20 deltas/second, this is ~200KB/s of patches. On a remote server this would warrant a special-cased delta bypass. But koan is a localhost tool — loopback traffic doesn't hit a NIC, and 200KB/s is noise compared to the LLM API traffic that dwarfs it. The simplicity of a uniform protocol (two event types, two handlers, zero special cases) is worth more than the bandwidth savings of a third event type that only matters at scale we'll never hit. +**Everything goes through JSON Patch — including thinking and text deltas.** A thinking delta produces a `replace` on the agent's `pendingThinking` field carrying the full accumulated string. At 10KB of accumulated thinking with 20 deltas/second, this is ~200KB/s of patches. On a remote server this would warrant a special-cased delta bypass. But koan is a localhost tool — loopback traffic doesn't hit a NIC, and 200KB/s is noise compared to the LLM API traffic that dwarfs it. **The simplicity of a uniform protocol (two event types, two handlers, zero special cases) is worth more than the bandwidth savings of a third event type that only matters at scale we'll never hit.** ### Connection lifecycle ``` First connect: GET /events?since=0 - ← snapshot {version: N, state: <Projection>} (camelCase keys) - ← patch {version: N+1, patch: [...]} (camelCase paths) - ← patch {version: N+2, patch: [{op:"replace", path:"/pendingThinking", value:"The user"}]} - ← patch {version: N+3, patch: [{op:"replace", path:"/pendingThinking", value:"The user wants me"}]} - ← patch {version: N+4, patch: [...]} + ← snapshot {version: N, state: {...}} (camelCase keys) + ← patch {version: N+1, patch: [...]} (camelCase paths) + ← patch {version: N+2, patch: [...]} ... -Reconnect: GET /events?since=N+4 - ← snapshot {version: M, state: <Projection>} +Reconnect: GET /events?since=N+2 + ← snapshot {version: M, state: {...}} (always a fresh snapshot — no patch replay) -Server restart: GET /events?since=N+4 - ← snapshot {version: 0, state: <empty projection>} +Server restart: GET /events?since=N+2 + ← snapshot {version: 0, state: {settings: {...}, run: null}} (client detects version < lastVersion, resets UI) ``` -**Catch-up always uses snapshots.** Storing patches for replay is expensive (200K–500K events over a full epic, thinking patches are large). On reconnect, the server sends a fresh snapshot at the current version. The `since` parameter is a version check: if it matches the server's version, skip the snapshot and go straight to live events. Otherwise, send a snapshot. +**Catch-up always uses snapshots.** Storing patches for replay is expensive (200K–500K events over a full epic). On reconnect, the server sends a fresh snapshot at the current version. The `since` parameter is a version check: if it matches the server's version, skip the snapshot and go straight to live events. Otherwise, send a snapshot. -This eliminates `events_since()` and the catch-up replay code path entirely. It also **eliminates `fatal_error`**: the current code sends `fatal_error` when `since > store.version` (after server restart), requiring the user to manually reload. The new design always sends a snapshot instead — the client detects the version regression (`snapshot.version < lastVersion`) and resets its UI automatically. One code path for all reconnects. +This eliminates `events_since()` and the catch-up replay code path entirely. It also eliminates `fatal_error`: the current code sends `fatal_error` when `since > store.version` (after server restart), requiring manual reload. The new design always sends a snapshot — the client detects the version regression and resets automatically. One code path for all reconnects. ### What the server stores @@ -93,13 +91,13 @@ def push_event(self, event_type, payload, agent_id=None): q.put_nowait(msg) ``` -Every event takes the same path: fold, diff, broadcast. No branching on event type. Subscriber queues carry **plain dicts**, not `VersionedEvent` objects. The dict shape matches the SSE JSON payload directly — the `sse_stream()` consumer just serializes and sends. +Every event takes the same path: fold, diff, broadcast. No branching on event type. Subscriber queues carry **plain dicts** — the dict shape matches the SSE JSON payload directly, and the `sse_stream()` consumer just serializes and sends. ### Wire format: camelCase via Pydantic aliases The server emits camelCase JSON. The frontend applies it directly — no field renaming, no shadow state, no mapping function. -Pydantic's `alias_generator` handles the conversion at serialization boundaries. Python fold code still uses snake_case attributes (`projection.pending_thinking`). Only `to_wire()` output is camelCase: +Pydantic's `alias_generator` handles the conversion at serialization boundaries. Python fold code uses snake_case attributes (`agent.conversation.pending_thinking`). Only `to_wire()` output is camelCase: ```python from pydantic import ConfigDict @@ -113,14 +111,14 @@ class KoanBaseModel(BaseModel): return self.model_dump(by_alias=True) ``` -All projection models (`Projection`, `AgentProjection`, `ConversationEntry` types, etc.) inherit from `KoanBaseModel`. Snapshot JSON and patch paths are all camelCase. The frontend receives `pendingThinking`, `primaryAgent`, `configActiveProfile` — matching JavaScript conventions natively. +All projection models inherit from `KoanBaseModel`. Snapshot JSON and patch paths are all camelCase. The frontend receives `pendingThinking`, `scoutConcurrency`, `isThinking` — matching JavaScript conventions natively. -**Why not keep snake_case on the wire and rename in the frontend?** Because that requires a `mapProjectionToStore()` function that renames every field, a `projectionState` shadow variable holding the snake_case dict for patch application (separate from the Zustand store), and maintenance of both in sync with the Projection model. Every new field needs a rename entry. That mapping layer *is* business logic — it contradicts the "frontend has zero business logic" principle. Emitting camelCase from the server eliminates the layer entirely: patches apply directly to the store, snapshots spread directly into the store, and adding a field to the Projection requires zero frontend changes. +**Why not keep snake_case on the wire and rename in the frontend?** Because that requires a `mapProjectionToStore()` function that renames every field, a `projectionState` shadow variable for patch application, and maintenance of both in sync with the Projection model. Every new field needs a rename entry. That mapping layer *is* business logic — it contradicts the "frontend has zero business logic" principle. Emitting camelCase from the server eliminates the layer entirely: patches apply directly to the store, snapshots spread directly into the store, adding a field to the Projection requires zero frontend changes. -### Frontend event handling — complete implementation +### Frontend — complete implementation ```typescript -let storeState: Record<string, unknown> = {} // raw state for patch application +let storeState: Record<string, unknown> = {} es.addEventListener('snapshot', (e) => { const { version, state } = JSON.parse(e.data) @@ -135,69 +133,252 @@ es.addEventListener('patch', (e) => { }) ``` -That is the **entire** frontend sync implementation. Two handlers. No `applyEvent`. No 33-case switch. No fold logic. No buffer management. No agent filtering. No `completedCallIds` sets. No `mapProjectionToStore`. No field renaming. No special cases for streaming events. +That is the **entire** frontend sync implementation. Two handlers. No `applyEvent`. No 33-case switch. No fold logic. No buffer management. No agent filtering. No field renaming. No special cases. -**`storeState`** is a module-level variable in `connect.ts` that holds the current raw projection dict for patch application. It must be a plain JS object (not Zustand state) because `fast-json-patch`'s `applyPatch` operates on plain objects. On snapshot, it is replaced wholesale. On patch, `applyPatch` returns a `newDocument` (the immutable variant — avoids mutating the previous state in case Zustand still references it). The Zustand store is updated by spreading `storeState` into it. +**`storeState`** is a module-level variable in `connect.ts` — the raw projection dict for patch application. It must be a plain JS object because `fast-json-patch`'s `applyPatch` operates on plain objects. On snapshot, it is replaced wholesale. On patch, `applyPatch` returns a `newDocument` (immutable variant — avoids mutating state Zustand may still reference). -**`isThinking`** is a projection field computed by the fold (`is_thinking = bool(self.pending_thinking)`). It arrives via patch like everything else. The frontend does not manage it — it reads a boolean from the store. When the fold flushes `pending_thinking` into a `ThinkingEntry`, it also sets `is_thinking = False`, and the patch carries both changes. +**Error handling:** If `applyPatch` throws, the client's local state may be inconsistent. Recovery: log the error, close EventSource, reset `lastVersion` to 0, reconnect for a fresh snapshot. -**Error handling:** If `applyPatch` throws (malformed patch, path mismatch, or stale state), the client cannot safely continue — its local state may be inconsistent. The correct recovery is to force a reconnect with `since=0` to get a fresh snapshot. The error handler should: log the error, close the EventSource, reset `lastVersion` to 0, and reconnect. - -**Ordering guarantee:** SSE messages are delivered in order over a single HTTP connection. Patches cannot arrive out of order. If the connection drops, the client reconnects and receives a fresh snapshot — there is no partial patch replay to misorder. The `version` field in each message is for diagnostics only; the client does not need to reorder messages. +**Ordering guarantee:** SSE is connection-ordered. Patches cannot arrive out of order. If the connection drops, the client reconnects and gets a fresh snapshot. The `version` field is diagnostic only. --- -## Why not dual folds? +## Rejected alternatives -The initial design considered symmetric folds: identical fold logic in Python and TypeScript. This was rejected: +### Dual folds (symmetric fold in Python + TypeScript) | Concern | Dual folds | JSON Patch | |---------|-----------|------------| -| Fold implementations | 2 (Python + TypeScript) — must stay in sync forever | **1 (Python only)** | -| New event type cost | Python fold + TS fold + TS snapshot reconstruction | **Python fold only** — frontend unchanged | -| Bug surface | Proportional to event_type_count × 2 | Proportional to event_type_count × 1 | -| Frontend complexity | 33-case switch + buffer management + agent filtering | **2 event listeners, zero business logic** | -| Correctness guarantee | Requires "symmetric fold invariant" — manual discipline | **Correct by construction** — frontend cannot diverge | +| Fold implementations | 2 — must stay in sync forever | **1 (Python only)** | +| New event type cost | Python fold + TS fold + TS snapshot | **Python fold only** | +| Bug surface | event_type_count × 2 | event_type_count × 1 | +| Frontend complexity | 33-case switch, buffer management, agent filtering | **2 event listeners, zero logic** | +| Correctness | Requires discipline ("symmetric fold invariant") | **Correct by construction** | -The dual-fold approach is *complected* in the Rich Hickey sense: fold logic interleaved with two language runtimes. The "symmetric fold invariant" is an admission that the architecture requires discipline to maintain. JSON Patch eliminates the problem: there is no invariant to enforce because the logic exists in one place. +The dual-fold approach is *complected*: fold logic interleaved with two language runtimes. JSON Patch eliminates the invariant because the logic exists in one place. -### Why not WASM shared fold? +### WASM shared fold Compile fold to WASM, run in both Python and browser. Eliminates duplication but adds WASM toolchain, FFI boundaries, and build complexity. Over-engineered for a single-user local tool. -### Why not server-rendered HTML (LiveView)? +### Server-rendered HTML (LiveView) Server renders the full UI, sends DOM diffs. Zero client logic. But koan's UI has rich interactivity — question wizards, settings overlays, artifact browsing, drag interactions. LiveView fights against client-side interactivity. +### Delta bypass for streaming + +Special-case `thinking`/`stream_delta` events: send raw string deltas instead of JSON Patch `replace` operations. Saves bandwidth (600B/s vs 200KB/s for thinking). Rejected because koan is localhost — loopback bandwidth is free, and the complexity of a third event type (third handler, branching in `push_event`, special-case in frontend) is not worth the savings. Two event types, two handlers, zero special cases. + --- ## Projection Model -The projection is the single materialized view of all state. The backend fold produces it, `get_snapshot()` serializes it, patches express incremental changes to it, the frontend renders it. +### Top-level structure + +The projection has three concerns with different lifetimes: + +```python +class Projection(KoanBaseModel): + settings: Settings = Settings() # persistent config + probe results + run: Run | None = None # None when no run is active + notifications: list[Notification] = [] # transient UI toasts +``` + +`run is None` → show landing page. `run.completion is not None` → run finished. No boolean flags. + +### Settings + +Settings are what's *available* — they exist before any run, persist across runs to `~/.koan/config.json`, and describe the user's configured environment. + +```python +class Installation(KoanBaseModel): + """A configured LLM CLI installation.""" + alias: str # unique key: "claude-default", "claude-fast" + runner_type: str # "claude" | "codex" | "gemini" + binary: str # resolved path: "/usr/local/bin/claude" + extra_args: list[str] = [] # e.g. ["--effort", "low"] + available: bool = False # probe result: binary exists and responds + # Everything except `available` persists to config.json. + # `available` is ephemeral — re-probed each server start. + # Replaces the separate `config_runners` concept: the list of available + # runner types is derivable from installations where available == True. + +class Profile(KoanBaseModel): + """Maps roles to installations for a workflow run.""" + name: str # "balanced", "thorough", "fast" + read_only: bool = False # built-in profiles can't be edited + tiers: dict[str, str] = {} # role → installation alias + # {"primary": "claude-default", "scout": "haiku-default"} + +class Settings(KoanBaseModel): + installations: dict[str, Installation] = {} # alias → Installation + profiles: dict[str, Profile] = {} # name → Profile + default_profile: str = "balanced" # pre-selected for next run + default_scout_concurrency: int = 8 # default for next run + # installations and profiles are dicts (not lists) because JSON Patch + # paths for named entities must be stable — /settings/installations/claude-fast + # not /settings/installations/2 which shifts on insert/delete. +``` + +### Run configuration + +Run configuration describes *how a specific run uses settings*. Resolved from settings at run start, frozen for the run's lifetime. + +```python +class RunConfig(KoanBaseModel): + """Resolved configuration for a single workflow run.""" + profile: str # which profile was selected + installations: dict[str, str] # role → installation alias + # resolved from profile tiers + user overrides on landing page + # e.g. {"primary": "claude-default", "scout": "haiku-default"} + scout_concurrency: int # may differ from settings.default_scout_concurrency +``` + +The distinction between settings and run config: + +| | Settings | Run config | +|--|---------|-----------| +| Lifetime | Persists across runs | Single run | +| Mutation | Settings overlay, any time | Frozen at run start | +| `default_profile` | Pre-selected for next run | — | +| `profile` | — | Which profile this run uses | +| `scout_concurrency` | Default for next run | What this run uses | +| `installations` (map) | All configured installations | Role → alias mapping for this run | + +### Agent + +All agents — primary, scouts, queued — live in one dict. The lifecycle is a state machine on `status`. No separate collections, no `QueuedScout` type. + +```python +class Agent(KoanBaseModel): + # Identity — set at queue/spawn time, never changes + agent_id: str + role: str # "intake", "brief-writer", "implementer", ... + label: str = "" # human-readable: "engine-methods" for scouts + model: str | None = None # "sonnet", "haiku", "opus" + is_primary: bool = False + + # Lifecycle — state machine: queued → running → done | failed + status: Literal["queued", "running", "done", "failed"] = "queued" + error: str | None = None # set when status → failed + started_at_ms: int = 0 # 0 while queued + + # Progress — shown in agent monitor, updated during execution + step: int = 0 + step_name: str = "" + last_tool: str = "" # last tool summary for monitor display + + # Content + conversation: Conversation = Conversation() +``` + +The frontend derives views by filtering: + +```typescript +const primary = Object.values(agents).find(a => a.isPrimary && a.status === 'running') +const running = Object.values(agents).filter(a => !a.isPrimary && a.status === 'running') +const queued = Object.values(agents).filter(a => a.status === 'queued') +const done = Object.values(agents).filter(a => a.status === 'done' || a.status === 'failed') +``` + +### Conversation + +Per-agent. Groups everything about what an agent has said, done, and cost. The primary agent's conversation is rendered in the activity feed. Scout conversations are available for the agent monitor. + +```python +class Conversation(KoanBaseModel): + entries: list[ConversationEntry] = [] # materialized timeline + pending_thinking: str = "" # in-progress LLM reasoning, not yet flushed to ThinkingEntry + pending_text: str = "" # in-progress LLM text output, not yet flushed to TextEntry + is_thinking: bool = False # True while thinking deltas are arriving + input_tokens: int = 0 # accumulated from usage reports in agent_step_advanced + output_tokens: int = 0 +``` + +**Why `pending_thinking` / `pending_text`, not `thinkingBuffer` / `streamBuffer`?** "Buffer" describes the mechanism (accumulate, flush, reset). "Pending" describes the content: incomplete LLM output that will become a conversation entry on the next transition. The names should describe *what it is*, not *how it works*. + +**Why tokens are in Conversation, not Agent:** They're accumulated from conversation turns (each `agent_step_advanced` carries usage). They describe the cost of what the agent said, not the agent's identity or lifecycle. + +**Why `is_thinking` is a projection field, not derived:** The fold sets `is_thinking = True` when a thinking delta arrives and `False` on any transition. It arrives via patch like everything else. The frontend reads a boolean — no derivation logic. + +### Focus + +What the main content area renders. A discriminated union managed by the fold. Replaces the implicit "if interaction exists, show it, else show primary" logic. + +```python +class ConversationFocus(KoanBaseModel): + """Default state: showing an agent's conversation.""" + type: Literal["conversation"] = "conversation" + agent_id: str # whose conversation to render + +class QuestionFocus(KoanBaseModel): + """Agent is blocked, needs user input.""" + type: Literal["question"] = "question" + agent_id: str # who asked (conversation is backdrop) + token: str # correlation ID for response + questions: list[AskQuestion] + +class ReviewFocus(KoanBaseModel): + """Agent is blocked, artifact needs review.""" + type: Literal["review"] = "review" + agent_id: str + token: str + path: str # artifact under review + description: str + content: str + +class DecisionFocus(KoanBaseModel): + """Workflow decision needed from user.""" + type: Literal["decision"] = "decision" + agent_id: str + token: str + chat_turns: list[ChatTurn] + +Focus = Annotated[ + ConversationFocus | QuestionFocus | ReviewFocus | DecisionFocus, + Field(discriminator="type"), +] +``` + +The fold manages transitions: -### ConversationEntry — discriminated union of distinct types +| Event | Focus transition | +|-------|-----------------| +| `agent_spawned` (primary) | `ConversationFocus(agent_id=...)` | +| `questions_asked` | `QuestionFocus(agent_id=..., token=..., questions=...)` | +| `questions_answered` | `ConversationFocus(agent_id=primary_id)` | +| `artifact_review_requested` | `ReviewFocus(...)` | +| `artifact_reviewed` | `ConversationFocus(agent_id=primary_id)` | +| `workflow_decision_requested` | `DecisionFocus(...)` | +| `workflow_decided` | `ConversationFocus(agent_id=primary_id)` | -The primary agent's activity is a timeline: reasoning blocks, text output, tool calls, step transitions. Each entry type has exactly the fields it needs — no optional fields that only apply to other variants. +The frontend rendering is a switch on `focus.type` — no conditional logic about "is there an active interaction." + +`agent_id` on every variant means the frontend always knows whose conversation is the backdrop. A question overlays the asking agent's scrolled-up conversation. + +### ConversationEntry — discriminated union + +Each entry type has exactly the fields it needs. No optional fields that only apply to other variants. ```python class ThinkingEntry(KoanBaseModel): type: Literal["thinking"] = "thinking" - content: str # full accumulated thinking text + content: str # full accumulated thinking text class TextEntry(KoanBaseModel): type: Literal["text"] = "text" - text: str # full accumulated stream text + text: str # full accumulated output text class StepEntry(KoanBaseModel): type: Literal["step"] = "step" step: int - step_name: str # wire: "stepName" - total_steps: int | None = None # wire: "totalSteps" + step_name: str + total_steps: int | None = None class BaseToolEntry(KoanBaseModel): - """Shared fields for all tool conversation entries.""" - call_id: str # wire: "callId" - in_flight: bool # wire: "inFlight" + """Shared fields for all tool entries.""" + call_id: str # unique per tool invocation + in_flight: bool # True until tool_completed class ToolReadEntry(BaseToolEntry): type: Literal["tool_read"] = "tool_read" @@ -237,90 +418,144 @@ ConversationEntry = Annotated[ ] ``` -**Why one type per variant:** Invalid states are unrepresentable. You cannot access `.command` on a `ThinkingEntry`. The type system enforces valid field combinations. Each type maps 1:1 to a frontend rendering component. +**`tool_completed` handling:** The fold scans `agent.conversation.entries` for `isinstance(entry, BaseToolEntry) and entry.call_id == target`, sets `in_flight = False`. -**`tool_completed` handling:** All tool types inherit `BaseToolEntry` with `call_id` and `in_flight`. The fold scans `conversation` for `isinstance(entry, BaseToolEntry) and entry.call_id == target`, sets `in_flight = False`. +**Extensibility:** Adding `ToolWebFetchEntry` means: define the model, add to the union, add a fold case. The frontend is unchanged — JSON Patch carries the new structure automatically. -**Extensibility:** Adding `ToolWebFetchEntry` means: define the Pydantic model, add to the union, add a fold case. The frontend is unchanged — JSON Patch carries the new entry structure automatically. +### Run -### Fold rules +Ephemeral workflow state. Exists only during a run. -The fold maintains `conversation: list[ConversationEntry]` plus two pending fields (`pending_thinking`, `pending_text`). These accumulate deltas from the LLM; they flush to completed entries on transitions. +```python +class Run(KoanBaseModel): + config: RunConfig # frozen at run start + phase: str = "" # current workflow phase + agents: dict[str, Agent] = {} # all agents by ID, all lifecycle states + focus: Focus | None = None # None before first agent spawns + artifacts: dict[str, ArtifactInfo] = {} + completion: CompletionInfo | None = None +``` -| Event | Action | -|-------|--------| -| `thinking` (primary only) | Flush `pending_text` → TextEntry. Append delta to `pending_thinking`. Set `is_thinking = True`. | -| `stream_delta` (primary only) | Flush `pending_thinking` → ThinkingEntry. Append delta to `pending_text`. Set `is_thinking = False`. | -| `tool_*` (primary, non-koan) | Flush both pending fields. Append typed tool entry (`in_flight=True`). Set `is_thinking = False`. | -| `tool_called` (koan MCP — `koan_*`) | Ignore for conversation. | -| `tool_completed` (primary only) | Set `in_flight=False` on matching `call_id`. | -| `agent_step_advanced` (primary) | Flush both pending fields. Append StepEntry if `step >= 1`. Update agent step/tokens. Set `is_thinking = False`. | -| `agent_step_advanced` (scout) | Update scout step/tokens only. | -| `stream_cleared` (primary only) | Flush both pending fields. Set `is_thinking = False`. | -| Tool events (scout) | Update scout's `last_tool`. | -| `agent_exited` | Set `status`, `error` on agent. Move to `completed_agents`. | +### Complete Projection -**Why primary-agent filtering is in the fold:** The fold owns the semantics of what belongs in the conversation. A single authoritative filter prevents the inconsistency bugs that triggered this plan. +```python +class Projection(KoanBaseModel): + settings: Settings = Settings() + run: Run | None = None + notifications: list[Notification] = [] +``` -**Why koan MCP tools are filtered:** `koan_complete_step` et al. are infrastructure — their effects are captured by `agent_step_advanced`, `questions_asked`, etc. Showing them as tool lines is noise. +Three top-level fields. Everything else is nested where it belongs. -### Full projection +**JSON Patch paths:** -```python -class Projection(KoanBaseModel): # inherits alias_generator=to_camel - run_started: bool = False - phase: str = "" +``` +Settings: /settings/installations/claude-default/available + /settings/profiles/balanced/tiers/primary + /settings/defaultProfile + /settings/defaultScoutConcurrency + +Run config: /run/config/profile + /run/config/scoutConcurrency + +Agent: /run/agents/abc123/status + /run/agents/abc123/step + /run/agents/abc123/lastTool + +Conversation:/run/agents/abc123/conversation/pendingThinking + /run/agents/abc123/conversation/entries/- + /run/agents/abc123/conversation/isThinking + /run/agents/abc123/conversation/inputTokens + +Focus: /run/focus +Artifacts: /run/artifacts/docs~1architecture.md/size +Phase: /run/phase +``` - primary_agent: AgentProjection | None = None - scouts: dict[str, AgentProjection] = {} - queued_scouts: list[QueuedScout] = [] - completed_agents: list[AgentProjection] = [] +Named entities (installations, profiles, agents, artifacts) are dicts for stable patch paths. Ordered collections (conversation entries, notifications) are lists — append-only, so positional indices are stable. - conversation: list[ConversationEntry] = [] - pending_thinking: str = "" # in-progress thinking (wire: "pendingThinking") - pending_text: str = "" # in-progress text output (wire: "pendingText") - is_thinking: bool = False # wire: "isThinking" — True while thinking deltas are arriving +--- - active_interaction: InteractionState | None = None - artifacts: dict[str, ArtifactInfo] = {} - notifications: list[NotificationEntry] = [] - completion: CompletionInfo | None = None +## Fold rules - config_runners: list[RunnerInfo] = [] - config_profiles: list[ProfileInfo] = [] - config_installations: list[InstallationInfo] = [] - config_active_profile: str = "balanced" - config_scout_concurrency: int = 8 -``` +### Agent conversation -### Agent model +These rules apply to the agent identified by `event.agent_id`. Since every agent has its own conversation, there is no primary-agent filtering — the fold appends to the relevant agent's conversation unconditionally. The frontend chooses which conversation to render via `focus`. -```python -class AgentProjection(KoanBaseModel): - agent_id: str - role: str - label: str = "" # NEW — scout identifier (e.g. "engine-methods") - model: str | None = None - step: int = 0 - step_name: str = "" - started_at_ms: int = 0 # existing field - input_tokens: int = 0 - output_tokens: int = 0 - status: Literal["running", "done", "failed"] = "running" # NEW - error: str | None = None # NEW - last_tool: str = "" # NEW — last tool summary for scout monitor -``` +| Event | Action on agent's conversation | +|-------|-------------------------------| +| `thinking` | Flush `pending_text` → TextEntry. Append delta to `pending_thinking`. Set `is_thinking = True`. | +| `stream_delta` | Flush `pending_thinking` → ThinkingEntry. Append delta to `pending_text`. Set `is_thinking = False`. | +| typed tool (`tool_read`, `tool_write`, etc.) | Flush both pending fields. Append typed entry (`in_flight=True`). Set `is_thinking = False`. | +| `tool_called` where tool starts with `koan_` | Skip — koan MCP tools are infrastructure noise. | +| `tool_completed` | Set `in_flight=False` on matching `call_id`. | +| `agent_step_advanced` | Flush both pending fields. Append StepEntry if `step >= 1`. Update `step`, `step_name`. Accumulate `input_tokens`, `output_tokens` from usage. Set `is_thinking = False`. | +| `stream_cleared` | Flush both pending fields. Set `is_thinking = False`. | + +"Flush" means: if the pending field is non-empty, create a completed entry (ThinkingEntry or TextEntry) with its content, append to `entries`, reset the field to `""`. -`label`, `status`, `error`, `last_tool` are the four additions. The frontend's `transformAgent()` already reads these fields from the snapshot — they are expected but not yet emitted by the backend's `AgentProjection`. This plan closes that gap. +**Why koan MCP tools are filtered:** `koan_complete_step`, `koan_request_scouts`, etc. are infrastructure. Their effects are captured by `agent_step_advanced`, `questions_asked`, etc. Showing them as tool lines is noise. + +### Agent lifecycle + +| Event | Action | +|-------|--------| +| `scout_queued` | Add `Agent(agent_id=scout_id, status="queued", ...)` to `run.agents`. | +| `agent_spawned` | If agent exists (queued scout), update `status="running"`, `started_at_ms`. If new (primary), add to `run.agents` with `status="running"`, `is_primary=True`. | +| `agent_exited` | Set `status="done"` or `"failed"`, set `error` if present. Accumulate final usage into conversation tokens. | +| `agent_spawn_failed` | Append to `notifications`. | + +### Focus transitions + +| Event | Action | +|-------|--------| +| `agent_spawned` (primary) | `run.focus = ConversationFocus(agent_id=...)` | +| `questions_asked` | `run.focus = QuestionFocus(agent_id=..., token=..., questions=...)` | +| `questions_answered` | `run.focus = ConversationFocus(agent_id=primary_agent_id)` | +| `artifact_review_requested` | `run.focus = ReviewFocus(...)` | +| `artifact_reviewed` | `run.focus = ConversationFocus(agent_id=primary_agent_id)` | +| `workflow_decision_requested` | `run.focus = DecisionFocus(...)` | +| `workflow_decided` | `run.focus = ConversationFocus(agent_id=primary_agent_id)` | + +### Run lifecycle + +| Event | Action | +|-------|--------| +| `run_started` | `projection.run = Run(config=RunConfig(...))` | +| `phase_started` | `run.phase = phase` | +| `workflow_completed` | `run.completion = CompletionInfo(...)` | + +### Settings + +| Event | Action | +|-------|--------| +| `probe_completed` | Set `available` flag on each installation in `settings.installations`. | +| `installation_created` | Add to `settings.installations`. | +| `installation_modified` | Update in `settings.installations`. | +| `installation_removed` | Remove from `settings.installations`. | +| `profile_created` | Add to `settings.profiles`. | +| `profile_modified` | Update in `settings.profiles`. | +| `profile_removed` | Remove from `settings.profiles`. | +| `default_profile_changed` | Set `settings.default_profile`. | +| `default_scout_concurrency_changed` | Set `settings.default_scout_concurrency`. | + +### Artifacts + +| Event | Action | +|-------|--------| +| `artifact_created` | Add to `run.artifacts`. | +| `artifact_modified` | Update in `run.artifacts`. | +| `artifact_removed` | Remove from `run.artifacts`. | --- -## Event Types (36 total) +## Event Types (37 total) -### Lifecycle (7) +### Lifecycle (8) | Event | Payload | |-------|---------| +| `run_started` | `{profile, installations, scout_concurrency}` | | `phase_started` | `{phase}` | | `agent_spawned` | `{agent_id, role, label, model, is_primary, started_at_ms}` | | `agent_spawn_failed` | `{role, error_code, message, details?}` | @@ -345,7 +580,7 @@ class AgentProjection(KoanBaseModel): | `stream_delta` | `{delta}` | | `stream_cleared` | `{}` | -### Interactions (6) +### Focus (6) | Event | Payload | |-------|---------| @@ -364,181 +599,126 @@ class AgentProjection(KoanBaseModel): | `artifact_modified` | `{path, size, modified_at}` | | `artifact_removed` | `{path}` | -### Configuration (9) +### Settings (9) | Event | Payload | |-------|---------| -| `probe_completed` | `{runners}` | +| `probe_completed` | `{results: {alias: available, ...}}` | | `installation_created` | `{alias, runner_type, binary, extra_args}` | | `installation_modified` | `{alias, runner_type, binary, extra_args}` | | `installation_removed` | `{alias}` | | `profile_created` | `{name, read_only, tiers}` | | `profile_modified` | `{name, read_only, tiers}` | | `profile_removed` | `{name}` | -| `active_profile_changed` | `{name}` | -| `scout_concurrency_changed` | `{value}` | +| `default_profile_changed` | `{name}` | +| `default_scout_concurrency_changed` | `{value}` | --- ## Scale considerations **Projected state over a full epic:** -- 20 markdown documents × 10 tickets = 200 artifacts (~2MB of content references) -- 5 agent sessions per ticket × 10 tickets = 50 primary agent runs -- 5 batches of 10 scouts = 250 scout sessions -- Each scout: ~50 tool calls, ~20 thinking blocks -- Primary agents: ~200 tool calls, ~100 thinking blocks per session -- Total events: ~200K–500K over the epic - -**Why JSON Patch works at this scale:** -- Tool call patches: ~100 bytes each (add entry to conversation array) -- Step advance patches: ~200 bytes (flush + add) -- `tool_completed`: ~80 bytes (replace one `in_flight` field) -- Thinking deltas: `replace` on `/pendingThinking` — O(accumulated_size) per delta, ~200KB/s peak. Acceptable on localhost (see "Protocol" section). -- Snapshot size at peak: ~50MB (dominated by artifact content references) -- Snapshot sent only on connect/reconnect — not per-event - -**Why patch replay was rejected for catch-up:** 500K events × variable patch size = unbounded memory. A fresh snapshot (50MB once) is cheaper and simpler than replaying patches. +- 200 artifacts, 50 primary agent runs, 250 scout sessions +- 200K–500K total events + +**Patch sizes:** +- Tool call: ~100 bytes (add entry to conversation array) +- Step advance: ~200 bytes (flush + add) +- `tool_completed`: ~80 bytes (replace `inFlight`) +- Thinking delta: `replace` on agent's `pendingThinking` — O(accumulated_size), ~200KB/s peak. Acceptable on localhost. +- Snapshot at peak: ~50MB. Sent only on connect/reconnect. + +**Why patch replay was rejected:** 500K events × variable patch size = unbounded memory. A fresh snapshot is cheaper and simpler. --- ## Implementation Plan -### Phase 1: Backend — materialized projection with JSON Patch +### Phase 1: Backend — projection model + JSON Patch 1. `pip install jsonpatch` — add to dependencies -2. Define `KoanBaseModel` with `alias_generator=to_camel, populate_by_name=True` and `to_wire()` method -3. Define `ConversationEntry` union and all entry types inheriting `KoanBaseModel` -4. Migrate `Projection`, `AgentProjection`, and all sub-models to inherit `KoanBaseModel` -5. Add `conversation`, `pending_thinking`, `pending_text`, `is_thinking` to `Projection`; remove `activity_log` -6. Add `label`, `status`, `error`, `last_tool` to `AgentProjection` -7. Rewrite fold cases for all 36 event types -8. Update `ProjectionStore.push_event()`: - - Use `projection.to_wire()` (not `model_dump()`) for camelCase dicts - - Compute JSON Patch between old and new `to_wire()` output - - Broadcast patch message (all events take the same path, no branching) - - Store `prev_state` for next diff computation -9. Update `sse_stream()`: - - `since=0`: send snapshot via `to_wire()`, then live - - `since=N` where N == server version: skip snapshot, go straight to live - - `since=N` where N != server version: send fresh snapshot (not event replay) - - Remove `events_since()` — no longer used for catch-up - - Remove `fatal_error` path — replaced by always-snapshot (client auto-recovers from version regression) -10. Update `get_snapshot()` to use `to_wire()` — output is camelCase, frontend reads it directly +2. Define `KoanBaseModel` with `alias_generator=to_camel`, `populate_by_name=True`, and `to_wire()` method +3. Define all model classes: `Settings`, `Installation`, `Profile`, `RunConfig`, `Run`, `Agent`, `Conversation`, `Focus` variants, `ConversationEntry` union — all inheriting `KoanBaseModel` +4. Replace current `Projection` (15 top-level fields) with new `Projection` (3 fields: `settings`, `run`, `notifications`) +5. Add `run_started` event — creates `Run` with `RunConfig` +6. Rewrite fold: settings events → `projection.settings.*`, run events → `projection.run.*`, agent events → `projection.run.agents[id].*`, conversation events → `...agents[id].conversation.*`, focus events → `projection.run.focus` +7. Update `ProjectionStore.push_event()`: `to_wire()` for camelCase dicts, `make_patch` for diffs, uniform broadcast +8. Update `sse_stream()`: always-snapshot on reconnect, remove `events_since()`, remove `fatal_error` +9. Update `get_snapshot()` to use `to_wire()` ### Phase 2: Frontend — dumb renderer 1. `npm install fast-json-patch` -2. Define TypeScript `ConversationEntry` union matching the wire format (camelCase) -3. Replace `connect.ts`: - - 2 event listeners: `snapshot`, `patch` - - Module-level `storeState` variable for patch application - - Remove KNOWN_EVENTS list and per-event-type listeners - - Remove `fatal_error` listener (no longer emitted) -4. Delete `applySnapshot` and `applyEvent` entirely — snapshot spreads directly into store -5. Delete `mapProjectionToStore()` — no field renaming needed (server emits camelCase) -6. Update Zustand store field names to match wire format where they diverge -7. Update `ActivityFeed` and components to read `ConversationEntry` camelCase field names (`callId`, `inFlight`, `stepName`, `toolName`) +2. Define TypeScript types matching wire format (camelCase): `Projection`, `Settings`, `Run`, `Agent`, `Conversation`, `Focus`, `ConversationEntry` +3. Replace `connect.ts`: 2 event listeners (`snapshot`, `patch`), module-level `storeState` +4. Delete `applySnapshot`, `applyEvent`, `mapProjectionToStore`, `transformAgent`, `transformArtifact`, KNOWN_EVENTS +5. Update components: `ActivityFeed` reads `run.agents[focusId].conversation`, `AgentMonitor` filters `run.agents` by status, `SettingsOverlay` reads `settings.*`, `LandingPage` reads `settings.*` for defaults ### Phase 3: Tests -1. Backend fold tests: assert `conversation` entries, `pending_thinking`, `is_thinking`, `in_flight` state -2. JSON Patch tests: fold event → verify patch operations are correct -3. Thinking/stream patch tests: `thinking`/`stream_delta` produce `replace` patches on `pendingThinking`/`pendingText` -4. Snapshot round-trip: fold events → snapshot → verify frontend can read it directly -5. Reconnect test: client with stale version gets fresh snapshot -6. **Delete `events_since()` tests:** `test_projections.py` has tests that call `store.events_since()` directly (currently lines ~360–373). These must be deleted, not updated — the method no longer exists. Replace with tests that verify the snapshot contains the correct materialized state after N events. +1. Fold tests: assert `conversation.entries`, `pending_thinking`, `is_thinking`, `in_flight` state per agent +2. Patch tests: fold event → verify JSON Patch operations target correct camelCase paths +3. Focus transition tests: interaction events produce correct focus variants +4. Settings/run separation tests: settings events don't touch `run`, run events don't touch `settings` +5. Snapshot round-trip: fold events → `to_wire()` → verify frontend-readable structure +6. Delete `events_since()` tests — replace with snapshot-based assertions ### Phase 4: Cleanup & docs -1. Remove dead frontend code: `applyEvent`, `applySnapshot`, `mapProjectionToStore`, `transformAgent`, `transformArtifact`, `ActivityEntry` type, buffer flush helpers, KNOWN_EVENTS +1. Remove dead frontend code 2. Remove `events_since()` from `ProjectionStore` -3. Update `docs/projections.md`: - - Replace `activity_log` with `conversation` model - - Document JSON Patch protocol (two event types: snapshot, patch) - - Update fold rules table -4. Update `docs/architecture.md`: - - Add invariant: "The fold runs only in Python. The frontend applies server-computed patches. It has no business logic." -5. Code comments on `ProjectionStore.push_event()` explaining the patch computation flow +3. Update `docs/projections.md`: new model, two-message protocol, fold rules, localhost assumption for uniform patches +4. Update `docs/architecture.md`: "The fold runs only in Python. The frontend applies server-computed patches. It has no business logic." +5. Docstrings on `ProjectionStore` and `KoanBaseModel` --- ## Risks -**JSON Patch array diffing:** `make_patch` uses positional indices for arrays. Conversation is append-only (entries are never reordered or removed), so patches are clean `add` operations at the end. The one mutation is `tool_completed` setting `in_flight=False` on an existing entry, which produces a targeted `replace` at `/conversation/N/in_flight`. +**JSON Patch array diffing:** `make_patch` uses positional indices. Conversation entries are append-only (never reordered or removed), so patches are clean `add` operations. The one mutation is `tool_completed` setting `in_flight=False`, which produces a targeted `replace` at `/run/agents/{id}/conversation/entries/{N}/inFlight`. -**Patch computation cost:** `make_patch` diffs two dicts. At 50MB state, this could be expensive. Mitigation: most events change a small part of state; the diff is proportional to what changed, not total state. Thinking deltas produce a `replace` on a single string field — the diff is O(1) to detect, though the patch payload is O(accumulated_size). This is acceptable on localhost (see protocol section). +**Nesting depth:** Paths like `/run/agents/abc123/conversation/entries/-` are 5 levels deep. Frontend access is `state.run?.agents?.[id]?.conversation?.entries`. Verbose, but selectors encapsulate the patterns. The nesting is meaningful — each level represents a real domain concept. -**Library trust:** `jsonpatch` (Python, 10+ years, well-maintained) and `fast-json-patch` (JavaScript, RFC 6902 compliant, widely used). Both are mature. +**Patch computation cost:** `make_patch` diffs two dicts. Proportional to what changed, not total state. Thinking deltas replace one string field — O(1) to detect, O(accumulated_size) payload. Acceptable on localhost. -**Snapshot size:** At 50MB, the initial snapshot takes ~1 second on localhost. This is acceptable for a local tool. If it becomes a problem, the snapshot can be gzip-compressed (SSE supports `Content-Encoding: gzip`). +**Library trust:** `jsonpatch` (Python) and `fast-json-patch` (JavaScript) — both mature, RFC 6902 compliant, widely used. ---- +**Snapshot size:** ~50MB at peak. ~1 second on localhost. Gzip-compressible if needed. -## Documentation Updates +--- -These changes require corresponding updates to existing docs. Do not defer — out-of-date docs create invisible knowledge debt. +## Documentation updates ### `docs/projections.md` -1. **Projection model:** Replace `activity_log: list[dict]` with `conversation: list[ConversationEntry]`, `pending_thinking: str`, `pending_text: str`, `is_thinking: bool`. Add the full `ConversationEntry` union definition with all 10 entry types. -2. **SSE protocol section:** Replace the current "snapshot + raw events" description with the two-message protocol (`snapshot`, `patch`). Include the connection lifecycle diagram from this plan. -3. **Fold rules table:** Rewrite the activity section — replace "append raw event to activity_log" with the actual fold rules (pending field accumulation, flush triggers, in-flight tracking, agent filtering, koan MCP filtering). -4. **"Why catch-up uses snapshots":** Document the memory cost of storing 500K patches. Document the localhost assumption that makes uniform JSON Patch viable for streaming (no delta bypass needed). These decisions must be visible, not inferred. -5. **Event types:** Add `scout_queued` and the 6 typed tool events (`tool_read` through `tool_ls`) which are currently missing. -6. **`AgentProjection`:** Add `status`, `error`, `last_tool`, `label` fields. -7. **Remove:** The "Why activity_log stores raw events" section — that rationale is obsolete. +1. Replace `activity_log` with per-agent `Conversation` model. Document `ConversationEntry` union. +2. Replace "snapshot + raw events" SSE description with two-message protocol (`snapshot`, `patch`). +3. Rewrite fold rules: per-agent conversation, focus transitions, settings vs run separation. +4. Document localhost assumption for uniform JSON Patch (no delta bypass). +5. Document settings vs run config distinction. +6. Add all event types including `run_started`, `scout_queued`, typed tool events. +7. Remove "Why activity_log stores raw events" section. ### `docs/architecture.md` -Add a principle to the projection invariant section: +Add invariant: > **The fold runs only in Python.** The frontend applies server-computed JSON Patches mechanically. It has no fold logic, no event interpretation, and no business rules. When the frontend's view of state differs from the backend's, the bug is in the fold or the patch computation — not in the frontend. -This replaces any "symmetric fold invariant" language, which implied two folds that needed to stay in sync. - ### `koan/projections.py` -Add module-level docstring: -``` -ProjectionStore maintains: - - events: append-only audit log of all VersionedEvents - - projection: materialized view produced by fold() — the source of truth - - prev_state: to_wire() of the previous projection, used for JSON Patch computation - -push_event() folds the event, computes a JSON Patch between prev_state and -the new to_wire() output, and broadcasts the patch. Every event takes the -same path: fold → diff → broadcast. No branching on event type. -All wire output is camelCase via KoanBaseModel.to_wire() (alias_generator). -The fold is the only place where business logic runs. The frontend applies -patches mechanically with no field renaming. -``` +Module-level docstring documenting `ProjectionStore`: events (audit log), projection (materialized state), prev_state (for patch computation). Push flow: fold → to_wire → make_patch → broadcast. Uniform path, no branching. CamelCase via `KoanBaseModel`. ### `frontend/src/sse/connect.ts` -After the change, the file should have a comment explaining: -``` -State sync protocol: - snapshot → replace storeState + spread into Zustand - patch → apply RFC 6902 patch to storeState + spread into Zustand - -Server emits camelCase JSON (via Pydantic alias_generator). No field -renaming needed — wire keys match store keys. storeState is a plain JS -object for fast-json-patch; Zustand state is updated by spreading it. -All events — including thinking/text deltas — go through JSON Patch. -The frontend has no fold logic — all business rules live in the Python fold. -``` - -### `AGENTS.md` — no changes required - -The six core invariants are unchanged. The new architecture is a refinement of how Invariant 5 (projections) is implemented, not a change to the invariant itself. +Comment documenting: snapshot → replace, patch → apply. Server emits camelCase. No field renaming. All events go through JSON Patch. Frontend has no fold logic. --- ## Migration -**Breaking change.** The SSE protocol changes from per-event-type messages to `snapshot`/`patch`. Old clients cannot connect to new servers (they'd receive unknown event types). Old servers cannot serve new clients (missing `patch` event). +**Breaking change.** The SSE protocol changes from per-event-type messages to `snapshot`/`patch`. The projection structure changes completely (3 top-level fields, nested model). Old clients cannot connect to new servers. -**No on-disk migration.** All state is in-memory. Server restart already forces a full reload. +**No on-disk migration.** All state is in-memory. Server restart forces a full reload. `~/.koan/config.json` schema is unchanged — the projection model restructuring is in-memory only. -**Deployment:** Single-user local tool. The user runs `pip install --upgrade koan` and restarts. No coordinated rollout needed. +**Deployment:** Single-user local tool. `pip install --upgrade koan` and restart. From 9f36ce1307aecfd3f351cd0bfb4eaff5db4dea39 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 16:38:00 +0700 Subject: [PATCH 250/412] =?UTF-8?q?plan:=20technical=20writer=20pass=20?= =?UTF-8?q?=E2=80=94=20code=20comments,=20clarity,=20consistency?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Code snippet improvements: - KoanBaseModel: explain populate_by_name=True and to_wire() call sites - push_event: comment audit log invariant, subscriber snapshot reason, and no-op early return semantics - Frontend: explain storeState purpose, applyPatch immutable variant (.newDocument) Design rationale now explicit in prose: - Why dict[str, Agent] not list[Agent]: stable JSON Patch paths - Why Conversation is a sub-object: separates identity/lifecycle from content/cost; natural unit to pass to ActivityFeed - Why focus starts as None: no agents yet; first agent_spawned sets it - Why notifications at top level: fed by both settings and run events Fold rules improvements: - 'Flush' definition moved before the table that uses it - Added ToolGenericEntry row for non-koan tool_called without typed variant - Removed duplicate 'Why koan MCP tools filtered' paragraph (now in table) Prose tightening: - Catch-up paragraph collapsed (no duplication) - Focus transition paragraph clarifies None → ConversationFocus transition Existing types annotated: - AskQuestion, ChatTurn, ArtifactInfo, CompletionInfo noted as existing koan types --- .../2026-03-31-symmetric-projection-folds.md | 74 ++++++++++++------- 1 file changed, 48 insertions(+), 26 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index 02e8c7a..9765271 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -55,9 +55,7 @@ Server restart: GET /events?since=N+2 (client detects version < lastVersion, resets UI) ``` -**Catch-up always uses snapshots.** Storing patches for replay is expensive (200K–500K events over a full epic). On reconnect, the server sends a fresh snapshot at the current version. The `since` parameter is a version check: if it matches the server's version, skip the snapshot and go straight to live events. Otherwise, send a snapshot. - -This eliminates `events_since()` and the catch-up replay code path entirely. It also eliminates `fatal_error`: the current code sends `fatal_error` when `since > store.version` (after server restart), requiring manual reload. The new design always sends a snapshot — the client detects the version regression and resets automatically. One code path for all reconnects. +**Catch-up always uses snapshots.** The `since` parameter is a version check: if it matches the server's current version, skip the snapshot and stream live events. Otherwise, send a fresh snapshot. This eliminates the `events_since()` replay path (500K events × variable patch sizes = unbounded memory) and the `fatal_error` case (server restart caused `since > store.version`, requiring manual reload). One code path handles all reconnects; the client detects version regression and resets automatically. ### What the server stores @@ -75,18 +73,21 @@ No stored patches. No catch-up replay buffer. def push_event(self, event_type, payload, agent_id=None): self.version += 1 event = VersionedEvent(version=self.version, ...) - self.events.append(event) # audit log + self.events.append(event) # append-only audit log — never modified - old_state = self.prev_state + old_state = self.prev_state # camelCase dict from previous to_wire() self.projection = fold(self.projection, event) - new_state = self.projection.to_wire() # camelCase via alias_generator + new_state = self.projection.to_wire() # camelCase — patch paths will be camelCase self.prev_state = new_state patch = jsonpatch.make_patch(old_state, new_state) if not patch: - return # no-op (e.g. koan MCP tool filtered by fold) + return # fold produced no state change (e.g. koan MCP tool filtered by fold) + # no message broadcast — subscribers stay at the same version msg = {"type": "patch", "version": self.version, "patch": patch.to_string()} + # Snapshot self.subscribers before iterating — a subscriber may be added + # or removed concurrently (asyncio, not threading, but still defensive) for q in list(self.subscribers): q.put_nowait(msg) ``` @@ -104,10 +105,23 @@ from pydantic import ConfigDict from pydantic.alias_generators import to_camel class KoanBaseModel(BaseModel): - model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True) + model_config = ConfigDict( + alias_generator=to_camel, # snake_case → camelCase at serialization + populate_by_name=True, # Python code still uses snake_case attributes; + # only the JSON output uses camelCase aliases + ) def to_wire(self) -> dict: - """Serialize for snapshots and patch computation. Always camelCase.""" + """Serialize for snapshots and JSON Patch computation. + + Always produces camelCase keys via the alias_generator. + Call this at the two serialization boundaries: + - ProjectionStore.push_event(): to_wire() twice (before and after fold) + to compute the JSON Patch diff + - get_snapshot(): to_wire() once to build the snapshot payload + Never call model_dump() directly on projection objects — that produces + snake_case keys and breaks patch paths on the frontend. + """ return self.model_dump(by_alias=True) ``` @@ -118,17 +132,22 @@ All projection models inherit from `KoanBaseModel`. Snapshot JSON and patch path ### Frontend — complete implementation ```typescript +// Module-level projection dict. fast-json-patch operates on plain JS objects, +// not on Zustand state. Patches mutate this, then we spread it into the store. let storeState: Record<string, unknown> = {} es.addEventListener('snapshot', (e) => { const { version, state } = JSON.parse(e.data) - storeState = state - set({ lastVersion: version, ...state }) + storeState = state // replace wholesale on every snapshot + set({ lastVersion: version, ...state }) // spread all camelCase fields into store }) es.addEventListener('patch', (e) => { const { version, patch } = JSON.parse(e.data) - storeState = applyPatch(storeState, patch).newDocument + // applyPatch with mutate:false returns { newDocument } — a new object + // rather than modifying storeState in-place. This matters because Zustand + // may still hold a reference to the previous storeState for the current render. + storeState = applyPatch(storeState, patch, /*validate*/false, /*mutate*/false).newDocument set({ lastVersion: version, ...storeState }) }) ``` @@ -247,7 +266,9 @@ The distinction between settings and run config: ### Agent -All agents — primary, scouts, queued — live in one dict. The lifecycle is a state machine on `status`. No separate collections, no `QueuedScout` type. +All agents — primary, scouts, queued — live in one dict keyed by `agent_id`. The lifecycle is a state machine on `status`. No separate collections, no `QueuedScout` type. + +**Why `dict[str, Agent]` not `list[Agent]`?** JSON Patch paths for list elements use positional indices (`/run/agents/2`). If an agent is removed or the list is reordered, subsequent indices shift and pending patches become invalid. Dict keys are stable: `/run/agents/abc123` refers to the same agent regardless of insertions or removals. ```python class Agent(KoanBaseModel): @@ -295,6 +316,8 @@ class Conversation(KoanBaseModel): output_tokens: int = 0 ``` +**Why `Conversation` is a sub-object, not fields directly on `Agent`?** `Agent` describes who the agent is and where it is in the workflow (identity + lifecycle + progress). `Conversation` describes what the agent has said and what it cost. These change at different rates and serve different UI concerns — `step`/`status` update for every agent in the monitor, while `entries`/`pending_thinking` update only for the visible conversation. Separating them also makes `agent.conversation` a natural unit to pass to `ActivityFeed` as a single prop. + **Why `pending_thinking` / `pending_text`, not `thinkingBuffer` / `streamBuffer`?** "Buffer" describes the mechanism (accumulate, flush, reset). "Pending" describes the content: incomplete LLM output that will become a conversation entry on the next transition. The names should describe *what it is*, not *how it works*. **Why tokens are in Conversation, not Agent:** They're accumulated from conversation turns (each `agent_step_advanced` carries usage). They describe the cost of what the agent said, not the agent's identity or lifecycle. @@ -316,7 +339,7 @@ class QuestionFocus(KoanBaseModel): type: Literal["question"] = "question" agent_id: str # who asked (conversation is backdrop) token: str # correlation ID for response - questions: list[AskQuestion] + questions: list[AskQuestion] # existing koan type (koan/web/interactions.py) class ReviewFocus(KoanBaseModel): """Agent is blocked, artifact needs review.""" @@ -332,7 +355,7 @@ class DecisionFocus(KoanBaseModel): type: Literal["decision"] = "decision" agent_id: str token: str - chat_turns: list[ChatTurn] + chat_turns: list[ChatTurn] # existing koan type Focus = Annotated[ ConversationFocus | QuestionFocus | ReviewFocus | DecisionFocus, @@ -340,7 +363,7 @@ Focus = Annotated[ ] ``` -The fold manages transitions: +The fold manages transitions. `run.focus` starts as `None` (no agents yet). The first `agent_spawned` event for the primary agent sets it to `ConversationFocus` — from that point, the main content area always has an explicit state. | Event | Focus transition | |-------|-----------------| @@ -432,8 +455,8 @@ class Run(KoanBaseModel): phase: str = "" # current workflow phase agents: dict[str, Agent] = {} # all agents by ID, all lifecycle states focus: Focus | None = None # None before first agent spawns - artifacts: dict[str, ArtifactInfo] = {} - completion: CompletionInfo | None = None + artifacts: dict[str, ArtifactInfo] = {} # existing type; keyed by path + completion: CompletionInfo | None = None # existing type; set by workflow_completed event ``` ### Complete Projection @@ -482,20 +505,19 @@ Named entities (installations, profiles, agents, artifacts) are dicts for stable These rules apply to the agent identified by `event.agent_id`. Since every agent has its own conversation, there is no primary-agent filtering — the fold appends to the relevant agent's conversation unconditionally. The frontend chooses which conversation to render via `focus`. +"Flush" means: if the pending field is non-empty, create a completed entry (ThinkingEntry or TextEntry) with its content, append to `entries`, reset the field to `""`. + | Event | Action on agent's conversation | |-------|-------------------------------| | `thinking` | Flush `pending_text` → TextEntry. Append delta to `pending_thinking`. Set `is_thinking = True`. | | `stream_delta` | Flush `pending_thinking` → ThinkingEntry. Append delta to `pending_text`. Set `is_thinking = False`. | -| typed tool (`tool_read`, `tool_write`, etc.) | Flush both pending fields. Append typed entry (`in_flight=True`). Set `is_thinking = False`. | -| `tool_called` where tool starts with `koan_` | Skip — koan MCP tools are infrastructure noise. | -| `tool_completed` | Set `in_flight=False` on matching `call_id`. | -| `agent_step_advanced` | Flush both pending fields. Append StepEntry if `step >= 1`. Update `step`, `step_name`. Accumulate `input_tokens`, `output_tokens` from usage. Set `is_thinking = False`. | +| typed tool (`tool_read`, `tool_write`, etc.) | Flush both pending fields. Append typed entry with `in_flight=True`. Set `is_thinking = False`. | +| `tool_called` (non-koan, no typed variant) | Flush both pending fields. Append `ToolGenericEntry` with `in_flight=True`. Set `is_thinking = False`. | +| `tool_called` where tool name starts with `koan_` | Skip — koan MCP tools are infrastructure. Effects already captured by `agent_step_advanced`, `questions_asked`, etc. | +| `tool_completed` | Set `in_flight=False` on the entry whose `call_id` matches. | +| `agent_step_advanced` | Flush both pending fields. Append StepEntry if `step >= 1`. Update `step`, `step_name` on Agent. Accumulate `input_tokens`, `output_tokens` into Conversation. Set `is_thinking = False`. | | `stream_cleared` | Flush both pending fields. Set `is_thinking = False`. | -"Flush" means: if the pending field is non-empty, create a completed entry (ThinkingEntry or TextEntry) with its content, append to `entries`, reset the field to `""`. - -**Why koan MCP tools are filtered:** `koan_complete_step`, `koan_request_scouts`, etc. are infrastructure. Their effects are captured by `agent_step_advanced`, `questions_asked`, etc. Showing them as tool lines is noise. - ### Agent lifecycle | Event | Action | From 11e57a8be44f56428eb137f8d7ebb029303ab584 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 16:45:08 +0700 Subject: [PATCH 251/412] =?UTF-8?q?plan:=20comprehensive=20quality=20pass?= =?UTF-8?q?=20=E2=80=94=20code=20sketches,=20type=20definitions,=20narrati?= =?UTF-8?q?ves?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added: - sse_stream() code sketch with version-check logic and subscriber consumption - Focus rendering code (switch on focus.type with full TSX example) - Error recovery code (try/catch → reconnect for fresh snapshot) - End-to-end run start flow (landing page → POST → events → UI transitions) - ArtifactInfo, CompletionInfo, Notification type definitions - tool_called vs typed tool events explanation (one or the other, never both) - agent_spawned disambiguation (lookup in run.agents → transition or create) - Fold rules intro paragraph (pure function, grouped by concern, cross-cutting) - Scale section rewritten with narrative and table of patch sizes by event type 746 → 899 lines. 37 events verified. --- .../2026-03-31-symmetric-projection-folds.md | 233 +++++++++++++++--- 1 file changed, 193 insertions(+), 40 deletions(-) diff --git a/plans/2026-03-31-symmetric-projection-folds.md b/plans/2026-03-31-symmetric-projection-folds.md index 9765271..806c623 100644 --- a/plans/2026-03-31-symmetric-projection-folds.md +++ b/plans/2026-03-31-symmetric-projection-folds.md @@ -92,7 +92,38 @@ def push_event(self, event_type, payload, agent_id=None): q.put_nowait(msg) ``` -Every event takes the same path: fold, diff, broadcast. No branching on event type. Subscriber queues carry **plain dicts** — the dict shape matches the SSE JSON payload directly, and the `sse_stream()` consumer just serializes and sends. +Every event takes the same path: fold, diff, broadcast. No branching on event type. Subscriber queues carry **plain dicts** — the dict shape matches the SSE JSON payload directly. + +### Server-side sse_stream flow + +```python +async def sse_stream(request: Request, since: int = 0): + queue = asyncio.Queue() + store = request.app.state.projection_store + + # Version check: decide whether to send a snapshot first. + # The only branching is "same version or not" — no event replay, no fatal_error. + if since != store.version: + # Client is behind (reconnect) or ahead (server restarted). + # Either way, a fresh snapshot is the correct recovery. + yield sse_event("snapshot", { + "version": store.version, + "state": store.projection.to_wire(), + }) + + # Subscribe to live patches. From here, every message is a dict + # with {"type": "patch", "version": N, "patch": "..."} — we just + # forward it as an SSE event with the dict's "type" as the event name. + store.subscribers.add(queue) + try: + while True: + msg = await queue.get() # plain dict from push_event + yield sse_event(msg["type"], msg) # "patch" event with JSON payload + finally: + store.subscribers.discard(queue) +``` + +The consumer is trivial — it reads dicts from the queue and serializes them. No interpretation, no filtering, no transformation. ### Wire format: camelCase via Pydantic aliases @@ -156,7 +187,22 @@ That is the **entire** frontend sync implementation. Two handlers. No `applyEven **`storeState`** is a module-level variable in `connect.ts` — the raw projection dict for patch application. It must be a plain JS object because `fast-json-patch`'s `applyPatch` operates on plain objects. On snapshot, it is replaced wholesale. On patch, `applyPatch` returns a `newDocument` (immutable variant — avoids mutating state Zustand may still reference). -**Error handling:** If `applyPatch` throws, the client's local state may be inconsistent. Recovery: log the error, close EventSource, reset `lastVersion` to 0, reconnect for a fresh snapshot. +**Error handling:** If `applyPatch` throws, the client's local state may be inconsistent. The recovery path is the same as any connection failure — reconnect for a fresh snapshot: + +```typescript +es.addEventListener('patch', (e) => { + try { + const { version, patch } = JSON.parse(e.data) + storeState = applyPatch(storeState, patch, false, false).newDocument + set({ lastVersion: version, ...storeState }) + } catch (err) { + console.error('Patch failed, reconnecting for fresh snapshot:', err) + es.close() // tear down broken connection + set({ lastVersion: 0 }) // force snapshot on reconnect + setTimeout(() => connect(set), 1000) // reconnect after brief backoff + } +}) +``` **Ordering guarantee:** SSE is connection-ordered. Patches cannot arrive out of order. If the connection drops, the client reconnects and gets a fresh snapshot. The `version` field is diagnostic only. @@ -192,6 +238,23 @@ Special-case `thinking`/`stream_delta` events: send raw string deltas instead of ## Projection Model +The projection is the single materialized view of all state. It has a layered structure: + +- **Projection** — top level: `settings`, `run`, `notifications` + - **Settings** — persistent config: installations, profiles, defaults + - **Installation** — a configured LLM CLI binary + - **Profile** — maps roles to installations + - **Run** — ephemeral workflow state (or `None`) + - **RunConfig** — frozen configuration for this run + - **Agent** — identity + lifecycle + progress + conversation + - **Conversation** — timeline entries + pending fields + token stats + - **ConversationEntry** — discriminated union of 10 entry types + - **Focus** — discriminated union: what the main content area renders + - **ArtifactInfo**, **CompletionInfo** — existing types, unchanged + - **Notification** — transient UI toasts + +Each class is defined below in dependency order. + ### Top-level structure The projection has three concerns with different lifetimes: @@ -203,7 +266,9 @@ class Projection(KoanBaseModel): notifications: list[Notification] = [] # transient UI toasts ``` -`run is None` → show landing page. `run.completion is not None` → run finished. No boolean flags. +`run is None` → show landing page. `run.completion is not None` → run finished (show results + summary). The `run` object is **not** set to `None` on completion — it persists so the user can review the final conversation, artifacts, and token usage. It resets to `None` only when the user starts a new run (the `run_started` event creates a fresh `Run`). + +`notifications` are transient UI toasts (e.g. "agent spawn failed", "probe completed"). They span both settings and run events, which is why they live at the top level rather than inside `run`. They are currently append-only; a future `notification_dismissed` event could remove them. No boolean flags anywhere. ### Settings @@ -293,13 +358,21 @@ class Agent(KoanBaseModel): conversation: Conversation = Conversation() ``` -The frontend derives views by filtering: +The frontend derives views by filtering on `status` and `is_primary`. These are Zustand selectors — React components subscribe to them and re-render when the result changes: ```typescript -const primary = Object.values(agents).find(a => a.isPrimary && a.status === 'running') +// Agent monitor: grouped sections +const agents = useStore(s => s.run?.agents ?? {}) +const primary = Object.values(agents).find(a => a.isPrimary) // at most one const running = Object.values(agents).filter(a => !a.isPrimary && a.status === 'running') const queued = Object.values(agents).filter(a => a.status === 'queued') const done = Object.values(agents).filter(a => a.status === 'done' || a.status === 'failed') + +// Activity feed: conversation of the focused agent +const focusId = useStore(s => s.run?.focus?.agentId) +const conversation = useStore(s => + focusId ? s.run?.agents?.[focusId]?.conversation : undefined +) ``` ### Conversation @@ -375,9 +448,32 @@ The fold manages transitions. `run.focus` starts as `None` (no agents yet). The | `workflow_decision_requested` | `DecisionFocus(...)` | | `workflow_decided` | `ConversationFocus(agent_id=primary_id)` | -The frontend rendering is a switch on `focus.type` — no conditional logic about "is there an active interaction." +The frontend rendering is a switch on `focus.type`: + +```tsx +function MainContent({ focus, agents }: Props) { + if (!focus) return null // no agents yet — nothing to show + + // Every focus variant has agentId — the conversation is always the backdrop + const conversation = agents[focus.agentId]?.conversation + + switch (focus.type) { + case 'conversation': // default: just the conversation + return <ActivityFeed conversation={conversation} /> + case 'question': // agent blocked, needs user answer + return <> + <ActivityFeed conversation={conversation} dimmed /> + <QuestionWizard questions={focus.questions} token={focus.token} /> + </> + case 'review': // agent blocked, artifact needs review + return <ArtifactReview path={focus.path} content={focus.content} token={focus.token} /> + case 'decision': // workflow decision needed + return <DecisionChat turns={focus.chatTurns} token={focus.token} /> + } +} +``` -`agent_id` on every variant means the frontend always knows whose conversation is the backdrop. A question overlays the asking agent's scrolled-up conversation. +No conditional logic about "is there an active interaction." No implicit fallback to the primary agent. Every state of the main content area is explicitly modeled and rendered. ### ConversationEntry — discriminated union @@ -405,33 +501,34 @@ class BaseToolEntry(KoanBaseModel): class ToolReadEntry(BaseToolEntry): type: Literal["tool_read"] = "tool_read" - file: str - lines: str = "" + file: str # path that was read + lines: str = "" # line range, e.g. "1-50" class ToolWriteEntry(BaseToolEntry): type: Literal["tool_write"] = "tool_write" - file: str + file: str # path that was created or overwritten class ToolEditEntry(BaseToolEntry): type: Literal["tool_edit"] = "tool_edit" - file: str + file: str # path that was edited in-place class ToolBashEntry(BaseToolEntry): type: Literal["tool_bash"] = "tool_bash" - command: str + command: str # shell command executed class ToolGrepEntry(BaseToolEntry): type: Literal["tool_grep"] = "tool_grep" - pattern: str + pattern: str # search pattern class ToolLsEntry(BaseToolEntry): type: Literal["tool_ls"] = "tool_ls" - path: str + path: str # directory listed class ToolGenericEntry(BaseToolEntry): + """Catch-all for tools without a typed variant (e.g. custom MCP tools).""" type: Literal["tool_generic"] = "tool_generic" - tool_name: str - summary: str = "" + tool_name: str # original tool name from the LLM + summary: str = "" # human-readable one-liner from the runner parser ConversationEntry = Annotated[ ThinkingEntry | TextEntry | StepEntry | @@ -445,27 +542,75 @@ ConversationEntry = Annotated[ **Extensibility:** Adding `ToolWebFetchEntry` means: define the model, add to the union, add a fold case. The frontend is unchanged — JSON Patch carries the new structure automatically. +### Supporting types + +These existing types are referenced by `Run` and `Projection`. Key fields listed for completeness — full definitions remain in their current modules. + +```python +class ArtifactInfo(KoanBaseModel): + """A markdown document managed by the workflow.""" + path: str # relative to epic directory + size: int # bytes + modified_at: str # ISO 8601 timestamp + +class CompletionInfo(KoanBaseModel): + """Set when the workflow finishes.""" + success: bool + summary: str = "" # human-readable result summary + error: str | None = None # set on failure + +class Notification(KoanBaseModel): + """Transient UI toast. Shown briefly, then fades.""" + message: str + level: Literal["info", "warning", "error"] = "info" + timestamp_ms: int +``` + ### Run -Ephemeral workflow state. Exists only during a run. +Ephemeral workflow state. Created by `run_started`, persists through completion for result viewing. ```python class Run(KoanBaseModel): - config: RunConfig # frozen at run start - phase: str = "" # current workflow phase - agents: dict[str, Agent] = {} # all agents by ID, all lifecycle states - focus: Focus | None = None # None before first agent spawns - artifacts: dict[str, ArtifactInfo] = {} # existing type; keyed by path - completion: CompletionInfo | None = None # existing type; set by workflow_completed event + config: RunConfig # frozen at run start — never modified + phase: str = "" # current workflow phase (e.g. "intake", "execution") + agents: dict[str, Agent] = {} # all agents by ID — primary, scouts, queued, completed + focus: Focus | None = None # what the main content area renders; None before first agent + artifacts: dict[str, ArtifactInfo] = {} # keyed by relative path (e.g. "docs/architecture.md") + completion: CompletionInfo | None = None # None during run; set by workflow_completed +``` + +### End-to-end: starting a run + +``` +1. User opens koan web UI + ← Frontend connects to /events?since=0 + ← snapshot {settings: {installations: {...}, profiles: {...}, ...}, run: null} + → Landing page renders: profile selector (from settings.defaultProfile), + installation selector (from settings.installations where available == true) + +2. User selects profile + installations, clicks "Start Run" + → POST /api/start-run {profile: "balanced", installations: {"primary": "claude-default", ...}, scout_concurrency: 8} + +3. Backend validates binaries, emits run_started event + → fold creates Run(config=RunConfig(...)) + ← patch [{op: "add", path: "/run", value: {config: {...}, phase: "", agents: {}, ...}}] + → Frontend: run is no longer null → switch from landing page to run view + +4. Driver starts first phase, spawns primary agent + → phase_started {phase: "intake"} + → agent_spawned {agent_id: "intake-0", role: "intake", is_primary: true, ...} + → fold: adds agent, sets focus = ConversationFocus(agent_id="intake-0") + ← patches flow to frontend → activity feed appears ``` ### Complete Projection ```python class Projection(KoanBaseModel): - settings: Settings = Settings() - run: Run | None = None - notifications: list[Notification] = [] + settings: Settings = Settings() # persists across runs, loaded from config.json + probe + run: Run | None = None # None → landing page; set by run_started; persists after completion + notifications: list[Notification] = [] # append-only toasts from both settings and run events ``` Three top-level fields. Everything else is nested where it belongs. @@ -501,6 +646,8 @@ Named entities (installations, profiles, agents, artifacts) are dicts for stable ## Fold rules +The fold is a pure function: `fold(projection, event) → projection`. It is the **only** place where business logic runs. Rules are grouped by the part of the projection they modify. An event may trigger rules in multiple groups (e.g. `agent_step_advanced` updates the agent's conversation AND its progress fields). + ### Agent conversation These rules apply to the agent identified by `event.agent_id`. Since every agent has its own conversation, there is no primary-agent filtering — the fold appends to the relevant agent's conversation unconditionally. The frontend chooses which conversation to render via `focus`. @@ -511,11 +658,13 @@ These rules apply to the agent identified by `event.agent_id`. Since every agent |-------|-------------------------------| | `thinking` | Flush `pending_text` → TextEntry. Append delta to `pending_thinking`. Set `is_thinking = True`. | | `stream_delta` | Flush `pending_thinking` → ThinkingEntry. Append delta to `pending_text`. Set `is_thinking = False`. | -| typed tool (`tool_read`, `tool_write`, etc.) | Flush both pending fields. Append typed entry with `in_flight=True`. Set `is_thinking = False`. | -| `tool_called` (non-koan, no typed variant) | Flush both pending fields. Append `ToolGenericEntry` with `in_flight=True`. Set `is_thinking = False`. | +| typed tool (`tool_read`, `tool_write`, etc.) | Flush both pending fields. Append typed entry with `in_flight=True`. Set `is_thinking = False`. Update `agent.last_tool` with tool summary (e.g. `"read src/main.py:1-50"`). | +| `tool_called` (non-koan, no typed variant) | Flush both pending fields. Append `ToolGenericEntry` with `in_flight=True`. Set `is_thinking = False`. Update `agent.last_tool`. | | `tool_called` where tool name starts with `koan_` | Skip — koan MCP tools are infrastructure. Effects already captured by `agent_step_advanced`, `questions_asked`, etc. | + +**`tool_called` vs typed tool events:** The runner's stream parser decides which to emit. When it can extract structured metadata (file path, command, pattern), it emits a typed event (`tool_read`, `tool_bash`, etc.) *instead of* `tool_called`. When it cannot (custom MCP tools, unknown tool names), it emits `tool_called` as a fallback. The fold never receives both for the same invocation — it's one or the other. | `tool_completed` | Set `in_flight=False` on the entry whose `call_id` matches. | -| `agent_step_advanced` | Flush both pending fields. Append StepEntry if `step >= 1`. Update `step`, `step_name` on Agent. Accumulate `input_tokens`, `output_tokens` into Conversation. Set `is_thinking = False`. | +| `agent_step_advanced` | Flush both pending fields. Append StepEntry if `step >= 1`. Set `is_thinking = False`. **Cross-cutting:** updates `agent.step`, `agent.step_name` (progress) and accumulates `usage.input_tokens`, `usage.output_tokens` into `agent.conversation` (stats). | | `stream_cleared` | Flush both pending fields. Set `is_thinking = False`. | ### Agent lifecycle @@ -523,7 +672,7 @@ These rules apply to the agent identified by `event.agent_id`. Since every agent | Event | Action | |-------|--------| | `scout_queued` | Add `Agent(agent_id=scout_id, status="queued", ...)` to `run.agents`. | -| `agent_spawned` | If agent exists (queued scout), update `status="running"`, `started_at_ms`. If new (primary), add to `run.agents` with `status="running"`, `is_primary=True`. | +| `agent_spawned` | Look up `agent_id` in `run.agents`. If found (scout was previously queued via `scout_queued`), transition: set `status="running"`, `started_at_ms`. If not found (first time seeing this agent — always the primary), create a new `Agent` with `status="running"`, `is_primary=True`, and add to `run.agents`. | | `agent_exited` | Set `status="done"` or `"failed"`, set `error` if present. Accumulate final usage into conversation tokens. | | `agent_spawn_failed` | Append to `notifications`. | @@ -639,18 +788,22 @@ These rules apply to the agent identified by `event.agent_id`. Since every agent ## Scale considerations -**Projected state over a full epic:** -- 200 artifacts, 50 primary agent runs, 250 scout sessions -- 200K–500K total events +A full koan epic spans 10 tickets, each with multiple agent sessions and scout batches. The numbers below project the upper bound of state that the projection must handle. + +**Event volume:** 20 markdown documents × 10 tickets = 200 artifacts. 5 primary agent sessions per ticket = 50 primary runs. 5 scout batches × 10 concurrent scouts = 250 scout sessions. Each scout produces ~50 tool calls and ~20 thinking blocks. Each primary agent produces ~200 tool calls and ~100 thinking blocks. Total: **200K–500K events over the epic.** + +**Patch sizes by event type:** -**Patch sizes:** -- Tool call: ~100 bytes (add entry to conversation array) -- Step advance: ~200 bytes (flush + add) -- `tool_completed`: ~80 bytes (replace `inFlight`) -- Thinking delta: `replace` on agent's `pendingThinking` — O(accumulated_size), ~200KB/s peak. Acceptable on localhost. -- Snapshot at peak: ~50MB. Sent only on connect/reconnect. +| Event type | Patch size | Notes | +|-----------|-----------|-------| +| Tool call | ~100 bytes | `add` to `/run/agents/{id}/conversation/entries/-` | +| Step advance | ~200 bytes | Flush pending → `add` entry + `replace` step/step_name | +| `tool_completed` | ~80 bytes | `replace` on `/...entries/{N}/inFlight` | +| Thinking delta | ~10KB peak | `replace` on `pendingThinking` — O(accumulated_size). At 20 deltas/sec with 10KB accumulated = ~200KB/s. Acceptable on localhost. | +| Focus transition | ~500 bytes | `replace` on `/run/focus` with full focus object | +| Snapshot | ~50MB peak | Dominated by artifact content references. Sent only on connect/reconnect. | -**Why patch replay was rejected:** 500K events × variable patch size = unbounded memory. A fresh snapshot is cheaper and simpler. +**Why patch replay was rejected for catch-up:** Storing 500K patches for replay requires unbounded memory (patches vary from 80 bytes to 10KB+). A fresh 50MB snapshot sent once on reconnect is both cheaper and simpler — no replay buffer, no ordering logic, no partial-replay edge cases. --- From b600ebeb690f7aebb1f7e82e67878776d7c25345 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 17:51:24 +0700 Subject: [PATCH 252/412] add jsonpatch and fast-json-patch dependencies --- frontend/package-lock.json | 7 +++++++ frontend/package.json | 1 + pyproject.toml | 1 + uv.lock | 23 +++++++++++++++++++++++ 4 files changed, 32 insertions(+) diff --git a/frontend/package-lock.json b/frontend/package-lock.json index c07a2e9..349e8cb 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -8,6 +8,7 @@ "name": "koan-frontend", "version": "0.1.0", "dependencies": { + "fast-json-patch": "^3.1.1", "react": "^19", "react-dom": "^19", "zustand": "^5" @@ -1403,6 +1404,12 @@ "node": ">=6" } }, + "node_modules/fast-json-patch": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/fast-json-patch/-/fast-json-patch-3.1.1.tgz", + "integrity": "sha512-vf6IHUX2SBcA+5/+4883dsIjpBTqmfBjmYiWK1savxQmFk4JfBMLa7ynTYOs1Rolp/T1betJxHiGD3g1Mn8lUQ==", + "license": "MIT" + }, "node_modules/fdir": { "version": "6.5.0", "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz", diff --git a/frontend/package.json b/frontend/package.json index 61ddaf9..bb1ea6c 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -9,6 +9,7 @@ "preview": "vite preview" }, "dependencies": { + "fast-json-patch": "^3.1.1", "react": "^19", "react-dom": "^19", "zustand": "^5" diff --git a/pyproject.toml b/pyproject.toml index 18a0b0e..eedc45d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,6 +7,7 @@ dependencies = [ "uvicorn[standard]", "fastmcp", "aiofiles", + "jsonpatch", ] [project.scripts] diff --git a/uv.lock b/uv.lock index ff2fe1c..367e259 100644 --- a/uv.lock +++ b/uv.lock @@ -491,6 +491,27 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b2/a3/e137168c9c44d18eff0376253da9f1e9234d0239e0ee230d2fee6cea8e55/jeepney-0.9.0-py3-none-any.whl", hash = "sha256:97e5714520c16fc0a45695e5365a2e11b81ea79bba796e26f9f1d178cb182683", size = 49010, upload-time = "2025-02-27T18:51:00.104Z" }, ] +[[package]] +name = "jsonpatch" +version = "1.33" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "jsonpointer" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/42/78/18813351fe5d63acad16aec57f94ec2b70a09e53ca98145589e185423873/jsonpatch-1.33.tar.gz", hash = "sha256:9fcd4009c41e6d12348b4a0ff2563ba56a2923a7dfee731d004e212e1ee5030c", size = 21699, upload-time = "2023-06-26T12:07:29.144Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/73/07/02e16ed01e04a374e644b575638ec7987ae846d25ad97bcc9945a3ee4b0e/jsonpatch-1.33-py2.py3-none-any.whl", hash = "sha256:0ae28c0cd062bbd8b8ecc26d7d164fbbea9652a1a3693f3b956c1eae5145dade", size = 12898, upload-time = "2023-06-16T21:01:28.466Z" }, +] + +[[package]] +name = "jsonpointer" +version = "3.1.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/18/c7/af399a2e7a67fd18d63c40c5e62d3af4e67b836a2107468b6a5ea24c4304/jsonpointer-3.1.1.tar.gz", hash = "sha256:0b801c7db33a904024f6004d526dcc53bbb8a4a0f4e32bfd10beadf60adf1900", size = 9068, upload-time = "2026-03-23T22:32:32.458Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9e/6a/a83720e953b1682d2d109d3c2dbb0bc9bf28cc1cbc205be4ef4be5da709d/jsonpointer-3.1.1-py3-none-any.whl", hash = "sha256:8ff8b95779d071ba472cf5bc913028df06031797532f08a7d5b602d8b2a488ca", size = 7659, upload-time = "2026-03-23T22:32:31.568Z" }, +] + [[package]] name = "jsonref" version = "1.1.0" @@ -565,6 +586,7 @@ source = { editable = "." } dependencies = [ { name = "aiofiles" }, { name = "fastmcp" }, + { name = "jsonpatch" }, { name = "starlette" }, { name = "uvicorn", extra = ["standard"] }, ] @@ -579,6 +601,7 @@ dev = [ requires-dist = [ { name = "aiofiles" }, { name = "fastmcp" }, + { name = "jsonpatch" }, { name = "starlette" }, { name = "uvicorn", extras = ["standard"] }, ] From 543471b6e17003831ff3bc8297edf8bcb5cf313f Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 17:51:37 +0700 Subject: [PATCH 253/412] rewrite projection model with KoanBaseModel, per-agent conversations, JSON Patch KoanBaseModel with camelCase alias_generator and to_wire(). New 3-field Projection (settings, run, notifications) replaces 15 flat fields. Unified agents dict, Focus discriminated union, ConversationEntry union with flush semantics. ProjectionStore computes JSON Patches via jsonpatch.make_patch and broadcasts plain dicts. events_since removed. --- koan/driver.py | 8 +- koan/events.py | 28 +- koan/projections.py | 1202 +++++++++++++++++++++++++++++++++---------- 3 files changed, 949 insertions(+), 289 deletions(-) diff --git a/koan/driver.py b/koan/driver.py index 117dfcb..9b4a32d 100644 --- a/koan/driver.py +++ b/koan/driver.py @@ -94,7 +94,13 @@ def _push_artifact_diff(app_state: AppState) -> None: new_artifacts = list_artifacts(app_state.epic_dir) except Exception: return - old = app_state.projection_store.projection.artifacts + run = app_state.projection_store.projection.run + if run is None: + old = {} + else: + # build_artifact_diff expects dict[str, dict] with 'modified_at' and 'size' keys + old = {path: {"path": info.path, "size": info.size, "modified_at": info.modified_at} + for path, info in run.artifacts.items()} for event_type, payload in build_artifact_diff(old, new_artifacts): app_state.projection_store.push_event(event_type, payload) diff --git a/koan/events.py b/koan/events.py index f2e09a0..16e1e68 100644 --- a/koan/events.py +++ b/koan/events.py @@ -11,6 +11,18 @@ from .state import AgentState +def build_run_started( + profile: str, + installations: dict[str, str], + scout_concurrency: int, +) -> dict: + return { + "profile": profile, + "installations": installations, + "scout_concurrency": scout_concurrency, + } + + def build_agent_spawned(agent: AgentState) -> dict: return { "agent_id": agent.agent_id, @@ -216,8 +228,13 @@ def build_workflow_decided( # -- Configuration event builders --------------------------------------------- -def build_probe_completed(runners: list[dict]) -> dict: - return {"runners": runners} +def build_probe_completed(results: dict[str, bool]) -> dict: + """Build probe_completed payload. + + Args: + results: mapping of installation alias → available (bool). + """ + return {"results": results} def build_installation_created( @@ -258,10 +275,11 @@ def build_profile_removed(name: str) -> dict: return {"name": name} -def build_active_profile_changed(name: str) -> dict: +def build_default_profile_changed(name: str) -> dict: return {"name": name} - -def build_scout_concurrency_changed(value: int) -> dict: +def build_default_scout_concurrency_changed(value: int) -> dict: return {"value": value} + + diff --git a/koan/projections.py b/koan/projections.py index 1d550a2..7df3177 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -1,19 +1,36 @@ -# Projection event-sourcing machinery. -# Pure -- zero koan domain imports. All fold logic lives here. +# Projection event-sourcing machinery: server-authoritative state with JSON Patch. +# +# Architecture: the fold runs only in Python. The frontend receives a full snapshot on +# connect, then RFC 6902 JSON Patch operations after each event. It has no fold logic. +# +# ProjectionStore holds three things: +# events -- append-only audit log, never modified +# projection -- materialized state, recomputed on every push_event +# prev_state -- to_wire() output from before the last fold, used to compute patches +# +# push_event flow: append to log → fold → to_wire → make_patch → broadcast plain dicts. +# All paths are uniform; no branching by event type. CamelCase wire format via KoanBaseModel. from __future__ import annotations import asyncio import logging from datetime import datetime, timezone -from typing import Literal +from typing import Annotated, Literal -from pydantic import BaseModel, Field +import jsonpatch +from pydantic import BaseModel, ConfigDict, Field +from pydantic.alias_generators import to_camel log = logging.getLogger("koan.projections") +# --------------------------------------------------------------------------- +# Event type registry +# --------------------------------------------------------------------------- + EventType = Literal[ # Lifecycle + "run_started", "phase_started", "agent_spawned", "agent_spawn_failed", @@ -33,7 +50,7 @@ "thinking", "stream_delta", "stream_cleared", - # Interactions + # Focus (interactions) "questions_asked", "questions_answered", "artifact_review_requested", @@ -44,7 +61,7 @@ "artifact_created", "artifact_modified", "artifact_removed", - # Configuration + # Settings "probe_completed", "installation_created", "installation_modified", @@ -52,85 +69,348 @@ "profile_created", "profile_modified", "profile_removed", - "active_profile_changed", - "scout_concurrency_changed", + "default_profile_changed", + "default_scout_concurrency_changed", ] +# --------------------------------------------------------------------------- +# Wire serialization base +# --------------------------------------------------------------------------- + +class KoanBaseModel(BaseModel): + """Base model for all projection classes. + + alias_generator converts snake_case field names to camelCase at serialization. + populate_by_name=True lets Python code use snake_case attributes normally; + only to_wire() output is camelCase. + """ + + model_config = ConfigDict( + alias_generator=to_camel, + populate_by_name=True, + ) + + def to_wire(self) -> dict: + """Serialize to camelCase dict for snapshots and JSON Patch computation. + + Always call this at serialization boundaries, never model_dump() directly. + snake_case keys from model_dump() break patch paths on the frontend. + """ + return self.model_dump(by_alias=True) + + +# --------------------------------------------------------------------------- +# Versioned event envelope (audit log; NOT KoanBaseModel — never sent to wire) +# --------------------------------------------------------------------------- + class VersionedEvent(BaseModel): version: int - event_type: str # EventType string; stored as str so unknown types deserialise safely + event_type: str # stored as str so unknown types deserialise without error timestamp: str agent_id: str | None = None payload: dict -class AgentProjection(BaseModel): +# --------------------------------------------------------------------------- +# ConversationEntry discriminated union +# --------------------------------------------------------------------------- + +class ThinkingEntry(KoanBaseModel): + type: Literal["thinking"] = "thinking" + content: str # full accumulated thinking text + +class TextEntry(KoanBaseModel): + type: Literal["text"] = "text" + text: str # full accumulated output text + +class StepEntry(KoanBaseModel): + type: Literal["step"] = "step" + step: int + step_name: str + total_steps: int | None = None + +class BaseToolEntry(KoanBaseModel): + """Shared fields for all tool entries.""" + call_id: str # unique per tool invocation + in_flight: bool # True until tool_completed + +class ToolReadEntry(BaseToolEntry): + type: Literal["tool_read"] = "tool_read" + file: str # path that was read + lines: str = "" # line range, e.g. "1-50" + +class ToolWriteEntry(BaseToolEntry): + type: Literal["tool_write"] = "tool_write" + file: str # path that was created or overwritten + +class ToolEditEntry(BaseToolEntry): + type: Literal["tool_edit"] = "tool_edit" + file: str # path that was edited in-place + +class ToolBashEntry(BaseToolEntry): + type: Literal["tool_bash"] = "tool_bash" + command: str # shell command executed + +class ToolGrepEntry(BaseToolEntry): + type: Literal["tool_grep"] = "tool_grep" + pattern: str # search pattern + +class ToolLsEntry(BaseToolEntry): + type: Literal["tool_ls"] = "tool_ls" + path: str # directory listed + +class ToolGenericEntry(BaseToolEntry): + """Catch-all for tools without a typed variant (e.g. custom MCP tools).""" + type: Literal["tool_generic"] = "tool_generic" + tool_name: str # original tool name from the LLM + summary: str = "" # human-readable one-liner from the runner parser + +ConversationEntry = Annotated[ + ThinkingEntry | TextEntry | StepEntry | + ToolReadEntry | ToolWriteEntry | ToolEditEntry | + ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry, + Field(discriminator="type"), +] + + +# --------------------------------------------------------------------------- +# Conversation — per agent +# --------------------------------------------------------------------------- + +class Conversation(KoanBaseModel): + entries: list[ConversationEntry] = [] + pending_thinking: str = "" # in-progress reasoning, not yet flushed to ThinkingEntry + pending_text: str = "" # in-progress text output, not yet flushed to TextEntry + is_thinking: bool = False # True while thinking deltas are arriving + input_tokens: int = 0 # accumulated from agent_step_advanced usage + output_tokens: int = 0 + + +# --------------------------------------------------------------------------- +# Focus discriminated union +# --------------------------------------------------------------------------- + +class ConversationFocus(KoanBaseModel): + """Default state: rendering an agent's conversation.""" + type: Literal["conversation"] = "conversation" + agent_id: str + +class QuestionFocus(KoanBaseModel): + """Agent is blocked, needs user input.""" + type: Literal["question"] = "question" + agent_id: str + token: str + questions: list[dict] = [] + +class ReviewFocus(KoanBaseModel): + """Agent is blocked, artifact needs review.""" + type: Literal["review"] = "review" + agent_id: str + token: str + path: str = "" + description: str = "" + content: str = "" + +class DecisionFocus(KoanBaseModel): + """Workflow decision needed from user.""" + type: Literal["decision"] = "decision" + agent_id: str + token: str + chat_turns: list[dict] = [] + +Focus = Annotated[ + ConversationFocus | QuestionFocus | ReviewFocus | DecisionFocus, + Field(discriminator="type"), +] + + +# --------------------------------------------------------------------------- +# Agent +# --------------------------------------------------------------------------- + +class Agent(KoanBaseModel): + # Identity — set at queue/spawn time, never changes agent_id: str role: str + label: str = "" model: str | None = None + is_primary: bool = False + + # Lifecycle — state machine: queued → running → done | failed + status: Literal["queued", "running", "done", "failed"] = "queued" + error: str | None = None + started_at_ms: int = 0 + + # Progress — updated during execution, shown in agent monitor step: int = 0 step_name: str = "" - started_at_ms: int = 0 - input_tokens: int = 0 - output_tokens: int = 0 + last_tool: str = "" + # Content + conversation: Conversation = Field(default_factory=Conversation) -class Projection(BaseModel): - # Run state - run_started: bool = False - phase: str = "" - # Agents - primary_agent: AgentProjection | None = None - scouts: dict[str, AgentProjection] = Field(default_factory=dict) - completed_agents: list[AgentProjection] = Field(default_factory=list) +# --------------------------------------------------------------------------- +# Settings and run configuration +# --------------------------------------------------------------------------- - # Activity (raw events appended as-is: tool_called, tool_completed, thinking) - activity_log: list[dict] = Field(default_factory=list) - stream_buffer: str = "" +class Installation(KoanBaseModel): + """A configured LLM CLI installation.""" + alias: str + runner_type: str + binary: str + extra_args: list[str] = [] + available: bool = False # probe result: binary exists and responds - # Interactions - active_interaction: dict | None = None +class Profile(KoanBaseModel): + """Maps roles to installations for a workflow run.""" + name: str + read_only: bool = False + tiers: dict[str, str] = {} # role → installation alias - # Resources - artifacts: dict[str, dict] = Field(default_factory=dict) # keyed by path - notifications: list[dict] = Field(default_factory=list) # derived from error events +class Settings(KoanBaseModel): + installations: dict[str, Installation] = {} # alias → Installation + profiles: dict[str, Profile] = {} # name → Profile + default_profile: str = "balanced" + default_scout_concurrency: int = 8 + +class RunConfig(KoanBaseModel): + """Resolved configuration frozen at run start.""" + profile: str + installations: dict[str, str] = {} # role → installation alias + scout_concurrency: int = 8 + + +# --------------------------------------------------------------------------- +# Supporting types +# --------------------------------------------------------------------------- - queued_scouts: list[dict] = Field(default_factory=list) +class ArtifactInfo(KoanBaseModel): + path: str + size: int = 0 + modified_at: int = 0 # milliseconds since epoch - # Completion - completion: dict | None = None +class CompletionInfo(KoanBaseModel): + success: bool + summary: str = "" + error: str | None = None - # Configuration - config_runners: list[dict] = Field(default_factory=list) - config_profiles: list[dict] = Field(default_factory=list) - config_installations: list[dict] = Field(default_factory=list) - config_active_profile: str = "balanced" - config_scout_concurrency: int = 8 +class Notification(KoanBaseModel): + message: str + level: Literal["info", "warning", "error"] = "info" + timestamp_ms: int = 0 +# --------------------------------------------------------------------------- +# Run and top-level Projection +# --------------------------------------------------------------------------- + +class Run(KoanBaseModel): + config: RunConfig + phase: str = "" + agents: dict[str, Agent] = {} # all agents by ID — queued, running, done, failed + focus: Focus | None = None # None before first agent spawns + artifacts: dict[str, ArtifactInfo] = {} + completion: CompletionInfo | None = None + +class Projection(KoanBaseModel): + settings: Settings = Field(default_factory=Settings) + run: Run | None = None # None → show landing page + notifications: list[Notification] = [] + + +# --------------------------------------------------------------------------- +# Fold helpers +# --------------------------------------------------------------------------- + def _utcnow() -> str: return datetime.now(timezone.utc).isoformat() -def _accumulate_usage(agent: AgentProjection, usage: dict | None) -> AgentProjection: - if not usage: - return agent - return agent.model_copy(update={ - "input_tokens": agent.input_tokens + usage.get("input_tokens", 0), - "output_tokens": agent.output_tokens + usage.get("output_tokens", 0), +def _flush_conversation(conv: Conversation) -> Conversation: + """Flush both pending fields into completed entries. + + Creates a ThinkingEntry from pending_thinking and/or TextEntry from pending_text, + appends them to entries, and resets both pending fields and is_thinking. + """ + new_entries = list(conv.entries) + if conv.pending_thinking: + new_entries.append(ThinkingEntry(content=conv.pending_thinking)) + if conv.pending_text: + new_entries.append(TextEntry(text=conv.pending_text)) + return conv.model_copy(update={ + "entries": new_entries, + "pending_thinking": "", + "pending_text": "", + "is_thinking": False, + }) + + +def _flush_pending_text(conv: Conversation) -> Conversation: + """Flush only pending_text into a TextEntry (used when thinking starts).""" + if not conv.pending_text: + return conv.model_copy(update={"is_thinking": True}) + return conv.model_copy(update={ + "entries": [*conv.entries, TextEntry(text=conv.pending_text)], + "pending_text": "", + "is_thinking": True, }) +def _flush_pending_thinking(conv: Conversation) -> Conversation: + """Flush only pending_thinking into a ThinkingEntry (used when text starts).""" + if not conv.pending_thinking: + return conv.model_copy(update={"is_thinking": False}) + return conv.model_copy(update={ + "entries": [*conv.entries, ThinkingEntry(content=conv.pending_thinking)], + "pending_thinking": "", + "is_thinking": False, + }) + + +def _get_agent(run: Run, agent_id: str | None) -> Agent | None: + if not agent_id or run is None: + return None + return run.agents.get(agent_id) + + +def _primary_agent_id(run: Run) -> str | None: + """Return the agent_id of the primary agent, or None.""" + if run is None: + return None + for agent in run.agents.values(): + if agent.is_primary and agent.status == "running": + return agent.agent_id + # Fall back to any primary agent (e.g. if it just exited) + for agent in run.agents.values(): + if agent.is_primary: + return agent.agent_id + return None + + + + +def _update_agent_conversation(run: Run, agent_id: str, new_conv: Conversation, **extra) -> Run: + """Return a new Run with the agent's conversation replaced and optional extra updates.""" + agent = run.agents.get(agent_id) + if agent is None: + return run + new_agent = agent.model_copy(update={"conversation": new_conv, **extra}) + new_agents = dict(run.agents) + new_agents[agent_id] = new_agent + return run.model_copy(update={"agents": new_agents}) + + +# --------------------------------------------------------------------------- +# Fold +# --------------------------------------------------------------------------- + def fold(projection: Projection, event: VersionedEvent) -> Projection: - """Pure fold: (Projection, VersionedEvent) -> Projection. + """Pure fold: (Projection, VersionedEvent) → Projection. Unknown event types return projection unchanged with a logged warning. - Unknown agent_ids for agent-specific events return projection unchanged with a logged warning. - Any exception within a handler returns projection unchanged, with the exception logged. - The event is always appended to the log before fold() is called; fold exceptions do not - prevent appending. + Any exception returns projection unchanged with the exception logged. """ event_type = event.event_type payload = event.payload @@ -139,304 +419,637 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: try: match event_type: - # ── Lifecycle ────────────────────────────────────────────────────── - - case "phase_started": - return projection.model_copy(update={ - "phase": payload.get("phase", ""), - "run_started": True, - }) + # ── Run lifecycle ────────────────────────────────────────────── - case "agent_spawned": - eid = agent_id or payload.get("agent_id", "") - new_agent = AgentProjection( - agent_id=eid, - role=payload.get("role", ""), - model=payload.get("model"), - step=0, - started_at_ms=payload.get("started_at_ms", 0), + case "run_started": + config = RunConfig( + profile=payload.get("profile", ""), + installations=payload.get("installations", {}), + scout_concurrency=payload.get("scout_concurrency", 8), ) - if payload.get("is_primary", True): - return projection.model_copy(update={"primary_agent": new_agent}) - else: - new_scouts = dict(projection.scouts) - new_scouts[eid] = new_agent - # Remove from queued_scouts when scout starts running - lbl = payload.get("label", "") - new_queued = [s for s in projection.queued_scouts if s.get("label") != lbl] - return projection.model_copy(update={"scouts": new_scouts, "queued_scouts": new_queued}) + return projection.model_copy(update={"run": Run(config=config)}) - case "scout_queued": - entry = { - "scout_id": payload.get("scout_id", ""), - "label": payload.get("label", ""), - "model": payload.get("model"), - } - return projection.model_copy(update={ - "queued_scouts": [*projection.queued_scouts, entry], - }) + case "phase_started": + if projection.run is None: + log.warning("fold phase_started: run is None, skipping") + return projection + new_run = projection.run.model_copy(update={"phase": payload.get("phase", "")}) + return projection.model_copy(update={"run": new_run}) - case "agent_spawn_failed": - notification = { - "type": "agent_spawn_failed", - "role": payload.get("role", ""), - "error_code": payload.get("error_code", ""), - "message": payload.get("message", ""), - "details": payload.get("details"), - } - return projection.model_copy(update={ - "notifications": [*projection.notifications, notification], - }) + case "workflow_completed": + if projection.run is None: + log.warning("fold workflow_completed: run is None, skipping") + return projection + completion = CompletionInfo( + success=payload.get("success", False), + summary=payload.get("summary", ""), + error=payload.get("error"), + ) + new_run = projection.run.model_copy(update={"completion": completion}) + return projection.model_copy(update={"run": new_run}) - case "agent_step_advanced": - usage = payload.get("usage") - step = payload.get("step", 0) - step_name = payload.get("step_name", "") + # ── Agent lifecycle ──────────────────────────────────────────── - # Append to activity_log so snapshots include step markers - step_entry = {"event_type": event_type, "agent_id": agent_id, **payload} - new_log = [*projection.activity_log, step_entry] + case "scout_queued": + if projection.run is None: + log.warning("fold scout_queued: run is None, skipping") + return projection + scout_id = payload.get("scout_id", "") + new_agent = Agent( + agent_id=scout_id, + role="scout", + label=payload.get("label", ""), + model=payload.get("model"), + status="queued", + ) + new_agents = dict(projection.run.agents) + new_agents[scout_id] = new_agent + new_run = projection.run.model_copy(update={"agents": new_agents}) + return projection.model_copy(update={"run": new_run}) - if projection.primary_agent and projection.primary_agent.agent_id == agent_id: - updated = projection.primary_agent.model_copy(update={ - "step": step, - "step_name": step_name, - }) - updated = _accumulate_usage(updated, usage) - return projection.model_copy(update={ - "primary_agent": updated, - "activity_log": new_log, + case "agent_spawned": + if projection.run is None: + log.warning("fold agent_spawned: run is None, skipping") + return projection + eid = agent_id or payload.get("agent_id", "") + is_primary = payload.get("is_primary", False) + new_agents = dict(projection.run.agents) + + if eid in new_agents: + # Scout was previously queued — transition to running + existing = new_agents[eid] + new_agents[eid] = existing.model_copy(update={ + "status": "running", + "started_at_ms": payload.get("started_at_ms", 0), + "role": payload.get("role", existing.role), + "label": payload.get("label", existing.label), + "model": payload.get("model", existing.model), }) - elif agent_id and agent_id in projection.scouts: - updated = projection.scouts[agent_id].model_copy(update={ - "step": step, - "step_name": step_name, + else: + # New agent (primary agents are always new) + new_agents[eid] = Agent( + agent_id=eid, + role=payload.get("role", ""), + label=payload.get("label", ""), + model=payload.get("model"), + is_primary=is_primary, + status="running", + started_at_ms=payload.get("started_at_ms", 0), + ) + + new_run = projection.run.model_copy(update={"agents": new_agents}) + + # Set ConversationFocus when primary agent spawns + if is_primary: + new_run = new_run.model_copy(update={ + "focus": ConversationFocus(agent_id=eid), }) - updated = _accumulate_usage(updated, usage) - new_scouts = dict(projection.scouts) - new_scouts[agent_id] = updated + + return projection.model_copy(update={"run": new_run}) + + case "agent_exited": + error = payload.get("error") + # Append error notification regardless of run/agent state — the fact + # of a failed exit is worth preserving even if the agent wasn't tracked. + if error and (projection.run is None or not agent_id or + agent_id not in (projection.run.agents if projection.run else {})): + notif = Notification( + message=f"Agent exited with error: {error}", + level="error", + timestamp_ms=int(datetime.now(timezone.utc).timestamp() * 1000), + ) return projection.model_copy(update={ - "scouts": new_scouts, - "activity_log": new_log, + "notifications": [*projection.notifications, notif], }) - else: - log.warning("fold agent_step_advanced: unknown agent_id=%s", agent_id) - return projection.model_copy(update={"activity_log": new_log}) + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + log.warning("fold agent_exited: unknown agent_id=%s", agent_id) + return projection - case "agent_exited": + exit_code = payload.get("exit_code", 0) usage = payload.get("usage") - error = payload.get("error") + status: Literal["done", "failed"] = "failed" if error or exit_code != 0 else "done" + + # Accumulate final usage into conversation + new_conv = agent.conversation + if usage: + new_conv = new_conv.model_copy(update={ + "input_tokens": new_conv.input_tokens + usage.get("input_tokens", 0), + "output_tokens": new_conv.output_tokens + usage.get("output_tokens", 0), + }) - new_notifications = list(projection.notifications) + new_agent = agent.model_copy(update={ + "status": status, + "error": error, + "conversation": new_conv, + }) + new_agents = dict(projection.run.agents) + new_agents[agent_id] = new_agent + new_run = projection.run.model_copy(update={"agents": new_agents}) + new_projection = projection.model_copy(update={"run": new_run}) + + # Append error notification if error: - new_notifications.append({ - "type": "agent_exited_error", - "agent_id": agent_id, - "exit_code": payload.get("exit_code", 1), - "error": error, + notif = Notification( + message=f"Agent {agent_id} exited with error: {error}", + level="error", + timestamp_ms=int(datetime.now(timezone.utc).timestamp() * 1000), + ) + new_projection = new_projection.model_copy(update={ + "notifications": [*new_projection.notifications, notif], }) + return new_projection - new_completed = list(projection.completed_agents) + case "agent_spawn_failed": + notif = Notification( + message=payload.get("message", "Agent spawn failed"), + level="error", + timestamp_ms=int(datetime.now(timezone.utc).timestamp() * 1000), + ) + return projection.model_copy(update={ + "notifications": [*projection.notifications, notif], + }) - if projection.primary_agent and projection.primary_agent.agent_id == agent_id: - # Accumulate final tokens, preserve in completed_agents, then clear - final_agent = _accumulate_usage(projection.primary_agent, usage) - new_completed.append(final_agent) - return projection.model_copy(update={ - "primary_agent": None, - "completed_agents": new_completed, - "notifications": new_notifications, - }) - elif agent_id and agent_id in projection.scouts: - final_agent = _accumulate_usage(projection.scouts[agent_id], usage) - new_completed.append(final_agent) - new_scouts = {k: v for k, v in projection.scouts.items() if k != agent_id} - return projection.model_copy(update={ - "scouts": new_scouts, - "completed_agents": new_completed, - "notifications": new_notifications, - }) - else: - # Unknown agent_id: return unchanged per plan semantics. - # Error notifications are still recorded — the fact of an - # error exit is worth preserving even if the agent wasn't - # tracked (e.g. late-arriving event after projection reset). - if new_notifications != projection.notifications: - log.warning("fold agent_exited: unknown agent_id=%s, preserving error notification", agent_id) - return projection.model_copy(update={"notifications": new_notifications}) - log.warning("fold agent_exited: unknown agent_id=%s", agent_id) + # ── Agent conversation ───────────────────────────────────────── + + case "thinking": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: return projection + delta = payload.get("delta", "") + # Flush pending_text → TextEntry, then accumulate thinking delta + new_conv = _flush_pending_text(agent.conversation) + new_conv = new_conv.model_copy(update={ + "pending_thinking": new_conv.pending_thinking + delta, + "is_thinking": True, + }) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv), + }) - case "workflow_completed": - return projection.model_copy(update={"completion": payload}) + case "stream_delta": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + delta = payload.get("delta", "") + # Flush pending_thinking → ThinkingEntry, then accumulate text delta + new_conv = _flush_pending_thinking(agent.conversation) + new_conv = new_conv.model_copy(update={ + "pending_text": new_conv.pending_text + delta, + "is_thinking": False, + }) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv), + }) - # ── Activity ─────────────────────────────────────────────────────── + case "stream_cleared": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + new_conv = _flush_conversation(agent.conversation) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv), + }) case "tool_called": - entry = {"event_type": event_type, "agent_id": agent_id, **payload} + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + tool_name = payload.get("tool", "") + # Skip koan MCP tools — they are infrastructure, not user-visible activity + if tool_name.startswith("koan_") or tool_name.startswith("mcp__koan"): + return projection + call_id = payload.get("call_id", "") + summary = payload.get("summary", "") + last_tool = f"{tool_name} {summary}".strip() if summary else tool_name + new_conv = _flush_conversation(agent.conversation) + new_entry = ToolGenericEntry( + call_id=call_id, + in_flight=True, + tool_name=tool_name, + summary=summary, + ) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, new_entry], + }) return projection.model_copy(update={ - "activity_log": [*projection.activity_log, entry], + "run": _update_agent_conversation(projection.run, agent_id, new_conv, + last_tool=last_tool), }) - case "tool_completed": - entry = {"event_type": event_type, "agent_id": agent_id, **payload} + case "tool_read": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + file = payload.get("file", "") + lines = payload.get("lines", "") + last_tool = f"read {file}:{lines}" if lines else f"read {file}" + new_conv = _flush_conversation(agent.conversation) + new_entry = ToolReadEntry( + call_id=payload.get("call_id", ""), + in_flight=True, + file=file, + lines=lines, + ) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, new_entry], + }) return projection.model_copy(update={ - "activity_log": [*projection.activity_log, entry], + "run": _update_agent_conversation(projection.run, agent_id, new_conv, + last_tool=last_tool), }) - case "tool_read" | "tool_write" | "tool_edit" | "tool_bash" | "tool_grep" | "tool_ls": - entry = {"event_type": event_type, "agent_id": agent_id, **payload} + case "tool_write": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + file = payload.get("file", "") + new_conv = _flush_conversation(agent.conversation) + new_entry = ToolWriteEntry( + call_id=payload.get("call_id", ""), + in_flight=True, + file=file, + ) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, new_entry], + }) return projection.model_copy(update={ - "activity_log": [*projection.activity_log, entry], + "run": _update_agent_conversation(projection.run, agent_id, new_conv, + last_tool=f"write {file}"), }) - case "thinking": - entry = {"event_type": event_type, "agent_id": agent_id, **payload} + case "tool_edit": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + file = payload.get("file", "") + new_conv = _flush_conversation(agent.conversation) + new_entry = ToolEditEntry( + call_id=payload.get("call_id", ""), + in_flight=True, + file=file, + ) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, new_entry], + }) return projection.model_copy(update={ - "activity_log": [*projection.activity_log, entry], + "run": _update_agent_conversation(projection.run, agent_id, new_conv, + last_tool=f"edit {file}"), }) - case "stream_delta": + case "tool_bash": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + command = payload.get("command", "") + new_conv = _flush_conversation(agent.conversation) + new_entry = ToolBashEntry( + call_id=payload.get("call_id", ""), + in_flight=True, + command=command, + ) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, new_entry], + }) return projection.model_copy(update={ - "stream_buffer": projection.stream_buffer + payload.get("delta", ""), + "run": _update_agent_conversation(projection.run, agent_id, new_conv, + last_tool=f"bash {command}"), }) - case "stream_cleared": - return projection.model_copy(update={"stream_buffer": ""}) + case "tool_grep": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + pattern = payload.get("pattern", "") + new_conv = _flush_conversation(agent.conversation) + new_entry = ToolGrepEntry( + call_id=payload.get("call_id", ""), + in_flight=True, + pattern=pattern, + ) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, new_entry], + }) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv, + last_tool=f"grep {pattern}"), + }) - # ── Interactions ─────────────────────────────────────────────────── + case "tool_ls": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + path = payload.get("path", "") + new_conv = _flush_conversation(agent.conversation) + new_entry = ToolLsEntry( + call_id=payload.get("call_id", ""), + in_flight=True, + path=path, + ) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, new_entry], + }) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv, + last_tool=f"ls {path}"), + }) + + case "tool_completed": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + call_id = payload.get("call_id", "") + # Scan entries for the matching in-flight tool entry and mark it done + new_entries = [] + for entry in agent.conversation.entries: + if isinstance(entry, BaseToolEntry) and entry.call_id == call_id: + new_entries.append(entry.model_copy(update={"in_flight": False})) + else: + new_entries.append(entry) + new_conv = agent.conversation.model_copy(update={"entries": new_entries}) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv), + }) + + case "agent_step_advanced": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + log.warning("fold agent_step_advanced: unknown agent_id=%s", agent_id) + return projection + + step = payload.get("step", 0) + step_name = payload.get("step_name", "") + total_steps = payload.get("total_steps") + usage = payload.get("usage") + + # Flush both pending fields, optionally append StepEntry + new_conv = _flush_conversation(agent.conversation) + if step >= 1: + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, StepEntry( + step=step, + step_name=step_name, + total_steps=total_steps, + )], + }) + + # Accumulate token usage from step + if usage: + new_conv = new_conv.model_copy(update={ + "input_tokens": new_conv.input_tokens + usage.get("input_tokens", 0), + "output_tokens": new_conv.output_tokens + usage.get("output_tokens", 0), + }) + + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv, + step=step, step_name=step_name), + }) + + # ── Focus transitions ────────────────────────────────────────── case "questions_asked": - active = {"interaction_type": "questions_asked", **payload} - return projection.model_copy(update={"active_interaction": active}) + if projection.run is None or not agent_id: + return projection + new_focus = QuestionFocus( + agent_id=agent_id, + token=payload.get("token", ""), + questions=payload.get("questions", []), + ) + new_run = projection.run.model_copy(update={"focus": new_focus}) + return projection.model_copy(update={"run": new_run}) case "questions_answered": - return projection.model_copy(update={"active_interaction": None}) + if projection.run is None: + return projection + pid = _primary_agent_id(projection.run) + if pid is None: + return projection + new_run = projection.run.model_copy(update={ + "focus": ConversationFocus(agent_id=pid), + }) + return projection.model_copy(update={"run": new_run}) case "artifact_review_requested": - active = {"interaction_type": "artifact_review_requested", **payload} - return projection.model_copy(update={"active_interaction": active}) + if projection.run is None or not agent_id: + return projection + new_focus = ReviewFocus( + agent_id=agent_id, + token=payload.get("token", ""), + path=payload.get("path", ""), + description=payload.get("description", ""), + content=payload.get("content", ""), + ) + new_run = projection.run.model_copy(update={"focus": new_focus}) + return projection.model_copy(update={"run": new_run}) case "artifact_reviewed": - return projection.model_copy(update={"active_interaction": None}) + if projection.run is None: + return projection + pid = _primary_agent_id(projection.run) + if pid is None: + return projection + new_run = projection.run.model_copy(update={ + "focus": ConversationFocus(agent_id=pid), + }) + return projection.model_copy(update={"run": new_run}) case "workflow_decision_requested": - active = {"interaction_type": "workflow_decision_requested", **payload} - return projection.model_copy(update={"active_interaction": active}) + if projection.run is None or not agent_id: + return projection + new_focus = DecisionFocus( + agent_id=agent_id, + token=payload.get("token", ""), + chat_turns=payload.get("chat_turns", []), + ) + new_run = projection.run.model_copy(update={"focus": new_focus}) + return projection.model_copy(update={"run": new_run}) case "workflow_decided": - return projection.model_copy(update={"active_interaction": None}) + if projection.run is None: + return projection + pid = _primary_agent_id(projection.run) + if pid is None: + return projection + new_run = projection.run.model_copy(update={ + "focus": ConversationFocus(agent_id=pid), + }) + return projection.model_copy(update={"run": new_run}) - # ── Resources ────────────────────────────────────────────────────── + # ── Resources ───────────────────────────────────────────────── case "artifact_created": + if projection.run is None: + return projection path = payload.get("path", "") - new_artifacts = dict(projection.artifacts) - new_artifacts[path] = { - "path": path, - "size": payload.get("size", 0), - "modified_at": payload.get("modified_at", 0), - } - return projection.model_copy(update={"artifacts": new_artifacts}) + info = ArtifactInfo( + path=path, + size=payload.get("size", 0), + modified_at=payload.get("modified_at", 0), + ) + new_artifacts = dict(projection.run.artifacts) + new_artifacts[path] = info + new_run = projection.run.model_copy(update={"artifacts": new_artifacts}) + return projection.model_copy(update={"run": new_run}) case "artifact_modified": + if projection.run is None: + return projection path = payload.get("path", "") - new_artifacts = dict(projection.artifacts) - new_artifacts[path] = { - "path": path, - "size": payload.get("size", 0), - "modified_at": payload.get("modified_at", 0), - } - return projection.model_copy(update={"artifacts": new_artifacts}) + info = ArtifactInfo( + path=path, + size=payload.get("size", 0), + modified_at=payload.get("modified_at", 0), + ) + new_artifacts = dict(projection.run.artifacts) + new_artifacts[path] = info + new_run = projection.run.model_copy(update={"artifacts": new_artifacts}) + return projection.model_copy(update={"run": new_run}) case "artifact_removed": + if projection.run is None: + return projection path = payload.get("path", "") - new_artifacts = {k: v for k, v in projection.artifacts.items() if k != path} - return projection.model_copy(update={"artifacts": new_artifacts}) + new_artifacts = {k: v for k, v in projection.run.artifacts.items() if k != path} + new_run = projection.run.model_copy(update={"artifacts": new_artifacts}) + return projection.model_copy(update={"run": new_run}) - # ── Configuration ────────────────────────────────────────────────── + # ── Settings ────────────────────────────────────────────────── case "probe_completed": - return projection.model_copy(update={ - "config_runners": payload.get("runners", []), - }) + # Payload: {results: {alias: bool, ...}} + results: dict[str, bool] = payload.get("results", {}) + new_insts = dict(projection.settings.installations) + for alias, available in results.items(): + if alias in new_insts: + new_insts[alias] = new_insts[alias].model_copy(update={"available": available}) + new_settings = projection.settings.model_copy(update={"installations": new_insts}) + return projection.model_copy(update={"settings": new_settings}) case "installation_created": - new_inst = { - "alias": payload.get("alias", ""), - "runner_type": payload.get("runner_type", ""), - "binary": payload.get("binary", ""), - "extra_args": payload.get("extra_args", []), - } - return projection.model_copy(update={ - "config_installations": [*projection.config_installations, new_inst], - }) + alias = payload.get("alias", "") + inst = Installation( + alias=alias, + runner_type=payload.get("runner_type", ""), + binary=payload.get("binary", ""), + extra_args=payload.get("extra_args", []), + available=False, # availability set by probe_completed + ) + new_insts = dict(projection.settings.installations) + new_insts[alias] = inst + new_settings = projection.settings.model_copy(update={"installations": new_insts}) + return projection.model_copy(update={"settings": new_settings}) case "installation_modified": alias = payload.get("alias", "") - updated_inst = { - "alias": alias, - "runner_type": payload.get("runner_type", ""), - "binary": payload.get("binary", ""), - "extra_args": payload.get("extra_args", []), - } - new_insts = [ - updated_inst if inst.get("alias") == alias else inst - for inst in projection.config_installations - ] - return projection.model_copy(update={"config_installations": new_insts}) + existing = projection.settings.installations.get(alias) + available = existing.available if existing else False + inst = Installation( + alias=alias, + runner_type=payload.get("runner_type", ""), + binary=payload.get("binary", ""), + extra_args=payload.get("extra_args", []), + available=available, # preserve probe result + ) + new_insts = dict(projection.settings.installations) + new_insts[alias] = inst + new_settings = projection.settings.model_copy(update={"installations": new_insts}) + return projection.model_copy(update={"settings": new_settings}) case "installation_removed": alias = payload.get("alias", "") - new_insts = [ - inst for inst in projection.config_installations - if inst.get("alias") != alias - ] - return projection.model_copy(update={"config_installations": new_insts}) + new_insts = {k: v for k, v in projection.settings.installations.items() if k != alias} + new_settings = projection.settings.model_copy(update={"installations": new_insts}) + return projection.model_copy(update={"settings": new_settings}) case "profile_created": - new_profile = { - "name": payload.get("name", ""), - "read_only": payload.get("read_only", False), - "tiers": payload.get("tiers", {}), - } - return projection.model_copy(update={ - "config_profiles": [*projection.config_profiles, new_profile], - }) + name = payload.get("name", "") + # tiers in the projection are stored as dict[str, str] (role → alias). + # The payload tiers may be nested dicts from the old ProfileTier structure + # or simple string values from the new structure. Normalise to str. + raw_tiers = payload.get("tiers", {}) + tiers: dict[str, str] = {} + for role, val in raw_tiers.items(): + if isinstance(val, str): + tiers[role] = val + elif isinstance(val, dict): + # Legacy: extract alias or runner_type as a best-effort fallback + tiers[role] = val.get("alias", val.get("runner_type", str(val))) + else: + tiers[role] = str(val) + profile = Profile( + name=name, + read_only=payload.get("read_only", False), + tiers=tiers, + ) + new_profiles = dict(projection.settings.profiles) + new_profiles[name] = profile + new_settings = projection.settings.model_copy(update={"profiles": new_profiles}) + return projection.model_copy(update={"settings": new_settings}) case "profile_modified": name = payload.get("name", "") - updated_profile = { - "name": name, - "read_only": payload.get("read_only", False), - "tiers": payload.get("tiers", {}), - } - if any(p.get("name") == name for p in projection.config_profiles): - new_profiles = [ - updated_profile if p.get("name") == name else p - for p in projection.config_profiles - ] - else: - # First time (e.g. balanced on startup) - new_profiles = [*projection.config_profiles, updated_profile] - return projection.model_copy(update={"config_profiles": new_profiles}) + raw_tiers = payload.get("tiers", {}) + tiers = {} + for role, val in raw_tiers.items(): + if isinstance(val, str): + tiers[role] = val + elif isinstance(val, dict): + tiers[role] = val.get("alias", val.get("runner_type", str(val))) + else: + tiers[role] = str(val) + profile = Profile( + name=name, + read_only=payload.get("read_only", False), + tiers=tiers, + ) + new_profiles = dict(projection.settings.profiles) + new_profiles[name] = profile + new_settings = projection.settings.model_copy(update={"profiles": new_profiles}) + return projection.model_copy(update={"settings": new_settings}) case "profile_removed": name = payload.get("name", "") - new_profiles = [ - p for p in projection.config_profiles if p.get("name") != name - ] - return projection.model_copy(update={"config_profiles": new_profiles}) + new_profiles = {k: v for k, v in projection.settings.profiles.items() if k != name} + new_settings = projection.settings.model_copy(update={"profiles": new_profiles}) + return projection.model_copy(update={"settings": new_settings}) - case "active_profile_changed": - return projection.model_copy(update={ - "config_active_profile": payload.get("name", "balanced"), + case "default_profile_changed": + new_settings = projection.settings.model_copy(update={ + "default_profile": payload.get("name", "balanced"), }) + return projection.model_copy(update={"settings": new_settings}) - case "scout_concurrency_changed": - return projection.model_copy(update={ - "config_scout_concurrency": payload.get("value", 8), + case "default_scout_concurrency_changed": + new_settings = projection.settings.model_copy(update={ + "default_scout_concurrency": payload.get("value", 8), }) + return projection.model_copy(update={"settings": new_settings}) case _: log.warning("fold: unknown event_type=%r", event_type) @@ -444,20 +1057,35 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: except Exception: log.exception( - "fold: exception handling event_type=%r version=%d event=%r", - event_type, event.version, event, + "fold: exception handling event_type=%r version=%d", + event_type, event.version, ) return projection +# --------------------------------------------------------------------------- +# ProjectionStore +# --------------------------------------------------------------------------- + class ProjectionStore: - """In-memory versioned event log + materialized projection + asyncio.Queue subscribers.""" + """In-memory versioned event log + materialized projection + JSON Patch broadcaster. + + push_event flow: + 1. Increment version and append VersionedEvent to audit log. + 2. Fold event into projection. + 3. Compute RFC 6902 JSON Patch between prev_state and new_state (both camelCase). + 4. If patch is non-empty, broadcast {type, version, patch} dict to all subscriber queues. + + Subscriber queues receive plain dicts (not VersionedEvent objects) — the dict shape + matches the SSE JSON payload so sse_stream() can forward it directly. + """ def __init__(self) -> None: self.events: list[VersionedEvent] = [] self.projection: Projection = Projection() self.version: int = 0 - self.subscribers: list[asyncio.Queue] = [] + self.subscribers: set[asyncio.Queue] = set() + self.prev_state: dict = self.projection.to_wire() def push_event( self, @@ -465,7 +1093,7 @@ def push_event( payload: dict, agent_id: str | None = None, ) -> VersionedEvent: - """Append event, fold into projection, broadcast to subscribers.""" + """Append event, fold into projection, compute patch, broadcast to subscribers.""" self.version += 1 event = VersionedEvent( version=self.version, @@ -476,7 +1104,7 @@ def push_event( ) self.events.append(event) - # Fold — event is in the log regardless of fold success + old_state = self.prev_state try: self.projection = fold(self.projection, event) except Exception: @@ -485,10 +1113,25 @@ def push_event( self.version, event_type, ) - # Broadcast — snapshot list to avoid RuntimeError on concurrent subscribe/unsubscribe + new_state = self.projection.to_wire() + self.prev_state = new_state + + patch = jsonpatch.make_patch(old_state, new_state) + if not patch: + # No state change — koan MCP tools and other filtered events land here. + # Subscribers stay at the same version; no broadcast needed. + return event + + msg: dict = { + "type": "patch", + "version": self.version, + "patch": patch.patch, # list of RFC 6902 operation dicts + } + # Snapshot subscribers before iterating — defensive against concurrent + # add/remove (asyncio, not threading, but still good practice). for q in list(self.subscribers): try: - q.put_nowait(event) + q.put_nowait(msg) except asyncio.QueueFull: log.warning( "ProjectionStore: subscriber queue full, dropping event version=%d", @@ -500,25 +1143,18 @@ def push_event( return event def get_snapshot(self) -> dict: - """Return {version, state} for SSE snapshot.""" + """Return {version, state} for SSE snapshot. State is camelCase via to_wire().""" return { "version": self.version, - "state": self.projection.model_dump(), + "state": self.projection.to_wire(), } - def events_since(self, version: int) -> list[VersionedEvent]: - """Return all events with version > given version.""" - return [e for e in self.events if e.version > version] - def subscribe(self) -> asyncio.Queue: - """Create and register a subscriber queue.""" + """Create and register a subscriber queue. Returns the queue.""" q: asyncio.Queue = asyncio.Queue() - self.subscribers.append(q) + self.subscribers.add(q) return q def unsubscribe(self, queue: asyncio.Queue) -> None: """Remove a subscriber queue.""" - try: - self.subscribers.remove(queue) - except ValueError: - pass + self.subscribers.discard(queue) From 73067c0ed79a98665339a2017ba163d33665e214 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 17:51:46 +0700 Subject: [PATCH 254/412] rewrite SSE stream, emit run_started, fix startup event ordering sse_stream always sends fresh snapshot on reconnect (no events_since, no fatal_error). api_start_run emits run_started event. Event renames: active_profile_changed -> default_profile_changed, scout_concurrency_changed -> default_scout_concurrency_changed. Fix: emit installation_created before probe_completed so available flag is set correctly. --- koan/web/app.py | 103 ++++++++++++++++++++++++++---------------------- 1 file changed, 55 insertions(+), 48 deletions(-) diff --git a/koan/web/app.py b/koan/web/app.py index d6402dc..7155285 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -33,14 +33,15 @@ build_questions_answered, build_workflow_decided, build_probe_completed, + build_run_started, build_installation_created, build_installation_modified, build_installation_removed, build_profile_created, build_profile_modified, build_profile_removed, - build_active_profile_changed, - build_scout_concurrency_changed, + build_default_profile_changed, + build_default_scout_concurrency_changed, ) if TYPE_CHECKING: @@ -55,11 +56,6 @@ # without a build step. FRONTEND_DIST = Path(__file__).parent / "static" / "app" -ALL_PHASES = [ - "intake", "brief-generation", "core-flows", "tech-plan", - "ticket-breakdown", "cross-artifact-validation", - "execution", "implementation-validation", -] # -- Helpers ------------------------------------------------------------------ @@ -145,27 +141,18 @@ async def sse_stream(r: Request) -> Response: since = 0 async def event_generator(): - # Stale client: send fatal_error and close (not HTTP error -- EventSource - # cannot read non-200 bodies and would retry with same stale version). - if since > 0 and since > store.version: - yield _sse_event("fatal_error", {"reason": "version_not_available"}) - return - - # Subscribe before snapshot -- no await between subscribe and get_snapshot - # so no events can be missed between the two operations. + # Subscribe before snapshot so no events can slip between the two operations. queue = store.subscribe() try: - if since == 0: + # Version check: send snapshot unless client is exactly current. + # Handles first connect (since=0), reconnect (since<version), and + # server restart (since>version) uniformly — a fresh snapshot is always correct. + if since != store.version: yield _sse_event("snapshot", store.get_snapshot()) - else: - for event in store.events_since(since): - data = {"version": event.version, "agent_id": event.agent_id, **event.payload} - yield _sse_event(event.event_type, data) while True: - event = await queue.get() - data = {"version": event.version, "agent_id": event.agent_id, **event.payload} - yield _sse_event(event.event_type, data) + msg = await queue.get() # plain dict from push_event + yield _sse_event(msg["type"], msg) except asyncio.CancelledError: pass finally: @@ -258,7 +245,7 @@ async def api_start_run(r: Request) -> Response: if not any(pr.available for pr in st.probe_results): return JSONResponse( {"error": "no_runners", - "message": "No available runners. Install and authenticate at least one runner before starting a run."}, + "message": "No available agent installations. Add and configure at least one in Settings."}, status_code=422, ) @@ -310,14 +297,22 @@ async def api_start_run(r: Request) -> Response: st.config.active_profile = profile from ..config import save_koan_config await save_koan_config(st.config) - st.projection_store.push_event("active_profile_changed", build_active_profile_changed(profile)) + st.projection_store.push_event("default_profile_changed", build_default_profile_changed(profile)) # Apply optional overrides scout_concurrency = body.get("scout_concurrency") if isinstance(scout_concurrency, int) and scout_concurrency > 0: st.config.scout_concurrency = scout_concurrency await save_koan_config(st.config) - st.projection_store.push_event("scout_concurrency_changed", build_scout_concurrency_changed(scout_concurrency)) + st.projection_store.push_event("default_scout_concurrency_changed", build_default_scout_concurrency_changed(scout_concurrency)) + + # Emit run_started to create the Run object in the projection + _installations_map = dict(st.run_installations) + _scout_concurrency = st.config.scout_concurrency + st.projection_store.push_event( + "run_started", + build_run_started(profile, _installations_map, _scout_concurrency), + ) # Create epic directory epic_id = f"{int(time.time())}-{uuid.uuid4().hex[:8]}" @@ -565,14 +560,8 @@ async def _refresh_probe_state(st: AppState, broadcast: bool = True) -> None: await save_koan_config(st.config) if broadcast: - runners = [_serialize_probe_result(pr) for pr in st.probe_results] - st.projection_store.push_event("probe_completed", build_probe_completed(runners)) - if st.balanced_profile: - tiers = _serialize_profile(st.balanced_profile, True)["tiers"] - st.projection_store.push_event( - "profile_modified", - build_profile_modified("balanced", True, tiers), - ) + # New installations must exist in the projection BEFORE probe_completed + # sets their `available` flag. for inst in new_insts: st.projection_store.push_event( "installation_created", @@ -583,6 +572,19 @@ async def _refresh_probe_state(st: AppState, broadcast: bool = True) -> None: "installation_modified", build_installation_modified(inst.alias, inst.runner_type, inst.binary, inst.extra_args), ) + # Now set available on all installations (including the ones just created) + _probe_results_dict = { + inst.alias: any(pr.runner_type == inst.runner_type and pr.available + for pr in st.probe_results) + for inst in st.config.agent_installations + } + st.projection_store.push_event("probe_completed", build_probe_completed(_probe_results_dict)) + if st.balanced_profile: + tiers = _serialize_profile(st.balanced_profile, True)["tiers"] + st.projection_store.push_event( + "profile_modified", + build_profile_modified("balanced", True, tiers), + ) def _push_initial_config_events(st: AppState) -> None: @@ -593,9 +595,21 @@ def _push_initial_config_events(st: AppState) -> None: """ store = st.projection_store - # Runners from probe - runners = [_serialize_probe_result(pr) for pr in st.probe_results] - store.push_event("probe_completed", build_probe_completed(runners)) + # Installations FIRST — probe_completed needs them to exist so it can set + # the `available` flag on each one. + for inst in st.config.agent_installations: + store.push_event( + "installation_created", + build_installation_created(inst.alias, inst.runner_type, inst.binary, inst.extra_args), + ) + + # probe_completed: set available flag on each installation (now they exist) + _probe_avail = { + inst.alias: any(pr.runner_type == inst.runner_type and pr.available + for pr in st.probe_results) + for inst in st.config.agent_installations + } + store.push_event("probe_completed", build_probe_completed(_probe_avail)) # Profiles (balanced first, then user-defined) if st.balanced_profile: @@ -605,18 +619,11 @@ def _push_initial_config_events(st: AppState) -> None: sp = _serialize_profile(p, False) store.push_event("profile_created", build_profile_created(p.name, False, sp["tiers"])) - # Installations - for inst in st.config.agent_installations: - store.push_event( - "installation_created", - build_installation_created(inst.alias, inst.runner_type, inst.binary, inst.extra_args), - ) - # Active profile - store.push_event("active_profile_changed", build_active_profile_changed(st.config.active_profile)) + store.push_event("default_profile_changed", build_default_profile_changed(st.config.active_profile)) # Scout concurrency - store.push_event("scout_concurrency_changed", build_scout_concurrency_changed(st.config.scout_concurrency)) + store.push_event("default_scout_concurrency_changed", build_default_scout_concurrency_changed(st.config.scout_concurrency)) async def api_probe(r: Request) -> Response: @@ -759,7 +766,7 @@ async def api_profiles_delete(r: Request) -> Response: await save_koan_config(st.config) st.projection_store.push_event("profile_removed", build_profile_removed(name)) if reset_active: - st.projection_store.push_event("active_profile_changed", build_active_profile_changed("balanced")) + st.projection_store.push_event("default_profile_changed", build_default_profile_changed("balanced")) return JSONResponse({"ok": True}) @@ -980,7 +987,7 @@ async def api_settings_scout_concurrency(r: Request) -> Response: st.config.scout_concurrency = value from ..config import save_koan_config await save_koan_config(st.config) - st.projection_store.push_event("scout_concurrency_changed", build_scout_concurrency_changed(value)) + st.projection_store.push_event("default_scout_concurrency_changed", build_default_scout_concurrency_changed(value)) return JSONResponse({"ok": True}) From 73c0b752b171c41c83aa23c5888b4578cca66466 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 17:51:54 +0700 Subject: [PATCH 255/412] rewrite projection tests for new model (92 fold tests, patch paths, snapshots) --- tests/test_projections.py | 1218 +++++++++++++++++++++++-------------- tests/test_subagent.py | 15 +- tests/test_web_flows.py | 118 ++-- 3 files changed, 838 insertions(+), 513 deletions(-) diff --git a/tests/test_projections.py b/tests/test_projections.py index f184eb7..fb855e2 100644 --- a/tests/test_projections.py +++ b/tests/test_projections.py @@ -1,384 +1,708 @@ # Tests for koan.projections (ProjectionStore, fold) and koan.events (build_artifact_diff). +# New architecture: server-authoritative JSON Patch. fold() is the only business logic. +# Projection has 3 top-level fields: settings, run, notifications. from __future__ import annotations import asyncio -import json import pytest from koan.projections import ( - AgentProjection, + Agent, + ArtifactInfo, + BaseToolEntry, + Conversation, + ConversationFocus, + DecisionFocus, Projection, ProjectionStore, + QuestionFocus, + ReviewFocus, + Run, + RunConfig, + Settings, + StepEntry, + TextEntry, + ThinkingEntry, + ToolBashEntry, + ToolEditEntry, + ToolGenericEntry, + ToolGrepEntry, + ToolLsEntry, + ToolReadEntry, + ToolWriteEntry, VersionedEvent, fold, ) -# -- fold: lifecycle ----------------------------------------------------------- - -class TestFoldLifecycle: - def _event(self, event_type: str, payload: dict, agent_id: str | None = None, version: int = 1) -> VersionedEvent: - return VersionedEvent( - version=version, - event_type=event_type, - timestamp="2026-01-01T00:00:00Z", - agent_id=agent_id, - payload=payload, - ) - - def test_phase_started(self): +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +def _e( + event_type: str, + payload: dict, + agent_id: str | None = None, + version: int = 1, +) -> VersionedEvent: + return VersionedEvent( + version=version, + event_type=event_type, + timestamp="2026-01-01T00:00:00Z", + agent_id=agent_id, + payload=payload, + ) + + +def _proj_with_run(profile: str = "balanced") -> Projection: + """Return a Projection with an active run (post run_started).""" + p = Projection() + return fold(p, _e("run_started", { + "profile": profile, + "installations": {}, + "scout_concurrency": 8, + })) + + +def _proj_with_primary(agent_id: str = "a1", role: str = "intake") -> Projection: + """Return a Projection with an active run and a running primary agent.""" + p = _proj_with_run() + p = fold(p, _e("agent_spawned", { + "agent_id": agent_id, + "role": role, + "label": "", + "model": "opus", + "is_primary": True, + "started_at_ms": 1000, + }, agent_id=agent_id)) + return p + + +# --------------------------------------------------------------------------- +# fold: run lifecycle +# --------------------------------------------------------------------------- + +class TestFoldRunLifecycle: + + def test_run_started_creates_run(self): p = Projection() - e = self._event("phase_started", {"phase": "intake"}) - r = fold(p, e) - assert r.phase == "intake" - assert r.run_started is True - - def test_agent_spawned_primary(self): + assert p.run is None + r = fold(p, _e("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8})) + assert r.run is not None + assert r.run.config.profile == "balanced" + assert r.run.config.scout_concurrency == 8 + + def test_run_started_resets_run_on_new_start(self): + """A second run_started replaces the run entirely.""" + p = _proj_with_run("balanced") + # Simulate a new run + r = fold(p, _e("run_started", {"profile": "fast", "installations": {}, "scout_concurrency": 4})) + assert r.run is not None + assert r.run.config.profile == "fast" + assert r.run.agents == {} + + def test_phase_started_sets_phase(self): + p = _proj_with_run() + r = fold(p, _e("phase_started", {"phase": "intake"})) + assert r.run.phase == "intake" + + def test_phase_started_without_run_is_noop(self): p = Projection() - e = self._event("agent_spawned", {"role": "intake", "model": "opus", "is_primary": True}, agent_id="a1") - r = fold(p, e) - assert r.primary_agent is not None - assert r.primary_agent.agent_id == "a1" - assert r.primary_agent.role == "intake" + r = fold(p, _e("phase_started", {"phase": "intake"})) + assert r.run is None - def test_agent_spawned_scout(self): - p = Projection() - e = self._event("agent_spawned", {"role": "scout", "model": None, "is_primary": False}, agent_id="s1") - r = fold(p, e) - assert "s1" in r.scouts - assert r.primary_agent is None + def test_workflow_completed_sets_completion(self): + p = _proj_with_run() + r = fold(p, _e("workflow_completed", {"success": True, "summary": "done"})) + assert r.run.completion is not None + assert r.run.completion.success is True + assert r.run.completion.summary == "done" - def test_agent_spawn_failed(self): + def test_workflow_completed_without_run_is_noop(self): p = Projection() - e = self._event("agent_spawn_failed", {"role": "intake", "error_code": "binary_not_found", "message": "not found"}) - r = fold(p, e) + r = fold(p, _e("workflow_completed", {"success": True})) + assert r.run is None + + +# --------------------------------------------------------------------------- +# fold: agent lifecycle +# --------------------------------------------------------------------------- + +class TestFoldAgentLifecycle: + + def test_agent_spawned_primary_creates_agent(self): + p = _proj_with_run() + r = fold(p, _e("agent_spawned", { + "agent_id": "a1", "role": "intake", "is_primary": True, + "model": "opus", "started_at_ms": 1000, + }, agent_id="a1")) + assert "a1" in r.run.agents + agent = r.run.agents["a1"] + assert agent.is_primary is True + assert agent.status == "running" + assert agent.role == "intake" + + def test_agent_spawned_sets_conversation_focus(self): + p = _proj_with_run() + r = fold(p, _e("agent_spawned", { + "agent_id": "a1", "role": "intake", "is_primary": True, "started_at_ms": 0, + }, agent_id="a1")) + assert r.run.focus is not None + assert isinstance(r.run.focus, ConversationFocus) + assert r.run.focus.agent_id == "a1" + + def test_agent_spawned_scout_transitions_from_queued(self): + p = _proj_with_run() + # Queue the scout first + p = fold(p, _e("scout_queued", {"scout_id": "s1", "label": "eng", "model": "haiku"})) + assert p.run.agents["s1"].status == "queued" + # Spawn it + r = fold(p, _e("agent_spawned", { + "agent_id": "s1", "role": "scout", "is_primary": False, "started_at_ms": 2000, + }, agent_id="s1")) + assert r.run.agents["s1"].status == "running" + assert r.run.agents["s1"].started_at_ms == 2000 + + def test_scout_queued_adds_agent_with_queued_status(self): + p = _proj_with_run() + r = fold(p, _e("scout_queued", {"scout_id": "s1", "label": "eng", "model": "haiku"})) + assert "s1" in r.run.agents + assert r.run.agents["s1"].status == "queued" + assert r.run.agents["s1"].label == "eng" + + def test_agent_exited_sets_done_status(self): + p = _proj_with_primary("a1") + r = fold(p, _e("agent_exited", {"exit_code": 0}, agent_id="a1")) + assert r.run.agents["a1"].status == "done" + assert r.run.agents["a1"].error is None + + def test_agent_exited_with_error_sets_failed(self): + p = _proj_with_primary("a1") + r = fold(p, _e("agent_exited", {"exit_code": 1, "error": "boom"}, agent_id="a1")) + assert r.run.agents["a1"].status == "failed" + assert r.run.agents["a1"].error == "boom" + # Error notification appended assert len(r.notifications) == 1 - assert r.notifications[0]["type"] == "agent_spawn_failed" - assert r.notifications[0]["error_code"] == "binary_not_found" - - def test_agent_step_advanced(self): - p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake")) - e = self._event("agent_step_advanced", {"step": 2, "step_name": "Scout"}, agent_id="a1") - r = fold(p, e) - assert r.primary_agent.step == 2 - assert r.primary_agent.step_name == "Scout" - - def test_agent_step_advanced_unknown_agent(self): + assert "boom" in r.notifications[0].message + + def test_agent_exited_accumulates_usage_into_conversation(self): + p = _proj_with_primary("a1") + r = fold(p, _e("agent_exited", { + "exit_code": 0, + "usage": {"input_tokens": 10, "output_tokens": 20}, + }, agent_id="a1")) + assert r.run.agents["a1"].conversation.input_tokens == 10 + assert r.run.agents["a1"].conversation.output_tokens == 20 + + def test_agent_exited_unknown_agent_noop(self): + p = _proj_with_run() + r = fold(p, _e("agent_exited", {"exit_code": 0}, agent_id="ghost")) + # No change to agents + assert r.run.agents == p.run.agents + + def test_agent_spawn_failed_appends_notification(self): p = Projection() - e = self._event("agent_step_advanced", {"step": 1, "step_name": "X"}, agent_id="unknown") - r = fold(p, e) - # Unknown agent: agent state unchanged, but step still appended to activity_log - assert r.primary_agent is None - assert len(r.activity_log) == 1 - assert r.activity_log[0]["event_type"] == "agent_step_advanced" - - def test_agent_step_advanced_accumulates_usage(self): - p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake", output_tokens=10)) - e = self._event("agent_step_advanced", {"step": 1, "step_name": "", "usage": {"input_tokens": 5, "output_tokens": 20}}, agent_id="a1") - r = fold(p, e) - assert r.primary_agent.input_tokens == 5 - assert r.primary_agent.output_tokens == 30 - - def test_agent_exited_primary(self): - p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake")) - e = self._event("agent_exited", {"exit_code": 0}, agent_id="a1") - r = fold(p, e) - assert r.primary_agent is None - assert len(r.completed_agents) == 1 - assert r.completed_agents[0].agent_id == "a1" - - def test_agent_exited_accumulates_final_tokens(self): - p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake", output_tokens=50)) - e = self._event("agent_exited", {"exit_code": 0, "usage": {"output_tokens": 25}}, agent_id="a1") - r = fold(p, e) - assert r.completed_agents[0].output_tokens == 75 - assert r.primary_agent is None - - def test_agent_exited_with_error_appends_notification(self): - p = Projection(primary_agent=AgentProjection(agent_id="a1", role="intake")) - e = self._event("agent_exited", {"exit_code": 1, "error": "bootstrap_failure"}, agent_id="a1") - r = fold(p, e) + r = fold(p, _e("agent_spawn_failed", { + "role": "intake", "error_code": "binary_not_found", "message": "not found", + })) assert len(r.notifications) == 1 - assert r.notifications[0]["error"] == "bootstrap_failure" - assert r.notifications[0]["type"] == "agent_exited_error" - - def test_agent_exited_scout(self): - p = Projection(scouts={"s1": AgentProjection(agent_id="s1", role="scout")}) - e = self._event("agent_exited", {"exit_code": 0}, agent_id="s1") - r = fold(p, e) - assert "s1" not in r.scouts - assert len(r.completed_agents) == 1 + assert "not found" in r.notifications[0].message + assert r.notifications[0].level == "error" + + +# --------------------------------------------------------------------------- +# fold: conversation — pending fields and flush semantics +# --------------------------------------------------------------------------- + +class TestFoldConversation: + + def test_thinking_flushes_pending_text_first(self): + p = _proj_with_primary("a1") + # Accumulate some text + p = fold(p, _e("stream_delta", {"delta": "hello"}, agent_id="a1")) + # Now thinking arrives — text should flush to TextEntry + r = fold(p, _e("thinking", {"delta": "hmm"}, agent_id="a1")) + conv = r.run.agents["a1"].conversation + assert len(conv.entries) == 1 + assert isinstance(conv.entries[0], TextEntry) + assert conv.entries[0].text == "hello" + assert conv.pending_text == "" + assert conv.pending_thinking == "hmm" + assert conv.is_thinking is True + + def test_thinking_accumulates(self): + p = _proj_with_primary("a1") + p = fold(p, _e("thinking", {"delta": "The "}, agent_id="a1")) + r = fold(p, _e("thinking", {"delta": "answer"}, agent_id="a1")) + assert r.run.agents["a1"].conversation.pending_thinking == "The answer" + + def test_stream_delta_flushes_pending_thinking_first(self): + p = _proj_with_primary("a1") + p = fold(p, _e("thinking", {"delta": "consider"}, agent_id="a1")) + r = fold(p, _e("stream_delta", {"delta": "result"}, agent_id="a1")) + conv = r.run.agents["a1"].conversation + assert len(conv.entries) == 1 + assert isinstance(conv.entries[0], ThinkingEntry) + assert conv.entries[0].content == "consider" + assert conv.pending_thinking == "" + assert conv.pending_text == "result" + assert conv.is_thinking is False - def test_workflow_completed(self): + def test_stream_delta_accumulates(self): + p = _proj_with_primary("a1") + p = fold(p, _e("stream_delta", {"delta": "hello "}, agent_id="a1")) + r = fold(p, _e("stream_delta", {"delta": "world"}, agent_id="a1")) + assert r.run.agents["a1"].conversation.pending_text == "hello world" + + def test_stream_cleared_flushes_both(self): + p = _proj_with_primary("a1") + p = fold(p, _e("thinking", {"delta": "thoughts"}, agent_id="a1")) + p = fold(p, _e("stream_delta", {"delta": "text"}, agent_id="a1")) + # At this point pending_thinking got flushed when stream_delta arrived + # so pending_thinking = "", pending_text = "text" + r = fold(p, _e("stream_cleared", {}, agent_id="a1")) + conv = r.run.agents["a1"].conversation + # Both pending fields empty + assert conv.pending_thinking == "" + assert conv.pending_text == "" + assert conv.is_thinking is False + + def test_agent_step_advanced_flushes_both_and_appends_step(self): + p = _proj_with_primary("a1") + p = fold(p, _e("thinking", {"delta": "thinking..."}, agent_id="a1")) + # The stream_delta flush makes pending_thinking go to entry + # Let's test from a state with just pending_text + p2 = _proj_with_primary("a1") + p2 = fold(p2, _e("stream_delta", {"delta": "output"}, agent_id="a1")) + r = fold(p2, _e("agent_step_advanced", {"step": 1, "step_name": "Scout"}, agent_id="a1")) + conv = r.run.agents["a1"].conversation + # pending_text flushed to TextEntry, then StepEntry appended + assert len(conv.entries) == 2 + assert isinstance(conv.entries[0], TextEntry) + assert isinstance(conv.entries[1], StepEntry) + assert conv.entries[1].step == 1 + assert conv.entries[1].step_name == "Scout" + assert conv.pending_text == "" + assert conv.is_thinking is False + + def test_agent_step_advanced_step_0_no_entry(self): + """step=0 is bootstrap — no StepEntry appended.""" + p = _proj_with_primary("a1") + r = fold(p, _e("agent_step_advanced", {"step": 0, "step_name": ""}, agent_id="a1")) + assert r.run.agents["a1"].conversation.entries == [] + + def test_agent_step_advanced_updates_step_and_step_name(self): + p = _proj_with_primary("a1") + r = fold(p, _e("agent_step_advanced", {"step": 2, "step_name": "Generate"}, agent_id="a1")) + assert r.run.agents["a1"].step == 2 + assert r.run.agents["a1"].step_name == "Generate" + + def test_agent_step_advanced_accumulates_tokens(self): + p = _proj_with_primary("a1") + r = fold(p, _e("agent_step_advanced", { + "step": 1, "step_name": "", + "usage": {"input_tokens": 100, "output_tokens": 200}, + }, agent_id="a1")) + conv = r.run.agents["a1"].conversation + assert conv.input_tokens == 100 + assert conv.output_tokens == 200 + + def test_agent_step_advanced_unknown_agent_noop(self): + p = _proj_with_run() + r = fold(p, _e("agent_step_advanced", {"step": 1, "step_name": "X"}, agent_id="ghost")) + assert r.run.agents == {} + + +# --------------------------------------------------------------------------- +# fold: conversation — tool entries +# --------------------------------------------------------------------------- + +class TestFoldTools: + + def test_tool_read_appends_entry(self): + p = _proj_with_primary("a1") + r = fold(p, _e("tool_read", {"call_id": "c1", "file": "/foo.py", "lines": "1-10"}, agent_id="a1")) + conv = r.run.agents["a1"].conversation + assert len(conv.entries) == 1 + entry = conv.entries[0] + assert isinstance(entry, ToolReadEntry) + assert entry.file == "/foo.py" + assert entry.lines == "1-10" + assert entry.in_flight is True + assert r.run.agents["a1"].last_tool == "read /foo.py:1-10" + + def test_tool_write_appends_entry(self): + p = _proj_with_primary("a1") + r = fold(p, _e("tool_write", {"call_id": "c1", "file": "/out.py"}, agent_id="a1")) + assert isinstance(r.run.agents["a1"].conversation.entries[0], ToolWriteEntry) + assert r.run.agents["a1"].last_tool == "write /out.py" + + def test_tool_edit_appends_entry(self): + p = _proj_with_primary("a1") + r = fold(p, _e("tool_edit", {"call_id": "c1", "file": "/edit.py"}, agent_id="a1")) + assert isinstance(r.run.agents["a1"].conversation.entries[0], ToolEditEntry) + + def test_tool_bash_appends_entry(self): + p = _proj_with_primary("a1") + r = fold(p, _e("tool_bash", {"call_id": "c1", "command": "ls -la"}, agent_id="a1")) + entry = r.run.agents["a1"].conversation.entries[0] + assert isinstance(entry, ToolBashEntry) + assert entry.command == "ls -la" + + def test_tool_grep_appends_entry(self): + p = _proj_with_primary("a1") + r = fold(p, _e("tool_grep", {"call_id": "c1", "pattern": "def foo"}, agent_id="a1")) + entry = r.run.agents["a1"].conversation.entries[0] + assert isinstance(entry, ToolGrepEntry) + assert entry.pattern == "def foo" + + def test_tool_ls_appends_entry(self): + p = _proj_with_primary("a1") + r = fold(p, _e("tool_ls", {"call_id": "c1", "path": "/src"}, agent_id="a1")) + entry = r.run.agents["a1"].conversation.entries[0] + assert isinstance(entry, ToolLsEntry) + assert entry.path == "/src" + + def test_tool_called_appends_generic_entry(self): + p = _proj_with_primary("a1") + r = fold(p, _e("tool_called", { + "call_id": "c1", "tool": "fetch", "args": {}, "summary": "http://example.com" + }, agent_id="a1")) + entry = r.run.agents["a1"].conversation.entries[0] + assert isinstance(entry, ToolGenericEntry) + assert entry.tool_name == "fetch" + assert entry.in_flight is True + + def test_tool_called_koan_prefix_skipped(self): + p = _proj_with_primary("a1") + r = fold(p, _e("tool_called", {"call_id": "c1", "tool": "koan_complete_step", "args": {}}, agent_id="a1")) + assert r.run.agents["a1"].conversation.entries == [] + + def test_tool_called_mcp_koan_prefix_skipped(self): + p = _proj_with_primary("a1") + r = fold(p, _e("tool_called", {"call_id": "c1", "tool": "mcp__koan__step", "args": {}}, agent_id="a1")) + assert r.run.agents["a1"].conversation.entries == [] + + def test_tool_completed_clears_in_flight(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/f", "lines": ""}, agent_id="a1")) + assert p.run.agents["a1"].conversation.entries[0].in_flight is True + r = fold(p, _e("tool_completed", {"call_id": "c1", "tool": "read"}, agent_id="a1")) + assert r.run.agents["a1"].conversation.entries[0].in_flight is False + + def test_tool_flushes_pending_fields(self): + p = _proj_with_primary("a1") + p = fold(p, _e("stream_delta", {"delta": "output"}, agent_id="a1")) + r = fold(p, _e("tool_read", {"call_id": "c1", "file": "/f", "lines": ""}, agent_id="a1")) + conv = r.run.agents["a1"].conversation + assert len(conv.entries) == 2 + assert isinstance(conv.entries[0], TextEntry) # flushed + assert isinstance(conv.entries[1], ToolReadEntry) + assert conv.pending_text == "" + + def test_tool_events_per_agent_not_primary_only(self): + """Every agent gets its own conversation; scout tool events go to scout.""" + p = _proj_with_run() + p = fold(p, _e("scout_queued", {"scout_id": "s1", "label": "eng", "model": None})) + p = fold(p, _e("agent_spawned", {"agent_id": "s1", "role": "scout", "is_primary": False, "started_at_ms": 0}, agent_id="s1")) + r = fold(p, _e("tool_read", {"call_id": "c1", "file": "/f", "lines": ""}, agent_id="s1")) + assert len(r.run.agents["s1"].conversation.entries) == 1 + assert isinstance(r.run.agents["s1"].conversation.entries[0], ToolReadEntry) + + +# --------------------------------------------------------------------------- +# fold: focus transitions +# --------------------------------------------------------------------------- + +class TestFoldFocus: + + def test_questions_asked_sets_question_focus(self): + p = _proj_with_primary("a1") + r = fold(p, _e("questions_asked", {"token": "t1", "questions": [{"question": "Q?"}]}, agent_id="a1")) + assert isinstance(r.run.focus, QuestionFocus) + assert r.run.focus.agent_id == "a1" + assert r.run.focus.token == "t1" + assert len(r.run.focus.questions) == 1 + + def test_questions_answered_resets_to_conversation_focus(self): + p = _proj_with_primary("a1") + p = fold(p, _e("questions_asked", {"token": "t1", "questions": []}, agent_id="a1")) + r = fold(p, _e("questions_answered", {"token": "t1", "cancelled": False}, agent_id="a1")) + assert isinstance(r.run.focus, ConversationFocus) + assert r.run.focus.agent_id == "a1" + + def test_artifact_review_requested_sets_review_focus(self): + p = _proj_with_primary("a1") + r = fold(p, _e("artifact_review_requested", { + "token": "t2", "path": "/f.md", "description": "d", "content": "c", + }, agent_id="a1")) + assert isinstance(r.run.focus, ReviewFocus) + assert r.run.focus.path == "/f.md" + + def test_artifact_reviewed_resets_to_conversation_focus(self): + p = _proj_with_primary("a1") + p = fold(p, _e("artifact_review_requested", {"token": "t2", "path": "/f.md", "description": "", "content": ""}, agent_id="a1")) + r = fold(p, _e("artifact_reviewed", {"token": "t2", "cancelled": False}, agent_id="a1")) + assert isinstance(r.run.focus, ConversationFocus) + + def test_workflow_decision_requested_sets_decision_focus(self): + p = _proj_with_primary("a1") + r = fold(p, _e("workflow_decision_requested", {"token": "t3", "chat_turns": []}, agent_id="a1")) + assert isinstance(r.run.focus, DecisionFocus) + assert r.run.focus.token == "t3" + + def test_workflow_decided_resets_to_conversation_focus(self): + p = _proj_with_primary("a1") + p = fold(p, _e("workflow_decision_requested", {"token": "t3", "chat_turns": []}, agent_id="a1")) + r = fold(p, _e("workflow_decided", {"token": "t3", "cancelled": False}, agent_id="a1")) + assert isinstance(r.run.focus, ConversationFocus) + + +# --------------------------------------------------------------------------- +# fold: settings +# --------------------------------------------------------------------------- + +class TestFoldSettings: + + def test_installation_created_adds_to_dict(self): p = Projection() - e = self._event("workflow_completed", {"success": True, "summary": "done"}) - r = fold(p, e) - assert r.completion == {"success": True, "summary": "done"} - - -# -- fold: activity ----------------------------------------------------------- - -class TestFoldActivity: - def _event(self, event_type: str, payload: dict, agent_id: str | None = None) -> VersionedEvent: - return VersionedEvent(version=1, event_type=event_type, timestamp="2026-01-01T00:00:00Z", - agent_id=agent_id, payload=payload) - - def test_tool_called_appended(self): + r = fold(p, _e("installation_created", { + "alias": "claude-default", "runner_type": "claude", + "binary": "/fake/bin/claude", "extra_args": [], + })) + assert "claude-default" in r.settings.installations + inst = r.settings.installations["claude-default"] + assert inst.runner_type == "claude" + assert inst.available is False # not yet probed + + def test_probe_completed_sets_available_flag(self): p = Projection() - e = self._event("tool_called", {"call_id": "c1", "tool": "read", "args": {}, "summary": "reading"}, "a1") - r = fold(p, e) - assert len(r.activity_log) == 1 - assert r.activity_log[0]["event_type"] == "tool_called" - assert r.activity_log[0]["tool"] == "read" - - def test_tool_completed_appended(self): + p = fold(p, _e("installation_created", { + "alias": "claude-default", "runner_type": "claude", + "binary": "/fake/bin/claude", "extra_args": [], + })) + r = fold(p, _e("probe_completed", {"results": {"claude-default": True}})) + assert r.settings.installations["claude-default"].available is True + + def test_probe_completed_sets_unavailable(self): p = Projection() - e = self._event("tool_completed", {"call_id": "c1", "tool": "read"}, "a1") - r = fold(p, e) - assert len(r.activity_log) == 1 - assert r.activity_log[0]["event_type"] == "tool_completed" - - def test_thinking_appended(self): + p = fold(p, _e("installation_created", { + "alias": "claude-default", "runner_type": "claude", + "binary": "/fake/bin/claude", "extra_args": [], + })) + r = fold(p, _e("probe_completed", {"results": {"claude-default": False}})) + assert r.settings.installations["claude-default"].available is False + + def test_probe_completed_ignores_unknown_aliases(self): + """probe_completed for an alias not in installations is silently ignored.""" p = Projection() - e = self._event("thinking", {"delta": "hmm"}, "a1") - r = fold(p, e) - assert len(r.activity_log) == 1 - assert r.activity_log[0]["delta"] == "hmm" + r = fold(p, _e("probe_completed", {"results": {"ghost": True}})) + assert r.settings.installations == {} - def test_stream_delta_accumulates(self): - p = Projection(stream_buffer="hello ") - e = self._event("stream_delta", {"delta": "world"}) - r = fold(p, e) - assert r.stream_buffer == "hello world" - - def test_stream_cleared(self): - p = Projection(stream_buffer="some content") - e = self._event("stream_cleared", {}) - r = fold(p, e) - assert r.stream_buffer == "" - - -# -- fold: typed tool events -------------------------------------------------- - -class TestFoldTypedTools: - def _event(self, event_type: str, payload: dict) -> "VersionedEvent": - from koan.projections import VersionedEvent - return VersionedEvent(version=1, event_type=event_type, - timestamp="2026-01-01T00:00:00Z", agent_id="a1", payload=payload) - - def test_tool_read_appended(self): - from koan.projections import Projection, fold - p = Projection() - e = self._event("tool_read", {"call_id": "c1", "tool": "read", "file": "/foo.ts", "lines": ""}) - r = fold(p, e) - assert len(r.activity_log) == 1 - assert r.activity_log[0]["event_type"] == "tool_read" - assert r.activity_log[0]["file"] == "/foo.ts" - - def test_tool_write_appended(self): - from koan.projections import Projection, fold + def test_installation_modified_updates(self): p = Projection() - e = self._event("tool_write", {"call_id": "c1", "tool": "write", "file": "/out.ts"}) - r = fold(p, e) - assert len(r.activity_log) == 1 - assert r.activity_log[0]["event_type"] == "tool_write" - assert r.activity_log[0]["file"] == "/out.ts" - - def test_tool_edit_appended(self): - from koan.projections import Projection, fold + p = fold(p, _e("installation_created", { + "alias": "my-claude", "runner_type": "claude", + "binary": "/old/claude", "extra_args": [], + })) + r = fold(p, _e("installation_modified", { + "alias": "my-claude", "runner_type": "claude", + "binary": "/new/claude", "extra_args": ["--effort", "low"], + })) + assert r.settings.installations["my-claude"].binary == "/new/claude" + assert r.settings.installations["my-claude"].extra_args == ["--effort", "low"] + + def test_installation_modified_preserves_available(self): + """Modifying an installation keeps its probe result.""" p = Projection() - e = self._event("tool_edit", {"call_id": "c1", "tool": "edit", "file": "/edit.ts"}) - r = fold(p, e) - assert len(r.activity_log) == 1 - assert r.activity_log[0]["event_type"] == "tool_edit" + p = fold(p, _e("installation_created", {"alias": "c", "runner_type": "claude", "binary": "/b", "extra_args": []})) + p = fold(p, _e("probe_completed", {"results": {"c": True}})) + r = fold(p, _e("installation_modified", {"alias": "c", "runner_type": "claude", "binary": "/new", "extra_args": []})) + assert r.settings.installations["c"].available is True - def test_tool_bash_appended(self): - from koan.projections import Projection, fold + def test_installation_removed(self): p = Projection() - e = self._event("tool_bash", {"call_id": "c1", "tool": "bash", "command": "ls -la"}) - r = fold(p, e) - assert len(r.activity_log) == 1 - assert r.activity_log[0]["command"] == "ls -la" + p = fold(p, _e("installation_created", {"alias": "c", "runner_type": "claude", "binary": "/b", "extra_args": []})) + r = fold(p, _e("installation_removed", {"alias": "c"})) + assert "c" not in r.settings.installations - def test_tool_grep_appended(self): - from koan.projections import Projection, fold + def test_profile_created(self): p = Projection() - e = self._event("tool_grep", {"call_id": "c1", "tool": "grep", "pattern": "def foo"}) - r = fold(p, e) - assert len(r.activity_log) == 1 - assert r.activity_log[0]["pattern"] == "def foo" + r = fold(p, _e("profile_created", {"name": "fast", "read_only": False, "tiers": {}})) + assert "fast" in r.settings.profiles + assert r.settings.profiles["fast"].read_only is False - def test_tool_ls_appended(self): - from koan.projections import Projection, fold + def test_profile_modified_updates(self): p = Projection() - e = self._event("tool_ls", {"call_id": "c1", "tool": "ls", "path": "/src"}) - r = fold(p, e) - assert len(r.activity_log) == 1 - assert r.activity_log[0]["path"] == "/src" - - -# -- fold: interactions ------------------------------------------------------- - -class TestFoldInteractions: - def _event(self, event_type: str, payload: dict) -> VersionedEvent: - return VersionedEvent(version=1, event_type=event_type, timestamp="2026-01-01T00:00:00Z", - agent_id="a1", payload=payload) + p = fold(p, _e("profile_created", {"name": "fast", "read_only": False, "tiers": {}})) + r = fold(p, _e("profile_modified", {"name": "fast", "read_only": False, "tiers": {"scout": "haiku-default"}})) + assert r.settings.profiles["fast"].tiers["scout"] == "haiku-default" - def test_questions_asked_sets_active(self): + def test_profile_removed(self): p = Projection() - e = self._event("questions_asked", {"token": "t1", "questions": [{"question": "Q1"}]}) - r = fold(p, e) - assert r.active_interaction is not None - assert r.active_interaction["interaction_type"] == "questions_asked" - assert r.active_interaction["token"] == "t1" - - def test_questions_answered_clears(self): - p = Projection(active_interaction={"interaction_type": "questions_asked", "token": "t1"}) - e = self._event("questions_answered", {"token": "t1", "cancelled": False}) - r = fold(p, e) - assert r.active_interaction is None - - def test_artifact_review_request_response_cycle(self): + p = fold(p, _e("profile_created", {"name": "fast", "read_only": False, "tiers": {}})) + r = fold(p, _e("profile_removed", {"name": "fast"})) + assert "fast" not in r.settings.profiles + + def test_default_profile_changed(self): p = Projection() - req = self._event("artifact_review_requested", {"token": "t2", "path": "/tmp/f.md", "description": "d", "content": "c"}) - p2 = fold(p, req) - assert p2.active_interaction["interaction_type"] == "artifact_review_requested" - res = self._event("artifact_reviewed", {"token": "t2", "accepted": True, "cancelled": False}) - p3 = fold(p2, res) - assert p3.active_interaction is None - - def test_workflow_decision_cycle(self): + r = fold(p, _e("default_profile_changed", {"name": "fast"})) + assert r.settings.default_profile == "fast" + + def test_default_scout_concurrency_changed(self): p = Projection() - req = self._event("workflow_decision_requested", {"token": "t3", "chat_turns": []}) - p2 = fold(p, req) - assert p2.active_interaction["interaction_type"] == "workflow_decision_requested" - res = self._event("workflow_decided", {"token": "t3", "cancelled": False}) - p3 = fold(p2, res) - assert p3.active_interaction is None + r = fold(p, _e("default_scout_concurrency_changed", {"value": 16})) + assert r.settings.default_scout_concurrency == 16 - def test_cancelled_resolution_clears(self): - p = Projection(active_interaction={"interaction_type": "questions_asked", "token": "t1"}) - e = self._event("questions_answered", {"token": "t1", "cancelled": True}) - r = fold(p, e) - assert r.active_interaction is None + def test_settings_events_do_not_touch_run(self): + """Settings events must not modify run state.""" + p = _proj_with_run() + r = fold(p, _e("installation_created", {"alias": "c", "runner_type": "claude", "binary": "/b", "extra_args": []})) + assert r.run is not None + assert r.run.config == p.run.config -# -- fold: resources ---------------------------------------------------------- +# --------------------------------------------------------------------------- +# fold: resources (artifacts) +# --------------------------------------------------------------------------- -class TestFoldResources: - def _event(self, event_type: str, payload: dict) -> VersionedEvent: - return VersionedEvent(version=1, event_type=event_type, timestamp="2026-01-01T00:00:00Z", - agent_id=None, payload=payload) +class TestFoldArtifacts: def test_artifact_created(self): - p = Projection() - e = self._event("artifact_created", {"path": "foo.md", "size": 100, "modified_at": 1000}) - r = fold(p, e) - assert "foo.md" in r.artifacts - assert r.artifacts["foo.md"]["size"] == 100 + p = _proj_with_run() + r = fold(p, _e("artifact_created", {"path": "foo.md", "size": 100, "modified_at": 1000})) + assert "foo.md" in r.run.artifacts + assert r.run.artifacts["foo.md"].size == 100 def test_artifact_modified(self): - p = Projection(artifacts={"foo.md": {"path": "foo.md", "size": 50, "modified_at": 500}}) - e = self._event("artifact_modified", {"path": "foo.md", "size": 200, "modified_at": 2000}) - r = fold(p, e) - assert r.artifacts["foo.md"]["size"] == 200 + p = _proj_with_run() + p = fold(p, _e("artifact_created", {"path": "foo.md", "size": 50, "modified_at": 500})) + r = fold(p, _e("artifact_modified", {"path": "foo.md", "size": 200, "modified_at": 2000})) + assert r.run.artifacts["foo.md"].size == 200 def test_artifact_removed(self): - p = Projection(artifacts={"foo.md": {"path": "foo.md", "size": 100, "modified_at": 1000}}) - e = self._event("artifact_removed", {"path": "foo.md"}) - r = fold(p, e) - assert "foo.md" not in r.artifacts + p = _proj_with_run() + p = fold(p, _e("artifact_created", {"path": "foo.md", "size": 100, "modified_at": 1000})) + r = fold(p, _e("artifact_removed", {"path": "foo.md"})) + assert "foo.md" not in r.run.artifacts + + def test_artifact_events_without_run_noop(self): + p = Projection() + r = fold(p, _e("artifact_created", {"path": "foo.md", "size": 100, "modified_at": 1000})) + assert r.run is None + + def test_run_events_do_not_touch_settings(self): + """Artifact events must not modify settings.""" + p = _proj_with_run() + p = fold(p, _e("installation_created", {"alias": "c", "runner_type": "claude", "binary": "/b", "extra_args": []})) + r = fold(p, _e("artifact_created", {"path": "foo.md", "size": 100, "modified_at": 1000})) + assert r.settings.installations == p.settings.installations -# -- fold: safety ----------------------------------------------------------- +# --------------------------------------------------------------------------- +# fold: safety +# --------------------------------------------------------------------------- class TestFoldSafety: - def _event(self, event_type: str, payload: dict) -> VersionedEvent: - return VersionedEvent(version=1, event_type=event_type, timestamp="2026-01-01T00:00:00Z", - agent_id=None, payload=payload) - - def test_unknown_event_type_unchanged(self): - p = Projection(phase="intake") - e = self._event("completely_unknown_type", {"data": 42}) - r = fold(p, e) - assert r == p - def test_unknown_agent_id_step_appended(self): - p = Projection() # no agents registered - e = VersionedEvent(version=1, event_type="agent_step_advanced", timestamp="2026-01-01T00:00:00Z", - agent_id="nonexistent", payload={"step": 1, "step_name": "X"}) - r = fold(p, e) - # Agent state unchanged, but step marker still in activity_log - assert r.primary_agent is None - assert len(r.activity_log) == 1 - - def test_phase_started_empty_payload_returns_empty_phase(self): - # Verifies that phase_started with {} payload returns phase="" (not an error). - # This is valid input -- fold does not throw on missing-but-defaulted fields. - p = Projection(phase="intake") - e = VersionedEvent(version=1, event_type="phase_started", timestamp="2026-01-01T00:00:00Z", - agent_id=None, payload={}) - r = fold(p, e) - assert r.phase == "" - assert r.run_started is True + def test_unknown_event_type_returns_unchanged(self): + p = _proj_with_run() + r = fold(p, _e("completely_unknown", {"data": 42})) + assert r == p def test_fold_is_pure(self): - p = Projection(phase="intake") - e = self._event("phase_started", {"phase": "brief-generation"}) + p = _proj_with_run() + e = _e("phase_started", {"phase": "brief-generation"}) r1 = fold(p, e) r2 = fold(p, e) assert r1 == r2 - # Input projection unchanged - assert p.phase == "intake" + assert p.run.phase == "" # original unchanged + + def test_fold_exception_returns_unchanged(self, monkeypatch): + """If fold raises internally, projection stays unchanged.""" + import koan.projections as proj_mod + + call_count = [0] + original_fold = proj_mod.fold + + def raise_once(projection, event): + call_count[0] += 1 + if call_count[0] == 1: + raise RuntimeError("simulated fold failure") + return original_fold(projection, event) + + # Test the store's exception handling + store = ProjectionStore() + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + assert store.projection.run is not None + monkeypatch.setattr(proj_mod, "fold", raise_once) + store2 = proj_mod.ProjectionStore() + prev = store2.projection + store2.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + # fold raised — projection unchanged + assert store2.projection == prev -# -- ProjectionStore ---------------------------------------------------------- + +# --------------------------------------------------------------------------- +# ProjectionStore +# --------------------------------------------------------------------------- class TestProjectionStore: + def test_push_increments_version(self): store = ProjectionStore() assert store.version == 0 - store.push_event("phase_started", {"phase": "intake"}) + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) assert store.version == 1 - store.push_event("phase_started", {"phase": "brief-generation"}) - assert store.version == 2 - def test_fold_applied_to_projection(self): + def test_fold_applied(self): + store = ProjectionStore() + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + assert store.projection.run is not None + + def test_get_snapshot_camelcase(self): + """get_snapshot() must return camelCase keys (via to_wire).""" store = ProjectionStore() - store.push_event("phase_started", {"phase": "intake"}) - assert store.projection.phase == "intake" + snap = store.get_snapshot() + state = snap["state"] + # Top-level fields are camelCase + assert "settings" in state + assert "run" in state + assert "notifications" in state + # Nested camelCase + settings = state["settings"] + assert "defaultProfile" in settings # not default_profile + assert "defaultScoutConcurrency" in settings # not default_scout_concurrency def test_get_snapshot_includes_version(self): store = ProjectionStore() - store.push_event("phase_started", {"phase": "intake"}) + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) snap = store.get_snapshot() assert snap["version"] == 1 - assert snap["state"]["phase"] == "intake" - def test_events_since(self): + def test_subscriber_receives_dict_not_event(self): + """Subscribers get plain dicts (SSE-ready), not VersionedEvent objects.""" store = ProjectionStore() - store.push_event("phase_started", {"phase": "intake"}) - store.push_event("phase_started", {"phase": "brief-generation"}) - store.push_event("phase_started", {"phase": "core-flows"}) - events = store.events_since(1) - assert len(events) == 2 - assert events[0].version == 2 - assert events[1].version == 3 - - def test_events_since_zero_returns_all(self): - store = ProjectionStore() - store.push_event("phase_started", {"phase": "intake"}) - assert len(store.events_since(0)) == 1 + q = store.subscribe() + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + msg = q.get_nowait() + assert isinstance(msg, dict) + assert msg["type"] == "patch" + assert "version" in msg + assert "patch" in msg @pytest.mark.anyio - async def test_broadcast_to_subscribers(self): + async def test_subscriber_receives_patch(self): store = ProjectionStore() q = store.subscribe() - store.push_event("phase_started", {"phase": "intake"}) - event = await asyncio.wait_for(q.get(), timeout=1.0) - assert event.event_type == "phase_started" + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + msg = await asyncio.wait_for(q.get(), timeout=1.0) + assert msg["type"] == "patch" + assert msg["version"] == 1 + assert isinstance(msg["patch"], list) store.unsubscribe(q) @pytest.mark.anyio @@ -386,49 +710,150 @@ async def test_unsubscribe_stops_delivery(self): store = ProjectionStore() q = store.subscribe() store.unsubscribe(q) - store.push_event("phase_started", {"phase": "intake"}) + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) assert q.empty() - def test_subscriber_snapshot_avoids_mutation_during_broadcast(self): - """push_event snapshots subscribers before iterating.""" + def test_no_patch_broadcast_when_no_state_change(self): + """koan_ tools produce no state change; no patch broadcast.""" store = ProjectionStore() - q1 = store.subscribe() - # Should not raise even if we unsubscribe q1 from inside a subscriber - store.push_event("phase_started", {"phase": "intake"}) - store.unsubscribe(q1) - # No exception = pass - - def test_fold_exception_leaves_log_intact_projection_unchanged(self, monkeypatch): - """ProjectionStore: if fold() raises, event stays in log but projection is unchanged.""" - import koan.projections as proj_mod - original_fold = proj_mod.fold + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + store.push_event("agent_spawned", { + "agent_id": "a1", "role": "intake", "is_primary": True, + "started_at_ms": 0, "label": "", "model": None, + }, agent_id="a1") + q = store.subscribe() + # koan MCP tool is filtered — no state change → no patch broadcast + store.push_event("tool_called", { + "call_id": "c1", "tool": "koan_complete_step", "args": {}, + }, agent_id="a1") + assert q.empty() - call_count = [0] - def raising_fold(projection, event): - call_count[0] += 1 - if call_count[0] == 1: - raise RuntimeError("simulated fold failure") - return original_fold(projection, event) +# --------------------------------------------------------------------------- +# JSON Patch paths — verify camelCase patch operations +# --------------------------------------------------------------------------- - monkeypatch.setattr(proj_mod, "fold", raising_fold) +class TestJSONPatchPaths: - store = proj_mod.ProjectionStore() - # First push: fold raises, projection stays at default, but event IS in log - store.push_event("phase_started", {"phase": "intake"}) - assert store.version == 1 - assert store.events[0].event_type == "phase_started" - assert store.projection.phase == "" # unchanged -- fold raised + def test_patch_has_camelcase_run_path(self): + """run_started must produce a patch with /run path.""" + store = ProjectionStore() + q = store.subscribe() + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + msg = q.get_nowait() + ops = msg["patch"] + paths = [op["path"] for op in ops] + assert any("/run" in p for p in paths) + + def test_patch_has_camelcase_settings_path(self): + store = ProjectionStore() + q = store.subscribe() + store.push_event("installation_created", { + "alias": "claude-default", "runner_type": "claude", + "binary": "/fake/bin/claude", "extra_args": [], + }) + msg = q.get_nowait() + ops = msg["patch"] + paths = [op["path"] for op in ops] + # Should contain /settings/installations/claude-default + assert any("/settings/installations/claude-default" in p for p in paths) + + def test_patch_has_camelcase_agent_fields(self): + """Agent fields use camelCase in patch paths: lastTool, stepName, etc.""" + store = ProjectionStore() + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + store.push_event("agent_spawned", { + "agent_id": "a1", "role": "intake", "is_primary": True, + "started_at_ms": 0, "label": "", "model": None, + }, agent_id="a1") + store.push_event("agent_step_advanced", {"step": 1, "step_name": "Scout"}, agent_id="a1") + q = store.subscribe() + store.push_event("tool_read", {"call_id": "c1", "file": "/f.py", "lines": ""}, agent_id="a1") + msg = q.get_nowait() + ops = msg["patch"] + # Check some paths contain camelCase + all_paths = " ".join(op["path"] for op in ops) + # lastTool should be camelCase + assert "lastTool" in all_paths or "conversation" in all_paths + + def test_patch_pending_thinking_camelcase_path(self): + store = ProjectionStore() + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + store.push_event("agent_spawned", { + "agent_id": "a1", "role": "intake", "is_primary": True, + "started_at_ms": 0, "label": "", "model": None, + }, agent_id="a1") + q = store.subscribe() + store.push_event("thinking", {"delta": "hmm"}, agent_id="a1") + msg = q.get_nowait() + ops = msg["patch"] + all_paths = " ".join(op["path"] for op in ops) + # pendingThinking must be camelCase + assert "pendingThinking" in all_paths + + def test_patch_default_profile_camelcase(self): + store = ProjectionStore() + q = store.subscribe() + store.push_event("default_profile_changed", {"name": "fast"}) + msg = q.get_nowait() + ops = msg["patch"] + all_paths = " ".join(op["path"] for op in ops) + assert "defaultProfile" in all_paths + + +# --------------------------------------------------------------------------- +# Snapshot round-trip +# --------------------------------------------------------------------------- - # Second push: fold succeeds, projection advances - store.push_event("phase_started", {"phase": "brief-generation"}) - assert store.version == 2 - assert store.projection.phase == "brief-generation" +class TestSnapshotRoundTrip: + def test_snapshot_state_is_camelcase(self): + store = ProjectionStore() + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + state = store.get_snapshot()["state"] + run = state["run"] + assert "config" in run + assert "scoutConcurrency" in run["config"] # not scout_concurrency + assert "agents" in run + assert "isPrimary" not in run # no agents yet + + def test_snapshot_agent_camelcase(self): + store = ProjectionStore() + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + store.push_event("agent_spawned", { + "agent_id": "a1", "role": "intake", "is_primary": True, + "started_at_ms": 1000, "label": "", "model": "opus", + }, agent_id="a1") + state = store.get_snapshot()["state"] + agent = state["run"]["agents"]["a1"] + assert "isPrimary" in agent # not is_primary + assert "startedAtMs" in agent # not started_at_ms + assert "stepName" in agent # not step_name + assert "lastTool" in agent # not last_tool + assert "conversation" in agent + conv = agent["conversation"] + assert "pendingThinking" in conv # not pending_thinking + assert "pendingText" in conv # not pending_text + assert "isThinking" in conv # not is_thinking + + def test_snapshot_settings_camelcase(self): + store = ProjectionStore() + store.push_event("installation_created", { + "alias": "claude-default", "runner_type": "claude", + "binary": "/fake/bin/claude", "extra_args": [], + }) + state = store.get_snapshot()["state"] + inst = state["settings"]["installations"]["claude-default"] + assert "runnerType" in inst # not runner_type + assert "extraArgs" in inst # not extra_args -# -- build_artifact_diff ------------------------------------------------------ + +# --------------------------------------------------------------------------- +# build_artifact_diff (unchanged — regression guard) +# --------------------------------------------------------------------------- class TestBuildArtifactDiff: + def test_created(self): from koan.events import build_artifact_diff old = {} @@ -437,7 +862,7 @@ def test_created(self): assert len(events) == 1 assert events[0][0] == "artifact_created" assert events[0][1]["path"] == "foo.md" - assert events[0][1]["modified_at"] == 1000 # ms + assert events[0][1]["modified_at"] == 1000 def test_removed(self): from koan.events import build_artifact_diff @@ -446,7 +871,6 @@ def test_removed(self): events = build_artifact_diff(old, new) assert len(events) == 1 assert events[0][0] == "artifact_removed" - assert events[0][1]["path"] == "foo.md" def test_modified_by_size(self): from koan.events import build_artifact_diff @@ -456,20 +880,11 @@ def test_modified_by_size(self): assert len(events) == 1 assert events[0][0] == "artifact_modified" - def test_modified_by_mtime(self): - from koan.events import build_artifact_diff - old = {"foo.md": {"path": "foo.md", "size": 100, "modified_at": 1000}} - new = [{"path": "foo.md", "size": 100, "modified_at": 2.0}] - events = build_artifact_diff(old, new) - assert len(events) == 1 - assert events[0][0] == "artifact_modified" - - def test_unchanged_produces_no_events(self): + def test_unchanged_no_events(self): from koan.events import build_artifact_diff old = {"foo.md": {"path": "foo.md", "size": 100, "modified_at": 1000}} new = [{"path": "foo.md", "size": 100, "modified_at": 1.0}] - events = build_artifact_diff(old, new) - assert events == [] + assert build_artifact_diff(old, new) == [] def test_mixed_diff(self): from koan.events import build_artifact_diff @@ -478,9 +893,8 @@ def test_mixed_diff(self): "b.md": {"path": "b.md", "size": 20, "modified_at": 2000}, } new = [ - {"path": "a.md", "size": 15, "modified_at": 1.0}, # modified - {"path": "c.md", "size": 30, "modified_at": 3.0}, # created - # b.md removed + {"path": "a.md", "size": 15, "modified_at": 1.0}, + {"path": "c.md", "size": 30, "modified_at": 3.0}, ] events = build_artifact_diff(old, new) types = [e[0] for e in events] @@ -489,9 +903,12 @@ def test_mixed_diff(self): assert "artifact_removed" in types -# -- Tool name normalization (runner integration) ---------------------------- +# --------------------------------------------------------------------------- +# Tool name normalization (runner integration — unchanged) +# --------------------------------------------------------------------------- class TestToolNameNormalization: + def test_claude_normalizes_Read(self): import json from koan.runners.claude import ClaudeRunner @@ -560,112 +977,3 @@ def test_gemini_filters_koan_mcp_tool(self): line = json.dumps({"type": "tool_use", "name": "koan_complete_step", "input": {}}) evts = runner.parse_stream_event(line) assert evts == [] - - -# -- agent_spawned ordering --------------------------------------------------- - -class TestAgentSpawnedOrdering: - """agent_spawned must only be emitted after build_command succeeds. - If build_command raises, the projection must not have a dangling primary_agent. - """ - def test_spawn_failed_without_prior_spawned_leaves_no_primary(self): - """agent_spawn_failed without prior agent_spawned: projection stays clean.""" - store = ProjectionStore() - store.push_event("agent_spawn_failed", { - "role": "intake", "error_code": "binary_not_found", "message": "not found" - }) - assert store.projection.primary_agent is None - assert len(store.projection.notifications) == 1 - - def test_spawn_failed_after_spawned_leaves_dangling_primary(self): - """Demonstrates the bug that is now fixed: agent_spawned must be emitted - AFTER build_command succeeds, not before. This test documents the broken - sequence to catch regressions -- if agent_spawned fires before the process - starts and then spawn_failed fires, primary_agent is left set.""" - store = ProjectionStore() - # This sequence should NOT happen in production code after the fix - store.push_event( - "agent_spawned", - {"agent_id": "a1", "role": "intake", "model": None, "is_primary": True, "started_at_ms": 0}, - agent_id="a1", - ) - store.push_event("agent_spawn_failed", {"role": "intake", "error_code": "err", "message": "m"}) - # primary_agent is dangling -- this is why agent_spawned must come AFTER build_command - assert store.projection.primary_agent is not None # known bad state - # In production, this can't happen: subagent.py now emits agent_spawned only - # after build_command succeeds (just before create_subprocess_exec). - - -# -- fold: configuration events ----------------------------------------------- - -class TestConfigEvents: - def _e(self, event_type: str, payload: dict) -> VersionedEvent: - return VersionedEvent(version=1, event_type=event_type, timestamp="t", payload=payload) - - def test_probe_completed_sets_runners(self): - p = Projection() - runners = [{"runner_type": "claude", "available": True}] - p2 = fold(p, self._e("probe_completed", {"runners": runners})) - assert p2.config_runners == runners - - def test_installation_created_appends(self): - p = Projection() - inst = {"alias": "claude-default", "runner_type": "claude", "binary": "/fake/bin/claude", "extra_args": []} - p2 = fold(p, self._e("installation_created", inst)) - assert len(p2.config_installations) == 1 - assert p2.config_installations[0]["alias"] == "claude-default" - - def test_installation_modified_replaces(self): - inst = {"alias": "my-claude", "runner_type": "claude", "binary": "/old/claude", "extra_args": []} - p = Projection(config_installations=[inst]) - updated = {"alias": "my-claude", "runner_type": "claude", "binary": "/new/claude", "extra_args": []} - p2 = fold(p, self._e("installation_modified", updated)) - assert len(p2.config_installations) == 1 - assert p2.config_installations[0]["binary"] == "/new/claude" - - def test_installation_removed(self): - inst = {"alias": "my-claude", "runner_type": "claude", "binary": "/fake/bin/claude", "extra_args": []} - p = Projection(config_installations=[inst]) - p2 = fold(p, self._e("installation_removed", {"alias": "my-claude"})) - assert p2.config_installations == [] - - def test_profile_created_appends(self): - p = Projection() - profile = {"name": "fast", "read_only": False, "tiers": {}} - p2 = fold(p, self._e("profile_created", profile)) - assert len(p2.config_profiles) == 1 - assert p2.config_profiles[0]["name"] == "fast" - - def test_profile_modified_replaces(self): - profile = {"name": "fast", "read_only": False, "tiers": {"strong": {"runner_type": "claude"}}} - p = Projection(config_profiles=[profile]) - updated = {"name": "fast", "read_only": False, "tiers": {"strong": {"runner_type": "codex"}}} - p2 = fold(p, self._e("profile_modified", updated)) - assert len(p2.config_profiles) == 1 - assert p2.config_profiles[0]["tiers"]["strong"]["runner_type"] == "codex" - - def test_profile_modified_appends_when_not_found(self): - p = Projection() - balanced = {"name": "balanced", "read_only": True, "tiers": {}} - p2 = fold(p, self._e("profile_modified", balanced)) - assert len(p2.config_profiles) == 1 - assert p2.config_profiles[0]["name"] == "balanced" - - def test_profile_removed(self): - p = Projection(config_profiles=[ - {"name": "fast", "read_only": False, "tiers": {}}, - {"name": "slow", "read_only": False, "tiers": {}}, - ]) - p2 = fold(p, self._e("profile_removed", {"name": "fast"})) - assert len(p2.config_profiles) == 1 - assert p2.config_profiles[0]["name"] == "slow" - - def test_active_profile_changed(self): - p = Projection() - p2 = fold(p, self._e("active_profile_changed", {"name": "fast"})) - assert p2.config_active_profile == "fast" - - def test_scout_concurrency_changed(self): - p = Projection() - p2 = fold(p, self._e("scout_concurrency_changed", {"value": 16})) - assert p2.config_scout_concurrency == 16 diff --git a/tests/test_subagent.py b/tests/test_subagent.py index b85700f..d690d65 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -573,14 +573,12 @@ async def test_sse_notification_includes_diagnostic_fields(self, tmp_path): await spawn_subagent(task, app_state, runner=FakeRunner()) # Bootstrap failure is emitted as agent_exited with error="bootstrap_failure" - # and the fold populates projection.notifications. + # and the fold populates projection.notifications as Notification objects. notifs = app_state.projection_store.projection.notifications - boot_notifs = [n for n in notifs if n.get("error") == "bootstrap_failure"] + boot_notifs = [n for n in notifs if "bootstrap_failure" in n.message] assert len(boot_notifs) >= 1 notif = boot_notifs[0] - assert notif["type"] == "agent_exited_error" - assert "agent_id" in notif - assert "exit_code" in notif + assert notif.level == "error" def test_fold_populates_diagnostic_field(self): """fold() sets diagnostic dict on runner_diagnostic events.""" @@ -647,11 +645,12 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): assert exit_code == 1 - # Verify agent_spawn_failed event in projection notifications + # Verify agent_spawn_failed event in projection notifications (new model: Notification objects) notifs = app_state.projection_store.projection.notifications - spawn_fails = [n for n in notifs if n.get("type") == "agent_spawn_failed"] + spawn_fails = [n for n in notifs if n.level == "error"] assert len(spawn_fails) >= 1 - assert spawn_fails[0]["error_code"] == "binary_not_found" + # Message should mention the binary_not_found error + assert any("not found" in n.message.lower() or "binary" in n.message.lower() for n in spawn_fails) # Verify events.jsonl contains a runner_diagnostic events_path = Path(subagent_dir) / "events.jsonl" diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index 5b6d061..7681b3f 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -413,26 +413,26 @@ def test_agents_detect_missing_param(client, app_state): # -- SSE replay --------------------------------------------------------------- def test_sse_replay(app_state): - """Test that SSE stream sends a snapshot on ?since=0 and replays on ?since=N.""" + """SSE stream sends a snapshot and the protocol uses push_event / get_snapshot.""" from koan.web.app import _sse_event - # Push a phase event via projection store + # Prime with a run_started so phase_started has a run to update + app_state.projection_store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) app_state.projection_store.push_event("phase_started", {"phase": "intake"}) - # Verify projection holds the phase - assert app_state.projection_store.projection.phase == "intake" - assert app_state.projection_store.version == 1 + # Verify projection holds the phase in the new nested location + assert app_state.projection_store.projection.run is not None + assert app_state.projection_store.projection.run.phase == "intake" + assert app_state.projection_store.version == 2 # Verify the SSE event formatter produces correct output - event_str = _sse_event("phase_started", {"phase": "intake"}) - assert "event: phase_started" in event_str + event_str = _sse_event("snapshot", app_state.projection_store.get_snapshot()) + assert "event: snapshot" in event_str assert '"intake"' in event_str - # Verify events_since works for replay - events = app_state.projection_store.events_since(0) - assert len(events) == 1 - assert events[0].event_type == "phase_started" - assert events[0].payload["phase"] == "intake" + # Verify audit log retains events + assert len(app_state.projection_store.events) == 2 + assert app_state.projection_store.events[1].event_type == "phase_started" # -- Live page redirect (now SPA fallback) ------------------------------------ @@ -464,18 +464,26 @@ def test_workflow_interaction_sse_payload_shape(app_state): "recommended": True, }], }] + + # Setup: need a run with a running primary agent before focus can be set + app_state.projection_store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + app_state.projection_store.push_event("agent_spawned", { + "agent_id": "agent-1", "role": "intake", "is_primary": True, "started_at_ms": 0, + }, agent_id="agent-1") app_state.projection_store.push_event( "workflow_decision_requested", build_workflow_decision_requested(token, chat_turns), agent_id="agent-1", ) - # Verify projection holds the active interaction - active = app_state.projection_store.projection.active_interaction - assert active is not None - assert active["interaction_type"] == "workflow_decision_requested" - assert active["token"] == "tok" - turns = active["chat_turns"] + # Verify projection holds focus as DecisionFocus (new model) + from koan.projections import DecisionFocus + proj = app_state.projection_store.projection + assert proj.run is not None + focus = proj.run.focus + assert isinstance(focus, DecisionFocus) + assert focus.token == "tok" + turns = focus.chat_turns assert turns[0]["recommended_phases"][0]["phase"] == "tech-plan" @@ -621,15 +629,19 @@ def test_probe_no_refresh_skips_restate(self, client, app_state): @pytest.mark.anyio def test_sse_snapshot_contains_projection_state(app_state): - """Snapshot SSE event contains the full projection as {version, state}.""" + """Snapshot SSE event contains the full camelCase projection as {version, state}.""" from koan.web.app import _sse_event + app_state.projection_store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) app_state.projection_store.push_event("phase_started", {"phase": "intake"}) snapshot = app_state.projection_store.get_snapshot() - assert snapshot["version"] == 1 - assert snapshot["state"]["phase"] == "intake" - assert snapshot["state"]["run_started"] is True + assert snapshot["version"] == 2 + # New model: phase lives inside run + assert snapshot["state"]["run"]["phase"] == "intake" + # New model: top-level fields are settings, run, notifications + assert "settings" in snapshot["state"] + assert "notifications" in snapshot["state"] # Verify SSE wire format event_str = _sse_event("snapshot", snapshot) @@ -637,41 +649,47 @@ def test_sse_snapshot_contains_projection_state(app_state): assert '"intake"' in event_str -def test_sse_replay_events_since_n(app_state): - """events_since(N) returns events with version > N for replay.""" +def test_sse_audit_log_retains_events(app_state): + """Audit log retains all events in order; reconnecting clients get a fresh snapshot.""" + app_state.projection_store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) app_state.projection_store.push_event("phase_started", {"phase": "intake"}) app_state.projection_store.push_event("phase_started", {"phase": "brief-generation"}) - # version is now 2 + # version is now 3 + + assert len(app_state.projection_store.events) == 3 + assert app_state.projection_store.version == 3 - # Client at version 1 should get only version 2 - events = app_state.projection_store.events_since(1) - assert len(events) == 1 - assert events[0].version == 2 - assert events[0].event_type == "phase_started" - assert events[0].payload["phase"] == "brief-generation" + # Last event is in the log + last = app_state.projection_store.events[-1] + assert last.event_type == "phase_started" + assert last.payload["phase"] == "brief-generation" - # Client at version 0 gets both - all_events = app_state.projection_store.events_since(0) - assert len(all_events) == 2 + # Projection reflects latest state + assert app_state.projection_store.projection.run.phase == "brief-generation" - # Client at version 2 gets nothing (live-tail only) - none = app_state.projection_store.events_since(2) - assert len(none) == 0 + # Snapshot for reconnect reflects full current state + snap = app_state.projection_store.get_snapshot() + assert snap["version"] == 3 + assert snap["state"]["run"]["phase"] == "brief-generation" -def test_sse_fatal_error_stale_version(app_state): - """?since=N where N > server version triggers fatal_error condition.""" - # server version is 0, client claims version 99 +def test_sse_always_snapshot_on_version_mismatch(app_state): + """Any since != server.version triggers a fresh snapshot (no fatal_error).""" store = app_state.projection_store assert store.version == 0 - # The sse_stream handler checks: if since > 0 and since > store.version - # When true, it yields a fatal_error event and returns. - from koan.web.app import _sse_event - fatal_event = _sse_event("fatal_error", {"reason": "version_not_available"}) - assert "event: fatal_error" in fatal_event - assert "version_not_available" in fatal_event - - # Verify the condition: since=99 > version=0 and since > 0 - assert 99 > store.version - assert 99 > 0 + # Any client version (stale or ahead) gets a snapshot. No fatal_error. + # The server simply sends its current state. + snap = store.get_snapshot() + assert snap["version"] == 0 + assert snap["state"]["run"] is None + + # Advance server + store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) + assert store.version == 1 + + # Client at since=99 (> server) still gets a valid snapshot + # (sse_stream sends snapshot when since != store.version) + snap2 = store.get_snapshot() + assert snap2["version"] == 1 + assert snap2["state"]["run"] is not None From 59d7a8a7408f689dae4b2379f06d4edd1045cf8b Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 17:52:02 +0700 Subject: [PATCH 256/412] rewrite frontend store and SSE as dumb JSON Patch renderer Store types match camelCase wire format exactly. connect.ts: 2 event listeners (snapshot, patch) via fast-json-patch. All fold logic, buffer management, agent filtering, and field renaming removed. --- frontend/src/api/client.ts | 33 +- frontend/src/sse/connect.ts | 79 +-- frontend/src/store/index.ts | 1095 ++++--------------------------- frontend/src/store/selectors.ts | 36 +- frontend/src/utils.ts | 9 +- 5 files changed, 163 insertions(+), 1089 deletions(-) diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index f5c7ec4..381cf9b 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -1,5 +1,3 @@ -import { Installation } from '../store/index' - // -- Helpers ----------------------------------------------------------------- async function post<T>(url: string, body: unknown): Promise<T> { @@ -55,25 +53,6 @@ export async function startRun( return post('/api/start-run', body) } -// -- Start-run preflight ----------------------------------------------------- - -export interface PreflightInstallation { - alias: string - binary: string - binary_valid: boolean - extra_args: string[] -} - -export interface StartRunPreflight { - profile: string - required_runner_types: string[] - installations: Record<string, PreflightInstallation[]> -} - -export async function getStartRunPreflight(profile: string): Promise<StartRunPreflight> { - return get(`/api/start-run/preflight?profile=${encodeURIComponent(profile)}`) -} - // -- Interactions ------------------------------------------------------------ export async function submitAnswer(answers: unknown[], token: string) { @@ -121,6 +100,12 @@ export interface RunnerInfo { models: ModelInfo[] } +export async function getProbeInfo(): Promise<{ runners: RunnerInfo[] }> { + return get('/api/probe') +} + +// -- Profiles ---------------------------------------------------------------- + export async function createProfile( name: string, tiers: Record<string, { runner_type: string; model: string; thinking: string }>, @@ -141,12 +126,6 @@ export async function deleteProfile(name: string) { // -- Agent installations ----------------------------------------------------- -export async function getAgents(): Promise<{ - installations: Installation[] -}> { - return get('/api/agents') -} - export async function createAgent(params: { alias: string runner_type: string diff --git a/frontend/src/sse/connect.ts b/frontend/src/sse/connect.ts index 168f353..d53428b 100644 --- a/frontend/src/sse/connect.ts +++ b/frontend/src/sse/connect.ts @@ -1,69 +1,46 @@ +import { applyPatch } from 'fast-json-patch' import { KoanStore } from '../store/index' -// connectSSE opens an EventSource using version-negotiated catch-up: -// ?since=0 → server sends a snapshot event, then live events -// ?since=N → server replays events N+1..M, then live events +// Module-level projection dict for patch application. +// fast-json-patch operates on plain JS objects. Patches mutate this object, +// then we spread the result into the Zustand store. +let storeState: Record<string, unknown> = {} + +// connectSSE opens an EventSource using always-snapshot catch-up: +// ?since=0 → server always sends a snapshot event, then live patches +// ?since=N → if N !== server.version, still sends snapshot; then live patches // // Returns the EventSource so the caller can close it on unmount or reconnect. -// Does NOT schedule its own reconnect -- App.tsx owns that lifecycle. +// Does NOT schedule its own reconnect — App.tsx owns that lifecycle. export function connectSSE(store: KoanStore): EventSource { const lastVersion = store.getState().lastVersion const es = new EventSource(`/events?since=${lastVersion}`) store.getState().setConnected(true) - // ── Snapshot: atomic state replace (since=0) ─────────────────────────── - + // -- Snapshot: replace entire store state atomically ---------------------- es.addEventListener('snapshot', (e) => { - const data = JSON.parse((e as MessageEvent).data) as Record<string, unknown> - store.getState().applySnapshot(data) + const { version, state } = JSON.parse((e as MessageEvent).data) + storeState = state + store.setState({ lastVersion: version, ...state }) }) - // ── Fatal error: server cannot serve the requested version ───────────── - // Sent when ?since=N references a version the server no longer has - // (e.g. after server restart). Close without reconnect; App.tsx renders - // a "reload required" banner. - - es.addEventListener('fatal_error', () => { - store.getState().setFatalError(true) - store.getState().setConnected(false) - es.close() - // App.tsx overrides onerror -- but this is a named event, not an error. - // We do NOT call the reconnect path here. App.tsx checks fatalError - // in the reconnect scheduler and skips reconnect when it is set. + // -- Patch: apply RFC 6902 JSON Patch to store state ---------------------- + es.addEventListener('patch', (e) => { + try { + const { version, patch } = JSON.parse((e as MessageEvent).data) + // mutate:false returns a new document object — avoids mutating state + // that Zustand may still reference for the current render cycle. + storeState = applyPatch(storeState, patch, false, false).newDocument + store.setState({ lastVersion: version, ...storeState }) + } catch (err) { + console.error('Patch failed, reconnecting for fresh snapshot:', err) + es.close() + store.setState({ lastVersion: 0 }) // force snapshot on reconnect + // App.tsx onerror handler schedules the reconnect + } }) - // ── All other events: incremental fold ──────────────────────────────── - - const KNOWN_EVENTS = [ - // Lifecycle - 'phase_started', 'agent_spawned', 'agent_spawn_failed', 'scout_queued', - 'agent_step_advanced', 'agent_exited', 'workflow_completed', - // Activity - 'tool_called', 'tool_completed', - 'tool_read', 'tool_write', 'tool_edit', 'tool_bash', 'tool_grep', 'tool_ls', - 'thinking', 'stream_delta', 'stream_cleared', - // Interactions - 'questions_asked', 'questions_answered', - 'artifact_review_requested', 'artifact_reviewed', - 'workflow_decision_requested', 'workflow_decided', - // Resources - 'artifact_created', 'artifact_modified', 'artifact_removed', - // Configuration - 'probe_completed', - 'installation_created', 'installation_modified', 'installation_removed', - 'profile_created', 'profile_modified', 'profile_removed', - 'active_profile_changed', - 'scout_concurrency_changed', - ] - - for (const eventType of KNOWN_EVENTS) { - es.addEventListener(eventType, (e) => { - const data = JSON.parse((e as MessageEvent).data) as Record<string, unknown> - store.getState().applyEvent({ event_type: eventType, ...data }) - }) - } - // onerror is overridden by App.tsx to schedule reconnects. es.onerror = () => { store.getState().setConnected(false) diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 6c3734c..00f6b86 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -1,1043 +1,182 @@ import { create } from 'zustand' -import type { RunnerInfo } from '../api/client' -export const ALL_PHASES = [ - 'intake', 'brief-generation', 'core-flows', 'tech-plan', - 'ticket-breakdown', 'cross-artifact-validation', - 'execution', 'implementation-validation', -] +// -- Wire types — match backend KoanBaseModel.to_wire() output exactly -------- -// -- Domain types ------------------------------------------------------------ - -export type AgentStatus = 'running' | 'done' | 'failed' - -export interface AgentInfo { - agentId: string - role: string - model: string | null - step: number - stepName: string - startedAt: number // UTC epoch milliseconds - tokensSent: number - tokensReceived: number - status: AgentStatus - error?: string - label: string - lastTool: string +export interface Installation { + alias: string + runnerType: string + binary: string + extraArgs: string[] + available: boolean } -export interface ArtifactFile { - path: string - size: number - modifiedAt: number // UTC epoch milliseconds +export interface Profile { + name: string + readOnly: boolean + tiers: Record<string, string> // role → installation alias } -export interface CompletionInfo { - success: boolean - summary: string - error?: string - phase?: string +export interface Settings { + installations: Record<string, Installation> + profiles: Record<string, Profile> + defaultProfile: string + defaultScoutConcurrency: number } -export interface NotificationEntry { - id: string - type: string - severity: 'error' | 'warning' | 'info' - message: string - detail?: string +export interface RunConfig { + profile: string + installations: Record<string, string> // role → installation alias + scoutConcurrency: number } -export type ActivityEntryType = 'tool' | 'tool_read' | 'tool_write' | 'tool_edit' | 'tool_bash' | 'tool_grep' | 'tool_ls' | 'thinking' | 'step' | 'text' +// -- ConversationEntry — discriminated union ---------------------------------- -export interface ActivityEntry { - type: ActivityEntryType - tool: string - summary: string - inFlight: boolean - callId?: string - ts?: string - // Thinking entries - thinkingContent?: string - thinkingStartedAt?: number - thinkingEndedAt?: number - // Step entries - step?: number - stepName?: string - totalSteps?: number - // Text entries - textContent?: string - // Typed tool fields - file?: string - lines?: string - command?: string - pattern?: string - path?: string +export interface ThinkingEntry { type: 'thinking'; content: string } +export interface TextEntry { type: 'text'; text: string } +export interface StepEntry { type: 'step'; step: number; stepName: string; totalSteps: number | null } + +interface BaseToolEntry { callId: string; inFlight: boolean } +export interface ToolReadEntry extends BaseToolEntry { type: 'tool_read'; file: string; lines: string } +export interface ToolWriteEntry extends BaseToolEntry { type: 'tool_write'; file: string } +export interface ToolEditEntry extends BaseToolEntry { type: 'tool_edit'; file: string } +export interface ToolBashEntry extends BaseToolEntry { type: 'tool_bash'; command: string } +export interface ToolGrepEntry extends BaseToolEntry { type: 'tool_grep'; pattern: string } +export interface ToolLsEntry extends BaseToolEntry { type: 'tool_ls'; path: string } +export interface ToolGenericEntry extends BaseToolEntry { type: 'tool_generic'; toolName: string; summary: string } + +export type ConversationEntry = + | ThinkingEntry | TextEntry | StepEntry + | ToolReadEntry | ToolWriteEntry | ToolEditEntry + | ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry + +export interface Conversation { + entries: ConversationEntry[] + pendingThinking: string + pendingText: string + isThinking: boolean + inputTokens: number + outputTokens: number } -export interface AskOption { - value: string +// -- Agent -------------------------------------------------------------------- + +export type AgentStatus = 'queued' | 'running' | 'done' | 'failed' + +export interface Agent { + agentId: string + role: string label: string - recommended?: boolean + model: string | null + isPrimary: boolean + status: AgentStatus + error: string | null + startedAtMs: number + step: number + stepName: string + lastTool: string + conversation: Conversation } +// -- Focus — discriminated union ---------------------------------------------- + export interface AskQuestion { question: string multi: boolean - options: AskOption[] - allow_other?: boolean + options: { value: string; label: string; recommended?: boolean }[] + allow_other?: boolean // snake_case: comes from LLM via backend list[dict] context?: string } export interface ChatTurn { role: 'orchestrator' | 'user' - status_report?: string + status_report?: string // snake_case from backend list[dict] recommended_phases?: { phase: string; context?: string; recommended?: boolean }[] message?: string } -export type Interaction = - | { type: 'ask'; questions: AskQuestion[]; token: string } - | { type: 'artifact-review'; content: string; description?: string; path?: string; token: string } - | { type: 'workflow-decision'; chat_turns: ChatTurn[]; token: string } +export interface ConversationFocus { type: 'conversation'; agentId: string } +export interface QuestionFocus { type: 'question'; agentId: string; token: string; questions: AskQuestion[] } +export interface ReviewFocus { type: 'review'; agentId: string; token: string; path: string; description: string; content: string } +export interface DecisionFocus { type: 'decision'; agentId: string; token: string; chatTurns: ChatTurn[] } -export interface ProfileTierConfig { - runner_type: string - model: string - thinking: string -} +export type Focus = ConversationFocus | QuestionFocus | ReviewFocus | DecisionFocus -export interface Profile { - name: string - read_only: boolean - tiers: Record<string, ProfileTierConfig> -} +// -- Supporting types --------------------------------------------------------- -export interface Installation { - alias: string - runner_type: string - binary: string - extra_args: string[] - is_active?: boolean -} - -// Severity mapping for notification-worthy event types -const SEVERITY_MAP: Record<string, 'error' | 'warning' | 'info'> = { - agent_spawn_failed: 'error', - agent_exited_error: 'error', +export interface ArtifactInfo { + path: string + size: number + modifiedAt: number // ms since epoch } -// Map backend interaction_type event strings to frontend Interaction.type values -function interactionTypeToFrontend(interactionType: string): string { - switch (interactionType) { - case 'questions_asked': return 'ask' - case 'artifact_review_requested': return 'artifact-review' - case 'workflow_decision_requested': return 'workflow-decision' - default: return interactionType - } +export interface CompletionInfo { + success: boolean + summary: string + error?: string | null } -// Normalize raw questions from the backend (options may be strings or dicts) -function normalizeAskQuestions(rawQs: Record<string, unknown>[]): AskQuestion[] { - return rawQs.map(q => { - const rawOpts = (q['options'] ?? []) as (string | Record<string, unknown>)[] - const options: AskOption[] = rawOpts.map(o => { - if (typeof o === 'string') return { value: o, label: o } - const label = (o['label'] ?? o['text'] ?? o['value'] ?? o['option'] ?? '') as string - const value = (o['value'] ?? o['label'] ?? o['text'] ?? label) as string - return { - value, - label, - recommended: (o['recommended'] as boolean) ?? false, - } - }) - return { - question: (q['question'] ?? q['text'] ?? q['prompt'] ?? '') as string, - multi: (q['multi'] as boolean) ?? false, - options, - allow_other: (q['allow_other'] as boolean) ?? undefined, - context: (q['context'] ?? q['description'] ?? q['rationale']) as string | undefined, - } - }) +export interface Notification { + message: string + level: 'info' | 'warning' | 'error' + timestampMs: number } -function transformAgent(a: Record<string, unknown>): AgentInfo { - return { - agentId: a['agent_id'] as string, - role: a['role'] as string, - model: a['model'] as string | null, - step: (a['step'] as number) ?? 0, - stepName: (a['step_name'] as string) ?? '', - startedAt: (a['started_at_ms'] as number) ?? 0, - tokensSent: (a['input_tokens'] as number) ?? 0, - tokensReceived: (a['output_tokens'] as number) ?? 0, - status: (a['status'] as AgentStatus) ?? 'running', - error: a['error'] as string | undefined, - label: (a['label'] as string) ?? '', - lastTool: (a['lastTool'] as string) ?? '', - } -} +// -- Run ---------------------------------------------------------------------- -function transformArtifact(a: Record<string, unknown>): ArtifactFile { - return { - path: a['path'] as string, - size: (a['size'] as number) ?? 0, - modifiedAt: (a['modified_at'] as number) ?? 0, - } +export interface Run { + config: RunConfig + phase: string + agents: Record<string, Agent> + focus: Focus | null + artifacts: Record<string, ArtifactInfo> + completion: CompletionInfo | null } -// -- Store ------------------------------------------------------------------- +// -- Store -------------------------------------------------------------------- interface KoanState { // Connection connected: boolean lastVersion: number - fatalError: boolean - - // Run state - runStarted: boolean - phase: string - donePhases: string[] - - // Primary agent (phase-level) - primaryAgent: AgentInfo | null - - // Completed agents (exited, token totals preserved) - completedAgents: AgentInfo[] - - // Intake sub-phase progress (legacy, kept for compatibility) - intakeProgress: { subPhase: string; confidence: string | null; summary: string } | null - - // Scout agents — keyed by agentId - scouts: Record<string, AgentInfo> - - // Queued scouts (waiting for semaphore) - queuedScouts: Array<{ scoutId: string; label: string; model: string | null }> - - // Activity feed - activityLog: ActivityEntry[] - streamBuffer: string - isThinking: boolean - thinkingBuffer: string - thinkingStartedAt: number | null - // Notifications - notifications: NotificationEntry[] + // Projection state — mirrors server wire format; patches apply directly + settings: Settings + run: Run | null + notifications: Notification[] - // Active interaction (at most one at a time) - activeInteraction: Interaction | null - - // Artifacts — keyed by path - artifacts: Record<string, ArtifactFile> - - // Workflow completion - completion: CompletionInfo | null - - // Settings + // Local UI state (not from server) settingsOpen: boolean - profiles: Profile[] - installations: Installation[] - - // Configuration — sourced from projection events, always up to date - configProfiles: Profile[] - configInstallations: Installation[] - configActiveProfile: string - configScoutConcurrency: number - configRunners: RunnerInfo[] - // Legacy actions (used by existing components) + // Actions setConnected: (v: boolean) => void - setPhase: (phase: string) => void - setPrimaryAgent: (agent: AgentInfo | null) => void - setIntakeProgress: (p: KoanState['intakeProgress']) => void - setScouts: (scouts: Record<string, AgentInfo>) => void - appendLog: (entry: ActivityEntry) => void - completeLog: (callId: string) => void - appendStreamDelta: (delta: string) => void - clearStream: () => void - addNotification: (n: NotificationEntry) => void - dismissNotification: (id: string) => void - setInteraction: (interaction: Interaction | null) => void - setArtifacts: (artifacts: Record<string, ArtifactFile>) => void - setCompletion: (info: CompletionInfo) => void setSettingsOpen: (v: boolean) => void - setProfiles: (profiles: Profile[]) => void - setInstallations: (installations: Installation[]) => void - setFatalError: (v: boolean) => void - - // Event-sourced actions - applySnapshot: (data: Record<string, unknown>) => void - applyEvent: (event: Record<string, unknown>) => void } export const useStore = create<KoanState>((set) => ({ connected: false, lastVersion: 0, - fatalError: false, - runStarted: false, - phase: '', - donePhases: [], - primaryAgent: null, - completedAgents: [], - intakeProgress: null, - scouts: {}, - queuedScouts: [], - activityLog: [], - streamBuffer: '', - isThinking: false, - thinkingBuffer: '', - thinkingStartedAt: null, + + settings: { + installations: {}, + profiles: {}, + defaultProfile: 'balanced', + defaultScoutConcurrency: 8, + }, + run: null, notifications: [], - activeInteraction: null, - artifacts: {}, - completion: null, - settingsOpen: false, - profiles: [], - installations: [], - // Configuration defaults - configProfiles: [], - configInstallations: [], - configActiveProfile: 'balanced', - configScoutConcurrency: 8, - configRunners: [], + settingsOpen: false, setConnected: (v) => set({ connected: v }), - setFatalError: (v) => set({ fatalError: v }), - - setPhase: (phase) => set(() => { - const idx = ALL_PHASES.indexOf(phase) - const donePhases = idx === -1 ? [...ALL_PHASES] : ALL_PHASES.slice(0, idx) - return { phase, runStarted: true, donePhases } - }), - - setPrimaryAgent: (agent) => set({ primaryAgent: agent }), - setIntakeProgress: (p) => set({ intakeProgress: p }), - setScouts: (scouts) => set({ scouts }), - appendLog: (entry) => set((s) => ({ activityLog: [...s.activityLog, entry] })), - completeLog: (callId) => set((s) => ({ - activityLog: s.activityLog.map(e => - e.callId === callId ? { ...e, inFlight: false } : e - ), - })), - appendStreamDelta: (delta) => set((s) => ({ streamBuffer: s.streamBuffer + delta })), - clearStream: () => set({ streamBuffer: '' }), - addNotification: (n) => set((s) => ({ notifications: [...s.notifications, n] })), - dismissNotification: (id) => set((s) => ({ - notifications: s.notifications.filter((n) => n.id !== id), - })), - setInteraction: (interaction) => set({ activeInteraction: interaction }), - setArtifacts: (artifacts) => set({ artifacts }), - setCompletion: (info) => set({ completion: info }), setSettingsOpen: (v) => set({ settingsOpen: v }), - setProfiles: (profiles) => set({ profiles }), - setInstallations: (installations) => set({ installations }), - - // -- Snapshot: atomic state replace ---------------------------------------- - - applySnapshot: (data) => { - const version = data['version'] as number - const state = (data['state'] ?? {}) as Record<string, unknown> - - const phase = (state['phase'] as string) ?? '' - const idx = ALL_PHASES.indexOf(phase) - const donePhases = idx === -1 ? [...ALL_PHASES] : ALL_PHASES.slice(0, idx) - - // Transform primary_agent - const rawPrimary = state['primary_agent'] as Record<string, unknown> | null - const primaryAgent = rawPrimary ? transformAgent(rawPrimary) : null - - // Transform scouts - const rawScouts = (state['scouts'] ?? {}) as Record<string, Record<string, unknown>> - const scouts: Record<string, AgentInfo> = {} - for (const [id, a] of Object.entries(rawScouts)) { - scouts[id] = transformAgent(a) - } - - // Transform completed_agents - const rawCompleted = (state['completed_agents'] ?? []) as Record<string, unknown>[] - const completedAgents = rawCompleted.map(transformAgent) - - // Transform artifacts - const rawArtifacts = (state['artifacts'] ?? {}) as Record<string, Record<string, unknown>> - const artifacts: Record<string, ArtifactFile> = {} - for (const [path, a] of Object.entries(rawArtifacts)) { - artifacts[path] = transformArtifact(a) - } - - // Transform active_interaction: strip backend's interaction_type discriminator, - // map to frontend Interaction.type, and normalize questions if present. - let activeInteraction: Interaction | null = null - const rawInteraction = state['active_interaction'] as Record<string, unknown> | null - if (rawInteraction) { - const itype = interactionTypeToFrontend(rawInteraction['interaction_type'] as string) - const { interaction_type: _drop, ...interactionPayload } = rawInteraction - // Normalize ask interactions: options may be raw strings in the snapshot - if (itype === 'ask' && Array.isArray(interactionPayload['questions'])) { - interactionPayload['questions'] = normalizeAskQuestions( - interactionPayload['questions'] as Record<string, unknown>[], - ) - } - activeInteraction = { type: itype as Interaction['type'], ...interactionPayload } as Interaction - } - - // Transform notifications - const rawNotifs = (state['notifications'] ?? []) as Record<string, unknown>[] - const notifications: NotificationEntry[] = rawNotifs.map((n) => ({ - id: crypto.randomUUID(), - type: (n['type'] as string) ?? 'unknown', - severity: SEVERITY_MAP[(n['type'] as string) ?? ''] ?? 'info', - message: (n['message'] as string) ?? (n['error'] as string) ?? '', - })) - - // Transform activity_log - // The backend fold appends tool_called, tool_completed, thinking, and - // agent_step_advanced as raw entries. Reconstruct the rich view: - // - Filter to primary agent only (scout events shown in monitor) - // - Merge consecutive thinking deltas into single cards - // - Skip koan MCP tools (rendered as step headers) - const primaryAgentId = (rawPrimary?.['agent_id'] as string | undefined) - ?? (rawCompleted.find(a => (a['is_primary'] as boolean) ?? false)?.['agent_id'] as string | undefined) - const rawLog = (state['activity_log'] ?? []) as Record<string, unknown>[] - const completedCallIds = new Set( - rawLog - .filter(e => e['event_type'] === 'tool_completed') - .map(e => e['call_id'] as string) - .filter(Boolean) - ) - // Build flat entries, filtering to primary agent - const flatEntries: ActivityEntry[] = rawLog - .filter(e => { - if (e['event_type'] === 'tool_completed') return false - // Filter to primary agent if known - const eid = e['agent_id'] as string | undefined - if (primaryAgentId && eid && eid !== primaryAgentId) return false - return true - }) - .flatMap((e): ActivityEntry[] => { - const evtType = e['event_type'] as string - const callId = e['call_id'] as string | undefined - const inFlight = callId ? !completedCallIds.has(callId) : false - - if (evtType === 'thinking') { - return [{ type: 'thinking', tool: 'thinking', summary: '', - inFlight: false, - thinkingContent: (e['delta'] as string) ?? '' }] - } - if (evtType === 'agent_step_advanced') { - const step = e['step'] as number - if (step < 1) return [] // skip bootstrap - return [{ type: 'step', tool: '', summary: '', inFlight: false, - step, - stepName: (e['step_name'] as string) ?? '', - totalSteps: e['total_steps'] as number | undefined }] - } - if (evtType === 'tool_read') { - return [{ type: 'tool_read', tool: 'read', summary: '', inFlight, callId, - file: (e['file'] as string) ?? '', lines: (e['lines'] as string) ?? '' }] - } - if (evtType === 'tool_write') { - return [{ type: 'tool_write', tool: 'write', summary: '', inFlight, callId, - file: (e['file'] as string) ?? '' }] - } - if (evtType === 'tool_edit') { - return [{ type: 'tool_edit', tool: 'edit', summary: '', inFlight, callId, - file: (e['file'] as string) ?? '' }] - } - if (evtType === 'tool_bash') { - return [{ type: 'tool_bash', tool: 'bash', summary: '', inFlight, callId, - command: (e['command'] as string) ?? '' }] - } - if (evtType === 'tool_grep') { - return [{ type: 'tool_grep', tool: 'grep', summary: '', inFlight, callId, - pattern: (e['pattern'] as string) ?? '' }] - } - if (evtType === 'tool_ls') { - return [{ type: 'tool_ls', tool: 'ls', summary: '', inFlight, callId, - path: (e['path'] as string) ?? '' }] - } - if (evtType === 'tool_called') { - const toolName = (e['tool'] as string) ?? '' - if (toolName.startsWith('koan_') || toolName.startsWith('mcp__koan')) return [] - return [{ type: 'tool', tool: toolName, - summary: (e['summary'] as string) ?? '', inFlight, callId, - ts: e['ts'] as string | undefined }] - } - return [] - }) - // Merge consecutive thinking entries into single cards - const activityLog: ActivityEntry[] = [] - for (const entry of flatEntries) { - if (entry.type === 'thinking') { - const prev = activityLog[activityLog.length - 1] - if (prev?.type === 'thinking') { - // Merge into previous thinking card - prev.thinkingContent = (prev.thinkingContent ?? '') + (entry.thinkingContent ?? '') - continue - } - } - activityLog.push(entry) - } - - const completion = state['completion'] as CompletionInfo | null - - // Transform config fields - const configProfiles: Profile[] = ((state['config_profiles'] ?? []) as Record<string, unknown>[]).map(p => ({ - name: p['name'] as string, - read_only: (p['read_only'] as boolean) ?? false, - tiers: (p['tiers'] as Record<string, ProfileTierConfig>) ?? {}, - })) - - const configInstallations: Installation[] = ((state['config_installations'] ?? []) as Record<string, unknown>[]).map(i => ({ - alias: i['alias'] as string, - runner_type: i['runner_type'] as string, - binary: i['binary'] as string, - extra_args: (i['extra_args'] as string[]) ?? [], - })) - - set({ - lastVersion: version, - phase, - runStarted: phase !== '', - donePhases, - primaryAgent, - scouts, - completedAgents, - artifacts, - activeInteraction, - notifications, - activityLog, - streamBuffer: (state['stream_buffer'] as string) ?? '', - isThinking: false, - thinkingBuffer: '', - thinkingStartedAt: null, - queuedScouts: ((state['queued_scouts'] ?? []) as Array<{ scout_id: string; label: string; model: string | null }>).map(q => ({ - scoutId: (q as any).scout_id ?? (q as any).scoutId ?? '', - label: (q as any).label ?? '', - model: (q as any).model ?? null, - })), - completion: completion ?? null, - // Configuration - configProfiles, - configInstallations, - configActiveProfile: (state['config_active_profile'] as string) ?? 'balanced', - configScoutConcurrency: (state['config_scout_concurrency'] as number) ?? 8, - configRunners: (state['config_runners'] ?? []) as RunnerInfo[], - }) - }, - - // -- Event fold: mirrors backend fold -------------------------------------- - - applyEvent: (event) => { - // Helpers to flush accumulated buffers into activity entries. - function flushThinkingBuffer(s: KoanState): ActivityEntry[] { - if (!s.thinkingBuffer) return [...s.activityLog] - return [...s.activityLog, { - type: 'thinking', tool: 'thinking', summary: '', - inFlight: false, - thinkingContent: s.thinkingBuffer, - thinkingStartedAt: s.thinkingStartedAt ?? undefined, - thinkingEndedAt: Date.now(), - }] - } - function flushStreamBuffer(s: KoanState): ActivityEntry[] { - if (!s.streamBuffer) return [...s.activityLog] - return [...s.activityLog, { - type: 'text', tool: '', summary: '', - inFlight: false, - textContent: s.streamBuffer, - }] - } - function flushBuffers(s: KoanState): ActivityEntry[] { - let log = [...s.activityLog] - if (s.thinkingBuffer) { - log.push({ - type: 'thinking', tool: 'thinking', summary: '', - inFlight: false, - thinkingContent: s.thinkingBuffer, - thinkingStartedAt: s.thinkingStartedAt ?? undefined, - thinkingEndedAt: Date.now(), - }) - } - if (s.streamBuffer) { - log.push({ - type: 'text', tool: '', summary: '', - inFlight: false, - textContent: s.streamBuffer, - }) - } - return log - } - - const eventType = event['event_type'] as string - const version = event['version'] as number - const agentId = event['agent_id'] as string | null - - set((s) => { - // Update lastVersion - const base = { lastVersion: version } - - switch (eventType) { - - // ── Lifecycle ────────────────────────────────────────────────────── - - case 'phase_started': { - const phase = event['phase'] as string - const idx = ALL_PHASES.indexOf(phase) - const donePhases = idx === -1 ? [...ALL_PHASES] : ALL_PHASES.slice(0, idx) - return { ...base, phase, runStarted: true, donePhases } - } - - case 'agent_spawned': { - const isPrimary = event['is_primary'] as boolean ?? true - const agent: AgentInfo = { - agentId: (event['agent_id'] as string) ?? agentId ?? '', - role: event['role'] as string, - model: event['model'] as string | null, - step: 0, - stepName: '', - startedAt: (event['started_at_ms'] as number) ?? 0, - tokensSent: 0, - tokensReceived: 0, - status: 'running', - label: (event['label'] as string) ?? '', - lastTool: '', - } - if (isPrimary) { - return { ...base, primaryAgent: agent } - } else { - const lbl = (event['label'] as string) ?? '' - const newQueued = s.queuedScouts.filter(q => q.label !== lbl) - return { ...base, scouts: { ...s.scouts, [agent.agentId]: agent }, queuedScouts: newQueued } - } - } - - case 'agent_spawn_failed': { - const notif: NotificationEntry = { - id: crypto.randomUUID(), - type: 'agent_spawn_failed', - severity: 'error', - message: (event['message'] as string) ?? 'Agent spawn failed', - } - return { ...base, notifications: [...s.notifications, notif] } - } - - case 'scout_queued': { - const entry = { - scoutId: (event['scout_id'] as string) ?? '', - label: (event['label'] as string) ?? '', - model: (event['model'] as string | null) ?? null, - } - return { ...base, queuedScouts: [...s.queuedScouts, entry] } - } - - case 'agent_step_advanced': { - const step = event['step'] as number - const stepName = (event['step_name'] as string) ?? '' - const totalSteps = event['total_steps'] as number | undefined - const usage = event['usage'] as Record<string, number> | undefined - const isPrimary = s.primaryAgent?.agentId === agentId - - // Only add activity entries for the primary agent - let newLog = s.activityLog - if (isPrimary) { - newLog = flushBuffers(s) - if (step >= 1) { - newLog.push({ - type: 'step', tool: '', summary: '', - inFlight: false, - step, stepName, totalSteps, - }) - } - } - - const updates: Partial<KoanState> = { - ...base, - activityLog: newLog, - isThinking: false, - thinkingBuffer: isPrimary ? '' : s.thinkingBuffer, - thinkingStartedAt: isPrimary ? null : s.thinkingStartedAt, - streamBuffer: isPrimary ? '' : s.streamBuffer, - } - if (isPrimary) { - updates.primaryAgent = { ...s.primaryAgent!, step, stepName, - tokensSent: s.primaryAgent!.tokensSent + (usage?.['input_tokens'] ?? 0), - tokensReceived: s.primaryAgent!.tokensReceived + (usage?.['output_tokens'] ?? 0), - } - } else if (agentId && agentId in s.scouts) { - const scout = s.scouts[agentId] - updates.scouts = { ...s.scouts, [agentId]: { ...scout, step, stepName, - tokensSent: scout.tokensSent + (usage?.['input_tokens'] ?? 0), - tokensReceived: scout.tokensReceived + (usage?.['output_tokens'] ?? 0), - } } - } - return updates - } - - case 'agent_exited': { - const error = event['error'] as string | undefined - const usage = event['usage'] as Record<string, number> | undefined - const newNotifs = error ? [ - ...s.notifications, - { - id: crypto.randomUUID(), - type: 'agent_exited_error', - severity: 'error' as const, - message: `Agent exited with error: ${error}`, - }, - ] : s.notifications - - // Mirror backend _accumulate_usage: apply final token delta before - // moving the agent to completedAgents. - const exitStatus: AgentStatus = error ? 'failed' : 'done' - function finalize(agent: AgentInfo): AgentInfo { - const a = usage ? { - ...agent, - tokensSent: agent.tokensSent + (usage['input_tokens'] ?? 0), - tokensReceived: agent.tokensReceived + (usage['output_tokens'] ?? 0), - } : agent - return { ...a, status: exitStatus, error: error ?? undefined } - } - - if (s.primaryAgent?.agentId === agentId) { - const finalAgent = finalize(s.primaryAgent) - return { ...base, primaryAgent: null, completedAgents: [...s.completedAgents, finalAgent], notifications: newNotifs } - } else if (agentId && agentId in s.scouts) { - const finalAgent = finalize(s.scouts[agentId]) - const { [agentId]: _, ...rest } = s.scouts - return { ...base, scouts: rest, completedAgents: [...s.completedAgents, finalAgent], notifications: newNotifs } - } - return { ...base, notifications: newNotifs } - } - - case 'workflow_completed': { - const completion: CompletionInfo = { - success: event['success'] as boolean, - summary: (event['summary'] as string) ?? '', - error: event['error'] as string | undefined, - } - return { ...base, completion } - } - - // ── Activity ─────────────────────────────────────────────────────── - // Only primary agent events go into the main activity feed. - // Scout activity is shown in the agent monitor at the bottom. - - case 'tool_called': { - const toolName = (event['tool'] as string) ?? 'tool' - // Skip koan MCP tools — rendered as step headers via MCP endpoint - if (toolName.startsWith('koan_') || toolName.startsWith('mcp__koan')) return base - if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { - const summary = (event['summary'] as string) ?? '' - const lastTool = summary ? `${toolName} ${summary}` : toolName - return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool } } } - } - if (agentId !== s.primaryAgent?.agentId) return base - const newLog = flushBuffers(s) - const entry: ActivityEntry = { - type: 'tool', - tool: toolName, - summary: (event['summary'] as string) ?? '', - inFlight: true, - callId: event['call_id'] as string, - ts: new Date().toISOString(), - } - newLog.push(entry) - return { ...base, activityLog: newLog, isThinking: false, - thinkingBuffer: '', thinkingStartedAt: null, - streamBuffer: '' } - } - - case 'tool_read': { - if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { - const f = (event['file'] as string) ?? '' - const l = (event['lines'] as string) ?? '' - const lastTool = l ? `read ${f}:${l}` : `read ${f}` - return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool } } } - } - if (agentId !== s.primaryAgent?.agentId) return base - const newLog = flushBuffers(s) - newLog.push({ - type: 'tool_read', tool: 'read', summary: '', - inFlight: true, callId: event['call_id'] as string, - file: (event['file'] as string) ?? '', - lines: (event['lines'] as string) ?? '', - ts: new Date().toISOString(), - }) - return { ...base, activityLog: newLog, isThinking: false, - thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } - } - - case 'tool_write': { - if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { - return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool: `write ${(event['file'] as string) ?? ''}` } } } - } - if (agentId !== s.primaryAgent?.agentId) return base - const newLog = flushBuffers(s) - newLog.push({ - type: 'tool_write', tool: 'write', summary: '', - inFlight: true, callId: event['call_id'] as string, - file: (event['file'] as string) ?? '', - ts: new Date().toISOString(), - }) - return { ...base, activityLog: newLog, isThinking: false, - thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } - } - - case 'tool_edit': { - if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { - return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool: `edit ${(event['file'] as string) ?? ''}` } } } - } - if (agentId !== s.primaryAgent?.agentId) return base - const newLog = flushBuffers(s) - newLog.push({ - type: 'tool_edit', tool: 'edit', summary: '', - inFlight: true, callId: event['call_id'] as string, - file: (event['file'] as string) ?? '', - ts: new Date().toISOString(), - }) - return { ...base, activityLog: newLog, isThinking: false, - thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } - } - - case 'tool_bash': { - if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { - return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool: `bash ${(event['command'] as string) ?? ''}` } } } - } - if (agentId !== s.primaryAgent?.agentId) return base - const newLog = flushBuffers(s) - newLog.push({ - type: 'tool_bash', tool: 'bash', summary: '', - inFlight: true, callId: event['call_id'] as string, - command: (event['command'] as string) ?? '', - ts: new Date().toISOString(), - }) - return { ...base, activityLog: newLog, isThinking: false, - thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } - } - - case 'tool_grep': { - if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { - return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool: `grep ${(event['pattern'] as string) ?? ''}` } } } - } - if (agentId !== s.primaryAgent?.agentId) return base - const newLog = flushBuffers(s) - newLog.push({ - type: 'tool_grep', tool: 'grep', summary: '', - inFlight: true, callId: event['call_id'] as string, - pattern: (event['pattern'] as string) ?? '', - ts: new Date().toISOString(), - }) - return { ...base, activityLog: newLog, isThinking: false, - thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } - } - - case 'tool_ls': { - if (agentId && agentId in s.scouts && agentId !== s.primaryAgent?.agentId) { - return { ...base, scouts: { ...s.scouts, [agentId]: { ...s.scouts[agentId], lastTool: `ls ${(event['path'] as string) ?? ''}` } } } - } - if (agentId !== s.primaryAgent?.agentId) return base - const newLog = flushBuffers(s) - newLog.push({ - type: 'tool_ls', tool: 'ls', summary: '', - inFlight: true, callId: event['call_id'] as string, - path: (event['path'] as string) ?? '', - ts: new Date().toISOString(), - }) - return { ...base, activityLog: newLog, isThinking: false, - thinkingBuffer: '', thinkingStartedAt: null, streamBuffer: '' } - } - - case 'tool_completed': { - if (agentId !== s.primaryAgent?.agentId) return base - const callId = event['call_id'] as string - return { - ...base, - activityLog: s.activityLog.map(e => - e.callId === callId ? { ...e, inFlight: false } : e - ), - } - } - - case 'thinking': { - if (agentId !== s.primaryAgent?.agentId) return base - const delta = (event['delta'] as string) ?? '' - // If there was pending stream text, flush it first (text → thinking transition) - const thinkLog = s.streamBuffer ? flushStreamBuffer(s) : s.activityLog - return { - ...base, - isThinking: true, - activityLog: thinkLog, - thinkingBuffer: s.thinkingBuffer + delta, - thinkingStartedAt: s.thinkingStartedAt ?? Date.now(), - streamBuffer: '', - } - } - - case 'stream_delta': { - if (agentId !== s.primaryAgent?.agentId) return base - // If there was pending thinking, flush it first (thinking → text transition) - const sdLog = s.thinkingBuffer ? flushThinkingBuffer(s) : s.activityLog - return { - ...base, - activityLog: sdLog, - streamBuffer: s.streamBuffer + ((event['delta'] as string) ?? ''), - isThinking: false, - thinkingBuffer: '', - thinkingStartedAt: null, - } - } - - case 'stream_cleared': { - if (agentId !== s.primaryAgent?.agentId) return base - const clearedLog = flushBuffers(s) - return { ...base, streamBuffer: '', isThinking: false, activityLog: clearedLog, - thinkingBuffer: '', thinkingStartedAt: null } - } - - // ── Interactions ─────────────────────────────────────────────────── - - case 'questions_asked': { - // Normalize questions: options may arrive as strings or dicts - // with varying key names from the LLM. - const rawQs = (event['questions'] as Record<string, unknown>[]) ?? [] - const questions = normalizeAskQuestions(rawQs) - const interaction: Interaction = { - type: 'ask', token: event['token'] as string, questions, - } - return { ...base, activeInteraction: interaction } - } - - case 'questions_answered': - return { ...base, activeInteraction: null } - - case 'artifact_review_requested': { - const interaction: Interaction = { - type: 'artifact-review', - token: event['token'] as string, - path: event['path'] as string, - description: event['description'] as string | undefined, - content: (event['content'] as string) ?? '', - } - return { ...base, activeInteraction: interaction } - } - - case 'artifact_reviewed': - return { ...base, activeInteraction: null } - - case 'workflow_decision_requested': { - const interaction: Interaction = { - type: 'workflow-decision', - token: event['token'] as string, - chat_turns: (event['chat_turns'] as ChatTurn[]) ?? [], - } - return { ...base, activeInteraction: interaction } - } - - case 'workflow_decided': - return { ...base, activeInteraction: null } - - // ── Resources ────────────────────────────────────────────────────── - - case 'artifact_created': - case 'artifact_modified': { - const path = event['path'] as string - const artifact: ArtifactFile = { - path, - size: (event['size'] as number) ?? 0, - modifiedAt: (event['modified_at'] as number) ?? 0, - } - return { ...base, artifacts: { ...s.artifacts, [path]: artifact } } - } - - case 'artifact_removed': { - const path = event['path'] as string - const { [path]: _, ...rest } = s.artifacts - return { ...base, artifacts: rest } - } - - // ── Configuration ────────────────────────────────────────────────── - - case 'probe_completed': { - return { ...base, configRunners: (event['runners'] as RunnerInfo[]) ?? [] } - } - - case 'installation_created': { - const inst: Installation = { - alias: event['alias'] as string, - runner_type: event['runner_type'] as string, - binary: event['binary'] as string, - extra_args: (event['extra_args'] as string[]) ?? [], - } - return { ...base, configInstallations: [...s.configInstallations, inst] } - } - - case 'installation_modified': { - const alias = event['alias'] as string - const updated: Installation = { - alias, - runner_type: event['runner_type'] as string, - binary: event['binary'] as string, - extra_args: (event['extra_args'] as string[]) ?? [], - } - return { - ...base, - configInstallations: s.configInstallations.map(i => - i.alias === alias ? updated : i - ), - } - } - - case 'installation_removed': { - const alias = event['alias'] as string - return { ...base, configInstallations: s.configInstallations.filter(i => i.alias !== alias) } - } - - case 'profile_created': { - const profile: Profile = { - name: event['name'] as string, - read_only: (event['read_only'] as boolean) ?? false, - tiers: (event['tiers'] as Record<string, ProfileTierConfig>) ?? {}, - } - return { ...base, configProfiles: [...s.configProfiles, profile] } - } - - case 'profile_modified': { - const name = event['name'] as string - const updated: Profile = { - name, - read_only: (event['read_only'] as boolean) ?? false, - tiers: (event['tiers'] as Record<string, ProfileTierConfig>) ?? {}, - } - const exists = s.configProfiles.some(p => p.name === name) - return { - ...base, - configProfiles: exists - ? s.configProfiles.map(p => p.name === name ? updated : p) - : [...s.configProfiles, updated], - } - } - - case 'profile_removed': { - const name = event['name'] as string - return { - ...base, - configProfiles: s.configProfiles.filter(p => p.name !== name), - } - } - - case 'active_profile_changed': { - return { ...base, configActiveProfile: (event['name'] as string) ?? 'balanced' } - } - - case 'scout_concurrency_changed': { - return { ...base, configScoutConcurrency: (event['value'] as number) ?? 8 } - } - - default: - return base - } - }) - }, })) export type KoanStore = typeof useStore + +// -- ALL_PHASES (frontend-only derivation helper) ---------------------------- + +export const ALL_PHASES = [ + 'intake', 'brief-generation', 'core-flows', 'tech-plan', + 'ticket-breakdown', 'cross-artifact-validation', + 'execution', 'implementation-validation', +] diff --git a/frontend/src/store/selectors.ts b/frontend/src/store/selectors.ts index fb2149a..7a4877f 100644 --- a/frontend/src/store/selectors.ts +++ b/frontend/src/store/selectors.ts @@ -1,32 +1,9 @@ import { useMemo } from 'react' -import { useStore, ArtifactFile, ALL_PHASES } from './index' +import { useStore, ArtifactInfo } from './index' -// Subscribe to the raw scouts Record -- reference-stable until setScouts is called. -// Derive the array in the component via useMemo to avoid creating a new array -// on every render (which would trigger useSyncExternalStore's infinite loop). -export function useScoutList() { - const scouts = useStore(s => s.scouts) - return useMemo(() => Object.values(scouts), [scouts]) -} - -// Isolated subscription: StatusSidebar re-renders only when primaryAgent changes. -export const usePrimaryAgent = () => useStore(s => s.primaryAgent) - -// Boolean subscription: drives conditional rendering of the interaction overlay -// without subscribing to the full interaction payload. -export const useHasInteraction = () => useStore(s => s.activeInteraction !== null) - -// Derive done phases from current phase -- frontend-only derivation. -export function useDonePhases(): string[] { - const phase = useStore(s => s.phase) - return useMemo(() => { - const idx = ALL_PHASES.indexOf(phase) - return idx === -1 ? [...ALL_PHASES] : ALL_PHASES.slice(0, idx) - }, [phase]) -} - -function groupByDirectory(artifacts: ArtifactFile[]): Record<string, ArtifactFile[]> { - const tree: Record<string, ArtifactFile[]> = {} +// Derive artifact tree grouped by directory +function groupByDirectory(artifacts: ArtifactInfo[]): Record<string, ArtifactInfo[]> { + const tree: Record<string, ArtifactInfo[]> = {} for (const a of artifacts) { const parts = a.path.split('/') const dir = parts.length > 1 ? parts.slice(0, -1).join('/') : 'epic-root' @@ -36,8 +13,9 @@ function groupByDirectory(artifacts: ArtifactFile[]): Record<string, ArtifactFil return tree } -// Subscribe to the artifacts Record -- derive the tree in useMemo. +// Subscribe to run.artifacts — derive the tree in useMemo to avoid recreating +// the array on every render (which would trigger useSyncExternalStore loops). export function useArtifactTree() { - const artifacts = useStore(s => s.artifacts) + const artifacts = useStore(s => s.run?.artifacts ?? {}) return useMemo(() => groupByDirectory(Object.values(artifacts)), [artifacts]) } diff --git a/frontend/src/utils.ts b/frontend/src/utils.ts index 0ae647b..5996983 100644 --- a/frontend/src/utils.ts +++ b/frontend/src/utils.ts @@ -13,10 +13,11 @@ export function formatSize(bytes: number): string { return `${(bytes / (1024 * 1024)).toFixed(1)} MB` } -export function tierSummary(tiers: Record<string, { model?: string }>): string { +// tiers is now Record<string, string> — role → installation alias +export function tierSummary(tiers: Record<string, string>): string { const parts: string[] = [] - for (const t of ['strong', 'standard', 'cheap']) { - if (tiers[t]?.model) parts.push(`${t}: ${tiers[t].model}`) + for (const [role, alias] of Object.entries(tiers)) { + if (alias) parts.push(`${role}: ${alias}`) } - return parts.join(' | ') || '--' + return parts.slice(0, 3).join(' | ') || '--' } From 79b794ca9b27b4c29bc732a317cbac483ced4c06 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 17:52:11 +0700 Subject: [PATCH 257/412] update all components for new store shape Read from run.agents, run.focus, run.completion, settings.installations, settings.profiles. Focus discriminated union drives main content area. Fix landing page preflight for legacy tier format and terminology (runners -> agent installations). --- frontend/src/App.tsx | 43 ++-- frontend/src/components/ActivityFeed.tsx | 202 ++++++------------ frontend/src/components/AgentMonitor.tsx | 43 ++-- frontend/src/components/ArtifactsSidebar.tsx | 4 +- frontend/src/components/Completion.tsx | 9 +- frontend/src/components/Header.tsx | 4 +- frontend/src/components/LandingPage.tsx | 68 +++--- frontend/src/components/Notification.tsx | 21 +- frontend/src/components/PillStrip.tsx | 10 +- frontend/src/components/SettingsOverlay.tsx | 55 ++--- frontend/src/components/StatusSidebar.tsx | 44 ++-- .../interactions/ArtifactReview.tsx | 24 +-- .../src/components/interactions/AskWizard.tsx | 44 ++-- .../interactions/WorkflowDecision.tsx | 25 +-- 14 files changed, 260 insertions(+), 336 deletions(-) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 0cbb3ee..fc2cf2f 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -15,21 +15,23 @@ import { WorkflowDecision } from './components/interactions/WorkflowDecision' import { ArtifactReview } from './components/interactions/ArtifactReview' function InteractionView() { - const interaction = useStore(s => s.activeInteraction) - if (!interaction) return null - if (interaction.type === 'ask') return <AskWizard /> - if (interaction.type === 'workflow-decision') return <WorkflowDecision /> - if (interaction.type === 'artifact-review') return <ArtifactReview /> + const focus = useStore(s => s.run?.focus) + if (!focus) return null + if (focus.type === 'question') return <AskWizard /> + if (focus.type === 'decision') return <WorkflowDecision /> + if (focus.type === 'review') return <ArtifactReview /> return null } function WorkspaceMain() { - const interaction = useStore(s => s.activeInteraction) - const completion = useStore(s => s.completion) + const focus = useStore(s => s.run?.focus) + const completion = useStore(s => s.run?.completion) + + const hasInteraction = focus && focus.type !== 'conversation' return ( <div className="workspace-main"> - {interaction ? ( + {hasInteraction ? ( <InteractionView /> ) : completion ? ( <Completion /> @@ -42,19 +44,14 @@ function WorkspaceMain() { } export default function App() { - const runStarted = useStore(s => s.runStarted) + const run = useStore(s => s.run) const settingsOpen = useStore(s => s.settingsOpen) - const fatalError = useStore(s => s.fatalError) useEffect(() => { let es: EventSource | null = null let retryDelay = 500 function connect() { - // Do not reconnect after a fatal_error (server restart / stale version). - // User must reload the page. - if (useStore.getState().fatalError) return - es = connectSSE(useStore) // Override the onerror set inside connectSSE to schedule our retry. es.onerror = () => { @@ -72,29 +69,17 @@ export default function App() { connect() - // Cleanup on unmount -- prevents duplicate SSE connections in React StrictMode. + // Cleanup on unmount — prevents duplicate SSE connections in React StrictMode. return () => { es?.close() } - }, []) // Empty dep array: connect once, reconnect is managed inside - - if (fatalError) { - return ( - <div className="app"> - <Header /> - <div style={{ padding: '2rem', textAlign: 'center' }}> - <p>Connection lost. The server restarted or the session expired.</p> - <button onClick={() => window.location.reload()}>Reload page</button> - </div> - </div> - ) - } + }, []) // Empty dep array: connect once; reconnect is managed inside return ( <div className="app"> <Header /> - {!runStarted ? ( + {!run ? ( <LandingPage /> ) : ( <div className="workspace"> diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index 935df65..722d4f4 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -1,21 +1,17 @@ import { useRef, useState } from 'react' -import { useStore, ActivityEntry } from '../store/index' +import { useStore, ConversationEntry } from '../store/index' import { useAutoScroll } from '../hooks/useAutoScroll' -import { useElapsedBetween } from '../hooks/useElapsed' // -- Thinking ------------------------------------------------------------------ -function ThinkingCard({ entry }: { entry: ActivityEntry }) { +function ThinkingCard({ content }: { content: string }) { const [expanded, setExpanded] = useState(false) - const elapsed = useElapsedBetween(entry.thinkingStartedAt, entry.thinkingEndedAt) - const content = entry.thinkingContent || '' const isLong = content.length > 300 return ( <div className="activity-card activity-card-thinking"> <div className="activity-card-header"> <span className="activity-card-tool">thinking</span> - {elapsed && <span className="activity-card-meta thinking-timer">{elapsed}</span>} </div> {content && ( <div className={`activity-card-body ${expanded ? 'expanded' : ''}`}> @@ -31,177 +27,115 @@ function ThinkingCard({ entry }: { entry: ActivityEntry }) { ) } -function ActiveThinkingCard() { - const thinkingBuffer = useStore(s => s.thinkingBuffer) - const thinkingStartedAt = useStore(s => s.thinkingStartedAt) - const elapsed = useElapsedBetween(thinkingStartedAt, null) - - if (!thinkingBuffer) return null - - return ( - <div className="activity-card activity-card-thinking activity-card-active"> - <div className="activity-card-header"> - <span className="activity-card-tool">thinking</span> - {elapsed && <span className="activity-card-meta thinking-timer">{elapsed}</span>} - </div> - <div className="activity-card-body expanded"> - {thinkingBuffer} - </div> - </div> - ) -} - // -- Step header --------------------------------------------------------------- -function StepHeader({ entry }: { entry: ActivityEntry }) { - const label = entry.totalSteps - ? `step ${entry.step}/${entry.totalSteps}` - : `step ${entry.step}` - +function StepHeader({ step, stepName, totalSteps }: { + step: number; stepName: string; totalSteps: number | null +}) { + const label = totalSteps ? `step ${step}/${totalSteps}` : `step ${step}` return ( <div className="step-header"> <span className="step-header-label">{label}</span> - {entry.stepName && <span className="step-header-name">{entry.stepName}</span>} + {stepName && <span className="step-header-name">{stepName}</span>} </div> ) } // -- Text block ---------------------------------------------------------------- -function TextBlock({ entry }: { entry: ActivityEntry }) { - return ( - <div className="stream-output"> - {entry.textContent} - </div> - ) +function TextBlock({ text }: { text: string }) { + return <div className="stream-output">{text}</div> } // -- Tool lines ---------------------------------------------------------------- -function statusIcon(inFlight: boolean) { - return inFlight ? '›' : '✓' -} - -function statusClass(inFlight: boolean) { - return inFlight ? 'activity-inflight' : 'activity-done' -} +function statusIcon(inFlight: boolean) { return inFlight ? '›' : '✓' } +function statusClass(inFlight: boolean) { return inFlight ? 'activity-inflight' : 'activity-done' } -function ToolLine({ entry }: { entry: ActivityEntry }) { +function ToolLine({ tool, summary, inFlight }: { tool: string; summary: string; inFlight: boolean }) { return ( - <div className={`activity-line ${statusClass(entry.inFlight)}`}> - <span className="activity-status">{statusIcon(entry.inFlight)}</span> - <span className="activity-tool">{entry.tool || ''}</span> + <div className={`activity-line ${statusClass(inFlight)}`}> + <span className="activity-status">{statusIcon(inFlight)}</span> + <span className="activity-tool">{tool}</span> <span className="activity-summary"> - {entry.summary || ''} - {entry.inFlight && <span className="activity-dots">...</span>} + {summary} + {inFlight && <span className="activity-dots">...</span>} </span> </div> ) } -function ReadLine({ entry }: { entry: ActivityEntry }) { - const detail = entry.lines ? `${entry.file}:${entry.lines}` : (entry.file || '') +function DetailLine({ tool, detail, inFlight }: { tool: string; detail: string; inFlight: boolean }) { return ( - <div className={`activity-line ${statusClass(entry.inFlight)}`}> - <span className="activity-status">{statusIcon(entry.inFlight)}</span> - <span className="activity-tool">read</span> + <div className={`activity-line ${statusClass(inFlight)}`}> + <span className="activity-status">{statusIcon(inFlight)}</span> + <span className="activity-tool">{tool}</span> <span className="activity-detail">{detail}</span> - {entry.inFlight && <span className="activity-dots">...</span>} - </div> - ) -} - -function WriteLine({ entry }: { entry: ActivityEntry }) { - return ( - <div className={`activity-line ${statusClass(entry.inFlight)}`}> - <span className="activity-status">{statusIcon(entry.inFlight)}</span> - <span className="activity-tool">write</span> - <span className="activity-detail">{entry.file || ''}</span> - {entry.inFlight && <span className="activity-dots">...</span>} - </div> - ) -} - -function EditLine({ entry }: { entry: ActivityEntry }) { - return ( - <div className={`activity-line ${statusClass(entry.inFlight)}`}> - <span className="activity-status">{statusIcon(entry.inFlight)}</span> - <span className="activity-tool">edit</span> - <span className="activity-detail">{entry.file || ''}</span> - {entry.inFlight && <span className="activity-dots">...</span>} - </div> - ) -} - -function BashLine({ entry }: { entry: ActivityEntry }) { - return ( - <div className={`activity-line ${statusClass(entry.inFlight)}`}> - <span className="activity-status">{statusIcon(entry.inFlight)}</span> - <span className="activity-tool">bash</span> - <span className="activity-detail">{entry.command || ''}</span> - {entry.inFlight && <span className="activity-dots">...</span>} - </div> - ) -} - -function GrepLine({ entry }: { entry: ActivityEntry }) { - return ( - <div className={`activity-line ${statusClass(entry.inFlight)}`}> - <span className="activity-status">{statusIcon(entry.inFlight)}</span> - <span className="activity-tool">grep</span> - <span className="activity-detail">{entry.pattern || ''}</span> - {entry.inFlight && <span className="activity-dots">...</span>} - </div> - ) -} - -function LsLine({ entry }: { entry: ActivityEntry }) { - return ( - <div className={`activity-line ${statusClass(entry.inFlight)}`}> - <span className="activity-status">{statusIcon(entry.inFlight)}</span> - <span className="activity-tool">ls</span> - <span className="activity-detail">{entry.path || ''}</span> - {entry.inFlight && <span className="activity-dots">...</span>} + {inFlight && <span className="activity-dots">...</span>} </div> ) } -// -- Feed ---------------------------------------------------------------------- +// -- Entry renderer ----------------------------------------------------------- -function renderEntry(entry: ActivityEntry, i: number) { +function renderEntry(entry: ConversationEntry, i: number) { switch (entry.type) { - case 'thinking': return <ThinkingCard key={i} entry={entry} /> - case 'step': return <StepHeader key={i} entry={entry} /> - case 'text': return <TextBlock key={i} entry={entry} /> - case 'tool_read': return <ReadLine key={i} entry={entry} /> - case 'tool_write': return <WriteLine key={i} entry={entry} /> - case 'tool_edit': return <EditLine key={i} entry={entry} /> - case 'tool_bash': return <BashLine key={i} entry={entry} /> - case 'tool_grep': return <GrepLine key={i} entry={entry} /> - case 'tool_ls': return <LsLine key={i} entry={entry} /> - default: return <ToolLine key={i} entry={entry} /> + case 'thinking': + return <ThinkingCard key={i} content={entry.content} /> + case 'step': + return <StepHeader key={i} step={entry.step} stepName={entry.stepName} totalSteps={entry.totalSteps} /> + case 'text': + return <TextBlock key={i} text={entry.text} /> + case 'tool_read': { + const detail = entry.lines ? `${entry.file}:${entry.lines}` : entry.file + return <DetailLine key={i} tool="read" detail={detail} inFlight={entry.inFlight} /> + } + case 'tool_write': + return <DetailLine key={i} tool="write" detail={entry.file} inFlight={entry.inFlight} /> + case 'tool_edit': + return <DetailLine key={i} tool="edit" detail={entry.file} inFlight={entry.inFlight} /> + case 'tool_bash': + return <DetailLine key={i} tool="bash" detail={entry.command} inFlight={entry.inFlight} /> + case 'tool_grep': + return <DetailLine key={i} tool="grep" detail={entry.pattern} inFlight={entry.inFlight} /> + case 'tool_ls': + return <DetailLine key={i} tool="ls" detail={entry.path} inFlight={entry.inFlight} /> + case 'tool_generic': + return <ToolLine key={i} tool={entry.toolName} summary={entry.summary} inFlight={entry.inFlight} /> + default: + return null } } +// -- Feed --------------------------------------------------------------------- + export function ActivityFeed() { - const activityLog = useStore(s => s.activityLog) - const streamBuffer = useStore(s => s.streamBuffer) - const isThinking = useStore(s => s.isThinking) - const thinkingBuffer = useStore(s => s.thinkingBuffer) + const focusAgentId = useStore(s => s.run?.focus?.agentId) + const conversation = useStore(s => + focusAgentId ? s.run?.agents?.[focusAgentId]?.conversation : undefined + ) const scrollRef = useRef<HTMLDivElement>(null) - useAutoScroll(scrollRef) return ( <div className="activity-feed-scroll" ref={scrollRef}> <div id="activity-feed-inner" className="activity-feed-inner"> - {activityLog.map(renderEntry)} + {conversation?.entries.map(renderEntry)} {/* Active thinking card — shown while LLM is reasoning */} - {isThinking && thinkingBuffer && <ActiveThinkingCard />} + {conversation?.isThinking && conversation.pendingThinking && ( + <div className="activity-card activity-card-thinking activity-card-active"> + <div className="activity-card-header"> + <span className="activity-card-tool">thinking</span> + </div> + <div className="activity-card-body expanded"> + {conversation.pendingThinking} + </div> + </div> + )} {/* Thinking indicator — no content yet */} - {isThinking && !thinkingBuffer && ( + {conversation?.isThinking && !conversation.pendingThinking && ( <div className="activity-thinking-indicator"> <span className="thinking-dot">●</span> <span>Thinking…</span> @@ -209,9 +143,9 @@ export function ActivityFeed() { )} {/* Active stream output — text being produced right now */} - {streamBuffer && ( + {conversation?.pendingText && ( <div className="stream-output"> - {streamBuffer} + {conversation.pendingText} <span className="streaming-cursor" /> </div> )} diff --git a/frontend/src/components/AgentMonitor.tsx b/frontend/src/components/AgentMonitor.tsx index 6a41635..66ac5d9 100644 --- a/frontend/src/components/AgentMonitor.tsx +++ b/frontend/src/components/AgentMonitor.tsx @@ -1,10 +1,10 @@ import { useMemo } from 'react' -import { useStore, AgentInfo } from '../store/index' +import { useStore, Agent } from '../store/index' import { useElapsed } from '../hooks/useElapsed' import { formatTokens } from '../utils' -function AgentRow({ agent }: { agent: AgentInfo }) { - const elapsed = useElapsed(agent.startedAt) +function AgentRow({ agent }: { agent: Agent }) { + const elapsed = useElapsed(agent.startedAtMs) const status = agent.status const statusIcon = status === 'running' ? '›' @@ -24,7 +24,9 @@ function AgentRow({ agent }: { agent: AgentInfo }) { <span className={`agent-row-icon ${statusCls}`}>{statusIcon}</span> <span className={`agent-row-name ${nameCls}`}>{agent.label || agent.role}</span> <span className="agent-row-model">{agent.model ?? '--'}</span> - <span className="agent-row-tokens">{formatTokens(agent.tokensSent, agent.tokensReceived)}</span> + <span className="agent-row-tokens"> + {formatTokens(agent.conversation.inputTokens, agent.conversation.outputTokens)} + </span> <span className="agent-row-time">{elapsed}</span> <span className={`agent-row-doing ${doingCls}`}>{doingText}</span> </div> @@ -67,22 +69,23 @@ function SectionHeader({ icon, label, className }: { } export function AgentMonitor() { - const scouts = useStore(s => s.scouts) - const completedAgents = useStore(s => s.completedAgents) - const queuedScouts = useStore(s => s.queuedScouts) + const agents = useStore(s => s.run?.agents ?? {}) - const { running, done, failed } = useMemo(() => { - const runList = Object.values(scouts) - const doneList = completedAgents.filter(a => a.status === 'done' && a.role === 'scout') - const failList = completedAgents.filter(a => a.status === 'failed' && a.role === 'scout') - return { running: runList, done: doneList, failed: failList } - }, [scouts, completedAgents]) + const { running, queued, done, failed } = useMemo(() => { + const all = Object.values(agents) + return { + running: all.filter(a => !a.isPrimary && a.status === 'running'), + queued: all.filter(a => a.status === 'queued'), + done: all.filter(a => a.status === 'done' && !a.isPrimary), + failed: all.filter(a => a.status === 'failed' && !a.isPrimary), + } + }, [agents]) - const total = running.length + done.length + failed.length + queuedScouts.length + const total = running.length + queued.length + done.length + failed.length if (total === 0) return null // Collapse to just the counter bar when nothing is active - const hasActive = running.length > 0 || queuedScouts.length > 0 + const hasActive = running.length > 0 || queued.length > 0 const collapsed = !hasActive return ( @@ -90,7 +93,7 @@ export function AgentMonitor() { <div className="monitor-inner"> <CounterBar running={running.length} - queued={queuedScouts.length} + queued={queued.length} done={done.length} failed={failed.length} /> @@ -104,13 +107,13 @@ export function AgentMonitor() { </> )} - {queuedScouts.length > 0 && ( + {queued.length > 0 && ( <> <SectionHeader icon="○" label="queued" className="section-queued" /> - {queuedScouts.map((q, i) => ( - <div key={i} className="agent-row agent-row-queued"> + {queued.map(a => ( + <div key={a.agentId} className="agent-row agent-row-queued"> <span className="agent-row-icon agent-status-queued">○</span> - <span className="agent-row-name agent-name-queued">{q.label || 'scout'}</span> + <span className="agent-row-name agent-name-queued">{a.label || 'scout'}</span> <span className="agent-row-model">--</span> <span className="agent-row-tokens">--</span> <span className="agent-row-time">--</span> diff --git a/frontend/src/components/ArtifactsSidebar.tsx b/frontend/src/components/ArtifactsSidebar.tsx index 19717dc..2be0d68 100644 --- a/frontend/src/components/ArtifactsSidebar.tsx +++ b/frontend/src/components/ArtifactsSidebar.tsx @@ -1,6 +1,6 @@ import { useState } from 'react' import { useArtifactTree } from '../store/selectors' -import { ArtifactFile } from '../store/index' +import { ArtifactInfo } from '../store/index' import { formatSize } from '../utils' import * as api from '../api/client' @@ -44,7 +44,7 @@ function FolderNode({ onFileClick, }: { dir: string - files: ArtifactFile[] + files: ArtifactInfo[] onFileClick: (path: string) => void }) { const [open, setOpen] = useState(true) diff --git a/frontend/src/components/Completion.tsx b/frontend/src/components/Completion.tsx index 96e766f..0dd50a2 100644 --- a/frontend/src/components/Completion.tsx +++ b/frontend/src/components/Completion.tsx @@ -1,8 +1,8 @@ import { useStore } from '../store/index' export function Completion() { - const completion = useStore(s => s.completion) - const artifacts = useStore(s => s.artifacts) + const completion = useStore(s => s.run?.completion) + const artifacts = useStore(s => s.run?.artifacts ?? {}) if (!completion) return null @@ -34,11 +34,6 @@ export function Completion() { Run Failed </h2> <p className="phase-status">{completion.error || 'An error occurred.'}</p> - {completion.phase && ( - <p className="phase-status" style={{ color: 'var(--text-muted)' }}> - Failed during: {completion.phase} - </p> - )} </> )} </div> diff --git a/frontend/src/components/Header.tsx b/frontend/src/components/Header.tsx index 6bf0a2b..6595a40 100644 --- a/frontend/src/components/Header.tsx +++ b/frontend/src/components/Header.tsx @@ -2,14 +2,14 @@ import { useStore } from '../store/index' import { PillStrip } from './PillStrip' export function Header() { - const runStarted = useStore(s => s.runStarted) + const run = useStore(s => s.run) const setSettingsOpen = useStore(s => s.setSettingsOpen) return ( <header className="header"> <div className="header-left"> <span className="logo">koan</span> - {runStarted && <PillStrip />} + {run && <PillStrip />} </div> <div className="header-right"> <button diff --git a/frontend/src/components/LandingPage.tsx b/frontend/src/components/LandingPage.tsx index 98467d4..d50c5a7 100644 --- a/frontend/src/components/LandingPage.tsx +++ b/frontend/src/components/LandingPage.tsx @@ -11,12 +11,16 @@ export function LandingPage() { const [selectedInstallations, setSelectedInstallations] = useState<Record<string, string>>({}) // Read from store (fed by SSE — always current, no API fetch needed) - const profiles = useStore(s => s.configProfiles) - const installations = useStore(s => s.configInstallations) - const runners = useStore(s => s.configRunners) - const storeScoutConcurrency = useStore(s => s.configScoutConcurrency) + const profilesDict = useStore(s => s.settings.profiles) + const installationsDict = useStore(s => s.settings.installations) + const defaultProfile = useStore(s => s.settings.defaultProfile) + const defaultScoutConcurrency = useStore(s => s.settings.defaultScoutConcurrency) - const hasRunners = runners.some(r => r.available) + const profiles = useMemo(() => Object.values(profilesDict), [profilesDict]) + const installations = useMemo(() => Object.values(installationsDict), [installationsDict]) + + // Available means the binary was probed and found + const hasRunners = installations.some(i => i.available) // Load initial prompt (one-shot, not config state) useEffect(() => { @@ -25,48 +29,55 @@ export function LandingPage() { }) }, []) - // Auto-select first profile when profiles arrive from store + // Auto-select default profile when profiles arrive from store useEffect(() => { if (profiles.length > 0 && !profile) { - setProfile(profiles[0].name) + const def = profiles.find(p => p.name === defaultProfile) ?? profiles[0] + setProfile(def.name) } - }, [profiles, profile]) + }, [profiles, profile, defaultProfile]) // Sync scout concurrency from store useEffect(() => { - setScoutConcurrency(storeScoutConcurrency) - }, [storeScoutConcurrency]) + setScoutConcurrency(defaultScoutConcurrency) + }, [defaultScoutConcurrency]) - // Derive preflight locally from store state (no API call) + // Derive preflight locally from store state — no API call needed const preflight = useMemo(() => { const selectedProfile = profiles.find(p => p.name === profile) if (!selectedProfile) return null - // Collect unique runner types from profile tiers + // Profile tiers map role → value. The fold normalizes tier configs to strings. + // The string may be an installation alias ("claude-default") or a runner type + // ("claude") depending on whether the profile was created from the new or + // legacy format. Try alias lookup first, fall back to runner type. const requiredTypes = new Set<string>() - for (const tier of Object.values(selectedProfile.tiers)) { - if (tier.runner_type) requiredTypes.add(tier.runner_type) + for (const tierVal of Object.values(selectedProfile.tiers)) { + if (typeof tierVal === 'string') { + const inst = installationsDict[tierVal] + if (inst) { + // Value is an installation alias — derive runner type from it + requiredTypes.add(inst.runnerType) + } else { + // Value is a runner type string (legacy fold normalization) + requiredTypes.add(tierVal) + } + } } - // Group installations by runner type with binary validity - const installationsByType: Record<string, { alias: string; binary: string; binary_valid: boolean }[]> = {} + // Group available installations by runner type + const installationsByType: Record<string, { alias: string; binary: string }[]> = {} for (const rt of requiredTypes) { installationsByType[rt] = installations - .filter(i => i.runner_type === rt) - .map(i => ({ - alias: i.alias, - binary: i.binary, - // We can't check binary existence client-side, but the start-run - // endpoint validates. Show all installations as selectable. - binary_valid: true, - })) + .filter(i => i.runnerType === rt && i.available) + .map(i => ({ alias: i.alias, binary: i.binary })) } return { required_runner_types: [...requiredTypes].sort(), installations: installationsByType, } - }, [profile, profiles, installations]) + }, [profile, profiles, installations, installationsDict]) // Auto-select installations when preflight changes useEffect(() => { @@ -77,7 +88,6 @@ export function LandingPage() { const selections: Record<string, string> = {} for (const rt of preflight.required_runner_types) { const insts = preflight.installations[rt] || [] - // Prefer the {rt}-default installation, else first available const defaultInst = insts.find(i => i.alias === `${rt}-default`) const first = insts[0] if (defaultInst) selections[rt] = defaultInst.alias @@ -149,7 +159,7 @@ export function LandingPage() { {profiles.map(p => ( <option key={p.name} value={p.name}> {p.name} - {p.read_only ? ' (built-in)' : ''} + {p.readOnly ? ' (built-in)' : ''} </option> ))} </select> @@ -210,7 +220,7 @@ export function LandingPage() { disabled={!hasRunners || loading || !installationsReady} title={ !hasRunners - ? 'No available runners. Install and authenticate at least one runner in Settings.' + ? 'No available agent installations. Add and configure at least one in Settings.' : undefined } onClick={handleStart} @@ -221,7 +231,7 @@ export function LandingPage() { {!hasRunners && ( <span className="no-runners-msg"> - No available runners. Open Settings to install and authenticate a runner. + No available agent installations. Open Settings to add and configure one. </span> )} </div> diff --git a/frontend/src/components/Notification.tsx b/frontend/src/components/Notification.tsx index bc1ef70..61561c8 100644 --- a/frontend/src/components/Notification.tsx +++ b/frontend/src/components/Notification.tsx @@ -1,21 +1,24 @@ import { useEffect, useState } from 'react' -import { useStore, NotificationEntry } from '../store/index' +import { useStore, Notification as NotificationData } from '../store/index' -function NotificationItem({ entry }: { entry: NotificationEntry }) { - const dismissNotification = useStore(s => s.dismissNotification) +function NotificationItem({ entry }: { entry: NotificationData }) { const [fading, setFading] = useState(false) + const [hidden, setHidden] = useState(false) + // Server notifications are append-only — auto-dismiss after timeout via local state useEffect(() => { const fadeTimer = setTimeout(() => setFading(true), 4700) - const removeTimer = setTimeout(() => dismissNotification(entry.id), 5000) + const hideTimer = setTimeout(() => setHidden(true), 5000) return () => { clearTimeout(fadeTimer) - clearTimeout(removeTimer) + clearTimeout(hideTimer) } - }, [entry.id, dismissNotification]) + }, []) + + if (hidden) return null return ( - <div className={`notification ${entry.severity}${fading ? ' fade-out' : ''}`}> + <div className={`notification ${entry.level}${fading ? ' fade-out' : ''}`}> {entry.message} </div> ) @@ -26,8 +29,8 @@ export function Notification() { return ( <div id="notifications"> - {notifications.map(n => ( - <NotificationItem key={n.id} entry={n} /> + {notifications.map((n, i) => ( + <NotificationItem key={`${n.timestampMs}-${i}`} entry={n} /> ))} </div> ) diff --git a/frontend/src/components/PillStrip.tsx b/frontend/src/components/PillStrip.tsx index c9453d2..65d206a 100644 --- a/frontend/src/components/PillStrip.tsx +++ b/frontend/src/components/PillStrip.tsx @@ -1,8 +1,14 @@ +import { useMemo } from 'react' import { useStore, ALL_PHASES } from '../store/index' export function PillStrip() { - const phase = useStore(s => s.phase) - const donePhases = useStore(s => s.donePhases) + const phase = useStore(s => s.run?.phase ?? '') + + // Derive done phases locally — frontend-only computation from the phase string + const donePhases = useMemo(() => { + const idx = ALL_PHASES.indexOf(phase) + return idx === -1 ? [...ALL_PHASES] : ALL_PHASES.slice(0, idx) + }, [phase]) return ( <div className="pill-strip"> diff --git a/frontend/src/components/SettingsOverlay.tsx b/frontend/src/components/SettingsOverlay.tsx index 2decee6..0e4725e 100644 --- a/frontend/src/components/SettingsOverlay.tsx +++ b/frontend/src/components/SettingsOverlay.tsx @@ -24,14 +24,14 @@ function getThinkingModes(runners: RunnerInfo[], rt: string, model: string) { function ProfileForm({ initialName, - initialTiers, + initialRunnerType, // best-effort from stored tier string isEdit, runners, onSave, onCancel, }: { initialName: string - initialTiers: TierMap + initialRunnerType: string // pre-populate runner dropdown when editing isEdit: boolean runners: RunnerInfo[] onSave: () => void @@ -41,7 +41,7 @@ function ProfileForm({ const [tiers, setTiers] = useState<TierMap>(() => { const t: TierMap = {} for (const tier of TIER_NAMES) { - t[tier] = initialTiers[tier] ?? { runner_type: '', model: '', thinking: '' } + t[tier] = { runner_type: tier === 'strong' ? initialRunnerType : '', model: '', thinking: '' } } return t }) @@ -314,10 +314,19 @@ export function SettingsOverlay() { const setSettingsOpen = useStore(s => s.setSettingsOpen) // Read all config from the store (fed by SSE events — always current) - const profiles = useStore(s => s.configProfiles) - const installations = useStore(s => s.configInstallations) - const runners = useStore(s => s.configRunners) - const scoutConcurrency = useStore(s => s.configScoutConcurrency) + const profilesDict = useStore(s => s.settings.profiles) + const installationsDict = useStore(s => s.settings.installations) + const scoutConcurrency = useStore(s => s.settings.defaultScoutConcurrency) + + const profiles = Object.values(profilesDict) + const installations = Object.values(installationsDict) + + // Probe runner info is not in the projection store (only availability flags + // are stored). Fetch it once on open for the profile/installation forms. + const [runners, setRunners] = useState<RunnerInfo[]>([]) + useEffect(() => { + api.getProbeInfo().then(data => setRunners(data.runners ?? [])) + }, []) const availableRunners = runners.filter(r => r.available) @@ -358,10 +367,10 @@ export function SettingsOverlay() { // Group installations by runner type const installationsByType: Record<string, Installation[]> = {} for (const inst of installations) { - if (!installationsByType[inst.runner_type]) { - installationsByType[inst.runner_type] = [] + if (!installationsByType[inst.runnerType]) { + installationsByType[inst.runnerType] = [] } - installationsByType[inst.runner_type].push(inst) + installationsByType[inst.runnerType].push(inst) } const runnerTypes = Object.keys(installationsByType).sort() @@ -371,13 +380,8 @@ export function SettingsOverlay() { : runnerTypes[0] ?? null const currentTabInstallations = currentTab ? installationsByType[currentTab] ?? [] : [] - const editingProfileData = editingProfile - ? profiles.find(p => p.name === editingProfile) - : null - - const editingInstData = editingInstallation - ? installations.find(i => i.alias === editingInstallation) - : null + const editingProfileData = editingProfile ? profilesDict[editingProfile] : null + const editingInstData = editingInstallation ? installationsDict[editingInstallation] : null return ( <div className="settings-overlay"> @@ -402,12 +406,12 @@ export function SettingsOverlay() { <div key={p.name} className="profile-row"> <span className="profile-row-name"> {p.name} - {p.read_only && ' [locked]'} + {p.readOnly && ' [locked]'} </span> <span className="profile-row-tiers"> {tierSummary(p.tiers)} </span> - {!p.read_only && ( + {!p.readOnly && ( <span className="profile-row-actions"> <button className="btn btn-secondary" @@ -434,7 +438,7 @@ export function SettingsOverlay() { {editingProfile && editingProfileData && ( <ProfileForm initialName={editingProfile} - initialTiers={editingProfileData.tiers} + initialRunnerType={Object.values(editingProfileData.tiers)[0] ?? ''} isEdit runners={availableRunners} onSave={() => setEditingProfile(null)} @@ -456,7 +460,7 @@ export function SettingsOverlay() { ) : ( <ProfileForm initialName="" - initialTiers={{}} + initialRunnerType="" isEdit={false} runners={availableRunners} onSave={() => setShowNewProfile(false)} @@ -497,10 +501,11 @@ export function SettingsOverlay() { <div className="install-row-info"> <span className="install-row-alias">{inst.alias}</span> {isDefault && <span className="install-row-badge">default</span>} + {inst.available && <span className="install-row-badge">available</span>} </div> <span className="install-row-path"> {inst.binary || '--'} - {inst.extra_args && inst.extra_args.length > 0 && ` ${inst.extra_args.join(' ')}`} + {inst.extraArgs && inst.extraArgs.length > 0 && ` ${inst.extraArgs.join(' ')}`} </span> <span className="profile-row-actions"> <button @@ -527,12 +532,12 @@ export function SettingsOverlay() { ) })} - {editingInstallation && editingInstData && editingInstData.runner_type === currentTab && ( + {editingInstallation && editingInstData && editingInstData.runnerType === currentTab && ( <InstallationForm initialAlias={editingInstallation} - initialRunnerType={editingInstData.runner_type} + initialRunnerType={editingInstData.runnerType} initialBinary={editingInstData.binary} - initialExtraArgs={editingInstData.extra_args} + initialExtraArgs={editingInstData.extraArgs} isEdit allRunners={runners} onSave={() => setEditingInstallation(null)} diff --git a/frontend/src/components/StatusSidebar.tsx b/frontend/src/components/StatusSidebar.tsx index a6845f6..b451658 100644 --- a/frontend/src/components/StatusSidebar.tsx +++ b/frontend/src/components/StatusSidebar.tsx @@ -1,21 +1,26 @@ +import { useMemo } from 'react' import { useStore } from '../store/index' import { useElapsed } from '../hooks/useElapsed' import { formatTokens } from '../utils' function AgentSection() { - const agent = useStore(s => s.primaryAgent) - const elapsed = useElapsed(agent?.startedAt ?? Date.now()) + const agents = useStore(s => s.run?.agents) + const primary = useMemo( + () => agents ? Object.values(agents).find(a => a.isPrimary && a.status === 'running') : null, + [agents] + ) + const elapsed = useElapsed(primary?.startedAtMs ?? Date.now()) - if (!agent) return null + if (!primary) return null return ( <> <div className="sidebar-agent"> - <div className="sidebar-agent-role">{agent.role}</div> - <div className="sidebar-agent-model">{agent.model ?? '--'}</div> - <div className="sidebar-agent-step">{agent.stepName || `step ${agent.step}`}</div> + <div className="sidebar-agent-role">{primary.role}</div> + <div className="sidebar-agent-model">{primary.model ?? '--'}</div> + <div className="sidebar-agent-step">{primary.stepName || `step ${primary.step}`}</div> <div className="sidebar-agent-stats"> - <span>{formatTokens(agent.tokensSent, agent.tokensReceived)}</span> + <span>{formatTokens(primary.conversation.inputTokens, primary.conversation.outputTokens)}</span> <span className="elapsed-value">{elapsed}</span> </div> </div> @@ -25,11 +30,14 @@ function AgentSection() { } export function StatusSidebar() { - const phase = useStore(s => s.phase) - const primaryAgent = useStore(s => s.primaryAgent) - const intakeProgress = useStore(s => s.intakeProgress) + const phase = useStore(s => s.run?.phase ?? '') + const agents = useStore(s => s.run?.agents) + const hasPrimary = useMemo( + () => agents ? Object.values(agents).some(a => a.isPrimary && a.status === 'running') : false, + [agents] + ) - const hasContent = primaryAgent !== null || phase + const hasContent = hasPrimary || phase return ( <aside className="status-sidebar"> @@ -42,20 +50,6 @@ export function StatusSidebar() { </div> )} - {intakeProgress?.subPhase && ( - <div className="sidebar-section"> - <div className="sidebar-label">Sub-phase</div> - <div className="sidebar-value">{intakeProgress.subPhase}</div> - </div> - )} - - {intakeProgress?.summary && ( - <> - <div className="sidebar-divider" /> - <div className="sidebar-summary">{intakeProgress.summary}</div> - </> - )} - {!hasContent && ( <> <div className="sidebar-heading">Status</div> diff --git a/frontend/src/components/interactions/ArtifactReview.tsx b/frontend/src/components/interactions/ArtifactReview.tsx index 68bf07b..63f21e8 100644 --- a/frontend/src/components/interactions/ArtifactReview.tsx +++ b/frontend/src/components/interactions/ArtifactReview.tsx @@ -3,35 +3,25 @@ import { useStore } from '../../store/index' import * as api from '../../api/client' export function ArtifactReview() { - const interaction = useStore(s => s.activeInteraction) - const addNotification = useStore(s => s.addNotification) + const focus = useStore(s => s.run?.focus) const [feedback, setFeedback] = useState('') + const [submitError, setSubmitError] = useState<string | null>(null) - if (!interaction || interaction.type !== 'artifact-review') return null + if (!focus || focus.type !== 'review') return null - const { content, description, token } = interaction + const { content, description, token } = focus const handleAccept = async () => { const res = await api.submitArtifactReview('', true, token) if (!res.ok) { - addNotification({ - id: crypto.randomUUID(), - type: 'submit_error', - severity: 'error', - message: res.message ?? 'Failed to accept artifact', - }) + setSubmitError(res.message ?? 'Failed to accept artifact') } } const handleSendFeedback = async () => { const res = await api.submitArtifactReview(feedback, false, token) if (!res.ok) { - addNotification({ - id: crypto.randomUUID(), - type: 'submit_error', - severity: 'error', - message: res.message ?? 'Failed to send feedback', - }) + setSubmitError(res.message ?? 'Failed to send feedback') } } @@ -55,6 +45,8 @@ export function ArtifactReview() { onChange={e => setFeedback(e.target.value)} /> + {submitError && <div className="no-runners-msg">{submitError}</div>} + <div className="form-actions"> <button id="btn-send-feedback" diff --git a/frontend/src/components/interactions/AskWizard.tsx b/frontend/src/components/interactions/AskWizard.tsx index f28e050..94b2243 100644 --- a/frontend/src/components/interactions/AskWizard.tsx +++ b/frontend/src/components/interactions/AskWizard.tsx @@ -2,6 +2,20 @@ import { useState } from 'react' import { useStore, AskQuestion } from '../../store/index' import * as api from '../../api/client' +// Normalize raw question options from LLM output. Options may arrive as strings +// or dicts with varying key names. This is data cleaning for LLM output +// variability — not business logic. +function normalizeOptions( + rawOpts: (string | Record<string, unknown>)[], +): { value: string; label: string; recommended?: boolean }[] { + return rawOpts.map(o => { + if (typeof o === 'string') return { value: o, label: o } + const label = String(o['label'] ?? o['text'] ?? o['value'] ?? o['option'] ?? '') + const value = String(o['value'] ?? o['label'] ?? o['text'] ?? label) + return { value, label, recommended: (o['recommended'] as boolean) ?? false } + }) +} + interface AnswerMap { [qIdx: number]: string | string[] | null } @@ -51,7 +65,8 @@ function QuestionCard({ } } - + // Normalize options at render time to handle LLM output variability + const opts = normalizeOptions(question.options as (string | Record<string, unknown>)[]) return ( <div className="question-card"> @@ -66,7 +81,7 @@ function QuestionCard({ <div className="question-multi-hint">Select all that apply</div> )} <div className="options-list"> - {question.options.map(opt => ( + {opts.map(opt => ( <div key={opt.value} className={`option${selected.includes(opt.value) ? ' selected' : ''}${opt.recommended ? ' recommended' : ''}`} @@ -104,15 +119,14 @@ function QuestionCard({ } export function AskWizard() { - const interaction = useStore(s => s.activeInteraction) - const addNotification = useStore(s => s.addNotification) - + const focus = useStore(s => s.run?.focus) const [currentIdx, setCurrentIdx] = useState(0) const [answers, setAnswers] = useState<AnswerMap>({}) + const [submitError, setSubmitError] = useState<string | null>(null) - if (!interaction || interaction.type !== 'ask') return null + if (!focus || focus.type !== 'question') return null - const { questions, token } = interaction + const { questions, token } = focus const total = questions.length const handleAnswer = (qIdx: number, val: string | string[] | null) => { @@ -131,12 +145,7 @@ export function AskWizard() { const finalAnswers = questions.map((_, i) => answers[i] ?? null) const res = await api.submitAnswer(finalAnswers, token) if (!res.ok) { - addNotification({ - id: crypto.randomUUID(), - type: 'submit_error', - severity: 'error', - message: res.message ?? 'Failed to submit answers', - }) + setSubmitError(res.message ?? 'Failed to submit answers') } } @@ -145,12 +154,7 @@ export function AskWizard() { const finalAnswers = questions.map((_, i) => defaults[i] ?? null) const res = await api.submitAnswer(finalAnswers, token) if (!res.ok) { - addNotification({ - id: crypto.randomUUID(), - type: 'submit_error', - severity: 'error', - message: res.message ?? 'Failed to submit defaults', - }) + setSubmitError(res.message ?? 'Failed to submit defaults') } } @@ -169,6 +173,8 @@ export function AskWizard() { onAnswer={handleAnswer} /> + {submitError && <div className="no-runners-msg">{submitError}</div>} + <div className="form-actions"> {currentIdx > 0 && ( <button className="btn btn-secondary" onClick={handleBack}> diff --git a/frontend/src/components/interactions/WorkflowDecision.tsx b/frontend/src/components/interactions/WorkflowDecision.tsx index fe4b79c..9ef5195 100644 --- a/frontend/src/components/interactions/WorkflowDecision.tsx +++ b/frontend/src/components/interactions/WorkflowDecision.tsx @@ -3,33 +3,23 @@ import { useStore } from '../../store/index' import * as api from '../../api/client' export function WorkflowDecision() { - const interaction = useStore(s => s.activeInteraction) - const addNotification = useStore(s => s.addNotification) + const focus = useStore(s => s.run?.focus) const [selectedPhase, setSelectedPhase] = useState<string | null>(null) const [context, setContext] = useState('') + const [submitError, setSubmitError] = useState<string | null>(null) - if (!interaction || interaction.type !== 'workflow-decision') return null + if (!focus || focus.type !== 'decision') return null - const { chat_turns, token } = interaction + const { chatTurns, token } = focus const handleContinue = async () => { if (!selectedPhase) { - addNotification({ - id: crypto.randomUUID(), - type: 'validation', - severity: 'warning', - message: 'Please select a phase before continuing', - }) + setSubmitError('Please select a phase before continuing') return } const res = await api.submitWorkflowDecision(selectedPhase, context, token) if (!res.ok) { - addNotification({ - id: crypto.randomUUID(), - type: 'submit_error', - severity: 'error', - message: res.message ?? 'Failed to submit decision', - }) + setSubmitError(res.message ?? 'Failed to submit decision') } } @@ -37,7 +27,7 @@ export function WorkflowDecision() { <div className="phase-content"> <div className="phase-inner"> <div className="workflow-chat"> - {chat_turns.map((turn, i) => ( + {chatTurns.map((turn, i) => ( <div key={i} className="workflow-turn"> {turn.role === 'orchestrator' ? ( <> @@ -88,6 +78,7 @@ export function WorkflowDecision() { value={context} onChange={e => setContext(e.target.value)} /> + {submitError && <div className="no-runners-msg">{submitError}</div>} <div className="form-actions"> <button id="btn-workflow-continue" From 0cf254153848ff34e8b35637d38a108c0402e220 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 17:52:20 +0700 Subject: [PATCH 258/412] update docs for JSON Patch architecture projections.md: rewrite for new model, SSE protocol, fold rules, camelCase wire format, localhost assumption. architecture.md: add invariant 7 (server-authoritative fold). token-streaming.md: update terminology. --- docs/architecture.md | 66 ++- docs/projections.md | 1096 ++++++++++++++++++++++++++------------- docs/token-streaming.md | 63 ++- 3 files changed, 805 insertions(+), 420 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 2674478..2ad4be7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -13,8 +13,8 @@ principles, and pitfalls that govern the codebase. - [Token Streaming](./token-streaming.md) -- runner stdout parsing, SSE delta path - [State & Driver](./state.md) -- the driver/LLM boundary, JSON vs markdown ownership, epic and story state, routing rules -- [Projections](./projections.md) -- versioned event log, fold function, - projection shape, SSE protocol, version-negotiated catch-up +- [Projections](./projections.md) -- versioned event log, pure fold, JSON Patch + protocol, projection model, camelCase wire format - [Intake Loop](./intake-loop.md) -- confidence-gated investigation loop, non-linear step progression, prompt engineering principles - [Epic Brief](./epic-brief.md) -- brief artifact, brief-writer subagent, downstream references @@ -143,6 +143,26 @@ observation (audit). See [subagents.md -- Task Manifest](./subagents.md#task-manifest) for the `task.json` schema and spawn flow. +### 7. Server-authoritative projection + +The fold runs only in Python. The frontend applies server-computed JSON Patches +mechanically -- it has no fold logic, no event interpretation, and no business +rules. When the frontend's view of state differs from the backend's, the bug is +in the fold or the patch computation -- not in the frontend. + +``` +push_event() -> fold() -> to_wire() -> make_patch() -> broadcast to subscribers + | + Browser receives patch, + applies applyPatch(store, patch) +``` + +**Why:** Maintaining two fold implementations (Python + TypeScript) requires +disciplinary synchronization. Any divergence produces subtle display bugs that +are hard to trace. JSON Patch makes correctness structural: one fold, one +source of truth, mechanical application on the client. + + --- ## Atomic Writes @@ -225,9 +245,9 @@ State flows from LLM tool calls to the browser through the projection system. | [push_event() called with workflow-level event] | -[ProjectionStore: append to log, fold projection, broadcast to SSE subscribers] +[ProjectionStore: fold projection, compute JSON Patch, broadcast to subscribers] | -[Browser receives versioned SSE event, applies frontend fold] +[Browser receives patch, applies applyPatch(store, patch) — no interpretation] ``` ### Concrete example: `koan_complete_step` @@ -239,30 +259,32 @@ LLM calls koan_complete_step({ thoughts: "..." }) via MCP -> audit fold: projection.step = 2, projection.step_name = "Decompose" -> write_state(audit projection) -> state.json -> push_event("agent_step_advanced", {step: 2, step_name: "Decompose"}, agent_id="abc") - -> ProjectionStore appends event v=47, folds projection, broadcasts to SSE subscribers - -> browser receives: event: agent_step_advanced / data: {"version": 47, "agent_id": "abc", ...} - -> frontend fold: primaryAgent.step = 2, primaryAgent.stepName = "Decompose" + -> ProjectionStore: append to log, fold projection, compute JSON Patch diff + -> patch: [{op: "replace", path: "/run/agents/abc/step", value: 2}, ...] + -> broadcast patch dict to all SSE subscribers + -> browser receives: event: patch / data: {"version": 47, "patch": [...]} + -> applyPatch(store, patch) — store.run.agents.abc.step is now 2 -> returns step 2 instructions as MCP tool result ``` -### Version-negotiated catch-up +### Snapshot on reconnect -The `/events` endpoint accepts `?since=N`. On first connect (`since=0`), the -server sends a `snapshot` SSE event containing the full materialized projection -at the current version. On reconnect (`since=N`), the server replays events -with version > N, then streams live events. +The `/events` endpoint accepts `?since=N`. If `since` matches the server's +current version, the client is up to date and only live patches are streamed. +Otherwise — on first connect, page reload, connection drop, or server restart +— a fresh snapshot is sent, then live patches follow. ``` event: snapshot -data: {"version": 42, "state": { ...full projection... }} +data: {"version": 42, "state": { ...full projection in camelCase... }} -event: agent_spawned -data: {"version": 43, "agent_id": "...", "role": "intake", ...} +event: patch +data: {"type": "patch", "version": 43, "patch": [{...}, ...]} ``` -This ensures the browser always has complete state after a page reload or -network drop, without requiring a full page reload or losing accumulated state -(activity log, notifications, streaming buffer). +All reconnect scenarios are handled identically. The client does not distinguish +between a brief disconnect and a server restart — it receives a snapshot and +renders from it. --- @@ -408,7 +430,7 @@ append + fold + atomic-write cycles per second for data that has no persistence value. The runner stdout parsing path exists for exactly this case. See [token-streaming.md](./token-streaming.md). -Note: `stream_delta` events (the projection system's name for token deltas) DO -go through the projection fold, but the fold only appends to an in-memory -string — no disk I/O. The distinction is between the audit pipeline (disk -writes per event) and the projection fold (in-memory only). +Note: `stream_delta` events (token deltas) DO go through the projection fold, +but the fold only updates an in-memory string (`pending_text` on the agent's +conversation) — no disk I/O. The distinction is between the audit pipeline +(disk writes per event) and the projection fold (in-memory only). diff --git a/docs/projections.md b/docs/projections.md index 99fc142..a810d82 100644 --- a/docs/projections.md +++ b/docs/projections.md @@ -1,8 +1,7 @@ # Projections How koan maintains frontend-visible state as a versioned event log with a -materialized projection, enabling full state recovery on page reload or -reconnect. +materialized projection, served to the browser as JSON Patch diffs over SSE. > Parent doc: [architecture.md](./architecture.md) @@ -16,15 +15,17 @@ The projection system maintains: workflow run, in order, with a monotonically increasing version number. 2. A **materialized projection** — the complete frontend-visible state derived by folding the event log with a pure function. -3. A **subscriber mechanism** — one `asyncio.Queue` per connected SSE client, +3. A **diff engine** — `jsonpatch.make_patch` computes RFC 6902 JSON Patch + operations between projection states, broadcast to SSE subscribers. +4. A **subscriber mechanism** — one `asyncio.Queue` per connected SSE client, fed from `push_event()`. -The `/events` SSE endpoint serves either a full snapshot (for new clients) or -a replay of missed events (for reconnecting clients), then streams live events. +The `/events` SSE endpoint sends a full snapshot on connect or reconnect, then +streams JSON Patch operations for every subsequent state change. -**Design invariant:** Events are facts about things that happened — not state -snapshots. The fold function derives state from facts. Derived state is never -stored as an event. +**Design invariant:** The fold runs only in Python. The frontend applies +server-computed patches mechanically — it has no fold logic, no event +interpretation, and no business rules. --- @@ -34,299 +35,619 @@ All events share a common envelope. `agent_id` is set when the event originates from a specific agent; `None` otherwise. ```python -EventType = Literal[ - # Lifecycle - "phase_started", "agent_spawned", "agent_spawn_failed", - "agent_step_advanced", "agent_exited", "workflow_completed", - # Activity - "tool_called", "tool_completed", "thinking", "stream_delta", "stream_cleared", - # Interactions - "questions_asked", "questions_answered", - "artifact_review_requested", "artifact_reviewed", - "workflow_decision_requested", "workflow_decided", - # Resources - "artifact_created", "artifact_modified", "artifact_removed", -] - class VersionedEvent(BaseModel): version: int # 1-based, monotonic - event_type: str # EventType string; stored as str so unknown types deserialise safely + event_type: str # one of the 37 event types (stored as str for forward compat) timestamp: str # ISO8601 UTC agent_id: str | None = None # originating agent, when known payload: dict # typed per event_type (see below) ``` -The log is append-only. Events are never modified or removed. The entire log -is held in memory for the duration of a workflow run. koan is one-shot (one -server instance per run), so there is no cross-run accumulation concern. +The log is append-only. Events are never modified or removed. The entire log is +held in memory for the duration of a workflow run. --- -## Event Types - -### Lifecycle events - -| Event | What happened | Payload fields | `agent_id` | -|---|---|---|---| -| `phase_started` | Driver began a workflow phase | `phase` | `None` | -| `agent_spawned` | A subagent process was launched | `role, model, is_primary` | set | -| `agent_spawn_failed` | Spawn attempted but failed (runner error) | `role, error_code, message, ?details` | `None` | -| `agent_step_advanced` | Subagent called `koan_complete_step` | `step, step_name, ?usage` | set | -| `agent_exited` | Subagent process terminated | `exit_code, ?error, ?usage` | set | -| `workflow_completed` | Entire workflow finished | `success, summary, ?error` | `None` | - -`agent_spawned` does not carry `step` — step 0 is implied. The first -`agent_step_advanced` is for step 1. `agent_exited` does not carry `is_primary` -— the fold looks up the agent in projection state. `workflow_completed` does -not carry the artifact list — consumers read `projection.artifacts`. - -### Activity events - -| Event | What happened | Payload fields | `agent_id` | -|---|---|---|---| -| `tool_called` | A tool was invoked | `call_id, tool, args, summary` | set | -| `tool_completed` | A tool call finished | `call_id, tool, ?result, ?summary` | set | -| `thinking` | LLM produced thinking tokens | `delta` | set | -| `stream_delta` | LLM produced output tokens | `delta` | set | -| `stream_cleared` | End-of-stream tombstone | (none) | set | - -`tool_called` and `tool_completed` are paired by `call_id` (UUID). `tool` is a -canonical normalized name (`read`, `bash`, `edit`, `grep`, -`koan_complete_step`, etc.). `args` and `result` are unstructured (`dict | str`) -because tool schemas vary across runners. - -MCP tool calls are authoritative — both `tool_called` and `tool_completed` are -emitted from the MCP endpoint. Stdout-parsed events are filtered to exclude -koan MCP tool names (which would otherwise duplicate). Agent-native tools (file -read, bash, etc.) are sourced from stdout with a synthetic `call_id`. - -`thinking` events are fire-and-forget incremental deltas. No started/ended -lifecycle — the client derives "thinking stopped" from the next non-thinking -event. +## Event Types (37 total) + +### Lifecycle (8) + +| Event | Payload | `agent_id` | +|-------|---------|-----------| +| `run_started` | `{profile, installations, scout_concurrency}` | `None` | +| `phase_started` | `{phase}` | `None` | +| `agent_spawned` | `{agent_id, role, label, model, is_primary, started_at_ms}` | set | +| `agent_spawn_failed` | `{role, error_code, message, details?}` | `None` | +| `agent_step_advanced` | `{step, step_name, usage?, total_steps?}` | set | +| `agent_exited` | `{exit_code, error?, usage?}` | set | +| `workflow_completed` | `{success, summary?, error?}` | `None` | +| `scout_queued` | `{scout_id, label, model?}` | `None` | + +`run_started` is emitted by `api_start_run` before the driver begins. It +creates the `Run` object in the projection with the frozen `RunConfig`. + +`agent_spawned` does not carry `step` — step 0 is implied. `agent_exited` does +not carry `is_primary` — the fold looks up the agent in `run.agents`. + +### Activity (11) + +| Event | Payload | `agent_id` | +|-------|---------|-----------| +| `tool_called` | `{call_id, tool, args, summary}` | set | +| `tool_read` | `{call_id, file, lines}` | set | +| `tool_write` | `{call_id, file}` | set | +| `tool_edit` | `{call_id, file}` | set | +| `tool_bash` | `{call_id, command}` | set | +| `tool_grep` | `{call_id, pattern}` | set | +| `tool_ls` | `{call_id, path}` | set | +| `tool_completed` | `{call_id, tool, result?}` | set | +| `thinking` | `{delta}` | set | +| `stream_delta` | `{delta}` | set | +| `stream_cleared` | `{}` | set | + +`tool_called` and the typed tool events (`tool_read`, `tool_bash`, etc.) are +mutually exclusive for any given tool invocation. The runner's stream parser +emits a typed event when it can extract structured metadata (file path, command, +pattern). It falls back to `tool_called` for unknown or custom MCP tools. The +fold never receives both for the same `call_id`. + +`tool_called` and `tool_completed` are paired by `call_id` (UUID). `in_flight` +on the conversation entry is `True` until `tool_completed` arrives. + +`thinking` events are incremental deltas. The fold accumulates them into +`agent.conversation.pending_thinking`; the completed `ThinkingEntry` is created +on the next transition (tool call, step advance, or stream delta). + +### Focus (6) + +| Event | Payload | `agent_id` | +|-------|---------|-----------| +| `questions_asked` | `{token, questions}` | set | +| `questions_answered` | `{token, cancelled, answers?}` | set | +| `artifact_review_requested` | `{token, path, description, content}` | set | +| `artifact_reviewed` | `{token, cancelled, accepted?, response?}` | set | +| `workflow_decision_requested` | `{token, chat_turns}` | set | +| `workflow_decided` | `{token, cancelled, decision?}` | set | + +These events transition `run.focus` between variants of the `Focus` union. +Cancellation (`cancelled: true`) occurs when the agent exits while the +interaction is pending — there is no separate cancellation event type. + +### Resources (3) + +| Event | Payload | `agent_id` | +|-------|---------|-----------| +| `artifact_created` | `{path, size, modified_at}` | if known | +| `artifact_modified` | `{path, size, modified_at}` | if known | +| `artifact_removed` | `{path}` | if known | + +`agent_id` is the primary agent at scan time (approximate — scanning happens at +phase boundaries, not on individual file writes). `build_artifact_diff()` in +`koan/events.py` compares old and new artifact sets and emits individual events +for each difference. + +### Settings (9) -`stream_cleared` is emitted at the end of a primary agent's stdout streaming -loop (before `agent_exited`) and at the start of a new primary agent's -streaming loop (to reset for the new agent). +| Event | Payload | +|-------|---------| +| `probe_completed` | `{results: {alias: available_bool, ...}}` | +| `installation_created` | `{alias, runner_type, binary, extra_args}` | +| `installation_modified` | `{alias, runner_type, binary, extra_args}` | +| `installation_removed` | `{alias}` | +| `profile_created` | `{name, read_only, tiers}` | +| `profile_modified` | `{name, read_only, tiers}` | +| `profile_removed` | `{name}` | +| `default_profile_changed` | `{name}` | +| `default_scout_concurrency_changed` | `{value}` | -### Interaction events +`probe_completed` carries availability flags by installation alias, not a full +runner list. The fold uses this to set `installation.available` on each known +installation in `settings.installations`. -| Event | What happened | Payload fields | `agent_id` | -|---|---|---|---| -| `questions_asked` | Agent asked the user questions | `token, questions` | set | -| `questions_answered` | User answered (or interaction cancelled) | `token, ?answers, cancelled` | set | -| `artifact_review_requested` | Agent requested artifact review | `token, path, description, content` | set | -| `artifact_reviewed` | User reviewed artifact (or cancelled) | `token, ?accepted, ?response, cancelled` | set | -| `workflow_decision_requested` | Orchestrator proposed next phases | `token, chat_turns` | set | -| `workflow_decided` | User chose next phase (or cancelled) | `token, ?decision, cancelled` | set | +--- -`agent_id` on resolution events is the agent whose interaction was resolved -(same as the requesting agent). Cancellation (`cancelled: true`) occurs when -the agent exits while the interaction is pending — there is no separate -cancellation event type. +## The Projection -### Resource events +The fold is: `fold(Projection, VersionedEvent) → Projection`. It is a pure +function — same event sequence produces the same projection. No I/O, no side +effects. Unknown event types return the projection unchanged (logged warning). -| Event | What happened | Payload fields | `agent_id` | -|---|---|---|---| -| `artifact_created` | New file appeared in epic directory | `path, size, modified_at` | if known | -| `artifact_modified` | Existing file was modified | `path, size, modified_at` | if known | -| `artifact_removed` | File was removed from epic directory | `path` | if known | +### KoanBaseModel — wire format base class -`agent_id` is the primary agent at scan time (approximate — scanning happens -at phase boundaries, not on individual file writes). `build_artifact_diff()` in -`koan/events.py` compares old and new artifact sets and emits individual events -for each difference. +All projection models inherit from `KoanBaseModel`: + +```python +from pydantic import ConfigDict +from pydantic.alias_generators import to_camel + +class KoanBaseModel(BaseModel): + model_config = ConfigDict( + alias_generator=to_camel, # snake_case → camelCase at serialization + populate_by_name=True, # Python code uses snake_case; only JSON output is camelCase + ) + + def to_wire(self) -> dict: + """Serialize for snapshots and JSON Patch computation. + + Always produces camelCase keys. Call only at serialization boundaries: + - push_event(): to_wire() before and after fold to compute the diff + - get_snapshot(): to_wire() once for the snapshot payload + Never call model_dump() directly on projection objects. + """ + return self.model_dump(by_alias=True) +``` -### Optional usage metadata +Python fold code uses snake_case attributes (`agent.conversation.pending_thinking`). +The JSON output and all patch paths are camelCase (`pendingThinking`, +`isThinking`, `defaultScoutConcurrency`). -Token/usage fields are optional on events that naturally carry them: +### Projection model hierarchy + +``` +Projection +├── settings: Settings +│ ├── installations: dict[str, Installation] # alias → Installation +│ ├── profiles: dict[str, Profile] # name → Profile +│ ├── default_profile: str +│ └── default_scout_concurrency: int +├── run: Run | None +│ ├── config: RunConfig # frozen at run_started +│ ├── phase: str +│ ├── agents: dict[str, Agent] # agent_id → Agent (all statuses) +│ │ └── conversation: Conversation +│ │ ├── entries: list[ConversationEntry] # discriminated union of 10 types +│ │ ├── pending_thinking: str +│ │ ├── pending_text: str +│ │ ├── is_thinking: bool +│ │ ├── input_tokens: int +│ │ └── output_tokens: int +│ ├── focus: Focus | None # discriminated union of 4 variants +│ ├── artifacts: dict[str, ArtifactInfo] # path → ArtifactInfo +│ └── completion: CompletionInfo | None +└── notifications: list[Notification] +``` + +### Settings ```python -class Usage(BaseModel): - input_tokens: int = 0 # tokens sent to LLM - output_tokens: int = 0 # tokens received from LLM +class Installation(KoanBaseModel): + alias: str # unique key: "claude-default", "claude-fast" + runner_type: str # "claude" | "codex" | "gemini" + binary: str # resolved path: "/usr/local/bin/claude" + extra_args: list[str] = [] + available: bool = False # probe result: binary exists and responds + +class Profile(KoanBaseModel): + name: str + read_only: bool = False + tiers: dict[str, str] = {} # role → installation alias + +class Settings(KoanBaseModel): + installations: dict[str, Installation] = {} + profiles: dict[str, Profile] = {} + default_profile: str = "balanced" + default_scout_concurrency: int = 8 ``` -Present on: `agent_step_advanced`, `agent_exited`, `tool_called`, -`tool_completed`. The fold accumulates these into per-agent token totals. +`Settings` represents what is *available* — it persists across runs to +`~/.koan/config.json` and describes the user's configured environment. +`available` on `Installation` is ephemeral — re-probed each server start. ---- +### Run configuration -## The Projection +```python +class RunConfig(KoanBaseModel): + profile: str # which profile was selected + installations: dict[str, str] # role → installation alias for this run + scout_concurrency: int +``` + +`RunConfig` is frozen at `run_started` and never modified during the run. + +| | Settings | RunConfig | +|--|---------|----------| +| Lifetime | Persists across runs | Single run | +| Mutation | Settings overlay, any time | Frozen at run start | +| `default_profile` | Pre-selected for next run | — | +| `profile` | — | Which profile this run uses | +| `scout_concurrency` | Default for next run | What this run uses | -The fold reduces `(Projection, VersionedEvent) → Projection`. It is a pure -function: same event sequence → same projection. No I/O, no side effects. -Unknown event types return the projection unchanged (logged warning). +### Agent + +All agents — primary, scouts, queued — live in `run.agents`, keyed by +`agent_id`. Status is a state machine: `queued → running → done | failed`. ```python -class AgentProjection(BaseModel): +class Agent(KoanBaseModel): + # Identity agent_id: str role: str + label: str = "" model: str | None = None + is_primary: bool = False + + # Lifecycle + status: Literal["queued", "running", "done", "failed"] = "queued" + error: str | None = None + started_at_ms: int = 0 + + # Progress step: int = 0 step_name: str = "" - input_tokens: int = 0 - output_tokens: int = 0 + last_tool: str = "" # summary of last tool call, for monitor display -class Projection(BaseModel): - # Run state - run_started: bool = False - phase: str = "" + # Content + conversation: Conversation = Conversation() +``` - # Agents - primary_agent: AgentProjection | None = None - scouts: dict[str, AgentProjection] = {} # keyed by agent_id - completed_agents: list[AgentProjection] = [] # agents that exited (preserves final token totals) +Agents are never removed from `run.agents` — status transitions to `done` or +`failed` on exit. Dict keys are stable, which keeps JSON Patch paths valid +across insertions. - # Activity (raw events appended as-is) - activity_log: list[dict] = [] - stream_buffer: str = "" # accumulated stream_delta text +### Conversation + +Per-agent. The primary agent's conversation is rendered in the activity feed. + +```python +class Conversation(KoanBaseModel): + entries: list[ConversationEntry] = [] + pending_thinking: str = "" # accumulating thinking, not yet flushed to ThinkingEntry + pending_text: str = "" # accumulating output text, not yet flushed to TextEntry + is_thinking: bool = False # True while thinking deltas are arriving + input_tokens: int = 0 + output_tokens: int = 0 +``` - # Interactions - active_interaction: dict | None = None +`pending_thinking` and `pending_text` hold incomplete LLM output that will +become conversation entries on the next state transition. "Flush" means: if the +field is non-empty, create a completed entry (ThinkingEntry or TextEntry), +append it to `entries`, reset the field to `""`. - # Resources - artifacts: dict[str, dict] = {} # keyed by path - notifications: list[dict] = [] # derived from error events +### ConversationEntry — discriminated union - # Completion - completion: dict | None = None +```python +class ThinkingEntry(KoanBaseModel): + type: Literal["thinking"] = "thinking" + content: str # full accumulated thinking text + +class TextEntry(KoanBaseModel): + type: Literal["text"] = "text" + text: str # full accumulated output text + +class StepEntry(KoanBaseModel): + type: Literal["step"] = "step" + step: int + step_name: str + total_steps: int | None = None + +class BaseToolEntry(KoanBaseModel): + call_id: str # unique per tool invocation + in_flight: bool # True until tool_completed + +class ToolReadEntry(BaseToolEntry): + type: Literal["tool_read"] = "tool_read" + file: str + lines: str = "" # line range, e.g. "1-50" + +class ToolWriteEntry(BaseToolEntry): + type: Literal["tool_write"] = "tool_write" + file: str + +class ToolEditEntry(BaseToolEntry): + type: Literal["tool_edit"] = "tool_edit" + file: str + +class ToolBashEntry(BaseToolEntry): + type: Literal["tool_bash"] = "tool_bash" + command: str + +class ToolGrepEntry(BaseToolEntry): + type: Literal["tool_grep"] = "tool_grep" + pattern: str + +class ToolLsEntry(BaseToolEntry): + type: Literal["tool_ls"] = "tool_ls" + path: str + +class ToolGenericEntry(BaseToolEntry): + type: Literal["tool_generic"] = "tool_generic" + tool_name: str # original tool name from the LLM + summary: str = "" + +ConversationEntry = Annotated[ + ThinkingEntry | TextEntry | StepEntry | + ToolReadEntry | ToolWriteEntry | ToolEditEntry | + ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry, + Field(discriminator="type"), +] ``` -`done_phases` is NOT in the projection — it is a frontend-only derivation from -`phase` using the frontend's `ALL_PHASES` ordering constant. +### Focus — discriminated union -`notifications` is derived by the fold from `agent_spawn_failed` and -`agent_exited` with error. It is not a dedicated event type — these are -projections of facts, preserved in the snapshot so they survive page refresh. +`run.focus` determines what the main content area renders. Every variant +carries `agent_id` — the conversation is always the backdrop. -### Fold cases +```python +class ConversationFocus(KoanBaseModel): + type: Literal["conversation"] = "conversation" + agent_id: str -**Lifecycle:** +class QuestionFocus(KoanBaseModel): + type: Literal["question"] = "question" + agent_id: str + token: str + questions: list[dict] # raw LLM output, not validated by fold -| Event | Projection update | -|---|---| -| `phase_started` | `phase = event.phase`, `run_started = True` | -| `agent_spawned` | if `is_primary`: set `primary_agent`; else: add to `scouts[agent_id]` | -| `agent_spawn_failed` | append to `notifications` | -| `agent_step_advanced` | update `step`, `step_name` on agent; if `usage`: accumulate tokens | -| `agent_exited` | accumulate final `usage` tokens, move agent to `completed_agents`; if primary: `primary_agent = None`; if scout: remove from `scouts`; if `error`: append to `notifications` | -| `workflow_completed` | `completion = event.payload` | +class ReviewFocus(KoanBaseModel): + type: Literal["review"] = "review" + agent_id: str + token: str + path: str + description: str + content: str -**Activity:** +class DecisionFocus(KoanBaseModel): + type: Literal["decision"] = "decision" + agent_id: str + token: str + chat_turns: list[dict] # raw LLM output, not validated by fold -| Event | Projection update | -|---|---| -| `tool_called` | append raw event to `activity_log`; if `usage`: accumulate tokens on agent | -| `tool_completed` | append raw event to `activity_log`; if `usage`: accumulate tokens on agent | -| `thinking` | append raw event to `activity_log` | -| `stream_delta` | `stream_buffer += event.delta` | -| `stream_cleared` | `stream_buffer = ""` | +Focus = Annotated[ + ConversationFocus | QuestionFocus | ReviewFocus | DecisionFocus, + Field(discriminator="type"), +] +``` -**Interactions:** +`run.focus` is `None` before the first agent spawns. Once the primary agent +spawns, `focus` is always set — every state of the main content area is +explicit. -| Event | Projection update | -|---|---| -| `questions_asked` | `active_interaction = {interaction_type: "questions_asked", **payload}` | -| `questions_answered` | `active_interaction = None` | -| `artifact_review_requested` | `active_interaction = {interaction_type: "artifact_review_requested", **payload}` | -| `artifact_reviewed` | `active_interaction = None` | -| `workflow_decision_requested` | `active_interaction = {interaction_type: "workflow_decision_requested", **payload}` | -| `workflow_decided` | `active_interaction = None` | +### Supporting types -The fold stores `interaction_type` (the event type string) alongside the payload -so the frontend can discriminate which component to render without duck-typing -payload fields. +```python +class ArtifactInfo(KoanBaseModel): + path: str # relative to epic directory + size: int # bytes + modified_at: int = 0 # milliseconds since epoch + +class CompletionInfo(KoanBaseModel): + success: bool + summary: str = "" + error: str | None = None + +class Notification(KoanBaseModel): + message: str + level: Literal["info", "warning", "error"] = "info" + timestamp_ms: int +``` -**Resources:** +### Complete Projection -| Event | Projection update | -|---|---| -| `artifact_created` | add `{path, size, modified_at}` to `artifacts[path]` | -| `artifact_modified` | update `artifacts[path]` with new `size`, `modified_at` | -| `artifact_removed` | delete `artifacts[path]` | +```python +class Projection(KoanBaseModel): + settings: Settings = Settings() + run: Run | None = None + notifications: list[Notification] = [] +``` -**Unknown event type** → return projection unchanged, log warning. +`run is None` → show landing page. `run.completion is not None` → run finished +(results remain visible). `run` is replaced wholesale on the next `run_started` +event. -**Unknown `agent_id`** (event references an agent not in `primary_agent` or -`scouts`) → return projection unchanged, log warning. +### JSON Patch paths -**Fold exception safety:** `fold()` wraps each event type handler in -`try/except`. Any exception returns projection unchanged and logs the exception -with full event details. The event is still appended to the log (append-only is -inviolable) but its fold effect is skipped. +``` +Settings: /settings/installations/claude-default/available + /settings/profiles/balanced/tiers/primary + /settings/defaultProfile + /settings/defaultScoutConcurrency + +Run config: /run/config/profile + /run/config/scoutConcurrency + +Agent: /run/agents/abc123/status + /run/agents/abc123/step + /run/agents/abc123/lastTool + +Conversation: /run/agents/abc123/conversation/pendingThinking + /run/agents/abc123/conversation/entries/- + /run/agents/abc123/conversation/isThinking + /run/agents/abc123/conversation/inputTokens + +Focus: /run/focus +Artifacts: /run/artifacts/docs~1architecture.md/size +Phase: /run/phase +``` -**Accumulating fields** (`activity_log`, `notifications`, `stream_buffer`) are -unbounded — entries are never evicted. Runs are short-lived; the in-memory cost -is bounded by run duration. +Named entities (installations, profiles, agents, artifacts) are dicts for +stable patch paths. Ordered collections (conversation entries, notifications) +are append-only lists — positional indices are stable. + +--- + +## Fold Rules + +The fold is grouped by the part of the projection it modifies. An event may +trigger rules in multiple groups (`agent_step_advanced` updates both the +agent's progress fields and its conversation). + +### Agent conversation + +These rules apply to the agent identified by `event.agent_id`. There is no +primary-agent filtering in the fold — every agent has its own conversation and +the fold appends unconditionally. The frontend chooses which conversation to +render via `focus`. + +| Event | Action | +|-------|--------| +| `thinking` | Flush `pending_text` → TextEntry. Append delta to `pending_thinking`. Set `is_thinking = True`. | +| `stream_delta` | Flush `pending_thinking` → ThinkingEntry. Append delta to `pending_text`. Set `is_thinking = False`. | +| `tool_read`, `tool_write`, `tool_edit`, `tool_bash`, `tool_grep`, `tool_ls` | Flush both pending fields. Append typed entry with `in_flight=True`. Set `is_thinking = False`. Update `agent.last_tool`. | +| `tool_called` (non-koan) | Flush both pending fields. Append `ToolGenericEntry` with `in_flight=True`. Set `is_thinking = False`. Update `agent.last_tool`. | +| `tool_called` (tool name starts with `koan_`) | Skip. koan MCP tools are infrastructure; their effects arrive via `agent_step_advanced`, `questions_asked`, etc. | +| `tool_completed` | Find entry by `call_id`, set `in_flight = False`. | +| `agent_step_advanced` | Flush both pending fields. Append `StepEntry` if `step >= 1`. Set `is_thinking = False`. **Also** update `agent.step`, `agent.step_name`; accumulate `usage` into `conversation.input_tokens`, `conversation.output_tokens`. | +| `stream_cleared` | Flush both pending fields. Set `is_thinking = False`. | + +### Agent lifecycle + +| Event | Action | +|-------|--------| +| `scout_queued` | Add `Agent(agent_id=scout_id, status="queued", ...)` to `run.agents`. | +| `agent_spawned` | Look up `agent_id` in `run.agents`. If found (queued scout): set `status="running"`, `started_at_ms`. If not found (primary agent): create `Agent(is_primary=True, status="running", ...)`, add to `run.agents`. | +| `agent_exited` | Set `status="done"` or `"failed"`. Set `error` if present. Accumulate final `usage` into conversation tokens. | +| `agent_spawn_failed` | Append `Notification` to `projection.notifications`. | + +Agents are never removed from `run.agents`. Status distinguishes active from +completed agents. + +### Focus transitions + +| Event | Action | +|-------|--------| +| `agent_spawned` (primary) | `run.focus = ConversationFocus(agent_id=...)` | +| `questions_asked` | `run.focus = QuestionFocus(agent_id=..., token=..., questions=...)` | +| `questions_answered` | `run.focus = ConversationFocus(agent_id=primary_id)` | +| `artifact_review_requested` | `run.focus = ReviewFocus(...)` | +| `artifact_reviewed` | `run.focus = ConversationFocus(agent_id=primary_id)` | +| `workflow_decision_requested` | `run.focus = DecisionFocus(...)` | +| `workflow_decided` | `run.focus = ConversationFocus(agent_id=primary_id)` | + +### Run lifecycle + +| Event | Action | +|-------|--------| +| `run_started` | `projection.run = Run(config=RunConfig(...))` | +| `phase_started` | `run.phase = phase` | +| `workflow_completed` | `run.completion = CompletionInfo(...)` | + +### Settings + +| Event | Action | +|-------|--------| +| `probe_completed` | For each alias in `payload.results`, set `settings.installations[alias].available`. | +| `installation_created` | Add `Installation(...)` to `settings.installations[alias]`. | +| `installation_modified` | Update `settings.installations[alias]`. | +| `installation_removed` | Remove `settings.installations[alias]`. | +| `profile_created` | Add `Profile(...)` to `settings.profiles[name]`. | +| `profile_modified` | Update `settings.profiles[name]`. | +| `profile_removed` | Remove `settings.profiles[name]`. | +| `default_profile_changed` | Set `settings.default_profile`. | +| `default_scout_concurrency_changed` | Set `settings.default_scout_concurrency`. | + +### Artifacts + +| Event | Action | +|-------|--------| +| `artifact_created` | Add to `run.artifacts[path]`. | +| `artifact_modified` | Update `run.artifacts[path]`. | +| `artifact_removed` | Remove `run.artifacts[path]`. | + +### Fold safety + +- **Unknown event type** → return projection unchanged, log warning. +- **Agent event with unknown `agent_id`** → return projection unchanged, log + warning. (Exception: `agent_spawn_failed` — it appends a notification + regardless because the error fact is worth preserving.) +- **Fold exception** → return projection unchanged, log full exception. The + event is still in the audit log; only the fold effect is skipped. +- **`run is None` when a run event arrives** → return projection unchanged, log + warning. (Prevents crashes from late-arriving events after restart.) --- ## ProjectionStore `koan/projections.py` contains the store class. This module has **zero koan -domain imports** — it is pure event-sourcing machinery. Domain-to-event -bridging lives in `koan/events.py`. +domain imports** — it is pure event-sourcing machinery. ```python class ProjectionStore: - """In-memory versioned event log + materialized projection.""" - - events: list[VersionedEvent] # append-only - projection: Projection # eagerly materialized after each push_event + """In-memory versioned event log + materialized projection + JSON Patch broadcaster. + + Three stores, three purposes: + events — append-only audit log, never modified + projection — materialized state for snapshot serving and diff computation + prev_state — previous to_wire() output; overwritten each push_event() + + Push flow: + 1. Increment version, create VersionedEvent, append to events + 2. Fold: projection = fold(projection, event) + 3. Diff: patch = make_patch(prev_state, projection.to_wire()) + 4. If patch is non-empty: broadcast {type, version, patch} dict to all subscribers + 5. Update prev_state + + Every event takes the same path. No branching on event type. + Subscriber queues receive plain dicts — the dict is the SSE JSON payload. + """ + + events: list[VersionedEvent] # append-only + projection: Projection # eagerly materialized version: int # current version (0 = empty) - subscribers: list[asyncio.Queue] + prev_state: dict # previous to_wire() for diff computation + subscribers: set[asyncio.Queue] # one per connected SSE client +``` - def push_event(self, event_type: str, payload: dict, - agent_id: str | None = None) -> VersionedEvent: - """Append event, increment version, fold projection, broadcast to subscribers.""" +### push_event - def get_snapshot(self) -> dict: - """Return {version: int, state: dict} — the full projection as a dict.""" +```python +def push_event(self, event_type, payload, agent_id=None): + self.version += 1 + event = VersionedEvent(version=self.version, ...) + self.events.append(event) + + old_state = self.prev_state + self.projection = fold(self.projection, event) + new_state = self.projection.to_wire() + self.prev_state = new_state + + patch = jsonpatch.make_patch(old_state, new_state) + if not patch: + return event # no state change — no broadcast + + msg = {"type": "patch", "version": self.version, "patch": patch.patch} + for q in list(self.subscribers): # snapshot to avoid concurrent-modification issues + q.put_nowait(msg) + return event +``` - def events_since(self, version: int) -> list[VersionedEvent]: - """Return events with version > given version, in order.""" +When the fold produces no state change (e.g., a `tool_called` event for a koan +MCP tool that the fold skips), no message is broadcast. Subscribers stay at the +same version. - def subscribe(self) -> asyncio.Queue: - """Create and register a subscriber queue. Queue receives VersionedEvent objects.""" +### get_snapshot - def unsubscribe(self, queue: asyncio.Queue) -> None: - """Remove a subscriber queue.""" +```python +def get_snapshot(self) -> dict: + return {"version": self.version, "state": self.projection.to_wire()} ``` -`push_event()` snapshots `self.subscribers` before iterating -(`for q in list(self.subscribers)`) to avoid `RuntimeError` if a subscriber -is added or removed during broadcast. +Always produces camelCase via `to_wire()`. Called by `sse_stream()` for every +connect and reconnect. ### Event payload builders: koan/events.py -`koan/events.py` bridges koan domain types (`AgentState`, `list_artifacts`, -`RunnerDiagnostic`, etc.) into typed event payloads. It imports domain types; -`projections.py` does not. +`koan/events.py` bridges koan domain types into event payloads. It imports +domain types; `projections.py` does not. ```python +def build_run_started(profile, installations, scout_concurrency) -> dict def build_agent_spawned(agent: AgentState) -> dict -def build_agent_exited(exit_code: int, error: str | None = None, usage: dict | None = None) -> dict -def build_agent_spawn_failed(role: str, diagnostic: RunnerDiagnostic) -> dict -def build_step_advanced(step: int, step_name: str, usage: dict | None = None) -> dict -def build_tool_called(call_id: str, tool: str, args: dict | str, summary: str = "") -> dict -def build_tool_completed(call_id: str, tool: str, result: str | None = None) -> dict -def build_artifact_diff(old: dict[str, dict], new_artifacts: list[dict]) -> list[tuple[str, dict]] -# etc. +def build_agent_exited(exit_code, error=None, usage=None) -> dict +def build_agent_spawn_failed(role, diagnostic: RunnerDiagnostic) -> dict +def build_step_advanced(step, step_name, usage=None, total_steps=None) -> dict +def build_tool_called(call_id, tool, args, summary="") -> dict +def build_tool_read(call_id, file, lines="") -> dict +def build_tool_bash(call_id, command) -> dict +# ... other typed tool builders ... +def build_tool_completed(call_id, tool, result=None) -> dict +def build_artifact_diff(old, new_artifacts) -> list[tuple[str, dict]] +# ... interaction and settings builders ... ``` `build_artifact_diff` compares old and new artifact sets, returns a list of `(event_type, payload)` tuples — one per created/modified/removed file. -Callers import from both modules: - -```python -from .projections import ProjectionStore -from .events import build_agent_spawned - -store.push_event("agent_spawned", build_agent_spawned(agent), agent_id=agent.agent_id) -``` - --- ## SSE Protocol @@ -337,79 +658,123 @@ store.push_event("agent_spawned", build_agent_spawned(agent), agent_id=agent.age | `since` value | Server response | |---|---| -| `0` (or omitted) | Send one `snapshot` SSE event, then stream live events | -| `N > 0` | Replay events with `version > N`, then stream live events | -| `N > current_version` (server restart) | Send `fatal_error` SSE event, close connection | +| matches `store.version` | Subscribe and stream live patches (no snapshot needed) | +| anything else (including 0, reconnect, server restart) | Send snapshot, then stream live patches | -The server retains the full event log in memory. Replay is always possible for -any valid version. - -When `since > current_version` (stale client after server restart), the server -sends a `fatal_error` SSE event with `{"reason": "version_not_available"}` and -closes the connection. The frontend handles `fatal_error` by closing the -`EventSource` without scheduling a reconnect and rendering a "reload required" -banner. This avoids infinite reconnect loops (browsers' `EventSource` fires -`onerror` on non-200 responses and would retry with the same stale version). +The `since` parameter is a version check, not a replay cursor. If the client's +`lastVersion` matches the server's current version, there is nothing to catch +up on. Otherwise, a fresh snapshot is always the correct recovery — it handles +reconnects, page reloads, and server restarts identically. ### Wire format -**Snapshot event** (`since=0`): +**Snapshot** (on every connect or reconnect where `since != store.version`): ``` event: snapshot -data: {"version": 42, "state": { ...projection as dict... }} +data: {"version": 42, "state": { ...full projection in camelCase... }} ``` -**Versioned event** (replay or live stream): +**Patch** (after each state-changing event): ``` -event: agent_spawned -data: {"version": 43, "agent_id": "abc", "role": "intake", ...} +event: patch +data: {"type": "patch", "version": 43, "patch": [{"op": "replace", "path": "/run/agents/abc/conversation/pendingThinking", "value": "The user wants..."}]} ``` -The SSE event name is the event type. Version and `agent_id` are included in -every data payload. The snapshot payload uses backend-native snake_case — the -frontend transforms to camelCase at the bridge boundary. +All keys and paths are camelCase. The frontend applies patches directly to its +store without any field renaming. + +### sse_stream implementation + +```python +async def sse_stream(request, since=0): + store = request.app.state.projection_store + queue = store.subscribe() + try: + if since != store.version: + # Client is behind, ahead (server restart), or connecting fresh. + # Fresh snapshot is the correct recovery in all cases. + yield sse_event("snapshot", store.get_snapshot()) + while True: + msg = await queue.get() # plain dict: {type, version, patch} + yield sse_event(msg["type"], msg) + except asyncio.CancelledError: + pass + finally: + store.unsubscribe(queue) +``` + +The queue is subscribed before the snapshot is yielded — no events can be +missed between the two operations. ### Reconnect flow ``` -Browser loads → connect ?since=0 → receive snapshot → render full state -Browser refreshes → connect ?since=0 → receive snapshot → render full state -Connection drops → reconnect ?since=N → receive events N+1..M → fold each → up to date +Browser loads → GET /events?since=0 → snapshot → render full state +Browser refreshes → GET /events?since=0 → snapshot → render full state +Connection drops → GET /events?since=N → snapshot → render full state +Server restarts → GET /events?since=N → snapshot (version=0) → render fresh state ``` +All cases are handled by the same code path. The client does not need to +distinguish between them. + --- ## Frontend Integration -The Zustand store gains: +`frontend/src/sse/connect.ts` — the complete sync implementation: ```typescript -lastVersion: number // version of last applied event or snapshot - -applySnapshot(data): // atomic replace of entire store state -applyEvent(event): // incremental fold — mirrors backend fold cases +// Module-level projection dict for fast-json-patch operations. +// fast-json-patch operates on plain JS objects, not Zustand state. +// On snapshot, replaced wholesale. On patch, applyPatch returns a new object. +let storeState: Record<string, unknown> = {} + +es.addEventListener('snapshot', (e) => { + const { version, state } = JSON.parse(e.data) + storeState = state + set({ lastVersion: version, ...state }) // spread camelCase fields directly into Zustand store +}) + +es.addEventListener('patch', (e) => { + try { + const { version, patch } = JSON.parse(e.data) + // mutate:false returns a new object rather than modifying storeState in-place. + storeState = applyPatch(storeState, patch, false, false).newDocument + set({ lastVersion: version, ...storeState }) + } catch (err) { + console.error('Patch failed, reconnecting:', err) + es.close() + set({ lastVersion: 0 }) // force snapshot on next connect + setTimeout(() => connect(set), 1000) + } +}) ``` -On snapshot, `applySnapshot` atomically replaces all store state via -`useStore.setState(transform(data))`. No merge logic. Any visual flash from -the re-render is acceptable — simplicity over smoothness. +Two handlers. No `applyEvent`. No fold logic. No field renaming. No special +cases. The server emits camelCase; the frontend stores camelCase; patches apply +directly. -`connectSSE()` in `sse/connect.ts`: +**Component access pattern:** -1. Connects with `new EventSource('/events?since=${store.lastVersion}')` -2. `snapshot` event → `store.applySnapshot(data)`, sets `lastVersion` -3. All other events → `store.applyEvent(event)`, increments `lastVersion` -4. On disconnect: `lastVersion` is already in store; reconnect uses it automatically - -The TypeScript fold mirrors the Python fold. Both must produce the same -projection shape from the same event sequence. When adding a new event type, -add a fold case to both implementations. - -`done_phases` is NOT in the projection snapshot. The frontend derives it from -`phase` using its own `ALL_PHASES` ordering constant. Notification severity is -derived from event type in the frontend's `SEVERITY_MAP`. +```typescript +// Agent monitor: filter run.agents by status +const agents = useStore(s => s.run?.agents ?? {}) +const running = Object.values(agents).filter(a => !a.isPrimary && a.status === 'running') +const queued = Object.values(agents).filter(a => a.status === 'queued') + +// Activity feed: conversation of the focused agent +const focusId = useStore(s => s.run?.focus?.agentId) +const conversation = useStore(s => + focusId ? s.run?.agents?.[focusId]?.conversation : undefined +) + +// Settings: read directly from store +const installations = useStore(s => s.settings?.installations ?? {}) +const defaultProfile = useStore(s => s.settings?.defaultProfile ?? 'balanced') +``` --- @@ -421,129 +786,128 @@ fold function, append-only log) but serving different purposes: | Aspect | Audit fold (`koan/audit/fold.py`) | Projection fold (`koan/projections.py`) | |---|---|---| | Input | Per-subagent audit events (`events.jsonl`) | Workflow-level projection events | -| Output | Per-subagent `Projection` (phase, step, tokens, tool calls) | Frontend-visible `Projection` (all agents, run state, UI interactions) | +| Output | Per-subagent `Projection` written to `state.json` | Frontend-visible `Projection` (in-memory) | | Scope | One subagent's execution | Entire workflow run | -| Persistence | Written to `state.json` on disk | In-memory only | +| Persistence | Written to disk on each event | In-memory only | | Consumers | Debugging, post-mortem analysis | Browser frontend via SSE | -| Parallelism | One fold per subagent | Single fold for the whole run | - -The audit fold tracks the internal execution of each subagent. The projection -fold tracks the frontend-visible state of the whole workflow. They share the -same structural pattern but are not connected. --- ## Design Decisions -### No external library - -There is no canonical Python library for in-memory event sourcing with -subscriptions that fits this use case: - -- **`python-eventsourcing`** — designed for database persistence (PostgreSQL, - etc.), not in-memory UI state -- **`reactivex`/`rxpy`** — reactive streams, awkward with asyncio, overkill - for this volume - -The pattern — append-only list + pure fold + `asyncio.Queue` subscribers — is -simple enough to implement directly. `koan/audit/fold.py` demonstrates the same -pattern for the audit domain. - -### Why all events are versioned, including stream_delta - -Token deltas fire at high frequency. Including each delta in the versioned log -means the log grows large, but the **snapshot** captures only -`stream_buffer: "accumulated text"` — a single small string. Reconnecting -clients receive the accumulated buffer from the snapshot, not thousands of -individual deltas. +### Why JSON Patch over a dual fold + +The previous architecture maintained two fold implementations — one in Python, +one in TypeScript — that were required to produce the same projection from the +same event sequence ("symmetric fold invariant"). Every new event type required +adding a case to both, with no mechanical check that they stayed in sync. Two +bugs (fragmented thinking cards, scout events in the primary feed) traced +directly to the two folds diverging. JSON Patch eliminates the invariant: the +fold exists in one place, the server computes diffs, the frontend applies them +mechanically. Correctness is structural, not disciplinary. + +### Why camelCase on the wire + +Emitting snake_case from the server requires a `mapProjectionToStore()` function +in the frontend that renames every field, plus a `projectionState` shadow object +for patch application (patches must apply to the pre-renamed dict, not the +renamed store). Every new projection field needs a rename entry in that mapping. +The mapping layer *is* business logic and it contradicts the "frontend has zero +business logic" principle. Emitting camelCase eliminates the layer: patches +apply directly to the Zustand store, snapshots spread directly into it, and +adding a field to `Projection` requires zero frontend changes. + +### Why uniform JSON Patch (no delta bypass for thinking) + +A thinking delta produces a `replace` operation on `pendingThinking` carrying +the full accumulated string. At 10KB accumulated with 20 deltas/second, this is +~200KB/s of patches. On a remote server, a dedicated delta event type would be +worth the complexity. On localhost, loopback traffic is free — 200KB/s is noise +next to the LLM API traffic. Two event types (`snapshot`, `patch`) mean two +handlers, zero special cases, and no branching in `push_event`. The complexity +of a third event type (third handler, branching, special-case in the frontend) +costs more than the bandwidth savings are worth. + +### Why dict not list for named entities + +JSON Patch paths for list elements use positional indices (`/run/agents/2`). +When an agent is removed or the list is reordered, subsequent indices shift and +in-flight patches referencing those indices become invalid. Dict keys are stable: +`/run/agents/abc123` refers to the same agent regardless of insertions or +removals elsewhere. This applies to installations, profiles, agents, and +artifacts — all named entities are dicts. + +### Why `pending_thinking` / `pending_text` not `thinkingBuffer` / `streamBuffer` + +"Buffer" describes the mechanism — accumulate, flush, reset. "Pending" describes +the content: incomplete LLM output that will become a conversation entry on the +next transition. Names should describe what a field *is*, not how it works. +"Pending" also communicates the temporal relationship correctly: this text is +not yet complete and will be committed to `entries` on the next event. + +### Why Focus is a discriminated union + +The previous architecture used an `active_interaction` dict with an +`interaction_type` string that the frontend duck-typed. This created implicit +coupling between the backend's interaction type strings and the frontend's +rendering switch. Focus replaces it with an explicit discriminated union where +every possible main-content state is modeled. The frontend switch on +`focus.type` is exhaustive — TypeScript will flag unhandled variants. The +`agent_id` on every variant means the conversation is always available as +backdrop without a separate lookup. + +### Why Settings vs RunConfig + +Settings describe what's *available* (persistent, mutable via the settings +overlay at any time). RunConfig describes what *this run uses* (frozen at +`run_started`, never modified). This separation prevents a settings change +mid-run from affecting the in-flight run. It also makes the landing page +straightforward: it reads `settings.defaultProfile` and +`settings.defaultScoutConcurrency` as the pre-selected values, which the user +may override before starting. + +### Why always-snapshot on reconnect + +The previous architecture stored events and replayed them for reconnecting +clients (`?since=N` returned events `N+1..M`). At 500K events over a full epic, +with patches ranging from 80 bytes to 10KB, storing patches for replay requires +unbounded memory and adds ordering logic and partial-replay edge cases. A fresh +50MB snapshot is sent once on reconnect — cheaper, simpler, and handles server +restarts (which would have caused a `fatal_error` in the old protocol) +identically to a normal reconnect. + +### Why `is_thinking` is a projection field, not derived + +`is_thinking` could be derived as "is `pending_thinking` non-empty." But that +derivation would need to run in the frontend on every patch, which contradicts +the "frontend has zero business logic" principle. The fold sets it explicitly; +it arrives via patch like every other field. -The uniform model (every event gets a version) eliminates special-case code -paths. A system where some events are versioned and others are not creates -complexity in the reconnect path. - -### Why tool events are generic, not per-tool-type - -Tool schemas vary across runners and versions. A separate event type per tool -(`read_called`, `bash_called`, etc.) would require updating the event type -system whenever a runner adds or renames a tool. The `tool` field carries a -canonical normalized name; `args` and `result` are unstructured. The fold -appends raw events to the activity log without interpreting tool semantics. - -### Why tool name normalization is per-runner +### Why accumulating fields are unbounded -Each runner normalizes its own tool names in `parse_stream_event()`. This -keeps normalization knowledge co-located with runner-specific parsing logic. -By the time a `StreamEvent` leaves the runner, tool names are canonical -(`read`, `bash`, `edit`, `grep`, etc.). A central alias table would require -updating a shared file for each runner-specific change. +`conversation.entries` and `notifications` are never evicted. Capping them +would require eviction logic that creates edge cases for what a reconnecting +client receives in a snapshot. Koan is one-shot — the server shuts down after +the workflow completes — so accumulation is bounded by run duration. ### Why MCP tool calls are authoritative over stdout When a subagent calls a koan MCP tool, the call appears twice: as an MCP request (structured, complete) and in the runner's stdout stream (runner-specific format, possibly truncated). The MCP endpoint has full -structured data for both the call and the result. Stdout events are filtered -to exclude koan MCP tool names; only agent-native tools are sourced from stdout. - -### Why notification_fired is eliminated - -A generic notification bucket conflates facts with presentation concerns. Each -condition that warrants user notification is captured by a specific fact event -(`agent_spawn_failed`, `agent_exited` with error, `cancelled: true` on -interaction resolution). The fold derives `notifications` from these facts. The -frontend determines which events are notification-worthy and maps event types -to severity in its own `SEVERITY_MAP`. +structured data. Stdout events are filtered to exclude koan MCP tool names +(`koan_*`, `mcp__koan*`); only agent-native tools are sourced from stdout. -### Why artifacts use diff events, not a full list +### Why `build_artifact_diff` uses diff events, not a full list `artifact_created`/`artifact_modified`/`artifact_removed` carry exactly what -changed, not the full current set. The fold maintains `artifacts` as a -`dict[str, dict]` keyed by path, enabling O(1) per-event updates. - -### Why the envelope has no UUID or causation fields - -`version` is a unique identifier within a run — no UUID needed. Causation and -correlation IDs matter in multi-writer distributed systems where independent -producers interleave events and causal chains are ambiguous. Koan has a single -writer (the driver process). The causal chain is implicit in temporal ordering -plus `agent_id`. There is no cross-system correlation to track. +changed, not the full current set. The fold maintains `run.artifacts` as a dict +keyed by path, enabling O(1) per-event updates. `build_artifact_diff()` scans +the epic directory at phase boundaries and produces the minimal set of events. ### Why projections.py has zero koan domain imports -`koan/projections.py` contains pure event-sourcing machinery. It imports -nothing from the koan domain. Domain-to-event bridging lives in `koan/events.py`. -This separation makes the projection engine testable in isolation and prevents -the event schema from leaking domain implementation details. - -### Why activity_log stores raw events - -`tool_called`, `tool_completed`, and `thinking` events are appended to -`activity_log` as-is without normalization. The frontend renders what it needs -from the raw payload. A normalization layer would need to anticipate every -display use case in advance; raw events let the frontend decide. - -### Why accumulating fields are unbounded - -`activity_log`, `notifications`, and `stream_buffer` are never evicted. -Capping them would require eviction logic that creates edge cases around what a -reconnecting client receives in a snapshot. koan is one-shot — the server shuts -down after the workflow completes — so accumulation is bounded by run duration. - -### Why the server shuts down after workflow completion - -koan runs one workflow per server instance. After `workflow_completed` is -emitted, the server shuts down gracefully. There is no idle state between runs, -no need to reset projection state, and no ambiguity about what a freshly -connecting browser should receive. - -### Why version-negotiated catch-up instead of always-snapshot - -A brief network hiccup should not force the frontend to rebuild all state from -scratch. `?since=N` lets a briefly-disconnected client receive only the events -it missed (typically a handful) and fold them incrementally. - -### Why snapshot triggers atomic state replacement - -When the frontend receives a snapshot, `useStore.setState(transform(data))` -atomically replaces the entire store. No merge logic, no version comparison. -A snapshot is authoritative. Any visual re-render is acceptable. +`koan/projections.py` contains pure event-sourcing machinery. Domain-to-event +bridging lives in `koan/events.py`. This separation makes the projection engine +testable in isolation and prevents the event schema from leaking domain +implementation details. diff --git a/docs/token-streaming.md b/docs/token-streaming.md index 69ce868..e30de3a 100644 --- a/docs/token-streaming.md +++ b/docs/token-streaming.md @@ -66,14 +66,15 @@ Token deltas flow through the projection system: CLI stdout -> line parser -> runner.parse_stream_event(line) -> StreamEvent with delta -> push_event("stream_delta", {"agent_id": ..., "delta": "..."}) - -> ProjectionStore: append to log, fold projection.stream_buffer += delta - -> broadcast versioned event to SSE subscribers - -> browser receives: event: stream_delta / data: {"version": N, ...} - -> frontend fold: store.streamBuffer += event.delta + -> ProjectionStore: append to log, fold appends delta to agent.conversation.pending_text + -> compute JSON Patch: [{op: "replace", path: "/run/agents/{id}/conversation/pendingText", value: "..."}] + -> broadcast patch to SSE subscribers + -> browser receives: event: patch / data: {"version": N, "patch": [...]} + -> applyPatch(store, patch) — store.run.agents[id].conversation.pendingText updated ``` `stream_delta` events go through `ProjectionStore` like all other events. The -fold step is in-memory only (appending to `projection.stream_buffer`) — there +fold step is in-memory only (updating `agent.conversation.pending_text`) — there is no disk I/O per delta. This is distinct from the audit pipeline, which writes to disk after each event. @@ -83,60 +84,58 @@ When a subagent finishes streaming, the caller emits: push_event("stream_cleared", {"agent_id": ...}) ``` -The fold sets `projection.stream_buffer = ""`. The frontend clears its -`streamBuffer` slice accordingly. +The fold flushes `pending_text` to a `TextEntry` in `conversation.entries` and +resets `pending_text = ""`. The JSON Patch carries the resulting state change. --- ## Replay on Reconnect -When a client connects or reconnects with `?since=0`, the server sends a -`snapshot` event. The snapshot includes the current `stream_buffer` value — -the full accumulated text from all `stream_delta` events since the buffer was -last cleared. +When a client connects or reconnects, the server sends a `snapshot` event. The +snapshot includes the current state of each agent's conversation — including +`pendingText` (accumulated stream output not yet committed to an entry) and +`entries` (any `TextEntry` objects from completed text blocks). ``` event: snapshot -data: {"version": 142, "state": {"stream_buffer": "accumulated text...", ...}} +data: {"version": 142, "state": {"run": {"agents": {"abc": {"conversation": {"pendingText": "accumulated text...", ...}}}}}} ``` -The reconnecting client receives the complete buffer in a single snapshot field. -Individual `stream_delta` events are not replayed on reconnect — the snapshot -`stream_buffer` represents their accumulated effect. +The reconnecting client receives the complete accumulated state in a single +snapshot. Individual `stream_delta` events are not replayed — the snapshot +represents their accumulated effect. -When reconnecting with `?since=N` (brief disconnect), the client replays only -the `stream_delta` events it missed and folds them incrementally, same as any -other event type. +All reconnect scenarios send a snapshot: page reload, brief disconnect, and +server restart are handled identically. -See [projections.md -- Version-negotiated catch-up](./projections.md#sse-protocol) +See [projections.md -- SSE Protocol](./projections.md#sse-protocol) for the full reconnect protocol. --- ## Frontend -The frontend Zustand store has a `streamBuffer: string` slice. The `applyEvent` -fold handler for `stream_delta` appends the delta: +The frontend has no fold logic. The Zustand store is updated by applying JSON +Patches received from the server: ```typescript -case 'stream_delta': - return { streamBuffer: state.streamBuffer + event.delta } -case 'stream_cleared': - return { streamBuffer: '' } +// patch event for a stream_delta: +// [{op: "replace", path: "/run/agents/abc/conversation/pendingText", value: "accumulated..."}] +storeState = applyPatch(storeState, patch, false, false).newDocument +set({ ...storeState }) ``` -`applySnapshot` sets `streamBuffer` from the snapshot's `stream_buffer` field. - -The `ActivityFeed` component renders `streamBuffer` as the in-flight streaming -text area. When `stream_cleared` fires, the buffer empties and the streaming -display resets for the next agent. +The `ActivityFeed` component reads `conversation.pendingText` from the focused +agent and renders it as the in-flight streaming text. When `stream_cleared` +causes the fold to flush `pendingText` into a `TextEntry`, the patch reflects +that: `pendingText` becomes `""` and a new entry appears in `entries`. --- ## What Is Not Streamed -| Signal | Why excluded from stream_buffer | +| Signal | Why excluded from pendingText | | ---------------------- | ------------------------------------------------------------- | -| Thinking tokens | Go through `thinking` events into `activity_log`, not `stream_buffer` | +| Thinking tokens | Go through `thinking` events into `conversation.pendingThinking`, not `pendingText` | | Tool execution updates | Handled via `tool_called`/`tool_completed` projection events | | Scout output | Scouts push their own audit events; no token streaming needed | From 9137f48b8037ab3145b1a32ac1294144615b6395 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 18:10:47 +0700 Subject: [PATCH 259/412] constrain intake scouts to 3-5 with broad multi-part prompts Replace unbounded area-to-scout mapping with cluster-based planning. Remove 'scouts are cheap, don't merge' language. Add concrete example of a well-scoped multi-part scout prompt. Gate follow-up scouts to 1-2 only when a concrete gap is found. --- koan/phases/intake.py | 64 +++++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 30 deletions(-) diff --git a/koan/phases/intake.py b/koan/phases/intake.py index 1aac71b..3aaf4df 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -203,52 +203,56 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "scout prompts that reference actual function names, actual patterns, and", "actual file paths instead of conversation labels.", "", - "## Step 3: Plan -- enumerate coverage areas", + "## Step 3: Plan -- cluster into 3-5 scout investigations", "", - "Using your question list and what you observed in the code, enumerate the", - "areas that need investigation. Write out each area as a bullet.", - "Consider two categories:", + "Using your question list and what you observed in the code, identify the", + "concerns that need investigation. Consider both:", "", - "**Surface areas** -- what the conversation explicitly references:", - "- Each file, module, or system mentioned by name.", - "- Each integration point with existing code (APIs, databases, auth, config).", - "- Project conventions (linter configs, test framework, doc standards, architecture patterns).", - "- Each assumption the user makes about the codebase that needs verification.", + "- What the conversation explicitly references (files, modules, integration", + " points, assumptions that need verification, project conventions).", + "- What the conversation did NOT mention but could matter (hidden callers,", + " related subsystems, prior art, invariants, test coverage).", "", - "**Deep areas** -- what the conversation did NOT mention but could matter:", - "- Hidden consumers or callers of the code being changed -- who else depends on this?", - "- Related subsystems that might be affected by the proposed work.", - "- Prior art: has something similar been attempted before? Abandoned branches, TODO comments, commented-out code?", - "- Edge cases and invariants: what constraints does the existing code enforce that the conversation didn't mention?", - "- Test coverage: what test infrastructure exists for the affected areas?", + "Now group related concerns into **3-5 clusters**. Each cluster becomes one", + "scout. A scout is a broad investigator -- it can examine multiple files,", + "trace dependencies, and answer several related questions in a single run.", + "Merge concerns that touch the same area of the codebase or the same", + "conceptual boundary into one scout with a multi-part prompt.", "", - "Your area list determines your scout count. A simple single-file change may need", - "only a few areas. A cross-cutting system change will need many. Let the task", - "dictate coverage -- do not pick a number and fill it.", + "3-5 scouts is the target. Fewer than 3 means your prompts are probably", + "too broad to produce focused findings. More than 5 means you are splitting", + "related concerns that a single scout could cover together.", "", - "## Step 4: Execute -- map one scout to each area", + "## Step 4: Execute -- dispatch scouts", "", - "For each coverage area, formulate one scout. Use `koan_request_scouts` to dispatch", - "them all in a single call.", + "Use `koan_request_scouts` to dispatch all scouts in a single call.", "", "Each scout needs:", - "- id: short kebab-case identifier (e.g., 'auth-setup', 'hidden-callers')", + "- id: short kebab-case identifier (e.g., 'auth-and-permissions', 'data-layer')", "- role: investigator focus (e.g., 'authentication auditor', 'dependency tracer')", - "- prompt: a specific question to answer (e.g., 'Find all callers of updateUserProfile in src/ and identify every module that depends on its return type')", - "", - "Scouts are cheap -- they run on fast models in parallel. If you identified an area,", - "it deserves a scout. Do not merge areas to reduce count, and do not skip an area", - "because it \"probably\" won't matter.", + "- prompt: a rich, multi-part investigation brief. Tell the scout what area", + " to explore, what questions to answer, and what to look for. Include file", + " paths and function names from the Ground step. A good prompt is 3-8", + " sentences covering the full cluster.", + "", + "Example of a well-scoped scout prompt:", + " 'Investigate the authentication subsystem rooted at src/auth/. Find all", + " callers of verifyToken(), identify the middleware chain in server.ts,", + " check whether session storage uses Redis or in-memory, and note any", + " TODO or FIXME comments related to auth. Report the permission model", + " (RBAC, ACL, or ad-hoc checks) and how it integrates with the router.'", "", "## Step 5: Analyze results", "", "When scouts return, analyze each report:", - "- Does the finding answer the question you asked?", + "- Does the finding answer the questions you asked?", "- Does it reveal anything unexpected about the codebase?", "- Does it raise new questions that need user input?", - "- Did any deep scout uncover something the conversation didn't anticipate?", "", - "If results reveal new areas worth exploring, dispatch a follow-up round of scouts.", + "If a finding reveals a concrete gap -- a specific file, dependency, or", + "integration point that no scout covered and that affects scope -- dispatch", + "1-2 targeted follow-up scouts. Do not dispatch follow-ups for vague", + "curiosity or marginal coverage improvements.", "", "Do NOT ask the user questions in this step -- that happens in the Ask step.", ], From 811ee38c92677ba71315c0471ff534fac19d92c3 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 18:15:23 +0700 Subject: [PATCH 260/412] invert activity feed visual hierarchy: muted thinking, elevated text Thinking cards get green-tinted inset background with left border accent (recedes as secondary content). LLM text output gets white elevated card with border and padding (promoted as primary content). --- frontend/src/styles/layout.css | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index 155ff17..d2b3773 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -81,16 +81,17 @@ /* ---- Activity cards (thinking, future: tool results) ---- */ +/* ---- Thinking card -- muted inset, recedes behind LLM text ---- */ .activity-card { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); + background: var(--plum-bg); + border-left: 3px solid var(--plum); + border-radius: 0 var(--radius-sm) var(--radius-sm) 0; margin: var(--space-1) 0; overflow: hidden; } .activity-card-active { - border-color: var(--copper-border); + border-left-color: var(--copper-border); } .activity-card-header { @@ -99,11 +100,11 @@ align-items: center; padding: var(--space-2) var(--space-4); font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--font-size-xs); } .activity-card-tool { - color: var(--text-muted); + color: var(--plum); } .activity-card-thinking .activity-card-tool { @@ -122,7 +123,7 @@ .activity-card-body { padding: 0 var(--space-4) var(--space-2); font-family: var(--font-mono); - font-size: 13px; + font-size: 12px; color: var(--text-muted); white-space: pre-wrap; word-break: break-word; @@ -262,17 +263,19 @@ text-transform: capitalize; } -/* Stream output -- wrapping text block for LLM text */ +/* Stream output -- elevated white card for LLM text (primary content) */ .stream-output { + background: var(--bg-elevated); + border: 1px solid var(--border); + border-radius: var(--radius-lg); font-family: var(--font-mono); font-size: var(--font-size-sm); color: var(--text); line-height: 1.6; white-space: pre-wrap; word-break: break-word; - padding: var(--space-2) 0; - margin-top: var(--space-2); - border-top: 1px solid var(--border); + padding: var(--space-4); + margin: var(--space-1) 0; } /* Thinking indicator */ From b865859e45d3df006c47ed49561f40fdb6c98f58 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 21:41:45 +0700 Subject: [PATCH 261/412] fix scout queued-to-running transition when IDs differ scout_queued keys agents by label, agent_spawned keys by UUID. The fold now does a secondary lookup by label when UUID is not found, then re-keys the entry under the UUID for subsequent events. --- koan/projections.py | 22 ++++++++++++++++++++-- tests/test_projections.py | 27 +++++++++++++++++++++++++-- 2 files changed, 45 insertions(+), 4 deletions(-) diff --git a/koan/projections.py b/koan/projections.py index 7df3177..d66cab8 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -475,10 +475,28 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: is_primary = payload.get("is_primary", False) new_agents = dict(projection.run.agents) + # Look up by agent_id first (exact match), then fall back + # to label match. scout_queued keys agents by label + # (e.g. "database-and-testing") while agent_spawned keys + # by UUID, so the secondary lookup bridges the two. + queued_key: str | None = None if eid in new_agents: - # Scout was previously queued — transition to running - existing = new_agents[eid] + queued_key = eid + else: + spawn_label = payload.get("label", "") + if spawn_label: + for k, a in new_agents.items(): + if a.label == spawn_label and a.status == "queued": + queued_key = k + break + + if queued_key is not None: + # Transition queued -> running. Re-key under the real + # agent_id so all subsequent events (which use the UUID) + # find the right entry. + existing = new_agents.pop(queued_key) new_agents[eid] = existing.model_copy(update={ + "agent_id": eid, "status": "running", "started_at_ms": payload.get("started_at_ms", 0), "role": payload.get("role", existing.role), diff --git a/tests/test_projections.py b/tests/test_projections.py index fb855e2..c8c5511 100644 --- a/tests/test_projections.py +++ b/tests/test_projections.py @@ -153,18 +153,41 @@ def test_agent_spawned_sets_conversation_focus(self): assert isinstance(r.run.focus, ConversationFocus) assert r.run.focus.agent_id == "a1" - def test_agent_spawned_scout_transitions_from_queued(self): + def test_agent_spawned_scout_transitions_from_queued_same_id(self): p = _proj_with_run() # Queue the scout first p = fold(p, _e("scout_queued", {"scout_id": "s1", "label": "eng", "model": "haiku"})) assert p.run.agents["s1"].status == "queued" - # Spawn it + # Spawn with the same id r = fold(p, _e("agent_spawned", { "agent_id": "s1", "role": "scout", "is_primary": False, "started_at_ms": 2000, }, agent_id="s1")) assert r.run.agents["s1"].status == "running" assert r.run.agents["s1"].started_at_ms == 2000 + def test_agent_spawned_scout_transitions_by_label_when_id_differs(self): + """scout_queued keys by label, agent_spawned keys by UUID. + The fold must match by label and re-key under the UUID.""" + p = _proj_with_run() + # Queue keyed by label + p = fold(p, _e("scout_queued", {"scout_id": "eng", "label": "eng", "model": "haiku"})) + assert "eng" in p.run.agents + assert p.run.agents["eng"].status == "queued" + # Spawn with a UUID — different key + uuid_id = "aaaa-bbbb-cccc" + r = fold(p, _e("agent_spawned", { + "agent_id": uuid_id, "role": "scout", "label": "eng", + "is_primary": False, "started_at_ms": 3000, "model": "haiku", + }, agent_id=uuid_id)) + # Old label key should be gone, new UUID key should exist + assert "eng" not in r.run.agents + assert uuid_id in r.run.agents + assert r.run.agents[uuid_id].status == "running" + assert r.run.agents[uuid_id].agent_id == uuid_id + assert r.run.agents[uuid_id].label == "eng" + # Only one agent entry, not two + assert len(r.run.agents) == 1 + def test_scout_queued_adds_agent_with_queued_status(self): p = _proj_with_run() r = fold(p, _e("scout_queued", {"scout_id": "s1", "label": "eng", "model": "haiku"})) From 345470d5873cdc1e16389c592fa101a568b713fb Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 21:41:53 +0700 Subject: [PATCH 262/412] compress scout report format for signal density Replace verbatim code excerpts with compressed notation (signatures, struct field lists, enum values, call chains). Add concrete example of target density. Remove Files Examined section (refs are inline). --- koan/phases/scout.py | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/koan/phases/scout.py b/koan/phases/scout.py index 8aae0dc..cf353f6 100644 --- a/koan/phases/scout.py +++ b/koan/phases/scout.py @@ -46,7 +46,13 @@ "- MUST NOT express opinions about code quality.\n" "- MUST NOT produce implementation plans or design ideas.\n" "- MUST include file paths and line numbers when referencing code.\n" - "- MUST include relevant code excerpts (verbatim) to support each finding.\n" + "- MUST reference code precisely: file:line, function signature or key line.\n" + " Do NOT copy full function bodies or paste large code blocks.\n" + "- Use compressed notation throughout your report:\n" + " Signatures: `file.go:42 func Compile(*Rule) (*CompiledRule, error)`\n" + " Structs: `CompiledRule{RuleID, Name, Action, SampleRate, OrGroups}`\n" + " Enums: `Action: Observe|Drop|Fail`\n" + " Call chains: `cmd/main.go -> NewService() -> engine.Start()`\n" "- SHOULD be thorough within the question scope: follow references, check related files.\n" "- SHOULD note explicitly when something is NOT present (e.g., \"No tests found for this module\").\n" "\n" @@ -118,21 +124,30 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", f"**Output file:** {output_file}", "", - "Write a markdown file with these exact sections:", + "Write a compressed findings file. Optimize for signal density -- every line", + "should carry information the intake agent needs. No prose padding.", "", "## Question", - "Restate the assigned question verbatim.", + "Restate the assigned question in one line.", "", "## Findings", - "Factual observations that answer the question. Use sub-sections if the answer has multiple parts.", - "Cite file paths and line numbers for every claim. Include code snippets where relevant.", - "Every finding must be backed by a file you actually read -- no inferred claims.", + "Use compressed notation throughout:", + "- One bullet per finding. File:line reference required.", + "- Function signatures as: `file:line func Name(args) returns`", + "- Struct fields as: `TypeName{Field1, Field2, Field3}`", + "- Enum values as: `EnumName: Val1|Val2|Val3`", + "- Call chains as: `caller.go:10 -> middleware.go:25 -> handler.go:40`", + "- Group related facts under a sub-heading, not one finding per sub-section.", "", - "## Files Examined", - "List every file you read during this investigation.", + "Example of target density:", + " ### Rule Engine", + " - compile.go:109 `Compile(*Rule) (*CompiledRule, error)` -- validates, sorts by cost", + " - evaluate.go:52 `Evaluate(*CompiledRule, json.RawMessage) (MatchResult, error)` -- DNF short-circuit", + " - CompiledRule{RuleID, Name, Action, SampleRate, OrGroups, Priority}", + " - Action: Observe|Drop|Fail", "", "## Gaps", - "Note anything you could not determine. If no gaps, write: (none)", + "Bullet list. If none: (none)", ], ) From 8774d48340102c2182acf67e1c21375e769375cc Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 21:44:47 +0700 Subject: [PATCH 263/412] show connecting state before first SSE snapshot arrives --- frontend/src/App.tsx | 15 +++++++++++++++ frontend/src/styles/layout.css | 15 +++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index fc2cf2f..389cc82 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -75,6 +75,21 @@ export default function App() { } }, []) // Empty dep array: connect once; reconnect is managed inside + const connected = useStore(s => s.connected) + + // Show a minimal loading state until the first SSE snapshot arrives. + // This prevents a blank cornsilk void while the server is initializing. + if (!connected) { + return ( + <div className="app"> + <Header /> + <div className="loading-state"> + <span className="loading-label">connecting…</span> + </div> + </div> + ) + } + return ( <div className="app"> <Header /> diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index d2b3773..0da3bde 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -10,6 +10,21 @@ margin: 0 auto; } +/* Loading state -- shown before first SSE snapshot arrives */ +.loading-state { + flex: 1; + display: flex; + align-items: center; + justify-content: center; +} + +.loading-label { + font-family: var(--font-mono); + font-size: var(--font-size-sm); + color: var(--text-muted); + letter-spacing: 0.05em; +} + /* Header -- normal flex child, not fixed. Stays at top because .app is a * flex column with overflow:hidden; child areas scroll internally. */ .header { From 14304764df5b931850903ba7d9b321f9626496ef Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Wed, 1 Apr 2026 21:53:24 +0700 Subject: [PATCH 264/412] make feed container the white surface, not individual entries The activity-feed-inner div is now the elevated white card. Text, tool lines, and step headers all sit naturally on it. Thinking cards break out with their own inset green background. stream-output loses its card treatment and uses a border-top separator instead. --- frontend/src/styles/layout.css | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index 0da3bde..0f0c19c 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -87,16 +87,21 @@ -webkit-mask-image: linear-gradient(to bottom, transparent, black 8px, black); } +/* The feed inner container IS the white surface. Text and tool lines + * sit directly on it. Thinking cards break out with their own inset + * background — they're the exception, not the rule. */ .activity-feed-inner { display: flex; flex-direction: column; gap: 2px; max-width: 960px; + background: var(--bg-elevated); + border: 1px solid var(--border); + border-radius: var(--radius-lg); + padding: var(--space-2) var(--space-4); } -/* ---- Activity cards (thinking, future: tool results) ---- */ - -/* ---- Thinking card -- muted inset, recedes behind LLM text ---- */ +/* ---- Thinking card -- muted inset that visually recedes ---- */ .activity-card { background: var(--plum-bg); border-left: 3px solid var(--plum); @@ -278,19 +283,16 @@ text-transform: capitalize; } -/* Stream output -- elevated white card for LLM text (primary content) */ +/* Stream output -- LLM text on the shared white surface */ .stream-output { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); font-family: var(--font-mono); font-size: var(--font-size-sm); color: var(--text); line-height: 1.6; white-space: pre-wrap; word-break: break-word; - padding: var(--space-4); - margin: var(--space-1) 0; + padding: var(--space-2) 0; + border-top: 1px solid var(--border); } /* Thinking indicator */ From fdfe71bba838f88cb90e3a426caa8d7bdd13dd72 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 11:03:32 +0700 Subject: [PATCH 265/412] render all LLM content as markdown via react-markdown Add <Md> component wrapping react-markdown + remark-gfm. Applied to all 7 LLM text surfaces: text blocks, thinking cards, pending thinking, pending stream, question text/context, artifact review content, and workflow decision status reports. Markdown CSS inherits font from parent context so thinking cards stay muted and text blocks stay primary. Supports headings, code blocks, inline code, tables, lists, blockquotes, task lists, links, and images. --- frontend/package-lock.json | 1556 ++++++++++++++++- frontend/package.json | 2 + frontend/src/components/ActivityFeed.tsx | 9 +- frontend/src/components/Md.tsx | 10 + .../interactions/ArtifactReview.tsx | 5 +- .../src/components/interactions/AskWizard.tsx | 5 +- .../interactions/WorkflowDecision.tsx | 3 +- frontend/src/main.tsx | 1 + frontend/src/styles/layout.css | 5 - frontend/src/styles/markdown.css | 158 ++ 10 files changed, 1693 insertions(+), 61 deletions(-) create mode 100644 frontend/src/components/Md.tsx create mode 100644 frontend/src/styles/markdown.css diff --git a/frontend/package-lock.json b/frontend/package-lock.json index 349e8cb..aba1820 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -11,6 +11,8 @@ "fast-json-patch": "^3.1.1", "react": "^19", "react-dom": "^19", + "react-markdown": "^10.1.0", + "remark-gfm": "^4.0.1", "zustand": "^5" }, "devDependencies": { @@ -1197,18 +1199,58 @@ "@babel/types": "^7.28.2" } }, + "node_modules/@types/debug": { + "version": "4.1.13", + "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz", + "integrity": "sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==", + "license": "MIT", + "dependencies": { + "@types/ms": "*" + } + }, "node_modules/@types/estree": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz", "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==", - "dev": true, + "license": "MIT" + }, + "node_modules/@types/estree-jsx": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/@types/estree-jsx/-/estree-jsx-1.0.5.tgz", + "integrity": "sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==", + "license": "MIT", + "dependencies": { + "@types/estree": "*" + } + }, + "node_modules/@types/hast": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz", + "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/mdast": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", + "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/ms": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz", + "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==", "license": "MIT" }, "node_modules/@types/react": { "version": "19.2.14", "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz", "integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==", - "devOptional": true, "license": "MIT", "dependencies": { "csstype": "^3.2.2" @@ -1224,6 +1266,18 @@ "@types/react": "^19.2.0" } }, + "node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/@ungap/structured-clone": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.0.tgz", + "integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==", + "license": "ISC" + }, "node_modules/@vitejs/plugin-react": { "version": "4.7.0", "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-4.7.0.tgz", @@ -1245,6 +1299,16 @@ "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0" } }, + "node_modules/bail": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/bail/-/bail-2.0.2.tgz", + "integrity": "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/baseline-browser-mapping": { "version": "2.10.11", "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.11.tgz", @@ -1313,6 +1377,66 @@ ], "license": "CC-BY-4.0" }, + "node_modules/ccount": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz", + "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz", + "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-html4": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz", + "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-legacy": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", + "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-reference-invalid": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz", + "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/comma-separated-tokens": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz", + "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/convert-source-map": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz", @@ -1324,14 +1448,12 @@ "version": "3.2.3", "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz", "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==", - "devOptional": true, "license": "MIT" }, "node_modules/debug": { "version": "4.4.3", "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", - "dev": true, "license": "MIT", "dependencies": { "ms": "^2.1.3" @@ -1345,6 +1467,41 @@ } } }, + "node_modules/decode-named-character-reference": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz", + "integrity": "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==", + "license": "MIT", + "dependencies": { + "character-entities": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/dequal": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", + "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/devlop": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", + "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/electron-to-chromium": { "version": "1.5.328", "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.328.tgz", @@ -1404,6 +1561,34 @@ "node": ">=6" } }, + "node_modules/escape-string-regexp": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz", + "integrity": "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/estree-util-is-identifier-name": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/estree-util-is-identifier-name/-/estree-util-is-identifier-name-3.0.0.tgz", + "integrity": "sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/extend": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", + "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", + "license": "MIT" + }, "node_modules/fast-json-patch": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/fast-json-patch/-/fast-json-patch-3.1.1.tgz", @@ -1439,68 +1624,1032 @@ "os": [ "darwin" ], - "engines": { - "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/gensync": { + "version": "1.0.0-beta.2", + "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz", + "integrity": "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/hast-util-to-jsx-runtime": { + "version": "2.3.6", + "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.6.tgz", + "integrity": "sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "hast-util-whitespace": "^3.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "style-to-js": "^1.0.0", + "unist-util-position": "^5.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-whitespace": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz", + "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/html-url-attributes": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/html-url-attributes/-/html-url-attributes-3.0.1.tgz", + "integrity": "sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/inline-style-parser": { + "version": "0.2.7", + "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.7.tgz", + "integrity": "sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==", + "license": "MIT" + }, + "node_modules/is-alphabetical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", + "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-alphanumerical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz", + "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==", + "license": "MIT", + "dependencies": { + "is-alphabetical": "^2.0.0", + "is-decimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-decimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz", + "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-hexadecimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz", + "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-plain-obj": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-4.1.0.tgz", + "integrity": "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/js-tokens": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", + "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/jsesc": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz", + "integrity": "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==", + "dev": true, + "license": "MIT", + "bin": { + "jsesc": "bin/jsesc" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/json5": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz", + "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==", + "dev": true, + "license": "MIT", + "bin": { + "json5": "lib/cli.js" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/longest-streak": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/longest-streak/-/longest-streak-3.1.0.tgz", + "integrity": "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/lru-cache": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz", + "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==", + "dev": true, + "license": "ISC", + "dependencies": { + "yallist": "^3.0.2" + } + }, + "node_modules/markdown-table": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-3.0.4.tgz", + "integrity": "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/mdast-util-find-and-replace": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/mdast-util-find-and-replace/-/mdast-util-find-and-replace-3.0.2.tgz", + "integrity": "sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "escape-string-regexp": "^5.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-from-markdown": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.3.tgz", + "integrity": "sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark": "^4.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-3.1.0.tgz", + "integrity": "sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==", + "license": "MIT", + "dependencies": { + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-gfm-autolink-literal": "^2.0.0", + "mdast-util-gfm-footnote": "^2.0.0", + "mdast-util-gfm-strikethrough": "^2.0.0", + "mdast-util-gfm-table": "^2.0.0", + "mdast-util-gfm-task-list-item": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-autolink-literal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-autolink-literal/-/mdast-util-gfm-autolink-literal-2.0.1.tgz", + "integrity": "sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "ccount": "^2.0.0", + "devlop": "^1.0.0", + "mdast-util-find-and-replace": "^3.0.0", + "micromark-util-character": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-footnote": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-footnote/-/mdast-util-gfm-footnote-2.1.0.tgz", + "integrity": "sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.1.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-strikethrough": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-strikethrough/-/mdast-util-gfm-strikethrough-2.0.0.tgz", + "integrity": "sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-table": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-table/-/mdast-util-gfm-table-2.0.0.tgz", + "integrity": "sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "markdown-table": "^3.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-task-list-item": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-task-list-item/-/mdast-util-gfm-task-list-item-2.0.0.tgz", + "integrity": "sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-expression": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdx-expression/-/mdast-util-mdx-expression-2.0.1.tgz", + "integrity": "sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-jsx": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-mdx-jsx/-/mdast-util-mdx-jsx-3.2.0.tgz", + "integrity": "sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "devlop": "^1.1.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "parse-entities": "^4.0.0", + "stringify-entities": "^4.0.0", + "unist-util-stringify-position": "^4.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdxjs-esm": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdxjs-esm/-/mdast-util-mdxjs-esm-2.0.1.tgz", + "integrity": "sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-phrasing": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-phrasing/-/mdast-util-phrasing-4.1.0.tgz", + "integrity": "sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-hast": { + "version": "13.2.1", + "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.1.tgz", + "integrity": "sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@ungap/structured-clone": "^1.0.0", + "devlop": "^1.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "trim-lines": "^3.0.0", + "unist-util-position": "^5.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-markdown": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-2.1.2.tgz", + "integrity": "sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "longest-streak": "^3.0.0", + "mdast-util-phrasing": "^4.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "unist-util-visit": "^5.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-string": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-4.0.0.tgz", + "integrity": "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.2.tgz", + "integrity": "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/debug": "^4.0.0", + "debug": "^4.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-core-commonmark": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.3.tgz", + "integrity": "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-destination": "^2.0.0", + "micromark-factory-label": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-title": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-html-tag-name": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-extension-gfm": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm/-/micromark-extension-gfm-3.0.0.tgz", + "integrity": "sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==", + "license": "MIT", + "dependencies": { + "micromark-extension-gfm-autolink-literal": "^2.0.0", + "micromark-extension-gfm-footnote": "^2.0.0", + "micromark-extension-gfm-strikethrough": "^2.0.0", + "micromark-extension-gfm-table": "^2.0.0", + "micromark-extension-gfm-tagfilter": "^2.0.0", + "micromark-extension-gfm-task-list-item": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-autolink-literal": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz", + "integrity": "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==", + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-footnote": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz", + "integrity": "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-strikethrough": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-strikethrough/-/micromark-extension-gfm-strikethrough-2.1.0.tgz", + "integrity": "sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-table": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz", + "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-tagfilter": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-tagfilter/-/micromark-extension-gfm-tagfilter-2.0.0.tgz", + "integrity": "sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==", + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-task-list-item": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-task-list-item/-/micromark-extension-gfm-task-list-item-2.1.0.tgz", + "integrity": "sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-factory-destination": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz", + "integrity": "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-label": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-2.0.1.tgz", + "integrity": "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-space": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-2.0.1.tgz", + "integrity": "sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-title": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-2.0.1.tgz", + "integrity": "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-whitespace": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.1.tgz", + "integrity": "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-character": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz", + "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-chunked": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-2.0.1.tgz", + "integrity": "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-classify-character": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-2.0.1.tgz", + "integrity": "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-combine-extensions": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.1.tgz", + "integrity": "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-numeric-character-reference": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.2.tgz", + "integrity": "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" } }, - "node_modules/gensync": { - "version": "1.0.0-beta.2", - "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz", - "integrity": "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==", - "dev": true, + "node_modules/micromark-util-decode-string": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-decode-string/-/micromark-util-decode-string-2.0.1.tgz", + "integrity": "sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], "license": "MIT", - "engines": { - "node": ">=6.9.0" + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-symbol": "^2.0.0" } }, - "node_modules/js-tokens": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", - "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==", - "dev": true, + "node_modules/micromark-util-encode": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz", + "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], "license": "MIT" }, - "node_modules/jsesc": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz", - "integrity": "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==", - "dev": true, + "node_modules/micromark-util-html-tag-name": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.1.tgz", + "integrity": "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-normalize-identifier": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.1.tgz", + "integrity": "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], "license": "MIT", - "bin": { - "jsesc": "bin/jsesc" - }, - "engines": { - "node": ">=6" + "dependencies": { + "micromark-util-symbol": "^2.0.0" } }, - "node_modules/json5": { - "version": "2.2.3", - "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz", - "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==", - "dev": true, + "node_modules/micromark-util-resolve-all": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.1.tgz", + "integrity": "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], "license": "MIT", - "bin": { - "json5": "lib/cli.js" - }, - "engines": { - "node": ">=6" + "dependencies": { + "micromark-util-types": "^2.0.0" } }, - "node_modules/lru-cache": { - "version": "5.1.1", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz", - "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==", - "dev": true, - "license": "ISC", + "node_modules/micromark-util-sanitize-uri": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz", + "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", "dependencies": { - "yallist": "^3.0.2" + "micromark-util-character": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-subtokenize": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-2.1.0.tgz", + "integrity": "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" } }, + "node_modules/micromark-util-symbol": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz", + "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-types": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.2.tgz", + "integrity": "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, "node_modules/ms": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", - "dev": true, "license": "MIT" }, "node_modules/nanoid": { @@ -1529,6 +2678,31 @@ "dev": true, "license": "MIT" }, + "node_modules/parse-entities": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz", + "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "character-entities-legacy": "^3.0.0", + "character-reference-invalid": "^2.0.0", + "decode-named-character-reference": "^1.0.0", + "is-alphanumerical": "^2.0.0", + "is-decimal": "^2.0.0", + "is-hexadecimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/parse-entities/node_modules/@types/unist": { + "version": "2.0.11", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz", + "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==", + "license": "MIT" + }, "node_modules/picocolors": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", @@ -1578,6 +2752,16 @@ "node": "^10 || ^12 || >=14" } }, + "node_modules/property-information": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/property-information/-/property-information-7.1.0.tgz", + "integrity": "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/react": { "version": "19.2.4", "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz", @@ -1599,6 +2783,33 @@ "react": "^19.2.4" } }, + "node_modules/react-markdown": { + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/react-markdown/-/react-markdown-10.1.0.tgz", + "integrity": "sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "hast-util-to-jsx-runtime": "^2.0.0", + "html-url-attributes": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "remark-parse": "^11.0.0", + "remark-rehype": "^11.0.0", + "unified": "^11.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + }, + "peerDependencies": { + "@types/react": ">=18", + "react": ">=18" + } + }, "node_modules/react-refresh": { "version": "0.17.0", "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.17.0.tgz", @@ -1609,6 +2820,72 @@ "node": ">=0.10.0" } }, + "node_modules/remark-gfm": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz", + "integrity": "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-gfm": "^3.0.0", + "micromark-extension-gfm": "^3.0.0", + "remark-parse": "^11.0.0", + "remark-stringify": "^11.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-parse": { + "version": "11.0.0", + "resolved": "https://registry.npmjs.org/remark-parse/-/remark-parse-11.0.0.tgz", + "integrity": "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-from-markdown": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-rehype": { + "version": "11.1.2", + "resolved": "https://registry.npmjs.org/remark-rehype/-/remark-rehype-11.1.2.tgz", + "integrity": "sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "mdast-util-to-hast": "^13.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-stringify": { + "version": "11.0.0", + "resolved": "https://registry.npmjs.org/remark-stringify/-/remark-stringify-11.0.0.tgz", + "integrity": "sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-to-markdown": "^2.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/rollup": { "version": "4.60.0", "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.0.tgz", @@ -1680,6 +2957,48 @@ "node": ">=0.10.0" } }, + "node_modules/space-separated-tokens": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz", + "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/stringify-entities": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz", + "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==", + "license": "MIT", + "dependencies": { + "character-entities-html4": "^2.0.0", + "character-entities-legacy": "^3.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/style-to-js": { + "version": "1.1.21", + "resolved": "https://registry.npmjs.org/style-to-js/-/style-to-js-1.1.21.tgz", + "integrity": "sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==", + "license": "MIT", + "dependencies": { + "style-to-object": "1.0.14" + } + }, + "node_modules/style-to-object": { + "version": "1.0.14", + "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-1.0.14.tgz", + "integrity": "sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==", + "license": "MIT", + "dependencies": { + "inline-style-parser": "0.2.7" + } + }, "node_modules/tinyglobby": { "version": "0.2.15", "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz", @@ -1697,6 +3016,26 @@ "url": "https://github.com/sponsors/SuperchupuDev" } }, + "node_modules/trim-lines": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz", + "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/trough": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/trough/-/trough-2.2.0.tgz", + "integrity": "sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/typescript": { "version": "5.9.3", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", @@ -1711,6 +3050,93 @@ "node": ">=14.17" } }, + "node_modules/unified": { + "version": "11.0.5", + "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz", + "integrity": "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "bail": "^2.0.0", + "devlop": "^1.0.0", + "extend": "^3.0.0", + "is-plain-obj": "^4.0.0", + "trough": "^2.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-is": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.1.tgz", + "integrity": "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-position": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-5.0.0.tgz", + "integrity": "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-stringify-position": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz", + "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.1.0.tgz", + "integrity": "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-parents": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.0.2.tgz", + "integrity": "sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/update-browserslist-db": { "version": "1.2.3", "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz", @@ -1742,6 +3168,34 @@ "browserslist": ">= 4.21.0" } }, + "node_modules/vfile": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz", + "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-message": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.3.tgz", + "integrity": "sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/vite": { "version": "6.4.1", "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.1.tgz", @@ -1852,6 +3306,16 @@ "optional": true } } + }, + "node_modules/zwitch": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", + "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } } } } diff --git a/frontend/package.json b/frontend/package.json index bb1ea6c..8972ead 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -12,6 +12,8 @@ "fast-json-patch": "^3.1.1", "react": "^19", "react-dom": "^19", + "react-markdown": "^10.1.0", + "remark-gfm": "^4.0.1", "zustand": "^5" }, "devDependencies": { diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index 722d4f4..d98d009 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -1,6 +1,7 @@ import { useRef, useState } from 'react' import { useStore, ConversationEntry } from '../store/index' import { useAutoScroll } from '../hooks/useAutoScroll' +import { Md } from './Md' // -- Thinking ------------------------------------------------------------------ @@ -15,7 +16,7 @@ function ThinkingCard({ content }: { content: string }) { </div> {content && ( <div className={`activity-card-body ${expanded ? 'expanded' : ''}`}> - {content} + <Md>{content}</Md> </div> )} {isLong && !expanded && ( @@ -44,7 +45,7 @@ function StepHeader({ step, stepName, totalSteps }: { // -- Text block ---------------------------------------------------------------- function TextBlock({ text }: { text: string }) { - return <div className="stream-output">{text}</div> + return <div className="stream-output"><Md>{text}</Md></div> } // -- Tool lines ---------------------------------------------------------------- @@ -129,7 +130,7 @@ export function ActivityFeed() { <span className="activity-card-tool">thinking</span> </div> <div className="activity-card-body expanded"> - {conversation.pendingThinking} + <Md>{conversation.pendingThinking}</Md> </div> </div> )} @@ -145,7 +146,7 @@ export function ActivityFeed() { {/* Active stream output — text being produced right now */} {conversation?.pendingText && ( <div className="stream-output"> - {conversation.pendingText} + <Md>{conversation.pendingText}</Md> <span className="streaming-cursor" /> </div> )} diff --git a/frontend/src/components/Md.tsx b/frontend/src/components/Md.tsx new file mode 100644 index 0000000..6b3c892 --- /dev/null +++ b/frontend/src/components/Md.tsx @@ -0,0 +1,10 @@ +import ReactMarkdown from 'react-markdown' +import remarkGfm from 'remark-gfm' + +export function Md({ children }: { children: string }) { + return ( + <div className="markdown"> + <ReactMarkdown remarkPlugins={[remarkGfm]}>{children}</ReactMarkdown> + </div> + ) +} diff --git a/frontend/src/components/interactions/ArtifactReview.tsx b/frontend/src/components/interactions/ArtifactReview.tsx index 63f21e8..a4165cd 100644 --- a/frontend/src/components/interactions/ArtifactReview.tsx +++ b/frontend/src/components/interactions/ArtifactReview.tsx @@ -1,6 +1,7 @@ import { useState } from 'react' import { useStore } from '../../store/index' import * as api from '../../api/client' +import { Md } from '../Md' export function ArtifactReview() { const focus = useStore(s => s.run?.focus) @@ -32,9 +33,7 @@ export function ArtifactReview() { {description && <p className="phase-status">{description}</p>} <div className="artifact-review-content"> - <pre style={{ margin: 0, whiteSpace: 'pre-wrap', wordBreak: 'break-word' }}> - {content} - </pre> + <Md>{content}</Md> </div> <textarea diff --git a/frontend/src/components/interactions/AskWizard.tsx b/frontend/src/components/interactions/AskWizard.tsx index 94b2243..ba5f6d2 100644 --- a/frontend/src/components/interactions/AskWizard.tsx +++ b/frontend/src/components/interactions/AskWizard.tsx @@ -1,6 +1,7 @@ import { useState } from 'react' import { useStore, AskQuestion } from '../../store/index' import * as api from '../../api/client' +import { Md } from '../Md' // Normalize raw question options from LLM output. Options may arrive as strings // or dicts with varying key names. This is data cleaning for LLM output @@ -74,9 +75,9 @@ function QuestionCard({ Question {qIdx + 1} </div> {question.context && ( - <div className="question-context">{question.context}</div> + <div className="question-context"><Md>{question.context}</Md></div> )} - <div className="question-text">{question.question}</div> + <div className="question-text"><Md>{question.question}</Md></div> {question.multi && ( <div className="question-multi-hint">Select all that apply</div> )} diff --git a/frontend/src/components/interactions/WorkflowDecision.tsx b/frontend/src/components/interactions/WorkflowDecision.tsx index 9ef5195..9a1100d 100644 --- a/frontend/src/components/interactions/WorkflowDecision.tsx +++ b/frontend/src/components/interactions/WorkflowDecision.tsx @@ -1,6 +1,7 @@ import { useState } from 'react' import { useStore } from '../../store/index' import * as api from '../../api/client' +import { Md } from '../Md' export function WorkflowDecision() { const focus = useStore(s => s.run?.focus) @@ -35,7 +36,7 @@ export function WorkflowDecision() { <div className="workflow-turn-header"> <span className="workflow-turn-role">Orchestrator</span> </div> - <div className="workflow-turn-body">{turn.status_report}</div> + <div className="workflow-turn-body">{turn.status_report ? <Md>{turn.status_report}</Md> : null}</div> </div> {turn.recommended_phases && turn.recommended_phases.length > 0 && ( <div className="workflow-options"> diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx index 79eca21..56fcd4a 100644 --- a/frontend/src/main.tsx +++ b/frontend/src/main.tsx @@ -3,6 +3,7 @@ import { createRoot } from 'react-dom/client' import './styles/variables.css' import './styles/layout.css' import './styles/components.css' +import './styles/markdown.css' import App from './App' const root = document.getElementById('root')! diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index 0f0c19c..6a8d6fc 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -145,8 +145,6 @@ font-family: var(--font-mono); font-size: 12px; color: var(--text-muted); - white-space: pre-wrap; - word-break: break-word; line-height: 1.5; } @@ -288,9 +286,6 @@ font-family: var(--font-mono); font-size: var(--font-size-sm); color: var(--text); - line-height: 1.6; - white-space: pre-wrap; - word-break: break-word; padding: var(--space-2) 0; border-top: 1px solid var(--border); } diff --git a/frontend/src/styles/markdown.css b/frontend/src/styles/markdown.css new file mode 100644 index 0000000..ae4c925 --- /dev/null +++ b/frontend/src/styles/markdown.css @@ -0,0 +1,158 @@ +/* Markdown rendered content — inherits font from parent context so the + * same <Md> component works in both muted thinking cards and primary + * text blocks without special-casing. */ + +.markdown { + line-height: 1.6; + word-break: break-word; +} + +/* Vertical rhythm: consistent spacing between block elements */ +.markdown > :first-child { margin-top: 0; } +.markdown > :last-child { margin-bottom: 0; } + +.markdown h1, +.markdown h2, +.markdown h3, +.markdown h4 { + color: var(--text-strong); + font-family: var(--font-mono); + margin: 1em 0 0.4em; + line-height: 1.3; +} + +.markdown h1 { font-size: 1.3em; } +.markdown h2 { font-size: 1.15em; } +.markdown h3 { font-size: 1.05em; } +.markdown h4 { font-size: 1em; } + +.markdown p { + margin: 0.5em 0; +} + +/* Inline code */ +.markdown code { + font-family: var(--font-mono); + font-size: 0.9em; + background: var(--bg-muted); + border: 1px solid var(--border); + border-radius: 3px; + padding: 1px 4px; +} + +/* Code blocks — override inline code styles */ +.markdown pre { + margin: 0.6em 0; + padding: var(--space-2) var(--space-4); + background: var(--bg-muted); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + overflow-x: auto; +} + +.markdown pre code { + background: none; + border: none; + border-radius: 0; + padding: 0; + font-size: var(--font-size-sm); + line-height: 1.5; +} + +/* Lists */ +.markdown ul, +.markdown ol { + margin: 0.5em 0; + padding-left: 1.5em; +} + +.markdown li { + margin: 0.2em 0; +} + +.markdown li > p { + margin: 0.2em 0; +} + +/* Nested lists — tighter spacing */ +.markdown li ul, +.markdown li ol { + margin: 0.1em 0; +} + +/* Tables (via remark-gfm) */ +.markdown table { + border-collapse: collapse; + margin: 0.6em 0; + font-size: 0.9em; + width: auto; +} + +.markdown th, +.markdown td { + border: 1px solid var(--border); + padding: 4px 8px; + text-align: left; +} + +.markdown th { + background: var(--bg-muted); + font-weight: 600; + color: var(--text-strong); +} + +/* Blockquotes */ +.markdown blockquote { + margin: 0.5em 0; + padding: 2px 0 2px var(--space-4); + border-left: 3px solid var(--border-strong); + color: var(--text-muted); +} + +.markdown blockquote p { + margin: 0.2em 0; +} + +/* Horizontal rules */ +.markdown hr { + border: none; + border-top: 1px solid var(--border); + margin: 0.8em 0; +} + +/* Links */ +.markdown a { + color: var(--copper); + text-decoration: underline; + text-decoration-color: var(--copper-border); + text-underline-offset: 2px; +} + +.markdown a:hover { + color: var(--text-strong); +} + +/* Task lists (via remark-gfm) */ +.markdown ul.contains-task-list { + list-style: none; + padding-left: 0; +} + +.markdown li.task-list-item { + display: flex; + align-items: baseline; + gap: 6px; +} + +/* Strong / emphasis */ +.markdown strong { + color: var(--text-strong); + font-weight: 600; +} + +/* Images — constrain to content width */ +.markdown img { + max-width: 100%; + height: auto; + border-radius: var(--radius-sm); +} From d465d9745f45f442a14d26e8d0371a9d7cdcd49f Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 11:21:07 +0700 Subject: [PATCH 266/412] rewrite auto-scroll with ResizeObserver for reliable sticky-scroll Replace render-time scrollHeight check with scroll-event tracking + ResizeObserver on inner content. Fires on actual DOM size changes (markdown reflow, image loads, new entries) regardless of React batching. Pins to bottom by default, releases on scroll-up, re-pins when user scrolls back down. --- frontend/src/hooks/useAutoScroll.ts | 51 ++++++++++++++++++++++++----- 1 file changed, 42 insertions(+), 9 deletions(-) diff --git a/frontend/src/hooks/useAutoScroll.ts b/frontend/src/hooks/useAutoScroll.ts index 87b851b..752dc0f 100644 --- a/frontend/src/hooks/useAutoScroll.ts +++ b/frontend/src/hooks/useAutoScroll.ts @@ -1,16 +1,49 @@ -import { useEffect, RefObject } from 'react' +import { useEffect, useRef, RefObject } from 'react' -// useAutoScroll scrolls the referenced element to the bottom after every -// render of the calling component, but only if the user is already near the -// bottom. This preserves intentional scroll position when the user scrolls up -// to read earlier entries. Replaces manual scrollTop manipulation in koan.js. +// Sticky-scroll: stays pinned to the bottom while new content streams in, +// but releases when the user scrolls up. Re-pins when they scroll back down. +// +// How it works: +// - Scroll events on the container track whether the user is "at bottom" +// - A ResizeObserver on the inner content detects ANY size change (new +// entries, markdown reflow, image loads, code block expansion) +// - When content grows while pinned → scroll to bottom +// +// This is resize-driven, not render-driven — it fires on actual DOM changes +// regardless of React batching or async rendering. export function useAutoScroll(ref: RefObject<HTMLDivElement | null>): void { + const pinned = useRef(true) + useEffect(() => { const el = ref.current if (!el) return - const atBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - 40 - if (atBottom) { - el.scrollTop = el.scrollHeight + + const content = el.firstElementChild as HTMLElement | null + if (!content) return + + // Track whether user is near the bottom. + // 60px threshold forgives small overscroll / rounding. + const onScroll = () => { + pinned.current = + el.scrollTop + el.clientHeight >= el.scrollHeight - 60 + } + + // When content grows and we're pinned, scroll to bottom. + const ro = new ResizeObserver(() => { + if (pinned.current) { + el.scrollTop = el.scrollHeight + } + }) + + el.addEventListener('scroll', onScroll, { passive: true }) + ro.observe(content) + + // Initial scroll to bottom. + el.scrollTop = el.scrollHeight + + return () => { + el.removeEventListener('scroll', onScroll) + ro.disconnect() } - }) + }, [ref]) } From b68ed56ad4cd99265e27a9f6be95d79a5b04ecec Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 11:27:16 +0700 Subject: [PATCH 267/412] improve layout spacing: wider app, narrower sidebars, more breathing room MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - App max-width 1300→1600px for widescreen monitors - Sidebars narrowed from clamp(240,20vw,300) to clamp(180,14vw,240) giving ~200px more to the main content area - Feed inner padding 8/16→24px, entry gap 2→8px - Feed scroll padding 16/24→24/32px - Step headers get more top margin for section separation - Text blocks get more vertical padding - Tool lines slightly smaller (xs) to differentiate from LLM text - Remove stream-output border-top (spacing handles separation now) --- frontend/src/styles/layout.css | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index 6a8d6fc..36ddb0b 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -6,7 +6,7 @@ flex-direction: column; height: 100vh; overflow: hidden; - max-width: 1300px; + max-width: 1600px; margin: 0 auto; } @@ -81,7 +81,7 @@ flex: 1 1 0; min-height: 0; overflow-y: overlay; - padding: var(--space-4) var(--space-6); + padding: var(--space-6) var(--space-8); /* Subtle fade at top when scrolled */ mask-image: linear-gradient(to bottom, transparent, black 8px, black); -webkit-mask-image: linear-gradient(to bottom, transparent, black 8px, black); @@ -93,12 +93,11 @@ .activity-feed-inner { display: flex; flex-direction: column; - gap: 2px; - max-width: 960px; + gap: var(--space-2); background: var(--bg-elevated); border: 1px solid var(--border); border-radius: var(--radius-lg); - padding: var(--space-2) var(--space-4); + padding: var(--space-6); } /* ---- Thinking card -- muted inset that visually recedes ---- */ @@ -106,7 +105,7 @@ background: var(--plum-bg); border-left: 3px solid var(--plum); border-radius: 0 var(--radius-sm) var(--radius-sm) 0; - margin: var(--space-1) 0; + margin: var(--space-2) 0; overflow: hidden; } @@ -213,11 +212,11 @@ display: flex; gap: var(--space-1); font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--font-size-xs); color: var(--text-muted); - padding: 3px 0; + padding: 2px 0; line-height: 1.4; - min-height: 20px; + min-height: 18px; } .activity-line.activity-done { @@ -263,8 +262,8 @@ display: flex; align-items: baseline; gap: var(--space-2); - padding: var(--space-4) 0 var(--space-1); - margin-top: var(--space-2); + padding: var(--space-4) 0 var(--space-2); + margin-top: var(--space-4); border-bottom: 1px solid var(--border); font-family: var(--font-mono); font-size: var(--font-size-sm); @@ -286,8 +285,7 @@ font-family: var(--font-mono); font-size: var(--font-size-sm); color: var(--text); - padding: var(--space-2) 0; - border-top: 1px solid var(--border); + padding: var(--space-4) 0 var(--space-2); } /* Thinking indicator */ @@ -380,7 +378,7 @@ * The sidebar scrolls independently of the feed column. */ .status-sidebar { - width: clamp(240px, 20vw, 300px); + width: clamp(180px, 14vw, 240px); flex-shrink: 0; background: var(--bg-surface); border-right: 1px solid var(--border); @@ -482,7 +480,7 @@ } .artifacts-sidebar { - width: clamp(240px, 20vw, 300px); + width: clamp(180px, 14vw, 240px); flex-shrink: 0; background: var(--bg-surface); border-left: 1px solid var(--border); From 07df4ba4120feb31cf33336c439aff464ff4e86f Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 12:10:28 +0700 Subject: [PATCH 268/412] hide agent monitor entirely when no agents are running or queued The counter bar showing 0/0/6/0 adds no value. Now returns null when hasActive is false, reclaiming the vertical space for content. --- frontend/src/components/AgentMonitor.tsx | 69 ++++++++++++------------ 1 file changed, 33 insertions(+), 36 deletions(-) diff --git a/frontend/src/components/AgentMonitor.tsx b/frontend/src/components/AgentMonitor.tsx index 66ac5d9..39b1b0d 100644 --- a/frontend/src/components/AgentMonitor.tsx +++ b/frontend/src/components/AgentMonitor.tsx @@ -84,9 +84,10 @@ export function AgentMonitor() { const total = running.length + queued.length + done.length + failed.length if (total === 0) return null - // Collapse to just the counter bar when nothing is active + // Hide entirely when nothing is active — counter bar adds no value + // when all agents are done. const hasActive = running.length > 0 || queued.length > 0 - const collapsed = !hasActive + if (!hasActive) return null return ( <div id="monitor" className="monitor"> @@ -98,44 +99,40 @@ export function AgentMonitor() { failed={failed.length} /> - {!collapsed && ( + {running.length > 0 && ( <> - {running.length > 0 && ( - <> - <SectionHeader icon="●" label="running" className="section-running" /> - {running.map(a => <AgentRow key={a.agentId} agent={a} />)} - </> - )} + <SectionHeader icon="●" label="running" className="section-running" /> + {running.map(a => <AgentRow key={a.agentId} agent={a} />)} + </> + )} - {queued.length > 0 && ( - <> - <SectionHeader icon="○" label="queued" className="section-queued" /> - {queued.map(a => ( - <div key={a.agentId} className="agent-row agent-row-queued"> - <span className="agent-row-icon agent-status-queued">○</span> - <span className="agent-row-name agent-name-queued">{a.label || 'scout'}</span> - <span className="agent-row-model">--</span> - <span className="agent-row-tokens">--</span> - <span className="agent-row-time">--</span> - <span className="agent-row-doing agent-doing-dim">queued</span> - </div> - ))} - </> - )} + {queued.length > 0 && ( + <> + <SectionHeader icon="○" label="queued" className="section-queued" /> + {queued.map(a => ( + <div key={a.agentId} className="agent-row agent-row-queued"> + <span className="agent-row-icon agent-status-queued">○</span> + <span className="agent-row-name agent-name-queued">{a.label || 'scout'}</span> + <span className="agent-row-model">--</span> + <span className="agent-row-tokens">--</span> + <span className="agent-row-time">--</span> + <span className="agent-row-doing agent-doing-dim">queued</span> + </div> + ))} + </> + )} - {done.length > 0 && ( - <> - <SectionHeader icon="✓" label="done" className="section-done" /> - {done.map(a => <AgentRow key={a.agentId} agent={a} />)} - </> - )} + {done.length > 0 && ( + <> + <SectionHeader icon="✓" label="done" className="section-done" /> + {done.map(a => <AgentRow key={a.agentId} agent={a} />)} + </> + )} - {failed.length > 0 && ( - <> - <SectionHeader icon="✘" label="failed" className="section-failed" /> - {failed.map(a => <AgentRow key={a.agentId} agent={a} />)} - </> - )} + {failed.length > 0 && ( + <> + <SectionHeader icon="✘" label="failed" className="section-failed" /> + {failed.map(a => <AgentRow key={a.agentId} agent={a} />)} </> )} </div> From 354cdede3ee8d1e2ad707c7dcefb70cfef327b79 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 13:55:13 +0700 Subject: [PATCH 269/412] chore: remove stale __pycache__ bytecode files --- koan/lib/__pycache__/__init__.cpython-312.pyc | Bin 141 -> 0 bytes koan/lib/__pycache__/permissions.cpython-312.pyc | Bin 3820 -> 0 bytes koan/lib/__pycache__/phase_dag.cpython-312.pyc | Bin 2299 -> 0 bytes 3 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 koan/lib/__pycache__/__init__.cpython-312.pyc delete mode 100644 koan/lib/__pycache__/permissions.cpython-312.pyc delete mode 100644 koan/lib/__pycache__/phase_dag.cpython-312.pyc diff --git a/koan/lib/__pycache__/__init__.cpython-312.pyc b/koan/lib/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index f10c49df172e06d26a0b504999330cb2e6174a5e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 141 zcmX@j%ge<81bfquW`gL)AOanHW&w&!XQ*V*Wb|9fP{ah}eFmxdrK2BOoLW?@pOc$f zl%ATWpPpHwpPiqW2O)AYll0@`GxIV_;^XxSDsOSv<mRW8=A_ycu>v(S0&y{j@sXL4 Kk+Fyw$N~UbeIRiF diff --git a/koan/lib/__pycache__/permissions.cpython-312.pyc b/koan/lib/__pycache__/permissions.cpython-312.pyc deleted file mode 100644 index ea27afb2a0217b0d81d8c70fd7857a9485e38392..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3820 zcmb^zO-vlu`OW^!?9Q@3{Db)$15Vf&Oq@iiO%gYbjcW(IwgA^QI2{c;4;b$<vw1Us zy%{Ph_28aLq*QhlM?y`cQqcoaFFy3pOHaM*8l=#X53brAd|M#u!KZ%T>@K?oDea*T z@$LKm-+SNR{4E?739R3+ziO+Eg!~hc@(LF>-2P*ZkcZ?3QHjc>$vij7ak%%SJ@ej4 zFYLXlFYTN6Px?9HA=Iz>H$Vf|BoDYSM^yf6?tm6h1sYTX?*kvXYETvDJO^CS<%Y^! z(5<QHmaK)3P$EYt(Ib@D5z0}m+9NV`M<_?NswisxV{tO1Hoy%VtM1TLu`*fX-mtlf z+fv01yWCdf2Hiikz4&_=svT<EFa48|`^Vy)FYvMBoD))X-LMo(GjtPB-*v^Bd*Lba z#93;|X=8SlGAERwY+f@>lsm@*-|?hP$2YB*bB=FD(^bben>MBaGMaIGj4En2GQ*54 z)lF(mnHKxR5yytlUz8`VT^k*Dd{ose$G^lhi#nm3V^=1Ii=1-;7-vxgF?3U#G8A1_ z%#{4;0yXiRPMu3i8uOVnwWw@b;IZDNG3pA*X3|)&%n}j&%Sl6@(NwA@snbxBT-4~2 ztT0QPQIgg<?<-zeJ)r0OuhQxeMFwj?uJ2W@%V<JI5E(A0+#>2aHB(v!j%%>{PONka zi`_3$7@9BL)}(2gv`Ta|T)IismBB{we6KoktrSo1-l$3$pFyYhEIBi$nAB->50GI- z#xSY8WU$ms+E|K<4zKB!lA?~^eMCo8DY^wA_OfQ0X>?}54H|Q543?aOkT3;q<OrEG zq!MIGfZn6Y1t7g_EL$C@mV6nrv}B4}1JjTsDb-lgU$!KfVVVQwU<@oOX-!3|*;Z9c zy4lk&y_!s)II*#7qr>v`;jyb%#>cN*ON<vEz7t=+13@=}E(FIBNC-|K=tb}v04H*N z^n4<5CGis(jg23UsT*+&w$m^^F??M<Eq^q6?ZU`#DTxzF%#iZJyoERC_E(^M9uk|g z${eytm|x{okLrEw87DSTeW^Y;LZj_d{q8OX(pYrv0_lLt+uWB#6~3zI1pY^zU`5Bm z94*@9SeJ!m>#n<)G>4Wd+HmF#%o<qGqIorBlP^ixTE&)4T0vsjZ*#VPkz-=%tTnE* zw{%C&a>oSPg8Tf*CRPpZaRI(zd)PO&m;KK6-o+w0wA669xi9lpZJBBF76!y!8>QD` zzp!8k6_?GIweB{TX_eoN(so&>(l{6*Kd2F~1v`-X5k%}`3k%9!ws7DLpX1P~k_(jO z)JPVj%9z>vU*ZwPc-Xw{*(hZh#>CBvn9W0O)PChFzI7$DD!X`H_U$ohEihgBtXoM# zWmC0#NSa^^bnudrHfg`q4drJVI#8j6?S!Gz<x>-hxW^Gn@(y2=aI5JB&gV;6Q_@Tc z28N_8Dq32ZPE$!;V46NFS#wkxz6Z@9X@NnSk@{SCI(|yJQ0ml@+j6R!7)Z@%%(NuS zkQ8-Mf%c4BG&PPL+%<H{t=#PWAM`v1^XC8I_99beEa^3AjN*7G`p=%Yp{I1{QxY@a zzSC&~+Lt=yVjr9^;lxH7ezTEku^}njcJ#zE1}hqId>I(D4mX$`zKJ8SVioBUPA?c& z63u8yN!8d9XA+8`bCf{mf=iLQvu)kz_OJmMConPMVHSZfvN(d*0XSY5?~bsfFdbsZ zu+$iICZNOUcSOz9bkoAHI9^B+hV8@=7&VRbB6UPyG0R-ithsm)Mm{`_6U4`mb!DEy z9Dt+AaQG5YVY8-FlU!ho>NwkAXopLgCZm?=1emfUyYCV%`A}VsQ$f+DiQP*oua|>^ zH()lIgXww7W~n|nt677XXho3LrU$D&T~1|S^up9irsN8hod<)T!N2)?$nq6ZXdr>w zFFwu-ojYw^>+j^FZ{`AT7I+e<d2sKk(EMn0{ruDRfz9~#kH_<GjX!U0e_r3dda^*c z&M^*P?HIQ!@G-GK_@G#*L$#kj6*|`XH;+H<e)~yqd-!(#%<XEmDOYXku-bNgPhRMG z76|=1^s7*=;k_ple>uAyxVqCOt?N%Fo?OcHU&u!<<^mW0)zG^(k#Bfo<?3@G_9&be zPN2;F^;GWcMDE7z+{9$Ae<~lnlMCFzYt()*k{7zxF8(o*?;ZMksQ$OXoo4Cb^5@HI zKiz8Xe{lI(wDnQnHy5^}eb1!cwOe0DzLnn1OYd$;XI8^UDLeJj+SRA^r~lmZWPWRC z^xL7E`JtQJx2AG;w5?lrbMu+}t<3h&r_UOiAC7!JveP2(w6s6c)>}5ueDC)*HWftD z8{au`YHehFY4hIZ-Q0&$x$Zl=es6nIfgnFX+NE+3o;SCxS@}?Z&ey*W@gi|=B9VyK zFzC&My@TM)!R{>VvXG-pvL)<pYzPS<{GcdP-g8CZd#6Oej)y(d@u5^a>WH#Dvj7w- z%M2$YeC0shK~5D*fiHd>GaRh!P2>j;zEa#ubE2|b^??mm+!DjmbL*^FiI{$WAnYTg zeh9z`ygzTK3u$_ejR1<B*GvH{csY*ycN5`yz9TK)k*<I6vDJ<(zH7z18z7yp?-5U* zXP<aFy({8_1Z+5@clE6|Z8qon&Te%Mt%M%@Y>N!-@+8`_M*^+<J_$sH-8vF!-Xp#i zKz$KmS0wfAdxY-*l&=?dBc!o&kNCR)^*0K;H7+V5DgxR>Vyz&2425GTTzd@AHbiR? z#bf#U0QGgE<<@TC_8_+vxyRoC^dzFkh20CD%iN$RM`F3Ull$Z{$9Z-qJf!>N9ufQD zUShX*C9)cU4cx1R^qq!7y#;iCpEpMuR(05M-oi1+mYt5{J6%16&<EVWju<X@;rDs8 kuHc7XNdIVSLBL&r#M%l$+`)xAT<Jm$;l=O6Ky!ofAB6t)?f?J) diff --git a/koan/lib/__pycache__/phase_dag.cpython-312.pyc b/koan/lib/__pycache__/phase_dag.cpython-312.pyc deleted file mode 100644 index ef054c9a6b871694c61e1fae6728177b5380cce8..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2299 zcmZWq&2JM&6rZu3;17cH1tBznaRL=?VnS6Q6@o~VxJ_E(rUZIOg|_RRu{~tHyUgr5 zv6Tad{sFyl=^;`tAXKU9|4^w?FHS+Kwd$?vfg3bc4>|SCY~mzzrJ0?Nw{L#$_kQ#C z*S@|qg6GVmpShJm=ub7-fAkJQc;_crd4ldEiYT^G9j{`HXpF|~SUtWPhjD`TRAbOE z?S*y>S`u0cS{hoWimQko|1Pzfpna@|p11-2Vu<zD5Y2v%pX2Dj)nl|Db_dih9i&5a zn4YAk=m<ScN9h^;eUiQd7Gv6Cf{uTaSWVGMdKTVkc%OrJhMuPc-p8A{{DoJ_aUO>m z({Wti^ttQESFva<RrI*ETr(xx?Jo<?DupU@n9xSMY0DL?P_f;0xtsEtRV#S5>FoCV z+*)IPp)8oWM%{I1chnNDlm%1xykc5@p<&vbY9C>WZ7?fPXYP*jx@WUGb0Q2!tSndU z`HbdMVJ`=ZH70riqBy3yr0P<tQ^^pJAta8gt`E8vq1^Jn>IO1RY%UMYA3O*LmKScV z6ped#Z<SUS?=5~_TA9;+PjtQM6ZD!swR=`;xFXyZb0j<LF&tc6TE0_UDwggQ=MC+A zrFCa1uzg+-Zs1U2xs;WGRl+tr+l}}nCTvJw1ePBNM#&fN-XgwBfUBxQT!#quDBwa9 zBwKUy5Cpev5|IH89iMIZY6_pgwC(}Z#1k$Be+8R0m`xZYljt<Irsi3NJB$R93G&bl zgu|MWtaHCcB%H$>ive$DRhV_z`gp}-7OymkO0vT((<Y{{Y8<8t>UCmzaFA)$rU|6g zBz1_+p4K2-2l7cMlMqB}{*y>N48n9pvmkj3;yjvm5~*ho3uPX2D4=N`pt<>FBp*g1 zS(O!|rf4b-B(S2bO}z)?*+c?(z#C}~f?3>`S@$Tv23e`rfHxU<Of<LzSY^|<YKlOM z$vrd;CU^zHS8{DFEW6S#bma@_X>hhq7>GLn3#S@oPU%@^7A}hbz8vMvteV`BzJ?}S z1IyfFw#vr7%v-~6YZi3zARLTzI$vD5eRpwL3)R{y3!qel642tR6kUSB6XdHk{XB%# zx1UW^MbFhWhi3&n!=-#oWMLe}tIU6f!yZpvd#U`B-NMX$5Q?0!>r6len5lAqX3aI7 zsIz%_Mq3-ytX}e(;V`%`WMC=kTwz3>#A$GK4VpX&-DC7eX6*M2+0KxylTTwWGE?ou z)DCQ*BO&#`f)4323?QU#xPCXJO|)Md_umw+T~tBkW2IN>gM2KE+sx4bggQKmN{qlT z%yMa%f$th7ZI~c?F%GNOm65`$V4irHo!lzE$i4?4pFY~oTy7^Wi&5A-f>cp?i2P0X z3#`o|w1GtyBbdeZW=S<WNKFF+&Ui_eDqXblSoDLd|KaQdoYD`<5u4&1*vvtblh8dz zolO6?pKWK({g$z}itWO}_W1=E{&N52s@-0)+X*`Yyq9nI<d9m%VDbcQ;sbIIC~W|Z zVh9WXmf{1bOhd`5M<~K1@D^oPc_t*HbO@m88gKZ*ggdG3i%>W}f+m$W1$gM?$kfwM zUyRJQGqdf)tOi)hC&Ve(7b@>zuV7GLoL2U&ihbBfoL82Kvg_LUUXk1XR!nq9%0OIz zF5efX4WkmMnq?S52`KFGn;w(;xJdn3!#MOGG>kCSt?*G^29!HRg%*m=gO2SP(h)=q zByT_s3~V+hrod8ZQ2qej>o~^v-(iF&|3c%h(`fSQk9IqEyEAcV>uhJDur=P9xYEvD z?M&Qk=jQen4u-kOH$&;!SQ`zrhd$UrX&ieqhNiFnjgr@5J199FZ==EX@I@Hn`0LYX y!o!`M*~yhUIo`=tJGrm*V6Bt80)D2!Ph<^#cFtfty_3ZFebv?RKhS@u!}$-BDSbQu From 869f59328f8f5a2195dfdb871c468a6ff7fa306a Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 13:55:32 +0700 Subject: [PATCH 270/412] feat: add assistant_text stream event type to runners --- koan/runners/base.py | 2 +- koan/runners/claude.py | 10 ++++++++-- koan/runners/codex.py | 5 ++++- tests/test_runners.py | 20 +++++++++++++------- 4 files changed, 26 insertions(+), 11 deletions(-) diff --git a/koan/runners/base.py b/koan/runners/base.py index 1fd7318..4aa2322 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -11,7 +11,7 @@ @dataclass(kw_only=True) class StreamEvent: - type: Literal["token_delta", "turn_complete", "tool_call", "thinking"] + type: Literal["token_delta", "turn_complete", "tool_call", "thinking", "assistant_text"] content: str | None = None is_thinking: bool = False tool_name: str | None = None diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 5547501..2fa1140 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -196,6 +196,7 @@ def _parse_assistant(self, data: dict) -> list[StreamEvent]: return [] events: list[StreamEvent] = [] + text_parts: list[str] = [] for block in blocks: if not isinstance(block, dict): continue @@ -217,14 +218,19 @@ def _parse_assistant(self, data: dict) -> list[StreamEvent]: # stream_event deltas (--include-partial-messages). Only # emit them from assistant messages as a fallback when no # stream_events were seen (e.g. partial-messages disabled). - elif block_type == "text" and not self._saw_stream_events: - events.append(StreamEvent(type="token_delta", content=block.get("text", ""))) + elif block_type == "text": + text = block.get("text", "") + text_parts.append(text) + if not self._saw_stream_events: + events.append(StreamEvent(type="token_delta", content=text)) elif block_type == "thinking" and not self._saw_stream_events: events.append(StreamEvent( type="thinking", is_thinking=True, content=block.get("thinking") or block.get("text"), )) + if text_parts: + events.append(StreamEvent(type="assistant_text", content="".join(text_parts))) return events def _parse_result(self, data: dict) -> StreamEvent | None: diff --git a/koan/runners/codex.py b/koan/runners/codex.py index 15265f5..632a61a 100644 --- a/koan/runners/codex.py +++ b/koan/runners/codex.py @@ -115,7 +115,10 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: # Codex emits complete messages (not token-by-token). # Append a newline so consecutive messages don't run together # in the stream buffer. - return [StreamEvent(type="token_delta", content=text + "\n")] + return [ + StreamEvent(type="token_delta", content=text + "\n"), + StreamEvent(type="assistant_text", content=text), + ] elif item_type == "function_call": raw_name = item.get("name") or item.get("call_id", "tool") canonical = _normalize_tool_name(raw_name) diff --git a/tests/test_runners.py b/tests/test_runners.py index 5100a82..9b7fb90 100644 --- a/tests/test_runners.py +++ b/tests/test_runners.py @@ -28,7 +28,7 @@ def _msg(self, content: list) -> str: def test_text_delta(self): line = self._msg([{"type": "text", "text": "hello"}]) evts = self.runner.parse_stream_event(line) - assert evts == [StreamEvent(type="token_delta", content="hello")] + assert evts == [StreamEvent(type="token_delta", content="hello"), StreamEvent(type="assistant_text", content="hello")] def test_tool_call(self): line = self._msg([{"type": "tool_use", "name": "bash", "input": {"cmd": "ls"}}]) @@ -81,9 +81,12 @@ def test_stream_event_suppresses_assistant_text(self): {"type": "tool_use", "name": "bash", "input": {"cmd": "ls"}}, ]) evts = self.runner.parse_stream_event(msg_line) - # text is skipped (already streamed), tool_use preserved - assert len(evts) == 1 + # text is skipped for streaming (already streamed), but assistant_text still emitted; + # tool_use is preserved + assert len(evts) == 2 assert evts[0].type == "tool_call" + assert evts[1].type == "assistant_text" + assert evts[1].content == "hi" def test_result_success(self): line = json.dumps({"type": "result", "subtype": "success", "result": "done"}) @@ -103,9 +106,10 @@ def test_multi_block_text_and_tool(self): {"type": "tool_use", "name": "read", "input": {"path": "/a"}}, ]) evts = self.runner.parse_stream_event(line) - assert len(evts) == 2 + assert len(evts) == 3 assert evts[0] == StreamEvent(type="token_delta", content="calling tool") assert evts[1] == StreamEvent(type="tool_call", tool_name="read", tool_args={"path": "/a"}, summary="") + assert evts[2] == StreamEvent(type="assistant_text", content="calling tool") def test_multi_block_thinking_and_text(self): line = self._msg([ @@ -113,9 +117,10 @@ def test_multi_block_thinking_and_text(self): {"type": "text", "text": "answer"}, ]) evts = self.runner.parse_stream_event(line) - assert len(evts) == 2 + assert len(evts) == 3 assert evts[0] == StreamEvent(type="thinking", is_thinking=True, content="reasoning") assert evts[1] == StreamEvent(type="token_delta", content="answer") + assert evts[2] == StreamEvent(type="assistant_text", content="answer") def test_multi_block_with_unknown_type_skipped(self): line = self._msg([ @@ -124,9 +129,10 @@ def test_multi_block_with_unknown_type_skipped(self): {"type": "tool_use", "name": "bash", "input": {}}, ]) evts = self.runner.parse_stream_event(line) - assert len(evts) == 2 + assert len(evts) == 3 assert evts[0].type == "token_delta" assert evts[1].type == "tool_call" + assert evts[2].type == "assistant_text" def test_multi_block_non_dict_block_skipped(self): line = self._msg([ @@ -134,7 +140,7 @@ def test_multi_block_non_dict_block_skipped(self): {"type": "text", "text": "valid"}, ]) evts = self.runner.parse_stream_event(line) - assert evts == [StreamEvent(type="token_delta", content="valid")] + assert evts == [StreamEvent(type="token_delta", content="valid"), StreamEvent(type="assistant_text", content="valid")] # -- CodexRunner: parse_stream_event ------------------------------------------- From b4f42e8a3dbc1643c12147d858adeaee8abbe652 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 13:55:45 +0700 Subject: [PATCH 271/412] feat: add read_only parameter to runner build_command --- koan/lib/permissions.py | 2 ++ koan/runners/base.py | 1 + koan/runners/claude.py | 3 +++ koan/runners/codex.py | 3 +++ koan/runners/gemini.py | 23 +++++++++++++++++++++++ koan/runners/resolver.py | 3 +++ 6 files changed, 35 insertions(+) diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index 00a6d5f..be5e76b 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -110,6 +110,8 @@ "cross-artifact-validator", }) +READ_ONLY_ROLES: frozenset[str] = frozenset({"scout"}) + STEP_1_BLOCKED_TOOLS: frozenset[str] = frozenset({ "koan_request_scouts", "koan_ask_question", diff --git a/koan/runners/base.py b/koan/runners/base.py index 4aa2322..dec2c6e 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -45,6 +45,7 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, + read_only: bool = False, ) -> list[str]: ... def list_models(self, binary: str) -> list[ModelInfo]: ... diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 2fa1140..f9d5bf8 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -102,6 +102,7 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, + read_only: bool = False, ) -> list[str]: if thinking not in self.supported_thinking_modes: raise RunnerError(RunnerDiagnostic( @@ -138,6 +139,8 @@ def build_command( if thinking != "disabled": cmd.extend(["--effort", _EFFORT_MAP[thinking]]) cmd.extend(["--model", model]) + if read_only: + cmd.extend(["--disallowedTools", "Write,Edit"]) cmd.extend(installation.extra_args) return cmd diff --git a/koan/runners/codex.py b/koan/runners/codex.py index 632a61a..92900e3 100644 --- a/koan/runners/codex.py +++ b/koan/runners/codex.py @@ -68,6 +68,7 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, + read_only: bool = False, ) -> list[str]: if thinking != "disabled": raise RunnerError(RunnerDiagnostic( @@ -82,6 +83,8 @@ def build_command( "-c", f"mcp_servers.koan.url={mcp_url}", boot_prompt, ] + if read_only: + cmd.extend(["--sandbox", "read-only"]) cmd.extend(["--model", model]) cmd.extend(installation.extra_args) return cmd diff --git a/koan/runners/gemini.py b/koan/runners/gemini.py index f58e938..7a210e1 100644 --- a/koan/runners/gemini.py +++ b/koan/runners/gemini.py @@ -71,6 +71,7 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, + read_only: bool = False, ) -> list[str]: if thinking not in self.supported_thinking_modes: raise RunnerError(RunnerDiagnostic( @@ -87,7 +88,29 @@ def build_command( self._merge_mcp(existing, mcp_url, settings_path) self._write_settings(existing, settings_path, gemini_dir) + if read_only: + policy_path = config_dir / "read-only-policy.toml" + policy_content = ( + '# Deny write tools for read-only agents.\n' + '[[rule]]\n' + 'toolName = ["write_file", "replace"]\n' + 'decision = "deny"\n' + ) + try: + tmp = policy_path.with_suffix(".toml.tmp") + tmp.write_text(policy_content, "utf-8") + tmp.rename(policy_path) + except OSError as e: + raise RunnerError(RunnerDiagnostic( + code="policy_write_failed", + runner="gemini", + stage="build_command", + message=f"Failed to write read-only policy: {e}", + )) from e + cmd = [installation.binary, "--output-format", "stream-json", "-p", boot_prompt] + if read_only: + cmd.extend(["--policy", str(policy_path)]) if thinking != "disabled": cmd.extend(["--thinking-mode", thinking]) cmd.extend(["--model", model]) diff --git a/koan/runners/resolver.py b/koan/runners/resolver.py index e3e7b3b..55a08cb 100644 --- a/koan/runners/resolver.py +++ b/koan/runners/resolver.py @@ -52,12 +52,14 @@ def build_command( installation_or_model: AgentInstallation | str | None = None, model: str | None = None, thinking: ThinkingMode = "disabled", + read_only: bool = False, ) -> list[str]: # New 5-arg style: (boot_prompt, mcp_url, installation, model, thinking) if isinstance(installation_or_model, AgentInstallation): return self._inner.build_command( boot_prompt, mcp_url, installation_or_model, model or self._inner.name, thinking, + read_only=read_only, ) # Legacy 3-arg style: (boot_prompt, mcp_url, model_str) legacy_model = installation_or_model if isinstance(installation_or_model, str) else None @@ -70,6 +72,7 @@ def build_command( return self._inner.build_command( boot_prompt, mcp_url, installation, legacy_model or self._inner.name, "disabled", + read_only=read_only, ) From af0897e73bad2e68153eb5588c43ebf0a0781550 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 13:55:55 +0700 Subject: [PATCH 272/412] refactor: scout returns findings via SubagentResult instead of file --- koan/driver.py | 15 ++++++++++----- koan/lib/permissions.py | 2 -- koan/phases/__init__.py | 1 - koan/phases/scout.py | 18 ++++++++---------- koan/state.py | 1 + koan/subagent.py | 27 ++++++++++++++++++++------- koan/web/mcp_endpoint.py | 20 +++----------------- tests/test_subagent.py | 37 +++++++++++++++---------------------- 8 files changed, 57 insertions(+), 64 deletions(-) diff --git a/koan/driver.py b/koan/driver.py index 9b4a32d..799646b 100644 --- a/koan/driver.py +++ b/koan/driver.py @@ -166,7 +166,8 @@ async def run_workflow_orchestrator( } try: - exit_code = await spawn_subagent(task, app_state) + result = await spawn_subagent(task, app_state) + exit_code = result.exit_code except NotImplementedError: log.warning("spawn_subagent not implemented; workflow orchestrator skipped") return None @@ -216,7 +217,8 @@ async def run_story_execution( } try: - planner_exit = await spawn_subagent(planner_task, app_state) + result = await spawn_subagent(planner_task, app_state) + planner_exit = result.exit_code except NotImplementedError: log.warning("spawn_subagent not implemented; story execution skipped") return False @@ -236,7 +238,8 @@ async def run_story_execution( "subagent_dir": executor_dir, "story_id": story_id, } - executor_exit = await spawn_subagent(executor_task, app_state) + result = await spawn_subagent(executor_task, app_state) + executor_exit = result.exit_code executor_ok = executor_exit == 0 else: executor_ok = False @@ -362,7 +365,8 @@ async def run_story_loop(app_state: AppState, instructions: str | None) -> dict: } try: - pre_exit = await spawn_subagent(pre_task, app_state) + result = await spawn_subagent(pre_task, app_state) + pre_exit = result.exit_code except NotImplementedError: log.warning("spawn_subagent not implemented; story loop skipped") return {"success": False, "summary": "spawn_subagent not implemented"} @@ -449,7 +453,8 @@ async def run_phase( } try: - exit_code = await spawn_subagent(task, app_state) + result = await spawn_subagent(task, app_state) + exit_code = result.exit_code except NotImplementedError: log.warning("spawn_subagent not implemented; phase %s skipped", phase) return False diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index be5e76b..39eddf2 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -36,8 +36,6 @@ }), "scout": frozenset({ "koan_complete_step", - "edit", - "write", }), "decomposer": frozenset({ "koan_complete_step", diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index 34a565e..7bb2f45 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -33,7 +33,6 @@ class PhaseContext: completed_phase: str | None = None available_phases: list[str] = field(default_factory=list) scout_question: str | None = None - scout_output_file: str | None = None scout_investigator_role: str | None = None diff --git a/koan/phases/scout.py b/koan/phases/scout.py index cf353f6..da08029 100644 --- a/koan/phases/scout.py +++ b/koan/phases/scout.py @@ -2,7 +2,7 @@ # # Step 1 (Investigate) -- find entry points, read/trace code # Step 2 (Verify) -- spot-check critical claims with targeted tool calls -# Step 3 (Report) -- write findings.md with verified facts +# Step 3 (Report) -- output findings as final text response # # Scouts use cheap models for narrow codebase investigation. @@ -56,14 +56,14 @@ "- SHOULD be thorough within the question scope: follow references, check related files.\n" "- SHOULD note explicitly when something is NOT present (e.g., \"No tests found for this module\").\n" "\n" - "## Output file\n" + "## Output\n" "\n" - "You write a single markdown file with your findings. The file location and format are provided in your final step.\n" + "Your findings are returned as your final text response. Do not write any files.\n" + "The format is provided in your final step.\n" "\n" "## Tools available\n" "\n" "- All read tools (read, bash, grep, glob, find, ls) -- for reading the codebase.\n" - "- `write` / `edit` -- for writing the output file only.\n" "- `koan_complete_step` -- to advance to the next workflow step." ) @@ -72,7 +72,6 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: question = ctx.scout_question or "" - output_file = ctx.scout_output_file or "" investigator_role = ctx.scout_investigator_role or "" if step == 1: @@ -120,12 +119,11 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: return StepGuidance( title=STEP_NAMES[3], instructions=[ - "Write your findings to the output file.", + "Output your findings as your final response.", "", - f"**Output file:** {output_file}", - "", - "Write a compressed findings file. Optimize for signal density -- every line", - "should carry information the intake agent needs. No prose padding.", + "Write a compressed findings report directly as text. Optimize for signal", + "density -- every line should carry information the intake agent needs.", + "No prose padding. Do NOT write to any file.", "", "## Question", "Restate the assigned question in one line.", diff --git a/koan/state.py b/koan/state.py index 3ef4d4e..65ca4c5 100644 --- a/koan/state.py +++ b/koan/state.py @@ -44,6 +44,7 @@ class AgentState: pending_tool: asyncio.Future | None = None model: str | None = None token_count: dict = field(default_factory=lambda: {"sent": 0, "received": 0}) + final_response: str = "" is_primary: bool = True started_at: datetime = field(default_factory=_utcnow) diff --git a/koan/subagent.py b/koan/subagent.py index 40aec65..d81bf60 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -7,6 +7,7 @@ import json import os import uuid +from dataclasses import dataclass from pathlib import Path from typing import TYPE_CHECKING @@ -33,6 +34,7 @@ from .logger import get_logger from .phases import PHASE_MODULE_MAP, PhaseContext from .runners import RunnerDiagnostic, RunnerError +from .lib.permissions import READ_ONLY_ROLES from .runners.registry import RunnerRegistry if TYPE_CHECKING: @@ -47,6 +49,12 @@ def _now_iso() -> str: return datetime.now(timezone.utc).isoformat() +@dataclass +class SubagentResult: + exit_code: int + final_response: str = "" + + # -- Boot prompt --------------------------------------------------------------- def boot_prompt(role: str) -> str: @@ -75,7 +83,6 @@ def _build_phase_ctx(task: dict, subagent_dir: str) -> PhaseContext: completed_phase=task.get("completed_phase"), available_phases=task.get("available_phases", []), scout_question=task.get("question"), - scout_output_file=task.get("output_file"), scout_investigator_role=task.get("investigator_role"), retry_context=task.get("retryContext") or task.get("retry_context"), ) @@ -83,7 +90,7 @@ def _build_phase_ctx(task: dict, subagent_dir: str) -> PhaseContext: # -- Main spawn function ------------------------------------------------------- -async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None = None) -> int: +async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None = None) -> SubagentResult: role = task["role"] agent_id = str(uuid.uuid4()) store = app_state.projection_store @@ -125,7 +132,7 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None "agent_spawn_failed", build_agent_spawn_failed(role, e.diagnostic), ) - return 1 + return SubagentResult(exit_code=1) else: model = None installation = None @@ -143,7 +150,7 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None phase_module = PHASE_MODULE_MAP.get(role) if phase_module is None: log.error("no phase module for role %s", role) - return 1 + return SubagentResult(exit_code=1) # Create EventLog event_log = EventLog(subagent_dir, role, phase=role, model=model) @@ -175,9 +182,10 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None if installation is not None and thinking_mode is not None: cmd = runner.build_command( boot_prompt(role), mcp_url, installation, model, thinking_mode, + read_only=(role in READ_ONLY_ROLES), ) else: - cmd = runner.build_command(boot_prompt(role), mcp_url, model) + cmd = runner.build_command(boot_prompt(role), mcp_url, model, read_only=(role in READ_ONLY_ROLES)) except RunnerError as e: await event_log.emit_runner_diagnostic(e.diagnostic) store.push_event( @@ -186,7 +194,7 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None ) await event_log.close() del app_state.agents[agent_id] - return 1 + return SubagentResult(exit_code=1) # Emit agent_spawned only after build_command succeeds -- process is about to start store.push_event("agent_spawned", build_agent_spawned(agent), agent_id=agent_id) @@ -227,6 +235,9 @@ async def stream_stdout(): store.push_event("stream_delta", {"delta": ev.content or ""}, agent_id=agent_id) elif ev.type == "thinking": store.push_event("thinking", {"delta": ev.content or ""}, agent_id=agent_id) + elif ev.type == "assistant_text": + if ev.content: + agent.final_response = ev.content elif ev.type == "tool_call": # Close previous in-flight tool if last_call_id is not None and last_tool_name is not None: @@ -324,6 +335,8 @@ async def drain_stderr(): outcome = "completed" if exit_code == 0 else "failed" await event_log.emit_phase_end(outcome) await event_log.close() + + final_response = agent.final_response del app_state.agents[agent_id] # Emit agent_exited to projection @@ -338,7 +351,7 @@ async def drain_stderr(): ) log.info("%s (agent_id=%s) exited with code %d", role, agent_id, exit_code) - return exit_code + return SubagentResult(exit_code=exit_code, final_response=final_response) # -- Interaction cleanup ------------------------------------------------------- diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index d6dfa98..c8918db 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -229,32 +229,18 @@ async def koan_request_scouts(questions: list[dict] | None = None) -> str: "epic_dir": epic_dir, "subagent_dir": subagent_dir, "question": q.get("prompt", ""), - "output_file": "findings.md", "investigator_role": q.get("role", "investigator"), }) async def run_scout(scout_task: dict) -> str | None: async with semaphore: from ..subagent import spawn_subagent + result = await spawn_subagent(scout_task, _app_state) - exit_code = await spawn_subagent(scout_task, _app_state) - - # Require state.json with status=="completed" - state_path = Path(scout_task["subagent_dir"]) / "state.json" - try: - async with aiofiles.open(state_path, "r") as f: - projection = json.loads(await f.read()) - except (FileNotFoundError, json.JSONDecodeError): - return None - if projection.get("status") != "completed": + if result.exit_code != 0: return None - findings_path = Path(scout_task["subagent_dir"]) / "findings.md" - try: - async with aiofiles.open(findings_path, "r") as f: - return await f.read() - except FileNotFoundError: - return None + return result.final_response or None # Emit queued events for all scouts before concurrency-limited execution from ..events import build_scout_queued diff --git a/tests/test_subagent.py b/tests/test_subagent.py index d690d65..4f563a3 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -44,7 +44,7 @@ class FakeAppState: class FakeRunner: name = "fake" - def build_command(self, boot_prompt, mcp_url, model): + def build_command(self, boot_prompt, mcp_url, model, read_only=False): # Return a command that exits immediately with code 1 return ["python3", "-c", "import sys; sys.exit(1)"] @@ -56,7 +56,7 @@ class FakeRunnerSuccess: """Runner that exits 0. Handshake is set via MCP path, not stream.""" name = "fake" - def build_command(self, boot_prompt, mcp_url, model): + def build_command(self, boot_prompt, mcp_url, model, read_only=False): return ["python3", "-c", "pass"] def parse_stream_event(self, line): @@ -253,9 +253,9 @@ async def test_bootstrap_failure_detection(self, tmp_path): with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}): from koan.subagent import spawn_subagent - exit_code = await spawn_subagent(task, app_state, runner=FakeRunner()) + result = await spawn_subagent(task, app_state, runner=FakeRunner()) - assert exit_code == 1 + assert result.exit_code == 1 # Check that events.jsonl contains a runner_diagnostic events_path = Path(subagent_dir) / "events.jsonl" @@ -292,9 +292,9 @@ async def patched_subprocess(*args, **kwargs): patch("asyncio.create_subprocess_exec", side_effect=patched_subprocess): from koan.subagent import spawn_subagent - exit_code = await spawn_subagent(task, app_state, runner=FakeRunnerSuccess()) + result = await spawn_subagent(task, app_state, runner=FakeRunnerSuccess()) - assert exit_code == 0 + assert result.exit_code == 0 # Verify state.json shows completed state = json.loads((Path(subagent_dir) / "state.json").read_text()) @@ -397,12 +397,8 @@ async def fake_spawn(task, app, runner=None): nonlocal call_idx idx = call_idx call_idx += 1 - sd = Path(task["subagent_dir"]) - # Write state.json with completed status - (sd / "state.json").write_text(json.dumps({"status": "completed"})) - # Write findings - (sd / "findings.md").write_text(findings[idx]) - return 0 + from koan.subagent import SubagentResult + return SubagentResult(exit_code=0, final_response=findings[idx]) import koan.web.mcp_endpoint as mcp_mod old_app_state = mcp_mod._app_state @@ -460,10 +456,8 @@ async def fake_spawn(task, app, runner=None): await asyncio.sleep(0.01) async with lock: current_concurrent -= 1 - sd = Path(task["subagent_dir"]) - (sd / "state.json").write_text(json.dumps({"status": "completed"})) - (sd / "findings.md").write_text("ok") - return 0 + from koan.subagent import SubagentResult + return SubagentResult(exit_code=0, final_response="ok") import koan.web.mcp_endpoint as mcp_mod old_app_state = mcp_mod._app_state @@ -503,10 +497,9 @@ async def test_missing_state_json_treated_as_failure(self, tmp_path): ) async def fake_spawn(task, app, runner=None): - sd = Path(task["subagent_dir"]) - # Write findings but NO state.json - (sd / "findings.md").write_text("stale findings") - return 0 + # Exit 0 but return no final_response — treated as no findings + from koan.subagent import SubagentResult + return SubagentResult(exit_code=0) import koan.web.mcp_endpoint as mcp_mod old_app_state = mcp_mod._app_state @@ -641,9 +634,9 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): with patch("koan.subagent.PHASE_MODULE_MAP", {"intake": _fake_phase_module()}): from koan.subagent import spawn_subagent - exit_code = await spawn_subagent(task, app_state) + result = await spawn_subagent(task, app_state) - assert exit_code == 1 + assert result.exit_code == 1 # Verify agent_spawn_failed event in projection notifications (new model: Notification objects) notifs = app_state.projection_store.projection.notifications From de1a58f0ab496ccf899ce20cb2f3aaa55f646b6a Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 14:07:45 +0700 Subject: [PATCH 273/412] refactor: remove read_only runner parameter Conflicts with the project's permissive execution mode and adds unnecessary complexity. Scouts already have their tool permissions scoped via the MCP permission fence. --- koan/lib/permissions.py | 2 -- koan/runners/base.py | 1 - koan/runners/claude.py | 3 --- koan/runners/codex.py | 3 --- koan/runners/gemini.py | 23 ----------------------- koan/runners/resolver.py | 3 --- koan/subagent.py | 4 +--- tests/test_subagent.py | 4 ++-- 8 files changed, 3 insertions(+), 40 deletions(-) diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index 39eddf2..f9756b0 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -108,8 +108,6 @@ "cross-artifact-validator", }) -READ_ONLY_ROLES: frozenset[str] = frozenset({"scout"}) - STEP_1_BLOCKED_TOOLS: frozenset[str] = frozenset({ "koan_request_scouts", "koan_ask_question", diff --git a/koan/runners/base.py b/koan/runners/base.py index dec2c6e..4aa2322 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -45,7 +45,6 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, - read_only: bool = False, ) -> list[str]: ... def list_models(self, binary: str) -> list[ModelInfo]: ... diff --git a/koan/runners/claude.py b/koan/runners/claude.py index f9d5bf8..2fa1140 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -102,7 +102,6 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, - read_only: bool = False, ) -> list[str]: if thinking not in self.supported_thinking_modes: raise RunnerError(RunnerDiagnostic( @@ -139,8 +138,6 @@ def build_command( if thinking != "disabled": cmd.extend(["--effort", _EFFORT_MAP[thinking]]) cmd.extend(["--model", model]) - if read_only: - cmd.extend(["--disallowedTools", "Write,Edit"]) cmd.extend(installation.extra_args) return cmd diff --git a/koan/runners/codex.py b/koan/runners/codex.py index 92900e3..632a61a 100644 --- a/koan/runners/codex.py +++ b/koan/runners/codex.py @@ -68,7 +68,6 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, - read_only: bool = False, ) -> list[str]: if thinking != "disabled": raise RunnerError(RunnerDiagnostic( @@ -83,8 +82,6 @@ def build_command( "-c", f"mcp_servers.koan.url={mcp_url}", boot_prompt, ] - if read_only: - cmd.extend(["--sandbox", "read-only"]) cmd.extend(["--model", model]) cmd.extend(installation.extra_args) return cmd diff --git a/koan/runners/gemini.py b/koan/runners/gemini.py index 7a210e1..f58e938 100644 --- a/koan/runners/gemini.py +++ b/koan/runners/gemini.py @@ -71,7 +71,6 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, - read_only: bool = False, ) -> list[str]: if thinking not in self.supported_thinking_modes: raise RunnerError(RunnerDiagnostic( @@ -88,29 +87,7 @@ def build_command( self._merge_mcp(existing, mcp_url, settings_path) self._write_settings(existing, settings_path, gemini_dir) - if read_only: - policy_path = config_dir / "read-only-policy.toml" - policy_content = ( - '# Deny write tools for read-only agents.\n' - '[[rule]]\n' - 'toolName = ["write_file", "replace"]\n' - 'decision = "deny"\n' - ) - try: - tmp = policy_path.with_suffix(".toml.tmp") - tmp.write_text(policy_content, "utf-8") - tmp.rename(policy_path) - except OSError as e: - raise RunnerError(RunnerDiagnostic( - code="policy_write_failed", - runner="gemini", - stage="build_command", - message=f"Failed to write read-only policy: {e}", - )) from e - cmd = [installation.binary, "--output-format", "stream-json", "-p", boot_prompt] - if read_only: - cmd.extend(["--policy", str(policy_path)]) if thinking != "disabled": cmd.extend(["--thinking-mode", thinking]) cmd.extend(["--model", model]) diff --git a/koan/runners/resolver.py b/koan/runners/resolver.py index 55a08cb..e3e7b3b 100644 --- a/koan/runners/resolver.py +++ b/koan/runners/resolver.py @@ -52,14 +52,12 @@ def build_command( installation_or_model: AgentInstallation | str | None = None, model: str | None = None, thinking: ThinkingMode = "disabled", - read_only: bool = False, ) -> list[str]: # New 5-arg style: (boot_prompt, mcp_url, installation, model, thinking) if isinstance(installation_or_model, AgentInstallation): return self._inner.build_command( boot_prompt, mcp_url, installation_or_model, model or self._inner.name, thinking, - read_only=read_only, ) # Legacy 3-arg style: (boot_prompt, mcp_url, model_str) legacy_model = installation_or_model if isinstance(installation_or_model, str) else None @@ -72,7 +70,6 @@ def build_command( return self._inner.build_command( boot_prompt, mcp_url, installation, legacy_model or self._inner.name, "disabled", - read_only=read_only, ) diff --git a/koan/subagent.py b/koan/subagent.py index d81bf60..56c62d4 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -34,7 +34,6 @@ from .logger import get_logger from .phases import PHASE_MODULE_MAP, PhaseContext from .runners import RunnerDiagnostic, RunnerError -from .lib.permissions import READ_ONLY_ROLES from .runners.registry import RunnerRegistry if TYPE_CHECKING: @@ -182,10 +181,9 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None if installation is not None and thinking_mode is not None: cmd = runner.build_command( boot_prompt(role), mcp_url, installation, model, thinking_mode, - read_only=(role in READ_ONLY_ROLES), ) else: - cmd = runner.build_command(boot_prompt(role), mcp_url, model, read_only=(role in READ_ONLY_ROLES)) + cmd = runner.build_command(boot_prompt(role), mcp_url, model) except RunnerError as e: await event_log.emit_runner_diagnostic(e.diagnostic) store.push_event( diff --git a/tests/test_subagent.py b/tests/test_subagent.py index 4f563a3..d6a3050 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -44,7 +44,7 @@ class FakeAppState: class FakeRunner: name = "fake" - def build_command(self, boot_prompt, mcp_url, model, read_only=False): + def build_command(self, boot_prompt, mcp_url, model): # Return a command that exits immediately with code 1 return ["python3", "-c", "import sys; sys.exit(1)"] @@ -56,7 +56,7 @@ class FakeRunnerSuccess: """Runner that exits 0. Handshake is set via MCP path, not stream.""" name = "fake" - def build_command(self, boot_prompt, mcp_url, model, read_only=False): + def build_command(self, boot_prompt, mcp_url, model): return ["python3", "-c", "pass"] def parse_stream_event(self, line): From 485fe58c0d1b3096609a0ffcfae9d7564452d19e Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 17:13:52 +0700 Subject: [PATCH 274/412] chore: add CLAUDE.md config pointing to AGENTS.md --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From a9b70ed633829ee09c7dff7a2efe8849ef873c2b Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 17:14:18 +0700 Subject: [PATCH 275/412] =?UTF-8?q?docs:=20update=20intake=20phase=20?= =?UTF-8?q?=E2=80=94=20rename=20steps,=20simplify=20confidence=20gate?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename Deliberate→Ask, Synthesize→Write in step names - Confidence threshold: certain→high - Remove maximum iteration bound (was 4) - Remove step 3 confidence gating (koan_set_confidence) - Remove emit_iteration_start from on_loop_back - Update intake sub-phase derivation table - Move intake confidence/iteration tracking to PhaseContext (not persisted) --- docs/intake-loop.md | 81 +++++++++++++++++---------------------------- docs/state.md | 8 ++--- docs/subagents.md | 16 ++++----- 3 files changed, 40 insertions(+), 65 deletions(-) diff --git a/docs/intake-loop.md b/docs/intake-loop.md index 7a375c2..1544dba 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -21,17 +21,17 @@ This weight justifies a more elaborate workflow than other phases. Rather than a fixed sequence of steps, intake runs a **confidence-gated loop**: the LLM scouts the codebase, enumerates what it knows, asks the user questions, and then explicitly self-verifies its understanding. The loop repeats until the -LLM declares it is "certain" the decomposer has everything it needs. +LLM declares "high" confidence that the decomposer has everything it needs. ### Step structure -| Step | Name | Runs | Purpose | -| ---- | ---------- | ---- | ---------------------------------------------------------------------------------- | -| 1 | Extract | 1x | Read conversation input. No side effects. | -| 2 | Scout | 1-4x | Dispatch codebase investigators. | -| 3 | Deliberate | 1-4x | Enumerate knowns/unknowns, ask user questions. | -| 4 | Reflect | 1-4x | Self-verify completeness, declare confidence. | -| 5 | Synthesize | 1x | Write `landscape.md`. Review gate: calls `koan_review_artifact` before completing. | +| Step | Name | Runs | Purpose | +| ---- | ------- | ---- | ------------------------------------------------------------------------------- | +| 1 | Extract | 1x | Read conversation input. No side effects. | +| 2 | Scout | 1-4x | Dispatch codebase investigators. | +| 3 | Ask | 1-4x | Enumerate knowns/unknowns, ask user questions. | +| 4 | Reflect | 1-4x | Self-verify completeness, declare confidence. | +| 5 | Write | 1x | Write `landscape.md`. Review gate: calls `koan_review_artifact` before completing. | Steps 2-4 form the loop. Each call to `koan_complete_step` during these steps either returns the next step in sequence or loops back from step 4 to step 2. @@ -53,11 +53,11 @@ to implement non-linear flows. def get_next_step(step, ctx): """Pure query -- returns where to go, does not mutate state.""" if step == 4: # Reflect step - if confidence == "certain" or is_exhausted: - return 5 # -> Synthesize + if confidence == "high": + return 5 # -> Write return 2 # -> Scout (loop back) if step == 5: - return None # Synthesize -> done + return None # Write -> done return step + 1 # linear for steps 1-3 ``` @@ -66,7 +66,6 @@ def on_loop_back(from_step, to_step, ctx): """Side effects of the loop-back decision live here, not in get_next_step().""" ctx.iteration += 1 ctx.intake_confidence = None # reset for next round - emit_iteration_start(ctx.event_log, ctx.iteration, MAX_ITERATIONS) ``` `get_next_step()` is a **pure query** -- it only decides where to go. All side @@ -81,8 +80,8 @@ non-linear logic to the one module that needs it without touching other phases. For the intake phase, `total_steps = 5` reflects the number of distinct step definitions, not the number of `koan_complete_step` calls. The loop may -execute steps 2-4 up to four times, producing up to 1 + (3 x 4) + 1 = 14 -calls in the worst case. +execute steps 2-4 multiple times, with the total calls depending on when high +confidence is reached. --- @@ -126,12 +125,6 @@ backward transition and calls `on_loop_back()`. The intake module's `on_loop_back()` resets `ctx.intake_confidence = None`. This ensures that in the next Reflect step, the LLM must call `koan_set_confidence` again. -### Maximum iterations - -The loop is bounded at 4 iterations. When exhausted, `get_next_step()` returns -step 5 (Synthesize) instead of step 2. This prevents infinite loops if the LLM -consistently declares non-certain confidence. - --- ## Step-Aware Permission Gating @@ -149,23 +142,14 @@ frontloads all work into step 1. `role == "intake" and intake_step == 1`: ``` -koan_request_scouts, koan_ask_question, koan_set_confidence, write, edit +koan_request_scouts, koan_ask_question, write, edit ``` -### Step 3 (Deliberate): no confidence assessment - -Step 3 is for enumerating knowns/unknowns and asking questions. Confidence -assessment belongs exclusively in step 4 (Reflect). - -`check_permission()` blocks `koan_set_confidence` when -`role == "intake" and intake_step == 3`. - ### Prompt + enforcement is not redundant -The prompt tells the LLM not to use side-effecting tools in step 1 and not -to assess confidence in step 3. The permission gates are fallbacks that catch -prompt non-compliance. Together: the prompt prevents the behavior; the gate -catches it when the prompt fails. +The prompt tells the LLM not to use side-effecting tools in step 1. The +permission gate is a fallback that catches prompt non-compliance. Together: +the prompt prevents the behavior; the gate catches it when the prompt fails. --- @@ -196,28 +180,28 @@ The intake loop prompts apply several techniques from the prompting literature. This section records the reasoning so future changes don't inadvertently remove mechanisms that address specific failure modes. -### Prompt Chaining over Stepwise (Scout / Deliberate / Reflect as separate steps) +### Prompt Chaining over Stepwise (Scout / Ask / Reflect as separate steps) A monolithic "investigate" step is rejected in favor of three separate `koan_complete_step` calls. The risk with a monolithic step is **simulated refinement**: the LLM artificially degrades its initial output to manufacture visible improvement. Separate steps enforce genuinely isolated reasoning. -### Thread-of-Thought in Deliberate (explicit enumeration before questions) +### Thread-of-Thought in Ask (explicit enumeration before questions) -The Deliberate step instructs the LLM to walk through each area and explicitly +The Ask step instructs the LLM to walk through each area and explicitly state what is known, unknown, and its source -- before formulating questions. This surfaces gaps that are not top-of-mind. -### Anticipatory Reflection in Deliberate (downstream impact assessment) +### Anticipatory Reflection in Ask (downstream impact assessment) -Between enumeration and question formulation, the Deliberate step includes a +Between enumeration and question formulation, the Ask step includes a downstream impact assessment. Each unknown is classified as ASK (user input needed), SCOUT (follow-up can resolve), or SAFE (implementation detail). ### Default-ask question framing (preventing question avoidance) -The Deliberate step frames question-asking as the default, with skipping +The Ask step frames question-asking as the default, with skipping requiring triple justification. This inverts the typical LLM bias toward advancing the workflow. @@ -227,10 +211,11 @@ The Reflect step instructs the LLM to generate 3-5 verification questions framed from the decomposer's perspective, then answer each using only concrete evidence. This is the Chain-of-Verification (CoVe) pattern. -### Contrastive confidence definitions (preventing premature "certain") +### Contrastive confidence definitions (preventing premature "high") -The Reflect step provides both positive ("certain means ALL of these are true") -and negative ("you are NOT certain if ANY of these are true") definitions. +The Reflect step provides both positive ("high confidence means ALL of these +are true") and negative ("you do NOT have high confidence if ANY of these are +true") definitions. The negative examples make failure modes concrete and explicit. ### Stakes framing (EmotionPrompt for accountability) @@ -240,14 +225,14 @@ making up." This connects intake shortcuts directly to downstream failures. ### Iteration-aware guidance (first iteration vs. refinement) -Steps 2 (Scout) and 3 (Deliberate) produce different instruction text for +Steps 2 (Scout) and 3 (Ask) produce different instruction text for the first iteration vs. subsequent iterations. This prevents the LLM from repeating its initial exploration. ### Iteration expectations (soft minimum via GIoT) The Reflect step includes soft guidance that round 1 should rarely produce -"certain" confidence. This provides directional pressure without forcing +"high" confidence. This provides directional pressure without forcing unnecessary iterations on trivial tasks. --- @@ -275,13 +260,7 @@ The reset must happen in `on_loop_back()`, not in `get_next_step()`. `koan_set_confidence` is gated to the intake role via permissions. -### Don't allow koan_set_confidence during Deliberate (step 3) - -Without this gate, the LLM sets confidence during Deliberate, anchoring the -subsequent Reflect step toward "certain". Confidence assessment must happen -only during Reflect (step 4). - -### Don't make the "NOT certain" checklist vacuously satisfiable +### Don't make the "NOT high" checklist vacuously satisfiable Every condition must be non-vacuously testable. Prefer conditions that require positive evidence: "you have not asked any questions" is mechanically true or diff --git a/docs/state.md b/docs/state.md index 97db0c5..3656a44 100644 --- a/docs/state.md +++ b/docs/state.md @@ -257,9 +257,5 @@ Key projection fields common to all roles: | `tokens_sent` | number | Cumulative tokens in | | `tokens_received` | number | Cumulative tokens out | -Intake-specific fields (zero/null for all other roles): - -| Field | Type | Meaning | -| ------------------- | ------------------------------------------------------- | -------------------------------- | -| `intake_confidence` | `"exploring"\|"low"\|"medium"\|"high"\|"certain"\|null` | Last confidence level | -| `intake_iteration` | number | Current loop iteration (1-based) | +Intake confidence and iteration counters are tracked in the in-memory +`PhaseContext` during execution and are not persisted to the audit projection. diff --git a/docs/subagents.md b/docs/subagents.md index 956bfd6..54be0d1 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -343,11 +343,11 @@ Agent registration and deregistration are tracked in the in-process Intake sub-phase derivation happens server-side based on step number: -| Step | Pending ask? | Sub-phase | -| ---- | ------------ | -------------- | -| 1 | -- | `"extract"` | -| 2 | -- | `"scout"` | -| 3 | yes | `"questions"` | -| 3 | no | `"deliberate"` | -| 4 | -- | `"reflect"` | -| 5 | -- | `"synthesize"` | +| Step | Pending ask? | Sub-phase | +| ---- | ------------ | ----------- | +| 1 | -- | `"extract"` | +| 2 | -- | `"scout"` | +| 3 | yes | `"ask"` | +| 3 | no | `"ask"` | +| 4 | -- | `"reflect"` | +| 5 | -- | `"write"` | From 285f116424fcf2b855ca923d3a6b875545e6b5f5 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 17:14:29 +0700 Subject: [PATCH 276/412] docs: update subagent roles, permissions, and configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Expand role permission matrix with all roles (brief-writer, workflow-orchestrator, ticket-breakdown, cross-artifact-validator) - Scout: output_file→question, add no-file-writing constraint - Scout concurrency: 4→8 - Configuration: modelTiers→profile-based system with installations - Phase module list: add format_step.py, review_protocol.py --- docs/subagents.md | 68 +++++++++++++++++++++++++++++++---------------- 1 file changed, 45 insertions(+), 23 deletions(-) diff --git a/docs/subagents.md b/docs/subagents.md index 54be0d1..88e8bea 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -32,7 +32,7 @@ Role-specific fields: | Role | Additional fields | | -------------- | -------------------------------------- | | `intake` | -- | -| `scout` | `output_file`, `investigator_role` | +| `scout` | `question`, `investigator_role` | | `decomposer` | -- | | `orchestrator` | `step_sequence`, `story_id` (optional) | | `planner` | `story_id` | @@ -118,7 +118,7 @@ The MCP endpoint validates required `task.json` fields at agent registration: | Role | Required fields | Failure if missing | | -------- | --------------- | ----------------------------------------------------------------------- | -| scout | `output_file` | Step 1 guidance has no assignment -> LLM outputs confused text -> exits | +| scout | `question` | Step 1 guidance has no assignment -> LLM outputs confused text -> exits | | planner | `story_id` | Malformed paths like `stories//plan/plan.md` | | executor | `story_id` | Same path issue | @@ -148,6 +148,8 @@ koan/phases/ ticket_breakdown.py cross_artifact_validation.py workflow_orchestrator.py + format_step.py + review_protocol.py ``` Each phase module exposes: @@ -225,14 +227,18 @@ from write-bash is intractable at the permission layer. ### Role permission matrix -| Role | koan tools | write/edit | notes | -| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------ | -| **intake** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `koan_set_confidence` | path-scoped to epicDir | `koan_set_confidence` blocked in step 1 (Extract) | -| **scout** | `koan_complete_step` | path-scoped to epicDir | No `koan_ask_question` (no user interaction). No `koan_request_scouts` (no nested scouts). | -| **decomposer** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | -- | -| **orchestrator** | `koan_complete_step`, `koan_ask_question`, `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | path-scoped to epicDir | No `koan_request_scouts` -- orchestrator uses bash for verification | -| **planner** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | -- | -| **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | +| Role | koan tools | write/edit | notes | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------- | +| **intake** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `koan_set_confidence`, `koan_review_artifact` | path-scoped to epicDir | `koan_request_scouts, koan_ask_question, write, edit` blocked in step 1 (Extract) | +| **scout** | `koan_complete_step` | none | No `koan_ask_question` (no user interaction). No `koan_request_scouts` (no nested scouts). No file writing. | +| **brief-writer** | `koan_complete_step`, `koan_review_artifact`, `edit`, `write` | path-scoped to epicDir | `koan_request_scouts, koan_ask_question, write, edit` blocked in step 1 (Read) | +| **workflow-orchestrator** | `koan_complete_step`, `koan_propose_workflow`, `koan_set_next_phase` | -- | No file writing capability | +| **decomposer** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | -- | +| **orchestrator** | `koan_complete_step`, `koan_ask_question`, `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | path-scoped to epicDir | No `koan_request_scouts` -- orchestrator uses bash for verification | +| **planner** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | -- | +| **ticket-breakdown** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `edit`, `write` | path-scoped to epicDir | -- | +| **cross-artifact-validator**| `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `edit`, `write` | path-scoped to epicDir | -- | +| **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | ### Path scoping @@ -255,28 +261,43 @@ Koan has 6+ roles, but they cluster into 3 capability bands: | **standard** | executor | Code implementation: reliable tool use without deepest reasoning | | **cheap** | scout | Narrow codebase investigation: reading files, writing findings | -The mapping is defined in `koan/config.py`. Adding a new role requires -updating that map. +The role-to-tier mapping is defined in `koan/config.py`. Adding a new role +requires updating that map. ### Configuration -Model tiers are configured via the web UI at pipeline start. Config is -persisted to `~/.koan/config.json`: +Model tiers use a profile-based system. Each profile defines three tiers +(`strong`, `standard`, `cheap`), and an active profile is selected at runtime. +Agent installations declare available runners and binaries. Config is persisted +to `~/.koan/config.json`: ```json { - "modelTiers": { - "strong": "claude-opus-4-5", - "standard": "claude-sonnet-4-5", - "cheap": "claude-haiku-4-5" - }, - "scoutConcurrency": 4 + "agentInstallations": [ + { "alias": "claude-sonnet", "runnerType": "claude", "binary": "claude", "extraArgs": [] } + ], + "profiles": [ + { + "name": "balanced", + "tiers": { + "strong": { "runnerType": "claude", "model": "claude-sonnet-4-5", "thinking": "disabled" }, + "standard": { "runnerType": "claude", "model": "claude-sonnet-4-5", "thinking": "disabled" }, + "cheap": { "runnerType": "claude", "model": "claude-haiku-4-5", "thinking": "disabled" } + } + } + ], + "activeProfile": "balanced", + "scoutConcurrency": 8 } ``` +Roles map to tiers (`strong`/`standard`/`cheap`), and tier-to-model bindings +are configured per-profile. Switching profiles changes all model assignments at +once without touching role definitions. + ### Scout concurrency -`scoutConcurrency` (default: 4) controls how many scout subagents run in +`scoutConcurrency` (default: 8) controls how many scout subagents run in parallel. Increase for faster scouting on machines with ample resources; decrease to reduce peak memory pressure. @@ -288,13 +309,14 @@ Scouts are deliberately constrained compared to other roles: - **No `koan_ask_question`** -- scouts do not ask questions - **No `koan_request_scouts`** -- scouts do not spawn nested scouts +- **No file writing** -- scouts have no `write`/`edit` access - **Three steps** -- investigate -> verify -> report - **Cheap model** -- scouts use the cheapest available model -- **Parallel execution** -- up to 4 scouts run concurrently +- **Parallel execution** -- up to 8 scouts run concurrently - **Non-fatal failures** -- a failed scout does not abort the parent; its task ID is reported in the `failures` array -Scout task parameters (`output_file`, `investigator_role`) live in the scout's +Scout task parameters (`question`, `investigator_role`) live in the scout's `task.json`. The boot prompt stays minimal; step 1 guidance injects the parameters. From 47ee53d3fb72b3795f2242081273d1d0b3135db6 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 17:14:39 +0700 Subject: [PATCH 277/412] docs: rewrite IPC documentation for interaction queue model - Clarify PendingInteraction FIFO queue (1 active + 8 queued) - Scout flow: inline via asyncio.gather, no PendingInteraction - Artifact review: add queue activation and last_review_accepted - Add Workflow Decision Flow section - Update sequence diagrams for queue-based interactions - Distinguish user-facing tools from inline tools --- docs/ipc.md | 159 ++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 111 insertions(+), 48 deletions(-) diff --git a/docs/ipc.md b/docs/ipc.md index 122fc38..190b30a 100644 --- a/docs/ipc.md +++ b/docs/ipc.md @@ -26,32 +26,49 @@ while the driver awaits an external response: | `koan_ask_question` | User input needed | User via web UI | | `koan_request_scouts` | Scout subagents running | Driver (after scouts complete) | | `koan_review_artifact` | User review needed | User via web UI | +| `koan_propose_workflow`| User workflow decision | User via web UI | -For all three, the MCP tool handler creates an `asyncio.Future`, stores it in -`AgentState.pending_tool`, and awaits it. The HTTP connection stays open until -the Future resolves. There is no polling, no intermediate files. +User-facing tools (`koan_ask_question`, `koan_review_artifact`, +`koan_propose_workflow`) go through the `PendingInteraction` queue on +`AppState`. The MCP handler creates an `asyncio.Future`, stores it in +`AgentState.pending_tool`, enqueues a `PendingInteraction` on `AppState`, and +awaits the Future. The HTTP connection stays open until the Future resolves. + +`koan_request_scouts` is handled entirely inline: the handler spawns scouts via +`asyncio.gather` of `spawn_subagent` calls (bounded by a semaphore), collects +their results, and returns directly. No `PendingInteraction` is created; the +HTTP connection is held open only by the `await asyncio.gather(...)` call. + +There is no polling and no intermediate files for any of these flows. --- ## Blocking Interaction Model -### `asyncio.Future` resolution +### `asyncio.Future` resolution (user-facing interactions) -When a blocking tool is called: +When a user-facing blocking tool is called: 1. MCP endpoint receives tool call with `agent_id` -2. Handler creates `asyncio.Future` and stores it as a `PendingInteraction` in `AgentState` -3. For user-facing interactions: pushes SSE event to browsers (question form, review form) +2. Handler creates `asyncio.Future`, stores it in `AgentState.pending_tool`, + and enqueues a `PendingInteraction` on `AppState.interaction_queue` +3. If no interaction is currently active, the interaction is promoted to + `AppState.active_interaction` and an SSE event is pushed to browsers + (question form, review form, or workflow-decision form) 4. Handler `await`s the Future -- HTTP connection stays open -5. External actor resolves the Future: - - User interactions: web UI `POST /api/answer` or `POST /api/artifact-review` resolves it - - Scout requests: driver spawns scouts, awaits completion, resolves Future with findings -6. Handler returns the resolved value as the MCP tool result +5. User fills the form in the web UI and submits: + - `POST /api/answer` resolves the Future for `koan_ask_question` + - `POST /api/artifact-review` resolves it for `koan_review_artifact` + - `POST /api/workflow-decision` resolves it for `koan_propose_workflow` +6. Handler returns the resolved value as the MCP tool result; the next queued + interaction (if any) is promoted to active ``` subagent ---POST /mcp koan_ask_question---> driver | +-- create Future + +-- store Future in AgentState.pending_tool + +-- enqueue PendingInteraction on AppState +-- push SSE "ask" event to browser +-- await Future | @@ -65,17 +82,25 @@ subagent <---tool result (answer)----------- + ### `PendingInteraction` -The `PendingInteraction` object stored in `AgentState.pending_tool`: +The `PendingInteraction` object stored in `AppState.active_interaction` (or +queued in `AppState.interaction_queue`): -- `type` -- one of `"ask"`, `"scout-request"`, `"artifact-review"` -- `id` -- UUID for correlation +- `type` -- one of `"ask"`, `"artifact-review"`, `"workflow-decision"` +- `agent_id` -- the agent that issued the blocking call +- `token` -- UUID for SSE correlation - `payload` -- type-specific request data - `future` -- the `asyncio.Future` awaiting resolution +`AgentState.pending_tool` holds the raw `asyncio.Future` for the currently +blocked MCP call on that agent (not the `PendingInteraction` object itself). + ### Constraints -- **One pending interaction at a time** per agent. A second blocking tool call - while one is pending returns an error. +- **Global FIFO queue** -- `AppState.interaction_queue` is a single queue + shared across all agents. At most one interaction is active at a time; up to + 8 additional interactions may be queued (`interaction_queue_max = 8`). A + call that would exceed the cap (9 total: 1 active + 8 queued) raises + `interaction_queue_full`. - **No polling** -- resolution is immediate when the external actor responds. - **The subagent's LLM turn is blocked** while the Future is pending. The MCP HTTP connection is held open; the LLM cannot call other tools until the @@ -88,9 +113,9 @@ The `PendingInteraction` object stored in `AgentState.pending_tool`: ``` subagent calls koan_ask_question({ questions: [...] }) -> MCP endpoint checks permissions - -> creates PendingInteraction { type: "ask", future: asyncio.Future() } - -> stores in AgentState.pending_tool - -> pushes SSE `questions_asked` event to browsers + -> creates asyncio.Future, stores in AgentState.pending_tool + -> enqueues PendingInteraction { type: "ask" } on AppState + -> if no active interaction: promotes to active, pushes SSE `questions_asked` event to browsers -> awaits Future user sees question form in web UI @@ -99,6 +124,7 @@ user sees question form in web UI MCP handler receives resolved value -> clears AgentState.pending_tool + -> activates next queued interaction (if any) -> formats answer as structured text -> returns as MCP tool result to subagent ``` @@ -110,27 +136,25 @@ The "Other" option is appended server-side -- the LLM never includes it. ## Scout Flow ``` -subagent calls koan_request_scouts({ scouts: [...] }) +subagent calls koan_request_scouts({ questions: [...] }) -> MCP endpoint checks permissions - -> creates PendingInteraction { type: "scout-request", future: asyncio.Future() } - -> stores in AgentState.pending_tool + -> no PendingInteraction created - driver handles scout request in-process: + handler runs inline via asyncio.gather (semaphore-bounded concurrency): -> for each scout task: -> assign scout agent_id - -> register scout in agent registry - -> write MCP config pointing at same HTTP server - -> spawn scout CLI process + -> ensure subagent directory + -> spawn scout CLI process via spawn_subagent() -> scout connects to /mcp?agent_id={scout_id} -> scout calls koan_complete_step, does work, completes - -> deregister scout - -> collect findings from completed scouts - -> resolve Future with { findings: [paths], failures: [ids] } - -MCP handler receives resolved value - -> clears AgentState.pending_tool - -> reads each findings.md file verbatim - -> returns concatenated content as MCP tool result + -> SubagentResult collected (exit_code, final_response) + -> all scouts run concurrently up to scout_concurrency limit + -> asyncio.gather returns list of results + +MCP handler processes results + -> collects non-None final_response values as findings + -> returns concatenated findings as MCP tool result to subagent + (HTTP connection was held open by await asyncio.gather for the duration) ``` ### Scout pool behavior @@ -139,22 +163,27 @@ All scouts are submitted concurrently with a configurable concurrency limit (default: 4). The pool: - **Runs all items to completion** regardless of individual failures -- **Reports progress** via SSE events +- **Reports progress** via SSE events (`scout_queued` emitted before gather) - **Does not implement timeouts** -- timeout logic belongs in the caller ### Scout success determination -Scout success is derived from the audit projection, not file existence: +Scout success is derived from the subagent's exit code and final response, not +file existence: ```python -projection = read_projection(scout_dir) -succeeded = projection.get("status") == "completed" +result = await spawn_subagent(scout_task, _app_state) +succeeded = result.exit_code == 0 +findings = result.final_response or None ``` ### Failed scouts are non-fatal -The tool result tells the LLM: -`"Failed scouts (non-fatal, proceed without them): task-id-1, task-id-2"` +Scouts that exit non-zero return `None` from `run_scout()` and are omitted from +findings. The tool result notes any missing scouts: + +`"No findings returned."` (if all fail) or silently omits failed scouts from +the concatenated output. --- @@ -164,8 +193,10 @@ The tool result tells the LLM: subagent calls koan_review_artifact({ path: ".../brief.md" }) -> MCP endpoint checks permissions -> reads file content from path - -> creates PendingInteraction { type: "artifact-review", future: asyncio.Future() } - -> pushes SSE `artifact_review_requested` event to browsers (with rendered content) + -> creates asyncio.Future, stores in AgentState.pending_tool + -> enqueues PendingInteraction { type: "artifact-review" } on AppState + -> if no active interaction: promotes to active, pushes SSE `artifact_review_requested` + event to browsers (with rendered content) -> awaits Future user sees rendered markdown in web UI @@ -174,7 +205,9 @@ user sees rendered markdown in web UI MCP handler receives resolved value -> clears AgentState.pending_tool - -> returns "User feedback:\n{feedback}" as MCP tool result + -> activates next queued interaction (if any) + -> sets AgentState.phase_ctx.last_review_accepted + -> returns "ACCEPTED" or "REVISION REQUESTED: {feedback}" as MCP tool result if feedback == "Accept": LLM calls koan_complete_step -> phase advances @@ -187,37 +220,67 @@ See [artifact-review.md](./artifact-review.md) for the full protocol. --- +## Workflow Decision Flow + +``` +subagent calls koan_propose_workflow({ status: "...", phases: [...] }) + -> MCP endpoint checks permissions + -> normalises phases list to list[dict] + -> creates asyncio.Future, stores in AgentState.pending_tool + -> enqueues PendingInteraction { type: "workflow-decision" } on AppState + -> if no active interaction: promotes to active, pushes SSE + `workflow_decision_requested` event to browsers (with phase proposals) + -> awaits Future + +user sees workflow proposal in web UI + -> selects a phase (or types custom input), clicks Confirm + -> POST /api/workflow-decision -> resolves Future with { phase, context } + +MCP handler receives resolved value + -> clears AgentState.pending_tool + -> activates next queued interaction (if any) + -> sets AgentState.phase_ctx.proposal_made = True + -> returns "Selected: {phase}\n{context}" as MCP tool result to subagent + +subagent then calls koan_set_next_phase({ phase: "..." }) to commit the choice +``` + +--- + ## Sequence Diagrams -### Scout flow (blocking interaction) +### Scout flow (inline blocking, no PendingInteraction) ``` Driver Scout CLI Web UI | | | |<--koan_request_scouts---------| | - | create Future | | + | emit scout_queued events | | + | asyncio.gather (semaphore) | | | spawn scout processes------->| | | |--koan_complete_step->| | |<-step 1 guidance----| | | (does work) | | |--koan_complete_step->| | |<-"Phase complete."--| - | scout exits | | - | resolve Future | | + | scout exits (exit_code 0) | | + | gather collects results | | |--tool result (findings)------>| | ``` -### User interaction flow (blocking) +### User interaction flow (blocking via PendingInteraction queue) ``` Subagent Driver Web UI | | | |--koan_ask_question---------->| | | | create Future | + | | enqueue interaction | | |--SSE "ask" event------>| | | | user sees form | | | user submits | |<-POST /api/answer------| | | resolve Future | + | | activate next queued | |<-tool result (answer)--------| | ``` From 4d6444d83d15c21e8bb9701c3d557b5c983f2d51 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 17:14:51 +0700 Subject: [PATCH 278/412] docs: update frontend and artifact-review for projection model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Store slices: individual slices→single Run object with focus union - SSE bridge: snapshot+JSON Patch protocol (no frontend fold) - active_interaction→run.focus terminology throughout - Component subscriptions updated for run-based store - camelCase native from backend (no frontend transform) - Add fast-json-patch dependency note - Reconnect: always-snapshot catch-up --- docs/artifact-review.md | 8 +-- docs/frontend.md | 139 ++++++++++++++++++---------------------- 2 files changed, 67 insertions(+), 80 deletions(-) diff --git a/docs/artifact-review.md b/docs/artifact-review.md index 1562018..f048f7c 100644 --- a/docs/artifact-review.md +++ b/docs/artifact-review.md @@ -80,7 +80,7 @@ decide how to proceed. ## Web UI Component The artifact review is rendered by the `ArtifactReview.tsx` React component. -The component subscribes to `active_interaction` in the Zustand store and +The component subscribes to `run.focus` in the Zustand store and renders when an `artifact_review_requested` event sets it. **Layout:** @@ -104,7 +104,7 @@ renders when an `artifact_review_requested` event sets it. - Component renders markdown content client-side - "Accept" -> `POST /api/artifact-review` with `{ feedback: "Accept" }` - "Send Feedback" -> `POST /api/artifact-review` with `{ feedback: text }` -- Component unmounts when `artifact_reviewed` event clears `active_interaction` +- Component unmounts when `artifact_reviewed` event clears `run.focus` --- @@ -122,8 +122,8 @@ validation failure or missing pending interaction. | Event | Direction | Payload | | ---------------------------- | ----------------- | -------------------------------------------------------- | -| `artifact_review_requested` | server -> browser | `{ token, path, content, description }` (sets `active_interaction`) | -| `artifact_reviewed` | server -> browser | `{ token, ?accepted, ?response, cancelled }` (clears `active_interaction`) | +| `artifact_review_requested` | server -> browser | `{ token, path, content, description }` (sets `run.focus`) | +| `artifact_reviewed` | server -> browser | `{ token, ?accepted, ?response, cancelled }` (clears `run.focus`) | SSE events are pushed directly from the tool handler. On browser reconnect, pending reviews are replayed so the user does not lose the review form. diff --git a/docs/frontend.md b/docs/frontend.md index cf5250c..4cc6748 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -22,7 +22,7 @@ frontend/ # source tree (alongside koan/ Python package) │ │ ├── index.ts # single Zustand store (the app-db equivalent) │ │ └── selectors.ts # derived state computed from store slices │ ├── sse/ -│ │ └── connect.ts # EventSource wrapper: version-negotiated catch-up + fold +│ │ └── connect.ts # EventSource wrapper: always-snapshot catch-up + JSON Patch │ ├── api/ │ │ └── client.ts # typed fetch wrappers for POST/PUT endpoints │ ├── components/ # one file per UI component (see Component Mapping) @@ -82,91 +82,72 @@ Single Zustand store mirrors the backend projection. All live state enters through the SSE bridge — nothing else writes to the store from outside the component tree. -Key slices: +Store slices: | Slice | Type | Source | |---|---|---| | `connected` | `boolean` | EventSource open/error | -| `lastVersion` | `number` | Snapshot or event version field | -| `runStarted` | `boolean` | Derived from first `phase_started` event | -| `phase` / `donePhases` | `string` / `string[]` | `phase_started` | -| `primaryAgent` | `AgentInfo \| null` | `agent_spawned`, `agent_step_advanced`, `agent_exited` | -| `scouts` | `Record<string, AgentInfo>` | `agent_spawned`, `agent_exited` | -| `activityLog` | `ActivityEntry[]` | `tool_called`, `tool_completed`, `thinking` | -| `streamBuffer` | `string` | `stream_delta`, `stream_cleared` | -| `activeInteraction` | `Interaction \| null` | `questions_asked`, `artifact_review_requested`, `workflow_decision_requested`, and resolution events. Stores `interactionType` (the event type string) alongside payload for component discrimination. | -| `artifacts` | `Record<string, ArtifactFile>` | `artifact_created`, `artifact_modified`, `artifact_removed` | -| `completion` | `CompletionInfo \| null` | `workflow_completed` | -| `notifications` | `NotificationEntry[]` | derived by fold from `agent_spawn_failed`, `agent_exited` with error | - -`runStarted` gates top-level view (landing vs live). No router library — a -conditional render covers the binary choice. - -`lastVersion` tracks the version of the last applied event or snapshot. The -SSE connection uses `?since=${lastVersion}` on connect/reconnect so the server -knows whether to send a snapshot or replay missed events. - -### Store actions for the projection +| `lastVersion` | `number` | Snapshot/patch version | +| `settings` | `Settings` | installations, profiles, defaultProfile, defaultScoutConcurrency | +| `run` | `Run \| null` | config, phase, agents, focus, artifacts, completion | +| `notifications` | `Notification[]` | message, level, timestampMs | +| `settingsOpen` | `boolean` | Local UI state (not from server) | + +`run` being `null` vs non-null gates the top-level view (landing vs live). No +router library — a conditional render covers the binary choice. + +`lastVersion` tracks the version of the last applied snapshot or patch. The SSE +connection sends `?since=${lastVersion}` on connect/reconnect so the server +knows where the client left off. + +### Store actions ```typescript -applySnapshot(data: SnapshotPayload): void -// Atomically replaces the entire store state from a snapshot. -// Called when the server sends event: snapshot. -// Uses useStore.setState(transform(data)) — one update, no merge logic. -// Any visual flash from the re-render is acceptable. - -applyEvent(event: VersionedEvent): void -// Applies a single versioned event via the frontend fold. -// Called for every non-snapshot SSE event. -// Mirrors the backend fold cases exactly. +setConnected(v: boolean): void +// Sets the connected flag. Called by connectSSE on EventSource open/error. + +setSettingsOpen(v: boolean): void +// Toggles the settings panel. Called by UI controls only. ``` +State updates from the server (snapshots and patches) are applied directly via +`store.setState()` inside the SSE bridge — not through named actions. + --- ## SSE Bridge `connectSSE(store)` in `sse/connect.ts` opens an -`EventSource('/events?since=${store.lastVersion}')` and handles two event -paths: - -1. **`snapshot` event** → `store.applySnapshot(data)` — atomic state replace -2. **All other events** → `store.applyEvent(event)` — incremental fold - -Returns the `EventSource`; `App.tsx` owns the reconnect lifecycle (exponential -backoff, capped at 5 s). +`EventSource('/events?since=${lastVersion}')` and handles two event paths: -The bridge also handles `fatal_error` events (sent when `?since=N` references a -version the server no longer has, e.g. after server restart). On `fatal_error`, -the bridge closes the `EventSource` WITHOUT scheduling a reconnect and sets a -`fatalError` flag in the store. The UI renders a "reload required" banner. +1. **`snapshot` event** — atomically replaces the entire store state. + Parses `{ version, state }` from the event data, sets `storeState = state`, + then calls `store.setState({ lastVersion: version, ...state })`. -### The frontend fold +2. **`patch` event** — applies an RFC 6902 JSON Patch via `fast-json-patch`. + Parses `{ version, patch }`, calls `applyPatch(storeState, patch, false, false)` + with `mutate: false` to get a new document, then spreads the result into the + store with the updated `lastVersion`. -The frontend fold mirrors the backend fold in `koan/projections.py`. Both must -produce the same projection shape from the same event sequence. When a new -event type is added to the backend, a corresponding fold case must be added to -the frontend `applyEvent`. + On patch failure, the bridge logs the error, closes the `EventSource`, and + resets `lastVersion` to `0` to force a fresh snapshot on reconnect. The + `onerror` handler in `App.tsx` then schedules the reconnect. -Fold cases match the backend exactly. See -[projections.md -- Fold cases](./projections.md#fold-cases) for the full table. +Returns the `EventSource`; `App.tsx` owns the reconnect lifecycle (exponential +backoff, capped at 5 s). ### Reconnect flow ``` -Browser loads → connect ?since=0 → snapshot → applySnapshot → full state -Browser refreshes → connect ?since=0 → snapshot → applySnapshot → full state -Connection drops → reconnect ?since=N → events N+1..M → applyEvent each → up to date +Browser loads → connect ?since=0 → snapshot → state replace → full state +Browser refreshes → connect ?since=0 → snapshot → state replace → full state +Connection drops → reconnect ?since=N → snapshot (if N≠server version) → full state +Patch failure → reconnect ?since=0 → snapshot → state replace → full state ``` -**snake_case → camelCase mapping** happens in `applySnapshot` and `applyEvent` -for all agent payloads (`agent_id` → `agentId`, `started_at_ms` → `startedAt`, -etc.). The backend sends snake_case; the frontend transforms at the bridge -boundary. - -**`phase_started` fold effect:** sets `runStarted = true` and derives -`donePhases`. This ensures a mid-run page reload (which receives a snapshot -with `run_started: true` and a current `phase`) restores the live view -correctly. +The server always sends a snapshot when the client's `since` version does not +match the current server version, so clients never need to track or replay +individual events — a reconnect always converges to current state. --- @@ -177,9 +158,12 @@ payloads. Callers build complete payloads using helper functions; `push_event` does not enrich payloads. See [projections.md](./projections.md) for the full event type table and payload shapes. -All time values are UTC epoch milliseconds (`started_at_ms`). All token counts +All time values are UTC epoch milliseconds (`startedAtMs`). All token counts are raw integers. Formatting is done client-side (`useElapsed`, `formatTokens`). +The backend sends camelCase field names natively via `KoanBaseModel.to_wire()`. +No field name transformation is needed in the frontend. + ### Event builder helpers (Python) | Helper | Produces event(s) | Notes | @@ -201,26 +185,29 @@ form state and cascade dropdown logic. | React component | Primary store subscription | |---|---| -| `App.tsx` | `runStarted` | -| `LandingPage.tsx` | `runStarted` (negated) | -| `StatusSidebar.tsx` | `primaryAgent`, `phase` | -| `AgentMonitor.tsx` | `scouts` | -| `ArtifactsSidebar.tsx` | `artifacts` | -| `AskWizard.tsx` | `activeInteraction` | -| `WorkflowDecision.tsx` | `activeInteraction` | -| `ArtifactReview.tsx` | `activeInteraction` | -| `Completion.tsx` | `completion` | +| `App.tsx` | `run` | +| `LandingPage.tsx` | `run` (negated) | +| `StatusSidebar.tsx` | `run.agents`, `run.phase` | +| `AgentMonitor.tsx` | `run.agents` | +| `ArtifactsSidebar.tsx` | `run.artifacts` | +| `AskWizard.tsx` | `run.focus` | +| `WorkflowDecision.tsx` | `run.focus` | +| `ArtifactReview.tsx` | `run.focus` | +| `Completion.tsx` | `run.completion` | | `SettingsOverlay.tsx` | `settingsOpen` + local state | | `Notification.tsx` | `notifications` | +Scouts are agents where `isPrimary === false`. `AgentMonitor` filters +`run.agents` by this flag — there is no separate `scouts` slice. + --- ## Known Gaps (v1) **`story` events** — emitted during execution phase with story lifecycle status. Not implemented in v1: execution phase shows only primary agent status and -activity feed. Add a `stories` store slice and `StoryProgress` component when -designing the execution phase UI. +activity feed. Add a `stories` field inside `Run` and a `StoryProgress` +component when designing the execution phase UI. --- @@ -229,7 +216,7 @@ designing the execution phase UI. ```json { - "dependencies": { "react": "^19", "react-dom": "^19", "zustand": "^5" }, + "dependencies": { "react": "^19", "react-dom": "^19", "zustand": "^5", "fast-json-patch": "^3" }, "devDependencies": { "typescript": "^5.7", "vite": "^6", "@vitejs/plugin-react": "^4" } } ``` From c3e9050f84e0bae3ce4adc6e1b02c6a062440b75 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 17:36:11 +0700 Subject: [PATCH 279/412] feat: show tool call count instead of token counts in agent monitor Replace the '-- / --' token display with 'N tools' per subagent. Number is right-aligned in --text color, 'tools' suffix is muted. Tool count derived from conversation entries (type starts with 'tool_'). --- frontend/src/components/AgentMonitor.tsx | 12 ++++++++---- frontend/src/styles/components.css | 4 +++- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/frontend/src/components/AgentMonitor.tsx b/frontend/src/components/AgentMonitor.tsx index 39b1b0d..8ee9244 100644 --- a/frontend/src/components/AgentMonitor.tsx +++ b/frontend/src/components/AgentMonitor.tsx @@ -1,7 +1,6 @@ import { useMemo } from 'react' import { useStore, Agent } from '../store/index' import { useElapsed } from '../hooks/useElapsed' -import { formatTokens } from '../utils' function AgentRow({ agent }: { agent: Agent }) { const elapsed = useElapsed(agent.startedAtMs) @@ -13,6 +12,10 @@ function AgentRow({ agent }: { agent: Agent }) { const statusCls = `agent-status-${status}` const nameCls = `agent-name-${status}` const doingCls = status === 'failed' ? 'agent-doing-failed' : 'agent-doing-dim' + const toolCount = agent.conversation.entries.filter(e => + e.type.startsWith('tool_') + ).length + const doingText = status === 'failed' ? (agent.error || 'failed') : status === 'done' @@ -24,8 +27,9 @@ function AgentRow({ agent }: { agent: Agent }) { <span className={`agent-row-icon ${statusCls}`}>{statusIcon}</span> <span className={`agent-row-name ${nameCls}`}>{agent.label || agent.role}</span> <span className="agent-row-model">{agent.model ?? '--'}</span> - <span className="agent-row-tokens"> - {formatTokens(agent.conversation.inputTokens, agent.conversation.outputTokens)} + <span className="agent-row-tools"> + <span className="agent-row-tools-num">{toolCount}</span> + <span className="agent-row-tools-label"> tools</span> </span> <span className="agent-row-time">{elapsed}</span> <span className={`agent-row-doing ${doingCls}`}>{doingText}</span> @@ -114,7 +118,7 @@ export function AgentMonitor() { <span className="agent-row-icon agent-status-queued">○</span> <span className="agent-row-name agent-name-queued">{a.label || 'scout'}</span> <span className="agent-row-model">--</span> - <span className="agent-row-tokens">--</span> + <span className="agent-row-tools"><span className="agent-row-tools-num">0</span><span className="agent-row-tools-label"> tools</span></span> <span className="agent-row-time">--</span> <span className="agent-row-doing agent-doing-dim">queued</span> </div> diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 20c3119..d76c6b9 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -214,7 +214,9 @@ .agent-row-icon { width: 14px; text-align: center; flex-shrink: 0; } .agent-row-name { width: 200px; flex-shrink: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .agent-row-model { width: 70px; flex-shrink: 0; color: var(--text-muted); } -.agent-row-tokens { width: 60px; flex-shrink: 0; text-align: right; color: var(--text-muted); } +.agent-row-tools { width: 65px; flex-shrink: 0; text-align: right; font-size: var(--font-size-xs); } +.agent-row-tools-num { color: var(--text); } +.agent-row-tools-label { color: var(--text-muted); } .agent-row-time { width: 55px; flex-shrink: 0; text-align: right; color: var(--text-muted); font-size: var(--font-size-xs); } .agent-row-doing { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } From fb5cd915ecbe9912805a9f7760fb8b0e3abbb5f9 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 17:42:50 +0700 Subject: [PATCH 280/412] fix: guard normalizeOptions against undefined question.options LLM question dicts flow unvalidated through the pipeline. When a dict omits the options key, normalizeOptions crashes on .map() causing a blank page. Return an empty array instead. --- frontend/src/components/interactions/AskWizard.tsx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/frontend/src/components/interactions/AskWizard.tsx b/frontend/src/components/interactions/AskWizard.tsx index ba5f6d2..cd4eef0 100644 --- a/frontend/src/components/interactions/AskWizard.tsx +++ b/frontend/src/components/interactions/AskWizard.tsx @@ -7,8 +7,9 @@ import { Md } from '../Md' // or dicts with varying key names. This is data cleaning for LLM output // variability — not business logic. function normalizeOptions( - rawOpts: (string | Record<string, unknown>)[], + rawOpts: (string | Record<string, unknown>)[] | undefined, ): { value: string; label: string; recommended?: boolean }[] { + if (!rawOpts) return [] return rawOpts.map(o => { if (typeof o === 'string') return { value: o, label: o } const label = String(o['label'] ?? o['text'] ?? o['value'] ?? o['option'] ?? '') From b06d4b07c14237cd67af1be785031b479b838522 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 18:17:47 +0700 Subject: [PATCH 281/412] refactor: simplify intake phase from 5 steps to 3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Collapse the intake workflow from 5 steps (Extract, Scout, Ask, Reflect, Write) to 3 steps (Gather, Evaluate, Write): Step 1 (Gather): Read conversation + open ≤5 obvious files + dispatch 3-5 scouts. No read-only gate — all tools available from the start. Step 2 (Evaluate): Process scout results, verify by reading source files, enumerate knowns/unknowns with impact assessment, ask questions. Step 3 (Write): Write landscape.md with review gate (unchanged). Removed: - Confidence loop (steps 2-4 repeating via koan_set_confidence) - koan_set_confidence tool (MCP endpoint, permissions, runners) - Step-1 read-only permission gate for intake role - on_loop_back implementation for intake (now a no-op) - intake_confidence references throughout The old Extract step was artificially read-only, forcing the Scout step to re-derive what files to explore. The old Reflect step risked intrinsic self-correction without external grounding. The confidence loop produced unnecessary second scout batches. One focused pass suffices when the Evaluate step is thorough. --- docs/intake-loop.md | 281 ++++++++++--------------------- koan/lib/permissions.py | 11 -- koan/phases/intake.py | 279 ++++++++++-------------------- koan/runners/base.py | 1 - koan/web/mcp_endpoint.py | 23 +-- tests/test_mcp_check_or_raise.py | 2 +- tests/test_permissions.py | 38 +---- tests/test_phases.py | 63 ++----- 8 files changed, 209 insertions(+), 489 deletions(-) diff --git a/docs/intake-loop.md b/docs/intake-loop.md index 1544dba..d3e47c3 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -1,7 +1,7 @@ -# Intake Loop Design +# Intake Phase Design -How the intake phase implements a confidence-gated investigation loop, and the -prompt engineering principles that govern it. +How the intake phase gathers context in three steps, and the prompt +engineering principles that govern it. > Parent doc: [architecture.md](./architecture.md) > Related: [subagents.md -- Step-First Workflow](./subagents.md#step-first-workflow) @@ -17,256 +17,151 @@ produced downstream depends on the completeness and accuracy of that file. Gaps in `landscape.md` compound: a missed decision becomes a wrong story boundary becomes a wrong plan becomes wrong code. -This weight justifies a more elaborate workflow than other phases. Rather than -a fixed sequence of steps, intake runs a **confidence-gated loop**: the LLM -scouts the codebase, enumerates what it knows, asks the user questions, and -then explicitly self-verifies its understanding. The loop repeats until the -LLM declares "high" confidence that the decomposer has everything it needs. +The intake phase runs a focused **three-step workflow**: gather context +(conversation + codebase orientation + scouts), evaluate findings and ask the +user questions, then write `landscape.md`. ### Step structure -| Step | Name | Runs | Purpose | -| ---- | ------- | ---- | ------------------------------------------------------------------------------- | -| 1 | Extract | 1x | Read conversation input. No side effects. | -| 2 | Scout | 1-4x | Dispatch codebase investigators. | -| 3 | Ask | 1-4x | Enumerate knowns/unknowns, ask user questions. | -| 4 | Reflect | 1-4x | Self-verify completeness, declare confidence. | -| 5 | Write | 1x | Write `landscape.md`. Review gate: calls `koan_review_artifact` before completing. | +| Step | Name | Runs | Purpose | +| ---- | -------- | ---- | --------------------------------------------------------------------------------- | +| 1 | Gather | 1x | Read conversation, open obvious files (≤5), dispatch 3-5 scouts. | +| 2 | Evaluate | 1x | Process scout results, verify by reading files, enumerate knowns/unknowns, ask Qs. | +| 3 | Write | 1x | Write `landscape.md`. Review gate: calls `koan_review_artifact` before completing. | -Steps 2-4 form the loop. Each call to `koan_complete_step` during these steps -either returns the next step in sequence or loops back from step 4 to step 2. -Steps 1 and 5 execute exactly once. +Step 3 is review-gated: it blocks until `koan_review_artifact` is accepted. +All other steps advance linearly. --- -## Non-Linear Step Progression +## Step Design -### `get_next_step()` hook +### Step 1: Gather -The default step engine provides linear progression: `step+1` until -`total_steps`, then `None` (done). Phase modules override `get_next_step(step, ctx)` -to implement non-linear flows. +The Gather step combines what was previously three separate activities +(reading the conversation, orienting in the codebase, and dispatching scouts) +into a single `koan_complete_step` cycle. This avoids the latency and context +re-derivation overhead of artificially separating them. -`koan/phases/intake.py` overrides this to implement the confidence gate: +The step has a **5-file budget** for initial exploration: project root listing, +orientation files (README.md, AGENTS.md, CLAUDE.md), and files the conversation +explicitly referenced. This is enough to write scout prompts that reference +actual function names and file paths rather than conversation labels. -```python -def get_next_step(step, ctx): - """Pure query -- returns where to go, does not mutate state.""" - if step == 4: # Reflect step - if confidence == "high": - return 5 # -> Write - return 2 # -> Scout (loop back) - if step == 5: - return None # Write -> done - return step + 1 # linear for steps 1-3 -``` +No read-only permission gate -- the Gather step has full access to all intake +tools including `koan_request_scouts`. -```python -def on_loop_back(from_step, to_step, ctx): - """Side effects of the loop-back decision live here, not in get_next_step().""" - ctx.iteration += 1 - ctx.intake_confidence = None # reset for next round -``` +### Step 2: Evaluate -`get_next_step()` is a **pure query** -- it only decides where to go. All side -effects (counter increments, state resets, event emission) belong in -`on_loop_back()`, which the step engine calls whenever `get_next_step()` returns -a step number less than the current one. +The Evaluate step processes scout results, verifies findings by reading source +files directly, enumerates knowns and unknowns with a downstream impact +assessment, and asks the user targeted questions. -All other phase modules inherit the default linear behavior. The hook localizes -non-linear logic to the one module that needs it without touching other phases. +Key properties: +- **Scout verification**: Scouts are good at exploration but their output should + be confirmed. The Evaluate step reads actual files to verify key scout findings + that affect scope or story boundaries. +- **Thread-of-Thought enumeration**: The step walks through each area relevant + to the task, explicitly stating what is known and unknown before formulating + questions. This surfaces gaps that would otherwise go unnoticed. +- **Impact classification**: Each unknown is classified as ASK (user input + needed) or SAFE (implementation detail). Only ASK items become questions. +- **Default-ask framing**: Question-asking is the default; skipping requires + triple justification. This inverts the typical LLM bias toward advancing. -### `total_steps` semantics with a loop +### Step 3: Write -For the intake phase, `total_steps = 5` reflects the number of distinct step -definitions, not the number of `koan_complete_step` calls. The loop may -execute steps 2-4 multiple times, with the total calls depending on when high -confidence is reached. +The Write step produces `landscape.md` with required sections (Task Summary, +Prior Art, Codebase Findings, Project Conventions, Decisions, Constraints, +Open Items). Review-gated: the step calls `koan_review_artifact` and loops +on step 3 until the user accepts. --- -## The Confidence Gate - -### Why a separate tool, not a parameter - -`koan_set_confidence` is a dedicated tool rather than a parameter on -`koan_complete_step` for two reasons: - -1. **Optional parameters are skippable.** LLMs frequently omit optional - parameters, especially when under token pressure. A separate tool call is - harder to skip accidentally. - -2. **`koan_complete_step` is shared across all phases.** Adding confidence to - it would bloat the parameter schema for roles that never set confidence. - A dedicated `koan_set_confidence` tool, restricted to the intake role via - permissions, keeps the boundary clean. - -### Mandatory enforcement via `validate_step_completion()` +## Review Gate The step engine calls `validate_step_completion(step, ctx)` before -`get_next_step()`. It returns None to allow advancement or an error string that -is returned as the `koan_complete_step` tool result -- the LLM sees it and -must fix the pre-condition before retrying. - -The intake phase uses this to enforce that `koan_set_confidence` was called in -the Reflect step: +`get_next_step()`. For step 3, it verifies that `koan_review_artifact` was +called and accepted: ```python def validate_step_completion(step, ctx): - if step == 4 and ctx.intake_confidence is None: - return "You must call koan_set_confidence before completing the Reflect step." + if step == 3: + if ctx.last_review_accepted is None: + return "You must call koan_review_artifact..." + if ctx.last_review_accepted is False: + return "The user requested revisions..." return None ``` -### Confidence reset on loop-back - -When `get_next_step()` returns step 2 (loop-back), the step engine detects the -backward transition and calls `on_loop_back()`. The intake module's -`on_loop_back()` resets `ctx.intake_confidence = None`. This ensures that in -the next Reflect step, the LLM must call `koan_set_confidence` again. - ---- - -## Step-Aware Permission Gating - -The permission fence in `koan/lib/permissions.py` accepts the current step -context and blocks specific tools during steps where they would undermine the -workflow. - -### Step 1 (Extract): read-only - -Step 1 should only read the conversation. Without a mechanical gate, the LLM -frontloads all work into step 1. - -`check_permission()` blocks all side-effecting tools when -`role == "intake" and intake_step == 1`: - -``` -koan_request_scouts, koan_ask_question, write, edit +```python +def get_next_step(step, ctx): + if step < 3: + return step + 1 + if ctx.last_review_accepted is True: + return None # done + return 3 # loop on review ``` -### Prompt + enforcement is not redundant - -The prompt tells the LLM not to use side-effecting tools in step 1. The -permission gate is a fallback that catches prompt non-compliance. Together: -the prompt prevents the behavior; the gate catches it when the prompt fails. - ---- - -## Audit Events and SSE Propagation - -Two audit event types support UI visualization of confidence and iteration: - -| Event | Emitted by | When | -| ------------------- | ---------------------------------- | --------------------------------- | -| `confidence_change` | `koan_set_confidence` tool | Every call to koan_set_confidence | -| `iteration_start` | `on_loop_back()` + step transition | At every loop iteration start | - -Both events are folded into the `state.json` projection: - -- `confidence_change` -> `intake_confidence`, `intake_iteration` -- `iteration_start` -> `intake_iteration` - -Audit events are pushed directly from the tool handlers and step engine -- no -polling loop. Browser-visible intake state (current phase, confidence level) is -derived from `agent_step_advanced` and `phase_started` projection events, which -the frontend renders from the Zustand store. - --- ## Prompt Engineering Principles -The intake loop prompts apply several techniques from the prompting literature. +The intake prompts apply several techniques from the prompting literature. This section records the reasoning so future changes don't inadvertently remove mechanisms that address specific failure modes. -### Prompt Chaining over Stepwise (Scout / Ask / Reflect as separate steps) +### MARP (Maximizing Operations per Step) -A monolithic "investigate" step is rejected in favor of three separate -`koan_complete_step` calls. The risk with a monolithic step is **simulated -refinement**: the LLM artificially degrades its initial output to manufacture -visible improvement. Separate steps enforce genuinely isolated reasoning. +The three-step structure applies the MARP principle: maximize operations +per `koan_complete_step` call while minimizing planning or meta-reasoning +steps. Each step does real work across multiple activities rather than +artificially separating them into sequential tool calls. -### Thread-of-Thought in Ask (explicit enumeration before questions) +### Thread-of-Thought in Evaluate (explicit enumeration before questions) -The Ask step instructs the LLM to walk through each area and explicitly +The Evaluate step instructs the LLM to walk through each area and explicitly state what is known, unknown, and its source -- before formulating questions. This surfaces gaps that are not top-of-mind. -### Anticipatory Reflection in Ask (downstream impact assessment) - -Between enumeration and question formulation, the Ask step includes a -downstream impact assessment. Each unknown is classified as ASK (user input -needed), SCOUT (follow-up can resolve), or SAFE (implementation detail). - ### Default-ask question framing (preventing question avoidance) -The Ask step frames question-asking as the default, with skipping +The Evaluate step frames question-asking as the default, with skipping requiring triple justification. This inverts the typical LLM bias toward advancing the workflow. -### Chain-of-Verification in Reflect (evidence-grounded self-assessment) - -The Reflect step instructs the LLM to generate 3-5 verification questions -framed from the decomposer's perspective, then answer each using only concrete -evidence. This is the Chain-of-Verification (CoVe) pattern. - -### Contrastive confidence definitions (preventing premature "high") - -The Reflect step provides both positive ("high confidence means ALL of these -are true") and negative ("you do NOT have high confidence if ANY of these are -true") definitions. -The negative examples make failure modes concrete and explicit. - ### Stakes framing (EmotionPrompt for accountability) The system prompt includes: "A question you don't ask is an answer you're making up." This connects intake shortcuts directly to downstream failures. -### Iteration-aware guidance (first iteration vs. refinement) +### Contrastive examples for thinking density -Steps 2 (Scout) and 3 (Ask) produce different instruction text for -the first iteration vs. subsequent iterations. This prevents the LLM from -repeating its initial exploration. - -### Iteration expectations (soft minimum via GIoT) - -The Reflect step includes soft guidance that round 1 should rarely produce -"high" confidence. This provides directional pressure without forcing -unnecessary iterations on trivial tasks. +The system prompt includes WRONG → RIGHT examples for processing scout reports, +resolving conflicts, and classifying unknowns. These demonstrate the target +density for internal reasoning without affecting tool arguments or written +artifacts. --- ## Pitfalls -### Don't put confidence in koan_complete_step's `thoughts` parameter - -`thoughts` is an escape hatch for models that can't mix text + tool_call. -Parsing it for routing decisions would violate driver determinism. Confidence -must flow through a structured tool call. - -### Don't rely on the Reflect prompt alone to enforce koan_set_confidence - -The `validate_step_completion()` hook is the mechanical enforcement layer. -Both prompt and hook must be present. - -### Don't remove the confidence null-reset on loop-back - -Without this reset, `validate_step_completion()` sees the old confidence value -and allows advancement without the LLM calling `koan_set_confidence` again. -The reset must happen in `on_loop_back()`, not in `get_next_step()`. - -### Don't add koan_set_confidence to non-intake roles +### Don't re-add a step-1 read-only gate for intake -`koan_set_confidence` is gated to the intake role via permissions. +Intake's Gather step needs all tools (especially `koan_request_scouts`) from +the start. The brief-writer still has a step-1 read-only gate, but intake +does not. -### Don't make the "NOT high" checklist vacuously satisfiable +### Don't add a confidence loop -Every condition must be non-vacuously testable. Prefer conditions that require -positive evidence: "you have not asked any questions" is mechanically true or -false based on whether `koan_ask_question` was called. +Previous iterations had a confidence-gated loop (steps 2-4 repeating). +This was removed because: (a) it produced unnecessary second scout batches, +(b) the self-verification step (Reflect) risked intrinsic self-correction +without external grounding, and (c) one focused pass is sufficient when the +Evaluate step is thorough. -### Don't skip step sync on loop-back +### Don't separate scout verification from question-asking -The permission gate reads the current step at tool call time. If the step -context is not updated on loop-back, gates fire at the wrong step. +Scout result evaluation and question formulation are tightly coupled -- a scout +finding directly informs what questions to ask. Separating them forces the LLM +to defer questions it could ask immediately. diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index f9756b0..b3d605f 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -30,7 +30,6 @@ "koan_ask_question", "koan_request_scouts", "koan_review_artifact", - "koan_set_confidence", "edit", "write", }), @@ -131,16 +130,6 @@ def check_permission( if tool_name in READ_TOOLS: return {"allowed": True, "reason": None} - # Intake step 1 (Extract) is read-only. - if role == "intake" and current_step == 1 and tool_name in STEP_1_BLOCKED_TOOLS: - return { - "allowed": False, - "reason": ( - f"{tool_name} is not available during the Extract step (step 1). " - "Complete koan_complete_step first to advance to the Scout step." - ), - } - # Brief-writer step 1 (Read) is read-only. if role == "brief-writer" and current_step == 1 and tool_name in STEP_1_BLOCKED_TOOLS: return { diff --git a/koan/phases/intake.py b/koan/phases/intake.py index 3aaf4df..cfaf883 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -1,14 +1,10 @@ -# Intake phase -- 5-step workflow with confidence-gated loop. +# Intake phase -- 3-step workflow. # -# Step 1 (Extract) -- read-only comprehension of conversation.jsonl -# Step 2 (Scout) -- dispatch codebase scouts, analyze results -# Step 3 (Ask) -- enumerate knowns/unknowns, ask questions, follow up -# Step 4 (Reflect) -- verify completeness, set confidence via koan_set_confidence -# Step 5 (Write) -- write landscape.md, present for user review +# Step 1 (Gather) -- read conversation, explore obvious files, dispatch scouts +# Step 2 (Evaluate) -- process scout results, verify, ask questions +# Step 3 (Write) -- write landscape.md, present for user review # -# Confidence gate: step 4 -> step 5 only when confidence is "high". -# Otherwise loops back to step 2 (Scout) for another iteration. -# Step 5 is review-gated: blocks until koan_review_artifact accepted. +# Step 3 is review-gated: blocks until koan_review_artifact accepted. from __future__ import annotations @@ -16,14 +12,12 @@ from .review_protocol import REVIEW_PROTOCOL ROLE = "intake" -TOTAL_STEPS = 5 +TOTAL_STEPS = 3 STEP_NAMES: dict[int, str] = { - 1: "Extract", - 2: "Scout", - 3: "Ask", - 4: "Reflect", - 5: "Write", + 1: "Gather", + 2: "Evaluate", + 3: "Write", } SYSTEM_PROMPT = ( @@ -114,9 +108,8 @@ "\n" "## Workflow\n" "\n" - "You work in stages: read the conversation, scout the codebase, ask the user" - " questions, verify your understanding, and write landscape.md. Each step" - " builds on the previous one.\n" + "You work in three steps: gather context (conversation + codebase + scouts)," + " evaluate findings and ask questions, then write landscape.md.\n" "\n" "## Output\n" "\n" @@ -141,7 +134,9 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: if step == 1: conversation_path = f"{ctx.epic_dir}/conversation.jsonl" lines = [ - "Read the conversation file. Build a thorough mental model of what is being requested.", + "Read the conversation, orient yourself in the codebase, and dispatch scouts.", + "", + "## 1. Read the conversation", "", f"Conversation file: {conversation_path}", "", @@ -149,9 +144,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "Read entries with type 'message' and role 'user' or 'assistant'.", "Ignore internal entries (header, compaction, etc.).", "", - "## What to internalize", - "", - "As you read, track these categories:", + "As you read, track:", "- **Topic**: What is being built or changed?", "- **File references**: Every file, directory, or module mentioned.", "- **Decisions already made**: Only those explicitly stated and agreed upon.", @@ -159,12 +152,59 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "- **Gaps**: Questions raised but unanswered. Things unclear or unstated that would affect story boundaries.", "- **Conventions mentioned**: Any references to coding standards, test approaches, doc standards, or patterns to follow.", "", - "## Rules for this step", + "Be faithful to what was said. Do not invent context or infer unstated decisions.", + "", + "## 2. Quick orientation -- open obvious files", + "", + "Open up to **5 files** that any investigation would start from:", + "", + "- `ls` the project root.", + "- Open root-level orientation files if they exist: README.md, AGENTS.md, CLAUDE.md.", + "- Open any file the conversation explicitly referenced -- skim structure,", + " exports, key patterns (first 50-100 lines is enough).", + "- If the conversation mentions a module by name without a path, one", + " `find` or `ls` to locate it, then open the entry point.", + "", + "Budget: 5 file reads max. This is orientation, not investigation.", + "Just enough to write scout prompts that reference actual function names,", + "actual patterns, and actual file paths instead of conversation labels.", + "", + "## 3. Plan and dispatch scouts", + "", + "Using the conversation and what you observed in the files, identify the", + "concerns that need investigation. Consider both:", "", - "- Do NOT call koan_request_scouts, koan_ask_question, write, or edit.", - "- This step is read-only. Understand the conversation before acting on it.", - "- Be faithful to what was said. Do not invent context or infer unstated decisions.", - "- If the conversation references specific files or systems, note them -- you will scout those next.", + "- What the conversation explicitly references (files, modules, integration", + " points, assumptions that need verification, project conventions).", + "- What the conversation did NOT mention but could matter (hidden callers,", + " related subsystems, prior art, invariants, test coverage).", + "", + "Group related concerns into **3-5 clusters**. Each cluster becomes one", + "scout. A scout is a broad investigator -- it can examine multiple files,", + "trace dependencies, and answer several related questions in a single run.", + "Merge concerns that touch the same area of the codebase or the same", + "conceptual boundary into one scout with a multi-part prompt.", + "", + "3-5 scouts is the target. Fewer than 3 means your prompts are probably", + "too broad to produce focused findings. More than 5 means you are splitting", + "related concerns that a single scout could cover together.", + "", + "Use `koan_request_scouts` to dispatch all scouts in a single call.", + "", + "Each scout needs:", + "- id: short kebab-case identifier (e.g., 'auth-and-permissions', 'data-layer')", + "- role: investigator focus (e.g., 'authentication auditor', 'dependency tracer')", + "- prompt: a rich, multi-part investigation brief. Tell the scout what area", + " to explore, what questions to answer, and what to look for. Include file", + " paths and function names from the orientation step. A good prompt is 3-8", + " sentences covering the full cluster.", + "", + "Example of a well-scoped scout prompt:", + " 'Investigate the authentication subsystem rooted at src/auth/. Find all", + " callers of verifyToken(), identify the middleware chain in server.ts,", + " check whether session storage uses Redis or in-memory, and note any", + " TODO or FIXME comments related to auth. Report the permission model", + " (RBAC, ACL, or ad-hoc checks) and how it integrates with the router.'", ] if ctx.phase_instructions: lines.extend(["", "## Additional Context from Workflow Orchestrator", "", ctx.phase_instructions]) @@ -174,98 +214,27 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: return StepGuidance( title=STEP_NAMES[2], instructions=[ - "Based on your reading of the conversation, identify areas of the codebase that need exploration.", - "", - "## Step 1: Understand -- what questions need answers?", - "", - "Before doing anything else, articulate what you need to find out.", - "Walk through the conversation findings from Extract and list:", - "", - "- What areas of the codebase does this task touch?", - "- What assumptions did the user make that need verification?", - "- What integration points, dependencies, or constraints are unclear?", - "- What was NOT mentioned that could matter?", - "", - "This is your question list. Everything downstream serves it.", - "", - "## Step 2: Ground -- open the files the conversation named", - "", - "Now read the actual code for files the conversation explicitly referenced.", - "You noted them during Extract -- open them now.", - "", - "- `ls` the project root if you haven't already.", - "- Open each file or directory the conversation explicitly mentioned.", - " Skim structure, exports, key patterns -- first 50-100 lines is enough.", - "- If the conversation mentions a module by name without a path, one", - " `find` or `ls` to locate it, then open the entry point.", - "", - "Stop here. This is orientation, not investigation -- just enough to write", - "scout prompts that reference actual function names, actual patterns, and", - "actual file paths instead of conversation labels.", - "", - "## Step 3: Plan -- cluster into 3-5 scout investigations", - "", - "Using your question list and what you observed in the code, identify the", - "concerns that need investigation. Consider both:", - "", - "- What the conversation explicitly references (files, modules, integration", - " points, assumptions that need verification, project conventions).", - "- What the conversation did NOT mention but could matter (hidden callers,", - " related subsystems, prior art, invariants, test coverage).", - "", - "Now group related concerns into **3-5 clusters**. Each cluster becomes one", - "scout. A scout is a broad investigator -- it can examine multiple files,", - "trace dependencies, and answer several related questions in a single run.", - "Merge concerns that touch the same area of the codebase or the same", - "conceptual boundary into one scout with a multi-part prompt.", - "", - "3-5 scouts is the target. Fewer than 3 means your prompts are probably", - "too broad to produce focused findings. More than 5 means you are splitting", - "related concerns that a single scout could cover together.", - "", - "## Step 4: Execute -- dispatch scouts", - "", - "Use `koan_request_scouts` to dispatch all scouts in a single call.", - "", - "Each scout needs:", - "- id: short kebab-case identifier (e.g., 'auth-and-permissions', 'data-layer')", - "- role: investigator focus (e.g., 'authentication auditor', 'dependency tracer')", - "- prompt: a rich, multi-part investigation brief. Tell the scout what area", - " to explore, what questions to answer, and what to look for. Include file", - " paths and function names from the Ground step. A good prompt is 3-8", - " sentences covering the full cluster.", + "Analyze scout results, verify findings, and ask the user questions.", "", - "Example of a well-scoped scout prompt:", - " 'Investigate the authentication subsystem rooted at src/auth/. Find all", - " callers of verifyToken(), identify the middleware chain in server.ts,", - " check whether session storage uses Redis or in-memory, and note any", - " TODO or FIXME comments related to auth. Report the permission model", - " (RBAC, ACL, or ad-hoc checks) and how it integrates with the router.'", - "", - "## Step 5: Analyze results", + "## 1. Analyze scout results", "", "When scouts return, analyze each report:", "- Does the finding answer the questions you asked?", "- Does it reveal anything unexpected about the codebase?", - "- Does it raise new questions that need user input?", + "- Does it conflict with what the conversation stated?", "", - "If a finding reveals a concrete gap -- a specific file, dependency, or", - "integration point that no scout covered and that affects scope -- dispatch", - "1-2 targeted follow-up scouts. Do not dispatch follow-ups for vague", - "curiosity or marginal coverage improvements.", + "## 2. Verify -- read files to confirm", "", - "Do NOT ask the user questions in this step -- that happens in the Ask step.", - ], - ) - - if step == 3: - return StepGuidance( - title=STEP_NAMES[3], - instructions=[ - "Before asking questions, explicitly enumerate what you know and what you don't.", - "This grounds your questions in reality and prevents asking things already answered.", + "Scouts are good at exploration but their output should be verified.", + "For key findings that affect scope or story boundaries, open the", + "actual files and confirm what the scout reported. This is especially", + "important for:", + "", + "- Integration points the scout identified", + "- Patterns or conventions the scout claims to have found", + "- Anything that conflicts with what the conversation stated", "", - "## Phase A: Recite what you know", + "## 3. Enumerate what you know and what you don't", "", "Walk through each area relevant to the task and state what you have learned.", "Use this structure for each area:", @@ -275,15 +244,16 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: " - Unknown: [what remains unclear or unverified]", " - Source: [conversation / scout findings]", "", - "Cover every area relevant to the task. Be thorough -- gaps you miss here become gaps in the final output.", + "Cover every area relevant to the task. Be thorough -- gaps you miss here", + "become gaps in the final output.", "", "Include project conventions as an area: where are coding style, testing strategy,", "architecture patterns, and documentation standards defined? If not explicitly", "documented, note whether they are emergent from code patterns or absent entirely.", "", - "## Phase A.5: Downstream impact assessment", + "## 4. Downstream impact assessment", "", - "For each 'Unknown' item from Phase A, briefly assess:", + "For each 'Unknown' item, briefly assess:", "- If you assume wrong about this, what happens to downstream planning?", "- Could a wrong assumption split a story that should be one, or merge two that should be separate?", "- Would the executor hit a surprise that requires re-planning?", @@ -294,10 +264,9 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "Mark each unknown as:", "- **ASK**: user input needed -- this affects scope, boundaries, or sequencing.", - "- **SCOUT**: a follow-up scout can resolve this factually -- note for the Reflect step.", "- **SAFE**: genuinely an implementation detail with no scope impact.", "", - "## Phase B: Formulate and ask questions", + "## 5. Ask questions", "", "For each 'Unknown' marked ASK, ask yourself: if I get this wrong, does it affect", "the decomposer's ability to define correct story boundaries? If yes or maybe -- ask.", @@ -317,7 +286,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "Include the optional context field when background is needed for an informed decision.", "Ground questions in specific findings: 'Scout found X -- should this story follow the same pattern?'", "", - "## Phase C: Process answers and follow up", + "## 6. Process answers and follow up", "", "When answers arrive, think through each one carefully:", "", @@ -337,56 +306,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: ], ) - if step == 4: - return StepGuidance( - title=STEP_NAMES[4], - instructions=[ - "Step back and verify the completeness of your understanding. This is the last", - "chance to gather information before writing landscape.md.", - "", - "## Verification questions", - "", - "Generate 3-5 questions that test whether your understanding is complete.", - "Frame them from the decomposer's perspective -- the decomposer must split this work into stories.", - "", - "Example verification questions:", - "- 'Could I define the boundary between story 1 and story 2 right now?'", - "- 'If the user's codebase uses pattern X (per scout), does our understanding account for that?'", - "- 'Are there any user decisions that could split one story into two or merge two into one?'", - "", - "## Answer each question", - "", - "Answer each verification question using ONLY evidence you have:", - "- Direct quotes or facts from the conversation", - "- Specific findings from scouts", - "- Explicit answers from the user", - "", - "If you cannot answer a verification question with evidence, that is a gap.", - "", - "## Act on gaps", - "", - "If you identified gaps:", - "", - "- **Need codebase information?** Dispatch scouts via `koan_request_scouts`.", - " Analyze the results when they return.", - "- **Need user input?** Ask via `koan_ask_question`. Think through the answers.", - "- **Need to read specific files?** Read them directly with read tools.", - "", - "## Set confidence", - "", - "After resolving gaps (or confirming none remain), you MUST call `koan_set_confidence`", - "to declare your confidence level before completing this step.", - "", - "- `high` -- you are confident the understanding is complete and ready for synthesis.", - "- `medium` -- some areas are uncertain; another Scout/Ask cycle would help.", - "- `low` -- significant gaps remain; another iteration is needed.", - "", - "If confidence is not high, the workflow will loop back to the Scout step", - "for another iteration. If confidence is high, you will proceed to write landscape.md.", - ], - ) - - if step == 5: + if step == 3: lines = [ f"Write `{ctx.epic_dir}/landscape.md`." if ctx.epic_dir @@ -488,7 +408,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: ' and description "Landscape document -- background information for downstream planning".' ), ] - return StepGuidance(title=STEP_NAMES[5], instructions=lines) + return StepGuidance(title=STEP_NAMES[3], instructions=lines) return StepGuidance(title=f"Step {step}", instructions=[f"Execute step {step}."]) @@ -496,28 +416,16 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: # -- Lifecycle ----------------------------------------------------------------- def get_next_step(step: int, ctx: PhaseContext) -> int | None: - if step < 4: + if step < 3: return step + 1 - # Step 4 (Reflect): confidence gate. - if step == 4: - if ctx.intake_confidence == "high": - return 5 - return 2 # loop back to Scout - # Step 5 (Write): review-gated. + # Step 3 (Write): review-gated. if ctx.last_review_accepted is True: return None - return 5 + return 3 def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: - if step == 4: - if ctx.intake_confidence is None: - return ( - "You must call koan_set_confidence to declare your confidence level" - " before completing the Reflect step." - ) - return None - if step == 5: + if step == 3: if ctx.last_review_accepted is None: return "You must call koan_review_artifact to present landscape.md for review before completing this step." if ctx.last_review_accepted is False: @@ -527,5 +435,4 @@ def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: async def on_loop_back(from_step: int, to_step: int, ctx: PhaseContext) -> None: - ctx.intake_iteration += 1 - ctx.intake_confidence = None + pass # no loop-back in current workflow diff --git a/koan/runners/base.py b/koan/runners/base.py index 4aa2322..a6ca90f 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -62,7 +62,6 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: ... # When adding a new koan MCP tool to mcp_endpoint.py, update this set too. KOAN_MCP_TOOLS: frozenset[str] = frozenset({ "koan_complete_step", - "koan_set_confidence", "koan_request_scouts", "koan_ask_question", "koan_review_artifact", diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index c8918db..cfcd528 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -3,7 +3,7 @@ # Exposes build_mcp_asgi_app() which returns an ASGI sub-app that: # 1. Validates agent_id from query params before reaching fastmcp. # 2. Runs check_permission() on every tool call. -# 3. Implements koan_complete_step, koan_set_confidence, koan_request_scouts, +# 3. Implements koan_complete_step, koan_request_scouts, # koan_ask_question, koan_review_artifact, koan_propose_workflow, # koan_set_next_phase. @@ -176,27 +176,6 @@ async def koan_complete_step(thoughts: str = "") -> str: end_tool_call(agent, call_id, "koan_complete_step", result_str) -@mcp.tool(name="koan_set_confidence") -async def koan_set_confidence(level: str = "") -> str: - agent = _get_agent() - _check_or_raise(agent, "koan_set_confidence", {"level": level}) - - call_id = begin_tool_call(agent, "koan_set_confidence", {"level": level}, level) - result_str: str | None = None - try: - valid_levels = {"high", "medium", "low"} - if level not in valid_levels: - raise ToolError( - json.dumps({"error": "invalid_confidence", "message": f"level must be one of {valid_levels}"}) - ) - - agent.phase_ctx.intake_confidence = level - result_str = f"Confidence set to {level}." - return result_str - finally: - end_tool_call(agent, call_id, "koan_set_confidence", result_str) - - @mcp.tool(name="koan_request_scouts") async def koan_request_scouts(questions: list[dict] | None = None) -> str: agent = _get_agent() diff --git a/tests/test_mcp_check_or_raise.py b/tests/test_mcp_check_or_raise.py index 60038ca..460dd27 100644 --- a/tests/test_mcp_check_or_raise.py +++ b/tests/test_mcp_check_or_raise.py @@ -69,7 +69,7 @@ class TestPermissionDeniedEnvelope: def test_envelope_has_error_and_message(self): agent = _make_agent(role="scout") with pytest.raises(ToolError) as exc_info: - _check_or_raise(agent, "koan_set_confidence", {"level": "high"}) + _check_or_raise(agent, "koan_ask_question", {"questions": []}) body = json.loads(str(exc_info.value)) assert body["error"] == "permission_denied" assert "message" in body diff --git a/tests/test_permissions.py b/tests/test_permissions.py index e0e03f0..2a4ce31 100644 --- a/tests/test_permissions.py +++ b/tests/test_permissions.py @@ -55,16 +55,11 @@ class TestStep1Blocking: def setup_method(self): self.blocked = list(STEP_1_BLOCKED_TOOLS) - def test_intake_step_1_blocks(self): + def test_intake_step_1_allows(self): + """Intake no longer blocks tools at step 1 (gather step uses all tools).""" for tool in self.blocked: r = check_permission("intake", tool, current_step=1) - assert not r["allowed"], f"intake step 1 should block {tool}" - assert "step 1" in r["reason"].lower() - - def test_intake_step_2_allows(self): - for tool in self.blocked: - r = check_permission("intake", tool, current_step=2) - assert r["allowed"], f"intake step 2 should allow {tool}" + assert r["allowed"], f"intake step 1 should allow {tool}" def test_brief_writer_step_1_blocks(self): for tool in self.blocked: @@ -116,13 +111,15 @@ def test_role_tool(self, role, tool, expected): # -- Exhaustive step-1 matrix ------------------------------------------------- def _build_step1_matrix(): - """For intake and brief-writer at step 1, verify blocked tools are denied - and all other allowed tools still pass.""" + """For brief-writer at step 1, verify blocked tools are denied + and all other allowed tools still pass. Intake no longer has a + step-1 gate so its step-1 expectations match normal permissions.""" cases = [] for role in ("intake", "brief-writer"): allowed_set = ROLE_PERMISSIONS[role] | READ_TOOLS for tool in sorted(ALL_KOAN_TOOLS): - if tool in STEP_1_BLOCKED_TOOLS: + # Only brief-writer blocks tools at step 1; intake does not. + if role == "brief-writer" and tool in STEP_1_BLOCKED_TOOLS: expected = False elif tool in allowed_set: expected = True @@ -147,25 +144,6 @@ def test_step1(self, role, tool, expected): ) -# -- Intake koan_set_confidence access ----------------------------------------- - -class TestIntakeConfidenceTool: - def test_intake_can_call_set_confidence(self): - r = check_permission("intake", "koan_set_confidence", current_step=4) - assert r["allowed"] - - def test_intake_set_confidence_blocked_step_1(self): - """koan_set_confidence is not in STEP_1_BLOCKED_TOOLS, so it should - still be allowed at step 1 (permission layer does not block it).""" - r = check_permission("intake", "koan_set_confidence", current_step=1) - assert r["allowed"] - - def test_non_intake_roles_cannot_call_set_confidence(self): - for role in ("scout", "decomposer", "brief-writer", "executor"): - r = check_permission(role, "koan_set_confidence", current_step=2) - assert not r["allowed"], f"{role} should not have koan_set_confidence" - - # -- Path scoping -------------------------------------------------------------- class TestPathScoping: diff --git a/tests/test_phases.py b/tests/test_phases.py index 172cfb8..12e1424 100644 --- a/tests/test_phases.py +++ b/tests/test_phases.py @@ -26,60 +26,41 @@ def _ctx(**kw) -> PhaseContext: # -- Intake -------------------------------------------------------------------- class TestIntake: - # -- Linear progression (steps 1-3) ---------------------------------------- + # -- Linear progression (steps 1-2) ---------------------------------------- - @pytest.mark.parametrize("step", [1, 2, 3]) + @pytest.mark.parametrize("step", [1, 2]) def test_linear_steps(self, step): assert intake.get_next_step(step, _ctx()) == step + 1 - # -- Confidence gate (step 4) ---------------------------------------------- + # -- Review gate (step 3) -------------------------------------------------- - def test_step_4_high_confidence_advances_to_5(self): - assert intake.get_next_step(4, _ctx(intake_confidence="high")) == 5 + def test_step_3_accepted_completes(self): + assert intake.get_next_step(3, _ctx(last_review_accepted=True)) is None - def test_step_4_medium_confidence_loops_to_2(self): - assert intake.get_next_step(4, _ctx(intake_confidence="medium")) == 2 + def test_step_3_not_accepted_loops(self): + assert intake.get_next_step(3, _ctx(last_review_accepted=False)) == 3 - def test_step_4_low_confidence_loops_to_2(self): - assert intake.get_next_step(4, _ctx(intake_confidence="low")) == 2 - - def test_step_4_no_confidence_loops_to_2(self): - assert intake.get_next_step(4, _ctx(intake_confidence=None)) == 2 - - def test_validate_step_4_requires_confidence(self): - result = intake.validate_step_completion(4, _ctx(intake_confidence=None)) - assert result is not None - assert "koan_set_confidence" in result - - def test_validate_step_4_confidence_set_passes(self): - assert intake.validate_step_completion(4, _ctx(intake_confidence="medium")) is None - - # -- Review gate (step 5) -------------------------------------------------- - - def test_step_5_accepted_completes(self): - assert intake.get_next_step(5, _ctx(last_review_accepted=True)) is None - - def test_step_5_not_accepted_loops(self): - assert intake.get_next_step(5, _ctx(last_review_accepted=False)) == 5 - - def test_validate_step_5_never_reviewed(self): - result = intake.validate_step_completion(5, _ctx(last_review_accepted=None)) + def test_validate_step_3_never_reviewed(self): + result = intake.validate_step_completion(3, _ctx(last_review_accepted=None)) assert result is not None assert "koan_review_artifact" in result - def test_validate_step_5_feedback_pending(self): - result = intake.validate_step_completion(5, _ctx(last_review_accepted=False)) + def test_validate_step_3_feedback_pending(self): + result = intake.validate_step_completion(3, _ctx(last_review_accepted=False)) assert result is not None assert "revision" in result.lower() or "feedback" in result.lower() - def test_validate_step_5_accepted(self): - assert intake.validate_step_completion(5, _ctx(last_review_accepted=True)) is None + def test_validate_step_3_accepted(self): + assert intake.validate_step_completion(3, _ctx(last_review_accepted=True)) is None # -- No gate on other steps ------------------------------------------------ def test_validate_step_1_no_gate(self): assert intake.validate_step_completion(1, _ctx()) is None + def test_validate_step_2_no_gate(self): + assert intake.validate_step_completion(2, _ctx()) is None + # -- Brief Writer -------------------------------------------------------------- @@ -185,19 +166,11 @@ def test_validate_always_none(self, mod, total): # -- Purity invariant ---------------------------------------------------------- class TestPurity: - def test_intake_confidence_gate_purity(self): - ctx = _ctx(intake_confidence="medium") - ctx_copy = copy.deepcopy(ctx) - r1 = intake.get_next_step(4, ctx) - r2 = intake.get_next_step(4, ctx) - assert r1 == r2 - assert ctx == ctx_copy - def test_intake_review_gate_purity(self): ctx = _ctx(last_review_accepted=False) ctx_copy = copy.deepcopy(ctx) - r1 = intake.get_next_step(5, ctx) - r2 = intake.get_next_step(5, ctx) + r1 = intake.get_next_step(3, ctx) + r2 = intake.get_next_step(3, ctx) assert r1 == r2 assert ctx == ctx_copy From 11996c19b4115dd7e9b89eb68cd602068de7cdbe Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 18:51:35 +0700 Subject: [PATCH 282/412] feat: --debug flag to show step guidance prompts in UI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When koan is launched with --debug, the tool responses from koan_complete_step (the actual prompts that tell the LLM what to do) are rendered in the activity feed as collapsible cards. Pipeline: koan_complete_step emits debug_step_guidance event → projection folds it into DebugStepGuidanceEntry → frontend renders as a copper-colored card with click-to-expand. Cards are collapsed by default to avoid overwhelming the feed. Only emitted when --debug is active — zero overhead in normal mode. --- frontend/src/components/ActivityFeed.tsx | 22 ++++++++++++++++++++++ frontend/src/store/index.ts | 2 ++ frontend/src/styles/layout.css | 14 ++++++++++++++ koan/__main__.py | 4 +++- koan/projections.py | 23 ++++++++++++++++++++++- koan/state.py | 1 + koan/web/mcp_endpoint.py | 9 +++++++++ 7 files changed, 73 insertions(+), 2 deletions(-) diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index d98d009..92c5733 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -48,6 +48,26 @@ function TextBlock({ text }: { text: string }) { return <div className="stream-output"><Md>{text}</Md></div> } +// -- Debug step guidance ------------------------------------------------------- + +function DebugGuidanceCard({ content }: { content: string }) { + const [expanded, setExpanded] = useState(false) + + return ( + <div className="activity-card activity-card-debug"> + <div className="activity-card-header" onClick={() => setExpanded(!expanded)} style={{ cursor: 'pointer' }}> + <span className="activity-card-tool">step guidance</span> + <span className="activity-card-toggle">{expanded ? '▾' : '▸'}</span> + </div> + {expanded && ( + <div className="activity-card-body expanded"> + <Md>{content}</Md> + </div> + )} + </div> + ) +} + // -- Tool lines ---------------------------------------------------------------- function statusIcon(inFlight: boolean) { return inFlight ? '›' : '✓' } @@ -103,6 +123,8 @@ function renderEntry(entry: ConversationEntry, i: number) { return <DetailLine key={i} tool="ls" detail={entry.path} inFlight={entry.inFlight} /> case 'tool_generic': return <ToolLine key={i} tool={entry.toolName} summary={entry.summary} inFlight={entry.inFlight} /> + case 'debug_step_guidance': + return <DebugGuidanceCard key={i} content={entry.content} /> default: return null } diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 00f6b86..837ac53 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -43,11 +43,13 @@ export interface ToolBashEntry extends BaseToolEntry { type: 'tool_bash'; export interface ToolGrepEntry extends BaseToolEntry { type: 'tool_grep'; pattern: string } export interface ToolLsEntry extends BaseToolEntry { type: 'tool_ls'; path: string } export interface ToolGenericEntry extends BaseToolEntry { type: 'tool_generic'; toolName: string; summary: string } +export interface DebugStepGuidanceEntry { type: 'debug_step_guidance'; content: string } export type ConversationEntry = | ThinkingEntry | TextEntry | StepEntry | ToolReadEntry | ToolWriteEntry | ToolEditEntry | ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry + | DebugStepGuidanceEntry export interface Conversation { entries: ConversationEntry[] diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index 36ddb0b..c8d144d 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -130,6 +130,20 @@ color: var(--plum); } +.activity-card-debug { + background: var(--copper-bg); + border-left-color: var(--copper); +} + +.activity-card-debug .activity-card-tool { + color: var(--copper); +} + +.activity-card-toggle { + color: var(--text-muted); + font-size: var(--font-size-xs); +} + .activity-card-meta { color: var(--text-muted); font-size: var(--font-size-xs); diff --git a/koan/__main__.py b/koan/__main__.py index 996d575..b51c283 100644 --- a/koan/__main__.py +++ b/koan/__main__.py @@ -87,6 +87,8 @@ def main() -> None: help="Pre-fill the task description") parser.add_argument("--yolo", action="store_true", help="Skip all agent permission prompts (dangerous)") + parser.add_argument("--debug", action="store_true", + help="Show step guidance prompts in the UI") args = parser.parse_args() setup_logging(args.log_level) @@ -98,7 +100,7 @@ def main() -> None: config = asyncio.run(load_koan_config()) app_state = AppState(config=config, port=port, open_browser=not args.no_open, - initial_prompt=args.prompt, yolo=args.yolo) + initial_prompt=args.prompt, yolo=args.yolo, debug=args.debug) app = create_app(app_state) host = "127.0.0.1" diff --git a/koan/projections.py b/koan/projections.py index d66cab8..dfe08c1 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -50,6 +50,7 @@ "thinking", "stream_delta", "stream_cleared", + "debug_step_guidance", # Focus (interactions) "questions_asked", "questions_answered", @@ -166,10 +167,16 @@ class ToolGenericEntry(BaseToolEntry): tool_name: str # original tool name from the LLM summary: str = "" # human-readable one-liner from the runner parser +class DebugStepGuidanceEntry(KoanBaseModel): + """Step guidance prompt shown in --debug mode.""" + type: Literal["debug_step_guidance"] = "debug_step_guidance" + content: str # full formatted step guidance text + ConversationEntry = Annotated[ ThinkingEntry | TextEntry | StepEntry | ToolReadEntry | ToolWriteEntry | ToolEditEntry | - ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry, + ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry | + DebugStepGuidanceEntry, Field(discriminator="type"), ] @@ -813,6 +820,20 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: "run": _update_agent_conversation(projection.run, agent_id, new_conv), }) + case "debug_step_guidance": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + content = payload.get("content", "") + new_conv = agent.conversation.model_copy(update={ + "entries": [*agent.conversation.entries, DebugStepGuidanceEntry(content=content)], + }) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv), + }) + case "agent_step_advanced": if projection.run is None or not agent_id: return projection diff --git a/koan/state.py b/koan/state.py index 65ca4c5..96396c8 100644 --- a/koan/state.py +++ b/koan/state.py @@ -67,6 +67,7 @@ class AppState: open_browser: bool = True initial_prompt: str = "" yolo: bool = False + debug: bool = False config_write_lock: asyncio.Lock = field(default_factory=asyncio.Lock) # Installation selections for the current run: runner_type -> alias. # Set when a run starts; cleared when a new run begins. diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index cfcd528..440dfe1 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -171,6 +171,15 @@ async def koan_complete_step(thoughts: str = "") -> str: guidance = phase_module.step_guidance(next_step, ctx) result_str = format_step(guidance) + + # In debug mode, surface the step guidance in the UI + if _app_state is not None and _app_state.debug: + _app_state.projection_store.push_event( + "debug_step_guidance", + {"content": result_str}, + agent_id=agent.agent_id, + ) + return result_str finally: end_tool_call(agent, call_id, "koan_complete_step", result_str) From d0165499b7632e2ec605b386dd45d80c7950453c Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 18:55:49 +0700 Subject: [PATCH 283/412] fix: scope scouts to the project directory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Capture CWD at startup as project_dir and thread it through AppState → scout task → PhaseContext → scout step 1 guidance. Scouts now receive an explicit Project Directory section telling them where to search and forbidding broad filesystem scans like find / or find ~. --- koan/__main__.py | 3 ++- koan/phases/__init__.py | 1 + koan/phases/scout.py | 12 ++++++++++++ koan/state.py | 1 + koan/subagent.py | 1 + koan/web/mcp_endpoint.py | 1 + 6 files changed, 18 insertions(+), 1 deletion(-) diff --git a/koan/__main__.py b/koan/__main__.py index b51c283..5c8a01a 100644 --- a/koan/__main__.py +++ b/koan/__main__.py @@ -100,7 +100,8 @@ def main() -> None: config = asyncio.run(load_koan_config()) app_state = AppState(config=config, port=port, open_browser=not args.no_open, - initial_prompt=args.prompt, yolo=args.yolo, debug=args.debug) + initial_prompt=args.prompt, yolo=args.yolo, debug=args.debug, + project_dir=str(Path.cwd())) app = create_app(app_state) host = "127.0.0.1" diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index 7bb2f45..8aee4a4 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -21,6 +21,7 @@ class StepGuidance: class PhaseContext: epic_dir: str subagent_dir: str + project_dir: str = "" phase_instructions: str | None = None intake_confidence: str | None = None intake_iteration: int = 0 diff --git a/koan/phases/scout.py b/koan/phases/scout.py index da08029..3c31b66 100644 --- a/koan/phases/scout.py +++ b/koan/phases/scout.py @@ -75,6 +75,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: investigator_role = ctx.scout_investigator_role or "" if step == 1: + project_dir = ctx.project_dir or "" lines = [ "Find and read the relevant code to answer the question.", "", @@ -85,6 +86,17 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: lines.append(f"**Question:** {question}") if investigator_role: lines.append(f"**Your investigator role:** {investigator_role}") + if project_dir: + lines.extend([ + "", + "## Project Directory", + "", + f"The project root is: `{project_dir}`", + "", + "All investigation MUST be scoped to this directory.", + "Do NOT search outside this path -- no `find /`, no `find ~`, no `/tmp`.", + "Always `cd` into the project directory or use absolute paths within it.", + ]) lines.extend([ "", "## Actions", diff --git a/koan/state.py b/koan/state.py index 96396c8..999506a 100644 --- a/koan/state.py +++ b/koan/state.py @@ -53,6 +53,7 @@ class AgentState: class AppState: phase: EpicPhase = "intake" epic_dir: str | None = None + project_dir: str = "" start_event: asyncio.Event = field(default_factory=asyncio.Event) agents: dict[str, AgentState] = field(default_factory=dict) projection_store: ProjectionStore = field(default_factory=ProjectionStore) diff --git a/koan/subagent.py b/koan/subagent.py index 56c62d4..c5f5905 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -76,6 +76,7 @@ def _build_phase_ctx(task: dict, subagent_dir: str) -> PhaseContext: return PhaseContext( epic_dir=task.get("epic_dir", ""), subagent_dir=subagent_dir, + project_dir=task.get("project_dir", ""), phase_instructions=task.get("instructions") or task.get("phase_instructions") or task.get("task"), story_id=task.get("story_id"), step_sequence=task.get("step_sequence"), diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 440dfe1..6906d37 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -216,6 +216,7 @@ async def koan_request_scouts(questions: list[dict] | None = None) -> str: "label": scout_id, "epic_dir": epic_dir, "subagent_dir": subagent_dir, + "project_dir": _app_state.project_dir, "question": q.get("prompt", ""), "investigator_role": q.get("role", "investigator"), }) From 83de05e18d67ea7324a597d31739cfd47e78bff7 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 19:03:58 +0700 Subject: [PATCH 284/412] refactor: inline task description into intake prompt, remove conversation.jsonl MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit conversation.jsonl was a vestige from a previous iteration -- it wrapped the user's textarea input in JSONL, wrote it to a file, then told the intake LLM to read and parse it. The task description is now passed directly through AppState → task dict → PhaseContext and inlined in the step 1 guidance prompt. Also threads project_dir and task_description through the driver's run_phase task dict so all phases (not just scouts) have access. --- koan/driver.py | 2 ++ koan/phases/__init__.py | 1 + koan/phases/intake.py | 64 ++++++++++++++++++++++------------------- koan/state.py | 1 + koan/subagent.py | 1 + koan/web/app.py | 8 +----- 6 files changed, 41 insertions(+), 36 deletions(-) diff --git a/koan/driver.py b/koan/driver.py index 799646b..7e92163 100644 --- a/koan/driver.py +++ b/koan/driver.py @@ -449,6 +449,8 @@ async def run_phase( "role": role, "epic_dir": epic_dir, "subagent_dir": subagent_dir, + "project_dir": app_state.project_dir, + "task_description": app_state.task_description, "instructions": instructions, } diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index 8aee4a4..63cc4b8 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -22,6 +22,7 @@ class PhaseContext: epic_dir: str subagent_dir: str project_dir: str = "" + task_description: str = "" phase_instructions: str | None = None intake_confidence: str | None = None intake_iteration: int = 0 diff --git a/koan/phases/intake.py b/koan/phases/intake.py index cfaf883..2be8792 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -1,6 +1,6 @@ # Intake phase -- 3-step workflow. # -# Step 1 (Gather) -- read conversation, explore obvious files, dispatch scouts +# Step 1 (Gather) -- read task description, explore obvious files, dispatch scouts # Step 2 (Evaluate) -- process scout results, verify, ask questions # Step 3 (Write) -- write landscape.md, present for user review # @@ -21,8 +21,8 @@ } SYSTEM_PROMPT = ( - "You are an intake analyst for a coding task planner. You read a conversation" - " history, explore the codebase, and ask the user targeted questions until you" + "You are an intake analyst for a coding task planner. You read a task" + " description, explore the codebase, and ask the user targeted questions until you" " have complete context for planning.\n" "\n" "Your output -- a single landscape.md file -- is the sole foundation for all" @@ -43,7 +43,7 @@ "\n" "## Strict rules\n" "\n" - "- MUST NOT infer decisions not explicitly stated in the conversation.\n" + "- MUST NOT infer decisions not explicitly stated in the task description.\n" "- MUST NOT add architectural opinions or suggest approaches.\n" "- MUST NOT produce implementation recommendations.\n" "- MUST NOT define deliverables, work units, or scope boundaries -- that" @@ -91,8 +91,8 @@ " correct. Since the user is describing the desired behavior and the code\n" " shows the current behavior, this is likely a change they want to make. I\n" " should note this as an existing gap and ask the user to confirm.\"\n" - " RIGHT: \"[!!] conversation: pipeline runs hourly <-> scout: scheduler.py cron = daily@midnight\n" - " conversation = desired vs code = current therefore likely a requested change -> ASK user to confirm\"\n" + " RIGHT: \"[!!] task description: pipeline runs hourly <-> scout: scheduler.py cron = daily@midnight\n" + " task description = desired vs code = current therefore likely a requested change -> ASK user to confirm\"\n" "\n" "Classifying unknowns:\n" " WRONG: \"Looking at what I've gathered so far, I think I have a good\n" @@ -108,7 +108,7 @@ "\n" "## Workflow\n" "\n" - "You work in three steps: gather context (conversation + codebase + scouts)," + "You work in three steps: gather context (task description + codebase + scouts)," " evaluate findings and ask questions, then write landscape.md.\n" "\n" "## Output\n" @@ -117,7 +117,7 @@ "\n" "## Tools\n" "\n" - "- Read tools (read, bash, grep, glob, find, ls) -- reading the conversation and codebase.\n" + "- Read tools (read, bash, grep, glob, find, ls) -- reading the codebase.\n" "- `koan_request_scouts` -- request parallel codebase exploration.\n" "- `koan_ask_question` -- ask the user clarifying questions.\n" "- `koan_review_artifact` -- present landscape.md for user review (final step only).\n" @@ -132,19 +132,20 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: if step == 1: - conversation_path = f"{ctx.epic_dir}/conversation.jsonl" + project_dir = ctx.project_dir or "" lines = [ - "Read the conversation, orient yourself in the codebase, and dispatch scouts.", + "Read the task description, orient yourself in the codebase, and dispatch scouts.", "", - "## 1. Read the conversation", + "## 1. Task description", "", - f"Conversation file: {conversation_path}", - "", - "The file is JSONL. Each line is a JSON object.", - "Read entries with type 'message' and role 'user' or 'assistant'.", - "Ignore internal entries (header, compaction, etc.).", + ] + if ctx.task_description: + lines.append(f"<task_description>\n{ctx.task_description}\n</task_description>") + else: + lines.append("(No task description provided.)") + lines.extend([ "", - "As you read, track:", + "As you read the task, track:", "- **Topic**: What is being built or changed?", "- **File references**: Every file, directory, or module mentioned.", "- **Decisions already made**: Only those explicitly stated and agreed upon.", @@ -156,27 +157,32 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "## 2. Quick orientation -- open obvious files", "", + ]) + if project_dir: + lines.append(f"Project root: `{project_dir}`") + lines.append("") + lines.extend([ "Open up to **5 files** that any investigation would start from:", "", "- `ls` the project root.", "- Open root-level orientation files if they exist: README.md, AGENTS.md, CLAUDE.md.", - "- Open any file the conversation explicitly referenced -- skim structure,", + "- Open any file the task description explicitly referenced -- skim structure,", " exports, key patterns (first 50-100 lines is enough).", - "- If the conversation mentions a module by name without a path, one", + "- If the task description mentions a module by name without a path, one", " `find` or `ls` to locate it, then open the entry point.", "", "Budget: 5 file reads max. This is orientation, not investigation.", "Just enough to write scout prompts that reference actual function names,", - "actual patterns, and actual file paths instead of conversation labels.", + "actual patterns, and actual file paths instead of vague labels.", "", "## 3. Plan and dispatch scouts", "", - "Using the conversation and what you observed in the files, identify the", + "Using the task description and what you observed in the files, identify the", "concerns that need investigation. Consider both:", "", - "- What the conversation explicitly references (files, modules, integration", + "- What the task description explicitly references (files, modules, integration", " points, assumptions that need verification, project conventions).", - "- What the conversation did NOT mention but could matter (hidden callers,", + "- What the task description did NOT mention but could matter (hidden callers,", " related subsystems, prior art, invariants, test coverage).", "", "Group related concerns into **3-5 clusters**. Each cluster becomes one", @@ -205,7 +211,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: " check whether session storage uses Redis or in-memory, and note any", " TODO or FIXME comments related to auth. Report the permission model", " (RBAC, ACL, or ad-hoc checks) and how it integrates with the router.'", - ] + ]) if ctx.phase_instructions: lines.extend(["", "## Additional Context from Workflow Orchestrator", "", ctx.phase_instructions]) return StepGuidance(title=STEP_NAMES[1], instructions=lines) @@ -221,7 +227,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "When scouts return, analyze each report:", "- Does the finding answer the questions you asked?", "- Does it reveal anything unexpected about the codebase?", - "- Does it conflict with what the conversation stated?", + "- Does it conflict with what the task description stated?", "", "## 2. Verify -- read files to confirm", "", @@ -232,7 +238,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "- Integration points the scout identified", "- Patterns or conventions the scout claims to have found", - "- Anything that conflicts with what the conversation stated", + "- Anything that conflicts with what the task description stated", "", "## 3. Enumerate what you know and what you don't", "", @@ -240,9 +246,9 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "Use this structure for each area:", "", " **[Area name]** (e.g., 'Authentication', 'Database schema', 'API endpoints')", - " - Known: [what the conversation and/or scouts established]", + " - Known: [what the task description and/or scouts established]", " - Unknown: [what remains unclear or unverified]", - " - Source: [conversation / scout findings]", + " - Source: [task description / scout findings]", "", "Cover every area relevant to the task. Be thorough -- gaps you miss here", "become gaps in the final output.", @@ -379,7 +385,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "If no questions were needed: (no questions were needed -- context was sufficient)", "", "### Constraints", - "All constraints discovered: from conversation, codebase, user answers.", + "All constraints discovered: from task description, codebase, user answers.", "If none: (none identified)", "", "### Open Items", diff --git a/koan/state.py b/koan/state.py index 999506a..5496e86 100644 --- a/koan/state.py +++ b/koan/state.py @@ -54,6 +54,7 @@ class AppState: phase: EpicPhase = "intake" epic_dir: str | None = None project_dir: str = "" + task_description: str = "" start_event: asyncio.Event = field(default_factory=asyncio.Event) agents: dict[str, AgentState] = field(default_factory=dict) projection_store: ProjectionStore = field(default_factory=ProjectionStore) diff --git a/koan/subagent.py b/koan/subagent.py index c5f5905..e916319 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -77,6 +77,7 @@ def _build_phase_ctx(task: dict, subagent_dir: str) -> PhaseContext: epic_dir=task.get("epic_dir", ""), subagent_dir=subagent_dir, project_dir=task.get("project_dir", ""), + task_description=task.get("task_description", ""), phase_instructions=task.get("instructions") or task.get("phase_instructions") or task.get("task"), story_id=task.get("story_id"), step_sequence=task.get("step_sequence"), diff --git a/koan/web/app.py b/koan/web/app.py index 7155285..b98eef8 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -324,13 +324,7 @@ async def api_start_run(r: Request) -> Response: {"task": task, "created_at": time.time()}, ) - # Write conversation.jsonl so the intake phase can read it - import aiofiles as _aiofiles - conv_line = json.dumps({"type": "message", "role": "user", "content": task}) - conv_path = epic_dir / "conversation.jsonl" - async with _aiofiles.open(conv_path, "w") as _f: - await _f.write(conv_line + "\n") - + st.task_description = task st.epic_dir = str(epic_dir) st.start_event.set() From b04fac2be1dba31ddcab6a88b2480738cb787d90 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 19:13:05 +0700 Subject: [PATCH 285/412] fix: deliver SYSTEM_PROMPT to subagent processes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SYSTEM_PROMPT was defined in every phase module but never passed to the CLI process — it was dead code. Scouts (and all other agents) ran with only a one-sentence boot prompt and no role identity. Add system_prompt parameter to the Runner.build_command protocol. Claude uses --system-prompt; Codex and Gemini prepend it to the boot prompt. spawn_subagent reads phase_module.SYSTEM_PROMPT and passes it through. --- koan/runners/base.py | 1 + koan/runners/claude.py | 3 +++ koan/runners/codex.py | 4 +++- koan/runners/gemini.py | 4 +++- koan/subagent.py | 5 ++++- 5 files changed, 14 insertions(+), 3 deletions(-) diff --git a/koan/runners/base.py b/koan/runners/base.py index a6ca90f..0527772 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -45,6 +45,7 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, + system_prompt: str = "", ) -> list[str]: ... def list_models(self, binary: str) -> list[ModelInfo]: ... diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 2fa1140..200f796 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -102,6 +102,7 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, + system_prompt: str = "", ) -> list[str]: if thinking not in self.supported_thinking_modes: raise RunnerError(RunnerDiagnostic( @@ -135,6 +136,8 @@ def build_command( "--include-partial-messages", "--mcp-config", str(config_path), ] + if system_prompt: + cmd.extend(["--system-prompt", system_prompt]) if thinking != "disabled": cmd.extend(["--effort", _EFFORT_MAP[thinking]]) cmd.extend(["--model", model]) diff --git a/koan/runners/codex.py b/koan/runners/codex.py index 632a61a..9f49620 100644 --- a/koan/runners/codex.py +++ b/koan/runners/codex.py @@ -68,6 +68,7 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, + system_prompt: str = "", ) -> list[str]: if thinking != "disabled": raise RunnerError(RunnerDiagnostic( @@ -77,10 +78,11 @@ def build_command( message=f"Thinking mode '{thinking}' is not supported by codex", )) + prompt = f"{system_prompt}\n\n{boot_prompt}" if system_prompt else boot_prompt cmd = [ installation.binary, "exec", "--json", "-c", f"mcp_servers.koan.url={mcp_url}", - boot_prompt, + prompt, ] cmd.extend(["--model", model]) cmd.extend(installation.extra_args) diff --git a/koan/runners/gemini.py b/koan/runners/gemini.py index f58e938..081576e 100644 --- a/koan/runners/gemini.py +++ b/koan/runners/gemini.py @@ -71,6 +71,7 @@ def build_command( installation: AgentInstallation, model: str, thinking: ThinkingMode, + system_prompt: str = "", ) -> list[str]: if thinking not in self.supported_thinking_modes: raise RunnerError(RunnerDiagnostic( @@ -87,7 +88,8 @@ def build_command( self._merge_mcp(existing, mcp_url, settings_path) self._write_settings(existing, settings_path, gemini_dir) - cmd = [installation.binary, "--output-format", "stream-json", "-p", boot_prompt] + prompt = f"{system_prompt}\n\n{boot_prompt}" if system_prompt else boot_prompt + cmd = [installation.binary, "--output-format", "stream-json", "-p", prompt] if thinking != "disabled": cmd.extend(["--thinking-mode", thinking]) cmd.extend(["--model", model]) diff --git a/koan/subagent.py b/koan/subagent.py index e916319..fc09bd3 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -179,13 +179,16 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None # Build command before emitting agent_spawned -- if build_command fails, no # agent_spawned event is emitted (per plan: "the agent was never launched"). + system_prompt = getattr(phase_module, "SYSTEM_PROMPT", "") or "" try: if installation is not None and thinking_mode is not None: cmd = runner.build_command( boot_prompt(role), mcp_url, installation, model, thinking_mode, + system_prompt=system_prompt, ) else: - cmd = runner.build_command(boot_prompt(role), mcp_url, model) + cmd = runner.build_command(boot_prompt(role), mcp_url, model, + system_prompt=system_prompt) except RunnerError as e: await event_log.emit_runner_diagnostic(e.diagnostic) store.push_event( From db1dac214d0cfde669f53228c9a44567410db6bd Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 19:18:50 +0700 Subject: [PATCH 286/412] feat: support free-form text input in question UI Three changes: 1. Questions with no options (or free_text=true) now render a textarea instead of crashing or showing an empty option list. This lets the LLM ask open-ended questions. 2. Fix otherText bug: when a user selected 'Other' and typed custom text, the literal string '__other__' was submitted instead of what they typed. resolveOtherText() now substitutes the sentinel with actual input before submission. 3. collectDefaults() no longer crashes on questions without options. --- .../src/components/interactions/AskWizard.tsx | 138 +++++++++++++----- frontend/src/store/index.ts | 1 + frontend/src/styles/components.css | 29 ++++ 3 files changed, 130 insertions(+), 38 deletions(-) diff --git a/frontend/src/components/interactions/AskWizard.tsx b/frontend/src/components/interactions/AskWizard.tsx index cd4eef0..ade0369 100644 --- a/frontend/src/components/interactions/AskWizard.tsx +++ b/frontend/src/components/interactions/AskWizard.tsx @@ -18,14 +18,28 @@ function normalizeOptions( }) } +/** True when the question should render as a free-form text input. */ +function isFreeText(q: AskQuestion): boolean { + return q.free_text === true || !q.options || q.options.length === 0 +} + interface AnswerMap { [qIdx: number]: string | string[] | null } +/** Map from question index to the "Other" free-text typed by the user. */ +interface OtherTextMap { + [qIdx: number]: string +} + function collectDefaults(questions: AskQuestion[]): AnswerMap { const defaults: AnswerMap = {} questions.forEach((q, i) => { - const recommended = q.options.filter(o => o.recommended).map(o => o.value) + if (isFreeText(q)) { + defaults[i] = null + return + } + const recommended = (q.options ?? []).filter(o => o.recommended).map(o => o.value) defaults[i] = q.multi ? recommended : (recommended[0] ?? null) }) return defaults @@ -35,14 +49,17 @@ function QuestionCard({ question, qIdx, answer, + otherText, onAnswer, + onOtherText, }: { question: AskQuestion qIdx: number answer: string | string[] | null + otherText: string onAnswer: (qIdx: number, val: string | string[] | null) => void + onOtherText: (qIdx: number, text: string) => void }) { - const [otherText, setOtherText] = useState('') const selected = Array.isArray(answer) ? answer : answer ? [answer] : [] const toggle = (value: string) => { @@ -79,51 +96,90 @@ function QuestionCard({ <div className="question-context"><Md>{question.context}</Md></div> )} <div className="question-text"><Md>{question.question}</Md></div> - {question.multi && ( - <div className="question-multi-hint">Select all that apply</div> - )} - <div className="options-list"> - {opts.map(opt => ( - <div - key={opt.value} - className={`option${selected.includes(opt.value) ? ' selected' : ''}${opt.recommended ? ' recommended' : ''}`} - onClick={() => toggle(opt.value)} - > - <span className={question.multi ? 'checkbox-dot' : 'radio-dot'} /> - <span className="option-text">{opt.label}</span> - {opt.recommended && ( - <span className="recommended-badge">recommended</span> - )} - </div> - ))} - {question.allow_other && ( - <div - className={`option option-other${selected.includes('__other__') ? ' selected' : ''}`} - onClick={() => toggle('__other__')} - > - <span className={question.multi ? 'checkbox-dot' : 'radio-dot'} /> - <span className="option-text">Other (type your own)</span> - {selected.includes('__other__') && ( - <input - type="text" - className="other-input visible" - placeholder="Type here..." - value={otherText} - onChange={e => setOtherText(e.target.value)} - onClick={e => e.stopPropagation()} - /> + + {isFreeText(question) ? ( + /* Free-form text input — no predefined options */ + <div className="free-text-area"> + <textarea + className="free-text-input" + rows={4} + placeholder="Type your answer..." + value={typeof answer === 'string' ? answer : ''} + onChange={e => onAnswer(qIdx, e.target.value || null)} + /> + </div> + ) : ( + /* Standard option selection */ + <> + {question.multi && ( + <div className="question-multi-hint">Select all that apply</div> + )} + <div className="options-list"> + {opts.map(opt => ( + <div + key={opt.value} + className={`option${selected.includes(opt.value) ? ' selected' : ''}${opt.recommended ? ' recommended' : ''}`} + onClick={() => toggle(opt.value)} + > + <span className={question.multi ? 'checkbox-dot' : 'radio-dot'} /> + <span className="option-text">{opt.label}</span> + {opt.recommended && ( + <span className="recommended-badge">recommended</span> + )} + </div> + ))} + {question.allow_other && ( + <div + className={`option option-other${selected.includes('__other__') ? ' selected' : ''}`} + onClick={() => toggle('__other__')} + > + <span className={question.multi ? 'checkbox-dot' : 'radio-dot'} /> + <span className="option-text">Other (type your own)</span> + {selected.includes('__other__') && ( + <input + type="text" + className="other-input visible" + placeholder="Type here..." + value={otherText} + onChange={e => onOtherText(qIdx, e.target.value)} + onClick={e => e.stopPropagation()} + /> + )} + </div> )} </div> - )} - </div> + </> + )} </div> ) } +/** + * Resolve __other__ sentinels in the answer map with actual typed text. + * For single-select: "__other__" → the typed string. + * For multi-select: ["a", "__other__"] → ["a", "the typed string"]. + */ +function resolveOtherText( + answers: AnswerMap, + otherTexts: OtherTextMap, + questions: AskQuestion[], +): (string | string[] | null)[] { + return questions.map((_, i) => { + const raw = answers[i] ?? null + const typed = otherTexts[i] || '' + if (raw === '__other__') return typed || null + if (Array.isArray(raw)) { + return raw.map(v => (v === '__other__' ? typed : v)) + } + return raw + }) +} + export function AskWizard() { const focus = useStore(s => s.run?.focus) const [currentIdx, setCurrentIdx] = useState(0) const [answers, setAnswers] = useState<AnswerMap>({}) + const [otherTexts, setOtherTexts] = useState<OtherTextMap>({}) const [submitError, setSubmitError] = useState<string | null>(null) if (!focus || focus.type !== 'question') return null @@ -135,6 +191,10 @@ export function AskWizard() { setAnswers(prev => ({ ...prev, [qIdx]: val })) } + const handleOtherText = (qIdx: number, text: string) => { + setOtherTexts(prev => ({ ...prev, [qIdx]: text })) + } + const handleNext = () => { if (currentIdx < total - 1) setCurrentIdx(i => i + 1) } @@ -144,7 +204,7 @@ export function AskWizard() { } const handleSubmit = async () => { - const finalAnswers = questions.map((_, i) => answers[i] ?? null) + const finalAnswers = resolveOtherText(answers, otherTexts, questions) const res = await api.submitAnswer(finalAnswers, token) if (!res.ok) { setSubmitError(res.message ?? 'Failed to submit answers') @@ -172,7 +232,9 @@ export function AskWizard() { question={questions[currentIdx]} qIdx={currentIdx} answer={answers[currentIdx] ?? null} + otherText={otherTexts[currentIdx] ?? ''} onAnswer={handleAnswer} + onOtherText={handleOtherText} /> {submitError && <div className="no-runners-msg">{submitError}</div>} diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 837ac53..da06e4f 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -87,6 +87,7 @@ export interface AskQuestion { options: { value: string; label: string; recommended?: boolean }[] allow_other?: boolean // snake_case: comes from LLM via backend list[dict] context?: string + free_text?: boolean // when true (or when options is empty), render a textarea instead of options } export interface ChatTurn { diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index d76c6b9..d882ca2 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -459,6 +459,35 @@ animation: slide-open 150ms ease-out; } +/* Free-form text input (questions with no predefined options) */ +.free-text-area { + margin-top: var(--space-3); +} + +.free-text-input { + width: 100%; + min-height: 100px; + padding: var(--space-3); + background: var(--bg); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + color: var(--text); + font-family: var(--font-sans); + font-size: var(--font-size-md); + line-height: 1.5; + resize: vertical; + outline: none; + box-sizing: border-box; +} + +.free-text-input::placeholder { + color: var(--text-muted); +} + +.free-text-input:focus { + border-color: var(--copper); +} + /* ---- Config sections ---- */ .model-config-section { margin-top: var(--space-6); From b222e7e2db25adbf1e2ac02aa2904a4c33579c17 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 20:07:58 +0700 Subject: [PATCH 287/412] fix: always show 'Other' text input on every question MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The LLM was including an 'Other' option as a regular choice in the options array, so selecting it just stored the string 'Other' with no way to type a custom answer. - Always render an 'Other (type your own)' option at the bottom of every question that has predefined options. Selecting it reveals a textarea for free-form input. - Filter out any LLM-provided 'Other' option to avoid duplicates. - No longer gated on allow_other — the user can always provide a custom answer. --- .../src/components/interactions/AskWizard.tsx | 39 +++++++++---------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/frontend/src/components/interactions/AskWizard.tsx b/frontend/src/components/interactions/AskWizard.tsx index ade0369..4e12725 100644 --- a/frontend/src/components/interactions/AskWizard.tsx +++ b/frontend/src/components/interactions/AskWizard.tsx @@ -84,8 +84,10 @@ function QuestionCard({ } } - // Normalize options at render time to handle LLM output variability + // Normalize options at render time to handle LLM output variability. + // Filter out any LLM-provided "Other" option — we always render our own. const opts = normalizeOptions(question.options as (string | Record<string, unknown>)[]) + .filter(o => !/^other$/i.test(o.value.trim()) && !/^other$/i.test(o.label.trim())) return ( <div className="question-card"> @@ -109,7 +111,7 @@ function QuestionCard({ /> </div> ) : ( - /* Standard option selection */ + /* Standard option selection — always includes an "Other" text input */ <> {question.multi && ( <div className="question-multi-hint">Select all that apply</div> @@ -128,24 +130,21 @@ function QuestionCard({ )} </div> ))} - {question.allow_other && ( - <div - className={`option option-other${selected.includes('__other__') ? ' selected' : ''}`} - onClick={() => toggle('__other__')} - > - <span className={question.multi ? 'checkbox-dot' : 'radio-dot'} /> - <span className="option-text">Other (type your own)</span> - {selected.includes('__other__') && ( - <input - type="text" - className="other-input visible" - placeholder="Type here..." - value={otherText} - onChange={e => onOtherText(qIdx, e.target.value)} - onClick={e => e.stopPropagation()} - /> - )} - </div> + <div + className={`option option-other${selected.includes('__other__') ? ' selected' : ''}`} + onClick={() => toggle('__other__')} + > + <span className={question.multi ? 'checkbox-dot' : 'radio-dot'} /> + <span className="option-text">Other (type your own)</span> + </div> + {selected.includes('__other__') && ( + <textarea + className="free-text-input" + rows={3} + placeholder="Type your answer..." + value={otherText} + onChange={e => onOtherText(qIdx, e.target.value)} + /> )} </div> </> From 52f07fd3608bdbaf777d92ef0b7d67c459a0b79d Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 20:24:18 +0700 Subject: [PATCH 288/412] fix: spawn all agents with cwd=project_dir Agents were spawned with cwd=subagent_dir (~/.koan/epics/.../subagents/...) which meant find, ls, grep etc. started from an internal bookkeeping directory instead of the user's codebase. This caused scouts to scan broadly (home folder, /tmp) since their pwd was meaningless. Now spawn_subagent uses project_dir from the task dict as the working directory, falling back to subagent_dir if unavailable. project_dir is validated at startup to be an existing directory. --- koan/__main__.py | 6 +++++- koan/subagent.py | 9 ++++++--- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/koan/__main__.py b/koan/__main__.py index 5c8a01a..856b129 100644 --- a/koan/__main__.py +++ b/koan/__main__.py @@ -98,10 +98,14 @@ def main() -> None: port = args.port if args.port is not None else _find_free_port() + project_dir = Path.cwd() + if not project_dir.is_dir(): + sys.exit(f"koan: project directory does not exist: {project_dir}") + config = asyncio.run(load_koan_config()) app_state = AppState(config=config, port=port, open_browser=not args.no_open, initial_prompt=args.prompt, yolo=args.yolo, debug=args.debug, - project_dir=str(Path.cwd())) + project_dir=str(project_dir)) app = create_app(app_state) host = "127.0.0.1" diff --git a/koan/subagent.py b/koan/subagent.py index fc09bd3..c5c50db 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -202,13 +202,16 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None # Emit agent_spawned only after build_command succeeds -- process is about to start store.push_event("agent_spawned", build_agent_spawned(agent), agent_id=agent_id) - # Spawn process - log.info("spawning %s (agent_id=%s): %s", role, agent_id, " ".join(cmd)) + # Spawn process — cwd is the project directory so that tools like + # `find .`, `ls`, `grep -r` naturally scope to the user's codebase. + # Falls back to subagent_dir if project_dir is unavailable. + spawn_cwd = task.get("project_dir") or subagent_dir + log.info("spawning %s (agent_id=%s) cwd=%s: %s", role, agent_id, spawn_cwd, " ".join(cmd)) proc = await asyncio.create_subprocess_exec( *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, - cwd=subagent_dir, + cwd=spawn_cwd, ) app_state._active_processes[agent_id] = proc From f780c838cd9fb544155e35d77b5ceb98772b7563 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 20:30:54 +0700 Subject: [PATCH 289/412] =?UTF-8?q?fix:=20show=20'Starting=20agent?= =?UTF-8?q?=E2=80=A6'=20indicator=20while=20activity=20feed=20is=20empty?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When a run starts, the main content area was blank until the first agent event arrived. Now shows a pulsing 'Starting agent…' indicator that disappears as soon as the first activity entry or thinking state appears. --- frontend/src/components/ActivityFeed.tsx | 9 +++++++++ frontend/src/styles/components.css | 10 ++++++++++ 2 files changed, 19 insertions(+) diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index 92c5733..97174eb 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -140,9 +140,18 @@ export function ActivityFeed() { const scrollRef = useRef<HTMLDivElement>(null) useAutoScroll(scrollRef) + const hasEntries = conversation?.entries && conversation.entries.length > 0 + const isWaiting = !hasEntries && !conversation?.isThinking && !conversation?.pendingText + return ( <div className="activity-feed-scroll" ref={scrollRef}> <div id="activity-feed-inner" className="activity-feed-inner"> + {isWaiting && ( + <div className="activity-waiting"> + <span className="thinking-dot">●</span> + <span>Starting agent…</span> + </div> + )} {conversation?.entries.map(renderEntry)} {/* Active thinking card — shown while LLM is reasoning */} diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index d882ca2..b280555 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -1353,6 +1353,16 @@ to { opacity: 0; transform: translateY(8px); } } +/* Waiting / starting indicator */ +.activity-waiting { + display: flex; + align-items: center; + gap: var(--space-2); + padding: var(--space-4); + color: var(--text-muted); + font-size: var(--font-size-md); +} + /* Thinking indicator */ @keyframes thinking-pulse { 0%, 100% { opacity: 0.3; } From 53053c6d089c70930acd62386511fa57c9606c55 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 2 Apr 2026 20:57:57 +0700 Subject: [PATCH 290/412] fix: prevent LLM from sending letter-prefixed and 'Other' options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three-layer fix applied via prompt engineering (ACI Design pattern): 1. Tool docstring: koan_ask_question now has a detailed docstring with schema, format rules, and WRONG/RIGHT examples. The LLM sees this as the tool description in MCP and knows not to prefix options with (a)/(b) or include 'Other'. 2. Step guidance: intake step 2 'Ask questions' section now explicitly states the formatting rules — no letter prefixes, no meta-options, rationale goes in context field not labels. 3. Frontend defense: options are stripped of letter prefixes ((a), A:, etc.) and meta-options (Other, None of the above, N/A, etc.) are filtered out since the UI always provides its own free-text input. --- .../src/components/interactions/AskWizard.tsx | 10 ++++++-- koan/phases/intake.py | 12 +++++++--- koan/web/mcp_endpoint.py | 24 +++++++++++++++++++ 3 files changed, 41 insertions(+), 5 deletions(-) diff --git a/frontend/src/components/interactions/AskWizard.tsx b/frontend/src/components/interactions/AskWizard.tsx index 4e12725..ae1f76b 100644 --- a/frontend/src/components/interactions/AskWizard.tsx +++ b/frontend/src/components/interactions/AskWizard.tsx @@ -85,9 +85,15 @@ function QuestionCard({ } // Normalize options at render time to handle LLM output variability. - // Filter out any LLM-provided "Other" option — we always render our own. + // Filter out any LLM-provided "Other" / meta-options — we always render our own. + const isMetaOption = (s: string): boolean => + /^\(?[a-z]\)?\s*[.:\-)]?\s*/i.test(s) // strip letter prefixes like "(a) ", "A: " + ? isMetaOption(s.replace(/^\(?[a-z]\)?\s*[.:\-)]?\s*/i, '')) + : /^(other|none of the above|something else|other approach|other option|custom|n\/a)$/i.test(s.trim()) + const stripPrefix = (s: string) => s.replace(/^\(?[a-z]\)?\s*[.:\-)]?\s*/i, '').trim() const opts = normalizeOptions(question.options as (string | Record<string, unknown>)[]) - .filter(o => !/^other$/i.test(o.value.trim()) && !/^other$/i.test(o.label.trim())) + .filter(o => !isMetaOption(o.label)) + .map(o => ({ ...o, label: stripPrefix(o.label), value: stripPrefix(o.value) || o.value })) return ( <div className="question-card"> diff --git a/koan/phases/intake.py b/koan/phases/intake.py index 2be8792..60088f6 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -288,9 +288,15 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "Call `koan_ask_question` once with all your questions in the `questions` array.", "The user sees them one at a time. Aim for 3-5 questions.", - "Prefer multiple-choice when the answer space is bounded.", - "Include the optional context field when background is needed for an informed decision.", - "Ground questions in specific findings: 'Scout found X -- should this story follow the same pattern?'", + "", + "Formatting rules:", + "- Prefer multiple-choice when the answer space is bounded.", + "- Option labels are plain text -- no letter prefixes like (a)/(b), no numbering.", + "- Do NOT include 'Other', 'None of the above', or similar meta-options.", + " The UI provides a free-text input automatically.", + "- Put background and rationale in the `context` field, not in the option labels.", + "- Ground questions in specific findings:", + " 'Scout found X -- should this story follow the same pattern?'", "", "## 6. Process answers and follow up", "", diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 6906d37..01b1ca9 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -257,6 +257,30 @@ async def run_scout(scout_task: dict) -> str | None: @mcp.tool(name="koan_ask_question") async def koan_ask_question(questions: list[dict] | None = None) -> str: + """Ask the user one or more clarifying questions. The UI renders these as + interactive cards — one per question — with radio buttons or checkboxes. + + Each dict in `questions` must have: + - question (str): The question text (rendered as markdown). + - options (list[dict]): Choices. Each option has: + - value (str): Machine key returned in the answer. + - label (str): Human-readable label shown in the UI. + - recommended (bool, optional): Pre-select this option. + + Optional fields: + - context (str): Background/rationale shown above the question (markdown). + - multi (bool): Allow selecting multiple options (default false). + + Format rules for options: + - Labels are plain descriptions. Do NOT prefix with letters, numbers, + or bullets — the UI adds its own selection controls. + WRONG: "(a) Stateless wrapper" / "A: Stateless wrapper" + RIGHT: "Stateless wrapper — compile per request, optimize later" + - Do NOT include an "Other" or "None of the above" option. + The UI always provides a free-text alternative automatically. + - Keep labels concise (one line). Put rationale in `context`, not + in the label. + """ agent = _get_agent() _check_or_raise(agent, "koan_ask_question", {"questions": questions}) From 7eca0cca6b02b68a1f81932411a5c538aaa2fe1a Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 13:15:09 +0700 Subject: [PATCH 291/412] chore: set log level to debug when --debug flag is provided --- koan/__main__.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/koan/__main__.py b/koan/__main__.py index 856b129..11a01bf 100644 --- a/koan/__main__.py +++ b/koan/__main__.py @@ -91,7 +91,8 @@ def main() -> None: help="Show step guidance prompts in the UI") args = parser.parse_args() - setup_logging(args.log_level) + log_level = "DEBUG" if args.debug else args.log_level + setup_logging(log_level) if not args.skip_build and _frontend_needs_rebuild(): _rebuild_frontend() @@ -111,7 +112,7 @@ def main() -> None: host = "127.0.0.1" # timeout_graceful_shutdown=0: don't wait for HTTP clients to disconnect. # Agent cleanup happens in the lifespan shutdown handler instead. - uvicorn.run(app, host=host, port=port, log_level=args.log_level.lower(), + uvicorn.run(app, host=host, port=port, log_level=log_level.lower(), timeout_graceful_shutdown=0) From a4f5b3bdafc750b42a00aee3fa307486ea3328e0 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 13:15:57 +0700 Subject: [PATCH 292/412] fix: freeze agent timer on completion Add completed_at_ms timestamp to the Agent model, set it in the agent_exited fold, and use it in the frontend AgentRow to show a frozen duration instead of a live-ticking timer for done/failed agents. --- frontend/src/components/AgentMonitor.tsx | 8 ++++++-- frontend/src/hooks/useElapsed.ts | 2 +- frontend/src/store/index.ts | 1 + koan/projections.py | 2 ++ 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/frontend/src/components/AgentMonitor.tsx b/frontend/src/components/AgentMonitor.tsx index 8ee9244..a5463ad 100644 --- a/frontend/src/components/AgentMonitor.tsx +++ b/frontend/src/components/AgentMonitor.tsx @@ -1,9 +1,13 @@ import { useMemo } from 'react' import { useStore, Agent } from '../store/index' -import { useElapsed } from '../hooks/useElapsed' +import { useElapsed, formatElapsed } from '../hooks/useElapsed' function AgentRow({ agent }: { agent: Agent }) { - const elapsed = useElapsed(agent.startedAtMs) + const liveElapsed = useElapsed(agent.startedAtMs) + // Freeze the timer for completed agents: show static duration instead of live tick + const elapsed = agent.completedAtMs + ? formatElapsed(agent.completedAtMs - agent.startedAtMs) + : liveElapsed const status = agent.status const statusIcon = status === 'running' ? '›' diff --git a/frontend/src/hooks/useElapsed.ts b/frontend/src/hooks/useElapsed.ts index 5fee46f..4327f28 100644 --- a/frontend/src/hooks/useElapsed.ts +++ b/frontend/src/hooks/useElapsed.ts @@ -1,6 +1,6 @@ import { useState, useEffect } from 'react' -function formatElapsed(ms: number): string { +export function formatElapsed(ms: number): string { const s = Math.floor(ms / 1000) const m = Math.floor(s / 60) return `${m}m ${String(s % 60).padStart(2, '0')}s` diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index da06e4f..3ab5698 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -73,6 +73,7 @@ export interface Agent { status: AgentStatus error: string | null startedAtMs: number + completedAtMs: number | null step: number stepName: string lastTool: string diff --git a/koan/projections.py b/koan/projections.py index dfe08c1..81b1401 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -248,6 +248,7 @@ class Agent(KoanBaseModel): status: Literal["queued", "running", "done", "failed"] = "queued" error: str | None = None started_at_ms: int = 0 + completed_at_ms: int | None = None # Progress — updated during execution, shown in agent monitor step: int = 0 @@ -569,6 +570,7 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: "status": status, "error": error, "conversation": new_conv, + "completed_at_ms": int(datetime.now(timezone.utc).timestamp() * 1000), }) new_agents = dict(projection.run.agents) new_agents[agent_id] = new_agent From a1f6f236cfdfc6a8cca3bc34f6bac8030eb8c7c3 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 13:16:21 +0700 Subject: [PATCH 293/412] feat: replace workflow orchestrator with persistent orchestrator Replace the multi-subagent driver loop with a single long-lived orchestrator process that drives the entire workflow. The orchestrator receives phase-specific role context via koan_complete_step and transitions between phases via koan_set_phase. Key changes: - Driver simplified to spawn one orchestrator and await its exit - koan_complete_step refactored with step helpers for phase handshake, within-phase advancement, and phase-boundary blocking - Add koan_set_phase tool for orchestrator-driven phase transitions - Add chat messaging (api/chat, user_message events, ChatInput component) - Add phase-aware permissions for orchestrator role - Add execution tools (koan_spawn_executor, story management) - Non-primary agents (scouts) exit cleanly instead of blocking at phase boundary - Remove workflow_orchestrator, DecisionFocus, PillStrip, and related interaction flows --- frontend/src/App.tsx | 7 +- frontend/src/api/client.ts | 14 +- frontend/src/components/ActivityFeed.tsx | 22 +- frontend/src/components/ChatInput.tsx | 54 ++ frontend/src/components/Header.tsx | 3 - frontend/src/components/PillStrip.tsx | 27 - frontend/src/components/StatusSidebar.tsx | 116 ++-- .../interactions/WorkflowDecision.tsx | 97 ---- frontend/src/store/index.ts | 13 +- frontend/src/styles/components.css | 48 -- frontend/src/styles/layout.css | 124 ++-- koan/driver.py | 506 +--------------- koan/epic_state.py | 10 - koan/events.py | 15 - koan/lib/permissions.py | 178 ++++-- koan/lib/phase_dag.py | 9 +- koan/phases/__init__.py | 50 +- koan/phases/format_step.py | 42 +- koan/phases/workflow_orchestrator.py | 129 ----- koan/projections.py | 68 ++- koan/runners/base.py | 8 +- koan/state.py | 20 +- koan/subagent.py | 29 +- koan/types.py | 10 - koan/web/app.py | 85 ++- koan/web/interactions.py | 9 +- koan/web/mcp_endpoint.py | 543 ++++++++++++++---- tests/test_driver.py | 80 +-- tests/test_interactions.py | 97 +--- tests/test_permissions.py | 170 ++++-- tests/test_phases.py | 38 -- tests/test_projections.py | 13 - tests/test_subagent.py | 8 +- tests/test_web_flows.py | 37 -- 34 files changed, 1190 insertions(+), 1489 deletions(-) create mode 100644 frontend/src/components/ChatInput.tsx delete mode 100644 frontend/src/components/PillStrip.tsx delete mode 100644 frontend/src/components/interactions/WorkflowDecision.tsx delete mode 100644 koan/phases/workflow_orchestrator.py diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 389cc82..0d433e2 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -10,15 +10,14 @@ import { ArtifactsSidebar } from './components/ArtifactsSidebar' import { Notification } from './components/Notification' import { SettingsOverlay } from './components/SettingsOverlay' import { Completion } from './components/Completion' +import { ChatInput } from './components/ChatInput' import { AskWizard } from './components/interactions/AskWizard' -import { WorkflowDecision } from './components/interactions/WorkflowDecision' import { ArtifactReview } from './components/interactions/ArtifactReview' function InteractionView() { const focus = useStore(s => s.run?.focus) if (!focus) return null if (focus.type === 'question') return <AskWizard /> - if (focus.type === 'decision') return <WorkflowDecision /> if (focus.type === 'review') return <ArtifactReview /> return null } @@ -26,8 +25,11 @@ function InteractionView() { function WorkspaceMain() { const focus = useStore(s => s.run?.focus) const completion = useStore(s => s.run?.completion) + const run = useStore(s => s.run) const hasInteraction = focus && focus.type !== 'conversation' + // Hide chat input during structured interactions to prevent confusion + const showChatInput = run !== null && !hasInteraction return ( <div className="workspace-main"> @@ -39,6 +41,7 @@ function WorkspaceMain() { <ActivityFeed /> )} <AgentMonitor /> + {showChatInput && <ChatInput />} </div> ) } diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 381cf9b..01bdb1b 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -71,16 +71,10 @@ export async function submitArtifactReview( }) } -export async function submitWorkflowDecision( - phase: string, - context: string, - token: string, -) { - return post<{ ok: boolean; message?: string }>('/api/workflow-decision', { - phase, - context, - token, - }) +// -- Chat -------------------------------------------------------------------- + +export async function sendChatMessage(message: string) { + return post<{ ok: boolean; error?: string }>('/api/chat', { message }) } // -- Probe ------------------------------------------------------------------- diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index 97174eb..42c7745 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -33,11 +33,11 @@ function ThinkingCard({ content }: { content: string }) { function StepHeader({ step, stepName, totalSteps }: { step: number; stepName: string; totalSteps: number | null }) { - const label = totalSteps ? `step ${step}/${totalSteps}` : `step ${step}` + const label = step === 0 ? stepName : (totalSteps ? `step ${step}/${totalSteps}` : `step ${step}`) return ( <div className="step-header"> <span className="step-header-label">{label}</span> - {stepName && <span className="step-header-name">{stepName}</span>} + {step > 0 && stepName && <span className="step-header-name">{stepName}</span>} </div> ) } @@ -68,6 +68,22 @@ function DebugGuidanceCard({ content }: { content: string }) { ) } +// -- User message bubble ------------------------------------------------------- + +function UserMessageBubble({ content, timestampMs }: { content: string; timestampMs: number }) { + const ts = new Date(timestampMs) + const timeStr = ts.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) + + return ( + <div className="user-message-bubble"> + <div className="user-message-content"> + <Md>{content}</Md> + </div> + <div className="user-message-time">{timeStr}</div> + </div> + ) +} + // -- Tool lines ---------------------------------------------------------------- function statusIcon(inFlight: boolean) { return inFlight ? '›' : '✓' } @@ -107,6 +123,8 @@ function renderEntry(entry: ConversationEntry, i: number) { return <StepHeader key={i} step={entry.step} stepName={entry.stepName} totalSteps={entry.totalSteps} /> case 'text': return <TextBlock key={i} text={entry.text} /> + case 'user_message': + return <UserMessageBubble key={i} content={entry.content} timestampMs={entry.timestampMs} /> case 'tool_read': { const detail = entry.lines ? `${entry.file}:${entry.lines}` : entry.file return <DetailLine key={i} tool="read" detail={detail} inFlight={entry.inFlight} /> diff --git a/frontend/src/components/ChatInput.tsx b/frontend/src/components/ChatInput.tsx new file mode 100644 index 0000000..0f08deb --- /dev/null +++ b/frontend/src/components/ChatInput.tsx @@ -0,0 +1,54 @@ +import { useState, KeyboardEvent } from 'react' +import { useStore } from '../store/index' +import { sendChatMessage } from '../api/client' + +export function ChatInput() { + const [text, setText] = useState('') + const [sending, setSending] = useState(false) + + const run = useStore(s => s.run) + const isDisabled = !run || run.completion !== null || sending + + async function handleSend() { + const msg = text.trim() + if (!msg || isDisabled) return + + setSending(true) + try { + await sendChatMessage(msg) + setText('') + } catch (e) { + // Silently ignore network errors; message may still be buffered + } finally { + setSending(false) + } + } + + function handleKeyDown(e: KeyboardEvent<HTMLTextAreaElement>) { + if (e.key === 'Enter' && !e.shiftKey) { + e.preventDefault() + handleSend() + } + } + + return ( + <div className="chat-input"> + <textarea + className="chat-input-textarea" + value={text} + onChange={e => setText(e.target.value)} + onKeyDown={handleKeyDown} + placeholder={isDisabled ? 'No active run' : 'Message the orchestrator… (Enter to send, Shift+Enter for newline)'} + disabled={isDisabled} + rows={2} + /> + <button + className="chat-input-send" + onClick={handleSend} + disabled={isDisabled || !text.trim()} + > + Send + </button> + </div> + ) +} diff --git a/frontend/src/components/Header.tsx b/frontend/src/components/Header.tsx index 6595a40..4efd41d 100644 --- a/frontend/src/components/Header.tsx +++ b/frontend/src/components/Header.tsx @@ -1,15 +1,12 @@ import { useStore } from '../store/index' -import { PillStrip } from './PillStrip' export function Header() { - const run = useStore(s => s.run) const setSettingsOpen = useStore(s => s.setSettingsOpen) return ( <header className="header"> <div className="header-left"> <span className="logo">koan</span> - {run && <PillStrip />} </div> <div className="header-right"> <button diff --git a/frontend/src/components/PillStrip.tsx b/frontend/src/components/PillStrip.tsx deleted file mode 100644 index 65d206a..0000000 --- a/frontend/src/components/PillStrip.tsx +++ /dev/null @@ -1,27 +0,0 @@ -import { useMemo } from 'react' -import { useStore, ALL_PHASES } from '../store/index' - -export function PillStrip() { - const phase = useStore(s => s.run?.phase ?? '') - - // Derive done phases locally — frontend-only computation from the phase string - const donePhases = useMemo(() => { - const idx = ALL_PHASES.indexOf(phase) - return idx === -1 ? [...ALL_PHASES] : ALL_PHASES.slice(0, idx) - }, [phase]) - - return ( - <div className="pill-strip"> - {ALL_PHASES.map(p => { - const isActive = p === phase - const isDone = donePhases.includes(p) - const cls = ['pill', isActive ? 'active' : isDone ? 'done' : ''].filter(Boolean).join(' ') - return ( - <span key={p} className={cls} data-phase={p}> - {p} - </span> - ) - })} - </div> - ) -} diff --git a/frontend/src/components/StatusSidebar.tsx b/frontend/src/components/StatusSidebar.tsx index b451658..745d868 100644 --- a/frontend/src/components/StatusSidebar.tsx +++ b/frontend/src/components/StatusSidebar.tsx @@ -1,60 +1,104 @@ import { useMemo } from 'react' import { useStore } from '../store/index' import { useElapsed } from '../hooks/useElapsed' -import { formatTokens } from '../utils' -function AgentSection() { - const agents = useStore(s => s.run?.agents) - const primary = useMemo( - () => agents ? Object.values(agents).find(a => a.isPrimary && a.status === 'running') : null, - [agents] - ) - const elapsed = useElapsed(primary?.startedAtMs ?? Date.now()) - - if (!primary) return null +function toTitleCase(phase: string): string { + return phase + .split('-') + .map(w => w.charAt(0).toUpperCase() + w.slice(1)) + .join(' ') +} - return ( - <> - <div className="sidebar-agent"> - <div className="sidebar-agent-role">{primary.role}</div> - <div className="sidebar-agent-model">{primary.model ?? '--'}</div> - <div className="sidebar-agent-step">{primary.stepName || `step ${primary.step}`}</div> - <div className="sidebar-agent-stats"> - <span>{formatTokens(primary.conversation.inputTokens, primary.conversation.outputTokens)}</span> - <span className="elapsed-value">{elapsed}</span> - </div> - </div> - <div className="sidebar-divider" /> - </> - ) +function fmt(n: number): string { + if (!n) return '--' + if (n < 1000) return String(n) + return (n / 1000).toFixed(1).replace(/\.0$/, '') + 'k' } export function StatusSidebar() { const phase = useStore(s => s.run?.phase ?? '') const agents = useStore(s => s.run?.agents) - const hasPrimary = useMemo( - () => agents ? Object.values(agents).some(a => a.isPrimary && a.status === 'running') : false, + + const primary = useMemo( + () => agents ? Object.values(agents).find(a => a.isPrimary && a.status === 'running') : null, [agents] ) - const hasContent = hasPrimary || phase + // Derive totalSteps from the last StepEntry in the conversation + const totalSteps = useMemo(() => { + if (!primary) return null + const entries = primary.conversation.entries + for (let i = entries.length - 1; i >= 0; i--) { + const e = entries[i] + if (e.type === 'step' && e.totalSteps != null) return e.totalSteps + } + return null + }, [primary]) + + const elapsed = useElapsed(primary?.startedAtMs ?? Date.now()) + + const barPct = (totalSteps && primary && primary.step > 0) + ? Math.min(100, (primary.step / totalSteps) * 100) + : 0 + + const hasContent = !!phase || !!primary + + if (!hasContent) { + return ( + <aside className="status-sidebar"> + <div className="sidebar-waiting">Waiting…</div> + </aside> + ) + } return ( <aside className="status-sidebar"> - <AgentSection /> - {phase && ( - <div className="sidebar-section"> - <div className="sidebar-label">Phase</div> - <div className="sidebar-value">{phase}</div> + <div className="sidebar-phase-section"> + <div className="sidebar-section-label">Phase</div> + <div className="sidebar-phase-name">{toTitleCase(phase)}</div> + + {primary && primary.step > 0 && ( + <div className="sidebar-step-block"> + <div className="sidebar-step-meta"> + <span>{primary.stepName || `step ${primary.step}`}</span> + {totalSteps != null && ( + <span>{primary.step} / {totalSteps}</span> + )} + </div> + {totalSteps != null && ( + <div className="sidebar-step-bar"> + <div className="sidebar-step-fill" style={{ width: `${barPct}%` }} /> + </div> + )} + </div> + )} </div> )} - {!hasContent && ( + {primary && ( <> - <div className="sidebar-heading">Status</div> - <div className="sidebar-value" style={{ color: 'var(--text-ghost)' }}> - Waiting... + <div className="sidebar-divider" /> + <div className="sidebar-agent-section"> + <div className="sidebar-section-label">Orchestrator</div> + <div className="sidebar-model-row"> + <span className="sidebar-model-dot" /> + <span className="sidebar-model-name">{primary.model ?? '--'}</span> + </div> + <div className="sidebar-metrics"> + <div className="sidebar-metric-row"> + <span>tokens in</span> + <span>{fmt(primary.conversation.inputTokens)}</span> + </div> + <div className="sidebar-metric-row"> + <span>tokens out</span> + <span>{fmt(primary.conversation.outputTokens)}</span> + </div> + <div className="sidebar-metric-row"> + <span>elapsed</span> + <span>{elapsed}</span> + </div> + </div> </div> </> )} diff --git a/frontend/src/components/interactions/WorkflowDecision.tsx b/frontend/src/components/interactions/WorkflowDecision.tsx deleted file mode 100644 index 9a1100d..0000000 --- a/frontend/src/components/interactions/WorkflowDecision.tsx +++ /dev/null @@ -1,97 +0,0 @@ -import { useState } from 'react' -import { useStore } from '../../store/index' -import * as api from '../../api/client' -import { Md } from '../Md' - -export function WorkflowDecision() { - const focus = useStore(s => s.run?.focus) - const [selectedPhase, setSelectedPhase] = useState<string | null>(null) - const [context, setContext] = useState('') - const [submitError, setSubmitError] = useState<string | null>(null) - - if (!focus || focus.type !== 'decision') return null - - const { chatTurns, token } = focus - - const handleContinue = async () => { - if (!selectedPhase) { - setSubmitError('Please select a phase before continuing') - return - } - const res = await api.submitWorkflowDecision(selectedPhase, context, token) - if (!res.ok) { - setSubmitError(res.message ?? 'Failed to submit decision') - } - } - - return ( - <div className="phase-content"> - <div className="phase-inner"> - <div className="workflow-chat"> - {chatTurns.map((turn, i) => ( - <div key={i} className="workflow-turn"> - {turn.role === 'orchestrator' ? ( - <> - <div className="workflow-turn-orchestrator"> - <div className="workflow-turn-header"> - <span className="workflow-turn-role">Orchestrator</span> - </div> - <div className="workflow-turn-body">{turn.status_report ? <Md>{turn.status_report}</Md> : null}</div> - </div> - {turn.recommended_phases && turn.recommended_phases.length > 0 && ( - <div className="workflow-options"> - {turn.recommended_phases.map(rp => ( - <button - key={rp.phase} - className={[ - 'workflow-option', - rp.recommended ? 'recommended' : '', - selectedPhase === rp.phase ? 'selected' : '', - ] - .filter(Boolean) - .join(' ')} - data-phase={rp.phase} - onClick={() => setSelectedPhase(rp.phase)} - > - <span className="workflow-option-label">{rp.phase}</span> - {rp.context && ( - <span className="workflow-option-context">{rp.context}</span> - )} - </button> - ))} - </div> - )} - </> - ) : ( - <div className="workflow-turn-user">{turn.message}</div> - )} - </div> - ))} - - <div className="workflow-chat-input"> - <textarea - className="workflow-feedback" - placeholder={ - selectedPhase - ? `Optional context for ${selectedPhase}...` - : 'Optional context for the chosen phase...' - } - value={context} - onChange={e => setContext(e.target.value)} - /> - {submitError && <div className="no-runners-msg">{submitError}</div>} - <div className="form-actions"> - <button - id="btn-workflow-continue" - className="btn btn-primary" - onClick={handleContinue} - > - Continue - </button> - </div> - </div> - </div> - </div> - </div> - ) -} diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 3ab5698..3966188 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -34,6 +34,7 @@ export interface RunConfig { export interface ThinkingEntry { type: 'thinking'; content: string } export interface TextEntry { type: 'text'; text: string } export interface StepEntry { type: 'step'; step: number; stepName: string; totalSteps: number | null } +export interface UserMessageEntry { type: 'user_message'; content: string; timestampMs: number } interface BaseToolEntry { callId: string; inFlight: boolean } export interface ToolReadEntry extends BaseToolEntry { type: 'tool_read'; file: string; lines: string } @@ -46,7 +47,7 @@ export interface ToolGenericEntry extends BaseToolEntry { type: 'tool_generic'; export interface DebugStepGuidanceEntry { type: 'debug_step_guidance'; content: string } export type ConversationEntry = - | ThinkingEntry | TextEntry | StepEntry + | ThinkingEntry | TextEntry | StepEntry | UserMessageEntry | ToolReadEntry | ToolWriteEntry | ToolEditEntry | ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry | DebugStepGuidanceEntry @@ -91,19 +92,11 @@ export interface AskQuestion { free_text?: boolean // when true (or when options is empty), render a textarea instead of options } -export interface ChatTurn { - role: 'orchestrator' | 'user' - status_report?: string // snake_case from backend list[dict] - recommended_phases?: { phase: string; context?: string; recommended?: boolean }[] - message?: string -} - export interface ConversationFocus { type: 'conversation'; agentId: string } export interface QuestionFocus { type: 'question'; agentId: string; token: string; questions: AskQuestion[] } export interface ReviewFocus { type: 'review'; agentId: string; token: string; path: string; description: string; content: string } -export interface DecisionFocus { type: 'decision'; agentId: string; token: string; chatTurns: ChatTurn[] } -export type Focus = ConversationFocus | QuestionFocus | ReviewFocus | DecisionFocus +export type Focus = ConversationFocus | QuestionFocus | ReviewFocus // -- Supporting types --------------------------------------------------------- diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index b280555..b060192 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -1,46 +1,3 @@ -/* ---- Pill strip ---- */ -.pill-strip { - display: flex; - border-radius: var(--radius-md); - overflow: hidden; - border: 1px solid var(--border); -} - -.pill { - font-family: var(--font-sans); - font-size: var(--font-size-sm); - padding: 6px 16px; - border-right: 1px solid var(--border); - color: var(--text-ghost); - background: var(--bg); - transition: background 150ms, color 150ms; - white-space: nowrap; -} - -.pill:last-child { - border-right: none; -} - -.pill.active { - background: var(--copper); - color: #fff; - border-color: var(--copper); -} - -.pill.done { - background: var(--green); - color: #fff; - border-color: var(--green); -} - -.pill.done::before { - content: "[OK] "; -} - -.pill.active::before { - content: ">> "; -} - /* ---- Badges ---- */ .badge { font-family: var(--font-mono); @@ -1338,11 +1295,6 @@ to { max-height: 80px; opacity: 1; } } -/* Pill state transitions */ -.pill { - transition: background 200ms ease, color 200ms ease, border-color 200ms ease; -} - /* Notification fade-out */ .notification.fade-out { animation: fade-out 300ms ease-in forwards; diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index c8d144d..054d05e 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -398,82 +398,112 @@ border-right: 1px solid var(--border); overflow-y: auto; padding: var(--space-4); + font-family: var(--font-mono); } -.sidebar-heading { - font-family: var(--font-mono); - font-size: 12px; - color: var(--text-muted); +.sidebar-waiting { + color: var(--text-ghost); + font-size: 11px; +} + +.sidebar-divider { + height: 1px; + background: var(--border); + margin: var(--space-4) 0; +} + +/* Phase section */ + +.sidebar-phase-section { + margin-bottom: var(--space-2); +} + +.sidebar-section-label { + font-size: 10px; + color: var(--text-ghost); text-transform: uppercase; letter-spacing: 0.08em; - margin-bottom: var(--space-4); + margin-bottom: 6px; } -.sidebar-section { - margin-bottom: var(--space-4); +.sidebar-phase-name { + font-size: 15px; + font-weight: 600; + color: var(--text-strong); + line-height: 1.2; } -.sidebar-label { - font-family: var(--font-mono); - font-size: 12px; - color: var(--text-muted); - text-transform: uppercase; - letter-spacing: 0.06em; - margin-bottom: var(--space-1); +.sidebar-step-block { + margin-top: 10px; } -/* Value line beneath a section */ -.sidebar-value { - font-family: var(--font-mono); - font-size: 13px; - font-weight: 500; +.sidebar-step-meta { + display: flex; + justify-content: space-between; + font-size: 10px; color: var(--text-muted); + margin-bottom: 4px; } -.sidebar-divider { - height: 1px; +.sidebar-step-bar { + height: 4px; background: var(--border); - margin: var(--space-4) 0; + border-radius: 2px; + overflow: hidden; } -.sidebar-summary { - font-family: var(--font-mono); - font-size: 13px; - color: var(--text-muted); - line-height: 1.4; +.sidebar-step-fill { + height: 100%; + background: var(--copper); + border-radius: 2px; + transition: width 300ms ease; } -/* Agent identity section */ -.sidebar-agent { - margin-bottom: var(--space-4); - font-family: var(--font-mono); +/* Agent section */ + +.sidebar-agent-section { + /* no extra margin needed — divider handles spacing */ } -.sidebar-agent-role { - color: var(--copper); - font-weight: 600; - text-transform: uppercase; - letter-spacing: 0.06em; - font-size: 13px; +.sidebar-model-row { + display: flex; + align-items: center; + gap: 6px; + margin-top: 6px; + margin-bottom: 10px; } -.sidebar-agent-model { - color: var(--text-muted); - font-size: 13px; +.sidebar-model-dot { + width: 6px; + height: 6px; + border-radius: 50%; + background: var(--green); + flex-shrink: 0; } -.sidebar-agent-step { - color: var(--text-muted); - font-size: 13px; - margin-top: 2px; +.sidebar-model-name { + font-size: 12px; + font-weight: 500; + color: var(--text); +} + +.sidebar-metrics { + display: flex; + flex-direction: column; + gap: 2px; } -.sidebar-agent-stats { +.sidebar-metric-row { display: flex; justify-content: space-between; + font-size: 11px; color: var(--text-muted); - font-size: 13px; - margin-top: 2px; + padding: 2px 0; +} + +.sidebar-metric-row span:last-child { + color: var(--text); + font-variant-numeric: tabular-nums; } /* ---- Workspace shell: three-column layout ---- */ diff --git a/koan/driver.py b/koan/driver.py index 7e92163..2615f31 100644 --- a/koan/driver.py +++ b/koan/driver.py @@ -1,89 +1,22 @@ -# Driver FSM -- coordinates phase transitions for an epic run. -# Pure routing logic (route_from_state) plus async orchestration helpers. +# Driver -- coordinates the persistent orchestrator for an epic run. +# Simplified: spawns one long-lived orchestrator process for the entire run. from __future__ import annotations -import time -from datetime import datetime, timezone from typing import TYPE_CHECKING -import aiofiles - from .artifacts import list_artifacts -from .epic_state import ( - atomic_write_json, - ensure_subagent_directory, - load_all_story_states, - load_epic_state, - load_story_state, - read_workflow_decision, - save_epic_state, - save_story_state, -) +from .epic_state import ensure_subagent_directory from .events import build_artifact_diff -from .lib.phase_dag import ( - PHASE_DESCRIPTIONS, - get_successor_phases, - is_auto_advance, - is_stub_phase, - is_valid_transition, -) from .logger import get_logger from .subagent import spawn_subagent -from .types import DEFAULT_MAX_RETRIES, EpicPhase, SubagentRole if TYPE_CHECKING: - from pathlib import Path - from .state import AppState log = get_logger("driver") -def _now() -> str: - return datetime.now(timezone.utc).isoformat() - - -# -- Phase-to-role mapping ---------------------------------------------------- - -PHASE_ROLE: dict[str, SubagentRole] = { - "intake": "intake", - "brief-generation": "brief-writer", - "core-flows": "decomposer", - "tech-plan": "planner", - "ticket-breakdown": "ticket-breakdown", - "cross-artifact-validation": "cross-artifact-validator", - "execution": "executor", - "implementation-validation": "cross-artifact-validator", -} - - -# -- Pure routing function ---------------------------------------------------- - -def route_from_state(stories: list[dict]) -> dict: - """Determine the next action from a list of story state dicts. - - Returns a dict with 'action' and optionally 'story_id' or 'error'. - Pure function -- no I/O, no mutation of inputs. - """ - # Retry takes priority - for s in stories: - if s.get("status") == "retry": - return {"action": "retry", "story_id": s.get("storyId")} - - # Then selected - for s in stories: - if s.get("status") == "selected": - return {"action": "execute", "story_id": s.get("storyId")} - - # All terminal? - terminal = {"done", "skipped"} - if stories and all(s.get("status") in terminal for s in stories): - return {"action": "complete"} - - return {"action": "error", "error": "no actionable stories found"} - - # -- Artifact diff helper ------------------------------------------------------ def _push_artifact_diff(app_state: AppState) -> None: @@ -105,369 +38,10 @@ def _push_artifact_diff(app_state: AppState) -> None: app_state.projection_store.push_event(event_type, payload) -# -- Workflow status ---------------------------------------------------------- - -async def write_workflow_status( - epic_dir: str | Path, - completed_phase: EpicPhase, - available_phases: list[EpicPhase], -) -> None: - """Write workflow-status.md with completed phase, available phases, and artifacts.""" - lines: list[str] = [] - lines.append(f"# Workflow Status") - lines.append("") - lines.append(f"## Completed Phase") - lines.append(f"**{completed_phase}**: {PHASE_DESCRIPTIONS.get(completed_phase, '')}") - lines.append("") - lines.append("## Available Next Phases") - for p in available_phases: - desc = PHASE_DESCRIPTIONS.get(p, "") - lines.append(f"- **{p}**: {desc}") - lines.append("") - lines.append("## Artifacts") - - artifacts = list_artifacts(epic_dir) - if artifacts: - for a in artifacts: - lines.append(f"- `{a['path']}` ({a['size']} bytes)") - else: - lines.append("(none)") - lines.append("") - - from pathlib import Path as P - out = P(epic_dir) / "workflow-status.md" - tmp = out.with_suffix(".tmp") - async with aiofiles.open(tmp, "w") as f: - await f.write("\n".join(lines)) - import os - os.rename(tmp, out) - - -# -- Workflow orchestrator ---------------------------------------------------- - -async def run_workflow_orchestrator( - completed_phase: EpicPhase, - available_phases: list[EpicPhase], - app_state: AppState, -) -> dict | None: - """Spawn a workflow-orchestrator subagent and return its decision.""" - epic_dir = app_state.epic_dir - await write_workflow_status(epic_dir, completed_phase, available_phases) - - label = f"workflow-orch-{completed_phase}-{int(time.time() * 1000)}" - subagent_dir = await ensure_subagent_directory(epic_dir, label) - - task = { - "role": "workflow-orchestrator", - "epic_dir": epic_dir, - "subagent_dir": subagent_dir, - "completed_phase": completed_phase, - "available_phases": available_phases, - } - - try: - result = await spawn_subagent(task, app_state) - exit_code = result.exit_code - except NotImplementedError: - log.warning("spawn_subagent not implemented; workflow orchestrator skipped") - return None - - if exit_code != 0: - log.error("workflow orchestrator exited with code %d", exit_code) - return None - - decision = await read_workflow_decision(subagent_dir) - if decision is None: - log.error("no workflow decision found in %s", subagent_dir) - return None - - next_phase = decision.get("next_phase") - if not is_valid_transition(completed_phase, next_phase): - log.error( - "invalid transition %s -> %s", completed_phase, next_phase - ) - return None - - return { - "next_phase": next_phase, - "instructions": decision.get("instructions"), - } - - -# -- Story execution helpers -------------------------------------------------- - -async def run_story_execution( - story_id: str, app_state: AppState -) -> bool: - """Run planner + executor + post-execution orchestrator for a story.""" - epic_dir = app_state.epic_dir - - # Planner - await save_story_state(epic_dir, story_id, {"storyId": story_id, "status": "planning", "updatedAt": _now()}) - # story events deferred -- execution phase UI is a known gap - - planner_dir = await ensure_subagent_directory( - epic_dir, f"planner-{story_id}-{int(time.time() * 1000)}" - ) - planner_task = { - "role": "planner", - "epic_dir": epic_dir, - "subagent_dir": planner_dir, - "story_id": story_id, - } - - try: - result = await spawn_subagent(planner_task, app_state) - planner_exit = result.exit_code - except NotImplementedError: - log.warning("spawn_subagent not implemented; story execution skipped") - return False - - planner_ok = planner_exit == 0 - - # Executor (skip if planner failed) - if planner_ok: - await save_story_state(epic_dir, story_id, {"storyId": story_id, "status": "executing", "updatedAt": _now()}) - - executor_dir = await ensure_subagent_directory( - epic_dir, f"executor-{story_id}-{int(time.time() * 1000)}" - ) - executor_task = { - "role": "executor", - "epic_dir": epic_dir, - "subagent_dir": executor_dir, - "story_id": story_id, - } - result = await spawn_subagent(executor_task, app_state) - executor_exit = result.exit_code - executor_ok = executor_exit == 0 - else: - executor_ok = False - - # Post-execution orchestrator - await save_story_state(epic_dir, story_id, {"storyId": story_id, "status": "verifying", "updatedAt": _now()}) - - orch_dir = await ensure_subagent_directory( - epic_dir, f"orch-post-{story_id}-{int(time.time() * 1000)}" - ) - orch_task = { - "role": "orchestrator", - "epic_dir": epic_dir, - "subagent_dir": orch_dir, - "story_id": story_id, - "step_sequence": "post-execution", - "planner_ok": planner_ok, - "executor_ok": executor_ok, - } - await spawn_subagent(orch_task, app_state) - - # Validate that orchestrator committed a verdict via story state - story = await load_story_state(epic_dir, story_id) - status = story.get("status") - if status not in ("done", "retry", "skipped"): - log.error( - "post-execution orchestrator did not commit a valid verdict for %s (status=%s)", - story_id, status, - ) - await save_story_state(epic_dir, story_id, { - "storyId": story_id, - "status": "retry", - "failureSummary": "post-execution orchestrator exited without committing a verdict", - "updatedAt": _now(), - }) - - return True - - -async def run_story_reexecution( - story_id: str, app_state: AppState -) -> bool: - """Re-execute a story: executor with retry context + post-execution orchestrator. - - Skips planner -- retry uses the existing plan with failure context injected - into the executor task manifest. - """ - epic_dir = app_state.epic_dir - - story = await load_story_state(epic_dir, story_id) - retry_context = story.get("failureSummary") - retry_count = story.get("retryCount", 0) - - # Executor with retry context - await save_story_state(epic_dir, story_id, {"storyId": story_id, "status": "executing", "updatedAt": _now()}) - - executor_dir = await ensure_subagent_directory( - epic_dir, f"executor-{story_id}-retry-{retry_count}-{int(time.time() * 1000)}" - ) - executor_task = { - "role": "executor", - "epic_dir": epic_dir, - "subagent_dir": executor_dir, - "story_id": story_id, - "retryContext": retry_context, - } - - try: - await spawn_subagent(executor_task, app_state) - except NotImplementedError: - log.warning("spawn_subagent not implemented; story re-execution skipped") - return False - - # Post-execution orchestrator - await save_story_state(epic_dir, story_id, {"storyId": story_id, "status": "verifying", "updatedAt": _now()}) - - orch_dir = await ensure_subagent_directory( - epic_dir, f"orch-post-{story_id}-retry-{retry_count}-{int(time.time() * 1000)}" - ) - orch_task = { - "role": "orchestrator", - "epic_dir": epic_dir, - "subagent_dir": orch_dir, - "story_id": story_id, - "step_sequence": "post-execution", - } - await spawn_subagent(orch_task, app_state) - - # Validate orchestrator committed a verdict via story state - updated = await load_story_state(epic_dir, story_id) - status = updated.get("status") - if status not in ("done", "retry", "skipped"): - log.error( - "post-execution orchestrator did not commit a valid verdict for %s (status=%s)", - story_id, status, - ) - await save_story_state(epic_dir, story_id, { - "storyId": story_id, - "status": "retry", - "failureSummary": "post-execution orchestrator exited without committing a verdict", - "updatedAt": _now(), - }) - - return True - - -# -- Story loop --------------------------------------------------------------- - -async def run_story_loop(app_state: AppState, instructions: str | None) -> dict: - """Run the execution story loop until all stories complete or error.""" - epic_dir = app_state.epic_dir - - # Pre-execution orchestrator - pre_dir = await ensure_subagent_directory( - epic_dir, f"orch-pre-{int(time.time() * 1000)}" - ) - pre_task = { - "role": "orchestrator", - "epic_dir": epic_dir, - "subagent_dir": pre_dir, - "step_sequence": "pre-execution", - "instructions": instructions, - } - - try: - result = await spawn_subagent(pre_task, app_state) - pre_exit = result.exit_code - except NotImplementedError: - log.warning("spawn_subagent not implemented; story loop skipped") - return {"success": False, "summary": "spawn_subagent not implemented"} - - if pre_exit != 0: - log.error("pre-execution orchestrator exited with code %d", pre_exit) - return {"success": False, "summary": "pre-execution orchestrator failed"} - - while True: - stories = await load_all_story_states(epic_dir) - decision = route_from_state(stories) - action = decision["action"] - - if action == "execute": - sid = decision["story_id"] - log.info("executing story %s", sid) - await run_story_execution(sid, app_state) - - elif action == "retry": - sid = decision["story_id"] - story = next((s for s in stories if s.get("storyId") == sid), {}) - retry_count = story.get("retryCount", 0) - max_retries = story.get("maxRetries", DEFAULT_MAX_RETRIES) - if retry_count >= max_retries: - log.warning("story %s exceeded retry budget, skipping", sid) - await save_story_state( - epic_dir, sid, - { - "storyId": sid, - "status": "skipped", - "skipReason": f"Retry budget exhausted after {retry_count} attempt(s). Last failure: {story.get('failureSummary', '(none recorded)')}", - "updatedAt": _now(), - }, - ) - else: - log.info("retrying story %s (attempt %d)", sid, retry_count + 1) - await save_story_state( - epic_dir, sid, - { - "storyId": sid, - "status": "executing", - "retryCount": retry_count + 1, - "updatedAt": _now(), - }, - ) - await run_story_reexecution(sid, app_state) - - elif action == "complete": - log.info("all stories complete") - return {"success": True, "summary": "all stories completed"} - - else: - log.error("route_from_state returned error: %s", decision.get("error")) - return {"success": False, "summary": decision.get("error", "unknown routing error")} - - -# -- Phase runner ------------------------------------------------------------- - -async def run_phase( - phase: EpicPhase, - app_state: AppState, - instructions: str | None, -) -> bool: - """Run a single phase. Returns True on success.""" - epic_dir = app_state.epic_dir - - if phase == "execution": - result = await run_story_loop(app_state, instructions) - return result.get("success", False) - - role = PHASE_ROLE.get(phase) - if role is None: - log.error("no role mapping for phase %s", phase) - return False - - subagent_dir = await ensure_subagent_directory( - epic_dir, f"{role}-{int(time.time() * 1000)}" - ) - task = { - "role": role, - "epic_dir": epic_dir, - "subagent_dir": subagent_dir, - "project_dir": app_state.project_dir, - "task_description": app_state.task_description, - "instructions": instructions, - } - - try: - result = await spawn_subagent(task, app_state) - exit_code = result.exit_code - except NotImplementedError: - log.warning("spawn_subagent not implemented; phase %s skipped", phase) - return False - - return exit_code == 0 - - # -- Main driver loop --------------------------------------------------------- async def driver_main(app_state: AppState) -> None: - """Main FSM loop -- waits for start event, then runs phases until completion.""" + """Wait for start event, then spawn the persistent orchestrator for the entire run.""" log.info("Driver waiting for start event...") await app_state.start_event.wait() @@ -476,65 +50,23 @@ async def driver_main(app_state: AppState) -> None: log.error("epic_dir is None after start event -- aborting") return - phase: EpicPhase = "intake" - pending_instructions: str | None = None - - while phase != "completed": - epic_state = await load_epic_state(epic_dir) - await save_epic_state(epic_dir, {**epic_state, "phase": phase}) - - # Set app_state.phase before emitting phase_started (driver mutation, not projection) - app_state.phase = phase - app_state.projection_store.push_event("phase_started", {"phase": phase}) - - # Push artifact diff at start of each phase - _push_artifact_diff(app_state) - - if is_stub_phase(phase): - pass # carry forward pending_instructions - else: - ok = await run_phase(phase, app_state, pending_instructions) - pending_instructions = None - if not ok: - app_state.projection_store.push_event("workflow_completed", { - "success": False, - "phase": phase, - "error": f"Phase {phase} failed", - "summary": f"Phase {phase} failed", - }) - return - - successors = get_successor_phases(phase) - if not successors: - break - - if is_auto_advance(phase): - phase = successors[0] - continue - - # Freeze logs snapshot for orchestrator - app_state.frozen_logs = list(app_state.frozen_logs) - decision = await run_workflow_orchestrator(phase, successors, app_state) - if not decision: - app_state.projection_store.push_event("workflow_completed", { - "success": False, - "phase": phase, - "error": "Workflow orchestrator failed", - "summary": "Workflow orchestrator failed", - }) - return - phase = decision["next_phase"] - pending_instructions = decision.get("instructions") + app_state.phase = "intake" + app_state.projection_store.push_event("phase_started", {"phase": "intake"}) + subagent_dir = await ensure_subagent_directory(epic_dir, "orchestrator") - epic_state = await load_epic_state(epic_dir) - await save_epic_state(epic_dir, {**epic_state, "phase": "completed"}) - app_state.phase = "completed" - app_state.projection_store.push_event("phase_started", {"phase": "completed"}) + task = { + "role": "orchestrator", + "epic_dir": epic_dir, + "subagent_dir": subagent_dir, + "project_dir": app_state.project_dir, + "task_description": app_state.task_description, + } - # Final artifact diff before completion - _push_artifact_diff(app_state) + result = await spawn_subagent(task, app_state) + # Orchestrator exited — workflow is over app_state.projection_store.push_event("workflow_completed", { - "success": True, - "summary": "All phases completed successfully", + "success": result.exit_code == 0, + "phase": app_state.phase, + "summary": f"Workflow ended in phase '{app_state.phase}'", }) diff --git a/koan/epic_state.py b/koan/epic_state.py index b1810ee..314ef00 100644 --- a/koan/epic_state.py +++ b/koan/epic_state.py @@ -71,16 +71,6 @@ async def load_all_story_states(epic_dir: str | Path) -> list[dict]: return results -async def read_workflow_decision(subagent_dir: str | Path) -> dict | None: - p = Path(subagent_dir) / "workflow-decision.json" - try: - async with aiofiles.open(p, "r") as f: - return json.loads(await f.read()) - except (FileNotFoundError, json.JSONDecodeError) as exc: - log.warning("read_workflow_decision failed for %s: %s", p, exc) - return None - - async def ensure_subagent_directory( epic_dir: str | Path, label: str ) -> str: diff --git a/koan/events.py b/koan/events.py index 16e1e68..67547e9 100644 --- a/koan/events.py +++ b/koan/events.py @@ -211,21 +211,6 @@ def build_artifact_reviewed( return result -def build_workflow_decision_requested(token: str, chat_turns: list) -> dict: - return {"token": token, "chat_turns": chat_turns} - - -def build_workflow_decided( - token: str, - decision: dict | None = None, - cancelled: bool = False, -) -> dict: - result: dict = {"token": token, "cancelled": cancelled} - if decision is not None: - result["decision"] = decision - return result - - # -- Configuration event builders --------------------------------------------- def build_probe_completed(results: dict[str, bool]) -> dict: diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index b3d605f..62f20d4 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -1,10 +1,12 @@ # Default-deny role-based permissions for koan subagents. # # Permission model: -# 1. READ_TOOLS always allowed for all roles (bash read/write ambiguity accepted). -# 2. ROLE_PERMISSIONS controls koan-specific tools and write/edit access. -# 3. Planning roles have write/edit path-scoped to the epic directory. +# 1. READ_TOOLS (except bash) always allowed for all roles. +# 2. bash is always allowed for non-orchestrator roles; phase-gated for orchestrator. +# 3. ROLE_PERMISSIONS controls koan-specific tools and write/edit access. +# 4. Planning roles have write/edit path-scoped to the epic directory. # Only executor has unrestricted write access. +# 5. The orchestrator role uses phase-aware permissions (current_phase parameter). # # Pure functions -- no I/O, no mutable state. @@ -18,10 +20,14 @@ # -- Constants ---------------------------------------------------------------- +# Tools that are always allowed regardless of role (except bash for orchestrator). READ_TOOLS: frozenset[str] = frozenset({ "bash", "read", "grep", "glob", "find", "ls", }) +# Non-bash read tools — unconditionally allowed for all roles including orchestrator. +_NON_BASH_READ_TOOLS: frozenset[str] = READ_TOOLS - {"bash"} + WRITE_TOOLS: frozenset[str] = frozenset({"edit", "write"}) ROLE_PERMISSIONS: dict[str, frozenset[str]] = { @@ -36,22 +42,14 @@ "scout": frozenset({ "koan_complete_step", }), - "decomposer": frozenset({ + "orchestrator": frozenset({ + # Base set; actual permissions are phase-aware — see _check_orchestrator_permission "koan_complete_step", + "koan_set_phase", "koan_ask_question", "koan_request_scouts", - "edit", - "write", - }), - "brief-writer": frozenset({ - "koan_complete_step", "koan_review_artifact", - "edit", - "write", - }), - "orchestrator": frozenset({ - "koan_complete_step", - "koan_ask_question", + "koan_spawn_executor", "koan_select_story", "koan_complete_story", "koan_retry_story", @@ -74,37 +72,13 @@ "write", "bash", }), - "workflow-orchestrator": frozenset({ - "koan_complete_step", - "koan_propose_workflow", - "koan_set_next_phase", - }), - "ticket-breakdown": frozenset({ - "koan_complete_step", - "koan_ask_question", - "koan_request_scouts", - "edit", - "write", - }), - "cross-artifact-validator": frozenset({ - "koan_complete_step", - "koan_ask_question", - "koan_request_scouts", - "edit", - "write", - }), } PLANNING_ROLES: frozenset[str] = frozenset({ "intake", "scout", - "decomposer", - "brief-writer", "orchestrator", "planner", - "workflow-orchestrator", - "ticket-breakdown", - "cross-artifact-validator", }) STEP_1_BLOCKED_TOOLS: frozenset[str] = frozenset({ @@ -114,24 +88,142 @@ "edit", }) +# -- Orchestrator phase-specific constants ------------------------------------ + +_ORCHESTRATOR_SCOUT_PHASES: frozenset[str] = frozenset({ + "intake", "core-flows", "tech-plan", "ticket-breakdown", "cross-artifact-validation", +}) + +_ORCHESTRATOR_REVIEW_PHASES: frozenset[str] = frozenset({ + "intake", "brief-generation", "core-flows", "tech-plan", + "ticket-breakdown", "cross-artifact-validation", "implementation-validation", +}) + +_ORCHESTRATOR_EXECUTION_ONLY: frozenset[str] = frozenset({ + "koan_spawn_executor", "koan_select_story", "koan_complete_story", + "koan_retry_story", "koan_skip_story", +}) + +_ORCHESTRATOR_BASH_PHASES: frozenset[str] = frozenset({ + "execution", "implementation-validation", +}) + # -- Permission check --------------------------------------------------------- +def _check_orchestrator_permission( + tool_name: str, + current_phase: str | None, + current_step: int | None, + epic_dir: str | None, + tool_args: dict | None, +) -> dict: + """Phase-aware permission check for the persistent orchestrator role. + + Called after non-bash READ_TOOLS have already been allowed by check_permission. + This function handles bash (phase-gated) and all koan tool permissions. + """ + phase = current_phase or "" + + # Non-bash read tools: unconditionally allowed (already handled in check_permission, + # but guard here too for direct callers). + if tool_name in _NON_BASH_READ_TOOLS: + return {"allowed": True, "reason": None} + + # bash — execution and implementation-validation only + if tool_name == "bash": + if phase in _ORCHESTRATOR_BASH_PHASES: + return {"allowed": True, "reason": None} + return {"allowed": False, "reason": f"bash is not available in phase '{phase}'"} + + # Always allowed base koan tools + if tool_name in ("koan_complete_step", "koan_set_phase"): + return {"allowed": True, "reason": None} + + # koan_ask_question — always allowed except brief-generation step 1 + if tool_name == "koan_ask_question": + if phase == "brief-generation" and current_step == 1: + return { + "allowed": False, + "reason": ( + "koan_ask_question is not available during the Read step (step 1). " + "Complete koan_complete_step first to advance to the next step." + ), + } + return {"allowed": True, "reason": None} + + # koan_request_scouts — planning phases only (not brief-generation) + if tool_name == "koan_request_scouts": + if phase in _ORCHESTRATOR_SCOUT_PHASES: + return {"allowed": True, "reason": None} + return {"allowed": False, "reason": f"koan_request_scouts is not available in phase '{phase}'"} + + # koan_review_artifact — most planning phases + implementation-validation + if tool_name == "koan_review_artifact": + if phase in _ORCHESTRATOR_REVIEW_PHASES: + return {"allowed": True, "reason": None} + return {"allowed": False, "reason": f"koan_review_artifact is not available in phase '{phase}'"} + + # Execution-only tools + if tool_name in _ORCHESTRATOR_EXECUTION_ONLY: + if phase == "execution": + return {"allowed": True, "reason": None} + return {"allowed": False, "reason": f"{tool_name} is only available during the execution phase"} + + # write / edit — all phases except brief-generation step 1 + if tool_name in WRITE_TOOLS: + if phase == "brief-generation" and current_step == 1: + return { + "allowed": False, + "reason": ( + f"{tool_name} is not available during the Read step (step 1). " + "Complete koan_complete_step first to advance to the next step." + ), + } + # Path scoping + if epic_dir and tool_args: + raw_path = tool_args.get("path") + if isinstance(raw_path, str): + resolved_tool = Path(raw_path).resolve() + resolved_epic = Path(epic_dir).resolve() + if resolved_tool != resolved_epic and not str(resolved_tool).startswith(str(resolved_epic) + "/"): + log.warning( + "Write blocked: path outside epic dir: role=orchestrator tool=%s path=%s epic=%s", + tool_name, raw_path, epic_dir, + ) + return { + "allowed": False, + "reason": f'{tool_name} path "{raw_path}" is outside epic directory', + } + return {"allowed": True, "reason": None} + + return {"allowed": False, "reason": f"{tool_name} is not available for the orchestrator role"} + + def check_permission( role: str, tool_name: str, epic_dir: str | None = None, tool_args: dict | None = None, current_step: int | None = None, + current_phase: str | None = None, ) -> dict: """Return {"allowed": True/False, "reason": str|None}.""" - # Read tools always allowed -- check before role map lookup. - if tool_name in READ_TOOLS: + # Non-bash read tools always allowed for all roles. + if tool_name in _NON_BASH_READ_TOOLS: + return {"allowed": True, "reason": None} + + # Orchestrator uses phase-aware permission logic (handles bash phase-gating). + if role == "orchestrator": + return _check_orchestrator_permission(tool_name, current_phase, current_step, epic_dir, tool_args) + + # bash always allowed for non-orchestrator roles. + if tool_name == "bash": return {"allowed": True, "reason": None} - # Brief-writer step 1 (Read) is read-only. - if role == "brief-writer" and current_step == 1 and tool_name in STEP_1_BLOCKED_TOOLS: + # brief-generation step 1 (Read) is read-only — phase-aware gate. + if current_phase == "brief-generation" and current_step == 1 and tool_name in STEP_1_BLOCKED_TOOLS: return { "allowed": False, "reason": ( diff --git a/koan/lib/phase_dag.py b/koan/lib/phase_dag.py index b6caa40..6b37114 100644 --- a/koan/lib/phase_dag.py +++ b/koan/lib/phase_dag.py @@ -1,9 +1,8 @@ # Phase transition DAG -- the single source of truth for valid epic phase transitions. # # Consulted by: -# - the driver (to decide whether to spawn the orchestrator or auto-advance) -# - koan_set_next_phase (to validate the committed transition) -# - workflow_orchestrator step 2 guidance (lists available phases) +# - the driver (to decide when to spawn the orchestrator) +# - koan_set_phase (to validate the committed transition) # # Pure functions -- no I/O, no mutable state. @@ -63,5 +62,7 @@ def is_stub_phase(phase: EpicPhase) -> bool: return phase != "completed" and phase != "implementation-validation" and phase not in IMPLEMENTED_PHASES -def is_valid_transition(from_phase: EpicPhase, to_phase: EpicPhase) -> bool: +def is_valid_transition(from_phase: EpicPhase | None, to_phase: EpicPhase) -> bool: + if from_phase is None: + return False return to_phase in get_successor_phases(from_phase) diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index 63cc4b8..aa046d9 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -24,8 +24,6 @@ class PhaseContext: project_dir: str = "" task_description: str = "" phase_instructions: str | None = None - intake_confidence: str | None = None - intake_iteration: int = 0 last_review_accepted: bool | None = None proposal_made: bool = False next_phase_set: bool = False @@ -50,8 +48,33 @@ def validate_step_completion(self, step: int, ctx: PhaseContext) -> str | None: async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> None: ... +# -- Orchestrator base system prompt ------------------------------------------ +# Delivered via --system-prompt at spawn time. Phase-specific role context +# is injected via koan_complete_step's step-1 guidance (SYSTEM_PROMPT prepend). + +ORCHESTRATOR_SYSTEM_PROMPT = ( + "You are the koan workflow orchestrator. You run a coding task planning and" + " execution pipeline from start to finish in a single continuous session.\n" + "\n" + "You work through phases in sequence: each phase has numbered steps. Call" + " koan_complete_step to advance through steps. When a phase ends," + " koan_complete_step will return the user's message and available next phases." + " Converse with the user about what to do next, then call koan_set_phase to" + " commit the transition.\n" + "\n" + "At the start of each phase, koan_complete_step returns your role context for" + " that phase alongside the first step's instructions.\n" + "\n" + "Rules:\n" + "- Only call koan_set_phase after the user has confirmed the direction.\n" + "- When the user indicates they are done, or all phases are complete, exit gracefully.\n" + "- Available tools change depending on the current phase. The step 1 guidance" + " for each phase lists the tools relevant to that phase." +) + + # -- Phase module registry ---------------------------------------------------- -# Maps each SubagentRole string to its phase module. +# Maps each SubagentRole string to its phase module (for subagent spawn lookup). from . import ( brief_writer, @@ -63,19 +86,28 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> scout, tech_plan as planner, ticket_breakdown, - workflow_orchestrator, ) from typing import Any PHASE_MODULE_MAP: dict[str, Any] = { "intake": intake, "scout": scout, - "brief-writer": brief_writer, - "decomposer": core_flows, "orchestrator": orchestrator, "planner": planner, "executor": executor, - "workflow-orchestrator": workflow_orchestrator, - "ticket-breakdown": ticket_breakdown, - "cross-artifact-validator": cross_artifact_validation, +} + +# -- Phase guidance map ------------------------------------------------------- +# Maps EpicPhase strings to the phase module that provides step guidance. +# Used by koan_set_phase to load the module for the new phase. + +PHASE_GUIDANCE_MAP: dict[str, Any] = { + "intake": intake, + "brief-generation": brief_writer, + "core-flows": core_flows, + "tech-plan": planner, + "ticket-breakdown": ticket_breakdown, + "cross-artifact-validation": cross_artifact_validation, + "execution": executor, + "implementation-validation": cross_artifact_validation, } diff --git a/koan/phases/format_step.py b/koan/phases/format_step.py index 04d6ffc..6171286 100644 --- a/koan/phases/format_step.py +++ b/koan/phases/format_step.py @@ -3,7 +3,8 @@ from __future__ import annotations -from typing import TYPE_CHECKING +from datetime import datetime, timezone +from typing import TYPE_CHECKING, Any if TYPE_CHECKING: from . import StepGuidance @@ -20,3 +21,42 @@ def format_step(g: StepGuidance) -> str: body = "\n".join(g.instructions) invoke = g.invoke_after if g.invoke_after is not None else DEFAULT_INVOKE return f"{header}{body}\n\n{invoke}" + + +def format_user_messages(messages: list[Any]) -> str: + """Format a list of ChatMessage objects into a readable string block.""" + parts = [] + for msg in messages: + ts = datetime.fromtimestamp(msg.timestamp_ms / 1000, tz=timezone.utc) + ts_str = ts.strftime("%H:%M:%S UTC") + parts.append(f"---\nUSER MESSAGE (at {ts_str}):\n{msg.content}\n---") + return "\n\n".join(parts) + + +def format_phase_boundary(phase: str, messages: list[Any], successors: list[str]) -> str: + """Format a phase-boundary response that includes user messages and next-phase options.""" + title = f"Phase Complete: {phase}" + lines = [title, "=" * len(title), ""] + + if messages: + lines.append("## User Message(s)") + lines.append("") + for msg in messages: + ts = datetime.fromtimestamp(msg.timestamp_ms / 1000, tz=timezone.utc) + ts_str = ts.strftime("%H:%M:%S UTC") + lines.append(f"**[{ts_str}]** {msg.content}") + lines.append("") + + lines.append("## Available Next Phases") + lines.append("") + for s in successors: + lines.append(f"- **{s}**") + lines.append("") + + lines.append("## Instructions") + lines.append("") + lines.append("Discuss the completed phase and the user's message(s) with the user.") + lines.append("Once the user has confirmed what to do next, call `koan_set_phase` with") + lines.append("the chosen phase name. Then call `koan_complete_step` to begin.") + + return "\n".join(lines) diff --git a/koan/phases/workflow_orchestrator.py b/koan/phases/workflow_orchestrator.py deleted file mode 100644 index 7b2c147..0000000 --- a/koan/phases/workflow_orchestrator.py +++ /dev/null @@ -1,129 +0,0 @@ -# Workflow-orchestrator phase -- 2-step workflow. -# -# Step 1 (Evaluate) -- read workflow-status.md and phase artifacts -# Step 2 (Propose) -- call koan_propose_workflow, handle feedback, commit -# -# Step 2 is double-gated: both koan_propose_workflow and koan_set_next_phase -# must be called before completion. - -from __future__ import annotations - -from . import PhaseContext, StepGuidance - -ROLE = "workflow-orchestrator" -TOTAL_STEPS = 2 - -STEP_NAMES: dict[int, str] = { - 1: "Evaluate", - 2: "Propose", -} - -SYSTEM_PROMPT = ( - "You are a workflow orchestrator for a coding task planning pipeline. Your role" - " is to evaluate what has been accomplished and guide the user in choosing what" - " to do next.\n" - "\n" - "## Your responsibilities\n" - "\n" - "1. Read available context (workflow-status.md and any phase artifacts)\n" - "2. Understand what was accomplished and what options are available\n" - "3. Present a clear status report and phase options to the user\n" - "4. Hold a conversation until the user's intent is clear\n" - "5. Commit the next phase decision via koan_set_next_phase\n" - "\n" - "## Communication style\n" - "\n" - "- Be concise and direct\n" - "- Focus on what matters to the user's goal\n" - "- When the user's direction is clear, commit it -- don't over-clarify\n" - "- Present phase options with helpful context, not technical jargon\n" - "\n" - "## Constraints\n" - "\n" - "- You must call koan_propose_workflow before koan_set_next_phase\n" - "- You may call koan_propose_workflow multiple times if the user needs more clarification\n" - "- The phase you commit must be in your available phases list" -) - - -# -- Step guidance ------------------------------------------------------------- - -def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: - ed = ctx.epic_dir - - if step == 1: - return StepGuidance( - title=STEP_NAMES[1], - instructions=[ - f"Read `{ed}/workflow-status.md` to understand:", - "", - "- Which phase just completed", - "- What artifacts are available", - "- Which phases are available next", - "", - "Then read any relevant artifacts (landscape.md, brief.md, etc.) to", - "build a thorough understanding of what has been accomplished and what", - "the user's goal is.", - "", - "Do NOT call koan_propose_workflow yet. Comprehend the current state first.", - ], - ) - - if step == 2: - from ..lib.phase_dag import PHASE_DESCRIPTIONS - phase_list = [ - f"- **{p}**: {PHASE_DESCRIPTIONS.get(p, p)}" - for p in ctx.available_phases - ] - return StepGuidance( - title=STEP_NAMES[2], - instructions=[ - "Call koan_propose_workflow with:", - "", - "1. A **status_report** (markdown) summarizing what was accomplished", - " and why the available phases make sense right now", - "", - "2. **recommended_phases** -- the available next phases (in order of", - " recommendation):", - "", - *phase_list, - "", - "The user will respond with their direction. If their response is clear,", - "call koan_set_next_phase to commit the decision (with optional instructions", - "to focus the next phase). If their response needs clarification, call", - "koan_propose_workflow again with an updated status report.", - "", - "You MUST call both koan_propose_workflow and koan_set_next_phase before", - "completing this step.", - ], - ) - - return StepGuidance(title=f"Step {step}", instructions=[f"Execute step {step}."]) - - -# -- Lifecycle ----------------------------------------------------------------- - -def get_next_step(step: int, ctx: PhaseContext) -> int | None: - if step == 0: - return 1 - if step == 1: - return 2 - if step == 2: - if ctx.proposal_made and ctx.next_phase_set: - return None - return 2 - return None - - -def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: - if step != 2: - return None - if not ctx.proposal_made: - return "You must call koan_propose_workflow before completing this step." - if not ctx.next_phase_set: - return "You must call koan_set_next_phase to commit the phase decision before completing this step." - return None - - -async def on_loop_back(from_step: int, to_step: int, ctx: PhaseContext) -> None: - pass diff --git a/koan/projections.py b/koan/projections.py index 81b1401..b983934 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -51,13 +51,13 @@ "stream_delta", "stream_cleared", "debug_step_guidance", + # User chat + "user_message", # Focus (interactions) "questions_asked", "questions_answered", "artifact_review_requested", "artifact_reviewed", - "workflow_decision_requested", - "workflow_decided", # Resources "artifact_created", "artifact_modified", @@ -131,6 +131,11 @@ class StepEntry(KoanBaseModel): step_name: str total_steps: int | None = None +class UserMessageEntry(KoanBaseModel): + type: Literal["user_message"] = "user_message" + content: str + timestamp_ms: int + class BaseToolEntry(KoanBaseModel): """Shared fields for all tool entries.""" call_id: str # unique per tool invocation @@ -173,7 +178,7 @@ class DebugStepGuidanceEntry(KoanBaseModel): content: str # full formatted step guidance text ConversationEntry = Annotated[ - ThinkingEntry | TextEntry | StepEntry | + ThinkingEntry | TextEntry | StepEntry | UserMessageEntry | ToolReadEntry | ToolWriteEntry | ToolEditEntry | ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry | DebugStepGuidanceEntry, @@ -219,15 +224,8 @@ class ReviewFocus(KoanBaseModel): description: str = "" content: str = "" -class DecisionFocus(KoanBaseModel): - """Workflow decision needed from user.""" - type: Literal["decision"] = "decision" - agent_id: str - token: str - chat_turns: list[dict] = [] - Focus = Annotated[ - ConversationFocus | QuestionFocus | ReviewFocus | DecisionFocus, + ConversationFocus | QuestionFocus | ReviewFocus, Field(discriminator="type"), ] @@ -836,6 +834,27 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: "run": _update_agent_conversation(projection.run, agent_id, new_conv), }) + case "user_message": + if projection.run is None: + return projection + pid = _primary_agent_id(projection.run) + if pid is None: + return projection + agent = projection.run.agents.get(pid) + if agent is None: + return projection + entry = UserMessageEntry( + content=payload.get("content", ""), + timestamp_ms=payload.get("timestamp_ms", 0), + ) + new_conv = _flush_conversation(agent.conversation) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, entry], + }) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, pid, new_conv), + }) + case "agent_step_advanced": if projection.run is None or not agent_id: return projection @@ -849,9 +868,10 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: total_steps = payload.get("total_steps") usage = payload.get("usage") - # Flush both pending fields, optionally append StepEntry + # Flush both pending fields, optionally append StepEntry. + # step >= 0 so phase-transition markers (step=0 from koan_set_phase) also appear. new_conv = _flush_conversation(agent.conversation) - if step >= 1: + if step >= 0 and step_name: new_conv = new_conv.model_copy(update={ "entries": [*new_conv.entries, StepEntry( step=step, @@ -920,28 +940,6 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: }) return projection.model_copy(update={"run": new_run}) - case "workflow_decision_requested": - if projection.run is None or not agent_id: - return projection - new_focus = DecisionFocus( - agent_id=agent_id, - token=payload.get("token", ""), - chat_turns=payload.get("chat_turns", []), - ) - new_run = projection.run.model_copy(update={"focus": new_focus}) - return projection.model_copy(update={"run": new_run}) - - case "workflow_decided": - if projection.run is None: - return projection - pid = _primary_agent_id(projection.run) - if pid is None: - return projection - new_run = projection.run.model_copy(update={ - "focus": ConversationFocus(agent_id=pid), - }) - return projection.model_copy(update={"run": new_run}) - # ── Resources ───────────────────────────────────────────────── case "artifact_created": diff --git a/koan/runners/base.py b/koan/runners/base.py index 0527772..46f1671 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -63,9 +63,13 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: ... # When adding a new koan MCP tool to mcp_endpoint.py, update this set too. KOAN_MCP_TOOLS: frozenset[str] = frozenset({ "koan_complete_step", + "koan_set_phase", "koan_request_scouts", "koan_ask_question", "koan_review_artifact", - "koan_propose_workflow", - "koan_set_next_phase", + "koan_spawn_executor", + "koan_select_story", + "koan_complete_story", + "koan_retry_story", + "koan_skip_story", }) diff --git a/koan/state.py b/koan/state.py index 5496e86..88fbf6f 100644 --- a/koan/state.py +++ b/koan/state.py @@ -20,9 +20,15 @@ def _utcnow() -> datetime: from .types import EpicPhase, Profile, SubagentRole +@dataclass +class ChatMessage: + content: str + timestamp_ms: int + + @dataclass class PendingInteraction: - type: Literal["ask", "artifact-review", "workflow-decision"] + type: Literal["ask", "artifact-review"] agent_id: str future: asyncio.Future payload: dict @@ -61,7 +67,6 @@ class AppState: active_interaction: PendingInteraction | None = None interaction_queue: deque[PendingInteraction] = field(default_factory=deque) interaction_queue_max: int = 8 - frozen_logs: list = field(default_factory=list) config: KoanConfig = field(default_factory=KoanConfig) balanced_profile: Profile | None = None probe_results: list[ProbeResult] = field(default_factory=list) @@ -78,3 +83,14 @@ class AppState: _active_processes: dict[str, asyncio.subprocess.Process] = field( default_factory=dict, repr=False, ) + # Buffered user chat messages — drained at each koan_complete_step call. + user_message_buffer: list[ChatMessage] = field(default_factory=list) + # Non-None while koan_complete_step is blocking at a phase boundary. + phase_complete_future: asyncio.Future | None = None + + +def drain_user_messages(app_state: AppState) -> list[ChatMessage]: + """Atomically drain the user message buffer. Returns all buffered messages.""" + messages = list(app_state.user_message_buffer) + app_state.user_message_buffer.clear() + return messages diff --git a/koan/subagent.py b/koan/subagent.py index c5c50db..5d8f4f9 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -29,10 +29,9 @@ build_tool_ls, build_tool_read, build_tool_write, - build_workflow_decided, ) from .logger import get_logger -from .phases import PHASE_MODULE_MAP, PhaseContext +from .phases import ORCHESTRATOR_SYSTEM_PROMPT, PHASE_GUIDANCE_MAP, PHASE_MODULE_MAP, PhaseContext from .runners import RunnerDiagnostic, RunnerError from .runners.registry import RunnerRegistry @@ -147,8 +146,16 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None # Build PhaseContext phase_ctx = _build_phase_ctx(task, subagent_dir) - # Look up phase module - phase_module = PHASE_MODULE_MAP.get(role) + # Look up phase module and system prompt. + # Persistent orchestrator: uses intake as initial step-guidance module; + # ORCHESTRATOR_SYSTEM_PROMPT as the spawn-time --system-prompt. + if role == "orchestrator": + phase_module = PHASE_GUIDANCE_MAP.get("intake") + system_prompt = ORCHESTRATOR_SYSTEM_PROMPT + else: + phase_module = PHASE_MODULE_MAP.get(role) + system_prompt = getattr(phase_module, "SYSTEM_PROMPT", "") or "" if phase_module else "" + if phase_module is None: log.error("no phase module for role %s", role) return SubagentResult(exit_code=1) @@ -179,7 +186,6 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None # Build command before emitting agent_spawned -- if build_command fails, no # agent_spawned event is emitted (per plan: "the agent was never launched"). - system_prompt = getattr(phase_module, "SYSTEM_PROMPT", "") or "" try: if installation is not None and thinking_mode is not None: cmd = runner.build_command( @@ -368,6 +374,8 @@ def _cancel_pending_interactions(agent_id: str, app_state: AppState) -> None: Queued interactions are cancelled silently (no projection event). The active interaction (if it belongs to this agent) emits a typed cancellation resolution event. + + Also clears phase_complete_future if the agent was blocked at a phase boundary. """ from .web.interactions import activate_next_interaction @@ -403,13 +411,12 @@ def _cancel_pending_interactions(agent_id: str, app_state: AppState) -> None: build_artifact_reviewed(token, accepted=None, response=None, cancelled=True), agent_id=agent_id, ) - elif active.type == "workflow-decision": - store.push_event( - "workflow_decided", - build_workflow_decided(token, decision=None, cancelled=True), - agent_id=agent_id, - ) if not active.future.done(): active.future.set_result(error_result) activate_next_interaction(app_state) + + # Clear phase_complete_future if it was set (orchestrator crashed at phase boundary) + if app_state.phase_complete_future is not None and not app_state.phase_complete_future.done(): + app_state.phase_complete_future.set_result(False) + app_state.phase_complete_future = None diff --git a/koan/types.py b/koan/types.py index 85ed28a..af4981c 100644 --- a/koan/types.py +++ b/koan/types.py @@ -19,14 +19,9 @@ SubagentRole = Literal[ "intake", "scout", - "decomposer", "orchestrator", "planner", "executor", - "brief-writer", - "workflow-orchestrator", - "ticket-breakdown", - "cross-artifact-validator", ] ModelTier = Literal["strong", "standard", "cheap"] @@ -81,12 +76,7 @@ class AgentInstallation: ROLE_MODEL_TIER: dict[SubagentRole, ModelTier] = { "intake": "strong", "scout": "cheap", - "decomposer": "strong", - "brief-writer": "strong", "orchestrator": "strong", "planner": "strong", "executor": "standard", - "workflow-orchestrator": "strong", - "ticket-breakdown": "strong", - "cross-artifact-validator": "strong", } diff --git a/koan/web/app.py b/koan/web/app.py index b98eef8..bc8d94f 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -26,12 +26,13 @@ from ..artifacts import list_artifacts from ..epic_state import atomic_write_json from ..probe import ProbeResult +from ..projections import _primary_agent_id +from ..state import ChatMessage from ..types import AgentInstallation, Profile, ProfileTier from .interactions import activate_next_interaction from ..events import ( build_artifact_reviewed, build_questions_answered, - build_workflow_decided, build_probe_completed, build_run_started, build_installation_created, @@ -314,6 +315,12 @@ async def api_start_run(r: Request) -> Response: build_run_started(profile, _installations_map, _scout_concurrency), ) + # Reset run-scoped state + st.user_message_buffer.clear() + if st.phase_complete_future is not None and not st.phase_complete_future.done(): + st.phase_complete_future.set_result(False) + st.phase_complete_future = None + # Create epic directory epic_id = f"{int(time.time())}-{uuid.uuid4().hex[:8]}" epic_dir = Path.home() / ".koan" / "epics" / epic_id @@ -331,6 +338,37 @@ async def api_start_run(r: Request) -> Response: return JSONResponse({"ok": True, "epic_dir": str(epic_dir)}) +async def api_chat(r: Request) -> Response: + """Accept a user chat message, buffer it, and unblock any waiting phase boundary.""" + body = await r.json() + message = body.get("message", "") + if not isinstance(message, str) or not message.strip(): + return JSONResponse({"error": "empty_message"}, status_code=422) + + st = _app_state(r) + if st.epic_dir is None: + return JSONResponse({"error": "no_run"}, status_code=409) + + ts = int(time.time() * 1000) + msg = ChatMessage(content=message.strip(), timestamp_ms=ts) + st.user_message_buffer.append(msg) + + # Emit projection event so the message appears in the activity feed + run = st.projection_store.projection.run + primary_id = _primary_agent_id(run) if run else None + st.projection_store.push_event( + "user_message", + {"content": msg.content, "timestamp_ms": msg.timestamp_ms}, + agent_id=primary_id, + ) + + # Unblock koan_complete_step if it is blocking at a phase boundary + if st.phase_complete_future is not None and not st.phase_complete_future.done(): + st.phase_complete_future.set_result(True) + + return JSONResponse({"ok": True}) + + async def api_answer(r: Request) -> Response: body = await r.json() answers = body.get("answers", []) @@ -374,49 +412,6 @@ async def api_artifact_review(r: Request) -> Response: return JSONResponse({"ok": True}) -async def api_workflow_decision(r: Request) -> Response: - body = await r.json() - phase = body.get("phase", "") - context = body.get("context", "") - token = body.get("token", "") - - st = _app_state(r) - active = st.active_interaction - if active is None or active.type != "workflow-decision" or active.token != token: - return _stale_response() - - # Extract valid phases from the active interaction payload - valid_phases: set[str] = set() - for turn in active.payload.get("chat_turns", []): - for rp in turn.get("recommended_phases", []): - p = rp.get("phase", "") - if p: - valid_phases.add(p) - - if not phase: - return JSONResponse( - {"ok": False, "error": "empty_phase", "message": "A phase must be selected"}, - status_code=422, - ) - - if valid_phases and phase not in valid_phases: - return JSONResponse( - {"ok": False, "error": "invalid_phase", - "message": f"Phase '{phase}' is not among the proposed options"}, - status_code=422, - ) - - interaction = active - st.projection_store.push_event( - "workflow_decided", - build_workflow_decided(interaction.token, decision={"phase": phase, "context": context}, cancelled=False), - agent_id=interaction.agent_id, - ) - activate_next_interaction(st) - interaction.future.set_result({"phase": phase, "context": context}) - return JSONResponse({"ok": True}) - - async def api_artifacts_list(r: Request) -> Response: st = _app_state(r) if not st.epic_dir: @@ -1061,7 +1056,7 @@ async def _wait_proc(aid: str, proc: asyncio.subprocess.Process) -> None: Route("/api/start-run/preflight", api_start_run_preflight, methods=["GET"]), Route("/api/answer", api_answer, methods=["POST"]), Route("/api/artifact-review", api_artifact_review, methods=["POST"]), - Route("/api/workflow-decision", api_workflow_decision, methods=["POST"]), + Route("/api/chat", api_chat, methods=["POST"]), Route("/api/artifacts", api_artifacts_list), Route("/api/artifacts/{path:path}", api_artifact_content), Route("/api/probe", api_probe), diff --git a/koan/web/interactions.py b/koan/web/interactions.py index 05569e3..35de46d 100644 --- a/koan/web/interactions.py +++ b/koan/web/interactions.py @@ -24,7 +24,6 @@ def _emit_interaction_request(app_state: AppState, interaction: PendingInteracti from ..events import ( build_artifact_review_requested, build_questions_asked, - build_workflow_decision_requested, ) store = app_state.projection_store @@ -49,12 +48,6 @@ def _emit_interaction_request(app_state: AppState, interaction: PendingInteracti ), agent_id=agent_id, ) - elif interaction.type == "workflow-decision": - store.push_event( - "workflow_decision_requested", - build_workflow_decision_requested(token, payload.get("chat_turns", [])), - agent_id=agent_id, - ) # -- Queue helpers ------------------------------------------------------------ @@ -62,7 +55,7 @@ def _emit_interaction_request(app_state: AppState, interaction: PendingInteracti async def enqueue_interaction( agent: AgentState, app_state: AppState, - interaction_type: Literal["ask", "artifact-review", "workflow-decision"], + interaction_type: Literal["ask", "artifact-review"], payload: dict, ) -> asyncio.Future: total = len(app_state.interaction_queue) + (1 if app_state.active_interaction else 0) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 01b1ca9..d15ee98 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -4,28 +4,38 @@ # 1. Validates agent_id from query params before reaching fastmcp. # 2. Runs check_permission() on every tool call. # 3. Implements koan_complete_step, koan_request_scouts, -# koan_ask_question, koan_review_artifact, koan_propose_workflow, -# koan_set_next_phase. +# koan_ask_question, koan_review_artifact, koan_set_phase, +# koan_spawn_executor, and story management tools. from __future__ import annotations import asyncio import json +import time import uuid from contextvars import ContextVar +from datetime import datetime, timezone from pathlib import Path -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, Literal from urllib.parse import parse_qs import aiofiles from fastmcp import FastMCP from fastmcp.exceptions import ToolError -from ..epic_state import atomic_write_json, ensure_subagent_directory +from ..epic_state import ( + atomic_write_json, + ensure_subagent_directory, + load_story_state, + save_epic_state, + save_story_state, + load_epic_state, +) from ..lib.permissions import check_permission -from ..lib.phase_dag import is_valid_transition +from ..lib.phase_dag import get_successor_phases, is_valid_transition from ..logger import get_logger -from ..phases.format_step import format_step +from ..phases import PHASE_GUIDANCE_MAP, PhaseContext, StepGuidance +from ..phases.format_step import format_phase_boundary, format_step, format_user_messages from .interactions import activate_next_interaction, enqueue_interaction if TYPE_CHECKING: @@ -50,12 +60,14 @@ def _check_or_raise(agent: AgentState, tool_name: str, tool_args: dict | None = phase_ctx.epic_dir if phase_ctx is not None and phase_ctx.epic_dir else agent.epic_dir or None ) + current_phase = _app_state.phase if _app_state is not None else None result = check_permission( role=agent.role, tool_name=tool_name, epic_dir=resolved_epic_dir, tool_args=tool_args, current_step=agent.step, + current_phase=current_phase, ) if not result["allowed"]: raise ToolError( @@ -108,7 +120,160 @@ def end_tool_call( ) -# -- Tool implementations ----------------------------------------------------- +def _now_iso() -> str: + return datetime.now(timezone.utc).isoformat() + + +def _resolve_epic_dir(agent: AgentState) -> str | None: + phase_ctx = agent.phase_ctx + if phase_ctx is not None and phase_ctx.epic_dir: + return phase_ctx.epic_dir + if agent.epic_dir: + return agent.epic_dir + if _app_state is not None and _app_state.epic_dir: + return _app_state.epic_dir + return None + + +# -- koan_complete_step private helpers ---------------------------------------- + +async def _step_phase_handshake(agent: AgentState) -> str: + """Handle step 0 → 1: deliver step 1 guidance prepended with phase SYSTEM_PROMPT.""" + assert _app_state is not None + + phase_module = agent.phase_module + ctx = agent.phase_ctx + + step_names = getattr(phase_module, "STEP_NAMES", {}) + step_name = step_names.get(1, "") + + # Audit log + if agent.event_log is not None: + await agent.event_log.emit_step_transition(1, step_name, phase_module.TOTAL_STEPS) + + # Projection event + from ..events import build_step_advanced + _app_state.projection_store.push_event( + "agent_step_advanced", + build_step_advanced(1, step_name, total_steps=phase_module.TOTAL_STEPS), + agent_id=agent.agent_id, + ) + + agent.step = 1 + guidance = phase_module.step_guidance(1, ctx) + + # Prepend SYSTEM_PROMPT so the orchestrator receives the phase role context + system_prompt = getattr(phase_module, "SYSTEM_PROMPT", "") or "" + if system_prompt: + guidance = StepGuidance( + title=guidance.title, + instructions=[system_prompt, ""] + list(guidance.instructions), + invoke_after=guidance.invoke_after, + ) + + result = format_step(guidance) + + if _app_state.debug: + _app_state.projection_store.push_event( + "debug_step_guidance", + {"content": result}, + agent_id=agent.agent_id, + ) + + return result + + +async def _step_within_phase( + agent: AgentState, + phase_module: object, + ctx: PhaseContext, + next_step: int, +) -> str: + """Handle normal within-phase step advancement, appending any buffered user messages.""" + assert _app_state is not None + from ..state import drain_user_messages + + current_step = agent.step + + # Loop-back handling + if next_step <= current_step: + await phase_module.on_loop_back(current_step, next_step, ctx) + + agent.step = next_step + + step_names = getattr(phase_module, "STEP_NAMES", {}) + step_name = step_names.get(next_step, "") + + # Audit log + if agent.event_log is not None: + await agent.event_log.emit_step_transition(next_step, step_name, phase_module.TOTAL_STEPS) + + # Projection event + from ..events import build_step_advanced + _app_state.projection_store.push_event( + "agent_step_advanced", + build_step_advanced(next_step, step_name, total_steps=phase_module.TOTAL_STEPS), + agent_id=agent.agent_id, + ) + + guidance = phase_module.step_guidance(next_step, ctx) + result = format_step(guidance) + + # Drain buffered user messages and append to result + messages = drain_user_messages(_app_state) + if messages: + result += "\n\n" + format_user_messages(messages) + + if _app_state.debug: + _app_state.projection_store.push_event( + "debug_step_guidance", + {"content": result}, + agent_id=agent.agent_id, + ) + + return result + + +async def _step_phase_boundary( + agent: AgentState, + phase_module: object, + ctx: PhaseContext, +) -> str: + """Handle phase boundary: flush conversation, block for user message, return boundary response.""" + assert _app_state is not None + from ..state import drain_user_messages + + # Flush pending text/thinking in the projection without adding a duplicate + # step header (the step-N header was already emitted when we advanced TO + # this step in _step_within_phase). Emitting with an empty step_name + # causes the fold to flush pending content without creating a new StepEntry. + from ..events import build_step_advanced + _app_state.projection_store.push_event( + "agent_step_advanced", + build_step_advanced(agent.step, "", total_steps=phase_module.TOTAL_STEPS), + agent_id=agent.agent_id, + ) + + # Check for already-buffered messages first + messages = drain_user_messages(_app_state) + + if not messages: + # No messages yet — create Future and block until POST /api/chat resolves it + loop = asyncio.get_running_loop() + future = loop.create_future() + _app_state.phase_complete_future = future + + await future # yields to event loop; POST /api/chat will set_result(True) + + _app_state.phase_complete_future = None + messages = drain_user_messages(_app_state) + + successors = get_successor_phases(_app_state.phase) + return format_phase_boundary(_app_state.phase, messages, list(successors)) + + +# -- koan_complete_step ------------------------------------------------------- + @mcp.tool(name="koan_complete_step") async def koan_complete_step(thoughts: str = "") -> str: @@ -118,9 +283,13 @@ async def koan_complete_step(thoughts: str = "") -> str: call_id = begin_tool_call(agent, "koan_complete_step", {"thoughts": thoughts}, f"step {agent.step} → next") result_str: str | None = None try: - # Mark handshake observed (decoupled from stream parsing) agent.handshake_observed = True + # Step 0: phase handshake (initial call or post-koan_set_phase) + if agent.step == 0: + result_str = await _step_phase_handshake(agent) + return result_str + phase_module = agent.phase_module ctx = agent.phase_ctx current_step = agent.step @@ -135,55 +304,108 @@ async def koan_complete_step(thoughts: str = "") -> str: # Get next step next_step = phase_module.get_next_step(current_step, ctx) - # Loop-back handling - if next_step is not None and next_step <= current_step: - await phase_module.on_loop_back(current_step, next_step, ctx) + if next_step is None: + if not agent.is_primary: + # Non-primary agents (scouts) are done — signal completion + result_str = "All steps complete. You may now exit." + return result_str + # Phase boundary — block for user input + result_str = await _step_phase_boundary(agent, phase_module, ctx) + return result_str + + # Normal within-phase advancement + result_str = await _step_within_phase(agent, phase_module, ctx, next_step) + return result_str + + finally: + end_tool_call(agent, call_id, "koan_complete_step", result_str) - # Advance step - agent.step = next_step if next_step is not None else current_step - # Determine step name - step_names = getattr(phase_module, "STEP_NAMES", {}) - step_num = next_step if next_step is not None else current_step - step_name = step_names.get(step_num, "") +# -- koan_set_phase ----------------------------------------------------------- - # Emit audit event - if agent.event_log is not None: - await agent.event_log.emit_step_transition( - step_num, - step_name, - phase_module.TOTAL_STEPS, - ) +@mcp.tool(name="koan_set_phase") +async def koan_set_phase(phase: str) -> str: + """Commit transition to the next workflow phase. - # Emit agent_step_advanced to projection - if _app_state is not None: - from ..events import build_step_advanced - _app_state.projection_store.push_event( - "agent_step_advanced", - build_step_advanced(step_num, step_name, total_steps=phase_module.TOTAL_STEPS), - agent_id=agent.agent_id, - ) + Call this after the user has indicated what to do next. + The next koan_complete_step call will return step 1 guidance + for the new phase, including the role context for that phase. - # Return guidance or completion signal - if next_step is None: - result_str = "Phase complete." - return result_str + Args: + phase: Target phase name. Must be a valid successor of the current phase. + Valid successors are listed in the koan_complete_step response + when a phase completes. + """ + agent = _get_agent() + _check_or_raise(agent, "koan_set_phase", {"phase": phase}) - guidance = phase_module.step_guidance(next_step, ctx) - result_str = format_step(guidance) + call_id = begin_tool_call(agent, "koan_set_phase", {"phase": phase}, phase) + result_str: str | None = None + try: + assert _app_state is not None + + current = _app_state.phase + if not is_valid_transition(current, phase): + successors = get_successor_phases(current) + raise ToolError(json.dumps({ + "error": "invalid_transition", + "message": ( + f"'{phase}' is not a valid successor of '{current}'. " + f"Valid successors: {list(successors)}" + ), + })) + + # Look up new phase module + new_module = PHASE_GUIDANCE_MAP.get(phase) + if new_module is None: + raise ToolError(json.dumps({ + "error": "unknown_phase", + "message": f"Phase '{phase}' has no module implementation", + })) + + # Update driver state + _app_state.phase = phase + epic_dir = _resolve_epic_dir(agent) + if epic_dir: + epic_state = await load_epic_state(epic_dir) + await save_epic_state(epic_dir, {**epic_state, "phase": phase}) + + # Push artifact diff and phase_started event + from ..driver import _push_artifact_diff + _push_artifact_diff(_app_state) + _app_state.projection_store.push_event( + "phase_started", + {"phase": phase}, + agent_id=agent.agent_id, + ) - # In debug mode, surface the step guidance in the UI - if _app_state is not None and _app_state.debug: - _app_state.projection_store.push_event( - "debug_step_guidance", - {"content": result_str}, - agent_id=agent.agent_id, - ) + # Emit a step-advanced event (step=0) as visual phase-transition marker in the feed + phase_label = phase.replace("-", " ").title() + from ..events import build_step_advanced + _app_state.projection_store.push_event( + "agent_step_advanced", + build_step_advanced(0, f"→ {phase_label}"), + agent_id=agent.agent_id, + ) + + # Switch phase module and reset step counter + agent.phase_module = new_module + agent.step = 0 + agent.phase_ctx = PhaseContext( + epic_dir=epic_dir or "", + subagent_dir=agent.subagent_dir, + project_dir=_app_state.project_dir, + task_description=_app_state.task_description, + completed_phase=current, + ) + result_str = f"Phase set to '{phase}'. Call koan_complete_step to begin." return result_str finally: - end_tool_call(agent, call_id, "koan_complete_step", result_str) + end_tool_call(agent, call_id, "koan_set_phase", result_str) + +# -- koan_request_scouts ------------------------------------------------------- @mcp.tool(name="koan_request_scouts") async def koan_request_scouts(questions: list[dict] | None = None) -> str: @@ -200,7 +422,7 @@ async def koan_request_scouts(questions: list[dict] | None = None) -> str: result_str = "No scouts requested." return result_str - assert _app_state is not None, "app_state not initialized" + assert _app_state is not None semaphore = asyncio.Semaphore(_app_state.config.scout_concurrency) epic_dir = agent.phase_ctx.epic_dir @@ -255,6 +477,8 @@ async def run_scout(scout_task: dict) -> str | None: end_tool_call(agent, call_id, "koan_request_scouts", result_str) +# -- koan_ask_question --------------------------------------------------------- + @mcp.tool(name="koan_ask_question") async def koan_ask_question(questions: list[dict] | None = None) -> str: """Ask the user one or more clarifying questions. The UI renders these as @@ -290,7 +514,7 @@ async def koan_ask_question(questions: list[dict] | None = None) -> str: ) result_str: str | None = None try: - assert _app_state is not None, "app_state not initialized" + assert _app_state is not None future = await enqueue_interaction(agent, _app_state, "ask", {"questions": questions or []}) result = await future @@ -311,6 +535,8 @@ async def koan_ask_question(questions: list[dict] | None = None) -> str: end_tool_call(agent, call_id, "koan_ask_question", result_str) +# -- koan_review_artifact ------------------------------------------------------ + @mcp.tool(name="koan_review_artifact") async def koan_review_artifact(path: str = "", description: str = "") -> str: agent = _get_agent() @@ -322,7 +548,7 @@ async def koan_review_artifact(path: str = "", description: str = "") -> str: ) result_str: str | None = None try: - assert _app_state is not None, "app_state not initialized" + assert _app_state is not None try: async with aiofiles.open(path, "r") as f: @@ -351,84 +577,189 @@ async def koan_review_artifact(path: str = "", description: str = "") -> str: end_tool_call(agent, call_id, "koan_review_artifact", result_str) -@mcp.tool(name="koan_propose_workflow") -async def koan_propose_workflow(status: str = "", phases: list | None = None) -> str: +# -- koan_spawn_executor ------------------------------------------------------- + +@mcp.tool(name="koan_spawn_executor") +async def koan_spawn_executor( + story_id: str, + role: str, + retry_context: str | None = None, +) -> str: + """Spawn a planner or executor subagent for a story. + + Blocks until the spawned subagent exits. Returns a result summary. + The subagent's output artifacts (plan.md, verification output) will + be available in the story directory after this call returns. + + Args: + story_id: Story identifier (directory name in stories/) + role: "planner" generates plan.md; "executor" implements the plan + retry_context: Optional failure context from a prior executor attempt + """ agent = _get_agent() - _check_or_raise(agent, "koan_propose_workflow", {"status": status, "phases": phases}) + _check_or_raise(agent, "koan_spawn_executor", {"story_id": story_id, "role": role}) call_id = begin_tool_call( - agent, "koan_propose_workflow", {"status": status, "phases": phases or []}, - "proposing phases", + agent, "koan_spawn_executor", + {"story_id": story_id, "role": role}, + f"{role} for {story_id}", ) result_str: str | None = None try: - assert _app_state is not None, "app_state not initialized" - - # Normalise phases: accept both list[str] and list[dict]. - normalised: list[dict] = [] - for p in (phases or []): - if isinstance(p, str): - normalised.append({"phase": p, "context": "", "recommended": False}) - elif isinstance(p, dict): - normalised.append(p) - - chat_turns = [{ - "role": "orchestrator", - "status_report": status, - "recommended_phases": [ - { - "phase": p.get("phase", p.get("name", "")), - "context": p.get("context", p.get("description", "")), - "recommended": p.get("recommended", False), - } - for p in normalised - ], - }] - future = await enqueue_interaction( - agent, _app_state, "workflow-decision", - {"chat_turns": chat_turns}, + assert _app_state is not None + + if role not in ("planner", "executor"): + raise ToolError(json.dumps({ + "error": "invalid_role", + "message": f"role must be 'planner' or 'executor', got '{role}'", + })) + + epic_dir = _resolve_epic_dir(agent) + if not epic_dir: + raise ToolError(json.dumps({"error": "no_epic_dir", "message": "No epic directory available"})) + + story_dir = Path(epic_dir) / "stories" / story_id + if not story_dir.is_dir(): + raise ToolError(json.dumps({ + "error": "story_not_found", + "message": f"Story directory not found: {story_dir}", + })) + + ts_suffix = int(time.time() * 1000) + subagent_dir = await ensure_subagent_directory( + epic_dir, f"{role}-{story_id}-{ts_suffix}" ) - result = await future - if isinstance(result, dict) and "error" in result: - raise ToolError(json.dumps(result)) + task: dict = { + "role": role, + "epic_dir": epic_dir, + "subagent_dir": subagent_dir, + "project_dir": _app_state.project_dir, + "story_id": story_id, + } + if retry_context: + task["retryContext"] = retry_context + + from ..subagent import spawn_subagent + result = await spawn_subagent(task, _app_state) + + exit_code = result.exit_code + status = "succeeded" if exit_code == 0 else f"failed (exit code {exit_code})" + result_str = f"{role} for story '{story_id}' {status}." + return result_str + finally: + end_tool_call(agent, call_id, "koan_spawn_executor", result_str) - agent.phase_ctx.proposal_made = True - phase = result.get("phase", "") - context = result.get("context", "") - result_str = f"Selected: {phase}\n{context}".strip() +# -- Story management tools --------------------------------------------------- + +@mcp.tool(name="koan_select_story") +async def koan_select_story(story_id: str) -> str: + """Select the next story for execution.""" + agent = _get_agent() + _check_or_raise(agent, "koan_select_story", {"story_id": story_id}) + + call_id = begin_tool_call(agent, "koan_select_story", {"story_id": story_id}, story_id) + result_str: str | None = None + try: + assert _app_state is not None + epic_dir = _resolve_epic_dir(agent) + if not epic_dir: + raise ToolError(json.dumps({"error": "no_epic_dir"})) + + await save_story_state(epic_dir, story_id, { + "storyId": story_id, + "status": "selected", + "updatedAt": _now_iso(), + }) + result_str = f"Story '{story_id}' selected for execution." return result_str finally: - end_tool_call(agent, call_id, "koan_propose_workflow", result_str) + end_tool_call(agent, call_id, "koan_select_story", result_str) -@mcp.tool(name="koan_set_next_phase") -async def koan_set_next_phase(phase: str = "", instructions: str = "") -> str: +@mcp.tool(name="koan_complete_story") +async def koan_complete_story(story_id: str) -> str: + """Mark a story as successfully verified and completed.""" agent = _get_agent() - _check_or_raise(agent, "koan_set_next_phase", {"phase": phase, "instructions": instructions}) + _check_or_raise(agent, "koan_complete_story", {"story_id": story_id}) - call_id = begin_tool_call( - agent, "koan_set_next_phase", {"phase": phase, "instructions": instructions}, phase, - ) + call_id = begin_tool_call(agent, "koan_complete_story", {"story_id": story_id}, story_id) result_str: str | None = None try: - from_phase = getattr(agent.phase_ctx, "completed_phase", None) - if not is_valid_transition(from_phase, phase): - raise ToolError( - json.dumps({ - "error": "invalid_transition", - "message": f"Transition {from_phase} -> {phase} is not valid", - }) - ) + assert _app_state is not None + epic_dir = _resolve_epic_dir(agent) + if not epic_dir: + raise ToolError(json.dumps({"error": "no_epic_dir"})) + + await save_story_state(epic_dir, story_id, { + "storyId": story_id, + "status": "done", + "updatedAt": _now_iso(), + }) + result_str = f"Story '{story_id}' marked as done." + return result_str + finally: + end_tool_call(agent, call_id, "koan_complete_story", result_str) + + +@mcp.tool(name="koan_retry_story") +async def koan_retry_story(story_id: str, failure_summary: str) -> str: + """Send a story back for retry with a detailed failure summary.""" + agent = _get_agent() + _check_or_raise(agent, "koan_retry_story", {"story_id": story_id, "failure_summary": failure_summary}) + + call_id = begin_tool_call(agent, "koan_retry_story", {"story_id": story_id}, story_id) + result_str: str | None = None + try: + assert _app_state is not None + epic_dir = _resolve_epic_dir(agent) + if not epic_dir: + raise ToolError(json.dumps({"error": "no_epic_dir"})) + + existing = await load_story_state(epic_dir, story_id) + retry_count = existing.get("retryCount", 0) + 1 + + await save_story_state(epic_dir, story_id, { + "storyId": story_id, + "status": "retry", + "failureSummary": failure_summary, + "retryCount": retry_count, + "updatedAt": _now_iso(), + }) + result_str = f"Story '{story_id}' queued for retry (attempt {retry_count})." + return result_str + finally: + end_tool_call(agent, call_id, "koan_retry_story", result_str) - out_path = Path(agent.phase_ctx.subagent_dir) / "workflow-decision.json" - await atomic_write_json(out_path, {"next_phase": phase, "instructions": instructions}) - agent.phase_ctx.next_phase_set = True - result_str = f"Phase set to {phase}." + +@mcp.tool(name="koan_skip_story") +async def koan_skip_story(story_id: str, reason: str = "") -> str: + """Skip a story that is superseded or no longer needed.""" + agent = _get_agent() + _check_or_raise(agent, "koan_skip_story", {"story_id": story_id, "reason": reason}) + + call_id = begin_tool_call(agent, "koan_skip_story", {"story_id": story_id}, story_id) + result_str: str | None = None + try: + assert _app_state is not None + epic_dir = _resolve_epic_dir(agent) + if not epic_dir: + raise ToolError(json.dumps({"error": "no_epic_dir"})) + + state: dict = { + "storyId": story_id, + "status": "skipped", + "updatedAt": _now_iso(), + } + if reason: + state["skipReason"] = reason + + await save_story_state(epic_dir, story_id, state) + result_str = f"Story '{story_id}' skipped." return result_str finally: - end_tool_call(agent, call_id, "koan_set_next_phase", result_str) + end_tool_call(agent, call_id, "koan_skip_story", result_str) # -- ASGI wrapper -------------------------------------------------------------- diff --git a/tests/test_driver.py b/tests/test_driver.py index 002341f..31fba03 100644 --- a/tests/test_driver.py +++ b/tests/test_driver.py @@ -1,77 +1,17 @@ -# Tests for driver route_from_state -- pure routing logic. - -import copy +# Tests for driver -- the persistent orchestrator driver. +# route_from_state has been removed as part of the persistent orchestrator refactor. +# Driver now manages a single long-lived orchestrator process for the entire run. import pytest -from koan.driver import route_from_state - - -def _story(id: str, status: str) -> dict: - return {"storyId": id, "status": status} - - -class TestRouteFromState: - def test_retry_returns_retry(self): - stories = [_story("s1", "retry")] - result = route_from_state(stories) - assert result == {"action": "retry", "story_id": "s1"} - - def test_selected_returns_execute(self): - stories = [_story("s1", "selected")] - result = route_from_state(stories) - assert result == {"action": "execute", "story_id": "s1"} - - def test_retry_takes_priority_over_selected(self): - stories = [_story("s1", "selected"), _story("s2", "retry")] - result = route_from_state(stories) - assert result["action"] == "retry" - assert result["story_id"] == "s2" - - def test_all_done_returns_complete(self): - stories = [_story("s1", "done"), _story("s2", "done")] - result = route_from_state(stories) - assert result == {"action": "complete"} - - def test_all_skipped_returns_complete(self): - stories = [_story("s1", "skipped"), _story("s2", "skipped")] - result = route_from_state(stories) - assert result == {"action": "complete"} - - def test_done_and_skipped_mix_returns_complete(self): - stories = [_story("s1", "done"), _story("s2", "skipped")] - result = route_from_state(stories) - assert result == {"action": "complete"} - - def test_pending_only_returns_error(self): - stories = [_story("s1", "pending"), _story("s2", "pending")] - result = route_from_state(stories) - assert result["action"] == "error" - assert result["error"] is not None - - def test_empty_list_returns_error(self): - result = route_from_state([]) - assert result["action"] == "error" - assert result["error"] is not None +from koan.driver import driver_main, _push_artifact_diff - def test_retry_and_done_mix(self): - stories = [_story("s1", "done"), _story("s2", "retry")] - result = route_from_state(stories) - assert result["action"] == "retry" - assert result["story_id"] == "s2" - def test_selected_and_done_mix(self): - stories = [_story("s1", "done"), _story("s2", "selected")] - result = route_from_state(stories) - assert result["action"] == "execute" - assert result["story_id"] == "s2" +class TestDriverImports: + """Smoke test: driver module imports cleanly after refactor.""" + def test_driver_main_importable(self): + assert callable(driver_main) -class TestRouteFromStatePurity: - def test_no_mutation_same_result(self): - stories = [_story("s1", "retry"), _story("s2", "selected")] - stories_copy = copy.deepcopy(stories) - r1 = route_from_state(stories) - r2 = route_from_state(stories) - assert r1 == r2 - assert stories == stories_copy + def test_push_artifact_diff_importable(self): + assert callable(_push_artifact_diff) diff --git a/tests/test_interactions.py b/tests/test_interactions.py index 7b35e29..72bb45e 100644 --- a/tests/test_interactions.py +++ b/tests/test_interactions.py @@ -30,9 +30,9 @@ class FakeAppState: active_interaction: PendingInteraction | None = None interaction_queue: deque[PendingInteraction] = field(default_factory=deque) interaction_queue_max: int = 8 - frozen_logs: list = field(default_factory=list) epic_dir: str | None = None projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) + phase_complete_future: asyncio.Future | None = None def _make_interaction( @@ -150,86 +150,6 @@ async def test_artifact_review_stale_returns_409(self): resp = client.post("/api/artifact-review", json={"response": "Accept"}) assert resp.status_code == 409 - @pytest.mark.anyio - async def test_workflow_decision_stale_returns_409(self): - from starlette.testclient import TestClient - - from koan.state import AppState - from koan.web.app import create_app - - app_state = AppState() - app = create_app(app_state) - client = TestClient(app, raise_server_exceptions=False) - resp = client.post("/api/workflow-decision", json={"phase": "plan"}) - assert resp.status_code == 409 - - -# -- TestWorkflowDecisionValidation ------------------------------------------- - -class TestWorkflowDecisionValidation: - def _setup_workflow(self): - """Create app with an active workflow-decision interaction.""" - from starlette.testclient import TestClient - - from koan.state import AppState - from koan.web.app import create_app - - app_state = AppState() - interaction = _make_interaction( - interaction_type="workflow-decision", - payload={ - "chat_turns": [{ - "role": "orchestrator", - "status_report": "test", - "recommended_phases": [ - {"phase": "tech-plan", "context": "", "recommended": True}, - {"phase": "core-flows", "context": "", "recommended": False}, - ], - }], - }, - ) - app_state.active_interaction = interaction - - app = create_app(app_state) - client = TestClient(app, raise_server_exceptions=False) - return client, interaction - - @pytest.mark.anyio - async def test_valid_phase_resolves_future(self): - client, interaction = self._setup_workflow() - resp = client.post( - "/api/workflow-decision", - json={"phase": "tech-plan", "context": "go", "token": interaction.token}, - ) - assert resp.status_code == 200 - assert resp.json()["ok"] is True - assert interaction.future.done() - assert interaction.future.result()["phase"] == "tech-plan" - - @pytest.mark.anyio - async def test_empty_phase_rejected(self): - client, interaction = self._setup_workflow() - resp = client.post( - "/api/workflow-decision", - json={"phase": "", "context": "", "token": interaction.token}, - ) - assert resp.status_code == 422 - assert resp.json()["error"] == "empty_phase" - # Interaction stays active (future not resolved) - assert not interaction.future.done() - - @pytest.mark.anyio - async def test_stale_phase_rejected(self): - client, interaction = self._setup_workflow() - resp = client.post( - "/api/workflow-decision", - json={"phase": "execution", "context": "", "token": interaction.token}, - ) - assert resp.status_code == 422 - assert resp.json()["error"] == "invalid_phase" - # Interaction stays active (future not resolved) - assert not interaction.future.done() - # -- TestFIFOActivation ------------------------------------------------------- @@ -318,6 +238,21 @@ async def test_next_queued_activated_after_cancel(self): assert active_a.future.done() assert app_state.active_interaction is queued_b + @pytest.mark.anyio + async def test_phase_complete_future_cleared_on_exit(self): + """_cancel_pending_interactions clears phase_complete_future (QR4).""" + from koan.subagent import _cancel_pending_interactions + + app_state = FakeAppState() + loop = asyncio.get_running_loop() + future = loop.create_future() + app_state.phase_complete_future = future + + _cancel_pending_interactions("agent-1", app_state) + + assert future.done() + assert app_state.phase_complete_future is None + # -- TestArtifactReviewResolution --------------------------------------------- diff --git a/tests/test_permissions.py b/tests/test_permissions.py index 2a4ce31..9b504ab 100644 --- a/tests/test_permissions.py +++ b/tests/test_permissions.py @@ -27,8 +27,18 @@ class TestReadToolsAlwaysAllowed: def test_known_roles(self): for role in ALL_ROLES: for tool in READ_TOOLS: + # bash is phase-gated for orchestrator (requires execution/impl-validation phase) + if role == "orchestrator" and tool == "bash": + continue r = check_permission(role, tool) assert r["allowed"], f"{tool} should be allowed for {role}" + + def test_orchestrator_bash_needs_phase(self): + """bash is phase-gated for the orchestrator role.""" + r = check_permission("orchestrator", "bash", current_phase="intake") + assert not r["allowed"] + r = check_permission("orchestrator", "bash", current_phase="execution") + assert r["allowed"] def test_unknown_role(self): for tool in READ_TOOLS: @@ -61,19 +71,95 @@ def test_intake_step_1_allows(self): r = check_permission("intake", tool, current_step=1) assert r["allowed"], f"intake step 1 should allow {tool}" - def test_brief_writer_step_1_blocks(self): + def test_orchestrator_brief_generation_step_1_blocks(self): + """Orchestrator at brief-generation step 1 blocks write/edit/scouts/ask.""" for tool in self.blocked: - r = check_permission("brief-writer", tool, current_step=1) - assert not r["allowed"], f"brief-writer step 1 should block {tool}" - - def test_brief_writer_step_2_allows(self): - # Only check tools that brief-writer actually has in its role set. - bw_allowed = ROLE_PERMISSIONS["brief-writer"] + r = check_permission( + "orchestrator", tool, + current_step=1, + current_phase="brief-generation", + ) + assert not r["allowed"], ( + f"orchestrator brief-generation step 1 should block {tool}" + ) + + def test_orchestrator_brief_generation_step_2_allows_write(self): + """Orchestrator at brief-generation step 2 allows write/edit.""" + for tool in ("write", "edit"): + r = check_permission( + "orchestrator", tool, + current_step=2, + current_phase="brief-generation", + ) + assert r["allowed"], ( + f"orchestrator brief-generation step 2 should allow {tool}" + ) + + def test_orchestrator_intake_step_1_allows_all(self): + """Orchestrator at intake phase step 1 allows all base tools.""" for tool in self.blocked: - if tool not in bw_allowed: - continue - r = check_permission("brief-writer", tool, current_step=2) - assert r["allowed"], f"brief-writer step 2 should allow {tool}" + r = check_permission( + "orchestrator", tool, + current_step=1, + current_phase="intake", + ) + assert r["allowed"], f"orchestrator intake step 1 should allow {tool}" + + +# -- Orchestrator phase-aware permissions ------------------------------------- + +class TestOrchestratorPhasePermissions: + def test_koan_request_scouts_intake_allowed(self): + r = check_permission("orchestrator", "koan_request_scouts", current_phase="intake") + assert r["allowed"] + + def test_koan_request_scouts_brief_generation_denied(self): + r = check_permission("orchestrator", "koan_request_scouts", current_phase="brief-generation") + assert not r["allowed"] + + def test_koan_review_artifact_brief_generation_allowed(self): + r = check_permission("orchestrator", "koan_review_artifact", current_phase="brief-generation") + assert r["allowed"] + + def test_koan_review_artifact_execution_denied(self): + r = check_permission("orchestrator", "koan_review_artifact", current_phase="execution") + assert not r["allowed"] + + def test_koan_spawn_executor_execution_allowed(self): + r = check_permission("orchestrator", "koan_spawn_executor", current_phase="execution") + assert r["allowed"] + + def test_koan_spawn_executor_intake_denied(self): + r = check_permission("orchestrator", "koan_spawn_executor", current_phase="intake") + assert not r["allowed"] + + def test_story_tools_execution_allowed(self): + for tool in ("koan_select_story", "koan_complete_story", "koan_retry_story", "koan_skip_story"): + r = check_permission("orchestrator", tool, current_phase="execution") + assert r["allowed"], f"{tool} should be allowed during execution" + + def test_story_tools_intake_denied(self): + for tool in ("koan_select_story", "koan_complete_story", "koan_retry_story", "koan_skip_story"): + r = check_permission("orchestrator", tool, current_phase="intake") + assert not r["allowed"], f"{tool} should not be allowed during intake" + + def test_bash_execution_allowed(self): + r = check_permission("orchestrator", "bash", current_phase="execution") + assert r["allowed"] + + def test_bash_intake_denied(self): + r = check_permission("orchestrator", "bash", current_phase="intake") + assert not r["allowed"] + + def test_koan_set_phase_always_allowed(self): + for phase in ("intake", "brief-generation", "execution", "implementation-validation"): + r = check_permission("orchestrator", "koan_set_phase", current_phase=phase) + assert r["allowed"], f"koan_set_phase should be allowed in phase '{phase}'" + + def test_koan_complete_step_always_allowed(self): + for phase in ("intake", "brief-generation", "execution"): + r = check_permission("orchestrator", "koan_complete_step", current_phase=phase) + assert r["allowed"] # -- Exhaustive role x tool matrix --------------------------------------------- @@ -83,9 +169,12 @@ def _build_matrix(): Expected result: allowed iff the tool is in READ_TOOLS or in that role's ROLE_PERMISSIONS entry. Step is set to 2 to avoid step-1 blocking. + Only applies to non-orchestrator roles (orchestrator is phase-aware). """ cases = [] for role in ALL_ROLES: + if role == "orchestrator": + continue # orchestrator uses phase-aware checks, tested separately allowed_set = ROLE_PERMISSIONS[role] | READ_TOOLS for tool in sorted(ALL_KOAN_TOOLS): expected = tool in allowed_set @@ -98,7 +187,7 @@ def _build_matrix(): class TestExhaustiveRoleToolMatrix: - """Mechanically verify every role x tool combination against ROLE_PERMISSIONS.""" + """Mechanically verify every non-orchestrator role x tool combination.""" @pytest.mark.parametrize("role,tool,expected", _MATRIX, ids=_MATRIX_IDS) def test_role_tool(self, role, tool, expected): @@ -108,42 +197,6 @@ def test_role_tool(self, role, tool, expected): ) -# -- Exhaustive step-1 matrix ------------------------------------------------- - -def _build_step1_matrix(): - """For brief-writer at step 1, verify blocked tools are denied - and all other allowed tools still pass. Intake no longer has a - step-1 gate so its step-1 expectations match normal permissions.""" - cases = [] - for role in ("intake", "brief-writer"): - allowed_set = ROLE_PERMISSIONS[role] | READ_TOOLS - for tool in sorted(ALL_KOAN_TOOLS): - # Only brief-writer blocks tools at step 1; intake does not. - if role == "brief-writer" and tool in STEP_1_BLOCKED_TOOLS: - expected = False - elif tool in allowed_set: - expected = True - else: - expected = False - cases.append((role, tool, expected)) - return cases - - -_STEP1_MATRIX = _build_step1_matrix() -_STEP1_IDS = [f"{role}-step1-{tool}-{'allow' if exp else 'deny'}" for role, tool, exp in _STEP1_MATRIX] - - -class TestExhaustiveStep1Matrix: - """Verify step-1 blocking interacts correctly with every tool for affected roles.""" - - @pytest.mark.parametrize("role,tool,expected", _STEP1_MATRIX, ids=_STEP1_IDS) - def test_step1(self, role, tool, expected): - r = check_permission(role, tool, current_step=1) - assert r["allowed"] == expected, ( - f"role={role} step=1 tool={tool}: expected allowed={expected}, got {r}" - ) - - # -- Path scoping -------------------------------------------------------------- class TestPathScoping: @@ -187,6 +240,27 @@ def test_write_at_epic_root_allowed(self): ) assert r["allowed"] + def test_orchestrator_write_inside_epic_allowed(self): + r = check_permission( + "orchestrator", "write", + epic_dir=self.epic, + tool_args={"path": "/tmp/epic/brief.md"}, + current_phase="brief-generation", + current_step=2, + ) + assert r["allowed"] + + def test_orchestrator_write_outside_epic_denied(self): + r = check_permission( + "orchestrator", "write", + epic_dir=self.epic, + tool_args={"path": "/home/user/evil.sh"}, + current_phase="intake", + current_step=2, + ) + assert not r["allowed"] + assert "outside epic directory" in r["reason"] + # -- Executor unrestricted write ----------------------------------------------- diff --git a/tests/test_phases.py b/tests/test_phases.py index 12e1424..26dddf9 100644 --- a/tests/test_phases.py +++ b/tests/test_phases.py @@ -13,7 +13,6 @@ from koan.phases import cross_artifact_validation from koan.phases import executor from koan.phases import orchestrator -from koan.phases import workflow_orchestrator from koan.phases import scout @@ -86,35 +85,6 @@ def test_step_3_completes(self): assert brief_writer.get_next_step(3, _ctx()) is None -# -- Workflow Orchestrator ----------------------------------------------------- - -class TestWorkflowOrchestrator: - def test_step_2_both_gates_met(self): - ctx = _ctx(proposal_made=True, next_phase_set=True) - assert workflow_orchestrator.get_next_step(2, ctx) is None - - def test_step_2_proposal_only_loops(self): - ctx = _ctx(proposal_made=True, next_phase_set=False) - assert workflow_orchestrator.get_next_step(2, ctx) == 2 - - def test_validate_step_2_no_proposal(self): - result = workflow_orchestrator.validate_step_completion(2, _ctx()) - assert result is not None - assert "koan_propose_workflow" in result - - def test_validate_step_2_proposal_no_phase(self): - result = workflow_orchestrator.validate_step_completion(2, _ctx(proposal_made=True)) - assert result is not None - assert "koan_set_next_phase" in result - - def test_validate_step_2_both_gates_met(self): - ctx = _ctx(proposal_made=True, next_phase_set=True) - assert workflow_orchestrator.validate_step_completion(2, ctx) is None - - def test_step_1_to_2(self): - assert workflow_orchestrator.get_next_step(1, _ctx()) == 2 - - # -- Orchestrator -------------------------------------------------------------- class TestOrchestrator: @@ -181,11 +151,3 @@ def test_brief_writer_purity(self): r2 = brief_writer.get_next_step(2, ctx) assert r1 == r2 assert ctx == ctx_copy - - def test_workflow_orchestrator_purity(self): - ctx = _ctx(proposal_made=True, next_phase_set=False) - ctx_copy = copy.deepcopy(ctx) - r1 = workflow_orchestrator.get_next_step(2, ctx) - r2 = workflow_orchestrator.get_next_step(2, ctx) - assert r1 == r2 - assert ctx == ctx_copy diff --git a/tests/test_projections.py b/tests/test_projections.py index c8c5511..cd8c459 100644 --- a/tests/test_projections.py +++ b/tests/test_projections.py @@ -14,7 +14,6 @@ BaseToolEntry, Conversation, ConversationFocus, - DecisionFocus, Projection, ProjectionStore, QuestionFocus, @@ -470,18 +469,6 @@ def test_artifact_reviewed_resets_to_conversation_focus(self): r = fold(p, _e("artifact_reviewed", {"token": "t2", "cancelled": False}, agent_id="a1")) assert isinstance(r.run.focus, ConversationFocus) - def test_workflow_decision_requested_sets_decision_focus(self): - p = _proj_with_primary("a1") - r = fold(p, _e("workflow_decision_requested", {"token": "t3", "chat_turns": []}, agent_id="a1")) - assert isinstance(r.run.focus, DecisionFocus) - assert r.run.focus.token == "t3" - - def test_workflow_decided_resets_to_conversation_focus(self): - p = _proj_with_primary("a1") - p = fold(p, _e("workflow_decision_requested", {"token": "t3", "chat_turns": []}, agent_id="a1")) - r = fold(p, _e("workflow_decided", {"token": "t3", "cancelled": False}, agent_id="a1")) - assert isinstance(r.run.focus, ConversationFocus) - # --------------------------------------------------------------------------- # fold: settings diff --git a/tests/test_subagent.py b/tests/test_subagent.py index d6a3050..fa13a25 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -34,17 +34,19 @@ class FakeAppState: active_interaction: Any = None interaction_queue: Any = field(default_factory=lambda: __import__("collections").deque()) interaction_queue_max: int = 8 - frozen_logs: list = field(default_factory=list) epic_dir: str | None = None projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) run_installations: dict = field(default_factory=dict) _active_processes: dict = field(default_factory=dict) + phase_complete_future: Any = None + project_dir: str = "" + task_description: str = "" class FakeRunner: name = "fake" - def build_command(self, boot_prompt, mcp_url, model): + def build_command(self, boot_prompt, mcp_url, model, system_prompt="", **kwargs): # Return a command that exits immediately with code 1 return ["python3", "-c", "import sys; sys.exit(1)"] @@ -56,7 +58,7 @@ class FakeRunnerSuccess: """Runner that exits 0. Handshake is set via MCP path, not stream.""" name = "fake" - def build_command(self, boot_prompt, mcp_url, model): + def build_command(self, boot_prompt, mcp_url, model, system_prompt="", **kwargs): return ["python3", "-c", "pass"] def parse_stream_event(self, line): diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index 7681b3f..b9175a0 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -449,43 +449,6 @@ def test_live_page_when_running(client, app_state): assert "root" in resp.text -# -- Workflow interaction SSE payload ----------------------------------------- - -def test_workflow_interaction_sse_payload_shape(app_state): - from koan.events import build_workflow_decision_requested - - token = "tok" - chat_turns = [{ - "role": "orchestrator", - "status_report": "Done", - "recommended_phases": [{ - "phase": "tech-plan", - "context": "next", - "recommended": True, - }], - }] - - # Setup: need a run with a running primary agent before focus can be set - app_state.projection_store.push_event("run_started", {"profile": "balanced", "installations": {}, "scout_concurrency": 8}) - app_state.projection_store.push_event("agent_spawned", { - "agent_id": "agent-1", "role": "intake", "is_primary": True, "started_at_ms": 0, - }, agent_id="agent-1") - app_state.projection_store.push_event( - "workflow_decision_requested", - build_workflow_decision_requested(token, chat_turns), - agent_id="agent-1", - ) - - # Verify projection holds focus as DecisionFocus (new model) - from koan.projections import DecisionFocus - proj = app_state.projection_store.projection - assert proj.run is not None - focus = proj.run.focus - assert isinstance(focus, DecisionFocus) - assert focus.token == "tok" - turns = focus.chat_turns - assert turns[0]["recommended_phases"][0]["phase"] == "tech-plan" - # -- Old model-config route removed ------------------------------------------ From 036abfbf29a55fd4a54e26fa6c0abb632d2b9355 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 13:16:34 +0700 Subject: [PATCH 294/412] docs: update architecture docs for persistent orchestrator Update all spoke documents to reflect the persistent orchestrator model: single long-lived process, phase-boundary blocking, chat messaging, phase-aware permissions, and simplified role matrix. --- AGENTS.md | 98 +++++++++++++++++++++++++------------ docs/architecture.md | 34 ++++++------- docs/epic-brief.md | 25 ++++------ docs/intake-loop.md | 2 +- docs/ipc.md | 112 +++++++++++++++++++++++++++++-------------- docs/projections.md | 35 ++++++++------ docs/state.md | 104 +++++++++++++++------------------------- docs/subagents.md | 108 +++++++++++++++++++++-------------------- 8 files changed, 284 insertions(+), 234 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 612a5ff..d7778c2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,11 +5,11 @@ Full architecture documentation: **[docs/architecture.md](docs/architecture.md)* Spoke documents: - [docs/subagents.md](docs/subagents.md) -- spawn lifecycle, task manifest, step-first workflow, permissions -- [docs/ipc.md](docs/ipc.md) -- HTTP MCP tool calls, blocking interactions, scout spawning -- [docs/state.md](docs/state.md) -- driver/LLM boundary, epic and story state, routing rules -- [docs/intake-loop.md](docs/intake-loop.md) -- confidence-gated loop, non-linear step progression, prompt engineering +- [docs/ipc.md](docs/ipc.md) -- HTTP MCP tool calls, blocking interactions, scout spawning, phase-boundary blocking +- [docs/state.md](docs/state.md) -- driver/LLM boundary, epic and story state, orchestrator state +- [docs/intake-loop.md](docs/intake-loop.md) -- three-step intake design, review gate, prompt engineering - [docs/projections.md](docs/projections.md) -- versioned event log, fold function, projection shape, SSE protocol, version-negotiated catch-up -- [docs/epic-brief.md](docs/epic-brief.md) -- brief artifact, brief-writer subagent, downstream references +- [docs/epic-brief.md](docs/epic-brief.md) -- brief artifact, brief-generation phase, downstream references - [docs/artifact-review.md](docs/artifact-review.md) -- artifact review protocol, review loop, reusability - [docs/token-streaming.md](docs/token-streaming.md) -- runner stdout parsing, SSE delta path @@ -27,53 +27,91 @@ both worlds. ## 2. Step-First Workflow Pattern (critical) -Every subagent is a CLI process (`claude`, `codex`, or `gemini`) that connects -to the driver's HTTP MCP endpoint at `http://localhost:{port}/mcp?agent_id={id}`. -The subagent receives tools via MCP and calls them over HTTP. The driver handles -all tool logic in-process. +The orchestrator is a single long-lived CLI process (`claude`, `codex`, or +`gemini`) that runs the entire workflow. It connects to the driver's HTTP MCP +endpoint at `http://localhost:{port}/mcp?agent_id={id}` and receives tools via +MCP. The driver handles all tool logic in-process. -**The first thing any subagent does is call `koan_complete_step`.** The spawn -prompt contains _only_ this directive. The tool returns step 1 instructions. -This establishes the calling pattern before the LLM sees complex instructions. +**The first thing the orchestrator does is call `koan_complete_step`.** The +spawn prompt contains _only_ this directive. The tool returns step 1 +instructions. This establishes the calling pattern before the LLM sees complex +instructions. ``` -Boot prompt: "You are a koan {role} agent. Call koan_complete_step to receive your instructions." +Boot prompt: "You are a koan orchestrator agent. Call koan_complete_step to receive your instructions." | LLM calls koan_complete_step (step 0 -> 1 transition) -Tool returns: Step 1 instructions (rich context, task details, guidance) +Tool returns: Step 1 instructions (phase role context + task details) | LLM does work... | LLM calls koan_complete_step -Tool returns: Step 2 instructions (or "Phase complete.") +Tool returns: Step 2 instructions (or phase-boundary response) ``` -Step progression is normally linear, but phase modules may override -`get_next_step()` to implement non-linear flows. The intake phase loops steps -2-4 until a confidence gate is satisfied. See +When a phase ends, `koan_complete_step` blocks for a user message and returns +the transition context (user message + valid next phases). The orchestrator +converses, then calls `koan_set_phase` to commit the transition. The step +counter resets to 0 on each `koan_set_phase` call, then advances to 1 on the +next `koan_complete_step`. Phase-specific role context (`SYSTEM_PROMPT`) is +injected into that step-1 response. + +Step progression is normally linear within a phase, but phase modules may +override `get_next_step()` to implement non-linear flows. See [docs/intake-loop.md](docs/intake-loop.md). -## 3. Driver Determinism +Planner, executor, and scout subagents are still separate processes spawned by +the orchestrator via `koan_spawn_executor` and `koan_request_scouts`. + +## 3. Driver Determinism (partially relaxed) + +The driver (`koan/driver.py`) spawns the orchestrator and awaits its exit. +Phase routing is driven by the orchestrator via `koan_set_phase` rather than +the driver's routing loop. -The driver (`koan/driver.py`) reads JSON state files and exit codes, applies -routing rules, and spawns the next subagent. It never makes judgment calls or -parses free-text. +The driver still: +- Validates every phase transition (`is_valid_transition()` in the tool handler) +- Updates `epic-state.json` atomically +- Emits projection events +- Enforces the permission fence + +The driver does **not** decide which phase runs next. Invalid phase strings +raise `ToolError`; valid transitions are committed. All routing decisions flow +through typed tool parameters, not free text. ## 4. Default-Deny Permissions Every tool call passes through a role-based permission fence. Unknown roles -and tools are blocked. Planning roles can only write inside the epic directory. - -The fence also supports step-level gating for individual roles: the intake -phase blocks side-effecting tools during its read-only Extract step (step 1). +and tools are blocked. The orchestrator role uses **phase-aware permissions**: +available tools vary by `current_phase`. Planning-phase write access is +path-scoped to the epic directory. + +The fence also supports step-level gating: `write` and `edit` are blocked +during brief-generation step 1 (the read step). + +**Orchestrator tool availability by phase:** + +| Tool | Available phases | +|------|-----------------| +| `koan_complete_step` | All phases | +| `koan_set_phase` | All phases (blocked mid-story during execution) | +| `koan_ask_question` | All phases | +| `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation` | +| `koan_review_artifact` | `intake`, `brief-generation`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `implementation-validation` | +| `koan_spawn_executor` | `execution` only | +| `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | `execution` only | +| `write`, `edit` (epic_dir scoped) | All phases except `brief-generation` step 1 | +| `bash` | `execution`, `implementation-validation` | ## 5. Need-to-Know Prompts -Boot prompt is one sentence. System prompt has role identity, no task details. -Task details arrive via step 1 guidance after the tool-calling pattern is -established. +Boot prompt is one sentence. System prompt is minimal (orchestrator identity +only). Phase-specific role context arrives via step 1 guidance after +`koan_set_phase` is called -- the orchestrator doesn't know its next role until +`koan_complete_step` tells it. ## 6. Directory-as-Contract -The subagent directory is the sole interface between parent and child. -Two well-known JSON files plus the MCP endpoint URL: +The orchestrator has one subagent directory for the entire run. Planner, +executor, and scout subagents each get their own directory per the standard +contract: | File | Writer | Reader | Purpose | | -------------- | ------------------------- | ------------------------------ | ------------------ | diff --git a/docs/architecture.md b/docs/architecture.md index 2ad4be7..15d88c3 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,7 +1,7 @@ # Koan Architecture -Koan is a deterministic workflow that spawns isolated LLM subagents to plan and -execute complex coding tasks. This document captures the design invariants, +Koan coordinates coding task planning and execution through a single long-lived +orchestrator LLM process that runs the entire workflow in one continuous session. This document captures the design invariants, principles, and pitfalls that govern the codebase. **Spoke documents** cover subsystems in depth: @@ -9,15 +9,15 @@ principles, and pitfalls that govern the codebase. - [Subagents](./subagents.md) -- spawn lifecycle, boot protocol, step-first workflow, phase dispatch, permissions, model tiers - [IPC](./ipc.md) -- HTTP MCP inter-process communication, blocking tool calls, - scout spawning + scout spawning, phase-boundary blocking, chat message delivery - [Token Streaming](./token-streaming.md) -- runner stdout parsing, SSE delta path - [State & Driver](./state.md) -- the driver/LLM boundary, JSON vs markdown - ownership, epic and story state, routing rules + ownership, epic and story state, orchestrator state - [Projections](./projections.md) -- versioned event log, pure fold, JSON Patch protocol, projection model, camelCase wire format -- [Intake Loop](./intake-loop.md) -- confidence-gated investigation loop, - non-linear step progression, prompt engineering principles -- [Epic Brief](./epic-brief.md) -- brief artifact, brief-writer subagent, downstream references +- [Intake Loop](./intake-loop.md) -- three-step intake design, review gate, + prompt engineering principles +- [Epic Brief](./epic-brief.md) -- brief artifact, brief-generation phase, downstream references - [Artifact Review](./artifact-review.md) -- artifact review protocol, review loop, reusability --- @@ -76,19 +76,15 @@ Three reinforcement mechanisms make this robust across model capability levels: | **Recency** | `format_step()` appends "WHEN DONE: Call koan_complete_step..." last | LLMs weight end-of-context instructions heavily | | **Muscle memory** | By step 2+ the LLM has called the tool N times | Pattern is locked in through repetition | -### 3. Driver determinism +### 3. Driver determinism (partially relaxed) -The driver (`koan/driver.py`) is a deterministic state machine. It reads JSON -state files and exit codes, applies routing rules, and spawns the next subagent. -It never makes judgment calls, parses free-text output, or adapts to LLM -behavior. - -**Routing priority** in the story loop: - -1. `retry` status -> re-execute (retry takes precedence over new work) -2. `selected` status -> plan + execute -3. All stories `done` or `skipped` -> epic complete -4. None of the above -> error ("orchestrator may have exited without a routing decision") +The driver (`koan/driver.py`) spawns the orchestrator and awaits its exit. +Phase routing is driven by the orchestrator via `koan_set_phase` rather than +the driver's routing loop. The driver still validates every transition +(`is_valid_transition()` in the tool handler), updates `epic-state.json` +atomically, emits projection events, and enforces the permission fence. It +never parses free text or makes judgment calls. All routing decisions flow +through typed tool parameters. ### 4. Default-deny permissions diff --git a/docs/epic-brief.md b/docs/epic-brief.md index 1a7d3c9..d193b56 100644 --- a/docs/epic-brief.md +++ b/docs/epic-brief.md @@ -48,10 +48,10 @@ The brief sits between intake and core-flows: --- -## Brief-Writer Subagent +## Brief-Generation Phase -Role: `"brief-writer"`. Model tier: `"strong"` (synthesis from intake context -requires genuine reasoning). +The orchestrator handles the brief-generation phase using step guidance from +`koan/phases/brief_writer.py`. Model tier for the orchestrator: `"strong"`. ### Step Progression @@ -75,21 +75,12 @@ Step 3 (Finalize): `koan/phases/brief_writer.py` requires at least one `koan_review_artifact` call before `koan_complete_step` is allowed. -### Permissions - -```python -# koan/lib/permissions.py -"brief-writer": { - "koan_complete_step", - "koan_review_artifact", - "edit", - "write", - # No koan_ask_question -- uses artifact review, not structured questions. - # No koan_request_scouts -- all codebase context arrives via landscape.md. -} -``` +### Permissions during brief-generation -Write/edit access is path-scoped to the epic directory. +During `brief-generation`, the orchestrator has access to `koan_review_artifact`, +`write`, and `edit` (path-scoped to epic directory). `koan_request_scouts` and +`koan_ask_question` are not used — all codebase context arrives via +`landscape.md`. Write/edit access is blocked in step 1 (the Read step). --- diff --git a/docs/intake-loop.md b/docs/intake-loop.md index d3e47c3..0d47d27 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -149,7 +149,7 @@ artifacts. ### Don't re-add a step-1 read-only gate for intake Intake's Gather step needs all tools (especially `koan_request_scouts`) from -the start. The brief-writer still has a step-1 read-only gate, but intake +the start. The brief-generation phase still has a step-1 read-only gate, but intake does not. ### Don't add a confidence loop diff --git a/docs/ipc.md b/docs/ipc.md index 190b30a..b3590e2 100644 --- a/docs/ipc.md +++ b/docs/ipc.md @@ -18,27 +18,30 @@ that handles both the web dashboard and the MCP tool endpoint. When a tool call arrives, the server looks up the agent's state by `agent_id` in an in-process registry and handles the call directly. -Three tool calls involve blocking interactions -- the HTTP request is held open -while the driver awaits an external response: - -| Tool | What blocks | Who responds | -| ---------------------- | ----------------------- | ------------------------------ | -| `koan_ask_question` | User input needed | User via web UI | -| `koan_request_scouts` | Scout subagents running | Driver (after scouts complete) | -| `koan_review_artifact` | User review needed | User via web UI | -| `koan_propose_workflow`| User workflow decision | User via web UI | - -User-facing tools (`koan_ask_question`, `koan_review_artifact`, -`koan_propose_workflow`) go through the `PendingInteraction` queue on -`AppState`. The MCP handler creates an `asyncio.Future`, stores it in -`AgentState.pending_tool`, enqueues a `PendingInteraction` on `AppState`, and -awaits the Future. The HTTP connection stays open until the Future resolves. +Four interactions involve blocking -- the HTTP request is held open while the +driver awaits an external response: + +| Mechanism | What blocks | Who responds | +| ----------------------- | ---------------------------- | ------------------------------ | +| `koan_ask_question` | User input needed | User via web UI | +| `koan_review_artifact` | User review needed | User via web UI | +| `koan_request_scouts` | Scout subagents running | Driver (after scouts complete) | +| Phase-boundary blocking | Phase complete, next unknown | User via `POST /api/chat` | + +User-facing tool calls (`koan_ask_question`, `koan_review_artifact`) go through +the `PendingInteraction` queue on `AppState`. The MCP handler creates an +`asyncio.Future`, stores it in `AgentState.pending_tool`, enqueues a +`PendingInteraction` on `AppState`, and awaits the Future. The HTTP connection +stays open until the Future resolves. `koan_request_scouts` is handled entirely inline: the handler spawns scouts via `asyncio.gather` of `spawn_subagent` calls (bounded by a semaphore), collects their results, and returns directly. No `PendingInteraction` is created; the HTTP connection is held open only by the `await asyncio.gather(...)` call. +Phase-boundary blocking uses `AppState.phase_complete_future` directly (not +`PendingInteraction`). See [Phase-Boundary Blocking](#phase-boundary-blocking). + There is no polling and no intermediate files for any of these flows. --- @@ -54,12 +57,11 @@ When a user-facing blocking tool is called: and enqueues a `PendingInteraction` on `AppState.interaction_queue` 3. If no interaction is currently active, the interaction is promoted to `AppState.active_interaction` and an SSE event is pushed to browsers - (question form, review form, or workflow-decision form) + (question form, or review form) 4. Handler `await`s the Future -- HTTP connection stays open 5. User fills the form in the web UI and submits: - `POST /api/answer` resolves the Future for `koan_ask_question` - `POST /api/artifact-review` resolves it for `koan_review_artifact` - - `POST /api/workflow-decision` resolves it for `koan_propose_workflow` 6. Handler returns the resolved value as the MCP tool result; the next queued interaction (if any) is promoted to active @@ -85,7 +87,7 @@ subagent <---tool result (answer)----------- + The `PendingInteraction` object stored in `AppState.active_interaction` (or queued in `AppState.interaction_queue`): -- `type` -- one of `"ask"`, `"artifact-review"`, `"workflow-decision"` +- `type` -- one of `"ask"`, `"artifact-review"` - `agent_id` -- the agent that issued the blocking call - `token` -- UUID for SSE correlation - `payload` -- type-specific request data @@ -220,30 +222,66 @@ See [artifact-review.md](./artifact-review.md) for the full protocol. --- -## Workflow Decision Flow +## Phase-Boundary Blocking + +When the orchestrator finishes a phase (`get_next_step` returns `None`), +`koan_complete_step` blocks for user input before returning the phase-boundary +response. This uses `AppState.phase_complete_future` directly, not the +`PendingInteraction` queue. ``` -subagent calls koan_propose_workflow({ status: "...", phases: [...] }) - -> MCP endpoint checks permissions - -> normalises phases list to list[dict] - -> creates asyncio.Future, stores in AgentState.pending_tool - -> enqueues PendingInteraction { type: "workflow-decision" } on AppState - -> if no active interaction: promotes to active, pushes SSE - `workflow_decision_requested` event to browsers (with phase proposals) - -> awaits Future +orchestrator calls koan_complete_step (last step of a phase) + -> get_next_step() returns None + -> drain_user_messages(app_state) + -> if buffer empty: + future = asyncio.get_running_loop().create_future() + app_state.phase_complete_future = future + await future # HTTP connection held open + app_state.phase_complete_future = None + -> messages = drain_user_messages(app_state) + -> successors = get_successor_phases(app_state.phase) + -> returns format_phase_boundary(phase, messages, successors) +``` -user sees workflow proposal in web UI - -> selects a phase (or types custom input), clicks Confirm - -> POST /api/workflow-decision -> resolves Future with { phase, context } +The Future is resolved when the user sends a message via `POST /api/chat`. -MCP handler receives resolved value - -> clears AgentState.pending_tool - -> activates next queued interaction (if any) - -> sets AgentState.phase_ctx.proposal_made = True - -> returns "Selected: {phase}\n{context}" as MCP tool result to subagent +**Key asyncio invariant:** `api_chat` and `koan_complete_step` run in the same +asyncio event loop. `api_chat` appends to `user_message_buffer` before calling +`set_result()`. When `koan_complete_step` resumes, `drain_user_messages()` finds +the message in the buffer. No threads or locks are needed. + +**If messages are already buffered:** `koan_complete_step` drains them and +returns immediately — no Future is created. + +After receiving the phase-boundary response, the orchestrator converses with the +user and calls `koan_set_phase` to commit the transition. + +--- + +## Chat Message Delivery + +User messages are buffered in `AppState.user_message_buffer` and delivered +to the orchestrator at `koan_complete_step` call boundaries. -subagent then calls koan_set_next_phase({ phase: "..." }) to commit the choice ``` +user types in chat input + -> POST /api/chat { message: "..." } + -> ChatMessage appended to app_state.user_message_buffer + -> user_message projection event pushed (appears in activity feed) + -> if app_state.phase_complete_future is set: future.set_result(True) + -> returns { ok: true } + +orchestrator calls koan_complete_step (any step) + -> step guidance computed + -> messages = drain_user_messages(app_state) + -> if messages: appended to tool result as formatted block + -> returns combined guidance + user messages +``` + +Messages sent while the orchestrator is mid-step accumulate in the buffer and +are delivered at the next `koan_complete_step` call. Messages sent during +`koan_ask_question` or `koan_review_artifact` also buffer and deliver after +the structured interaction resolves. --- @@ -271,7 +309,7 @@ Driver Scout CLI Web UI ### User interaction flow (blocking via PendingInteraction queue) ``` -Subagent Driver Web UI +Orchestrator Driver Web UI | | | |--koan_ask_question---------->| | | | create Future | diff --git a/docs/projections.md b/docs/projections.md index a810d82..58af161 100644 --- a/docs/projections.md +++ b/docs/projections.md @@ -37,7 +37,7 @@ from a specific agent; `None` otherwise. ```python class VersionedEvent(BaseModel): version: int # 1-based, monotonic - event_type: str # one of the 37 event types (stored as str for forward compat) + event_type: str # one of the event types (stored as str for forward compat) timestamp: str # ISO8601 UTC agent_id: str | None = None # originating agent, when known payload: dict # typed per event_type (see below) @@ -98,7 +98,7 @@ on the conversation entry is `True` until `tool_completed` arrives. `agent.conversation.pending_thinking`; the completed `ThinkingEntry` is created on the next transition (tool call, step advance, or stream delta). -### Focus (6) +### Focus (4) | Event | Payload | `agent_id` | |-------|---------|-----------| @@ -106,13 +106,21 @@ on the next transition (tool call, step advance, or stream delta). | `questions_answered` | `{token, cancelled, answers?}` | set | | `artifact_review_requested` | `{token, path, description, content}` | set | | `artifact_reviewed` | `{token, cancelled, accepted?, response?}` | set | -| `workflow_decision_requested` | `{token, chat_turns}` | set | -| `workflow_decided` | `{token, cancelled, decision?}` | set | These events transition `run.focus` between variants of the `Focus` union. Cancellation (`cancelled: true`) occurs when the agent exits while the interaction is pending — there is no separate cancellation event type. +### User messages (1) + +| Event | Payload | `agent_id` | +|-------|---------|-----------| +| `user_message` | `{content, timestamp_ms}` | set (primary agent) | + +Emitted by `POST /api/chat` when the user sends a message during a run. The +fold appends a `UserMessageEntry` to the primary agent's conversation entries, +making user messages appear inline in the activity feed alongside agent output. + ### Resources (3) | Event | Payload | `agent_id` | @@ -354,8 +362,14 @@ class ToolGenericEntry(BaseToolEntry): tool_name: str # original tool name from the LLM summary: str = "" +class UserMessageEntry(KoanBaseModel): + type: Literal["user_message"] = "user_message" + content: str + timestamp_ms: int + + ConversationEntry = Annotated[ - ThinkingEntry | TextEntry | StepEntry | + ThinkingEntry | TextEntry | StepEntry | UserMessageEntry | ToolReadEntry | ToolWriteEntry | ToolEditEntry | ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry, Field(discriminator="type"), @@ -386,14 +400,8 @@ class ReviewFocus(KoanBaseModel): description: str content: str -class DecisionFocus(KoanBaseModel): - type: Literal["decision"] = "decision" - agent_id: str - token: str - chat_turns: list[dict] # raw LLM output, not validated by fold - Focus = Annotated[ - ConversationFocus | QuestionFocus | ReviewFocus | DecisionFocus, + ConversationFocus | QuestionFocus | ReviewFocus, Field(discriminator="type"), ] ``` @@ -510,8 +518,7 @@ completed agents. | `questions_answered` | `run.focus = ConversationFocus(agent_id=primary_id)` | | `artifact_review_requested` | `run.focus = ReviewFocus(...)` | | `artifact_reviewed` | `run.focus = ConversationFocus(agent_id=primary_id)` | -| `workflow_decision_requested` | `run.focus = DecisionFocus(...)` | -| `workflow_decided` | `run.focus = ConversationFocus(agent_id=primary_id)` | +| `user_message` | `primary_agent.conversation.entries += UserMessageEntry(...)` | ### Run lifecycle diff --git a/docs/state.md b/docs/state.md index 3656a44..d0cdd3a 100644 --- a/docs/state.md +++ b/docs/state.md @@ -27,7 +27,7 @@ markdown (for LLMs) in the same operation. ### Filesystem-driven story discovery Story IDs are discovered by scanning `stories/*/story.md`, not by reading a -driver-maintained JSON list. The decomposer LLM creates `story.md` files using +driver-maintained JSON list. The orchestrator (during the ticket-breakdown phase) creates `story.md` files using the `write` tool -- it has no reason to know the JSON state format. The driver discovers what the LLM created by scanning, then populates the JSON story list itself. @@ -63,15 +63,10 @@ phase and the list of story IDs. | `implementation-validation` | Post-execution alignment review | | `completed` | All phases done | -Additional epic directory files: -| File | Purpose | -| ------------------------ | -------------------------------------------------- | -| `workflow-decision.json` | Records workflow orchestrator decisions | -| `workflow-status.md` | Human-readable workflow status for LLM consumption | **`scouting` is intentionally absent.** Scouts run inside the -`koan_request_scouts` tool handler during intake/decomposer/planner phases, +`koan_request_scouts` tool handler during intake/planning phases, not as a top-level phase. --- @@ -126,56 +121,32 @@ the driver sets the story to `skipped`. --- -## Driver Routing +## Driver and Orchestrator -The driver's story loop is a deterministic state machine: +The driver spawns the orchestrator once at run start and awaits its exit. +The orchestrator drives the entire workflow, including phase transitions and +story execution. -```python -# koan/driver.py -while True: - stories = load_all_story_states(epic_dir) - routing = route_from_state(stories) - - if routing.action == "retry": # re-execute story - elif routing.action == "execute": # plan + execute story - elif routing.action == "complete": # all stories terminal -> exit loop - elif routing.action == "error": # no actionable state -> fail -``` - -**Priority:** `retry` is checked before `selected`. A story queued for retry -takes precedence over a newly selected story. - -**Terminal states:** exactly `done` and `skipped`. The epic is complete when -every story is in a terminal state. - -**Error state:** If no story is `retry` or `selected` and not all are terminal, -the driver reports: "orchestrator may have exited without a routing decision." +### Story execution (orchestrator-driven) -### Story execution pipeline - -For each story selected for execution: +The orchestrator selects and manages stories during the execution phase via +MCP tools: ``` -Driver sets status -> planning - -> spawn planner subagent - -> if planner fails: skip executor, go to post-execution orchestrator -Driver sets status -> executing - -> spawn executor subagent -Driver sets status -> verifying - -> spawn orchestrator (post-execution) - -> orchestrator decides: koan_complete_story / koan_retry_story / koan_skip_story +orchestrator calls koan_select_story(story_id) + -> story status set to "selected" +orchestrator calls koan_spawn_executor(story_id, role="planner") + -> driver spawns planner subagent, blocks until exit +orchestrator calls koan_spawn_executor(story_id, role="executor") + -> driver spawns executor subagent, blocks until exit + -> (if retry needed: pass retry_context to koan_spawn_executor) +orchestrator calls koan_complete_story / koan_retry_story / koan_skip_story ``` -### Planner failure fallthrough - -When the planner exits with non-zero exit code, the driver skips the executor -and proceeds directly to the post-execution orchestrator. This gives the -orchestrator a chance to make a routing decision. - ### Model config gate When a web server is available, the pipeline blocks at startup until the user -confirms model tier selection. This happens before any subagent spawns. +confirms model tier selection. This happens before the orchestrator spawns. --- @@ -206,36 +177,32 @@ This applies to: ``` {epic_dir}/ epic-state.json # Epic phase + story list - workflow-decision.json # Workflow orchestrator decisions - workflow-status.md # Human-readable workflow status - landscape.md # Written by intake - brief.md # Written by brief-writer + landscape.md # Written by orchestrator (intake phase) + brief.md # Written by orchestrator (brief-generation phase) stories/ {story_id}/ - story.md # Written by decomposer + story.md # Written by orchestrator (ticket-breakdown phase) state.json # Story lifecycle state status.md # Templated status for LLM consumption plan/ plan.md # Written by planner subagents/ - intake/ - task.json # Task manifest + orchestrator/ + task.json # Task manifest (written once at run start) state.json # Audit projection - events.jsonl # Audit log - decomposer/ - ... + events.jsonl # Audit log (covers entire run, all phases) scout-{id}-{timestamp}/ task.json findings.md # Scout output ... planner-{story_id}/ - ... + task.json + state.json + events.jsonl executor-{story_id}/ - ... - orchestrator-pre/ - ... - orchestrator-post-{story_id}/ - ... + task.json + state.json + events.jsonl ``` --- @@ -257,5 +224,12 @@ Key projection fields common to all roles: | `tokens_sent` | number | Cumulative tokens in | | `tokens_received` | number | Cumulative tokens out | -Intake confidence and iteration counters are tracked in the in-memory -`PhaseContext` during execution and are not persisted to the audit projection. +Orchestrator state tracked in `AppState` (in-memory, not persisted): + +| Field | Type | Purpose | +|-------|------|---------| +| `user_message_buffer` | `list[ChatMessage]` | Buffered user chat messages, drained at each `koan_complete_step` | +| `phase_complete_future` | `asyncio.Future \| None` | Non-None while `koan_complete_step` is blocking at a phase boundary | + +`ChatMessage` carries `content: str` and `timestamp_ms: int`. Messages are +appended by `POST /api/chat` and removed atomically by `drain_user_messages()`. diff --git a/docs/subagents.md b/docs/subagents.md index 88e8bea..b5fe035 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -29,14 +29,12 @@ are nested naturally rather than flattened into a shared namespace. Role-specific fields: -| Role | Additional fields | -| -------------- | -------------------------------------- | -| `intake` | -- | -| `scout` | `question`, `investigator_role` | -| `decomposer` | -- | -| `orchestrator` | `step_sequence`, `story_id` (optional) | -| `planner` | `story_id` | -| `executor` | `story_id`, `retry_context` (optional) | +| Role | Additional fields | +| -------------- | ------------------------------------------------- | +| `orchestrator` | `project_dir`, `task_description` | +| `scout` | `question`, `investigator_role` | +| `planner` | `story_id` | +| `executor` | `story_id`, `retry_context` (optional) | ### Lifecycle @@ -85,7 +83,7 @@ driver: spawn_subagent(task, subagent_dir, runner) -> parse stdout line-by-line for streaming events -> wait for process exit driver: deregister agent_id -driver: check exit code, route to next phase +driver: check exit code, emit workflow_completed ``` ### Child side @@ -137,19 +135,17 @@ Phase modules: ``` koan/phases/ - intake.py - brief_writer.py - scout.py - orchestrator.py - planner.py - executor.py - core_flows.py - tech_plan.py - ticket_breakdown.py - cross_artifact_validation.py - workflow_orchestrator.py - format_step.py - review_protocol.py + intake.py # guidance provider: intake phase + brief_writer.py # guidance provider: brief-generation phase + core_flows.py # guidance provider: core-flows phase + tech_plan.py # guidance provider: tech-plan phase + ticket_breakdown.py # guidance provider: ticket-breakdown phase + cross_artifact_validation.py # guidance provider: cross-artifact-validation and implementation-validation + executor.py # guidance provider: execution phase; also spawned as separate subagent + orchestrator.py # guidance provider: pre/post execution steps + scout.py # spawned as separate subagent; no step guidance role + format_step.py # shared formatting utilities + review_protocol.py # shared review loop logic ``` Each phase module exposes: @@ -166,12 +162,13 @@ Each phase module exposes: ``` koan_complete_step arrives via MCP: - step == 0 -> step=1, return format_step(step_guidance(1)) [boot transition] + step == 0 -> step=1, prepend SYSTEM_PROMPT, return format_step(step_guidance(1)) [boot/phase transition] otherwise -> validate_step_completion(step) [pre-condition check] -> next_step = get_next_step(step) [pure: decides where to go] - next_step is None -> return "Phase complete." [done] + next_step is None -> block for user message (asyncio.Future), then + return format_phase_boundary(phase, messages, successors) [phase boundary] next_step < prev -> on_loop_back(prev, next_step) [side effects of loop] - next_step != None -> step=next_step, return format_step(step_guidance(next_step)) [advance] + next_step != None -> step=next_step, return format_step(step_guidance(next_step)) + any buffered user messages [advance] ``` ### System prompt vs task content @@ -227,22 +224,34 @@ from write-bash is intractable at the permission layer. ### Role permission matrix -| Role | koan tools | write/edit | notes | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------- | -| **intake** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `koan_set_confidence`, `koan_review_artifact` | path-scoped to epicDir | `koan_request_scouts, koan_ask_question, write, edit` blocked in step 1 (Extract) | -| **scout** | `koan_complete_step` | none | No `koan_ask_question` (no user interaction). No `koan_request_scouts` (no nested scouts). No file writing. | -| **brief-writer** | `koan_complete_step`, `koan_review_artifact`, `edit`, `write` | path-scoped to epicDir | `koan_request_scouts, koan_ask_question, write, edit` blocked in step 1 (Read) | -| **workflow-orchestrator** | `koan_complete_step`, `koan_propose_workflow`, `koan_set_next_phase` | -- | No file writing capability | -| **decomposer** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | -- | -| **orchestrator** | `koan_complete_step`, `koan_ask_question`, `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | path-scoped to epicDir | No `koan_request_scouts` -- orchestrator uses bash for verification | -| **planner** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | -- | -| **ticket-breakdown** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `edit`, `write` | path-scoped to epicDir | -- | -| **cross-artifact-validator**| `koan_complete_step`, `koan_ask_question`, `koan_request_scouts`, `edit`, `write` | path-scoped to epicDir | -- | -| **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | +The orchestrator role uses **phase-aware permissions** — available tools +vary by the current phase. Planner, executor, and scout use static permission sets. + +**Orchestrator phase-aware permissions:** + +| Tool | Available phases | +|------|-----------------| +| `koan_complete_step` | All phases | +| `koan_set_phase` | All phases (blocked mid-story during execution) | +| `koan_ask_question` | All phases | +| `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation` | +| `koan_review_artifact` | `intake`, `brief-generation`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `implementation-validation` | +| `koan_spawn_executor` | `execution` only | +| `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | `execution` only | +| `write`, `edit` (epic_dir scoped) | All phases except `brief-generation` step 1 | +| `bash` | `execution`, `implementation-validation` | + +**Other role static permissions:** + +| Role | koan tools | write/edit | notes | +| -------------- | -------------------------------------------- | ---------------------- | ------------------------------------------- | +| **scout** | `koan_complete_step` | none | No user interaction. No nested scouts. No file writing. | +| **planner** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | -- | +| **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | ### Path scoping -Planning roles (intake, scout, decomposer, orchestrator, planner) can only +Planning roles (orchestrator, scout, planner) can only `write`/`edit` files inside the epic directory. The permission check resolves both the tool's `path` argument and the epic directory, then verifies the tool path starts with the epic path. @@ -255,11 +264,11 @@ path starts with the epic path. Koan has 6+ roles, but they cluster into 3 capability bands: -| Tier | Roles | Why this tier | -| ------------ | ----------------------------------------- | ---------------------------------------------------------------- | -| **strong** | intake, decomposer, orchestrator, planner | Complex multi-step reasoning | -| **standard** | executor | Code implementation: reliable tool use without deepest reasoning | -| **cheap** | scout | Narrow codebase investigation: reading files, writing findings | +| Tier | Roles | Why this tier | +| ------------ | ------------------------------ | ---------------------------------------------------------------- | +| **strong** | orchestrator, planner | Complex multi-step reasoning | +| **standard** | executor | Code implementation: reliable tool use without deepest reasoning | +| **cheap** | scout | Narrow codebase investigation: reading files, writing findings | The role-to-tier mapping is defined in `koan/config.py`. Adding a new role requires updating that map. @@ -365,11 +374,8 @@ Agent registration and deregistration are tracked in the in-process Intake sub-phase derivation happens server-side based on step number: -| Step | Pending ask? | Sub-phase | -| ---- | ------------ | ----------- | -| 1 | -- | `"extract"` | -| 2 | -- | `"scout"` | -| 3 | yes | `"ask"` | -| 3 | no | `"ask"` | -| 4 | -- | `"reflect"` | -| 5 | -- | `"write"` | +| Step | Sub-phase | +| ---- | ------------- | +| 1 | `"gather"` | +| 2 | `"evaluate"` | +| 3 | `"write"` | From 9f790e4208b98340e4a6b9b95707f9caf8cb2d31 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 13:40:18 +0700 Subject: [PATCH 295/412] fix: restyle chat input as bordered field inside the activity feed card Move ChatInput from a standalone element below the feed into the activity-feed-inner card. Style it as a bordered text field with rounded corners, copper focus glow, auto-resizing textarea, and an inline Send button. The input sits at the bottom of the conversation card, separated by a subtle divider. --- frontend/src/App.tsx | 5 -- frontend/src/components/ActivityFeed.tsx | 8 +++ frontend/src/components/ChatInput.tsx | 51 +++++++++------ frontend/src/styles/layout.css | 80 ++++++++++++++++++++++++ 4 files changed, 121 insertions(+), 23 deletions(-) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 0d433e2..9acb332 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -10,7 +10,6 @@ import { ArtifactsSidebar } from './components/ArtifactsSidebar' import { Notification } from './components/Notification' import { SettingsOverlay } from './components/SettingsOverlay' import { Completion } from './components/Completion' -import { ChatInput } from './components/ChatInput' import { AskWizard } from './components/interactions/AskWizard' import { ArtifactReview } from './components/interactions/ArtifactReview' @@ -25,11 +24,8 @@ function InteractionView() { function WorkspaceMain() { const focus = useStore(s => s.run?.focus) const completion = useStore(s => s.run?.completion) - const run = useStore(s => s.run) const hasInteraction = focus && focus.type !== 'conversation' - // Hide chat input during structured interactions to prevent confusion - const showChatInput = run !== null && !hasInteraction return ( <div className="workspace-main"> @@ -41,7 +37,6 @@ function WorkspaceMain() { <ActivityFeed /> )} <AgentMonitor /> - {showChatInput && <ChatInput />} </div> ) } diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index 42c7745..286042b 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -2,6 +2,7 @@ import { useRef, useState } from 'react' import { useStore, ConversationEntry } from '../store/index' import { useAutoScroll } from '../hooks/useAutoScroll' import { Md } from './Md' +import { ChatInput } from './ChatInput' // -- Thinking ------------------------------------------------------------------ @@ -155,11 +156,15 @@ export function ActivityFeed() { const conversation = useStore(s => focusAgentId ? s.run?.agents?.[focusAgentId]?.conversation : undefined ) + const run = useStore(s => s.run) + const focus = useStore(s => s.run?.focus) const scrollRef = useRef<HTMLDivElement>(null) useAutoScroll(scrollRef) const hasEntries = conversation?.entries && conversation.entries.length > 0 const isWaiting = !hasEntries && !conversation?.isThinking && !conversation?.pendingText + const hasInteraction = focus && focus.type !== 'conversation' + const showChatInput = run !== null && !hasInteraction return ( <div className="activity-feed-scroll" ref={scrollRef}> @@ -199,6 +204,9 @@ export function ActivityFeed() { <span className="streaming-cursor" /> </div> )} + + {/* Chat input — inside the feed card */} + {showChatInput && <ChatInput />} </div> </div> ) diff --git a/frontend/src/components/ChatInput.tsx b/frontend/src/components/ChatInput.tsx index 0f08deb..46eb2aa 100644 --- a/frontend/src/components/ChatInput.tsx +++ b/frontend/src/components/ChatInput.tsx @@ -1,14 +1,23 @@ -import { useState, KeyboardEvent } from 'react' +import { useState, useRef, useEffect, KeyboardEvent } from 'react' import { useStore } from '../store/index' import { sendChatMessage } from '../api/client' export function ChatInput() { const [text, setText] = useState('') const [sending, setSending] = useState(false) + const textareaRef = useRef<HTMLTextAreaElement>(null) const run = useStore(s => s.run) const isDisabled = !run || run.completion !== null || sending + // Auto-resize textarea to fit content + useEffect(() => { + const ta = textareaRef.current + if (!ta) return + ta.style.height = 'auto' + ta.style.height = Math.min(ta.scrollHeight, 120) + 'px' + }, [text]) + async function handleSend() { const msg = text.trim() if (!msg || isDisabled) return @@ -32,23 +41,29 @@ export function ChatInput() { } return ( - <div className="chat-input"> - <textarea - className="chat-input-textarea" - value={text} - onChange={e => setText(e.target.value)} - onKeyDown={handleKeyDown} - placeholder={isDisabled ? 'No active run' : 'Message the orchestrator… (Enter to send, Shift+Enter for newline)'} - disabled={isDisabled} - rows={2} - /> - <button - className="chat-input-send" - onClick={handleSend} - disabled={isDisabled || !text.trim()} - > - Send - </button> + <div className="chat-input-area"> + <div className="chat-input-box"> + <textarea + ref={textareaRef} + className="chat-input-textarea" + value={text} + onChange={e => setText(e.target.value)} + onKeyDown={handleKeyDown} + placeholder={isDisabled ? 'No active run' : 'Message the orchestrator…'} + disabled={isDisabled} + rows={1} + /> + <div className="chat-input-footer"> + <span className="chat-input-hint">Enter to send · Shift+Enter for newline</span> + <button + className="chat-input-send" + onClick={handleSend} + disabled={isDisabled || !text.trim()} + > + Send + </button> + </div> + </div> </div> ) } diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index 054d05e..a9def1e 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -323,6 +323,86 @@ min-width: 0; } +/* ---- Chat input (inside feed card) ---- */ + +.chat-input-area { + margin-top: var(--space-4); + border-top: 1px solid var(--border); + padding-top: var(--space-4); +} + +.chat-input-box { + border: 1px solid var(--border); + border-radius: var(--radius-sm); + background: var(--bg-elevated); + transition: border-color 200ms, box-shadow 200ms; +} + +.chat-input-box:focus-within { + border-color: var(--copper); + box-shadow: 0 0 0 3px rgba(188, 108, 37, 0.08); +} + +.chat-input-textarea { + width: 100%; + border: none; + background: transparent; + font-family: var(--font-sans); + font-size: 14px; + color: var(--text); + padding: 10px 12px; + outline: none; + resize: none; + line-height: 1.5; + min-height: 24px; + max-height: 120px; + display: block; +} + +.chat-input-textarea::placeholder { + color: var(--text-ghost); +} + +.chat-input-textarea:disabled { + opacity: 0.5; + cursor: not-allowed; +} + +.chat-input-footer { + display: flex; + justify-content: space-between; + align-items: center; + padding: 4px 12px 8px; +} + +.chat-input-hint { + font-family: var(--font-mono); + font-size: 10px; + color: var(--text-ghost); +} + +.chat-input-send { + font-family: var(--font-mono); + font-size: 12px; + color: var(--copper); + font-weight: 600; + background: none; + border: none; + cursor: pointer; + padding: 2px 8px; + border-radius: 4px; + transition: background 150ms; +} + +.chat-input-send:hover:not(:disabled) { + background: var(--copper-bg); +} + +.chat-input-send:disabled { + opacity: 0.3; + cursor: default; +} + /* Monitor -- sticky bottom, sizes to content, centered like activity feed. * No border-top or mask fade -- it connects seamlessly with the sidebars. */ .monitor { From 6f9e7fa84187329102333cf38a4cac601d0d3ab8 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 15:15:28 +0700 Subject: [PATCH 296/412] refactor: rename intake step 2 to Deepen, rewrite guidance for iterative dialogue MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the 'Evaluate' step with 'Deepen' to emphasize iterative understanding through multiple rounds of user dialogue. Key changes: - Restructure guidance into a deepening loop (process → map → ask → deepen → repeat) - Remove artificial question count ceiling ('aim for 3-5 questions') - Add ripple-effect reasoning: each answer may shift understanding of adjacent areas - Define completion criteria based on depth of understanding, not question count - Update docs/intake-loop.md to match --- docs/intake-loop.md | 42 ++++++++++----- koan/phases/intake.py | 122 +++++++++++++++++++++++------------------- 2 files changed, 95 insertions(+), 69 deletions(-) diff --git a/docs/intake-loop.md b/docs/intake-loop.md index 0d47d27..57b4ebe 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -26,7 +26,7 @@ user questions, then write `landscape.md`. | Step | Name | Runs | Purpose | | ---- | -------- | ---- | --------------------------------------------------------------------------------- | | 1 | Gather | 1x | Read conversation, open obvious files (≤5), dispatch 3-5 scouts. | -| 2 | Evaluate | 1x | Process scout results, verify by reading files, enumerate knowns/unknowns, ask Qs. | +| 2 | Deepen | 1x | Process scout results, verify by reading files, deepen understanding through iterative dialogue. | | 3 | Write | 1x | Write `landscape.md`. Review gate: calls `koan_review_artifact` before completing. | Step 3 is review-gated: it blocks until `koan_review_artifact` is accepted. @@ -51,19 +51,21 @@ actual function names and file paths rather than conversation labels. No read-only permission gate -- the Gather step has full access to all intake tools including `koan_request_scouts`. -### Step 2: Evaluate +### Step 2: Deepen -The Evaluate step processes scout results, verifies findings by reading source -files directly, enumerates knowns and unknowns with a downstream impact -assessment, and asks the user targeted questions. +The Deepen step builds genuine understanding through iterative dialogue with +the user. It processes scout results, verifies findings by reading source files +directly, identifies gaps, and asks the user targeted questions -- then deepens +further as each answer reveals new dimensions. Key properties: - **Scout verification**: Scouts are good at exploration but their output should - be confirmed. The Evaluate step reads actual files to verify key scout findings + be confirmed. The Deepen step reads actual files to verify key scout findings that affect scope or story boundaries. -- **Thread-of-Thought enumeration**: The step walks through each area relevant - to the task, explicitly stating what is known and unknown before formulating - questions. This surfaces gaps that would otherwise go unnoticed. +- **Iterative deepening**: Understanding deepens through multiple rounds of + dialogue. Each answer may shift the picture of adjacent areas, revealing + assumptions the agent was making without realizing it. Multiple rounds of + questions are expected for any non-trivial task. - **Impact classification**: Each unknown is classified as ASK (user input needed) or SAFE (implementation detail). Only ASK items become questions. - **Default-ask framing**: Question-asking is the default; skipping requires @@ -118,15 +120,19 @@ per `koan_complete_step` call while minimizing planning or meta-reasoning steps. Each step does real work across multiple activities rather than artificially separating them into sequential tool calls. -### Thread-of-Thought in Evaluate (explicit enumeration before questions) +### Iterative deepening through dialogue -The Evaluate step instructs the LLM to walk through each area and explicitly -state what is known, unknown, and its source -- before formulating questions. -This surfaces gaps that are not top-of-mind. +The Deepen step positions dialogue as the core mechanism, not an afterthought. +The agent maps knowns and unknowns, then enters an iterative loop: ask +questions, process answers, verify against code, surface new gaps, and ask +again. Each answer is treated as a thread to pull -- it may shift understanding +of adjacent areas and reveal assumptions the agent was making without realizing +it. This ripple effect is what produces genuine understanding rather than +surface-level coverage. ### Default-ask question framing (preventing question avoidance) -The Evaluate step frames question-asking as the default, with skipping +The Deepen step frames question-asking as the default, with skipping requiring triple justification. This inverts the typical LLM bias toward advancing the workflow. @@ -165,3 +171,11 @@ Evaluate step is thorough. Scout result evaluation and question formulation are tightly coupled -- a scout finding directly informs what questions to ask. Separating them forces the LLM to defer questions it could ask immediately. + +### Don't cap question rounds + +Previous iterations suggested "aim for 3-5 questions" in a single batch. This +created an implicit ceiling that discouraged iterative deepening. The current +design has no per-round limit and explicitly expects multiple rounds for +non-trivial tasks. Completion is defined by depth of understanding, not +question count. diff --git a/koan/phases/intake.py b/koan/phases/intake.py index 60088f6..ad8986c 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -1,7 +1,7 @@ # Intake phase -- 3-step workflow. # # Step 1 (Gather) -- read task description, explore obvious files, dispatch scouts -# Step 2 (Evaluate) -- process scout results, verify, ask questions +# Step 2 (Deepen) -- process scout results, verify, deepen through dialogue # Step 3 (Write) -- write landscape.md, present for user review # # Step 3 is review-gated: blocks until koan_review_artifact accepted. @@ -16,7 +16,7 @@ STEP_NAMES: dict[int, str] = { 1: "Gather", - 2: "Evaluate", + 2: "Deepen", 3: "Write", } @@ -109,7 +109,7 @@ "## Workflow\n" "\n" "You work in three steps: gather context (task description + codebase + scouts)," - " evaluate findings and ask questions, then write landscape.md.\n" + " deepen your understanding through dialogue with the user, then write landscape.md.\n" "\n" "## Output\n" "\n" @@ -220,76 +220,68 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: return StepGuidance( title=STEP_NAMES[2], instructions=[ - "Analyze scout results, verify findings, and ask the user questions.", + "Deepen your understanding through iterative dialogue with the user.", "", - "## 1. Analyze scout results", + "Scout results give you a starting point -- not the finish line. Your job now", + "is to build genuine, verified understanding by reading code, identifying gaps,", + "and asking the user targeted questions. Then doing it again as each answer", + "reveals new dimensions you couldn't have seen before.", "", - "When scouts return, analyze each report:", + "This is the only phase where the user can be consulted. After intake, all", + "downstream phases work from landscape.md alone. Anything you get wrong here", + "will silently propagate through decomposition, planning, and execution.", + "", + "## 1. Process scout results", + "", + "Analyze each scout report:", "- Does the finding answer the questions you asked?", "- Does it reveal anything unexpected about the codebase?", "- Does it conflict with what the task description stated?", "", - "## 2. Verify -- read files to confirm", - "", - "Scouts are good at exploration but their output should be verified.", - "For key findings that affect scope or story boundaries, open the", - "actual files and confirm what the scout reported. This is especially", - "important for:", - "", + "For key findings that affect scope or story boundaries, open the actual files", + "and confirm what the scout reported. Scouts are good at exploration but their", + "output should be verified. This is especially important for:", "- Integration points the scout identified", "- Patterns or conventions the scout claims to have found", - "- Anything that conflicts with what the task description stated", + "- Anything that conflicts with the task description", "", - "## 3. Enumerate what you know and what you don't", + "## 2. Map what you know and what you don't", "", - "Walk through each area relevant to the task and state what you have learned.", - "Use this structure for each area:", + "Walk through each area relevant to the task. Use this structure:", "", " **[Area name]** (e.g., 'Authentication', 'Database schema', 'API endpoints')", " - Known: [what the task description and/or scouts established]", " - Unknown: [what remains unclear or unverified]", " - Source: [task description / scout findings]", "", - "Cover every area relevant to the task. Be thorough -- gaps you miss here", - "become gaps in the final output.", - "", - "Include project conventions as an area: where are coding style, testing strategy,", - "architecture patterns, and documentation standards defined? If not explicitly", - "documented, note whether they are emergent from code patterns or absent entirely.", - "", - "## 4. Downstream impact assessment", + "Cover every area relevant to the task, including project conventions (coding", + "style, testing strategy, architecture patterns, documentation standards).", "", - "For each 'Unknown' item, briefly assess:", - "- If you assume wrong about this, what happens to downstream planning?", - "- Could a wrong assumption split a story that should be one, or merge two that should be separate?", + "For each unknown, briefly assess its downstream impact:", + "- If you assume wrong, does it change story boundaries?", "- Would the executor hit a surprise that requires re-planning?", "", - "This is the only phase where the user can be consulted. After intake, all", - "downstream phases work from landscape.md alone. Anything you get wrong here", - "will silently propagate through decomposition, planning, and execution.", - "", "Mark each unknown as:", - "- **ASK**: user input needed -- this affects scope, boundaries, or sequencing.", + "- **ASK**: user input needed -- affects scope, boundaries, or sequencing.", "- **SAFE**: genuinely an implementation detail with no scope impact.", "", - "## 5. Ask questions", + "## 3. The deepening loop", + "", + "This is the core of this step. Understanding deepens through dialogue, and", + "for any non-trivial task, multiple rounds of questions are expected.", "", - "For each 'Unknown' marked ASK, ask yourself: if I get this wrong, does it affect", - "the decomposer's ability to define correct story boundaries? If yes or maybe -- ask.", + "### a) Ask your first round of questions", "", - "The user is your collaborator, not an interruption. Questions are how you verify", - "your understanding against reality. The decomposer cannot ask questions later --", - "this is the only chance to get clarification.", + "For every unknown marked ASK, formulate a question. The user is your", + "collaborator, not an interruption. The decomposer cannot ask questions", + "later -- this is the only chance to get clarification.", "", "Default: ask. You may skip a question ONLY if ALL of these are true:", "- It is purely an implementation detail (HOW to code something, not WHAT to build).", "- Getting it wrong would not change any story boundary.", "- It cannot be misinterpreted -- there is exactly one reasonable interpretation.", "", - "Call `koan_ask_question` once with all your questions in the `questions` array.", - "The user sees them one at a time. Aim for 3-5 questions.", - "", - "Formatting rules:", + "Call `koan_ask_question` with your questions. Formatting rules:", "- Prefer multiple-choice when the answer space is bounded.", "- Option labels are plain text -- no letter prefixes like (a)/(b), no numbering.", "- Do NOT include 'Other', 'None of the above', or similar meta-options.", @@ -298,23 +290,43 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "- Ground questions in specific findings:", " 'Scout found X -- should this story follow the same pattern?'", "", - "## 6. Process answers and follow up", + "### b) Deepen with each answer", + "", + "When answers arrive, each one is a thread to pull. Think through:", + "", + "- **Does the answer reference files or code you haven't read?** Read them now.", + " Confirm the answer against what you find in the codebase.", + "- **Does understanding this answer change your picture of another area?**", + " An answer about the data model may reveal an assumption you were making", + " about the API layer. An answer about scope may invalidate a pattern you", + " assumed would apply.", + "- **Does it reveal an assumption you were making without realizing it?**", + " The most dangerous gaps are the ones you don't know you have.", + "- **Does it raise a new question you couldn't have anticipated before?**", + " This is the ripple effect: each answer shifts your understanding, and", + " that shift may expose new gaps in adjacent areas.", + "", + "### c) Ask follow-up questions", "", - "When answers arrive, think through each one carefully:", + "If new ambiguities surface -- and for any non-trivial task, they will --", + "call `koan_ask_question` again. There is no limit on rounds. Shallow", + "understanding compounds into wrong plans. Deep understanding prevents", + "re-work.", "", - "a) **Does an answer point to files you should read?** If the user references", - " specific files, code, or documentation -- read them immediately using read tools.", - " Confirm the answer against what you find in the codebase.", + "Each round should build on the last. Early questions establish the shape", + "of the problem. Later questions refine boundaries, resolve edge cases,", + "and confirm the assumptions that emerged from earlier answers.", "", - "b) **Does an answer raise new questions?** If understanding one answer reveals", - " a new ambiguity or decision point -- ask the follow-up immediately via another", - " `koan_ask_question` call. Think through those answers the same way.", + "### d) When are you done?", "", - "c) **Are you satisfied?** If all answers are clear and no follow-ups are needed,", - " proceed to the next step.", + "You are done deepening when:", + "- Every area relevant to the task has been verified against the codebase.", + "- You can explain the full context to a downstream planner without hedging.", + "- No answer you received left you with a 'I think I know what they mean'", + " feeling -- you either confirmed it or asked.", "", - "When in doubt, check with the user. It is always better to confirm an assumption", - "than to let a wrong assumption propagate through planning and execution.", + "When in doubt, ask. It is always better to confirm an assumption than to", + "let a wrong assumption propagate through planning and execution.", ], ) From ab12920d9ba27349543e0df7f5870b79fb0ae77e Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 15:15:38 +0700 Subject: [PATCH 297/412] refactor: remove client-side option sanitization from AskWizard Drop letter-prefix stripping and meta-option filtering. Prompt engineering ensures correct format at the source; the UI renders options as-is without parsing or rewriting LLM text. --- frontend/src/components/interactions/AskWizard.tsx | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/frontend/src/components/interactions/AskWizard.tsx b/frontend/src/components/interactions/AskWizard.tsx index ae1f76b..b44072f 100644 --- a/frontend/src/components/interactions/AskWizard.tsx +++ b/frontend/src/components/interactions/AskWizard.tsx @@ -84,16 +84,9 @@ function QuestionCard({ } } - // Normalize options at render time to handle LLM output variability. - // Filter out any LLM-provided "Other" / meta-options — we always render our own. - const isMetaOption = (s: string): boolean => - /^\(?[a-z]\)?\s*[.:\-)]?\s*/i.test(s) // strip letter prefixes like "(a) ", "A: " - ? isMetaOption(s.replace(/^\(?[a-z]\)?\s*[.:\-)]?\s*/i, '')) - : /^(other|none of the above|something else|other approach|other option|custom|n\/a)$/i.test(s.trim()) - const stripPrefix = (s: string) => s.replace(/^\(?[a-z]\)?\s*[.:\-)]?\s*/i, '').trim() + // Options are used as-is. Prompt engineering ensures correct format; + // code never parses or rewrites LLM text. const opts = normalizeOptions(question.options as (string | Record<string, unknown>)[]) - .filter(o => !isMetaOption(o.label)) - .map(o => ({ ...o, label: stripPrefix(o.label), value: stripPrefix(o.value) || o.value })) return ( <div className="question-card"> From 1cc24a67e58265ddaec0f99b64216d3b08c751ad Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 17:14:04 +0700 Subject: [PATCH 298/412] style: redesign question option cards with left-border accent pattern --- frontend/src/styles/components.css | 82 +++++++++++++++++++++--------- 1 file changed, 58 insertions(+), 24 deletions(-) diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index b060192..f18f33b 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -313,84 +313,118 @@ margin-bottom: var(--space-2); } +/* ---- Option list ---- */ .options-list { display: flex; flex-direction: column; - gap: var(--space-1); + gap: var(--space-2); } .option { display: flex; align-items: flex-start; - gap: var(--space-2); - padding: var(--space-2) var(--space-4); - border: 1px solid var(--border); - border-radius: var(--radius-sm); + gap: var(--space-4); + padding: var(--space-4); + border-left: 3px solid transparent; + border-radius: 0 var(--radius-sm) var(--radius-sm) 0; background: var(--bg); cursor: pointer; - transition: border-color 100ms, background 100ms; + transition: border-color var(--duration-fast), background var(--duration-fast); user-select: none; } .option:hover { - border-color: var(--text-muted); + background: var(--caramel-bg); + border-left-color: var(--border-strong); } .option.selected { - border-color: var(--copper-border); + border-left-color: var(--copper); background: var(--copper-bg); } +.option.recommended:not(.selected) { + border-left-color: var(--caramel); +} + .option-other { - border-style: dashed; + opacity: 0.7; +} +.option-other:hover { + opacity: 1; } .radio-dot, .checkbox-dot { - width: 14px; - height: 14px; - border: 2px solid var(--text-ghost); + width: 16px; + height: 16px; + border: 2px solid var(--border-strong); border-radius: 50%; flex-shrink: 0; - margin-top: 2px; - transition: border-color 100ms, background 100ms; + margin-top: 1px; + transition: border-color var(--duration-fast), background var(--duration-fast), box-shadow var(--duration-fast); + position: relative; } .checkbox-dot { - border-radius: 3px; + border-radius: 4px; +} + +.option:hover .radio-dot, +.option:hover .checkbox-dot { + border-color: var(--text-muted); +} + +.option.selected .radio-dot { + border-color: var(--copper); + background: var(--bg-elevated); + box-shadow: inset 0 0 0 3px var(--copper); } -.option.selected .radio-dot, .option.selected .checkbox-dot { border-color: var(--copper); background: var(--copper); } .option.selected .checkbox-dot::after { - content: "[OK]"; - display: block; - color: #fff; - font-size: 9px; - text-align: center; - line-height: 10px; + content: ""; + position: absolute; + top: 2px; + left: 5px; + width: 4px; + height: 7px; + border: solid #fff; + border-width: 0 2px 2px 0; + transform: rotate(45deg); } .option-text { font-family: var(--font-sans); - font-size: var(--font-size-lg); + font-size: var(--font-size-md); color: var(--text); flex: 1; + line-height: 1.5; +} + +.option.selected .option-text { + color: var(--text-strong); } .option-other .option-text { color: var(--text-muted); + font-style: italic; } .recommended-badge { font-family: var(--font-mono); font-size: var(--font-size-xs); color: var(--copper); - margin-left: auto; + background: var(--copper-bg); + border: 1px solid var(--copper-border); + border-radius: var(--radius-sm); + padding: 1px 6px; + margin-top: 1px; white-space: nowrap; + flex-shrink: 0; } .other-input { From f2414beba6395ba6fc1879b1a6087c88a10056b7 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 17:14:30 +0700 Subject: [PATCH 299/412] refactor: rename chat placeholder from 'Message the orchestrator' to 'Send feedback' --- frontend/src/components/ChatInput.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/components/ChatInput.tsx b/frontend/src/components/ChatInput.tsx index 46eb2aa..9d38cb1 100644 --- a/frontend/src/components/ChatInput.tsx +++ b/frontend/src/components/ChatInput.tsx @@ -49,7 +49,7 @@ export function ChatInput() { value={text} onChange={e => setText(e.target.value)} onKeyDown={handleKeyDown} - placeholder={isDisabled ? 'No active run' : 'Message the orchestrator…'} + placeholder={isDisabled ? 'No active run' : 'Send feedback…'} disabled={isDisabled} rows={1} /> From ca76fdf1c5abf30d6dabf3fdaa46eb1d59b2a9d8 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 17:15:00 +0700 Subject: [PATCH 300/412] feat: add steering queue infrastructure Adds the backend foundation for delivering user feedback to the orchestrator via tool responses: - AppState.steering_queue + drain_steering_messages() - format_steering_messages() wraps messages in <steering> XML tags - SteeringMessage projection model with steering_queued/delivered events - Fold cases to accumulate and clear pending steering messages --- koan/events.py | 8 ++++++++ koan/phases/format_step.py | 24 ++++++++++++++++++++++++ koan/projections.py | 24 ++++++++++++++++++++++++ koan/state.py | 11 +++++++++++ 4 files changed, 67 insertions(+) diff --git a/koan/events.py b/koan/events.py index 67547e9..c6c2d9f 100644 --- a/koan/events.py +++ b/koan/events.py @@ -264,6 +264,14 @@ def build_default_profile_changed(name: str) -> dict: return {"name": name} +def build_steering_queued(content: str) -> dict: + return {"content": content} + + +def build_steering_delivered(count: int) -> dict: + return {"count": count} + + def build_default_scout_concurrency_changed(value: int) -> dict: return {"value": value} diff --git a/koan/phases/format_step.py b/koan/phases/format_step.py index 6171286..a639402 100644 --- a/koan/phases/format_step.py +++ b/koan/phases/format_step.py @@ -33,6 +33,30 @@ def format_user_messages(messages: list[Any]) -> str: return "\n\n".join(parts) +def format_steering_messages(messages: list[Any]) -> str: + """Format steering queue messages into a clearly demarcated XML block. + + Appended to tool responses so the LLM sees user feedback that arrived + while it was working. The framing instructs the LLM to integrate the + feedback without derailing from the current workflow. + """ + parts = [] + for msg in messages: + ts = datetime.fromtimestamp(msg.timestamp_ms / 1000, tz=timezone.utc) + ts_str = ts.strftime("%H:%M:%S UTC") + parts.append(f"[{ts_str}] {msg.content}") + body = "\n\n".join(parts) + return ( + "\n\n<steering>\n" + "The user sent the following message(s) while you were working.\n" + "Take these into account going forward, but do not abandon the\n" + "current workflow step. Integrate the feedback into your approach.\n" + "\n" + f"{body}\n" + "</steering>" + ) + + def format_phase_boundary(phase: str, messages: list[Any], successors: list[str]) -> str: """Format a phase-boundary response that includes user messages and next-phase options.""" title = f"Phase Complete: {phase}" diff --git a/koan/projections.py b/koan/projections.py index b983934..6196766 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -53,6 +53,9 @@ "debug_step_guidance", # User chat "user_message", + # Steering + "steering_queued", + "steering_delivered", # Focus (interactions) "questions_asked", "questions_answered", @@ -312,6 +315,9 @@ class Notification(KoanBaseModel): # Run and top-level Projection # --------------------------------------------------------------------------- +class SteeringMessage(KoanBaseModel): + content: str + class Run(KoanBaseModel): config: RunConfig phase: str = "" @@ -319,6 +325,7 @@ class Run(KoanBaseModel): focus: Focus | None = None # None before first agent spawns artifacts: dict[str, ArtifactInfo] = {} completion: CompletionInfo | None = None + steering: list[SteeringMessage] = [] # pending steering messages shown above chat class Projection(KoanBaseModel): settings: Settings = Field(default_factory=Settings) @@ -855,6 +862,23 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: "run": _update_agent_conversation(projection.run, pid, new_conv), }) + case "steering_queued": + if projection.run is None: + return projection + entry = SteeringMessage(content=payload.get("content", "")) + return projection.model_copy(update={ + "run": projection.run.model_copy(update={ + "steering": [*projection.run.steering, entry], + }), + }) + + case "steering_delivered": + if projection.run is None: + return projection + return projection.model_copy(update={ + "run": projection.run.model_copy(update={"steering": []}), + }) + case "agent_step_advanced": if projection.run is None or not agent_id: return projection diff --git a/koan/state.py b/koan/state.py index 88fbf6f..ed8b80d 100644 --- a/koan/state.py +++ b/koan/state.py @@ -87,6 +87,10 @@ class AppState: user_message_buffer: list[ChatMessage] = field(default_factory=list) # Non-None while koan_complete_step is blocking at a phase boundary. phase_complete_future: asyncio.Future | None = None + # Steering queue — user messages delivered on the next koan_* tool response. + # Separate from user_message_buffer so phase-boundary blocking and steering + # can be drained independently without double-delivery. + steering_queue: list[ChatMessage] = field(default_factory=list) def drain_user_messages(app_state: AppState) -> list[ChatMessage]: @@ -94,3 +98,10 @@ def drain_user_messages(app_state: AppState) -> list[ChatMessage]: messages = list(app_state.user_message_buffer) app_state.user_message_buffer.clear() return messages + + +def drain_steering_messages(app_state: AppState) -> list[ChatMessage]: + """Atomically drain the steering queue. Returns all buffered messages.""" + messages = list(app_state.steering_queue) + app_state.steering_queue.clear() + return messages From c2a0d1b523de4b0ca8ce9a0b42ea2e8b9b6d5036 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 17:15:32 +0700 Subject: [PATCH 301/412] feat: wire steering queue into tool handlers and message routing - api_chat routes messages to steering_queue (normal) or user_message_buffer (phase boundary) to prevent double-delivery - _drain_and_append_steering appended to every koan_* tool response - Only the orchestrator (is_primary) receives steering; subagents skip - _step_within_phase no longer drains user messages (steering handles it) - _step_phase_boundary drains both queues to catch pre-boundary messages - _log_tool_call adds info logging for every koan tool invocation - Steering delivery logged separately with message previews --- koan/web/app.py | 27 +++++++++----- koan/web/mcp_endpoint.py | 75 ++++++++++++++++++++++++++++++++------ tests/test_interactions.py | 2 + tests/test_subagent.py | 2 + 4 files changed, 85 insertions(+), 21 deletions(-) diff --git a/koan/web/app.py b/koan/web/app.py index bc8d94f..4ea0afe 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -35,6 +35,7 @@ build_questions_answered, build_probe_completed, build_run_started, + build_steering_queued, build_installation_created, build_installation_modified, build_installation_removed, @@ -317,6 +318,7 @@ async def api_start_run(r: Request) -> Response: # Reset run-scoped state st.user_message_buffer.clear() + st.steering_queue.clear() if st.phase_complete_future is not None and not st.phase_complete_future.done(): st.phase_complete_future.set_result(False) st.phase_complete_future = None @@ -351,20 +353,27 @@ async def api_chat(r: Request) -> Response: ts = int(time.time() * 1000) msg = ChatMessage(content=message.strip(), timestamp_ms=ts) - st.user_message_buffer.append(msg) - - # Emit projection event so the message appears in the activity feed + # Route to one buffer based on context to prevent double-delivery. + # During phase-boundary blocking: message is the transition directive. + # Otherwise: message is steering feedback delivered on next tool response. run = st.projection_store.projection.run primary_id = _primary_agent_id(run) if run else None - st.projection_store.push_event( - "user_message", - {"content": msg.content, "timestamp_ms": msg.timestamp_ms}, - agent_id=primary_id, - ) - # Unblock koan_complete_step if it is blocking at a phase boundary if st.phase_complete_future is not None and not st.phase_complete_future.done(): + st.user_message_buffer.append(msg) + # Show inline in the activity feed — this is a direct conversation message + st.projection_store.push_event( + "user_message", + {"content": msg.content, "timestamp_ms": msg.timestamp_ms}, + agent_id=primary_id, + ) st.phase_complete_future.set_result(True) + else: + st.steering_queue.append(msg) + # Show in the steering indicator above chat — not inline + st.projection_store.push_event( + "steering_queued", build_steering_queued(msg.content), + ) return JSONResponse({"ok": True}) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index d15ee98..48f5ed3 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -35,7 +35,7 @@ from ..lib.phase_dag import get_successor_phases, is_valid_transition from ..logger import get_logger from ..phases import PHASE_GUIDANCE_MAP, PhaseContext, StepGuidance -from ..phases.format_step import format_phase_boundary, format_step, format_user_messages +from ..phases.format_step import format_phase_boundary, format_steering_messages, format_step from .interactions import activate_next_interaction, enqueue_interaction if TYPE_CHECKING: @@ -84,14 +84,24 @@ def _get_agent() -> AgentState: return agent +def _log_tool_call(agent: AgentState, tool: str, summary: str) -> None: + """Log an info-level message for every koan tool invocation.""" + phase = _app_state.phase if _app_state else "?" + log.info( + "tool %s | agent=%s role=%s phase=%s | %s", + tool, agent.agent_id[:8], agent.role, phase, summary, + ) + + def begin_tool_call( agent: AgentState, tool: str, args: dict | str, summary: str = "", ) -> str: - """Emit tool_called event and return call_id. No-op if app_state is not set.""" + """Log and emit tool_called event. Returns call_id.""" call_id = str(uuid.uuid4()) + _log_tool_call(agent, tool, summary) if _app_state is None: return call_id from ..events import build_tool_called @@ -135,6 +145,34 @@ def _resolve_epic_dir(agent: AgentState) -> str | None: return None +# -- Steering queue helper ----------------------------------------------------- + +def _drain_and_append_steering(result: str, agent: AgentState | None = None) -> str: + """Drain any queued steering messages and append to a tool result string. + + Only the primary agent (orchestrator) receives steering. Subagents + (scouts, planners, executors) never see user steering messages. + """ + if _app_state is None: + return result + if agent is not None and not agent.is_primary: + return result + from ..state import drain_steering_messages + messages = drain_steering_messages(_app_state) + if messages: + previews = [m.content[:80] for m in messages] + log.info( + "steering delivered | %d message(s): %s", + len(messages), previews, + ) + result += format_steering_messages(messages) + from ..events import build_steering_delivered + _app_state.projection_store.push_event( + "steering_delivered", build_steering_delivered(len(messages)), + ) + return result + + # -- koan_complete_step private helpers ---------------------------------------- async def _step_phase_handshake(agent: AgentState) -> str: @@ -189,9 +227,12 @@ async def _step_within_phase( ctx: PhaseContext, next_step: int, ) -> str: - """Handle normal within-phase step advancement, appending any buffered user messages.""" + """Handle normal within-phase step advancement. + + User messages are not drained here -- they are delivered via the steering + queue which is drained by _drain_and_append_steering after every tool call. + """ assert _app_state is not None - from ..state import drain_user_messages current_step = agent.step @@ -219,11 +260,6 @@ async def _step_within_phase( guidance = phase_module.step_guidance(next_step, ctx) result = format_step(guidance) - # Drain buffered user messages and append to result - messages = drain_user_messages(_app_state) - if messages: - result += "\n\n" + format_user_messages(messages) - if _app_state.debug: _app_state.projection_store.push_event( "debug_step_guidance", @@ -241,7 +277,7 @@ async def _step_phase_boundary( ) -> str: """Handle phase boundary: flush conversation, block for user message, return boundary response.""" assert _app_state is not None - from ..state import drain_user_messages + from ..state import drain_steering_messages, drain_user_messages # Flush pending text/thinking in the projection without adding a duplicate # step header (the step-N header was already emitted when we advanced TO @@ -254,8 +290,9 @@ async def _step_phase_boundary( agent_id=agent.agent_id, ) - # Check for already-buffered messages first - messages = drain_user_messages(_app_state) + # Check for already-buffered messages. Messages that arrived before the + # boundary was set up go to the steering queue; drain both to catch them. + messages = drain_user_messages(_app_state) + drain_steering_messages(_app_state) if not messages: # No messages yet — create Future and block until POST /api/chat resolves it @@ -288,6 +325,7 @@ async def koan_complete_step(thoughts: str = "") -> str: # Step 0: phase handshake (initial call or post-koan_set_phase) if agent.step == 0: result_str = await _step_phase_handshake(agent) + result_str = _drain_and_append_steering(result_str, agent) return result_str phase_module = agent.phase_module @@ -311,10 +349,12 @@ async def koan_complete_step(thoughts: str = "") -> str: return result_str # Phase boundary — block for user input result_str = await _step_phase_boundary(agent, phase_module, ctx) + result_str = _drain_and_append_steering(result_str, agent) return result_str # Normal within-phase advancement result_str = await _step_within_phase(agent, phase_module, ctx, next_step) + result_str = _drain_and_append_steering(result_str, agent) return result_str finally: @@ -400,6 +440,7 @@ async def koan_set_phase(phase: str) -> str: ) result_str = f"Phase set to '{phase}'. Call koan_complete_step to begin." + result_str = _drain_and_append_steering(result_str, agent) return result_str finally: end_tool_call(agent, call_id, "koan_set_phase", result_str) @@ -420,6 +461,7 @@ async def koan_request_scouts(questions: list[dict] | None = None) -> str: try: if not questions: result_str = "No scouts requested." + result_str = _drain_and_append_steering(result_str, agent) return result_str assert _app_state is not None @@ -469,9 +511,11 @@ async def run_scout(scout_task: dict) -> str | None: if not findings: result_str = "No findings returned." + result_str = _drain_and_append_steering(result_str, agent) return result_str result_str = "\n\n---\n\n".join(findings) + result_str = _drain_and_append_steering(result_str, agent) return result_str finally: end_tool_call(agent, call_id, "koan_request_scouts", result_str) @@ -530,6 +574,7 @@ async def koan_ask_question(questions: list[dict] | None = None) -> str: a_text = a.get("answer", "") if isinstance(a, dict) else str(a) lines.append(f"Q: {q_text}\nA: {a_text}") result_str = "\n\n".join(lines) if lines else "No answers provided." + result_str = _drain_and_append_steering(result_str, agent) return result_str finally: end_tool_call(agent, call_id, "koan_ask_question", result_str) @@ -572,6 +617,7 @@ async def koan_review_artifact(path: str = "", description: str = "") -> str: agent.phase_ctx.last_review_accepted = accepted result_str = "ACCEPTED" if accepted else f"REVISION REQUESTED: {response}" + result_str = _drain_and_append_steering(result_str, agent) return result_str finally: end_tool_call(agent, call_id, "koan_review_artifact", result_str) @@ -646,6 +692,7 @@ async def koan_spawn_executor( exit_code = result.exit_code status = "succeeded" if exit_code == 0 else f"failed (exit code {exit_code})" result_str = f"{role} for story '{story_id}' {status}." + result_str = _drain_and_append_steering(result_str, agent) return result_str finally: end_tool_call(agent, call_id, "koan_spawn_executor", result_str) @@ -673,6 +720,7 @@ async def koan_select_story(story_id: str) -> str: "updatedAt": _now_iso(), }) result_str = f"Story '{story_id}' selected for execution." + result_str = _drain_and_append_steering(result_str, agent) return result_str finally: end_tool_call(agent, call_id, "koan_select_story", result_str) @@ -698,6 +746,7 @@ async def koan_complete_story(story_id: str) -> str: "updatedAt": _now_iso(), }) result_str = f"Story '{story_id}' marked as done." + result_str = _drain_and_append_steering(result_str, agent) return result_str finally: end_tool_call(agent, call_id, "koan_complete_story", result_str) @@ -728,6 +777,7 @@ async def koan_retry_story(story_id: str, failure_summary: str) -> str: "updatedAt": _now_iso(), }) result_str = f"Story '{story_id}' queued for retry (attempt {retry_count})." + result_str = _drain_and_append_steering(result_str, agent) return result_str finally: end_tool_call(agent, call_id, "koan_retry_story", result_str) @@ -757,6 +807,7 @@ async def koan_skip_story(story_id: str, reason: str = "") -> str: await save_story_state(epic_dir, story_id, state) result_str = f"Story '{story_id}' skipped." + result_str = _drain_and_append_steering(result_str, agent) return result_str finally: end_tool_call(agent, call_id, "koan_skip_story", result_str) diff --git a/tests/test_interactions.py b/tests/test_interactions.py index 72bb45e..abbd1d1 100644 --- a/tests/test_interactions.py +++ b/tests/test_interactions.py @@ -33,6 +33,8 @@ class FakeAppState: epic_dir: str | None = None projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) phase_complete_future: asyncio.Future | None = None + steering_queue: list = field(default_factory=list) + phase: str = "intake" def _make_interaction( diff --git a/tests/test_subagent.py b/tests/test_subagent.py index fa13a25..d0dfa09 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -39,6 +39,8 @@ class FakeAppState: run_installations: dict = field(default_factory=dict) _active_processes: dict = field(default_factory=dict) phase_complete_future: Any = None + steering_queue: list = field(default_factory=list) + phase: str = "intake" project_dir: str = "" task_description: str = "" From b965c2c13da6cf8c4b7477adbdfeb80e4494252f Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 3 Apr 2026 17:16:04 +0700 Subject: [PATCH 302/412] feat: add steering indicator component above chat input Shows pending steering messages with 'queued' badge above the chat input. Uses the left-border accent card pattern. Messages render as markdown and clear when delivered to the orchestrator via JSON Patch. --- frontend/src/components/ActivityFeed.tsx | 29 +++++++++++++++-- frontend/src/store/index.ts | 5 +++ frontend/src/styles/components.css | 40 ++++++++++++++++++++++++ 3 files changed, 72 insertions(+), 2 deletions(-) diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index 286042b..7eb803e 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -4,6 +4,26 @@ import { useAutoScroll } from '../hooks/useAutoScroll' import { Md } from './Md' import { ChatInput } from './ChatInput' +// -- Steering indicator -------------------------------------------------------- + +function SteeringIndicator() { + const steering = useStore(s => s.run?.steering ?? []) + if (steering.length === 0) return null + return ( + <div className="steering-indicator"> + <div className="steering-header">steering</div> + <div className="steering-messages"> + {steering.map((m, i) => ( + <div key={i} className="steering-message"> + <span className="steering-queued-badge">queued</span> + <Md>{m.content}</Md> + </div> + ))} + </div> + </div> + ) +} + // -- Thinking ------------------------------------------------------------------ function ThinkingCard({ content }: { content: string }) { @@ -205,8 +225,13 @@ export function ActivityFeed() { </div> )} - {/* Chat input — inside the feed card */} - {showChatInput && <ChatInput />} + {/* Steering indicator + chat input — inside the feed card */} + {showChatInput && ( + <> + <SteeringIndicator /> + <ChatInput /> + </> + )} </div> </div> ) diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 3966188..fa53f4f 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -120,6 +120,10 @@ export interface Notification { // -- Run ---------------------------------------------------------------------- +export interface SteeringMessage { + content: string +} + export interface Run { config: RunConfig phase: string @@ -127,6 +131,7 @@ export interface Run { focus: Focus | null artifacts: Record<string, ArtifactInfo> completion: CompletionInfo | null + steering: SteeringMessage[] } // -- Store -------------------------------------------------------------------- diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index f18f33b..48dc2bf 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -1086,6 +1086,46 @@ font-style: italic; } +/* ---- Steering indicator ---- */ +.steering-indicator { + background: var(--copper-bg); + border-left: 3px solid var(--copper); + border-radius: 0 var(--radius-sm) var(--radius-sm) 0; + margin: var(--space-2) 0; + overflow: hidden; +} +.steering-header { + display: flex; + align-items: center; + gap: var(--space-2); + padding: var(--space-2) var(--space-4); + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--copper); +} +.steering-messages { + padding: 0 var(--space-4) var(--space-2); + display: flex; + flex-direction: column; + gap: var(--space-2); +} +.steering-message { + display: flex; + align-items: baseline; + gap: var(--space-2); + color: var(--text); + font-size: var(--font-size-sm); + line-height: 1.4; +} +.steering-message .md-content { display: inline; } +.steering-message .md-content p { display: inline; margin: 0; } +.steering-queued-badge { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--text-muted); + flex-shrink: 0; +} + /* ---- Settings overlay ---- */ .settings-overlay { position: fixed; From d9e1716968ba6d534fd6a8c9c90322de4aa89a0c Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 14:29:39 +0700 Subject: [PATCH 303/412] =?UTF-8?q?rename=20epic=20=E2=86=92=20run/workflo?= =?UTF-8?q?w=20throughout=20codebase?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - EpicPhase → WorkflowPhase in types.py - koan/epic_state.py → koan/run_state.py; load_epic_state → load_run_state, etc. - epic-state.json → run-state.json (on-disk filename) - ~/.koan/epics/ → ~/.koan/runs/ path - AppState.epic_dir → run_dir, AgentState.epic_dir → run_dir - PhaseContext.epic_dir → run_dir - _resolve_epic_dir → _resolve_run_dir in mcp_endpoint.py - error key no_epic_dir → no_run_dir - check_permission epic_dir= → run_dir= param - All phase modules: ctx.epic_dir → ctx.run_dir - Frontend: epic_dir → run_dir in StartRunResult, 'epic-root' → 'run-root' in selectors - All test files: epic_dir → run_dir Also includes all behavioral changes (Steps 1-10): - New koan/lib/workflows.py: Workflow dataclass, PLAN_WORKFLOW, MILESTONES_WORKFLOW - New phases: plan_spec.py, plan_review.py, execute.py - Executor rewritten: 3-step (Comprehend → Plan → Implement) - Remove blocking artifact review gate (koan_review_artifact, ReviewFocus) - koan_spawn_executor → koan_request_executor with artifacts/instructions params - Format phase boundary: suggested phases with descriptions, empty-list stub handling - Workflow selection in api_start_run; workflow field in AppState and Run projection - Frontend: workflow selection cards in LandingPage, remove ArtifactReview component - Tests: delete test_phase_dag.py, add test_workflows.py, update all affected tests --- frontend/src/App.tsx | 2 - frontend/src/api/client.ts | 18 +- frontend/src/components/LandingPage.tsx | 26 +- .../interactions/ArtifactReview.tsx | 68 ----- frontend/src/store/index.ts | 7 +- frontend/src/store/selectors.ts | 2 +- frontend/src/styles/components.css | 102 ------- koan/artifacts.py | 9 +- koan/driver.py | 34 ++- koan/events.py | 35 +-- koan/lib/permissions.py | 65 ++--- koan/lib/phase_dag.py | 28 +- koan/lib/workflows.py | 184 +++++++++++++ koan/logger.py | 4 +- koan/phases/__init__.py | 28 +- koan/phases/brief_writer.py | 47 +--- koan/phases/core_flows.py | 7 +- koan/phases/cross_artifact_validation.py | 3 +- koan/phases/execute.py | 123 +++++++++ koan/phases/executor.py | 217 +++++++-------- koan/phases/format_step.py | 48 +++- koan/phases/intake.py | 254 +++++------------ koan/phases/orchestrator.py | 5 +- koan/phases/plan_review.py | 140 ++++++++++ koan/phases/plan_spec.py | 144 ++++++++++ koan/phases/review_protocol.py | 30 -- koan/phases/tech_plan.py | 3 +- koan/phases/ticket_breakdown.py | 3 +- koan/projections.py | 45 +-- koan/{epic_state.py => run_state.py} | 42 +-- koan/runners/base.py | 3 +- koan/state.py | 11 +- koan/subagent.py | 19 +- koan/types.py | 7 +- koan/web/app.py | 74 +++-- koan/web/interactions.py | 18 +- koan/web/mcp_endpoint.py | 258 +++++++----------- tests/test_interactions.py | 167 +----------- tests/test_mcp_check_or_raise.py | 30 +- tests/test_permissions.py | 43 ++- tests/test_phase_dag.py | 143 ---------- tests/test_phases.py | 221 ++++++++++++--- tests/test_projections.py | 32 +-- tests/test_subagent.py | 36 +-- tests/test_web_flows.py | 10 +- tests/test_workflows.py | 162 +++++++++++ 46 files changed, 1553 insertions(+), 1404 deletions(-) delete mode 100644 frontend/src/components/interactions/ArtifactReview.tsx create mode 100644 koan/lib/workflows.py create mode 100644 koan/phases/execute.py create mode 100644 koan/phases/plan_review.py create mode 100644 koan/phases/plan_spec.py delete mode 100644 koan/phases/review_protocol.py rename koan/{epic_state.py => run_state.py} (56%) delete mode 100644 tests/test_phase_dag.py create mode 100644 tests/test_workflows.py diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 9acb332..c25e2a8 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -11,13 +11,11 @@ import { Notification } from './components/Notification' import { SettingsOverlay } from './components/SettingsOverlay' import { Completion } from './components/Completion' import { AskWizard } from './components/interactions/AskWizard' -import { ArtifactReview } from './components/interactions/ArtifactReview' function InteractionView() { const focus = useStore(s => s.run?.focus) if (!focus) return null if (focus.type === 'question') return <AskWizard /> - if (focus.type === 'review') return <ArtifactReview /> return null } diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 01bdb1b..20463e6 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -32,7 +32,7 @@ async function get<T>(url: string): Promise<T> { export interface StartRunResult { ok: boolean - epic_dir?: string + run_dir?: string error?: string message?: string } @@ -42,6 +42,7 @@ export async function startRun( profile: string, scoutConcurrency?: number, installations?: Record<string, string>, + workflow?: string, ): Promise<StartRunResult> { const body: Record<string, unknown> = { task, profile } if (scoutConcurrency !== undefined) { @@ -50,6 +51,9 @@ export async function startRun( if (installations && Object.keys(installations).length > 0) { body['installations'] = installations } + if (workflow) { + body['workflow'] = workflow + } return post('/api/start-run', body) } @@ -59,18 +63,6 @@ export async function submitAnswer(answers: unknown[], token: string) { return post<{ ok: boolean; message?: string }>('/api/answer', { answers, token }) } -export async function submitArtifactReview( - response: string, - accepted: boolean, - token: string, -) { - return post<{ ok: boolean; message?: string }>('/api/artifact-review', { - response, - accepted, - token, - }) -} - // -- Chat -------------------------------------------------------------------- export async function sendChatMessage(message: string) { diff --git a/frontend/src/components/LandingPage.tsx b/frontend/src/components/LandingPage.tsx index d50c5a7..e985466 100644 --- a/frontend/src/components/LandingPage.tsx +++ b/frontend/src/components/LandingPage.tsx @@ -9,6 +9,7 @@ export function LandingPage() { const [loading, setLoading] = useState(false) const [error, setError] = useState<string | null>(null) const [selectedInstallations, setSelectedInstallations] = useState<Record<string, string>>({}) + const [workflow, setWorkflow] = useState<'plan' | 'milestones'>('plan') // Read from store (fed by SSE — always current, no API fetch needed) const profilesDict = useStore(s => s.settings.profiles) @@ -48,18 +49,13 @@ export function LandingPage() { if (!selectedProfile) return null // Profile tiers map role → value. The fold normalizes tier configs to strings. - // The string may be an installation alias ("claude-default") or a runner type - // ("claude") depending on whether the profile was created from the new or - // legacy format. Try alias lookup first, fall back to runner type. const requiredTypes = new Set<string>() for (const tierVal of Object.values(selectedProfile.tiers)) { if (typeof tierVal === 'string') { const inst = installationsDict[tierVal] if (inst) { - // Value is an installation alias — derive runner type from it requiredTypes.add(inst.runnerType) } else { - // Value is a runner type string (legacy fold normalization) requiredTypes.add(tierVal) } } @@ -118,7 +114,7 @@ export function LandingPage() { setLoading(true) try { const result = await api.startRun( - trimmedTask, profile, scoutConcurrency, selectedInstallations, + trimmedTask, profile, scoutConcurrency, selectedInstallations, workflow, ) if (!result.ok) { setError(result.message ?? 'Failed to start run') @@ -136,6 +132,24 @@ export function LandingPage() { <div className="phase-inner"> <h2 className="phase-heading">New Run</h2> + <div className="question-card"> + <div className="question-header">Workflow</div> + <div className="workflow-options"> + <button + className={`workflow-card${workflow === 'plan' ? ' selected' : ''}`} + onClick={() => setWorkflow('plan')} + > + <strong>Plan</strong> + <span>Plan an implementation approach, review it, then execute</span> + </button> + <button className="workflow-card disabled" disabled> + <strong>Milestones</strong> + <span>Break work into milestones with phased delivery</span> + <span className="badge">coming soon</span> + </button> + </div> + </div> + <div className="question-card"> <div className="question-header">Task</div> <textarea diff --git a/frontend/src/components/interactions/ArtifactReview.tsx b/frontend/src/components/interactions/ArtifactReview.tsx deleted file mode 100644 index a4165cd..0000000 --- a/frontend/src/components/interactions/ArtifactReview.tsx +++ /dev/null @@ -1,68 +0,0 @@ -import { useState } from 'react' -import { useStore } from '../../store/index' -import * as api from '../../api/client' -import { Md } from '../Md' - -export function ArtifactReview() { - const focus = useStore(s => s.run?.focus) - const [feedback, setFeedback] = useState('') - const [submitError, setSubmitError] = useState<string | null>(null) - - if (!focus || focus.type !== 'review') return null - - const { content, description, token } = focus - - const handleAccept = async () => { - const res = await api.submitArtifactReview('', true, token) - if (!res.ok) { - setSubmitError(res.message ?? 'Failed to accept artifact') - } - } - - const handleSendFeedback = async () => { - const res = await api.submitArtifactReview(feedback, false, token) - if (!res.ok) { - setSubmitError(res.message ?? 'Failed to send feedback') - } - } - - return ( - <div className="phase-content"> - <div className="phase-inner"> - <h2 className="phase-heading">Artifact Review</h2> - {description && <p className="phase-status">{description}</p>} - - <div className="artifact-review-content"> - <Md>{content}</Md> - </div> - - <textarea - id="artifact-review-textarea" - className="artifact-review-feedback" - placeholder="Optional feedback..." - value={feedback} - onChange={e => setFeedback(e.target.value)} - /> - - {submitError && <div className="no-runners-msg">{submitError}</div>} - - <div className="form-actions"> - <button - id="btn-send-feedback" - className="btn btn-secondary" - onClick={handleSendFeedback} - > - Send Feedback - </button> - <button - id="btn-accept-artifact" - className="btn btn-primary" - onClick={handleAccept} - > - Accept - </button> - </div> - </div> - </div> - ) -} diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index fa53f4f..b2e065c 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -94,9 +94,8 @@ export interface AskQuestion { export interface ConversationFocus { type: 'conversation'; agentId: string } export interface QuestionFocus { type: 'question'; agentId: string; token: string; questions: AskQuestion[] } -export interface ReviewFocus { type: 'review'; agentId: string; token: string; path: string; description: string; content: string } -export type Focus = ConversationFocus | QuestionFocus | ReviewFocus +export type Focus = ConversationFocus | QuestionFocus // -- Supporting types --------------------------------------------------------- @@ -127,6 +126,7 @@ export interface SteeringMessage { export interface Run { config: RunConfig phase: string + workflow: string // active workflow name agents: Record<string, Agent> focus: Focus | null artifacts: Record<string, ArtifactInfo> @@ -178,7 +178,10 @@ export type KoanStore = typeof useStore // -- ALL_PHASES (frontend-only derivation helper) ---------------------------- export const ALL_PHASES = [ + // Legacy workflow phases 'intake', 'brief-generation', 'core-flows', 'tech-plan', 'ticket-breakdown', 'cross-artifact-validation', 'execution', 'implementation-validation', + // Plan workflow phases + 'plan-spec', 'plan-review', 'execute', ] diff --git a/frontend/src/store/selectors.ts b/frontend/src/store/selectors.ts index 7a4877f..7c4eca2 100644 --- a/frontend/src/store/selectors.ts +++ b/frontend/src/store/selectors.ts @@ -6,7 +6,7 @@ function groupByDirectory(artifacts: ArtifactInfo[]): Record<string, ArtifactInf const tree: Record<string, ArtifactInfo[]> = {} for (const a of artifacts) { const parts = a.path.split('/') - const dir = parts.length > 1 ? parts.slice(0, -1).join('/') : 'epic-root' + const dir = parts.length > 1 ? parts.slice(0, -1).join('/') : 'run-root' if (!tree[dir]) tree[dir] = [] tree[dir].push(a) } diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 48dc2bf..419d620 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -827,108 +827,6 @@ color: var(--text) !important; } -/* ---- Artifact review ---- */ -.artifact-review-content { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-6); - overflow-y: auto; - max-height: 60vh; - margin-bottom: var(--space-4); - font-family: var(--font-sans); - font-size: var(--font-size-md); - line-height: 1.7; - color: var(--text); -} - -.artifact-review-content h1, -.artifact-review-content h2, -.artifact-review-content h3, -.artifact-review-content h4 { - color: var(--text-strong); - margin-top: var(--space-4); - margin-bottom: var(--space-2); -} - -.artifact-review-content h1 { font-size: 1.4em; } -.artifact-review-content h2 { font-size: 1.2em; border-bottom: 1px solid var(--border); padding-bottom: 4px; } -.artifact-review-content h3 { font-size: 1.05em; } - -.artifact-review-content p { margin: var(--space-2) 0; } - -.artifact-review-content ul, -.artifact-review-content ol { - padding-left: var(--space-6); - margin: var(--space-2) 0; -} - -.artifact-review-content li { margin: 2px 0; } - -.artifact-review-content code { - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - padding: 1px 5px; - font-family: var(--font-mono); - font-size: 0.9em; -} - -.artifact-review-content pre { - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - padding: var(--space-4); - overflow-x: auto; - margin: var(--space-2) 0; -} - -.artifact-review-content pre code { - background: none; - border: none; - padding: 0; - font-size: var(--font-size-sm); -} - -.artifact-review-content blockquote { - border-left: 3px solid var(--border); - padding-left: var(--space-4); - color: var(--text-muted); - margin: var(--space-2) 0; -} - -.artifact-review-content strong { color: var(--text-strong); } - -.artifact-review-content a { - color: var(--copper); - text-decoration: underline; -} - -.artifact-review-feedback { - width: 100%; - min-height: 80px; - padding: var(--space-2) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); - font-family: var(--font-sans); - font-size: var(--font-size-md); - resize: vertical; - outline: none; - box-sizing: border-box; - margin-bottom: var(--space-4); -} - -.artifact-review-feedback:focus { - border-color: var(--copper); -} - -.artifact-review-feedback::placeholder { - color: var(--text-muted); - font-style: italic; -} - /* ---- Workflow chat ---- */ .workflow-chat { margin-top: var(--space-4); diff --git a/koan/artifacts.py b/koan/artifacts.py index 5530cba..f2caa12 100644 --- a/koan/artifacts.py +++ b/koan/artifacts.py @@ -1,6 +1,5 @@ -# Artifact listing for workflow-status.md generation. -# Scans epic root .md files and stories/ recursively, excluding subagents/. -# Python port of src/planner/epic/artifacts.ts listArtifacts(). +# Artifact listing for run directory. +# Scans run root .md files and stories/ recursively, excluding subagents/. from __future__ import annotations @@ -8,8 +7,8 @@ from pathlib import Path -def list_artifacts(epic_dir: str | Path) -> list[dict]: - root = Path(epic_dir) +def list_artifacts(run_dir: str | Path) -> list[dict]: + root = Path(run_dir) results: list[dict] = [] # Root-level .md files diff --git a/koan/driver.py b/koan/driver.py index 2615f31..c42ad98 100644 --- a/koan/driver.py +++ b/koan/driver.py @@ -1,4 +1,4 @@ -# Driver -- coordinates the persistent orchestrator for an epic run. +# Driver -- coordinates the persistent orchestrator for a workflow run. # Simplified: spawns one long-lived orchestrator process for the entire run. from __future__ import annotations @@ -6,7 +6,7 @@ from typing import TYPE_CHECKING from .artifacts import list_artifacts -from .epic_state import ensure_subagent_directory +from .run_state import ensure_subagent_directory from .events import build_artifact_diff from .logger import get_logger from .subagent import spawn_subagent @@ -20,11 +20,11 @@ # -- Artifact diff helper ------------------------------------------------------ def _push_artifact_diff(app_state: AppState) -> None: - """Scan epic artifacts and emit per-file diff events against current projection.""" - if not app_state.epic_dir: + """Scan run artifacts and emit per-file diff events against current projection.""" + if not app_state.run_dir: return try: - new_artifacts = list_artifacts(app_state.epic_dir) + new_artifacts = list_artifacts(app_state.run_dir) except Exception: return run = app_state.projection_store.projection.run @@ -45,21 +45,31 @@ async def driver_main(app_state: AppState) -> None: log.info("Driver waiting for start event...") await app_state.start_event.wait() - epic_dir = app_state.epic_dir - if epic_dir is None: - log.error("epic_dir is None after start event -- aborting") + run_dir = app_state.run_dir + if run_dir is None: + log.error("run_dir is None after start event -- aborting") return - app_state.phase = "intake" - app_state.projection_store.push_event("phase_started", {"phase": "intake"}) - subagent_dir = await ensure_subagent_directory(epic_dir, "orchestrator") + # Use workflow's initial phase; default to "intake" if no workflow set + workflow = app_state.workflow + initial_phase = workflow.initial_phase if workflow else "intake" + workflow_name = workflow.name if workflow else "plan" + + app_state.phase = initial_phase + app_state.projection_store.push_event("phase_started", {"phase": initial_phase}) + subagent_dir = await ensure_subagent_directory(run_dir, "orchestrator") + + # Inject phase_guidance for the initial phase so intake adapts to workflow scope + initial_guidance = workflow.phase_guidance.get(initial_phase, "") if workflow else "" task = { "role": "orchestrator", - "epic_dir": epic_dir, + "run_dir": run_dir, "subagent_dir": subagent_dir, "project_dir": app_state.project_dir, "task_description": app_state.task_description, + "workflow": workflow_name, + "phase_instructions": initial_guidance, # scope framing for initial phase } result = await spawn_subagent(task, app_state) diff --git a/koan/events.py b/koan/events.py index c6c2d9f..041d6ce 100644 --- a/koan/events.py +++ b/koan/events.py @@ -23,6 +23,11 @@ def build_run_started( } +def build_workflow_selected(workflow: str) -> dict: + """Build workflow_selected event payload.""" + return {"workflow": workflow} + + def build_agent_spawned(agent: AgentState) -> dict: return { "agent_id": agent.agent_id, @@ -183,34 +188,6 @@ def build_questions_answered( return result -def build_artifact_review_requested( - token: str, - path: str, - description: str, - content: str, -) -> dict: - return { - "token": token, - "path": path, - "description": description, - "content": content, - } - - -def build_artifact_reviewed( - token: str, - accepted: bool | None = None, - response: str | None = None, - cancelled: bool = False, -) -> dict: - result: dict = {"token": token, "cancelled": cancelled} - if accepted is not None: - result["accepted"] = accepted - if response is not None: - result["response"] = response - return result - - # -- Configuration event builders --------------------------------------------- def build_probe_completed(results: dict[str, bool]) -> dict: @@ -274,5 +251,3 @@ def build_steering_delivered(count: int) -> dict: def build_default_scout_concurrency_changed(value: int) -> dict: return {"value": value} - - diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index 62f20d4..18586ab 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -4,7 +4,7 @@ # 1. READ_TOOLS (except bash) always allowed for all roles. # 2. bash is always allowed for non-orchestrator roles; phase-gated for orchestrator. # 3. ROLE_PERMISSIONS controls koan-specific tools and write/edit access. -# 4. Planning roles have write/edit path-scoped to the epic directory. +# 4. Planning roles have write/edit path-scoped to the run directory. # Only executor has unrestricted write access. # 5. The orchestrator role uses phase-aware permissions (current_phase parameter). # @@ -35,7 +35,6 @@ "koan_complete_step", "koan_ask_question", "koan_request_scouts", - "koan_review_artifact", "edit", "write", }), @@ -48,8 +47,7 @@ "koan_set_phase", "koan_ask_question", "koan_request_scouts", - "koan_review_artifact", - "koan_spawn_executor", + "koan_request_executor", "koan_select_story", "koan_complete_story", "koan_retry_story", @@ -91,16 +89,13 @@ # -- Orchestrator phase-specific constants ------------------------------------ _ORCHESTRATOR_SCOUT_PHASES: frozenset[str] = frozenset({ - "intake", "core-flows", "tech-plan", "ticket-breakdown", "cross-artifact-validation", + "intake", "core-flows", "tech-plan", "ticket-breakdown", + "cross-artifact-validation", + "plan-spec", "plan-review", # plan workflow phases }) -_ORCHESTRATOR_REVIEW_PHASES: frozenset[str] = frozenset({ - "intake", "brief-generation", "core-flows", "tech-plan", - "ticket-breakdown", "cross-artifact-validation", "implementation-validation", -}) - -_ORCHESTRATOR_EXECUTION_ONLY: frozenset[str] = frozenset({ - "koan_spawn_executor", "koan_select_story", "koan_complete_story", +_ORCHESTRATOR_STORY_TOOLS: frozenset[str] = frozenset({ + "koan_select_story", "koan_complete_story", "koan_retry_story", "koan_skip_story", }) @@ -115,7 +110,7 @@ def _check_orchestrator_permission( tool_name: str, current_phase: str | None, current_step: int | None, - epic_dir: str | None, + run_dir: str | None, tool_args: dict | None, ) -> dict: """Phase-aware permission check for the persistent orchestrator role. @@ -158,14 +153,14 @@ def _check_orchestrator_permission( return {"allowed": True, "reason": None} return {"allowed": False, "reason": f"koan_request_scouts is not available in phase '{phase}'"} - # koan_review_artifact — most planning phases + implementation-validation - if tool_name == "koan_review_artifact": - if phase in _ORCHESTRATOR_REVIEW_PHASES: + # koan_request_executor — execute and execution phases + if tool_name == "koan_request_executor": + if phase in ("execution", "execute"): return {"allowed": True, "reason": None} - return {"allowed": False, "reason": f"koan_review_artifact is not available in phase '{phase}'"} + return {"allowed": False, "reason": f"koan_request_executor is only available during execution phases"} - # Execution-only tools - if tool_name in _ORCHESTRATOR_EXECUTION_ONLY: + # Story management tools — legacy execution phase only + if tool_name in _ORCHESTRATOR_STORY_TOOLS: if phase == "execution": return {"allowed": True, "reason": None} return {"allowed": False, "reason": f"{tool_name} is only available during the execution phase"} @@ -181,19 +176,19 @@ def _check_orchestrator_permission( ), } # Path scoping - if epic_dir and tool_args: + if run_dir and tool_args: raw_path = tool_args.get("path") if isinstance(raw_path, str): resolved_tool = Path(raw_path).resolve() - resolved_epic = Path(epic_dir).resolve() - if resolved_tool != resolved_epic and not str(resolved_tool).startswith(str(resolved_epic) + "/"): + resolved_run = Path(run_dir).resolve() + if resolved_tool != resolved_run and not str(resolved_tool).startswith(str(resolved_run) + "/"): log.warning( - "Write blocked: path outside epic dir: role=orchestrator tool=%s path=%s epic=%s", - tool_name, raw_path, epic_dir, + "Write blocked: path outside run dir: role=orchestrator tool=%s path=%s run=%s", + tool_name, raw_path, run_dir, ) return { "allowed": False, - "reason": f'{tool_name} path "{raw_path}" is outside epic directory', + "reason": f'{tool_name} path "{raw_path}" is outside run directory', } return {"allowed": True, "reason": None} @@ -203,7 +198,7 @@ def _check_orchestrator_permission( def check_permission( role: str, tool_name: str, - epic_dir: str | None = None, + run_dir: str | None = None, tool_args: dict | None = None, current_step: int | None = None, current_phase: str | None = None, @@ -216,7 +211,7 @@ def check_permission( # Orchestrator uses phase-aware permission logic (handles bash phase-gating). if role == "orchestrator": - return _check_orchestrator_permission(tool_name, current_phase, current_step, epic_dir, tool_args) + return _check_orchestrator_permission(tool_name, current_phase, current_step, run_dir, tool_args) # bash always allowed for non-orchestrator roles. if tool_name == "bash": @@ -228,7 +223,7 @@ def check_permission( "allowed": False, "reason": ( f"{tool_name} is not available during the Read step (step 1). " - "Complete koan_complete_step first to advance to the Draft & Review step." + "Complete koan_complete_step first to advance to the Draft step." ), } @@ -242,21 +237,21 @@ def check_permission( if tool_name not in allowed_tools: return {"allowed": False, "reason": f"{tool_name} is not available for role {role}"} - # Path-scope enforcement: planning roles may only write inside epic dir. + # Path-scope enforcement: planning roles may only write inside run dir. if tool_name in WRITE_TOOLS and role in PLANNING_ROLES: - if epic_dir and tool_args: + if run_dir and tool_args: raw_path = tool_args.get("path") if isinstance(raw_path, str): resolved_tool = Path(raw_path).resolve() - resolved_epic = Path(epic_dir).resolve() - if resolved_tool != resolved_epic and not str(resolved_tool).startswith(str(resolved_epic) + "/"): + resolved_run = Path(run_dir).resolve() + if resolved_tool != resolved_run and not str(resolved_tool).startswith(str(resolved_run) + "/"): log.warning( - "Write blocked: path outside epic dir: role=%s tool=%s path=%s epic=%s", - role, tool_name, raw_path, epic_dir, + "Write blocked: path outside run dir: role=%s tool=%s path=%s run=%s", + role, tool_name, raw_path, run_dir, ) return { "allowed": False, - "reason": f'{tool_name} path "{raw_path}" is outside epic directory', + "reason": f'{tool_name} path "{raw_path}" is outside run directory', } return {"allowed": True, "reason": None} diff --git a/koan/lib/phase_dag.py b/koan/lib/phase_dag.py index 6b37114..0dfac42 100644 --- a/koan/lib/phase_dag.py +++ b/koan/lib/phase_dag.py @@ -1,18 +1,18 @@ -# Phase transition DAG -- the single source of truth for valid epic phase transitions. +# DEPRECATED: This file is superseded by koan/lib/workflows.py. +# PHASE_TRANSITIONS, IMPLEMENTED_PHASES, PHASE_DESCRIPTIONS, get_successor_phases, +# is_valid_transition, is_auto_advance, and is_stub_phase are no longer used +# by the active code path. Kept for reference only. # -# Consulted by: -# - the driver (to decide when to spawn the orchestrator) -# - koan_set_phase (to validate the committed transition) -# -# Pure functions -- no I/O, no mutable state. +# The active code path uses koan/lib/workflows.py for phase transition logic. +# Phase DAG validation has been replaced by workflow membership checks. from __future__ import annotations -from ..types import EpicPhase +from ..types import WorkflowPhase # Valid successor phases for each phase. Order = recommendation priority. # The first entry is the most-recommended default path. -PHASE_TRANSITIONS: dict[EpicPhase, list[EpicPhase]] = { +PHASE_TRANSITIONS: dict[WorkflowPhase, list[WorkflowPhase]] = { "intake": ["brief-generation", "core-flows"], "brief-generation": ["core-flows"], "core-flows": ["tech-plan"], @@ -26,7 +26,7 @@ # Phases that have a real implementation (subagent-backed). # All other non-terminal phases are stubs that auto-advance when reached. -IMPLEMENTED_PHASES: frozenset[EpicPhase] = frozenset({ +IMPLEMENTED_PHASES: frozenset[WorkflowPhase] = frozenset({ "intake", "brief-generation", "core-flows", @@ -37,7 +37,7 @@ }) # Human-readable one-line description of each phase. -PHASE_DESCRIPTIONS: dict[EpicPhase, str] = { +PHASE_DESCRIPTIONS: dict[WorkflowPhase, str] = { "intake": "Multi-round codebase exploration and structured Q&A to align on requirements", "brief-generation": "Distill intake context into a compact product-level epic brief", "core-flows": "Define user journeys with sequence diagrams", @@ -50,19 +50,19 @@ } -def get_successor_phases(phase: EpicPhase) -> list[EpicPhase]: +def get_successor_phases(phase: WorkflowPhase) -> list[WorkflowPhase]: return PHASE_TRANSITIONS.get(phase, []) -def is_auto_advance(phase: EpicPhase) -> bool: +def is_auto_advance(phase: WorkflowPhase) -> bool: return len(get_successor_phases(phase)) == 1 -def is_stub_phase(phase: EpicPhase) -> bool: +def is_stub_phase(phase: WorkflowPhase) -> bool: return phase != "completed" and phase != "implementation-validation" and phase not in IMPLEMENTED_PHASES -def is_valid_transition(from_phase: EpicPhase | None, to_phase: EpicPhase) -> bool: +def is_valid_transition(from_phase: WorkflowPhase | None, to_phase: WorkflowPhase) -> bool: if from_phase is None: return False return to_phase in get_successor_phases(from_phase) diff --git a/koan/lib/workflows.py b/koan/lib/workflows.py new file mode 100644 index 0000000..7fcedf0 --- /dev/null +++ b/koan/lib/workflows.py @@ -0,0 +1,184 @@ +# Workflow definitions for the koan orchestrator. +# +# A Workflow defines the phases available to the orchestrator, their suggested +# transition order, phase descriptions shown at boundaries, and per-phase +# guidance injected into step 1 instructions. +# +# Design notes: +# - frozen=True prevents field reassignment after construction (mutation protection). +# - frozen=True does NOT make Workflow hashable — dict fields are unhashable. +# Do not use Workflow as a dict key or set member. +# - Workflows are defined as module-level constants (PLAN_WORKFLOW, etc.). +# - Phase transition validation: any phase in available_phases is reachable +# from any other (user-directed), except self-transitions. + +from __future__ import annotations + +from dataclasses import dataclass + + +@dataclass(frozen=True) +class Workflow: + """Immutable workflow definition. + + Attributes: + name: Short identifier (e.g. "plan", "milestones"). + description: Human-readable description shown in the UI. + available_phases: All phases the user can transition to in this workflow. + initial_phase: Phase the orchestrator starts in. + suggested_transitions: Per-phase ordered list of suggested next phases. + Guides the orchestrator's boundary response; user can override. + phase_descriptions: One-line description of each phase shown at boundaries. + phase_guidance: Per-phase scope framing injected at the top of step 1 + guidance. Controls investigation depth, question posture, etc. + """ + name: str + description: str + available_phases: tuple[str, ...] + initial_phase: str + suggested_transitions: dict[str, list[str]] + phase_descriptions: dict[str, str] + phase_guidance: dict[str, str] + + +# -- Plan workflow ------------------------------------------------------------- +# intake → plan-spec → plan-review → execute +# Lightweight focused-change pipeline. Single executor spawn. + +PLAN_WORKFLOW = Workflow( + name="plan", + description="Plan an implementation approach, review it, then execute", + available_phases=("intake", "plan-spec", "plan-review", "execute"), + initial_phase="intake", + suggested_transitions={ + "intake": ["plan-spec", "execute"], + "plan-spec": ["plan-review", "execute"], + "plan-review": ["plan-spec", "execute"], + "execute": ["plan-review"], + }, + phase_descriptions={ + "intake": "Explore the codebase and align on requirements through Q&A", + "plan-spec": "Write a technical implementation plan grounded in the codebase", + "plan-review": "Evaluate the plan for completeness, correctness, and risks", + "execute": "Hand off the plan to an executor agent for implementation", + }, + phase_guidance={ + "intake": ( + "## Scope\n" + "This is a **plan** workflow \u2014 typically a focused change touching a\n" + "bounded area of the codebase.\n" + "\n" + "## Downstream consumer\n" + "The landscape.md you produce feeds into **plan-spec**, which writes a\n" + "single implementation plan (plan.md). The plan-spec phase needs enough\n" + "context to write specific file-level instructions, but does not need\n" + "exhaustive coverage of the entire codebase.\n" + "\n" + "## Investigation posture\n" + "- **Prefer direct reading.** For focused changes, reading the referenced\n" + " files yourself is usually faster and more precise than dispatching scouts.\n" + "- **Dispatch scouts** when the task references subsystems you're unfamiliar\n" + " with, or when dependency tracing would require opening more than ~10 files.\n" + "- If you do dispatch scouts, 1\u20133 is typical for a plan workflow.\n" + "\n" + "## Question posture\n" + "- Ask questions when the task has genuine ambiguity that affects approach.\n" + "- For well-specified changes, a single round of 2\u20134 targeted questions\n" + " may suffice \u2014 or none at all if context is clear.\n" + "- Do not force questions when the task description and codebase provide\n" + " sufficient clarity.\n" + "\n" + "## User override\n" + "The user can always ask you to go deeper, dispatch more scouts, or ask\n" + "more questions. Follow their lead over these defaults." + ), + "execute": ( + "## What to hand off\n" + "Call `koan_request_executor` with:\n" + "- **artifacts**: `[\"plan.md\"]` \u2014 the implementation plan. Include\n" + " `\"landscape.md\"` if it contains context beyond what's in the plan.\n" + "- **instructions**: Key decisions from plan-review, user clarifications,\n" + " or constraints. Do NOT repeat plan.md contents \u2014 the executor reads\n" + " it directly. Instructions are for context that isn't in the files.\n" + "\n" + "## After execution\n" + "Report the result. If the executor failed or asked questions, relay\n" + "the situation to the user and suggest next steps." + ), + }, +) + + +# -- Milestones workflow (stub) ----------------------------------------------- +# Runs intake only. Phase boundary reports the workflow is not yet implemented. + +MILESTONES_WORKFLOW = Workflow( + name="milestones", + description="Break work into milestones with phased delivery (coming soon)", + available_phases=("intake",), + initial_phase="intake", + suggested_transitions={"intake": []}, + phase_descriptions={ + "intake": "Explore the codebase and align on requirements through Q&A", + }, + phase_guidance={ + "intake": ( + "## Scope\n" + "This is a **milestones** workflow \u2014 a broad initiative that may span\n" + "multiple subsystems and require significant codebase exploration.\n" + "\n" + "## Downstream consumer\n" + "The landscape.md you produce feeds into milestone decomposition and\n" + "multi-phase planning. Downstream phases need comprehensive coverage:\n" + "every affected subsystem, integration point, and constraint must be\n" + "documented.\n" + "\n" + "## Investigation posture\n" + "- **Dispatch scouts broadly.** Explore every subsystem the task touches\n" + " and adjacent areas that might be affected. 3\u20135 scouts is typical.\n" + "- **Also read directly** \u2014 verify key scout findings against the actual\n" + " code, especially integration points and conventions.\n" + "\n" + "## Question posture\n" + "- Ask multiple rounds of questions. For broad initiatives, 2\u20133 rounds\n" + " of 3\u20136 questions is typical.\n" + "- Surface assumptions early. Each answer may reveal new areas to probe.\n" + "- Probe cross-cutting concerns: shared patterns, naming conventions,\n" + " error handling strategies, test coverage expectations.\n" + "\n" + "## User override\n" + "The user can always tell you to narrow scope or skip questions.\n" + "Follow their lead over these defaults." + ), + }, +) + + +# -- Registry ----------------------------------------------------------------- + +WORKFLOWS: dict[str, Workflow] = { + "plan": PLAN_WORKFLOW, + "milestones": MILESTONES_WORKFLOW, +} + + +def get_workflow(name: str) -> Workflow: + """Return the Workflow for the given name, or raise ValueError.""" + wf = WORKFLOWS.get(name) + if wf is None: + raise ValueError(f"Unknown workflow: {name!r}. Valid: {list(WORKFLOWS)}") + return wf + + +def get_suggested_phases(workflow: Workflow, phase: str) -> list[str]: + """Return the ordered suggested next phases for the current phase.""" + return list(workflow.suggested_transitions.get(phase, [])) + + +def is_valid_transition(workflow: Workflow, from_phase: str, to_phase: str) -> bool: + """Any phase in the workflow is reachable from any other (except self-transition). + + The user drives macro-level progression; suggested_transitions guides defaults + but does not constrain choices. + """ + return to_phase in workflow.available_phases and to_phase != from_phase diff --git a/koan/logger.py b/koan/logger.py index e8c1fdc..b328031 100644 --- a/koan/logger.py +++ b/koan/logger.py @@ -22,9 +22,9 @@ def setup_logging(level: str = "INFO") -> None: root.addHandler(handler) -def set_log_dir(epic_dir: str) -> None: +def set_log_dir(run_dir: str) -> None: root = logging.getLogger("koan") - log_path = Path(epic_dir) / "koan.log" + log_path = Path(run_dir) / "koan.log" log_path.parent.mkdir(parents=True, exist_ok=True) handler = logging.FileHandler(str(log_path)) diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index aa046d9..9ff5dce 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -19,12 +19,13 @@ class StepGuidance: @dataclass class PhaseContext: - epic_dir: str + run_dir: str subagent_dir: str project_dir: str = "" task_description: str = "" + workflow_name: str = "" # populated from task["workflow"] phase_instructions: str | None = None - last_review_accepted: bool | None = None + executor_artifacts: list[str] = field(default_factory=list) # for executor subagent proposal_made: bool = False next_phase_set: bool = False step_sequence: str | None = None @@ -57,10 +58,15 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> " execution pipeline from start to finish in a single continuous session.\n" "\n" "You work through phases in sequence: each phase has numbered steps. Call" - " koan_complete_step to advance through steps. When a phase ends," - " koan_complete_step will return the user's message and available next phases." - " Converse with the user about what to do next, then call koan_set_phase to" - " commit the transition.\n" + " koan_complete_step to advance through steps.\n" + "\n" + "When a phase ends, koan_complete_step returns the user's message and" + " suggested next phases with descriptions. At each phase boundary:\n" + "1. Briefly summarize what was accomplished and what artifacts were produced.\n" + "2. Present the suggested phases, explaining what each one does in plain" + " language (use the descriptions from the boundary response).\n" + "3. Ask the user what they would like to do next.\n" + "4. Only call koan_set_phase after the user has confirmed the direction.\n" "\n" "At the start of each phase, koan_complete_step returns your role context for" " that phase alongside the first step's instructions.\n" @@ -86,6 +92,9 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> scout, tech_plan as planner, ticket_breakdown, + execute as execute_phase, + plan_review, + plan_spec, ) from typing import Any @@ -98,10 +107,11 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> } # -- Phase guidance map ------------------------------------------------------- -# Maps EpicPhase strings to the phase module that provides step guidance. +# Maps WorkflowPhase strings to the phase module that provides step guidance. # Used by koan_set_phase to load the module for the new phase. PHASE_GUIDANCE_MAP: dict[str, Any] = { + # Legacy workflow phases (dead code — no active workflow uses these) "intake": intake, "brief-generation": brief_writer, "core-flows": core_flows, @@ -110,4 +120,8 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> "cross-artifact-validation": cross_artifact_validation, "execution": executor, "implementation-validation": cross_artifact_validation, + # Plan workflow phases + "plan-spec": plan_spec, + "plan-review": plan_review, + "execute": execute_phase, } diff --git a/koan/phases/brief_writer.py b/koan/phases/brief_writer.py index fbeba51..f93efd2 100644 --- a/koan/phases/brief_writer.py +++ b/koan/phases/brief_writer.py @@ -1,23 +1,22 @@ -# Brief-writer phase -- 3-step workflow. +# Brief-writer phase -- 2-step workflow (collapsed from 3). # -# Step 1 (Read) -- read landscape.md; build mental model; no writes -# Step 2 (Draft & Review) -- write brief.md + review gate (loops until Accept) -# Step 3 (Finalize) -- phase complete +# Step 1 (Read) -- read landscape.md; build mental model; no writes +# Step 2 (Draft) -- write brief.md; artifact available in panel # -# Step 2 is review-gated via validate_step_completion. +# Review gate removed (D1): step 2 completes unconditionally. +# SCOPE="legacy": part of the old epic pipeline, not used by any active workflow. from __future__ import annotations from . import PhaseContext, StepGuidance -from .review_protocol import REVIEW_PROTOCOL ROLE = "brief-writer" -TOTAL_STEPS = 3 +SCOPE = "legacy" +TOTAL_STEPS = 2 STEP_NAMES: dict[int, str] = { 1: "Read", - 2: "Draft & Review", - 3: "Finalize", + 2: "Draft", } SYSTEM_PROMPT = ( @@ -32,7 +31,7 @@ "\n" "## Output\n" "\n" - "One file: **brief.md** in the epic directory.\n" + "One file: **brief.md** in the run directory.\n" "\n" "## Structure\n" "\n" @@ -43,8 +42,6 @@ "\n" "Keep the brief compact -- under 50 lines. No UI flows, no technical design," " no implementation details.\n" - "\n" - + REVIEW_PROTOCOL ) @@ -53,7 +50,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: if step == 1: lines = [ - f"Read `{ctx.epic_dir}/landscape.md`. Build a thorough mental model of:", + f"Read `{ctx.run_dir}/landscape.md`. Build a thorough mental model of:", "", "- Task Summary -- what is being built or changed", "- Prior Art -- previous attempts, related systems, or prior conversations", @@ -71,43 +68,27 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: return StepGuidance( title=STEP_NAMES[2], instructions=[ - f"Draft `{ctx.epic_dir}/brief.md` with the required sections", + f"Draft `{ctx.run_dir}/brief.md` with the required sections", "(Summary, Context & Problem, Goals, Constraints). Keep it under 50", "lines. No UI flows, no technical design, no implementation details.", "", - f"After writing, invoke `koan_review_artifact` with the path to `{ctx.epic_dir}/brief.md`.", + "brief.md is now available in the artifacts panel for review.", + "Call `koan_complete_step` when done.", ], ) - if step == 3: - return StepGuidance(title=STEP_NAMES[3], instructions=["Phase complete."]) - return StepGuidance(title=f"Step {step}", instructions=[f"Execute step {step}."]) # -- Lifecycle ----------------------------------------------------------------- def get_next_step(step: int, ctx: PhaseContext) -> int | None: - if step == 0: - return 1 if step == 1: return 2 - if step == 2: - if ctx.last_review_accepted is True: - return 3 - return 2 - if step == 3: - return None - return None + return None # step 2 is terminal def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: - if step != 2: - return None - if ctx.last_review_accepted is None: - return "You must call koan_review_artifact to present brief.md for review before completing this step." - if ctx.last_review_accepted is False: - return "The user requested revisions. Address the feedback, then call koan_review_artifact again." return None diff --git a/koan/phases/core_flows.py b/koan/phases/core_flows.py index 6200814..011930c 100644 --- a/koan/phases/core_flows.py +++ b/koan/phases/core_flows.py @@ -10,6 +10,7 @@ from . import PhaseContext, StepGuidance ROLE = "decomposer" +SCOPE = "legacy" TOTAL_STEPS = 2 STEP_NAMES: dict[int, str] = { @@ -71,8 +72,8 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "## Files to read", "", - f"- `{ctx.epic_dir}/landscape.md` -- task summary, prior art, codebase findings, project conventions, decisions, and constraints", - f"- `{ctx.epic_dir}/brief.md` -- epic brief: problem statement, goals, and constraints", + f"- `{ctx.run_dir}/landscape.md` -- task summary, prior art, codebase findings, project conventions, decisions, and constraints", + f"- `{ctx.run_dir}/brief.md` -- epic brief: problem statement, goals, and constraints", "", "## What to understand", "", @@ -92,7 +93,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: instructions=[ "Produce the core-flows document with user journeys and sequence diagrams.", "", - f"Write `{ctx.epic_dir}/core-flows.md` with one section per user journey.", + f"Write `{ctx.run_dir}/core-flows.md` with one section per user journey.", "", "For each journey include:", "- Journey name, actor, and trigger", diff --git a/koan/phases/cross_artifact_validation.py b/koan/phases/cross_artifact_validation.py index a784ecb..da04a20 100644 --- a/koan/phases/cross_artifact_validation.py +++ b/koan/phases/cross_artifact_validation.py @@ -10,6 +10,7 @@ from . import PhaseContext, StepGuidance ROLE = "cross-artifact-validator" +SCOPE = "legacy" TOTAL_STEPS = 2 STEP_NAMES: dict[int, str] = { @@ -58,7 +59,7 @@ # -- Step guidance ------------------------------------------------------------- def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: - ed = ctx.epic_dir + ed = ctx.run_dir if step == 1: return StepGuidance( diff --git a/koan/phases/execute.py b/koan/phases/execute.py new file mode 100644 index 0000000..cf25770 --- /dev/null +++ b/koan/phases/execute.py @@ -0,0 +1,123 @@ +# Execute phase (orchestrator-side) -- 2-step workflow. +# +# Step 1 (Compose) -- read artifacts; compose koan_request_executor call +# Step 2 (Request) -- call koan_request_executor; report result +# +# General-purpose: reusable by any workflow. The workflow's phase_guidance["execute"] +# controls what artifacts and instructions the orchestrator hands off. +# Scope: "general" -- not tied to a specific workflow. + +from __future__ import annotations + +from . import PhaseContext, StepGuidance + +ROLE = "orchestrator" +SCOPE = "general" # reusable by any workflow +TOTAL_STEPS = 2 + +STEP_NAMES: dict[int, str] = { + 1: "Compose", + 2: "Request", +} + +SYSTEM_PROMPT = ( + "You are an execution coordinator. You translate accumulated session knowledge" + " into a structured executor handoff. You do NOT write code.\n" + "\n" + "## Your role\n" + "\n" + "You compose a `koan_request_executor` call with the right artifacts and" + " instructions, then spawn the executor and report the result.\n" + "\n" + "## What the executor needs\n" + "\n" + "- **artifacts**: File paths relative to the run directory that the executor\n" + " must read before coding. These are the primary source of truth.\n" + "- **instructions**: Free-form context NOT captured in the artifact files:\n" + " key decisions from plan-review, user clarifications, constraints.\n" + " Do NOT repeat artifact contents -- the executor reads them directly.\n" + "\n" + "## Strict rules\n" + "\n" + "- MUST call koan_request_executor and wait for it to complete.\n" + "- MUST NOT write code yourself.\n" + "- MUST report the result to the user after the executor exits.\n" +) + + +# -- Step guidance ------------------------------------------------------------- + +def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: + if step == 1: + lines = [ + "Read the artifacts and compose the executor handoff. Do NOT call koan_request_executor yet.", + "", + ] + + if ctx.phase_instructions: + lines.extend([ + "## Workflow guidance", + "", + ctx.phase_instructions, + "", + ]) + + lines.extend([ + "## Compose the koan_request_executor call", + "", + "Review the artifacts the executor will need and decide:", + "- **artifacts**: Which files in the run directory should the executor read?", + " Include the plan (plan.md) and any other files with context not captured", + " in the plan itself.", + "- **instructions**: What context from this session is not in the artifact files?", + " Include: key findings from plan-review, user clarifications received,", + " constraints emphasized by the user. Keep it concise.", + "", + "Call `koan_complete_step` with the composed call parameters (artifacts list", + "and instructions text) so they appear in the audit trail before execution.", + ]) + return StepGuidance(title=STEP_NAMES[1], instructions=lines) + + if step == 2: + return StepGuidance( + title=STEP_NAMES[2], + instructions=[ + "Call `koan_request_executor` with the artifacts and instructions from step 1.", + "", + "```", + "koan_request_executor(", + ' artifacts=["plan.md", ...],', + ' instructions="...",', + ")", + "```", + "", + "This tool blocks until the executor exits. While it's running, the", + "executor is implementing the changes.", + "", + "## After the executor exits", + "", + "Report the result to the user:", + "- If succeeded: summarize what was implemented.", + "- If failed: relay the failure and suggest next steps (re-run, plan revision, etc.).", + "", + "Then call `koan_complete_step` to trigger the phase boundary.", + ], + ) + + return StepGuidance(title=f"Step {step}", instructions=[f"Execute step {step}."]) + + +# -- Lifecycle ----------------------------------------------------------------- + +def get_next_step(step: int, ctx: PhaseContext) -> int | None: + if step < TOTAL_STEPS: + return step + 1 + return None # linear + + +def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: + return None + + +async def on_loop_back(from_step: int, to_step: int, ctx: PhaseContext) -> None: + pass diff --git a/koan/phases/executor.py b/koan/phases/executor.py index 6410a14..6327aaf 100644 --- a/koan/phases/executor.py +++ b/koan/phases/executor.py @@ -1,180 +1,159 @@ -# Executor phase -- 2-step workflow. +# Executor phase -- 3-step workflow. # -# Step 1 (Comprehension) -- read and understand the implementation plan -# Step 2 (Implementation) -- implement the plan step by step +# Step 1 (Comprehend) -- read artifacts and codebase; build mental model +# Step 2 (Plan) -- explain implementation approach (no file written) +# Step 3 (Implement) -- implement all changes # # The executor is the only agent that writes source code. +# Scope: "general" -- reusable by any workflow. from __future__ import annotations from . import PhaseContext, StepGuidance ROLE = "executor" -TOTAL_STEPS = 2 +SCOPE = "general" # reusable by any workflow +TOTAL_STEPS = 3 STEP_NAMES: dict[int, str] = { - 1: "Comprehension", - 2: "Implementation", + 1: "Comprehend", + 2: "Plan", + 3: "Implement", } SYSTEM_PROMPT = ( - "You are a coding agent. You implement changes to a codebase by following a" - " detailed plan written by a planner. You are the only agent in the koan" - " workflow that writes source code.\n" + "You are a coding agent. You implement changes to a codebase based on" + " artifacts and instructions provided by the orchestrator.\n" "\n" - "## Your role\n" + "You receive artifact files to read and free-form instructions. You plan" + " your approach, then implement. You are the only agent that writes source" + " code.\n" "\n" - "You receive a plan (plan/plan.md) and supporting context (plan/context.md)," - " and you implement each step in order. You do not design. You do not make" - " architectural decisions. You execute the plan faithfully.\n" + "## Resolve trivial issues independently\n" "\n" - "## What you receive\n" + "- Incorrect file paths or function names in artifacts \u2192 find correct ones\n" + "- Syntax errors or typos in plan snippets \u2192 fix them\n" + "- Minor import adjustments \u2192 handle them\n" + "- Obvious missing error handling \u2192 add it\n" "\n" - "- **plan/plan.md**: A numbered list of implementation steps. Each step specifies" - " the file, location, action, and exact change to make.\n" - "- **plan/context.md**: Curated code snippets for the files you will modify --" - " function signatures, type definitions, and import blocks.\n" - "- **retryContext** (when present): A failure summary from a previous execution" - " attempt. Read it carefully -- it describes what went wrong and what you should" - " do differently.\n" + "## Call koan_ask_question only when\n" "\n" - "## How to work\n" + "- The artifacts are genuinely ambiguous about *what* to build\n" + "- You discover a conflict between plan and codebase that isn't trivial\n" + "- A dependency or prerequisite is missing that blocks implementation\n" "\n" - "Work through the plan steps in order. Before touching any file:\n" + "## Strict rules\n" "\n" - "1. Read the file to understand its current state. Plan/context.md is a snapshot;" - " the file may have changed due to earlier steps in this execution.\n" - "2. Identify exactly where the change goes.\n" - "3. Make the change precisely -- no more, no less.\n" - "4. Verify the change looks correct before moving on.\n" - "\n" - "## When plan and reality diverge\n" - "\n" - "If what you find in the codebase does not match what the plan describes -- the" - " function doesn't exist, the signature is different, the file structure changed" - " -- you MUST stop immediately and call `koan_ask_question`. Do not improvise a" - " solution. Do not make assumptions.\n" - "\n" - "Describe:\n" - "- Which plan step you are on\n" - "- What the plan expected to find\n" - "- What you actually found\n" - "- What you need to know to proceed\n" - "\n" - "Improvised solutions that seem reasonable in isolation frequently break other" - " parts of the system that are not visible in your context window.\n" - "\n" - "## Strict rules -- violations cause retry cycles\n" - "\n" - "- MUST implement steps in the order specified by the plan.\n" - "- MUST NOT skip any step, even if it seems redundant.\n" - "- MUST NOT add features, functions, or logic that the plan does not specify.\n" - "- MUST NOT refactor code that the plan does not mention -- even if you notice an improvement opportunity.\n" - "- MUST NOT modify test expectations to make tests pass. If a test fails after your implementation, report it via koan_ask_question.\n" - "- MUST read each file before modifying it. Context.md is a reference, not a guarantee of current state.\n" - "- MUST call koan_ask_question immediately when plan assumptions don't hold. Do not continue to the next step.\n" - "\n" - "## On retries\n" - "\n" - "If retryContext is present, this is your second (or later) attempt at this story." - " The failure summary tells you what went wrong. Read it before you read the plan," - " and keep the failure context in mind as you implement. Do not repeat the mistake" - " from the previous attempt." + "- MUST read all listed artifacts before writing any code.\n" + "- MUST NOT add features the instructions don't mention.\n" + "- MUST NOT refactor code the plan doesn't touch.\n" + "- MUST NOT modify test expectations to make tests pass -- report via koan_ask_question.\n" ) # -- Step guidance ------------------------------------------------------------- def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: - sid = ctx.story_id or "<story-id>" - ed = ctx.epic_dir - if step == 1: lines = [ - f"Read and fully understand the implementation plan for story `{sid}` before writing any code.", + "Read and understand the implementation scope before writing any code.", "", - "## What to read", + "## Artifacts to read", "", - f"1. Read `{ed}/stories/{sid}/plan/plan.md` -- read every step from start to finish. Do not skim.", - f"2. Read `{ed}/stories/{sid}/plan/context.md` -- understand the function signatures, types, and imports for every file the plan touches.", ] + + if ctx.executor_artifacts: + for artifact in ctx.executor_artifacts: + lines.append(f"- `{ctx.run_dir}/{artifact}`") + else: + lines.append("(No specific artifacts listed -- read all relevant files in the run directory.)") + + lines.extend([ + "", + "## Instructions from orchestrator", + "", + ctx.phase_instructions or "(no additional instructions)", + "", + "## What to understand", + "", + "Read every artifact. For each file or module they reference, open it and", + "understand its current state. Build a mental model of:", + "- What changes are needed", + "- Which files are affected", + "- What order makes sense", + "- Any risks or edge cases", + "", + "Do NOT write code in this step.", + "", + "Call `koan_complete_step` with a comprehension summary:", + "- What you will change and in what order", + "- Files affected", + "- Any ambiguities or concerns (do not block on these -- note them)", + ]) + if ctx.retry_context: lines.extend([ "", "## Retry context -- read this first", "", - "This is a retry attempt. A previous execution of this story failed. The failure summary is:", + "This is a retry attempt. A previous execution failed. The failure summary is:", "", ctx.retry_context, "", - "Keep this failure context in mind as you read the plan. Identify which step caused the failure and what you will do differently.", + "Keep this in mind as you read the artifacts.", ]) - lines.extend([ - "", - "## What to understand", - "", - "After reading, you must be able to answer these questions without referring back to the files:", - "", - "- How many steps are in the plan?", - "- Which files will you modify?", - "- What is the dependency order between steps?", - "- Are there any steps that touch the same file (potential ordering conflicts)?", - "- What types or interfaces are central to the changes?", - "", - "Do NOT start writing code in this step. Comprehension only.", - "", - "Call koan_complete_step with your comprehension summary:", - "- Number of steps", - "- List of files to modify", - "- Any ambiguities or concerns you spotted in the plan (do not block on these -- note them)", - ]) - if ctx.retry_context: - lines.append("- How you plan to avoid the previous failure") + return StepGuidance(title=STEP_NAMES[1], instructions=lines) if step == 2: return StepGuidance( title=STEP_NAMES[2], instructions=[ - f"Implement the plan for story `{sid}` step by step.", + "Explain your implementation approach before coding.", "", - "## Execution protocol", + "Walk through in your response:", + "- What you will change and in what order", + "- Any risks or edge cases you identified", + "- How you will verify the changes work", "", - "Work through plan/plan.md in order. For each step:", + "Do NOT write a plan file. This is your reasoning made visible for the", + "audit trail, communicated as a regular response.", "", - "1. **Read the target file** -- do not rely solely on plan/context.md; read the actual current state of the file.", - "2. **Locate the change site** -- find the exact function, class, or section described in the plan step.", - "3. **Verify your assumption** -- confirm that what you find matches what the plan describes. If it does not match, call koan_ask_question immediately.", - "4. **Make the change** -- implement exactly what the plan step specifies. No more, no less.", - "5. **Move to the next step** -- do not review or revisit previous steps.", - "", - "## Plan-reality mismatch protocol", + "Call `koan_complete_step` with your approach summary.", + ], + ) + + if step == 3: + return StepGuidance( + title=STEP_NAMES[3], + instructions=[ + "Implement the changes according to your plan from step 2.", "", - "If at any point the codebase does not match the plan's description:", + "For each change:", + "1. Read the target file to confirm its current state.", + "2. Make the change.", + "3. Move to the next change.", "", - "- STOP immediately. Do not attempt to adapt the plan.", - "- Call `koan_ask_question` with:", - " - The plan step number and description", - " - What the plan expected", - " - What you actually found", - " - What specific information you need to proceed", + "## Trivial issues", "", - "## Common pitfalls", + "Resolve independently:", + "- Wrong path \u2192 find the correct one", + "- Typo or syntax error in plan \u2192 fix it", + "- Missing import \u2192 add it", "", - "- Do not add logging, error handling, or validation beyond what the plan specifies.", - "- Do not fix code style issues you notice in passing.", - "- Do not update imports for files not mentioned in the plan.", - "- Do not change test files unless a plan step explicitly says to.", - "- Do not run the tests yourself -- the orchestrator will verify.", + "## Genuine ambiguity", "", - "## When all steps are complete", + "Call `koan_ask_question` when:", + "- Artifacts are ambiguous about what to build", + "- You discover a plan/codebase conflict that isn't trivial", + "- A prerequisite is missing that blocks implementation", "", - "Review your changes at a high level: are all plan steps implemented? Did you accidentally modify something you shouldn't have? Correct any accidental changes.", + "## When done", "", - "Then call koan_complete_step with a summary of what you implemented:", - "- Each plan step: completed or skipped (with reason if skipped)", + "Verify your work (run builds/tests if relevant).", + "Call `koan_complete_step` with a summary of what was implemented:", "- Files modified", - "- Any concerns or observations for the orchestrator", + "- Any concerns or observations", ], ) diff --git a/koan/phases/format_step.py b/koan/phases/format_step.py index a639402..8ae5bb3 100644 --- a/koan/phases/format_step.py +++ b/koan/phases/format_step.py @@ -57,8 +57,17 @@ def format_steering_messages(messages: list[Any]) -> str: ) -def format_phase_boundary(phase: str, messages: list[Any], successors: list[str]) -> str: - """Format a phase-boundary response that includes user messages and next-phase options.""" +def format_phase_boundary( + phase: str, + messages: list[Any], + suggested: list[str], + phase_descriptions: dict[str, str] | None = None, +) -> str: + """Format a phase-boundary response with user messages and suggested next phases. + + If suggested is empty (stub workflow), renders a graceful end-of-workflow message + instead of an empty phases section. + """ title = f"Phase Complete: {phase}" lines = [title, "=" * len(title), ""] @@ -71,16 +80,29 @@ def format_phase_boundary(phase: str, messages: list[Any], successors: list[str] lines.append(f"**[{ts_str}]** {msg.content}") lines.append("") - lines.append("## Available Next Phases") - lines.append("") - for s in successors: - lines.append(f"- **{s}**") - lines.append("") - - lines.append("## Instructions") - lines.append("") - lines.append("Discuss the completed phase and the user's message(s) with the user.") - lines.append("Once the user has confirmed what to do next, call `koan_set_phase` with") - lines.append("the chosen phase name. Then call `koan_complete_step` to begin.") + if suggested: + descs = phase_descriptions or {} + lines.append("## Suggested Next Phases") + lines.append("") + for s in suggested: + desc = descs.get(s, "") + if desc: + lines.append(f"- **{s}** \u2014 {desc}") + else: + lines.append(f"- **{s}**") + lines.append("") + lines.append("## Instructions") + lines.append("") + lines.append("Briefly summarize what was accomplished in this phase. Present the") + lines.append("suggested phases above to the user, explaining what each one does.") + lines.append("Ask which direction they would like to go. The user can also request") + lines.append("any other phase available in this workflow.") + lines.append("Once confirmed, call `koan_set_phase` then `koan_complete_step`.") + else: + lines.append("## Workflow Stub") + lines.append("") + lines.append("This workflow does not have further phases implemented yet.") + lines.append("Summarize what was accomplished in intake and let the user know") + lines.append("the workflow will end here for now.") return "\n".join(lines) diff --git a/koan/phases/intake.py b/koan/phases/intake.py index ad8986c..c48ac10 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -2,16 +2,17 @@ # # Step 1 (Gather) -- read task description, explore obvious files, dispatch scouts # Step 2 (Deepen) -- process scout results, verify, deepen through dialogue -# Step 3 (Write) -- write landscape.md, present for user review +# Step 3 (Write) -- write landscape.md # -# Step 3 is review-gated: blocks until koan_review_artifact accepted. +# Review gate removed (D1): step 3 completes unconditionally. +# Prompt injection model (D8): workflow scope framing appears at top of step 1. from __future__ import annotations from . import PhaseContext, StepGuidance -from .review_protocol import REVIEW_PROTOCOL ROLE = "intake" +SCOPE = "general" # reusable by any workflow TOTAL_STEPS = 3 STEP_NAMES: dict[int, str] = { @@ -26,13 +27,13 @@ " have complete context for planning.\n" "\n" "Your output -- a single landscape.md file -- is the sole foundation for all" - " downstream work. Every story boundary, every implementation plan, and every" - " line of code written downstream depends on the quality and completeness of" - " this file. Gaps here compound into wrong plans and wrong code.\n" + " downstream work. Every downstream phase and every implementation decision" + " depends on the quality and completeness of this file. Gaps here compound" + " into wrong plans and wrong code.\n" "\n" - "An assumption you make without verifying will become a fact the decomposer" - " treats as decided. A question you don't ask is an answer you're making up." - " When the executor writes the wrong code because landscape.md contained an" + "An assumption you make without verifying will become a fact that downstream" + " phases treat as decided. A question you don't ask is an answer you're making" + " up. When the executor writes the wrong code because landscape.md contained an" " unchecked assumption, that failure traces back to this phase.\n" "\n" "## Your role\n" @@ -47,7 +48,7 @@ "- MUST NOT add architectural opinions or suggest approaches.\n" "- MUST NOT produce implementation recommendations.\n" "- MUST NOT define deliverables, work units, or scope boundaries -- that" - " belongs to the decomposer.\n" + " belongs to downstream phases.\n" "- MUST capture only what was explicitly said. If unclear, mark it as unresolved.\n" "- SHOULD prefer multiple-choice questions when the answer space is bounded.\n" "- SHOULD ground questions in codebase findings.\n" @@ -71,41 +72,6 @@ "prompts, questions) and written artifacts (landscape.md) should remain\n" "clear and complete.\n" "\n" - "Examples of target density (WRONG -> RIGHT):\n" - "\n" - "Processing scout reports:\n" - " WRONG: \"The kernel-structure scout found that CUDA kernels live in src/kernels/\n" - " and use shared memory for the parallel reduction step. The build-system scout\n" - " found CMake with FindCUDAToolkit. The host-code scout reports that device memory\n" - " is allocated with cudaMalloc and copied back with cudaMemcpy. This answers my\n" - " questions about project structure. Nothing unexpected so far.\"\n" - " RIGHT: \"kernel-structure scout: src/kernels/, shared mem for reductions\n" - " build-system scout: CMake + FindCUDAToolkit\n" - " host-code scout: cudaMalloc -> cudaMemcpy pattern\n" - " All three answered [OK]; no unexpected findings\"\n" - "\n" - "Resolving conflicting information:\n" - " WRONG: \"There's a conflict between what the user said and what the code\n" - " shows. The user said the data pipeline runs hourly, but the cron expression\n" - " in scheduler.py is set to daily at midnight. I need to figure out which is\n" - " correct. Since the user is describing the desired behavior and the code\n" - " shows the current behavior, this is likely a change they want to make. I\n" - " should note this as an existing gap and ask the user to confirm.\"\n" - " RIGHT: \"[!!] task description: pipeline runs hourly <-> scout: scheduler.py cron = daily@midnight\n" - " task description = desired vs code = current therefore likely a requested change -> ASK user to confirm\"\n" - "\n" - "Classifying unknowns:\n" - " WRONG: \"Looking at what I've gathered so far, I think I have a good\n" - " understanding of the database schema and the CLI argument parsing. But I\n" - " still don't know how the plugin system loads extensions at runtime -- if we\n" - " get that wrong it could affect story boundaries. The user also mentioned a\n" - " config file format I haven't found, but that's just an implementation detail.\n" - " I should dispatch a scout for the plugin system and ask the user about the\n" - " config format.\"\n" - " RIGHT: \"[OK] db schema, CLI arg parsing\n" - " [FAIL] plugin loading -- wrong assumption changes story boundaries -> SCOUT\n" - " [FAIL] cfg file format -- impl detail, no scope impact -> SAFE\"\n" - "\n" "## Workflow\n" "\n" "You work in three steps: gather context (task description + codebase + scouts)," @@ -113,18 +79,15 @@ "\n" "## Output\n" "\n" - "One file: **landscape.md** in the epic directory.\n" + "One file: **landscape.md** in the run directory.\n" "\n" "## Tools\n" "\n" "- Read tools (read, bash, grep, glob, find, ls) -- reading the codebase.\n" "- `koan_request_scouts` -- request parallel codebase exploration.\n" "- `koan_ask_question` -- ask the user clarifying questions.\n" - "- `koan_review_artifact` -- present landscape.md for user review (final step only).\n" "- `write` / `edit` -- for writing landscape.md (final step only).\n" "- `koan_complete_step` -- signal step completion.\n" - "\n" - + REVIEW_PROTOCOL ) @@ -133,12 +96,27 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: if step == 1: project_dir = ctx.project_dir or "" - lines = [ - "Read the task description, orient yourself in the codebase, and dispatch scouts.", + lines = [] + + # Workflow scope framing appears at the top if injected (D8) + if ctx.phase_instructions: + lines.extend([ + "## Workflow Context", + "", + ctx.phase_instructions, + "", + ]) + + if ctx.workflow_name: + lines.insert(0, f"Active workflow: **{ctx.workflow_name}**") + lines.insert(1, "") + + lines.extend([ + "Read the task description, orient yourself in the codebase, and plan your investigation.", "", "## 1. Task description", "", - ] + ]) if ctx.task_description: lines.append(f"<task_description>\n{ctx.task_description}\n</task_description>") else: @@ -150,7 +128,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "- **File references**: Every file, directory, or module mentioned.", "- **Decisions already made**: Only those explicitly stated and agreed upon.", "- **Constraints**: Technical, timeline, compatibility requirements.", - "- **Gaps**: Questions raised but unanswered. Things unclear or unstated that would affect story boundaries.", + "- **Gaps**: Questions raised but unanswered. Things unclear or unstated that would affect scope.", "- **Conventions mentioned**: Any references to coding standards, test approaches, doc standards, or patterns to follow.", "", "Be faithful to what was said. Do not invent context or infer unstated decisions.", @@ -175,29 +153,22 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "Just enough to write scout prompts that reference actual function names,", "actual patterns, and actual file paths instead of vague labels.", "", - "## 3. Plan and dispatch scouts", - "", - "Using the task description and what you observed in the files, identify the", - "concerns that need investigation. Consider both:", - "", - "- What the task description explicitly references (files, modules, integration", - " points, assumptions that need verification, project conventions).", - "- What the task description did NOT mention but could matter (hidden callers,", - " related subsystems, prior art, invariants, test coverage).", + "## 3. Plan your investigation", "", - "Group related concerns into **3-5 clusters**. Each cluster becomes one", - "scout. A scout is a broad investigator -- it can examine multiple files,", - "trace dependencies, and answer several related questions in a single run.", - "Merge concerns that touch the same area of the codebase or the same", - "conceptual boundary into one scout with a multi-part prompt.", + "Two investigation tools are available:", "", - "3-5 scouts is the target. Fewer than 3 means your prompts are probably", - "too broad to produce focused findings. More than 5 means you are splitting", - "related concerns that a single scout could cover together.", + "- **Direct reading**: best for focused tasks where you can reach the", + " relevant files from the orientation step. Fast and precise.", + "- **Scouts** (`koan_request_scouts`): best for unfamiliar subsystems,", + " broad dependency tracing, or when you need parallel coverage of", + " multiple unrelated areas. Each scout is a broad investigator that", + " can examine multiple files, trace dependencies, and answer several", + " related questions in a single run.", "", - "Use `koan_request_scouts` to dispatch all scouts in a single call.", + "You can use both. Read what you can reach directly; scout what you can't.", + "The workflow context above (if present) tells you which posture to default to.", "", - "Each scout needs:", + "If dispatching scouts, each needs:", "- id: short kebab-case identifier (e.g., 'auth-and-permissions', 'data-layer')", "- role: investigator focus (e.g., 'authentication auditor', 'dependency tracer')", "- prompt: a rich, multi-part investigation brief. Tell the scout what area", @@ -205,15 +176,8 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: " paths and function names from the orientation step. A good prompt is 3-8", " sentences covering the full cluster.", "", - "Example of a well-scoped scout prompt:", - " 'Investigate the authentication subsystem rooted at src/auth/. Find all", - " callers of verifyToken(), identify the middleware chain in server.ts,", - " check whether session storage uses Redis or in-memory, and note any", - " TODO or FIXME comments related to auth. Report the permission model", - " (RBAC, ACL, or ad-hoc checks) and how it integrates with the router.'", + "Use `koan_request_scouts` to dispatch all scouts in a single call.", ]) - if ctx.phase_instructions: - lines.extend(["", "## Additional Context from Workflow Orchestrator", "", ctx.phase_instructions]) return StepGuidance(title=STEP_NAMES[1], instructions=lines) if step == 2: @@ -224,12 +188,11 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "Scout results give you a starting point -- not the finish line. Your job now", "is to build genuine, verified understanding by reading code, identifying gaps,", - "and asking the user targeted questions. Then doing it again as each answer", - "reveals new dimensions you couldn't have seen before.", + "and asking the user targeted questions.", "", "This is the only phase where the user can be consulted. After intake, all", "downstream phases work from landscape.md alone. Anything you get wrong here", - "will silently propagate through decomposition, planning, and execution.", + "will silently propagate through planning and execution.", "", "## 1. Process scout results", "", @@ -238,12 +201,8 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "- Does it reveal anything unexpected about the codebase?", "- Does it conflict with what the task description stated?", "", - "For key findings that affect scope or story boundaries, open the actual files", - "and confirm what the scout reported. Scouts are good at exploration but their", - "output should be verified. This is especially important for:", - "- Integration points the scout identified", - "- Patterns or conventions the scout claims to have found", - "- Anything that conflicts with the task description", + "For key findings that affect scope, open the actual files", + "and confirm what the scout reported.", "", "## 2. Map what you know and what you don't", "", @@ -254,32 +213,21 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: " - Unknown: [what remains unclear or unverified]", " - Source: [task description / scout findings]", "", - "Cover every area relevant to the task, including project conventions (coding", - "style, testing strategy, architecture patterns, documentation standards).", + "Cover every area relevant to the task, including project conventions.", "", - "For each unknown, briefly assess its downstream impact:", - "- If you assume wrong, does it change story boundaries?", + "For each unknown, assess its downstream impact:", + "- If you assume wrong, does it change the approach or scope?", "- Would the executor hit a surprise that requires re-planning?", "", "Mark each unknown as:", - "- **ASK**: user input needed -- affects scope, boundaries, or sequencing.", + "- **ASK**: user input needed -- affects scope, approach, or sequencing.", "- **SAFE**: genuinely an implementation detail with no scope impact.", "", "## 3. The deepening loop", "", - "This is the core of this step. Understanding deepens through dialogue, and", - "for any non-trivial task, multiple rounds of questions are expected.", - "", - "### a) Ask your first round of questions", - "", - "For every unknown marked ASK, formulate a question. The user is your", - "collaborator, not an interruption. The decomposer cannot ask questions", - "later -- this is the only chance to get clarification.", + "### a) Ask questions", "", - "Default: ask. You may skip a question ONLY if ALL of these are true:", - "- It is purely an implementation detail (HOW to code something, not WHAT to build).", - "- Getting it wrong would not change any story boundary.", - "- It cannot be misinterpreted -- there is exactly one reasonable interpretation.", + "For every unknown marked ASK, formulate a question.", "", "Call `koan_ask_question` with your questions. Formatting rules:", "- Prefer multiple-choice when the answer space is bounded.", @@ -292,30 +240,16 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "### b) Deepen with each answer", "", - "When answers arrive, each one is a thread to pull. Think through:", - "", - "- **Does the answer reference files or code you haven't read?** Read them now.", - " Confirm the answer against what you find in the codebase.", - "- **Does understanding this answer change your picture of another area?**", - " An answer about the data model may reveal an assumption you were making", - " about the API layer. An answer about scope may invalidate a pattern you", - " assumed would apply.", - "- **Does it reveal an assumption you were making without realizing it?**", - " The most dangerous gaps are the ones you don't know you have.", - "- **Does it raise a new question you couldn't have anticipated before?**", - " This is the ripple effect: each answer shifts your understanding, and", - " that shift may expose new gaps in adjacent areas.", + "When answers arrive, each one is a thread to pull:", + "- Does the answer reference files or code you haven't read? Read them now.", + "- Does understanding this answer change your picture of another area?", + "- Does it reveal an assumption you were making without realizing it?", + "- Does it raise a new question you couldn't have anticipated before?", "", "### c) Ask follow-up questions", "", - "If new ambiguities surface -- and for any non-trivial task, they will --", - "call `koan_ask_question` again. There is no limit on rounds. Shallow", - "understanding compounds into wrong plans. Deep understanding prevents", - "re-work.", - "", - "Each round should build on the last. Early questions establish the shape", - "of the problem. Later questions refine boundaries, resolve edge cases,", - "and confirm the assumptions that emerged from earlier answers.", + "If new ambiguities surface, call `koan_ask_question` again.", + "The workflow context (step 1) guides how many rounds are appropriate.", "", "### d) When are you done?", "", @@ -324,17 +258,14 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "- You can explain the full context to a downstream planner without hedging.", "- No answer you received left you with a 'I think I know what they mean'", " feeling -- you either confirmed it or asked.", - "", - "When in doubt, ask. It is always better to confirm an assumption than to", - "let a wrong assumption propagate through planning and execution.", ], ) if step == 3: lines = [ - f"Write `{ctx.epic_dir}/landscape.md`." - if ctx.epic_dir - else "Write `landscape.md` to the epic directory.", + f"Write `{ctx.run_dir}/landscape.md`." + if ctx.run_dir + else "Write `landscape.md` to the run directory.", "This file is the sole input for all downstream phases. Write it carefully.", "", "## Formatting rules (apply to all sections)", @@ -355,10 +286,6 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "### Prior Art", "Previous attempts, referenced plans, related systems, or prior conversations mentioned.", - "For each reference: what it contains, what is relevant to the current task, and what to expect when reading it.", - "Example:", - " - [phases.md](plans/phases.md) -- phased implementation plan; Phase 5 defines the deliverables this epic covers", - " - Previous PR #42 attempted this but was reverted due to migration issues", "If none: (none referenced)", "", "### Codebase Findings", @@ -366,7 +293,6 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "For each area, include:", "- **Entry points**: files, functions, or modules that are the primary sites of interest.", - " Use annotated file references: `[filename](path) -- what this file does`.", "- **Current behavior**: how the relevant code works today.", "- **Patterns**: recurring patterns, conventions, or idioms observed in this area.", "- **Integration points**: how this area connects to other parts of the system.", @@ -375,27 +301,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "### Project Conventions", "Where to find coding standards and patterns for this project -- pointers to sources,", - "not the conventions themselves. Downstream agents will read the referenced sources directly.", - "", - "Cover at minimum these areas. Add any other convention categories relevant to this project:", - "", - "#### Coding Style", - "Where style is defined: linter config, formatter config, or emergent from codebase.", - 'Example: "ESLint config at [.eslintrc.json](.eslintrc.json)" or "no linter; follows Go stdlib style"', - "", - "#### Testing Strategy", - "Where testing approach is defined: doc, config, patterns.", - 'Example: "[testing-philosophy.md](doc/01-principles/testing-philosophy.md) -- integration-first with testcontainers"', - "", - "#### Architecture Patterns", - "Where architecture conventions live: docs, or emergent from code.", - 'Example: "constructor-based DI, no framework; see [BasePhase](src/planner/phases/base-phase.ts)"', - "", - "#### Documentation", - "Where documentation standards are defined.", - 'Example: "CLAUDE.md per package", "JSDoc on all exports"', - "", - "If no explicit conventions exist for an area, note whether patterns are emergent from code or absent entirely.", + "not the conventions themselves.", "", "### Decisions", "Every question asked and the user's answer.", @@ -413,24 +319,12 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "## Pre-write verification", "", "Before writing, verify landscape.md is complete -- a downstream agent must be able", - "to understand the full background from this file alone:", - "- What is being built or changed, and why?", - "- What existing code is affected and how is it structured?", - "- Where do project conventions live?", - "- What decisions have been made that constrain downstream work?", - "- Is every file reference annotated with what it contains?", - "", - "If you cannot answer any of these from what you've gathered, note it in Open Items.", + "to understand the full background from this file alone.", "", "## After writing", "", - ( - f"Call `koan_review_artifact` with the path `{ctx.epic_dir}/landscape.md`" - ' and description "Landscape document -- background information for downstream planning".' - if ctx.epic_dir - else "Call `koan_review_artifact` with the path to landscape.md" - ' and description "Landscape document -- background information for downstream planning".' - ), + "landscape.md is now available in the artifacts panel for review.", + "Call `koan_complete_step` to signal phase completion.", ] return StepGuidance(title=STEP_NAMES[3], instructions=lines) @@ -442,19 +336,11 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: def get_next_step(step: int, ctx: PhaseContext) -> int | None: if step < 3: return step + 1 - # Step 3 (Write): review-gated. - if ctx.last_review_accepted is True: - return None - return 3 + # Step 3 (Write): terminal — no review gate. + return None def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: - if step == 3: - if ctx.last_review_accepted is None: - return "You must call koan_review_artifact to present landscape.md for review before completing this step." - if ctx.last_review_accepted is False: - return "The user requested revisions. Address the feedback, then call koan_review_artifact again." - return None return None diff --git a/koan/phases/orchestrator.py b/koan/phases/orchestrator.py index 9799de7..cb1e599 100644 --- a/koan/phases/orchestrator.py +++ b/koan/phases/orchestrator.py @@ -18,6 +18,7 @@ from . import PhaseContext, StepGuidance ROLE = "orchestrator" +SCOPE = "legacy" TOTAL_STEPS = 2 # default; actual depends on step_sequence SYSTEM_PROMPT = ( @@ -113,7 +114,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: def _pre_step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: - ed = ctx.epic_dir + ed = ctx.run_dir if step == 1: return StepGuidance( @@ -179,7 +180,7 @@ def _pre_step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: def _post_step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: - ed = ctx.epic_dir + ed = ctx.run_dir sid = ctx.story_id or "<story-id>" story_ref = f"story `{sid}`" verify_path = f"{ed}/stories/{sid}/plan/verify.md" diff --git a/koan/phases/plan_review.py b/koan/phases/plan_review.py new file mode 100644 index 0000000..4c9faf5 --- /dev/null +++ b/koan/phases/plan_review.py @@ -0,0 +1,140 @@ +# Plan-review phase -- 2-step workflow. +# +# Step 1 (Read) -- read landscape.md and plan.md; no writes +# Step 2 (Evaluate) -- evaluate the plan and report findings via chat +# +# Advisory only: findings are reported in chat, not written to a file. +# Scope: "plan" -- specific to the plan workflow. + +from __future__ import annotations + +from . import PhaseContext, StepGuidance + +ROLE = "orchestrator" +SCOPE = "plan" # specific to the plan workflow +TOTAL_STEPS = 2 + +STEP_NAMES: dict[int, str] = { + 1: "Read", + 2: "Evaluate", +} + +SYSTEM_PROMPT = ( + "You are a quality reviewer pressure-testing an implementation plan.\n" + "\n" + "You verify all codebase claims against actual source files. You report findings" + " organized by severity. You are advisory -- you do NOT modify plan.md directly.\n" + "\n" + "## Your role\n" + "\n" + "Find problems in the plan before the executor runs. Focus on issues that would" + " cause the executor to fail or produce wrong results. Do NOT flag trivial issues" + " the executor can resolve independently (wrong filenames, syntax errors in" + " snippets, missing imports, minor typos -- executors handle these routinely).\n" + "\n" + "## Evaluation dimensions\n" + "\n" + "- **Completeness**: Does the plan cover every requirement from landscape.md?\n" + "- **Correctness**: Are the file paths, function names, and interfaces accurate?\n" + " Verify against the actual codebase.\n" + "- **Feasibility**: Are the implementation steps actionable as described? Would\n" + " an executor be able to follow them without ambiguity?\n" + "- **Risks**: What could go wrong during execution? Missing edge cases?\n" + "- **Gaps**: Anything not addressed that should be?\n" + "\n" + "## Strict rules\n" + "\n" + "- MUST read landscape.md and plan.md before evaluating.\n" + "- MUST read the codebase files the plan references. Verify claims.\n" + "- MUST NOT modify plan.md.\n" + "- MUST NOT flag issues the executor can trivially resolve.\n" +) + + +# -- Step guidance ------------------------------------------------------------- + +def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: + if step == 1: + lines = [ + "Read and comprehend before evaluating. Do NOT write any files in this step.", + "", + "## What to read", + "", + f"1. Read `{ctx.run_dir}/landscape.md` -- understand requirements and constraints.", + f"2. Read `{ctx.run_dir}/plan.md` -- read every section from start to finish.", + "3. Read the codebase files the plan references. For each claim the plan makes", + " (file path, function name, interface, type), verify it against the actual source.", + "", + "## Build a mental model", + "", + "After reading, you should be able to answer:", + "- What does the plan claim to change, and in which files?", + "- Are those files and functions real and accurately described?", + "- Does the plan cover all requirements from landscape.md?", + "- Are the implementation steps in the right order?", + "", + "Do NOT write an evaluation yet. Comprehend first.", + ] + if ctx.phase_instructions: + lines.extend(["", "## Additional Context from Workflow Orchestrator", "", ctx.phase_instructions]) + return StepGuidance(title=STEP_NAMES[1], instructions=lines) + + if step == 2: + return StepGuidance( + title=STEP_NAMES[2], + instructions=[ + "Evaluate the plan and report findings in your response.", + "", + "## What to evaluate", + "", + "**Completeness**: Does the plan cover every requirement from landscape.md?", + "List any requirements not addressed.", + "", + "**Correctness**: Are file paths, function names, and interfaces accurate?", + "Note any incorrect references you verified against the codebase.", + "", + "**Feasibility**: Can an executor follow each step without ambiguity?", + "Note any steps that are vague, contradictory, or would require judgment calls.", + "", + "**Risks**: What could go wrong? Missing edge cases, ordering issues, dependencies?", + "", + "**Gaps**: Anything the plan should address but doesn't?", + "", + "## Severity classification", + "", + "Report findings organized by severity:", + "- **Critical**: would cause the executor to fail or produce wrong results", + "- **Major**: significant gap or incorrectness requiring plan revision", + "- **Minor**: small issue the executor can likely resolve independently", + "", + "Do NOT flag trivial executor-resolvable issues as major findings.", + "", + "## Using koan_ask_question", + "", + "If the review surfaces ambiguities requiring user input (requirements unclear," + " conflicting constraints, genuine design questions), call `koan_ask_question`.", + "Only ask questions that affect the evaluation outcome.", + "", + "## After reporting", + "", + "Call `koan_complete_step` when your evaluation report is delivered in chat.", + ], + ) + + return StepGuidance(title=f"Step {step}", instructions=[f"Execute step {step}."]) + + +# -- Lifecycle ----------------------------------------------------------------- + +def get_next_step(step: int, ctx: PhaseContext) -> int | None: + if step < TOTAL_STEPS: + return step + 1 + return None # linear, no review gate + + +def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: + return None + + +async def on_loop_back(from_step: int, to_step: int, ctx: PhaseContext) -> None: + pass diff --git a/koan/phases/plan_spec.py b/koan/phases/plan_spec.py new file mode 100644 index 0000000..24838c7 --- /dev/null +++ b/koan/phases/plan_spec.py @@ -0,0 +1,144 @@ +# Plan-spec phase -- 2-step workflow. +# +# Step 1 (Analyze) -- read landscape.md and codebase; no writes +# Step 2 (Write) -- write plan.md to the run directory +# +# Scope: "plan" -- specific to the plan workflow. + +from __future__ import annotations + +from . import PhaseContext, StepGuidance + +ROLE = "orchestrator" +SCOPE = "plan" # specific to the plan workflow +TOTAL_STEPS = 2 + +STEP_NAMES: dict[int, str] = { + 1: "Analyze", + 2: "Write", +} + +SYSTEM_PROMPT = ( + "You are a technical architect writing an implementation plan for a coding task.\n" + "\n" + "You read the codebase thoroughly before planning. Your plans reference actual" + " file paths and function names, not abstract descriptions. You write instructions" + " specific enough that a coding agent can execute them without making judgment" + " calls about what to do.\n" + "\n" + "## Your role\n" + "\n" + "You plan implementation. You do NOT write code. You produce a plan.md that an" + " executor agent will follow to implement the changes.\n" + "\n" + "## Output\n" + "\n" + "One file: **plan.md** in the run directory.\n" + "\n" + "## plan.md structure\n" + "\n" + "- **Approach summary**: 2-4 sentences on the overall strategy.\n" + "- **Key decisions**: Numbered list of architectural/design decisions made.\n" + "- **Implementation steps**: Numbered list, each specifying file path,\n" + " function/location, and the exact change. Be specific -- include function\n" + " signatures and type names where relevant.\n" + "- **Constraints**: Hard boundaries the executor must respect.\n" + "- **Verification**: How to verify the implementation is correct.\n" + "\n" + "## Strict rules\n" + "\n" + "- MUST read landscape.md before writing the plan.\n" + "- MUST read the codebase files the plan references. Verify paths, signatures,\n" + " and types before including them in the plan.\n" + "- MUST NOT write code -- write instructions for an executor that will write code.\n" + "- MUST NOT invent file paths or function names without verifying them in the codebase.\n" +) + + +# -- Step guidance ------------------------------------------------------------- + +def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: + if step == 1: + lines = [ + "Read and analyze before writing the plan. Do NOT write any files in this step.", + "", + "## What to read", + "", + f"1. Read `{ctx.run_dir}/landscape.md` -- understand the task, codebase" + " context, decisions, and constraints.", + "2. Read every file the plan will reference. Open the actual source files", + " to verify function signatures, type names, and integration points.", + " Do not rely on landscape.md's descriptions alone.", + "", + "## What to analyze", + "", + "After reading, identify:", + "- **Key architectural decisions**: What approach will you take and why?", + "- **Integration points**: Which existing code will the changes touch?", + "- **Risks**: Where could things go wrong during execution?", + "- **Order**: What is the safest sequence of implementation steps?", + "", + "Call `koan_complete_step` with an analysis summary:", + "- Overall approach (2-3 sentences)", + "- Files that will be modified", + "- Key decisions and rationale", + "- Any ambiguities or risks spotted", + ] + if ctx.phase_instructions: + lines.extend(["", "## Additional Context from Workflow Orchestrator", "", ctx.phase_instructions]) + return StepGuidance(title=STEP_NAMES[1], instructions=lines) + + if step == 2: + return StepGuidance( + title=STEP_NAMES[2], + instructions=[ + f"Write `{ctx.run_dir}/plan.md` with a complete implementation plan.", + "", + "## Required sections", + "", + "### Approach summary", + "2-4 sentences on the overall strategy.", + "", + "### Key decisions", + "Numbered list of architectural/design decisions. For each decision, state", + "the choice made and why (alternative considered + reason rejected if applicable).", + "", + "### Implementation steps", + "Numbered list. Each step must specify:", + "- **File**: exact path relative to project root", + "- **Location**: function name, class, or section", + "- **Change**: what to add, modify, or remove -- be specific", + " Include function signatures, type names, and interface names where relevant.", + "", + "Order steps so that each step's dependencies are satisfied by prior steps.", + "", + "### Constraints", + "Hard boundaries the executor must respect (from landscape.md Constraints section).", + "", + "### Verification", + "How to verify the implementation is correct (tests to run, behaviors to check).", + "", + "## After writing", + "", + "plan.md is now available in the artifacts panel for review.", + "Call `koan_complete_step` when done.", + ], + ) + + return StepGuidance(title=f"Step {step}", instructions=[f"Execute step {step}."]) + + +# -- Lifecycle ----------------------------------------------------------------- + +def get_next_step(step: int, ctx: PhaseContext) -> int | None: + if step < TOTAL_STEPS: + return step + 1 + return None # linear, no review gate + + +def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: + return None + + +async def on_loop_back(from_step: int, to_step: int, ctx: PhaseContext) -> None: + pass diff --git a/koan/phases/review_protocol.py b/koan/phases/review_protocol.py deleted file mode 100644 index 51db814..0000000 --- a/koan/phases/review_protocol.py +++ /dev/null @@ -1,30 +0,0 @@ -# Shared review protocol prompt fragment. -# -# Included in the system prompt of every role that has koan_review_artifact -# permission (currently: intake, brief-writer). Establishes the review loop -# contract, ripple-effect awareness, and mechanical enforcement -- once, in -# one place. - -REVIEW_PROTOCOL = """## Review protocol - -When you present an artifact for review via `koan_review_artifact`, the user -can either accept it or provide feedback. - -**On acceptance**: the tool response will say ACCEPTED. You may then call -`koan_complete_step` to advance. - -**On feedback**: the tool response will say REVISION REQUESTED and include the -user's feedback. You MUST: - -1. Treat the feedback as authoritative. It may introduce new decisions, - constraints, or context that were not available during earlier phases. -2. Consider the ripple effect. If the feedback changes your understanding of - the task, other artifacts in the epic directory may need updating too -- you - have write access and should fix any factual inconsistency the feedback - creates. For example, feedback on brief.md that introduces a new constraint - should also appear in landscape.md's Constraints or Decisions section. -3. Revise the artifact to fully address every point in the feedback. -4. Call `koan_review_artifact` again to present the revision. - -This loop continues until the user accepts. You cannot complete the current -step without acceptance -- the system enforces this mechanically.""" diff --git a/koan/phases/tech_plan.py b/koan/phases/tech_plan.py index a03eee9..a8c1dd8 100644 --- a/koan/phases/tech_plan.py +++ b/koan/phases/tech_plan.py @@ -11,6 +11,7 @@ from . import PhaseContext, StepGuidance ROLE = "planner" +SCOPE = "legacy" TOTAL_STEPS = 3 STEP_NAMES: dict[int, str] = { @@ -88,7 +89,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: sid = ctx.story_id or "<story-id>" - ed = ctx.epic_dir + ed = ctx.run_dir if step == 1: return StepGuidance( diff --git a/koan/phases/ticket_breakdown.py b/koan/phases/ticket_breakdown.py index 71c9ecd..fe72357 100644 --- a/koan/phases/ticket_breakdown.py +++ b/koan/phases/ticket_breakdown.py @@ -10,6 +10,7 @@ from . import PhaseContext, StepGuidance ROLE = "ticket-breakdown" +SCOPE = "legacy" TOTAL_STEPS = 2 STEP_NAMES: dict[int, str] = { @@ -71,7 +72,7 @@ # -- Step guidance ------------------------------------------------------------- def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: - ed = ctx.epic_dir + ed = ctx.run_dir if step == 1: return StepGuidance( diff --git a/koan/projections.py b/koan/projections.py index 6196766..2de9656 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -37,6 +37,7 @@ "agent_step_advanced", "agent_exited", "workflow_completed", + "workflow_selected", "scout_queued", # Activity "tool_called", @@ -59,8 +60,6 @@ # Focus (interactions) "questions_asked", "questions_answered", - "artifact_review_requested", - "artifact_reviewed", # Resources "artifact_created", "artifact_modified", @@ -218,17 +217,8 @@ class QuestionFocus(KoanBaseModel): token: str questions: list[dict] = [] -class ReviewFocus(KoanBaseModel): - """Agent is blocked, artifact needs review.""" - type: Literal["review"] = "review" - agent_id: str - token: str - path: str = "" - description: str = "" - content: str = "" - Focus = Annotated[ - ConversationFocus | QuestionFocus | ReviewFocus, + ConversationFocus | QuestionFocus, Field(discriminator="type"), ] @@ -321,6 +311,7 @@ class SteeringMessage(KoanBaseModel): class Run(KoanBaseModel): config: RunConfig phase: str = "" + workflow: str = "" # active workflow name agents: dict[str, Agent] = {} # all agents by ID — queued, running, done, failed focus: Focus | None = None # None before first agent spawns artifacts: dict[str, ArtifactInfo] = {} @@ -442,6 +433,14 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: ) return projection.model_copy(update={"run": Run(config=config)}) + + case "workflow_selected": + if projection.run is None: + log.warning("fold workflow_selected: run is None, skipping") + return projection + new_run = projection.run.model_copy(update={"workflow": payload.get("workflow", "")}) + return projection.model_copy(update={"run": new_run}) + case "phase_started": if projection.run is None: log.warning("fold phase_started: run is None, skipping") @@ -940,29 +939,7 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: }) return projection.model_copy(update={"run": new_run}) - case "artifact_review_requested": - if projection.run is None or not agent_id: - return projection - new_focus = ReviewFocus( - agent_id=agent_id, - token=payload.get("token", ""), - path=payload.get("path", ""), - description=payload.get("description", ""), - content=payload.get("content", ""), - ) - new_run = projection.run.model_copy(update={"focus": new_focus}) - return projection.model_copy(update={"run": new_run}) - case "artifact_reviewed": - if projection.run is None: - return projection - pid = _primary_agent_id(projection.run) - if pid is None: - return projection - new_run = projection.run.model_copy(update={ - "focus": ConversationFocus(agent_id=pid), - }) - return projection.model_copy(update={"run": new_run}) # ── Resources ───────────────────────────────────────────────── diff --git a/koan/epic_state.py b/koan/run_state.py similarity index 56% rename from koan/epic_state.py rename to koan/run_state.py index 314ef00..abcac81 100644 --- a/koan/epic_state.py +++ b/koan/run_state.py @@ -1,6 +1,6 @@ -# On-disk state I/O for epic and story state files. +# On-disk state I/O for run and story state files. # All JSON writes use atomic tmp+rename to prevent partial reads. -# Python port of src/planner/epic/state.ts. +# Renamed from koan/epic_state.py: all "epic" terminology replaced with "run". from __future__ import annotations @@ -12,7 +12,7 @@ from .logger import get_logger -log = get_logger("epic_state") +log = get_logger("run_state") async def atomic_write_json(path: str | Path, value: object) -> None: @@ -24,22 +24,22 @@ async def atomic_write_json(path: str | Path, value: object) -> None: os.rename(tmp, p) -async def load_epic_state(epic_dir: str | Path) -> dict: - p = Path(epic_dir) / "epic-state.json" +async def load_run_state(run_dir: str | Path) -> dict: + p = Path(run_dir) / "run-state.json" try: async with aiofiles.open(p, "r") as f: return json.loads(await f.read()) except (FileNotFoundError, json.JSONDecodeError) as exc: - log.warning("load_epic_state failed for %s: %s", p, exc) + log.warning("load_run_state failed for %s: %s", p, exc) return {} -async def save_epic_state(epic_dir: str | Path, state: dict) -> None: - await atomic_write_json(Path(epic_dir) / "epic-state.json", state) +async def save_run_state(run_dir: str | Path, state: dict) -> None: + await atomic_write_json(Path(run_dir) / "run-state.json", state) -async def load_story_state(epic_dir: str | Path, story_id: str) -> dict: - p = Path(epic_dir) / "stories" / story_id / "state.json" +async def load_story_state(run_dir: str | Path, story_id: str) -> dict: + p = Path(run_dir) / "stories" / story_id / "state.json" try: async with aiofiles.open(p, "r") as f: return json.loads(await f.read()) @@ -49,22 +49,22 @@ async def load_story_state(epic_dir: str | Path, story_id: str) -> dict: async def save_story_state( - epic_dir: str | Path, story_id: str, updates: dict + run_dir: str | Path, story_id: str, updates: dict ) -> None: - existing = await load_story_state(epic_dir, story_id) + existing = await load_story_state(run_dir, story_id) merged = {**existing, **updates} await atomic_write_json( - Path(epic_dir) / "stories" / story_id / "state.json", merged + Path(run_dir) / "stories" / story_id / "state.json", merged ) -async def load_all_story_states(epic_dir: str | Path) -> list[dict]: - epic = await load_epic_state(epic_dir) +async def load_all_story_states(run_dir: str | Path) -> list[dict]: + run = await load_run_state(run_dir) story_ids = [s.get("id", s) if isinstance(s, dict) else s - for s in epic.get("stories", [])] + for s in run.get("stories", [])] results = [] for sid in story_ids: - st = await load_story_state(epic_dir, sid) + st = await load_story_state(run_dir, sid) if st: st.setdefault("storyId", sid) results.append(st) @@ -72,15 +72,15 @@ async def load_all_story_states(epic_dir: str | Path) -> list[dict]: async def ensure_subagent_directory( - epic_dir: str | Path, label: str + run_dir: str | Path, label: str ) -> str: - d = Path(epic_dir) / "subagents" / label + d = Path(run_dir) / "subagents" / label d.mkdir(parents=True, exist_ok=True) return str(d) -async def discover_story_ids(epic_dir: str | Path) -> list[str]: - stories_dir = Path(epic_dir) / "stories" +async def discover_story_ids(run_dir: str | Path) -> list[str]: + stories_dir = Path(run_dir) / "stories" if not stories_dir.is_dir(): return [] return sorted( diff --git a/koan/runners/base.py b/koan/runners/base.py index 46f1671..db58b5e 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -66,8 +66,7 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: ... "koan_set_phase", "koan_request_scouts", "koan_ask_question", - "koan_review_artifact", - "koan_spawn_executor", + "koan_request_executor", "koan_select_story", "koan_complete_story", "koan_retry_story", diff --git a/koan/state.py b/koan/state.py index ed8b80d..47a56e6 100644 --- a/koan/state.py +++ b/koan/state.py @@ -17,7 +17,7 @@ def _utcnow() -> datetime: from .config import KoanConfig from .probe import ProbeResult from .projections import ProjectionStore -from .types import EpicPhase, Profile, SubagentRole +from .types import WorkflowPhase, Profile, SubagentRole @dataclass @@ -28,7 +28,7 @@ class ChatMessage: @dataclass class PendingInteraction: - type: Literal["ask", "artifact-review"] + type: Literal["ask"] agent_id: str future: asyncio.Future payload: dict @@ -40,7 +40,7 @@ class AgentState: agent_id: str role: SubagentRole subagent_dir: str - epic_dir: str = "" + run_dir: str = "" label: str = "" step: int = 0 phase_module: Any = None @@ -57,10 +57,11 @@ class AgentState: @dataclass class AppState: - phase: EpicPhase = "intake" - epic_dir: str | None = None + phase: WorkflowPhase = "intake" + run_dir: str | None = None project_dir: str = "" task_description: str = "" + workflow: Any = None # Workflow | None — imported lazily to avoid circular deps start_event: asyncio.Event = field(default_factory=asyncio.Event) agents: dict[str, AgentState] = field(default_factory=dict) projection_store: ProjectionStore = field(default_factory=ProjectionStore) diff --git a/koan/subagent.py b/koan/subagent.py index 5d8f4f9..7ddf6fb 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -14,12 +14,11 @@ import aiofiles from .audit import EventLog -from .epic_state import ensure_subagent_directory +from .run_state import ensure_subagent_directory from .events import ( build_agent_exited, build_agent_spawn_failed, build_agent_spawned, - build_artifact_reviewed, build_questions_answered, build_tool_bash, build_tool_called, @@ -73,11 +72,13 @@ async def write_task_json(subagent_dir: str, task_dict: dict) -> None: def _build_phase_ctx(task: dict, subagent_dir: str) -> PhaseContext: return PhaseContext( - epic_dir=task.get("epic_dir", ""), + run_dir=task.get("run_dir", ""), subagent_dir=subagent_dir, project_dir=task.get("project_dir", ""), task_description=task.get("task_description", ""), + workflow_name=task.get("workflow", ""), phase_instructions=task.get("instructions") or task.get("phase_instructions") or task.get("task"), + executor_artifacts=task.get("artifacts", []), story_id=task.get("story_id"), step_sequence=task.get("step_sequence"), completed_phase=task.get("completed_phase"), @@ -98,9 +99,9 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None # Own directory creation -- derive if not provided, ensure it exists subagent_dir = task.get("subagent_dir", "") if not subagent_dir: - epic_dir = task.get("epic_dir", "") + run_dir = task.get("run_dir", "") label = f"{role}-{agent_id[:8]}" - subagent_dir = await ensure_subagent_directory(epic_dir, label) + subagent_dir = await ensure_subagent_directory(run_dir, label) task["subagent_dir"] = subagent_dir else: Path(subagent_dir).mkdir(parents=True, exist_ok=True) @@ -170,7 +171,7 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None agent_id=agent_id, role=role, subagent_dir=subagent_dir, - epic_dir=task.get("epic_dir", ""), + run_dir=task.get("run_dir", ""), label=task.get("label", ""), step=0, phase_module=phase_module, @@ -405,12 +406,6 @@ def _cancel_pending_interactions(agent_id: str, app_state: AppState) -> None: build_questions_answered(token, answers=None, cancelled=True), agent_id=agent_id, ) - elif active.type == "artifact-review": - store.push_event( - "artifact_reviewed", - build_artifact_reviewed(token, accepted=None, response=None, cancelled=True), - agent_id=agent_id, - ) if not active.future.done(): active.future.set_result(error_result) diff --git a/koan/types.py b/koan/types.py index af4981c..6707285 100644 --- a/koan/types.py +++ b/koan/types.py @@ -4,7 +4,8 @@ from dataclasses import dataclass, field from typing import Literal -EpicPhase = Literal[ +WorkflowPhase = Literal[ + # Legacy workflow phases (kept as dead code; no active workflow uses these) "intake", "brief-generation", "core-flows", @@ -14,6 +15,10 @@ "execution", "implementation-validation", "completed", + # Plan workflow phases + "plan-spec", + "plan-review", + "execute", ] SubagentRole = Literal[ diff --git a/koan/web/app.py b/koan/web/app.py index 4ea0afe..8fb9614 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -24,14 +24,13 @@ from starlette.responses import StreamingResponse from ..artifacts import list_artifacts -from ..epic_state import atomic_write_json +from ..run_state import atomic_write_json from ..probe import ProbeResult from ..projections import _primary_agent_id from ..state import ChatMessage from ..types import AgentInstallation, Profile, ProfileTier from .interactions import activate_next_interaction from ..events import ( - build_artifact_reviewed, build_questions_answered, build_probe_completed, build_run_started, @@ -324,20 +323,32 @@ async def api_start_run(r: Request) -> Response: st.phase_complete_future = None # Create epic directory - epic_id = f"{int(time.time())}-{uuid.uuid4().hex[:8]}" - epic_dir = Path.home() / ".koan" / "epics" / epic_id - epic_dir.mkdir(parents=True, exist_ok=True) + run_id = f"{int(time.time())}-{uuid.uuid4().hex[:8]}" + run_dir = Path.home() / ".koan" / "runs" / run_id + run_dir.mkdir(parents=True, exist_ok=True) + + workflow_name = body.get("workflow", "plan") # default to "plan" + try: + from ..lib.workflows import get_workflow + workflow_obj = get_workflow(workflow_name) + except ValueError as e: + return JSONResponse( + {"error": "validation_error", "message": str(e)}, + status_code=422, + ) await atomic_write_json( - epic_dir / "task.json", - {"task": task, "created_at": time.time()}, + run_dir / "task.json", + {"task": task, "workflow": workflow_name, "created_at": time.time()}, ) st.task_description = task - st.epic_dir = str(epic_dir) + st.run_dir = str(run_dir) + st.workflow = workflow_obj + st.projection_store.push_event("workflow_selected", {"workflow": workflow_name}) st.start_event.set() - return JSONResponse({"ok": True, "epic_dir": str(epic_dir)}) + return JSONResponse({"ok": True, "run_dir": str(run_dir)}) async def api_chat(r: Request) -> Response: @@ -348,7 +359,7 @@ async def api_chat(r: Request) -> Response: return JSONResponse({"error": "empty_message"}, status_code=422) st = _app_state(r) - if st.epic_dir is None: + if st.run_dir is None: return JSONResponse({"error": "no_run"}, status_code=409) ts = int(time.time() * 1000) @@ -399,34 +410,12 @@ async def api_answer(r: Request) -> Response: return JSONResponse({"ok": True}) -async def api_artifact_review(r: Request) -> Response: - body = await r.json() - response = body.get("response", "") - accepted = body.get("accepted", False) - token = body.get("token", "") - - st = _app_state(r) - active = st.active_interaction - if active is None or active.type != "artifact-review" or active.token != token: - return _stale_response() - - interaction = active - st.projection_store.push_event( - "artifact_reviewed", - build_artifact_reviewed(interaction.token, accepted=accepted, response=response, cancelled=False), - agent_id=interaction.agent_id, - ) - activate_next_interaction(st) - interaction.future.set_result({"response": response, "accepted": accepted}) - return JSONResponse({"ok": True}) - - async def api_artifacts_list(r: Request) -> Response: st = _app_state(r) - if not st.epic_dir: + if not st.run_dir: return JSONResponse({"error": "no_run", "message": "No run started"}, status_code=404) - artifacts = list_artifacts(st.epic_dir) + artifacts = list_artifacts(st.run_dir) files = [] for a in artifacts: files.append({ @@ -442,15 +431,15 @@ async def api_artifacts_list(r: Request) -> Response: async def api_artifact_content(r: Request) -> Response: st = _app_state(r) - if not st.epic_dir: + if not st.run_dir: return JSONResponse({"error": "no_run"}, status_code=404) req_path = r.path_params.get("path", "") # Path traversal guard - epic = Path(st.epic_dir).resolve() - target = (epic / req_path).resolve() - if not str(target).startswith(str(epic)): + run = Path(st.run_dir).resolve() + target = (run / req_path).resolve() + if not str(target).startswith(str(run)): return JSONResponse( {"error": "invalid_path", "message": "Path traversal not allowed"}, status_code=400, @@ -460,13 +449,13 @@ async def api_artifact_content(r: Request) -> Response: return JSONResponse({"error": "not_found"}, status_code=404) try: - content = target.read_text("utf-8") + run_content = target.read_text("utf-8") except Exception: - content = "(binary or unreadable file)" + run_content = "(binary or unreadable file)" return JSONResponse({ - "content": content, - "displayPath": str(target.relative_to(epic)), + "content": run_content, + "displayPath": str(target.relative_to(run)), }) @@ -1064,7 +1053,6 @@ async def _wait_proc(aid: str, proc: asyncio.subprocess.Process) -> None: Route("/api/start-run", api_start_run, methods=["POST"]), Route("/api/start-run/preflight", api_start_run_preflight, methods=["GET"]), Route("/api/answer", api_answer, methods=["POST"]), - Route("/api/artifact-review", api_artifact_review, methods=["POST"]), Route("/api/chat", api_chat, methods=["POST"]), Route("/api/artifacts", api_artifacts_list), Route("/api/artifacts/{path:path}", api_artifact_content), diff --git a/koan/web/interactions.py b/koan/web/interactions.py index 35de46d..98ed8a7 100644 --- a/koan/web/interactions.py +++ b/koan/web/interactions.py @@ -21,10 +21,7 @@ def _emit_interaction_request(app_state: AppState, interaction: PendingInteraction) -> None: """Emit the typed request event for an interaction becoming active.""" - from ..events import ( - build_artifact_review_requested, - build_questions_asked, - ) + from ..events import build_questions_asked store = app_state.projection_store token = interaction.token @@ -37,17 +34,6 @@ def _emit_interaction_request(app_state: AppState, interaction: PendingInteracti build_questions_asked(token, payload.get("questions", [])), agent_id=agent_id, ) - elif interaction.type == "artifact-review": - store.push_event( - "artifact_review_requested", - build_artifact_review_requested( - token, - payload.get("path", ""), - payload.get("description", ""), - payload.get("content", ""), - ), - agent_id=agent_id, - ) # -- Queue helpers ------------------------------------------------------------ @@ -55,7 +41,7 @@ def _emit_interaction_request(app_state: AppState, interaction: PendingInteracti async def enqueue_interaction( agent: AgentState, app_state: AppState, - interaction_type: Literal["ask", "artifact-review"], + interaction_type: Literal["ask"], payload: dict, ) -> asyncio.Future: total = len(app_state.interaction_queue) + (1 if app_state.active_interaction else 0) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 48f5ed3..d0b4bf6 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -4,8 +4,8 @@ # 1. Validates agent_id from query params before reaching fastmcp. # 2. Runs check_permission() on every tool call. # 3. Implements koan_complete_step, koan_request_scouts, -# koan_ask_question, koan_review_artifact, koan_set_phase, -# koan_spawn_executor, and story management tools. +# koan_ask_question, koan_set_phase, koan_request_executor, +# and story management tools. from __future__ import annotations @@ -19,20 +19,19 @@ from typing import TYPE_CHECKING, Literal from urllib.parse import parse_qs -import aiofiles from fastmcp import FastMCP from fastmcp.exceptions import ToolError -from ..epic_state import ( +from ..run_state import ( atomic_write_json, ensure_subagent_directory, load_story_state, - save_epic_state, + save_run_state, save_story_state, - load_epic_state, + load_run_state, ) from ..lib.permissions import check_permission -from ..lib.phase_dag import get_successor_phases, is_valid_transition +from ..lib.workflows import get_suggested_phases, is_valid_transition as wf_is_valid from ..logger import get_logger from ..phases import PHASE_GUIDANCE_MAP, PhaseContext, StepGuidance from ..phases.format_step import format_phase_boundary, format_steering_messages, format_step @@ -56,15 +55,15 @@ def _check_or_raise(agent: AgentState, tool_name: str, tool_args: dict | None = None) -> None: phase_ctx = agent.phase_ctx - resolved_epic_dir = ( - phase_ctx.epic_dir if phase_ctx is not None and phase_ctx.epic_dir - else agent.epic_dir or None + resolved_run_dir = ( + phase_ctx.run_dir if phase_ctx is not None and phase_ctx.run_dir + else agent.run_dir or None ) current_phase = _app_state.phase if _app_state is not None else None result = check_permission( role=agent.role, tool_name=tool_name, - epic_dir=resolved_epic_dir, + run_dir=resolved_run_dir, tool_args=tool_args, current_step=agent.step, current_phase=current_phase, @@ -134,14 +133,14 @@ def _now_iso() -> str: return datetime.now(timezone.utc).isoformat() -def _resolve_epic_dir(agent: AgentState) -> str | None: +def _resolve_run_dir(agent: AgentState) -> str | None: phase_ctx = agent.phase_ctx - if phase_ctx is not None and phase_ctx.epic_dir: - return phase_ctx.epic_dir - if agent.epic_dir: - return agent.epic_dir - if _app_state is not None and _app_state.epic_dir: - return _app_state.epic_dir + if phase_ctx is not None and phase_ctx.run_dir: + return phase_ctx.run_dir + if agent.run_dir: + return agent.run_dir + if _app_state is not None and _app_state.run_dir: + return _app_state.run_dir return None @@ -227,11 +226,7 @@ async def _step_within_phase( ctx: PhaseContext, next_step: int, ) -> str: - """Handle normal within-phase step advancement. - - User messages are not drained here -- they are delivered via the steering - queue which is drained by _drain_and_append_steering after every tool call. - """ + """Handle normal within-phase step advancement.""" assert _app_state is not None current_step = agent.step @@ -279,10 +274,7 @@ async def _step_phase_boundary( assert _app_state is not None from ..state import drain_steering_messages, drain_user_messages - # Flush pending text/thinking in the projection without adding a duplicate - # step header (the step-N header was already emitted when we advanced TO - # this step in _step_within_phase). Emitting with an empty step_name - # causes the fold to flush pending content without creating a new StepEntry. + # Flush pending text/thinking in the projection from ..events import build_step_advanced _app_state.projection_store.push_event( "agent_step_advanced", @@ -290,8 +282,7 @@ async def _step_phase_boundary( agent_id=agent.agent_id, ) - # Check for already-buffered messages. Messages that arrived before the - # boundary was set up go to the steering queue; drain both to catch them. + # Check for already-buffered messages messages = drain_user_messages(_app_state) + drain_steering_messages(_app_state) if not messages: @@ -305,8 +296,11 @@ async def _step_phase_boundary( _app_state.phase_complete_future = None messages = drain_user_messages(_app_state) - successors = get_successor_phases(_app_state.phase) - return format_phase_boundary(_app_state.phase, messages, list(successors)) + # Use workflow's suggested transitions and phase descriptions + workflow = _app_state.workflow + suggested = get_suggested_phases(workflow, _app_state.phase) if workflow else [] + descs = workflow.phase_descriptions if workflow else {} + return format_phase_boundary(_app_state.phase, messages, suggested, descs) # -- koan_complete_step ------------------------------------------------------- @@ -367,14 +361,18 @@ async def koan_complete_step(thoughts: str = "") -> str: async def koan_set_phase(phase: str) -> str: """Commit transition to the next workflow phase. - Call this after the user has indicated what to do next. - The next koan_complete_step call will return step 1 guidance - for the new phase, including the role context for that phase. + Call this after the user has confirmed what to do next. The next + koan_complete_step call will return step 1 guidance for the new + phase, including the role context for that phase. + + The available phases and their descriptions are listed in the + koan_complete_step response when a phase completes. Any phase in + the current workflow is a valid target (not just the suggested ones). Args: - phase: Target phase name. Must be a valid successor of the current phase. - Valid successors are listed in the koan_complete_step response - when a phase completes. + phase: Target phase name from the current workflow's available + phases. The phase boundary response from koan_complete_step + lists suggested phases with descriptions. """ agent = _get_agent() _check_or_raise(agent, "koan_set_phase", {"phase": phase}) @@ -385,13 +383,16 @@ async def koan_set_phase(phase: str) -> str: assert _app_state is not None current = _app_state.phase - if not is_valid_transition(current, phase): - successors = get_successor_phases(current) + workflow = _app_state.workflow + + # Validate transition using workflow membership check + if workflow is None or not wf_is_valid(workflow, current, phase): + phases = list(workflow.available_phases) if workflow else [] raise ToolError(json.dumps({ "error": "invalid_transition", "message": ( - f"'{phase}' is not a valid successor of '{current}'. " - f"Valid successors: {list(successors)}" + f"'{phase}' is not available from '{current}' in the current workflow. " + f"Available phases: {phases}" ), })) @@ -405,10 +406,10 @@ async def koan_set_phase(phase: str) -> str: # Update driver state _app_state.phase = phase - epic_dir = _resolve_epic_dir(agent) - if epic_dir: - epic_state = await load_epic_state(epic_dir) - await save_epic_state(epic_dir, {**epic_state, "phase": phase}) + run_dir = _resolve_run_dir(agent) + if run_dir: + run_state = await load_run_state(run_dir) + await save_run_state(run_dir, {**run_state, "phase": phase}) # Push artifact diff and phase_started event from ..driver import _push_artifact_diff @@ -428,14 +429,19 @@ async def koan_set_phase(phase: str) -> str: agent_id=agent.agent_id, ) + # Inject per-workflow phase guidance for the new phase + phase_guidance = workflow.phase_guidance.get(phase, "") if workflow else "" + # Switch phase module and reset step counter agent.phase_module = new_module agent.step = 0 agent.phase_ctx = PhaseContext( - epic_dir=epic_dir or "", + run_dir=run_dir or "", subagent_dir=agent.subagent_dir, project_dir=_app_state.project_dir, task_description=_app_state.task_description, + workflow_name=workflow.name if workflow else "", + phase_instructions=phase_guidance, # scope framing from workflow completed_phase=current, ) @@ -467,18 +473,18 @@ async def koan_request_scouts(questions: list[dict] | None = None) -> str: assert _app_state is not None semaphore = asyncio.Semaphore(_app_state.config.scout_concurrency) - epic_dir = agent.phase_ctx.epic_dir + run_dir = agent.phase_ctx.run_dir scout_tasks = [] for q in questions: scout_id = q.get("id", str(uuid.uuid4())[:8]) subagent_dir = await ensure_subagent_directory( - epic_dir, f"scout-{scout_id}-{uuid.uuid4().hex[:8]}" + run_dir, f"scout-{scout_id}-{uuid.uuid4().hex[:8]}" ) scout_tasks.append({ "role": "scout", "label": scout_id, - "epic_dir": epic_dir, + "run_dir": run_dir, "subagent_dir": subagent_dir, "project_dir": _app_state.project_dir, "question": q.get("prompt", ""), @@ -580,125 +586,69 @@ async def koan_ask_question(questions: list[dict] | None = None) -> str: end_tool_call(agent, call_id, "koan_ask_question", result_str) -# -- koan_review_artifact ------------------------------------------------------ - -@mcp.tool(name="koan_review_artifact") -async def koan_review_artifact(path: str = "", description: str = "") -> str: - agent = _get_agent() - _check_or_raise(agent, "koan_review_artifact", {"path": path, "description": description}) - - call_id = begin_tool_call( - agent, "koan_review_artifact", {"path": path, "description": description}, - description or path, - ) - result_str: str | None = None - try: - assert _app_state is not None - - try: - async with aiofiles.open(path, "r") as f: - content = await f.read() - except FileNotFoundError: - raise ToolError( - json.dumps({"error": "file_not_found", "message": f"Artifact not found: {path}"}) - ) +# -- koan_request_executor ----------------------------------------------------- - future = await enqueue_interaction( - agent, _app_state, "artifact-review", - {"path": path, "description": description, "content": content}, - ) - result = await future - - if isinstance(result, dict) and "error" in result: - raise ToolError(json.dumps(result)) - - response = result.get("response", "") - accepted = result.get("accepted", response == "" or response.strip().lower() in ("", "ok", "approved", "lgtm", "accept")) - agent.phase_ctx.last_review_accepted = accepted - - result_str = "ACCEPTED" if accepted else f"REVISION REQUESTED: {response}" - result_str = _drain_and_append_steering(result_str, agent) - return result_str - finally: - end_tool_call(agent, call_id, "koan_review_artifact", result_str) - - -# -- koan_spawn_executor ------------------------------------------------------- - -@mcp.tool(name="koan_spawn_executor") -async def koan_spawn_executor( - story_id: str, - role: str, - retry_context: str | None = None, +@mcp.tool(name="koan_request_executor") +async def koan_request_executor( + artifacts: list[str] | None = None, + instructions: str = "", ) -> str: - """Spawn a planner or executor subagent for a story. + """Spawn a coding agent to implement changes. - Blocks until the spawned subagent exits. Returns a result summary. - The subagent's output artifacts (plan.md, verification output) will - be available in the story directory after this call returns. + The executor reads the listed artifacts from the run directory, + plans its approach internally, then implements. Blocks until + the executor exits and returns a result summary. Args: - story_id: Story identifier (directory name in stories/) - role: "planner" generates plan.md; "executor" implements the plan - retry_context: Optional failure context from a prior executor attempt + artifacts: File paths relative to run directory that the + executor must read before coding. + Example: ["plan.md", "landscape.md"] + instructions: Free-form context for the executor — key + decisions, constraints, or user direction + not captured in the artifact files. """ agent = _get_agent() - _check_or_raise(agent, "koan_spawn_executor", {"story_id": story_id, "role": role}) + _check_or_raise(agent, "koan_request_executor", {"artifacts": artifacts, "instructions": instructions}) call_id = begin_tool_call( - agent, "koan_spawn_executor", - {"story_id": story_id, "role": role}, - f"{role} for {story_id}", + agent, "koan_request_executor", + {"artifacts": artifacts or [], "instructions": instructions}, + f"{len(artifacts or [])} artifact(s)", ) result_str: str | None = None try: assert _app_state is not None - if role not in ("planner", "executor"): - raise ToolError(json.dumps({ - "error": "invalid_role", - "message": f"role must be 'planner' or 'executor', got '{role}'", - })) - - epic_dir = _resolve_epic_dir(agent) - if not epic_dir: - raise ToolError(json.dumps({"error": "no_epic_dir", "message": "No epic directory available"})) - - story_dir = Path(epic_dir) / "stories" / story_id - if not story_dir.is_dir(): - raise ToolError(json.dumps({ - "error": "story_not_found", - "message": f"Story directory not found: {story_dir}", - })) + run_dir = _resolve_run_dir(agent) + if not run_dir: + raise ToolError(json.dumps({"error": "no_run_dir", "message": "No run directory available"})) ts_suffix = int(time.time() * 1000) subagent_dir = await ensure_subagent_directory( - epic_dir, f"{role}-{story_id}-{ts_suffix}" + run_dir, f"executor-{ts_suffix}" ) - task: dict = { - "role": role, - "epic_dir": epic_dir, + task = { + "role": "executor", + "run_dir": run_dir, "subagent_dir": subagent_dir, "project_dir": _app_state.project_dir, - "story_id": story_id, + "artifacts": artifacts or [], + "instructions": instructions, } - if retry_context: - task["retryContext"] = retry_context from ..subagent import spawn_subagent result = await spawn_subagent(task, _app_state) - exit_code = result.exit_code - status = "succeeded" if exit_code == 0 else f"failed (exit code {exit_code})" - result_str = f"{role} for story '{story_id}' {status}." + status = "succeeded" if result.exit_code == 0 else f"failed (exit {result.exit_code})" + result_str = f"Executor {status}." result_str = _drain_and_append_steering(result_str, agent) return result_str finally: - end_tool_call(agent, call_id, "koan_spawn_executor", result_str) + end_tool_call(agent, call_id, "koan_request_executor", result_str) -# -- Story management tools --------------------------------------------------- +# -- Story management tools (legacy execution phase) --------------------------- @mcp.tool(name="koan_select_story") async def koan_select_story(story_id: str) -> str: @@ -710,11 +660,11 @@ async def koan_select_story(story_id: str) -> str: result_str: str | None = None try: assert _app_state is not None - epic_dir = _resolve_epic_dir(agent) - if not epic_dir: - raise ToolError(json.dumps({"error": "no_epic_dir"})) + run_dir = _resolve_run_dir(agent) + if not run_dir: + raise ToolError(json.dumps({"error": "no_run_dir"})) - await save_story_state(epic_dir, story_id, { + await save_story_state(run_dir, story_id, { "storyId": story_id, "status": "selected", "updatedAt": _now_iso(), @@ -736,11 +686,11 @@ async def koan_complete_story(story_id: str) -> str: result_str: str | None = None try: assert _app_state is not None - epic_dir = _resolve_epic_dir(agent) - if not epic_dir: - raise ToolError(json.dumps({"error": "no_epic_dir"})) + run_dir = _resolve_run_dir(agent) + if not run_dir: + raise ToolError(json.dumps({"error": "no_run_dir"})) - await save_story_state(epic_dir, story_id, { + await save_story_state(run_dir, story_id, { "storyId": story_id, "status": "done", "updatedAt": _now_iso(), @@ -762,14 +712,14 @@ async def koan_retry_story(story_id: str, failure_summary: str) -> str: result_str: str | None = None try: assert _app_state is not None - epic_dir = _resolve_epic_dir(agent) - if not epic_dir: - raise ToolError(json.dumps({"error": "no_epic_dir"})) + run_dir = _resolve_run_dir(agent) + if not run_dir: + raise ToolError(json.dumps({"error": "no_run_dir"})) - existing = await load_story_state(epic_dir, story_id) + existing = await load_story_state(run_dir, story_id) retry_count = existing.get("retryCount", 0) + 1 - await save_story_state(epic_dir, story_id, { + await save_story_state(run_dir, story_id, { "storyId": story_id, "status": "retry", "failureSummary": failure_summary, @@ -793,9 +743,9 @@ async def koan_skip_story(story_id: str, reason: str = "") -> str: result_str: str | None = None try: assert _app_state is not None - epic_dir = _resolve_epic_dir(agent) - if not epic_dir: - raise ToolError(json.dumps({"error": "no_epic_dir"})) + run_dir = _resolve_run_dir(agent) + if not run_dir: + raise ToolError(json.dumps({"error": "no_run_dir"})) state: dict = { "storyId": story_id, @@ -805,7 +755,7 @@ async def koan_skip_story(story_id: str, reason: str = "") -> str: if reason: state["skipReason"] = reason - await save_story_state(epic_dir, story_id, state) + await save_story_state(run_dir, story_id, state) result_str = f"Story '{story_id}' skipped." result_str = _drain_and_append_steering(result_str, agent) return result_str diff --git a/tests/test_interactions.py b/tests/test_interactions.py index abbd1d1..dd92102 100644 --- a/tests/test_interactions.py +++ b/tests/test_interactions.py @@ -30,7 +30,7 @@ class FakeAppState: active_interaction: PendingInteraction | None = None interaction_queue: deque[PendingInteraction] = field(default_factory=deque) interaction_queue_max: int = 8 - epic_dir: str | None = None + run_dir: str | None = None projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) phase_complete_future: asyncio.Future | None = None steering_queue: list = field(default_factory=list) @@ -78,7 +78,7 @@ async def test_9th_request_raises_queue_full(self): ) with pytest.raises(ToolError) as exc_info: - await enqueue_interaction(agent, app_state, "ask", {"questions": []}) + await enqueue_interaction(agent, app_state, "ask", {"questions": []}) err = json.loads(str(exc_info.value)) assert err["error"] == "interaction_queue_full" @@ -126,21 +126,8 @@ async def test_answer_with_no_active_interaction_returns_409(self): assert resp.json()["error"] == "stale_interaction" @pytest.mark.anyio - async def test_answer_wrong_type_returns_409(self): - from starlette.testclient import TestClient - - from koan.state import AppState - from koan.web.app import create_app - - app_state = AppState() - app_state.active_interaction = _make_interaction(interaction_type="artifact-review") - app = create_app(app_state) - client = TestClient(app, raise_server_exceptions=False) - resp = client.post("/api/answer", json={"answers": []}) - assert resp.status_code == 409 - - @pytest.mark.anyio - async def test_artifact_review_stale_returns_409(self): + async def test_artifact_review_route_removed(self): + """POST /api/artifact-review route is removed — returns 404 or 405.""" from starlette.testclient import TestClient from koan.state import AppState @@ -149,8 +136,9 @@ async def test_artifact_review_stale_returns_409(self): app_state = AppState() app = create_app(app_state) client = TestClient(app, raise_server_exceptions=False) + # Route removed; SPA fallback returns 200 for GET but POST should 405 or 404 resp = client.post("/api/artifact-review", json={"response": "Accept"}) - assert resp.status_code == 409 + assert resp.status_code in (404, 405, 409) # -- TestFIFOActivation ------------------------------------------------------- @@ -242,7 +230,7 @@ async def test_next_queued_activated_after_cancel(self): @pytest.mark.anyio async def test_phase_complete_future_cleared_on_exit(self): - """_cancel_pending_interactions clears phase_complete_future (QR4).""" + """_cancel_pending_interactions clears phase_complete_future.""" from koan.subagent import _cancel_pending_interactions app_state = FakeAppState() @@ -254,144 +242,3 @@ async def test_phase_complete_future_cleared_on_exit(self): assert future.done() assert app_state.phase_complete_future is None - - -# -- TestArtifactReviewResolution --------------------------------------------- - -class TestArtifactReviewResolution: - @pytest.mark.anyio - async def test_accept_resolves_future_with_accepted_true(self): - from starlette.testclient import TestClient - - from koan.state import AppState - from koan.web.app import create_app - - app_state = AppState() - interaction = _make_interaction(interaction_type="artifact-review") - app_state.active_interaction = interaction - - app = create_app(app_state) - client = TestClient(app, raise_server_exceptions=False) - resp = client.post( - "/api/artifact-review", - json={"accepted": True, "token": interaction.token}, - ) - - assert resp.status_code == 200 - result = interaction.future.result() - assert result["accepted"] is True - assert result["response"] == "" - - @pytest.mark.anyio - async def test_feedback_resolves_future_with_accepted_false(self): - from starlette.testclient import TestClient - - from koan.state import AppState - from koan.web.app import create_app - - app_state = AppState() - interaction = _make_interaction(interaction_type="artifact-review") - app_state.active_interaction = interaction - - app = create_app(app_state) - client = TestClient(app, raise_server_exceptions=False) - resp = client.post( - "/api/artifact-review", - json={"response": "Please add more detail", "token": interaction.token}, - ) - - assert resp.status_code == 200 - result = interaction.future.result() - assert result["accepted"] is False - assert result["response"] == "Please add more detail" - - @pytest.mark.anyio - async def test_accept_mcp_handler_returns_accepted_string(self): - from koan.phases import PhaseContext - from koan.state import AgentState - from koan.web.mcp_endpoint import _agent_ctx, koan_review_artifact - - import koan.web.mcp_endpoint as mcp_mod - - app_state = FakeAppState() - old_app_state = mcp_mod._app_state - mcp_mod._app_state = app_state - - phase_ctx = PhaseContext(epic_dir="/tmp", subagent_dir="/tmp/test") - agent = AgentState( - agent_id="test-review", - role="intake", - subagent_dir="/tmp/test", - phase_ctx=phase_ctx, - ) - - # Pre-create and resolve the interaction future - interaction = _make_interaction(interaction_type="artifact-review", agent_id="test-review") - interaction.future.set_result({"response": "", "accepted": True}) - app_state.active_interaction = interaction - - token = _agent_ctx.set(agent) - try: - with patch("koan.web.mcp_endpoint._check_or_raise"), \ - patch("koan.web.mcp_endpoint.enqueue_interaction", return_value=interaction.future), \ - patch("aiofiles.open", side_effect=FileNotFoundError): - # We need to provide a real file for the artifact read; - # patch aiofiles to return content - import aiofiles - from unittest.mock import AsyncMock, MagicMock - - mock_file = AsyncMock() - mock_file.__aenter__ = AsyncMock(return_value=mock_file) - mock_file.__aexit__ = AsyncMock(return_value=False) - mock_file.read = AsyncMock(return_value="artifact content") - - with patch("aiofiles.open", return_value=mock_file): - result = await koan_review_artifact(path="/tmp/test.md", description="test") - finally: - _agent_ctx.reset(token) - mcp_mod._app_state = old_app_state - - assert result == "ACCEPTED" - - @pytest.mark.anyio - async def test_feedback_mcp_handler_returns_revision_requested(self): - from koan.phases import PhaseContext - from koan.state import AgentState - from koan.web.mcp_endpoint import _agent_ctx, koan_review_artifact - - import koan.web.mcp_endpoint as mcp_mod - - app_state = FakeAppState() - old_app_state = mcp_mod._app_state - mcp_mod._app_state = app_state - - phase_ctx = PhaseContext(epic_dir="/tmp", subagent_dir="/tmp/test") - agent = AgentState( - agent_id="test-review", - role="intake", - subagent_dir="/tmp/test", - phase_ctx=phase_ctx, - ) - - interaction = _make_interaction(interaction_type="artifact-review", agent_id="test-review") - interaction.future.set_result({"response": "needs work", "accepted": False}) - app_state.active_interaction = interaction - - token = _agent_ctx.set(agent) - try: - from unittest.mock import AsyncMock - - mock_file = AsyncMock() - mock_file.__aenter__ = AsyncMock(return_value=mock_file) - mock_file.__aexit__ = AsyncMock(return_value=False) - mock_file.read = AsyncMock(return_value="artifact content") - - with patch("koan.web.mcp_endpoint._check_or_raise"), \ - patch("koan.web.mcp_endpoint.enqueue_interaction", return_value=interaction.future), \ - patch("aiofiles.open", return_value=mock_file): - result = await koan_review_artifact(path="/tmp/test.md", description="test") - finally: - _agent_ctx.reset(token) - mcp_mod._app_state = old_app_state - - assert result.startswith("REVISION REQUESTED:") diff --git a/tests/test_mcp_check_or_raise.py b/tests/test_mcp_check_or_raise.py index 460dd27..03e1175 100644 --- a/tests/test_mcp_check_or_raise.py +++ b/tests/test_mcp_check_or_raise.py @@ -1,6 +1,6 @@ # Unit tests for _check_or_raise in koan.web.mcp_endpoint. # -# Validates epic_dir resolution from phase_ctx vs agent.epic_dir, +# Validates run_dir resolution from phase_ctx vs agent.run_dir, # and confirms the permission-denied JSON envelope shape. import json @@ -15,28 +15,28 @@ def _make_agent( role="intake", - epic_dir="", + run_dir="", step=2, phase_ctx=None, ): a = AgentState(agent_id="test", role=role, subagent_dir="/tmp/sub") - a.epic_dir = epic_dir + a.run_dir = run_dir a.step = step a.phase_ctx = phase_ctx return a -# -- phase_ctx.epic_dir enforcement ------------------------------------------- +# -- phase_ctx.run_dir enforcement ------------------------------------------- -class TestPhaseCtxEpicDir: - def test_phase_ctx_epic_dir_enforced(self): - ctx = PhaseContext(epic_dir="/tmp/epic", subagent_dir="/tmp/sub") +class TestPhaseCtxRunDir: + def test_phase_ctx_run_dir_enforced(self): + ctx = PhaseContext(run_dir="/tmp/epic", subagent_dir="/tmp/sub") agent = _make_agent(phase_ctx=ctx) with pytest.raises(ToolError, match="permission_denied"): _check_or_raise(agent, "write", {"path": "/home/evil.sh"}) - def test_phase_ctx_epic_dir_allows_inside(self): - ctx = PhaseContext(epic_dir="/tmp/epic", subagent_dir="/tmp/sub") + def test_phase_ctx_run_dir_allows_inside(self): + ctx = PhaseContext(run_dir="/tmp/epic", subagent_dir="/tmp/sub") agent = _make_agent(phase_ctx=ctx) _check_or_raise(agent, "write", {"path": "/tmp/epic/foo.md"}) @@ -48,17 +48,17 @@ def test_no_phase_ctx_no_crash(self): agent = _make_agent() _check_or_raise(agent, "write") - def test_agent_epic_dir_fallback(self): - agent = _make_agent(epic_dir="/tmp/epic") + def test_agent_run_dir_fallback(self): + agent = _make_agent(run_dir="/tmp/epic") with pytest.raises(ToolError, match="permission_denied"): _check_or_raise(agent, "write", {"path": "/home/evil.sh"}) -# -- Empty epic_dir everywhere ------------------------------------------------ +# -- Empty run_dir everywhere ------------------------------------------------ -class TestEmptyEpicDir: - def test_phase_ctx_empty_epic_dir_no_crash(self): - ctx = PhaseContext(epic_dir="", subagent_dir="/tmp/sub") +class TestEmptyRunDir: + def test_phase_ctx_empty_run_dir_no_crash(self): + ctx = PhaseContext(run_dir="", subagent_dir="/tmp/sub") agent = _make_agent(phase_ctx=ctx) _check_or_raise(agent, "write") diff --git a/tests/test_permissions.py b/tests/test_permissions.py index 9b504ab..db7fb49 100644 --- a/tests/test_permissions.py +++ b/tests/test_permissions.py @@ -117,20 +117,17 @@ def test_koan_request_scouts_brief_generation_denied(self): r = check_permission("orchestrator", "koan_request_scouts", current_phase="brief-generation") assert not r["allowed"] - def test_koan_review_artifact_brief_generation_allowed(self): - r = check_permission("orchestrator", "koan_review_artifact", current_phase="brief-generation") - assert r["allowed"] - def test_koan_review_artifact_execution_denied(self): - r = check_permission("orchestrator", "koan_review_artifact", current_phase="execution") - assert not r["allowed"] + def test_koan_request_executor_execution_allowed(self): + r = check_permission("orchestrator", "koan_request_executor", current_phase="execution") + assert r["allowed"] - def test_koan_spawn_executor_execution_allowed(self): - r = check_permission("orchestrator", "koan_spawn_executor", current_phase="execution") + def test_koan_request_executor_execute_phase_allowed(self): + r = check_permission("orchestrator", "koan_request_executor", current_phase="execute") assert r["allowed"] - def test_koan_spawn_executor_intake_denied(self): - r = check_permission("orchestrator", "koan_spawn_executor", current_phase="intake") + def test_koan_request_executor_intake_denied(self): + r = check_permission("orchestrator", "koan_request_executor", current_phase="intake") assert not r["allowed"] def test_story_tools_execution_allowed(self): @@ -206,7 +203,7 @@ def setup_method(self): def test_write_inside_epic_allowed(self): r = check_permission( "intake", "write", - epic_dir=self.epic, + run_dir=self.epic, tool_args={"path": "/tmp/epic/foo.md"}, current_step=2, ) @@ -215,17 +212,17 @@ def test_write_inside_epic_allowed(self): def test_write_outside_epic_denied(self): r = check_permission( "intake", "write", - epic_dir=self.epic, + run_dir=self.epic, tool_args={"path": "/home/user/evil.sh"}, current_step=2, ) assert not r["allowed"] - assert "outside epic directory" in r["reason"] + assert "outside run directory" in r["reason"] def test_edit_outside_epic_denied(self): r = check_permission( "planner", "edit", - epic_dir=self.epic, + run_dir=self.epic, tool_args={"path": "/etc/passwd"}, current_step=2, ) @@ -234,7 +231,7 @@ def test_edit_outside_epic_denied(self): def test_write_at_epic_root_allowed(self): r = check_permission( "intake", "write", - epic_dir=self.epic, + run_dir=self.epic, tool_args={"path": "/tmp/epic"}, current_step=2, ) @@ -243,7 +240,7 @@ def test_write_at_epic_root_allowed(self): def test_orchestrator_write_inside_epic_allowed(self): r = check_permission( "orchestrator", "write", - epic_dir=self.epic, + run_dir=self.epic, tool_args={"path": "/tmp/epic/brief.md"}, current_phase="brief-generation", current_step=2, @@ -253,13 +250,13 @@ def test_orchestrator_write_inside_epic_allowed(self): def test_orchestrator_write_outside_epic_denied(self): r = check_permission( "orchestrator", "write", - epic_dir=self.epic, + run_dir=self.epic, tool_args={"path": "/home/user/evil.sh"}, current_phase="intake", current_step=2, ) assert not r["allowed"] - assert "outside epic directory" in r["reason"] + assert "outside run directory" in r["reason"] # -- Executor unrestricted write ----------------------------------------------- @@ -268,24 +265,24 @@ class TestExecutorUnrestricted: def test_write_outside_epic_allowed(self): r = check_permission( "executor", "write", - epic_dir="/tmp/epic", + run_dir="/tmp/epic", tool_args={"path": "/home/user/code.py"}, current_step=2, ) assert r["allowed"] -# -- No epic_dir / no path arg ------------------------------------------------ +# -- No run_dir / no path arg ------------------------------------------------ class TestNoEpicDirNoPathArg: - def test_no_epic_dir_allows_write(self): + def test_no_run_dir_allows_write(self): r = check_permission("intake", "write", current_step=2) assert r["allowed"] def test_no_path_arg_allows_write(self): r = check_permission( "intake", "write", - epic_dir="/tmp/epic", + run_dir="/tmp/epic", tool_args={"content": "hello"}, current_step=2, ) @@ -294,7 +291,7 @@ def test_no_path_arg_allows_write(self): def test_no_tool_args_allows_write(self): r = check_permission( "intake", "write", - epic_dir="/tmp/epic", + run_dir="/tmp/epic", current_step=2, ) assert r["allowed"] diff --git a/tests/test_phase_dag.py b/tests/test_phase_dag.py deleted file mode 100644 index 34ea31f..0000000 --- a/tests/test_phase_dag.py +++ /dev/null @@ -1,143 +0,0 @@ -# Tests for koan/lib/phase_dag.py -- phase transition DAG. - -from koan.lib.phase_dag import ( - IMPLEMENTED_PHASES, - PHASE_DESCRIPTIONS, - PHASE_TRANSITIONS, - get_successor_phases, - is_auto_advance, - is_stub_phase, - is_valid_transition, -) - -ALL_PHASES = [ - "intake", - "brief-generation", - "core-flows", - "tech-plan", - "ticket-breakdown", - "cross-artifact-validation", - "execution", - "implementation-validation", - "completed", -] - - -# -- PHASE_TRANSITIONS completeness ------------------------------------------- - -def test_all_phases_have_transition_entries(): - for phase in ALL_PHASES: - assert phase in PHASE_TRANSITIONS, f"{phase} missing from PHASE_TRANSITIONS" - - -def test_completed_has_no_successors(): - assert PHASE_TRANSITIONS["completed"] == [] - - -def test_intake_has_two_successors(): - assert len(PHASE_TRANSITIONS["intake"]) == 2 - - -# -- get_successor_phases ------------------------------------------------------ - -def test_successor_phases_intake(): - assert get_successor_phases("intake") == ["brief-generation", "core-flows"] - - -def test_successor_phases_brief_generation(): - assert get_successor_phases("brief-generation") == ["core-flows"] - - -def test_successor_phases_completed(): - assert get_successor_phases("completed") == [] - - -# -- is_auto_advance ----------------------------------------------------------- - -def test_auto_advance_false_for_intake(): - assert is_auto_advance("intake") is False - - -def test_auto_advance_true_for_single_successor_phases(): - single_successor = [p for p in ALL_PHASES if len(PHASE_TRANSITIONS[p]) == 1] - for phase in single_successor: - assert is_auto_advance(phase) is True, f"{phase} should auto-advance" - - -def test_auto_advance_false_for_completed(): - assert is_auto_advance("completed") is False - - -# -- is_stub_phase ------------------------------------------------------------- - -def test_not_stub_for_implemented_phases(): - for phase in IMPLEMENTED_PHASES: - assert is_stub_phase(phase) is False, f"{phase} should not be a stub" - - -def test_not_stub_for_completed(): - assert is_stub_phase("completed") is False - - -def test_not_stub_for_implementation_validation(): - assert is_stub_phase("implementation-validation") is False - - -# -- is_valid_transition ------------------------------------------------------- - -def test_valid_transition_intake_to_brief(): - assert is_valid_transition("intake", "brief-generation") is True - - -def test_valid_transition_intake_to_core_flows(): - assert is_valid_transition("intake", "core-flows") is True - - -def test_valid_transition_full_linear_path(): - linear = [ - ("brief-generation", "core-flows"), - ("core-flows", "tech-plan"), - ("tech-plan", "ticket-breakdown"), - ("ticket-breakdown", "cross-artifact-validation"), - ("cross-artifact-validation", "execution"), - ("execution", "implementation-validation"), - ("implementation-validation", "completed"), - ] - for from_p, to_p in linear: - assert is_valid_transition(from_p, to_p) is True, f"{from_p} -> {to_p} should be valid" - - -def test_invalid_transition_skip(): - assert is_valid_transition("intake", "tech-plan") is False - - -def test_invalid_transition_backward(): - assert is_valid_transition("core-flows", "intake") is False - - -def test_invalid_transition_from_completed(): - assert is_valid_transition("completed", "intake") is False - - -# -- PHASE_DESCRIPTIONS -------------------------------------------------------- - -def test_all_phases_have_descriptions(): - for phase in ALL_PHASES: - assert phase in PHASE_DESCRIPTIONS, f"{phase} missing from PHASE_DESCRIPTIONS" - assert isinstance(PHASE_DESCRIPTIONS[phase], str) - assert len(PHASE_DESCRIPTIONS[phase]) > 0 - - -# -- IMPLEMENTED_PHASES -------------------------------------------------------- - -def test_implemented_phases_content(): - expected = { - "intake", - "brief-generation", - "core-flows", - "tech-plan", - "ticket-breakdown", - "cross-artifact-validation", - "execution", - } - assert IMPLEMENTED_PHASES == expected diff --git a/tests/test_phases.py b/tests/test_phases.py index 26dddf9..0c936d8 100644 --- a/tests/test_phases.py +++ b/tests/test_phases.py @@ -14,10 +14,13 @@ from koan.phases import executor from koan.phases import orchestrator from koan.phases import scout +from koan.phases import plan_spec +from koan.phases import plan_review +from koan.phases import execute as execute_phase def _ctx(**kw) -> PhaseContext: - defaults = {"epic_dir": "/tmp/epic", "subagent_dir": "/tmp/sub"} + defaults = {"run_dir": "/tmp/run", "subagent_dir": "/tmp/sub"} defaults.update(kw) return PhaseContext(**defaults) @@ -25,64 +28,150 @@ def _ctx(**kw) -> PhaseContext: # -- Intake -------------------------------------------------------------------- class TestIntake: - # -- Linear progression (steps 1-2) ---------------------------------------- + # -- Linear progression (steps 1-3) ---------------------------------------- @pytest.mark.parametrize("step", [1, 2]) def test_linear_steps(self, step): assert intake.get_next_step(step, _ctx()) == step + 1 - # -- Review gate (step 3) -------------------------------------------------- - - def test_step_3_accepted_completes(self): - assert intake.get_next_step(3, _ctx(last_review_accepted=True)) is None - - def test_step_3_not_accepted_loops(self): - assert intake.get_next_step(3, _ctx(last_review_accepted=False)) == 3 + def test_step_3_completes(self): + """Step 3 (Write) completes unconditionally — no review gate.""" + assert intake.get_next_step(3, _ctx()) is None - def test_validate_step_3_never_reviewed(self): - result = intake.validate_step_completion(3, _ctx(last_review_accepted=None)) - assert result is not None - assert "koan_review_artifact" in result + # -- No validation gates --------------------------------------------------- - def test_validate_step_3_feedback_pending(self): - result = intake.validate_step_completion(3, _ctx(last_review_accepted=False)) - assert result is not None - assert "revision" in result.lower() or "feedback" in result.lower() + def test_validate_all_steps_none(self): + ctx = _ctx() + for s in range(1, 4): + assert intake.validate_step_completion(s, ctx) is None - def test_validate_step_3_accepted(self): - assert intake.validate_step_completion(3, _ctx(last_review_accepted=True)) is None + # -- Step guidance contains workflow context injection ---------------------- - # -- No gate on other steps ------------------------------------------------ + def test_step_1_guidance_with_phase_instructions(self): + ctx = _ctx(phase_instructions="## Scope\nThis is a plan workflow.") + g = intake.step_guidance(1, ctx) + text = "\n".join(g.instructions) + assert "Workflow Context" in text + assert "plan workflow" in text - def test_validate_step_1_no_gate(self): - assert intake.validate_step_completion(1, _ctx()) is None + def test_step_1_guidance_with_workflow_name(self): + ctx = _ctx(workflow_name="plan") + g = intake.step_guidance(1, ctx) + text = "\n".join(g.instructions) + assert "plan" in text - def test_validate_step_2_no_gate(self): - assert intake.validate_step_completion(2, _ctx()) is None + def test_step_3_guidance_references_run_dir(self): + ctx = _ctx(run_dir="/tmp/myrun") + g = intake.step_guidance(3, ctx) + text = "\n".join(g.instructions) + assert "/tmp/myrun/landscape.md" in text # -- Brief Writer -------------------------------------------------------------- class TestBriefWriter: - def test_step_2_accepted_advances(self): - assert brief_writer.get_next_step(2, _ctx(last_review_accepted=True)) == 3 + def test_step_1_to_2(self): + assert brief_writer.get_next_step(1, _ctx()) == 2 + + def test_step_2_completes(self): + """Step 2 is terminal — no review gate.""" + assert brief_writer.get_next_step(2, _ctx()) is None - def test_step_2_not_accepted_loops(self): - assert brief_writer.get_next_step(2, _ctx(last_review_accepted=False)) == 2 + def test_validate_all_none(self): + ctx = _ctx() + for s in (1, 2): + assert brief_writer.validate_step_completion(s, ctx) is None + + def test_total_steps_is_2(self): + assert brief_writer.TOTAL_STEPS == 2 - def test_validate_step_2_never_reviewed(self): - result = brief_writer.validate_step_completion(2, _ctx(last_review_accepted=None)) - assert result is not None - assert "koan_review_artifact" in result - def test_validate_step_2_accepted(self): - assert brief_writer.validate_step_completion(2, _ctx(last_review_accepted=True)) is None +# -- Plan Spec ----------------------------------------------------------------- +class TestPlanSpec: def test_step_1_to_2(self): - assert brief_writer.get_next_step(1, _ctx()) == 2 + assert plan_spec.get_next_step(1, _ctx()) == 2 - def test_step_3_completes(self): - assert brief_writer.get_next_step(3, _ctx()) is None + def test_step_2_completes(self): + assert plan_spec.get_next_step(2, _ctx()) is None + + def test_validate_always_none(self): + ctx = _ctx() + for s in (1, 2): + assert plan_spec.validate_step_completion(s, ctx) is None + + def test_total_steps_is_2(self): + assert plan_spec.TOTAL_STEPS == 2 + + def test_scope_is_plan(self): + assert plan_spec.SCOPE == "plan" + + def test_step_1_guidance_references_run_dir(self): + ctx = _ctx(run_dir="/tmp/myrun") + g = plan_spec.step_guidance(1, ctx) + text = "\n".join(g.instructions) + assert "landscape.md" in text + + def test_step_2_guidance_references_plan_md(self): + ctx = _ctx(run_dir="/tmp/myrun") + g = plan_spec.step_guidance(2, ctx) + text = "\n".join(g.instructions) + assert "plan.md" in text + + +# -- Plan Review --------------------------------------------------------------- + +class TestPlanReview: + def test_step_1_to_2(self): + assert plan_review.get_next_step(1, _ctx()) == 2 + + def test_step_2_completes(self): + assert plan_review.get_next_step(2, _ctx()) is None + + def test_validate_always_none(self): + ctx = _ctx() + for s in (1, 2): + assert plan_review.validate_step_completion(s, ctx) is None + + def test_total_steps_is_2(self): + assert plan_review.TOTAL_STEPS == 2 + + def test_scope_is_plan(self): + assert plan_review.SCOPE == "plan" + + def test_step_1_guidance_references_landscape_and_plan(self): + ctx = _ctx(run_dir="/tmp/myrun") + g = plan_review.step_guidance(1, ctx) + text = "\n".join(g.instructions) + assert "landscape.md" in text + assert "plan.md" in text + + +# -- Execute Phase ------------------------------------------------------------- + +class TestExecutePhase: + def test_step_1_to_2(self): + assert execute_phase.get_next_step(1, _ctx()) == 2 + + def test_step_2_completes(self): + assert execute_phase.get_next_step(2, _ctx()) is None + + def test_validate_always_none(self): + ctx = _ctx() + for s in (1, 2): + assert execute_phase.validate_step_completion(s, ctx) is None + + def test_total_steps_is_2(self): + assert execute_phase.TOTAL_STEPS == 2 + + def test_scope_is_general(self): + assert execute_phase.SCOPE == "general" + + def test_step_1_guidance_with_phase_instructions(self): + ctx = _ctx(phase_instructions="## What to hand off\nCall koan_request_executor.") + g = execute_phase.step_guidance(1, ctx) + text = "\n".join(g.instructions) + assert "koan_request_executor" in text # -- Orchestrator -------------------------------------------------------------- @@ -105,6 +194,49 @@ def test_pre_execution_step_1_advances(self): assert orchestrator.get_next_step(1, ctx) == 2 +# -- Executor (rewritten: 3-step) ---------------------------------------------- + +class TestExecutor: + def test_step_1_to_2(self): + assert executor.get_next_step(1, _ctx()) == 2 + + def test_step_2_to_3(self): + assert executor.get_next_step(2, _ctx()) == 3 + + def test_step_3_completes(self): + assert executor.get_next_step(3, _ctx()) is None + + def test_validate_always_none(self): + ctx = _ctx() + for s in (1, 2, 3): + assert executor.validate_step_completion(s, ctx) is None + + def test_total_steps_is_3(self): + assert executor.TOTAL_STEPS == 3 + + def test_scope_is_general(self): + assert executor.SCOPE == "general" + + def test_step_1_guidance_with_artifacts(self): + ctx = _ctx(run_dir="/tmp/myrun", executor_artifacts=["plan.md", "landscape.md"]) + g = executor.step_guidance(1, ctx) + text = "\n".join(g.instructions) + assert "/tmp/myrun/plan.md" in text + assert "/tmp/myrun/landscape.md" in text + + def test_step_1_guidance_with_phase_instructions(self): + ctx = _ctx(phase_instructions="Key constraint: don't touch auth module.") + g = executor.step_guidance(1, ctx) + text = "\n".join(g.instructions) + assert "Key constraint" in text + + def test_step_1_guidance_with_retry_context(self): + ctx = _ctx(retry_context="Previous run failed at step 3 due to import error.") + g = executor.step_guidance(1, ctx) + text = "\n".join(g.instructions) + assert "import error" in text + + # -- Linear modules (all steps linear, no validation gates) -------------------- LINEAR_MODULES = [ @@ -112,7 +244,6 @@ def test_pre_execution_step_1_advances(self): (tech_plan, 3), (ticket_breakdown, 2), (cross_artifact_validation, 2), - (executor, 2), (scout, 3), ] @@ -136,18 +267,20 @@ def test_validate_always_none(self, mod, total): # -- Purity invariant ---------------------------------------------------------- class TestPurity: - def test_intake_review_gate_purity(self): - ctx = _ctx(last_review_accepted=False) + def test_intake_step_3_pure(self): + """Intake step 3 always returns None (no review gate).""" + ctx = _ctx() ctx_copy = copy.deepcopy(ctx) r1 = intake.get_next_step(3, ctx) r2 = intake.get_next_step(3, ctx) - assert r1 == r2 + assert r1 == r2 == None assert ctx == ctx_copy - def test_brief_writer_purity(self): - ctx = _ctx(last_review_accepted=True) + def test_brief_writer_step_2_pure(self): + """Brief writer step 2 always returns None (no review gate).""" + ctx = _ctx() ctx_copy = copy.deepcopy(ctx) r1 = brief_writer.get_next_step(2, ctx) r2 = brief_writer.get_next_step(2, ctx) - assert r1 == r2 + assert r1 == r2 == None assert ctx == ctx_copy diff --git a/tests/test_projections.py b/tests/test_projections.py index cd8c459..bb57b8b 100644 --- a/tests/test_projections.py +++ b/tests/test_projections.py @@ -17,7 +17,6 @@ Projection, ProjectionStore, QuestionFocus, - ReviewFocus, Run, RunConfig, Settings, @@ -124,6 +123,16 @@ def test_workflow_completed_without_run_is_noop(self): r = fold(p, _e("workflow_completed", {"success": True})) assert r.run is None + def test_workflow_selected_sets_workflow(self): + p = _proj_with_run() + r = fold(p, _e("workflow_selected", {"workflow": "plan"})) + assert r.run.workflow == "plan" + + def test_workflow_selected_without_run_is_noop(self): + p = Projection() + r = fold(p, _e("workflow_selected", {"workflow": "plan"})) + assert r.run is None + # --------------------------------------------------------------------------- # fold: agent lifecycle @@ -455,27 +464,6 @@ def test_questions_answered_resets_to_conversation_focus(self): assert isinstance(r.run.focus, ConversationFocus) assert r.run.focus.agent_id == "a1" - def test_artifact_review_requested_sets_review_focus(self): - p = _proj_with_primary("a1") - r = fold(p, _e("artifact_review_requested", { - "token": "t2", "path": "/f.md", "description": "d", "content": "c", - }, agent_id="a1")) - assert isinstance(r.run.focus, ReviewFocus) - assert r.run.focus.path == "/f.md" - - def test_artifact_reviewed_resets_to_conversation_focus(self): - p = _proj_with_primary("a1") - p = fold(p, _e("artifact_review_requested", {"token": "t2", "path": "/f.md", "description": "", "content": ""}, agent_id="a1")) - r = fold(p, _e("artifact_reviewed", {"token": "t2", "cancelled": False}, agent_id="a1")) - assert isinstance(r.run.focus, ConversationFocus) - - -# --------------------------------------------------------------------------- -# fold: settings -# --------------------------------------------------------------------------- - -class TestFoldSettings: - def test_installation_created_adds_to_dict(self): p = Projection() r = fold(p, _e("installation_created", { diff --git a/tests/test_subagent.py b/tests/test_subagent.py index d0dfa09..d6b2461 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -34,7 +34,7 @@ class FakeAppState: active_interaction: Any = None interaction_queue: Any = field(default_factory=lambda: __import__("collections").deque()) interaction_queue_max: int = 8 - epic_dir: str | None = None + run_dir: str | None = None projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) run_installations: dict = field(default_factory=dict) _active_processes: dict = field(default_factory=dict) @@ -163,7 +163,7 @@ async def test_step_0_to_1_returns_guidance(self): subagent_dir="/tmp/test", step=0, phase_module=phase_mod, - phase_ctx=PhaseContext(epic_dir="/tmp", subagent_dir="/tmp/test"), + phase_ctx=PhaseContext(run_dir="/tmp", subagent_dir="/tmp/test"), event_log=event_log, ) @@ -193,7 +193,7 @@ async def test_validation_failure_raises(self): subagent_dir="/tmp/test", step=4, phase_module=phase_mod, - phase_ctx=PhaseContext(epic_dir="/tmp", subagent_dir="/tmp/test"), + phase_ctx=PhaseContext(run_dir="/tmp", subagent_dir="/tmp/test"), event_log=AsyncMock(), ) @@ -222,7 +222,7 @@ async def test_loop_back_calls_on_loop_back(self): subagent_dir="/tmp/test", step=4, phase_module=phase_mod, - phase_ctx=PhaseContext(epic_dir="/tmp", subagent_dir="/tmp/test"), + phase_ctx=PhaseContext(run_dir="/tmp", subagent_dir="/tmp/test"), event_log=AsyncMock(), ) @@ -250,7 +250,7 @@ async def test_bootstrap_failure_detection(self, tmp_path): task = { "role": "intake", - "epic_dir": str(tmp_path), + "run_dir": str(tmp_path), "subagent_dir": subagent_dir, } @@ -278,7 +278,7 @@ async def test_successful_handshake_via_mcp(self, tmp_path): task = { "role": "intake", - "epic_dir": str(tmp_path), + "run_dir": str(tmp_path), "subagent_dir": subagent_dir, } @@ -330,7 +330,7 @@ async def test_model_field_propagated_to_agent_state(self, tmp_path): task = { "role": "intake", - "epic_dir": str(tmp_path), + "run_dir": str(tmp_path), "subagent_dir": subagent_dir, } @@ -382,15 +382,15 @@ async def test_aggregation_ordering(self, tmp_path): from koan.state import AgentState from koan.web.mcp_endpoint import _agent_ctx, _app_state, koan_request_scouts - app_state = FakeAppState(port=9999, epic_dir=str(tmp_path)) + app_state = FakeAppState(port=9999, run_dir=str(tmp_path)) agent = AgentState( agent_id="scout-parent", role="intake", subagent_dir=str(tmp_path), - epic_dir=str(tmp_path), + run_dir=str(tmp_path), phase_module=_fake_phase_module(), - phase_ctx=PhaseContext(epic_dir=str(tmp_path), subagent_dir=str(tmp_path)), + phase_ctx=PhaseContext(run_dir=str(tmp_path), subagent_dir=str(tmp_path)), event_log=AsyncMock(), ) @@ -434,16 +434,16 @@ async def test_semaphore_bounds_concurrency(self, tmp_path): from koan.state import AgentState from koan.web.mcp_endpoint import _agent_ctx, koan_request_scouts - app_state = FakeAppState(port=9999, epic_dir=str(tmp_path)) + app_state = FakeAppState(port=9999, run_dir=str(tmp_path)) app_state.config.scout_concurrency = 1 # serial execution agent = AgentState( agent_id="scout-parent", role="intake", subagent_dir=str(tmp_path), - epic_dir=str(tmp_path), + run_dir=str(tmp_path), phase_module=_fake_phase_module(), - phase_ctx=PhaseContext(epic_dir=str(tmp_path), subagent_dir=str(tmp_path)), + phase_ctx=PhaseContext(run_dir=str(tmp_path), subagent_dir=str(tmp_path)), event_log=AsyncMock(), ) @@ -488,15 +488,15 @@ async def test_missing_state_json_treated_as_failure(self, tmp_path): from koan.state import AgentState from koan.web.mcp_endpoint import _agent_ctx, koan_request_scouts - app_state = FakeAppState(port=9999, epic_dir=str(tmp_path)) + app_state = FakeAppState(port=9999, run_dir=str(tmp_path)) agent = AgentState( agent_id="scout-parent", role="intake", subagent_dir=str(tmp_path), - epic_dir=str(tmp_path), + run_dir=str(tmp_path), phase_module=_fake_phase_module(), - phase_ctx=PhaseContext(epic_dir=str(tmp_path), subagent_dir=str(tmp_path)), + phase_ctx=PhaseContext(run_dir=str(tmp_path), subagent_dir=str(tmp_path)), event_log=AsyncMock(), ) @@ -560,7 +560,7 @@ async def test_sse_notification_includes_diagnostic_fields(self, tmp_path): task = { "role": "intake", - "epic_dir": str(tmp_path), + "run_dir": str(tmp_path), "subagent_dir": subagent_dir, } @@ -631,7 +631,7 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): task = { "role": "intake", - "epic_dir": str(tmp_path), + "run_dir": str(tmp_path), "subagent_dir": subagent_dir, } diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index b9175a0..258c675 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -79,7 +79,7 @@ def test_start_run_sets_event(client, app_state): data = resp.json() assert data["ok"] is True assert app_state.start_event.is_set() - assert app_state.epic_dir is not None + assert app_state.run_dir is not None def test_start_run_requires_task(client, app_state): @@ -217,7 +217,7 @@ def test_artifact_listing(client, app_state): with tempfile.TemporaryDirectory() as tmp: epic = Path(tmp) (epic / "landscape.md").write_text("# Landscape\n", "utf-8") - app_state.epic_dir = str(epic) + app_state.run_dir = str(epic) app_state.start_event.set() resp = client.get("/api/artifacts") @@ -231,7 +231,7 @@ def test_artifact_content(client, app_state): with tempfile.TemporaryDirectory() as tmp: epic = Path(tmp) (epic / "landscape.md").write_text("# Hello\n", "utf-8") - app_state.epic_dir = str(epic) + app_state.run_dir = str(epic) app_state.start_event.set() resp = client.get("/api/artifacts/landscape.md") @@ -245,7 +245,7 @@ def test_path_traversal_blocked(client, app_state): with tempfile.TemporaryDirectory() as tmp: epic = Path(tmp) epic.mkdir(exist_ok=True) - app_state.epic_dir = str(epic) + app_state.run_dir = str(epic) app_state.start_event.set() # URL-normalized traversal (../) is resolved before routing and hits the SPA fallback. @@ -441,7 +441,7 @@ def test_live_page_when_running(client, app_state): # After SPA migration, GET / always returns the SPA entry point. # The React app reads store state client-side to render the live view. app_state.start_event.set() - app_state.epic_dir = "/tmp/fake-epic" + app_state.run_dir = "/tmp/fake-epic" app_state.phase = "intake" resp = client.get("/") diff --git a/tests/test_workflows.py b/tests/test_workflows.py new file mode 100644 index 0000000..7e60fca --- /dev/null +++ b/tests/test_workflows.py @@ -0,0 +1,162 @@ +# Tests for koan/lib/workflows.py -- workflow type system. + +import pytest + +from koan.lib.workflows import ( + MILESTONES_WORKFLOW, + PLAN_WORKFLOW, + WORKFLOWS, + Workflow, + get_suggested_phases, + get_workflow, + is_valid_transition, +) + + +# -- get_workflow -------------------------------------------------------------- + +def test_get_workflow_valid_plan(): + wf = get_workflow("plan") + assert wf.name == "plan" + + +def test_get_workflow_valid_milestones(): + wf = get_workflow("milestones") + assert wf.name == "milestones" + + +def test_get_workflow_invalid_raises(): + with pytest.raises(ValueError, match="Unknown workflow"): + get_workflow("nonexistent") + + +def test_get_workflow_lists_valid_in_error(): + with pytest.raises(ValueError, match="plan"): + get_workflow("bogus") + + +# -- get_suggested_phases ----------------------------------------------------- + +def test_get_suggested_phases_intake(): + phases = get_suggested_phases(PLAN_WORKFLOW, "intake") + assert "plan-spec" in phases + assert "execute" in phases + + +def test_get_suggested_phases_plan_spec(): + phases = get_suggested_phases(PLAN_WORKFLOW, "plan-spec") + assert "plan-review" in phases + assert "execute" in phases + + +def test_get_suggested_phases_plan_review(): + phases = get_suggested_phases(PLAN_WORKFLOW, "plan-review") + assert "plan-spec" in phases + assert "execute" in phases + + +def test_get_suggested_phases_execute(): + phases = get_suggested_phases(PLAN_WORKFLOW, "execute") + assert "plan-review" in phases + + +def test_get_suggested_phases_milestones_intake_empty(): + phases = get_suggested_phases(MILESTONES_WORKFLOW, "intake") + assert phases == [] + + +def test_get_suggested_phases_unknown_phase(): + phases = get_suggested_phases(PLAN_WORKFLOW, "nonexistent") + assert phases == [] + + +# -- is_valid_transition ------------------------------------------------------- + +def test_is_valid_transition_available_phase(): + assert is_valid_transition(PLAN_WORKFLOW, "intake", "plan-spec") is True + + +def test_is_valid_transition_self_blocked(): + assert is_valid_transition(PLAN_WORKFLOW, "intake", "intake") is False + + +def test_is_valid_transition_unavailable_phase(): + assert is_valid_transition(PLAN_WORKFLOW, "intake", "execution") is False + + +def test_is_valid_transition_any_to_any_within_workflow(): + """Any phase can transition to any other phase in the workflow (user-directed).""" + phases = list(PLAN_WORKFLOW.available_phases) + for from_p in phases: + for to_p in phases: + if from_p != to_p: + assert is_valid_transition(PLAN_WORKFLOW, from_p, to_p) is True, \ + f"{from_p} -> {to_p} should be valid" + + +def test_is_valid_transition_milestones_to_plan_spec_denied(): + assert is_valid_transition(MILESTONES_WORKFLOW, "intake", "plan-spec") is False + + +# -- PLAN_WORKFLOW structure --------------------------------------------------- + +def test_plan_workflow_structure(): + wf = PLAN_WORKFLOW + assert wf.name == "plan" + assert "intake" in wf.available_phases + assert "plan-spec" in wf.available_phases + assert "plan-review" in wf.available_phases + assert "execute" in wf.available_phases + assert wf.initial_phase == "intake" + + +def test_plan_workflow_has_phase_descriptions(): + for phase in PLAN_WORKFLOW.available_phases: + assert phase in PLAN_WORKFLOW.phase_descriptions + assert len(PLAN_WORKFLOW.phase_descriptions[phase]) > 0 + + +def test_plan_workflow_has_guidance_for_intake(): + assert "intake" in PLAN_WORKFLOW.phase_guidance + assert len(PLAN_WORKFLOW.phase_guidance["intake"]) > 0 + + +def test_plan_workflow_has_guidance_for_execute(): + assert "execute" in PLAN_WORKFLOW.phase_guidance + assert len(PLAN_WORKFLOW.phase_guidance["execute"]) > 0 + + +# -- MILESTONES_WORKFLOW structure --------------------------------------------- + +def test_milestones_workflow_structure(): + wf = MILESTONES_WORKFLOW + assert wf.name == "milestones" + assert wf.available_phases == ("intake",) + assert wf.initial_phase == "intake" + assert wf.suggested_transitions == {"intake": []} + + +def test_milestones_workflow_has_intake_guidance(): + assert "intake" in MILESTONES_WORKFLOW.phase_guidance + assert len(MILESTONES_WORKFLOW.phase_guidance["intake"]) > 0 + + +# -- Workflow immutability ----------------------------------------------------- + +def test_workflow_frozen(): + """Workflow instances cannot have fields reassigned (frozen=True).""" + with pytest.raises(Exception): # FrozenInstanceError or AttributeError + PLAN_WORKFLOW.name = "mutated" + + +# -- WORKFLOWS registry ------------------------------------------------------- + +def test_workflows_registry_complete(): + assert "plan" in WORKFLOWS + assert "milestones" in WORKFLOWS + + +def test_workflows_registry_values_are_workflow_instances(): + for name, wf in WORKFLOWS.items(): + assert isinstance(wf, Workflow) + assert wf.name == name From fd0f3b6210b2b22ef083b15cb307c86bd72a71a8 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 15:19:06 +0700 Subject: [PATCH 304/412] refactor: remove temporal contamination from code comments Remove design-decision codes (D1, D8), 'Renamed from', 'Replaces the T6 stub', 'collapsed from 3', and dead path reference from module comments. --- koan/phases/brief_writer.py | 5 ++--- koan/phases/format_step.py | 1 - koan/phases/intake.py | 6 +++--- koan/run_state.py | 1 - koan/subagent.py | 1 - 5 files changed, 5 insertions(+), 9 deletions(-) diff --git a/koan/phases/brief_writer.py b/koan/phases/brief_writer.py index f93efd2..51e531e 100644 --- a/koan/phases/brief_writer.py +++ b/koan/phases/brief_writer.py @@ -1,10 +1,9 @@ -# Brief-writer phase -- 2-step workflow (collapsed from 3). +# Brief-writer phase -- 2-step workflow. # # Step 1 (Read) -- read landscape.md; build mental model; no writes # Step 2 (Draft) -- write brief.md; artifact available in panel # -# Review gate removed (D1): step 2 completes unconditionally. -# SCOPE="legacy": part of the old epic pipeline, not used by any active workflow. +# SCOPE="legacy": not used by any active workflow. from __future__ import annotations diff --git a/koan/phases/format_step.py b/koan/phases/format_step.py index 8ae5bb3..9465163 100644 --- a/koan/phases/format_step.py +++ b/koan/phases/format_step.py @@ -1,5 +1,4 @@ # Step prompt assembly -- formats StepGuidance into the string returned to the LLM. -# Python port of src/planner/lib/step.ts formatStep(). from __future__ import annotations diff --git a/koan/phases/intake.py b/koan/phases/intake.py index c48ac10..c551e5b 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -4,8 +4,8 @@ # Step 2 (Deepen) -- process scout results, verify, deepen through dialogue # Step 3 (Write) -- write landscape.md # -# Review gate removed (D1): step 3 completes unconditionally. -# Prompt injection model (D8): workflow scope framing appears at top of step 1. +# Step 3 completes unconditionally -- no review gate. +# Workflow scope framing (phase_instructions) appears at the top of step 1 guidance. from __future__ import annotations @@ -98,7 +98,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: project_dir = ctx.project_dir or "" lines = [] - # Workflow scope framing appears at the top if injected (D8) + # Workflow scope framing (phase_instructions) appears at the top of step 1 if ctx.phase_instructions: lines.extend([ "## Workflow Context", diff --git a/koan/run_state.py b/koan/run_state.py index abcac81..1c2ccf2 100644 --- a/koan/run_state.py +++ b/koan/run_state.py @@ -1,6 +1,5 @@ # On-disk state I/O for run and story state files. # All JSON writes use atomic tmp+rename to prevent partial reads. -# Renamed from koan/epic_state.py: all "epic" terminology replaced with "run". from __future__ import annotations diff --git a/koan/subagent.py b/koan/subagent.py index 7ddf6fb..3a47c82 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -1,5 +1,4 @@ # Subagent manager -- spawn, monitor, and cleanup subagent processes. -# Replaces the T6 stub in driver.py with a complete lifecycle implementation. from __future__ import annotations From e696c865d56e10279d89a9e81c2e8964dae75ae8 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 15:19:16 +0700 Subject: [PATCH 305/412] refactor: fix stale epic references in code and tests Rename leftover 'epic' variable names, path strings, test method names, and comments that the mechanical rename commit missed. Standardize permission error message format. --- koan/lib/permissions.py | 2 +- koan/web/app.py | 2 +- tests/test_mcp_check_or_raise.py | 8 +++---- tests/test_permissions.py | 40 ++++++++++++++++---------------- tests/test_web_flows.py | 20 ++++++++-------- 5 files changed, 36 insertions(+), 36 deletions(-) diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index 18586ab..2c4cd1c 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -157,7 +157,7 @@ def _check_orchestrator_permission( if tool_name == "koan_request_executor": if phase in ("execution", "execute"): return {"allowed": True, "reason": None} - return {"allowed": False, "reason": f"koan_request_executor is only available during execution phases"} + return {"allowed": False, "reason": f"koan_request_executor is not available in phase '{phase}'"} # Story management tools — legacy execution phase only if tool_name in _ORCHESTRATOR_STORY_TOOLS: diff --git a/koan/web/app.py b/koan/web/app.py index 8fb9614..ca6ee0a 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -322,7 +322,7 @@ async def api_start_run(r: Request) -> Response: st.phase_complete_future.set_result(False) st.phase_complete_future = None - # Create epic directory + # Create run directory run_id = f"{int(time.time())}-{uuid.uuid4().hex[:8]}" run_dir = Path.home() / ".koan" / "runs" / run_id run_dir.mkdir(parents=True, exist_ok=True) diff --git a/tests/test_mcp_check_or_raise.py b/tests/test_mcp_check_or_raise.py index 03e1175..3a9ca4b 100644 --- a/tests/test_mcp_check_or_raise.py +++ b/tests/test_mcp_check_or_raise.py @@ -30,15 +30,15 @@ def _make_agent( class TestPhaseCtxRunDir: def test_phase_ctx_run_dir_enforced(self): - ctx = PhaseContext(run_dir="/tmp/epic", subagent_dir="/tmp/sub") + ctx = PhaseContext(run_dir="/tmp/run", subagent_dir="/tmp/sub") agent = _make_agent(phase_ctx=ctx) with pytest.raises(ToolError, match="permission_denied"): _check_or_raise(agent, "write", {"path": "/home/evil.sh"}) def test_phase_ctx_run_dir_allows_inside(self): - ctx = PhaseContext(run_dir="/tmp/epic", subagent_dir="/tmp/sub") + ctx = PhaseContext(run_dir="/tmp/run", subagent_dir="/tmp/sub") agent = _make_agent(phase_ctx=ctx) - _check_or_raise(agent, "write", {"path": "/tmp/epic/foo.md"}) + _check_or_raise(agent, "write", {"path": "/tmp/run/foo.md"}) # -- No phase_ctx ------------------------------------------------------------- @@ -49,7 +49,7 @@ def test_no_phase_ctx_no_crash(self): _check_or_raise(agent, "write") def test_agent_run_dir_fallback(self): - agent = _make_agent(run_dir="/tmp/epic") + agent = _make_agent(run_dir="/tmp/run") with pytest.raises(ToolError, match="permission_denied"): _check_or_raise(agent, "write", {"path": "/home/evil.sh"}) diff --git a/tests/test_permissions.py b/tests/test_permissions.py index db7fb49..570dc5b 100644 --- a/tests/test_permissions.py +++ b/tests/test_permissions.py @@ -198,59 +198,59 @@ def test_role_tool(self, role, tool, expected): class TestPathScoping: def setup_method(self): - self.epic = "/tmp/epic" + self.run_dir = "/tmp/run" - def test_write_inside_epic_allowed(self): + def test_write_inside_run_dir_allowed(self): r = check_permission( "intake", "write", - run_dir=self.epic, - tool_args={"path": "/tmp/epic/foo.md"}, + run_dir=self.run_dir, + tool_args={"path": "/tmp/run/foo.md"}, current_step=2, ) assert r["allowed"] - def test_write_outside_epic_denied(self): + def test_write_outside_run_dir_denied(self): r = check_permission( "intake", "write", - run_dir=self.epic, + run_dir=self.run_dir, tool_args={"path": "/home/user/evil.sh"}, current_step=2, ) assert not r["allowed"] assert "outside run directory" in r["reason"] - def test_edit_outside_epic_denied(self): + def test_edit_outside_run_dir_denied(self): r = check_permission( "planner", "edit", - run_dir=self.epic, + run_dir=self.run_dir, tool_args={"path": "/etc/passwd"}, current_step=2, ) assert not r["allowed"] - def test_write_at_epic_root_allowed(self): + def test_write_at_run_dir_root_allowed(self): r = check_permission( "intake", "write", - run_dir=self.epic, - tool_args={"path": "/tmp/epic"}, + run_dir=self.run_dir, + tool_args={"path": "/tmp/run"}, current_step=2, ) assert r["allowed"] - def test_orchestrator_write_inside_epic_allowed(self): + def test_orchestrator_write_inside_run_dir_allowed(self): r = check_permission( "orchestrator", "write", - run_dir=self.epic, - tool_args={"path": "/tmp/epic/brief.md"}, + run_dir=self.run_dir, + tool_args={"path": "/tmp/run/brief.md"}, current_phase="brief-generation", current_step=2, ) assert r["allowed"] - def test_orchestrator_write_outside_epic_denied(self): + def test_orchestrator_write_outside_run_dir_denied(self): r = check_permission( "orchestrator", "write", - run_dir=self.epic, + run_dir=self.run_dir, tool_args={"path": "/home/user/evil.sh"}, current_phase="intake", current_step=2, @@ -262,10 +262,10 @@ def test_orchestrator_write_outside_epic_denied(self): # -- Executor unrestricted write ----------------------------------------------- class TestExecutorUnrestricted: - def test_write_outside_epic_allowed(self): + def test_write_outside_run_dir_allowed(self): r = check_permission( "executor", "write", - run_dir="/tmp/epic", + run_dir="/tmp/run", tool_args={"path": "/home/user/code.py"}, current_step=2, ) @@ -282,7 +282,7 @@ def test_no_run_dir_allows_write(self): def test_no_path_arg_allows_write(self): r = check_permission( "intake", "write", - run_dir="/tmp/epic", + run_dir="/tmp/run", tool_args={"content": "hello"}, current_step=2, ) @@ -291,7 +291,7 @@ def test_no_path_arg_allows_write(self): def test_no_tool_args_allows_write(self): r = check_permission( "intake", "write", - run_dir="/tmp/epic", + run_dir="/tmp/run", current_step=2, ) assert r["allowed"] diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index 258c675..b5651a2 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -215,9 +215,9 @@ def test_start_run_rejects_unknown_installation_alias(client, app_state): def test_artifact_listing(client, app_state): with tempfile.TemporaryDirectory() as tmp: - epic = Path(tmp) - (epic / "landscape.md").write_text("# Landscape\n", "utf-8") - app_state.run_dir = str(epic) + run_dir = Path(tmp) + (run_dir / "landscape.md").write_text("# Landscape\n", "utf-8") + app_state.run_dir = str(run_dir) app_state.start_event.set() resp = client.get("/api/artifacts") @@ -229,9 +229,9 @@ def test_artifact_listing(client, app_state): def test_artifact_content(client, app_state): with tempfile.TemporaryDirectory() as tmp: - epic = Path(tmp) - (epic / "landscape.md").write_text("# Hello\n", "utf-8") - app_state.run_dir = str(epic) + run_dir = Path(tmp) + (run_dir / "landscape.md").write_text("# Hello\n", "utf-8") + app_state.run_dir = str(run_dir) app_state.start_event.set() resp = client.get("/api/artifacts/landscape.md") @@ -243,9 +243,9 @@ def test_artifact_content(client, app_state): def test_path_traversal_blocked(client, app_state): with tempfile.TemporaryDirectory() as tmp: - epic = Path(tmp) - epic.mkdir(exist_ok=True) - app_state.run_dir = str(epic) + run_dir = Path(tmp) + run_dir.mkdir(exist_ok=True) + app_state.run_dir = str(run_dir) app_state.start_event.set() # URL-normalized traversal (../) is resolved before routing and hits the SPA fallback. @@ -441,7 +441,7 @@ def test_live_page_when_running(client, app_state): # After SPA migration, GET / always returns the SPA entry point. # The React app reads store state client-side to render the live view. app_state.start_event.set() - app_state.run_dir = "/tmp/fake-epic" + app_state.run_dir = "/tmp/fake-run" app_state.phase = "intake" resp = client.get("/") From bb16d3bc9942093f14e17a383ec4f3e6ec9faeae Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 15:19:27 +0700 Subject: [PATCH 306/412] refactor: add SCOPE field to PhaseModule protocol and reorganize registry Add SCOPE to PhaseModule Protocol class. Reorganize PHASE_GUIDANCE_MAP into General / Plan / Legacy sections. Move misplaced 'from typing import Any' to top-of-file import block. --- koan/phases/__init__.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index 9ff5dce..6644fb5 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -7,7 +7,7 @@ from __future__ import annotations from dataclasses import dataclass, field -from typing import Protocol, runtime_checkable +from typing import Any, Protocol, runtime_checkable @dataclass @@ -40,6 +40,7 @@ class PhaseContext: @runtime_checkable class PhaseModule(Protocol): ROLE: str + SCOPE: str TOTAL_STEPS: int SYSTEM_PROMPT: str @@ -96,8 +97,6 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> plan_review, plan_spec, ) -from typing import Any - PHASE_MODULE_MAP: dict[str, Any] = { "intake": intake, "scout": scout, @@ -111,8 +110,13 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> # Used by koan_set_phase to load the module for the new phase. PHASE_GUIDANCE_MAP: dict[str, Any] = { - # Legacy workflow phases (dead code — no active workflow uses these) - "intake": intake, + # General-purpose phases (reusable by any workflow) + "intake": intake, + "execute": execute_phase, + # Plan workflow phases (SCOPE="plan") + "plan-spec": plan_spec, + "plan-review": plan_review, + # Legacy phases (SCOPE="legacy" — dead code, available for future workflows) "brief-generation": brief_writer, "core-flows": core_flows, "tech-plan": planner, @@ -120,8 +124,4 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> "cross-artifact-validation": cross_artifact_validation, "execution": executor, "implementation-validation": cross_artifact_validation, - # Plan workflow phases - "plan-spec": plan_spec, - "plan-review": plan_review, - "execute": execute_phase, } From e3006d89c2a1cd92faae824c7c05f9eb80231589 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 15:19:37 +0700 Subject: [PATCH 307/412] refactor: update legacy phase prompts from epic to run terminology Replace 'epic directory', 'epic artifacts', and 'beginning an epic run' with 'run directory', 'run artifacts', and 'beginning an execution run' in orchestrator, core_flows, and ticket_breakdown prompt text. --- koan/phases/core_flows.py | 4 ++-- koan/phases/orchestrator.py | 10 +++++----- koan/phases/ticket_breakdown.py | 6 +++--- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/koan/phases/core_flows.py b/koan/phases/core_flows.py index 011930c..ef6ffca 100644 --- a/koan/phases/core_flows.py +++ b/koan/phases/core_flows.py @@ -31,7 +31,7 @@ "\n" "## Output\n" "\n" - "One file: **core-flows.md** in the epic directory.\n" + "One file: **core-flows.md** in the run directory.\n" "\n" "## Structure\n" "\n" @@ -55,7 +55,7 @@ "\n" "- All read tools (read, bash, grep, glob, find, ls) -- for reading intake output and codebase.\n" "- `koan_request_scouts` -- to request additional codebase exploration if needed.\n" - "- `write` / `edit` -- for writing output files inside the epic directory.\n" + "- `write` / `edit` -- for writing output files inside the run directory.\n" "- `koan_complete_step` -- to signal step completion." ) diff --git a/koan/phases/orchestrator.py b/koan/phases/orchestrator.py index cb1e599..909c89b 100644 --- a/koan/phases/orchestrator.py +++ b/koan/phases/orchestrator.py @@ -1,7 +1,7 @@ # Orchestrator phase -- dynamic step count. # # Pre-execution (2 steps): -# Step 1 (Dependency Analysis) -- read epic artifacts, build dependency model +# Step 1 (Dependency Analysis) -- read run artifacts, build dependency model # Step 2 (Story Selection) -- select the first story for execution # # Post-execution (4 steps): @@ -61,14 +61,14 @@ "\n" "## Tools available\n" "\n" - "- All read tools (read, bash, grep, glob, find, ls) -- for reading epic artifacts and running verification checks.\n" + "- All read tools (read, bash, grep, glob, find, ls) -- for reading run artifacts and running verification checks.\n" "- `koan_select_story` -- to declare which story should execute next.\n" "- `koan_complete_story` -- to mark a story as successfully verified and completed.\n" "- `koan_retry_story` -- to send a story back to the executor with a detailed failure summary.\n" "- `koan_skip_story` -- to skip a story that is superseded or no longer needed.\n" "- `koan_ask_question` -- to ask the human a targeted question when judgment is genuinely ambiguous.\n" "- `koan_complete_step` -- to signal step completion with your findings.\n" - "- `write` / `edit` -- for updating artifact files inside the epic directory only.\n" + "- `write` / `edit` -- for updating artifact files inside the run directory only.\n" "- `bash` -- for running verification commands.\n" "\n" "## The [autonomous] marker\n" @@ -120,9 +120,9 @@ def _pre_step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: return StepGuidance( title=PRE_STEP_NAMES[1], instructions=[ - "You are beginning an epic run. Analyze story dependencies and select the first story for execution.", + "You are beginning an execution run. Analyze story dependencies and select the first story for execution.", "", - "Read the epic artifacts to understand the full scope of work and story dependencies.", + "Read the run artifacts to understand the full scope of work and story dependencies.", "", "## What to read", "", diff --git a/koan/phases/ticket_breakdown.py b/koan/phases/ticket_breakdown.py index fe72357..ddc7f28 100644 --- a/koan/phases/ticket_breakdown.py +++ b/koan/phases/ticket_breakdown.py @@ -1,6 +1,6 @@ # Ticket-breakdown phase -- 2-step workflow. # -# Step 1 (Analysis) -- read epic artifacts; understand scope and dependencies +# Step 1 (Analysis) -- read run artifacts; understand scope and dependencies # Step 2 (Breakdown) -- generate story-sized implementation tickets # # New phase with dedicated "ticket-breakdown" role. @@ -46,7 +46,7 @@ "\n" "## Output files\n" "\n" - "You write the following files, all inside the epic directory:\n" + "You write the following files, all inside the run directory:\n" "\n" "1. **epic.md** -- overview of the full scope and the story list with sequencing rationale.\n" "2. **stories/{story-id}/story.md** -- one file per story with title, goal, scope, and dependencies.\n" @@ -64,7 +64,7 @@ "\n" "- All read tools (read, bash, grep, glob, find, ls) -- for reading upstream artifacts.\n" "- `koan_request_scouts` -- to request additional codebase exploration if needed.\n" - "- `write` / `edit` -- for writing output files inside the epic directory.\n" + "- `write` / `edit` -- for writing output files inside the run directory.\n" "- `koan_complete_step` -- to signal step completion." ) From 75737eae86bb8db7360e45b3de129dcac7005aaa Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 15:19:50 +0700 Subject: [PATCH 308/412] docs: update documentation for workflow system Rewrite all docs to reflect the workflow-based architecture: run_dir, WorkflowPhase, koan_request_executor, workflow selection, phase boundary behavior. Remove artifact review and epic-brief docs. Update AGENTS.md phase permission table, intake-loop phase boundary section, IPC interaction types, projection model, and state docs. Remove dead links from README. --- AGENTS.md | 43 ++++++---- README.md | 105 ++++++++++++++----------- docs/architecture.md | 85 +++++++++++++++++--- docs/artifact-review.md | 170 ---------------------------------------- docs/epic-brief.md | 125 ----------------------------- docs/intake-loop.md | 32 +++----- docs/ipc.md | 77 +++++++++--------- docs/projections.md | 54 ++++++------- docs/state.md | 96 +++++++++-------------- docs/subagents.md | 71 ++++++++++++----- 10 files changed, 320 insertions(+), 538 deletions(-) delete mode 100644 docs/artifact-review.md delete mode 100644 docs/epic-brief.md diff --git a/AGENTS.md b/AGENTS.md index d7778c2..a5171a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,14 +6,12 @@ Spoke documents: - [docs/subagents.md](docs/subagents.md) -- spawn lifecycle, task manifest, step-first workflow, permissions - [docs/ipc.md](docs/ipc.md) -- HTTP MCP tool calls, blocking interactions, scout spawning, phase-boundary blocking -- [docs/state.md](docs/state.md) -- driver/LLM boundary, epic and story state, orchestrator state -- [docs/intake-loop.md](docs/intake-loop.md) -- three-step intake design, review gate, prompt engineering +- [docs/state.md](docs/state.md) -- driver/LLM boundary, run state, orchestrator state +- [docs/intake-loop.md](docs/intake-loop.md) -- three-step intake design, prompt engineering - [docs/projections.md](docs/projections.md) -- versioned event log, fold function, projection shape, SSE protocol, version-negotiated catch-up -- [docs/epic-brief.md](docs/epic-brief.md) -- brief artifact, brief-generation phase, downstream references -- [docs/artifact-review.md](docs/artifact-review.md) -- artifact review protocol, review loop, reusability - [docs/token-streaming.md](docs/token-streaming.md) -- runner stdout parsing, SSE delta path -**Workflow phases:** `intake` -> `brief-generation` -> `core-flows` -> `tech-plan` -> `ticket-breakdown` -> `cross-artifact-validation` -> `execution` -> `implementation-validation` -> `completed` +**Workflow types:** `plan` (intake → plan-spec → plan-review → execute) · `milestones` (stub: intake only) --- @@ -47,7 +45,7 @@ Tool returns: Step 2 instructions (or phase-boundary response) ``` When a phase ends, `koan_complete_step` blocks for a user message and returns -the transition context (user message + valid next phases). The orchestrator +the transition context (user message + suggested next phases). The orchestrator converses, then calls `koan_set_phase` to commit the transition. The step counter resets to 0 on each `koan_set_phase` call, then advances to 1 on the next `koan_complete_step`. Phase-specific role context (`SYSTEM_PROMPT`) is @@ -57,8 +55,8 @@ Step progression is normally linear within a phase, but phase modules may override `get_next_step()` to implement non-linear flows. See [docs/intake-loop.md](docs/intake-loop.md). -Planner, executor, and scout subagents are still separate processes spawned by -the orchestrator via `koan_spawn_executor` and `koan_request_scouts`. +Executor subagents are spawned by the orchestrator via `koan_request_executor`. +Scout subagents are spawned via `koan_request_scouts`. ## 3. Driver Determinism (partially relaxed) @@ -68,7 +66,7 @@ the driver's routing loop. The driver still: - Validates every phase transition (`is_valid_transition()` in the tool handler) -- Updates `epic-state.json` atomically +- Updates `run-state.json` atomically - Emits projection events - Enforces the permission fence @@ -76,12 +74,17 @@ The driver does **not** decide which phase runs next. Invalid phase strings raise `ToolError`; valid transitions are committed. All routing decisions flow through typed tool parameters, not free text. +`is_valid_transition(workflow, from_phase, to_phase)` checks that `to_phase` is +in the active workflow's `available_phases` and is not equal to `from_phase`. +Any phase in the workflow is reachable from any other — there is no DAG of +required successors. + ## 4. Default-Deny Permissions Every tool call passes through a role-based permission fence. Unknown roles and tools are blocked. The orchestrator role uses **phase-aware permissions**: available tools vary by `current_phase`. Planning-phase write access is -path-scoped to the epic directory. +path-scoped to the run directory. The fence also supports step-level gating: `write` and `edit` are blocked during brief-generation step 1 (the read step). @@ -93,11 +96,10 @@ during brief-generation step 1 (the read step). | `koan_complete_step` | All phases | | `koan_set_phase` | All phases (blocked mid-story during execution) | | `koan_ask_question` | All phases | -| `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation` | -| `koan_review_artifact` | `intake`, `brief-generation`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `implementation-validation` | -| `koan_spawn_executor` | `execution` only | +| `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `plan-spec`, `plan-review` | +| `koan_request_executor` | `execution`, `execute` | | `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | `execution` only | -| `write`, `edit` (epic_dir scoped) | All phases except `brief-generation` step 1 | +| `write`, `edit` (run_dir scoped) | All phases except `brief-generation` step 1 | | `bash` | `execution`, `implementation-validation` | ## 5. Need-to-Know Prompts @@ -107,11 +109,15 @@ only). Phase-specific role context arrives via step 1 guidance after `koan_set_phase` is called -- the orchestrator doesn't know its next role until `koan_complete_step` tells it. +Each workflow provides a `phase_guidance` injection for the phases it defines. +This injection appears at the top of step 1 guidance and sets workflow-specific +posture (investigation depth, question aggressiveness, what to hand off to the +executor). See [docs/architecture.md](docs/architecture.md) for the injection contract. + ## 6. Directory-as-Contract -The orchestrator has one subagent directory for the entire run. Planner, -executor, and scout subagents each get their own directory per the standard -contract: +The orchestrator has one subagent directory for the entire run. Executor and +scout subagents each get their own directory per the standard contract: | File | Writer | Reader | Purpose | | -------------- | ------------------------- | ------------------------------ | ------------------ | @@ -123,3 +129,6 @@ The `mcp_url` field in `task.json` tells the child where to connect for tool calls. No structured configuration flows through CLI flags. The spawn command carries the directory path and the MCP config pointing at the driver's HTTP endpoint. + +The `task.json` for every subagent includes `run_dir` — the path to the current +workflow run directory (`~/.koan/runs/<id>/`). diff --git a/README.md b/README.md index 93d00c2..14e4a14 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Koan -Koan is a deterministic planning pipeline that takes a conversation describing a -coding task and produces working code -- through a structured sequence of -isolated LLM subagents, each with a narrow, auditable responsibility. +Koan is a workflow system for coding tasks. A single Python process hosts a web +dashboard and MCP tool endpoint; the user selects a workflow type, describes a +task, and the system runs a sequence of LLM subagents to plan and implement it. ## Setup @@ -13,19 +13,26 @@ uv run koan ## How it works +At startup, the user selects a workflow type and describes the task. Koan spawns +a long-lived orchestrator LLM process that runs the entire workflow via MCP tool +calls. At each phase boundary, the orchestrator pauses, summarizes progress, and +asks the user where to go next. + +### Plan workflow + ``` -Conversation - -> Intake (confidence-gated investigation loop) - -> Brief generation (distill landscape into product brief) - -> Core flows (user journeys, sequence diagrams) - -> Tech plan (technical architecture) - -> Ticket breakdown (story-sized implementation tickets) - -> Cross-artifact validation (consistency check) - -> Execution (implement tickets) - -> Implementation validation (post-execution review) - -> Done +intake — explore codebase, ask clarifying questions, write landscape.md +plan-spec — read landscape.md, write plan.md (technical implementation plan) +plan-review — read landscape.md + plan.md, evaluate quality, report findings +execute — spawn executor agent with plan.md; implements the changes ``` +### Milestones workflow + +Stub — runs intake only, then reports the workflow is not yet fully implemented. + +--- + A single Python process (`koan/driver.py`) runs a Starlette HTTP server that hosts both the web dashboard and an MCP tool endpoint. Subagents are CLI processes (`claude`, `codex`, or `gemini`) that connect to @@ -33,16 +40,13 @@ processes (`claude`, `codex`, or `gemini`) that connect to koan tools. The driver reads JSON state and exit codes; it never parses LLM output. -## Phases +## Roles -| Phase | Role | What it does | -| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ | -| **Intake** | `intake` | Reads the conversation, scouts the codebase, asks clarifying questions. Iterates until confident. Writes `landscape.md`. | -| **Scout** | `scout` | Narrow codebase investigator. Spawned in parallel by intake, decomposer, and planner via `koan_request_scouts`. | -| **Brief writer** | `brief-writer` | Distills `landscape.md` into `brief.md`. User reviews via artifact review. | -| **Orchestrator** | `orchestrator` | Selects the next story, verifies execution results, routes to retry/done/next. | -| **Planner** | `planner` | Reads a story sketch, writes a step-by-step implementation plan and code context file. | -| **Executor** | `executor` | Follows the plan, modifies the codebase, reports what changed. | +| Role | What it does | +|------|-------------| +| **orchestrator** | Runs the entire workflow in one long-lived process. Calls `koan_set_phase` to advance phases. | +| **scout** | Narrow codebase investigator. Spawned in parallel via `koan_request_scouts`. Writes `findings.md`. | +| **executor** | Reads artifacts and instructions from `task.json`, implements code changes in one pass. | ## Web Dashboard @@ -52,8 +56,8 @@ execution. The dashboard provides: - **Activity feed** -- real-time tool calls, scout dispatches, thinking traces - **Agent monitor** -- status, token counts, and recent actions for each running subagent -- **User interaction** -- question forms (intake clarifications), review gates - (story approval), model configuration +- **Artifacts panel** -- markdown files written during the run (landscape.md, plan.md) +- **User interaction** -- question forms (clarifications), chat for phase-boundary direction The dashboard uses Server-Sent Events for real-time updates. SSE events are pushed directly from in-process state transitions and tool handlers. @@ -70,18 +74,22 @@ spawn command carries the directory path and the MCP endpoint URL. **Default-deny permissions.** Every tool call passes through a permission fence. Roles cannot use tools outside their scope. Planning roles can only -write inside the epic directory. The intake phase's Extract step additionally -blocks scouting and writing tools at the mechanism level. +write inside the run directory. -**Driver determinism.** The driver (`koan/driver.py`) reads JSON and exit codes, -applies routing rules, and spawns the next subagent. It never parses markdown -or adapts to LLM behavior. Routing decisions are deterministic. +**Driver determinism.** The driver reads JSON and exit codes, validates phase +transitions against the active workflow, and spawns subagents. It never parses +markdown or adapts to LLM behavior. Routing decisions are deterministic. **HTTP MCP.** Subagents connect to the driver's MCP endpoint at `/mcp?agent_id={id}`. Tool calls arrive as HTTP requests; the driver looks up the agent's state by `agent_id` in an in-process registry and handles the call directly. No separate MCP server processes, no file-based IPC polling. +**Workflow-based phase transitions.** Phase transitions are validated against +the active workflow's `available_phases`. Any phase in the workflow is reachable +from any other. Suggested transitions guide the orchestrator's boundary response +but do not restrict the user. + ## Configuration Model tiers and scout concurrency are configured via the web UI at pipeline @@ -89,33 +97,38 @@ start, then saved to `~/.koan/config.json`: ```json { - "modelTiers": { - "strong": "claude-opus-4-5", - "standard": "claude-sonnet-4-5", - "cheap": "claude-haiku-4-5" - }, - "scoutConcurrency": 4 + "agentInstallations": [ + { "alias": "claude-sonnet", "runnerType": "claude", "binary": "claude", "extraArgs": [] } + ], + "profiles": [ + { + "name": "balanced", + "tiers": { + "strong": { "runnerType": "claude", "model": "claude-sonnet-4-5", "thinking": "disabled" }, + "standard": { "runnerType": "claude", "model": "claude-sonnet-4-5", "thinking": "disabled" }, + "cheap": { "runnerType": "claude", "model": "claude-haiku-4-5", "thinking": "disabled" } + } + } + ], + "activeProfile": "balanced", + "scoutConcurrency": 8 } ``` -Roles map to tiers: intake/decomposer/orchestrator/planner -> strong, -executor -> standard, scout -> cheap. +Roles map to tiers: orchestrator → strong, executor → standard, scout → cheap. ## Architecture Documentation - **[docs/architecture.md](./docs/architecture.md)** -- core invariants, - design principles, pitfalls + design principles, workflow system, pitfalls - **[docs/subagents.md](./docs/subagents.md)** -- spawn lifecycle, step-first workflow, permissions, model tiers - **[docs/ipc.md](./docs/ipc.md)** -- HTTP MCP inter-process communication, blocking tool calls -- **[docs/state.md](./docs/state.md)** -- driver state machine, story lifecycle, - routing rules -- **[docs/intake-loop.md](./docs/intake-loop.md)** -- confidence-gated intake - loop, prompt engineering principles -- **[docs/epic-brief.md](./docs/epic-brief.md)** -- brief artifact, brief-writer - subagent, downstream references -- **[docs/artifact-review.md](./docs/artifact-review.md)** -- artifact review - protocol, review loop, reusability +- **[docs/state.md](./docs/state.md)** -- run state, driver state, routing +- **[docs/intake-loop.md](./docs/intake-loop.md)** -- three-step intake design, + prompt engineering principles +- **[docs/projections.md](./docs/projections.md)** -- versioned event log, + fold function, SSE protocol - **[docs/token-streaming.md](./docs/token-streaming.md)** -- runner stdout parsing, SSE delta path diff --git a/docs/architecture.md b/docs/architecture.md index 15d88c3..cbd6f2a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -12,13 +12,10 @@ principles, and pitfalls that govern the codebase. scout spawning, phase-boundary blocking, chat message delivery - [Token Streaming](./token-streaming.md) -- runner stdout parsing, SSE delta path - [State & Driver](./state.md) -- the driver/LLM boundary, JSON vs markdown - ownership, epic and story state, orchestrator state + ownership, run state, orchestrator state - [Projections](./projections.md) -- versioned event log, pure fold, JSON Patch protocol, projection model, camelCase wire format -- [Intake Loop](./intake-loop.md) -- three-step intake design, review gate, - prompt engineering principles -- [Epic Brief](./epic-brief.md) -- brief artifact, brief-generation phase, downstream references -- [Artifact Review](./artifact-review.md) -- artifact review protocol, review loop, reusability +- [Intake Loop](./intake-loop.md) -- three-step intake design, prompt engineering principles --- @@ -81,16 +78,23 @@ Three reinforcement mechanisms make this robust across model capability levels: The driver (`koan/driver.py`) spawns the orchestrator and awaits its exit. Phase routing is driven by the orchestrator via `koan_set_phase` rather than the driver's routing loop. The driver still validates every transition -(`is_valid_transition()` in the tool handler), updates `epic-state.json` +(`is_valid_transition()` in the tool handler), updates `run-state.json` atomically, emits projection events, and enforces the permission fence. It never parses free text or makes judgment calls. All routing decisions flow through typed tool parameters. +`is_valid_transition(workflow, from_phase, to_phase)` validates that `to_phase` +is a member of the active workflow's `available_phases` and is not equal to +`from_phase`. Any phase in the workflow is reachable from any other — suggested +transitions guide the orchestrator's default recommendations at phase boundaries, +but the user can request any available phase. Invalid phase strings raise +`ToolError`. + ### 4. Default-deny permissions Every tool call passes through a permission fence (`check_permission()` in `koan/lib/permissions.py`). Unknown roles are blocked. Unknown tools are -blocked. Planning roles can only write inside the epic directory. +blocked. Planning roles can only write inside the run directory. The one accepted limitation: `READ_TOOLS` (bash, read, grep, glob, find, ls) are always allowed because distinguishing "read bash" from "write bash" is @@ -111,6 +115,23 @@ established the `koan_complete_step` calling pattern. Weaker models produce text output and exit without entering the workflow. Step guidance is delivered exclusively through `koan_complete_step` return values. +**Phase guidance injection.** Each workflow provides a `phase_guidance` dict +mapping phase names to scope-framing text. When the orchestrator calls +`koan_set_phase(phase)`, the workflow's guidance for that phase is stored in +`PhaseContext.phase_instructions`. The step 1 response renders this injection +at the top of the guidance, before procedural instructions, so scope framing +reaches the LLM before it reads task details. + +The injection contract every `phase_guidance` entry must cover: + +| Section | Purpose | +|---------|---------| +| **Scope** | What kind of task this workflow targets | +| **Downstream consumer** | What phase reads the output, what detail level it needs | +| **Investigation posture** | Direct reading vs. scouts, typical scout count | +| **Question posture** | How aggressively to ask, typical round count | +| **User override** | Always present, always last: "follow their lead" | + ### 6. Directory-as-contract The subagent directory is the **sole interface** between parent and child. @@ -159,6 +180,50 @@ are hard to trace. JSON Patch makes correctness structural: one fold, one source of truth, mechanical application on the client. +--- + +## Workflow System + +### Workflow definitions + +A `Workflow` defines the set of phases available for a run, the initial phase, +and suggested transitions between phases. Two workflows are defined in +`koan/lib/workflows.py`: + +**plan** — intake → plan-spec → plan-review → execute + +| Phase | Role | Steps | Artifact | +|-------|------|-------|---------| +| `intake` | Requirement gathering | 3 (Gather → Deepen → Write) | `landscape.md` | +| `plan-spec` | Technical planning | 2 (Analyze → Write) | `plan.md` | +| `plan-review` | Quality review | 2 (Read → Evaluate) | Chat report only | +| `execute` | Implementation handoff | 2 (Compose → Request) | Code changes via executor | + +**milestones** — stub workflow; runs intake only, then reports the workflow is +not yet fully implemented. + +### Workflow selection + +The user selects a workflow at run start. The selection is stored in +`AppState.workflow` and used throughout the run for: +- Phase transition validation (`is_valid_transition`) +- Phase boundary suggestions (`get_suggested_phases`) +- Phase guidance injection (`workflow.phase_guidance[phase]`) + +### Phase transition validation + +```python +def is_valid_transition(workflow: Workflow, from_phase: str, to_phase: str) -> bool: + return ( + to_phase in workflow.available_phases + and to_phase != from_phase + ) +``` + +At phase boundaries, `format_phase_boundary` renders the suggested next phases +from `workflow.suggested_transitions[current_phase]`. These are recommendations, +not constraints — the user can request any phase in `workflow.available_phases`. + --- ## Atomic Writes @@ -302,11 +367,11 @@ answers -> MCP response). A separate `escalated` status creates a dead routing path -- the driver has nowhere clean to send it without duplicating the ask UI flow. -### Don't add `scouting` as an epic phase +### Don't add `scouting` as a workflow phase Scouts run inside the `koan_request_scouts` tool handler during -intake/decomposer/planner phases, not as a top-level driver phase. Adding -`scouting` to `EpicPhase` would imply a driver state that never exists, +intake/planning phases, not as a top-level driver phase. Adding +`scouting` to `WorkflowPhase` would imply a driver state that never exists, creating dead code paths. ### Don't rely on file existence for scout success diff --git a/docs/artifact-review.md b/docs/artifact-review.md deleted file mode 100644 index f048f7c..0000000 --- a/docs/artifact-review.md +++ /dev/null @@ -1,170 +0,0 @@ -# Artifact Review - -Protocol for presenting a written artifact to the user and collecting feedback. -Used by the brief-writer phase; reusable for any future markdown artifact that -requires a review-revise loop before workflow advancement. - -> Parent doc: [architecture.md](./architecture.md) -> -> IPC model: [ipc.md](./ipc.md) - ---- - -## Overview - -The artifact review protocol pauses subagent execution while the user reads a -rendered markdown artifact and either accepts it or provides revision feedback. -The review loop is LLM-driven: the subagent writes the artifact, calls -`koan_review_artifact`, revises on feedback, and calls the tool again. The -protocol is stateless -- each invocation is a fresh request. - ---- - -## Interaction Model - -When `koan_review_artifact` is called via MCP, the tool handler: - -1. Reads the file at `path` to obtain raw markdown content -2. Creates a `PendingInteraction` with type `"artifact-review"` and an `asyncio.Future` -3. Stores it in `AgentState.pending_tool` -4. Pushes SSE `artifact_review_requested` event to connected browsers -5. Awaits the Future -- the MCP HTTP connection stays open -6. When the user responds (Accept or feedback), the web endpoint resolves the Future -7. Returns feedback string to the LLM as the MCP tool result - -There is no file-based IPC. The entire interaction is in-process via -`asyncio.Future`. - ---- - -## Tool Interface - -**Name:** `koan_review_artifact` - -**Parameters:** - -- `path` (string) -- file path of the artifact to review -- `description` (string, optional) -- context for the reviewer - -**Return values:** - -``` -User feedback: -Accept - ---- or --- - -User feedback: -The goals section needs a latency metric. Constraint #3 is too broad. -``` - -**LLM behavior on response:** - -- `"Accept"` -> call `koan_complete_step` -- Any other text -> revise the artifact, call `koan_review_artifact` again - ---- - -## "Accept" Is Verbatim Text - -When the user clicks "Accept" in the web UI, the feedback string sent to the -subagent is literally `"Accept"`. When the user provides feedback, it is their -typed text. Both cases travel the same code path. - -**Why:** A dedicated `accepted: boolean` field would create two response shapes -and require branching. Uniform text keeps the tool stateless and lets the LLM -decide how to proceed. - ---- - -## Web UI Component - -The artifact review is rendered by the `ArtifactReview.tsx` React component. -The component subscribes to `run.focus` in the Zustand store and -renders when an `artifact_review_requested` event sets it. - -**Layout:** - -``` -+------------------------------------------+ -| Review: <artifact_path> | -| --------------------- | -| +----------------------------------+ | -| | [rendered markdown content] | | -| +----------------------------------+ | -| +----------------------------------+ | -| | Feedback (optional) | | -| +----------------------------------+ | -| [Send Feedback] [Accept] | -+------------------------------------------+ -``` - -**Behavior:** - -- Component renders markdown content client-side -- "Accept" -> `POST /api/artifact-review` with `{ feedback: "Accept" }` -- "Send Feedback" -> `POST /api/artifact-review` with `{ feedback: text }` -- Component unmounts when `artifact_reviewed` event clears `run.focus` - ---- - -## HTTP Endpoint - -**`POST /api/artifact-review`** in `koan/web/interactions.py` - -Validates request parameters and resolves the pending `asyncio.Future` in the -agent's `PendingInteraction`. Returns `{ ok: true }` on success, error on -validation failure or missing pending interaction. - ---- - -## SSE Events - -| Event | Direction | Payload | -| ---------------------------- | ----------------- | -------------------------------------------------------- | -| `artifact_review_requested` | server -> browser | `{ token, path, content, description }` (sets `run.focus`) | -| `artifact_reviewed` | server -> browser | `{ token, ?accepted, ?response, cancelled }` (clears `run.focus`) | - -SSE events are pushed directly from the tool handler. On browser reconnect, -pending reviews are replayed so the user does not lose the review form. - ---- - -## Review Loop - -``` -subagent calls koan_review_artifact({ path: ".../brief.md" }) via MCP - -> MCP endpoint reads brief.md content - -> creates PendingInteraction { type: "artifact-review", future: Future() } - -> pushes SSE `artifact_review_requested` event to browsers - -> awaits Future - -user sees rendered markdown in web UI - -> clicks "Accept" or types feedback - -> POST /api/artifact-review -> resolves Future - -MCP handler returns feedback as tool result - -> subagent receives "User feedback:\n{feedback}" - -if feedback == "Accept": - LLM calls koan_complete_step -> phase advances -else: - LLM revises artifact, calls koan_review_artifact again - (loop repeats with fresh PendingInteraction) -``` - ---- - -## Reusability - -The artifact review mechanism is not epic-brief-specific. Any planning phase -that produces a markdown artifact can use the same pattern: - -1. Write the artifact to the epic directory -2. Call `koan_review_artifact` with the path -3. Process the feedback string: revise and re-invoke, or accept and advance - -Future phases that could use this pattern: core flows document, technical plan, -architecture decision record. Adding a new phase requires only: assigning the -`koan_review_artifact` permission to the new role (in `koan/lib/permissions.py`) -and implementing the review loop in the phase's step guidance. diff --git a/docs/epic-brief.md b/docs/epic-brief.md deleted file mode 100644 index d193b56..0000000 --- a/docs/epic-brief.md +++ /dev/null @@ -1,125 +0,0 @@ -# Epic Brief - -The epic brief is a compact product-level artifact produced between intake and -core-flows. It captures the **what and why** of an epic and serves as a -correctness anchor for all downstream phases. - -> Related: [artifact-review.md](./artifact-review.md) -- the mechanism used -> to present brief.md for human review before pipeline advancement. - ---- - -## What It Captures - -| Section | Content | -| --------------------- | ----------------------------------------------------------------------- | -| **Summary** | 3-8 sentences: what this epic is about | -| **Context & Problem** | Who is affected, where in the product, what the current pain is | -| **Goals** | Numbered list of measurable objectives | -| **Constraints** | Hard constraints from landscape.md (technical, timeline, compatibility) | - -**Size constraint:** Under 50 lines. The brief is consulted by the core-flows -phase, planner, and orchestrator on every pipeline run -- compact size ensures -it remains a quick reference rather than a specification to read in full. - -## What It Excludes - -- UI flows and wireframes -- Technical architecture decisions -- Implementation details -- Story decomposition - -These belong in later artifacts (story sketches, `plan/context.md`). - ---- - -## Pipeline Position - -``` -intake -> brief-generation -> core-flows -> tech-plan -> ticket-breakdown -> cross-artifact-validation -> execution -> implementation-validation -``` - -The brief sits between intake and core-flows: - -- **After intake:** `landscape.md` is complete. The brief distills this into a - problem statement. -- **Before core-flows:** Downstream phases read `brief.md` to scope work - against stated goals and constraints. - ---- - -## Brief-Generation Phase - -The orchestrator handles the brief-generation phase using step guidance from -`koan/phases/brief_writer.py`. Model tier for the orchestrator: `"strong"`. - -### Step Progression - -``` -Boot -> koan_complete_step (step 0 -> 1) - -Step 1 (Read): - Read landscape.md. Build mental model. No file writes allowed. - -Step 2 (Draft & Review): - Write brief.md. Call koan_review_artifact. - If feedback -> revise brief.md, call koan_review_artifact again. - If "Accept" -> call koan_complete_step. - [Loops within step 2 until user accepts] - -Step 3 (Finalize): - Phase complete. -``` - -**Review gate:** `validate_step_completion(step=2)` in -`koan/phases/brief_writer.py` requires at least one `koan_review_artifact` call -before `koan_complete_step` is allowed. - -### Permissions during brief-generation - -During `brief-generation`, the orchestrator has access to `koan_review_artifact`, -`write`, and `edit` (path-scoped to epic directory). `koan_request_scouts` and -`koan_ask_question` are not used — all codebase context arrives via -`landscape.md`. Write/edit access is blocked in step 1 (the Read step). - ---- - -## Downstream References - -All planning phases are prompted to read `brief.md` before acting: - -| Phase | Why | -| ------------------------------- | ----------------------------------------------------------------------- | -| **Core-flows and later phases** | Scope work against brief goals; must not invent scope absent from brief | -| **Planner** | Plans must serve product-level goals and respect constraints | -| **Orchestrator** | Validates story completion against product goals | - -The executor reads `plan/context.md` (story-level context) and does not -consult the epic brief directly. - ---- - -## Design Rationale - -### Artifact cascade - -Each phase produces an artifact that downstream phases consult: - -``` -landscape.md (intake synthesis) - -> brief.md (problem + goals + constraints) - -> core-flows.md (user journeys) - -> story.md x N (ticket-breakdown) - -> plan/context.md x N (story plans) -``` - -Each artifact is progressively more specific. - -### Why a separate brief phase - -A merged "brief + core-flows" agent would violate the single-cognitive-goal -principle. Separating them: - -- Forces the brief to be reviewed and accepted before core-flows begins -- Prevents downstream phases from anchoring on their own interpretation of scope -- Creates a reviewable artifact that can be corrected before downstream work starts diff --git a/docs/intake-loop.md b/docs/intake-loop.md index 57b4ebe..11d94f3 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -27,10 +27,10 @@ user questions, then write `landscape.md`. | ---- | -------- | ---- | --------------------------------------------------------------------------------- | | 1 | Gather | 1x | Read conversation, open obvious files (≤5), dispatch 3-5 scouts. | | 2 | Deepen | 1x | Process scout results, verify by reading files, deepen understanding through iterative dialogue. | -| 3 | Write | 1x | Write `landscape.md`. Review gate: calls `koan_review_artifact` before completing. | +| 3 | Write | 1x | Write `landscape.md`. The artifact is available in the artifacts panel. | -Step 3 is review-gated: it blocks until `koan_review_artifact` is accepted. -All other steps advance linearly. +All steps advance linearly. The phase boundary after step 3 gives the user a +natural point to review `landscape.md` and discuss next steps. --- @@ -75,34 +75,22 @@ Key properties: The Write step produces `landscape.md` with required sections (Task Summary, Prior Art, Codebase Findings, Project Conventions, Decisions, Constraints, -Open Items). Review-gated: the step calls `koan_review_artifact` and loops -on step 3 until the user accepts. +Open Items). After writing, the phase completes and the orchestrator presents +suggested next phases at the boundary. --- -## Review Gate +## Phase Boundary -The step engine calls `validate_step_completion(step, ctx)` before -`get_next_step()`. For step 3, it verifies that `koan_review_artifact` was -called and accepted: - -```python -def validate_step_completion(step, ctx): - if step == 3: - if ctx.last_review_accepted is None: - return "You must call koan_review_artifact..." - if ctx.last_review_accepted is False: - return "The user requested revisions..." - return None -``` +After step 3 completes, `get_next_step()` returns `None`, which triggers the +phase boundary. The orchestrator summarizes what was accomplished, presents +suggested next phases with descriptions, and asks the user what to do next. ```python def get_next_step(step, ctx): if step < 3: return step + 1 - if ctx.last_review_accepted is True: - return None # done - return 3 # loop on review + return None # phase complete ``` --- diff --git a/docs/ipc.md b/docs/ipc.md index b3590e2..158edd9 100644 --- a/docs/ipc.md +++ b/docs/ipc.md @@ -18,27 +18,28 @@ that handles both the web dashboard and the MCP tool endpoint. When a tool call arrives, the server looks up the agent's state by `agent_id` in an in-process registry and handles the call directly. -Four interactions involve blocking -- the HTTP request is held open while the +Three interactions involve blocking -- the HTTP request is held open while the driver awaits an external response: | Mechanism | What blocks | Who responds | | ----------------------- | ---------------------------- | ------------------------------ | | `koan_ask_question` | User input needed | User via web UI | -| `koan_review_artifact` | User review needed | User via web UI | | `koan_request_scouts` | Scout subagents running | Driver (after scouts complete) | | Phase-boundary blocking | Phase complete, next unknown | User via `POST /api/chat` | -User-facing tool calls (`koan_ask_question`, `koan_review_artifact`) go through -the `PendingInteraction` queue on `AppState`. The MCP handler creates an -`asyncio.Future`, stores it in `AgentState.pending_tool`, enqueues a -`PendingInteraction` on `AppState`, and awaits the Future. The HTTP connection -stays open until the Future resolves. +User-facing tool calls (`koan_ask_question`) go through the `PendingInteraction` +queue on `AppState`. The MCP handler creates an `asyncio.Future`, stores it in +`AgentState.pending_tool`, enqueues a `PendingInteraction` on `AppState`, and +awaits the Future. The HTTP connection stays open until the Future resolves. `koan_request_scouts` is handled entirely inline: the handler spawns scouts via `asyncio.gather` of `spawn_subagent` calls (bounded by a semaphore), collects their results, and returns directly. No `PendingInteraction` is created; the HTTP connection is held open only by the `await asyncio.gather(...)` call. +`koan_request_executor` spawns a single executor subagent and blocks until it +exits. Like scouts, it is handled inline with no `PendingInteraction`. + Phase-boundary blocking uses `AppState.phase_complete_future` directly (not `PendingInteraction`). See [Phase-Boundary Blocking](#phase-boundary-blocking). @@ -57,11 +58,10 @@ When a user-facing blocking tool is called: and enqueues a `PendingInteraction` on `AppState.interaction_queue` 3. If no interaction is currently active, the interaction is promoted to `AppState.active_interaction` and an SSE event is pushed to browsers - (question form, or review form) + (question form) 4. Handler `await`s the Future -- HTTP connection stays open 5. User fills the form in the web UI and submits: - `POST /api/answer` resolves the Future for `koan_ask_question` - - `POST /api/artifact-review` resolves it for `koan_review_artifact` 6. Handler returns the resolved value as the MCP tool result; the next queued interaction (if any) is promoted to active @@ -87,7 +87,7 @@ subagent <---tool result (answer)----------- + The `PendingInteraction` object stored in `AppState.active_interaction` (or queued in `AppState.interaction_queue`): -- `type` -- one of `"ask"`, `"artifact-review"` +- `type` -- `"ask"` - `agent_id` -- the agent that issued the blocking call - `token` -- UUID for SSE correlation - `payload` -- type-specific request data @@ -189,36 +189,25 @@ the concatenated output. --- -## Artifact Review Flow +## Executor Flow ``` -subagent calls koan_review_artifact({ path: ".../brief.md" }) - -> MCP endpoint checks permissions - -> reads file content from path - -> creates asyncio.Future, stores in AgentState.pending_tool - -> enqueues PendingInteraction { type: "artifact-review" } on AppState - -> if no active interaction: promotes to active, pushes SSE `artifact_review_requested` - event to browsers (with rendered content) - -> awaits Future - -user sees rendered markdown in web UI - -> clicks "Accept" or types feedback and clicks "Send Feedback" - -> POST /api/artifact-review -> resolves Future with feedback string - -MCP handler receives resolved value - -> clears AgentState.pending_tool - -> activates next queued interaction (if any) - -> sets AgentState.phase_ctx.last_review_accepted - -> returns "ACCEPTED" or "REVISION REQUESTED: {feedback}" as MCP tool result - -if feedback == "Accept": - LLM calls koan_complete_step -> phase advances -else: - LLM revises artifact, calls koan_review_artifact again - (loop repeats with fresh PendingInteraction) +orchestrator calls koan_request_executor({ artifacts: [...], instructions: "..." }) + -> MCP endpoint checks permissions (execute or execution phase only) + -> no PendingInteraction created + -> ensures subagent directory, writes task.json with artifacts + instructions + -> spawns executor CLI process via spawn_subagent() + -> executor connects to /mcp?agent_id={executor_id} + -> executor calls koan_complete_step, reads artifacts, plans, implements + -> executor calls koan_complete_step at each step boundary + -> executor process exits when done + -> MCP handler collects SubagentResult (exit_code, final_response) + -> returns success/failure summary as MCP tool result to orchestrator + (HTTP connection held open for the duration of execution) ``` -See [artifact-review.md](./artifact-review.md) for the full protocol. +The orchestrator reports the result to the user in chat and then calls +`koan_complete_step` to trigger the execute phase boundary. --- @@ -239,12 +228,20 @@ orchestrator calls koan_complete_step (last step of a phase) await future # HTTP connection held open app_state.phase_complete_future = None -> messages = drain_user_messages(app_state) - -> successors = get_successor_phases(app_state.phase) - -> returns format_phase_boundary(phase, messages, successors) + -> suggested = get_suggested_phases(workflow, app_state.phase) + -> descs = workflow.phase_descriptions + -> returns format_phase_boundary(phase, messages, suggested, descs) ``` The Future is resolved when the user sends a message via `POST /api/chat`. +`format_phase_boundary` renders the suggested phases (from +`workflow.suggested_transitions[current_phase]`) with descriptions and +instructs the orchestrator to present them to the user. The user can also +request any other phase in the workflow's `available_phases`. If the +workflow has no suggested transitions for the current phase (milestones stub), +`format_phase_boundary` renders a "workflow not yet fully implemented" message. + **Key asyncio invariant:** `api_chat` and `koan_complete_step` run in the same asyncio event loop. `api_chat` appends to `user_message_buffer` before calling `set_result()`. When `koan_complete_step` resumes, `drain_user_messages()` finds @@ -280,8 +277,8 @@ orchestrator calls koan_complete_step (any step) Messages sent while the orchestrator is mid-step accumulate in the buffer and are delivered at the next `koan_complete_step` call. Messages sent during -`koan_ask_question` or `koan_review_artifact` also buffer and deliver after -the structured interaction resolves. +`koan_ask_question` also buffer and deliver after the structured interaction +resolves. --- diff --git a/docs/projections.md b/docs/projections.md index 58af161..b181a78 100644 --- a/docs/projections.md +++ b/docs/projections.md @@ -48,13 +48,14 @@ held in memory for the duration of a workflow run. --- -## Event Types (37 total) +## Event Types (36 total) ### Lifecycle (8) | Event | Payload | `agent_id` | |-------|---------|-----------| | `run_started` | `{profile, installations, scout_concurrency}` | `None` | +| `workflow_selected` | `{workflow}` | `None` | | `phase_started` | `{phase}` | `None` | | `agent_spawned` | `{agent_id, role, label, model, is_primary, started_at_ms}` | set | | `agent_spawn_failed` | `{role, error_code, message, details?}` | `None` | @@ -66,6 +67,9 @@ held in memory for the duration of a workflow run. `run_started` is emitted by `api_start_run` before the driver begins. It creates the `Run` object in the projection with the frozen `RunConfig`. +`workflow_selected` is emitted immediately after `run_started`, recording the +workflow type chosen by the user. The fold sets `run.workflow` from this event. + `agent_spawned` does not carry `step` — step 0 is implied. `agent_exited` does not carry `is_primary` — the fold looks up the agent in `run.agents`. @@ -98,14 +102,12 @@ on the conversation entry is `True` until `tool_completed` arrives. `agent.conversation.pending_thinking`; the completed `ThinkingEntry` is created on the next transition (tool call, step advance, or stream delta). -### Focus (4) +### Focus (2) | Event | Payload | `agent_id` | |-------|---------|-----------| | `questions_asked` | `{token, questions}` | set | | `questions_answered` | `{token, cancelled, answers?}` | set | -| `artifact_review_requested` | `{token, path, description, content}` | set | -| `artifact_reviewed` | `{token, cancelled, accepted?, response?}` | set | These events transition `run.focus` between variants of the `Focus` union. Cancellation (`cancelled: true`) occurs when the agent exits while the @@ -200,6 +202,7 @@ Projection │ └── default_scout_concurrency: int ├── run: Run | None │ ├── config: RunConfig # frozen at run_started +│ ├── workflow: str # workflow name, set by workflow_selected │ ├── phase: str │ ├── agents: dict[str, Agent] # agent_id → Agent (all statuses) │ │ └── conversation: Conversation @@ -209,7 +212,7 @@ Projection │ │ ├── is_thinking: bool │ │ ├── input_tokens: int │ │ └── output_tokens: int -│ ├── focus: Focus | None # discriminated union of 4 variants +│ ├── focus: Focus | None # discriminated union of 2 variants │ ├── artifacts: dict[str, ArtifactInfo] # path → ArtifactInfo │ └── completion: CompletionInfo | None └── notifications: list[Notification] @@ -392,16 +395,8 @@ class QuestionFocus(KoanBaseModel): token: str questions: list[dict] # raw LLM output, not validated by fold -class ReviewFocus(KoanBaseModel): - type: Literal["review"] = "review" - agent_id: str - token: str - path: str - description: str - content: str - Focus = Annotated[ - ConversationFocus | QuestionFocus | ReviewFocus, + ConversationFocus | QuestionFocus, Field(discriminator="type"), ] ``` @@ -414,7 +409,7 @@ explicit. ```python class ArtifactInfo(KoanBaseModel): - path: str # relative to epic directory + path: str # relative to run directory size: int # bytes modified_at: int = 0 # milliseconds since epoch @@ -453,6 +448,9 @@ Settings: /settings/installations/claude-default/available Run config: /run/config/profile /run/config/scoutConcurrency +Run: /run/workflow + /run/phase + Agent: /run/agents/abc123/status /run/agents/abc123/step /run/agents/abc123/lastTool @@ -464,7 +462,6 @@ Conversation: /run/agents/abc123/conversation/pendingThinking Focus: /run/focus Artifacts: /run/artifacts/docs~1architecture.md/size -Phase: /run/phase ``` Named entities (installations, profiles, agents, artifacts) are dicts for @@ -516,8 +513,6 @@ completed agents. | `agent_spawned` (primary) | `run.focus = ConversationFocus(agent_id=...)` | | `questions_asked` | `run.focus = QuestionFocus(agent_id=..., token=..., questions=...)` | | `questions_answered` | `run.focus = ConversationFocus(agent_id=primary_id)` | -| `artifact_review_requested` | `run.focus = ReviewFocus(...)` | -| `artifact_reviewed` | `run.focus = ConversationFocus(agent_id=primary_id)` | | `user_message` | `primary_agent.conversation.entries += UserMessageEntry(...)` | ### Run lifecycle @@ -525,6 +520,7 @@ completed agents. | Event | Action | |-------|--------| | `run_started` | `projection.run = Run(config=RunConfig(...))` | +| `workflow_selected` | `run.workflow = payload["workflow"]` | | `phase_started` | `run.phase = phase` | | `workflow_completed` | `run.completion = CompletionInfo(...)` | @@ -639,6 +635,7 @@ domain types; `projections.py` does not. ```python def build_run_started(profile, installations, scout_concurrency) -> dict +def build_workflow_selected(workflow: str) -> dict def build_agent_spawned(agent: AgentState) -> dict def build_agent_exited(exit_code, error=None, usage=None) -> dict def build_agent_spawn_failed(role, diagnostic: RunnerDiagnostic) -> dict @@ -781,6 +778,9 @@ const conversation = useStore(s => // Settings: read directly from store const installations = useStore(s => s.settings?.installations ?? {}) const defaultProfile = useStore(s => s.settings?.defaultProfile ?? 'balanced') + +// Run: workflow type +const workflow = useStore(s => s.run?.workflow) ``` --- @@ -854,14 +854,10 @@ not yet complete and will be committed to `entries` on the next event. ### Why Focus is a discriminated union -The previous architecture used an `active_interaction` dict with an -`interaction_type` string that the frontend duck-typed. This created implicit -coupling between the backend's interaction type strings and the frontend's -rendering switch. Focus replaces it with an explicit discriminated union where -every possible main-content state is modeled. The frontend switch on -`focus.type` is exhaustive — TypeScript will flag unhandled variants. The -`agent_id` on every variant means the conversation is always available as -backdrop without a separate lookup. +An explicit discriminated union models every possible main-content state. +The frontend switch on `focus.type` is exhaustive — TypeScript will flag +unhandled variants. The `agent_id` on every variant means the conversation is +always available as backdrop without a separate lookup. ### Why Settings vs RunConfig @@ -876,10 +872,10 @@ may override before starting. ### Why always-snapshot on reconnect The previous architecture stored events and replayed them for reconnecting -clients (`?since=N` returned events `N+1..M`). At 500K events over a full epic, +clients (`?since=N` returned events `N+1..M`). At 500K events over a full run, with patches ranging from 80 bytes to 10KB, storing patches for replay requires unbounded memory and adds ordering logic and partial-replay edge cases. A fresh -50MB snapshot is sent once on reconnect — cheaper, simpler, and handles server +snapshot is sent once on reconnect — cheaper, simpler, and handles server restarts (which would have caused a `fatal_error` in the old protocol) identically to a normal reconnect. @@ -910,7 +906,7 @@ structured data. Stdout events are filtered to exclude koan MCP tool names `artifact_created`/`artifact_modified`/`artifact_removed` carry exactly what changed, not the full current set. The fold maintains `run.artifacts` as a dict keyed by path, enabling O(1) per-event updates. `build_artifact_diff()` scans -the epic directory at phase boundaries and produces the minimal set of events. +the run directory at phase boundaries and produces the minimal set of events. ### Why projections.py has zero koan domain imports diff --git a/docs/state.md b/docs/state.md index d0cdd3a..b201751 100644 --- a/docs/state.md +++ b/docs/state.md @@ -1,7 +1,7 @@ # State & Driver -How the driver manages epic and story state, routes between phases, and -enforces the file boundary invariant. +How the driver manages run state, routes between phases, and enforces the file +boundary invariant. > Parent doc: [architecture.md](./architecture.md) @@ -17,9 +17,9 @@ The driver writes JSON; LLMs write markdown. Tool code bridges both. | **LLM** | `.md` files, codebase files | `.md` files (output) | | **Tool code** | `.json` state (to validate) | `.json` state + `.md` status (both) | -### Why the epic state module must not write markdown +### Why the run state module must not write markdown -The epic state module (`koan/epic_state.py`) reads and writes JSON only. +The run state module (`koan/run_state.py`) reads and writes JSON only. `status.md` writes belong exclusively in orchestrator tool handlers, which bridge the two worlds by writing JSON state (for the driver) and templated markdown (for LLMs) in the same operation. @@ -34,36 +34,33 @@ itself. --- -## Epic State +## Run State -`epic-state.json` in the epic directory root. Tracks the current pipeline -phase and the list of story IDs. +`run-state.json` in the run directory root. Tracks the current workflow phase, +the active workflow type, and the list of story IDs. ```python -# koan/epic_state.py +# koan/run_state.py { - "phase": "intake", # intake -> brief-generation -> core-flows -> tech-plan - # -> ticket-breakdown -> cross-artifact-validation - # -> execution -> implementation-validation -> completed - "stories": [] # populated by driver after filesystem scan + "phase": "intake", # current phase name; valid values depend on the active workflow + "workflow": "plan", # workflow type selected at run start ("plan" | "milestones") + "stories": [] # populated by driver after filesystem scan } ``` -### Epic phases - -| Phase | What happens | -| --------------------------- | ------------------------------------------------------------------------------------------- | -| `intake` | Intake subagent reads conversation, scouts codebase, asks user questions | -| `brief-generation` | Brief-writer subagent distills landscape.md into brief.md; user reviews via artifact review | -| `core-flows` | Define user journeys with sequence diagrams | -| `tech-plan` | Specify technical architecture | -| `ticket-breakdown` | Generate story-sized implementation tickets | -| `cross-artifact-validation` | Validate cross-boundary consistency | -| `execution` | Implement tickets through supervised batch process | -| `implementation-validation` | Post-execution alignment review | -| `completed` | All phases done | +### Plan workflow phases +| Phase | What happens | +|-------|--------------| +| `intake` | Orchestrator reads conversation, scouts codebase, asks clarifying questions. Writes `landscape.md`. | +| `plan-spec` | Orchestrator reads `landscape.md` and codebase, writes `plan.md`. | +| `plan-review` | Orchestrator reads `landscape.md` and `plan.md`, evaluates quality, reports findings via chat. | +| `execute` | Orchestrator composes executor instructions and spawns a single executor subagent. | +Phases advance via `koan_set_phase`. Any phase in the active workflow's +`available_phases` is a valid transition target from any other phase (except +self-transitions). The suggested transitions in `workflow.suggested_transitions` +guide the orchestrator's default boundary response but do not restrict the user. **`scouting` is intentionally absent.** Scouts run inside the `koan_request_scouts` tool handler during intake/planning phases, @@ -127,26 +124,10 @@ The driver spawns the orchestrator once at run start and awaits its exit. The orchestrator drives the entire workflow, including phase transitions and story execution. -### Story execution (orchestrator-driven) - -The orchestrator selects and manages stories during the execution phase via -MCP tools: - -``` -orchestrator calls koan_select_story(story_id) - -> story status set to "selected" -orchestrator calls koan_spawn_executor(story_id, role="planner") - -> driver spawns planner subagent, blocks until exit -orchestrator calls koan_spawn_executor(story_id, role="executor") - -> driver spawns executor subagent, blocks until exit - -> (if retry needed: pass retry_context to koan_spawn_executor) -orchestrator calls koan_complete_story / koan_retry_story / koan_skip_story -``` - ### Model config gate When a web server is available, the pipeline blocks at startup until the user -confirms model tier selection. This happens before the orchestrator spawns. +confirms model tier selection and workflow type. This happens before the orchestrator spawns. --- @@ -164,7 +145,7 @@ os.rename(tmp, file_path) This applies to: -- `epic-state.json` (driver) +- `run-state.json` (driver) - `stories/{id}/state.json` (driver + orchestrator tools) - `stories/{id}/status.md` (orchestrator tools) - `subagents/{label}/task.json` (driver, before spawn) @@ -172,13 +153,13 @@ This applies to: --- -## Epic Directory Structure +## Run Directory Structure ``` -{epic_dir}/ - epic-state.json # Epic phase + story list +~/.koan/runs/{run_id}/ + run-state.json # Workflow phase + workflow type + story list landscape.md # Written by orchestrator (intake phase) - brief.md # Written by orchestrator (brief-generation phase) + plan.md # Written by orchestrator (plan-spec phase) stories/ {story_id}/ story.md # Written by orchestrator (ticket-breakdown phase) @@ -195,11 +176,7 @@ This applies to: task.json findings.md # Scout output ... - planner-{story_id}/ - task.json - state.json - events.jsonl - executor-{story_id}/ + executor-{run_id}/ task.json state.json events.jsonl @@ -216,18 +193,19 @@ transitions. Key projection fields common to all roles: -| Field | Type | Meaning | -| ----------------- | ------ | ------------------------------------------------------- | -| `phase` | string | Overall phase name (e.g., "intake", "brief-generation") | -| `step` | number | Current step index within the phase | -| `step_name` | string | Human-readable step label (e.g., "Scout (round 2)") | -| `tokens_sent` | number | Cumulative tokens in | -| `tokens_received` | number | Cumulative tokens out | +| Field | Type | Meaning | +| ----------------- | ------ | -------------------------------------------------------- | +| `phase` | string | Overall phase name (e.g., "intake", "plan-spec") | +| `step` | number | Current step index within the phase | +| `step_name` | string | Human-readable step label (e.g., "Scout (round 2)") | +| `tokens_sent` | number | Cumulative tokens in | +| `tokens_received` | number | Cumulative tokens out | Orchestrator state tracked in `AppState` (in-memory, not persisted): | Field | Type | Purpose | |-------|------|---------| +| `workflow` | `Workflow \| None` | Active workflow; set at run start, drives transition validation and phase guidance | | `user_message_buffer` | `list[ChatMessage]` | Buffered user chat messages, drained at each `koan_complete_step` | | `phase_complete_future` | `asyncio.Future \| None` | Non-None while `koan_complete_step` is blocking at a phase boundary | diff --git a/docs/subagents.md b/docs/subagents.md index b5fe035..9bd4c68 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -16,13 +16,13 @@ registry. ### `task.json` schema The manifest is a discriminated union on the `role` field. Common fields -(`role`, `epic_dir`, `mcp_url`) appear on every variant; role-specific fields +(`role`, `run_dir`, `mcp_url`) appear on every variant; role-specific fields are nested naturally rather than flattened into a shared namespace. ```json { "role": "intake", - "epic_dir": "/path/to/epic", + "run_dir": "/path/to/run", "mcp_url": "http://localhost:8420/mcp?agent_id=intake-abc123" } ``` @@ -33,8 +33,7 @@ Role-specific fields: | -------------- | ------------------------------------------------- | | `orchestrator` | `project_dir`, `task_description` | | `scout` | `question`, `investigator_role` | -| `planner` | `story_id` | -| `executor` | `story_id`, `retry_context` (optional) | +| `executor` | `artifacts`, `instructions` | ### Lifecycle @@ -117,8 +116,7 @@ The MCP endpoint validates required `task.json` fields at agent registration: | Role | Required fields | Failure if missing | | -------- | --------------- | ----------------------------------------------------------------------- | | scout | `question` | Step 1 guidance has no assignment -> LLM outputs confused text -> exits | -| planner | `story_id` | Malformed paths like `stories//plan/plan.md` | -| executor | `story_id` | Same path issue | +| executor | `artifacts` | Executor has no files to read before implementing | These checks are intentionally fail-fast because they indicate a broken parent->child contract (programming/configuration error), not model behavior. @@ -136,16 +134,18 @@ Phase modules: ``` koan/phases/ intake.py # guidance provider: intake phase + plan_spec.py # guidance provider: plan-spec phase + plan_review.py # guidance provider: plan-review phase + execute.py # guidance provider: execute phase (general-purpose) brief_writer.py # guidance provider: brief-generation phase core_flows.py # guidance provider: core-flows phase tech_plan.py # guidance provider: tech-plan phase ticket_breakdown.py # guidance provider: ticket-breakdown phase cross_artifact_validation.py # guidance provider: cross-artifact-validation and implementation-validation - executor.py # guidance provider: execution phase; also spawned as separate subagent + executor.py # spawned as separate subagent; implements code changes orchestrator.py # guidance provider: pre/post execution steps scout.py # spawned as separate subagent; no step guidance role format_step.py # shared formatting utilities - review_protocol.py # shared review loop logic ``` Each phase module exposes: @@ -153,11 +153,17 @@ Each phase module exposes: | Symbol | Kind | Purpose | Default | | --------------------------------------- | -------- | ------------------------------------ | ----------------------------------- | | `SYSTEM_PROMPT` | constant | Role identity and rules | Required | +| `SCOPE` | constant | `"general"`, `"plan"`, or `"legacy"` | Required | | `step_guidance(step, ctx)` | function | Return step instructions | Required | | `get_next_step(step, ctx)` | function | Next step or None (done) | Linear: step+1, None at total_steps | | `validate_step_completion(step, ctx)` | function | Pre-condition check before advancing | None (always allow) | | `on_loop_back(from_step, to_step, ctx)` | function | Side effects of backward transitions | no-op | +`SCOPE` is metadata, not enforcement. It communicates reusability intent: +`"general"` phases are designed to work across workflows; `"plan"` phases are +specific to the plan workflow; `"legacy"` phases are dead code from an older +pipeline, kept for reference. + ### Step progression state machine ``` @@ -166,7 +172,7 @@ koan_complete_step arrives via MCP: otherwise -> validate_step_completion(step) [pre-condition check] -> next_step = get_next_step(step) [pure: decides where to go] next_step is None -> block for user message (asyncio.Future), then - return format_phase_boundary(phase, messages, successors) [phase boundary] + return format_phase_boundary(phase, messages, suggested, descriptions) [phase boundary] next_step < prev -> on_loop_back(prev, next_step) [side effects of loop] next_step != None -> step=next_step, return format_step(step_guidance(next_step)) + any buffered user messages [advance] ``` @@ -225,7 +231,7 @@ from write-bash is intractable at the permission layer. ### Role permission matrix The orchestrator role uses **phase-aware permissions** — available tools -vary by the current phase. Planner, executor, and scout use static permission sets. +vary by the current phase. Executor and scout use static permission sets. **Orchestrator phase-aware permissions:** @@ -234,11 +240,10 @@ vary by the current phase. Planner, executor, and scout use static permission se | `koan_complete_step` | All phases | | `koan_set_phase` | All phases (blocked mid-story during execution) | | `koan_ask_question` | All phases | -| `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation` | -| `koan_review_artifact` | `intake`, `brief-generation`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `implementation-validation` | -| `koan_spawn_executor` | `execution` only | +| `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `plan-spec`, `plan-review` | +| `koan_request_executor` | `execution`, `execute` | | `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | `execution` only | -| `write`, `edit` (epic_dir scoped) | All phases except `brief-generation` step 1 | +| `write`, `edit` (run_dir scoped) | All phases except `brief-generation` step 1 | | `bash` | `execution`, `implementation-validation` | **Other role static permissions:** @@ -246,15 +251,41 @@ vary by the current phase. Planner, executor, and scout use static permission se | Role | koan tools | write/edit | notes | | -------------- | -------------------------------------------- | ---------------------- | ------------------------------------------- | | **scout** | `koan_complete_step` | none | No user interaction. No nested scouts. No file writing. | -| **planner** | `koan_complete_step`, `koan_ask_question`, `koan_request_scouts` | path-scoped to epicDir | -- | | **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | ### Path scoping -Planning roles (orchestrator, scout, planner) can only -`write`/`edit` files inside the epic directory. The permission check resolves -both the tool's `path` argument and the epic directory, then verifies the tool -path starts with the epic path. +Planning roles (orchestrator, scout) can only `write`/`edit` files inside the +run directory. The permission check resolves both the tool's `path` argument +and the run directory, then verifies the tool path starts with the run path. + +--- + +## Executor Subagent + +The executor is spawned by the orchestrator via `koan_request_executor`. It +receives structured inputs via `task.json` and implements code changes in a +3-step workflow: + +| Step | Name | What happens | +|------|------|--------------| +| 1 | Comprehend | Read all artifacts listed in `task.json`. Understand the plan and codebase context. | +| 2 | Plan | Identify the specific file edits needed. Do not write code yet. | +| 3 | Implement | Apply changes, verify they match the plan, report what was done. | + +`task.json` fields for the executor role: + +| Field | Type | Purpose | +|-------|------|---------| +| `artifacts` | `list[str]` | Paths relative to `run_dir` that the executor must read before coding | +| `instructions` | `str` | Free-form context: key decisions, user direction, review findings. Does NOT repeat artifact contents. | + +The executor has unrestricted `write`/`edit` access — it must be able to modify +the actual codebase. It may call `koan_ask_question` if it encounters genuine +ambiguity that cannot be resolved from the artifacts and instructions. + +`koan_request_executor` blocks until the executor process exits. The orchestrator +receives a success/failure summary and reports it to the user at the execute phase boundary. --- @@ -266,7 +297,7 @@ Koan has 6+ roles, but they cluster into 3 capability bands: | Tier | Roles | Why this tier | | ------------ | ------------------------------ | ---------------------------------------------------------------- | -| **strong** | orchestrator, planner | Complex multi-step reasoning | +| **strong** | orchestrator | Complex multi-step reasoning | | **standard** | executor | Code implementation: reliable tool use without deepest reasoning | | **cheap** | scout | Narrow codebase investigation: reading files, writing findings | From 1e8fbefb89f84705a6b2098ea09432e20aa27683 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 15:50:24 +0700 Subject: [PATCH 309/412] feat: redesign launch page with stacked-card layout Three-card design: Workflow (radio-card selector), Description (with warm prompt sub-label), and Configuration (profile, agent installations by runner type with probe status dots, scout concurrency). Add project directory display below heading. Expose project_dir from the initial-prompt API endpoint. All new CSS classes use launch-* prefix to avoid collisions. --- frontend/src/api/client.ts | 2 +- frontend/src/components/LandingPage.tsx | 159 +++++++++++-------- frontend/src/styles/components.css | 199 ++++++++++++++++++++++++ koan/web/app.py | 2 +- 4 files changed, 293 insertions(+), 69 deletions(-) diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 20463e6..a732c85 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -146,7 +146,7 @@ export async function saveScoutConcurrency(value: number) { // -- Initial prompt ---------------------------------------------------------- -export async function getInitialPrompt(): Promise<{ prompt: string }> { +export async function getInitialPrompt(): Promise<{ prompt: string; project_dir?: string }> { return get('/api/initial-prompt') } diff --git a/frontend/src/components/LandingPage.tsx b/frontend/src/components/LandingPage.tsx index e985466..cac0127 100644 --- a/frontend/src/components/LandingPage.tsx +++ b/frontend/src/components/LandingPage.tsx @@ -10,6 +10,7 @@ export function LandingPage() { const [error, setError] = useState<string | null>(null) const [selectedInstallations, setSelectedInstallations] = useState<Record<string, string>>({}) const [workflow, setWorkflow] = useState<'plan' | 'milestones'>('plan') + const [projectDir, setProjectDir] = useState('') // Read from store (fed by SSE — always current, no API fetch needed) const profilesDict = useStore(s => s.settings.profiles) @@ -27,6 +28,7 @@ export function LandingPage() { useEffect(() => { api.getInitialPrompt().then(data => { if (data.prompt) setTask(data.prompt) + if (data.project_dir) setProjectDir(data.project_dir) }) }, []) @@ -132,26 +134,40 @@ export function LandingPage() { <div className="phase-inner"> <h2 className="phase-heading">New Run</h2> + <div className="launch-project-dir"> + <span className="launch-project-dir-label">PROJECT</span> + <span className="launch-project-dir-path">{projectDir || '—'}</span> + </div> + + {/* Workflow card */} <div className="question-card"> <div className="question-header">Workflow</div> - <div className="workflow-options"> + <div className="launch-workflow-grid"> <button - className={`workflow-card${workflow === 'plan' ? ' selected' : ''}`} + className={`launch-workflow-card${workflow === 'plan' ? ' selected' : ''}`} onClick={() => setWorkflow('plan')} > - <strong>Plan</strong> - <span>Plan an implementation approach, review it, then execute</span> + <div className="launch-workflow-card-header"> + <div className={`launch-radio-dot${workflow === 'plan' ? ' selected' : ''}`} /> + <span className="launch-workflow-card-name">Plan</span> + </div> + <div className="launch-workflow-card-desc">Plan an approach, review it, then execute</div> </button> - <button className="workflow-card disabled" disabled> - <strong>Milestones</strong> - <span>Break work into milestones with phased delivery</span> - <span className="badge">coming soon</span> + <button className="launch-workflow-card disabled" disabled> + <div className="launch-workflow-card-header"> + <div className="launch-radio-dot" /> + <span className="launch-workflow-card-name">Milestones</span> + <span className="launch-badge-soon">coming soon</span> + </div> + <div className="launch-workflow-card-desc">Break work into milestones with phased delivery</div> </button> </div> </div> + {/* Description card */} <div className="question-card"> - <div className="question-header">Task</div> + <div className="question-header">Description</div> + <div className="launch-description-hint">What should this run accomplish?</div> <textarea id="task-input" className="workflow-feedback" @@ -162,67 +178,76 @@ export function LandingPage() { /> </div> - <div className="model-config-section"> - <h3 className="model-config-section-heading">Profile</h3> - <select - id="profile-select" - className="model-tier-select" - value={profile} - onChange={e => setProfile(e.target.value)} - > - {profiles.map(p => ( - <option key={p.name} value={p.name}> - {p.name} - {p.readOnly ? ' (built-in)' : ''} - </option> - ))} - </select> - </div> + {/* Configuration card */} + <div className="question-card"> + <div className="question-header">Configuration</div> - {preflight && preflight.required_runner_types.length > 0 && ( - <div className="model-config-section"> - <h3 className="model-config-section-heading">Agent Installations</h3> - {preflight.required_runner_types.map(rt => { - const insts = preflight.installations[rt] || [] - const selected = selectedInstallations[rt] || '' - return ( - <div key={rt} style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 6 }}> - <span style={{ minWidth: 70, fontWeight: 500 }}>{rt}</span> - <select - className="model-tier-select" - value={selected} - onChange={e => setSelectedInstallations(prev => ({...prev, [rt]: e.target.value}))} - style={{ flex: 1 }} - > - <option value="">-- select installation --</option> - {insts.map(inst => ( - <option key={inst.alias} value={inst.alias}> - {inst.alias} ({inst.binary}) - </option> - ))} - </select> - {insts.length === 0 && ( - <span className="no-runners-msg" style={{ fontSize: 13 }}> - No installations. Add one in Settings. - </span> - )} - </div> - ) - })} + {/* Profile */} + <div className="launch-config-group"> + <div className="launch-config-label">Profile</div> + <select + id="profile-select" + className="model-tier-select" + value={profile} + onChange={e => setProfile(e.target.value)} + > + {profiles.map(p => ( + <option key={p.name} value={p.name}> + {p.name} + {p.readOnly ? ' (built-in)' : ''} + </option> + ))} + </select> </div> - )} - <div className="model-config-section"> - <h3 className="model-config-section-heading">Scout Concurrency</h3> - <input - id="scout-concurrency" - className="scout-concurrency-input" - type="number" - min={1} - max={32} - value={scoutConcurrency} - onChange={e => setScoutConcurrency(parseInt(e.target.value, 10) || 8)} - /> + {/* Agent installations */} + {preflight && preflight.required_runner_types.length > 0 && ( + <div className="launch-config-group"> + <div className="launch-config-label">Agent Installations</div> + {preflight.required_runner_types.map(rt => { + const insts = preflight.installations[rt] || [] + const selected = selectedInstallations[rt] || '' + return ( + <div key={rt} className="launch-agent-row"> + <span className="launch-agent-type">{rt}</span> + <div className={`launch-agent-status ${insts.length > 0 && selected ? 'available' : 'unavailable'}`} /> + <select + className="launch-agent-select" + value={selected} + onChange={e => setSelectedInstallations(prev => ({ ...prev, [rt]: e.target.value }))} + > + <option value="">-- select --</option> + {insts.map(inst => ( + <option key={inst.alias} value={inst.alias}> + {inst.alias} ({inst.binary}) + </option> + ))} + </select> + {insts.length === 0 && ( + <span className="launch-agent-missing">Not detected — configure in Settings</span> + )} + </div> + ) + })} + </div> + )} + + {/* Scout concurrency */} + <div className="launch-config-group"> + <div className="launch-config-label">Scout Concurrency</div> + <div className="launch-scouts-row"> + <input + id="scout-concurrency" + className="scout-concurrency-input" + type="number" + min={1} + max={32} + value={scoutConcurrency} + onChange={e => setScoutConcurrency(parseInt(e.target.value, 10) || 8)} + /> + <span className="launch-scouts-hint">max parallel scout agents</span> + </div> + </div> </div> {error && <div className="no-runners-msg">{error}</div>} diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 419d620..1f63e51 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -1328,3 +1328,202 @@ background: var(--copper); animation: thinking-pulse 1.5s ease-in-out infinite; } + +/* ---- Launch page ---- */ + +.launch-project-dir { + display: flex; + align-items: center; + gap: 8px; + margin-bottom: 24px; + font-family: var(--font-mono); + font-size: var(--font-size-xs); +} + +.launch-project-dir-label { + color: var(--text-ghost); +} + +.launch-project-dir-path { + color: var(--text); + font-weight: 500; +} + +/* Workflow radio cards */ +.launch-workflow-grid { + display: flex; + gap: 12px; + margin-top: var(--space-2); +} + +.launch-workflow-card { + flex: 1; + border: 2px solid var(--border); + border-radius: var(--radius-md); + padding: var(--space-4); + background: var(--bg-elevated); + cursor: pointer; + text-align: left; + transition: border-color var(--duration-fast), background var(--duration-fast); + font-family: var(--font-sans); +} + +.launch-workflow-card:hover:not(.disabled) { + border-color: var(--border-strong); +} + +.launch-workflow-card.selected { + border-color: var(--copper); + background: var(--copper-bg); +} + +.launch-workflow-card.disabled { + opacity: 0.5; + cursor: not-allowed; +} + +.launch-workflow-card-header { + display: flex; + align-items: center; + gap: 8px; + margin-bottom: 6px; +} + +.launch-radio-dot { + width: 16px; + height: 16px; + border-radius: 50%; + border: 2px solid var(--border-strong); + flex-shrink: 0; + transition: border-color var(--duration-fast), box-shadow var(--duration-fast); +} + +.launch-radio-dot.selected { + border-color: var(--copper); + box-shadow: inset 0 0 0 3px var(--copper); +} + +.launch-workflow-card-name { + font-weight: 700; + font-size: var(--font-size-md); + color: var(--text-strong); +} + +.launch-badge-soon { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + background: var(--bg-inset); + padding: 2px 8px; + border-radius: var(--radius-sm); + color: var(--text-muted); +} + +.launch-workflow-card-desc { + font-size: var(--font-size-sm); + color: var(--text-muted); + line-height: 1.5; +} + +/* Description hint */ +.launch-description-hint { + font-size: var(--font-size-sm); + color: var(--text-ghost); + margin-bottom: 10px; +} + +/* Configuration groups */ +.launch-config-group { + margin-bottom: var(--space-4); +} + +.launch-config-group:last-child { + margin-bottom: 0; +} + +.launch-config-label { + font-size: var(--font-size-sm); + font-weight: 600; + color: var(--text-strong); + margin-bottom: 6px; +} + +/* Agent installation rows */ +.launch-agent-row { + display: flex; + align-items: center; + gap: 10px; + padding: 10px 14px; + background: var(--bg); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + margin-bottom: 6px; +} + +.launch-agent-type { + font-family: var(--font-mono); + font-size: var(--font-size-sm); + font-weight: 600; + color: var(--text-strong); + min-width: 70px; +} + +.launch-agent-status { + width: 7px; + height: 7px; + border-radius: 50%; + flex-shrink: 0; +} + +.launch-agent-status.available { + background: var(--green); +} + +.launch-agent-status.unavailable { + background: var(--red); +} + +.launch-agent-select { + flex: 1; + padding: var(--space-1) var(--space-2); + background: var(--bg-elevated); + border: 1px solid var(--border); + border-radius: var(--radius-sm); + color: var(--text); + font-family: var(--font-mono); + font-size: var(--font-size-sm); + outline: none; + cursor: pointer; + -webkit-appearance: none; + appearance: none; + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8'%3E%3Cpath d='M1 1l5 5 5-5' stroke='%23957E68' stroke-width='1.5' fill='none'/%3E%3C/svg%3E"); + background-repeat: no-repeat; + background-position: right 8px center; + padding-right: 28px; +} + +.launch-agent-select:focus { + border-color: var(--copper); +} + +.launch-agent-missing { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--red); +} + +.launch-agent-row.error { + background: var(--red-bg); + border-color: var(--red-border); +} + +/* Scout concurrency row */ +.launch-scouts-row { + display: flex; + align-items: center; + gap: 10px; +} + +.launch-scouts-hint { + font-size: var(--font-size-sm); + color: var(--text-ghost); +} diff --git a/koan/web/app.py b/koan/web/app.py index ca6ee0a..26bb5fb 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -982,7 +982,7 @@ async def api_settings_scout_concurrency(r: Request) -> Response: async def api_initial_prompt(r: Request) -> Response: st = _app_state(r) - return JSONResponse({"prompt": st.initial_prompt}) + return JSONResponse({"prompt": st.initial_prompt, "project_dir": st.project_dir}) # -- App factory -------------------------------------------------------------- From 4ca4d09a4a280bb2a450e33a0d2d3c874bc2de3a Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:07:04 +0700 Subject: [PATCH 310/412] fix: scan artifacts at phase boundaries and step transitions --- koan/web/mcp_endpoint.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index d0b4bf6..b4e4be2 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -252,6 +252,10 @@ async def _step_within_phase( agent_id=agent.agent_id, ) + # Scan for artifacts between steps (e.g. after a write step) + from ..driver import _push_artifact_diff + _push_artifact_diff(_app_state) + guidance = phase_module.step_guidance(next_step, ctx) result = format_step(guidance) @@ -282,6 +286,10 @@ async def _step_phase_boundary( agent_id=agent.agent_id, ) + # Scan for new artifacts so they appear before the user is asked to respond + from ..driver import _push_artifact_diff + _push_artifact_diff(_app_state) + # Check for already-buffered messages messages = drain_user_messages(_app_state) + drain_steering_messages(_app_state) From 1005298c0c78fbf9213c84a2993228649024cceb Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:07:49 +0700 Subject: [PATCH 311/412] fix: emit phase_boundary_reached event for user visibility --- frontend/src/components/ActivityFeed.tsx | 8 +++++++- frontend/src/store/index.ts | 3 ++- frontend/src/styles/components.css | 16 +++++++++++++++ koan/projections.py | 26 +++++++++++++++++++++++- koan/web/mcp_endpoint.py | 7 +++++++ 5 files changed, 57 insertions(+), 3 deletions(-) diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index 7eb803e..16725e0 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -1,5 +1,5 @@ import { useRef, useState } from 'react' -import { useStore, ConversationEntry } from '../store/index' +import { useStore, ConversationEntry, PhaseBoundaryEntry } from '../store/index' import { useAutoScroll } from '../hooks/useAutoScroll' import { Md } from './Md' import { ChatInput } from './ChatInput' @@ -164,6 +164,12 @@ function renderEntry(entry: ConversationEntry, i: number) { return <ToolLine key={i} tool={entry.toolName} summary={entry.summary} inFlight={entry.inFlight} /> case 'debug_step_guidance': return <DebugGuidanceCard key={i} content={entry.content} /> + case 'phase_boundary': + return ( + <div key={i} className="activity-card activity-phase-boundary"> + <div className="activity-boundary-message">{entry.message}</div> + </div> + ) default: return null } diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index b2e065c..2819651 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -45,12 +45,13 @@ export interface ToolGrepEntry extends BaseToolEntry { type: 'tool_grep'; export interface ToolLsEntry extends BaseToolEntry { type: 'tool_ls'; path: string } export interface ToolGenericEntry extends BaseToolEntry { type: 'tool_generic'; toolName: string; summary: string } export interface DebugStepGuidanceEntry { type: 'debug_step_guidance'; content: string } +export interface PhaseBoundaryEntry { type: 'phase_boundary'; phase: string; message: string } export type ConversationEntry = | ThinkingEntry | TextEntry | StepEntry | UserMessageEntry | ToolReadEntry | ToolWriteEntry | ToolEditEntry | ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry - | DebugStepGuidanceEntry + | DebugStepGuidanceEntry | PhaseBoundaryEntry export interface Conversation { entries: ConversationEntry[] diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 1f63e51..ec4bec1 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -1527,3 +1527,19 @@ font-size: var(--font-size-sm); color: var(--text-ghost); } + +/* ---- Phase boundary ---- */ +.activity-phase-boundary { + text-align: center; + padding: var(--space-4); + color: var(--text-muted); + font-size: var(--font-size-sm); + border: 1px dashed var(--border); + border-radius: var(--radius-md); + margin: var(--space-3) 0; + background: var(--bg-elevated); +} + +.activity-boundary-message { + font-style: italic; +} diff --git a/koan/projections.py b/koan/projections.py index 2de9656..cdba3bd 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -54,6 +54,7 @@ "debug_step_guidance", # User chat "user_message", + "phase_boundary_reached", # Steering "steering_queued", "steering_delivered", @@ -179,11 +180,16 @@ class DebugStepGuidanceEntry(KoanBaseModel): type: Literal["debug_step_guidance"] = "debug_step_guidance" content: str # full formatted step guidance text +class PhaseBoundaryEntry(KoanBaseModel): + type: Literal["phase_boundary"] = "phase_boundary" + phase: str + message: str + ConversationEntry = Annotated[ ThinkingEntry | TextEntry | StepEntry | UserMessageEntry | ToolReadEntry | ToolWriteEntry | ToolEditEntry | ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry | - DebugStepGuidanceEntry, + DebugStepGuidanceEntry | PhaseBoundaryEntry, Field(discriminator="type"), ] @@ -861,6 +867,24 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: "run": _update_agent_conversation(projection.run, pid, new_conv), }) + case "phase_boundary_reached": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + entry = PhaseBoundaryEntry( + phase=payload.get("phase", ""), + message=payload.get("message", ""), + ) + new_conv = _flush_conversation(agent.conversation) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, entry], + }) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv), + }) + case "steering_queued": if projection.run is None: return projection diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index b4e4be2..b6011e3 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -290,6 +290,13 @@ async def _step_phase_boundary( from ..driver import _push_artifact_diff _push_artifact_diff(_app_state) + # Let the frontend know we're waiting for user input at phase boundary + _app_state.projection_store.push_event( + "phase_boundary_reached", + {"phase": _app_state.phase, "message": f"{_app_state.phase.replace('-', ' ').title()} is complete. Send a message to continue."}, + agent_id=agent.agent_id, + ) + # Check for already-buffered messages messages = drain_user_messages(_app_state) + drain_steering_messages(_app_state) From b6d478c691f58a6e18389c721e9be7d6d92db7e0 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:08:04 +0700 Subject: [PATCH 312/412] fix: strengthen plan-mode question guidance to prevent skipping --- frontend/src/components/ActivityFeed.tsx | 2 +- koan/lib/workflows.py | 11 ++++++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx index 16725e0..a16c6f2 100644 --- a/frontend/src/components/ActivityFeed.tsx +++ b/frontend/src/components/ActivityFeed.tsx @@ -1,5 +1,5 @@ import { useRef, useState } from 'react' -import { useStore, ConversationEntry, PhaseBoundaryEntry } from '../store/index' +import { useStore, ConversationEntry } from '../store/index' import { useAutoScroll } from '../hooks/useAutoScroll' import { Md } from './Md' import { ChatInput } from './ChatInput' diff --git a/koan/lib/workflows.py b/koan/lib/workflows.py index 7fcedf0..c27adb6 100644 --- a/koan/lib/workflows.py +++ b/koan/lib/workflows.py @@ -82,11 +82,12 @@ class Workflow: "- If you do dispatch scouts, 1\u20133 is typical for a plan workflow.\n" "\n" "## Question posture\n" - "- Ask questions when the task has genuine ambiguity that affects approach.\n" - "- For well-specified changes, a single round of 2\u20134 targeted questions\n" - " may suffice \u2014 or none at all if context is clear.\n" - "- Do not force questions when the task description and codebase provide\n" - " sufficient clarity.\n" + "- Always ask at least one round of questions. Even well-specified tasks\n" + " benefit from confirming assumptions and surfacing implicit decisions.\n" + "- A typical plan workflow needs 2\u20134 targeted questions covering: approach\n" + " confirmation, constraint verification, and scope boundaries.\n" + "- The user wants to be consulted \u2014 asking questions is a feature, not a\n" + " burden. When in doubt, ask.\n" "\n" "## User override\n" "The user can always ask you to go deeper, dispatch more scouts, or ask\n" From bfd4c26db0cbbee29aef639cddcbadb0aeafc0b0 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:32:35 +0700 Subject: [PATCH 313/412] refactor: remove landscape.md identity from intake SYSTEM_PROMPT MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The persistent orchestrator's context window carries all intake findings to downstream phases — no file needs to be written. Remove landscape.md as output target, the Output/Workflow/Tools sections (tools are self-descriptive via MCP), and tighten stakes language to focus on understanding quality rather than file quality. --- koan/phases/intake.py | 71 +++++++++++++++---------------------------- 1 file changed, 25 insertions(+), 46 deletions(-) diff --git a/koan/phases/intake.py b/koan/phases/intake.py index c551e5b..09167b8 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -1,8 +1,8 @@ # Intake phase -- 3-step workflow. # -# Step 1 (Gather) -- read task description, explore obvious files, dispatch scouts -# Step 2 (Deepen) -- process scout results, verify, deepen through dialogue -# Step 3 (Write) -- write landscape.md +# Step 1 (Gather) -- read task description, explore obvious files, dispatch scouts +# Step 2 (Deepen) -- process scout results, verify, deepen through dialogue +# Step 3 (Summarize) -- synthesize findings, present summary, transition # # Step 3 completes unconditionally -- no review gate. # Workflow scope framing (phase_instructions) appears at the top of step 1 guidance. @@ -18,40 +18,37 @@ STEP_NAMES: dict[int, str] = { 1: "Gather", 2: "Deepen", - 3: "Write", + 3: "Summarize", } SYSTEM_PROMPT = ( "You are an intake analyst for a coding task planner. You read a task" - " description, explore the codebase, and ask the user targeted questions until you" - " have complete context for planning.\n" + " description, explore the codebase, and ask the user targeted questions" + " until you have complete context for planning.\n" "\n" - "Your output -- a single landscape.md file -- is the sole foundation for all" - " downstream work. Every downstream phase and every implementation decision" - " depends on the quality and completeness of this file. Gaps here compound" - " into wrong plans and wrong code.\n" - "\n" - "An assumption you make without verifying will become a fact that downstream" - " phases treat as decided. A question you don't ask is an answer you're making" - " up. When the executor writes the wrong code because landscape.md contained an" - " unchecked assumption, that failure traces back to this phase.\n" + "Everything you learn here carries forward to planning and execution.\n" + "Gaps in your understanding compound into wrong plans and wrong code.\n" + "An assumption you make without verifying will become a fact that\n" + "downstream phases treat as decided. A question you don't ask is an\n" + "answer you're making up. When the executor writes the wrong code\n" + "because you accepted an unchecked assumption, that failure traces\n" + "back to this phase.\n" "\n" "## Your role\n" "\n" - "You gather, verify, and organize background information. You do NOT plan," - " design, or implement. You do NOT define what work should be done -- you" - " describe what exists and what was said.\n" + "You gather, verify, and organize background information. You do NOT\n" + "plan, design, or implement. You do NOT define what work should be\n" + "done -- you describe what exists and what was said.\n" "\n" "## Strict rules\n" "\n" "- MUST NOT infer decisions not explicitly stated in the task description.\n" "- MUST NOT add architectural opinions or suggest approaches.\n" "- MUST NOT produce implementation recommendations.\n" - "- MUST NOT define deliverables, work units, or scope boundaries -- that" - " belongs to downstream phases.\n" - "- MUST capture only what was explicitly said. If unclear, mark it as unresolved.\n" - "- SHOULD prefer multiple-choice questions when the answer space is bounded.\n" - "- SHOULD ground questions in codebase findings.\n" + "- MUST NOT define deliverables, work units, or scope boundaries -- that\n" + " belongs to downstream phases.\n" + "- MUST capture only what was explicitly said. If unclear, mark it as\n" + " unresolved.\n" "\n" "## Thinking style\n" "\n" @@ -64,30 +61,12 @@ " say, stop. Do not recap what you just worked out.\n" "- State things once. Never restate something from earlier in the same\n" " reasoning block or from a prior step.\n" - "- Use compressed notation: -> for flow, [OK] exists, [FAIL] missing, [!!] conflict,\n" - " therefore. Abbreviate freely (fn, dep, impl, cfg, db, auth, mw, req, resp).\n" - " Bullets and sentence fragments over full prose.\n" - "\n" - "These rules apply to your internal reasoning only. Tool arguments (scout\n" - "prompts, questions) and written artifacts (landscape.md) should remain\n" - "clear and complete.\n" - "\n" - "## Workflow\n" - "\n" - "You work in three steps: gather context (task description + codebase + scouts)," - " deepen your understanding through dialogue with the user, then write landscape.md.\n" - "\n" - "## Output\n" - "\n" - "One file: **landscape.md** in the run directory.\n" - "\n" - "## Tools\n" + "- Use compressed notation: -> for flow, [OK] exists, [FAIL] missing,\n" + " [!!] conflict, therefore. Abbreviate freely (fn, dep, impl, cfg, db,\n" + " auth, mw, req, resp). Bullets and sentence fragments over full prose.\n" "\n" - "- Read tools (read, bash, grep, glob, find, ls) -- reading the codebase.\n" - "- `koan_request_scouts` -- request parallel codebase exploration.\n" - "- `koan_ask_question` -- ask the user clarifying questions.\n" - "- `write` / `edit` -- for writing landscape.md (final step only).\n" - "- `koan_complete_step` -- signal step completion.\n" + "These rules apply to your internal reasoning only. Tool arguments\n" + "(scout prompts, questions to the user) should remain clear and complete.\n" ) From 0776f664326a95e5825dd70bb531df0d1b7d6be8 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:33:04 +0700 Subject: [PATCH 314/412] =?UTF-8?q?refactor:=20clean=20intake=20step=202?= =?UTF-8?q?=20=E2=80=94=20remove=20landscape.md=20refs,=20strengthen=20fol?= =?UTF-8?q?low-ups?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace 'downstream phases work from landscape.md alone' with context-window framing. Make follow-up question directive active ('identify new unknowns') rather than passive ('if new ambiguities surface'). Remove 'downstream planner' specificity. --- koan/phases/intake.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/koan/phases/intake.py b/koan/phases/intake.py index 09167b8..afac109 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -169,9 +169,9 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "is to build genuine, verified understanding by reading code, identifying gaps,", "and asking the user targeted questions.", "", - "This is the only phase where the user can be consulted. After intake, all", - "downstream phases work from landscape.md alone. Anything you get wrong here", - "will silently propagate through planning and execution.", + "This is the primary phase for user dialogue. The understanding you", + "build here carries directly into planning and execution. Anything you", + "get wrong will silently propagate.", "", "## 1. Process scout results", "", @@ -227,14 +227,16 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "### c) Ask follow-up questions", "", - "If new ambiguities surface, call `koan_ask_question` again.", + "After each round of answers, identify new unknowns that surfaced.", + "If any are marked ASK, call `koan_ask_question` again.", "The workflow context (step 1) guides how many rounds are appropriate.", "", "### d) When are you done?", "", "You are done deepening when:", "- Every area relevant to the task has been verified against the codebase.", - "- You can explain the full context to a downstream planner without hedging.", + "- You can explain the full context to someone writing an implementation", + " plan without hedging.", "- No answer you received left you with a 'I think I know what they mean'", " feeling -- you either confirmed it or asked.", ], From fb5abd275a15a8269f5ae8adfcd9158e26aca911 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:33:40 +0700 Subject: [PATCH 315/412] refactor: rewrite intake step 3 from 'write landscape.md' to 'summarize' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The persistent orchestrator's context window IS the landscape — writing a file is redundant. Step 3 now instructs the orchestrator to synthesize findings into a summary presented in chat, then call koan_complete_step to trigger the phase boundary with transition options. --- koan/phases/intake.py | 73 ++++++++++--------------------------------- 1 file changed, 16 insertions(+), 57 deletions(-) diff --git a/koan/phases/intake.py b/koan/phases/intake.py index afac109..ebcb565 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -244,68 +244,27 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: if step == 3: lines = [ - f"Write `{ctx.run_dir}/landscape.md`." - if ctx.run_dir - else "Write `landscape.md` to the run directory.", - "This file is the sole input for all downstream phases. Write it carefully.", + "Synthesize what you learned and present a summary to the user.", "", - "## Formatting rules (apply to all sections)", + "## What to summarize", "", - "- **File references**: Always use markdown link format: `[display name](relative/path)`.", - " After each reference, briefly state what the file contains or why it matters.", - " Example: `[base-phase.ts](src/planner/phases/base-phase.ts) -- abstract lifecycle for all phase subagents`.", - " Never use bare paths.", - "- **Section headings**: Use exactly the heading names below. Downstream agents locate content by heading.", - "- **Content rule**: Describe what IS, not what SHOULD be done. No recommendations, no deliverables, no implementation suggestions.", + "Present a concise summary covering:", "", - "## Required sections", + "- **Task scope**: What is being built or changed, in the user's framing.", + "- **Key codebase findings**: The most important things you discovered about", + " the relevant code — entry points, current behavior, integration points.", + "- **Decisions made**: Every question you asked and the user's answer.", + "- **Constraints**: Technical, timeline, or compatibility boundaries.", + "- **Open items**: Anything still unresolved (if any).", "", - "### Task Summary", - "What is being built or changed, in the user's own framing.", - "State the scope as the user described it -- what areas of the codebase are affected and why.", - "Do NOT decompose this into deliverables or work units. A downstream agent will do that.", + "Describe what IS, not what SHOULD be done. No recommendations, no", + "deliverables, no implementation suggestions.", "", - "### Prior Art", - "Previous attempts, referenced plans, related systems, or prior conversations mentioned.", - "If none: (none referenced)", + "## After summarizing", "", - "### Codebase Findings", - "Key findings from scouts, organized by area of the codebase (not by scout task).", - "", - "For each area, include:", - "- **Entry points**: files, functions, or modules that are the primary sites of interest.", - "- **Current behavior**: how the relevant code works today.", - "- **Patterns**: recurring patterns, conventions, or idioms observed in this area.", - "- **Integration points**: how this area connects to other parts of the system.", - "", - "If no scouts were needed: (no codebase exploration was needed)", - "", - "### Project Conventions", - "Where to find coding standards and patterns for this project -- pointers to sources,", - "not the conventions themselves.", - "", - "### Decisions", - "Every question asked and the user's answer.", - "Format: **Q:** [question] / **A:** [answer]", - "If no questions were needed: (no questions were needed -- context was sufficient)", - "", - "### Constraints", - "All constraints discovered: from task description, codebase, user answers.", - "If none: (none identified)", - "", - "### Open Items", - "Anything unresolved.", - "If none: (none)", - "", - "## Pre-write verification", - "", - "Before writing, verify landscape.md is complete -- a downstream agent must be able", - "to understand the full background from this file alone.", - "", - "## After writing", - "", - "landscape.md is now available in the artifacts panel for review.", - "Call `koan_complete_step` to signal phase completion.", + "Call `koan_complete_step`. The phase boundary will provide suggested", + "next phases and their descriptions. Present them to the user and ask", + "which direction they want to go.", ] return StepGuidance(title=STEP_NAMES[3], instructions=lines) @@ -317,7 +276,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: def get_next_step(step: int, ctx: PhaseContext) -> int | None: if step < 3: return step + 1 - # Step 3 (Write): terminal — no review gate. + # Step 3 (Summarize): terminal — no review gate. return None From 06ab65fd4e256eaf0bfce723676f871dc71f394b Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:34:24 +0700 Subject: [PATCH 316/412] =?UTF-8?q?refactor:=20clean=20workflow=20phase=5F?= =?UTF-8?q?guidance=20=E2=80=94=20remove=20landscape.md,=20hedging,=20spec?= =?UTF-8?q?ificity?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plan intake: 'typically a focused change' → 'a focused change'. Remove plan-spec/plan.md naming from downstream section — the model needs to know what the planner needs, not the phase name. Remove landscape.md from execute artifact list. Milestones: 'may span' → 'spanning'. --- koan/lib/workflows.py | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/koan/lib/workflows.py b/koan/lib/workflows.py index c27adb6..f8bacf4 100644 --- a/koan/lib/workflows.py +++ b/koan/lib/workflows.py @@ -65,26 +65,26 @@ class Workflow: phase_guidance={ "intake": ( "## Scope\n" - "This is a **plan** workflow \u2014 typically a focused change touching a\n" - "bounded area of the codebase.\n" + "This is a **plan** workflow \u2014 a focused change touching a bounded\n" + "area of the codebase.\n" "\n" - "## Downstream consumer\n" - "The landscape.md you produce feeds into **plan-spec**, which writes a\n" - "single implementation plan (plan.md). The plan-spec phase needs enough\n" - "context to write specific file-level instructions, but does not need\n" - "exhaustive coverage of the entire codebase.\n" + "## Downstream\n" + "The understanding you build here feeds into an implementation plan.\n" + "The planner needs enough context to write specific file-level\n" + "instructions, but does not need exhaustive coverage of the entire\n" + "codebase.\n" "\n" "## Investigation posture\n" "- **Prefer direct reading.** For focused changes, reading the referenced\n" - " files yourself is usually faster and more precise than dispatching scouts.\n" + " files yourself is faster and more precise than dispatching scouts.\n" "- **Dispatch scouts** when the task references subsystems you're unfamiliar\n" " with, or when dependency tracing would require opening more than ~10 files.\n" - "- If you do dispatch scouts, 1\u20133 is typical for a plan workflow.\n" + "- If you dispatch scouts, 1\u20133 is typical for a plan workflow.\n" "\n" "## Question posture\n" "- Always ask at least one round of questions. Even well-specified tasks\n" " benefit from confirming assumptions and surfacing implicit decisions.\n" - "- A typical plan workflow needs 2\u20134 targeted questions covering: approach\n" + "- A plan workflow needs 2\u20134 targeted questions covering: approach\n" " confirmation, constraint verification, and scope boundaries.\n" "- The user wants to be consulted \u2014 asking questions is a feature, not a\n" " burden. When in doubt, ask.\n" @@ -96,8 +96,7 @@ class Workflow: "execute": ( "## What to hand off\n" "Call `koan_request_executor` with:\n" - "- **artifacts**: `[\"plan.md\"]` \u2014 the implementation plan. Include\n" - " `\"landscape.md\"` if it contains context beyond what's in the plan.\n" + "- **artifacts**: `[\"plan.md\"]` \u2014 the implementation plan.\n" "- **instructions**: Key decisions from plan-review, user clarifications,\n" " or constraints. Do NOT repeat plan.md contents \u2014 the executor reads\n" " it directly. Instructions are for context that isn't in the files.\n" @@ -125,14 +124,14 @@ class Workflow: phase_guidance={ "intake": ( "## Scope\n" - "This is a **milestones** workflow \u2014 a broad initiative that may span\n" - "multiple subsystems and require significant codebase exploration.\n" + "This is a **milestones** workflow \u2014 a broad initiative spanning\n" + "multiple subsystems requiring significant codebase exploration.\n" "\n" - "## Downstream consumer\n" - "The landscape.md you produce feeds into milestone decomposition and\n" - "multi-phase planning. Downstream phases need comprehensive coverage:\n" - "every affected subsystem, integration point, and constraint must be\n" - "documented.\n" + "## Downstream\n" + "The understanding you build here feeds into milestone decomposition\n" + "and multi-phase planning. Downstream phases need comprehensive\n" + "coverage: every affected subsystem, integration point, and constraint\n" + "must be documented.\n" "\n" "## Investigation posture\n" "- **Dispatch scouts broadly.** Explore every subsystem the task touches\n" From b87fd7f68a5cfd58bb63f656333074b86d8406d1 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:34:46 +0700 Subject: [PATCH 317/412] refactor: remove landscape.md from plan-spec prompts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The orchestrator already has intake context in its window. Replace 'read landscape.md' with 'review what you learned during intake'. Remove the 'MUST read landscape.md' strict rule. Reframe verification as 'do not rely on intake memory alone — verify against actual code'. --- koan/phases/plan_spec.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/koan/phases/plan_spec.py b/koan/phases/plan_spec.py index 24838c7..0c124ba 100644 --- a/koan/phases/plan_spec.py +++ b/koan/phases/plan_spec.py @@ -1,6 +1,6 @@ # Plan-spec phase -- 2-step workflow. # -# Step 1 (Analyze) -- read landscape.md and codebase; no writes +# Step 1 (Analyze) -- review intake context and codebase; no writes # Step 2 (Write) -- write plan.md to the run directory # # Scope: "plan" -- specific to the plan workflow. @@ -47,7 +47,6 @@ "\n" "## Strict rules\n" "\n" - "- MUST read landscape.md before writing the plan.\n" "- MUST read the codebase files the plan references. Verify paths, signatures,\n" " and types before including them in the plan.\n" "- MUST NOT write code -- write instructions for an executor that will write code.\n" @@ -64,11 +63,11 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "## What to read", "", - f"1. Read `{ctx.run_dir}/landscape.md` -- understand the task, codebase" - " context, decisions, and constraints.", + "1. Review what you learned during intake \u2014 the task scope, codebase", + " findings, decisions, and constraints are in your context.", "2. Read every file the plan will reference. Open the actual source files", " to verify function signatures, type names, and integration points.", - " Do not rely on landscape.md's descriptions alone.", + " Do not rely on intake memory alone \u2014 verify against the actual code.", "", "## What to analyze", "", @@ -113,7 +112,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "Order steps so that each step's dependencies are satisfied by prior steps.", "", "### Constraints", - "Hard boundaries the executor must respect (from landscape.md Constraints section).", + "Hard boundaries the executor must respect (from intake findings).", "", "### Verification", "How to verify the implementation is correct (tests to run, behaviors to check).", From 161fbdf1fde11b987feb32b0ea91b7c58a869e04 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:35:02 +0700 Subject: [PATCH 318/412] refactor: remove landscape.md from plan-review prompts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace 'read landscape.md' with 'review intake findings in your context'. Remove the compound 'read landscape.md and plan.md' strict rule — only plan.md needs to be read from disk. All completeness checks now reference 'intake findings' instead of a file. --- koan/phases/plan_review.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/koan/phases/plan_review.py b/koan/phases/plan_review.py index 4c9faf5..6a21ec1 100644 --- a/koan/phases/plan_review.py +++ b/koan/phases/plan_review.py @@ -1,6 +1,6 @@ # Plan-review phase -- 2-step workflow. # -# Step 1 (Read) -- read landscape.md and plan.md; no writes +# Step 1 (Read) -- review intake context and plan.md; no writes # Step 2 (Evaluate) -- evaluate the plan and report findings via chat # # Advisory only: findings are reported in chat, not written to a file. @@ -34,7 +34,7 @@ "\n" "## Evaluation dimensions\n" "\n" - "- **Completeness**: Does the plan cover every requirement from landscape.md?\n" + "- **Completeness**: Does the plan cover every requirement from the intake findings?\n" "- **Correctness**: Are the file paths, function names, and interfaces accurate?\n" " Verify against the actual codebase.\n" "- **Feasibility**: Are the implementation steps actionable as described? Would\n" @@ -44,7 +44,7 @@ "\n" "## Strict rules\n" "\n" - "- MUST read landscape.md and plan.md before evaluating.\n" + "- MUST read plan.md before evaluating.\n" "- MUST read the codebase files the plan references. Verify claims.\n" "- MUST NOT modify plan.md.\n" "- MUST NOT flag issues the executor can trivially resolve.\n" @@ -60,7 +60,8 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "## What to read", "", - f"1. Read `{ctx.run_dir}/landscape.md` -- understand requirements and constraints.", + "1. Review the intake findings in your context \u2014 requirements, constraints,", + " codebase structure, and user decisions.", f"2. Read `{ctx.run_dir}/plan.md` -- read every section from start to finish.", "3. Read the codebase files the plan references. For each claim the plan makes", " (file path, function name, interface, type), verify it against the actual source.", @@ -70,7 +71,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "After reading, you should be able to answer:", "- What does the plan claim to change, and in which files?", "- Are those files and functions real and accurately described?", - "- Does the plan cover all requirements from landscape.md?", + "- Does the plan cover all requirements from the intake findings?", "- Are the implementation steps in the right order?", "", "Do NOT write an evaluation yet. Comprehend first.", @@ -87,7 +88,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "## What to evaluate", "", - "**Completeness**: Does the plan cover every requirement from landscape.md?", + "**Completeness**: Does the plan cover every requirement from the intake findings?", "List any requirements not addressed.", "", "**Correctness**: Are file paths, function names, and interfaces accurate?", From 0e2f7f5ae0f96faa41d3692b22401ae2585c85d5 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:35:24 +0700 Subject: [PATCH 319/412] refactor: remove stale tool-list claim from orchestrator system prompt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The claim 'step 1 guidance for each phase lists the tools' is no longer true after removing the Tools section from intake. Tools are self-descriptive via MCP — the orchestrator discovers them naturally. --- koan/phases/__init__.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index 6644fb5..02b9d9d 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -75,8 +75,7 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> "Rules:\n" "- Only call koan_set_phase after the user has confirmed the direction.\n" "- When the user indicates they are done, or all phases are complete, exit gracefully.\n" - "- Available tools change depending on the current phase. The step 1 guidance" - " for each phase lists the tools relevant to that phase." + "- Available tools change depending on the current phase." ) From 258068b820b3b99f07d54306874043820e21c594 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:36:50 +0700 Subject: [PATCH 320/412] test: update phase tests for landscape.md removal Intake step 3 test now checks for 'Summarize' title instead of landscape.md path. Plan-spec and plan-review tests check for 'intake' context reference instead of landscape.md. Executor test uses plan.md only. --- tests/test_phases.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/tests/test_phases.py b/tests/test_phases.py index 0c936d8..6843183 100644 --- a/tests/test_phases.py +++ b/tests/test_phases.py @@ -60,11 +60,12 @@ def test_step_1_guidance_with_workflow_name(self): text = "\n".join(g.instructions) assert "plan" in text - def test_step_3_guidance_references_run_dir(self): + def test_step_3_guidance_is_summarize(self): ctx = _ctx(run_dir="/tmp/myrun") g = intake.step_guidance(3, ctx) + assert g.title == "Summarize" text = "\n".join(g.instructions) - assert "/tmp/myrun/landscape.md" in text + assert "summary" in text.lower() # -- Brief Writer -------------------------------------------------------------- @@ -106,11 +107,11 @@ def test_total_steps_is_2(self): def test_scope_is_plan(self): assert plan_spec.SCOPE == "plan" - def test_step_1_guidance_references_run_dir(self): + def test_step_1_guidance_references_intake_context(self): ctx = _ctx(run_dir="/tmp/myrun") g = plan_spec.step_guidance(1, ctx) text = "\n".join(g.instructions) - assert "landscape.md" in text + assert "intake" in text.lower() def test_step_2_guidance_references_plan_md(self): ctx = _ctx(run_dir="/tmp/myrun") @@ -139,11 +140,11 @@ def test_total_steps_is_2(self): def test_scope_is_plan(self): assert plan_review.SCOPE == "plan" - def test_step_1_guidance_references_landscape_and_plan(self): + def test_step_1_guidance_references_intake_and_plan(self): ctx = _ctx(run_dir="/tmp/myrun") g = plan_review.step_guidance(1, ctx) text = "\n".join(g.instructions) - assert "landscape.md" in text + assert "intake" in text.lower() assert "plan.md" in text @@ -218,11 +219,10 @@ def test_scope_is_general(self): assert executor.SCOPE == "general" def test_step_1_guidance_with_artifacts(self): - ctx = _ctx(run_dir="/tmp/myrun", executor_artifacts=["plan.md", "landscape.md"]) + ctx = _ctx(run_dir="/tmp/myrun", executor_artifacts=["plan.md"]) g = executor.step_guidance(1, ctx) text = "\n".join(g.instructions) assert "/tmp/myrun/plan.md" in text - assert "/tmp/myrun/landscape.md" in text def test_step_1_guidance_with_phase_instructions(self): ctx = _ctx(phase_instructions="Key constraint: don't touch auth module.") From 91387d823d3b244f2f958f6698d8bc17e51e24fa Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 16:37:21 +0700 Subject: [PATCH 321/412] refactor: update koan_request_executor docstring example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove landscape.md from the example artifacts list — the plan workflow no longer produces this file. --- koan/web/mcp_endpoint.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index b6011e3..43f156c 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -617,7 +617,7 @@ async def koan_request_executor( Args: artifacts: File paths relative to run directory that the executor must read before coding. - Example: ["plan.md", "landscape.md"] + Example: ["plan.md"] instructions: Free-form context for the executor — key decisions, constraints, or user direction not captured in the artifact files. From 5095d1874aa3bb834395d89c146024c64e139d23 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 18:05:05 +0700 Subject: [PATCH 322/412] refactor: describe split-panel layout in koan_ask_question tool and intake prompt The tool docstring now explains the two-panel rendering: left panel shows context as reference material (markdown with code, bullets, bold), right panel shows the decision question and options. This guides the LLM to write richer context content and crisper question text. Intake step 2 guidance updated to match: explains the split-panel card layout and coaches the LLM to use context for reference material. --- koan/phases/intake.py | 13 ++++++++++--- koan/web/mcp_endpoint.py | 21 +++++++++++++++++---- 2 files changed, 27 insertions(+), 7 deletions(-) diff --git a/koan/phases/intake.py b/koan/phases/intake.py index ebcb565..cb098b1 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -208,14 +208,21 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "For every unknown marked ASK, formulate a question.", "", - "Call `koan_ask_question` with your questions. Formatting rules:", + "Call `koan_ask_question` with your questions. The UI renders a", + "split-panel card: context on the left as reference material, question", + "and options on the right as the decision.", + "", + "Formatting rules:", "- Prefer multiple-choice when the answer space is bounded.", "- Option labels are plain text -- no letter prefixes like (a)/(b), no numbering.", "- Do NOT include 'Other', 'None of the above', or similar meta-options.", " The UI provides a free-text input automatically.", - "- Put background and rationale in the `context` field, not in the option labels.", + "- Use the `context` field for reference material the user reads while", + " deciding: codebase findings, code snippets, tradeoff summaries.", + " This renders in a dedicated left panel -- write rich markdown here.", + "- Keep the `question` field crisp -- it's the decision prompt.", "- Ground questions in specific findings:", - " 'Scout found X -- should this story follow the same pattern?'", + " 'Scout found X -- should this follow the same pattern?'", "", "### b) Deepen with each answer", "", diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 43f156c..ae91781 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -546,18 +546,31 @@ async def run_scout(scout_task: dict) -> str | None: @mcp.tool(name="koan_ask_question") async def koan_ask_question(questions: list[dict] | None = None) -> str: - """Ask the user one or more clarifying questions. The UI renders these as - interactive cards — one per question — with radio buttons or checkboxes. + """Ask the user one or more clarifying questions. + + The UI renders a split-panel card for each question: + - LEFT PANEL ("Context"): reference material the user reads while + deciding. Write markdown here — code snippets, bullet lists, bold + terms, file references. This is your chance to show the user what + you found and why the question matters. Think of it as an + illustration panel, not a preamble. + - RIGHT PANEL ("Decision"): the question text and selectable options. + This is the action side — keep the question crisp. + + When context is omitted, the card renders as a single column with + just the question and options. Each dict in `questions` must have: - - question (str): The question text (rendered as markdown). + - question (str): The decision question (rendered as markdown). - options (list[dict]): Choices. Each option has: - value (str): Machine key returned in the answer. - label (str): Human-readable label shown in the UI. - recommended (bool, optional): Pre-select this option. Optional fields: - - context (str): Background/rationale shown above the question (markdown). + - context (str): Background shown in the left reference panel + (markdown). Include codebase findings, tradeoff summaries, + or relevant code snippets that inform the decision. - multi (bool): Allow selecting multiple options (default false). Format rules for options: From 56c098336c6810d73be1188b79476cd544fd9d7b Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 18:06:08 +0700 Subject: [PATCH 323/412] feat: redesign question cards as split reference panels Questions with context render as a two-column layout: left panel shows context as scrollable reference material (CONTEXT label, inset bg), right panel shows the decision question and selectable options (DECISION label in copper). Actions (Back/Use Defaults/Submit) move inside the card with a top border separator. Questions without context render single-column with just the decision panel. The split layout guides users to scan reference material while making their selection. --- .../src/components/interactions/AskWizard.tsx | 91 +++++++++++-------- frontend/src/styles/components.css | 70 +++++++++++--- 2 files changed, 112 insertions(+), 49 deletions(-) diff --git a/frontend/src/components/interactions/AskWizard.tsx b/frontend/src/components/interactions/AskWizard.tsx index b44072f..822ddd6 100644 --- a/frontend/src/components/interactions/AskWizard.tsx +++ b/frontend/src/components/interactions/AskWizard.tsx @@ -52,6 +52,7 @@ function QuestionCard({ otherText, onAnswer, onOtherText, + children, }: { question: AskQuestion qIdx: number @@ -59,6 +60,7 @@ function QuestionCard({ otherText: string onAnswer: (qIdx: number, val: string | string[] | null) => void onOtherText: (qIdx: number, text: string) => void + children?: React.ReactNode }) { const selected = Array.isArray(answer) ? answer : answer ? [answer] : [] @@ -88,18 +90,12 @@ function QuestionCard({ // code never parses or rewrites LLM text. const opts = normalizeOptions(question.options as (string | Record<string, unknown>)[]) - return ( - <div className="question-card"> - <div className="question-header"> - Question {qIdx + 1} - </div> - {question.context && ( - <div className="question-context"><Md>{question.context}</Md></div> - )} + const decisionContent = ( + <> + <div className="question-decision-label">Decision</div> <div className="question-text"><Md>{question.question}</Md></div> {isFreeText(question) ? ( - /* Free-form text input — no predefined options */ <div className="free-text-area"> <textarea className="free-text-input" @@ -110,7 +106,6 @@ function QuestionCard({ /> </div> ) : ( - /* Standard option selection — always includes an "Other" text input */ <> {question.multi && ( <div className="question-multi-hint">Select all that apply</div> @@ -148,6 +143,30 @@ function QuestionCard({ </div> </> )} + </> + ) + + const hasContext = !!question.context + + return ( + <div className={`question-card${hasContext ? ' question-card--split' : ''}`}> + {hasContext ? ( + <> + <div className="question-context-panel"> + <div className="question-context-label">Context</div> + <div className="question-context"><Md>{question.context!}</Md></div> + </div> + <div className="question-decision-panel"> + {decisionContent} + {children} + </div> + </> + ) : ( + <div className="question-decision-panel question-decision-panel--full"> + {decisionContent} + {children} + </div> + )} </div> ) } @@ -233,34 +252,34 @@ export function AskWizard() { otherText={otherTexts[currentIdx] ?? ''} onAnswer={handleAnswer} onOtherText={handleOtherText} - /> + > + {submitError && <div className="no-runners-msg">{submitError}</div>} - {submitError && <div className="no-runners-msg">{submitError}</div>} - - <div className="form-actions"> - {currentIdx > 0 && ( - <button className="btn btn-secondary" onClick={handleBack}> - Back - </button> - )} - <button className="btn btn-secondary" onClick={handleUseDefaults}> - Use Defaults - </button> - {currentIdx < total - 1 && ( - <button className="btn btn-primary" onClick={handleNext}> - Next - </button> - )} - {currentIdx === total - 1 && ( - <button - id="btn-submit-answers" - className="btn btn-primary" - onClick={handleSubmit} - > - Submit + <div className="question-actions"> + {currentIdx > 0 && ( + <button className="btn btn-secondary" onClick={handleBack}> + Back + </button> + )} + <button className="btn btn-secondary" onClick={handleUseDefaults}> + Use Defaults </button> - )} - </div> + {currentIdx < total - 1 && ( + <button className="btn btn-primary" onClick={handleNext}> + Next + </button> + )} + {currentIdx === total - 1 && ( + <button + id="btn-submit-answers" + className="btn btn-primary" + onClick={handleSubmit} + > + Submit + </button> + )} + </div> + </QuestionCard> </div> </div> ) diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index ec4bec1..4d63e36 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -233,25 +233,39 @@ background: var(--bg-elevated); border: 1px solid var(--border); border-radius: var(--radius-lg); - padding: var(--space-6); + overflow: hidden; margin-bottom: var(--space-4); } -.question-header { +/* Split layout: context panel left, decision panel right */ +.question-card--split { + display: flex; +} + +/* -- Context panel (left) -- */ +.question-context-panel { + width: 44%; + flex-shrink: 0; + padding: var(--space-6); + background: var(--bg); + border-right: 1px solid var(--border); + overflow-y: auto; +} + +.question-context-label { font-family: var(--font-mono); font-size: var(--font-size-xs); - color: var(--text-muted); + color: var(--text-ghost); text-transform: uppercase; - letter-spacing: 0.06em; - margin-bottom: var(--space-2); + letter-spacing: 0.1em; + margin-bottom: var(--space-4); } .question-context { font-family: var(--font-sans); - font-size: var(--font-size-md); - color: var(--text-muted); - line-height: 1.6; - margin-bottom: var(--space-4); + font-size: var(--font-size-sm); + color: var(--text); + line-height: 1.7; } .question-context p { @@ -265,12 +279,12 @@ .question-context code, .question-text code, .option-text code { - background: var(--bg); + background: var(--bg-inset); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: 1px 5px; font-family: var(--font-mono); - font-size: 0.9em; + font-size: 0.85em; } .question-context strong, @@ -297,13 +311,33 @@ margin: 2px 0; } +/* -- Decision panel (right, or full-width when no context) -- */ +.question-decision-panel { + flex: 1; + padding: var(--space-6); + min-width: 0; +} + +.question-decision-panel--full { + /* Full-width single-column when no context */ +} + +.question-decision-label { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--copper); + text-transform: uppercase; + letter-spacing: 0.1em; + margin-bottom: var(--space-4); +} + .question-text { font-family: var(--font-sans); font-size: 18px; - font-weight: 500; + font-weight: 600; color: var(--text-strong); margin-bottom: var(--space-4); - line-height: 1.6; + line-height: 1.5; } .question-multi-hint { @@ -313,6 +347,16 @@ margin-bottom: var(--space-2); } +/* Actions inside the decision panel */ +.question-actions { + display: flex; + gap: var(--space-4); + margin-top: var(--space-6); + padding-top: var(--space-4); + border-top: 1px solid var(--border); + align-items: center; +} + /* ---- Option list ---- */ .options-list { display: flex; From f51a0412bad177814cb3b62115a061720e435470 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 20:23:29 +0700 Subject: [PATCH 324/412] fix: restore landing page card styling broken by question card redesign LandingPage was reusing question-card/question-header CSS classes, which lost padding and header styles in the split-panel redesign. Switch to the generic .card class (which retains padding) and a new .launch-section-label for the Workflow/Description/Configuration headers. --- frontend/src/components/LandingPage.tsx | 12 ++++++------ frontend/src/styles/components.css | 10 ++++++++++ 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/frontend/src/components/LandingPage.tsx b/frontend/src/components/LandingPage.tsx index cac0127..0ee6964 100644 --- a/frontend/src/components/LandingPage.tsx +++ b/frontend/src/components/LandingPage.tsx @@ -140,8 +140,8 @@ export function LandingPage() { </div> {/* Workflow card */} - <div className="question-card"> - <div className="question-header">Workflow</div> + <div className="card"> + <div className="launch-section-label">Workflow</div> <div className="launch-workflow-grid"> <button className={`launch-workflow-card${workflow === 'plan' ? ' selected' : ''}`} @@ -165,8 +165,8 @@ export function LandingPage() { </div> {/* Description card */} - <div className="question-card"> - <div className="question-header">Description</div> + <div className="card"> + <div className="launch-section-label">Description</div> <div className="launch-description-hint">What should this run accomplish?</div> <textarea id="task-input" @@ -179,8 +179,8 @@ export function LandingPage() { </div> {/* Configuration card */} - <div className="question-card"> - <div className="question-header">Configuration</div> + <div className="card"> + <div className="launch-section-label">Configuration</div> {/* Profile */} <div className="launch-config-group"> diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 4d63e36..e457bb9 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -1375,6 +1375,16 @@ /* ---- Launch page ---- */ +/* Section label for launch page cards */ +.launch-section-label { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--text-muted); + text-transform: uppercase; + letter-spacing: 0.06em; + margin-bottom: var(--space-2); +} + .launch-project-dir { display: flex; align-items: center; From 8a4ec4ee83ca15adde277fe7376dd6721576f689 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 20:27:31 +0700 Subject: [PATCH 325/412] fix: use stone surface background for question context panel The context panel was using var(--bg) which is the same cornsilk as the page background, making it visually disappear. Switch to var(--bg-surface) (stone #E0D8C8) which reads as a distinct reference panel against both the page and the white decision panel. --- frontend/src/styles/components.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index e457bb9..268917a 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -247,7 +247,7 @@ width: 44%; flex-shrink: 0; padding: var(--space-6); - background: var(--bg); + background: var(--bg-surface); border-right: 1px solid var(--border); overflow-y: auto; } From 02f7394f0c5f4d22f83bf5a69609d212e727f4c9 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 20:28:44 +0700 Subject: [PATCH 326/412] =?UTF-8?q?fix:=20improve=20context=20panel=20read?= =?UTF-8?q?ability=20=E2=80=94=20larger=20font,=20visible=20code,=20strong?= =?UTF-8?q?er=20label?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Context font: 13px → 15px (matches body text, no longer feels like a footnote) - CONTEXT label: text-ghost → text-muted (visible on stone background) - Code snippets: bg-inset → bg-elevated (white pops on stone, was invisible) --- frontend/src/styles/components.css | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 268917a..a75a758 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -255,7 +255,7 @@ .question-context-label { font-family: var(--font-mono); font-size: var(--font-size-xs); - color: var(--text-ghost); + color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.1em; margin-bottom: var(--space-4); @@ -263,9 +263,9 @@ .question-context { font-family: var(--font-sans); - font-size: var(--font-size-sm); + font-size: var(--font-size-md); color: var(--text); - line-height: 1.7; + line-height: 1.6; } .question-context p { @@ -279,7 +279,7 @@ .question-context code, .question-text code, .option-text code { - background: var(--bg-inset); + background: var(--bg-elevated); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: 1px 5px; From b61caeebb8dacdad5892750a4e16a17f67372b1e Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 20:37:06 +0700 Subject: [PATCH 327/412] feat: white-on-white context panel with copper left rule Replace stone background with white (bg-elevated) for the context panel. Add a 3px copper left rule to visually distinguish context from decision. Context text uses muted color, bold/strong uses regular text color, code snippets use cornsilk background (visible on white). Both panels top-aligned with natural card growth (no vertical centering). --- frontend/src/components/interactions/AskWizard.tsx | 6 ++++-- frontend/src/styles/components.css | 14 ++++++++++---- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/frontend/src/components/interactions/AskWizard.tsx b/frontend/src/components/interactions/AskWizard.tsx index 822ddd6..65dc5ff 100644 --- a/frontend/src/components/interactions/AskWizard.tsx +++ b/frontend/src/components/interactions/AskWizard.tsx @@ -153,8 +153,10 @@ function QuestionCard({ {hasContext ? ( <> <div className="question-context-panel"> - <div className="question-context-label">Context</div> - <div className="question-context"><Md>{question.context!}</Md></div> + <div className="question-context-rule"> + <div className="question-context-label">Context</div> + <div className="question-context"><Md>{question.context!}</Md></div> + </div> </div> <div className="question-decision-panel"> {decisionContent} diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index a75a758..d629b25 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -247,11 +247,16 @@ width: 44%; flex-shrink: 0; padding: var(--space-6); - background: var(--bg-surface); + background: var(--bg-elevated); border-right: 1px solid var(--border); overflow-y: auto; } +.question-context-rule { + border-left: 3px solid var(--copper); + padding-left: var(--space-4); +} + .question-context-label { font-family: var(--font-mono); font-size: var(--font-size-xs); @@ -264,7 +269,7 @@ .question-context { font-family: var(--font-sans); font-size: var(--font-size-md); - color: var(--text); + color: var(--text-muted); line-height: 1.6; } @@ -279,18 +284,19 @@ .question-context code, .question-text code, .option-text code { - background: var(--bg-elevated); + background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: 1px 5px; font-family: var(--font-mono); font-size: 0.85em; + color: var(--text); } .question-context strong, .question-text strong, .option-text strong { - color: var(--text-strong); + color: var(--text); font-weight: 600; } From e7f12392ec2dec66789f8a0dc4f0fe8d174fb87f Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 20:43:03 +0700 Subject: [PATCH 328/412] =?UTF-8?q?fix:=20quiet=20inline=20code=20in=20con?= =?UTF-8?q?text=20panel=20=E2=80=94=20mono=20font=20only,=20no=20bordered?= =?UTF-8?q?=20boxes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The context panel was visually overwhelming because every inline code span (file names, function names, types) rendered as a bordered box with background. With 2-3 per bullet line, it created a wall of visual noise. Context code now uses just the mono typeface with no border or background — typographically distinct but visually quiet. Decision panel code keeps the bordered box treatment. --- frontend/src/styles/components.css | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index d629b25..47b5c92 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -281,7 +281,17 @@ margin-bottom: 0; } -.question-context code, +/* Code in context panel: quiet — just mono font, no boxes. + Needs higher specificity to override .markdown code {} */ +.question-context .markdown code { + background: none; + border: none; + padding: 0; + font-size: 0.88em; + color: var(--text); +} + +/* Code in question text and options: visible boxes */ .question-text code, .option-text code { background: var(--bg); From 8e6636a0dec4ebb14acec5093f88cb0fea77ea64 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 4 Apr 2026 23:26:09 +0700 Subject: [PATCH 329/412] fix: textarea padding was zero due to undefined --space-3 variable The spacing scale defines --space-1 (4px), --space-2 (8px), --space-4 (16px) but not --space-3. Three references to var(--space-3) resolved to nothing, causing zero padding on the free-text textarea and missing margins on free-text-area and phase-boundary elements. Replace all with var(--space-4) (16px). --- frontend/src/styles/components.css | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index 47b5c92..d85cc14 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -512,13 +512,13 @@ /* Free-form text input (questions with no predefined options) */ .free-text-area { - margin-top: var(--space-3); + margin-top: var(--space-4); } .free-text-input { width: 100%; min-height: 100px; - padding: var(--space-3); + padding: var(--space-4); background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius-sm); @@ -1606,7 +1606,7 @@ font-size: var(--font-size-sm); border: 1px dashed var(--border); border-radius: var(--radius-md); - margin: var(--space-3) 0; + margin: var(--space-4) 0; background: var(--bg-elevated); } From d937ffd279719db1c73e32eaf1299e2411348c36 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 5 Apr 2026 17:39:11 +0700 Subject: [PATCH 330/412] fix: enforce minimum scout dispatches in intake gather --- koan/phases/intake.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/koan/phases/intake.py b/koan/phases/intake.py index cb098b1..18b2ff2 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -144,8 +144,8 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: " can examine multiple files, trace dependencies, and answer several", " related questions in a single run.", "", - "You can use both. Read what you can reach directly; scout what you can't.", - "The workflow context above (if present) tells you which posture to default to.", + "You MUST dispatch at least 2 scouts. This is mandatory regardless of task size.", + "Read what you can reach directly AND scout everything else.", "", "If dispatching scouts, each needs:", "- id: short kebab-case identifier (e.g., 'auth-and-permissions', 'data-layer')", From 03646591601551a867e105799b6cbf651dfcd407 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 5 Apr 2026 17:39:30 +0700 Subject: [PATCH 331/412] docs: replace design system with new visual language Navy/orange/teal palette replaces the warm earth-tone system. Mid-century modern geometric aesthetic. New token naming convention, component specifications, and layout patterns. --- docs/design-system.md | 787 +++++++++++------------------------------- 1 file changed, 193 insertions(+), 594 deletions(-) diff --git a/docs/design-system.md b/docs/design-system.md index 903c278..308a341 100644 --- a/docs/design-system.md +++ b/docs/design-system.md @@ -1,661 +1,260 @@ # Koan Design System -The definitive reference for Koan's visual language. Every UI decision — from -token values to component construction to layout patterns — is derived from -this document. When implementing or reviewing UI code, verify against these -specifications. +## Overview + +This document defines the complete visual language for koan's web UI. Every component must reference these tokens — nothing hardcodes values. The aesthetic is mid-century modern geometric: confident, warm, professional with controlled playfulness. Inspired by Lobotain's navy/orange/teal palette, Kolur's complementary duotones, and Japanese-influenced earthy pastels. + +## Color Palette + +### Core colors + +These are the three identity colors. They appear in the header, accents, status indicators, and interactive elements. + +| Token | Hex | Usage | +|---|---|---| +| `--color-navy` | `#2e3a5e` | Header bar, scout bar frame, primary text, artifact icons (dark), logo text | +| `--color-orange` | `#d4775a` | Primary accent, active states, running indicators, progress bars, primary buttons, decision borders, numbered list markers | +| `--color-teal` | `#5a9a8a` | Secondary accent, success/completion states, checkmarks in tool calls, completed progress segments, orchestrator dot, "recommended" badges | + +### Background surfaces + +These define the layering system. The hierarchy from back to front is: base → surface → card. Each layer must be visually distinguishable from its neighbors. + +| Token | Hex | Usage | +|---|---|---| +| `--bg-base` | `#f8f6f2` | Main content area background. Warm-tinted near-white — warm enough to avoid clinical, light enough to avoid brown. | +| `--bg-surface` | `#f3efe8` | Artifacts sidebar background. Slightly warmer and darker than base to create panel distinction. | +| `--bg-card` | `#ffffff` | Prose output cards, form sections, scout table interior, artifact cards, input fields. True white provides the strongest contrast against base. | +| `--bg-tool-row` | `#f0ede6` | Tool call rows (bash, read, edit). Sits between base and surface in warmth. | +| `--bg-thinking` | `#eae5f2` | Thinking/reasoning blocks. Lavender — in the cool family with navy but lighter, creating warm/cool interplay. | +| `--bg-step-guidance` | `#efece6` | Step guidance pill, model badges in scout table, "coming soon" badges. Neutral warm. | +| `--bg-completion` | `#e8f5ee` | Completion/success banners. Teal-family light green. | +| `--bg-selected` | `#fdf8f5` | Selected card state (e.g., selected workflow option). Very faint orange tint. | + +### Text colors + +| Token | Hex | Usage | +|---|---|---| +| `--text-primary` | `#2e3a5e` | Headings, prose body text, scout names, form labels. Same as navy — this is intentional, it ties text to the brand. | +| `--text-body` | `#4a4a5a` | Secondary body text within prose cards, list items, codebase findings. | +| `--text-muted` | `#9a8e7e` | Tool call type labels ("bash", "read"), metadata, timestamps, placeholder labels, column headers. | +| `--text-subtle` | `#7a6e60` | Step guidance text, form descriptions, secondary labels. | +| `--text-placeholder` | `#b0a498` | Input placeholder text ("Send feedback..."). | +| `--text-hint` | `#c8baa8` | Hint text below inputs ("Enter to send · Shift+Enter for newline"). | +| `--text-thinking` | `#3a3460` | Text inside thinking blocks. Dark purple for contrast against lavender. | +| `--text-thinking-label` | `#5a5080` | "THINKING" label text. Medium purple. | +| `--text-completion` | `#2a6a4a` | Completion banner text. Dark teal-green. | +| `--text-artifact-time` | `#a89888` | Artifact "modified X ago" timestamps. | + +### Text on dark backgrounds (navy header, scout bar frame) + +| Token | Hex | Usage | +|---|---|---| +| `--text-on-dark` | `#f0e8d8` | Primary text on navy. Warm off-white, not pure white. | +| `--text-on-dark-muted` | `rgba(240,232,216,0.55)` | Breadcrumb inactive segments, secondary labels on navy. | +| `--text-on-dark-subtle` | `rgba(240,232,216,0.4)` | Timestamps, tertiary info on navy. | +| `--text-on-dark-faint` | `rgba(255,255,255,0.15)` | Dividers, inactive progress segments, icon button borders on navy. | +| `--text-on-dark-scouts-muted` | `rgba(240,232,216,0.45)` | Scout summary labels ("running", "done") on navy. | + +### Border colors + +| Token | Hex | Usage | +|---|---|---| +| `--border-card` | `#eae6e0` | Card borders (prose cards, artifact cards). Faint warm line. | +| `--border-input` | `#c8c0b4` | Input field borders, text area borders. Distinctly visible against white and base backgrounds. | +| `--border-radio` | `#e0d8cc` | Radio option card borders, form element borders. Between card and input in weight. | +| `--border-divider` | `#e8e2d8` | Artifact sidebar dividers, table row separators, panel borders. | +| `--border-divider-light` | `#f0ebe4` | Scout table internal row separators. Very faint. | + +### Semantic status colors + +These are used exclusively for scout status indicators and similar operational state. + +| Token | Hex | Usage | +|---|---|---| +| `--status-running` | `#d4775a` | Running scout dots, active step labels. Same as orange accent. | +| `--status-done` | `#5a9a8a` | Completed scout dots. Same as teal accent. | +| `--status-queued` | `#b8aca0` | Queued count text. Desaturated warm. | +| `--status-failed` | `#c44` | Failed count text. Standard red — used sparingly. | + +## Typography ---- +### Font families -## 1. Design Principles +| Token | Value | Usage | +|---|---|---| +| `--font-display` | System serif stack (Georgia, "Times New Roman", serif) | Logo "koan" wordmark only. | +| `--font-body` | System sans-serif stack (-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif) | All UI text, headings, labels, prose, form elements. | +| `--font-mono` | Monospace stack ("SF Mono", "Fira Code", "Cascadia Code", monospace) | File paths, tool call commands, scout names, code inline, timestamps, model names, artifact filenames. | -Six principles, ordered by priority. When principles conflict, higher wins. +### Type scale -### 1.1 Warm Workshop +All weights are 400 (regular) or 500 (medium). Never use 600 or 700. -Koan feels like a well-made craft tool — wood, leather, paper. Earth tones, -natural textures, nothing clinical or cold. If a design choice feels -"tech-startup" or "developer-dark-mode," it's wrong. +| Token | Size | Weight | Usage | +|---|---|---|---| +| `--type-page-title` | 26px | 500 | "New Run" page title. Letter-spacing: -0.5px. | +| `--type-logo` | 17px | 500 | "koan" wordmark in header. Uses `--font-display`. Letter-spacing: -0.3px. | +| `--type-section-title` | 17px | 500 | "Gather Summary" and similar section headings within prose cards. | +| `--type-step-header` | 16px | 500 | Step name next to step indicator ("Gather", "Summarize"). | +| `--type-prose` | 15px | 400 | Agent prose output, decision question text, form field values. Line-height: 1.7. | +| `--type-body` | 14px | 400 | Body text within cards (findings, decisions list items, context descriptions). Line-height: 1.65. | +| `--type-step-indicator` | 14px | 500 | "step 1/3", "step 3/3" colored labels. | +| `--type-breadcrumb` | 13px | 400/500 | Header breadcrumb segments (400 for inactive, 500 for active). | +| `--type-tool-type` | 12px | 400 | Tool call type label ("bash", "read", "edit"). Uses `--text-muted`. | +| `--type-tool-path` | 12px | 400 | Tool call file paths. Uses `--font-mono`. | +| `--type-label` | 11px | 500 | Section labels ("ARTIFACTS", "CONTEXT", "DECISION", "SCOUTS", "THINKING"). Uppercase, letter-spacing: 1px. | +| `--type-badge` | 10px | 500 | "coming soon", "recommended", model badges, scout column headers. | +| `--type-timestamp` | 10px | 400 | "modified 2m ago" artifact timestamps. | -### 1.2 Breathing Space +### Inline code -Generous whitespace. Things float, they don't crowd. Accept showing less at -once in exchange for calm clarity. Padding is never too much; cramming is -always wrong. +Code tokens within prose use: `background: #f0ede6; padding: 1px 5px; border-radius: 3px; font-size: one step below surrounding text; color: #2e3a5e; font-family: var(--font-mono)`. -### 1.3 Paper on Paper +## Spacing -Flat design. No drop shadows, no gradients, no glassmorphism. Containment -comes from thin warm borders — like sheets of paper laid on a wooden desk. -Depth is implied by background color tiers, not by visual effects. +### Page-level spacing -### 1.4 Color is Earned +| Token | Value | Usage | +|---|---|---| +| `--page-padding` | 28px 32px | Main content area padding. | +| `--sidebar-padding` | 20px 16px | Artifacts sidebar padding. | +| `--header-height` | 50px | Header bar fixed height. | +| `--form-max-width` | 640px | Max width for standalone form pages ("New Run"). Centered. | +| `--form-page-padding` | 40px 24px | Padding around centered form content. | -Most of the interface is neutral (cream, white, warm browns). Saturated color -appears only where it carries meaning: status indicators, active states, -errors. If everything is colorful, nothing is. +### Component gaps -### 1.5 Weight, Not Decoration +| Token | Value | Usage | +|---|---|---| +| `--gap-content` | 20px | Between major content blocks in the stream (thinking → prose → tools → thinking). | +| `--gap-tool-rows` | 3px | Between individual tool call rows within a group. | +| `--gap-artifact-cards` | 10px | Between artifact cards in the sidebar. | +| `--gap-form-sections` | 28px | Between form card sections on the "New Run" page. | +| `--gap-radio-options` | 10px | Between radio option cards in elicitation. | +| `--gap-scout-summary` | 16px | Between scout summary count groups. | +| `--gap-progress-segments` | 3px | Between progress bar segments in header. | -Typography hierarchy comes from font weight and size, never from underlines, -all-caps body text, or decorative flourishes. The type system is a single -sans-serif family differentiated by weight. Mono is reserved strictly for -data, paths, and code. +### Component internal padding -### 1.6 Gentle Motion +| Token | Value | Usage | +|---|---|---| +| `--padding-card` | 14px 20px | Prose output cards. | +| `--padding-card-form` | 20px 24px | Form section cards, context/decision panels. | +| `--padding-tool-row` | 7px 14px | Individual tool call rows. | +| `--padding-step-guidance` | 8px 16px | Step guidance pill. | +| `--padding-artifact` | 10px 12px | Artifact cards in sidebar. | +| `--padding-scout-bar` | 14px 24px | Scout bar outer padding. | +| `--padding-scout-row` | 8px 14px | Scout table rows. | +| `--padding-input` | 14px 18px | Feedback input area. | +| `--padding-radio` | 12px 14px | Radio option cards. | -Animation is subtle and purposeful. Fade-ins for appearing content, smooth -transitions for state changes, a quiet pulse for "thinking." No bouncing, -no sliding panels, no attention-grabbing motion. The UI should feel still. +## Border Radius ---- +| Token | Value | Usage | +|---|---|---| +| `--radius-sm` | 3px | Inline code tags, model badges. | +| `--radius-md` | 6px | Tool call rows, progress bar segments, small buttons. | +| `--radius-lg` | 8px | Artifact cards, scout table, step guidance pill, input fields, form dropdowns. | +| `--radius-xl` | 10px | Prose cards, thinking blocks, feedback input, completion banner, radio options. | +| `--radius-2xl` | 12px | Form section cards, context/decision panels, page-level container. | +| `--radius-pill` | 20px | Pill-shaped badges ("coming soon", "recommended"). | +| `--radius-circle` | 50% | Status dots, radio buttons, logo circles, orchestrator dot. | -## 2. Design Tokens +## Component Specifications -All visual values. CSS custom properties live in `variables.css`. Every -component references tokens — never raw color codes or pixel values. +### Header bar -### 2.1 Color Palette +The header is a fixed 50px bar with `--color-navy` background. It contains the logo, breadcrumb navigation, progress segments, orchestrator info, elapsed time, and settings button. It spans the full width of the viewport. -#### Backgrounds +The logo is the "koan" wordmark in `--font-display` at 17px/500, colored `--text-on-dark`. To the left of the wordmark are two overlapping circles: a 16px circle in `--color-orange` (top-left) and a 10px circle in `--color-teal` (bottom-right). This geometric motif is the brand mark. -| Token | Value | Usage | -| --------------- | --------- | ---------------------------------- | -| `--bg` | `#FEFAE0` | Cornsilk base — the "desk" | -| `--bg-surface` | `#E0D8C8` | Stone — sidebars, panels, monitor | -| `--bg-elevated` | `#FFFFFF` | Cards, overlays — "paper on paper" | -| `--bg-inset` | `#D4CCB8` | Pressed/inset areas | +A 1px vertical divider at `rgba(255,255,255,0.15)` separates the logo from the breadcrumb. The breadcrumb shows phase and step as `Phase > Step` with a small chevron. The inactive segment uses `--text-on-dark-muted`, the active segment uses `--text-on-dark` at weight 500. -#### Text +Progress segments are 24px wide, 4px tall, with `--radius-md`. Completed segments use `--color-teal`, the active segment uses `--color-orange`, and future segments use `--text-on-dark-faint`. Gap between segments: 3px. -| Token | Value | Name | Usage | -| --------------- | --------- | ------------ | ------------------------------------ | -| `--text` | `#4A4428` | Olive-brown | Default body text | -| `--text-strong` | `#283618` | Black Forest | Headings, names, emphasis | -| `--text-muted` | `#7A7450` | Dried sage | Metadata, timestamps, secondary info | -| `--text-ghost` | `#A09A6E` | Faded straw | Placeholders, disabled states | +The settings button is a 30px square with `--radius-lg`, 1px border in `--text-on-dark-faint`, containing a 14px gear SVG icon stroked at `rgba(240,232,216,0.6)`. -#### Borders +### Prose output card -| Token | Value | Usage | -| ----------------- | --------- | -------------------------- | -| `--border` | `#C8C0A8` | Default card/panel borders | -| `--border-strong` | `#B8B098` | Dividers, emphasis borders | +White card (`--bg-card`) with `--radius-xl`, `0.5px solid --border-card` on all sides, plus a 3px `--color-orange` left border. Padding: `--padding-card`. Text is `--type-prose` in `--text-primary`. These cards contain the agent's spoken output — everything the agent says directly to the user (as opposed to thinking or tool calls). -#### Status — The Pigment Palette +### Thinking block -Based on the Olive Garden Feast palette. Use sparingly. +Lavender block (`--bg-thinking`) with `--radius-xl`. Padding: 16px 20px. Contains a label row with a small 14px navy circle (with a 6px `#b8b0d0` inner circle) followed by "THINKING" in `--type-label` at `--text-thinking-label`. Body text is `--type-body` in `--text-thinking`. -| Token | Value | Name | Meaning | -| ------------------ | --------- | ------- | ------------------------------- | -| `--green` | `#606C38` | Olive | Done, success, complete | -| `--green-bg` | `#EEF2E4` | — | Success background tint | -| `--green-border` | `#606C38` | — | Success border accent | -| `--copper` | `#BC6C25` | Copper | Active, running, primary action | -| `--copper-bg` | `#FDF3E4` | — | Active background tint | -| `--copper-border` | `#BC6C25` | — | Active border accent | -| `--caramel` | `#DDA15E` | Caramel | Pulsing dots, secondary accent | -| `--caramel-bg` | `#FEF7E8` | — | Caramel background tint | -| `--caramel-border` | `#DDA15E` | — | Caramel border accent | -| `--red` | `#9A3412` | Ember | Error, failed, destructive | -| `--red-bg` | `#FEF0E8` | — | Error background tint | -| `--red-border` | `#9A3412` | — | Error border accent | -| `--ochre` | `#92810A` | Ochre | Warning, caution | -| `--ochre-bg` | `#FEFCE8` | — | Warning background tint | -| `--ochre-border` | `#92810A` | — | Warning border accent | -| `--plum` | `#606C38` | Olive | Thinking, AI-internal states | -| `--plum-bg` | `#EEF2E4` | — | Thinking background tint | +### Tool call row -#### Status Color Usage Rules +Background `--bg-tool-row`, `--radius-md`, padding `--padding-tool-row`. Contains a 13px teal checkmark SVG, a tool type label ("bash", "read", "edit") in `--type-tool-type` and `--text-muted` with min-width 36px, and the command/path in `--type-tool-path` and `--font-mono` colored `#4a4a5a`. Rows within a group are spaced `--gap-tool-rows` apart. -- **Backgrounds:** Status tints (`*-bg`) are used on cards/badges to signal - state. They are very low saturation — barely tinted cream. -- **Text:** Status colors are used directly as text color on their tinted - backgrounds. Never use status colors on the base `--bg` background for text - — contrast is insufficient. -- **Borders:** `border-left: 3px solid` accent borders on cards to signal - state. Only left borders get colored — top/right/bottom remain `--border`. -- **No other hues exist.** If you need a new semantic color, it must fit the - earth-pigment family. No blues, no cyans, no neon greens. - -### 2.2 Typography - -#### Font Stacks - -| Token | Value | Usage | -| ------------- | ---------------------------------------------------------------------- | ------------------------------ | -| `--font-sans` | `-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif` | All UI text | -| `--font-mono` | `'SF Mono', 'JetBrains Mono', 'Cascadia Code', 'Fira Code', monospace` | Data, paths, code, model names | - -#### Type Scale +### Step guidance pill -| Token | Value | Usage | -| --------------------- | ------ | ----------------------------- | -| `--font-size-xs` | `11px` | Micro labels, ghost text | -| `--font-size-sm` | `13px` | Metadata, captions, secondary | -| `--font-size-md` | `15px` | Body text (default) | -| `--font-size-lg` | `17px` | Section headings, card titles | -| `--font-size-xl` | `22px` | Phase headings, page titles | -| `--font-size-display` | `28px` | Logo, hero text | - -#### Weight Rules - -| Weight | Token | Usage | -| ------ | ----------------------- | ------------------------------------ | -| `400` | — | Body text, descriptions | -| `500` | — | Sidebar values, emphasis within body | -| `600` | `--font-weight-heading` | Section headings, card titles | -| `700` | `--font-weight-strong` | Page headings, agent names, logo | -| `800` | `--font-weight-display` | Display/hero text only | - -#### Typography Decision Tree - -- **Is it a heading?** → `--font-sans`, `--text-strong`, weight 600-800 -- **Is it body text?** → `--font-sans`, `--text`, weight 400 -- **Is it metadata (time, count, model)?** → `--font-mono`, `--text-muted`, weight 400 -- **Is it an agent/file name?** → `--font-mono`, `--text` or status color, weight 600 -- **Is it a label (uppercase)?** → `--font-sans`, `--text-muted`, weight 700, `letter-spacing: .1em`, `text-transform: uppercase`, `--font-size-xs` - -### 2.3 Spacing - -Base unit: `4px`. Scale follows: 4, 8, 16, 24, 32, 48, 64. - -| Token | Value | Usage | -| ------------ | ------ | -------------------------------------------- | -| `--space-1` | `4px` | Tight gaps (between badge and text) | -| `--space-2` | `8px` | Small gaps (between related items) | -| `--space-4` | `16px` | Default gap (between sections within a card) | -| `--space-6` | `24px` | Card padding, section spacing | -| `--space-8` | `32px` | Between cards, panel padding | -| `--space-12` | `48px` | Major section breaks | -| `--space-16` | `64px` | Page-level padding, hero spacing | - -#### Spacing Decision Tree - -- **Inside a card:** `--space-6` padding. `--space-4` between internal sections. -- **Between cards:** `--space-8` gap. -- **Between a label and its content:** `--space-2`. -- **Between inline items (badges, buttons):** `--space-2` to `--space-4`. -- **Page margins:** `--space-8` to `--space-12`. - -### 2.4 Shape - -| Token | Value | Usage | -| ------------- | ------ | ---------------------------------------- | -| `--radius-sm` | `6px` | Buttons, inputs, badges, inline controls | -| `--radius-md` | `10px` | Badges, pills, tags | -| `--radius-lg` | `14px` | Cards, panels, overlays | - -#### Shape Rules - -- **Cards, panels, overlays:** `--radius-lg` (14px) — soft, cushioned. -- **Buttons, inputs, selects:** `--radius-sm` (6px) — crisp, interactive. -- **Badges, pills:** `--radius-md` (10px) — rounded but not pill-shaped. -- **Status accent borders:** `border-left: 3px solid` with `border-radius: 0` on left, `--radius-lg` on right. -- **Never use `border-radius: 50%`** except for avatar circles (if added later). -- **Never use `border-radius: 9999px`** (full pill). Nothing is fully rounded. +Inline-flex element with `--bg-step-guidance`, `--radius-lg`, padding `--padding-step-guidance`. Contains an 8px circle in `--color-orange` (or `--color-teal` when step is complete), label text in `--text-subtle` at 13px/500, and a 10px chevron-down SVG. Aligns to `flex-start` (left-aligned, not full-width). -### 2.5 Motion +### Artifact card -| Token | Value | Usage | -| ------------------- | ---------- | ---------------------------- | -| `--duration-fast` | `150ms` | Hover states, button presses | -| `--duration-normal` | `250ms` | Content fade-in, transitions | -| `--duration-slow` | `400ms` | Notification fade-out | -| `--ease-default` | `ease-out` | All transitions | +Background `--bg-card` (specifically `#faf8f4` — slightly warmer than pure white to distinguish from prose cards), `--radius-lg`, `0.5px solid --border-divider`, padding `--padding-artifact`. Contains a 28px square icon with `--radius-lg`: navy background with a lavender file SVG for recently modified artifacts, or teal background with a light-teal file SVG for older/stable artifacts. Next to the icon: filename in `--font-mono` at 12px/500 in `--text-primary`, and timestamp in `--type-timestamp` at `--text-artifact-time`. -#### Allowed Animations +### Scout bar -| Name | Properties | Usage | -| ---------------- | ------------------------------- | -------------------------------- | -| `fade-in` | opacity 0→1 | Content appearing | -| `fade-out` | opacity 1→0 + translateY(0→8px) | Notifications dismissing | -| `thinking-pulse` | opacity 0.3→1→0.3 | Pulsing dot for "thinking" state | -| `cursor-blink` | opacity 1→0→1, step-end | Streaming text cursor | +Navy frame (`--color-navy`) with padding `--padding-scout-bar`. The summary line sits directly on navy: an 8px orange dot, "SCOUTS" label in `--text-on-dark-muted` at `--type-label`, then count groups (e.g., "3 running") where the number uses the appropriate status color and the label uses `--text-on-dark-scouts-muted`. -#### Forbidden Motion +Below the summary, a white table card (`--bg-card` with `#faf8f4`) with `--radius-lg` and no outer border. The table has a header row with column labels in `--type-badge` / `--text-muted`, uppercase, with a `0.5px solid --border-divider` bottom border. Data rows use `--padding-scout-row` with `0.5px solid --border-divider-light` separators (no border on the last row). -- No `transform: scale()` — nothing grows/shrinks. -- No `translateX/Y` for layout shifts — things don't slide in. -- No `bounce` or spring easings. -- No `animation-iteration-count: infinite` except `thinking-pulse` and `cursor-blink`. +Table columns: status dot (20px col, 6px dot in status color), name (flex, `--font-mono` 12px/500 in `--text-primary`), model (60px, `--text-muted` 11px), tools (60px, `--text-muted`), elapsed (70px, `--text-muted`), status (flex, `--color-orange` for active steps). ---- +### Feedback input -## 3. Primitives +White card (`--bg-card`), `--radius-xl`, `1.5px solid --border-input` (this is intentionally darker than card borders for definition). Padding `--padding-input`. Placeholder text in `--text-placeholder`. Below: hint text in `--text-hint` at 11px left-aligned, and a "Send" button right-aligned with `--color-orange` background, white text, `--radius-md`, padding 5px 16px, 13px/500. -Base-level elements. Every component is built from these. +### Completion banner -### 3.1 Text Styles +Background `--bg-completion`, `--radius-xl`, padding 14px, text centered in `--text-completion` at 14px. -``` -.text-display → --font-size-display, --font-weight-display, --text-strong, letter-spacing: -.03em -.text-heading → --font-size-xl, --font-weight-strong, --text-strong, letter-spacing: -.02em -.text-title → --font-size-lg, --font-weight-heading, --text-strong -.text-body → --font-size-md, 400, --text, line-height: 1.6 -.text-caption → --font-size-sm, 400, --text-muted -.text-micro → --font-size-xs, 400, --text-ghost -.text-label → --font-size-xs, 700, --text-muted, uppercase, letter-spacing: .1em -.text-mono → --font-mono, --font-size-sm, 400, --text -``` +### Form cards (New Run page) -### 3.2 Buttons +White card (`--bg-card`), `--radius-2xl`, `0.5px solid --border-card`, padding `--padding-card-form`. Section label in `--type-label` / `--text-muted` at the top. Form inputs use `background: --bg-base`, `1.5px solid --border-input`, `--radius-lg`, padding 10px 14px. -Three variants. All use `--radius-sm` (6px), `--font-sans`. +### Workflow selection cards (New Run page) -| Variant | Background | Text | Border | When to use | -| ----------- | ------------- | -------- | --------------------------- | ---------------------------------------------------- | -| **Primary** | `--green` | `#fff` | none | Single main action per view (Begin Planning, Submit) | -| **Accent** | `--copper` | `#fff` | none | Secondary prominent action (Submit Review) | -| **Ghost** | `transparent` | `--text` | `1px solid --border-strong` | Cancel, Back, non-committal actions | +Two cards side by side in a 2-column grid with 12px gap. The selected card has `2px solid --color-orange` border, `--bg-selected` background, and a filled radio circle (16px outer circle with 2px orange border, 8px filled orange inner). The unselected/disabled card has `1.5px solid --border-radio` border, opacity 0.6 for disabled state. -Sizing: `padding: 12px 24px`, `font-size: --font-size-md`, `font-weight: 600`. +### Elicitation panels (Deepen view) -States: +Two-panel 1fr/1fr grid with 20px gap. Each panel is a white card (`--bg-card`) with `--radius-2xl` and `0.5px solid --border-card`. The Context panel has a 3px `--color-teal` top border. The Decision panel has a 3px `--color-orange` top border. Panel labels use the respective accent color for text. -- **Hover:** `opacity: 0.85` (primary/accent), `border-color: --text-muted` (ghost) -- **Disabled:** `opacity: 0.4`, `cursor: not-allowed` -- **No focus ring color** — use browser default outline. +### Radio option cards (Deepen view) -### 3.3 Inputs +Each option is a label element with `--radius-lg`, `1.5px solid --border-radio`, padding `--padding-radio`. Contains an 18px circle with `2px solid --border-input` (unfilled state) or `2px solid --color-orange` with 8px filled inner (selected state). The "recommended" badge uses `background: --bg-completion; color: --text-completion` (teal-green family), `--radius-pill`, `--type-badge`. -All inputs: `--radius-sm`, `padding: 12px 16px`, `border: 1px solid --border`, -`background: --bg-elevated`, `font-size: --font-size-md`, `color: --text-strong`. +When `isCustom` is true and selected, a text input appears below the label (8px top margin, full-width, transparent background, bottom-border-only: --border-card default, --border-input on focus, placeholder "Type your response..." in --text-placeholder). Hidden when not selected. -- **Focus:** `border-color: --copper` -- **Placeholder:** `color: --text-ghost`, `font-style: italic` -- **Textarea:** Same as input. `min-height: 80px`, `resize: vertical`. -- **Select:** Same as input. Custom chevron via background SVG in `--text-muted`. +### Buttons -### 3.4 Badges +Primary: `--color-orange` background, white text, `--radius-lg` (8px for larger buttons, 6px for small), 13-15px/500. Used for "Start Run", "Next", "Send". -Inline status indicators. `--radius-md` (10px), `padding: 5px 14px`, -`font-size: --font-size-sm`, `font-weight: 600`. +Secondary/outline: `1.5px solid --border-input`, `--text-subtle`, `--radius-lg`. Used for "Use Defaults". -| State | Background | Text | -| ------- | ------------- | -------------- | -| Done | `--green-bg` | `--green` | -| Active | `--copper-bg` | `--copper` | -| Failed | `--red-bg` | `--red` | -| Warning | `--ochre-bg` | `--ochre` | -| Neutral | `--bg-inset` | `--text-muted` | +## Layout -### 3.5 Labels +### Three-column workflow view -Uppercase section markers. See `.text-label` style. +Used during active workflow phases (Gather, Deepen, Summarize). Grid: `minmax(0, 1fr) 240px`. The main content column scrolls vertically. The artifacts sidebar is fixed-width at 240px with `--bg-surface` background and a 1px `--border-divider` left border. -`font-size: --font-size-xs`, `font-weight: 700`, `color: --text-muted`, -`text-transform: uppercase`, `letter-spacing: .1em`. +### Centered form view -Always followed by `--space-2` gap before content. +Used for the "New Run" page. Single centered column with `--form-max-width` (640px), no sidebar, no scout bar. Content sections are stacked with `--gap-form-sections`. ---- +### Scout bar (conditional) -## 4. Components +Appears at the bottom of the viewport only during phases where scouts are active. Full-width, `--color-navy` background. Contains the summary line and white table card. Not present on the New Run page or completion views where scouts aren't running. -Composed from primitives. Each component has a clear purpose and defined -states. +## Logo -### 4.1 Card +The koan logo consists of two elements: a geometric mark and a wordmark. -The primary container. Paper on the desk. +The geometric mark is two overlapping circles. The larger circle (16px diameter) is `--color-orange`, positioned top-left. The smaller circle (10px diameter) is `--color-teal`, positioned bottom-right, partially overlapping the orange circle. Total mark footprint: approximately 20x20px. -``` -background: --bg-elevated -border: 1px solid --border -border-radius: --radius-lg (14px) -padding: --space-6 (24px) -``` +The wordmark "koan" is set in `--font-display` (serif) at 17px/500, colored `--text-on-dark` when on navy, or `--text-primary` when on light backgrounds. Letter-spacing: -0.3px. -**Status variants** — left accent border, tinted background: - -| State | Background | Left border | -| ------- | --------------- | -------------------- | -| Default | `--bg-elevated` | none | -| Running | `--copper-bg` | `3px solid --copper` | -| Done | `--green-bg` | `3px solid --green` | -| Failed | `--red-bg` | `3px solid --red` | - -When a card has a status border, use `border-radius: 0 --radius-lg --radius-lg 0` -so the left edge is straight. - -**Card anatomy:** - -``` -┌──────────────────────────────────┐ -│ [label] [badge] │ ← card header (flex, space-between) -│ │ -│ Title Text │ ← .text-title -│ Body description text that │ ← .text-body -│ wraps to multiple lines. │ -│ │ -│ [metadata] [action btn] │ ← card footer (flex, space-between) -└──────────────────────────────────┘ -``` - -### 4.2 Pill Strip - -Phase navigation. A row of connected segments showing workflow progress. - -``` -display: flex -border-radius: --radius-md (10px) -overflow: hidden -border: 1px solid --border -background: --bg -``` - -Individual pills: `padding: 6px 16px`, `font-size: --font-size-sm`, `font-weight: 600`. - -| State | Background | Text | Prefix | -| -------- | ---------- | -------------- | ------ | -| Inactive | `--bg` | `--text-ghost` | none | -| Active | `--copper` | `#fff` | `● ` | -| Done | `--green` | `#fff` | `✓ ` | - -Pills are separated by `border-right: 1px solid --border`. Last pill has no -right border. - -### 4.3 Agent Table - -Data table for subagent monitoring. Mono typography throughout. - -``` -Header row: .text-label style (uppercase, xs, muted) -Data cells: --font-mono, --font-size-sm - padding: 8px on each cell - border-bottom: 1px solid --border -``` - -Agent name is `--font-weight-heading` (600) and colored by status: - -- Running: `--copper` -- Done: `--green` -- Failed: `--red` -- Queued: `--text-ghost` - -Token counts and model names are always `--text-muted`. - -### 4.4 Activity Card - -Collapsible card in the activity feed showing a thinking block, tool call, -or scout dispatch. - -``` -background: --bg-surface -border: 1px solid --border -border-radius: --radius-lg -``` - -**Header:** flex row — tool name (left, `--text-muted` or status color) and -metadata (right, `--text-muted`, `--font-size-xs`). - -**Body:** `--font-mono`, `--font-size-sm`, `--text-muted`, `white-space: pre-wrap`. -Clamped to 3 lines with "show more ▸" link in `--copper`. - -**Active variant:** `border-color: --copper-border`. - -**Thinking variant:** tool name in `--plum`. - -### 4.5 Question Card - -User-facing form for answering questions during intake. - -``` -background: --bg-elevated -border: 1px solid --border -border-radius: --radius-lg -padding: --space-6 -``` - -**Structure:** - -1. Header label (`.text-label`) -2. Context paragraphs (`.text-body`, `--text-muted`) -3. Question text (`--font-size-lg + 1px = 18px`, weight 500, `--text-strong`) -4. Options list (vertical stack, `--space-1` gap) - -**Option items:** `padding: --space-2 --space-4`, `border: 1px solid --border`, -`border-radius: --radius-sm`, `cursor: pointer`. - -- Hover: `border-color: --text-muted` -- Selected: `border-color: --copper-border`, `background: --copper-bg` - -Radio dots: `14px` circle, `border: 2px solid --text-ghost`. -Selected: `border-color: --copper`, `background: --copper`. - -### 4.6 Notification Toast - -Transient feedback. Appears bottom-right, fades out. - -``` -padding: --space-2 --space-6 -border-radius: --radius-md -color: #fff -animation: fade-in --duration-fast, then fade-out --duration-slow after 3s -``` - -| Type | Background | -| ------- | ---------- | -| Info | `--copper` | -| Warning | `--ochre` | -| Error | `--red` | - -### 4.7 Overlay / Modal - -For artifact review, settings, etc. - -``` -Backdrop: rgba(42, 31, 20, 0.5) ← warm dark, not cold black -Panel: --bg-elevated - border: 1px solid --border - border-radius: --radius-lg - max-width: 860px - max-height: 88vh -``` - -Header: `padding: 16px 24px`, `border-bottom: 1px solid --border`. -Body: `padding: 24px 28px`, scrollable. - ---- - -## 5. Layout Patterns - -### 5.1 App Shell - -``` -┌──────────────────────────────────────────────┐ -│ HEADER (logo + pill strip + settings) │ ← 56px height, border-bottom -├──────────────────────────────────────────────┤ -│ │ -│ MAIN AREA │ ← flex: 1, scrollable -│ │ -├──────────────────────────────────────────────┤ -│ MONITOR (agent table) │ ← flex: 0 auto, border-top -└──────────────────────────────────────────────┘ -``` - -- Max-width: `1300px`, centered. -- Background: `--bg` everywhere except monitor (`--bg-surface`). -- Header background: `--bg`. - -### 5.2 Three-Column Workspace - -Used during execution phase: - -``` -┌────────┬─────────────────────┬────────┐ -│ STATUS │ ACTIVITY FEED │ ARTI- │ -│ SIDE- │ │ FACTS │ -│ BAR │ │ SIDE- │ -│ │ │ BAR │ -│ 240- │ flex: 1 │ 240- │ -│ 300px │ │ 300px │ -└────────┴─────────────────────┴────────┘ -``` - -- Sidebars: `background: --bg-surface`, `border-right/left: 1px solid --border`. -- Activity feed: `background: --bg`, centered content with `max-width: 960px`. - -### 5.3 Centered Content - -For intake, brief, planning phases — single centered column: - -``` -max-width: 960px -margin: 0 auto -padding: --space-8 --space-6 -``` - ---- - -## 6. Decision Trees - -Use these when deciding how to implement a new UI element. - -### 6.1 "What container should I use?" - -``` -Is it a distinct content block with its own identity? - → Card (--bg-elevated, border, --radius-lg) - -Is it a list of status items (agents, scouts)? - → Agent Table or scout-entry list (no outer card — direct on --bg-surface) - -Is it a user-interactive form section? - → Question Card - -Is it above the page (blocking interaction)? - → Overlay/Modal - -Is it transient feedback? - → Notification Toast -``` - -### 6.2 "What color should this text be?" - -``` -Is it a heading or name? → --text-strong -Is it body copy? → --text -Is it a timestamp, count, model? → --text-muted -Is it a placeholder or disabled? → --text-ghost -Is it a status indicator? → Use the status color (--green, --copper, --red, --ochre) -Is it an interactive link/action? → --copper -``` - -### 6.3 "Should I use mono or sans?" - -``` -Is it a file path, command, or code? → mono -Is it an agent/model name? → mono -Is it a token count or numeric stat? → mono -Is it a timestamp or duration? → mono -Everything else → sans -``` - -### 6.4 "How should I signal state?" - -``` -Idle/default → no color, --border, --bg-elevated -Running/active → left accent border (--copper), tinted bg (--copper-bg) -Complete/done → left accent border (--green), tinted bg (--green-bg) -Error/failed → left accent border (--red), tinted bg (--red-bg) -Warning → left accent border (--ochre), tinted bg (--ochre-bg) -Thinking → text color --plum, pulsing dot animation -Queued → --text-ghost, no accent -``` - -### 6.5 "What spacing should I use?" - -``` -Between a label and its content → --space-2 (8px) -Between items in a list → --space-2 (8px) -Inside a card → --space-6 (24px) padding -Between cards → --space-8 (32px) gap -Between major sections → --space-12 (48px) -Page edge padding → --space-8 (32px) -``` - ---- - -## 7. Anti-Patterns - -Things that violate the design system. If you see these in code or are -tempted to add them, stop. - -| ❌ Don't | ✅ Do instead | -| --------------------------------------------- | ---------------------------------------------- | -| Use `box-shadow` for elevation | Use `border: 1px solid --border` | -| Use blue (`#58a6ff`) for anything | Use `--copper` for active/accent | -| Use raw hex colors in components | Reference `var(--token)` | -| Make text uppercase in body copy | Uppercase only in `.text-label` elements | -| Add `transform: scale()` animations | Use `opacity` transitions only | -| Use `border-radius: 50%` on cards | Cards always use `--radius-lg` | -| Put saturated color on `--bg` base | Status color only on status-tinted backgrounds | -| Use `--font-mono` for descriptions | Mono is for data/code/paths only | -| Add padding less than `--space-2` | Minimum meaningful spacing is 8px | -| Use more than 2 font weights in one component | Pick from the weight scale | - ---- - -## 8. Implementation Notes - -### File Organization - -``` -koan/web/static/css/ - variables.css <- all tokens defined here - layout.css <- app shell, grid, sidebar layouts - components.css <- card, badge, pill, table, form components - animations.css <- keyframes and motion utilities -``` - -### Token Naming Convention - -- Background tokens: `--bg-*` -- Text tokens: `--text-*` -- Border tokens: `--border-*` -- Status colors: `--{color-name}`, `--{color-name}-bg`, `--{color-name}-border` -- Spacing: `--space-{multiplier}` (multiplier × 4px) -- Radii: `--radius-{sm|md|lg}` -- Motion: `--duration-{speed}`, `--ease-*` - -### Scrollbar Styling - -Scrollbars must blend into the warm palette. Never use browser defaults. - -```css -scrollbar-width: thin; -scrollbar-color: var(--border-strong) transparent; -``` - -Webkit: - -- Track: `transparent` -- Thumb: `var(--border-strong)` (`#B8B098`) — warm tan, not gray or black -- Thumb hover: `var(--text-muted)` (`#7A7450`) — slightly darker on interaction -- Width: `7px` -- Border-radius: `4px` - -**Never use dark/black scrollbar thumbs.** They break the warm paper aesthetic. - -### Global Reset - -```css -*, -*::before, -*::after { - box-sizing: border-box; -} -html, -body { - margin: 0; - background: var(--bg); - color: var(--text); - font-family: var(--font-sans); - font-size: var(--font-size-md); - line-height: 1.6; -} -``` - -Note: `line-height` is `1.6` (not `1.5`) for the breathing layout. +The mark and wordmark are separated by 8px. On the header bar, a 1px vertical divider at `--text-on-dark-faint` separates the logo group from the navigation breadcrumb with 16px gap on each side. From 582b60f71ffa87f097ea5883ec81803e4c5335bc Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 5 Apr 2026 17:39:54 +0700 Subject: [PATCH 332/412] refactor: replace CSS tokens and migrate to new design system Replace all CSS custom properties with the new token set from design-system.md. Complete rewrite of variables.css with new color palette, typography scale, spacing system, and border radii. Migrate all references in layout.css, components.css, markdown.css, and Completion.tsx. Adds derived tokens for overlay backdrop, focus ring, and flash animation colors. Eliminates all hardcoded hex and rgba values from component CSS. --- frontend/src/components/Completion.tsx | 2 +- frontend/src/styles/components.css | 854 ++++++++++++------------- frontend/src/styles/layout.css | 244 +++---- frontend/src/styles/markdown.css | 38 +- frontend/src/styles/variables.css | 329 +++++++--- 5 files changed, 821 insertions(+), 646 deletions(-) diff --git a/frontend/src/components/Completion.tsx b/frontend/src/components/Completion.tsx index 0dd50a2..c7ad493 100644 --- a/frontend/src/components/Completion.tsx +++ b/frontend/src/components/Completion.tsx @@ -30,7 +30,7 @@ export function Completion() { </> ) : ( <> - <h2 className="phase-heading" style={{ color: 'var(--red)' }}> + <h2 className="phase-heading" style={{ color: 'var(--status-failed)' }}> Run Failed </h2> <p className="phase-status">{completion.error || 'An error occurred.'}</p> diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css index d85cc14..7d58e98 100644 --- a/frontend/src/styles/components.css +++ b/frontend/src/styles/components.css @@ -1,39 +1,39 @@ /* ---- Badges ---- */ .badge { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); padding: 5px 14px; - border-radius: var(--radius-md); + border-radius: var(--radius-xl); font-weight: 600; } -.badge.done { background: var(--green-bg); color: var(--green); } -.badge.active { background: var(--copper-bg); color: var(--copper); } -.badge.failed { background: var(--red-bg); color: var(--red); } +.badge.done { background: var(--bg-completion); color: var(--color-teal); } +.badge.active { background: var(--bg-selected); color: var(--color-orange); } +.badge.failed { background: var(--bg-base); color: var(--status-failed); } /* ---- Agent table ---- */ .agent-table { width: 100%; border-collapse: collapse; table-layout: fixed; - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); } .agent-table th { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.06em; padding: 4px 8px; text-align: left; - border-bottom: 1px solid var(--border); + border-bottom: 1px solid var(--border-card); } .agent-table td { padding: 8px; vertical-align: top; - border-bottom: 1px solid var(--border); + border-bottom: 1px solid var(--border-card); } .col-status { width: 28px; text-align: center; } @@ -55,22 +55,22 @@ } .agent-status-queued { color: var(--text-muted); } -.agent-status-running { color: var(--copper); } -.agent-status-done { color: var(--green); font-weight: 600; } -.agent-status-failed { color: var(--red); } +.agent-status-running { color: var(--color-orange); } +.agent-status-done { color: var(--color-teal); font-weight: 600; } +.agent-status-failed { color: var(--status-failed); } .agent-name-queued { color: var(--text-muted); font-family: var(--font-mono); } -.agent-name-running { color: var(--text); font-weight: 600; font-family: var(--font-mono); } -.agent-name-done { color: var(--green); font-family: var(--font-mono); } -.agent-name-failed { color: var(--red); font-family: var(--font-mono); } +.agent-name-running { color: var(--text-body); font-weight: 600; font-family: var(--font-mono); } +.agent-name-done { color: var(--color-teal); font-family: var(--font-mono); } +.agent-name-failed { color: var(--status-failed); font-family: var(--font-mono); } .agent-model-cell { font-family: var(--font-mono); color: var(--text-muted); } .agent-tokens-cell { font-family: var(--font-mono); color: var(--text-muted); } .agent-time-cell { font-family: var(--font-mono); color: var(--text-muted); } -.agent-timer { font-size: var(--font-size-xs); } +.agent-timer { font-size: var(--type-label); } -.agent-doing-dim { font-family: var(--font-mono); font-size: var(--font-size-xs); color: var(--text-muted); } -.agent-doing-failed { color: var(--red); } +.agent-doing-dim { font-family: var(--font-mono); font-size: var(--type-label); color: var(--text-muted); } +.agent-doing-failed { color: var(--status-failed); } .agent-doing-lines { display: flex; @@ -80,7 +80,7 @@ .agent-doing-line { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); white-space: nowrap; overflow: hidden; @@ -88,7 +88,7 @@ } .agent-doing-line:last-child { - color: var(--text); + color: var(--text-body); } /* ---- Agent counter bar (option B) ---- */ @@ -104,8 +104,8 @@ text-align: center; } -.agent-counter:first-child { border-radius: var(--radius-sm) 0 0 var(--radius-sm); } -.agent-counter:last-child { border-radius: 0 var(--radius-sm) var(--radius-sm) 0; } +.agent-counter:first-child { border-radius: var(--radius-md) 0 0 var(--radius-md); } +.agent-counter:last-child { border-radius: 0 var(--radius-md) var(--radius-md) 0; } .agent-counter-num { display: block; @@ -124,14 +124,14 @@ color: var(--text-muted); } -.agent-counter-running { background: var(--copper-bg); } -.agent-counter-running .agent-counter-num { color: var(--copper); } -.agent-counter-queued { background: var(--ochre-bg); } +.agent-counter-running { background: var(--bg-selected); } +.agent-counter-running .agent-counter-num { color: var(--color-orange); } +.agent-counter-queued { background: var(--bg-selected); } .agent-counter-queued .agent-counter-num { color: var(--text-muted); } -.agent-counter-done { background: var(--green-bg); } -.agent-counter-done .agent-counter-num { color: var(--green); } -.agent-counter-failed { background: var(--red-bg); } -.agent-counter-failed .agent-counter-num { color: var(--red); } +.agent-counter-done { background: var(--bg-completion); } +.agent-counter-done .agent-counter-num { color: var(--color-teal); } +.agent-counter-failed { background: var(--bg-base); } +.agent-counter-failed .agent-counter-num { color: var(--status-failed); } /* Hide counter cells with zero count */ .agent-counter-num:empty + .agent-counter-label { display: none; } @@ -139,19 +139,19 @@ /* ---- Agent section headers ---- */ .agent-section-header { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); text-transform: uppercase; letter-spacing: 0.08em; padding: 4px 0; - border-bottom: 1px solid var(--border); + border-bottom: 1px solid var(--border-card); margin-bottom: 2px; margin-top: 8px; } .agent-section-header:first-of-type { margin-top: 0; } -.section-running { color: var(--copper); } -.section-done { color: var(--green); } -.section-failed { color: var(--red); } +.section-running { color: var(--color-orange); } +.section-done { color: var(--color-teal); } +.section-failed { color: var(--status-failed); } .section-queued { color: var(--text-muted); } .agent-row-queued { opacity: 0.5; } @@ -162,7 +162,7 @@ gap: 10px; padding: 5px 8px; font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); } .agent-row-done { opacity: 0.7; } @@ -171,70 +171,70 @@ .agent-row-icon { width: 14px; text-align: center; flex-shrink: 0; } .agent-row-name { width: 200px; flex-shrink: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .agent-row-model { width: 70px; flex-shrink: 0; color: var(--text-muted); } -.agent-row-tools { width: 65px; flex-shrink: 0; text-align: right; font-size: var(--font-size-xs); } -.agent-row-tools-num { color: var(--text); } +.agent-row-tools { width: 65px; flex-shrink: 0; text-align: right; font-size: var(--type-label); } +.agent-row-tools-num { color: var(--text-body); } .agent-row-tools-label { color: var(--text-muted); } -.agent-row-time { width: 55px; flex-shrink: 0; text-align: right; color: var(--text-muted); font-size: var(--font-size-xs); } +.agent-row-time { width: 55px; flex-shrink: 0; text-align: right; color: var(--text-muted); font-size: var(--type-label); } .agent-row-doing { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } /* ---- Card ---- */ .card { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-6); - margin-bottom: var(--space-4); + background: var(--bg-card); + border: 1px solid var(--border-card); + border-radius: var(--radius-2xl); + padding: 24px; + margin-bottom: 16px; } .card.card-running { - border-left: 3px solid var(--copper); + border-left: 3px solid var(--color-orange); } .card.card-done { - background: var(--green-bg); - border-color: var(--green-border); + background: var(--bg-completion); + border-color: var(--color-teal); } .card.card-failed { - background: var(--red-bg); - border-color: var(--red-border); + background: var(--bg-base); + border-color: var(--status-failed); } .card-header { display: flex; align-items: center; - gap: var(--space-2); - margin-bottom: var(--space-2); + gap: 8px; + margin-bottom: 8px; } .card-title { - font-family: var(--font-sans); + font-family: var(--font-body); font-weight: 700; - font-size: var(--font-size-lg); - color: var(--text-strong); + font-size: var(--type-section-title); + color: var(--text-primary); } .card-role { margin-left: auto; font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); color: var(--text-muted); } .card-body { - font-family: var(--font-sans); - font-size: var(--font-size-lg); + font-family: var(--font-body); + font-size: var(--type-section-title); color: var(--text-muted); line-height: 1.6; } /* ---- Question cards ---- */ .question-card { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); + background: var(--bg-card); + border: 1px solid var(--border-card); + border-radius: var(--radius-2xl); overflow: hidden; - margin-bottom: var(--space-4); + margin-bottom: 16px; } /* Split layout: context panel left, decision panel right */ @@ -246,35 +246,35 @@ .question-context-panel { width: 44%; flex-shrink: 0; - padding: var(--space-6); - background: var(--bg-elevated); - border-right: 1px solid var(--border); + padding: 24px; + background: var(--bg-card); + border-right: 1px solid var(--border-card); overflow-y: auto; } .question-context-rule { - border-left: 3px solid var(--copper); - padding-left: var(--space-4); + border-left: 3px solid var(--color-orange); + padding-left: 16px; } .question-context-label { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.1em; - margin-bottom: var(--space-4); + margin-bottom: 16px; } .question-context { - font-family: var(--font-sans); - font-size: var(--font-size-md); + font-family: var(--font-body); + font-size: var(--type-prose); color: var(--text-muted); line-height: 1.6; } .question-context p { - margin: 0 0 var(--space-2) 0; + margin: 0 0 8px 0; } .question-context p:last-child { @@ -288,39 +288,39 @@ border: none; padding: 0; font-size: 0.88em; - color: var(--text); + color: var(--text-body); } /* Code in question text and options: visible boxes */ .question-text code, .option-text code { - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); + background: var(--bg-base); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); padding: 1px 5px; font-family: var(--font-mono); font-size: 0.85em; - color: var(--text); + color: var(--text-body); } .question-context strong, .question-text strong, .option-text strong { - color: var(--text); + color: var(--text-body); font-weight: 600; } .question-context a, .question-text a, .option-text a { - color: var(--copper); + color: var(--color-orange); text-decoration: underline; } .question-context ul, .question-context ol { - padding-left: var(--space-6); - margin: var(--space-2) 0; + padding-left: 24px; + margin: 8px 0; } .question-context li { @@ -330,7 +330,7 @@ /* -- Decision panel (right, or full-width when no context) -- */ .question-decision-panel { flex: 1; - padding: var(--space-6); + padding: 24px; min-width: 0; } @@ -340,36 +340,36 @@ .question-decision-label { font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--copper); + font-size: var(--type-label); + color: var(--color-orange); text-transform: uppercase; letter-spacing: 0.1em; - margin-bottom: var(--space-4); + margin-bottom: 16px; } .question-text { - font-family: var(--font-sans); + font-family: var(--font-body); font-size: 18px; font-weight: 600; - color: var(--text-strong); - margin-bottom: var(--space-4); + color: var(--text-primary); + margin-bottom: 16px; line-height: 1.5; } .question-multi-hint { font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--copper); - margin-bottom: var(--space-2); + font-size: var(--type-label); + color: var(--color-orange); + margin-bottom: 8px; } /* Actions inside the decision panel */ .question-actions { display: flex; - gap: var(--space-4); - margin-top: var(--space-6); - padding-top: var(--space-4); - border-top: 1px solid var(--border); + gap: 16px; + margin-top: 24px; + padding-top: 16px; + border-top: 1px solid var(--border-card); align-items: center; } @@ -377,34 +377,34 @@ .options-list { display: flex; flex-direction: column; - gap: var(--space-2); + gap: 8px; } .option { display: flex; align-items: flex-start; - gap: var(--space-4); - padding: var(--space-4); + gap: 16px; + padding: 16px; border-left: 3px solid transparent; - border-radius: 0 var(--radius-sm) var(--radius-sm) 0; - background: var(--bg); + border-radius: 0 var(--radius-md) var(--radius-md) 0; + background: var(--bg-base); cursor: pointer; transition: border-color var(--duration-fast), background var(--duration-fast); user-select: none; } .option:hover { - background: var(--caramel-bg); - border-left-color: var(--border-strong); + background: var(--bg-selected); + border-left-color: var(--border-input); } .option.selected { - border-left-color: var(--copper); - background: var(--copper-bg); + border-left-color: var(--color-orange); + background: var(--bg-selected); } .option.recommended:not(.selected) { - border-left-color: var(--caramel); + border-left-color: var(--color-orange); } .option-other { @@ -417,7 +417,7 @@ .radio-dot, .checkbox-dot { width: 16px; height: 16px; - border: 2px solid var(--border-strong); + border: 2px solid var(--border-input); border-radius: 50%; flex-shrink: 0; margin-top: 1px; @@ -435,14 +435,14 @@ } .option.selected .radio-dot { - border-color: var(--copper); - background: var(--bg-elevated); - box-shadow: inset 0 0 0 3px var(--copper); + border-color: var(--color-orange); + background: var(--bg-card); + box-shadow: inset 0 0 0 3px var(--color-orange); } .option.selected .checkbox-dot { - border-color: var(--copper); - background: var(--copper); + border-color: var(--color-orange); + background: var(--color-orange); } .option.selected .checkbox-dot::after { @@ -452,21 +452,21 @@ left: 5px; width: 4px; height: 7px; - border: solid #fff; + border: solid var(--text-on-dark); border-width: 0 2px 2px 0; transform: rotate(45deg); } .option-text { - font-family: var(--font-sans); - font-size: var(--font-size-md); - color: var(--text); + font-family: var(--font-body); + font-size: var(--type-prose); + color: var(--text-body); flex: 1; line-height: 1.5; } .option.selected .option-text { - color: var(--text-strong); + color: var(--text-primary); } .option-other .option-text { @@ -476,11 +476,11 @@ .recommended-badge { font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--copper); - background: var(--copper-bg); - border: 1px solid var(--copper-border); - border-radius: var(--radius-sm); + font-size: var(--type-label); + color: var(--color-orange); + background: var(--bg-selected); + border: 1px solid var(--color-orange); + border-radius: var(--radius-md); padding: 1px 6px; margin-top: 1px; white-space: nowrap; @@ -490,19 +490,19 @@ .other-input { display: none; width: 100%; - margin-top: var(--space-2); - padding: var(--space-2); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); - font-family: var(--font-sans); - font-size: var(--font-size-md); + margin-top: 8px; + padding: 8px; + background: var(--bg-base); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); + color: var(--text-body); + font-family: var(--font-body); + font-size: var(--type-prose); outline: none; } .other-input:focus { - border-color: var(--copper); + border-color: var(--color-orange); } .other-input.visible { @@ -512,19 +512,19 @@ /* Free-form text input (questions with no predefined options) */ .free-text-area { - margin-top: var(--space-4); + margin-top: 16px; } .free-text-input { width: 100%; min-height: 100px; - padding: var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); - font-family: var(--font-sans); - font-size: var(--font-size-md); + padding: 16px; + background: var(--bg-base); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); + color: var(--text-body); + font-family: var(--font-body); + font-size: var(--type-prose); line-height: 1.5; resize: vertical; outline: none; @@ -536,57 +536,57 @@ } .free-text-input:focus { - border-color: var(--copper); + border-color: var(--color-orange); } /* ---- Config sections ---- */ .model-config-section { - margin-top: var(--space-6); + margin-top: 24px; } .model-config-section-heading { - font-size: var(--font-size-lg); + font-size: var(--type-section-title); font-weight: 600; - color: var(--text-strong); - margin: 0 0 var(--space-1) 0; + color: var(--text-primary); + margin: 0 0 var(--gap-tool-rows) 0; } .scout-concurrency-input { width: 80px; - padding: var(--space-2) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); + padding: 8px 16px; + background: var(--bg-base); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); + color: var(--text-body); font-family: var(--font-mono); - font-size: var(--font-size-md); + font-size: var(--type-prose); } .scout-concurrency-input:focus { - border-color: var(--copper); + border-color: var(--color-orange); outline: none; } /* ---- Form actions ---- */ .form-actions { display: flex; - gap: var(--space-4); - margin-top: var(--space-6); + gap: 16px; + margin-top: 24px; align-items: center; } .form-helper { font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); color: var(--text-muted); margin-left: auto; } .btn { padding: 12px 24px; - border-radius: var(--radius-sm); - font-size: var(--font-size-md); - font-family: var(--font-sans); + border-radius: var(--radius-md); + font-size: var(--type-prose); + font-family: var(--font-body); cursor: pointer; border: 1px solid transparent; transition: opacity 100ms; @@ -598,167 +598,167 @@ } .btn-primary { - background: var(--green); - color: #fff; - border-color: var(--green); + background: var(--color-teal); + color: var(--text-on-dark); + border-color: var(--color-teal); } .btn-secondary { background: transparent; - color: var(--text); - border-color: var(--border-strong); + color: var(--text-body); + border-color: var(--border-input); } /* ---- Topic card ---- */ .topic-card { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-4) var(--space-6); - margin-top: var(--space-4); + background: var(--bg-card); + border: 1px solid var(--border-card); + border-radius: var(--radius-2xl); + padding: 16px 24px; + margin-top: 16px; max-width: 640px; } .topic-label { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.08em; - margin-bottom: var(--space-1); + margin-bottom: var(--gap-tool-rows); } .topic-text { - font-family: var(--font-sans); - font-size: var(--font-size-lg); - color: var(--text); + font-family: var(--font-body); + font-size: var(--type-section-title); + color: var(--text-body); font-style: italic; line-height: 1.6; } /* ---- Phase status messages ---- */ .phase-status { - font-family: var(--font-sans); - font-size: var(--font-size-lg); - color: var(--text); - margin-bottom: var(--space-4); + font-family: var(--font-body); + font-size: var(--type-section-title); + color: var(--text-body); + margin-bottom: 16px; } .phase-heading { - font-family: var(--font-sans); - font-size: 22px; - font-weight: 600; - color: var(--text-strong); - margin-bottom: var(--space-4); + font-family: var(--font-body); + font-size: var(--type-page-title); + font-weight: 500; + color: var(--text-primary); + margin-bottom: 16px; } /* ---- Summary checklist ---- */ .summary-list { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-4) var(--space-6); + background: var(--bg-card); + border: 1px solid var(--border-card); + border-radius: var(--radius-2xl); + padding: 16px 24px; } .summary-item { display: flex; align-items: center; - gap: var(--space-4); + gap: 16px; padding: 4px 0; - font-family: var(--font-sans); - font-size: var(--font-size-md); + font-family: var(--font-body); + font-size: var(--type-prose); } -.summary-item .icon-done { color: var(--green); } +.summary-item .icon-done { color: var(--color-teal); } .summary-item .icon-pending { color: var(--text-muted); } /* ---- Notification toasts ---- */ #notifications { position: fixed; - bottom: var(--space-6); - right: var(--space-6); + bottom: 24px; + right: 24px; display: flex; flex-direction: column; - gap: var(--space-2); + gap: 8px; z-index: 200; } .notification { - padding: var(--space-2) var(--space-4); - border-radius: var(--radius-md); - font-family: var(--font-sans); - font-size: var(--font-size-md); - color: #fff; + padding: 8px 16px; + border-radius: var(--radius-xl); + font-family: var(--font-body); + font-size: var(--type-prose); + color: var(--text-on-dark); animation: fade-in 150ms ease-out; } -.notification.info { background: var(--copper); } -.notification.warning { background: var(--ochre); } -.notification.error { background: var(--red); } +.notification.info { background: var(--color-orange); } +.notification.warning { background: var(--color-orange); } +.notification.error { background: var(--status-failed); } /* ---- Count progress indicator ---- */ .count-progress { font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); color: var(--text-muted); - margin-bottom: var(--space-4); + margin-bottom: 16px; } /* ---- Model config ---- */ .model-config-tiers { display: flex; flex-direction: column; - gap: var(--space-4); - margin-top: var(--space-4); - margin-bottom: var(--space-6); + gap: 16px; + margin-top: 16px; + margin-bottom: 24px; } .model-tier-row { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-4) var(--space-6); + background: var(--bg-card); + border: 1px solid var(--border-card); + border-radius: var(--radius-2xl); + padding: 16px 24px; } .model-tier-header { display: flex; align-items: center; - gap: var(--space-2); - margin-bottom: var(--space-1); + gap: 8px; + margin-bottom: var(--gap-tool-rows); } .model-tier-label { font-family: var(--font-mono); - font-size: var(--font-size-lg); + font-size: var(--type-section-title); font-weight: 700; - color: var(--text-strong); + color: var(--text-primary); text-transform: uppercase; letter-spacing: 0.06em; } .model-tier-description { - font-family: var(--font-sans); - font-size: var(--font-size-md); + font-family: var(--font-body); + font-size: var(--type-prose); color: var(--text-muted); line-height: 1.6; - margin: 0 0 var(--space-4); + margin: 0 0 16px; } .model-tier-input { width: 100%; - padding: var(--space-2) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); + padding: 8px 16px; + background: var(--bg-base); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); + color: var(--text-body); font-family: var(--font-mono); - font-size: var(--font-size-md); + font-size: var(--type-prose); outline: none; box-sizing: border-box; } .model-tier-input:focus { - border-color: var(--copper); + border-color: var(--color-orange); } .model-tier-input::placeholder { @@ -768,31 +768,31 @@ .model-tier-select { width: 100%; - padding: var(--space-2) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); + padding: 8px 16px; + background: var(--bg-base); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); + color: var(--text-body); font-family: var(--font-mono); - font-size: var(--font-size-md); + font-size: var(--type-prose); outline: none; box-sizing: border-box; cursor: pointer; -webkit-appearance: none; appearance: none; - background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8'%3E%3Cpath d='M1 1l5 5 5-5' stroke='%23957E68' stroke-width='1.5' fill='none'/%3E%3C/svg%3E"); + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8'%3E%3Cpath d='M1 1l5 5 5-5' stroke='%239a8e7e' stroke-width='1.5' fill='none'/%3E%3C/svg%3E"); background-repeat: no-repeat; background-position: right 12px center; padding-right: 36px; } .model-tier-select:focus { - border-color: var(--copper); + border-color: var(--color-orange); } .model-tier-select option { background: var(--bg-surface); - color: var(--text); + color: var(--text-body); } .model-tier-select optgroup { @@ -801,23 +801,23 @@ } .model-config-warning { - font-family: var(--font-sans); - font-size: var(--font-size-sm); - color: var(--red); - margin-bottom: var(--space-4); + font-family: var(--font-body); + font-size: var(--type-breadcrumb); + color: var(--status-failed); + margin-bottom: 16px; } /* ---- Settings button ---- */ .header-right { display: flex; align-items: center; - gap: var(--space-4); + gap: 16px; } .settings-btn { background: none; - border: 1px solid var(--border); - border-radius: var(--radius-sm); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); color: var(--text-muted); font-size: 16px; padding: 4px 8px; @@ -827,18 +827,18 @@ } .settings-btn:hover { - color: var(--text-strong); + color: var(--text-primary); border-color: var(--text-muted); } /* ---- Activity feed: in-flight + flash ---- */ @keyframes result-flash { - 0% { background: rgba(78, 122, 66, 0.12); } + 0% { background: var(--flash-teal); } 100% { background: transparent; } } .activity-inflight .activity-summary { - color: var(--ochre); + color: var(--color-orange); } .activity-flash { @@ -875,71 +875,71 @@ } .prefix-done { - color: var(--green); + color: var(--color-teal); } .prefix-active { - color: var(--copper); + color: var(--color-orange); animation: pulse-dot 1s ease-in-out infinite; } .agent-doing-inflight { - color: var(--text) !important; + color: var(--text-body) !important; } /* ---- Workflow chat ---- */ .workflow-chat { - margin-top: var(--space-4); - border-top: 1px solid var(--border); - padding-top: var(--space-4); + margin-top: 16px; + border-top: 1px solid var(--border-card); + padding-top: 16px; display: flex; flex-direction: column; - gap: var(--space-4); + gap: 16px; } .workflow-turn { display: flex; flex-direction: column; - gap: var(--space-1); + gap: var(--gap-tool-rows); } .workflow-turn-orchestrator { background: var(--bg-surface); - border: 1px solid var(--border); - border-radius: var(--radius-md); - padding: var(--space-2) var(--space-4); + border: 1px solid var(--border-card); + border-radius: var(--radius-xl); + padding: 8px 16px; } .workflow-turn-header { display: flex; align-items: center; - margin-bottom: var(--space-1); + margin-bottom: var(--gap-tool-rows); } .workflow-turn-role { font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--plum); + font-size: var(--type-label); + color: var(--text-thinking-label); font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; } .workflow-turn-body { - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); line-height: 1.6; - color: var(--text); + color: var(--text-body); } -.workflow-turn-body p { margin: 0 0 var(--space-1) 0; } +.workflow-turn-body p { margin: 0 0 var(--gap-tool-rows) 0; } .workflow-turn-body p:last-child { margin-bottom: 0; } -.workflow-turn-body ul, .workflow-turn-body ol { margin: var(--space-1) 0; padding-left: 1.4em; } +.workflow-turn-body ul, .workflow-turn-body ol { margin: var(--gap-tool-rows) 0; padding-left: 1.4em; } .workflow-turn-body li { margin: 2px 0; } -.workflow-turn-body strong { color: var(--text-strong); } +.workflow-turn-body strong { color: var(--text-primary); } .workflow-turn-body code { - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); + background: var(--bg-base); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); padding: 1px 4px; font-family: var(--font-mono); font-size: 0.9em; @@ -948,30 +948,30 @@ .workflow-turn-user { align-self: flex-end; max-width: 80%; - background: var(--copper-bg); - border: 1px solid var(--copper-border); - border-radius: var(--radius-md); - padding: var(--space-1) var(--space-4); - font-size: var(--font-size-sm); - color: var(--text); + background: var(--bg-selected); + border: 1px solid var(--color-orange); + border-radius: var(--radius-xl); + padding: var(--gap-tool-rows) 16px; + font-size: var(--type-breadcrumb); + color: var(--text-body); } /* ---- Workflow phase options ---- */ .workflow-options { display: flex; flex-direction: column; - gap: var(--space-1); - margin-top: var(--space-2); + gap: var(--gap-tool-rows); + margin-top: 8px; } .workflow-option { display: flex; flex-direction: column; gap: 2px; - padding: var(--space-1) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); + padding: var(--gap-tool-rows) 16px; + background: var(--bg-base); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); text-align: left; cursor: pointer; transition: background 150ms, border-color 150ms; @@ -979,36 +979,36 @@ .workflow-option:hover { background: var(--bg-surface); - border-color: var(--copper-border); + border-color: var(--color-orange); } .workflow-option.recommended { - border-color: var(--copper-border); - background: var(--copper-bg); + border-color: var(--color-orange); + background: var(--bg-selected); } .workflow-option.selected { - border-color: var(--copper-border); - background: var(--copper-bg); + border-color: var(--color-orange); + background: var(--bg-selected); } .workflow-option.selected .workflow-option-label { - color: var(--copper); + color: var(--color-orange); } .workflow-option-label { font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); font-weight: 600; - color: var(--text); + color: var(--text-body); } .workflow-option.recommended .workflow-option-label { - color: var(--copper); + color: var(--color-orange); } .workflow-option-context { - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); line-height: 1.4; } @@ -1017,26 +1017,26 @@ .workflow-chat-input { display: flex; flex-direction: column; - gap: var(--space-2); + gap: 8px; } .workflow-feedback { width: 100%; min-height: 72px; - padding: var(--space-2) var(--space-4); - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); - font-family: var(--font-sans); - font-size: var(--font-size-md); + padding: 8px 16px; + background: var(--bg-base); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); + color: var(--text-body); + font-family: var(--font-body); + font-size: var(--type-prose); resize: vertical; outline: none; box-sizing: border-box; } .workflow-feedback:focus { - border-color: var(--copper); + border-color: var(--color-orange); } .workflow-feedback::placeholder { @@ -1046,40 +1046,40 @@ /* ---- Steering indicator ---- */ .steering-indicator { - background: var(--copper-bg); - border-left: 3px solid var(--copper); - border-radius: 0 var(--radius-sm) var(--radius-sm) 0; - margin: var(--space-2) 0; + background: var(--bg-selected); + border-left: 3px solid var(--color-orange); + border-radius: 0 var(--radius-md) var(--radius-md) 0; + margin: 8px 0; overflow: hidden; } .steering-header { display: flex; align-items: center; - gap: var(--space-2); - padding: var(--space-2) var(--space-4); + gap: 8px; + padding: 8px 16px; font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--copper); + font-size: var(--type-label); + color: var(--color-orange); } .steering-messages { - padding: 0 var(--space-4) var(--space-2); + padding: 0 16px 8px; display: flex; flex-direction: column; - gap: var(--space-2); + gap: 8px; } .steering-message { display: flex; align-items: baseline; - gap: var(--space-2); - color: var(--text); - font-size: var(--font-size-sm); + gap: 8px; + color: var(--text-body); + font-size: var(--type-breadcrumb); line-height: 1.4; } .steering-message .md-content { display: inline; } .steering-message .md-content p { display: inline; margin: 0; } .steering-queued-badge { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); flex-shrink: 0; } @@ -1094,16 +1094,16 @@ .settings-overlay-backdrop { width: 100%; height: 100%; - background: rgba(42, 31, 20, 0.5); + background: var(--overlay-backdrop); display: flex; align-items: center; justify-content: center; } .settings-overlay-panel { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); + background: var(--bg-card); + border: 1px solid var(--border-card); + border-radius: var(--radius-2xl); width: 720px; max-width: 94vw; max-height: 90vh; @@ -1117,59 +1117,59 @@ align-items: center; justify-content: space-between; padding: 14px 20px; - border-bottom: 1px solid var(--border); + border-bottom: 1px solid var(--border-card); flex-shrink: 0; } .settings-overlay-title { font-weight: 700; - font-size: var(--font-size-lg); - color: var(--text-strong); + font-size: var(--type-section-title); + color: var(--text-primary); } .settings-overlay-body { flex: 1; overflow-y: auto; - padding: var(--space-6); + padding: 24px; } .settings-section-heading { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); text-transform: uppercase; letter-spacing: 0.08em; color: var(--text-muted); - margin-bottom: var(--space-4); + margin-bottom: 16px; } .profile-row { display: flex; align-items: center; - gap: var(--space-4); - padding: var(--space-2) var(--space-4); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - margin-bottom: var(--space-2); - background: var(--bg); + gap: 16px; + padding: 8px 16px; + border: 1px solid var(--border-card); + border-radius: var(--radius-md); + margin-bottom: 8px; + background: var(--bg-base); } .profile-row-name { font-family: var(--font-mono); font-weight: 600; - color: var(--text-strong); + color: var(--text-primary); min-width: 120px; } .profile-row-tiers { flex: 1; font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); } .profile-row-actions { display: flex; - gap: var(--space-2); + gap: 8px; margin-left: auto; } @@ -1178,14 +1178,14 @@ .install-tab-bar { display: flex; gap: 0; - border-bottom: 2px solid var(--border); + border-bottom: 2px solid var(--border-card); margin-bottom: 0; } .install-tab { - padding: var(--space-2) var(--space-4); + padding: 8px 16px; font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); color: var(--text-muted); background: none; border: none; @@ -1197,113 +1197,113 @@ } .install-tab:hover { - color: var(--text); + color: var(--text-body); } .install-tab--active { font-weight: 600; - color: var(--text-strong); - border-bottom-color: var(--green); + color: var(--text-primary); + border-bottom-color: var(--color-teal); } .install-tab-content { - padding: var(--space-4) 0; + padding: 16px 0; } .install-row { display: flex; align-items: center; - gap: var(--space-4); - padding: var(--space-2) var(--space-4); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - margin-bottom: var(--space-2); - background: var(--bg-elevated); + gap: 16px; + padding: 8px 16px; + border: 1px solid var(--border-card); + border-radius: var(--radius-md); + margin-bottom: 8px; + background: var(--bg-card); } .install-row--default { - background: var(--bg); + background: var(--bg-base); border-color: transparent; } .install-row-info { display: flex; align-items: center; - gap: var(--space-2); + gap: 8px; min-width: 160px; } .install-row-alias { font-family: var(--font-mono); font-weight: 600; - font-size: var(--font-size-sm); - color: var(--text-strong); + font-size: var(--type-breadcrumb); + color: var(--text-primary); } .install-row-badge { font-family: var(--font-mono); - font-size: var(--font-size-xs); - background: var(--green-bg); - color: var(--green); + font-size: var(--type-label); + background: var(--bg-completion); + color: var(--color-teal); padding: 1px 8px; - border-radius: var(--radius-sm); + border-radius: var(--radius-md); } .install-row-path { flex: 1; font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); } .install-add-btn { font-family: var(--font-mono); - font-size: var(--font-size-sm); - padding: var(--space-2) var(--space-4); - border: 1px dashed var(--border); - border-radius: var(--radius-sm); + font-size: var(--type-breadcrumb); + padding: 8px 16px; + border: 1px dashed var(--border-card); + border-radius: var(--radius-md); background: none; color: var(--text-muted); cursor: pointer; - margin-top: var(--space-2); + margin-top: 8px; transition: border-color var(--duration-fast) var(--ease-default), color var(--duration-fast) var(--ease-default); } .install-add-btn:hover { - border-color: var(--border-strong); - color: var(--text); + border-color: var(--border-input); + color: var(--text-body); } .btn-danger { - color: var(--red); + color: var(--status-failed); } .no-runners-msg { - font-family: var(--font-sans); - font-size: var(--font-size-sm); - color: var(--red); - margin-top: var(--space-2); + font-family: var(--font-body); + font-size: var(--type-breadcrumb); + color: var(--status-failed); + margin-top: 8px; } .profile-form { - border: 1px solid var(--copper-border); - border-radius: var(--radius-lg); - padding: var(--space-4); - background: var(--copper-bg); - margin-top: var(--space-4); + border: 1px solid var(--color-orange); + border-radius: var(--radius-2xl); + padding: 16px; + background: var(--bg-selected); + margin-top: 16px; } .tier-form-row { display: flex; align-items: center; - gap: var(--space-2); - margin-bottom: var(--space-2); + gap: 8px; + margin-bottom: 8px; } .tier-form-label { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); text-transform: uppercase; min-width: 70px; color: var(--text-muted); @@ -1341,10 +1341,10 @@ .activity-waiting { display: flex; align-items: center; - gap: var(--space-2); - padding: var(--space-4); + gap: 8px; + padding: 16px; color: var(--text-muted); - font-size: var(--font-size-md); + font-size: var(--type-prose); } /* Thinking indicator */ @@ -1368,7 +1368,7 @@ display: inline-block; width: 6px; height: 14px; - background: var(--copper); + background: var(--color-orange); border-radius: 1px; vertical-align: text-bottom; margin-left: 2px; @@ -1385,7 +1385,7 @@ width: 12px; height: 12px; border-radius: 50%; - background: var(--copper); + background: var(--color-orange); animation: thinking-pulse 1.5s ease-in-out infinite; } @@ -1394,11 +1394,11 @@ /* Section label for launch page cards */ .launch-section-label { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.06em; - margin-bottom: var(--space-2); + margin-bottom: 8px; } .launch-project-dir { @@ -1407,15 +1407,15 @@ gap: 8px; margin-bottom: 24px; font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); } .launch-project-dir-label { - color: var(--text-ghost); + color: var(--text-placeholder); } .launch-project-dir-path { - color: var(--text); + color: var(--text-body); font-weight: 500; } @@ -1423,28 +1423,28 @@ .launch-workflow-grid { display: flex; gap: 12px; - margin-top: var(--space-2); + margin-top: 8px; } .launch-workflow-card { flex: 1; - border: 2px solid var(--border); - border-radius: var(--radius-md); - padding: var(--space-4); - background: var(--bg-elevated); + border: 2px solid var(--border-card); + border-radius: var(--radius-xl); + padding: 16px; + background: var(--bg-card); cursor: pointer; text-align: left; transition: border-color var(--duration-fast), background var(--duration-fast); - font-family: var(--font-sans); + font-family: var(--font-body); } .launch-workflow-card:hover:not(.disabled) { - border-color: var(--border-strong); + border-color: var(--border-input); } .launch-workflow-card.selected { - border-color: var(--copper); - background: var(--copper-bg); + border-color: var(--color-orange); + background: var(--bg-selected); } .launch-workflow-card.disabled { @@ -1463,47 +1463,47 @@ width: 16px; height: 16px; border-radius: 50%; - border: 2px solid var(--border-strong); + border: 2px solid var(--border-input); flex-shrink: 0; transition: border-color var(--duration-fast), box-shadow var(--duration-fast); } .launch-radio-dot.selected { - border-color: var(--copper); - box-shadow: inset 0 0 0 3px var(--copper); + border-color: var(--color-orange); + box-shadow: inset 0 0 0 3px var(--color-orange); } .launch-workflow-card-name { font-weight: 700; - font-size: var(--font-size-md); - color: var(--text-strong); + font-size: var(--type-prose); + color: var(--text-primary); } .launch-badge-soon { font-family: var(--font-mono); - font-size: var(--font-size-xs); - background: var(--bg-inset); + font-size: var(--type-label); + background: var(--bg-tool-row); padding: 2px 8px; - border-radius: var(--radius-sm); + border-radius: var(--radius-md); color: var(--text-muted); } .launch-workflow-card-desc { - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); color: var(--text-muted); line-height: 1.5; } /* Description hint */ .launch-description-hint { - font-size: var(--font-size-sm); - color: var(--text-ghost); + font-size: var(--type-breadcrumb); + color: var(--text-placeholder); margin-bottom: 10px; } /* Configuration groups */ .launch-config-group { - margin-bottom: var(--space-4); + margin-bottom: 16px; } .launch-config-group:last-child { @@ -1511,9 +1511,9 @@ } .launch-config-label { - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); font-weight: 600; - color: var(--text-strong); + color: var(--text-primary); margin-bottom: 6px; } @@ -1523,17 +1523,17 @@ align-items: center; gap: 10px; padding: 10px 14px; - background: var(--bg); - border: 1px solid var(--border); - border-radius: var(--radius-sm); + background: var(--bg-base); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); margin-bottom: 6px; } .launch-agent-type { font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); font-weight: 600; - color: var(--text-strong); + color: var(--text-primary); min-width: 70px; } @@ -1545,45 +1545,45 @@ } .launch-agent-status.available { - background: var(--green); + background: var(--color-teal); } .launch-agent-status.unavailable { - background: var(--red); + background: var(--status-failed); } .launch-agent-select { flex: 1; - padding: var(--space-1) var(--space-2); - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-sm); - color: var(--text); + padding: var(--gap-tool-rows) 8px; + background: var(--bg-card); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); + color: var(--text-body); font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); outline: none; cursor: pointer; -webkit-appearance: none; appearance: none; - background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8'%3E%3Cpath d='M1 1l5 5 5-5' stroke='%23957E68' stroke-width='1.5' fill='none'/%3E%3C/svg%3E"); + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8'%3E%3Cpath d='M1 1l5 5 5-5' stroke='%239a8e7e' stroke-width='1.5' fill='none'/%3E%3C/svg%3E"); background-repeat: no-repeat; background-position: right 8px center; padding-right: 28px; } .launch-agent-select:focus { - border-color: var(--copper); + border-color: var(--color-orange); } .launch-agent-missing { font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--red); + font-size: var(--type-label); + color: var(--status-failed); } .launch-agent-row.error { - background: var(--red-bg); - border-color: var(--red-border); + background: var(--bg-base); + border-color: var(--status-failed); } /* Scout concurrency row */ @@ -1594,20 +1594,20 @@ } .launch-scouts-hint { - font-size: var(--font-size-sm); - color: var(--text-ghost); + font-size: var(--type-breadcrumb); + color: var(--text-placeholder); } /* ---- Phase boundary ---- */ .activity-phase-boundary { text-align: center; - padding: var(--space-4); + padding: 16px; color: var(--text-muted); - font-size: var(--font-size-sm); - border: 1px dashed var(--border); - border-radius: var(--radius-md); - margin: var(--space-4) 0; - background: var(--bg-elevated); + font-size: var(--type-breadcrumb); + border: 1px dashed var(--border-card); + border-radius: var(--radius-xl); + margin: 16px 0; + background: var(--bg-card); } .activity-boundary-message { diff --git a/frontend/src/styles/layout.css b/frontend/src/styles/layout.css index a9def1e..c813b76 100644 --- a/frontend/src/styles/layout.css +++ b/frontend/src/styles/layout.css @@ -20,7 +20,7 @@ .loading-label { font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); color: var(--text-muted); letter-spacing: 0.05em; } @@ -33,23 +33,23 @@ display: flex; align-items: center; justify-content: space-between; - padding: 0 var(--space-6); - background: var(--bg); - border-bottom: 1px solid var(--border); + padding: 0 24px; + background: var(--bg-base); + border-bottom: 1px solid var(--border-card); } .header-left { display: flex; align-items: center; - gap: var(--space-4); + gap: 16px; } .logo { - font-family: var(--font-sans); - font-size: 20px; - font-weight: 800; - color: var(--text-strong); - letter-spacing: -0.03em; + font-family: var(--font-display); + font-size: var(--type-logo); + font-weight: 500; + color: var(--text-primary); + letter-spacing: -0.3px; } /* Main panel -- fills all remaining vertical space */ @@ -65,7 +65,7 @@ flex: 1 1 0; min-height: 0; overflow-y: auto; - padding: var(--space-6); + padding: 24px; display: flex; flex-direction: column; align-items: center; @@ -81,7 +81,7 @@ flex: 1 1 0; min-height: 0; overflow-y: overlay; - padding: var(--space-6) var(--space-8); + padding: 24px 32px; /* Subtle fade at top when scrolled */ mask-image: linear-gradient(to bottom, transparent, black 8px, black); -webkit-mask-image: linear-gradient(to bottom, transparent, black 8px, black); @@ -93,60 +93,60 @@ .activity-feed-inner { display: flex; flex-direction: column; - gap: var(--space-2); - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); - padding: var(--space-6); + gap: 8px; + background: var(--bg-card); + border: 1px solid var(--border-card); + border-radius: var(--radius-2xl); + padding: 24px; } /* ---- Thinking card -- muted inset that visually recedes ---- */ .activity-card { - background: var(--plum-bg); - border-left: 3px solid var(--plum); - border-radius: 0 var(--radius-sm) var(--radius-sm) 0; - margin: var(--space-2) 0; + background: var(--bg-thinking); + border-left: 3px solid var(--text-thinking-label); + border-radius: 0 var(--radius-md) var(--radius-md) 0; + margin: 8px 0; overflow: hidden; } .activity-card-active { - border-left-color: var(--copper-border); + border-left-color: var(--color-orange); } .activity-card-header { display: flex; justify-content: space-between; align-items: center; - padding: var(--space-2) var(--space-4); + padding: 8px 16px; font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); } .activity-card-tool { - color: var(--plum); + color: var(--text-thinking-label); } .activity-card-thinking .activity-card-tool { - color: var(--plum); + color: var(--text-thinking-label); } .activity-card-debug { - background: var(--copper-bg); - border-left-color: var(--copper); + background: var(--bg-selected); + border-left-color: var(--color-orange); } .activity-card-debug .activity-card-tool { - color: var(--copper); + color: var(--color-orange); } .activity-card-toggle { color: var(--text-muted); - font-size: var(--font-size-xs); + font-size: var(--type-label); } .activity-card-meta { color: var(--text-muted); - font-size: var(--font-size-xs); + font-size: var(--type-label); } .activity-elapsed { @@ -154,7 +154,7 @@ } .activity-card-body { - padding: 0 var(--space-4) var(--space-2); + padding: 0 16px 8px; font-family: var(--font-mono); font-size: 12px; color: var(--text-muted); @@ -169,10 +169,10 @@ } .activity-card-more { - padding: 2px var(--space-4) var(--space-2); + padding: 2px 16px 8px; font-family: var(--font-mono); - font-size: var(--font-size-xs); - color: var(--copper); + font-size: var(--type-label); + color: var(--color-orange); cursor: pointer; user-select: none; } @@ -180,32 +180,32 @@ /* ---- Scout dispatch card ---- */ .activity-card-scouts .activity-card-tool { - color: var(--copper); + color: var(--color-orange); } .scout-list { display: flex; flex-direction: column; gap: 2px; - padding: 0 var(--space-4) var(--space-2); + padding: 0 16px 8px; } .scout-entry { display: flex; align-items: baseline; gap: 10px; - padding: 5px var(--space-2); + padding: 5px 8px; font-family: var(--font-mono); - font-size: var(--font-size-xs); - border-left: 2px solid var(--border); - border-radius: 0 var(--radius-sm) var(--radius-sm) 0; + font-size: var(--type-label); + border-left: 2px solid var(--border-card); + border-radius: 0 var(--radius-md) var(--radius-md) 0; } /* Status-based accent bar colors -- synced with agent status convention */ .scout-queued { border-left-color: var(--text-muted); } -.scout-running { border-left-color: var(--copper); background: var(--copper-bg); } -.scout-completed { border-left-color: var(--green); background: var(--green-bg); } -.scout-failed { border-left-color: var(--red); background: var(--red-bg); } +.scout-running { border-left-color: var(--color-orange); background: var(--bg-selected); } +.scout-completed { border-left-color: var(--color-teal); background: var(--bg-completion); } +.scout-failed { border-left-color: var(--status-failed); background: var(--bg-base); } .scout-name { color: var(--text-muted); @@ -215,18 +215,18 @@ } .scout-role { - color: var(--text-ghost); + color: var(--text-placeholder); } .activity-card-more:hover { - color: var(--text-strong); + color: var(--text-primary); } .activity-line { display: flex; - gap: var(--space-1); + gap: var(--gap-tool-rows); font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); padding: 2px 0; line-height: 1.4; @@ -234,7 +234,7 @@ } .activity-line.activity-done { - color: var(--text-ghost); + color: var(--text-placeholder); } .activity-status { @@ -244,11 +244,11 @@ } .activity-inflight .activity-status { - color: var(--copper); + color: var(--color-orange); } .activity-done .activity-status { - color: var(--green); + color: var(--color-teal); font-size: 10px; } @@ -260,7 +260,7 @@ } .activity-inflight .activity-tool { - color: var(--copper); + color: var(--color-orange); } .activity-summary { @@ -275,21 +275,21 @@ .step-header { display: flex; align-items: baseline; - gap: var(--space-2); - padding: var(--space-4) 0 var(--space-2); - margin-top: var(--space-4); - border-bottom: 1px solid var(--border); + gap: 8px; + padding: 16px 0 8px; + margin-top: 16px; + border-bottom: 1px solid var(--border-card); font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); } .step-header-label { - color: var(--copper); + color: var(--color-orange); font-weight: 600; } .step-header-name { - color: var(--text-strong); + color: var(--text-primary); font-weight: 500; text-transform: capitalize; } @@ -297,25 +297,25 @@ /* Stream output -- LLM text on the shared white surface */ .stream-output { font-family: var(--font-mono); - font-size: var(--font-size-sm); - color: var(--text); - padding: var(--space-4) 0 var(--space-2); + font-size: var(--type-breadcrumb); + color: var(--text-body); + padding: 16px 0 8px; } /* Thinking indicator */ .activity-thinking-indicator { display: flex; align-items: center; - gap: var(--space-2); + gap: 8px; font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); color: var(--text-muted); - padding: var(--space-2) 0; - margin-top: var(--space-2); + padding: 8px 0; + margin-top: 8px; } .activity-detail { - color: var(--text-ghost); + color: var(--text-placeholder); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; @@ -326,30 +326,30 @@ /* ---- Chat input (inside feed card) ---- */ .chat-input-area { - margin-top: var(--space-4); - border-top: 1px solid var(--border); - padding-top: var(--space-4); + margin-top: 16px; + border-top: 1px solid var(--border-card); + padding-top: 16px; } .chat-input-box { - border: 1px solid var(--border); - border-radius: var(--radius-sm); - background: var(--bg-elevated); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); + background: var(--bg-card); transition: border-color 200ms, box-shadow 200ms; } .chat-input-box:focus-within { - border-color: var(--copper); - box-shadow: 0 0 0 3px rgba(188, 108, 37, 0.08); + border-color: var(--color-orange); + box-shadow: 0 0 0 3px var(--focus-ring); } .chat-input-textarea { width: 100%; border: none; background: transparent; - font-family: var(--font-sans); + font-family: var(--font-body); font-size: 14px; - color: var(--text); + color: var(--text-body); padding: 10px 12px; outline: none; resize: none; @@ -360,7 +360,7 @@ } .chat-input-textarea::placeholder { - color: var(--text-ghost); + color: var(--text-placeholder); } .chat-input-textarea:disabled { @@ -378,13 +378,13 @@ .chat-input-hint { font-family: var(--font-mono); font-size: 10px; - color: var(--text-ghost); + color: var(--text-placeholder); } .chat-input-send { font-family: var(--font-mono); font-size: 12px; - color: var(--copper); + color: var(--color-orange); font-weight: 600; background: none; border: none; @@ -395,7 +395,7 @@ } .chat-input-send:hover:not(:disabled) { - background: var(--copper-bg); + background: var(--bg-selected); } .chat-input-send:disabled { @@ -410,7 +410,7 @@ max-height: 40vh; overflow-y: overlay; background: var(--bg-surface); - padding: var(--space-4) var(--space-6); + padding: 16px 24px; } .monitor-inner { @@ -421,13 +421,13 @@ .agent-table-header { display: flex; align-items: center; - gap: var(--space-4); - margin-bottom: var(--space-2); + gap: 16px; + margin-bottom: 8px; } .monitor-label { font-family: var(--font-mono); - font-size: var(--font-size-xs); + font-size: var(--type-label); color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.08em; @@ -435,13 +435,13 @@ .agent-badges { display: flex; - gap: var(--space-1); + gap: var(--gap-tool-rows); } .token-totals { margin-left: auto; font-family: var(--font-mono); - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); color: var(--text-muted); } @@ -475,32 +475,32 @@ width: clamp(180px, 14vw, 240px); flex-shrink: 0; background: var(--bg-surface); - border-right: 1px solid var(--border); + border-right: 1px solid var(--border-card); overflow-y: auto; - padding: var(--space-4); + padding: 16px; font-family: var(--font-mono); } .sidebar-waiting { - color: var(--text-ghost); + color: var(--text-placeholder); font-size: 11px; } .sidebar-divider { height: 1px; - background: var(--border); - margin: var(--space-4) 0; + background: var(--border-card); + margin: 16px 0; } /* Phase section */ .sidebar-phase-section { - margin-bottom: var(--space-2); + margin-bottom: 8px; } .sidebar-section-label { font-size: 10px; - color: var(--text-ghost); + color: var(--text-placeholder); text-transform: uppercase; letter-spacing: 0.08em; margin-bottom: 6px; @@ -509,7 +509,7 @@ .sidebar-phase-name { font-size: 15px; font-weight: 600; - color: var(--text-strong); + color: var(--text-primary); line-height: 1.2; } @@ -527,14 +527,14 @@ .sidebar-step-bar { height: 4px; - background: var(--border); + background: var(--border-card); border-radius: 2px; overflow: hidden; } .sidebar-step-fill { height: 100%; - background: var(--copper); + background: var(--color-orange); border-radius: 2px; transition: width 300ms ease; } @@ -557,14 +557,14 @@ width: 6px; height: 6px; border-radius: 50%; - background: var(--green); + background: var(--color-teal); flex-shrink: 0; } .sidebar-model-name { font-size: 12px; font-weight: 500; - color: var(--text); + color: var(--text-body); } .sidebar-metrics { @@ -582,7 +582,7 @@ } .sidebar-metric-row span:last-child { - color: var(--text); + color: var(--text-body); font-variant-numeric: tabular-nums; } @@ -607,18 +607,18 @@ width: clamp(180px, 14vw, 240px); flex-shrink: 0; background: var(--bg-surface); - border-left: 1px solid var(--border); + border-left: 1px solid var(--border-card); overflow-y: auto; - padding: var(--space-4); + padding: 16px; display: flex; flex-direction: column; } .artifacts-empty { - color: var(--text-ghost); + color: var(--text-placeholder); font-family: var(--font-mono); font-size: 12px; - padding: var(--space-4) 0; + padding: 16px 0; } /* ---- Artifact tree ---- */ @@ -636,13 +636,13 @@ cursor: pointer; font-family: var(--font-mono); font-size: 12px; - border-radius: var(--radius-sm); + border-radius: var(--radius-md); user-select: none; } .tree-folder-label:hover { - color: var(--text-strong); - background: var(--bg-inset); + color: var(--text-primary); + background: var(--bg-tool-row); } .tree-children { @@ -653,31 +653,31 @@ display: flex; flex-direction: column; padding: 3px 4px; - border-radius: var(--radius-sm); + border-radius: var(--radius-md); cursor: pointer; margin-bottom: 1px; } .tree-hover { - background: var(--bg-inset); + background: var(--bg-tool-row); } .tree-file-name { - color: var(--copper); + color: var(--color-orange); font-family: var(--font-mono); font-size: 12px; } .tree-file-meta { - color: var(--text-ghost); + color: var(--text-placeholder); font-family: var(--font-mono); font-size: 11px; } .tree-new-badge { display: inline-block; - background: var(--green); - color: #fff; + background: var(--color-teal); + color: var(--text-on-dark); font-size: 9px; padding: 1px 4px; border-radius: 3px; @@ -690,7 +690,7 @@ .artifact-overlay { position: fixed; inset: 0; - background: rgba(42, 31, 20, 0.5); + background: var(--overlay-backdrop); display: flex; align-items: center; justify-content: center; @@ -698,9 +698,9 @@ } .artifact-overlay-panel { - background: var(--bg-elevated); - border: 1px solid var(--border); - border-radius: var(--radius-lg); + background: var(--bg-card); + border: 1px solid var(--border-card); + border-radius: var(--radius-2xl); width: 860px; max-width: 92vw; max-height: 88vh; @@ -714,7 +714,7 @@ align-items: center; justify-content: space-between; padding: 14px 20px; - border-bottom: 1px solid var(--border); + border-bottom: 1px solid var(--border-card); flex-shrink: 0; } @@ -722,20 +722,20 @@ font-family: var(--font-mono); font-size: 14px; font-weight: 600; - color: var(--text-strong); + color: var(--text-primary); } .artifact-overlay-path { font-family: var(--font-mono); font-size: 11px; - color: var(--text-ghost); + color: var(--text-placeholder); margin-top: 2px; } .artifact-overlay-readonly-badge { font-size: 10px; - color: var(--text-ghost); - border: 1px solid var(--border); + color: var(--text-placeholder); + border: 1px solid var(--border-card); padding: 2px 6px; border-radius: 3px; margin-left: 8px; diff --git a/frontend/src/styles/markdown.css b/frontend/src/styles/markdown.css index ae4c925..2f858ff 100644 --- a/frontend/src/styles/markdown.css +++ b/frontend/src/styles/markdown.css @@ -15,7 +15,7 @@ .markdown h2, .markdown h3, .markdown h4 { - color: var(--text-strong); + color: var(--text-primary); font-family: var(--font-mono); margin: 1em 0 0.4em; line-height: 1.3; @@ -34,8 +34,8 @@ .markdown code { font-family: var(--font-mono); font-size: 0.9em; - background: var(--bg-muted); - border: 1px solid var(--border); + background: var(--bg-tool-row); + border: 1px solid var(--border-card); border-radius: 3px; padding: 1px 4px; } @@ -43,10 +43,10 @@ /* Code blocks — override inline code styles */ .markdown pre { margin: 0.6em 0; - padding: var(--space-2) var(--space-4); - background: var(--bg-muted); - border: 1px solid var(--border); - border-radius: var(--radius-sm); + padding: 8px 16px; + background: var(--bg-tool-row); + border: 1px solid var(--border-card); + border-radius: var(--radius-md); overflow-x: auto; } @@ -55,7 +55,7 @@ border: none; border-radius: 0; padding: 0; - font-size: var(--font-size-sm); + font-size: var(--type-breadcrumb); line-height: 1.5; } @@ -90,22 +90,22 @@ .markdown th, .markdown td { - border: 1px solid var(--border); + border: 1px solid var(--border-card); padding: 4px 8px; text-align: left; } .markdown th { - background: var(--bg-muted); + background: var(--bg-tool-row); font-weight: 600; - color: var(--text-strong); + color: var(--text-primary); } /* Blockquotes */ .markdown blockquote { margin: 0.5em 0; - padding: 2px 0 2px var(--space-4); - border-left: 3px solid var(--border-strong); + padding: 2px 0 2px 16px; + border-left: 3px solid var(--border-input); color: var(--text-muted); } @@ -116,20 +116,20 @@ /* Horizontal rules */ .markdown hr { border: none; - border-top: 1px solid var(--border); + border-top: 1px solid var(--border-card); margin: 0.8em 0; } /* Links */ .markdown a { - color: var(--copper); + color: var(--color-orange); text-decoration: underline; - text-decoration-color: var(--copper-border); + text-decoration-color: var(--color-orange); text-underline-offset: 2px; } .markdown a:hover { - color: var(--text-strong); + color: var(--text-primary); } /* Task lists (via remark-gfm) */ @@ -146,7 +146,7 @@ /* Strong / emphasis */ .markdown strong { - color: var(--text-strong); + color: var(--text-primary); font-weight: 600; } @@ -154,5 +154,5 @@ .markdown img { max-width: 100%; height: auto; - border-radius: var(--radius-sm); + border-radius: var(--radius-md); } diff --git a/frontend/src/styles/variables.css b/frontend/src/styles/variables.css index ce2705a..0f8528c 100644 --- a/frontend/src/styles/variables.css +++ b/frontend/src/styles/variables.css @@ -1,76 +1,249 @@ +/* ========================================================================== + * Koan Design Tokens + * ========================================================================== + * Source of truth: docs/design-system.md + * This file defines ALL visual tokens. Components reference var(--token) + * exclusively — no raw hex, px, or font-family values in component CSS. + * ========================================================================== */ + + +/* -------------------------------------------------------------------------- + * TOKEN MIGRATION MAP + * -------------------------------------------------------------------------- + * Old token → New token(s) + * + * --bg → --bg-base + * --bg-surface → --bg-surface + * --bg-elevated → --bg-card + * --bg-inset → --bg-tool-row (closest equivalent) + * --bg-muted → --bg-tool-row (was undefined; used in markdown.css) + * + * --text → --text-body + * --text-strong → --text-primary + * --text-muted → --text-muted (same name, new value) + * --text-ghost → --text-placeholder or --text-hint + * + * --border → --border-card + * --border-strong → --border-input + * + * --green → --status-done / --color-teal + * --green-bg → --bg-completion + * --green-border → --color-teal (border usage) + * --copper → --color-orange / --status-running + * --copper-bg → --bg-selected + * --copper-border → --color-orange (border usage) + * --caramel → --color-orange (no separate caramel in new system) + * --caramel-bg → --bg-selected + * --caramel-border → --color-orange + * --red → --status-failed + * --red-bg → (no equivalent bg; use light tint or --bg-base) + * --red-border → --status-failed + * --ochre → --color-orange (warning/in-flight → orange) + * --ochre-bg → --bg-selected + * --ochre-border → --color-orange + * --plum → --text-thinking-label / --color-navy + * --plum-bg → --bg-thinking + * + * --font-sans → --font-body + * --font-mono → --font-mono (same name, updated stack) + * (new) → --font-display (serif, logo only) + * + * --font-size-xs (11px) → --type-label (11px) + * --font-size-sm (13px) → --type-breadcrumb (13px) + * --font-size-md (15px) → --type-prose (15px) + * --font-size-lg (17px) → --type-section-title (17px) + * --font-size-xl (22px) → (removed; closest --type-page-title 26px) + * --font-size-display(28px)→ (removed; closest --type-page-title 26px) + * + * --space-1 (4px) → --gap-tool-rows (3px) (closest) + * --space-2 (8px) → (component-specific padding tokens) + * --space-4 (16px) → (component-specific padding/gap tokens) + * --space-6 (24px) → --padding-card-form / --gap-form-sections + * --space-8 (32px) → --page-padding + * --space-12 (48px) → (removed) + * --space-16 (64px) → (removed) + * + * --radius-sm (6px) → --radius-md (6px) + * --radius-md (10px) → --radius-xl (10px) + * --radius-lg (14px) → --radius-2xl (12px) + * + * --duration-fast (150ms) → --duration-fast (preserved) + * --duration-normal (250ms)→ --duration-normal (preserved) + * --duration-slow (400ms) → --duration-slow (preserved) + * --ease-default (ease-out)→ --ease-default (preserved) + * + * --header-height (56px) → --header-height (50px) + * --monitor-min-height → (removed; scout bar is auto-sized) + * -------------------------------------------------------------------------- */ + + +/* -------------------------------------------------------------------------- + * HARDCODED VALUES TO MIGRATE + * -------------------------------------------------------------------------- + * These raw values appear in component CSS files and should eventually be + * replaced with token references during the component migration step. + * + * layout.css line 343: rgba(188, 108, 37, 0.08) → focus ring, derive from --color-orange + * layout.css line 680: #fff → white text on status bg → --text-on-dark or explicit white token + * layout.css line 693: rgba(42, 31, 20, 0.5) → overlay backdrop → define --overlay-backdrop + * layout.css line 49: font-size: 20px → logo size → --type-logo (17px) + * layout.css line 76: max-width: 960px → content max-width → --form-max-width or layout token + * layout.css line 9: max-width: 1600px → app max-width → layout token + * + * components.css line 455: #fff → checkbox check color → white on accent + * components.css line 602: #fff → primary button text → white on accent + * components.css line 691: #fff → notification text → --text-on-dark + * components.css line 783: %23957E68 → SVG chevron stroke → derive from --text-muted + * components.css line 836: rgba(78, 122, 66, 0.12) → result flash → derive from --color-teal + * components.css line 1097: rgba(42, 31, 20, 0.5) → settings backdrop → --overlay-backdrop + * components.css line 1568: %23957E68 → SVG chevron stroke → derive from --text-muted + * + * SettingsOverlay.tsx line 158: marginTop: 12 → spacing token + * SettingsOverlay.tsx line 282: padding/fontSize → token refs + * SettingsOverlay.tsx line 299: marginTop: 12 → spacing token + * SettingsOverlay.tsx line 472: marginTop: 24 → spacing token + * SettingsOverlay.tsx line 576: marginTop: 24 → spacing token + * Completion.tsx line 33: color: 'var(--red)' → --status-failed + * -------------------------------------------------------------------------- */ + + :root { - /* Background layers */ - --bg: #FEFAE0; /* cornsilk base -- "the desk" */ - --bg-surface: #E0D8C8; /* stone -- sidebars, panels, monitor */ - --bg-elevated: #FFFFFF; /* cards, overlays -- "paper on paper" */ - --bg-inset: #D4CCB8; /* pressed/inset areas */ - - /* Borders */ - --border: #C8C0A8; - --border-strong: #B8B098; - - /* Text hierarchy */ - --text: #4A4428; /* Olive-brown -- default body */ - --text-strong: #283618; /* Black Forest -- headings */ - --text-muted: #7A7450; /* Dried sage -- metadata */ - --text-ghost: #A09A6E; /* Faded straw -- disabled/placeholder */ - - /* Status -- the ONLY saturated colors */ - --green: #606C38; - --green-bg: #EEF2E4; - --green-border: #606C38; - --copper: #BC6C25; - --copper-bg: #FDF3E4; - --copper-border: #BC6C25; - --caramel: #DDA15E; - --caramel-bg: #FEF7E8; - --caramel-border: #DDA15E; - --red: #9A3412; - --red-bg: #FEF0E8; - --red-border: #9A3412; - --ochre: #92810A; - --ochre-bg: #FEFCE8; - --ochre-border: #92810A; - --plum: #606C38; - --plum-bg: #EEF2E4; - - /* Typography */ - --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; - --font-mono: 'SF Mono', 'JetBrains Mono', 'Cascadia Code', 'Fira Code', monospace; - - /* Font sizes */ - --font-size-xs: 11px; - --font-size-sm: 13px; - --font-size-md: 15px; - --font-size-lg: 17px; - --font-size-xl: 22px; - --font-size-display: 28px; - - /* Spacing (base unit 4px) */ - --space-1: 4px; - --space-2: 8px; - --space-4: 16px; - --space-6: 24px; - --space-8: 32px; - --space-12: 48px; - --space-16: 64px; - - /* Shape */ - --radius-sm: 6px; - --radius-md: 10px; - --radius-lg: 14px; - - /* Motion */ - --duration-fast: 150ms; - --duration-normal: 250ms; - --duration-slow: 400ms; - --ease-default: ease-out; - - /* Layout */ - --header-height: 56px; - --monitor-min-height: 120px; + + /* ===== Core Colors ===== */ + --color-navy: #2e3a5e; + --color-orange: #d4775a; + --color-teal: #5a9a8a; + + + /* ===== Background Surfaces ===== */ + --bg-base: #f8f6f2; + --bg-surface: #f3efe8; + --bg-card: #ffffff; + --bg-tool-row: #f0ede6; + --bg-thinking: #eae5f2; + --bg-step-guidance: #efece6; + --bg-completion: #e8f5ee; + --bg-selected: #fdf8f5; + + + /* ===== Text Colors (light backgrounds) ===== */ + --text-primary: #2e3a5e; + --text-body: #4a4a5a; + --text-muted: #9a8e7e; + --text-subtle: #7a6e60; + --text-placeholder: #b0a498; + --text-hint: #c8baa8; + --text-thinking: #3a3460; + --text-thinking-label: #5a5080; + --text-completion: #2a6a4a; + --text-artifact-time: #a89888; + + + /* ===== Text Colors (dark backgrounds — header, scout bar) ===== */ + --text-on-dark: #f0e8d8; + --text-on-dark-muted: rgba(240, 232, 216, 0.55); + --text-on-dark-subtle: rgba(240, 232, 216, 0.4); + --text-on-dark-faint: rgba(255, 255, 255, 0.15); + --text-on-dark-scouts-muted: rgba(240, 232, 216, 0.45); + + + /* ===== Border Colors ===== */ + --border-card: #eae6e0; + --border-input: #c8c0b4; + --border-radio: #e0d8cc; + --border-divider: #e8e2d8; + --border-divider-light: #f0ebe4; + + + /* ===== Semantic Status Colors ===== */ + --status-running: #d4775a; + --status-done: #5a9a8a; + --status-queued: #b8aca0; + --status-failed: #c44; + + + /* ===== Font Families ===== */ + --font-display: Georgia, "Times New Roman", serif; + --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; + --font-mono: "SF Mono", "Fira Code", "Cascadia Code", monospace; + + + /* ===== Type Scale (font-size values only) ===== */ + --type-page-title: 26px; + --type-logo: 17px; + --type-section-title: 17px; + --type-step-header: 16px; + --type-prose: 15px; + --type-body: 14px; + --type-step-indicator: 14px; + --type-breadcrumb: 13px; + --type-tool-type: 12px; + --type-tool-path: 12px; + --type-label: 11px; + --type-badge: 10px; + --type-timestamp: 10px; + + + /* ===== Spacing — Page-level ===== */ + --page-padding: 28px 32px; + --sidebar-padding: 20px 16px; + --header-height: 50px; + --form-max-width: 640px; + --form-page-padding: 40px 24px; + + + /* ===== Spacing — Component Gaps ===== */ + --gap-content: 20px; + --gap-tool-rows: 3px; + --gap-artifact-cards: 10px; + --gap-form-sections: 28px; + --gap-radio-options: 10px; + --gap-scout-summary: 16px; + --gap-progress-segments: 3px; + + + /* ===== Spacing — Component Internal Padding ===== */ + --padding-card: 14px 20px; + --padding-card-form: 20px 24px; + --padding-tool-row: 7px 14px; + --padding-step-guidance: 8px 16px; + --padding-artifact: 10px 12px; + --padding-scout-bar: 14px 24px; + --padding-scout-row: 8px 14px; + --padding-input: 14px 18px; + --padding-radio: 12px 14px; + + + /* ===== Border Radius ===== */ + --radius-sm: 3px; + --radius-md: 6px; + --radius-lg: 8px; + --radius-xl: 10px; + --radius-2xl: 12px; + --radius-pill: 20px; + --radius-circle: 50%; + + + /* ===== Preserved from Original ===== */ + /* Motion tokens — not redefined in the new design system; kept as-is */ + --duration-fast: 150ms; + --duration-normal: 250ms; + --duration-slow: 400ms; + --ease-default: ease-out; + + + /* ===== Derived Tokens ===== */ + /* These are not in the design system doc but are needed by component CSS. + * Each is derived from a core token or replaces a hardcoded value. */ + --overlay-backdrop: rgba(46, 58, 94, 0.45); /* navy-tinted translucent backdrop for modals/overlays */ + --focus-ring: rgba(212, 119, 90, 0.12); /* orange-derived focus ring glow */ + --flash-teal: rgba(90, 154, 138, 0.12); /* teal-derived result flash animation */ + --bg-card-warm: #faf8f4; /* slightly warmer white for artifact cards, scout table interior (from design-system.md) */ } + +/* ===== Global Reset (preserved) ===== */ + *, *::before, *::after { box-sizing: border-box; } @@ -79,16 +252,18 @@ html, body { margin: 0; padding: 0; height: 100%; - background: var(--bg); - color: var(--text); - font-family: var(--font-sans); - font-size: var(--font-size-md); - line-height: 1.6; + background: var(--bg-base); + color: var(--text-body); + font-family: var(--font-body); + font-size: var(--type-prose); + line-height: 1.7; } +/* ===== Scrollbar Styling (updated to new palette) ===== */ + * { scrollbar-width: thin; - scrollbar-color: var(--border-strong) transparent; + scrollbar-color: var(--border-input) transparent; } ::-webkit-scrollbar { @@ -101,7 +276,7 @@ html, body { } ::-webkit-scrollbar-thumb { - background: var(--border-strong); + background: var(--border-input); border-radius: 4px; } From ede5077d9e13528f1034903c0cf8fd285eb9a30b Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 5 Apr 2026 17:40:11 +0700 Subject: [PATCH 333/412] feat: add atom components for new design system --- frontend/src/components/atoms/Badge.css | 16 ++++++++++ frontend/src/components/atoms/Badge.tsx | 26 +++++++++++++++++ frontend/src/components/atoms/Button.css | 16 ++++++++++ frontend/src/components/atoms/Button.tsx | 29 +++++++++++++++++++ frontend/src/components/atoms/LogoMark.css | 25 ++++++++++++++++ frontend/src/components/atoms/LogoMark.tsx | 27 +++++++++++++++++ .../src/components/atoms/ProgressSegment.css | 11 +++++++ .../src/components/atoms/ProgressSegment.tsx | 22 ++++++++++++++ .../src/components/atoms/SectionLabel.css | 12 ++++++++ .../src/components/atoms/SectionLabel.tsx | 26 +++++++++++++++++ frontend/src/components/atoms/StatusDot.css | 15 ++++++++++ frontend/src/components/atoms/StatusDot.tsx | 27 +++++++++++++++++ 12 files changed, 252 insertions(+) create mode 100644 frontend/src/components/atoms/Badge.css create mode 100644 frontend/src/components/atoms/Badge.tsx create mode 100644 frontend/src/components/atoms/Button.css create mode 100644 frontend/src/components/atoms/Button.tsx create mode 100644 frontend/src/components/atoms/LogoMark.css create mode 100644 frontend/src/components/atoms/LogoMark.tsx create mode 100644 frontend/src/components/atoms/ProgressSegment.css create mode 100644 frontend/src/components/atoms/ProgressSegment.tsx create mode 100644 frontend/src/components/atoms/SectionLabel.css create mode 100644 frontend/src/components/atoms/SectionLabel.tsx create mode 100644 frontend/src/components/atoms/StatusDot.css create mode 100644 frontend/src/components/atoms/StatusDot.tsx diff --git a/frontend/src/components/atoms/Badge.css b/frontend/src/components/atoms/Badge.css new file mode 100644 index 0000000..0338173 --- /dev/null +++ b/frontend/src/components/atoms/Badge.css @@ -0,0 +1,16 @@ +.atom-badge { + display: inline-flex; + align-items: center; + font-size: var(--type-badge); + font-weight: 500; + border-radius: var(--radius-pill); + padding: 2px 8px; + white-space: nowrap; + line-height: 1.4; +} + +/* Variants */ +.atom-badge--neutral { background: var(--bg-step-guidance); color: var(--text-muted); } +.atom-badge--success { background: var(--bg-completion); color: var(--text-completion); } +.atom-badge--accent { background: var(--bg-selected); color: var(--color-orange); } +.atom-badge--model { background: var(--bg-step-guidance); color: var(--text-muted); } diff --git a/frontend/src/components/atoms/Badge.tsx b/frontend/src/components/atoms/Badge.tsx new file mode 100644 index 0000000..c7d6508 --- /dev/null +++ b/frontend/src/components/atoms/Badge.tsx @@ -0,0 +1,26 @@ +/** + * Badge — pill-shaped inline label for metadata and status. + * + * Used for: "coming soon", "recommended", "haiku" model labels, + * and other small inline indicators throughout the UI. + */ + +import './Badge.css' +import type { ReactNode } from 'react' + +type Variant = 'neutral' | 'success' | 'accent' | 'model' + +interface BadgeProps { + variant: Variant + children: ReactNode +} + +export function Badge({ variant, children }: BadgeProps) { + return ( + <span className={`atom-badge atom-badge--${variant}`}> + {children} + </span> + ) +} + +export default Badge diff --git a/frontend/src/components/atoms/Button.css b/frontend/src/components/atoms/Button.css new file mode 100644 index 0000000..6ac6cff --- /dev/null +++ b/frontend/src/components/atoms/Button.css @@ -0,0 +1,16 @@ +.atom-btn { + font-family: var(--font-body); + font-weight: 500; + cursor: pointer; + border: none; + transition: opacity var(--duration-fast) var(--ease-default); +} +.atom-btn:disabled { opacity: 0.45; cursor: not-allowed; } + +/* Variants */ +.atom-btn--primary { background: var(--color-orange); color: var(--text-on-dark); } +.atom-btn--secondary { background: transparent; color: var(--text-subtle); border: 1.5px solid var(--border-input); } + +/* Sizes */ +.atom-btn--sm { padding: 5px 16px; font-size: 13px; border-radius: var(--radius-md); } +.atom-btn--md { padding: 10px 28px; font-size: 15px; border-radius: var(--radius-lg); } diff --git a/frontend/src/components/atoms/Button.tsx b/frontend/src/components/atoms/Button.tsx new file mode 100644 index 0000000..0d282d0 --- /dev/null +++ b/frontend/src/components/atoms/Button.tsx @@ -0,0 +1,29 @@ +/** + * Button — primary and secondary action triggers. + * + * Used for: "Start Run", "Next", "Send", "Use Defaults", + * and other interactive actions throughout the UI. + */ + +import './Button.css' +import type { ReactNode, ButtonHTMLAttributes } from 'react' + +type Variant = 'primary' | 'secondary' +type Size = 'sm' | 'md' + +interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> { + variant: Variant + size?: Size + children: ReactNode +} + +export function Button({ variant, size = 'md', children, className, ...rest }: ButtonProps) { + const cls = `atom-btn atom-btn--${variant} atom-btn--${size}${className ? ` ${className}` : ''}` + return ( + <button className={cls} {...rest}> + {children} + </button> + ) +} + +export default Button diff --git a/frontend/src/components/atoms/LogoMark.css b/frontend/src/components/atoms/LogoMark.css new file mode 100644 index 0000000..09e1f81 --- /dev/null +++ b/frontend/src/components/atoms/LogoMark.css @@ -0,0 +1,25 @@ +.logo-mark { + position: relative; + display: inline-block; + flex-shrink: 0; +} + +.logo-mark__orange { + position: absolute; + top: 0; + left: 0; + width: 16px; + height: 16px; + border-radius: var(--radius-circle); + background: var(--color-orange); +} + +.logo-mark__teal { + position: absolute; + bottom: 0; + right: 0; + width: 10px; + height: 10px; + border-radius: var(--radius-circle); + background: var(--color-teal); +} diff --git a/frontend/src/components/atoms/LogoMark.tsx b/frontend/src/components/atoms/LogoMark.tsx new file mode 100644 index 0000000..9628333 --- /dev/null +++ b/frontend/src/components/atoms/LogoMark.tsx @@ -0,0 +1,27 @@ +/** + * LogoMark — the koan geometric brand mark. + * + * Two overlapping circles: 16px orange (top-left) and 10px teal + * (bottom-right). Pure CSS, no SVG. Used in: header bar. + */ + +import './LogoMark.css' + +interface LogoMarkProps { + size?: number +} + +export function LogoMark({ size = 20 }: LogoMarkProps) { + return ( + <span + className="logo-mark" + style={{ width: size, height: size }} + aria-hidden="true" + > + <span className="logo-mark__orange" /> + <span className="logo-mark__teal" /> + </span> + ) +} + +export default LogoMark diff --git a/frontend/src/components/atoms/ProgressSegment.css b/frontend/src/components/atoms/ProgressSegment.css new file mode 100644 index 0000000..3a47097 --- /dev/null +++ b/frontend/src/components/atoms/ProgressSegment.css @@ -0,0 +1,11 @@ +.progress-segment { + display: inline-block; + width: 24px; + height: 4px; + border-radius: var(--radius-md); +} + +/* States */ +.progress-segment--completed { background: var(--color-teal); } +.progress-segment--active { background: var(--color-orange); } +.progress-segment--future { background: var(--text-on-dark-faint); } diff --git a/frontend/src/components/atoms/ProgressSegment.tsx b/frontend/src/components/atoms/ProgressSegment.tsx new file mode 100644 index 0000000..5d3e0b6 --- /dev/null +++ b/frontend/src/components/atoms/ProgressSegment.tsx @@ -0,0 +1,22 @@ +/** + * ProgressSegment — a single bar in the header progress indicator. + * + * Composed as a row of segments to show workflow step progress. + * Used in: header bar (e.g., 3 segments for intake steps). + */ + +import './ProgressSegment.css' + +type State = 'completed' | 'active' | 'future' + +interface ProgressSegmentProps { + state: State +} + +export function ProgressSegment({ state }: ProgressSegmentProps) { + return ( + <span className={`progress-segment progress-segment--${state}`} /> + ) +} + +export default ProgressSegment diff --git a/frontend/src/components/atoms/SectionLabel.css b/frontend/src/components/atoms/SectionLabel.css new file mode 100644 index 0000000..1a16f24 --- /dev/null +++ b/frontend/src/components/atoms/SectionLabel.css @@ -0,0 +1,12 @@ +.section-label { + font-size: var(--type-label); + font-weight: 500; + text-transform: uppercase; + letter-spacing: 1px; + line-height: 1; +} + +/* Color variants */ +.section-label--default { color: var(--text-muted); } +.section-label--teal { color: var(--color-teal); } +.section-label--orange { color: var(--color-orange); } diff --git a/frontend/src/components/atoms/SectionLabel.tsx b/frontend/src/components/atoms/SectionLabel.tsx new file mode 100644 index 0000000..9cea4d2 --- /dev/null +++ b/frontend/src/components/atoms/SectionLabel.tsx @@ -0,0 +1,26 @@ +/** + * SectionLabel — uppercase label for content sections. + * + * Used for: "ARTIFACTS", "SCOUTS", "CONTEXT", "DECISION", + * "THINKING", and other section headings. + */ + +import './SectionLabel.css' +import type { ReactNode } from 'react' + +type Color = 'default' | 'teal' | 'orange' + +interface SectionLabelProps { + children: ReactNode + color?: Color +} + +export function SectionLabel({ children, color = 'default' }: SectionLabelProps) { + return ( + <span className={`section-label section-label--${color}`}> + {children} + </span> + ) +} + +export default SectionLabel diff --git a/frontend/src/components/atoms/StatusDot.css b/frontend/src/components/atoms/StatusDot.css new file mode 100644 index 0000000..120fac0 --- /dev/null +++ b/frontend/src/components/atoms/StatusDot.css @@ -0,0 +1,15 @@ +.status-dot { + display: inline-block; + border-radius: var(--radius-circle); + flex-shrink: 0; +} + +/* Sizes */ +.status-dot--sm { width: 6px; height: 6px; } +.status-dot--md { width: 8px; height: 8px; } + +/* Status colors */ +.status-dot--running { background: var(--status-running); } +.status-dot--done { background: var(--status-done); } +.status-dot--queued { background: var(--status-queued); } +.status-dot--failed { background: var(--status-failed); } diff --git a/frontend/src/components/atoms/StatusDot.tsx b/frontend/src/components/atoms/StatusDot.tsx new file mode 100644 index 0000000..7e5f528 --- /dev/null +++ b/frontend/src/components/atoms/StatusDot.tsx @@ -0,0 +1,27 @@ +/** + * StatusDot — a small colored circle indicating operational state. + * + * Used in: header orchestrator indicator, scout table rows, + * artifact cards, step guidance pill. + */ + +import './StatusDot.css' + +type Status = 'running' | 'done' | 'queued' | 'failed' +type Size = 'sm' | 'md' + +interface StatusDotProps { + status: Status + size?: Size +} + +export function StatusDot({ status, size = 'md' }: StatusDotProps) { + return ( + <span + className={`status-dot status-dot--${status} status-dot--${size}`} + aria-label={status} + /> + ) +} + +export default StatusDot From d2bc3e2c58f875f4eeca86bfa4762890d4ea36cd Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 5 Apr 2026 17:40:29 +0700 Subject: [PATCH 334/412] feat: add molecule components for new design system --- .../src/components/molecules/ArtifactCard.css | 46 ++++++++++ .../src/components/molecules/ArtifactCard.tsx | 40 +++++++++ .../components/molecules/BreadcrumbNav.css | 29 ++++++ .../components/molecules/BreadcrumbNav.tsx | 44 ++++++++++ .../components/molecules/FeedbackInput.css | 42 +++++++++ .../components/molecules/FeedbackInput.tsx | 70 +++++++++++++++ .../src/components/molecules/ProseCard.css | 51 +++++++++++ .../src/components/molecules/ProseCard.tsx | 28 ++++++ .../src/components/molecules/RadioOption.css | 88 +++++++++++++++++++ .../src/components/molecules/RadioOption.tsx | 63 +++++++++++++ .../src/components/molecules/ScoutRow.css | 69 +++++++++++++++ .../src/components/molecules/ScoutRow.tsx | 38 ++++++++ .../components/molecules/StepGuidancePill.css | 52 +++++++++++ .../components/molecules/StepGuidancePill.tsx | 43 +++++++++ .../components/molecules/ThinkingBlock.css | 69 +++++++++++++++ .../components/molecules/ThinkingBlock.tsx | 43 +++++++++ .../src/components/molecules/ToolCallRow.css | 73 +++++++++++++++ .../src/components/molecules/ToolCallRow.tsx | 39 ++++++++ 18 files changed, 927 insertions(+) create mode 100644 frontend/src/components/molecules/ArtifactCard.css create mode 100644 frontend/src/components/molecules/ArtifactCard.tsx create mode 100644 frontend/src/components/molecules/BreadcrumbNav.css create mode 100644 frontend/src/components/molecules/BreadcrumbNav.tsx create mode 100644 frontend/src/components/molecules/FeedbackInput.css create mode 100644 frontend/src/components/molecules/FeedbackInput.tsx create mode 100644 frontend/src/components/molecules/ProseCard.css create mode 100644 frontend/src/components/molecules/ProseCard.tsx create mode 100644 frontend/src/components/molecules/RadioOption.css create mode 100644 frontend/src/components/molecules/RadioOption.tsx create mode 100644 frontend/src/components/molecules/ScoutRow.css create mode 100644 frontend/src/components/molecules/ScoutRow.tsx create mode 100644 frontend/src/components/molecules/StepGuidancePill.css create mode 100644 frontend/src/components/molecules/StepGuidancePill.tsx create mode 100644 frontend/src/components/molecules/ThinkingBlock.css create mode 100644 frontend/src/components/molecules/ThinkingBlock.tsx create mode 100644 frontend/src/components/molecules/ToolCallRow.css create mode 100644 frontend/src/components/molecules/ToolCallRow.tsx diff --git a/frontend/src/components/molecules/ArtifactCard.css b/frontend/src/components/molecules/ArtifactCard.css new file mode 100644 index 0000000..1f1c961 --- /dev/null +++ b/frontend/src/components/molecules/ArtifactCard.css @@ -0,0 +1,46 @@ +.ac { + display: flex; + align-items: center; + gap: 10px; + padding: var(--padding-artifact); + background: var(--bg-card-warm); + border-radius: var(--radius-lg); + border: 0.5px solid var(--border-divider); +} + +/* ---- Icon square ---- */ +.ac-icon { + width: 28px; + height: 28px; + border-radius: var(--radius-lg); + display: flex; + align-items: center; + justify-content: center; + flex-shrink: 0; +} + +.ac-icon--recent { background: var(--color-navy); } +.ac-icon--stable { background: var(--color-teal); } + +/* ---- Text column ---- */ +.ac-info { + display: flex; + flex-direction: column; + min-width: 0; +} + +.ac-filename { + font-family: var(--font-mono); + font-size: 12px; + font-weight: 500; + color: var(--text-primary); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; +} + +.ac-time { + font-size: var(--type-timestamp); + color: var(--text-artifact-time); + margin-top: 1px; +} diff --git a/frontend/src/components/molecules/ArtifactCard.tsx b/frontend/src/components/molecules/ArtifactCard.tsx new file mode 100644 index 0000000..c2ee1c6 --- /dev/null +++ b/frontend/src/components/molecules/ArtifactCard.tsx @@ -0,0 +1,40 @@ +/** + * ArtifactCard — a file entry in the artifacts sidebar. + * + * Shows a colored icon square, filename (truncated), and a + * last-modified timestamp. "recent" files get a navy icon, + * "stable" files get a teal icon. + * + * Used in: artifacts sidebar. + */ + +import './ArtifactCard.css' + +interface ArtifactCardProps { + filename: string + modifiedAgo: string + variant?: 'recent' | 'stable' +} + +const FileIcon = ({ stroke }: { stroke: string }) => ( + <svg width="12" height="12" viewBox="0 0 24 24" fill="none" aria-hidden="true"> + <path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z" stroke={stroke} strokeWidth="2" /> + <path d="M14 2v6h6" stroke={stroke} strokeWidth="2" /> + </svg> +) + +export function ArtifactCard({ filename, modifiedAgo, variant = 'recent' }: ArtifactCardProps) { + return ( + <div className="ac"> + <span className={`ac-icon ac-icon--${variant}`}> + <FileIcon stroke={variant === 'recent' ? '#b8b0d0' : '#d0f0e8'} /> + </span> + <span className="ac-info"> + <span className="ac-filename">{filename}</span> + <span className="ac-time">{modifiedAgo}</span> + </span> + </div> + ) +} + +export default ArtifactCard diff --git a/frontend/src/components/molecules/BreadcrumbNav.css b/frontend/src/components/molecules/BreadcrumbNav.css new file mode 100644 index 0000000..ec6503d --- /dev/null +++ b/frontend/src/components/molecules/BreadcrumbNav.css @@ -0,0 +1,29 @@ +.bcn { + display: flex; + align-items: center; +} + +.bcn-phase { + font-size: var(--type-breadcrumb); + color: var(--text-on-dark-muted); + font-weight: 400; +} + +.bcn-chevron { + width: 8px; + height: 8px; + flex-shrink: 0; + margin: 0 6px; +} + +.bcn-step { + font-size: var(--type-breadcrumb); + color: var(--text-on-dark); + font-weight: 500; +} + +.bcn-segments { + display: flex; + gap: var(--gap-progress-segments); + margin-left: 12px; +} diff --git a/frontend/src/components/molecules/BreadcrumbNav.tsx b/frontend/src/components/molecules/BreadcrumbNav.tsx new file mode 100644 index 0000000..0077ea8 --- /dev/null +++ b/frontend/src/components/molecules/BreadcrumbNav.tsx @@ -0,0 +1,44 @@ +/** + * BreadcrumbNav — header navigation showing phase, step, and progress. + * + * Displays "Phase > Step" breadcrumb text followed by progress segments. + * Designed for use on a navy (--color-navy) background. + * + * Used in: header bar. + */ + +import { ProgressSegment } from '../atoms/ProgressSegment' +import './BreadcrumbNav.css' + +interface BreadcrumbNavProps { + phase: string + step: string + totalSteps: number + currentStep: number +} + +export function BreadcrumbNav({ phase, step, totalSteps, currentStep }: BreadcrumbNavProps) { + const segments = Array.from({ length: totalSteps }, (_, i) => { + const n = i + 1 + if (n < currentStep) return 'completed' as const + if (n === currentStep) return 'active' as const + return 'future' as const + }) + + return ( + <nav className="bcn" aria-label="Workflow breadcrumb"> + <span className="bcn-phase">{phase}</span> + <svg className="bcn-chevron" viewBox="0 0 24 24" fill="none" aria-hidden="true"> + <path d="M9 6l6 6-6 6" stroke="var(--text-on-dark-subtle)" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" /> + </svg> + <span className="bcn-step">{step}</span> + <span className="bcn-segments"> + {segments.map((state, i) => ( + <ProgressSegment key={i} state={state} /> + ))} + </span> + </nav> + ) +} + +export default BreadcrumbNav diff --git a/frontend/src/components/molecules/FeedbackInput.css b/frontend/src/components/molecules/FeedbackInput.css new file mode 100644 index 0000000..908f8ec --- /dev/null +++ b/frontend/src/components/molecules/FeedbackInput.css @@ -0,0 +1,42 @@ +.fi { + background: var(--bg-card); + border: 1.5px solid var(--border-input); + border-radius: var(--radius-xl); + padding: var(--padding-input); +} + +.fi--disabled { + opacity: 0.5; +} + +/* ---- Textarea ---- */ +.fi-textarea { + display: block; + width: 100%; + border: none; + background: transparent; + font-family: var(--font-body); + font-size: var(--type-body); + color: var(--text-primary); + line-height: 1.5; + resize: vertical; + outline: none; + min-height: 40px; +} + +.fi-textarea::placeholder { + color: var(--text-placeholder); +} + +/* ---- Footer row ---- */ +.fi-footer { + display: flex; + justify-content: space-between; + align-items: center; + margin-top: 10px; +} + +.fi-hint { + font-size: 11px; + color: var(--text-hint); +} diff --git a/frontend/src/components/molecules/FeedbackInput.tsx b/frontend/src/components/molecules/FeedbackInput.tsx new file mode 100644 index 0000000..6ae3c59 --- /dev/null +++ b/frontend/src/components/molecules/FeedbackInput.tsx @@ -0,0 +1,70 @@ +/** + * FeedbackInput — text input for sending feedback/messages to the agent. + * + * Sits at the bottom of the content stream. Enter sends, Shift+Enter + * inserts a newline. Uses the Button atom for the send action. + * + * Used in: activity feed footer, phase-boundary prompts. + */ + +import { useState, useRef, type KeyboardEvent } from 'react' +import { Button } from '../atoms/Button' +import './FeedbackInput.css' + +interface FeedbackInputProps { + placeholder?: string + onSend?: (text: string) => void + disabled?: boolean +} + +export function FeedbackInput({ + placeholder = 'Send feedback...', + onSend, + disabled = false, +}: FeedbackInputProps) { + const [text, setText] = useState('') + const ref = useRef<HTMLTextAreaElement>(null) + + const send = () => { + const trimmed = text.trim() + if (!trimmed || disabled) return + onSend?.(trimmed) + setText('') + ref.current?.focus() + } + + const onKey = (e: KeyboardEvent<HTMLTextAreaElement>) => { + if (e.key === 'Enter' && !e.shiftKey) { + e.preventDefault() + send() + } + } + + return ( + <div className={`fi${disabled ? ' fi--disabled' : ''}`}> + <textarea + ref={ref} + className="fi-textarea" + placeholder={placeholder} + value={text} + onChange={e => setText(e.target.value)} + onKeyDown={onKey} + disabled={disabled} + rows={1} + /> + <div className="fi-footer"> + <span className="fi-hint">Enter to send · Shift+Enter for newline</span> + <Button + variant="primary" + size="sm" + onClick={send} + disabled={disabled || !text.trim()} + > + Send + </Button> + </div> + </div> + ) +} + +export default FeedbackInput diff --git a/frontend/src/components/molecules/ProseCard.css b/frontend/src/components/molecules/ProseCard.css new file mode 100644 index 0000000..f71f78f --- /dev/null +++ b/frontend/src/components/molecules/ProseCard.css @@ -0,0 +1,51 @@ +.prose-card { + background: var(--bg-card); + border: 0.5px solid var(--border-card); + border-left: 3px solid var(--color-orange); + border-radius: var(--radius-xl); + padding: var(--padding-card); + font-size: var(--type-prose); + color: var(--text-primary); + line-height: 1.7; +} + +/* Paragraph spacing within prose */ +.prose-card p { + margin: 0 0 12px 0; +} + +.prose-card p:last-child { + margin-bottom: 0; +} + +/* Inline code inside prose */ +.prose-card code { + background: var(--bg-tool-row); + padding: 1px 5px; + border-radius: var(--radius-sm); + font-family: var(--font-mono); + font-size: 0.88em; + color: var(--text-primary); +} + +/* Lists */ +.prose-card ul, +.prose-card ol { + margin: 0 0 12px 0; + padding-left: 1.5em; +} + +.prose-card ul:last-child, +.prose-card ol:last-child { + margin-bottom: 0; +} + +.prose-card li { + margin: 2px 0; +} + +/* Bold text */ +.prose-card strong { + font-weight: 500; + color: var(--text-primary); +} diff --git a/frontend/src/components/molecules/ProseCard.tsx b/frontend/src/components/molecules/ProseCard.tsx new file mode 100644 index 0000000..11f326f --- /dev/null +++ b/frontend/src/components/molecules/ProseCard.tsx @@ -0,0 +1,28 @@ +/** + * ProseCard — the agent's spoken output surface. + * + * White card with an orange left accent border, distinguishing direct + * agent communication from thinking (lavender) and tool calls (beige). + * This is the primary text surface in the app. + * + * Accepts already-rendered children (from react-markdown or plain JSX). + * + * Used in: activity feed, as the main prose output container. + */ + +import type { ReactNode } from 'react' +import './ProseCard.css' + +interface ProseCardProps { + children: ReactNode +} + +export function ProseCard({ children }: ProseCardProps) { + return ( + <div className="prose-card"> + {children} + </div> + ) +} + +export default ProseCard diff --git a/frontend/src/components/molecules/RadioOption.css b/frontend/src/components/molecules/RadioOption.css new file mode 100644 index 0000000..ec078a7 --- /dev/null +++ b/frontend/src/components/molecules/RadioOption.css @@ -0,0 +1,88 @@ +.ro { + display: flex; + align-items: flex-start; + gap: 12px; + padding: var(--padding-radio); + border-radius: var(--radius-lg); + border: 1.5px solid var(--border-radio); + cursor: pointer; + transition: border-color var(--duration-fast), background var(--duration-fast); +} + +.ro--selected { + border-color: var(--color-orange); + background: var(--bg-selected); +} + +/* ---- Radio circle ---- */ +.ro-circle { + width: 18px; + height: 18px; + border-radius: var(--radius-circle); + border: 2px solid var(--border-input); + flex-shrink: 0; + margin-top: 2px; + display: flex; + align-items: center; + justify-content: center; + transition: border-color var(--duration-fast); +} + +.ro--selected .ro-circle { + border-color: var(--color-orange); +} + +.ro-circle-inner { + width: 8px; + height: 8px; + border-radius: var(--radius-circle); + background: var(--color-orange); +} + +/* ---- Content column (label + optional input) ---- */ +.ro-content { + flex: 1; + min-width: 0; +} + +.ro-label-row { + display: flex; + align-items: flex-start; + gap: 8px; +} + +.ro-label { + font-size: var(--type-body); + color: var(--text-primary); + line-height: 1.5; + flex: 1; +} + +/* Custom / "Other" variant */ +.ro--custom .ro-label { + font-style: italic; + color: var(--text-muted); +} + +/* ---- Custom text input (visible only when isCustom + selected) ---- */ +.ro-custom-input { + display: block; + width: 100%; + padding: 8px 0; + margin-top: 8px; + background: transparent; + border: none; + border-bottom: 1px solid var(--border-card); + font-family: var(--font-body); + font-size: var(--type-body); + color: var(--text-primary); + outline: none; +} + +.ro-custom-input::placeholder { + color: var(--text-placeholder); +} + +.ro-custom-input:focus { + border-bottom-color: var(--border-input); +} diff --git a/frontend/src/components/molecules/RadioOption.tsx b/frontend/src/components/molecules/RadioOption.tsx new file mode 100644 index 0000000..476d966 --- /dev/null +++ b/frontend/src/components/molecules/RadioOption.tsx @@ -0,0 +1,63 @@ +/** + * RadioOption — a selectable option card for elicitation questions. + * + * Renders a radio circle, label text, and optional "recommended" badge. + * Controlled component — parent manages selection state via `selected` + * prop and `onClick` callback. + * + * Used in: deepen/elicitation decision panels. + */ + +import { useEffect, useRef } from 'react' +import { Badge } from '../atoms/Badge' +import './RadioOption.css' + +interface RadioOptionProps { + label: string + selected?: boolean + recommended?: boolean + isCustom?: boolean + customText?: string + onCustomTextChange?: (text: string) => void + onClick?: () => void +} + +export function RadioOption({ label, selected, recommended, isCustom, customText, onCustomTextChange, onClick }: RadioOptionProps) { + const inputRef = useRef<HTMLInputElement>(null) + + useEffect(() => { + if (isCustom && selected) inputRef.current?.focus() + }, [isCustom, selected]) + + return ( + <div + className={`ro${selected ? ' ro--selected' : ''}${isCustom ? ' ro--custom' : ''}`} + onClick={onClick} + role="radio" + aria-checked={selected} + > + <span className="ro-circle"> + {selected && <span className="ro-circle-inner" />} + </span> + <span className="ro-content"> + <span className="ro-label-row"> + <span className="ro-label">{label}</span> + {recommended && <Badge variant="success">recommended</Badge>} + </span> + {isCustom && selected && ( + <input + ref={inputRef} + className="ro-custom-input" + type="text" + placeholder="Type your response..." + value={customText ?? ''} + onChange={e => onCustomTextChange?.(e.target.value)} + onClick={e => e.stopPropagation()} + /> + )} + </span> + </div> + ) +} + +export default RadioOption diff --git a/frontend/src/components/molecules/ScoutRow.css b/frontend/src/components/molecules/ScoutRow.css new file mode 100644 index 0000000..9ceb558 --- /dev/null +++ b/frontend/src/components/molecules/ScoutRow.css @@ -0,0 +1,69 @@ +.sr { + display: grid; + grid-template-columns: 20px minmax(0, 1.5fr) 60px 60px 70px minmax(0, 1fr); + align-items: center; + padding: var(--padding-scout-row); + font-size: 12px; + font-family: var(--font-mono); + border-bottom: 0.5px solid var(--border-divider-light); +} + +.sr:last-child { + border-bottom: none; +} + +/* ---- Cells ---- */ +.sr-dot { + display: flex; + align-items: center; + justify-content: center; +} + +.sr-name { + color: var(--text-primary); + font-weight: 500; + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; +} + +.sr-model { + display: flex; + align-items: center; +} + +.sr-tools { + color: var(--text-muted); +} + +.sr-elapsed { + color: var(--text-muted); +} + +.sr-step { + color: var(--text-muted); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; +} + +.sr-step--active { + color: var(--color-orange); +} + +/* ---- Status variants ---- */ +.sr--done { + opacity: 0.7; +} + +.sr--done .sr-step { + color: var(--color-teal); +} + +.sr--failed .sr-step { + color: var(--status-failed); +} + +.sr--queued { + opacity: 0.5; +} diff --git a/frontend/src/components/molecules/ScoutRow.tsx b/frontend/src/components/molecules/ScoutRow.tsx new file mode 100644 index 0000000..66722dd --- /dev/null +++ b/frontend/src/components/molecules/ScoutRow.tsx @@ -0,0 +1,38 @@ +/** + * ScoutRow — a single data row in the scout/subagent table. + * + * Renders as a CSS grid row conforming to the scout table column + * template. Shows status dot, name, model badge, tool count, + * elapsed time, and current step label. + * + * Used in: scout bar table (ScoutBar organism, not yet built). + */ + +import { StatusDot } from '../atoms/StatusDot' +import { Badge } from '../atoms/Badge' +import './ScoutRow.css' + +interface ScoutRowProps { + name: string + model: string + status: 'running' | 'done' | 'queued' | 'failed' + tools: number + elapsed: string + currentStep: string +} + +export function ScoutRow({ name, model, status, tools, elapsed, currentStep }: ScoutRowProps) { + const stepColor = status === 'done' || status === 'failed' ? undefined : 'running' + return ( + <div className={`sr sr--${status}`}> + <span className="sr-dot"><StatusDot status={status} size="sm" /></span> + <span className="sr-name">{name}</span> + <span className="sr-model"><Badge variant="model">{model}</Badge></span> + <span className="sr-tools">{tools} tools</span> + <span className="sr-elapsed">{elapsed}</span> + <span className={`sr-step${stepColor ? ' sr-step--active' : ''}`}>{currentStep}</span> + </div> + ) +} + +export default ScoutRow diff --git a/frontend/src/components/molecules/StepGuidancePill.css b/frontend/src/components/molecules/StepGuidancePill.css new file mode 100644 index 0000000..952ee75 --- /dev/null +++ b/frontend/src/components/molecules/StepGuidancePill.css @@ -0,0 +1,52 @@ +.sgp-wrapper { + display: flex; + flex-direction: column; + align-items: flex-start; +} + +.sgp { + display: inline-flex; + align-items: center; + gap: 8px; + background: var(--bg-step-guidance); + border-radius: var(--radius-lg); + padding: var(--padding-step-guidance); + border: none; + cursor: pointer; + font-family: inherit; +} + +/* ---- Dot ---- */ +.sgp-dot { + width: 8px; + height: 8px; + border-radius: var(--radius-circle); + flex-shrink: 0; +} + +.sgp-dot--active { background: var(--color-orange); } +.sgp-dot--complete { background: var(--color-teal); } + +/* ---- Label ---- */ +.sgp-label { + font-size: 13px; + font-weight: 500; + color: var(--text-subtle); +} + +/* ---- Chevron ---- */ +.sgp-chevron { + width: 10px; + height: 10px; + flex-shrink: 0; + transition: transform var(--duration-fast) var(--ease-default); +} + +.sgp-chevron--up { + transform: rotate(180deg); +} + +/* ---- Expanded content ---- */ +.sgp-content { + margin-top: 12px; +} diff --git a/frontend/src/components/molecules/StepGuidancePill.tsx b/frontend/src/components/molecules/StepGuidancePill.tsx new file mode 100644 index 0000000..77a554c --- /dev/null +++ b/frontend/src/components/molecules/StepGuidancePill.tsx @@ -0,0 +1,43 @@ +/** + * StepGuidancePill — clickable toggle pill for step guidance content. + * + * Sits at the top of each step's content stream, above the first + * thinking block. Shows a colored dot (orange=active, teal=complete), + * a label, and a chevron that rotates when expanded. + * + * Used in: activity feed, at the beginning of each step. + */ + +import { useState, type ReactNode } from 'react' +import './StepGuidancePill.css' + +interface StepGuidancePillProps { + status?: 'active' | 'complete' + children?: ReactNode + defaultExpanded?: boolean +} + +export function StepGuidancePill({ status = 'active', children, defaultExpanded = false }: StepGuidancePillProps) { + const [expanded, setExpanded] = useState(defaultExpanded) + + return ( + <div className="sgp-wrapper"> + <button + className="sgp" + onClick={() => setExpanded(e => !e)} + aria-expanded={expanded} + > + <span className={`sgp-dot sgp-dot--${status}`} /> + <span className="sgp-label">step guidance</span> + <svg className={`sgp-chevron${expanded ? ' sgp-chevron--up' : ''}`} viewBox="0 0 10 6" fill="none" aria-hidden="true"> + <path d="M1 1l4 4 4-4" stroke="var(--text-subtle)" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" /> + </svg> + </button> + {expanded && children && ( + <div className="sgp-content">{children}</div> + )} + </div> + ) +} + +export default StepGuidancePill diff --git a/frontend/src/components/molecules/ThinkingBlock.css b/frontend/src/components/molecules/ThinkingBlock.css new file mode 100644 index 0000000..a988b46 --- /dev/null +++ b/frontend/src/components/molecules/ThinkingBlock.css @@ -0,0 +1,69 @@ +.thinking-block { + background: var(--bg-thinking); + border-radius: var(--radius-xl); + padding: 16px 20px; +} + +/* ---- Label row ---- */ +.thinking-block__header { + display: flex; + align-items: center; + gap: 6px; + cursor: pointer; + user-select: none; + margin-bottom: 8px; +} + +/* Collapsed: remove bottom margin since there's no body */ +.thinking-block__body ~ .thinking-block__header, +.thinking-block:not(:has(.thinking-block__body)) .thinking-block__header { + margin-bottom: 0; +} + +/* Navy circle with inner lavender dot */ +.thinking-block__icon { + width: 14px; + height: 14px; + border-radius: var(--radius-circle); + background: var(--color-navy); + display: flex; + align-items: center; + justify-content: center; + flex-shrink: 0; +} + +.thinking-block__icon-inner { + width: 6px; + height: 6px; + border-radius: var(--radius-circle); + background: #b8b0d0; /* lavender inner dot — derived from thinking palette */ +} + +.thinking-block__label { + font-size: var(--type-label); + font-weight: 500; + text-transform: uppercase; + letter-spacing: 0.5px; + color: var(--text-thinking-label); +} + +.thinking-block__toggle { + font-size: 10px; + color: var(--text-thinking-label); + margin-left: auto; +} + +/* ---- Body ---- */ +.thinking-block__body { + font-size: var(--type-body); + color: var(--text-thinking); + line-height: 1.65; +} + +.thinking-block__body p { + margin: 0 0 8px 0; +} + +.thinking-block__body p:last-child { + margin-bottom: 0; +} diff --git a/frontend/src/components/molecules/ThinkingBlock.tsx b/frontend/src/components/molecules/ThinkingBlock.tsx new file mode 100644 index 0000000..dd8486e --- /dev/null +++ b/frontend/src/components/molecules/ThinkingBlock.tsx @@ -0,0 +1,43 @@ +/** + * ThinkingBlock — collapsible container for agent internal reasoning. + * + * Lavender background distinguishes thinking from prose output. + * Contains a label row (navy circle + "THINKING") and the reasoning + * body text. Collapses to label-only with a toggle indicator. + * + * Used in: activity feed, between tool call groups and prose cards. + */ + +import { useState, type ReactNode } from 'react' +import './ThinkingBlock.css' + +interface ThinkingBlockProps { + children: ReactNode + defaultExpanded?: boolean +} + +export function ThinkingBlock({ children, defaultExpanded = true }: ThinkingBlockProps) { + const [expanded, setExpanded] = useState(defaultExpanded) + + return ( + <div className="thinking-block"> + <div + className="thinking-block__header" + onClick={() => setExpanded(e => !e)} + > + <span className="thinking-block__icon" aria-hidden="true"> + <span className="thinking-block__icon-inner" /> + </span> + <span className="thinking-block__label">Thinking</span> + <span className="thinking-block__toggle">{expanded ? '▾' : '▸'}</span> + </div> + {expanded && ( + <div className="thinking-block__body"> + {children} + </div> + )} + </div> + ) +} + +export default ThinkingBlock diff --git a/frontend/src/components/molecules/ToolCallRow.css b/frontend/src/components/molecules/ToolCallRow.css new file mode 100644 index 0000000..f4a1510 --- /dev/null +++ b/frontend/src/components/molecules/ToolCallRow.css @@ -0,0 +1,73 @@ +.tcr { + display: flex; + align-items: center; + gap: 10px; + background: var(--bg-tool-row); + border-radius: var(--radius-md); + padding: var(--padding-tool-row); +} + +/* ---- Status indicator column ---- */ +.tcr-indicator { + display: flex; + align-items: center; + justify-content: center; + width: 13px; + flex-shrink: 0; +} + +.tcr-check { + width: 13px; + height: 13px; +} + +.tcr-running-dot { + width: 6px; + height: 6px; + border-radius: var(--radius-circle); + background: var(--status-running); + animation: tcr-pulse 1.5s ease-in-out infinite; +} + +.tcr-error-x { + font-size: 11px; + line-height: 1; + color: var(--status-failed); +} + +/* ---- Type label ---- */ +.tcr-type { + font-size: var(--type-tool-type); + color: var(--text-muted); + min-width: 36px; + flex-shrink: 0; +} + +/* ---- Command / path ---- */ +.tcr-command { + font-family: var(--font-mono); + font-size: var(--type-tool-path); + color: var(--text-body); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; + min-width: 0; +} + +/* ---- Status variants ---- */ +.tcr--running { + opacity: 0.8; +} + +.tcr--error { + background: var(--bg-tool-row); +} + +.tcr--error .tcr-command { + color: var(--status-failed); +} + +@keyframes tcr-pulse { + 0%, 100% { opacity: 0.3; } + 50% { opacity: 1; } +} diff --git a/frontend/src/components/molecules/ToolCallRow.tsx b/frontend/src/components/molecules/ToolCallRow.tsx new file mode 100644 index 0000000..edf0320 --- /dev/null +++ b/frontend/src/components/molecules/ToolCallRow.tsx @@ -0,0 +1,39 @@ +/** + * ToolCallRow — a single row representing a tool call in the activity stream. + * + * Shows a status indicator, tool type label, and the command or file path. + * Rows stack tightly (--gap-tool-rows) within a tool call group, sitting + * between prose output cards in the content stream. + * + * Used in: activity feed, between prose cards and thinking blocks. + */ + +import './ToolCallRow.css' + +interface ToolCallRowProps { + tool: string + command: string + status?: 'done' | 'running' | 'error' +} + +const CheckSvg = () => ( + <svg className="tcr-check" viewBox="0 0 14 14" fill="none" aria-hidden="true"> + <path d="M2.5 7.5L5.5 10.5L11.5 4" stroke="var(--color-teal)" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" /> + </svg> +) + +export function ToolCallRow({ tool, command, status = 'done' }: ToolCallRowProps) { + return ( + <div className={`tcr tcr--${status}`}> + <span className="tcr-indicator"> + {status === 'done' && <CheckSvg />} + {status === 'running' && <span className="tcr-running-dot" />} + {status === 'error' && <span className="tcr-error-x">✕</span>} + </span> + <span className="tcr-type">{tool}</span> + <span className="tcr-command">{command}</span> + </div> + ) +} + +export default ToolCallRow From c8cc929f1ab2aa670d8b6dc3fa516b26a4c11ce1 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 12:23:28 +0700 Subject: [PATCH 335/412] docs: add derived tokens and fix hardcoded values in design system --- docs/design-system.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/design-system.md b/docs/design-system.md index 308a341..960f57a 100644 --- a/docs/design-system.md +++ b/docs/design-system.md @@ -30,6 +30,7 @@ These define the layering system. The hierarchy from back to front is: base → | `--bg-step-guidance` | `#efece6` | Step guidance pill, model badges in scout table, "coming soon" badges. Neutral warm. | | `--bg-completion` | `#e8f5ee` | Completion/success banners. Teal-family light green. | | `--bg-selected` | `#fdf8f5` | Selected card state (e.g., selected workflow option). Very faint orange tint. | +| `--bg-card-warm` | `#faf8f4` | Slightly warmer white for artifact cards, scout table interior, and secondary card surfaces distinguishable from prose cards. | ### Text colors @@ -77,6 +78,16 @@ These are used exclusively for scout status indicators and similar operational s | `--status-queued` | `#b8aca0` | Queued count text. Desaturated warm. | | `--status-failed` | `#c44` | Failed count text. Standard red — used sparingly. | +### Derived colors + +These are derived from core tokens for specific UI effects. Not part of the primary palette. + +| Token | Value | Usage | +|---|---|---| +| `--overlay-backdrop` | `rgba(46, 58, 94, 0.45)` | Navy-tinted translucent backdrop for modals and overlays. | +| `--focus-ring` | `rgba(212, 119, 90, 0.12)` | Orange-derived focus ring glow for input fields. | +| `--flash-teal` | `rgba(90, 154, 138, 0.12)` | Teal-derived background flash for result animations. | + ## Typography ### Font families @@ -109,7 +120,7 @@ All weights are 400 (regular) or 500 (medium). Never use 600 or 700. ### Inline code -Code tokens within prose use: `background: #f0ede6; padding: 1px 5px; border-radius: 3px; font-size: one step below surrounding text; color: #2e3a5e; font-family: var(--font-mono)`. +Code tokens within prose use: `background: var(--bg-tool-row); padding: 1px 5px; border-radius: 3px; font-size: one step below surrounding text; color: var(--text-primary); font-family: var(--font-mono)`. ## Spacing @@ -185,7 +196,7 @@ Lavender block (`--bg-thinking`) with `--radius-xl`. Padding: 16px 20px. Contain ### Tool call row -Background `--bg-tool-row`, `--radius-md`, padding `--padding-tool-row`. Contains a 13px teal checkmark SVG, a tool type label ("bash", "read", "edit") in `--type-tool-type` and `--text-muted` with min-width 36px, and the command/path in `--type-tool-path` and `--font-mono` colored `#4a4a5a`. Rows within a group are spaced `--gap-tool-rows` apart. +Background `--bg-tool-row`, `--radius-md`, padding `--padding-tool-row`. Contains a 13px teal checkmark SVG, a tool type label ("bash", "read", "edit") in `--type-tool-type` and `--text-muted` with min-width 36px, and the command/path in `--type-tool-path` and `--font-mono` colored `var(--text-body)`. Rows within a group are spaced `--gap-tool-rows` apart. ### Step guidance pill @@ -193,13 +204,13 @@ Inline-flex element with `--bg-step-guidance`, `--radius-lg`, padding `--padding ### Artifact card -Background `--bg-card` (specifically `#faf8f4` — slightly warmer than pure white to distinguish from prose cards), `--radius-lg`, `0.5px solid --border-divider`, padding `--padding-artifact`. Contains a 28px square icon with `--radius-lg`: navy background with a lavender file SVG for recently modified artifacts, or teal background with a light-teal file SVG for older/stable artifacts. Next to the icon: filename in `--font-mono` at 12px/500 in `--text-primary`, and timestamp in `--type-timestamp` at `--text-artifact-time`. +Background `--bg-card-warm` (`#faf8f4` — slightly warmer than pure white to distinguish from prose cards), `--radius-lg`, `0.5px solid --border-divider`, padding `--padding-artifact`. Contains a 28px square icon with `--radius-lg`: navy background with a lavender file SVG for recently modified artifacts, or teal background with a light-teal file SVG for older/stable artifacts. Next to the icon: filename in `--font-mono` at 12px/500 in `--text-primary`, and timestamp in `--type-timestamp` at `--text-artifact-time`. ### Scout bar Navy frame (`--color-navy`) with padding `--padding-scout-bar`. The summary line sits directly on navy: an 8px orange dot, "SCOUTS" label in `--text-on-dark-muted` at `--type-label`, then count groups (e.g., "3 running") where the number uses the appropriate status color and the label uses `--text-on-dark-scouts-muted`. -Below the summary, a white table card (`--bg-card` with `#faf8f4`) with `--radius-lg` and no outer border. The table has a header row with column labels in `--type-badge` / `--text-muted`, uppercase, with a `0.5px solid --border-divider` bottom border. Data rows use `--padding-scout-row` with `0.5px solid --border-divider-light` separators (no border on the last row). +Below the summary, a white table card (`--bg-card-warm`) with `--radius-lg` and no outer border. The table has a header row with column labels in `--type-badge` / `--text-muted`, uppercase, with a `0.5px solid --border-divider` bottom border. Data rows use `--padding-scout-row` with `0.5px solid --border-divider-light` separators (no border on the last row). Table columns: status dot (20px col, 6px dot in status color), name (flex, `--font-mono` 12px/500 in `--text-primary`), model (60px, `--text-muted` 11px), tools (60px, `--text-muted`), elapsed (70px, `--text-muted`), status (flex, `--color-orange` for active steps). From cbdabd9e0b7124f8b74788ecf55213aafd78139f Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 12:23:56 +0700 Subject: [PATCH 336/412] docs: rewrite layout section for centered container approach --- docs/design-system.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/design-system.md b/docs/design-system.md index 960f57a..752368a 100644 --- a/docs/design-system.md +++ b/docs/design-system.md @@ -248,9 +248,19 @@ Secondary/outline: `1.5px solid --border-input`, `--text-subtle`, `--radius-lg`. ## Layout -### Three-column workflow view +### Page frame -Used during active workflow phases (Gather, Deepen, Summarize). Grid: `minmax(0, 1fr) 240px`. The main content column scrolls vertically. The artifacts sidebar is fixed-width at 240px with `--bg-surface` background and a 1px `--border-divider` left border. +The page is a flex column filling `100vh`. Three direct children: + +1. **HeaderBar** — `flex-shrink: 0`, full viewport width, `--color-navy` background. +2. **Centered container** — `flex: 1`, `min-height: 0`, `max-width: 1400px`, `margin: 0 auto`, `width: 100%`. Contains the content+sidebar grid. +3. **ScoutBar** (conditional) — `flex-shrink: 0`, full viewport width, `--color-navy` background. Omitted when no scouts are active. + +The HeaderBar and ScoutBar span the full viewport width. The centered container constrains the content grid to 1400px. On wide screens, the space beyond the container edges is `--bg-base` background. No pseudo-elements. No `overflow-x: hidden`. + +### Two-column workflow view + +Used during active workflow phases (Gather, Deepen, Summarize). The centered container is a CSS grid with `grid-template-columns: minmax(0, 1fr) 260px`, filling the height between header and scout bar. The content column (left) scrolls vertically (`overflow-y: auto`, `padding: 28px 32px`) and is at most ~1140px wide — a comfortable reading width without needing further constraint. The artifacts sidebar (right) is 260px with `--bg-surface` background and a 1px `--border-divider` left border. Both columns stretch to fill the full grid height. The sidebar does not touch the right viewport edge on wide screens — this is intentional. ### Centered form view @@ -258,7 +268,7 @@ Used for the "New Run" page. Single centered column with `--form-max-width` (640 ### Scout bar (conditional) -Appears at the bottom of the viewport only during phases where scouts are active. Full-width, `--color-navy` background. Contains the summary line and white table card. Not present on the New Run page or completion views where scouts aren't running. +Appears at the bottom of the viewport only during phases where scouts are active. Full-viewport-width frame element at the same level as the HeaderBar. Contains the summary line and white table card. Not present on the New Run page or completion views where scouts aren't running. ## Logo From b139b61c2fab9dff1d6838800b4577e2482a634d Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 12:24:29 +0700 Subject: [PATCH 337/412] feat: add organism components for new design system --- .../components/organisms/ArtifactsSidebar.css | 27 +++ .../components/organisms/ArtifactsSidebar.tsx | 49 ++++ .../components/organisms/ElicitationPanel.css | 92 +++++++ .../components/organisms/ElicitationPanel.tsx | 87 +++++++ .../src/components/organisms/HeaderBar.css | 73 ++++++ .../src/components/organisms/HeaderBar.tsx | 78 ++++++ .../src/components/organisms/NewRunForm.css | 228 ++++++++++++++++++ .../src/components/organisms/NewRunForm.tsx | 144 +++++++++++ .../src/components/organisms/ScoutBar.css | 76 ++++++ .../src/components/organisms/ScoutBar.tsx | 75 ++++++ 10 files changed, 929 insertions(+) create mode 100644 frontend/src/components/organisms/ArtifactsSidebar.css create mode 100644 frontend/src/components/organisms/ArtifactsSidebar.tsx create mode 100644 frontend/src/components/organisms/ElicitationPanel.css create mode 100644 frontend/src/components/organisms/ElicitationPanel.tsx create mode 100644 frontend/src/components/organisms/HeaderBar.css create mode 100644 frontend/src/components/organisms/HeaderBar.tsx create mode 100644 frontend/src/components/organisms/NewRunForm.css create mode 100644 frontend/src/components/organisms/NewRunForm.tsx create mode 100644 frontend/src/components/organisms/ScoutBar.css create mode 100644 frontend/src/components/organisms/ScoutBar.tsx diff --git a/frontend/src/components/organisms/ArtifactsSidebar.css b/frontend/src/components/organisms/ArtifactsSidebar.css new file mode 100644 index 0000000..3908dbf --- /dev/null +++ b/frontend/src/components/organisms/ArtifactsSidebar.css @@ -0,0 +1,27 @@ +.asb { + width: 260px; + flex-shrink: 0; + background: var(--bg-surface); + border-left: 1px solid var(--border-divider); + padding: var(--sidebar-padding); + display: flex; + flex-direction: column; + overflow-y: auto; +} + +.asb-header { + margin-bottom: 4px; +} + +.asb-list { + display: flex; + flex-direction: column; + gap: var(--gap-artifact-cards); +} + +.asb-empty { + font-size: 12px; + color: var(--text-artifact-time); + text-align: center; + padding: 20px 0; +} diff --git a/frontend/src/components/organisms/ArtifactsSidebar.tsx b/frontend/src/components/organisms/ArtifactsSidebar.tsx new file mode 100644 index 0000000..4b6608b --- /dev/null +++ b/frontend/src/components/organisms/ArtifactsSidebar.tsx @@ -0,0 +1,49 @@ +/** + * ArtifactsSidebar — right-side panel listing spec artifacts. + * + * Fixed 240px column beside the main content stream. Shows a section + * label, a list of ArtifactCard molecules, or an empty-state message + * when no artifacts exist. + * + * Used in: workspace layout, right column. + */ + +import { SectionLabel } from '../atoms/SectionLabel' +import { ArtifactCard } from '../molecules/ArtifactCard' +import './ArtifactsSidebar.css' + +interface ArtifactEntry { + filename: string + modifiedAgo: string + variant?: 'recent' | 'stable' +} + +interface ArtifactsSidebarProps { + artifacts: ArtifactEntry[] +} + +export function ArtifactsSidebar({ artifacts }: ArtifactsSidebarProps) { + return ( + <aside className="asb"> + <div className="asb-header"> + <SectionLabel>Artifacts</SectionLabel> + </div> + {artifacts.length === 0 ? ( + <div className="asb-empty">No artifacts yet</div> + ) : ( + <div className="asb-list"> + {artifacts.map((a, i) => ( + <ArtifactCard + key={i} + filename={a.filename} + modifiedAgo={a.modifiedAgo} + variant={a.variant} + /> + ))} + </div> + )} + </aside> + ) +} + +export default ArtifactsSidebar diff --git a/frontend/src/components/organisms/ElicitationPanel.css b/frontend/src/components/organisms/ElicitationPanel.css new file mode 100644 index 0000000..21bb1f7 --- /dev/null +++ b/frontend/src/components/organisms/ElicitationPanel.css @@ -0,0 +1,92 @@ +.ep-counter { + font-family: var(--font-mono); + font-size: 13px; + color: var(--text-muted); + margin-bottom: 20px; +} + +.ep-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 20px; +} + +/* ---- Panels ---- */ +.ep-panel { + background: var(--bg-card); + border-radius: var(--radius-2xl); + border: 0.5px solid var(--border-card); + padding: var(--padding-card-form); +} + +.ep-panel--context { + border-top: 3px solid var(--color-teal); +} + +.ep-panel--decision { + border-top: 3px solid var(--color-orange); +} + +.ep-panel-body { + margin-top: 12px; + font-size: var(--type-body); + color: var(--text-body); + line-height: 1.65; +} + +.ep-panel-body p { + margin: 0 0 8px 0; +} + +.ep-panel-body p:last-child { + margin-bottom: 0; +} + +.ep-panel-body strong { + font-weight: 500; + color: var(--text-primary); +} + +.ep-panel-body code { + background: var(--bg-tool-row); + padding: 1px 5px; + border-radius: var(--radius-sm); + font-family: var(--font-mono); + font-size: 0.88em; + color: var(--text-primary); +} + +.ep-panel-body ul, +.ep-panel-body ol { + padding-left: 1.5em; + margin: 4px 0 8px; +} + +.ep-panel-body li { + margin: 2px 0; +} + +/* ---- Question ---- */ +.ep-question { + font-family: var(--font-body); + font-size: var(--type-prose); + font-weight: 500; + color: var(--text-primary); + line-height: 1.5; + margin: 12px 0 20px; +} + +/* ---- Options ---- */ +.ep-options { + display: flex; + flex-direction: column; + gap: var(--gap-radio-options); +} + +/* ---- Actions ---- */ +.ep-actions { + display: flex; + align-items: center; + gap: 12px; + margin-top: 24px; +} diff --git a/frontend/src/components/organisms/ElicitationPanel.tsx b/frontend/src/components/organisms/ElicitationPanel.tsx new file mode 100644 index 0000000..ed27a24 --- /dev/null +++ b/frontend/src/components/organisms/ElicitationPanel.tsx @@ -0,0 +1,87 @@ +/** + * ElicitationPanel — two-panel context/decision layout for the Deepen step. + * + * Presents gathered context alongside a question with selectable options. + * Fully controlled — parent manages selection state and actions. + * + * Used in: elicitation interactions during the Deepen intake step. + */ + +import type { ReactNode } from 'react' +import { SectionLabel } from '../atoms/SectionLabel' +import { Button } from '../atoms/Button' +import { RadioOption } from '../molecules/RadioOption' +import './ElicitationPanel.css' + +interface OptionEntry { + label: string + recommended?: boolean + isCustom?: boolean +} + +interface ElicitationPanelProps { + context: ReactNode + question: string + options: OptionEntry[] + selectedIndex: number | null + customText?: string + onSelect: (index: number) => void + onCustomTextChange?: (text: string) => void + onSubmit: () => void + onUseDefaults: () => void + questionNumber?: string +} + +export function ElicitationPanel({ + context, + question, + options, + selectedIndex, + customText, + onSelect, + onCustomTextChange, + onSubmit, + onUseDefaults, + questionNumber, +}: ElicitationPanelProps) { + return ( + <div className="ep"> + {questionNumber && ( + <div className="ep-counter">{questionNumber}</div> + )} + <div className="ep-grid"> + {/* Context panel */} + <div className="ep-panel ep-panel--context"> + <SectionLabel color="teal">Context</SectionLabel> + <div className="ep-panel-body">{context}</div> + </div> + + {/* Decision panel */} + <div className="ep-panel ep-panel--decision"> + <SectionLabel color="orange">Decision</SectionLabel> + <div className="ep-question">{question}</div> + <div className="ep-options"> + {options.map((opt, i) => ( + <RadioOption + key={i} + label={opt.label} + selected={selectedIndex === i} + recommended={opt.recommended} + isCustom={opt.isCustom} + customText={opt.isCustom ? customText : undefined} + onCustomTextChange={opt.isCustom ? onCustomTextChange : undefined} + onClick={() => onSelect(i)} + /> + ))} + </div> + <div className="ep-actions"> + <Button variant="secondary" onClick={onUseDefaults}>Use Defaults</Button> + <Button variant="primary" onClick={onSubmit}>Next</Button> + </div> + </div> + </div> + </div> + ) +} + +export default ElicitationPanel diff --git a/frontend/src/components/organisms/HeaderBar.css b/frontend/src/components/organisms/HeaderBar.css new file mode 100644 index 0000000..ba87d68 --- /dev/null +++ b/frontend/src/components/organisms/HeaderBar.css @@ -0,0 +1,73 @@ +.hb { + background: var(--color-navy); + height: var(--header-height); + padding: 0 24px; + display: flex; + align-items: center; + justify-content: space-between; + flex-shrink: 0; +} + +/* ---- Left group ---- */ +.hb-left { + display: flex; + align-items: center; + gap: 16px; +} + +.hb-logo { + display: flex; + align-items: center; + gap: 8px; +} + +.hb-wordmark { + font-family: var(--font-display); + font-size: var(--type-logo); + font-weight: 500; + color: var(--text-on-dark); + letter-spacing: -0.3px; +} + +.hb-divider { + width: 1px; + height: 18px; + background: var(--text-on-dark-faint); +} + +/* ---- Right group ---- */ +.hb-right { + display: flex; + align-items: center; + gap: 14px; +} + +.hb-orchestrator { + display: flex; + align-items: center; + gap: 6px; +} + +.hb-model { + font-size: 12px; + font-family: var(--font-mono); + color: var(--text-on-dark-muted); +} + +.hb-elapsed { + font-size: 12px; + font-family: var(--font-mono); + color: var(--text-on-dark-subtle); +} + +.hb-settings { + width: 30px; + height: 30px; + border-radius: var(--radius-lg); + border: 1px solid var(--text-on-dark-faint); + background: none; + display: flex; + align-items: center; + justify-content: center; + cursor: pointer; +} diff --git a/frontend/src/components/organisms/HeaderBar.tsx b/frontend/src/components/organisms/HeaderBar.tsx new file mode 100644 index 0000000..a6014a6 --- /dev/null +++ b/frontend/src/components/organisms/HeaderBar.tsx @@ -0,0 +1,78 @@ +/** + * HeaderBar — the fixed navy bar at the top of every view. + * + * Contains the logo mark + wordmark, a vertical divider, breadcrumb + * navigation with progress segments, orchestrator status, elapsed + * time, and a settings button. + * + * Used in: app shell, rendered above all content views. + */ + +import { LogoMark } from '../atoms/LogoMark' +import { StatusDot } from '../atoms/StatusDot' +import { BreadcrumbNav } from '../molecules/BreadcrumbNav' +import './HeaderBar.css' + +interface HeaderBarProps { + phase: string + step: string + totalSteps: number + currentStep: number + orchestratorModel?: string + elapsed?: string + onSettingsClick?: () => void +} + +const GearIcon = () => ( + <svg width="14" height="14" viewBox="0 0 24 24" fill="none" aria-hidden="true"> + <circle cx="12" cy="12" r="3" + stroke="rgba(240,232,216,0.6)" strokeWidth="2" /* warm off-white gear stroke — from design-system.md header spec */ /> + <path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42" + stroke="rgba(240,232,216,0.6)" strokeWidth="2" strokeLinecap="round" /* same warm off-white */ /> + </svg> +) + +export function HeaderBar({ + phase, + step, + totalSteps, + currentStep, + orchestratorModel = 'opus', + elapsed, + onSettingsClick, +}: HeaderBarProps) { + return ( + <header className="hb"> + <div className="hb-left"> + <div className="hb-logo"> + <LogoMark /> + <span className="hb-wordmark">koan</span> + </div> + <span className="hb-divider" /> + <BreadcrumbNav + phase={phase} + step={step} + totalSteps={totalSteps} + currentStep={currentStep} + /> + </div> + + <div className="hb-right"> + <div className="hb-orchestrator"> + <StatusDot status="done" size="sm" /> + <span className="hb-model">{orchestratorModel}</span> + </div> + {elapsed && <span className="hb-elapsed">{elapsed}</span>} + <button + className="hb-settings" + onClick={onSettingsClick} + aria-label="Settings" + > + <GearIcon /> + </button> + </div> + </header> + ) +} + +export default HeaderBar diff --git a/frontend/src/components/organisms/NewRunForm.css b/frontend/src/components/organisms/NewRunForm.css new file mode 100644 index 0000000..9016a69 --- /dev/null +++ b/frontend/src/components/organisms/NewRunForm.css @@ -0,0 +1,228 @@ +.nrf { + max-width: var(--form-max-width); + margin: 0 auto; + padding: var(--form-page-padding); + display: flex; + flex-direction: column; + gap: var(--gap-form-sections); +} + +/* ---- Header ---- */ +.nrf-header { + display: flex; + flex-direction: column; +} + +.nrf-title { + font-size: var(--type-page-title); + font-weight: 500; + color: var(--text-primary); + letter-spacing: -0.5px; + margin: 0 0 6px; +} + +.nrf-project { + font-size: 13px; + font-family: var(--font-mono); + color: var(--text-muted); +} + +/* ---- Card sections ---- */ +.nrf-card { + background: var(--bg-card); + border-radius: var(--radius-2xl); + border: 0.5px solid var(--border-card); + padding: var(--padding-card-form); +} + +/* ---- Workflow selection ---- */ +.nrf-wf-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 12px; + margin-top: 12px; +} + +.nrf-wf-option { + display: flex; + align-items: flex-start; + gap: 10px; + padding: 14px; /* slightly more than --padding-radio for the larger card feel */ + border-radius: var(--radius-xl); + border: 1.5px solid var(--border-radio); + background: var(--bg-card); + cursor: pointer; + text-align: left; + font-family: inherit; +} + +.nrf-wf-option--selected { + border: 2px solid var(--color-orange); + background: var(--bg-selected); +} + +.nrf-wf-option--disabled { + opacity: 0.6; + cursor: not-allowed; +} + +/* Radio circle */ +.nrf-wf-radio { + width: 16px; + height: 16px; + border-radius: var(--radius-circle); + border: 2px solid var(--border-input); + flex-shrink: 0; + margin-top: 2px; + display: flex; + align-items: center; + justify-content: center; +} + +.nrf-wf-radio--selected { + border-color: var(--color-orange); +} + +.nrf-wf-radio-inner { + width: 8px; + height: 8px; + border-radius: var(--radius-circle); + background: var(--color-orange); +} + +.nrf-wf-info { + display: flex; + flex-direction: column; + gap: 2px; +} + +.nrf-wf-name { + font-size: 15px; + font-weight: 500; + color: var(--text-primary); + display: flex; + align-items: center; + gap: 8px; +} + +.nrf-wf-desc { + font-size: 13px; + color: var(--text-subtle); + line-height: 1.4; +} + +/* ---- Description ---- */ +.nrf-helper { + font-size: 13px; + color: var(--text-subtle); + margin: 8px 0 10px; +} + +.nrf-textarea { + display: block; + width: 100%; + min-height: 80px; + padding: 12px 14px; + background: var(--bg-base); + border: 1.5px solid var(--border-input); + border-radius: var(--radius-lg); + font-family: var(--font-body); + font-size: var(--type-body); + color: var(--text-primary); + line-height: 1.5; + resize: vertical; + outline: none; + box-sizing: border-box; +} + +.nrf-textarea:focus { + border-color: var(--color-orange); +} + +/* ---- Configuration ---- */ +.nrf-config-fields { + display: flex; + flex-direction: column; + gap: 18px; + margin-top: 12px; +} + +.nrf-field-label { + font-size: 14px; + font-weight: 500; + color: var(--text-primary); + margin-bottom: 6px; +} + +/* Select-style div */ +.nrf-select { + display: flex; + align-items: center; + justify-content: space-between; + padding: 10px 14px; + background: var(--bg-base); + border: 1.5px solid var(--border-input); + border-radius: var(--radius-lg); + font-family: var(--font-mono); + font-size: var(--type-body); + color: var(--text-primary); +} + +.nrf-select--flex { + flex: 1; +} + +/* Agent row */ +.nrf-agent-row { + display: flex; + align-items: center; + gap: 10px; +} + +.nrf-agent-chip { + display: flex; + align-items: center; + gap: 6px; + padding: 8px 12px; + background: var(--bg-base); + border: 1.5px solid var(--border-input); + border-radius: var(--radius-lg); + flex-shrink: 0; +} + +.nrf-agent-name { + font-family: var(--font-mono); + font-size: var(--type-body); + font-weight: 500; + color: var(--text-primary); +} + +/* Scout concurrency */ +.nrf-concurrency-row { + display: flex; + align-items: center; + gap: 10px; +} + +.nrf-concurrency-input { + width: 60px; + padding: 10px 14px; + background: var(--bg-base); + border: 1.5px solid var(--border-input); + border-radius: var(--radius-lg); + font-family: var(--font-mono); + font-size: var(--type-body); + color: var(--text-primary); + text-align: center; + outline: none; + box-sizing: border-box; +} + +.nrf-concurrency-input:focus { + border-color: var(--color-orange); +} + +.nrf-concurrency-hint { + font-size: 13px; + color: var(--text-muted); +} diff --git a/frontend/src/components/organisms/NewRunForm.tsx b/frontend/src/components/organisms/NewRunForm.tsx new file mode 100644 index 0000000..285aca3 --- /dev/null +++ b/frontend/src/components/organisms/NewRunForm.tsx @@ -0,0 +1,144 @@ +/** + * NewRunForm — standalone form page for starting a new koan run. + * + * Centered column of form sections: workflow selection, description + * textarea, configuration (profile, agent, concurrency), and a + * submit button. No sidebar, no scout bar. + * + * Used in: landing page when no run is active. + */ + +import { SectionLabel } from '../atoms/SectionLabel' +import { Button } from '../atoms/Button' +import { Badge } from '../atoms/Badge' +import { StatusDot } from '../atoms/StatusDot' +import './NewRunForm.css' + +interface NewRunFormProps { + projectPath: string + description: string + onDescriptionChange: (text: string) => void + workflow: 'plan' | 'milestones' + onWorkflowChange: (workflow: 'plan' | 'milestones') => void + profile: string + agentName: string + agentInstallation: string + scoutConcurrency: number + onScoutConcurrencyChange: (n: number) => void + onSubmit: () => void +} + +const ChevronDown = () => ( + <svg width="12" height="8" viewBox="0 0 12 8" fill="none" aria-hidden="true"> + <path d="M1 1l5 5 5-5" stroke="var(--text-muted)" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /> + </svg> +) + +export function NewRunForm({ + projectPath, description, onDescriptionChange, + workflow, onWorkflowChange, + profile, agentName, agentInstallation, + scoutConcurrency, onScoutConcurrencyChange, + onSubmit, +}: NewRunFormProps) { + return ( + <div className="nrf"> + {/* Title + project */} + <div className="nrf-header"> + <h1 className="nrf-title">New Run</h1> + <div className="nrf-project">{projectPath}</div> + </div> + + {/* Workflow */} + <div className="nrf-card"> + <SectionLabel>Workflow</SectionLabel> + <div className="nrf-wf-grid"> + <button + className={`nrf-wf-option${workflow === 'plan' ? ' nrf-wf-option--selected' : ''}`} + onClick={() => onWorkflowChange('plan')} + > + <span className={`nrf-wf-radio${workflow === 'plan' ? ' nrf-wf-radio--selected' : ''}`}> + {workflow === 'plan' && <span className="nrf-wf-radio-inner" />} + </span> + <span className="nrf-wf-info"> + <span className="nrf-wf-name">Plan</span> + <span className="nrf-wf-desc">Plan an approach, review it, then execute</span> + </span> + </button> + <button className="nrf-wf-option nrf-wf-option--disabled" disabled> + <span className="nrf-wf-radio" /> + <span className="nrf-wf-info"> + <span className="nrf-wf-name"> + Milestones <Badge variant="neutral">coming soon</Badge> + </span> + <span className="nrf-wf-desc">Break work into milestones with phased delivery</span> + </span> + </button> + </div> + </div> + + {/* Description */} + <div className="nrf-card"> + <SectionLabel>Description</SectionLabel> + <div className="nrf-helper">What should this run accomplish?</div> + <textarea + className="nrf-textarea" + value={description} + onChange={e => onDescriptionChange(e.target.value)} + rows={4} + /> + </div> + + {/* Configuration */} + <div className="nrf-card"> + <SectionLabel>Configuration</SectionLabel> + <div className="nrf-config-fields"> + {/* Profile */} + <div className="nrf-field"> + <div className="nrf-field-label">Profile</div> + <div className="nrf-select"> + <span>{profile}</span> + <ChevronDown /> + </div> + </div> + + {/* Agent */} + <div className="nrf-field"> + <div className="nrf-field-label">Agent Installations</div> + <div className="nrf-agent-row"> + <span className="nrf-agent-chip"> + <span className="nrf-agent-name">{agentName}</span> + <StatusDot status="done" size="sm" /> + </span> + <div className="nrf-select nrf-select--flex"> + <span>{agentInstallation}</span> + <ChevronDown /> + </div> + </div> + </div> + + {/* Scout concurrency */} + <div className="nrf-field"> + <div className="nrf-field-label">Scout Concurrency</div> + <div className="nrf-concurrency-row"> + <input + className="nrf-concurrency-input" + type="number" + min={1} + max={32} + value={scoutConcurrency} + onChange={e => onScoutConcurrencyChange(parseInt(e.target.value, 10) || 1)} + /> + <span className="nrf-concurrency-hint">max parallel scout agents</span> + </div> + </div> + </div> + </div> + + {/* Submit */} + <Button variant="primary" onClick={onSubmit}>Start Run</Button> + </div> + ) +} + +export default NewRunForm diff --git a/frontend/src/components/organisms/ScoutBar.css b/frontend/src/components/organisms/ScoutBar.css new file mode 100644 index 0000000..5570e14 --- /dev/null +++ b/frontend/src/components/organisms/ScoutBar.css @@ -0,0 +1,76 @@ +.sb { + background: var(--color-navy); + padding: var(--padding-scout-bar); + flex-shrink: 0; +} + +/* ---- Summary line ---- */ +.sb-summary { + display: flex; + justify-content: space-between; + align-items: center; + margin-bottom: 10px; +} + +.sb-summary-left { + display: flex; + align-items: center; + gap: 8px; +} + +.sb-label { + font-size: var(--type-label); + font-weight: 500; + color: var(--text-on-dark-muted); + text-transform: uppercase; + letter-spacing: 1px; +} + +.sb-counts { + display: flex; + gap: var(--gap-scout-summary); + font-family: var(--font-mono); + font-size: 12px; +} + +.sb-count-group { + display: flex; + align-items: baseline; + gap: 4px; +} + +.sb-count-num { + color: var(--text-on-dark-scouts-muted); + font-weight: 500; +} + +/* Non-zero counts use their status color */ +.sb-count--running { color: var(--status-running); } +.sb-count--queued { color: var(--status-queued); } +.sb-count--done { color: var(--status-done); } +.sb-count--failed { color: var(--status-failed); } + +.sb-count-word { + color: var(--text-on-dark-scouts-muted); +} + +/* ---- Table card ---- */ +.sb-table { + background: var(--bg-card-warm); + border-radius: var(--radius-lg); + overflow: hidden; +} + +.sb-table-header { + display: grid; + grid-template-columns: 20px minmax(0, 1.5fr) 60px 60px 70px minmax(0, 1fr); + align-items: center; + padding: 6px 14px; + border-bottom: 0.5px solid var(--border-divider); + font-family: var(--font-mono); + font-size: var(--type-badge); + color: var(--text-muted); + text-transform: uppercase; + letter-spacing: 0.5px; + font-weight: 500; +} diff --git a/frontend/src/components/organisms/ScoutBar.tsx b/frontend/src/components/organisms/ScoutBar.tsx new file mode 100644 index 0000000..a750d23 --- /dev/null +++ b/frontend/src/components/organisms/ScoutBar.tsx @@ -0,0 +1,75 @@ +/** + * ScoutBar — navy-framed bottom panel showing running subagents. + * + * Contains a summary line (dot + label + counts) and a white table + * card with column headers and ScoutRow molecules. Returns null + * when there are no scouts to display. + * + * Used in: workspace layout, below the content+sidebar grid. + */ + +import { StatusDot } from '../atoms/StatusDot' +import { ScoutRow } from '../molecules/ScoutRow' +import './ScoutBar.css' + +interface ScoutEntry { + name: string + model: string + status: 'running' | 'done' | 'queued' | 'failed' + tools: number + elapsed: string + currentStep: string +} + +interface ScoutBarProps { + scouts: ScoutEntry[] +} + +type StatusKey = 'running' | 'queued' | 'done' | 'failed' +const STATUS_ORDER: StatusKey[] = ['running', 'queued', 'done', 'failed'] + +export function ScoutBar({ scouts }: ScoutBarProps) { + if (scouts.length === 0) return null + + const counts: Record<StatusKey, number> = { running: 0, queued: 0, done: 0, failed: 0 } + for (const s of scouts) counts[s.status]++ + + return ( + <div className="sb"> + {/* Summary line */} + <div className="sb-summary"> + <div className="sb-summary-left"> + <StatusDot status="running" /> + <span className="sb-label">Scouts</span> + </div> + <div className="sb-counts"> + {STATUS_ORDER.map(key => ( + <span key={key} className="sb-count-group"> + <span className={`sb-count-num${counts[key] > 0 ? ` sb-count--${key}` : ''}`}> + {counts[key]} + </span> + <span className="sb-count-word">{key}</span> + </span> + ))} + </div> + </div> + + {/* Table card */} + <div className="sb-table"> + <div className="sb-table-header"> + <span /> + <span>name</span> + <span>model</span> + <span>tools</span> + <span>elapsed</span> + <span>status</span> + </div> + {scouts.map((s, i) => ( + <ScoutRow key={i} {...s} /> + ))} + </div> + </div> + ) +} + +export default ScoutBar From a2ec3975b5d1de115fc86bb0a4f89b2d769f8cf2 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 15:25:11 +0700 Subject: [PATCH 338/412] feat: add remaining content stream molecules --- .../components/molecules/CheckboxOption.css | 46 ++++++++++++++ .../components/molecules/CheckboxOption.tsx | 63 +++++++++++++++++++ .../components/molecules/CompletionBanner.css | 17 +++++ .../components/molecules/CompletionBanner.tsx | 23 +++++++ .../components/molecules/PhaseBoundary.css | 21 +++++++ .../components/molecules/PhaseBoundary.tsx | 22 +++++++ .../src/components/molecules/SteeringBar.css | 40 ++++++++++++ .../src/components/molecules/SteeringBar.tsx | 36 +++++++++++ .../src/components/molecules/StepHeader.css | 19 ++++++ .../src/components/molecules/StepHeader.tsx | 30 +++++++++ .../src/components/molecules/UserBubble.css | 16 +++++ .../src/components/molecules/UserBubble.tsx | 23 +++++++ 12 files changed, 356 insertions(+) create mode 100644 frontend/src/components/molecules/CheckboxOption.css create mode 100644 frontend/src/components/molecules/CheckboxOption.tsx create mode 100644 frontend/src/components/molecules/CompletionBanner.css create mode 100644 frontend/src/components/molecules/CompletionBanner.tsx create mode 100644 frontend/src/components/molecules/PhaseBoundary.css create mode 100644 frontend/src/components/molecules/PhaseBoundary.tsx create mode 100644 frontend/src/components/molecules/SteeringBar.css create mode 100644 frontend/src/components/molecules/SteeringBar.tsx create mode 100644 frontend/src/components/molecules/StepHeader.css create mode 100644 frontend/src/components/molecules/StepHeader.tsx create mode 100644 frontend/src/components/molecules/UserBubble.css create mode 100644 frontend/src/components/molecules/UserBubble.tsx diff --git a/frontend/src/components/molecules/CheckboxOption.css b/frontend/src/components/molecules/CheckboxOption.css new file mode 100644 index 0000000..51ba4fa --- /dev/null +++ b/frontend/src/components/molecules/CheckboxOption.css @@ -0,0 +1,46 @@ +.co { + display: flex; + align-items: flex-start; + gap: 12px; + padding: var(--padding-radio); + border-radius: var(--radius-lg); + border: 1.5px solid var(--border-radio); + cursor: pointer; + transition: border-color var(--duration-fast), background var(--duration-fast); +} + +.co--selected { + border-color: var(--color-orange); + background: var(--bg-selected); +} + +.co-box { + width: 18px; + height: 18px; + border-radius: var(--radius-sm); + border: 2px solid var(--border-input); + flex-shrink: 0; + margin-top: 2px; + display: flex; + align-items: center; + justify-content: center; + transition: border-color var(--duration-fast), background var(--duration-fast); +} + +.co--selected .co-box { + border-color: var(--color-orange); + background: var(--color-orange); +} + +.co-content { flex: 1; min-width: 0; } +.co-label-row { display: flex; align-items: flex-start; gap: 8px; } +.co-label { font-size: var(--type-body); color: var(--text-primary); line-height: 1.5; flex: 1; } +.co--custom .co-label { font-style: italic; color: var(--text-muted); } + +.co-custom-input { + display: block; width: 100%; padding: 8px 0; margin-top: 8px; + background: transparent; border: none; border-bottom: 1px solid var(--border-card); + font-family: var(--font-body); font-size: var(--type-body); color: var(--text-primary); outline: none; +} +.co-custom-input::placeholder { color: var(--text-placeholder); } +.co-custom-input:focus { border-bottom-color: var(--border-input); } diff --git a/frontend/src/components/molecules/CheckboxOption.tsx b/frontend/src/components/molecules/CheckboxOption.tsx new file mode 100644 index 0000000..43352dd --- /dev/null +++ b/frontend/src/components/molecules/CheckboxOption.tsx @@ -0,0 +1,63 @@ +/** + * CheckboxOption — a multi-select option card for elicitation questions. + * Square checkbox instead of RadioOption's circle. + * Used in: elicitation decision panels (multi-select mode). + */ +import { useEffect, useRef } from 'react' +import { Badge } from '../atoms/Badge' +import './CheckboxOption.css' + +interface CheckboxOptionProps { + label: string + selected?: boolean + recommended?: boolean + isCustom?: boolean + customText?: string + onCustomTextChange?: (text: string) => void + onClick?: () => void +} + +const CheckSvg = () => ( + <svg width="12" height="12" viewBox="0 0 24 24" fill="none" aria-hidden="true"> + <path d="M20 6L9 17l-5-5" stroke="white" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" /> + </svg> +) + +export function CheckboxOption({ label, selected, recommended, isCustom, customText, onCustomTextChange, onClick }: CheckboxOptionProps) { + const inputRef = useRef<HTMLInputElement>(null) + useEffect(() => { + if (isCustom && selected) inputRef.current?.focus() + }, [isCustom, selected]) + + return ( + <div + className={`co${selected ? ' co--selected' : ''}${isCustom ? ' co--custom' : ''}`} + onClick={onClick} + role="checkbox" + aria-checked={selected} + > + <span className="co-box"> + {selected && <CheckSvg />} + </span> + <span className="co-content"> + <span className="co-label-row"> + <span className="co-label">{label}</span> + {recommended && <Badge variant="success">recommended</Badge>} + </span> + {isCustom && selected && ( + <input + ref={inputRef} + className="co-custom-input" + type="text" + placeholder="Type your response..." + value={customText ?? ''} + onChange={e => onCustomTextChange?.(e.target.value)} + onClick={e => e.stopPropagation()} + /> + )} + </span> + </div> + ) +} + +export default CheckboxOption diff --git a/frontend/src/components/molecules/CompletionBanner.css b/frontend/src/components/molecules/CompletionBanner.css new file mode 100644 index 0000000..f3193b8 --- /dev/null +++ b/frontend/src/components/molecules/CompletionBanner.css @@ -0,0 +1,17 @@ +.cb { + border-radius: var(--radius-xl); + padding: 14px; + text-align: center; + font-size: var(--type-body); +} + +.cb--success { + background: var(--bg-completion); + color: var(--text-completion); +} + +.cb--error { + background: var(--bg-base); + color: var(--status-failed); + border: 1px solid var(--status-failed); +} diff --git a/frontend/src/components/molecules/CompletionBanner.tsx b/frontend/src/components/molecules/CompletionBanner.tsx new file mode 100644 index 0000000..6ea362f --- /dev/null +++ b/frontend/src/components/molecules/CompletionBanner.tsx @@ -0,0 +1,23 @@ +/** + * CompletionBanner — phase completion message. + * + * Teal-green banner for successful completion, red-bordered for errors. + * + * Used in: completion view, at the top of the content stream. + */ + +import type { ReactNode } from 'react' +import './CompletionBanner.css' + +interface CompletionBannerProps { + children: ReactNode + variant?: 'success' | 'error' +} + +export function CompletionBanner({ children, variant = 'success' }: CompletionBannerProps) { + return ( + <div className={`cb cb--${variant}`}>{children}</div> + ) +} + +export default CompletionBanner diff --git a/frontend/src/components/molecules/PhaseBoundary.css b/frontend/src/components/molecules/PhaseBoundary.css new file mode 100644 index 0000000..fd55371 --- /dev/null +++ b/frontend/src/components/molecules/PhaseBoundary.css @@ -0,0 +1,21 @@ +.pb { + display: flex; + align-items: center; + gap: 12px; + padding: 20px 0; +} + +.pb-line { + flex: 1; + height: 1px; + background: var(--border-divider); +} + +.pb-label { + font-size: var(--type-label); + color: var(--text-muted); + text-transform: uppercase; + letter-spacing: 1px; + font-weight: 500; + white-space: nowrap; +} diff --git a/frontend/src/components/molecules/PhaseBoundary.tsx b/frontend/src/components/molecules/PhaseBoundary.tsx new file mode 100644 index 0000000..dd532f5 --- /dev/null +++ b/frontend/src/components/molecules/PhaseBoundary.tsx @@ -0,0 +1,22 @@ +/** + * PhaseBoundary — visual separator between workflow phases. + * A centered label between two horizontal lines. + * Used in: content stream, for phase_boundary events. + */ +import './PhaseBoundary.css' + +interface PhaseBoundaryProps { + label: string +} + +export function PhaseBoundary({ label }: PhaseBoundaryProps) { + return ( + <div className="pb"> + <span className="pb-line" /> + <span className="pb-label">{label}</span> + <span className="pb-line" /> + </div> + ) +} + +export default PhaseBoundary diff --git a/frontend/src/components/molecules/SteeringBar.css b/frontend/src/components/molecules/SteeringBar.css new file mode 100644 index 0000000..68779fd --- /dev/null +++ b/frontend/src/components/molecules/SteeringBar.css @@ -0,0 +1,40 @@ +.stb { + background: var(--bg-selected); + border-left: 3px solid var(--color-orange); + border-radius: 0 var(--radius-md) var(--radius-md) 0; + margin: 8px 0; + overflow: hidden; +} + +.stb-header { + display: flex; + align-items: center; + gap: 8px; + padding: 8px 16px; + font-family: var(--font-mono); + font-size: var(--type-label); + color: var(--color-orange); +} + +.stb-messages { + padding: 0 16px 8px; + display: flex; + flex-direction: column; + gap: 8px; +} + +.stb-msg { + display: flex; + align-items: baseline; + gap: 8px; + color: var(--text-body); + font-size: var(--type-breadcrumb); + line-height: 1.4; +} + +.stb-badge { + font-family: var(--font-mono); + font-size: var(--type-label); + color: var(--text-muted); + flex-shrink: 0; +} diff --git a/frontend/src/components/molecules/SteeringBar.tsx b/frontend/src/components/molecules/SteeringBar.tsx new file mode 100644 index 0000000..0f590d9 --- /dev/null +++ b/frontend/src/components/molecules/SteeringBar.tsx @@ -0,0 +1,36 @@ +/** + * SteeringBar — queued steering messages from the user. + * + * Shows an orange-accented bar with "steering" label and a list of + * queued messages, each with a "queued" badge. Returns null when + * there are no messages. + * + * Used in: content stream, above the FeedbackInput. + */ + +import { Md } from '../Md' +import './SteeringBar.css' + +interface SteeringBarProps { + messages: string[] +} + +export function SteeringBar({ messages }: SteeringBarProps) { + if (messages.length === 0) return null + + return ( + <div className="stb"> + <div className="stb-header">steering</div> + <div className="stb-messages"> + {messages.map((m, i) => ( + <div key={i} className="stb-msg"> + <span className="stb-badge">queued</span> + <Md>{m}</Md> + </div> + ))} + </div> + </div> + ) +} + +export default SteeringBar diff --git a/frontend/src/components/molecules/StepHeader.css b/frontend/src/components/molecules/StepHeader.css new file mode 100644 index 0000000..313c1ae --- /dev/null +++ b/frontend/src/components/molecules/StepHeader.css @@ -0,0 +1,19 @@ +.sh { + display: flex; + align-items: center; + gap: 10px; +} + +.sh-label { + font-size: var(--type-step-indicator); + font-weight: 500; +} + +.sh-label--active { color: var(--color-orange); } +.sh-label--complete { color: var(--color-teal); } + +.sh-name { + font-size: var(--type-step-header); + font-weight: 500; + color: var(--text-primary); +} diff --git a/frontend/src/components/molecules/StepHeader.tsx b/frontend/src/components/molecules/StepHeader.tsx new file mode 100644 index 0000000..2deec56 --- /dev/null +++ b/frontend/src/components/molecules/StepHeader.tsx @@ -0,0 +1,30 @@ +/** + * StepHeader — step indicator at the top of each step's content stream. + * + * Shows "step N/M" in the accent color followed by the step name. + * Active steps use orange, completed steps use teal. + * + * Used in: content stream, for step entry events. + */ + +import './StepHeader.css' + +interface StepHeaderProps { + stepNumber: number + totalSteps: number + stepName: string + status?: 'active' | 'complete' +} + +export function StepHeader({ stepNumber, totalSteps, stepName, status = 'active' }: StepHeaderProps) { + const label = totalSteps > 0 ? `step ${stepNumber}/${totalSteps}` : stepName + + return ( + <div className="sh"> + <span className={`sh-label sh-label--${status}`}>{label}</span> + {stepNumber > 0 && stepName && <span className="sh-name">{stepName}</span>} + </div> + ) +} + +export default StepHeader diff --git a/frontend/src/components/molecules/UserBubble.css b/frontend/src/components/molecules/UserBubble.css new file mode 100644 index 0000000..109ea36 --- /dev/null +++ b/frontend/src/components/molecules/UserBubble.css @@ -0,0 +1,16 @@ +.ub { + background: var(--bg-card); + border-radius: var(--radius-xl); + padding: var(--padding-card); + border: 0.5px solid var(--border-card); + border-left: 3px solid var(--text-muted); + font-size: var(--type-prose); + color: var(--text-primary); + line-height: 1.7; +} + +.ub-time { + font-size: var(--type-timestamp); + color: var(--text-muted); + margin-top: 4px; +} diff --git a/frontend/src/components/molecules/UserBubble.tsx b/frontend/src/components/molecules/UserBubble.tsx new file mode 100644 index 0000000..7716541 --- /dev/null +++ b/frontend/src/components/molecules/UserBubble.tsx @@ -0,0 +1,23 @@ +/** + * UserBubble — the user's own messages in the content stream. + * Gray left border distinguishes user messages from agent prose (orange). + * Used in: content stream, for user_message events. + */ +import type { ReactNode } from 'react' +import './UserBubble.css' + +interface UserBubbleProps { + children: ReactNode + timestamp?: string +} + +export function UserBubble({ children, timestamp }: UserBubbleProps) { + return ( + <div className="ub"> + <div className="ub-content">{children}</div> + {timestamp && <div className="ub-time">{timestamp}</div>} + </div> + ) +} + +export default UserBubble From e0438cb90562e8a8e5ee7930ea70c182cf22417a Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 15:25:40 +0700 Subject: [PATCH 339/412] feat: extend ElicitationPanel and NewRunForm to replace legacy components --- .../components/organisms/ElicitationPanel.css | 46 ++++ .../components/organisms/ElicitationPanel.tsx | 141 ++++++++---- .../src/components/organisms/NewRunForm.css | 74 ++++++- .../src/components/organisms/NewRunForm.tsx | 203 +++++++++++------- 4 files changed, 347 insertions(+), 117 deletions(-) diff --git a/frontend/src/components/organisms/ElicitationPanel.css b/frontend/src/components/organisms/ElicitationPanel.css index 21bb1f7..9d373d6 100644 --- a/frontend/src/components/organisms/ElicitationPanel.css +++ b/frontend/src/components/organisms/ElicitationPanel.css @@ -90,3 +90,49 @@ gap: 12px; margin-top: 24px; } + +/* Full-width when no context panel */ +.ep-grid--full { + grid-template-columns: 1fr; +} + +/* Multi-select hint */ +.ep-multi-hint { + font-family: var(--font-mono); + font-size: var(--type-label); + color: var(--color-orange); + margin-bottom: 8px; +} + +/* Free-text textarea */ +.ep-free-text { + display: block; + width: 100%; + min-height: 100px; + padding: 12px 14px; + background: var(--bg-base); + border: 1.5px solid var(--border-input); + border-radius: var(--radius-lg); + font-family: var(--font-body); + font-size: var(--type-body); + color: var(--text-primary); + line-height: 1.5; + resize: vertical; + outline: none; + box-sizing: border-box; +} + +.ep-free-text:focus { + border-color: var(--color-orange); +} + +.ep-free-text::placeholder { + color: var(--text-placeholder); +} + +/* Error message */ +.ep-error { + font-size: var(--type-breadcrumb); + color: var(--status-failed); + margin-top: 12px; +} diff --git a/frontend/src/components/organisms/ElicitationPanel.tsx b/frontend/src/components/organisms/ElicitationPanel.tsx index ed27a24..2712504 100644 --- a/frontend/src/components/organisms/ElicitationPanel.tsx +++ b/frontend/src/components/organisms/ElicitationPanel.tsx @@ -1,16 +1,15 @@ /** - * ElicitationPanel — two-panel context/decision layout for the Deepen step. - * - * Presents gathered context alongside a question with selectable options. - * Fully controlled — parent manages selection state and actions. - * - * Used in: elicitation interactions during the Deepen intake step. + * ElicitationPanel — two-panel context/decision layout. + * Supports single-select (radio), multi-select (checkbox), and free-text modes. + * Supports multi-question pagination with Previous/Next. + * Used in: elicitation interactions during workflow. */ import type { ReactNode } from 'react' import { SectionLabel } from '../atoms/SectionLabel' import { Button } from '../atoms/Button' import { RadioOption } from '../molecules/RadioOption' +import { CheckboxOption } from '../molecules/CheckboxOption' import './ElicitationPanel.css' interface OptionEntry { @@ -20,63 +19,131 @@ interface OptionEntry { } interface ElicitationPanelProps { - context: ReactNode + context?: ReactNode question: string options: OptionEntry[] - selectedIndex: number | null + // Single-select mode (default) + mode?: 'single-select' | 'multi-select' | 'free-text' + selectedIndex?: number | null + onSelect?: (index: number) => void + // Multi-select mode + selectedIndices?: number[] + onToggle?: (index: number) => void + // Free-text mode + freeText?: string + onFreeTextChange?: (text: string) => void + // Custom "other" text (shared across modes) customText?: string - onSelect: (index: number) => void onCustomTextChange?: (text: string) => void + // Pagination + questionNumber?: number + totalQuestions?: number + onPrevious?: () => void + showPrevious?: boolean + // Actions onSubmit: () => void onUseDefaults: () => void - questionNumber?: string + // Error + error?: string | null } export function ElicitationPanel({ context, question, options, + mode = 'single-select', selectedIndex, - customText, onSelect, + selectedIndices, + onToggle, + freeText, + onFreeTextChange, + customText, onCustomTextChange, + questionNumber, + totalQuestions, + onPrevious, + showPrevious, onSubmit, onUseDefaults, - questionNumber, + error, }: ElicitationPanelProps) { + const isLastQuestion = !totalQuestions || !questionNumber || questionNumber >= totalQuestions + const submitLabel = isLastQuestion ? 'Submit' : 'Next' + + const renderOptions = () => { + if (mode === 'free-text') { + return ( + <textarea + className="ep-free-text" + rows={4} + placeholder="Type your answer..." + value={freeText ?? ''} + onChange={e => onFreeTextChange?.(e.target.value)} + /> + ) + } + if (mode === 'multi-select') { + return ( + <div className="ep-options"> + {options.map((opt, i) => ( + <CheckboxOption + key={i} + label={opt.label} + selected={selectedIndices?.includes(i)} + recommended={opt.recommended} + isCustom={opt.isCustom} + customText={opt.isCustom ? customText : undefined} + onCustomTextChange={opt.isCustom ? onCustomTextChange : undefined} + onClick={() => onToggle?.(i)} + /> + ))} + </div> + ) + } + // single-select (default) + return ( + <div className="ep-options"> + {options.map((opt, i) => ( + <RadioOption + key={i} + label={opt.label} + selected={selectedIndex === i} + recommended={opt.recommended} + isCustom={opt.isCustom} + customText={opt.isCustom ? customText : undefined} + onCustomTextChange={opt.isCustom ? onCustomTextChange : undefined} + onClick={() => onSelect?.(i)} + /> + ))} + </div> + ) + } + return ( <div className="ep"> - {questionNumber && ( - <div className="ep-counter">{questionNumber}</div> + {totalQuestions && totalQuestions > 1 && questionNumber && ( + <div className="ep-counter">{questionNumber} / {totalQuestions}</div> )} - <div className="ep-grid"> - {/* Context panel */} - <div className="ep-panel ep-panel--context"> - <SectionLabel color="teal">Context</SectionLabel> - <div className="ep-panel-body">{context}</div> - </div> - - {/* Decision panel */} + <div className={context ? 'ep-grid' : 'ep-grid ep-grid--full'}> + {context && ( + <div className="ep-panel ep-panel--context"> + <SectionLabel color="teal">Context</SectionLabel> + <div className="ep-panel-body">{context}</div> + </div> + )} <div className="ep-panel ep-panel--decision"> <SectionLabel color="orange">Decision</SectionLabel> <div className="ep-question">{question}</div> - <div className="ep-options"> - {options.map((opt, i) => ( - <RadioOption - key={i} - label={opt.label} - selected={selectedIndex === i} - recommended={opt.recommended} - isCustom={opt.isCustom} - customText={opt.isCustom ? customText : undefined} - onCustomTextChange={opt.isCustom ? onCustomTextChange : undefined} - onClick={() => onSelect(i)} - /> - ))} - </div> + {mode === 'multi-select' && ( + <div className="ep-multi-hint">Select all that apply</div> + )} + {renderOptions()} + {error && <div className="ep-error">{error}</div>} <div className="ep-actions"> + {showPrevious && <Button variant="secondary" onClick={onPrevious}>Previous</Button>} <Button variant="secondary" onClick={onUseDefaults}>Use Defaults</Button> - <Button variant="primary" onClick={onSubmit}>Next</Button> + <Button variant="primary" onClick={onSubmit}>{submitLabel}</Button> </div> </div> </div> diff --git a/frontend/src/components/organisms/NewRunForm.css b/frontend/src/components/organisms/NewRunForm.css index 9016a69..f06e302 100644 --- a/frontend/src/components/organisms/NewRunForm.css +++ b/frontend/src/components/organisms/NewRunForm.css @@ -7,6 +7,11 @@ gap: var(--gap-form-sections); } +/* Button should not stretch to full width in a flex column */ +.nrf > .atom-btn { + align-self: flex-start; +} + /* ---- Header ---- */ .nrf-header { display: flex; @@ -173,6 +178,13 @@ } /* Agent row */ +.nrf-agent-rows { + display: flex; + flex-direction: column; + gap: 10px; + margin-top: 6px; +} + .nrf-agent-row { display: flex; align-items: center; @@ -183,18 +195,17 @@ display: flex; align-items: center; gap: 6px; - padding: 8px 12px; - background: var(--bg-base); - border: 1.5px solid var(--border-input); - border-radius: var(--radius-lg); + padding: 6px 12px; + background: var(--bg-thinking); /* lavender — agents are "thinking entities" */ + border-radius: var(--radius-md); flex-shrink: 0; } .nrf-agent-name { font-family: var(--font-mono); - font-size: var(--type-body); + font-size: 13px; font-weight: 500; - color: var(--text-primary); + color: var(--text-thinking); /* dark purple — ties to thinking/agent palette */ } /* Scout concurrency */ @@ -226,3 +237,54 @@ font-size: 13px; color: var(--text-muted); } + +/* ---- Real select dropdown (replaces static display div) ---- */ +.nrf-real-select { + display: block; + width: 100%; + padding: 10px 14px; + background: var(--bg-base); + border: 1.5px solid var(--border-input); + border-radius: var(--radius-lg); + font-family: var(--font-mono); + font-size: var(--type-body); + color: var(--text-primary); + outline: none; + cursor: pointer; + -webkit-appearance: none; + appearance: none; + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8'%3E%3Cpath d='M1 1l5 5 5-5' stroke='%239a8e7e' stroke-width='1.5' fill='none'/%3E%3C/svg%3E"); + background-repeat: no-repeat; + background-position: right 14px center; + padding-right: 36px; +} + +.nrf-real-select:focus { + border-color: var(--color-orange); +} + +.nrf-real-select--flex { + flex: 1; +} + +.nrf-real-select--sm { + font-size: 13px; +} + +.nrf-real-select option { + background: var(--bg-surface); + color: var(--text-body); +} + +/* ---- Error message ---- */ +.nrf-error { + font-size: var(--type-breadcrumb); + color: var(--status-failed); +} + +/* ---- Missing agent warning ---- */ +.nrf-missing { + font-family: var(--font-mono); + font-size: var(--type-label); + color: var(--status-failed); +} diff --git a/frontend/src/components/organisms/NewRunForm.tsx b/frontend/src/components/organisms/NewRunForm.tsx index 285aca3..df8f487 100644 --- a/frontend/src/components/organisms/NewRunForm.tsx +++ b/frontend/src/components/organisms/NewRunForm.tsx @@ -1,62 +1,111 @@ /** * NewRunForm — standalone form page for starting a new koan run. - * - * Centered column of form sections: workflow selection, description - * textarea, configuration (profile, agent, concurrency), and a - * submit button. No sidebar, no scout bar. - * + * Reads profiles and installations from the store, manages form state + * internally, and calls the API to start a run. * Used in: landing page when no run is active. */ +import { useState, useEffect, useMemo } from 'react' +import { useStore } from '../../store/index' +import * as api from '../../api/client' import { SectionLabel } from '../atoms/SectionLabel' import { Button } from '../atoms/Button' import { Badge } from '../atoms/Badge' import { StatusDot } from '../atoms/StatusDot' import './NewRunForm.css' -interface NewRunFormProps { - projectPath: string - description: string - onDescriptionChange: (text: string) => void - workflow: 'plan' | 'milestones' - onWorkflowChange: (workflow: 'plan' | 'milestones') => void - profile: string - agentName: string - agentInstallation: string - scoutConcurrency: number - onScoutConcurrencyChange: (n: number) => void - onSubmit: () => void -} +export function NewRunForm() { + const [task, setTask] = useState('') + const [profile, setProfile] = useState('') + const [scoutConcurrency, setScoutConcurrency] = useState(8) + const [loading, setLoading] = useState(false) + const [error, setError] = useState<string | null>(null) + const [selectedInstallations, setSelectedInstallations] = useState<Record<string, string>>({}) + const [workflow, setWorkflow] = useState<'plan' | 'milestones'>('plan') + const [projectDir, setProjectDir] = useState('') + + const profilesDict = useStore(s => s.settings.profiles) + const installationsDict = useStore(s => s.settings.installations) + const defaultProfile = useStore(s => s.settings.defaultProfile) + const defaultScoutConcurrency = useStore(s => s.settings.defaultScoutConcurrency) + + const profiles = useMemo(() => Object.values(profilesDict), [profilesDict]) + const installations = useMemo(() => Object.values(installationsDict), [installationsDict]) + const hasRunners = installations.some(i => i.available) + + useEffect(() => { + api.getInitialPrompt().then(data => { + if (data.prompt) setTask(data.prompt) + if (data.project_dir) setProjectDir(data.project_dir) + }) + }, []) + + useEffect(() => { + if (profiles.length > 0 && !profile) { + const def = profiles.find(p => p.name === defaultProfile) ?? profiles[0] + setProfile(def.name) + } + }, [profiles, profile, defaultProfile]) + + useEffect(() => { setScoutConcurrency(defaultScoutConcurrency) }, [defaultScoutConcurrency]) + + const preflight = useMemo(() => { + const sel = profiles.find(p => p.name === profile) + if (!sel) return null + const requiredTypes = new Set<string>() + for (const tierVal of Object.values(sel.tiers)) { + if (typeof tierVal === 'string') { + const inst = installationsDict[tierVal] + if (inst) requiredTypes.add(inst.runnerType) + else requiredTypes.add(tierVal) + } + } + const byType: Record<string, { alias: string; binary: string }[]> = {} + for (const rt of requiredTypes) { + byType[rt] = installations.filter(i => i.runnerType === rt && i.available).map(i => ({ alias: i.alias, binary: i.binary })) + } + return { types: [...requiredTypes].sort(), byType } + }, [profile, profiles, installations, installationsDict]) + + useEffect(() => { + if (!preflight) { setSelectedInstallations({}); return } + const sel: Record<string, string> = {} + for (const rt of preflight.types) { + const insts = preflight.byType[rt] || [] + const def = insts.find(i => i.alias === `${rt}-default`) ?? insts[0] + if (def) sel[rt] = def.alias + } + setSelectedInstallations(sel) + }, [preflight]) + + const installationsReady = preflight ? preflight.types.every(rt => selectedInstallations[rt]) : false + + const handleStart = async () => { + const trimmed = task.trim() + if (!trimmed) { setError('Please enter a task description'); return } + if (!profile) { setError('Please select a profile'); return } + if (!installationsReady) { setError('Please select an installation for each required runner type'); return } + setError(null); setLoading(true) + try { + const result = await api.startRun(trimmed, profile, scoutConcurrency, selectedInstallations, workflow) + if (!result.ok) setError(result.message ?? 'Failed to start run') + } catch { setError('Network error') } + finally { setLoading(false) } + } -const ChevronDown = () => ( - <svg width="12" height="8" viewBox="0 0 12 8" fill="none" aria-hidden="true"> - <path d="M1 1l5 5 5-5" stroke="var(--text-muted)" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /> - </svg> -) - -export function NewRunForm({ - projectPath, description, onDescriptionChange, - workflow, onWorkflowChange, - profile, agentName, agentInstallation, - scoutConcurrency, onScoutConcurrencyChange, - onSubmit, -}: NewRunFormProps) { return ( <div className="nrf"> - {/* Title + project */} <div className="nrf-header"> <h1 className="nrf-title">New Run</h1> - <div className="nrf-project">{projectPath}</div> + <div className="nrf-project">{projectDir || '—'}</div> </div> {/* Workflow */} <div className="nrf-card"> <SectionLabel>Workflow</SectionLabel> <div className="nrf-wf-grid"> - <button - className={`nrf-wf-option${workflow === 'plan' ? ' nrf-wf-option--selected' : ''}`} - onClick={() => onWorkflowChange('plan')} - > + <button className={`nrf-wf-option${workflow === 'plan' ? ' nrf-wf-option--selected' : ''}`} + onClick={() => setWorkflow('plan')}> <span className={`nrf-wf-radio${workflow === 'plan' ? ' nrf-wf-radio--selected' : ''}`}> {workflow === 'plan' && <span className="nrf-wf-radio-inner" />} </span> @@ -68,9 +117,7 @@ export function NewRunForm({ <button className="nrf-wf-option nrf-wf-option--disabled" disabled> <span className="nrf-wf-radio" /> <span className="nrf-wf-info"> - <span className="nrf-wf-name"> - Milestones <Badge variant="neutral">coming soon</Badge> - </span> + <span className="nrf-wf-name">Milestones <Badge variant="neutral">coming soon</Badge></span> <span className="nrf-wf-desc">Break work into milestones with phased delivery</span> </span> </button> @@ -81,62 +128,70 @@ export function NewRunForm({ <div className="nrf-card"> <SectionLabel>Description</SectionLabel> <div className="nrf-helper">What should this run accomplish?</div> - <textarea - className="nrf-textarea" - value={description} - onChange={e => onDescriptionChange(e.target.value)} - rows={4} - /> + <textarea className="nrf-textarea" value={task} onChange={e => setTask(e.target.value)} rows={4} + placeholder="Describe what you want to build..." /> </div> {/* Configuration */} <div className="nrf-card"> <SectionLabel>Configuration</SectionLabel> <div className="nrf-config-fields"> - {/* Profile */} <div className="nrf-field"> <div className="nrf-field-label">Profile</div> - <div className="nrf-select"> - <span>{profile}</span> - <ChevronDown /> - </div> + <select className="nrf-real-select" value={profile} onChange={e => setProfile(e.target.value)}> + {profiles.map(p => ( + <option key={p.name} value={p.name}>{p.name}{p.readOnly ? ' (built-in)' : ''}</option> + ))} + </select> </div> - {/* Agent */} - <div className="nrf-field"> - <div className="nrf-field-label">Agent Installations</div> - <div className="nrf-agent-row"> - <span className="nrf-agent-chip"> - <span className="nrf-agent-name">{agentName}</span> - <StatusDot status="done" size="sm" /> - </span> - <div className="nrf-select nrf-select--flex"> - <span>{agentInstallation}</span> - <ChevronDown /> + {preflight && preflight.types.length > 0 && ( + <div className="nrf-field"> + <div className="nrf-field-label">Agent Installations</div> + <div className="nrf-agent-rows"> + {preflight.types.map(rt => { + const insts = preflight.byType[rt] || [] + const selected = selectedInstallations[rt] || '' + return ( + <div key={rt} className="nrf-agent-row"> + <span className="nrf-agent-chip"> + <span className="nrf-agent-name">{rt}</span> + <StatusDot status={insts.length > 0 && selected ? 'done' : 'failed'} size="sm" /> + </span> + <select className="nrf-real-select nrf-real-select--flex nrf-real-select--sm" + value={selected} onChange={e => setSelectedInstallations(prev => ({ ...prev, [rt]: e.target.value }))}> + <option value="">-- select --</option> + {insts.map(inst => ( + <option key={inst.alias} value={inst.alias}>{inst.alias} ({inst.binary})</option> + ))} + </select> + {insts.length === 0 && <span className="nrf-missing">Not detected — configure in Settings</span>} + </div> + ) + })} </div> </div> - </div> + )} - {/* Scout concurrency */} <div className="nrf-field"> <div className="nrf-field-label">Scout Concurrency</div> <div className="nrf-concurrency-row"> - <input - className="nrf-concurrency-input" - type="number" - min={1} - max={32} - value={scoutConcurrency} - onChange={e => onScoutConcurrencyChange(parseInt(e.target.value, 10) || 1)} - /> + <input className="nrf-concurrency-input" type="number" min={1} max={32} + value={scoutConcurrency} onChange={e => setScoutConcurrency(parseInt(e.target.value, 10) || 8)} /> <span className="nrf-concurrency-hint">max parallel scout agents</span> </div> </div> </div> </div> - {/* Submit */} - <Button variant="primary" onClick={onSubmit}>Start Run</Button> + {error && <div className="nrf-error">{error}</div>} + + <Button variant="primary" onClick={handleStart} + disabled={!hasRunners || loading || !installationsReady}> + {loading ? 'Starting...' : 'Start Run'} + </Button> + + {!hasRunners && <div className="nrf-error">No available agent installations. Open Settings to add and configure one.</div>} </div> ) } From 646d8d343bb5811d5f6d29de4f33f973debafcac Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 15:26:11 +0700 Subject: [PATCH 340/412] refactor: extract normalizeOptions utility from AskWizard --- frontend/src/utils.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/frontend/src/utils.ts b/frontend/src/utils.ts index 5996983..1a15f9a 100644 --- a/frontend/src/utils.ts +++ b/frontend/src/utils.ts @@ -21,3 +21,17 @@ export function tierSummary(tiers: Record<string, string>): string { } return parts.slice(0, 3).join(' | ') || '--' } + +// Normalize raw question options from LLM output. Options may arrive as +// strings or dicts with varying key names. +export function normalizeOptions( + rawOpts: (string | Record<string, unknown>)[] | undefined, +): { value: string; label: string; recommended?: boolean }[] { + if (!rawOpts) return [] + return rawOpts.map(o => { + if (typeof o === 'string') return { value: o, label: o } + const label = String(o['label'] ?? o['text'] ?? o['value'] ?? o['option'] ?? '') + const value = String(o['value'] ?? o['label'] ?? o['text'] ?? label) + return { value, label, recommended: (o['recommended'] as boolean) ?? false } + }) +} From 0d46d530a6c980f4bc389d6eb1e54141250a779e Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 15:26:46 +0700 Subject: [PATCH 341/412] refactor: rewrite view layer with new organisms, delete legacy components --- frontend/src/App.tsx | 451 +++++++++++++++--- frontend/src/components/ActivityFeed.tsx | 244 ---------- frontend/src/components/AgentMonitor.tsx | 149 ------ frontend/src/components/ArtifactsSidebar.tsx | 127 ----- frontend/src/components/ChatInput.tsx | 69 --- frontend/src/components/Completion.tsx | 42 -- frontend/src/components/Header.tsx | 22 - frontend/src/components/LandingPage.tsx | 280 ----------- frontend/src/components/StatusSidebar.tsx | 107 ----- .../src/components/interactions/AskWizard.tsx | 288 ----------- frontend/src/main.tsx | 1 + frontend/src/styles/app-shell.css | 112 +++++ 12 files changed, 502 insertions(+), 1390 deletions(-) delete mode 100644 frontend/src/components/ActivityFeed.tsx delete mode 100644 frontend/src/components/AgentMonitor.tsx delete mode 100644 frontend/src/components/ArtifactsSidebar.tsx delete mode 100644 frontend/src/components/ChatInput.tsx delete mode 100644 frontend/src/components/Completion.tsx delete mode 100644 frontend/src/components/Header.tsx delete mode 100644 frontend/src/components/LandingPage.tsx delete mode 100644 frontend/src/components/StatusSidebar.tsx delete mode 100644 frontend/src/components/interactions/AskWizard.tsx create mode 100644 frontend/src/styles/app-shell.css diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index c25e2a8..c6d6ccf 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -1,107 +1,434 @@ -import { useEffect } from 'react' -import { useStore } from './store/index' +/* + * EVENT TYPE → MOLECULE MAPPING (final, no gaps) + * ───────────────────────────────────────────────── + * thinking → ThinkingBlock + Md + * text → ProseCard + Md + * tool_read/write/edit → ToolCallRow + * tool_bash/grep/ls → ToolCallRow + * tool_generic → ToolCallRow + * step → StepHeader + * debug_step_guidance → StepGuidancePill + Md + * user_message → UserBubble + Md + * phase_boundary → PhaseBoundary + * pendingThinking → ThinkingBlock (always expanded) + * pendingText → ProseCard + Md + streaming cursor + */ + +import { useEffect, useMemo, useRef, useState } from 'react' +import { useStore, ConversationEntry, AskQuestion } from './store/index' import { connectSSE } from './sse/connect' -import { Header } from './components/Header' -import { LandingPage } from './components/LandingPage' -import { StatusSidebar } from './components/StatusSidebar' -import { ActivityFeed } from './components/ActivityFeed' -import { AgentMonitor } from './components/AgentMonitor' -import { ArtifactsSidebar } from './components/ArtifactsSidebar' +import { useElapsed, formatElapsed } from './hooks/useElapsed' +import { useAutoScroll } from './hooks/useAutoScroll' +import { normalizeOptions } from './utils' +import * as api from './api/client' + +import { HeaderBar } from './components/organisms/HeaderBar' +import { ArtifactsSidebar as ArtifactsSidebarOrg } from './components/organisms/ArtifactsSidebar' +import { ScoutBar } from './components/organisms/ScoutBar' +import { ElicitationPanel } from './components/organisms/ElicitationPanel' +import { NewRunForm } from './components/organisms/NewRunForm' + +import { ThinkingBlock } from './components/molecules/ThinkingBlock' +import { ProseCard } from './components/molecules/ProseCard' +import { ToolCallRow } from './components/molecules/ToolCallRow' +import { StepGuidancePill } from './components/molecules/StepGuidancePill' +import { FeedbackInput } from './components/molecules/FeedbackInput' +import { UserBubble } from './components/molecules/UserBubble' +import { PhaseBoundary } from './components/molecules/PhaseBoundary' +import { StepHeader } from './components/molecules/StepHeader' +import { CompletionBanner } from './components/molecules/CompletionBanner' +import { SteeringBar } from './components/molecules/SteeringBar' + +import { Md } from './components/Md' import { Notification } from './components/Notification' import { SettingsOverlay } from './components/SettingsOverlay' -import { Completion } from './components/Completion' -import { AskWizard } from './components/interactions/AskWizard' -function InteractionView() { +// --------------------------------------------------------------------------- +// Header data +// --------------------------------------------------------------------------- + +function useHeaderData() { + const run = useStore(s => s.run) + const agents = useStore(s => s.run?.agents) + const primary = useMemo(() => agents ? Object.values(agents).find(a => a.isPrimary) : null, [agents]) + const lastStep = useMemo(() => { + if (!primary) return null + for (let i = primary.conversation.entries.length - 1; i >= 0; i--) { + const e = primary.conversation.entries[i] + if (e.type === 'step') return e + } + return null + }, [primary]) + const elapsed = useElapsed(primary?.startedAtMs ?? Date.now()) + return { + phase: run ? run.phase.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join(' ') : '', + step: lastStep?.stepName ?? primary?.stepName ?? '', + totalSteps: lastStep?.totalSteps ?? 0, + currentStep: lastStep?.step ?? 0, + orchestratorModel: primary?.model ?? undefined, + elapsed: primary ? elapsed : undefined, + } +} + +// --------------------------------------------------------------------------- +// Sidebar + scout bar wiring +// --------------------------------------------------------------------------- + +function ConnectedSidebar() { + const artifacts = useStore(s => s.run?.artifacts ?? {}) + const entries = useMemo(() => { + const now = Date.now() + const list = Object.values(artifacts).map(a => { + const mins = Math.floor((now - a.modifiedAt) / 60000) + return { + filename: a.path.split('/').pop() || a.path, + modifiedAgo: mins < 1 ? 'just now' : mins < 60 ? `modified ${mins}m ago` : `modified ${Math.floor(mins / 60)}h ago`, + variant: mins < 5 ? ('recent' as const) : ('stable' as const), + _ts: a.modifiedAt, + } + }) + list.sort((a, b) => b._ts - a._ts) + return list.map(({ filename, modifiedAgo, variant }) => ({ filename, modifiedAgo, variant })) + }, [artifacts]) + return <ArtifactsSidebarOrg artifacts={entries} /> +} + +function ConnectedScoutBar() { + const agents = useStore(s => s.run?.agents ?? {}) + const scouts = useMemo(() => { + const now = Date.now() + return Object.values(agents).filter(a => !a.isPrimary).map(a => ({ + name: a.label || a.role, + model: a.model ?? '--', + status: a.status, + tools: a.conversation.entries.filter(e => e.type.startsWith('tool_')).length, + elapsed: a.completedAtMs + ? formatElapsed(a.completedAtMs - (a.startedAtMs || 0)) + : formatElapsed(a.startedAtMs ? now - a.startedAtMs : 0), + currentStep: a.stepName || (a.step > 0 ? `step ${a.step}` : 'step 0'), + })) + }, [agents]) + return <ScoutBar scouts={scouts} /> +} + +// --------------------------------------------------------------------------- +// Content stream +// --------------------------------------------------------------------------- + +function renderEntry(entry: ConversationEntry, i: number) { + switch (entry.type) { + case 'thinking': + return <ThinkingBlock key={i}><Md>{entry.content}</Md></ThinkingBlock> + case 'text': + return <ProseCard key={i}><Md>{entry.text}</Md></ProseCard> + case 'tool_read': + return <ToolCallRow key={i} tool="read" command={entry.lines ? `${entry.file}:${entry.lines}` : entry.file} status={entry.inFlight ? 'running' : 'done'} /> + case 'tool_write': + return <ToolCallRow key={i} tool="write" command={entry.file} status={entry.inFlight ? 'running' : 'done'} /> + case 'tool_edit': + return <ToolCallRow key={i} tool="edit" command={entry.file} status={entry.inFlight ? 'running' : 'done'} /> + case 'tool_bash': + return <ToolCallRow key={i} tool="bash" command={entry.command} status={entry.inFlight ? 'running' : 'done'} /> + case 'tool_grep': + return <ToolCallRow key={i} tool="grep" command={entry.pattern} status={entry.inFlight ? 'running' : 'done'} /> + case 'tool_ls': + return <ToolCallRow key={i} tool="ls" command={entry.path} status={entry.inFlight ? 'running' : 'done'} /> + case 'tool_generic': + return <ToolCallRow key={i} tool={entry.toolName} command={entry.summary} status={entry.inFlight ? 'running' : 'done'} /> + case 'step': + return <StepHeader key={i} stepNumber={entry.step} totalSteps={entry.totalSteps ?? 0} stepName={entry.stepName} /> + case 'debug_step_guidance': + return <StepGuidancePill key={i} status="active" defaultExpanded={false}><Md>{entry.content}</Md></StepGuidancePill> + case 'user_message': { + const ts = new Date(entry.timestampMs).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) + return <UserBubble key={i} timestamp={ts}><Md>{entry.content}</Md></UserBubble> + } + case 'phase_boundary': + return <PhaseBoundary key={i} label={entry.message} /> + default: + return null + } +} + +function ConnectedSteeringBar() { + const steering = useStore(s => s.run?.steering ?? []) + return <SteeringBar messages={steering.map(m => m.content)} /> +} + +function ContentStream() { + const focusAgentId = useStore(s => s.run?.focus?.agentId) + const conversation = useStore(s => focusAgentId ? s.run?.agents?.[focusAgentId]?.conversation : undefined) + const run = useStore(s => s.run) const focus = useStore(s => s.run?.focus) - if (!focus) return null - if (focus.type === 'question') return <AskWizard /> - return null + const scrollRef = useRef<HTMLDivElement>(null) + useAutoScroll(scrollRef) + const hasEntries = !!(conversation?.entries?.length) + const isWaiting = !hasEntries && !conversation?.isThinking && !conversation?.pendingText + const hasInteraction = focus && focus.type !== 'conversation' + const showFeedback = run !== null && !hasInteraction + return ( + <div className="content-column" ref={scrollRef}> + <div className="content-stream"> + {isWaiting && ( + <div className="waiting-indicator"> + <span className="pulse-dot">●</span> + <span>Starting agent…</span> + </div> + )} + {conversation?.entries.map(renderEntry)} + {conversation?.isThinking && conversation.pendingThinking && ( + <ThinkingBlock defaultExpanded={true}><Md>{conversation.pendingThinking}</Md></ThinkingBlock> + )} + {conversation?.isThinking && !conversation.pendingThinking && ( + <div className="thinking-indicator"> + <span className="pulse-dot">●</span> + <span>Thinking…</span> + </div> + )} + {conversation?.pendingText && ( + <ProseCard><Md>{conversation.pendingText}</Md><span className="stream-cursor" /></ProseCard> + )} + {showFeedback && ( + <> + <ConnectedSteeringBar /> + <FeedbackInput onSend={msg => api.sendChatMessage(msg)} disabled={!!run?.completion} /> + </> + )} + </div> + </div> + ) } -function WorkspaceMain() { +// --------------------------------------------------------------------------- +// Elicitation view — fully replaces AskWizard +// --------------------------------------------------------------------------- + +function isFreeText(q: AskQuestion): boolean { + return q.free_text === true || !q.options || q.options.length === 0 +} + +function ElicitationView() { const focus = useStore(s => s.run?.focus) - const completion = useStore(s => s.run?.completion) + const [currentIdx, setCurrentIdx] = useState(0) + const [answers, setAnswers] = useState<Record<number, string | string[] | null>>({}) + const [otherTexts, setOtherTexts] = useState<Record<number, string>>({}) + const [submitError, setSubmitError] = useState<string | null>(null) - const hasInteraction = focus && focus.type !== 'conversation' + if (!focus || focus.type !== 'question') return null + const { questions, token } = focus + const total = questions.length + const q = questions[currentIdx] + const opts = normalizeOptions(q.options as (string | Record<string, unknown>)[]) + const freeText = isFreeText(q) + const multi = q.multi + + const optionEntries = [ + ...opts.map(o => ({ label: o.label, recommended: o.recommended })), + ...(!freeText ? [{ label: 'Other (type your own)', isCustom: true }] : []), + ] + + const answer = answers[currentIdx] ?? null + const selected = Array.isArray(answer) ? answer : answer ? [answer] : [] + + const selectedIndex = (!multi && !freeText) + ? (() => { + const idx = optionEntries.findIndex((_, i) => { + if (i < opts.length) return selected.includes(opts[i].value) + return selected.includes('__other__') + }) + return idx >= 0 ? idx : null + })() + : null + + const selectedIndices = multi + ? optionEntries.map((_, i) => { + const val = i < opts.length ? opts[i].value : '__other__' + return selected.includes(val) ? i : -1 + }).filter(i => i >= 0) + : [] + + const handleSelect = (idx: number) => { + const val = idx < opts.length ? opts[idx].value : '__other__' + setAnswers(prev => ({ ...prev, [currentIdx]: selected[0] === val ? null : val })) + } + + const handleToggle = (idx: number) => { + const val = idx < opts.length ? opts[idx].value : '__other__' + const newSel = selected.includes(val) ? selected.filter(v => v !== val) : [...selected, val] + setAnswers(prev => ({ ...prev, [currentIdx]: newSel })) + } + + const handleFreeTextChange = (text: string) => { + setAnswers(prev => ({ ...prev, [currentIdx]: text || null })) + } + + const handleCustomTextChange = (text: string) => { + setOtherTexts(prev => ({ ...prev, [currentIdx]: text })) + } + + const resolveAnswers = () => { + return questions.map((_, i) => { + const raw = answers[i] ?? null + const typed = otherTexts[i] || '' + if (raw === '__other__') return typed || null + if (Array.isArray(raw)) return raw.map(v => v === '__other__' ? typed : v) + return raw + }) + } + + const handleSubmit = async () => { + if (currentIdx < total - 1) { setCurrentIdx(i => i + 1); return } + const final = resolveAnswers() + const res = await api.submitAnswer(final, token) + if (!res.ok) setSubmitError(res.message ?? 'Failed to submit answers') + } + + const handleUseDefaults = async () => { + const defaults = questions.map(qq => { + if (isFreeText(qq)) return null + const rec = (qq.options ?? []).filter(o => o.recommended).map(o => o.value) + return qq.multi ? rec : (rec[0] ?? null) + }) + const res = await api.submitAnswer(defaults, token) + if (!res.ok) setSubmitError(res.message ?? 'Failed to submit defaults') + } + + const mode = freeText ? 'free-text' : multi ? 'multi-select' : 'single-select' + + return ( + <ElicitationPanel + context={q.context ? <Md>{q.context}</Md> : undefined} + question={q.question} + options={optionEntries} + mode={mode as 'single-select' | 'multi-select' | 'free-text'} + selectedIndex={selectedIndex} + onSelect={handleSelect} + selectedIndices={selectedIndices} + onToggle={handleToggle} + freeText={freeText ? (typeof answer === 'string' ? answer : '') : undefined} + onFreeTextChange={freeText ? handleFreeTextChange : undefined} + customText={otherTexts[currentIdx] ?? ''} + onCustomTextChange={handleCustomTextChange} + questionNumber={currentIdx + 1} + totalQuestions={total} + showPrevious={currentIdx > 0} + onPrevious={() => setCurrentIdx(i => i - 1)} + onSubmit={handleSubmit} + onUseDefaults={handleUseDefaults} + error={submitError} + /> + ) +} +// --------------------------------------------------------------------------- +// Completion +// --------------------------------------------------------------------------- + +function CompletionView() { + const completion = useStore(s => s.run?.completion) + const artifacts = useStore(s => s.run?.artifacts ?? {}) + if (!completion) return null return ( - <div className="workspace-main"> - {hasInteraction ? ( - <InteractionView /> - ) : completion ? ( - <Completion /> - ) : ( - <ActivityFeed /> - )} - <AgentMonitor /> + <div className="content-column"> + <div className="content-stream"> + {completion.success ? ( + <> + <CompletionBanner>{completion.summary || 'All phases completed successfully.'}</CompletionBanner> + {Object.keys(artifacts).length > 0 && ( + <ProseCard> + <p><strong>Artifacts produced:</strong></p> + <ul>{Object.keys(artifacts).map(p => <li key={p}><code>{p}</code></li>)}</ul> + </ProseCard> + )} + </> + ) : ( + <CompletionBanner variant="error">{completion.error || 'An error occurred.'}</CompletionBanner> + )} + </div> </div> ) } +// --------------------------------------------------------------------------- +// App +// --------------------------------------------------------------------------- + export default function App() { const run = useStore(s => s.run) + const connected = useStore(s => s.connected) const settingsOpen = useStore(s => s.settingsOpen) + const header = useHeaderData() useEffect(() => { let es: EventSource | null = null let retryDelay = 500 - function connect() { es = connectSSE(useStore) - // Override the onerror set inside connectSSE to schedule our retry. es.onerror = () => { useStore.getState().setConnected(false) es?.close() - // Exponential backoff capped at 5s. setTimeout(connect, retryDelay) retryDelay = Math.min(retryDelay * 2, 5000) } - // Reset backoff on successful connection. - es.onopen = () => { - retryDelay = 500 - } + es.onopen = () => { retryDelay = 500 } } - connect() + return () => { es?.close() } + }, []) - // Cleanup on unmount — prevents duplicate SSE connections in React StrictMode. - return () => { - es?.close() - } - }, []) // Empty dep array: connect once; reconnect is managed inside - - const connected = useStore(s => s.connected) + const openSettings = () => useStore.getState().setSettingsOpen(true) + const focus = run?.focus + const hasInteraction = focus && focus.type !== 'conversation' + const completion = run?.completion - // Show a minimal loading state until the first SSE snapshot arrives. - // This prevents a blank cornsilk void while the server is initializing. if (!connected) { return ( - <div className="app"> - <Header /> - <div className="loading-state"> - <span className="loading-label">connecting…</span> - </div> + <div className="app-root"> + <HeaderBar phase="" step="" totalSteps={0} currentStep={0} onSettingsClick={openSettings} /> + <div className="single-column"><div className="loading-center">connecting…</div></div> </div> ) } - return ( - <div className="app"> - <Header /> - - {!run ? ( - <LandingPage /> - ) : ( - <div className="workspace"> - <StatusSidebar /> - <WorkspaceMain /> - <ArtifactsSidebar /> + if (!run) { + return ( + <div className="app-root"> + <HeaderBar phase="" step="" totalSteps={0} currentStep={0} onSettingsClick={openSettings} /> + <div className="single-column"><NewRunForm /></div> + <Notification />{settingsOpen && <SettingsOverlay />} + </div> + ) + } + + if (hasInteraction) { + return ( + <div className="app-root"> + <HeaderBar {...header} onSettingsClick={openSettings} /> + <div className="workflow-grid"> + <div className="content-column"><ElicitationView /></div> + <ConnectedSidebar /> </div> - )} + <Notification />{settingsOpen && <SettingsOverlay />} + </div> + ) + } + + if (completion) { + return ( + <div className="app-root"> + <HeaderBar {...header} onSettingsClick={openSettings} /> + <div className="workflow-grid"><CompletionView /><ConnectedSidebar /></div> + <Notification />{settingsOpen && <SettingsOverlay />} + </div> + ) + } - <Notification /> - {settingsOpen && <SettingsOverlay />} + return ( + <div className="app-root"> + <HeaderBar {...header} onSettingsClick={openSettings} /> + <div className="workflow-grid"><ContentStream /><ConnectedSidebar /></div> + <ConnectedScoutBar /> + <Notification />{settingsOpen && <SettingsOverlay />} </div> ) } diff --git a/frontend/src/components/ActivityFeed.tsx b/frontend/src/components/ActivityFeed.tsx deleted file mode 100644 index a16c6f2..0000000 --- a/frontend/src/components/ActivityFeed.tsx +++ /dev/null @@ -1,244 +0,0 @@ -import { useRef, useState } from 'react' -import { useStore, ConversationEntry } from '../store/index' -import { useAutoScroll } from '../hooks/useAutoScroll' -import { Md } from './Md' -import { ChatInput } from './ChatInput' - -// -- Steering indicator -------------------------------------------------------- - -function SteeringIndicator() { - const steering = useStore(s => s.run?.steering ?? []) - if (steering.length === 0) return null - return ( - <div className="steering-indicator"> - <div className="steering-header">steering</div> - <div className="steering-messages"> - {steering.map((m, i) => ( - <div key={i} className="steering-message"> - <span className="steering-queued-badge">queued</span> - <Md>{m.content}</Md> - </div> - ))} - </div> - </div> - ) -} - -// -- Thinking ------------------------------------------------------------------ - -function ThinkingCard({ content }: { content: string }) { - const [expanded, setExpanded] = useState(false) - const isLong = content.length > 300 - - return ( - <div className="activity-card activity-card-thinking"> - <div className="activity-card-header"> - <span className="activity-card-tool">thinking</span> - </div> - {content && ( - <div className={`activity-card-body ${expanded ? 'expanded' : ''}`}> - <Md>{content}</Md> - </div> - )} - {isLong && !expanded && ( - <div className="activity-card-more" onClick={() => setExpanded(true)}> - show more - </div> - )} - </div> - ) -} - -// -- Step header --------------------------------------------------------------- - -function StepHeader({ step, stepName, totalSteps }: { - step: number; stepName: string; totalSteps: number | null -}) { - const label = step === 0 ? stepName : (totalSteps ? `step ${step}/${totalSteps}` : `step ${step}`) - return ( - <div className="step-header"> - <span className="step-header-label">{label}</span> - {step > 0 && stepName && <span className="step-header-name">{stepName}</span>} - </div> - ) -} - -// -- Text block ---------------------------------------------------------------- - -function TextBlock({ text }: { text: string }) { - return <div className="stream-output"><Md>{text}</Md></div> -} - -// -- Debug step guidance ------------------------------------------------------- - -function DebugGuidanceCard({ content }: { content: string }) { - const [expanded, setExpanded] = useState(false) - - return ( - <div className="activity-card activity-card-debug"> - <div className="activity-card-header" onClick={() => setExpanded(!expanded)} style={{ cursor: 'pointer' }}> - <span className="activity-card-tool">step guidance</span> - <span className="activity-card-toggle">{expanded ? '▾' : '▸'}</span> - </div> - {expanded && ( - <div className="activity-card-body expanded"> - <Md>{content}</Md> - </div> - )} - </div> - ) -} - -// -- User message bubble ------------------------------------------------------- - -function UserMessageBubble({ content, timestampMs }: { content: string; timestampMs: number }) { - const ts = new Date(timestampMs) - const timeStr = ts.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) - - return ( - <div className="user-message-bubble"> - <div className="user-message-content"> - <Md>{content}</Md> - </div> - <div className="user-message-time">{timeStr}</div> - </div> - ) -} - -// -- Tool lines ---------------------------------------------------------------- - -function statusIcon(inFlight: boolean) { return inFlight ? '›' : '✓' } -function statusClass(inFlight: boolean) { return inFlight ? 'activity-inflight' : 'activity-done' } - -function ToolLine({ tool, summary, inFlight }: { tool: string; summary: string; inFlight: boolean }) { - return ( - <div className={`activity-line ${statusClass(inFlight)}`}> - <span className="activity-status">{statusIcon(inFlight)}</span> - <span className="activity-tool">{tool}</span> - <span className="activity-summary"> - {summary} - {inFlight && <span className="activity-dots">...</span>} - </span> - </div> - ) -} - -function DetailLine({ tool, detail, inFlight }: { tool: string; detail: string; inFlight: boolean }) { - return ( - <div className={`activity-line ${statusClass(inFlight)}`}> - <span className="activity-status">{statusIcon(inFlight)}</span> - <span className="activity-tool">{tool}</span> - <span className="activity-detail">{detail}</span> - {inFlight && <span className="activity-dots">...</span>} - </div> - ) -} - -// -- Entry renderer ----------------------------------------------------------- - -function renderEntry(entry: ConversationEntry, i: number) { - switch (entry.type) { - case 'thinking': - return <ThinkingCard key={i} content={entry.content} /> - case 'step': - return <StepHeader key={i} step={entry.step} stepName={entry.stepName} totalSteps={entry.totalSteps} /> - case 'text': - return <TextBlock key={i} text={entry.text} /> - case 'user_message': - return <UserMessageBubble key={i} content={entry.content} timestampMs={entry.timestampMs} /> - case 'tool_read': { - const detail = entry.lines ? `${entry.file}:${entry.lines}` : entry.file - return <DetailLine key={i} tool="read" detail={detail} inFlight={entry.inFlight} /> - } - case 'tool_write': - return <DetailLine key={i} tool="write" detail={entry.file} inFlight={entry.inFlight} /> - case 'tool_edit': - return <DetailLine key={i} tool="edit" detail={entry.file} inFlight={entry.inFlight} /> - case 'tool_bash': - return <DetailLine key={i} tool="bash" detail={entry.command} inFlight={entry.inFlight} /> - case 'tool_grep': - return <DetailLine key={i} tool="grep" detail={entry.pattern} inFlight={entry.inFlight} /> - case 'tool_ls': - return <DetailLine key={i} tool="ls" detail={entry.path} inFlight={entry.inFlight} /> - case 'tool_generic': - return <ToolLine key={i} tool={entry.toolName} summary={entry.summary} inFlight={entry.inFlight} /> - case 'debug_step_guidance': - return <DebugGuidanceCard key={i} content={entry.content} /> - case 'phase_boundary': - return ( - <div key={i} className="activity-card activity-phase-boundary"> - <div className="activity-boundary-message">{entry.message}</div> - </div> - ) - default: - return null - } -} - -// -- Feed --------------------------------------------------------------------- - -export function ActivityFeed() { - const focusAgentId = useStore(s => s.run?.focus?.agentId) - const conversation = useStore(s => - focusAgentId ? s.run?.agents?.[focusAgentId]?.conversation : undefined - ) - const run = useStore(s => s.run) - const focus = useStore(s => s.run?.focus) - const scrollRef = useRef<HTMLDivElement>(null) - useAutoScroll(scrollRef) - - const hasEntries = conversation?.entries && conversation.entries.length > 0 - const isWaiting = !hasEntries && !conversation?.isThinking && !conversation?.pendingText - const hasInteraction = focus && focus.type !== 'conversation' - const showChatInput = run !== null && !hasInteraction - - return ( - <div className="activity-feed-scroll" ref={scrollRef}> - <div id="activity-feed-inner" className="activity-feed-inner"> - {isWaiting && ( - <div className="activity-waiting"> - <span className="thinking-dot">●</span> - <span>Starting agent…</span> - </div> - )} - {conversation?.entries.map(renderEntry)} - - {/* Active thinking card — shown while LLM is reasoning */} - {conversation?.isThinking && conversation.pendingThinking && ( - <div className="activity-card activity-card-thinking activity-card-active"> - <div className="activity-card-header"> - <span className="activity-card-tool">thinking</span> - </div> - <div className="activity-card-body expanded"> - <Md>{conversation.pendingThinking}</Md> - </div> - </div> - )} - - {/* Thinking indicator — no content yet */} - {conversation?.isThinking && !conversation.pendingThinking && ( - <div className="activity-thinking-indicator"> - <span className="thinking-dot">●</span> - <span>Thinking…</span> - </div> - )} - - {/* Active stream output — text being produced right now */} - {conversation?.pendingText && ( - <div className="stream-output"> - <Md>{conversation.pendingText}</Md> - <span className="streaming-cursor" /> - </div> - )} - - {/* Steering indicator + chat input — inside the feed card */} - {showChatInput && ( - <> - <SteeringIndicator /> - <ChatInput /> - </> - )} - </div> - </div> - ) -} diff --git a/frontend/src/components/AgentMonitor.tsx b/frontend/src/components/AgentMonitor.tsx deleted file mode 100644 index a5463ad..0000000 --- a/frontend/src/components/AgentMonitor.tsx +++ /dev/null @@ -1,149 +0,0 @@ -import { useMemo } from 'react' -import { useStore, Agent } from '../store/index' -import { useElapsed, formatElapsed } from '../hooks/useElapsed' - -function AgentRow({ agent }: { agent: Agent }) { - const liveElapsed = useElapsed(agent.startedAtMs) - // Freeze the timer for completed agents: show static duration instead of live tick - const elapsed = agent.completedAtMs - ? formatElapsed(agent.completedAtMs - agent.startedAtMs) - : liveElapsed - const status = agent.status - - const statusIcon = status === 'running' ? '›' - : status === 'done' ? '✓' - : '✘' - const statusCls = `agent-status-${status}` - const nameCls = `agent-name-${status}` - const doingCls = status === 'failed' ? 'agent-doing-failed' : 'agent-doing-dim' - const toolCount = agent.conversation.entries.filter(e => - e.type.startsWith('tool_') - ).length - - const doingText = status === 'failed' - ? (agent.error || 'failed') - : status === 'done' - ? 'done' - : (agent.lastTool || agent.stepName || `step ${agent.step}`) - - return ( - <div className={`agent-row agent-row-${status}`}> - <span className={`agent-row-icon ${statusCls}`}>{statusIcon}</span> - <span className={`agent-row-name ${nameCls}`}>{agent.label || agent.role}</span> - <span className="agent-row-model">{agent.model ?? '--'}</span> - <span className="agent-row-tools"> - <span className="agent-row-tools-num">{toolCount}</span> - <span className="agent-row-tools-label"> tools</span> - </span> - <span className="agent-row-time">{elapsed}</span> - <span className={`agent-row-doing ${doingCls}`}>{doingText}</span> - </div> - ) -} - -function CounterBar({ running, queued, done, failed }: { - running: number; queued: number; done: number; failed: number -}) { - return ( - <div className="agent-counter-bar"> - <div className="agent-counter agent-counter-running"> - <span className="agent-counter-num">{running}</span> - <span className="agent-counter-label">running</span> - </div> - <div className="agent-counter agent-counter-queued"> - <span className="agent-counter-num">{queued}</span> - <span className="agent-counter-label">queued</span> - </div> - <div className="agent-counter agent-counter-done"> - <span className="agent-counter-num">{done}</span> - <span className="agent-counter-label">done</span> - </div> - <div className="agent-counter agent-counter-failed"> - <span className="agent-counter-num">{failed}</span> - <span className="agent-counter-label">failed</span> - </div> - </div> - ) -} - -function SectionHeader({ icon, label, className }: { - icon: string; label: string; className: string -}) { - return ( - <div className={`agent-section-header ${className}`}> - {icon} {label} - </div> - ) -} - -export function AgentMonitor() { - const agents = useStore(s => s.run?.agents ?? {}) - - const { running, queued, done, failed } = useMemo(() => { - const all = Object.values(agents) - return { - running: all.filter(a => !a.isPrimary && a.status === 'running'), - queued: all.filter(a => a.status === 'queued'), - done: all.filter(a => a.status === 'done' && !a.isPrimary), - failed: all.filter(a => a.status === 'failed' && !a.isPrimary), - } - }, [agents]) - - const total = running.length + queued.length + done.length + failed.length - if (total === 0) return null - - // Hide entirely when nothing is active — counter bar adds no value - // when all agents are done. - const hasActive = running.length > 0 || queued.length > 0 - if (!hasActive) return null - - return ( - <div id="monitor" className="monitor"> - <div className="monitor-inner"> - <CounterBar - running={running.length} - queued={queued.length} - done={done.length} - failed={failed.length} - /> - - {running.length > 0 && ( - <> - <SectionHeader icon="●" label="running" className="section-running" /> - {running.map(a => <AgentRow key={a.agentId} agent={a} />)} - </> - )} - - {queued.length > 0 && ( - <> - <SectionHeader icon="○" label="queued" className="section-queued" /> - {queued.map(a => ( - <div key={a.agentId} className="agent-row agent-row-queued"> - <span className="agent-row-icon agent-status-queued">○</span> - <span className="agent-row-name agent-name-queued">{a.label || 'scout'}</span> - <span className="agent-row-model">--</span> - <span className="agent-row-tools"><span className="agent-row-tools-num">0</span><span className="agent-row-tools-label"> tools</span></span> - <span className="agent-row-time">--</span> - <span className="agent-row-doing agent-doing-dim">queued</span> - </div> - ))} - </> - )} - - {done.length > 0 && ( - <> - <SectionHeader icon="✓" label="done" className="section-done" /> - {done.map(a => <AgentRow key={a.agentId} agent={a} />)} - </> - )} - - {failed.length > 0 && ( - <> - <SectionHeader icon="✘" label="failed" className="section-failed" /> - {failed.map(a => <AgentRow key={a.agentId} agent={a} />)} - </> - )} - </div> - </div> - ) -} diff --git a/frontend/src/components/ArtifactsSidebar.tsx b/frontend/src/components/ArtifactsSidebar.tsx deleted file mode 100644 index 2be0d68..0000000 --- a/frontend/src/components/ArtifactsSidebar.tsx +++ /dev/null @@ -1,127 +0,0 @@ -import { useState } from 'react' -import { useArtifactTree } from '../store/selectors' -import { ArtifactInfo } from '../store/index' -import { formatSize } from '../utils' -import * as api from '../api/client' - -function ArtifactOverlay({ - displayPath, - content, - onClose, -}: { - displayPath: string - content: string - onClose: () => void -}) { - const filename = displayPath.split('/').pop() ?? displayPath - - return ( - <div className="artifact-overlay" onClick={onClose}> - <div className="artifact-overlay-panel" onClick={e => e.stopPropagation()}> - <div className="artifact-overlay-header"> - <div> - <div className="artifact-overlay-title"> - {filename} - <span className="artifact-overlay-readonly-badge">read-only</span> - </div> - <div className="artifact-overlay-path">{displayPath}</div> - </div> - <button className="settings-btn" onClick={onClose} aria-label="Close"> - ✕ - </button> - </div> - <div className="artifact-overlay-body"> - <pre>{content}</pre> - </div> - </div> - </div> - ) -} - -function FolderNode({ - dir, - files, - onFileClick, -}: { - dir: string - files: ArtifactInfo[] - onFileClick: (path: string) => void -}) { - const [open, setOpen] = useState(true) - - return ( - <div className="tree-folder"> - <div className="tree-folder-label" onClick={() => setOpen(v => !v)}> - {open ? '▾' : '▸'} {dir}/ - </div> - {open && ( - <div className="tree-children"> - {files.map(f => { - const filename = f.path.split('/').pop() ?? f.path - const modTime = new Date(f.modifiedAt).toLocaleTimeString([], { - hour: '2-digit', - minute: '2-digit', - second: '2-digit', - }) - return ( - <div - key={f.path} - className="tree-file" - onClick={() => onFileClick(f.path)} - > - <span className="tree-file-name">{filename}</span> - <span className="tree-file-meta"> - {formatSize(f.size)} — {modTime} - </span> - </div> - ) - })} - </div> - )} - </div> - ) -} - -export function ArtifactsSidebar() { - const tree = useArtifactTree() - const [overlay, setOverlay] = useState<{ displayPath: string; content: string } | null>(null) - - const handleFileClick = async (path: string) => { - try { - const data = await api.getArtifactContent(path) - setOverlay({ displayPath: data.displayPath, content: data.content }) - } catch { - // ignore fetch errors - } - } - - const dirs = Object.keys(tree) - - return ( - <> - <aside id="artifacts-sidebar" className="artifacts-sidebar"> - <div className="sidebar-heading">Artifacts</div> - {dirs.length === 0 ? ( - <div className="artifacts-empty">No artifacts yet</div> - ) : ( - dirs.map(dir => ( - <FolderNode - key={dir} - dir={dir} - files={tree[dir]} - onFileClick={handleFileClick} - /> - )) - )} - </aside> - - {overlay && ( - <ArtifactOverlay - displayPath={overlay.displayPath} - content={overlay.content} - onClose={() => setOverlay(null)} - /> - )} - </> - ) -} diff --git a/frontend/src/components/ChatInput.tsx b/frontend/src/components/ChatInput.tsx deleted file mode 100644 index 9d38cb1..0000000 --- a/frontend/src/components/ChatInput.tsx +++ /dev/null @@ -1,69 +0,0 @@ -import { useState, useRef, useEffect, KeyboardEvent } from 'react' -import { useStore } from '../store/index' -import { sendChatMessage } from '../api/client' - -export function ChatInput() { - const [text, setText] = useState('') - const [sending, setSending] = useState(false) - const textareaRef = useRef<HTMLTextAreaElement>(null) - - const run = useStore(s => s.run) - const isDisabled = !run || run.completion !== null || sending - - // Auto-resize textarea to fit content - useEffect(() => { - const ta = textareaRef.current - if (!ta) return - ta.style.height = 'auto' - ta.style.height = Math.min(ta.scrollHeight, 120) + 'px' - }, [text]) - - async function handleSend() { - const msg = text.trim() - if (!msg || isDisabled) return - - setSending(true) - try { - await sendChatMessage(msg) - setText('') - } catch (e) { - // Silently ignore network errors; message may still be buffered - } finally { - setSending(false) - } - } - - function handleKeyDown(e: KeyboardEvent<HTMLTextAreaElement>) { - if (e.key === 'Enter' && !e.shiftKey) { - e.preventDefault() - handleSend() - } - } - - return ( - <div className="chat-input-area"> - <div className="chat-input-box"> - <textarea - ref={textareaRef} - className="chat-input-textarea" - value={text} - onChange={e => setText(e.target.value)} - onKeyDown={handleKeyDown} - placeholder={isDisabled ? 'No active run' : 'Send feedback…'} - disabled={isDisabled} - rows={1} - /> - <div className="chat-input-footer"> - <span className="chat-input-hint">Enter to send · Shift+Enter for newline</span> - <button - className="chat-input-send" - onClick={handleSend} - disabled={isDisabled || !text.trim()} - > - Send - </button> - </div> - </div> - </div> - ) -} diff --git a/frontend/src/components/Completion.tsx b/frontend/src/components/Completion.tsx deleted file mode 100644 index c7ad493..0000000 --- a/frontend/src/components/Completion.tsx +++ /dev/null @@ -1,42 +0,0 @@ -import { useStore } from '../store/index' - -export function Completion() { - const completion = useStore(s => s.run?.completion) - const artifacts = useStore(s => s.run?.artifacts ?? {}) - - if (!completion) return null - - const artifactList = Object.keys(artifacts) - - return ( - <div className="phase-content"> - <div className="phase-inner"> - {completion.success ? ( - <> - <h2 className="phase-heading">Run Complete</h2> - <p className="phase-status"> - {completion.summary || 'All phases completed successfully.'} - </p> - {artifactList.length > 0 && ( - <div className="summary-list"> - {artifactList.map(path => ( - <div key={path} className="summary-item"> - <span className="icon-done">[OK]</span> - <span>{path}</span> - </div> - ))} - </div> - )} - </> - ) : ( - <> - <h2 className="phase-heading" style={{ color: 'var(--status-failed)' }}> - Run Failed - </h2> - <p className="phase-status">{completion.error || 'An error occurred.'}</p> - </> - )} - </div> - </div> - ) -} diff --git a/frontend/src/components/Header.tsx b/frontend/src/components/Header.tsx deleted file mode 100644 index 4efd41d..0000000 --- a/frontend/src/components/Header.tsx +++ /dev/null @@ -1,22 +0,0 @@ -import { useStore } from '../store/index' - -export function Header() { - const setSettingsOpen = useStore(s => s.setSettingsOpen) - - return ( - <header className="header"> - <div className="header-left"> - <span className="logo">koan</span> - </div> - <div className="header-right"> - <button - className="settings-btn" - aria-label="Settings" - onClick={() => setSettingsOpen(true)} - > - ⚙ - </button> - </div> - </header> - ) -} diff --git a/frontend/src/components/LandingPage.tsx b/frontend/src/components/LandingPage.tsx deleted file mode 100644 index 0ee6964..0000000 --- a/frontend/src/components/LandingPage.tsx +++ /dev/null @@ -1,280 +0,0 @@ -import { useState, useEffect, useMemo } from 'react' -import { useStore } from '../store/index' -import * as api from '../api/client' - -export function LandingPage() { - const [task, setTask] = useState('') - const [profile, setProfile] = useState('') - const [scoutConcurrency, setScoutConcurrency] = useState(8) - const [loading, setLoading] = useState(false) - const [error, setError] = useState<string | null>(null) - const [selectedInstallations, setSelectedInstallations] = useState<Record<string, string>>({}) - const [workflow, setWorkflow] = useState<'plan' | 'milestones'>('plan') - const [projectDir, setProjectDir] = useState('') - - // Read from store (fed by SSE — always current, no API fetch needed) - const profilesDict = useStore(s => s.settings.profiles) - const installationsDict = useStore(s => s.settings.installations) - const defaultProfile = useStore(s => s.settings.defaultProfile) - const defaultScoutConcurrency = useStore(s => s.settings.defaultScoutConcurrency) - - const profiles = useMemo(() => Object.values(profilesDict), [profilesDict]) - const installations = useMemo(() => Object.values(installationsDict), [installationsDict]) - - // Available means the binary was probed and found - const hasRunners = installations.some(i => i.available) - - // Load initial prompt (one-shot, not config state) - useEffect(() => { - api.getInitialPrompt().then(data => { - if (data.prompt) setTask(data.prompt) - if (data.project_dir) setProjectDir(data.project_dir) - }) - }, []) - - // Auto-select default profile when profiles arrive from store - useEffect(() => { - if (profiles.length > 0 && !profile) { - const def = profiles.find(p => p.name === defaultProfile) ?? profiles[0] - setProfile(def.name) - } - }, [profiles, profile, defaultProfile]) - - // Sync scout concurrency from store - useEffect(() => { - setScoutConcurrency(defaultScoutConcurrency) - }, [defaultScoutConcurrency]) - - // Derive preflight locally from store state — no API call needed - const preflight = useMemo(() => { - const selectedProfile = profiles.find(p => p.name === profile) - if (!selectedProfile) return null - - // Profile tiers map role → value. The fold normalizes tier configs to strings. - const requiredTypes = new Set<string>() - for (const tierVal of Object.values(selectedProfile.tiers)) { - if (typeof tierVal === 'string') { - const inst = installationsDict[tierVal] - if (inst) { - requiredTypes.add(inst.runnerType) - } else { - requiredTypes.add(tierVal) - } - } - } - - // Group available installations by runner type - const installationsByType: Record<string, { alias: string; binary: string }[]> = {} - for (const rt of requiredTypes) { - installationsByType[rt] = installations - .filter(i => i.runnerType === rt && i.available) - .map(i => ({ alias: i.alias, binary: i.binary })) - } - - return { - required_runner_types: [...requiredTypes].sort(), - installations: installationsByType, - } - }, [profile, profiles, installations, installationsDict]) - - // Auto-select installations when preflight changes - useEffect(() => { - if (!preflight) { - setSelectedInstallations({}) - return - } - const selections: Record<string, string> = {} - for (const rt of preflight.required_runner_types) { - const insts = preflight.installations[rt] || [] - const defaultInst = insts.find(i => i.alias === `${rt}-default`) - const first = insts[0] - if (defaultInst) selections[rt] = defaultInst.alias - else if (first) selections[rt] = first.alias - } - setSelectedInstallations(selections) - }, [preflight]) - - const installationsReady = preflight - ? preflight.required_runner_types.every(rt => selectedInstallations[rt]) - : false - - const handleStart = async () => { - const trimmedTask = task.trim() - if (!trimmedTask) { - setError('Please enter a task description') - return - } - if (!profile) { - setError('Please select a profile') - return - } - if (!installationsReady) { - setError('Please select an installation for each required runner type') - return - } - setError(null) - setLoading(true) - try { - const result = await api.startRun( - trimmedTask, profile, scoutConcurrency, selectedInstallations, workflow, - ) - if (!result.ok) { - setError(result.message ?? 'Failed to start run') - } - } catch { - setError('Network error') - } finally { - setLoading(false) - } - } - - return ( - <div className="main-panel"> - <div className="phase-content"> - <div className="phase-inner"> - <h2 className="phase-heading">New Run</h2> - - <div className="launch-project-dir"> - <span className="launch-project-dir-label">PROJECT</span> - <span className="launch-project-dir-path">{projectDir || '—'}</span> - </div> - - {/* Workflow card */} - <div className="card"> - <div className="launch-section-label">Workflow</div> - <div className="launch-workflow-grid"> - <button - className={`launch-workflow-card${workflow === 'plan' ? ' selected' : ''}`} - onClick={() => setWorkflow('plan')} - > - <div className="launch-workflow-card-header"> - <div className={`launch-radio-dot${workflow === 'plan' ? ' selected' : ''}`} /> - <span className="launch-workflow-card-name">Plan</span> - </div> - <div className="launch-workflow-card-desc">Plan an approach, review it, then execute</div> - </button> - <button className="launch-workflow-card disabled" disabled> - <div className="launch-workflow-card-header"> - <div className="launch-radio-dot" /> - <span className="launch-workflow-card-name">Milestones</span> - <span className="launch-badge-soon">coming soon</span> - </div> - <div className="launch-workflow-card-desc">Break work into milestones with phased delivery</div> - </button> - </div> - </div> - - {/* Description card */} - <div className="card"> - <div className="launch-section-label">Description</div> - <div className="launch-description-hint">What should this run accomplish?</div> - <textarea - id="task-input" - className="workflow-feedback" - placeholder="Describe what you want to build..." - rows={4} - value={task} - onChange={e => setTask(e.target.value)} - /> - </div> - - {/* Configuration card */} - <div className="card"> - <div className="launch-section-label">Configuration</div> - - {/* Profile */} - <div className="launch-config-group"> - <div className="launch-config-label">Profile</div> - <select - id="profile-select" - className="model-tier-select" - value={profile} - onChange={e => setProfile(e.target.value)} - > - {profiles.map(p => ( - <option key={p.name} value={p.name}> - {p.name} - {p.readOnly ? ' (built-in)' : ''} - </option> - ))} - </select> - </div> - - {/* Agent installations */} - {preflight && preflight.required_runner_types.length > 0 && ( - <div className="launch-config-group"> - <div className="launch-config-label">Agent Installations</div> - {preflight.required_runner_types.map(rt => { - const insts = preflight.installations[rt] || [] - const selected = selectedInstallations[rt] || '' - return ( - <div key={rt} className="launch-agent-row"> - <span className="launch-agent-type">{rt}</span> - <div className={`launch-agent-status ${insts.length > 0 && selected ? 'available' : 'unavailable'}`} /> - <select - className="launch-agent-select" - value={selected} - onChange={e => setSelectedInstallations(prev => ({ ...prev, [rt]: e.target.value }))} - > - <option value="">-- select --</option> - {insts.map(inst => ( - <option key={inst.alias} value={inst.alias}> - {inst.alias} ({inst.binary}) - </option> - ))} - </select> - {insts.length === 0 && ( - <span className="launch-agent-missing">Not detected — configure in Settings</span> - )} - </div> - ) - })} - </div> - )} - - {/* Scout concurrency */} - <div className="launch-config-group"> - <div className="launch-config-label">Scout Concurrency</div> - <div className="launch-scouts-row"> - <input - id="scout-concurrency" - className="scout-concurrency-input" - type="number" - min={1} - max={32} - value={scoutConcurrency} - onChange={e => setScoutConcurrency(parseInt(e.target.value, 10) || 8)} - /> - <span className="launch-scouts-hint">max parallel scout agents</span> - </div> - </div> - </div> - - {error && <div className="no-runners-msg">{error}</div>} - - <div className="form-actions"> - <button - id="btn-start-run" - className="btn btn-primary" - disabled={!hasRunners || loading || !installationsReady} - title={ - !hasRunners - ? 'No available agent installations. Add and configure at least one in Settings.' - : undefined - } - onClick={handleStart} - > - {loading ? 'Starting...' : 'Start Run'} - </button> - </div> - - {!hasRunners && ( - <span className="no-runners-msg"> - No available agent installations. Open Settings to add and configure one. - </span> - )} - </div> - </div> - </div> - ) -} diff --git a/frontend/src/components/StatusSidebar.tsx b/frontend/src/components/StatusSidebar.tsx deleted file mode 100644 index 745d868..0000000 --- a/frontend/src/components/StatusSidebar.tsx +++ /dev/null @@ -1,107 +0,0 @@ -import { useMemo } from 'react' -import { useStore } from '../store/index' -import { useElapsed } from '../hooks/useElapsed' - -function toTitleCase(phase: string): string { - return phase - .split('-') - .map(w => w.charAt(0).toUpperCase() + w.slice(1)) - .join(' ') -} - -function fmt(n: number): string { - if (!n) return '--' - if (n < 1000) return String(n) - return (n / 1000).toFixed(1).replace(/\.0$/, '') + 'k' -} - -export function StatusSidebar() { - const phase = useStore(s => s.run?.phase ?? '') - const agents = useStore(s => s.run?.agents) - - const primary = useMemo( - () => agents ? Object.values(agents).find(a => a.isPrimary && a.status === 'running') : null, - [agents] - ) - - // Derive totalSteps from the last StepEntry in the conversation - const totalSteps = useMemo(() => { - if (!primary) return null - const entries = primary.conversation.entries - for (let i = entries.length - 1; i >= 0; i--) { - const e = entries[i] - if (e.type === 'step' && e.totalSteps != null) return e.totalSteps - } - return null - }, [primary]) - - const elapsed = useElapsed(primary?.startedAtMs ?? Date.now()) - - const barPct = (totalSteps && primary && primary.step > 0) - ? Math.min(100, (primary.step / totalSteps) * 100) - : 0 - - const hasContent = !!phase || !!primary - - if (!hasContent) { - return ( - <aside className="status-sidebar"> - <div className="sidebar-waiting">Waiting…</div> - </aside> - ) - } - - return ( - <aside className="status-sidebar"> - {phase && ( - <div className="sidebar-phase-section"> - <div className="sidebar-section-label">Phase</div> - <div className="sidebar-phase-name">{toTitleCase(phase)}</div> - - {primary && primary.step > 0 && ( - <div className="sidebar-step-block"> - <div className="sidebar-step-meta"> - <span>{primary.stepName || `step ${primary.step}`}</span> - {totalSteps != null && ( - <span>{primary.step} / {totalSteps}</span> - )} - </div> - {totalSteps != null && ( - <div className="sidebar-step-bar"> - <div className="sidebar-step-fill" style={{ width: `${barPct}%` }} /> - </div> - )} - </div> - )} - </div> - )} - - {primary && ( - <> - <div className="sidebar-divider" /> - <div className="sidebar-agent-section"> - <div className="sidebar-section-label">Orchestrator</div> - <div className="sidebar-model-row"> - <span className="sidebar-model-dot" /> - <span className="sidebar-model-name">{primary.model ?? '--'}</span> - </div> - <div className="sidebar-metrics"> - <div className="sidebar-metric-row"> - <span>tokens in</span> - <span>{fmt(primary.conversation.inputTokens)}</span> - </div> - <div className="sidebar-metric-row"> - <span>tokens out</span> - <span>{fmt(primary.conversation.outputTokens)}</span> - </div> - <div className="sidebar-metric-row"> - <span>elapsed</span> - <span>{elapsed}</span> - </div> - </div> - </div> - </> - )} - </aside> - ) -} diff --git a/frontend/src/components/interactions/AskWizard.tsx b/frontend/src/components/interactions/AskWizard.tsx deleted file mode 100644 index 65dc5ff..0000000 --- a/frontend/src/components/interactions/AskWizard.tsx +++ /dev/null @@ -1,288 +0,0 @@ -import { useState } from 'react' -import { useStore, AskQuestion } from '../../store/index' -import * as api from '../../api/client' -import { Md } from '../Md' - -// Normalize raw question options from LLM output. Options may arrive as strings -// or dicts with varying key names. This is data cleaning for LLM output -// variability — not business logic. -function normalizeOptions( - rawOpts: (string | Record<string, unknown>)[] | undefined, -): { value: string; label: string; recommended?: boolean }[] { - if (!rawOpts) return [] - return rawOpts.map(o => { - if (typeof o === 'string') return { value: o, label: o } - const label = String(o['label'] ?? o['text'] ?? o['value'] ?? o['option'] ?? '') - const value = String(o['value'] ?? o['label'] ?? o['text'] ?? label) - return { value, label, recommended: (o['recommended'] as boolean) ?? false } - }) -} - -/** True when the question should render as a free-form text input. */ -function isFreeText(q: AskQuestion): boolean { - return q.free_text === true || !q.options || q.options.length === 0 -} - -interface AnswerMap { - [qIdx: number]: string | string[] | null -} - -/** Map from question index to the "Other" free-text typed by the user. */ -interface OtherTextMap { - [qIdx: number]: string -} - -function collectDefaults(questions: AskQuestion[]): AnswerMap { - const defaults: AnswerMap = {} - questions.forEach((q, i) => { - if (isFreeText(q)) { - defaults[i] = null - return - } - const recommended = (q.options ?? []).filter(o => o.recommended).map(o => o.value) - defaults[i] = q.multi ? recommended : (recommended[0] ?? null) - }) - return defaults -} - -function QuestionCard({ - question, - qIdx, - answer, - otherText, - onAnswer, - onOtherText, - children, -}: { - question: AskQuestion - qIdx: number - answer: string | string[] | null - otherText: string - onAnswer: (qIdx: number, val: string | string[] | null) => void - onOtherText: (qIdx: number, text: string) => void - children?: React.ReactNode -}) { - const selected = Array.isArray(answer) ? answer : answer ? [answer] : [] - - const toggle = (value: string) => { - if (value === '__other__') { - if (question.multi) { - const newSel = selected.includes('__other__') - ? selected.filter(v => v !== '__other__') - : [...selected, '__other__'] - onAnswer(qIdx, newSel) - } else { - onAnswer(qIdx, selected[0] === '__other__' ? null : '__other__') - } - return - } - if (question.multi) { - const newSel = selected.includes(value) - ? selected.filter(v => v !== value) - : [...selected, value] - onAnswer(qIdx, newSel) - } else { - onAnswer(qIdx, selected[0] === value ? null : value) - } - } - - // Options are used as-is. Prompt engineering ensures correct format; - // code never parses or rewrites LLM text. - const opts = normalizeOptions(question.options as (string | Record<string, unknown>)[]) - - const decisionContent = ( - <> - <div className="question-decision-label">Decision</div> - <div className="question-text"><Md>{question.question}</Md></div> - - {isFreeText(question) ? ( - <div className="free-text-area"> - <textarea - className="free-text-input" - rows={4} - placeholder="Type your answer..." - value={typeof answer === 'string' ? answer : ''} - onChange={e => onAnswer(qIdx, e.target.value || null)} - /> - </div> - ) : ( - <> - {question.multi && ( - <div className="question-multi-hint">Select all that apply</div> - )} - <div className="options-list"> - {opts.map(opt => ( - <div - key={opt.value} - className={`option${selected.includes(opt.value) ? ' selected' : ''}${opt.recommended ? ' recommended' : ''}`} - onClick={() => toggle(opt.value)} - > - <span className={question.multi ? 'checkbox-dot' : 'radio-dot'} /> - <span className="option-text">{opt.label}</span> - {opt.recommended && ( - <span className="recommended-badge">recommended</span> - )} - </div> - ))} - <div - className={`option option-other${selected.includes('__other__') ? ' selected' : ''}`} - onClick={() => toggle('__other__')} - > - <span className={question.multi ? 'checkbox-dot' : 'radio-dot'} /> - <span className="option-text">Other (type your own)</span> - </div> - {selected.includes('__other__') && ( - <textarea - className="free-text-input" - rows={3} - placeholder="Type your answer..." - value={otherText} - onChange={e => onOtherText(qIdx, e.target.value)} - /> - )} - </div> - </> - )} - </> - ) - - const hasContext = !!question.context - - return ( - <div className={`question-card${hasContext ? ' question-card--split' : ''}`}> - {hasContext ? ( - <> - <div className="question-context-panel"> - <div className="question-context-rule"> - <div className="question-context-label">Context</div> - <div className="question-context"><Md>{question.context!}</Md></div> - </div> - </div> - <div className="question-decision-panel"> - {decisionContent} - {children} - </div> - </> - ) : ( - <div className="question-decision-panel question-decision-panel--full"> - {decisionContent} - {children} - </div> - )} - </div> - ) -} - -/** - * Resolve __other__ sentinels in the answer map with actual typed text. - * For single-select: "__other__" → the typed string. - * For multi-select: ["a", "__other__"] → ["a", "the typed string"]. - */ -function resolveOtherText( - answers: AnswerMap, - otherTexts: OtherTextMap, - questions: AskQuestion[], -): (string | string[] | null)[] { - return questions.map((_, i) => { - const raw = answers[i] ?? null - const typed = otherTexts[i] || '' - if (raw === '__other__') return typed || null - if (Array.isArray(raw)) { - return raw.map(v => (v === '__other__' ? typed : v)) - } - return raw - }) -} - -export function AskWizard() { - const focus = useStore(s => s.run?.focus) - const [currentIdx, setCurrentIdx] = useState(0) - const [answers, setAnswers] = useState<AnswerMap>({}) - const [otherTexts, setOtherTexts] = useState<OtherTextMap>({}) - const [submitError, setSubmitError] = useState<string | null>(null) - - if (!focus || focus.type !== 'question') return null - - const { questions, token } = focus - const total = questions.length - - const handleAnswer = (qIdx: number, val: string | string[] | null) => { - setAnswers(prev => ({ ...prev, [qIdx]: val })) - } - - const handleOtherText = (qIdx: number, text: string) => { - setOtherTexts(prev => ({ ...prev, [qIdx]: text })) - } - - const handleNext = () => { - if (currentIdx < total - 1) setCurrentIdx(i => i + 1) - } - - const handleBack = () => { - if (currentIdx > 0) setCurrentIdx(i => i - 1) - } - - const handleSubmit = async () => { - const finalAnswers = resolveOtherText(answers, otherTexts, questions) - const res = await api.submitAnswer(finalAnswers, token) - if (!res.ok) { - setSubmitError(res.message ?? 'Failed to submit answers') - } - } - - const handleUseDefaults = async () => { - const defaults = collectDefaults(questions) - const finalAnswers = questions.map((_, i) => defaults[i] ?? null) - const res = await api.submitAnswer(finalAnswers, token) - if (!res.ok) { - setSubmitError(res.message ?? 'Failed to submit defaults') - } - } - - return ( - <div className="phase-content"> - <div className="phase-inner"> - <div className="count-progress"> - {currentIdx + 1} / {total} - </div> - - <QuestionCard - key={currentIdx} - question={questions[currentIdx]} - qIdx={currentIdx} - answer={answers[currentIdx] ?? null} - otherText={otherTexts[currentIdx] ?? ''} - onAnswer={handleAnswer} - onOtherText={handleOtherText} - > - {submitError && <div className="no-runners-msg">{submitError}</div>} - - <div className="question-actions"> - {currentIdx > 0 && ( - <button className="btn btn-secondary" onClick={handleBack}> - Back - </button> - )} - <button className="btn btn-secondary" onClick={handleUseDefaults}> - Use Defaults - </button> - {currentIdx < total - 1 && ( - <button className="btn btn-primary" onClick={handleNext}> - Next - </button> - )} - {currentIdx === total - 1 && ( - <button - id="btn-submit-answers" - className="btn btn-primary" - onClick={handleSubmit} - > - Submit - </button> - )} - </div> - </QuestionCard> - </div> - </div> - ) -} diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx index 56fcd4a..7001412 100644 --- a/frontend/src/main.tsx +++ b/frontend/src/main.tsx @@ -4,6 +4,7 @@ import './styles/variables.css' import './styles/layout.css' import './styles/components.css' import './styles/markdown.css' +import './styles/app-shell.css' import App from './App' const root = document.getElementById('root')! diff --git a/frontend/src/styles/app-shell.css b/frontend/src/styles/app-shell.css new file mode 100644 index 0000000..7f9daf0 --- /dev/null +++ b/frontend/src/styles/app-shell.css @@ -0,0 +1,112 @@ +/* App shell layout — the page frame for all views */ + +.app-root { + display: flex; + flex-direction: column; + height: 100vh; + overflow: hidden; + background: var(--bg-base); +} + +/* Two-column workflow grid: content + sidebar */ +.workflow-grid { + flex: 1; + min-height: 0; + max-width: 1400px; + margin: 0 auto; + width: 100%; + display: grid; + grid-template-columns: minmax(0, 1fr) 260px; +} + +/* Left column of the workflow grid — scrollable content stream */ +.content-column { + overflow-y: auto; + padding: 28px 32px; +} + +/* Flex column for content stream items with standard gap */ +.content-stream { + display: flex; + flex-direction: column; + gap: var(--gap-content); +} + +/* Group consecutive tool call rows with tight spacing */ +.tool-group { + display: flex; + flex-direction: column; + gap: var(--gap-tool-rows); +} + +/* Single column layout — used for landing page, completion, loading */ +.single-column { + flex: 1; + min-height: 0; + overflow-y: auto; + background: var(--bg-base); +} + +/* Centered loading indicator */ +.loading-center { + display: flex; + align-items: center; + justify-content: center; + height: 100%; + font-family: var(--font-mono); + font-size: var(--type-breadcrumb); + color: var(--text-muted); + letter-spacing: 0.05em; +} + +/* Thinking indicator (no content yet) */ +.thinking-indicator { + display: flex; + align-items: center; + gap: 8px; + font-family: var(--font-mono); + font-size: var(--type-breadcrumb); + color: var(--text-muted); + padding: 8px 0; + margin-top: 8px; +} + +/* Pulsing dot animation */ +@keyframes pulse-dot { + 0%, 100% { opacity: 0.3; } + 50% { opacity: 1; } +} + +.pulse-dot { + color: var(--color-orange); + animation: pulse-dot 1.5s ease-in-out infinite; +} + +/* Streaming cursor */ +.stream-cursor { + display: inline-block; + width: 6px; + height: 14px; + background: var(--color-orange); + border-radius: 1px; + vertical-align: text-bottom; + margin-left: 2px; + animation: cursor-blink 1s step-end infinite; +} + +@keyframes cursor-blink { + 0%, 100% { opacity: 1; } + 50% { opacity: 0; } +} + +/* Waiting state */ +.waiting-indicator { + display: flex; + align-items: center; + gap: 8px; + padding: 16px; + color: var(--text-muted); + font-size: var(--type-prose); +} + + From 020a2b94f6e5a756c93789b157ad8cc150d9c0c7 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 15:27:18 +0700 Subject: [PATCH 342/412] fix: align header and scout bar content with centered container --- frontend/src/components/organisms/HeaderBar.css | 9 ++++++++- frontend/src/components/organisms/HeaderBar.tsx | 2 ++ frontend/src/components/organisms/ScoutBar.css | 8 +++++++- frontend/src/components/organisms/ScoutBar.tsx | 2 ++ 4 files changed, 19 insertions(+), 2 deletions(-) diff --git a/frontend/src/components/organisms/HeaderBar.css b/frontend/src/components/organisms/HeaderBar.css index ba87d68..b96c08b 100644 --- a/frontend/src/components/organisms/HeaderBar.css +++ b/frontend/src/components/organisms/HeaderBar.css @@ -1,11 +1,18 @@ .hb { background: var(--color-navy); height: var(--header-height); + flex-shrink: 0; +} + +.hb-inner { + max-width: 1400px; + margin: 0 auto; + width: 100%; + height: 100%; padding: 0 24px; display: flex; align-items: center; justify-content: space-between; - flex-shrink: 0; } /* ---- Left group ---- */ diff --git a/frontend/src/components/organisms/HeaderBar.tsx b/frontend/src/components/organisms/HeaderBar.tsx index a6014a6..0fd4d04 100644 --- a/frontend/src/components/organisms/HeaderBar.tsx +++ b/frontend/src/components/organisms/HeaderBar.tsx @@ -43,6 +43,7 @@ export function HeaderBar({ }: HeaderBarProps) { return ( <header className="hb"> + <div className="hb-inner"> <div className="hb-left"> <div className="hb-logo"> <LogoMark /> @@ -71,6 +72,7 @@ export function HeaderBar({ <GearIcon /> </button> </div> + </div> </header> ) } diff --git a/frontend/src/components/organisms/ScoutBar.css b/frontend/src/components/organisms/ScoutBar.css index 5570e14..3743014 100644 --- a/frontend/src/components/organisms/ScoutBar.css +++ b/frontend/src/components/organisms/ScoutBar.css @@ -1,9 +1,15 @@ .sb { background: var(--color-navy); - padding: var(--padding-scout-bar); flex-shrink: 0; } +.sb-inner { + max-width: 1400px; + margin: 0 auto; + width: 100%; + padding: var(--padding-scout-bar); +} + /* ---- Summary line ---- */ .sb-summary { display: flex; diff --git a/frontend/src/components/organisms/ScoutBar.tsx b/frontend/src/components/organisms/ScoutBar.tsx index a750d23..1a6e404 100644 --- a/frontend/src/components/organisms/ScoutBar.tsx +++ b/frontend/src/components/organisms/ScoutBar.tsx @@ -36,6 +36,7 @@ export function ScoutBar({ scouts }: ScoutBarProps) { return ( <div className="sb"> + <div className="sb-inner"> {/* Summary line */} <div className="sb-summary"> <div className="sb-summary-left"> @@ -68,6 +69,7 @@ export function ScoutBar({ scouts }: ScoutBarProps) { <ScoutRow key={i} {...s} /> ))} </div> + </div> </div> ) } From 3589aad6eb8d8d55710a54b64045482d179f8ca0 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 15:27:49 +0700 Subject: [PATCH 343/412] docs: sync design system with implemented components and content stream mapping --- docs/design-system.md | 69 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/docs/design-system.md b/docs/design-system.md index 752368a..11a4211 100644 --- a/docs/design-system.md +++ b/docs/design-system.md @@ -218,9 +218,41 @@ Table columns: status dot (20px col, 6px dot in status color), name (flex, `--fo White card (`--bg-card`), `--radius-xl`, `1.5px solid --border-input` (this is intentionally darker than card borders for definition). Padding `--padding-input`. Placeholder text in `--text-placeholder`. Below: hint text in `--text-hint` at 11px left-aligned, and a "Send" button right-aligned with `--color-orange` background, white text, `--radius-md`, padding 5px 16px, 13px/500. +### User bubble + +The user's own messages in the content stream. Visually distinct from agent prose (orange border) via a gray left border. Background `--bg-card`, `--radius-xl`, `0.5px solid --border-card`, `border-left: 3px solid --text-muted`. Padding: `--padding-card`. Text: `--type-prose` in `--text-primary`, line-height 1.7. Optional timestamp below in `--type-timestamp` / `--text-muted`. + +Props: `children: ReactNode`, `timestamp?: string`. + +### Phase boundary + +Visual separator between workflow phases. A centered label between two horizontal lines. Container: flex, align-items center, gap 12px, padding 20px 0. Lines: flex 1, height 1px, background `--border-divider`. Label: `--type-label`, `--text-muted`, uppercase, letter-spacing 1px, font-weight 500, white-space nowrap. + +Props: `label: string`. + +### Step header + +Step indicator at the top of each step's content stream. Shows "step N/M" in accent color followed by the step name. Container: flex, align-items center, gap 10px. Step label: `--type-step-indicator` (14px), font-weight 500. Active steps: `--color-orange`. Completed steps: `--color-teal`. Step name: `--type-step-header` (16px), font-weight 500, `--text-primary`. + +Props: `stepNumber: number`, `totalSteps: number`, `stepName: string`, `status?: 'active' | 'complete'`. + ### Completion banner -Background `--bg-completion`, `--radius-xl`, padding 14px, text centered in `--text-completion` at 14px. +Phase completion message. Success variant: background `--bg-completion`, `--radius-xl`, padding 14px, text centered in `--text-completion` at `--type-body`. Error variant: background `--bg-base`, `--status-failed` text and 1px border. + +Props: `children: ReactNode`, `variant?: 'success' | 'error'`. + +### Steering bar + +Queued steering messages from the user, shown above the FeedbackInput. Container: background `--bg-selected`, `border-left: 3px solid --color-orange`, `border-radius: 0 --radius-md --radius-md 0`, margin 8px 0. Header: "steering" label in `--font-mono`, `--type-label`, `--color-orange`. Each message: "queued" badge in `--type-label` / `--text-muted`, content in `--type-breadcrumb` / `--text-body`. Returns null when no messages. + +Props: `messages: string[]`. + +### Checkbox option card + +Multi-select variant of the radio option card. Structurally identical to RadioOption but with a square checkbox (18px, `--radius-sm`, `2px solid --border-input`). When selected: border `--color-orange`, filled with `--color-orange`, white checkmark SVG inside. All other styling matches RadioOption. + +Props: same as RadioOption (`label`, `selected`, `recommended`, `isCustom`, `customText`, `onCustomTextChange`, `onClick`). ### Form cards (New Run page) @@ -232,7 +264,13 @@ Two cards side by side in a 2-column grid with 12px gap. The selected card has ` ### Elicitation panels (Deepen view) -Two-panel 1fr/1fr grid with 20px gap. Each panel is a white card (`--bg-card`) with `--radius-2xl` and `0.5px solid --border-card`. The Context panel has a 3px `--color-teal` top border. The Decision panel has a 3px `--color-orange` top border. Panel labels use the respective accent color for text. +Two-panel 1fr/1fr grid with 20px gap (single column when no context). Each panel is a white card (`--bg-card`) with `--radius-2xl` and `0.5px solid --border-card`. The Context panel (optional) has a 3px `--color-teal` top border. The Decision panel has a 3px `--color-orange` top border. Panel labels use the respective accent color for text. + +Supports three modes: `single-select` (RadioOption), `multi-select` (CheckboxOption with "Select all that apply" hint), and `free-text` (textarea only). Supports multi-question pagination with a "N / M" counter and Previous/Next buttons. Error messages displayed below options in `--status-failed`. + +The NewRunForm organism is self-contained: it reads profiles and installations directly from the Zustand store, manages all form state internally, and calls the API to start a run. No props required. + +Agent installation rows: each row has a runner chip (background `--bg-thinking` lavender, `--radius-md`, padding 6px 12px, runner name in `--font-mono` 13px/500 `--text-thinking`, StatusDot sm) followed by an installation `<select>` dropdown (same styling as profile select but at 13px). Multiple rows stack with 10px gap. ### Radio option cards (Deepen view) @@ -246,6 +284,27 @@ Primary: `--color-orange` background, white text, `--radius-lg` (8px for larger Secondary/outline: `1.5px solid --border-input`, `--text-subtle`, `--radius-lg`. Used for "Use Defaults". +## Content Stream Rendering + +The content stream maps each conversation event type to a molecule: + +| Event type | Molecule | Notes | +|---|---|---| +| `thinking` | ThinkingBlock + Md | Collapsible, lavender background | +| `text` | ProseCard + Md | Orange left border, white card | +| `tool_read/write/edit` | ToolCallRow | status from `inFlight` flag | +| `tool_bash/grep/ls` | ToolCallRow | status from `inFlight` flag | +| `tool_generic` | ToolCallRow | uses `toolName` + `summary` | +| `step` | StepHeader | orange (active) or teal (complete) | +| `debug_step_guidance` | StepGuidancePill + Md | collapsed by default | +| `user_message` | UserBubble + Md | gray left border, with timestamp | +| `phase_boundary` | PhaseBoundary | centered label between lines | +| `pendingThinking` | ThinkingBlock (always expanded) | live streaming | +| `pendingText` | ProseCard + Md + streaming cursor | pulsing cursor animation | +| steering messages | SteeringBar | orange accent bar with queued badges | + +The FeedbackInput molecule sits at the bottom of the stream, above any SteeringBar messages. + ## Layout ### Page frame @@ -279,3 +338,9 @@ The geometric mark is two overlapping circles. The larger circle (16px diameter) The wordmark "koan" is set in `--font-display` (serif) at 17px/500, colored `--text-on-dark` when on navy, or `--text-primary` when on light backgrounds. Letter-spacing: -0.3px. The mark and wordmark are separated by 8px. On the header bar, a 1px vertical divider at `--text-on-dark-faint` separates the logo group from the navigation breadcrumb with 16px gap on each side. + +## Deferred Items + +- **SettingsOverlay redesign** — currently uses migrated tokens from the old design system. Functional but not visually redesigned. Deferred to a future pass. +- **Thinking/waiting indicators** — the pulsing dot and "Thinking…" / "Starting agent…" indicators use inline CSS classes in app-shell.css rather than standalone molecules. Functional but could be promoted to atoms in a future pass. +- **Streaming cursor** — the blinking orange cursor during text streaming uses an inline CSS class. Could become an atom. From 8535a39c68fce747842f831bef4bf55b791a98b0 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 17:49:47 +0700 Subject: [PATCH 344/412] fix: handle empty phase string during run initialization --- frontend/src/App.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index c6d6ccf..a5a903d 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -61,7 +61,7 @@ function useHeaderData() { }, [primary]) const elapsed = useElapsed(primary?.startedAtMs ?? Date.now()) return { - phase: run ? run.phase.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join(' ') : '', + phase: run?.phase ? run.phase.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join(' ') : '', step: lastStep?.stepName ?? primary?.stepName ?? '', totalSteps: lastStep?.totalSteps ?? 0, currentStep: lastStep?.step ?? 0, From 4e1cd86598ba365af0ef6062da90e463ad23bb9c Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 17:50:19 +0700 Subject: [PATCH 345/412] fix: show last tool call and completion status in scout rows --- frontend/src/App.tsx | 4 +++- frontend/src/components/molecules/ScoutRow.tsx | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index a5a903d..0d9fa75 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -105,7 +105,9 @@ function ConnectedScoutBar() { elapsed: a.completedAtMs ? formatElapsed(a.completedAtMs - (a.startedAtMs || 0)) : formatElapsed(a.startedAtMs ? now - a.startedAtMs : 0), - currentStep: a.stepName || (a.step > 0 ? `step ${a.step}` : 'step 0'), + currentStep: a.status === 'done' ? 'Done' + : a.status === 'failed' ? (a.error || 'failed') + : a.lastTool || a.stepName || (a.step > 0 ? `step ${a.step}` : 'step 0'), })) }, [agents]) return <ScoutBar scouts={scouts} /> diff --git a/frontend/src/components/molecules/ScoutRow.tsx b/frontend/src/components/molecules/ScoutRow.tsx index 66722dd..1d512fb 100644 --- a/frontend/src/components/molecules/ScoutRow.tsx +++ b/frontend/src/components/molecules/ScoutRow.tsx @@ -28,7 +28,7 @@ export function ScoutRow({ name, model, status, tools, elapsed, currentStep }: S <span className="sr-dot"><StatusDot status={status} size="sm" /></span> <span className="sr-name">{name}</span> <span className="sr-model"><Badge variant="model">{model}</Badge></span> - <span className="sr-tools">{tools} tools</span> + <span className="sr-tools">{tools}</span> <span className="sr-elapsed">{elapsed}</span> <span className={`sr-step${stepColor ? ' sr-step--active' : ''}`}>{currentStep}</span> </div> From 76b6cb39f6a28f34e741de3b6a9a42e6633da7e3 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 17:51:40 +0700 Subject: [PATCH 346/412] fix: hide scout bar when all scouts have finished --- frontend/src/components/organisms/ScoutBar.tsx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/frontend/src/components/organisms/ScoutBar.tsx b/frontend/src/components/organisms/ScoutBar.tsx index 1a6e404..3c332db 100644 --- a/frontend/src/components/organisms/ScoutBar.tsx +++ b/frontend/src/components/organisms/ScoutBar.tsx @@ -34,6 +34,9 @@ export function ScoutBar({ scouts }: ScoutBarProps) { const counts: Record<StatusKey, number> = { running: 0, queued: 0, done: 0, failed: 0 } for (const s of scouts) counts[s.status]++ + // Hide when all scouts have finished (no running or queued) + if (counts.running === 0 && counts.queued === 0) return null + return ( <div className="sb"> <div className="sb-inner"> From a71d714e9208f1a86e237cf0d579377f1589c6cb Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 17:52:18 +0700 Subject: [PATCH 347/412] refactor: improve scout bar column distribution and summary readability --- .../src/components/molecules/ScoutRow.css | 2 +- .../src/components/organisms/ScoutBar.css | 30 +++++++++---------- .../src/components/organisms/ScoutBar.tsx | 8 ++--- 3 files changed, 19 insertions(+), 21 deletions(-) diff --git a/frontend/src/components/molecules/ScoutRow.css b/frontend/src/components/molecules/ScoutRow.css index 9ceb558..fc3c67b 100644 --- a/frontend/src/components/molecules/ScoutRow.css +++ b/frontend/src/components/molecules/ScoutRow.css @@ -1,6 +1,6 @@ .sr { display: grid; - grid-template-columns: 20px minmax(0, 1.5fr) 60px 60px 70px minmax(0, 1fr); + grid-template-columns: 20px 1fr 60px 50px 70px 1fr; align-items: center; padding: var(--padding-scout-row); font-size: 12px; diff --git a/frontend/src/components/organisms/ScoutBar.css b/frontend/src/components/organisms/ScoutBar.css index 3743014..e8e67ef 100644 --- a/frontend/src/components/organisms/ScoutBar.css +++ b/frontend/src/components/organisms/ScoutBar.css @@ -7,21 +7,15 @@ max-width: 1400px; margin: 0 auto; width: 100%; - padding: var(--padding-scout-bar); + padding: 14px 24px; /* horizontal matches header bar's .hb-inner for left/right edge alignment */ } /* ---- Summary line ---- */ .sb-summary { - display: flex; - justify-content: space-between; - align-items: center; - margin-bottom: 10px; -} - -.sb-summary-left { display: flex; align-items: center; gap: 8px; + margin-bottom: 10px; } .sb-label { @@ -30,6 +24,7 @@ color: var(--text-on-dark-muted); text-transform: uppercase; letter-spacing: 1px; + margin-right: 8px; /* extra space before counts */ } .sb-counts { @@ -45,21 +40,26 @@ gap: 4px; } +/* Zero-value: both number and label use muted text */ .sb-count-num { - color: var(--text-on-dark-scouts-muted); + color: var(--text-on-dark-muted); font-weight: 500; } -/* Non-zero counts use their status color */ +.sb-count-word { + color: var(--text-on-dark-muted); +} + +/* Non-zero: number gets full status color, label gets warm white */ +.sb-count-group--active .sb-count-word { + color: var(--text-on-dark); +} + .sb-count--running { color: var(--status-running); } .sb-count--queued { color: var(--status-queued); } .sb-count--done { color: var(--status-done); } .sb-count--failed { color: var(--status-failed); } -.sb-count-word { - color: var(--text-on-dark-scouts-muted); -} - /* ---- Table card ---- */ .sb-table { background: var(--bg-card-warm); @@ -69,7 +69,7 @@ .sb-table-header { display: grid; - grid-template-columns: 20px minmax(0, 1.5fr) 60px 60px 70px minmax(0, 1fr); + grid-template-columns: 20px 1fr 60px 50px 70px 1fr; align-items: center; padding: 6px 14px; border-bottom: 0.5px solid var(--border-divider); diff --git a/frontend/src/components/organisms/ScoutBar.tsx b/frontend/src/components/organisms/ScoutBar.tsx index 3c332db..b75b96f 100644 --- a/frontend/src/components/organisms/ScoutBar.tsx +++ b/frontend/src/components/organisms/ScoutBar.tsx @@ -42,13 +42,11 @@ export function ScoutBar({ scouts }: ScoutBarProps) { <div className="sb-inner"> {/* Summary line */} <div className="sb-summary"> - <div className="sb-summary-left"> - <StatusDot status="running" /> - <span className="sb-label">Scouts</span> - </div> + <StatusDot status="running" /> + <span className="sb-label">Scouts</span> <div className="sb-counts"> {STATUS_ORDER.map(key => ( - <span key={key} className="sb-count-group"> + <span key={key} className={`sb-count-group${counts[key] > 0 ? ' sb-count-group--active' : ''}`}> <span className={`sb-count-num${counts[key] > 0 ? ` sb-count--${key}` : ''}`}> {counts[key]} </span> From 4827e507ffbc86d40093c08b4453bed8d8704b0a Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 17:52:59 +0700 Subject: [PATCH 348/412] fix: prevent code blocks from expanding elicitation grid columns --- .../components/organisms/ElicitationPanel.css | 22 ++++++++++++++++++- frontend/src/styles/app-shell.css | 1 + 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/frontend/src/components/organisms/ElicitationPanel.css b/frontend/src/components/organisms/ElicitationPanel.css index 9d373d6..d9b1f60 100644 --- a/frontend/src/components/organisms/ElicitationPanel.css +++ b/frontend/src/components/organisms/ElicitationPanel.css @@ -7,10 +7,24 @@ .ep-grid { display: grid; - grid-template-columns: 1fr 1fr; + grid-template-columns: 2fr 3fr; gap: 20px; } +.ep-grid > * { + min-width: 0; +} + +/* Stack vertically when content column is narrow */ +@container (max-width: 700px) { + .ep-grid { grid-template-columns: 1fr; } +} + +/* Fallback for browsers without container queries */ +@media (max-width: 960px) { + .ep-grid { grid-template-columns: 1fr; } +} + /* ---- Panels ---- */ .ep-panel { background: var(--bg-card); @@ -66,6 +80,12 @@ margin: 2px 0; } +.ep-panel-body pre { + max-width: 100%; + overflow-x: auto; + white-space: pre; +} + /* ---- Question ---- */ .ep-question { font-family: var(--font-body); diff --git a/frontend/src/styles/app-shell.css b/frontend/src/styles/app-shell.css index 7f9daf0..174e37a 100644 --- a/frontend/src/styles/app-shell.css +++ b/frontend/src/styles/app-shell.css @@ -23,6 +23,7 @@ .content-column { overflow-y: auto; padding: 28px 32px; + container-type: inline-size; /* enables @container queries for children */ } /* Flex column for content stream items with standard gap */ From 0c7fdc09fc185594806385a08e04b0c33c1b92a3 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 21:36:19 +0700 Subject: [PATCH 349/412] refactor: rename phase_complete_future to yield_future and add workflow_done flag --- koan/state.py | 10 ++++++---- koan/subagent.py | 10 +++++----- koan/web/app.py | 13 +++++++------ tests/test_interactions.py | 10 +++++----- tests/test_subagent.py | 2 +- 5 files changed, 24 insertions(+), 21 deletions(-) diff --git a/koan/state.py b/koan/state.py index 47a56e6..2f2dee1 100644 --- a/koan/state.py +++ b/koan/state.py @@ -84,12 +84,14 @@ class AppState: _active_processes: dict[str, asyncio.subprocess.Process] = field( default_factory=dict, repr=False, ) - # Buffered user chat messages — drained at each koan_complete_step call. + # Buffered user chat messages — drained when koan_yield unblocks. user_message_buffer: list[ChatMessage] = field(default_factory=list) - # Non-None while koan_complete_step is blocking at a phase boundary. - phase_complete_future: asyncio.Future | None = None + # Non-None while koan_yield is blocking, waiting for a user message. + yield_future: asyncio.Future | None = None + # True after koan_set_phase("done") — signals the orchestrator to exit. + workflow_done: bool = False # Steering queue — user messages delivered on the next koan_* tool response. - # Separate from user_message_buffer so phase-boundary blocking and steering + # Separate from user_message_buffer so yield blocking and steering # can be drained independently without double-delivery. steering_queue: list[ChatMessage] = field(default_factory=list) diff --git a/koan/subagent.py b/koan/subagent.py index 3a47c82..15ce2d9 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -375,7 +375,7 @@ def _cancel_pending_interactions(agent_id: str, app_state: AppState) -> None: The active interaction (if it belongs to this agent) emits a typed cancellation resolution event. - Also clears phase_complete_future if the agent was blocked at a phase boundary. + Also clears yield_future if the agent was blocked at a phase boundary. """ from .web.interactions import activate_next_interaction @@ -410,7 +410,7 @@ def _cancel_pending_interactions(agent_id: str, app_state: AppState) -> None: active.future.set_result(error_result) activate_next_interaction(app_state) - # Clear phase_complete_future if it was set (orchestrator crashed at phase boundary) - if app_state.phase_complete_future is not None and not app_state.phase_complete_future.done(): - app_state.phase_complete_future.set_result(False) - app_state.phase_complete_future = None + # Clear yield_future if it was set (orchestrator crashed at phase boundary) + if app_state.yield_future is not None and not app_state.yield_future.done(): + app_state.yield_future.set_result(False) + app_state.yield_future = None diff --git a/koan/web/app.py b/koan/web/app.py index 26bb5fb..2da06a0 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -318,9 +318,10 @@ async def api_start_run(r: Request) -> Response: # Reset run-scoped state st.user_message_buffer.clear() st.steering_queue.clear() - if st.phase_complete_future is not None and not st.phase_complete_future.done(): - st.phase_complete_future.set_result(False) - st.phase_complete_future = None + if st.yield_future is not None and not st.yield_future.done(): + st.yield_future.set_result(False) + st.yield_future = None + st.workflow_done = False # Create run directory run_id = f"{int(time.time())}-{uuid.uuid4().hex[:8]}" @@ -352,7 +353,7 @@ async def api_start_run(r: Request) -> Response: async def api_chat(r: Request) -> Response: - """Accept a user chat message, buffer it, and unblock any waiting phase boundary.""" + """Accept a user chat message, buffer it, and unblock any waiting koan_yield.""" body = await r.json() message = body.get("message", "") if not isinstance(message, str) or not message.strip(): @@ -370,7 +371,7 @@ async def api_chat(r: Request) -> Response: run = st.projection_store.projection.run primary_id = _primary_agent_id(run) if run else None - if st.phase_complete_future is not None and not st.phase_complete_future.done(): + if st.yield_future is not None and not st.yield_future.done(): st.user_message_buffer.append(msg) # Show inline in the activity feed — this is a direct conversation message st.projection_store.push_event( @@ -378,7 +379,7 @@ async def api_chat(r: Request) -> Response: {"content": msg.content, "timestamp_ms": msg.timestamp_ms}, agent_id=primary_id, ) - st.phase_complete_future.set_result(True) + st.yield_future.set_result(True) else: st.steering_queue.append(msg) # Show in the steering indicator above chat — not inline diff --git a/tests/test_interactions.py b/tests/test_interactions.py index dd92102..82cd593 100644 --- a/tests/test_interactions.py +++ b/tests/test_interactions.py @@ -32,7 +32,7 @@ class FakeAppState: interaction_queue_max: int = 8 run_dir: str | None = None projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) - phase_complete_future: asyncio.Future | None = None + yield_future: asyncio.Future | None = None steering_queue: list = field(default_factory=list) phase: str = "intake" @@ -229,16 +229,16 @@ async def test_next_queued_activated_after_cancel(self): assert app_state.active_interaction is queued_b @pytest.mark.anyio - async def test_phase_complete_future_cleared_on_exit(self): - """_cancel_pending_interactions clears phase_complete_future.""" + async def test_yield_future_cleared_on_exit(self): + """_cancel_pending_interactions clears yield_future.""" from koan.subagent import _cancel_pending_interactions app_state = FakeAppState() loop = asyncio.get_running_loop() future = loop.create_future() - app_state.phase_complete_future = future + app_state.yield_future = future _cancel_pending_interactions("agent-1", app_state) assert future.done() - assert app_state.phase_complete_future is None + assert app_state.yield_future is None diff --git a/tests/test_subagent.py b/tests/test_subagent.py index d6b2461..1d0658a 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -38,7 +38,7 @@ class FakeAppState: projection_store: object = field(default_factory=lambda: __import__('koan.projections', fromlist=['ProjectionStore']).ProjectionStore()) run_installations: dict = field(default_factory=dict) _active_processes: dict = field(default_factory=dict) - phase_complete_future: Any = None + yield_future: Any = None steering_queue: list = field(default_factory=list) phase: str = "intake" project_dir: str = "" From 908c7f8d90227367f8815ade02762d77aea29a88 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 21:36:28 +0700 Subject: [PATCH 350/412] feat: add yield projection types, events, and permissions infrastructure --- koan/events.py | 10 ++++++ koan/lib/permissions.py | 3 +- koan/projections.py | 68 +++++++++++++++++++++++++++++++++++++++-- 3 files changed, 77 insertions(+), 4 deletions(-) diff --git a/koan/events.py b/koan/events.py index 041d6ce..5518827 100644 --- a/koan/events.py +++ b/koan/events.py @@ -188,6 +188,16 @@ def build_questions_answered( return result +def build_yield_started(suggestions: list[dict]) -> dict: + """Build yield_started event payload. + + Args: + suggestions: List of {id, label, command} dicts — the structured + options the orchestrator presents at a yield point. + """ + return {"suggestions": suggestions} + + # -- Configuration event builders --------------------------------------------- def build_probe_completed(results: dict[str, bool]) -> dict: diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index 2c4cd1c..1614512 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -45,6 +45,7 @@ # Base set; actual permissions are phase-aware — see _check_orchestrator_permission "koan_complete_step", "koan_set_phase", + "koan_yield", "koan_ask_question", "koan_request_scouts", "koan_request_executor", @@ -132,7 +133,7 @@ def _check_orchestrator_permission( return {"allowed": False, "reason": f"bash is not available in phase '{phase}'"} # Always allowed base koan tools - if tool_name in ("koan_complete_step", "koan_set_phase"): + if tool_name in ("koan_complete_step", "koan_set_phase", "koan_yield"): return {"allowed": True, "reason": None} # koan_ask_question — always allowed except brief-generation step 1 diff --git a/koan/projections.py b/koan/projections.py index cdba3bd..3d18f49 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -55,6 +55,9 @@ # User chat "user_message", "phase_boundary_reached", + # Yield — orchestrator hands control back to the user + "yield_started", + "yield_cleared", # Steering "steering_queued", "steering_delivered", @@ -185,11 +188,30 @@ class PhaseBoundaryEntry(KoanBaseModel): phase: str message: str +class Suggestion(KoanBaseModel): + """A structured option presented to the user at a yield point.""" + id: str # machine key (e.g. "plan-spec", "done") + label: str # display text (e.g. "Write implementation plan") + command: str = "" # pre-fills the chat input when the pill is clicked + +class YieldEntry(KoanBaseModel): + """Conversation entry emitted when the orchestrator yields to the user.""" + type: Literal["yield"] = "yield" + suggestions: list[Suggestion] = [] # clickable options shown in the UI + +class ActiveYield(KoanBaseModel): + """Run-level state tracking the current yield's suggestions. + + Non-None while the orchestrator is blocked in koan_yield. Cleared when + a phase starts, the workflow completes, or a new yield supersedes it. + """ + suggestions: list[Suggestion] = [] + ConversationEntry = Annotated[ ThinkingEntry | TextEntry | StepEntry | UserMessageEntry | ToolReadEntry | ToolWriteEntry | ToolEditEntry | ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry | - DebugStepGuidanceEntry | PhaseBoundaryEntry, + DebugStepGuidanceEntry | PhaseBoundaryEntry | YieldEntry, Field(discriminator="type"), ] @@ -323,6 +345,7 @@ class Run(KoanBaseModel): artifacts: dict[str, ArtifactInfo] = {} completion: CompletionInfo | None = None steering: list[SteeringMessage] = [] # pending steering messages shown above chat + active_yield: ActiveYield | None = None # non-None while orchestrator is in koan_yield class Projection(KoanBaseModel): settings: Settings = Field(default_factory=Settings) @@ -451,7 +474,10 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: if projection.run is None: log.warning("fold phase_started: run is None, skipping") return projection - new_run = projection.run.model_copy(update={"phase": payload.get("phase", "")}) + new_run = projection.run.model_copy(update={ + "phase": payload.get("phase", ""), + "active_yield": None, # clear yield when a new phase starts + }) return projection.model_copy(update={"run": new_run}) case "workflow_completed": @@ -463,7 +489,10 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: summary=payload.get("summary", ""), error=payload.get("error"), ) - new_run = projection.run.model_copy(update={"completion": completion}) + new_run = projection.run.model_copy(update={ + "completion": completion, + "active_yield": None, # clear yield on completion + }) return projection.model_copy(update={"run": new_run}) # ── Agent lifecycle ──────────────────────────────────────────── @@ -1115,6 +1144,39 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: }) return projection.model_copy(update={"settings": new_settings}) + case "yield_started": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + raw_suggestions = payload.get("suggestions", []) + suggestions = [ + Suggestion( + id=s.get("id", ""), + label=s.get("label", ""), + command=s.get("command", ""), + ) + for s in raw_suggestions + ] + # Append YieldEntry to the agent's conversation stream + new_conv = _flush_conversation(agent.conversation) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, YieldEntry(suggestions=suggestions)], + }) + # Set run-level active_yield so the UI can pin pills above the input + new_run = _update_agent_conversation(projection.run, agent_id, new_conv) + new_run = new_run.model_copy(update={ + "active_yield": ActiveYield(suggestions=suggestions), + }) + return projection.model_copy(update={"run": new_run}) + + case "yield_cleared": + if projection.run is None: + return projection + new_run = projection.run.model_copy(update={"active_yield": None}) + return projection.model_copy(update={"run": new_run}) + case _: log.warning("fold: unknown event_type=%r", event_type) return projection From da469fb0589209667bc5ab1f680a5fa7f0cd26c3 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 21:36:39 +0700 Subject: [PATCH 351/412] feat: replace phase boundary with koan_yield tool and add done tombstone --- koan/phases/__init__.py | 21 +++-- koan/phases/format_step.py | 78 +++++++++-------- koan/web/mcp_endpoint.py | 166 +++++++++++++++++++++++++------------ 3 files changed, 172 insertions(+), 93 deletions(-) diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index 02b9d9d..51066f6 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -61,20 +61,25 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> "You work through phases in sequence: each phase has numbered steps. Call" " koan_complete_step to advance through steps.\n" "\n" - "When a phase ends, koan_complete_step returns the user's message and" - " suggested next phases with descriptions. At each phase boundary:\n" - "1. Briefly summarize what was accomplished and what artifacts were produced.\n" - "2. Present the suggested phases, explaining what each one does in plain" - " language (use the descriptions from the boundary response).\n" - "3. Ask the user what they would like to do next.\n" - "4. Only call koan_set_phase after the user has confirmed the direction.\n" + "When a phase ends, koan_complete_step tells you to summarize and yield.\n" + "Call koan_yield with a summary and structured suggestions for the user.\n" + "Each suggestion needs:\n" + "- id: phase name (e.g. \"plan-spec\") or \"done\"\n" + "- label: short action label (e.g. \"Write implementation plan\")\n" + "- command: task-specific sentence pre-filled in the chat input when clicked\n" + "Always include a \"done\" suggestion so the user can end the workflow.\n" + "\n" + "koan_yield blocks until the user sends a message and returns it to you.\n" + "Respond conversationally. Call koan_yield again to continue the conversation.\n" + "When the user confirms a direction, call koan_set_phase with the phase name.\n" + "When the user is done, call koan_set_phase with \"done\".\n" "\n" "At the start of each phase, koan_complete_step returns your role context for" " that phase alongside the first step's instructions.\n" "\n" "Rules:\n" "- Only call koan_set_phase after the user has confirmed the direction.\n" - "- When the user indicates they are done, or all phases are complete, exit gracefully.\n" + "- Use koan_yield for all user interaction at phase boundaries.\n" "- Available tools change depending on the current phase." ) diff --git a/koan/phases/format_step.py b/koan/phases/format_step.py index 9465163..147e352 100644 --- a/koan/phases/format_step.py +++ b/koan/phases/format_step.py @@ -1,4 +1,11 @@ -# Step prompt assembly -- formats StepGuidance into the string returned to the LLM. +# Step prompt assembly -- formats StepGuidance into strings returned to the LLM. +# +# format_step() -- normal step guidance with WHEN DONE footer +# format_phase_complete() -- non-blocking response when a phase ends; instructs +# the orchestrator to summarize and call koan_yield +# format_user_messages() -- formats buffered user messages for inclusion in +# koan_yield's tool result +# format_steering_messages() -- formats steering queue for inline delivery from __future__ import annotations @@ -56,52 +63,55 @@ def format_steering_messages(messages: list[Any]) -> str: ) -def format_phase_boundary( +def format_phase_complete( phase: str, - messages: list[Any], - suggested: list[str], - phase_descriptions: dict[str, str] | None = None, + suggested_phases: list[str], + descriptions: dict[str, str] | None = None, ) -> str: - """Format a phase-boundary response with user messages and suggested next phases. + """Non-blocking response when a phase completes. - If suggested is empty (stub workflow), renders a graceful end-of-workflow message - instead of an empty phases section. + Tells the orchestrator to summarize its work and call koan_yield with + structured suggestions. Does not block — koan_yield handles blocking. + + Args: + phase: The phase that just completed (e.g. "intake"). + suggested_phases: Ordered list of suggested next phase IDs from the workflow. + descriptions: Phase descriptions from the workflow definition. """ title = f"Phase Complete: {phase}" lines = [title, "=" * len(title), ""] - if messages: - lines.append("## User Message(s)") - lines.append("") - for msg in messages: - ts = datetime.fromtimestamp(msg.timestamp_ms / 1000, tz=timezone.utc) - ts_str = ts.strftime("%H:%M:%S UTC") - lines.append(f"**[{ts_str}]** {msg.content}") - lines.append("") + lines.append("Summarize what was accomplished in this phase.") + lines.append("") - if suggested: - descs = phase_descriptions or {} - lines.append("## Suggested Next Phases") + descs = descriptions or {} + + if suggested_phases: + lines.append("Then call `koan_yield` with suggestions for the user.") + lines.append("Available phases:") lines.append("") - for s in suggested: - desc = descs.get(s, "") + for p in suggested_phases: + desc = descs.get(p, "") if desc: - lines.append(f"- **{s}** \u2014 {desc}") + lines.append(f"- **{p}** — {desc}") else: - lines.append(f"- **{s}**") + lines.append(f"- **{p}**") lines.append("") - lines.append("## Instructions") + lines.append("For each suggestion, provide:") + lines.append("- id: the phase name (e.g. \"plan-spec\")") + lines.append("- label: a short action label (e.g. \"Write implementation plan\")") + lines.append("- command: a task-specific sentence capturing what would be done") + lines.append(" (e.g. \"write dashboard redesign implementation plan\")") lines.append("") - lines.append("Briefly summarize what was accomplished in this phase. Present the") - lines.append("suggested phases above to the user, explaining what each one does.") - lines.append("Ask which direction they would like to go. The user can also request") - lines.append("any other phase available in this workflow.") - lines.append("Once confirmed, call `koan_set_phase` then `koan_complete_step`.") + lines.append("Always include a suggestion with id \"done\", label \"End workflow\",") + lines.append("and a brief farewell command summarising what was accomplished.") else: - lines.append("## Workflow Stub") - lines.append("") - lines.append("This workflow does not have further phases implemented yet.") - lines.append("Summarize what was accomplished in intake and let the user know") - lines.append("the workflow will end here for now.") + lines.append("This workflow has no further phases. Call `koan_yield` with a single") + lines.append("suggestion: id \"done\", label \"End workflow\", command describing") + lines.append("what was accomplished. Let the user know the workflow ends here.") + + lines.append("") + lines.append("WHEN DONE: Call koan_yield with your suggestions.") + lines.append("Do NOT call koan_set_phase yet — wait for the user's response.") return "\n".join(lines) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index ae91781..c06c274 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -3,9 +3,22 @@ # Exposes build_mcp_asgi_app() which returns an ASGI sub-app that: # 1. Validates agent_id from query params before reaching fastmcp. # 2. Runs check_permission() on every tool call. -# 3. Implements koan_complete_step, koan_request_scouts, +# 3. Implements koan_complete_step, koan_yield, koan_request_scouts, # koan_ask_question, koan_set_phase, koan_request_executor, # and story management tools. +# +# Phase boundary flow: +# koan_complete_step (last step) → format_phase_complete (non-blocking) +# → orchestrator calls koan_yield(suggestions=[...]) +# → blocks on AppState.yield_future until POST /api/chat resolves it +# → orchestrator converses, then calls koan_set_phase(phase) or koan_set_phase("done") +# +# koan_yield is phase-agnostic — it works wherever the orchestrator needs to +# pause for user input, not only at phase boundaries. +# +# koan_set_phase("done") is a tombstone: sets AppState.workflow_done = True, +# emits workflow_completed, and causes the next koan_complete_step to return +# an exit signal so the orchestrator process terminates cleanly. from __future__ import annotations @@ -34,7 +47,7 @@ from ..lib.workflows import get_suggested_phases, is_valid_transition as wf_is_valid from ..logger import get_logger from ..phases import PHASE_GUIDANCE_MAP, PhaseContext, StepGuidance -from ..phases.format_step import format_phase_boundary, format_steering_messages, format_step +from ..phases.format_step import format_phase_complete, format_steering_messages, format_step, format_user_messages from .interactions import activate_next_interaction, enqueue_interaction if TYPE_CHECKING: @@ -269,53 +282,6 @@ async def _step_within_phase( return result -async def _step_phase_boundary( - agent: AgentState, - phase_module: object, - ctx: PhaseContext, -) -> str: - """Handle phase boundary: flush conversation, block for user message, return boundary response.""" - assert _app_state is not None - from ..state import drain_steering_messages, drain_user_messages - - # Flush pending text/thinking in the projection - from ..events import build_step_advanced - _app_state.projection_store.push_event( - "agent_step_advanced", - build_step_advanced(agent.step, "", total_steps=phase_module.TOTAL_STEPS), - agent_id=agent.agent_id, - ) - - # Scan for new artifacts so they appear before the user is asked to respond - from ..driver import _push_artifact_diff - _push_artifact_diff(_app_state) - - # Let the frontend know we're waiting for user input at phase boundary - _app_state.projection_store.push_event( - "phase_boundary_reached", - {"phase": _app_state.phase, "message": f"{_app_state.phase.replace('-', ' ').title()} is complete. Send a message to continue."}, - agent_id=agent.agent_id, - ) - - # Check for already-buffered messages - messages = drain_user_messages(_app_state) + drain_steering_messages(_app_state) - - if not messages: - # No messages yet — create Future and block until POST /api/chat resolves it - loop = asyncio.get_running_loop() - future = loop.create_future() - _app_state.phase_complete_future = future - - await future # yields to event loop; POST /api/chat will set_result(True) - - _app_state.phase_complete_future = None - messages = drain_user_messages(_app_state) - - # Use workflow's suggested transitions and phase descriptions - workflow = _app_state.workflow - suggested = get_suggested_phases(workflow, _app_state.phase) if workflow else [] - descs = workflow.phase_descriptions if workflow else {} - return format_phase_boundary(_app_state.phase, messages, suggested, descs) # -- koan_complete_step ------------------------------------------------------- @@ -331,6 +297,11 @@ async def koan_complete_step(thoughts: str = "") -> str: try: agent.handshake_observed = True + # workflow_done tombstone — orchestrator called koan_set_phase("done") earlier + if _app_state is not None and _app_state.workflow_done: + result_str = "All phases complete. You may now exit." + return result_str + # Step 0: phase handshake (initial call or post-koan_set_phase) if agent.step == 0: result_str = await _step_phase_handshake(agent) @@ -356,8 +327,19 @@ async def koan_complete_step(thoughts: str = "") -> str: # Non-primary agents (scouts) are done — signal completion result_str = "All steps complete. You may now exit." return result_str - # Phase boundary — block for user input - result_str = await _step_phase_boundary(agent, phase_module, ctx) + # Phase complete — flush conversation and return non-blocking instructions + from ..events import build_step_advanced + _app_state.projection_store.push_event( + "agent_step_advanced", + build_step_advanced(agent.step, "", total_steps=phase_module.TOTAL_STEPS), + agent_id=agent.agent_id, + ) + from ..driver import _push_artifact_diff + _push_artifact_diff(_app_state) + workflow = _app_state.workflow + suggested = get_suggested_phases(workflow, _app_state.phase) if workflow else [] + descs = workflow.phase_descriptions if workflow else {} + result_str = format_phase_complete(_app_state.phase, suggested, descs) result_str = _drain_and_append_steering(result_str, agent) return result_str @@ -370,6 +352,73 @@ async def koan_complete_step(thoughts: str = "") -> str: end_tool_call(agent, call_id, "koan_complete_step", result_str) +# -- koan_yield --------------------------------------------------------------- + +@mcp.tool(name="koan_yield") +async def koan_yield( + summary: str = "", + suggestions: list[dict] | None = None, +) -> str: + """Yield to the user for open-ended conversation. + + Blocks until the user sends a message. The message is returned as + the tool result. Call this in a loop for multi-turn conversation. + + Optionally provide suggestions — the UI renders them as clickable + pills that pre-fill the chat input. The user still has to press Send. + + Each dict in suggestions should have: + - id (str): machine key (e.g. "plan-spec", "done") + - label (str): display text shown on the pill (e.g. "Write implementation plan") + - command (str): text pre-filled in chat input when the pill is clicked + + Args: + summary: Brief context about what the agent is waiting for (unused by + the driver; passed for logging/tooling purposes). + suggestions: Clickable options shown in the UI above the chat input. + """ + agent = _get_agent() + _check_or_raise(agent, "koan_yield", {"summary": summary, "suggestions": suggestions}) + + call_id = begin_tool_call( + agent, "koan_yield", {"summary": summary}, + f"{len(suggestions or [])} suggestion(s)", + ) + result_str: str | None = None + try: + assert _app_state is not None + from ..state import drain_user_messages, drain_steering_messages + + # Emit yield_started — renders YieldEntry in the conversation stream and + # sets run.active_yield so the UI pins pills above the chat input. + from ..events import build_yield_started + _app_state.projection_store.push_event( + "yield_started", + build_yield_started(suggestions or []), + agent_id=agent.agent_id, + ) + + # Check for already-buffered messages (user typed before we yielded) + messages = drain_user_messages(_app_state) + drain_steering_messages(_app_state) + + if not messages: + loop = asyncio.get_running_loop() + future = loop.create_future() + _app_state.yield_future = future + + await future # yields to event loop; POST /api/chat resolves it + + _app_state.yield_future = None + messages = drain_user_messages(_app_state) + + result_str = format_user_messages(messages) if messages else "No message received." + result_str = _drain_and_append_steering(result_str, agent) + return result_str + finally: + end_tool_call(agent, call_id, "koan_yield", result_str) + + + # -- koan_set_phase ----------------------------------------------------------- @mcp.tool(name="koan_set_phase") @@ -400,6 +449,19 @@ async def koan_set_phase(phase: str) -> str: current = _app_state.phase workflow = _app_state.workflow + # "done" tombstone — cleanly ends the workflow without a phase transition + if phase == "done": + _app_state.workflow_done = True + _app_state.projection_store.push_event("yield_cleared", {}) + _app_state.projection_store.push_event("workflow_completed", { + "success": True, + "phase": current, + "summary": f"Workflow completed from phase '{current}'", + }) + result_str = "Workflow complete. Call koan_complete_step to finish." + result_str = _drain_and_append_steering(result_str, agent) + return result_str + # Validate transition using workflow membership check if workflow is None or not wf_is_valid(workflow, current, phase): phases = list(workflow.available_phases) if workflow else [] @@ -434,6 +496,8 @@ async def koan_set_phase(phase: str) -> str: {"phase": phase}, agent_id=agent.agent_id, ) + # Clear any active yield now that a phase transition is committed + _app_state.projection_store.push_event("yield_cleared", {}) # Emit a step-advanced event (step=0) as visual phase-transition marker in the feed phase_label = phase.replace("-", " ").title() From 73c004ef26d95cd345c74c20e159d0e2472263b5 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 21:36:50 +0700 Subject: [PATCH 352/412] feat: add YieldCard molecule and wire frontend yield support --- frontend/src/App.tsx | 11 +++++ .../components/molecules/FeedbackInput.tsx | 22 +++++++++- .../src/components/molecules/YieldCard.css | 36 +++++++++++++++ .../src/components/molecules/YieldCard.tsx | 44 +++++++++++++++++++ frontend/src/store/index.ts | 13 +++++- 5 files changed, 123 insertions(+), 3 deletions(-) create mode 100644 frontend/src/components/molecules/YieldCard.css create mode 100644 frontend/src/components/molecules/YieldCard.tsx diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 0d9fa75..feda534 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -10,6 +10,7 @@ * debug_step_guidance → StepGuidancePill + Md * user_message → UserBubble + Md * phase_boundary → PhaseBoundary + * yield → YieldCard * pendingThinking → ThinkingBlock (always expanded) * pendingText → ProseCard + Md + streaming cursor */ @@ -35,6 +36,7 @@ import { StepGuidancePill } from './components/molecules/StepGuidancePill' import { FeedbackInput } from './components/molecules/FeedbackInput' import { UserBubble } from './components/molecules/UserBubble' import { PhaseBoundary } from './components/molecules/PhaseBoundary' +import { YieldCard } from './components/molecules/YieldCard' import { StepHeader } from './components/molecules/StepHeader' import { CompletionBanner } from './components/molecules/CompletionBanner' import { SteeringBar } from './components/molecules/SteeringBar' @@ -147,6 +149,8 @@ function renderEntry(entry: ConversationEntry, i: number) { } case 'phase_boundary': return <PhaseBoundary key={i} label={entry.message} /> + case 'yield': + return <YieldCard key={i} suggestions={entry.suggestions} /> default: return null } @@ -157,6 +161,12 @@ function ConnectedSteeringBar() { return <SteeringBar messages={steering.map(m => m.content)} /> } +function ActiveYieldPills() { + const activeYield = useStore(s => s.run?.activeYield) + if (!activeYield?.suggestions?.length) return null + return <YieldCard suggestions={activeYield.suggestions} /> +} + function ContentStream() { const focusAgentId = useStore(s => s.run?.focus?.agentId) const conversation = useStore(s => focusAgentId ? s.run?.agents?.[focusAgentId]?.conversation : undefined) @@ -193,6 +203,7 @@ function ContentStream() { {showFeedback && ( <> <ConnectedSteeringBar /> + <ActiveYieldPills /> <FeedbackInput onSend={msg => api.sendChatMessage(msg)} disabled={!!run?.completion} /> </> )} diff --git a/frontend/src/components/molecules/FeedbackInput.tsx b/frontend/src/components/molecules/FeedbackInput.tsx index 6ae3c59..fb69f0e 100644 --- a/frontend/src/components/molecules/FeedbackInput.tsx +++ b/frontend/src/components/molecules/FeedbackInput.tsx @@ -4,10 +4,16 @@ * Sits at the bottom of the content stream. Enter sends, Shift+Enter * inserts a newline. Uses the Button atom for the send action. * - * Used in: activity feed footer, phase-boundary prompts. + * Watches the chatDraft store field: when a YieldCard pill is clicked, + * it sets chatDraft to the suggestion command, which FeedbackInput picks + * up via useEffect, populates the textarea, and focuses it. The user + * reviews and presses Send — no auto-submit. + * + * Used in: content stream footer. */ -import { useState, useRef, type KeyboardEvent } from 'react' +import { useState, useRef, useEffect, type KeyboardEvent } from 'react' +import { useStore } from '../../store/index' import { Button } from '../atoms/Button' import './FeedbackInput.css' @@ -25,6 +31,18 @@ export function FeedbackInput({ const [text, setText] = useState('') const ref = useRef<HTMLTextAreaElement>(null) + const chatDraft = useStore(s => s.chatDraft) + const setChatDraft = useStore(s => s.setChatDraft) + + // Pick up draft set by YieldCard pill clicks + useEffect(() => { + if (chatDraft) { + setText(chatDraft) + setChatDraft('') // consume the draft immediately + ref.current?.focus() + } + }, [chatDraft, setChatDraft]) + const send = () => { const trimmed = text.trim() if (!trimmed || disabled) return diff --git a/frontend/src/components/molecules/YieldCard.css b/frontend/src/components/molecules/YieldCard.css new file mode 100644 index 0000000..71662e5 --- /dev/null +++ b/frontend/src/components/molecules/YieldCard.css @@ -0,0 +1,36 @@ +/* YieldCard — suggestion pills at a koan_yield point. */ + +.yc { + padding: 12px 0 4px; +} + +.yc-pills { + display: flex; + flex-wrap: wrap; + gap: 8px; +} + +.yc-pill { + font-family: var(--font-body); + font-size: var(--type-breadcrumb); + font-weight: 500; + color: var(--color-teal); + background: transparent; + border: 1.5px solid var(--color-teal); + border-radius: var(--radius-xl); + padding: 5px 14px; + cursor: pointer; + transition: + background var(--duration-fast) var(--ease-default), + color var(--duration-fast) var(--ease-default); + white-space: nowrap; +} + +.yc-pill:hover { + background: var(--color-teal); + color: var(--text-on-dark); +} + +.yc-pill:active { + opacity: 0.8; +} diff --git a/frontend/src/components/molecules/YieldCard.tsx b/frontend/src/components/molecules/YieldCard.tsx new file mode 100644 index 0000000..98816e1 --- /dev/null +++ b/frontend/src/components/molecules/YieldCard.tsx @@ -0,0 +1,44 @@ +/** + * YieldCard — suggestion pills rendered at a koan_yield point. + * + * Appears in the content stream as a historical record of the yield, and + * also pinned above FeedbackInput via ActiveYieldPills when the yield is active. + * + * Clicking a pill pre-fills the FeedbackInput textarea via the chatDraft store + * field. The user reviews the pre-filled text and presses Send — no auto-submit. + * + * Used in: content stream (yield entry), pinned above FeedbackInput. + */ + +import { useStore } from '../../store/index' +import type { Suggestion } from '../../store/index' +import './YieldCard.css' + +interface YieldCardProps { + suggestions: Suggestion[] +} + +export function YieldCard({ suggestions }: YieldCardProps) { + const setChatDraft = useStore(s => s.setChatDraft) + + if (!suggestions.length) return null + + return ( + <div className="yc"> + <div className="yc-pills"> + {suggestions.map(s => ( + <button + key={s.id} + className="yc-pill" + onClick={() => setChatDraft(s.command || s.label)} + title={s.command || s.label} + > + {s.label} + </button> + ))} + </div> + </div> + ) +} + +export default YieldCard diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 2819651..249d2eb 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -47,11 +47,15 @@ export interface ToolGenericEntry extends BaseToolEntry { type: 'tool_generic'; export interface DebugStepGuidanceEntry { type: 'debug_step_guidance'; content: string } export interface PhaseBoundaryEntry { type: 'phase_boundary'; phase: string; message: string } +export interface Suggestion { id: string; label: string; command: string } +export interface YieldEntry { type: 'yield'; suggestions: Suggestion[] } +export interface ActiveYield { suggestions: Suggestion[] } + export type ConversationEntry = | ThinkingEntry | TextEntry | StepEntry | UserMessageEntry | ToolReadEntry | ToolWriteEntry | ToolEditEntry | ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry - | DebugStepGuidanceEntry | PhaseBoundaryEntry + | DebugStepGuidanceEntry | PhaseBoundaryEntry | YieldEntry export interface Conversation { entries: ConversationEntry[] @@ -133,6 +137,7 @@ export interface Run { artifacts: Record<string, ArtifactInfo> completion: CompletionInfo | null steering: SteeringMessage[] + activeYield: ActiveYield | null } // -- Store -------------------------------------------------------------------- @@ -150,9 +155,13 @@ interface KoanState { // Local UI state (not from server) settingsOpen: boolean + // Local draft for chat input — set by YieldCard pill clicks + chatDraft: string + // Actions setConnected: (v: boolean) => void setSettingsOpen: (v: boolean) => void + setChatDraft: (text: string) => void } export const useStore = create<KoanState>((set) => ({ @@ -169,9 +178,11 @@ export const useStore = create<KoanState>((set) => ({ notifications: [], settingsOpen: false, + chatDraft: '', setConnected: (v) => set({ connected: v }), setSettingsOpen: (v) => set({ settingsOpen: v }), + setChatDraft: (text) => set({ chatDraft: text }), })) export type KoanStore = typeof useStore From 11f7e95ec7262a4ff84ae79908689b7b4fe79cb8 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 21:37:22 +0700 Subject: [PATCH 353/412] docs: add frontend component development guidelines --- frontend/AGENTS.md | 78 ++++++++++++++++++ frontend/src/components/AGENTS.md | 128 ++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+) create mode 100644 frontend/AGENTS.md create mode 100644 frontend/src/components/AGENTS.md diff --git a/frontend/AGENTS.md b/frontend/AGENTS.md new file mode 100644 index 0000000..0635616 --- /dev/null +++ b/frontend/AGENTS.md @@ -0,0 +1,78 @@ +# Frontend + +React + TypeScript SPA with a token-driven design system. Visual identity +is controlled by the user — agents implement it, they do not define it. + +## Protected Files + +These files require explicit user approval before any modification: + +| File | Role | Why protected | +|------|------|---------------| +| `src/styles/variables.css` | All CSS design tokens | Tokens define the visual identity. Adding, renaming, or removing tokens changes the design language. | +| `docs/design-system.md` | Visual specification | The authoritative spec for every component's appearance. Changes here propagate to all components. | + +If a task requires changing either file, describe the proposed change and +ask for approval. Do not apply it silently. + +## Design System + +The UI uses a token-driven design system documented in +[docs/design-system.md](../docs/design-system.md). + +- **Tokens** are CSS custom properties defined in `src/styles/variables.css` +- **Components** reference tokens via `var(--token-name)` — never raw hex, + px, or font-family values in component CSS +- If a value has no token, hardcode it in the component CSS with a comment + explaining what it is and where it comes from, then tell the user so they + can decide whether to promote it to a token + +## Component Architecture + +Components follow an atom → molecule → organism hierarchy in +`src/components/`: + +| Tier | Directory | What it contains | Store access | +|------|-----------|------------------|--------------| +| Atoms | `atoms/` | Single visual elements (dots, badges, buttons) | Never | +| Molecules | `molecules/` | Compositions of atoms or elements (cards, rows, inputs) | Never | +| Organisms | `organisms/` | Page sections composing molecules (header bar, sidebar, forms) | Allowed | + +**Read [src/components/AGENTS.md](src/components/AGENTS.md) when building, +modifying, or reviewing any UI component.** It contains the development +rules, CSS conventions, and verification checklist. + +## Data Layer + +These directories are the data layer. Do not modify them during visual work. + +| Directory | Contains | +|-----------|----------| +| `src/store/` | Zustand store, state types, selectors | +| `src/sse/` | SSE connection, JSON Patch application | +| `src/api/` | Typed fetch wrappers | +| `src/hooks/` | useElapsed, useAutoScroll | + +The store mirrors the backend projection via SSE. Components subscribe to +store slices and pass data to organisms/molecules as props. + +## CSS Files + +| File | Status | Rule | +|------|--------|------| +| `src/styles/variables.css` | Active — all tokens | **Protected** (see above) | +| `src/styles/app-shell.css` | Active — page frame layout | May modify for layout changes | +| `src/styles/markdown.css` | Active — rendered markdown | May modify carefully | +| `src/styles/components.css` | Legacy — only SettingsOverlay | Do not add new rules | +| `src/styles/layout.css` | Legacy — only SettingsOverlay | Do not add new rules | +| Component `.css` files | Active — colocated per component | All new styles go here | + +## When to Ask the User + +- Before modifying `variables.css` or `docs/design-system.md` +- When unsure whether a visual element should be an atom, molecule, or + organism +- When a value needs to be used across multiple components (potential + token promotion) +- When an existing component's visual spec doesn't match the design + system document diff --git a/frontend/src/components/AGENTS.md b/frontend/src/components/AGENTS.md new file mode 100644 index 0000000..5c97578 --- /dev/null +++ b/frontend/src/components/AGENTS.md @@ -0,0 +1,128 @@ +# Component Development Rules + +Read this file when building, modifying, or reviewing UI components. + +## Hierarchy + +**Atoms** (`atoms/`): The foundation. Pure visual primitives. +- No imports from other atoms, molecules, or organisms +- No store access, no API calls, no side effects +- Props control all behavior — fully presentational +- Examples: StatusDot, Badge, Button, SectionLabel, LogoMark + +**Molecules** (`molecules/`): Composed from atoms or plain elements. +- May import atoms — never other molecules or organisms +- No store access — controlled entirely via props +- Each molecule handles one visual concept +- Examples: ToolCallRow, ProseCard, ThinkingBlock, RadioOption + +**Organisms** (`organisms/`): Page-level sections. +- Compose molecules and atoms into layout regions +- May access the store directly (NewRunForm does) or receive props + from a `Connected*` wrapper in App.tsx +- Examples: HeaderBar, ScoutBar, ElicitationPanel, NewRunForm + +**Deciding the tier:** +1. Single styled element with no children? → **Atom** +2. Composes atoms into a self-contained visual unit? → **Molecule** +3. Composes molecules into a page section with layout? → **Organism** +4. Uncertain? Start as a molecule. Promote later if needed. + +## CSS Conventions + +Every component gets a colocated `.css` file (e.g., `ProseCard.css`). + +**Token discipline:** +- All colors, fonts, sizes, spacing, and radii reference tokens via + `var(--token-name)` +- Never use raw hex values, pixel sizes, or font-family strings in + component CSS +- One-off decorative values (SVG stroke colors, icon fills) may be + hardcoded with a comment explaining origin: + `/* lavender dot — from thinking palette */` +- After hardcoding, flag it in your response so the user can decide + whether it warrants a token + +**The promotion rule:** +- Value used by ONE component → hardcode in that component's CSS with + a descriptive comment +- Value used by MULTIPLE components, or clearly about to be → flag it + for token promotion. Do not add the token yourself. +- `variables.css` is protected — modification requires user approval + +**Class naming:** Prefix CSS class names with a short component +abbreviation to avoid collisions: `.tcr-` (ToolCallRow), `.hb-` +(HeaderBar), `.ep-` (ElicitationPanel). + +## Building a New Component + +1. **Create** `ComponentName.tsx` + `ComponentName.css` in the correct + tier directory +2. **Write** the component with TypeScript props, JSDoc comment + describing purpose and usage +3. **Style** using tokens from `variables.css` — check available tokens + before hardcoding anything +4. **Export** as both named and default export +5. **Integrate** into the parent component + +### Review Harness Protocol + +For visual verification of new components: + +1. Create `ReviewComponentName.tsx` in the same directory +2. In App.tsx, add a temporary import and route: + ```tsx + import { ReviewX } from './components/molecules/ReviewX' + const reviewParam = new URLSearchParams(window.location.search).get('review') + // then in the render: if (reviewParam === 'x') return <ReviewX /> + ``` +3. View at `http://localhost:5173/?review=x` +4. After approval, delete the review harness and remove the App.tsx changes +5. Commit the component only — never the harness + +## Content Stream Event Mapping + +Every conversation event type renders through a molecule. No inline CSS +class renderings for event types. + +| Event type | Molecule | +|---|---| +| `thinking` | ThinkingBlock + Md | +| `text` | ProseCard + Md | +| `tool_read/write/edit/bash/grep/ls` | ToolCallRow | +| `tool_generic` | ToolCallRow | +| `step` | StepHeader | +| `debug_step_guidance` | StepGuidancePill + Md | +| `user_message` | UserBubble + Md | +| `phase_boundary` | PhaseBoundary | +| pending thinking | ThinkingBlock (always expanded) | +| pending text | ProseCard + Md + streaming cursor | +| steering messages | SteeringBar | + +When encountering a new event type with no molecule: render as ProseCard +with raw content and flag it for a dedicated molecule. + +## Verification Checklist + +Before considering component work done: + +- [ ] TypeScript compiles with zero errors (`npx tsc --noEmit`) +- [ ] All CSS values reference tokens — no raw hex or px (except + flagged one-off decoratives) +- [ ] No references to old/deleted token names remain (grep the + codebase) +- [ ] Component is in the correct tier directory +- [ ] CSS class names use the component's namespace prefix +- [ ] `docs/design-system.md` has a spec for this component (or + you've flagged that it needs one) +- [ ] Review harness is deleted before committing + +## Do Not Modify + +During component work, do not touch: + +- `src/store/`, `src/sse/`, `src/api/`, `src/hooks/` — data layer +- `src/styles/variables.css` — requires user approval +- `src/styles/components.css`, `src/styles/layout.css` — legacy files, + do not add new rules +- Existing atoms — they are the foundation; changes require approval From 8232b7f46f98ce6c99a538461204c9d40bb11ca4 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 21:37:35 +0700 Subject: [PATCH 354/412] docs: update frontend.md for atomic design system and new component hierarchy --- docs/frontend.md | 65 ++++++++++++++++++++++++++++++------------------ 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/docs/frontend.md b/docs/frontend.md index 4cc6748..c75de73 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -10,7 +10,8 @@ files — no Node.js in production. ## Directory Layout ``` -frontend/ # source tree (alongside koan/ Python package) +frontend/ +├── AGENTS.md # frontend-specific agent rules (read first) ├── package.json ├── tsconfig.json ├── vite.config.ts # proxies /api/*, /events, /mcp/* to Python in dev @@ -18,6 +19,7 @@ frontend/ # source tree (alongside koan/ Python package) ├── src/ │ ├── main.tsx # mounts <App /> into #root; imports global CSS │ ├── App.tsx # top-level layout; owns SSE connection lifecycle +│ ├── utils.ts # formatTokens, formatSize, normalizeOptions │ ├── store/ │ │ ├── index.ts # single Zustand store (the app-db equivalent) │ │ └── selectors.ts # derived state computed from store slices @@ -25,14 +27,23 @@ frontend/ # source tree (alongside koan/ Python package) │ │ └── connect.ts # EventSource wrapper: always-snapshot catch-up + JSON Patch │ ├── api/ │ │ └── client.ts # typed fetch wrappers for POST/PUT endpoints -│ ├── components/ # one file per UI component (see Component Mapping) +│ ├── components/ +│ │ ├── AGENTS.md # component development rules (read when building components) +│ │ ├── atoms/ # StatusDot, Badge, Button, SectionLabel, LogoMark, ProgressSegment +│ │ ├── molecules/ # ProseCard, ThinkingBlock, ToolCallRow, FeedbackInput, etc. +│ │ ├── organisms/ # HeaderBar, ScoutBar, ArtifactsSidebar, ElicitationPanel, NewRunForm +│ │ ├── Md.tsx # shared markdown renderer (ReactMarkdown + remark-gfm) +│ │ ├── Notification.tsx # toast notification system +│ │ └── SettingsOverlay.tsx # settings modal (not yet redesigned) │ ├── hooks/ │ │ ├── useElapsed.ts # elapsed time hook for agent start times -│ │ └── useAutoScroll.ts +│ │ └── useAutoScroll.ts # sticky-scroll for content stream │ └── styles/ -│ ├── variables.css # CSS custom properties -│ ├── layout.css -│ └── components.css # components.css + animations.css merged +│ ├── variables.css # design tokens (PROTECTED — see frontend/AGENTS.md) +│ ├── app-shell.css # page frame layout (.app-root, .workflow-grid) +│ ├── markdown.css # rendered markdown content styling +│ ├── layout.css # legacy — SettingsOverlay only +│ └── components.css # legacy — SettingsOverlay only └── dist/ # Vite build output (gitignored) koan/web/static/app/ # Vite build target (committed build artifacts) @@ -181,24 +192,30 @@ form state and cascade dropdown logic. --- -## Component Mapping - -| React component | Primary store subscription | -|---|---| -| `App.tsx` | `run` | -| `LandingPage.tsx` | `run` (negated) | -| `StatusSidebar.tsx` | `run.agents`, `run.phase` | -| `AgentMonitor.tsx` | `run.agents` | -| `ArtifactsSidebar.tsx` | `run.artifacts` | -| `AskWizard.tsx` | `run.focus` | -| `WorkflowDecision.tsx` | `run.focus` | -| `ArtifactReview.tsx` | `run.focus` | -| `Completion.tsx` | `run.completion` | -| `SettingsOverlay.tsx` | `settingsOpen` + local state | -| `Notification.tsx` | `notifications` | - -Scouts are agents where `isPrimary === false`. `AgentMonitor` filters -`run.agents` by this flag — there is no separate `scouts` slice. +## Component Architecture + +Components follow an atom → molecule → organism hierarchy. See +[frontend/src/components/AGENTS.md](../frontend/src/components/AGENTS.md) +for development rules. + +**Organisms and their store subscriptions:** + +| Organism | Store subscription | Wiring | +|---|---|---| +| `HeaderBar` | `run.phase`, `run.agents` (primary) | `useHeaderData()` hook in App.tsx | +| `NewRunForm` | `settings.profiles`, `settings.installations` | Reads store directly | +| `ElicitationPanel` | `run.focus` (questions) | `ElicitationView` in App.tsx | +| `ArtifactsSidebar` | `run.artifacts` | `ConnectedSidebar` in App.tsx | +| `ScoutBar` | `run.agents` (non-primary) | `ConnectedScoutBar` in App.tsx | +| `SettingsOverlay` | `settingsOpen` + local state | Direct store access | + +**Content stream rendering** maps each conversation event type to a molecule. +The full mapping is documented in +[docs/design-system.md](./design-system.md#content-stream-rendering) and in +[frontend/src/components/AGENTS.md](../frontend/src/components/AGENTS.md). + +Scouts are agents where `isPrimary === false`. App.tsx filters `run.agents` +by this flag — there is no separate `scouts` slice. --- From 8d7868352fa92f2f095586bb25a08a83ad911c1b Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Mon, 6 Apr 2026 21:37:45 +0700 Subject: [PATCH 355/412] docs: document koan_yield conversation primitive and done tombstone --- AGENTS.md | 39 ++++++++++--- docs/architecture.md | 107 +++++++++++++++++++++++++++-------- docs/ipc.md | 131 +++++++++++++++++++++++++++---------------- docs/projections.md | 52 ++++++++++++++--- docs/state.md | 5 +- docs/subagents.md | 3 +- 6 files changed, 245 insertions(+), 92 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a5171a9..15d7e8c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,10 +2,29 @@ Full architecture documentation: **[docs/architecture.md](docs/architecture.md)** +## Frontend Design System (read before any frontend work) + +The frontend uses a strict token-driven component system. Visual identity +is user-controlled — agents implement it but do not change it without +approval. Violations compound: a misplaced color becomes a wrong token +becomes an inconsistent component becomes a broken design language. + +**When touching any file under `frontend/`**, read +**[frontend/AGENTS.md](frontend/AGENTS.md)** first. It defines protected +files, the component hierarchy (atoms → molecules → organisms), and CSS +conventions. + +**When building or modifying a UI component**, also read +**[frontend/src/components/AGENTS.md](frontend/src/components/AGENTS.md)**. +It contains the development rules, the tier decision tree, and the +verification checklist. + +--- + Spoke documents: - [docs/subagents.md](docs/subagents.md) -- spawn lifecycle, task manifest, step-first workflow, permissions -- [docs/ipc.md](docs/ipc.md) -- HTTP MCP tool calls, blocking interactions, scout spawning, phase-boundary blocking +- [docs/ipc.md](docs/ipc.md) -- HTTP MCP tool calls, blocking interactions, scout spawning, koan_yield blocking - [docs/state.md](docs/state.md) -- driver/LLM boundary, run state, orchestrator state - [docs/intake-loop.md](docs/intake-loop.md) -- three-step intake design, prompt engineering - [docs/projections.md](docs/projections.md) -- versioned event log, fold function, projection shape, SSE protocol, version-negotiated catch-up @@ -44,12 +63,15 @@ Tool returns: Step 1 instructions (phase role context + task details) Tool returns: Step 2 instructions (or phase-boundary response) ``` -When a phase ends, `koan_complete_step` blocks for a user message and returns -the transition context (user message + suggested next phases). The orchestrator -converses, then calls `koan_set_phase` to commit the transition. The step -counter resets to 0 on each `koan_set_phase` call, then advances to 1 on the -next `koan_complete_step`. Phase-specific role context (`SYSTEM_PROMPT`) is -injected into that step-1 response. +When a phase ends, `koan_complete_step` returns a **non-blocking** response +telling the orchestrator to summarize and call `koan_yield`. `koan_yield` is +the generic conversation primitive — it blocks until the user sends a message, +then returns that message as the tool result. The orchestrator calls `koan_yield` +repeatedly for multi-turn conversation, then calls `koan_set_phase` to commit +the transition. Passing `koan_set_phase("done")` ends the workflow (tombstone). +The step counter resets to 0 on each `koan_set_phase` call, then advances to 1 +on the next `koan_complete_step`. Phase-specific role context (`SYSTEM_PROMPT`) +is injected into that step-1 response. Step progression is normally linear within a phase, but phase modules may override `get_next_step()` to implement non-linear flows. See @@ -94,7 +116,8 @@ during brief-generation step 1 (the read step). | Tool | Available phases | |------|-----------------| | `koan_complete_step` | All phases | -| `koan_set_phase` | All phases (blocked mid-story during execution) | +| `koan_set_phase` | All phases (blocked mid-story during execution); accepts `"done"` as tombstone | +| `koan_yield` | All phases | | `koan_ask_question` | All phases | | `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `plan-spec`, `plan-review` | | `koan_request_executor` | `execution`, `execute` | diff --git a/docs/architecture.md b/docs/architecture.md index cbd6f2a..dab5c98 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -9,7 +9,7 @@ principles, and pitfalls that govern the codebase. - [Subagents](./subagents.md) -- spawn lifecycle, boot protocol, step-first workflow, phase dispatch, permissions, model tiers - [IPC](./ipc.md) -- HTTP MCP inter-process communication, blocking tool calls, - scout spawning, phase-boundary blocking, chat message delivery + scout spawning, koan_yield blocking, chat message delivery - [Token Streaming](./token-streaming.md) -- runner stdout parsing, SSE delta path - [State & Driver](./state.md) -- the driver/LLM boundary, JSON vs markdown ownership, run state, orchestrator state @@ -62,7 +62,7 @@ Boot prompt: "You are a koan {role} agent. Call koan_complete_step to receive y Tool returns: Step 1 instructions (rich context, task details, guidance) | LLM does work... | LLM calls koan_complete_step -Tool returns: Step 2 instructions (or "Phase complete.") +Tool returns: Step 2 instructions (or "Phase complete. Call koan_yield.") ``` Three reinforcement mechanisms make this robust across model capability levels: @@ -73,6 +73,54 @@ Three reinforcement mechanisms make this robust across model capability levels: | **Recency** | `format_step()` appends "WHEN DONE: Call koan_complete_step..." last | LLMs weight end-of-context instructions heavily | | **Muscle memory** | By step 2+ the LLM has called the tool N times | Pattern is locked in through repetition | +#### Phase boundaries and koan_yield + +When a phase's final step completes, `koan_complete_step` returns a **non-blocking** +response (`format_phase_complete`) that tells the orchestrator to summarize its +work and call `koan_yield`. The orchestrator then generates a summary and calls +`koan_yield` with structured suggestions. + +`koan_yield` is the **generic conversation primitive** — it blocks the +orchestrator process until the user sends a message, then returns that message +as the tool result. The orchestrator can call `koan_yield` repeatedly for +multi-turn conversation before committing a phase transition. + +``` +koan_complete_step (last step) + -> returns: "Phase complete. Summarize and call koan_yield." + | LLM writes summary, constructs suggestions + | LLM calls koan_yield(suggestions=[{id, label, command}, ...]) +Tool blocks until user sends message + | user types in chat or clicks a suggestion pill +Tool returns: user message text + | LLM responds conversationally + | LLM calls koan_yield again (or calls koan_set_phase if direction confirmed) +... + | LLM calls koan_set_phase("plan-spec") -- or "done" to end the workflow +``` + +`koan_yield` is phase-agnostic — it knows nothing about workflow structure. +Suggestions are constructed by the orchestrator at each yield point; the UI +renders them as clickable pills that pre-fill the chat input. + +#### Ending the workflow + +Passing `"done"` to `koan_set_phase` acts as a tombstone: + +``` +koan_set_phase("done") + -> emits workflow_completed + -> sets AppState.workflow_done = True + -> returns "Workflow complete. Call koan_complete_step to finish." + | LLM calls koan_complete_step +Tool returns: "All phases complete. You may now exit." + | LLM exits (no more tool calls) +``` + +`"done"` is detected before the normal `is_valid_transition()` check and is +not a member of any workflow's `available_phases`. The driver treats the +orchestrator's process exit as the actual workflow end signal. + ### 3. Driver determinism (partially relaxed) The driver (`koan/driver.py`) spawns the orchestrator and awaits its exit. @@ -85,10 +133,10 @@ through typed tool parameters. `is_valid_transition(workflow, from_phase, to_phase)` validates that `to_phase` is a member of the active workflow's `available_phases` and is not equal to -`from_phase`. Any phase in the workflow is reachable from any other — suggested -transitions guide the orchestrator's default recommendations at phase boundaries, -but the user can request any available phase. Invalid phase strings raise -`ToolError`. +`from_phase`. The special value `"done"` bypasses this check entirely. Any +real phase in the workflow is reachable from any other — suggested transitions +guide the orchestrator's default recommendations at phase boundaries, but the +user can request any available phase. Invalid phase strings raise `ToolError`. ### 4. Default-deny permissions @@ -194,13 +242,13 @@ and suggested transitions between phases. Two workflows are defined in | Phase | Role | Steps | Artifact | |-------|------|-------|---------| -| `intake` | Requirement gathering | 3 (Gather → Deepen → Write) | `landscape.md` | +| `intake` | Requirement gathering | 3 (Gather → Deepen → Summarize) | Chat summary only | | `plan-spec` | Technical planning | 2 (Analyze → Write) | `plan.md` | | `plan-review` | Quality review | 2 (Read → Evaluate) | Chat report only | | `execute` | Implementation handoff | 2 (Compose → Request) | Code changes via executor | -**milestones** — stub workflow; runs intake only, then reports the workflow is -not yet fully implemented. +**milestones** — stub workflow; runs intake only, then yields with a single +"done" suggestion. ### Workflow selection @@ -220,9 +268,11 @@ def is_valid_transition(workflow: Workflow, from_phase: str, to_phase: str) -> b ) ``` -At phase boundaries, `format_phase_boundary` renders the suggested next phases -from `workflow.suggested_transitions[current_phase]`. These are recommendations, -not constraints — the user can request any phase in `workflow.available_phases`. +The special value `"done"` bypasses this function — it is handled before the +validation call in `koan_set_phase`. For real phases, suggested transitions +from `workflow.suggested_transitions[current_phase]` guide the orchestrator's +default `koan_yield` suggestions. These are recommendations, not constraints — +the user can request any phase in `workflow.available_phases`. --- @@ -311,21 +361,30 @@ State flows from LLM tool calls to the browser through the projection system. [Browser receives patch, applies applyPatch(store, patch) — no interpretation] ``` -### Concrete example: `koan_complete_step` +### Concrete example: `koan_yield` ``` -LLM calls koan_complete_step({ thoughts: "..." }) via MCP +LLM calls koan_yield({ suggestions: [{id:"plan-spec", label:"Write plan", command:"..."}] }) -> MCP endpoint checks permissions - -> emits step_advance audit event (audit fold) - -> audit fold: projection.step = 2, projection.step_name = "Decompose" - -> write_state(audit projection) -> state.json - -> push_event("agent_step_advanced", {step: 2, step_name: "Decompose"}, agent_id="abc") - -> ProjectionStore: append to log, fold projection, compute JSON Patch diff - -> patch: [{op: "replace", path: "/run/agents/abc/step", value: 2}, ...] - -> broadcast patch dict to all SSE subscribers - -> browser receives: event: patch / data: {"version": 47, "patch": [...]} - -> applyPatch(store, patch) — store.run.agents.abc.step is now 2 - -> returns step 2 instructions as MCP tool result + -> push_event("yield_started", {suggestions: [...]}, agent_id="abc") + -> fold: appends YieldEntry to agent conversation, sets run.active_yield + -> patch: [{op:"add", path:"/run/agents/abc/conversation/entries/-", value:{type:"yield",...}}, + {op:"replace", path:"/run/activeYield", value:{suggestions:[...]}}] + -> broadcast patch to SSE subscribers + -> browser renders suggestion pills in activity feed and above chat input + -> tool handler creates asyncio.Future, stores in app_state.yield_future, awaits it + -> (HTTP connection held open) + +user clicks suggestion pill "Write plan" in the browser + -> YieldCard.onClick -> setChatDraft("write dashboard redesign implementation plan") + -> FeedbackInput useEffect fires -> textarea pre-filled + -> user reviews, presses Enter + -> POST /api/chat { message: "write dashboard redesign implementation plan" } + -> api_chat: yield_future is set -> append to user_message_buffer -> set_result(True) + -> yield_future resolves + -> drain_user_messages -> "write dashboard redesign implementation plan" + -> returns message text as MCP tool result +LLM receives user's message, responds, calls koan_set_phase("plan-spec") ``` ### Snapshot on reconnect diff --git a/docs/ipc.md b/docs/ipc.md index 158edd9..91227ca 100644 --- a/docs/ipc.md +++ b/docs/ipc.md @@ -21,11 +21,11 @@ registry and handles the call directly. Three interactions involve blocking -- the HTTP request is held open while the driver awaits an external response: -| Mechanism | What blocks | Who responds | -| ----------------------- | ---------------------------- | ------------------------------ | -| `koan_ask_question` | User input needed | User via web UI | -| `koan_request_scouts` | Scout subagents running | Driver (after scouts complete) | -| Phase-boundary blocking | Phase complete, next unknown | User via `POST /api/chat` | +| Mechanism | What blocks | Who responds | +| ----------------------- | ---------------------------------- | ------------------------------ | +| `koan_ask_question` | User input needed | User via web UI | +| `koan_request_scouts` | Scout subagents running | Driver (after scouts complete) | +| `koan_yield` | Phase complete, awaiting direction | User via `POST /api/chat` | User-facing tool calls (`koan_ask_question`) go through the `PendingInteraction` queue on `AppState`. The MCP handler creates an `asyncio.Future`, stores it in @@ -40,8 +40,8 @@ HTTP connection is held open only by the `await asyncio.gather(...)` call. `koan_request_executor` spawns a single executor subagent and blocks until it exits. Like scouts, it is handled inline with no `PendingInteraction`. -Phase-boundary blocking uses `AppState.phase_complete_future` directly (not -`PendingInteraction`). See [Phase-Boundary Blocking](#phase-boundary-blocking). +`koan_yield` uses `AppState.yield_future` directly (not `PendingInteraction`). +See [koan_yield Blocking](#koan_yield-blocking). There is no polling and no intermediate files for any of these flows. @@ -207,83 +207,116 @@ orchestrator calls koan_request_executor({ artifacts: [...], instructions: "..." ``` The orchestrator reports the result to the user in chat and then calls -`koan_complete_step` to trigger the execute phase boundary. +`koan_yield` to present follow-up options. --- -## Phase-Boundary Blocking +## koan_yield Blocking -When the orchestrator finishes a phase (`get_next_step` returns `None`), -`koan_complete_step` blocks for user input before returning the phase-boundary -response. This uses `AppState.phase_complete_future` directly, not the -`PendingInteraction` queue. +`koan_yield` is the generic conversation primitive — the orchestrator calls it +whenever it needs to yield control to the user for open-ended chat. It uses +`AppState.yield_future` directly, not the `PendingInteraction` queue. ``` -orchestrator calls koan_complete_step (last step of a phase) - -> get_next_step() returns None +orchestrator calls koan_yield({ suggestions: [...] }) + -> push_event("yield_started", {suggestions: [...]}) + -> fold: appends YieldEntry to conversation, sets run.active_yield + -> browser renders suggestion pills -> drain_user_messages(app_state) -> if buffer empty: future = asyncio.get_running_loop().create_future() - app_state.phase_complete_future = future + app_state.yield_future = future await future # HTTP connection held open - app_state.phase_complete_future = None + app_state.yield_future = None -> messages = drain_user_messages(app_state) - -> suggested = get_suggested_phases(workflow, app_state.phase) - -> descs = workflow.phase_descriptions - -> returns format_phase_boundary(phase, messages, suggested, descs) + -> returns format_user_messages(messages) ``` The Future is resolved when the user sends a message via `POST /api/chat`. -`format_phase_boundary` renders the suggested phases (from -`workflow.suggested_transitions[current_phase]`) with descriptions and -instructs the orchestrator to present them to the user. The user can also -request any other phase in the workflow's `available_phases`. If the -workflow has no suggested transitions for the current phase (milestones stub), -`format_phase_boundary` renders a "workflow not yet fully implemented" message. +**Multi-turn conversation:** The orchestrator calls `koan_yield` repeatedly +for as long as the user wants to chat. Each call blocks, waits for one message, +returns it. No new `yield_started` event is emitted on subsequent calls unless +the orchestrator provides updated suggestions; the `active_yield` pills remain +visible. -**Key asyncio invariant:** `api_chat` and `koan_complete_step` run in the same -asyncio event loop. `api_chat` appends to `user_message_buffer` before calling -`set_result()`. When `koan_complete_step` resumes, `drain_user_messages()` finds -the message in the buffer. No threads or locks are needed. +**If messages are already buffered** (user sent a message before the tool was +called): `koan_yield` drains them and returns immediately — no Future is +created. -**If messages are already buffered:** `koan_complete_step` drains them and -returns immediately — no Future is created. +**Key asyncio invariant:** `api_chat` and `koan_yield` run in the same asyncio +event loop. `api_chat` appends to `user_message_buffer` before calling +`set_result()`. When `koan_yield` resumes, `drain_user_messages()` finds the +message in the buffer. No threads or locks are needed. -After receiving the phase-boundary response, the orchestrator converses with the -user and calls `koan_set_phase` to commit the transition. +**`yield_future` vs `PendingInteraction`:** `koan_yield` bypasses the +interaction queue because it is not a structured question with a UI form — it +is free-form chat. The PendingInteraction mechanism renders a specific UI widget +(`koan_ask_question`); `koan_yield` renders suggestion pills via the projection +(`yield_started` event). Both resolve via `asyncio.Future` but through +independent code paths. --- ## Chat Message Delivery -User messages are buffered in `AppState.user_message_buffer` and delivered -to the orchestrator at `koan_complete_step` call boundaries. +User messages are routed based on whether the orchestrator is waiting for them. ``` user types in chat input -> POST /api/chat { message: "..." } - -> ChatMessage appended to app_state.user_message_buffer - -> user_message projection event pushed (appears in activity feed) - -> if app_state.phase_complete_future is set: future.set_result(True) + -> ChatMessage created with content + timestamp_ms + -> push_event("user_message", ...) — appears in activity feed + -> if app_state.yield_future is set and not done: + user_message_buffer.append(msg) + yield_future.set_result(True) -- unblocks koan_yield + -> else: + steering_queue.append(msg) + push_event("steering_queued", ...) -- shown in SteeringBar above input -> returns { ok: true } - -orchestrator calls koan_complete_step (any step) - -> step guidance computed - -> messages = drain_user_messages(app_state) - -> if messages: appended to tool result as formatted block - -> returns combined guidance + user messages ``` -Messages sent while the orchestrator is mid-step accumulate in the buffer and -are delivered at the next `koan_complete_step` call. Messages sent during -`koan_ask_question` also buffer and deliver after the structured interaction -resolves. +**Phase-boundary messages** (sent while `koan_yield` is blocking): routed to +`user_message_buffer`, delivered as the koan_yield return value. + +**Steering messages** (sent while the orchestrator is mid-step): routed to +`steering_queue`, appended to the next tool response via +`_drain_and_append_steering()`. The LLM integrates them without abandoning +the current step. + +The two queues are drained independently to prevent double-delivery: +`drain_user_messages()` and `drain_steering_messages()` each clear their own +list atomically. --- ## Sequence Diagrams +### koan_yield flow (phase boundary) + +``` +Orchestrator Driver Web UI + | | | + |--koan_yield(suggestions)--->| | + | | push yield_started | + | |--SSE patch----------->| + | | (pills render) | + | | create yield_future | + | | await yield_future | + | | | user clicks pill + | | | setChatDraft(cmd) + | | | user presses Enter + | |<-POST /api/chat--------| + | | buffer + set_result | + |<-tool result (msg text)------| | + | (converses with user) | | + |--koan_set_phase("plan-spec")->| | + | | push yield_cleared | + | | push phase_started | + | |--SSE patches--------->| + |<-"Phase set to plan-spec."---| | +``` + ### Scout flow (inline blocking, no PendingInteraction) ``` diff --git a/docs/projections.md b/docs/projections.md index b181a78..a33f8c6 100644 --- a/docs/projections.md +++ b/docs/projections.md @@ -48,9 +48,9 @@ held in memory for the duration of a workflow run. --- -## Event Types (36 total) +## Event Types (38 total) -### Lifecycle (8) +### Lifecycle (10) | Event | Payload | `agent_id` | |-------|---------|-----------| @@ -63,6 +63,15 @@ held in memory for the duration of a workflow run. | `agent_exited` | `{exit_code, error?, usage?}` | set | | `workflow_completed` | `{success, summary?, error?}` | `None` | | `scout_queued` | `{scout_id, label, model?}` | `None` | +| `yield_started` | `{suggestions: [{id, label, command}, ...]}` | set (primary) | +| `yield_cleared` | `{}` | `None` | + +`yield_started` is emitted by `koan_yield` when the orchestrator yields to the +user for conversation. The fold appends a `YieldEntry` to the agent's +conversation and sets `run.active_yield`. `yield_cleared` removes +`run.active_yield`; it is emitted by `koan_set_phase` (any transition, +including `"done"`) and implicitly by `phase_started` and +`workflow_completed`. `run_started` is emitted by `api_start_run` before the driver begins. It creates the `Run` object in the projection with the frozen `RunConfig`. @@ -206,7 +215,7 @@ Projection │ ├── phase: str │ ├── agents: dict[str, Agent] # agent_id → Agent (all statuses) │ │ └── conversation: Conversation -│ │ ├── entries: list[ConversationEntry] # discriminated union of 10 types +│ │ ├── entries: list[ConversationEntry] # discriminated union of 11 types │ │ ├── pending_thinking: str │ │ ├── pending_text: str │ │ ├── is_thinking: bool @@ -214,7 +223,9 @@ Projection │ │ └── output_tokens: int │ ├── focus: Focus | None # discriminated union of 2 variants │ ├── artifacts: dict[str, ArtifactInfo] # path → ArtifactInfo -│ └── completion: CompletionInfo | None +│ ├── completion: CompletionInfo | None +│ ├── steering: list[SteeringMessage] # pending user feedback shown above chat +│ └── active_yield: ActiveYield | None # non-None while koan_yield is blocking └── notifications: list[Notification] ``` @@ -371,14 +382,24 @@ class UserMessageEntry(KoanBaseModel): timestamp_ms: int +class YieldEntry(KoanBaseModel): + type: Literal["yield"] = "yield" + suggestions: list[Suggestion] = [] # structured options presented at this yield point + + ConversationEntry = Annotated[ ThinkingEntry | TextEntry | StepEntry | UserMessageEntry | ToolReadEntry | ToolWriteEntry | ToolEditEntry | - ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry, + ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry | + YieldEntry, Field(discriminator="type"), ] ``` +`YieldEntry` is appended to the conversation when the orchestrator calls +`koan_yield`. It records the suggestions the orchestrator offered at that +yield point, providing a historical record of what options were presented. + ### Focus — discriminated union `run.focus` determines what the main content area renders. Every variant @@ -408,6 +429,19 @@ explicit. ### Supporting types ```python +class Suggestion(KoanBaseModel): + id: str # machine key — phase name (e.g. "plan-spec") or "done" + label: str # display text shown in UI pill (e.g. "Write implementation plan") + command: str = "" # pre-filled into chat input when pill is clicked + +class ActiveYield(KoanBaseModel): + # Live view of the last yield point — non-None while koan_yield is blocking. + # Cleared by yield_cleared, phase_started, and workflow_completed. + suggestions: list[Suggestion] = [] + +class SteeringMessage(KoanBaseModel): + content: str # user feedback message queued during active agent work + class ArtifactInfo(KoanBaseModel): path: str # relative to run directory size: int # bytes @@ -462,6 +496,8 @@ Conversation: /run/agents/abc123/conversation/pendingThinking Focus: /run/focus Artifacts: /run/artifacts/docs~1architecture.md/size +Yield: /run/activeYield + /run/activeYield/suggestions ``` Named entities (installations, profiles, agents, artifacts) are dicts for @@ -521,8 +557,10 @@ completed agents. |-------|--------| | `run_started` | `projection.run = Run(config=RunConfig(...))` | | `workflow_selected` | `run.workflow = payload["workflow"]` | -| `phase_started` | `run.phase = phase` | -| `workflow_completed` | `run.completion = CompletionInfo(...)` | +| `phase_started` | `run.phase = phase`. Clear `run.active_yield = None`. | +| `workflow_completed` | `run.completion = CompletionInfo(...)`. Clear `run.active_yield = None`. | +| `yield_started` | Parse `suggestions` from payload → `Suggestion` list. Append `YieldEntry(suggestions=...)` to primary agent's conversation (flushing pending fields first). Set `run.active_yield = ActiveYield(suggestions=...)`. | +| `yield_cleared` | Set `run.active_yield = None`. | ### Settings diff --git a/docs/state.md b/docs/state.md index b201751..63caef5 100644 --- a/docs/state.md +++ b/docs/state.md @@ -206,8 +206,9 @@ Orchestrator state tracked in `AppState` (in-memory, not persisted): | Field | Type | Purpose | |-------|------|---------| | `workflow` | `Workflow \| None` | Active workflow; set at run start, drives transition validation and phase guidance | -| `user_message_buffer` | `list[ChatMessage]` | Buffered user chat messages, drained at each `koan_complete_step` | -| `phase_complete_future` | `asyncio.Future \| None` | Non-None while `koan_complete_step` is blocking at a phase boundary | +| `user_message_buffer` | `list[ChatMessage]` | Buffered user chat messages, drained when `koan_yield` unblocks | +| `yield_future` | `asyncio.Future \| None` | Non-None while `koan_yield` is blocking, waiting for a user message | +| `workflow_done` | `bool` | Set to `True` by `koan_set_phase("done")`; causes `koan_complete_step` to return exit signal | `ChatMessage` carries `content: str` and `timestamp_ms: int`. Messages are appended by `POST /api/chat` and removed atomically by `drain_user_messages()`. diff --git a/docs/subagents.md b/docs/subagents.md index 9bd4c68..6e0eada 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -171,8 +171,7 @@ koan_complete_step arrives via MCP: step == 0 -> step=1, prepend SYSTEM_PROMPT, return format_step(step_guidance(1)) [boot/phase transition] otherwise -> validate_step_completion(step) [pre-condition check] -> next_step = get_next_step(step) [pure: decides where to go] - next_step is None -> block for user message (asyncio.Future), then - return format_phase_boundary(phase, messages, suggested, descriptions) [phase boundary] + next_step is None -> return format_phase_complete(phase, suggested, descriptions) [non-blocking; orchestrator then calls koan_yield] next_step < prev -> on_loop_back(prev, next_step) [side effects of loop] next_step != None -> step=next_step, return format_step(step_guidance(next_step)) + any buffered user messages [advance] ``` From 3f46397768df40aef423eb3bb4f96d8ee44c8761 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 9 Apr 2026 17:42:10 +0700 Subject: [PATCH 356/412] feat: support multiple built-in runner profiles --- koan/config.py | 10 ++-- koan/runners/__init__.py | 3 +- koan/runners/registry.py | 110 +++++++++++++++++++++++++++------------ koan/state.py | 2 +- koan/subagent.py | 2 +- koan/types.py | 3 ++ koan/web/app.py | 50 +++++++++--------- tests/test_registry.py | 6 +-- tests/test_subagent.py | 2 +- tests/test_web_flows.py | 42 ++++++++------- 10 files changed, 138 insertions(+), 92 deletions(-) diff --git a/koan/config.py b/koan/config.py index 70c3704..2e7156b 100644 --- a/koan/config.py +++ b/koan/config.py @@ -9,7 +9,7 @@ from dataclasses import dataclass, field from pathlib import Path -from .types import AgentInstallation, Profile, ProfileTier +from .types import BUILTIN_PROFILE_NAMES, AgentInstallation, Profile, ProfileTier log = logging.getLogger("koan.config") @@ -131,8 +131,8 @@ async def load_koan_config() -> KoanConfig: if not isinstance(active_profile, str) or not active_profile: active_profile = "balanced" - # Exclude "balanced" from persisted profiles -- it is recomputed at startup - profiles = [p for p in _parse_profiles(parsed.get("profiles", [])) if p.name != "balanced"] + # Exclude built-in profiles from persisted profiles -- they are recomputed at startup + profiles = [p for p in _parse_profiles(parsed.get("profiles", [])) if p.name not in BUILTIN_PROFILE_NAMES] return KoanConfig( agent_installations=_parse_agent_installations(parsed.get("agentInstallations", [])), @@ -174,7 +174,7 @@ async def save_koan_config(config: KoanConfig) -> None: else: existing.pop("activeProfile", None) - # Serialize profiles (user-defined only; balanced never persisted) + # Serialize profiles (user-defined only; built-in profiles never persisted) existing["profiles"] = [ { "name": p.name, @@ -188,7 +188,7 @@ async def save_koan_config(config: KoanConfig) -> None: }, } for p in config.profiles - if p.name != "balanced" + if p.name not in BUILTIN_PROFILE_NAMES ] existing["scoutConcurrency"] = config.scout_concurrency diff --git a/koan/runners/__init__.py b/koan/runners/__init__.py index 2ff9da0..be94933 100644 --- a/koan/runners/__init__.py +++ b/koan/runners/__init__.py @@ -4,7 +4,7 @@ from .claude import ClaudeRunner from .codex import CodexRunner from .gemini import GeminiRunner -from .registry import RunnerRegistry, compute_balanced_profile +from .registry import RunnerRegistry, compute_balanced_profile, compute_builtin_profiles from .resolver import resolve_runner __all__ = [ @@ -17,5 +17,6 @@ "GeminiRunner", "RunnerRegistry", "compute_balanced_profile", + "compute_builtin_profiles", "resolve_runner", ] diff --git a/koan/runners/registry.py b/koan/runners/registry.py index d37ffc7..6c5ccb5 100644 --- a/koan/runners/registry.py +++ b/koan/runners/registry.py @@ -8,6 +8,7 @@ from ..probe import ProbeResult from ..types import ( + BUILTIN_PROFILE_NAMES, ROLE_MODEL_TIER, AgentInstallation, ModelInfo, @@ -38,14 +39,24 @@ _NEEDS_SUBAGENT_DIR = frozenset({"claude", "gemini"}) -# -- Balanced profile priority table ------------------------------------------- +# -- Built-in profile definitions ---------------------------------------------- +# Balanced: auto-fallback across available runners _TIER_PRIORITY: dict[ModelTier, list[tuple[str, str]]] = { - "strong": [("claude", "opus"), ("codex", "gpt-5"), ("gemini", "gemini-pro")], + "strong": [("claude", "sonnet"), ("codex", "gpt-5"), ("gemini", "gemini-pro")], "standard": [("claude", "sonnet"), ("codex", "gpt-5"), ("gemini", "gemini-pro")], "cheap": [("claude", "haiku"), ("codex", "gpt-5-mini"), ("gemini", "gemini-flash")], } +# Fixed built-in profiles: (runner_type, model) per tier, no fallback logic +_FIXED_PROFILE_SPECS: dict[str, dict[ModelTier, tuple[str, str]]] = { + "frontier": { + "strong": ("claude", "opus"), + "standard": ("claude", "sonnet"), + "cheap": ("claude", "haiku"), + }, +} + _TIER_DEFAULT_THINKING: dict[ModelTier, ThinkingMode] = { "strong": "high", "standard": "medium", @@ -144,11 +155,17 @@ def resolve_agent_config( self, role: SubagentRole, config: KoanConfig, - balanced_profile: Profile | None = None, + builtin_profiles: dict[str, Profile] | None = None, run_installations: dict[str, str] | None = None, + # DEPRECATED parameter -- ignored if builtin_profiles is provided + balanced_profile: Profile | None = None, ) -> tuple[AgentInstallation, str, ThinkingMode]: tier = ROLE_MODEL_TIER.get(role, "standard") + # Back-compat: wrap legacy balanced_profile into builtin_profiles dict + if builtin_profiles is None and balanced_profile is not None: + builtin_profiles = {"balanced": balanced_profile} + # Resolve active profile profile: Profile | None = None for p in config.profiles: @@ -156,8 +173,8 @@ def resolve_agent_config( profile = p break - if profile is None and config.active_profile == "balanced": - profile = balanced_profile + if profile is None and builtin_profiles: + profile = builtin_profiles.get(config.active_profile) if profile is None: raise RunnerError(RunnerDiagnostic( @@ -182,55 +199,80 @@ def resolve_agent_config( return installation, profile_tier.model, profile_tier.thinking -# -- Balanced profile computation ---------------------------------------------- +# -- Built-in profile computation ---------------------------------------------- -def compute_balanced_profile(probe_results: list[ProbeResult]) -> Profile: - available_runners = {pr.runner_type for pr in probe_results if pr.available} +def _resolve_thinking( + model_lookup: dict[tuple[str, str], ModelInfo], + runner_type: str, + model: str, + tier_name: ModelTier, +) -> ThinkingMode: + default_thinking = _TIER_DEFAULT_THINKING[tier_name] + info = model_lookup.get((runner_type, model)) + if info is not None and default_thinking not in info.thinking_modes: + return _best_supported_thinking(info.thinking_modes, default_thinking) + return default_thinking - # Build model lookup: (runner_type, alias) -> ModelInfo - model_lookup: dict[tuple[str, str], ModelInfo] = {} - for pr in probe_results: - if pr.available: - for m in pr.models: - model_lookup[(pr.runner_type, m.alias)] = m +def _compute_balanced( + available_runners: set[str], + model_lookup: dict[tuple[str, str], ModelInfo], +) -> Profile: tiers: dict[str, ProfileTier] = {} for tier_name in ("strong", "standard", "cheap"): priority = _TIER_PRIORITY[tier_name] - default_thinking = _TIER_DEFAULT_THINKING[tier_name] picked = False for runner_type, model in priority: if runner_type in available_runners: - # Resolve thinking: clamp to model capabilities when known - thinking = default_thinking - model_info = model_lookup.get((runner_type, model)) - if model_info is not None and thinking not in model_info.thinking_modes: - thinking = _best_supported_thinking( - model_info.thinking_modes, thinking, - ) + thinking = _resolve_thinking(model_lookup, runner_type, model, tier_name) tiers[tier_name] = ProfileTier( - runner_type=runner_type, - model=model, - thinking=thinking, + runner_type=runner_type, model=model, thinking=thinking, ) picked = True break if not picked and available_runners: - # Safe fallback: first available runner with its first priority-table model fallback_rt = next(iter(available_runners)) fallback_model = fallback_rt for rt, m in priority: if rt == fallback_rt: fallback_model = m break - thinking = default_thinking - fb_info = model_lookup.get((fallback_rt, fallback_model)) - if fb_info is not None and thinking not in fb_info.thinking_modes: - thinking = _best_supported_thinking(fb_info.thinking_modes, thinking) + thinking = _resolve_thinking(model_lookup, fallback_rt, fallback_model, tier_name) tiers[tier_name] = ProfileTier( - runner_type=fallback_rt, - model=fallback_model, - thinking=thinking, + runner_type=fallback_rt, model=fallback_model, thinking=thinking, ) - return Profile(name="balanced", tiers=tiers) + + +def _compute_fixed( + name: str, + spec: dict[ModelTier, tuple[str, str]], + model_lookup: dict[tuple[str, str], ModelInfo], +) -> Profile: + tiers: dict[str, ProfileTier] = {} + for tier_name, (runner_type, model) in spec.items(): + thinking = _resolve_thinking(model_lookup, runner_type, model, tier_name) + tiers[tier_name] = ProfileTier( + runner_type=runner_type, model=model, thinking=thinking, + ) + return Profile(name=name, tiers=tiers) + + +def compute_builtin_profiles(probe_results: list[ProbeResult]) -> dict[str, Profile]: + available_runners = {pr.runner_type for pr in probe_results if pr.available} + model_lookup: dict[tuple[str, str], ModelInfo] = {} + for pr in probe_results: + if pr.available: + for m in pr.models: + model_lookup[(pr.runner_type, m.alias)] = m + + profiles: dict[str, Profile] = {} + profiles["balanced"] = _compute_balanced(available_runners, model_lookup) + for name, spec in _FIXED_PROFILE_SPECS.items(): + profiles[name] = _compute_fixed(name, spec, model_lookup) + return profiles + + +def compute_balanced_profile(probe_results: list[ProbeResult]) -> Profile: + """DEPRECATED: use compute_builtin_profiles instead.""" + return compute_builtin_profiles(probe_results)["balanced"] diff --git a/koan/state.py b/koan/state.py index 2f2dee1..9358a03 100644 --- a/koan/state.py +++ b/koan/state.py @@ -69,7 +69,7 @@ class AppState: interaction_queue: deque[PendingInteraction] = field(default_factory=deque) interaction_queue_max: int = 8 config: KoanConfig = field(default_factory=KoanConfig) - balanced_profile: Profile | None = None + builtin_profiles: dict[str, Profile] = field(default_factory=dict) probe_results: list[ProbeResult] = field(default_factory=list) port: int = 8000 open_browser: bool = True diff --git a/koan/subagent.py b/koan/subagent.py index 15ce2d9..a1d5982 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -112,7 +112,7 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None registry = RunnerRegistry() installation, model_alias, thinking_mode = registry.resolve_agent_config( role, config, - balanced_profile=app_state.balanced_profile, + builtin_profiles=app_state.builtin_profiles, run_installations=app_state.run_installations, ) diff --git a/koan/types.py b/koan/types.py index 6707285..42c1089 100644 --- a/koan/types.py +++ b/koan/types.py @@ -70,6 +70,9 @@ class Profile: tiers: dict[ModelTier, ProfileTier] = field(default_factory=dict) +BUILTIN_PROFILE_NAMES: frozenset[str] = frozenset({"balanced", "frontier"}) + + @dataclass class AgentInstallation: alias: str diff --git a/koan/web/app.py b/koan/web/app.py index 2da06a0..72a65fd 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -172,9 +172,10 @@ def _sse_event(event_type: str, payload: Any) -> str: def _resolve_profile(st: AppState, name: str) -> Profile | None: - """Look up a profile by name, including the computed balanced profile.""" - if name == "balanced": - return st.balanced_profile + """Look up a profile by name, including built-in profiles.""" + builtin = st.builtin_profiles.get(name) + if builtin is not None: + return builtin for p in st.config.profiles: if p.name == name: return p @@ -498,10 +499,10 @@ def _serialize_profile(p: Profile, read_only: bool) -> dict: async def _refresh_probe_state(st: AppState, broadcast: bool = True) -> None: from ..probe import probe_all_runners - from ..runners.registry import compute_balanced_profile + from ..runners.registry import compute_builtin_profiles st.probe_results = await probe_all_runners() - st.balanced_profile = compute_balanced_profile(st.probe_results) + st.builtin_profiles = compute_builtin_profiles(st.probe_results) # --yolo: per-runner permission-skipping flags for default installations _YOLO_ARGS: dict[str, list[str]] = { @@ -567,11 +568,11 @@ async def _refresh_probe_state(st: AppState, broadcast: bool = True) -> None: for inst in st.config.agent_installations } st.projection_store.push_event("probe_completed", build_probe_completed(_probe_results_dict)) - if st.balanced_profile: - tiers = _serialize_profile(st.balanced_profile, True)["tiers"] + for bp in st.builtin_profiles.values(): + tiers = _serialize_profile(bp, True)["tiers"] st.projection_store.push_event( "profile_modified", - build_profile_modified("balanced", True, tiers), + build_profile_modified(bp.name, True, tiers), ) @@ -599,10 +600,10 @@ def _push_initial_config_events(st: AppState) -> None: } store.push_event("probe_completed", build_probe_completed(_probe_avail)) - # Profiles (balanced first, then user-defined) - if st.balanced_profile: - tiers = _serialize_profile(st.balanced_profile, True)["tiers"] - store.push_event("profile_created", build_profile_created("balanced", True, tiers)) + # Profiles (built-in first, then user-defined) + for bp in st.builtin_profiles.values(): + tiers = _serialize_profile(bp, True)["tiers"] + store.push_event("profile_created", build_profile_created(bp.name, True, tiers)) for p in st.config.profiles: sp = _serialize_profile(p, False) store.push_event("profile_created", build_profile_created(p.name, False, sp["tiers"])) @@ -619,15 +620,14 @@ async def api_probe(r: Request) -> Response: if r.query_params.get("refresh", "") in ("1", "true"): await _refresh_probe_state(st) runners = [_serialize_probe_result(pr) for pr in st.probe_results] - balanced = _serialize_profile(st.balanced_profile, True) if st.balanced_profile else None - return JSONResponse({"runners": runners, "balanced_profile": balanced}) + balanced = st.builtin_profiles.get("balanced") + balanced_json = _serialize_profile(balanced, True) if balanced else None + return JSONResponse({"runners": runners, "balanced_profile": balanced_json}) async def api_profiles_list(r: Request) -> Response: st = _app_state(r) - profiles = [] - if st.balanced_profile: - profiles.append(_serialize_profile(st.balanced_profile, True)) + profiles = [_serialize_profile(bp, True) for bp in st.builtin_profiles.values()] for p in st.config.profiles: profiles.append(_serialize_profile(p, False)) return JSONResponse({"profiles": profiles}) @@ -643,9 +643,9 @@ async def api_profiles_create(r: Request) -> Response: {"error": "validation_error", "message": "name is required"}, status_code=422, ) - if name == "balanced": + if name in _app_state(r).builtin_profiles: return JSONResponse( - {"error": "validation_error", "message": "cannot use reserved name 'balanced'"}, + {"error": "validation_error", "message": f"cannot use reserved name '{name}'"}, status_code=422, ) if any(p.name == name for p in _app_state(r).config.profiles): @@ -686,9 +686,9 @@ async def api_profiles_create(r: Request) -> Response: async def api_profiles_update(r: Request) -> Response: name = r.path_params["name"] - if name == "balanced": + if name in _app_state(r).builtin_profiles: return JSONResponse( - {"error": "read_only", "message": "balanced profile cannot be edited"}, + {"error": "read_only", "message": f"built-in profile '{name}' cannot be edited"}, status_code=422, ) @@ -730,9 +730,9 @@ async def api_profiles_update(r: Request) -> Response: async def api_profiles_delete(r: Request) -> Response: name = r.path_params["name"] - if name == "balanced": + if name in _app_state(r).builtin_profiles: return JSONResponse( - {"error": "read_only", "message": "balanced profile cannot be deleted"}, + {"error": "read_only", "message": f"built-in profile '{name}' cannot be deleted"}, status_code=400, ) @@ -885,9 +885,7 @@ async def api_agents_detect(r: Request) -> Response: async def api_settings_body(r: Request) -> Response: st = _app_state(r) - profiles = [] - if st.balanced_profile: - profiles.append(_serialize_profile(st.balanced_profile, True)) + profiles = [_serialize_profile(bp, True) for bp in st.builtin_profiles.values()] for p in st.config.profiles: profiles.append(_serialize_profile(p, False)) diff --git a/tests/test_registry.py b/tests/test_registry.py index 104fca2..dfde838 100644 --- a/tests/test_registry.py +++ b/tests/test_registry.py @@ -65,7 +65,7 @@ def test_all_available_with_models(self): p = compute_balanced_profile(probes) assert p.name == "balanced" assert p.tiers["strong"].runner_type == "claude" - assert p.tiers["strong"].model == "opus" + assert p.tiers["strong"].model == "sonnet" assert p.tiers["strong"].thinking == "high" assert p.tiers["standard"].runner_type == "claude" assert p.tiers["standard"].model == "sonnet" @@ -93,7 +93,7 @@ def test_only_claude_available(self): ] p = compute_balanced_profile(probes) assert p.tiers["strong"].runner_type == "claude" - assert p.tiers["strong"].model == "opus" + assert p.tiers["strong"].model == "sonnet" assert p.tiers["strong"].thinking == "high" # claude/opus supports high assert p.tiers["standard"].runner_type == "claude" assert p.tiers["standard"].model == "sonnet" @@ -127,7 +127,7 @@ def test_claude_preferred_for_strong(self): ] p = compute_balanced_profile(probes) assert p.tiers["strong"].runner_type == "claude" - assert p.tiers["strong"].model == "opus" + assert p.tiers["strong"].model == "sonnet" def test_claude_preferred_for_standard(self): probes = [ diff --git a/tests/test_subagent.py b/tests/test_subagent.py index 1d0658a..0b2fedd 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -29,7 +29,7 @@ class FakeConfig: class FakeAppState: agents: dict = field(default_factory=dict) config: FakeConfig = field(default_factory=FakeConfig) - balanced_profile: Any = None + builtin_profiles: dict = field(default_factory=dict) port: int = 9999 active_interaction: Any = None interaction_queue: Any = field(default_factory=lambda: __import__("collections").deque()) diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index b5651a2..e0484e7 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -128,9 +128,9 @@ def test_start_run_persists_profile(client, app_state): # -- Start-run preflight ------------------------------------------------------- def test_preflight_returns_required_types(client, app_state): - from koan.runners.registry import compute_balanced_profile + from koan.runners.registry import compute_builtin_profiles app_state.probe_results = _make_probe_results() - app_state.balanced_profile = compute_balanced_profile(app_state.probe_results) + app_state.builtin_profiles = compute_builtin_profiles(app_state.probe_results) resp = client.get("/api/start-run/preflight?profile=balanced") assert resp.status_code == 200 data = resp.json() @@ -139,9 +139,9 @@ def test_preflight_returns_required_types(client, app_state): def test_preflight_shows_binary_validity(client, app_state, tmp_path): - from koan.runners.registry import compute_balanced_profile + from koan.runners.registry import compute_builtin_profiles app_state.probe_results = _make_probe_results() - app_state.balanced_profile = compute_balanced_profile(app_state.probe_results) + app_state.builtin_profiles = compute_builtin_profiles(app_state.probe_results) real_binary = tmp_path / "claude" real_binary.touch() app_state.config.agent_installations = [ @@ -165,9 +165,9 @@ def test_preflight_missing_profile(client, app_state): # -- Start-run installation validation ----------------------------------------- def test_start_run_accepts_installation_selection(client, app_state, tmp_path): - from koan.runners.registry import compute_balanced_profile + from koan.runners.registry import compute_builtin_profiles app_state.probe_results = _make_probe_results() - app_state.balanced_profile = compute_balanced_profile(app_state.probe_results) + app_state.builtin_profiles = compute_builtin_profiles(app_state.probe_results) binary = tmp_path / "claude" binary.touch() app_state.config.agent_installations = [ @@ -183,9 +183,9 @@ def test_start_run_accepts_installation_selection(client, app_state, tmp_path): def test_start_run_rejects_missing_binary(client, app_state): - from koan.runners.registry import compute_balanced_profile + from koan.runners.registry import compute_builtin_profiles app_state.probe_results = _make_probe_results() - app_state.balanced_profile = compute_balanced_profile(app_state.probe_results) + app_state.builtin_profiles = compute_builtin_profiles(app_state.probe_results) app_state.config.agent_installations = [ AgentInstallation(alias="broken", runner_type="claude", binary="/nonexistent/claude"), ] @@ -258,9 +258,9 @@ def test_path_traversal_blocked(client, app_state): def test_probe_endpoint(client, app_state): app_state.probe_results = _make_probe_results() - app_state.balanced_profile = Profile(name="balanced", tiers={ + app_state.builtin_profiles = {"balanced": Profile(name="balanced", tiers={ "strong": ProfileTier(runner_type="claude", model="opus", thinking="high"), - }) + })} resp = client.get("/api/probe") assert resp.status_code == 200 @@ -275,9 +275,9 @@ def test_probe_endpoint(client, app_state): # -- Profile endpoints -------------------------------------------------------- def test_profiles_list_includes_balanced(client, app_state): - app_state.balanced_profile = Profile(name="balanced", tiers={ + app_state.builtin_profiles = {"balanced": Profile(name="balanced", tiers={ "strong": ProfileTier(runner_type="claude", model="opus", thinking="high"), - }) + })} resp = client.get("/api/profiles") assert resp.status_code == 200 @@ -470,9 +470,9 @@ def test_landing_includes_profile_selector(client, app_state): # After SPA migration, GET / serves the React SPA, not server-rendered HTML. # Profile selector is rendered client-side by React. app_state.probe_results = _make_probe_results() - app_state.balanced_profile = Profile(name="balanced", tiers={ + app_state.builtin_profiles = {"balanced": Profile(name="balanced", tiers={ "strong": ProfileTier(runner_type="claude", model="opus", thinking="high"), - }) + })} resp = client.get("/") assert resp.status_code == 200 @@ -490,7 +490,7 @@ def test_landing_start_run_disabled_no_runners(client, app_state): def test_landing_start_run_enabled_with_runners(client, app_state): # After SPA migration, GET / serves the SPA regardless of runner state. app_state.probe_results = _make_probe_results() - app_state.balanced_profile = Profile(name="balanced", tiers={}) + app_state.builtin_profiles = {"balanced": Profile(name="balanced", tiers={})} resp = client.get("/") assert resp.status_code == 200 @@ -558,25 +558,27 @@ def test_probe_refresh_triggers_restate(self, client, app_state): "strong": ProfileTier(runner_type="claude", model="opus", thinking="high"), }) + fresh_builtins = {"balanced": fresh_profile} + # Pre-populate with stale data app_state.probe_results = _make_probe_results() - app_state.balanced_profile = None + app_state.builtin_profiles = {} with patch("koan.probe.probe_all_runners", new_callable=AsyncMock, return_value=fresh_probes) as mock_probe, \ - patch("koan.runners.registry.compute_balanced_profile", return_value=fresh_profile) as mock_balanced: + patch("koan.runners.registry.compute_builtin_profiles", return_value=fresh_builtins) as mock_builtins: resp = client.get("/api/probe?refresh=1") assert resp.status_code == 200 mock_probe.assert_called_once() - mock_balanced.assert_called_once_with(fresh_probes) + mock_builtins.assert_called_once_with(fresh_probes) assert app_state.probe_results is fresh_probes - assert app_state.balanced_profile is fresh_profile + assert app_state.builtin_profiles is fresh_builtins data = resp.json() assert len(data["runners"]) == 2 def test_probe_no_refresh_skips_restate(self, client, app_state): app_state.probe_results = _make_probe_results() - app_state.balanced_profile = Profile(name="balanced", tiers={}) + app_state.builtin_profiles = {"balanced": Profile(name="balanced", tiers={})} with patch("koan.probe.probe_all_runners", new_callable=AsyncMock) as mock_probe: resp = client.get("/api/probe") From 6e88f5c8176b7a88b8e0b3e833c6212bcd0750ea Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 9 Apr 2026 17:42:17 +0700 Subject: [PATCH 357/412] fix: relax intake scout dispatch mandate --- koan/phases/intake.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/koan/phases/intake.py b/koan/phases/intake.py index 18b2ff2..cb098b1 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -144,8 +144,8 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: " can examine multiple files, trace dependencies, and answer several", " related questions in a single run.", "", - "You MUST dispatch at least 2 scouts. This is mandatory regardless of task size.", - "Read what you can reach directly AND scout everything else.", + "You can use both. Read what you can reach directly; scout what you can't.", + "The workflow context above (if present) tells you which posture to default to.", "", "If dispatching scouts, each needs:", "- id: short kebab-case identifier (e.g., 'auth-and-permissions', 'data-layer')", From 11f45f4967a25129c4285ba29bba7ecd89cb11de Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 9 Apr 2026 17:42:37 +0700 Subject: [PATCH 358/412] feat: redesign settings and yield command UX --- frontend/src/App.tsx | 241 +++++++++++-- frontend/src/components/AGENTS.md | 3 +- frontend/src/components/atoms/Badge.css | 8 + frontend/src/components/atoms/Badge.tsx | 7 +- frontend/src/components/atoms/Button.css | 35 ++ frontend/src/components/atoms/Button.tsx | 11 +- frontend/src/components/atoms/NumberInput.css | 23 ++ frontend/src/components/atoms/NumberInput.tsx | 75 ++++ frontend/src/components/atoms/Select.css | 38 ++ frontend/src/components/atoms/Select.tsx | 59 +++ frontend/src/components/atoms/TextInput.css | 65 ++++ frontend/src/components/atoms/TextInput.tsx | 59 +++ frontend/src/components/atoms/Toggle.css | 46 +++ frontend/src/components/atoms/Toggle.tsx | 34 ++ .../components/molecules/CommandPalette.css | 97 +++++ .../components/molecules/CommandPalette.tsx | 68 ++++ .../src/components/molecules/EntityRow.css | 37 ++ .../src/components/molecules/EntityRow.tsx | 43 +++ .../components/molecules/FeedbackInput.css | 6 + .../components/molecules/FeedbackInput.tsx | 130 ++++++- frontend/src/components/molecules/FormRow.css | 27 ++ frontend/src/components/molecules/FormRow.tsx | 28 ++ .../src/components/molecules/InlineForm.css | 13 + .../src/components/molecules/InlineForm.tsx | 43 +++ frontend/src/components/molecules/NavItem.css | 26 ++ frontend/src/components/molecules/NavItem.tsx | 28 ++ .../components/molecules/PhaseBoundary.css | 21 -- .../components/molecules/PhaseBoundary.tsx | 22 -- .../src/components/molecules/PhaseMarker.css | 71 ++++ .../src/components/molecules/PhaseMarker.tsx | 33 ++ .../src/components/molecules/SettingRow.css | 33 ++ .../src/components/molecules/SettingRow.tsx | 37 ++ frontend/src/components/molecules/TabBar.css | 29 ++ frontend/src/components/molecules/TabBar.tsx | 41 +++ .../src/components/molecules/YieldCard.css | 36 -- .../src/components/molecules/YieldCard.tsx | 44 --- .../src/components/molecules/YieldPanel.css | 82 +++++ .../src/components/molecules/YieldPanel.tsx | 48 +++ .../src/components/organisms/HeaderBar.css | 28 ++ .../src/components/organisms/HeaderBar.tsx | 89 +++-- .../src/components/organisms/SettingsPage.css | 40 ++ .../src/components/organisms/SettingsPage.tsx | 341 ++++++++++++++++++ frontend/src/store/index.ts | 12 +- frontend/src/styles/app-shell.css | 7 + frontend/src/styles/variables.css | 14 + 45 files changed, 2072 insertions(+), 206 deletions(-) create mode 100644 frontend/src/components/atoms/NumberInput.css create mode 100644 frontend/src/components/atoms/NumberInput.tsx create mode 100644 frontend/src/components/atoms/Select.css create mode 100644 frontend/src/components/atoms/Select.tsx create mode 100644 frontend/src/components/atoms/TextInput.css create mode 100644 frontend/src/components/atoms/TextInput.tsx create mode 100644 frontend/src/components/atoms/Toggle.css create mode 100644 frontend/src/components/atoms/Toggle.tsx create mode 100644 frontend/src/components/molecules/CommandPalette.css create mode 100644 frontend/src/components/molecules/CommandPalette.tsx create mode 100644 frontend/src/components/molecules/EntityRow.css create mode 100644 frontend/src/components/molecules/EntityRow.tsx create mode 100644 frontend/src/components/molecules/FormRow.css create mode 100644 frontend/src/components/molecules/FormRow.tsx create mode 100644 frontend/src/components/molecules/InlineForm.css create mode 100644 frontend/src/components/molecules/InlineForm.tsx create mode 100644 frontend/src/components/molecules/NavItem.css create mode 100644 frontend/src/components/molecules/NavItem.tsx delete mode 100644 frontend/src/components/molecules/PhaseBoundary.css delete mode 100644 frontend/src/components/molecules/PhaseBoundary.tsx create mode 100644 frontend/src/components/molecules/PhaseMarker.css create mode 100644 frontend/src/components/molecules/PhaseMarker.tsx create mode 100644 frontend/src/components/molecules/SettingRow.css create mode 100644 frontend/src/components/molecules/SettingRow.tsx create mode 100644 frontend/src/components/molecules/TabBar.css create mode 100644 frontend/src/components/molecules/TabBar.tsx delete mode 100644 frontend/src/components/molecules/YieldCard.css delete mode 100644 frontend/src/components/molecules/YieldCard.tsx create mode 100644 frontend/src/components/molecules/YieldPanel.css create mode 100644 frontend/src/components/molecules/YieldPanel.tsx create mode 100644 frontend/src/components/organisms/SettingsPage.css create mode 100644 frontend/src/components/organisms/SettingsPage.tsx diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index feda534..283a645 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -5,18 +5,20 @@ * text → ProseCard + Md * tool_read/write/edit → ToolCallRow * tool_bash/grep/ls → ToolCallRow - * tool_generic → ToolCallRow + * tool_generic → ToolCallRow (koan_* orchestration tools suppressed) * step → StepHeader * debug_step_guidance → StepGuidancePill + Md * user_message → UserBubble + Md - * phase_boundary → PhaseBoundary - * yield → YieldCard + * phase_boundary → PhaseMarker + * yield → YieldPanel * pendingThinking → ThinkingBlock (always expanded) * pendingText → ProseCard + Md + streaming cursor */ import { useEffect, useMemo, useRef, useState } from 'react' import { useStore, ConversationEntry, AskQuestion } from './store/index' +// DEBUG: expose store to window for browser-agent introspection +;(window as unknown as { __store: typeof useStore }).__store = useStore import { connectSSE } from './sse/connect' import { useElapsed, formatElapsed } from './hooks/useElapsed' import { useAutoScroll } from './hooks/useAutoScroll' @@ -35,15 +37,17 @@ import { ToolCallRow } from './components/molecules/ToolCallRow' import { StepGuidancePill } from './components/molecules/StepGuidancePill' import { FeedbackInput } from './components/molecules/FeedbackInput' import { UserBubble } from './components/molecules/UserBubble' -import { PhaseBoundary } from './components/molecules/PhaseBoundary' -import { YieldCard } from './components/molecules/YieldCard' +import { PhaseMarker } from './components/molecules/PhaseMarker' +import { YieldPanel } from './components/molecules/YieldPanel' import { StepHeader } from './components/molecules/StepHeader' import { CompletionBanner } from './components/molecules/CompletionBanner' import { SteeringBar } from './components/molecules/SteeringBar' import { Md } from './components/Md' import { Notification } from './components/Notification' -import { SettingsOverlay } from './components/SettingsOverlay' +// SettingsOverlay is no longer rendered — replaced by SettingsPage organism +// import { SettingsOverlay } from './components/SettingsOverlay' +import { SettingsPage, type Profile as SPProfile, type Installation as SPInstallation } from './components/organisms/SettingsPage' // --------------------------------------------------------------------------- // Header data @@ -119,6 +123,10 @@ function ConnectedScoutBar() { // Content stream // --------------------------------------------------------------------------- +// Orchestration tools whose effects are visible through other molecules +// (YieldPanel, StepHeader, PhaseMarker). They should not render as rows. +const SUPPRESSED_TOOLS = new Set(['koan_yield', 'koan_complete_step', 'koan_set_phase']) + function renderEntry(entry: ConversationEntry, i: number) { switch (entry.type) { case 'thinking': @@ -138,6 +146,7 @@ function renderEntry(entry: ConversationEntry, i: number) { case 'tool_ls': return <ToolCallRow key={i} tool="ls" command={entry.path} status={entry.inFlight ? 'running' : 'done'} /> case 'tool_generic': + if (SUPPRESSED_TOOLS.has(entry.toolName)) return null return <ToolCallRow key={i} tool={entry.toolName} command={entry.summary} status={entry.inFlight ? 'running' : 'done'} /> case 'step': return <StepHeader key={i} stepNumber={entry.step} totalSteps={entry.totalSteps ?? 0} stepName={entry.stepName} /> @@ -148,9 +157,18 @@ function renderEntry(entry: ConversationEntry, i: number) { return <UserBubble key={i} timestamp={ts}><Md>{entry.content}</Md></UserBubble> } case 'phase_boundary': - return <PhaseBoundary key={i} label={entry.message} /> - case 'yield': - return <YieldCard key={i} suggestions={entry.suggestions} /> + return <PhaseMarker key={i} name={entry.phase} description={entry.description || entry.message} /> + case 'yield': { + const setChatDraft = useStore.getState().setChatDraft + return ( + <YieldPanel + key={i} + prompt={entry.prompt || 'What would you like to do next?'} + suggestions={entry.suggestions} + onSelect={s => setChatDraft(`/${s.id} `)} + /> + ) + } default: return null } @@ -161,18 +179,13 @@ function ConnectedSteeringBar() { return <SteeringBar messages={steering.map(m => m.content)} /> } -function ActiveYieldPills() { - const activeYield = useStore(s => s.run?.activeYield) - if (!activeYield?.suggestions?.length) return null - return <YieldCard suggestions={activeYield.suggestions} /> -} - function ContentStream() { const focusAgentId = useStore(s => s.run?.focus?.agentId) const conversation = useStore(s => focusAgentId ? s.run?.agents?.[focusAgentId]?.conversation : undefined) const run = useStore(s => s.run) const focus = useStore(s => s.run?.focus) const scrollRef = useRef<HTMLDivElement>(null) + const [paletteOpen, setPaletteOpen] = useState(false) useAutoScroll(scrollRef) const hasEntries = !!(conversation?.entries?.length) const isWaiting = !hasEntries && !conversation?.isThinking && !conversation?.pendingText @@ -180,7 +193,7 @@ function ContentStream() { const showFeedback = run !== null && !hasInteraction return ( <div className="content-column" ref={scrollRef}> - <div className="content-stream"> + <div className={`content-stream${paletteOpen ? ' content-stream--faded' : ''}`}> {isWaiting && ( <div className="waiting-indicator"> <span className="pulse-dot">●</span> @@ -203,8 +216,12 @@ function ContentStream() { {showFeedback && ( <> <ConnectedSteeringBar /> - <ActiveYieldPills /> - <FeedbackInput onSend={msg => api.sendChatMessage(msg)} disabled={!!run?.completion} /> + <FeedbackInput + onSend={msg => api.sendChatMessage(msg)} + disabled={!!run?.completion} + availableCommands={run?.isYielded ? run.availablePhases : undefined} + onPaletteToggle={setPaletteOpen} + /> </> )} </div> @@ -366,11 +383,160 @@ function CompletionView() { // App // --------------------------------------------------------------------------- +// --------------------------------------------------------------------------- +// Navigation items +// --------------------------------------------------------------------------- + +const NAV_ITEMS = [ + { label: 'New run', key: 'new-run' }, + { label: 'Sessions', key: 'sessions' }, + { label: 'Settings', key: 'settings' }, +] + +// --------------------------------------------------------------------------- +// Settings page wiring +// --------------------------------------------------------------------------- + +function ConnectedSettingsPage() { + const profilesDict = useStore(s => s.settings.profiles) + const installationsDict = useStore(s => s.settings.installations) + const scoutConcurrency = useStore(s => s.settings.defaultScoutConcurrency) + const [probeData, setProbeData] = useState<api.RunnerInfo[]>([]) + + useEffect(() => { + api.getProbeInfo() + .then(data => setProbeData(data.runners)) + .catch(() => {}) /* probe failure is non-fatal — dropdowns stay empty */ + }, []) + + const profiles: SPProfile[] = useMemo(() => + Object.values(profilesDict).map(p => ({ + id: p.name, + name: p.name, + locked: p.readOnly, + tiers: { + /* TODO: model and thinking are not in the store wire format — + the backend profile tiers map role → installation alias. + We resolve the runner from the installation but model/thinking + are managed backend-side and not exposed in SSE state yet. */ + strong: { runner: installationsDict[p.tiers['strong']]?.runnerType || p.tiers['strong'] || '', model: '', thinking: '' }, + standard: { runner: installationsDict[p.tiers['standard']]?.runnerType || p.tiers['standard'] || '', model: '', thinking: '' }, + cheap: { runner: installationsDict[p.tiers['cheap']]?.runnerType || p.tiers['cheap'] || '', model: '', thinking: '' }, + }, + })), + [profilesDict, installationsDict], + ) + + const installations: SPInstallation[] = useMemo(() => + Object.values(installationsDict).map(i => ({ + id: i.alias, + alias: i.alias, + runner: i.runnerType, + binary: i.binary, + extraArgs: i.extraArgs.join(' '), + isDefault: i.alias.endsWith('-default'), + available: i.available, + })), + [installationsDict], + ) + + const runnerTypes = useMemo(() => { + // Prefer probe data (includes runners without installations); fall back to installed + if (probeData.length > 0) return probeData.map(r => r.runner_type).sort() + const types = new Set(Object.values(installationsDict).map(i => i.runnerType)) + return [...types].sort() + }, [probeData, installationsDict]) + + const runnerOptions = useMemo(() => + runnerTypes.map(r => ({ value: r, label: r })), + [runnerTypes], + ) + + const modelOptionsForRunner = useMemo(() => + (runner: string) => { + const info = probeData.find(r => r.runner_type === runner) + return info?.models.map(m => ({ value: m.alias, label: m.display_name })) ?? [] + }, + [probeData], + ) + + const thinkingOptionsForModel = useMemo(() => + (runner: string, model: string) => { + const info = probeData.find(r => r.runner_type === runner) + const modelInfo = info?.models.find(m => m.alias === model) + if (modelInfo && modelInfo.thinking_modes.length > 0) { + return modelInfo.thinking_modes.map(t => ({ value: t, label: t })) + } + // Fallback when no model selected or probe data unavailable + return [{ value: 'budget', label: 'budget' }, { value: 'medium', label: 'medium' }, { value: 'high', label: 'high' }] + }, + [probeData], + ) + + return ( + <SettingsPage + profiles={profiles} + onCreateProfile={async p => { + const tiers: Record<string, { runner_type: string; model: string; thinking: string }> = {} + for (const [k, v] of Object.entries(p.tiers)) { + tiers[k] = { runner_type: v.runner, model: v.model, thinking: v.thinking } + } + const res = await api.createProfile(p.name, tiers) + if (!res.ok) throw new Error(res.message || 'Failed to create profile') + }} + onUpdateProfile={async (id, p) => { + if (p.tiers) { + const tiers: Record<string, { runner_type: string; model: string; thinking: string }> = {} + for (const [k, v] of Object.entries(p.tiers)) { + tiers[k] = { runner_type: v.runner, model: v.model, thinking: v.thinking } + } + const res = await api.updateProfile(id, tiers) + if (!res.ok) throw new Error(res.message || 'Failed to update profile') + } + }} + onDeleteProfile={id => api.deleteProfile(id)} + installations={installations} + runnerTypes={runnerTypes} + onCreateInstallation={async inst => { + const res = await api.createAgent({ + alias: inst.alias, + runner_type: inst.runner, + binary: inst.binary, + extra_args: inst.extraArgs ? inst.extraArgs.split(' ').filter(Boolean) : [], + }) + if (!res.ok) throw new Error(res.message || 'Failed to create installation') + }} + onUpdateInstallation={async (id, inst) => { + const res = await api.updateAgent(id, { + ...(inst.runner && { runner_type: inst.runner }), + ...(inst.binary && { binary: inst.binary }), + ...(inst.extraArgs !== undefined && { extra_args: inst.extraArgs.split(' ').filter(Boolean) }), + }) + if (!res.ok) throw new Error(res.message || 'Failed to update installation') + }} + onDeleteInstallation={id => api.deleteAgent(id)} + onDetectBinary={async runner => { + const res = await api.detectAgent(runner) + return res.path + }} + scoutConcurrency={scoutConcurrency} + onScoutConcurrencyChange={n => api.saveScoutConcurrency(n)} + runnerOptions={runnerOptions} + modelOptionsForRunner={modelOptionsForRunner} + thinkingOptionsForModel={thinkingOptionsForModel} + /> + ) +} + +// --------------------------------------------------------------------------- +// App +// --------------------------------------------------------------------------- + export default function App() { const run = useStore(s => s.run) const connected = useStore(s => s.connected) - const settingsOpen = useStore(s => s.settingsOpen) const header = useHeaderData() + const [page, setPage] = useState<'new-run' | 'sessions' | 'settings'>('new-run') useEffect(() => { let es: EventSource | null = null @@ -389,39 +555,54 @@ export default function App() { return () => { es?.close() } }, []) - const openSettings = () => useStore.getState().setSettingsOpen(true) + const goToSettings = () => setPage('settings') const focus = run?.focus const hasInteraction = focus && focus.type !== 'conversation' const completion = run?.completion + // --- Loading --- if (!connected) { return ( <div className="app-root"> - <HeaderBar phase="" step="" totalSteps={0} currentStep={0} onSettingsClick={openSettings} /> + <HeaderBar phase="" step="" totalSteps={0} currentStep={0} /> <div className="single-column"><div className="loading-center">connecting…</div></div> </div> ) } + // --- No active run: page navigation --- if (!run) { return ( <div className="app-root"> - <HeaderBar phase="" step="" totalSteps={0} currentStep={0} onSettingsClick={openSettings} /> - <div className="single-column"><NewRunForm /></div> - <Notification />{settingsOpen && <SettingsOverlay />} + <HeaderBar + phase="" step="" totalSteps={0} currentStep={0} + mode="navigation" + navItems={NAV_ITEMS} + activeNav={page} + onNavChange={k => setPage(k as typeof page)} + /> + {page === 'new-run' && <div className="single-column"><NewRunForm /></div>} + {page === 'sessions' && ( + <div className="single-column"> + <div className="loading-center">Sessions — coming soon</div> + </div> + )} + {page === 'settings' && <ConnectedSettingsPage />} + <Notification /> </div> ) } + // --- Active run: workflow views --- if (hasInteraction) { return ( <div className="app-root"> - <HeaderBar {...header} onSettingsClick={openSettings} /> + <HeaderBar {...header} onSettingsClick={goToSettings} /> <div className="workflow-grid"> <div className="content-column"><ElicitationView /></div> <ConnectedSidebar /> </div> - <Notification />{settingsOpen && <SettingsOverlay />} + <Notification /> </div> ) } @@ -429,19 +610,19 @@ export default function App() { if (completion) { return ( <div className="app-root"> - <HeaderBar {...header} onSettingsClick={openSettings} /> + <HeaderBar {...header} onSettingsClick={goToSettings} /> <div className="workflow-grid"><CompletionView /><ConnectedSidebar /></div> - <Notification />{settingsOpen && <SettingsOverlay />} + <Notification /> </div> ) } return ( <div className="app-root"> - <HeaderBar {...header} onSettingsClick={openSettings} /> + <HeaderBar {...header} onSettingsClick={goToSettings} /> <div className="workflow-grid"><ContentStream /><ConnectedSidebar /></div> <ConnectedScoutBar /> - <Notification />{settingsOpen && <SettingsOverlay />} + <Notification /> </div> ) } diff --git a/frontend/src/components/AGENTS.md b/frontend/src/components/AGENTS.md index 5c97578..3145f38 100644 --- a/frontend/src/components/AGENTS.md +++ b/frontend/src/components/AGENTS.md @@ -94,7 +94,8 @@ class renderings for event types. | `step` | StepHeader | | `debug_step_guidance` | StepGuidancePill + Md | | `user_message` | UserBubble + Md | -| `phase_boundary` | PhaseBoundary | +| `phase_boundary` | PhaseMarker | +| `yield` | YieldPanel | | pending thinking | ThinkingBlock (always expanded) | | pending text | ProseCard + Md + streaming cursor | | steering messages | SteeringBar | diff --git a/frontend/src/components/atoms/Badge.css b/frontend/src/components/atoms/Badge.css index 0338173..2108304 100644 --- a/frontend/src/components/atoms/Badge.css +++ b/frontend/src/components/atoms/Badge.css @@ -14,3 +14,11 @@ .atom-badge--success { background: var(--bg-completion); color: var(--text-completion); } .atom-badge--accent { background: var(--bg-selected); color: var(--color-orange); } .atom-badge--model { background: var(--bg-step-guidance); color: var(--text-muted); } +.atom-badge--default { + background: #fdf2ee; /* orange-tinted badge bg — no token, settings-specific */ + color: #c06030; /* darkened orange badge text — no token, settings-specific */ +} +.atom-badge--error { + background: var(--bg-danger); + color: var(--status-failed); +} diff --git a/frontend/src/components/atoms/Badge.tsx b/frontend/src/components/atoms/Badge.tsx index c7d6508..a432e44 100644 --- a/frontend/src/components/atoms/Badge.tsx +++ b/frontend/src/components/atoms/Badge.tsx @@ -1,14 +1,15 @@ /** * Badge — pill-shaped inline label for metadata and status. * - * Used for: "coming soon", "recommended", "haiku" model labels, - * and other small inline indicators throughout the UI. + * Used for: "coming soon", "recommended" (neutral/success), model labels + * (model), "default" installation labels (default), "unavailable" (error), + * and other small inline indicators. */ import './Badge.css' import type { ReactNode } from 'react' -type Variant = 'neutral' | 'success' | 'accent' | 'model' +type Variant = 'neutral' | 'success' | 'accent' | 'model' | 'default' | 'error' interface BadgeProps { variant: Variant diff --git a/frontend/src/components/atoms/Button.css b/frontend/src/components/atoms/Button.css index 6ac6cff..cd764c7 100644 --- a/frontend/src/components/atoms/Button.css +++ b/frontend/src/components/atoms/Button.css @@ -12,5 +12,40 @@ .atom-btn--secondary { background: transparent; color: var(--text-subtle); border: 1.5px solid var(--border-input); } /* Sizes */ +.atom-btn--xs { padding: 2px 10px; font-size: 12px; border-radius: var(--radius-md); } .atom-btn--sm { padding: 5px 16px; font-size: 13px; border-radius: var(--radius-md); } .atom-btn--md { padding: 10px 28px; font-size: 15px; border-radius: var(--radius-lg); } + +/* Danger — size-dependent appearance */ +.atom-btn--danger.atom-btn--sm { + color: var(--status-failed); + background: transparent; + border: 1px solid var(--border-danger); +} +.atom-btn--danger.atom-btn--md { + color: #fff; + background: var(--status-failed); + border: none; +} +.atom-btn--danger.atom-btn--xs { + color: var(--status-failed); + background: transparent; + border: 1px solid var(--border-danger); +} + +/* Teal — utility actions */ +.atom-btn--teal { + color: var(--color-teal); + background: transparent; + border: 1px solid var(--border-teal); +} + +/* Text — borderless add triggers */ +.atom-btn--text { + color: var(--color-orange); + background: none; + border: none; + padding: 0; + font-size: 13px; + border-radius: 0; +} diff --git a/frontend/src/components/atoms/Button.tsx b/frontend/src/components/atoms/Button.tsx index 0d282d0..1f334a0 100644 --- a/frontend/src/components/atoms/Button.tsx +++ b/frontend/src/components/atoms/Button.tsx @@ -1,15 +1,16 @@ /** - * Button — primary and secondary action triggers. + * Button — action triggers in primary, secondary, danger, teal, and text variants. * - * Used for: "Start Run", "Next", "Send", "Use Defaults", - * and other interactive actions throughout the UI. + * Used for: "Start Run", "Next", "Send" (primary), "Cancel", "Use Defaults" + * (secondary), "Delete" (danger), "Detect", "Explore" (teal), + * "+ New profile", "+ Add installation" (text). */ import './Button.css' import type { ReactNode, ButtonHTMLAttributes } from 'react' -type Variant = 'primary' | 'secondary' -type Size = 'sm' | 'md' +type Variant = 'primary' | 'secondary' | 'danger' | 'teal' | 'text' +type Size = 'xs' | 'sm' | 'md' interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> { variant: Variant diff --git a/frontend/src/components/atoms/NumberInput.css b/frontend/src/components/atoms/NumberInput.css new file mode 100644 index 0000000..983b238 --- /dev/null +++ b/frontend/src/components/atoms/NumberInput.css @@ -0,0 +1,23 @@ +.atom-number-input { + width: 48px; + text-align: center; + font-family: var(--font-mono); + font-size: 13px; + color: var(--text-primary); + background: var(--bg-base); + border: 1.5px solid var(--border-input); + border-radius: var(--radius-lg); + padding: 8px 0; + outline: none; + transition: border-color var(--duration-fast) var(--ease-default); +} + +.atom-number-input:focus { + border-color: var(--color-orange); + box-shadow: 0 0 0 3px var(--focus-ring); +} + +.atom-number-input:disabled { + opacity: 0.5; + cursor: not-allowed; +} diff --git a/frontend/src/components/atoms/NumberInput.tsx b/frontend/src/components/atoms/NumberInput.tsx new file mode 100644 index 0000000..918edb8 --- /dev/null +++ b/frontend/src/components/atoms/NumberInput.tsx @@ -0,0 +1,75 @@ +/** + * NumberInput — compact numeric input for scalar configuration values. + * + * Used in: settings Runtime section (scout concurrency), NewRunForm + * (scout concurrency). Auto-saves on blur — no explicit save UI. + */ + +import { useState, useEffect } from 'react' +import './NumberInput.css' + +interface NumberInputProps { + value: number + onChange: (value: number) => void + min?: number + max?: number + disabled?: boolean + className?: string +} + +export function NumberInput({ + value, + onChange, + min, + max, + disabled = false, + className, +}: NumberInputProps) { + const [display, setDisplay] = useState(value.toString()) + + useEffect(() => { + setDisplay(value.toString()) + }, [value]) + + const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => { + const raw = e.target.value + if (raw === '') { + setDisplay('') + return + } + if (!/^\d+$/.test(raw)) return + setDisplay(raw) + } + + const handleBlur = () => { + let num = parseInt(display, 10) + if (isNaN(num)) { + setDisplay(value.toString()) + return + } + if (min !== undefined && num < min) num = min + if (max !== undefined && num > max) num = max + setDisplay(num.toString()) + onChange(num) + } + + const cls = [ + 'atom-number-input', + className, + ].filter(Boolean).join(' ') + + return ( + <input + type="text" + inputMode="numeric" + pattern="[0-9]*" + className={cls} + value={display} + onChange={handleChange} + onBlur={handleBlur} + disabled={disabled} + /> + ) +} + +export default NumberInput diff --git a/frontend/src/components/atoms/Select.css b/frontend/src/components/atoms/Select.css new file mode 100644 index 0000000..2f20fcb --- /dev/null +++ b/frontend/src/components/atoms/Select.css @@ -0,0 +1,38 @@ +.atom-select { + font-family: var(--font-body); + font-size: 13px; + color: var(--text-primary); + background: var(--bg-base); + border: 1.5px solid var(--border-input); + border-radius: var(--radius-lg); + padding: 8px 28px 8px 12px; + outline: none; + width: 100%; + cursor: pointer; + transition: border-color var(--duration-fast) var(--ease-default); + -webkit-appearance: none; + appearance: none; + /* chevron SVG — text-muted color (#9a8e7e) encoded */ + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='6'%3E%3Cpath d='M1 1l4 4 4-4' stroke='%239a8e7e' stroke-width='1.3' fill='none'/%3E%3C/svg%3E"); + background-repeat: no-repeat; + background-position: right 10px center; +} + +.atom-select:focus { + border-color: var(--color-orange); +} + +.atom-select:disabled { + opacity: 0.5; + cursor: not-allowed; +} + +/* Placeholder state — value is empty */ +.atom-select--placeholder { + color: var(--text-placeholder); +} + +/* Mono modifier — for technical identifiers */ +.atom-select--mono { + font-family: var(--font-mono); +} diff --git a/frontend/src/components/atoms/Select.tsx b/frontend/src/components/atoms/Select.tsx new file mode 100644 index 0000000..f74cac5 --- /dev/null +++ b/frontend/src/components/atoms/Select.tsx @@ -0,0 +1,59 @@ +/** + * Select — shared dropdown select for all forms. + * + * Used in: settings profile forms (runner, model, thinking cascade), + * settings installation forms (runner type), NewRunForm (profile select, + * installation select), and standalone preference selects. + */ + +import './Select.css' + +interface SelectOption { + value: string + label: string +} + +interface SelectProps { + value: string + onChange: (value: string) => void + options: SelectOption[] + placeholder?: string + disabled?: boolean + mono?: boolean + className?: string +} + +export function Select({ + value, + onChange, + options, + placeholder, + disabled = false, + mono = false, + className, +}: SelectProps) { + const cls = [ + 'atom-select', + value === '' && placeholder && 'atom-select--placeholder', + mono && 'atom-select--mono', + className, + ].filter(Boolean).join(' ') + + return ( + <select + className={cls} + value={value} + onChange={e => onChange(e.target.value)} + disabled={disabled} + > + {placeholder && ( + <option value="" disabled hidden>{placeholder}</option> + )} + {options.map(opt => ( + <option key={opt.value} value={opt.value}>{opt.label}</option> + ))} + </select> + ) +} + +export default Select diff --git a/frontend/src/components/atoms/TextInput.css b/frontend/src/components/atoms/TextInput.css new file mode 100644 index 0000000..dc8a3e1 --- /dev/null +++ b/frontend/src/components/atoms/TextInput.css @@ -0,0 +1,65 @@ +.atom-text-input { + font-family: var(--font-body); + font-size: 13px; + color: var(--text-primary); + outline: none; + width: 100%; + transition: border-color var(--duration-fast) var(--ease-default); +} + +.atom-text-input::placeholder { + color: var(--text-placeholder); +} + +.atom-text-input:disabled { + opacity: 0.5; + cursor: not-allowed; +} + +/* Field variant (default) */ +.atom-text-input--field { + background: var(--bg-base); + border: 1.5px solid var(--border-input); + border-radius: var(--radius-lg); + padding: 8px 12px; +} + +.atom-text-input--field:focus { + border-color: var(--color-orange); + box-shadow: 0 0 0 3px var(--focus-ring); +} + +/* Inline variant (bottom-border only) */ +.atom-text-input--inline { + background: transparent; + border: none; + border-bottom: 1px solid var(--border-card); + border-radius: 0; + padding: 8px 0; +} + +.atom-text-input--inline:focus { + border-bottom-color: var(--border-input); +} + +/* Mono modifier */ +.atom-text-input--mono { + font-family: var(--font-mono); +} + +/* Error modifier (field variant only) */ +.atom-text-input--error { + border-color: var(--status-failed); +} + +.atom-text-input--error:focus { + border-color: var(--status-failed); + box-shadow: none; +} + +/* Textarea mode */ +textarea.atom-text-input { + min-height: 80px; + resize: vertical; + line-height: 1.5; +} diff --git a/frontend/src/components/atoms/TextInput.tsx b/frontend/src/components/atoms/TextInput.tsx new file mode 100644 index 0000000..1f0b727 --- /dev/null +++ b/frontend/src/components/atoms/TextInput.tsx @@ -0,0 +1,59 @@ +/** + * TextInput — shared text input for all forms. + * + * Used in: settings forms (profile name, binary path, extra args), + * NewRunForm (description textarea, concurrency input), + * RadioOption/CheckboxOption (custom "Other" text input), + * FeedbackInput (message textarea). + * + * Two variants: "field" (bordered rectangle) and "inline" (bottom-border + * only, for embedded contexts like RadioOption custom input). + */ + +import './TextInput.css' + +interface TextInputProps { + value: string + onChange: (value: string) => void + placeholder?: string + variant?: 'field' | 'inline' + mono?: boolean + error?: boolean + disabled?: boolean + as?: 'input' | 'textarea' + className?: string +} + +export function TextInput({ + value, + onChange, + placeholder, + variant = 'field', + mono = false, + error = false, + disabled = false, + as = 'input', + className, +}: TextInputProps) { + const Tag = as + const cls = [ + 'atom-text-input', + `atom-text-input--${variant}`, + mono && 'atom-text-input--mono', + error && 'atom-text-input--error', + className, + ].filter(Boolean).join(' ') + + return ( + <Tag + className={cls} + value={value} + onChange={(e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => onChange(e.target.value)} + placeholder={placeholder} + disabled={disabled} + {...(as === 'textarea' ? { rows: 3 } : {})} + /> + ) +} + +export default TextInput diff --git a/frontend/src/components/atoms/Toggle.css b/frontend/src/components/atoms/Toggle.css new file mode 100644 index 0000000..542932f --- /dev/null +++ b/frontend/src/components/atoms/Toggle.css @@ -0,0 +1,46 @@ +.atom-toggle { + display: inline-flex; + align-items: center; + width: 36px; + height: 20px; + border-radius: var(--radius-pill); + border: none; + padding: 0; + cursor: pointer; + position: relative; + transition: background var(--duration-fast) var(--ease-default); + outline: none; + flex-shrink: 0; +} + +.atom-toggle:disabled { + opacity: 0.5; + cursor: not-allowed; +} + +.atom-toggle--off { + background: var(--bg-toggle-off); +} + +.atom-toggle--on { + background: var(--color-teal); +} + +.atom-toggle__thumb { + display: block; + width: 16px; + height: 16px; + border-radius: var(--radius-circle); + background: var(--bg-card); + position: absolute; + top: 2px; + transition: left var(--duration-fast) var(--ease-default); +} + +.atom-toggle--off .atom-toggle__thumb { + left: 2px; +} + +.atom-toggle--on .atom-toggle__thumb { + left: 18px; +} diff --git a/frontend/src/components/atoms/Toggle.tsx b/frontend/src/components/atoms/Toggle.tsx new file mode 100644 index 0000000..492b9a8 --- /dev/null +++ b/frontend/src/components/atoms/Toggle.tsx @@ -0,0 +1,34 @@ +/** + * Toggle — boolean switch for auto-saving preferences. + * + * Used in: settings SettingRow (auto-open artifacts, sandbox execution, + * verbose debug output, and future boolean preferences). + * + * Auto-saves on click. The parent component handles the API call — + * no explicit save UI. + */ + +import './Toggle.css' + +interface ToggleProps { + checked: boolean + onChange: (checked: boolean) => void + disabled?: boolean +} + +export function Toggle({ checked, onChange, disabled = false }: ToggleProps) { + return ( + <button + type="button" + role="switch" + aria-checked={checked} + className={`atom-toggle atom-toggle--${checked ? 'on' : 'off'}`} + onClick={() => !disabled && onChange(!checked)} + disabled={disabled} + > + <span className="atom-toggle__thumb" /> + </button> + ) +} + +export default Toggle diff --git a/frontend/src/components/molecules/CommandPalette.css b/frontend/src/components/molecules/CommandPalette.css new file mode 100644 index 0000000..5ccff8e --- /dev/null +++ b/frontend/src/components/molecules/CommandPalette.css @@ -0,0 +1,97 @@ +/* CommandPalette -- floating command dropdown above FeedbackInput. */ + +.cp { + position: absolute; + bottom: 100%; + left: 0; + right: 0; + margin-bottom: 6px; + background: var(--bg-card); + border: 0.5px solid var(--border-card); + border-radius: var(--radius-2xl); + overflow: hidden; + /* candidate for --shadow-dropdown token */ + box-shadow: 0 4px 16px rgba(46, 58, 94, 0.10); + z-index: 10; +} + +/* ---- Hint bar ---- */ +.cp-hint { + display: flex; + align-items: center; + gap: 8px; + padding: 10px 16px; + background: var(--bg-base); + border-bottom: 1px solid var(--border-divider-light); +} + +.cp-hint-icon { + width: 14px; + height: 14px; + border: 1.5px solid var(--border-input); + border-radius: var(--radius-circle); + display: flex; + align-items: center; + justify-content: center; + font-family: var(--font-body); + font-size: 9px; + font-weight: 500; + color: var(--text-muted); + line-height: 1; + flex-shrink: 0; +} + +.cp-hint-text { + font-family: var(--font-body); + font-size: var(--type-tool-type); + color: var(--text-muted); +} + +/* ---- Items ---- */ +.cp-items { + max-height: 260px; /* ~5 items before scroll */ + overflow-y: auto; +} + +.cp-item { + padding: 10px 16px; + cursor: pointer; + transition: background var(--duration-fast) var(--ease-default); +} + +.cp-item + .cp-item { + border-top: 0.5px solid var(--border-divider-light); +} + +.cp-item:hover, +.cp-item--active { + background: var(--bg-tool-row); +} + +.cp-name { + font-family: var(--font-mono); + font-size: var(--type-breadcrumb); + font-weight: 500; + color: var(--text-primary); + margin-bottom: 2px; +} + +.cp-slash { + color: var(--color-orange); +} + +.cp-desc { + font-family: var(--font-body); + font-size: var(--type-tool-type); + color: var(--text-muted); + line-height: 1.3; +} + +/* ---- Empty state ---- */ +.cp-empty { + padding: 12px 16px; + text-align: center; + font-family: var(--font-body); + font-size: var(--type-tool-type); + color: var(--text-muted); +} diff --git a/frontend/src/components/molecules/CommandPalette.tsx b/frontend/src/components/molecules/CommandPalette.tsx new file mode 100644 index 0000000..4ae2033 --- /dev/null +++ b/frontend/src/components/molecules/CommandPalette.tsx @@ -0,0 +1,68 @@ +/** + * CommandPalette -- floating dropdown anchored above FeedbackInput, + * showing workflow phase commands filterable by typing. + * + * Pure presentational molecule. All state (open/closed, filter, + * active index) is owned by FeedbackInput. CommandPalette receives + * the full command list plus the current filter and highlights the + * item at activeIndex within the filtered result. + * + * Clicking an item calls onSelect(command). onNavigate/onDismiss are + * part of the API contract but not used internally -- FeedbackInput + * owns the keyboard handling. + */ + +import './CommandPalette.css' + +interface Command { + id: string + description: string +} + +interface CommandPaletteProps { + commands: Command[] + filter: string + activeIndex: number + onSelect: (command: Command) => void + onNavigate: (direction: 'up' | 'down') => void + onDismiss: () => void +} + +export function CommandPalette(props: CommandPaletteProps) { + const { commands, filter, activeIndex, onSelect } = props + const filtered = commands.filter(c => c.id.startsWith(filter)) + + return ( + <div className="cp"> + <div className="cp-hint"> + <span className="cp-hint-icon" aria-hidden="true">i</span> + <span className="cp-hint-text">Select a command or keep typing to filter</span> + </div> + {filtered.length === 0 ? ( + <div className="cp-empty">No matching commands</div> + ) : ( + <div className="cp-items"> + {filtered.map((cmd, i) => ( + <div + key={cmd.id} + className={`cp-item${i === activeIndex ? ' cp-item--active' : ''}`} + // onMouseDown + preventDefault keeps focus on the textarea + // so the browser doesn't blur it mid-click. + onMouseDown={e => { + e.preventDefault() + onSelect(cmd) + }} + > + <div className="cp-name"> + <span className="cp-slash">/</span>{cmd.id} + </div> + <div className="cp-desc">{cmd.description}</div> + </div> + ))} + </div> + )} + </div> + ) +} + +export default CommandPalette diff --git a/frontend/src/components/molecules/EntityRow.css b/frontend/src/components/molecules/EntityRow.css new file mode 100644 index 0000000..72756e8 --- /dev/null +++ b/frontend/src/components/molecules/EntityRow.css @@ -0,0 +1,37 @@ +.entity-row { + padding: var(--padding-entity-row); + border-radius: var(--radius-lg); + border: 0.5px solid var(--border-card); + margin-bottom: var(--gap-entity-rows); +} + +.entity-row--active { + border: 1.5px solid var(--color-orange); +} + +.entity-row-top { + display: flex; + align-items: center; + gap: 8px; /* inline gap between name, badges, and action buttons — no token */ +} + +.entity-row-name { + font-size: 14px; /* entity name body size — no token */ + font-weight: 500; + color: var(--text-primary); +} + +.entity-row--mono .entity-row-name { + font-size: 13px; /* technical identifier size — no token */ + font-family: var(--font-mono); +} + +.entity-row-meta { + font-size: 12px; /* subtitle/meta size — no token */ + color: var(--text-muted); + font-family: var(--font-mono); + margin-top: 5px; /* spacing between top line and meta — no token */ + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} diff --git a/frontend/src/components/molecules/EntityRow.tsx b/frontend/src/components/molecules/EntityRow.tsx new file mode 100644 index 0000000..4ed58bc --- /dev/null +++ b/frontend/src/components/molecules/EntityRow.tsx @@ -0,0 +1,43 @@ +/** + * EntityRow — two-line list item for configuration entities. + * + * Used in: settings Profiles section (profile rows), settings Agents + * section (installation rows). Displays a name, optional badges, + * optional action buttons, and a metadata subtitle line. + * + * The `children` slot receives inline content for the top line: badges + * and action buttons. The parent composes these directly rather than + * EntityRow accepting badge/action arrays — this keeps the component + * simple and flexible. + */ + +import type { ReactNode } from 'react' +import './EntityRow.css' + +interface EntityRowProps { + name: string + mono?: boolean + meta?: string + active?: boolean + children?: ReactNode +} + +export function EntityRow({ name, mono = false, meta, active = false, children }: EntityRowProps) { + const cls = [ + 'entity-row', + active && 'entity-row--active', + mono && 'entity-row--mono', + ].filter(Boolean).join(' ') + + return ( + <div className={cls}> + <div className="entity-row-top"> + <span className="entity-row-name">{name}</span> + {children} + </div> + {meta && <div className="entity-row-meta">{meta}</div>} + </div> + ) +} + +export default EntityRow diff --git a/frontend/src/components/molecules/FeedbackInput.css b/frontend/src/components/molecules/FeedbackInput.css index 908f8ec..52b5e5a 100644 --- a/frontend/src/components/molecules/FeedbackInput.css +++ b/frontend/src/components/molecules/FeedbackInput.css @@ -1,10 +1,16 @@ .fi { + position: relative; background: var(--bg-card); border: 1.5px solid var(--border-input); border-radius: var(--radius-xl); padding: var(--padding-input); } +.fi--focused { + border-color: var(--color-orange); + box-shadow: 0 0 0 3px var(--focus-ring); +} + .fi--disabled { opacity: 0.5; } diff --git a/frontend/src/components/molecules/FeedbackInput.tsx b/frontend/src/components/molecules/FeedbackInput.tsx index fb69f0e..17b7ecd 100644 --- a/frontend/src/components/molecules/FeedbackInput.tsx +++ b/frontend/src/components/molecules/FeedbackInput.tsx @@ -1,13 +1,19 @@ /** - * FeedbackInput — text input for sending feedback/messages to the agent. + * FeedbackInput -- text input for sending feedback/messages to the agent. * * Sits at the bottom of the content stream. Enter sends, Shift+Enter * inserts a newline. Uses the Button atom for the send action. * - * Watches the chatDraft store field: when a YieldCard pill is clicked, - * it sets chatDraft to the suggestion command, which FeedbackInput picks + * Watches the chatDraft store field: when a YieldPanel row is selected, + * the parent sets chatDraft to "/<phase-id> ", which FeedbackInput picks * up via useEffect, populates the textarea, and focuses it. The user - * reviews and presses Send — no auto-submit. + * reviews and presses Send -- no auto-submit. + * + * /-command support: when availableCommands is provided and the textarea + * starts with "/", a CommandPalette floats above showing filterable phase + * commands. Selecting a command inserts "/<id> " into the textarea. On + * send, /-commands are rewritten into a natural-language instruction + * before calling onSend. * * Used in: content stream footer. */ @@ -15,43 +21,135 @@ import { useState, useRef, useEffect, type KeyboardEvent } from 'react' import { useStore } from '../../store/index' import { Button } from '../atoms/Button' +import { CommandPalette } from './CommandPalette' import './FeedbackInput.css' +interface Command { + id: string + description: string +} + interface FeedbackInputProps { placeholder?: string onSend?: (text: string) => void disabled?: boolean + availableCommands?: Command[] + onPaletteToggle?: (open: boolean) => void +} + +// Parse "/<cmd> <instruction>" and rewrite into a phase-transition message. +// Non-slash input passes through unchanged. +function transformCommand(text: string): string { + if (!text.startsWith('/')) return text + const body = text.slice(1) + const space = body.indexOf(' ') + const cmd = space === -1 ? body : body.slice(0, space) + const instruction = space === -1 ? '' : body.slice(space + 1).trim() + if (instruction) { + return `The user wishes to transition to phase \`${cmd}\` with instruction: ${instruction}` + } + return `The user wishes to transition to phase \`${cmd}\`.` } export function FeedbackInput({ placeholder = 'Send feedback...', onSend, disabled = false, + availableCommands, + onPaletteToggle, }: FeedbackInputProps) { const [text, setText] = useState('') + const [activeIndex, setActiveIndex] = useState(0) const ref = useRef<HTMLTextAreaElement>(null) const chatDraft = useStore(s => s.chatDraft) const setChatDraft = useStore(s => s.setChatDraft) - // Pick up draft set by YieldCard pill clicks + // Pick up draft set by YieldPanel row selections useEffect(() => { if (chatDraft) { setText(chatDraft) - setChatDraft('') // consume the draft immediately + setChatDraft('') ref.current?.focus() } }, [chatDraft, setChatDraft]) + // Palette open rule: text begins with "/" AND the body (post-slash) has + // no space. Once a command is selected we insert "/<id> " with a space, + // which naturally closes the palette so the user can type instructions. + const paletteOpen = !!( + availableCommands && + availableCommands.length > 0 && + text.startsWith('/') && + !text.slice(1).includes(' ') + ) + + const filter = paletteOpen ? text.slice(1) : '' + const filteredCommands = paletteOpen + ? (availableCommands ?? []).filter(c => c.id.startsWith(filter)) + : [] + + // Reset active index when filter changes so the first match is always highlighted. + useEffect(() => { + setActiveIndex(0) + }, [filter]) + + // Notify parent whenever palette toggles. + useEffect(() => { + onPaletteToggle?.(paletteOpen) + }, [paletteOpen, onPaletteToggle]) + const send = () => { const trimmed = text.trim() if (!trimmed || disabled) return - onSend?.(trimmed) + onSend?.(transformCommand(trimmed)) setText('') ref.current?.focus() } + const selectCommand = (cmd: Command) => { + const next = `/${cmd.id} ` + setText(next) + // Re-focus and move the cursor past the trailing space. + requestAnimationFrame(() => { + const el = ref.current + if (el) { + el.focus() + el.setSelectionRange(next.length, next.length) + } + }) + } + const onKey = (e: KeyboardEvent<HTMLTextAreaElement>) => { + if (paletteOpen) { + if (e.key === 'ArrowDown') { + e.preventDefault() + if (filteredCommands.length > 0) { + setActiveIndex(i => (i + 1) % filteredCommands.length) + } + return + } + if (e.key === 'ArrowUp') { + e.preventDefault() + if (filteredCommands.length > 0) { + setActiveIndex(i => (i - 1 + filteredCommands.length) % filteredCommands.length) + } + return + } + if (e.key === 'Enter') { + e.preventDefault() + const cmd = filteredCommands[activeIndex] + if (cmd) selectCommand(cmd) + return + } + if (e.key === 'Escape') { + e.preventDefault() + setText('') + return + } + // Any other key: default textarea behavior (updates filter). + return + } if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault() send() @@ -59,7 +157,17 @@ export function FeedbackInput({ } return ( - <div className={`fi${disabled ? ' fi--disabled' : ''}`}> + <div className={`fi${disabled ? ' fi--disabled' : ''}${paletteOpen ? ' fi--focused' : ''}`}> + {paletteOpen && ( + <CommandPalette + commands={availableCommands ?? []} + filter={filter} + activeIndex={activeIndex} + onSelect={selectCommand} + onNavigate={() => {}} + onDismiss={() => setText('')} + /> + )} <textarea ref={ref} className="fi-textarea" @@ -71,7 +179,11 @@ export function FeedbackInput({ rows={1} /> <div className="fi-footer"> - <span className="fi-hint">Enter to send · Shift+Enter for newline</span> + <span className="fi-hint"> + {paletteOpen + ? '\u2191\u2193 navigate \u00b7 Enter select \u00b7 Esc dismiss' + : 'Enter to send \u00b7 Shift+Enter for newline'} + </span> <Button variant="primary" size="sm" diff --git a/frontend/src/components/molecules/FormRow.css b/frontend/src/components/molecules/FormRow.css new file mode 100644 index 0000000..5459504 --- /dev/null +++ b/frontend/src/components/molecules/FormRow.css @@ -0,0 +1,27 @@ +.form-row { + display: flex; + align-items: center; +} + +.form-row + .form-row { + margin-top: var(--gap-form-rows); +} + +.form-row-label { + font-size: var(--type-label); + font-weight: 500; + color: var(--text-muted); + text-transform: uppercase; + letter-spacing: 0.5px; + width: 82px; + text-align: right; + padding-right: 16px; + flex-shrink: 0; +} + +.form-row-controls { + flex: 1; + display: flex; + gap: var(--gap-form-controls); + min-width: 0; +} diff --git a/frontend/src/components/molecules/FormRow.tsx b/frontend/src/components/molecules/FormRow.tsx new file mode 100644 index 0000000..3f2ac23 --- /dev/null +++ b/frontend/src/components/molecules/FormRow.tsx @@ -0,0 +1,28 @@ +/** + * FormRow — label + control(s) horizontal layout for inline forms. + * + * Used in: InlineForm (profile create/edit, installation create/edit). + * Contains a fixed-width right-aligned uppercase label and a flexible + * controls area that holds one or more TextInput, Select, or Button atoms. + */ + +import type { ReactNode } from 'react' +import './FormRow.css' + +interface FormRowProps { + label: string + children: ReactNode +} + +export function FormRow({ label, children }: FormRowProps) { + return ( + <div className="form-row"> + <span className="form-row-label">{label}</span> + <div className="form-row-controls"> + {children} + </div> + </div> + ) +} + +export default FormRow diff --git a/frontend/src/components/molecules/InlineForm.css b/frontend/src/components/molecules/InlineForm.css new file mode 100644 index 0000000..662bfdb --- /dev/null +++ b/frontend/src/components/molecules/InlineForm.css @@ -0,0 +1,13 @@ +.inline-form { + border: 1.5px solid var(--color-orange); + border-radius: var(--radius-xl); + padding: var(--padding-inline-form); + background: var(--bg-card); +} + +.inline-form-actions { + display: flex; + gap: 8px; + margin-top: 20px; + padding-left: 82px; /* aligns with FormRow controls left edge (82px label width) */ +} diff --git a/frontend/src/components/molecules/InlineForm.tsx b/frontend/src/components/molecules/InlineForm.tsx new file mode 100644 index 0000000..69a8cd4 --- /dev/null +++ b/frontend/src/components/molecules/InlineForm.tsx @@ -0,0 +1,43 @@ +/** + * InlineForm — expandable edit/create region for settings entity lists. + * + * Used in: settings Profiles section (create/edit profile), settings + * Agents section (create/edit installation). Appears inline below + * entity rows within a settings section card. + * + * The orange border signals "user input expected here" — the same + * semantic as the Decision panel's orange top border in elicitation + * and the selected-state border on RadioOption/CheckboxOption. + * + * InlineForm is the only place in configuration UI where explicit + * Cancel/Save buttons appear. All standalone controls auto-save. + */ + +import type { ReactNode } from 'react' +import { Button } from '../atoms/Button' +import './InlineForm.css' + +interface InlineFormProps { + children: ReactNode + onSave: () => void + onCancel: () => void + saving?: boolean +} + +export function InlineForm({ children, onSave, onCancel, saving = false }: InlineFormProps) { + return ( + <div className="inline-form"> + {children} + <div className="inline-form-actions"> + <Button variant="secondary" size="sm" onClick={onCancel} disabled={saving}> + Cancel + </Button> + <Button variant="primary" size="sm" onClick={onSave} disabled={saving}> + {saving ? 'Saving...' : 'Save'} + </Button> + </div> + </div> + ) +} + +export default InlineForm diff --git a/frontend/src/components/molecules/NavItem.css b/frontend/src/components/molecules/NavItem.css new file mode 100644 index 0000000..e94c31b --- /dev/null +++ b/frontend/src/components/molecules/NavItem.css @@ -0,0 +1,26 @@ +.nav-item { + display: block; + width: 100%; + padding: 8px 16px; + cursor: pointer; + font-family: inherit; + font-size: var(--type-body); + font-weight: 400; + color: var(--text-muted); + text-align: left; + background: none; + border: none; + border-left: 2px solid transparent; + user-select: none; + transition: color var(--duration-fast) var(--ease-default); +} + +.nav-item:hover:not(.nav-item--active) { + color: var(--text-primary); +} + +.nav-item--active { + font-weight: 500; + color: var(--text-primary); + border-left-color: var(--color-orange); +} diff --git a/frontend/src/components/molecules/NavItem.tsx b/frontend/src/components/molecules/NavItem.tsx new file mode 100644 index 0000000..dc4d236 --- /dev/null +++ b/frontend/src/components/molecules/NavItem.tsx @@ -0,0 +1,28 @@ +/** + * NavItem — side navigation item for the Settings page left nav. + * + * Used in: SettingsPage organism left navigation (Profiles, Agents, + * Runtime section switcher). + */ + +import './NavItem.css' + +interface NavItemProps { + label: string + active?: boolean + onClick?: () => void +} + +export function NavItem({ label, active = false, onClick }: NavItemProps) { + return ( + <button + type="button" + className={`nav-item${active ? ' nav-item--active' : ''}`} + onClick={onClick} + > + {label} + </button> + ) +} + +export default NavItem diff --git a/frontend/src/components/molecules/PhaseBoundary.css b/frontend/src/components/molecules/PhaseBoundary.css deleted file mode 100644 index fd55371..0000000 --- a/frontend/src/components/molecules/PhaseBoundary.css +++ /dev/null @@ -1,21 +0,0 @@ -.pb { - display: flex; - align-items: center; - gap: 12px; - padding: 20px 0; -} - -.pb-line { - flex: 1; - height: 1px; - background: var(--border-divider); -} - -.pb-label { - font-size: var(--type-label); - color: var(--text-muted); - text-transform: uppercase; - letter-spacing: 1px; - font-weight: 500; - white-space: nowrap; -} diff --git a/frontend/src/components/molecules/PhaseBoundary.tsx b/frontend/src/components/molecules/PhaseBoundary.tsx deleted file mode 100644 index dd532f5..0000000 --- a/frontend/src/components/molecules/PhaseBoundary.tsx +++ /dev/null @@ -1,22 +0,0 @@ -/** - * PhaseBoundary — visual separator between workflow phases. - * A centered label between two horizontal lines. - * Used in: content stream, for phase_boundary events. - */ -import './PhaseBoundary.css' - -interface PhaseBoundaryProps { - label: string -} - -export function PhaseBoundary({ label }: PhaseBoundaryProps) { - return ( - <div className="pb"> - <span className="pb-line" /> - <span className="pb-label">{label}</span> - <span className="pb-line" /> - </div> - ) -} - -export default PhaseBoundary diff --git a/frontend/src/components/molecules/PhaseMarker.css b/frontend/src/components/molecules/PhaseMarker.css new file mode 100644 index 0000000..768b676 --- /dev/null +++ b/frontend/src/components/molecules/PhaseMarker.css @@ -0,0 +1,71 @@ +/* PhaseMarker -- dot-on-divider event marker. */ + +.pm { + padding: 20px 0; + position: relative; +} + +.pm-rule { + position: absolute; + left: 0; + right: 0; + top: 50%; + transform: translateY(-50%); + height: 1px; + background: var(--border-divider); +} + +.pm-row { + position: relative; + display: inline-flex; + align-items: baseline; + gap: 10px; + background: var(--bg-base); + padding-right: 16px; + max-width: 100%; + min-width: 0; +} + +.pm-dot { + width: 10px; + height: 10px; + background: var(--color-teal); + border-radius: var(--radius-circle); + flex-shrink: 0; + align-self: center; +} + +.pm-label { + font-family: var(--font-body); + font-size: var(--type-label); + text-transform: uppercase; + letter-spacing: 1px; + font-weight: 500; + color: var(--text-muted); + flex-shrink: 0; +} + +.pm-name { + font-family: var(--font-body); + font-size: var(--type-breadcrumb); + font-weight: 500; + color: var(--color-teal); + flex-shrink: 0; +} + +.pm-sep { + font-size: 12px; + color: var(--text-muted); + flex-shrink: 0; +} + +.pm-desc { + font-family: var(--font-body); + font-size: var(--type-breadcrumb); + color: var(--text-muted); + line-height: 1.4; + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} diff --git a/frontend/src/components/molecules/PhaseMarker.tsx b/frontend/src/components/molecules/PhaseMarker.tsx new file mode 100644 index 0000000..c87d565 --- /dev/null +++ b/frontend/src/components/molecules/PhaseMarker.tsx @@ -0,0 +1,33 @@ +/** + * PhaseMarker -- event divider rendered in the content stream when a + * phase transition occurs. + * + * A teal dot sits on a horizontal rule (acting as a timeline node) with + * the "Phase:" label, phase name, and description flowing to the right. + * The content group has bg-base behind it so the rule appears to pass + * behind it. + */ + +import './PhaseMarker.css' + +interface PhaseMarkerProps { + name: string + description: string +} + +export function PhaseMarker({ name, description }: PhaseMarkerProps) { + return ( + <div className="pm"> + <div className="pm-rule" /> + <div className="pm-row"> + <span className="pm-dot" /> + <span className="pm-label">Phase:</span> + <span className="pm-name">{name}</span> + <span className="pm-sep" aria-hidden="true">·</span> + <span className="pm-desc">{description}</span> + </div> + </div> + ) +} + +export default PhaseMarker diff --git a/frontend/src/components/molecules/SettingRow.css b/frontend/src/components/molecules/SettingRow.css new file mode 100644 index 0000000..6ce39dd --- /dev/null +++ b/frontend/src/components/molecules/SettingRow.css @@ -0,0 +1,33 @@ +.setting-row { + display: flex; + align-items: flex-start; + gap: 16px; + padding: 14px 0; +} + +.setting-row + .setting-row { + border-top: 0.5px solid var(--border-card); +} + +.setting-row-text { + flex: 1; + min-width: 0; +} + +.setting-row-label { + font-size: 14px; + font-weight: 500; + color: var(--text-primary); +} + +.setting-row-desc { + font-size: 12px; + color: var(--text-muted); + margin-top: 3px; + line-height: 1.4; +} + +.setting-row-control { + flex-shrink: 0; + margin-top: 2px; /* aligns control with label text baseline */ +} diff --git a/frontend/src/components/molecules/SettingRow.tsx b/frontend/src/components/molecules/SettingRow.tsx new file mode 100644 index 0000000..8392d9e --- /dev/null +++ b/frontend/src/components/molecules/SettingRow.tsx @@ -0,0 +1,37 @@ +/** + * SettingRow — horizontal layout for individual auto-saving preference + * controls: label + description on the left, compact control on the right. + * + * Used in: settings Runtime section (toggles, selects, number inputs), + * settings Preferences section, and future preference panels. + * + * The right-side control is passed as children — typically a Toggle, + * Select, or NumberInput atom. + */ + +import type { ReactNode } from 'react' +import './SettingRow.css' + +interface SettingRowProps { + label: string + description?: string + children: ReactNode +} + +export function SettingRow({ label, description, children }: SettingRowProps) { + return ( + <div className="setting-row"> + <div className="setting-row-text"> + <div className="setting-row-label">{label}</div> + {description && ( + <div className="setting-row-desc">{description}</div> + )} + </div> + <div className="setting-row-control"> + {children} + </div> + </div> + ) +} + +export default SettingRow diff --git a/frontend/src/components/molecules/TabBar.css b/frontend/src/components/molecules/TabBar.css new file mode 100644 index 0000000..2c5db05 --- /dev/null +++ b/frontend/src/components/molecules/TabBar.css @@ -0,0 +1,29 @@ +.tab-bar { + display: flex; + gap: 20px; + border-bottom: 1px solid var(--border-divider); + margin-bottom: 18px; +} + +.tab-bar-tab { + font-family: var(--font-body); + font-size: 13px; + font-weight: 400; + color: var(--text-muted); + padding-bottom: 8px; + border-bottom: 2px solid transparent; + margin-bottom: -1px; /* overlaps container border so active underline sits ON divider */ + cursor: pointer; + user-select: none; + transition: color var(--duration-fast) var(--ease-default); +} + +.tab-bar-tab:hover { + color: var(--text-subtle); +} + +.tab-bar-tab--active { + color: var(--text-primary); + font-weight: 500; + border-bottom-color: var(--color-orange); +} diff --git a/frontend/src/components/molecules/TabBar.tsx b/frontend/src/components/molecules/TabBar.tsx new file mode 100644 index 0000000..2c90d0f --- /dev/null +++ b/frontend/src/components/molecules/TabBar.tsx @@ -0,0 +1,41 @@ +/** + * TabBar — horizontal category switcher with underline indicator. + * + * Used in: settings Agents section (runner type tabs: claude, codex, + * gemini) and future tabbed content areas. + */ + +import './TabBar.css' + +interface TabBarProps { + tabs: string[] + activeTab: string + onChange: (tab: string) => void +} + +export function TabBar({ tabs, activeTab, onChange }: TabBarProps) { + return ( + <div className="tab-bar" role="tablist"> + {tabs.map(tab => ( + <span + key={tab} + role="tab" + tabIndex={0} + aria-selected={tab === activeTab} + className={`tab-bar-tab${tab === activeTab ? ' tab-bar-tab--active' : ''}`} + onClick={() => onChange(tab)} + onKeyDown={e => { + if (e.key === 'Enter' || e.key === ' ') { + e.preventDefault() + onChange(tab) + } + }} + > + {tab} + </span> + ))} + </div> + ) +} + +export default TabBar diff --git a/frontend/src/components/molecules/YieldCard.css b/frontend/src/components/molecules/YieldCard.css deleted file mode 100644 index 71662e5..0000000 --- a/frontend/src/components/molecules/YieldCard.css +++ /dev/null @@ -1,36 +0,0 @@ -/* YieldCard — suggestion pills at a koan_yield point. */ - -.yc { - padding: 12px 0 4px; -} - -.yc-pills { - display: flex; - flex-wrap: wrap; - gap: 8px; -} - -.yc-pill { - font-family: var(--font-body); - font-size: var(--type-breadcrumb); - font-weight: 500; - color: var(--color-teal); - background: transparent; - border: 1.5px solid var(--color-teal); - border-radius: var(--radius-xl); - padding: 5px 14px; - cursor: pointer; - transition: - background var(--duration-fast) var(--ease-default), - color var(--duration-fast) var(--ease-default); - white-space: nowrap; -} - -.yc-pill:hover { - background: var(--color-teal); - color: var(--text-on-dark); -} - -.yc-pill:active { - opacity: 0.8; -} diff --git a/frontend/src/components/molecules/YieldCard.tsx b/frontend/src/components/molecules/YieldCard.tsx deleted file mode 100644 index 98816e1..0000000 --- a/frontend/src/components/molecules/YieldCard.tsx +++ /dev/null @@ -1,44 +0,0 @@ -/** - * YieldCard — suggestion pills rendered at a koan_yield point. - * - * Appears in the content stream as a historical record of the yield, and - * also pinned above FeedbackInput via ActiveYieldPills when the yield is active. - * - * Clicking a pill pre-fills the FeedbackInput textarea via the chatDraft store - * field. The user reviews the pre-filled text and presses Send — no auto-submit. - * - * Used in: content stream (yield entry), pinned above FeedbackInput. - */ - -import { useStore } from '../../store/index' -import type { Suggestion } from '../../store/index' -import './YieldCard.css' - -interface YieldCardProps { - suggestions: Suggestion[] -} - -export function YieldCard({ suggestions }: YieldCardProps) { - const setChatDraft = useStore(s => s.setChatDraft) - - if (!suggestions.length) return null - - return ( - <div className="yc"> - <div className="yc-pills"> - {suggestions.map(s => ( - <button - key={s.id} - className="yc-pill" - onClick={() => setChatDraft(s.command || s.label)} - title={s.command || s.label} - > - {s.label} - </button> - ))} - </div> - </div> - ) -} - -export default YieldCard diff --git a/frontend/src/components/molecules/YieldPanel.css b/frontend/src/components/molecules/YieldPanel.css new file mode 100644 index 0000000..b9ad2d1 --- /dev/null +++ b/frontend/src/components/molecules/YieldPanel.css @@ -0,0 +1,82 @@ +/* YieldPanel -- command panel at koan_yield points. */ + +.yp { + background: var(--bg-card); + border: 0.5px solid var(--border-card); + border-radius: var(--radius-2xl); + overflow: hidden; +} + +/* ---- Header ---- */ +.yp-header { + padding: var(--padding-card); + border-bottom: 1px solid var(--border-divider-light); + font-family: var(--font-body); + font-size: var(--type-body); + font-weight: 500; + color: var(--text-primary); + line-height: 1.4; +} + +/* ---- Body ---- */ +.yp-body { + padding: 2px 0; +} + +/* ---- Command row ---- */ +.yp-row { + display: flex; + align-items: flex-start; + gap: 14px; + padding: 11px 20px; + cursor: pointer; + transition: background var(--duration-fast) var(--ease-default); +} + +.yp-row:hover { + background: var(--bg-card-warm); +} + +.yp-row + .yp-row { + border-top: 0.5px solid var(--border-divider-light); +} + +/* ---- Recommended row ---- */ +.yp-row--recommended { + border-left: 3px solid var(--color-orange); + padding-left: 17px; /* 20px default minus 3px border */ + background: var(--bg-selected); +} + +.yp-row--recommended:hover { + background: var(--bg-selected); +} + +/* ---- Command name column ---- */ +.yp-command { + font-family: var(--font-mono); + font-size: var(--type-breadcrumb); + font-weight: 500; + color: var(--text-primary); + white-space: nowrap; + flex-shrink: 0; + min-width: 100px; +} + +.yp-command--recommended { + color: var(--color-orange); +} + +.yp-slash { + color: var(--color-orange); +} + +/* ---- Description column ---- */ +.yp-desc { + font-family: var(--font-body); + font-size: var(--type-breadcrumb); + color: var(--text-muted); + line-height: 1.4; + flex: 1; + min-width: 0; +} diff --git a/frontend/src/components/molecules/YieldPanel.tsx b/frontend/src/components/molecules/YieldPanel.tsx new file mode 100644 index 0000000..7de05be --- /dev/null +++ b/frontend/src/components/molecules/YieldPanel.tsx @@ -0,0 +1,48 @@ +/** + * YieldPanel -- command panel rendered in the content stream when the + * orchestrator yields for a phase transition decision. + * + * Shows a prompt header and a stack of clickable command rows. At most + * one row is marked recommended (orange left accent + warm tint). + * + * Used in: content stream at koan_yield points. + */ + +import './YieldPanel.css' + +interface Suggestion { + id: string + label: string + command: string + recommended?: boolean +} + +interface YieldPanelProps { + prompt: string + suggestions: Suggestion[] + onSelect: (suggestion: Suggestion) => void +} + +export function YieldPanel({ prompt, suggestions, onSelect }: YieldPanelProps) { + return ( + <div className="yp"> + <div className="yp-header">{prompt}</div> + <div className="yp-body"> + {suggestions.map(s => ( + <div + key={s.id} + className={`yp-row${s.recommended ? ' yp-row--recommended' : ''}`} + onClick={() => onSelect(s)} + > + <span className={`yp-command${s.recommended ? ' yp-command--recommended' : ''}`}> + <span className="yp-slash">/</span>{s.id} + </span> + <span className="yp-desc">{s.label}</span> + </div> + ))} + </div> + </div> + ) +} + +export default YieldPanel diff --git a/frontend/src/components/organisms/HeaderBar.css b/frontend/src/components/organisms/HeaderBar.css index b96c08b..e48dcc4 100644 --- a/frontend/src/components/organisms/HeaderBar.css +++ b/frontend/src/components/organisms/HeaderBar.css @@ -78,3 +78,31 @@ justify-content: center; cursor: pointer; } + +/* ---- Navigation mode ---- */ +.hb-nav { + display: flex; + align-items: center; + gap: 24px; +} + +.hb-nav-link { + font-family: inherit; + font-size: var(--type-breadcrumb); + font-weight: 400; + color: var(--text-on-dark-muted); + background: none; + border: none; + padding: 0; + cursor: pointer; + transition: color var(--duration-fast) var(--ease-default); +} + +.hb-nav-link:hover:not(.hb-nav-link--active) { + color: var(--text-on-dark); +} + +.hb-nav-link--active { + font-weight: 500; + color: var(--text-on-dark); +} diff --git a/frontend/src/components/organisms/HeaderBar.tsx b/frontend/src/components/organisms/HeaderBar.tsx index 0fd4d04..0a3b905 100644 --- a/frontend/src/components/organisms/HeaderBar.tsx +++ b/frontend/src/components/organisms/HeaderBar.tsx @@ -1,9 +1,11 @@ /** * HeaderBar — the fixed navy bar at the top of every view. * - * Contains the logo mark + wordmark, a vertical divider, breadcrumb - * navigation with progress segments, orchestrator status, elapsed - * time, and a settings button. + * Two modes: + * - workflow: breadcrumb nav with phase/step/progress, orchestrator + * status, elapsed time, settings gear button. + * - navigation: top-level page navigation links (New run, Sessions, + * Settings). No workflow-specific controls. * * Used in: app shell, rendered above all content views. */ @@ -14,6 +16,7 @@ import { BreadcrumbNav } from '../molecules/BreadcrumbNav' import './HeaderBar.css' interface HeaderBarProps { + // Workflow mode props phase: string step: string totalSteps: number @@ -21,6 +24,12 @@ interface HeaderBarProps { orchestratorModel?: string elapsed?: string onSettingsClick?: () => void + + // Mode switching + mode?: 'workflow' | 'navigation' + navItems?: { label: string; key: string }[] + activeNav?: string + onNavChange?: (key: string) => void } const GearIcon = () => ( @@ -40,38 +49,60 @@ export function HeaderBar({ orchestratorModel = 'opus', elapsed, onSettingsClick, + mode = 'workflow', + navItems, + activeNav, + onNavChange, }: HeaderBarProps) { return ( <header className="hb"> <div className="hb-inner"> - <div className="hb-left"> - <div className="hb-logo"> - <LogoMark /> - <span className="hb-wordmark">koan</span> - </div> - <span className="hb-divider" /> - <BreadcrumbNav - phase={phase} - step={step} - totalSteps={totalSteps} - currentStep={currentStep} - /> - </div> + <div className="hb-left"> + <div className="hb-logo"> + <LogoMark /> + <span className="hb-wordmark">koan</span> + </div> + <span className="hb-divider" /> - <div className="hb-right"> - <div className="hb-orchestrator"> - <StatusDot status="done" size="sm" /> - <span className="hb-model">{orchestratorModel}</span> + {mode === 'workflow' ? ( + <BreadcrumbNav + phase={phase} + step={step} + totalSteps={totalSteps} + currentStep={currentStep} + /> + ) : ( + <div className="hb-nav"> + {navItems?.map(item => ( + <button + key={item.key} + type="button" + className={`hb-nav-link${item.key === activeNav ? ' hb-nav-link--active' : ''}`} + onClick={() => onNavChange?.(item.key)} + > + {item.label} + </button> + ))} + </div> + )} </div> - {elapsed && <span className="hb-elapsed">{elapsed}</span>} - <button - className="hb-settings" - onClick={onSettingsClick} - aria-label="Settings" - > - <GearIcon /> - </button> - </div> + + {mode === 'workflow' && ( + <div className="hb-right"> + <div className="hb-orchestrator"> + <StatusDot status="done" size="sm" /> + <span className="hb-model">{orchestratorModel}</span> + </div> + {elapsed && <span className="hb-elapsed">{elapsed}</span>} + <button + className="hb-settings" + onClick={onSettingsClick} + aria-label="Settings" + > + <GearIcon /> + </button> + </div> + )} </div> </header> ) diff --git a/frontend/src/components/organisms/SettingsPage.css b/frontend/src/components/organisms/SettingsPage.css new file mode 100644 index 0000000..fd225dc --- /dev/null +++ b/frontend/src/components/organisms/SettingsPage.css @@ -0,0 +1,40 @@ +.settings-page { + flex: 1; + overflow-y: auto; + background: var(--bg-base); +} + +.settings-content { + max-width: var(--settings-max-width); + margin: 0 auto; + padding: var(--form-page-padding); + display: flex; + flex-direction: column; + gap: var(--gap-form-sections); +} + +.settings-title { + font-size: var(--type-page-title); + font-weight: 500; + color: var(--text-primary); + letter-spacing: -0.5px; + margin: 0; +} + +.settings-card { + background: var(--bg-card); + border-radius: var(--radius-2xl); + border: 0.5px solid var(--border-card); + padding: var(--padding-card-settings); +} + +.settings-card-title { + font-size: 17px; /* --type-section-title */ + font-weight: 500; + color: var(--text-primary); + margin-bottom: 20px; +} + +.settings-add-trigger { + margin-top: 16px; +} diff --git a/frontend/src/components/organisms/SettingsPage.tsx b/frontend/src/components/organisms/SettingsPage.tsx new file mode 100644 index 0000000..6e9a006 --- /dev/null +++ b/frontend/src/components/organisms/SettingsPage.tsx @@ -0,0 +1,341 @@ +/** + * SettingsPage — full-page settings view with all sections stacked. + * + * Presentational organism. All data and callbacks come from props. + * The parent connects the store. Single centered scrollable column + * matching the NewRunForm layout pattern. + * + * Used in: app shell, replaces SettingsOverlay for the new design. + */ + +import { useState, useRef, useEffect } from 'react' +import { EntityRow } from '../molecules/EntityRow' +import { InlineForm } from '../molecules/InlineForm' +import { FormRow } from '../molecules/FormRow' +import { TabBar } from '../molecules/TabBar' +import { SettingRow } from '../molecules/SettingRow' +import { TextInput } from '../atoms/TextInput' +import { Select } from '../atoms/Select' +import { NumberInput } from '../atoms/NumberInput' +import { Button } from '../atoms/Button' +import { Badge } from '../atoms/Badge' +import './SettingsPage.css' + +// --------------------------------------------------------------------------- +// Types +// --------------------------------------------------------------------------- + +interface TierConfig { + runner: string + model: string + thinking: string +} + +export interface Profile { + id: string + name: string + locked?: boolean + tiers: { strong: TierConfig; standard: TierConfig; cheap: TierConfig } +} + +export interface Installation { + id: string + alias: string + runner: string + binary: string + extraArgs?: string + isDefault?: boolean + available?: boolean +} + +export interface SettingsPageProps { + profiles: Profile[] + onCreateProfile: (profile: Omit<Profile, 'id'>) => Promise<void> + onUpdateProfile: (id: string, profile: Partial<Profile>) => Promise<void> + onDeleteProfile: (id: string) => void + + installations: Installation[] + runnerTypes: string[] + onCreateInstallation: (install: Omit<Installation, 'id'>) => Promise<void> + onUpdateInstallation: (id: string, install: Partial<Installation>) => Promise<void> + onDeleteInstallation: (id: string) => void + onDetectBinary: (runner: string) => Promise<string | null> + + scoutConcurrency: number + onScoutConcurrencyChange: (n: number) => void + + runnerOptions: { value: string; label: string }[] + modelOptionsForRunner: (runner: string) => { value: string; label: string }[] + thinkingOptionsForModel: (runner: string, model: string) => { value: string; label: string }[] +} + +// --------------------------------------------------------------------------- +// Helpers +// --------------------------------------------------------------------------- + +const TIER_KEYS = ['strong', 'standard', 'cheap'] as const + +function tierSummary(tiers: Profile['tiers']): string { + return TIER_KEYS.map(k => `${k}: ${tiers[k].runner}`).join(' · ') +} + +function emptyTier(): TierConfig { + return { runner: '', model: '', thinking: '' } +} + +// --------------------------------------------------------------------------- +// Profile tier form rows +// --------------------------------------------------------------------------- + +function TierFormRows({ + tiers, onChange, runnerOptions, modelOptionsForRunner, thinkingOptionsForModel, +}: { + tiers: Record<string, TierConfig> + onChange: (tier: string, field: keyof TierConfig, value: string) => void + runnerOptions: { value: string; label: string }[] + modelOptionsForRunner: (runner: string) => { value: string; label: string }[] + thinkingOptionsForModel: (runner: string, model: string) => { value: string; label: string }[] +}) { + return ( + <> + {TIER_KEYS.map(tier => ( + <FormRow key={tier} label={tier.charAt(0).toUpperCase() + tier.slice(1)}> + <Select value={tiers[tier].runner} onChange={v => onChange(tier, 'runner', v)} options={runnerOptions} mono placeholder="— runner —" /> + <Select value={tiers[tier].model} onChange={v => onChange(tier, 'model', v)} options={modelOptionsForRunner(tiers[tier].runner)} mono placeholder="— model —" /> + <Select value={tiers[tier].thinking} onChange={v => onChange(tier, 'thinking', v)} options={thinkingOptionsForModel(tiers[tier].runner, tiers[tier].model)} mono placeholder="— thinking —" /> + </FormRow> + ))} + </> + ) +} + +// --------------------------------------------------------------------------- +// SettingsPage +// --------------------------------------------------------------------------- + +export function SettingsPage(props: SettingsPageProps) { + const { + profiles, onCreateProfile, onUpdateProfile, onDeleteProfile, + installations, runnerTypes, onCreateInstallation, onUpdateInstallation, onDeleteInstallation, onDetectBinary, + scoutConcurrency, onScoutConcurrencyChange, + runnerOptions, modelOptionsForRunner, thinkingOptionsForModel, + } = props + + // Agents tab + const [activeTab, setActiveTab] = useState(runnerTypes[0] || '') + + // Inline form state — only one open at a time across all sections + const [editingProfileId, setEditingProfileId] = useState<string | null>(null) + const [editingInstallationId, setEditingInstallationId] = useState<string | null>(null) + const [creatingProfile, setCreatingProfile] = useState(false) + const [creatingInstallation, setCreatingInstallation] = useState(false) + + // Auto-scroll to the active inline form when it opens + const activeFormRef = useRef<HTMLDivElement>(null) + const formOpen = editingProfileId || editingInstallationId || creatingProfile || creatingInstallation + useEffect(() => { + if (formOpen && activeFormRef.current) { + activeFormRef.current.scrollIntoView({ behavior: 'smooth', block: 'nearest' }) + } + }, [formOpen, editingProfileId, editingInstallationId, creatingProfile, creatingInstallation]) + + // Profile form fields + const [pfName, setPfName] = useState('') + const [pfTiers, setPfTiers] = useState<Record<string, TierConfig>>({ + strong: emptyTier(), standard: emptyTier(), cheap: emptyTier(), + }) + + // Installation form fields + const [ifAlias, setIfAlias] = useState('') + const [ifRunner, setIfRunner] = useState('') + const [ifBinary, setIfBinary] = useState('') + const [ifExtra, setIfExtra] = useState('') + + const closeAllForms = () => { + setEditingProfileId(null) + setEditingInstallationId(null) + setCreatingProfile(false) + setCreatingInstallation(false) + } + + const switchTab = (tab: string) => { + closeAllForms() + setActiveTab(tab) + } + + // Profile form helpers + const openProfileEdit = (p: Profile) => { + closeAllForms() + setEditingProfileId(p.id) + setPfName(p.name) + setPfTiers({ ...p.tiers }) + } + + const openProfileCreate = () => { + closeAllForms() + setCreatingProfile(true) + setPfName('') + setPfTiers({ strong: emptyTier(), standard: emptyTier(), cheap: emptyTier() }) + } + + const handleTierChange = (tier: string, field: keyof TierConfig, value: string) => { + setPfTiers(prev => ({ ...prev, [tier]: { ...prev[tier], [field]: value } })) + } + + const saveProfile = async () => { + const data = { name: pfName, tiers: pfTiers as Profile['tiers'] } + try { + if (editingProfileId) await onUpdateProfile(editingProfileId, data) + else await onCreateProfile(data) + closeAllForms() + } catch { + /* API error — keep form open so user can retry */ + } + } + + // Installation form helpers + const openInstallEdit = (inst: Installation) => { + closeAllForms() + setEditingInstallationId(inst.id) + setIfAlias(inst.alias) + setIfRunner(inst.runner) + setIfBinary(inst.binary) + setIfExtra(inst.extraArgs || '') + } + + const openInstallCreate = () => { + closeAllForms() + setCreatingInstallation(true) + setIfAlias('') + setIfRunner(activeTab) + setIfBinary('') + setIfExtra('') + } + + const saveInstallation = async () => { + const data = { alias: ifAlias, runner: ifRunner, binary: ifBinary, extraArgs: ifExtra } + try { + if (editingInstallationId) await onUpdateInstallation(editingInstallationId, data) + else await onCreateInstallation(data) + closeAllForms() + } catch { + /* API error — keep form open so user can retry */ + } + } + + // Shared form content + const profileFormContent = ( + <> + <FormRow label="Name"> + {/* Profile rename requires delete + recreate — not supported in current API */} + <TextInput value={pfName} onChange={setPfName} placeholder="profile name" disabled={!!editingProfileId} /> + </FormRow> + <TierFormRows tiers={pfTiers} onChange={handleTierChange} runnerOptions={runnerOptions} modelOptionsForRunner={modelOptionsForRunner} thinkingOptionsForModel={thinkingOptionsForModel} /> + </> + ) + + const installFormContent = ( + <> + <FormRow label="Alias"> + {/* Installation alias is the API identifier — not editable on update */} + <TextInput value={ifAlias} onChange={setIfAlias} placeholder="installation name" disabled={!!editingInstallationId} /> + </FormRow> + <FormRow label="Runner"> + <Select value={ifRunner} onChange={setIfRunner} options={runnerOptions} mono /> + </FormRow> + <FormRow label="Binary"> + <TextInput value={ifBinary} onChange={setIfBinary} mono /> + <Button variant="teal" size="sm" onClick={async () => { + const path = await onDetectBinary(ifRunner) + if (path) setIfBinary(path) + }}>Detect</Button> + </FormRow> + <FormRow label="Extra args"> + <TextInput value={ifExtra} onChange={setIfExtra} mono /> + </FormRow> + </> + ) + + const tabInstallations = installations.filter(i => i.runner === activeTab) + + return ( + <div className="settings-page"> + <div className="settings-content"> + <h1 className="settings-title">Settings</h1> + + {/* ═══ PROFILES ═══ */} + <div className="settings-card"> + <div className="settings-card-title">Profiles</div> + {profiles.map(p => ( + <div key={p.id}> + <EntityRow name={p.name} meta={tierSummary(p.tiers)} active={editingProfileId === p.id}> + {p.locked ? ( + <Badge variant="neutral">locked</Badge> + ) : ( + <> + <span style={{ flex: 1 }} /> + <Button variant="secondary" size="xs" onClick={() => openProfileEdit(p)}>Edit</Button> + <Button variant="danger" size="xs" onClick={() => onDeleteProfile(p.id)}>Delete</Button> + </> + )} + </EntityRow> + {editingProfileId === p.id && ( + <div ref={activeFormRef}> + <InlineForm onSave={saveProfile} onCancel={closeAllForms}>{profileFormContent}</InlineForm> + </div> + )} + </div> + ))} + {creatingProfile && ( + <div ref={activeFormRef}> + <InlineForm onSave={saveProfile} onCancel={closeAllForms}>{profileFormContent}</InlineForm> + </div> + )} + <div className="settings-add-trigger"> + <Button variant="text" onClick={openProfileCreate}>+ New profile</Button> + </div> + </div> + + {/* ═══ AGENT INSTALLATIONS ═══ */} + <div className="settings-card"> + <div className="settings-card-title">Agent Installations</div> + <TabBar tabs={runnerTypes} activeTab={activeTab} onChange={switchTab} /> + {tabInstallations.map(inst => ( + <div key={inst.id}> + <EntityRow name={inst.alias} mono meta={inst.binary + (inst.extraArgs ? ' ' + inst.extraArgs : '')} active={editingInstallationId === inst.id}> + {inst.isDefault && <Badge variant="default">default</Badge>} + {inst.available ? <Badge variant="success">available</Badge> : <Badge variant="error">unavailable</Badge>} + <span style={{ flex: 1 }} /> + <Button variant="secondary" size="xs" onClick={() => openInstallEdit(inst)}>Edit</Button> + {!inst.isDefault && <Button variant="danger" size="xs" onClick={() => onDeleteInstallation(inst.id)}>Delete</Button>} + </EntityRow> + {editingInstallationId === inst.id && ( + <div ref={activeFormRef}> + <InlineForm onSave={saveInstallation} onCancel={closeAllForms}>{installFormContent}</InlineForm> + </div> + )} + </div> + ))} + {creatingInstallation && ( + <div ref={activeFormRef}> + <InlineForm onSave={saveInstallation} onCancel={closeAllForms}>{installFormContent}</InlineForm> + </div> + )} + <div className="settings-add-trigger"> + <Button variant="text" onClick={openInstallCreate}>+ Add {activeTab} installation</Button> + </div> + </div> + + {/* ═══ RUNTIME ═══ */} + <div className="settings-card"> + <div className="settings-card-title">Runtime</div> + <SettingRow label="Scout concurrency" description="Maximum number of parallel scout agents"> + <NumberInput value={scoutConcurrency} onChange={onScoutConcurrencyChange} min={1} max={32} /> + </SettingRow> + </div> + </div> + </div> + ) +} + +export default SettingsPage diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 249d2eb..505ff2e 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -45,11 +45,10 @@ export interface ToolGrepEntry extends BaseToolEntry { type: 'tool_grep'; export interface ToolLsEntry extends BaseToolEntry { type: 'tool_ls'; path: string } export interface ToolGenericEntry extends BaseToolEntry { type: 'tool_generic'; toolName: string; summary: string } export interface DebugStepGuidanceEntry { type: 'debug_step_guidance'; content: string } -export interface PhaseBoundaryEntry { type: 'phase_boundary'; phase: string; message: string } +export interface PhaseBoundaryEntry { type: 'phase_boundary'; phase: string; message: string; description: string } -export interface Suggestion { id: string; label: string; command: string } -export interface YieldEntry { type: 'yield'; suggestions: Suggestion[] } -export interface ActiveYield { suggestions: Suggestion[] } +export interface Suggestion { id: string; label: string; command: string; recommended?: boolean } +export interface YieldEntry { type: 'yield'; prompt: string; suggestions: Suggestion[] } export type ConversationEntry = | ThinkingEntry | TextEntry | StepEntry | UserMessageEntry @@ -137,7 +136,8 @@ export interface Run { artifacts: Record<string, ArtifactInfo> completion: CompletionInfo | null steering: SteeringMessage[] - activeYield: ActiveYield | null + isYielded: boolean + availablePhases: { id: string; description: string }[] } // -- Store -------------------------------------------------------------------- @@ -155,7 +155,7 @@ interface KoanState { // Local UI state (not from server) settingsOpen: boolean - // Local draft for chat input — set by YieldCard pill clicks + // Local draft for chat input — set by YieldPanel row selections chatDraft: string // Actions diff --git a/frontend/src/styles/app-shell.css b/frontend/src/styles/app-shell.css index 174e37a..29457be 100644 --- a/frontend/src/styles/app-shell.css +++ b/frontend/src/styles/app-shell.css @@ -33,6 +33,13 @@ gap: var(--gap-content); } +/* When the command palette is open, fade all stream entries except the + last child (FeedbackInput) so focus goes to the input + palette. */ +.content-stream--faded > *:not(:last-child) { + opacity: 0.35; + transition: opacity var(--duration-fast) var(--ease-default); +} + /* Group consecutive tool call rows with tight spacing */ .tool-group { display: flex; diff --git a/frontend/src/styles/variables.css b/frontend/src/styles/variables.css index 0f8528c..54f55c5 100644 --- a/frontend/src/styles/variables.css +++ b/frontend/src/styles/variables.css @@ -124,6 +124,8 @@ --bg-step-guidance: #efece6; --bg-completion: #e8f5ee; --bg-selected: #fdf8f5; + --bg-danger: #fce8e8; + --bg-toggle-off: #d3d1c7; /* ===== Text Colors (light backgrounds) ===== */ @@ -137,6 +139,8 @@ --text-thinking-label: #5a5080; --text-completion: #2a6a4a; --text-artifact-time: #a89888; + --text-danger: #791f1f; + --text-danger-body: #a03030; /* ===== Text Colors (dark backgrounds — header, scout bar) ===== */ @@ -153,6 +157,8 @@ --border-radio: #e0d8cc; --border-divider: #e8e2d8; --border-divider-light: #f0ebe4; + --border-danger: #e8c8c8; + --border-teal: #b8d8cc; /* ===== Semantic Status Colors ===== */ @@ -190,6 +196,8 @@ --header-height: 50px; --form-max-width: 640px; --form-page-padding: 40px 24px; + --settings-nav-width: 152px; + --settings-max-width: 960px; /* ===== Spacing — Component Gaps ===== */ @@ -200,6 +208,9 @@ --gap-radio-options: 10px; --gap-scout-summary: 16px; --gap-progress-segments: 3px; + --gap-entity-rows: 8px; + --gap-form-rows: 12px; + --gap-form-controls: 8px; /* ===== Spacing — Component Internal Padding ===== */ @@ -212,6 +223,9 @@ --padding-scout-row: 8px 14px; --padding-input: 14px 18px; --padding-radio: 12px 14px; + --padding-card-settings: 22px 26px; + --padding-entity-row: 12px 16px; + --padding-inline-form: 22px 26px; /* ===== Border Radius ===== */ From 13ecabb6dad6cf23a7bfbd1d15363142f215bff0 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 9 Apr 2026 17:42:52 +0700 Subject: [PATCH 359/412] refactor: restyle recommended elicitation options --- frontend/src/components/molecules/CheckboxOption.css | 9 +++++++++ frontend/src/components/molecules/CheckboxOption.tsx | 4 +--- frontend/src/components/molecules/RadioOption.css | 9 +++++++++ frontend/src/components/molecules/RadioOption.tsx | 4 +--- 4 files changed, 20 insertions(+), 6 deletions(-) diff --git a/frontend/src/components/molecules/CheckboxOption.css b/frontend/src/components/molecules/CheckboxOption.css index 51ba4fa..11837d3 100644 --- a/frontend/src/components/molecules/CheckboxOption.css +++ b/frontend/src/components/molecules/CheckboxOption.css @@ -14,6 +14,15 @@ background: var(--bg-selected); } +.co--recommended { + border-left: 3px solid var(--color-orange); + background: var(--bg-selected); +} + +.co--recommended.co--selected { + border-left-width: 1.5px; +} + .co-box { width: 18px; height: 18px; diff --git a/frontend/src/components/molecules/CheckboxOption.tsx b/frontend/src/components/molecules/CheckboxOption.tsx index 43352dd..37076e5 100644 --- a/frontend/src/components/molecules/CheckboxOption.tsx +++ b/frontend/src/components/molecules/CheckboxOption.tsx @@ -4,7 +4,6 @@ * Used in: elicitation decision panels (multi-select mode). */ import { useEffect, useRef } from 'react' -import { Badge } from '../atoms/Badge' import './CheckboxOption.css' interface CheckboxOptionProps { @@ -31,7 +30,7 @@ export function CheckboxOption({ label, selected, recommended, isCustom, customT return ( <div - className={`co${selected ? ' co--selected' : ''}${isCustom ? ' co--custom' : ''}`} + className={`co${selected ? ' co--selected' : ''}${recommended ? ' co--recommended' : ''}${isCustom ? ' co--custom' : ''}`} onClick={onClick} role="checkbox" aria-checked={selected} @@ -42,7 +41,6 @@ export function CheckboxOption({ label, selected, recommended, isCustom, customT <span className="co-content"> <span className="co-label-row"> <span className="co-label">{label}</span> - {recommended && <Badge variant="success">recommended</Badge>} </span> {isCustom && selected && ( <input diff --git a/frontend/src/components/molecules/RadioOption.css b/frontend/src/components/molecules/RadioOption.css index ec078a7..85e742a 100644 --- a/frontend/src/components/molecules/RadioOption.css +++ b/frontend/src/components/molecules/RadioOption.css @@ -14,6 +14,15 @@ background: var(--bg-selected); } +.ro--recommended { + border-left: 3px solid var(--color-orange); + background: var(--bg-selected); +} + +.ro--recommended.ro--selected { + border-left-width: 1.5px; +} + /* ---- Radio circle ---- */ .ro-circle { width: 18px; diff --git a/frontend/src/components/molecules/RadioOption.tsx b/frontend/src/components/molecules/RadioOption.tsx index 476d966..0c9184c 100644 --- a/frontend/src/components/molecules/RadioOption.tsx +++ b/frontend/src/components/molecules/RadioOption.tsx @@ -9,7 +9,6 @@ */ import { useEffect, useRef } from 'react' -import { Badge } from '../atoms/Badge' import './RadioOption.css' interface RadioOptionProps { @@ -31,7 +30,7 @@ export function RadioOption({ label, selected, recommended, isCustom, customText return ( <div - className={`ro${selected ? ' ro--selected' : ''}${isCustom ? ' ro--custom' : ''}`} + className={`ro${selected ? ' ro--selected' : ''}${recommended ? ' ro--recommended' : ''}${isCustom ? ' ro--custom' : ''}`} onClick={onClick} role="radio" aria-checked={selected} @@ -42,7 +41,6 @@ export function RadioOption({ label, selected, recommended, isCustom, customText <span className="ro-content"> <span className="ro-label-row"> <span className="ro-label">{label}</span> - {recommended && <Badge variant="success">recommended</Badge>} </span> {isCustom && selected && ( <input From ce18fea583386f625f5a6a264ab9b7b1436b1c43 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 9 Apr 2026 17:43:07 +0700 Subject: [PATCH 360/412] docs: update design system for new frontend patterns --- docs/design-system.md | 548 ++++++++++++++++++++++++------------------ 1 file changed, 317 insertions(+), 231 deletions(-) diff --git a/docs/design-system.md b/docs/design-system.md index 11a4211..b8b6253 100644 --- a/docs/design-system.md +++ b/docs/design-system.md @@ -1,346 +1,432 @@ # Koan Design System -## Overview +The single source of truth for koan's visual design. `src/styles/variables.css` is a mechanical translation of the token tables below. The doc changes first, then the CSS follows. -This document defines the complete visual language for koan's web UI. Every component must reference these tokens — nothing hardcodes values. The aesthetic is mid-century modern geometric: confident, warm, professional with controlled playfulness. Inspired by Lobotain's navy/orange/teal palette, Kolur's complementary duotones, and Japanese-influenced earthy pastels. +--- -## Color Palette +## Tokens -### Core colors +### Background surfaces -These are the three identity colors. They appear in the header, accents, status indicators, and interactive elements. +| Token | Hex | Usage | +| ----------------- | --------- | ------------------------------------------------------------------------- | +| `--bg-danger` | `#fce8e8` | Destructive confirmation backgrounds. Red-family tint. | +| `--bg-toggle-off` | `#d3d1c7` | Toggle track off state. Neutral warm gray, lighter than `--border-input`. | -| Token | Hex | Usage | -|---|---|---| -| `--color-navy` | `#2e3a5e` | Header bar, scout bar frame, primary text, artifact icons (dark), logo text | -| `--color-orange` | `#d4775a` | Primary accent, active states, running indicators, progress bars, primary buttons, decision borders, numbered list markers | -| `--color-teal` | `#5a9a8a` | Secondary accent, success/completion states, checkmarks in tool calls, completed progress segments, orchestrator dot, "recommended" badges | +### Text colors -### Background surfaces +| Token | Hex | Usage | +| -------------------- | --------- | --------------------------------------------------- | +| `--text-danger` | `#791f1f` | Destructive confirmation heading text. Darkest red. | +| `--text-danger-body` | `#a03030` | Destructive confirmation body text. | -These define the layering system. The hierarchy from back to front is: base → surface → card. Each layer must be visually distinguishable from its neighbors. +### Border colors -| Token | Hex | Usage | -|---|---|---| -| `--bg-base` | `#f8f6f2` | Main content area background. Warm-tinted near-white — warm enough to avoid clinical, light enough to avoid brown. | -| `--bg-surface` | `#f3efe8` | Artifacts sidebar background. Slightly warmer and darker than base to create panel distinction. | -| `--bg-card` | `#ffffff` | Prose output cards, form sections, scout table interior, artifact cards, input fields. True white provides the strongest contrast against base. | -| `--bg-tool-row` | `#f0ede6` | Tool call rows (bash, read, edit). Sits between base and surface in warmth. | -| `--bg-thinking` | `#eae5f2` | Thinking/reasoning blocks. Lavender — in the cool family with navy but lighter, creating warm/cool interplay. | -| `--bg-step-guidance` | `#efece6` | Step guidance pill, model badges in scout table, "coming soon" badges. Neutral warm. | -| `--bg-completion` | `#e8f5ee` | Completion/success banners. Teal-family light green. | -| `--bg-selected` | `#fdf8f5` | Selected card state (e.g., selected workflow option). Very faint orange tint. | -| `--bg-card-warm` | `#faf8f4` | Slightly warmer white for artifact cards, scout table interior, and secondary card surfaces distinguishable from prose cards. | +| Token | Hex | Usage | +| ----------------- | --------- | ------------------------------------------------------------- | +| `--border-danger` | `#e8c8c8` | Danger button borders, destructive confirmation card borders. | +| `--border-teal` | `#b8d8cc` | Teal-accented button borders (Detect, Explore actions). | -### Text colors +### Component gaps -| Token | Hex | Usage | -|---|---|---| -| `--text-primary` | `#2e3a5e` | Headings, prose body text, scout names, form labels. Same as navy — this is intentional, it ties text to the brand. | -| `--text-body` | `#4a4a5a` | Secondary body text within prose cards, list items, codebase findings. | -| `--text-muted` | `#9a8e7e` | Tool call type labels ("bash", "read"), metadata, timestamps, placeholder labels, column headers. | -| `--text-subtle` | `#7a6e60` | Step guidance text, form descriptions, secondary labels. | -| `--text-placeholder` | `#b0a498` | Input placeholder text ("Send feedback..."). | -| `--text-hint` | `#c8baa8` | Hint text below inputs ("Enter to send · Shift+Enter for newline"). | -| `--text-thinking` | `#3a3460` | Text inside thinking blocks. Dark purple for contrast against lavender. | -| `--text-thinking-label` | `#5a5080` | "THINKING" label text. Medium purple. | -| `--text-completion` | `#2a6a4a` | Completion banner text. Dark teal-green. | -| `--text-artifact-time` | `#a89888` | Artifact "modified X ago" timestamps. | - -### Text on dark backgrounds (navy header, scout bar frame) - -| Token | Hex | Usage | -|---|---|---| -| `--text-on-dark` | `#f0e8d8` | Primary text on navy. Warm off-white, not pure white. | -| `--text-on-dark-muted` | `rgba(240,232,216,0.55)` | Breadcrumb inactive segments, secondary labels on navy. | -| `--text-on-dark-subtle` | `rgba(240,232,216,0.4)` | Timestamps, tertiary info on navy. | -| `--text-on-dark-faint` | `rgba(255,255,255,0.15)` | Dividers, inactive progress segments, icon button borders on navy. | -| `--text-on-dark-scouts-muted` | `rgba(240,232,216,0.45)` | Scout summary labels ("running", "done") on navy. | +| Token | Value | Usage | +| --------------------- | ----- | -------------------------------------------------------------------- | +| `--gap-entity-rows` | 8px | Between entity rows within a settings section card. | +| `--gap-form-rows` | 12px | Between form rows inside an inline form. | +| `--gap-form-controls` | 8px | Between controls in a single form row (e.g., three cascade selects). | -### Border colors +### Component internal padding -| Token | Hex | Usage | -|---|---|---| -| `--border-card` | `#eae6e0` | Card borders (prose cards, artifact cards). Faint warm line. | -| `--border-input` | `#c8c0b4` | Input field borders, text area borders. Distinctly visible against white and base backgrounds. | -| `--border-radio` | `#e0d8cc` | Radio option card borders, form element borders. Between card and input in weight. | -| `--border-divider` | `#e8e2d8` | Artifact sidebar dividers, table row separators, panel borders. | -| `--border-divider-light` | `#f0ebe4` | Scout table internal row separators. Very faint. | +| Token | Value | Usage | +| ------------------------- | --------- | ----------------------------------------------------------------------------- | +| `--padding-card-settings` | 22px 26px | Settings section cards. | +| `--padding-entity-row` | 12px 16px | Entity rows (profile rows, installation rows). | +| `--padding-inline-form` | 22px 26px | Inline edit/create forms. Matches settings card padding for visual alignment. | -### Semantic status colors +### Page-level spacing -These are used exclusively for scout status indicators and similar operational state. +| Token | Value | Usage | +| ---------------------- | ----- | ----------------------------------------------------------------- | +| `--settings-nav-width` | 152px | Side navigation column width on the Settings page. | +| `--settings-max-width` | 960px | Max width for the Settings page layout container (nav + content). | -| Token | Hex | Usage | -|---|---|---| -| `--status-running` | `#d4775a` | Running scout dots, active step labels. Same as orange accent. | -| `--status-done` | `#5a9a8a` | Completed scout dots. Same as teal accent. | -| `--status-queued` | `#b8aca0` | Queued count text. Desaturated warm. | -| `--status-failed` | `#c44` | Failed count text. Standard red — used sparingly. | +--- -### Derived colors +## Atoms -These are derived from core tokens for specific UI effects. Not part of the primary palette. +### TextInput -| Token | Value | Usage | -|---|---|---| -| `--overlay-backdrop` | `rgba(46, 58, 94, 0.45)` | Navy-tinted translucent backdrop for modals and overlays. | -| `--focus-ring` | `rgba(212, 119, 90, 0.12)` | Orange-derived focus ring glow for input fields. | -| `--flash-teal` | `rgba(90, 154, 138, 0.12)` | Teal-derived background flash for result animations. | +Shared text input used in settings forms, NewRunForm textarea, NewRunForm concurrency input, RadioOption/CheckboxOption custom text input, and FeedbackInput textarea. -## Typography +**Field variant (default):** Background `--bg-base`, `1.5px solid --border-input`, `--radius-lg`. Padding: 8px 12px. Font: `--font-body`, 13px, `--text-primary`. Placeholder: `--text-placeholder`. Focus: border-color `--color-orange`, box-shadow `0 0 0 3px var(--focus-ring)`. Error state: border-color `--status-failed`. Disabled: opacity 0.5. -### Font families +**Inline variant:** Transparent background, no side/top borders, `border-bottom: 1px solid --border-card`. Padding: 8px 0. Focus: border-bottom-color `--border-input`. Used inside RadioOption and CheckboxOption for the custom "Other" text input. -| Token | Value | Usage | -|---|---|---| -| `--font-display` | System serif stack (Georgia, "Times New Roman", serif) | Logo "koan" wordmark only. | -| `--font-body` | System sans-serif stack (-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif) | All UI text, headings, labels, prose, form elements. | -| `--font-mono` | Monospace stack ("SF Mono", "Fira Code", "Cascadia Code", monospace) | File paths, tool call commands, scout names, code inline, timestamps, model names, artifact filenames. | +**Mono modifier:** When `mono` is true, uses `--font-mono` at 13px. For file paths, extra args, and technical identifiers. -### Type scale +**Textarea mode:** When rendered as `<textarea>`, uses field variant styling with `min-height: 80px`, `resize: vertical`. Used in NewRunForm description field and FeedbackInput. -All weights are 400 (regular) or 500 (medium). Never use 600 or 700. +Props: `value`, `onChange`, `placeholder`, `variant?: 'field' | 'inline'`, `mono?: boolean`, `error?: boolean`, `disabled?: boolean`, `as?: 'input' | 'textarea'`. -| Token | Size | Weight | Usage | -|---|---|---|---| -| `--type-page-title` | 26px | 500 | "New Run" page title. Letter-spacing: -0.5px. | -| `--type-logo` | 17px | 500 | "koan" wordmark in header. Uses `--font-display`. Letter-spacing: -0.3px. | -| `--type-section-title` | 17px | 500 | "Gather Summary" and similar section headings within prose cards. | -| `--type-step-header` | 16px | 500 | Step name next to step indicator ("Gather", "Summarize"). | -| `--type-prose` | 15px | 400 | Agent prose output, decision question text, form field values. Line-height: 1.7. | -| `--type-body` | 14px | 400 | Body text within cards (findings, decisions list items, context descriptions). Line-height: 1.65. | -| `--type-step-indicator` | 14px | 500 | "step 1/3", "step 3/3" colored labels. | -| `--type-breadcrumb` | 13px | 400/500 | Header breadcrumb segments (400 for inactive, 500 for active). | -| `--type-tool-type` | 12px | 400 | Tool call type label ("bash", "read", "edit"). Uses `--text-muted`. | -| `--type-tool-path` | 12px | 400 | Tool call file paths. Uses `--font-mono`. | -| `--type-label` | 11px | 500 | Section labels ("ARTIFACTS", "CONTEXT", "DECISION", "SCOUTS", "THINKING"). Uppercase, letter-spacing: 1px. | -| `--type-badge` | 10px | 500 | "coming soon", "recommended", model badges, scout column headers. | -| `--type-timestamp` | 10px | 400 | "modified 2m ago" artifact timestamps. | +### Select -### Inline code +Shared dropdown select used in settings profile/installation forms, NewRunForm profile and installation dropdowns, and standalone preference selects. -Code tokens within prose use: `background: var(--bg-tool-row); padding: 1px 5px; border-radius: 3px; font-size: one step below surrounding text; color: var(--text-primary); font-family: var(--font-mono)`. +Background `--bg-base`, `1.5px solid --border-input`, `--radius-lg`. Padding: 8px 28px 8px 12px. Font: `--font-body`, 13px, `--text-primary`. When `mono` is true, uses `--font-mono` at 13px. Used for selects displaying technical identifiers (runner types in installation forms). Custom chevron: 10×6px SVG arrow, stroke `--text-muted`, positioned via `background-image` at `right 10px center`. `-webkit-appearance: none; appearance: none`. Focus: border-color `--color-orange`. Disabled: opacity 0.5. Placeholder option (no value selected): `--text-placeholder`. -## Spacing +Props: `value`, `onChange`, `options: { value: string, label: string }[]`, `placeholder?: string`, `disabled?: boolean`, `mono?: boolean`. -### Page-level spacing +### Toggle -| Token | Value | Usage | -|---|---|---| -| `--page-padding` | 28px 32px | Main content area padding. | -| `--sidebar-padding` | 20px 16px | Artifacts sidebar padding. | -| `--header-height` | 50px | Header bar fixed height. | -| `--form-max-width` | 640px | Max width for standalone form pages ("New Run"). Centered. | -| `--form-page-padding` | 40px 24px | Padding around centered form content. | +A boolean switch for auto-saving preferences (auto-open artifacts, sandbox execution, verbose debug output). -### Component gaps +Track: 36px wide, 20px tall, `--radius-pill`. Off state: `--bg-toggle-off`. On state: `--color-teal`. Thumb: 16px diameter, `--bg-card` (white), `--radius-circle`. Off position: `left: 2px`. On position: `left: 18px`. Transition: background and left, `--duration-fast`. Disabled: opacity 0.5. -| Token | Value | Usage | -|---|---|---| -| `--gap-content` | 20px | Between major content blocks in the stream (thinking → prose → tools → thinking). | -| `--gap-tool-rows` | 3px | Between individual tool call rows within a group. | -| `--gap-artifact-cards` | 10px | Between artifact cards in the sidebar. | -| `--gap-form-sections` | 28px | Between form card sections on the "New Run" page. | -| `--gap-radio-options` | 10px | Between radio option cards in elicitation. | -| `--gap-scout-summary` | 16px | Between scout summary count groups. | -| `--gap-progress-segments` | 3px | Between progress bar segments in header. | +Auto-saves on click. The parent component handles the API call — no explicit save UI. -### Component internal padding +Props: `checked: boolean`, `onChange: (checked: boolean) => void`, `disabled?: boolean`. + +### NumberInput + +A compact numeric input for scalar configuration values (scout concurrency, limits). + +Width: 48px. Center-aligned text. Font: `--font-mono`, 13px. Otherwise identical to TextInput field variant (`--bg-base`, `1.5px solid --border-input`, `--radius-lg`, padding 8px 0). Focus: border-color `--color-orange`. + +Auto-saves on blur. The parent component handles the API call — no explicit save UI. + +Props: `value: number`, `onChange: (value: number) => void`, `min?: number`, `max?: number`, `disabled?: boolean`. + +### Buttons — sizes and variants + +**Sizes:** + +- `xs`: padding 2px 10px, font-size 12px, `--radius-md`. Used for compact inline actions on entity rows (Edit, Delete, Explore). +- `sm`: padding 5px 16px, font-size 13px, `--radius-md`. Used for form-level actions (Cancel, Save in InlineForm) and utility actions inside form rows (Detect). +- `md`: padding 10px 28px, font-size 15px, `--radius-lg`. Used for page-level actions (Start Run, Submit, Next). + +**Danger variant:** At `xs` and `sm` sizes: `--status-failed` text, `1px solid --border-danger`, `--radius-md`. Used for Delete actions on entity rows (`xs`) and form-level destructive actions (`sm`). At `md` size: `--status-failed` background, white text, `--radius-lg`. Used in destructive confirmation dialogs. + +**Teal variant:** `--color-teal` text, `1px solid --border-teal`, `--radius-md`. Available at `xs` and `sm` sizes. Used for utility actions: Detect (find binary path), Explore (view session). + +**Text variant:** `--color-orange` text, font-weight 500, no border, no background, no padding. Used for add triggers ("+ New profile", "+ Add claude installation"). + +Type: `Variant = 'primary' | 'secondary' | 'danger' | 'teal' | 'text'`, `Size = 'xs' | 'sm' | 'md'`. + +### Badges + +Variant type: `'neutral' | 'success' | 'accent' | 'model' | 'default' | 'error'`. + +**Default variant:** text `#c06030` (darkened orange), background `#fdf2ee` (orange-tinted). Used for "default" installation labels. + +**Error variant:** text `--status-failed`, background `--bg-danger`. Used for "unavailable" status. + +--- + +## Molecules + +### Stream Molecules + +#### RadioOption + +A selectable option card for elicitation questions (single-select mode). + +Container: `--padding-radio` (12px 14px), `--radius-lg`, `1.5px solid --border-radio`. Cursor: pointer. Transition: border-color and background, `--duration-fast`. + +Selected state: `border-color: --color-orange`, `background: --bg-selected`. + +Recommended state: `border-left: 3px solid --color-orange`, `background: --bg-selected`. No padding adjustment — the 1.5px content shift from the thicker border is sub-pixel. When recommended and selected simultaneously, selected wins: `border-left-width` resets to `1.5px` for a uniform orange border. + +Contains a radio circle (18px, `2px solid --border-input`, selected: `--color-orange` with 8px inner dot), label text (`--type-body`, `--text-primary`), and optional custom text input (inline variant TextInput, visible when `isCustom && selected`). + +Props: `label`, `selected?: boolean`, `recommended?: boolean`, `isCustom?: boolean`, `customText?: string`, `onCustomTextChange?: (text: string) => void`, `onClick?: () => void`. + +#### CheckboxOption + +A selectable option card for elicitation questions (multi-select mode). Identical to RadioOption except: square checkbox (18px, `--radius-sm`, `2px solid --border-input`, selected: `--color-orange` fill with white checkmark SVG). + +Same recommended treatment as RadioOption: `border-left: 3px solid --color-orange`, `background: --bg-selected`. Selected+recommended resets `border-left-width` to `1.5px`. + +Props: same as RadioOption. + +#### YieldPanel + +A self-contained command panel rendered in the content stream when the orchestrator yields for a phase transition decision. + +Container: `--bg-card`, `0.5px solid --border-card`, `--radius-2xl` (12px), `overflow: hidden`. + +Header: `padding: var(--padding-card)` (14px 20px), `border-bottom: 1px solid --border-divider-light`. Prompt text: `--font-body`, `--type-body` (14px), font-weight 500, `--text-primary`, `line-height: 1.4`. The orchestrator provides the prompt text (e.g., "Intake is complete. What would you like to do next?"). + +Body: `padding: 2px 0`. + +Command row: `display: flex; align-items: flex-start; gap: 14px; padding: 11px 20px`. Cursor: pointer. Hover: `background: var(--bg-card-warm)`. Transition: `background var(--duration-fast) var(--ease-default)`. Adjacent rows separated by `border-top: 0.5px solid --border-divider-light`. Clicking a row sets `chatDraft` to `/${suggestion.id} ` (slash, phase ID, trailing space). + +Command name column: `--font-mono`, `--type-breadcrumb` (13px), font-weight 500, `--text-primary`, `white-space: nowrap`, `flex-shrink: 0`, `min-width: 100px`. The `/` prefix rendered as `<span>` with `color: --color-orange`. + +Description column: `--font-body`, `--type-breadcrumb` (13px), `--text-muted`, `line-height: 1.4`, `flex: 1`, `min-width: 0`. + +Recommended row: `border-left: 3px solid --color-orange`, `padding-left: 17px` (20px minus 3px border), `background: --bg-selected`. Command name color: `--color-orange`. At most one recommended row per panel. + +Props: `prompt: string`, `suggestions: Suggestion[]`, `onSelect: (suggestion: Suggestion) => void`. + +#### CommandPalette + +A floating dropdown anchored above FeedbackInput, triggered when the user types `/` as the first character during a yield point. Shows all available phases in the current workflow, filterable as the user types. + +Availability: only when `run.isYielded` is `true`. Gated by `availableCommands` prop on FeedbackInput — when undefined or empty, `/` is regular text. + +Positioning: `position: absolute`, `bottom: 100%`, `left: 0`, `right: 0`, `margin-bottom: 6px`. FeedbackInput's `.fi` container provides `position: relative`. + +Container: `--bg-card`, `0.5px solid --border-card`, `--radius-2xl` (12px), `overflow: hidden`. Box-shadow: `0 4px 16px rgba(46,58,94,0.10)` (hardcoded, candidate for future `--shadow-dropdown` token). `z-index: 10`. + +Backdrop: content stream receives `opacity: 0.35` when the palette is open. Dismissed by Escape, clicking outside, or deleting the `/`. + +Hint bar: `padding: 10px 16px`, `background: var(--bg-base)`, `border-bottom: 1px solid --border-divider-light`. Info icon (14px circle, `1.5px solid --border-input`, "i" in `--text-muted`, 9px) + hint text: `--type-tool-type` (12px), `--text-muted`. Text: "Select a command or keep typing to filter". + +Palette items: `padding: 10px 16px`. Hover / keyboard-active: `background: var(--bg-tool-row)`. Transition: `background var(--duration-fast) var(--ease-default)`. Adjacent items separated by `border-top: 0.5px solid --border-divider-light`. Max visible before scrolling: 5. + +Item command name: `--font-mono`, `--type-breadcrumb` (13px), font-weight 500, `--text-primary`, `margin-bottom: 2px`. `/` prefix: `color: --color-orange`. + +Item description: `--type-tool-type` (12px), `--text-muted`, `line-height: 1.3`. + +Keyboard: `↑`/`↓` navigate, `Enter` selects, `Escape` closes and clears the `/`. Filtering by prefix match on command name. Empty state: "No matching commands" centered in `--text-muted`. + +Selection inserts `/${command.id} ` into FeedbackInput. Cursor placed after trailing space. + +Props: `commands: PhaseCommand[]`, `filter: string`, `activeIndex: number`, `onSelect`, `onNavigate`, `onDismiss`. + +Component ownership: molecule rendered by FeedbackInput. Palette state is local to FeedbackInput. + +#### PhaseMarker + +An event divider rendered in the content stream when a phase transition occurs. The teal dot sits on a horizontal rule, acting as a timeline node. The phase label and description flow to the right on the same line. + +Container: `padding: 20px 0`, `position: relative`. + +Horizontal rule: `position: absolute`, `left: 0`, `right: 0`, `top: 50%`, `transform: translateY(-50%)`, `height: 1px`, `background: var(--border-divider)`. Spans the full content width behind the content group. + +Content overlay: `position: relative`, `display: flex`, `align-items: center`, `gap: 10px`, `background: var(--bg-base)`, `padding-right: 16px`. The background creates a visual break in the rule behind the content. + +Teal dot: 10px diameter, `background: var(--color-teal)`, `var(--radius-circle)`, `flex-shrink: 0`. + +"Phase:" label: `--type-label` (11px), `text-transform: uppercase`, `letter-spacing: 1px`, font-weight 500, `--text-muted`. + +Phase name: `--type-breadcrumb` (13px), font-weight 500, `--color-teal`. + +Separator: "·" in `--text-muted`. + +Description: `--font-body`, `--type-breadcrumb` (13px), `--text-muted`. + +Props: `name: string`, `description: string`. + +#### FeedbackInput + +Text input for sending messages to the orchestrator. Sits at the bottom of the content stream. + +Container: `--bg-card`, `1.5px solid --border-input`, `--radius-xl` (10px), `var(--padding-input)` (14px 18px). `position: relative` (provides positioning context for CommandPalette). + +Focused state (palette open): `border-color: var(--color-orange)`, `box-shadow: 0 0 0 3px var(--focus-ring)`. + +Textarea: `--font-body`, `--type-body` (14px), `--text-primary`. Placeholder: `--text-placeholder`. No border, transparent background. + +Footer: flex row. Left: hint text in `--type-label` (11px), `--text-hint`. Default: "Enter to send · Shift+Enter for newline". Palette open: "↑↓ navigate · Enter select · Esc dismiss". Right: Button primary `sm`. + +**`/`-command support:** When the input value starts with `/` and `availableCommands` is provided, the CommandPalette renders above the input. When a `/`-command message is sent, FeedbackInput transforms it before calling `onSend`: + +- `/plan-spec write an implementation plan` → `The user wishes to transition to phase \`plan-spec\` with instruction: write an implementation plan` +- `/plan-spec` (no instruction) → `The user wishes to transition to phase \`plan-spec\`.` + +Props: `placeholder?: string`, `onSend?: (text: string) => void`, `disabled?: boolean`, `availableCommands?: PhaseCommand[]`, `onPaletteToggle?: (open: boolean) => void`. + +### Settings Molecules + +#### FormRow + +Label + control(s) horizontal layout. Used inside InlineForm. + +Container: `display: flex; align-items: center`. Rows separated by `--gap-form-rows` (12px) via margin-bottom. -| Token | Value | Usage | -|---|---|---| -| `--padding-card` | 14px 20px | Prose output cards. | -| `--padding-card-form` | 20px 24px | Form section cards, context/decision panels. | -| `--padding-tool-row` | 7px 14px | Individual tool call rows. | -| `--padding-step-guidance` | 8px 16px | Step guidance pill. | -| `--padding-artifact` | 10px 12px | Artifact cards in sidebar. | -| `--padding-scout-bar` | 14px 24px | Scout bar outer padding. | -| `--padding-scout-row` | 8px 14px | Scout table rows. | -| `--padding-input` | 14px 18px | Feedback input area. | -| `--padding-radio` | 12px 14px | Radio option cards. | +Label: `--type-label` (11px), font-weight 500, `--text-muted`, uppercase, letter-spacing 0.5px. Width: 82px, `text-align: right`, `padding-right: 16px`, `flex-shrink: 0`. -## Border Radius +Controls container: `flex: 1; display: flex; gap: var(--gap-form-controls)` (8px). Contains one or more TextInput or Select atoms. -| Token | Value | Usage | -|---|---|---| -| `--radius-sm` | 3px | Inline code tags, model badges. | -| `--radius-md` | 6px | Tool call rows, progress bar segments, small buttons. | -| `--radius-lg` | 8px | Artifact cards, scout table, step guidance pill, input fields, form dropdowns. | -| `--radius-xl` | 10px | Prose cards, thinking blocks, feedback input, completion banner, radio options. | -| `--radius-2xl` | 12px | Form section cards, context/decision panels, page-level container. | -| `--radius-pill` | 20px | Pill-shaped badges ("coming soon", "recommended"). | -| `--radius-circle` | 50% | Status dots, radio buttons, logo circles, orchestrator dot. | +Props: `label: string`, `children: ReactNode`. -## Component Specifications +#### EntityRow -### Header bar +A two-line list item for configuration entities: profiles, agent installations. -The header is a fixed 50px bar with `--color-navy` background. It contains the logo, breadcrumb navigation, progress segments, orchestrator info, elapsed time, and settings button. It spans the full width of the viewport. +Container: `--padding-entity-row` (12px 16px), `--radius-lg`, `0.5px solid --border-card`. Margin-bottom: `--gap-entity-rows` (8px). -The logo is the "koan" wordmark in `--font-display` at 17px/500, colored `--text-on-dark`. To the left of the wordmark are two overlapping circles: a 16px circle in `--color-orange` (top-left) and a 10px circle in `--color-teal` (bottom-right). This geometric motif is the brand mark. +Line 1: `display: flex; align-items: center; gap: 8px`. Entity name: 14px/500 `--text-primary`. For technical identifiers (installation aliases): 13px/500 `--font-mono`. Badges sit inline after the name. Action buttons pushed right via `flex: 1` spacer before them. -A 1px vertical divider at `rgba(255,255,255,0.15)` separates the logo from the breadcrumb. The breadcrumb shows phase and step as `Phase > Step` with a small chevron. The inactive segment uses `--text-on-dark-muted`, the active segment uses `--text-on-dark` at weight 500. +Line 2: 12px `--text-muted`, `margin-top: 5px`. Uses `--font-mono` for tier summaries and file paths. -Progress segments are 24px wide, 4px tall, with `--radius-md`. Completed segments use `--color-teal`, the active segment uses `--color-orange`, and future segments use `--text-on-dark-faint`. Gap between segments: 3px. +Active state (entity is being edited): border changes to `1.5px solid --color-orange`, visually connecting the row to the InlineForm below it. -The settings button is a 30px square with `--radius-lg`, 1px border in `--text-on-dark-faint`, containing a 14px gear SVG icon stroked at `rgba(240,232,216,0.6)`. +Props: `name: string`, `mono?: boolean`, `badges?: BadgeProps[]`, `meta?: string`, `actions?: ReactNode`, `active?: boolean`. -### Prose output card +#### TabBar -White card (`--bg-card`) with `--radius-xl`, `0.5px solid --border-card` on all sides, plus a 3px `--color-orange` left border. Padding: `--padding-card`. Text is `--type-prose` in `--text-primary`. These cards contain the agent's spoken output — everything the agent says directly to the user (as opposed to thinking or tool calls). +Horizontal category switcher. Used for agent installation runner types. -### Thinking block +Container: `display: flex; gap: 20px; border-bottom: 1px solid --border-divider; margin-bottom: 18px`. -Lavender block (`--bg-thinking`) with `--radius-xl`. Padding: 16px 20px. Contains a label row with a small 14px navy circle (with a 6px `#b8b0d0` inner circle) followed by "THINKING" in `--type-label` at `--text-thinking-label`. Body text is `--type-body` in `--text-thinking`. +Each tab: `--font-body`, 13px, `padding-bottom: 8px; border-bottom: 2px solid transparent; margin-bottom: -1px` (overlaps container border). Cursor: pointer. No background, no side padding, no border-radius. -### Tool call row +Active tab: `--text-primary`, font-weight 500, `border-bottom-color: --color-orange`. +Inactive tab: `--text-muted`, font-weight 400. -Background `--bg-tool-row`, `--radius-md`, padding `--padding-tool-row`. Contains a 13px teal checkmark SVG, a tool type label ("bash", "read", "edit") in `--type-tool-type` and `--text-muted` with min-width 36px, and the command/path in `--type-tool-path` and `--font-mono` colored `var(--text-body)`. Rows within a group are spaced `--gap-tool-rows` apart. +Props: `tabs: string[]`, `activeTab: string`, `onChange: (tab: string) => void`. -### Step guidance pill +#### SettingRow -Inline-flex element with `--bg-step-guidance`, `--radius-lg`, padding `--padding-step-guidance`. Contains an 8px circle in `--color-orange` (or `--color-teal` when step is complete), label text in `--text-subtle` at 13px/500, and a 10px chevron-down SVG. Aligns to `flex-start` (left-aligned, not full-width). +A horizontal layout for individual auto-saving preference controls: label + description on the left, compact control on the right. -### Artifact card +Container: `display: flex; align-items: flex-start; gap: 16px; padding: 14px 0`. Adjacent SettingRows are separated by a `0.5px solid --border-card` top border. -Background `--bg-card-warm` (`#faf8f4` — slightly warmer than pure white to distinguish from prose cards), `--radius-lg`, `0.5px solid --border-divider`, padding `--padding-artifact`. Contains a 28px square icon with `--radius-lg`: navy background with a lavender file SVG for recently modified artifacts, or teal background with a light-teal file SVG for older/stable artifacts. Next to the icon: filename in `--font-mono` at 12px/500 in `--text-primary`, and timestamp in `--type-timestamp` at `--text-artifact-time`. +Left side (`flex: 1`): Label in 14px/500 `--text-primary`. Description in 12px `--text-muted`, `margin-top: 3px`, `line-height: 1.4`. -### Scout bar +Right side (`flex-shrink: 0`, `margin-top: 2px`): any compact control — Toggle, Select, or similar. The 2px top margin aligns the control with the label baseline. -Navy frame (`--color-navy`) with padding `--padding-scout-bar`. The summary line sits directly on navy: an 8px orange dot, "SCOUTS" label in `--text-on-dark-muted` at `--type-label`, then count groups (e.g., "3 running") where the number uses the appropriate status color and the label uses `--text-on-dark-scouts-muted`. +Props: `label: string`, `description?: string`, `children: ReactNode`. -Below the summary, a white table card (`--bg-card-warm`) with `--radius-lg` and no outer border. The table has a header row with column labels in `--type-badge` / `--text-muted`, uppercase, with a `0.5px solid --border-divider` bottom border. Data rows use `--padding-scout-row` with `0.5px solid --border-divider-light` separators (no border on the last row). +#### InlineForm -Table columns: status dot (20px col, 6px dot in status color), name (flex, `--font-mono` 12px/500 in `--text-primary`), model (60px, `--text-muted` 11px), tools (60px, `--text-muted`), elapsed (70px, `--text-muted`), status (flex, `--color-orange` for active steps). +An expandable edit/create region that appears inline below entity rows within a settings section card. -### Feedback input +Container: `1.5px solid --color-orange`, `--radius-xl` (10px), `--padding-inline-form` (22px 26px), `--bg-card`. The orange border signals "user input expected here." -White card (`--bg-card`), `--radius-xl`, `1.5px solid --border-input` (this is intentionally darker than card borders for definition). Padding `--padding-input`. Placeholder text in `--text-placeholder`. Below: hint text in `--text-hint` at 11px left-aligned, and a "Send" button right-aligned with `--color-orange` background, white text, `--radius-md`, padding 5px 16px, 13px/500. +Contains FormRow children and a form actions row. Form actions: `display: flex; gap: 8px; margin-top: 20px; padding-left: 82px` (aligns with the left edge of form controls). Contains Cancel (Button secondary) and Save (Button primary). -### User bubble +InlineForm is the only place where explicit Save buttons appear in configuration UI. All standalone controls (Toggle, NumberInput, standalone Select in SettingRow) auto-save on interaction. -The user's own messages in the content stream. Visually distinct from agent prose (orange border) via a gray left border. Background `--bg-card`, `--radius-xl`, `0.5px solid --border-card`, `border-left: 3px solid --text-muted`. Padding: `--padding-card`. Text: `--type-prose` in `--text-primary`, line-height 1.7. Optional timestamp below in `--type-timestamp` / `--text-muted`. +Props: `children: ReactNode`, `onSave: () => void`, `onCancel: () => void`, `saving?: boolean`. -Props: `children: ReactNode`, `timestamp?: string`. +#### NavItem -### Phase boundary +A side navigation item for the Settings page. -Visual separator between workflow phases. A centered label between two horizontal lines. Container: flex, align-items center, gap 12px, padding 20px 0. Lines: flex 1, height 1px, background `--border-divider`. Label: `--type-label`, `--text-muted`, uppercase, letter-spacing 1px, font-weight 500, white-space nowrap. +`display: block; font-size: 13px; --font-body; padding: 6px 16px; border-left: 2px solid transparent; cursor: pointer; margin-bottom: 1px`. -Props: `label: string`. +Active: `font-weight: 500; color: --text-primary; border-left-color: --color-orange`. +Inactive: `font-weight: 400; color: --text-muted`. +Hover (inactive): `color: --text-subtle`. -### Step header +No background on any state. No border-radius. -Step indicator at the top of each step's content stream. Shows "step N/M" in accent color followed by the step name. Container: flex, align-items center, gap 10px. Step label: `--type-step-indicator` (14px), font-weight 500. Active steps: `--color-orange`. Completed steps: `--color-teal`. Step name: `--type-step-header` (16px), font-weight 500, `--text-primary`. +Props: `label: string`, `active: boolean`, `onClick: () => void`. -Props: `stepNumber: number`, `totalSteps: number`, `stepName: string`, `status?: 'active' | 'complete'`. +--- -### Completion banner +## Organisms -Phase completion message. Success variant: background `--bg-completion`, `--radius-xl`, padding 14px, text centered in `--text-completion` at `--type-body`. Error variant: background `--bg-base`, `--status-failed` text and 1px border. +### SettingsPage -Props: `children: ReactNode`, `variant?: 'success' | 'error'`. +Full-page settings view accessible via "Settings" in the header navigation. -### Steering bar +Two-column flex layout within a centered container (`--settings-max-width`, 960px, `margin: 0 auto`). Left column: stack of NavItem elements (`--settings-nav-width`, 152px, `padding: 36px 0`, `flex-shrink: 0`). Right column: content area (`flex: 1`, `padding: 36px 0 36px 28px`, `min-width: 0`, `overflow-y: auto`). -Queued steering messages from the user, shown above the FeedbackInput. Container: background `--bg-selected`, `border-left: 3px solid --color-orange`, `border-radius: 0 --radius-md --radius-md 0`, margin 8px 0. Header: "steering" label in `--font-mono`, `--type-label`, `--color-orange`. Each message: "queued" badge in `--type-label` / `--text-muted`, content in `--type-breadcrumb` / `--text-body`. Returns null when no messages. +Content area shows: section title (20px/500 `--text-primary`, letter-spacing -0.3px, margin-bottom 6px), section description (13px `--text-muted`, margin-bottom 22px), then one or more section cards. -Props: `messages: string[]`. +Section cards: `--bg-card`, `--radius-2xl` (12px), `0.5px solid --border-card`, `--padding-card-settings` (22px 26px). -### Checkbox option card +Only the active section renders. Side nav controls which section is visible. -Multi-select variant of the radio option card. Structurally identical to RadioOption but with a square checkbox (18px, `--radius-sm`, `2px solid --border-input`). When selected: border `--color-orange`, filled with `--color-orange`, white checkmark SVG inside. All other styling matches RadioOption. +**Sections:** -Props: same as RadioOption (`label`, `selected`, `recommended`, `isCustom`, `customText`, `onCustomTextChange`, `onClick`). +- **Profiles:** EntityRows + InlineForm for create/edit + Button text trigger. All inside a section card. +- **Agents:** TabBar for runner types + EntityRows for installations + InlineForm for create/edit. All inside a section card. +- **Runtime:** NumberInput for scout concurrency (with heading above), then SettingRows with Toggle/Select controls. Hairline `0.5px solid --border-card` divider separates the scalar controls from the SettingRow list. All inside a section card. +- **Preferences, Debug, About:** future sections using the same patterns. -### Form cards (New Run page) +--- -White card (`--bg-card`), `--radius-2xl`, `0.5px solid --border-card`, padding `--padding-card-form`. Section label in `--type-label` / `--text-muted` at the top. Form inputs use `background: --bg-base`, `1.5px solid --border-input`, `--radius-lg`, padding 10px 14px. +## Header Bar -### Workflow selection cards (New Run page) +The header bar operates in two modes: -Two cards side by side in a 2-column grid with 12px gap. The selected card has `2px solid --color-orange` border, `--bg-selected` background, and a filled radio circle (16px outer circle with 2px orange border, 8px filled orange inner). The unselected/disabled card has `1.5px solid --border-radio` border, opacity 0.6 for disabled state. +**Navigation mode:** Used on the New Run, Sessions, and Settings pages. The zone right of the logo divider shows top-level navigation links: "New run", "Sessions", "Settings". Each link: `--type-breadcrumb` (13px), `--font-body`. Active page: `--text-on-dark`, font-weight 500. Inactive pages: `--text-on-dark-muted`, font-weight 400. Links separated by 6px gap. -### Elicitation panels (Deepen view) +**Workflow mode:** Used during an active workflow run. The zone right of the logo divider shows the phase/step breadcrumb and progress segments. Navigation links are not shown. -Two-panel 1fr/1fr grid with 20px gap (single column when no context). Each panel is a white card (`--bg-card`) with `--radius-2xl` and `0.5px solid --border-card`. The Context panel (optional) has a 3px `--color-teal` top border. The Decision panel has a 3px `--color-orange` top border. Panel labels use the respective accent color for text. +Settings is accessed via the "Settings" navigation link. There is no separate settings icon in the header. -Supports three modes: `single-select` (RadioOption), `multi-select` (CheckboxOption with "Select all that apply" hint), and `free-text` (textarea only). Supports multi-question pagination with a "N / M" counter and Previous/Next buttons. Error messages displayed below options in `--status-failed`. +--- -The NewRunForm organism is self-contained: it reads profiles and installations directly from the Zustand store, manages all form state internally, and calls the API to start a run. No props required. +## Layout: Settings View -Agent installation rows: each row has a runner chip (background `--bg-thinking` lavender, `--radius-md`, padding 6px 12px, runner name in `--font-mono` 13px/500 `--text-thinking`, StatusDot sm) followed by an installation `<select>` dropdown (same styling as profile select but at 13px). Multiple rows stack with 10px gap. +Used for the Settings page. Two-column layout: side navigation + scrollable content area. -### Radio option cards (Deepen view) +``` +Structure: + Flex column (100vh, overflow: hidden): + ├─ HeaderBar (flex-shrink: 0, full viewport width, navigation mode) + └─ Centered container (flex: 1, min-height: 0, max-width: 960px, margin: 0 auto) + ├─ Side nav (width: 152px, padding: 36px 0, flex-shrink: 0) + │ └─ Stack of NavItem elements + └─ Content area (flex: 1, padding: 36px 0 36px 28px, min-width: 0, + overflow-y: auto) + ├─ Section title (20px/500, --text-primary, letter-spacing: -0.3px) + ├─ Section description (13px, --text-muted, margin-bottom: 22px) + └─ Section card(s) (--bg-card, --radius-2xl, --padding-card-settings) + └─ Section-specific content +``` -Each option is a label element with `--radius-lg`, `1.5px solid --border-radio`, padding `--padding-radio`. Contains an 18px circle with `2px solid --border-input` (unfilled state) or `2px solid --color-orange` with 8px filled inner (selected state). The "recommended" badge uses `background: --bg-completion; color: --text-completion` (teal-green family), `--radius-pill`, `--type-badge`. +No ArtifactsSidebar. No ScoutBar. Header in navigation mode. -When `isCustom` is true and selected, a text input appears below the label (8px top margin, full-width, transparent background, bottom-border-only: --border-card default, --border-input on focus, placeholder "Type your response..." in --text-placeholder). Hidden when not selected. +--- -### Buttons +## Design Rationale -Primary: `--color-orange` background, white text, `--radius-lg` (8px for larger buttons, 6px for small), 13-15px/500. Used for "Start Run", "Next", "Send". +### Border weight rules -Secondary/outline: `1.5px solid --border-input`, `--text-subtle`, `--radius-lg`. Used for "Use Defaults". +Two border weight tiers: -## Content Stream Rendering +- **`0.5px solid`** — cards, panels, dividers. Used for ProseCard, UserBubble, ElicitationPanel, YieldPanel, CommandPalette, EntityRow, section cards. These are passive containers. +- **`1.5px solid`** — input fields and active editing regions. Used for TextInput, Select, FeedbackInput, InlineForm (with `--color-orange`), EntityRow active state. These are interactive input surfaces. -The content stream maps each conversation event type to a molecule: +The `1.5px` weight is never used for cards or panels. The `0.5px` weight is never used for input fields. -| Event type | Molecule | Notes | -|---|---|---| -| `thinking` | ThinkingBlock + Md | Collapsible, lavender background | -| `text` | ProseCard + Md | Orange left border, white card | -| `tool_read/write/edit` | ToolCallRow | status from `inFlight` flag | -| `tool_bash/grep/ls` | ToolCallRow | status from `inFlight` flag | -| `tool_generic` | ToolCallRow | uses `toolName` + `summary` | -| `step` | StepHeader | orange (active) or teal (complete) | -| `debug_step_guidance` | StepGuidancePill + Md | collapsed by default | -| `user_message` | UserBubble + Md | gray left border, with timestamp | -| `phase_boundary` | PhaseBoundary | centered label between lines | -| `pendingThinking` | ThinkingBlock (always expanded) | live streaming | -| `pendingText` | ProseCard + Md + streaming cursor | pulsing cursor animation | -| steering messages | SteeringBar | orange accent bar with queued badges | +### Orange semantics -The FeedbackInput molecule sits at the bottom of the stream, above any SteeringBar messages. +Orange is used at three weight tiers, each with a distinct meaning: -## Layout +- **`3px solid` left accent** — "suggested default." Applied to the recommended option in RadioOption/CheckboxOption and the recommended command row in YieldPanel. Draws the eye without demanding action. Paired with `--bg-selected` background tint. This is the weakest orange signal. +- **`1.5px solid` full border** — "user input expected." Applied to selected RadioOption/CheckboxOption cards and InlineForm active regions. Signals an active editing surface. When an option is both recommended and selected, the `1.5px` full border takes precedence over the `3px` left accent (uniform border wins). +- **`3px solid` top accent** — "panel-level attention." Applied to ElicitationPanel decision panel. The strongest orange signal, used at the organism level. -### Page frame +### Teal for system events -The page is a flex column filling `100vh`. Three direct children: +`--color-teal` is used for system-level indicators: status dots (done/running), CompletionBanner, PhaseMarker labels, teal-variant buttons for utility actions. Phase transitions are system events — the teal PhaseMarker label distinguishes it from agent content (orange accent) and user content (gray left border). -1. **HeaderBar** — `flex-shrink: 0`, full viewport width, `--color-navy` background. -2. **Centered container** — `flex: 1`, `min-height: 0`, `max-width: 1400px`, `margin: 0 auto`, `width: 100%`. Contains the content+sidebar grid. -3. **ScoutBar** (conditional) — `flex-shrink: 0`, full viewport width, `--color-navy` background. Omitted when no scouts are active. +### Dot-on-divider = event -The HeaderBar and ScoutBar span the full viewport width. The centered container constrains the content grid to 1400px. On wide screens, the space beyond the container edges is `--bg-base` background. No pseudo-elements. No `overflow-x: hidden`. +A teal dot sitting on a horizontal rule signals a system event — something structural happened in the workflow. PhaseMarker uses this pattern for phase transitions. The dot interrupts the divider line and anchors the event label to its right. This pattern is distinct from content cards (which have borders and padding) and section labels (which sit above content). Events happen between content; cards contain content. -### Two-column workflow view +### Left border = content source -Used during active workflow phases (Gather, Deepen, Summarize). The centered container is a CSS grid with `grid-template-columns: minmax(0, 1fr) 260px`, filling the height between header and scout bar. The content column (left) scrolls vertically (`overflow-y: auto`, `padding: 28px 32px`) and is at most ~1140px wide — a comfortable reading width without needing further constraint. The artifacts sidebar (right) is 260px with `--bg-surface` background and a 1px `--border-divider` left border. Both columns stretch to fill the full grid height. The sidebar does not touch the right viewport edge on wide screens — this is intentional. +Left-border color on stream cards encodes content origin: -### Centered form view +- **Orange** — agent prose (ProseCard). +- **Gray (`--text-muted`)** — user messages (UserBubble). +- **Teal** — system events (PhaseMarker label uses teal text rather than a border, but the principle holds). -Used for the "New Run" page. Single centered column with `--form-max-width` (640px), no sidebar, no scout bar. Content sections are stacked with `--gap-form-sections`. +### Save model -### Scout bar (conditional) +Explicit Cancel/Save appears only inside InlineForm. All standalone controls (Toggle, NumberInput, Select outside InlineForm) auto-save on interaction. The distinction: if a control always has a valid state at every moment, it auto-saves. If a multi-field form can have invalid intermediate states (e.g., profile with runner set but model blank), it requires explicit save. -Appears at the bottom of the viewport only during phases where scouts are active. Full-viewport-width frame element at the same level as the HeaderBar. Contains the summary line and white table card. Not present on the New Run page or completion views where scouts aren't running. +### Font usage in form controls -## Logo +All form controls use `--font-body`. The `mono` prop on TextInput is for values that are technical identifiers (file paths, binary paths, extra args). Select always uses `--font-body` even when displaying technical values like runner or model names. CommandPalette and YieldPanel use `--font-mono` for `/command` names since these are technical identifiers. -The koan logo consists of two elements: a geometric mark and a wordmark. +### Section cards in settings vs stream content -The geometric mark is two overlapping circles. The larger circle (16px diameter) is `--color-orange`, positioned top-left. The smaller circle (10px diameter) is `--color-teal`, positioned bottom-right, partially overlapping the orange circle. Total mark footprint: approximately 20x20px. +The content stream uses individual molecules (ProseCard, ToolCallRow, YieldPanel) floating on `--bg-base`. Settings uses white section cards grouping related entity rows. The stream is a timeline where each item is independent. Settings is a form where items within a section are related. The card boundary communicates "these things belong together." -The wordmark "koan" is set in `--font-display` (serif) at 17px/500, colored `--text-on-dark` when on navy, or `--text-primary` when on light backgrounds. Letter-spacing: -0.3px. +### `/`-command transformation -The mark and wordmark are separated by 8px. On the header bar, a 1px vertical divider at `--text-on-dark-faint` separates the logo group from the navigation breadcrumb with 16px gap on each side. +FeedbackInput rewrites `/plan-spec ...` into natural language before sending to the backend. The `/` prefix is a UI convention only — the orchestrator receives a clear, structured instruction without requiring backend slash-command parsing. -## Deferred Items +### Internal tool call suppression -- **SettingsOverlay redesign** — currently uses migrated tokens from the old design system. Functional but not visually redesigned. Deferred to a future pass. -- **Thinking/waiting indicators** — the pulsing dot and "Thinking…" / "Starting agent…" indicators use inline CSS classes in app-shell.css rather than standalone molecules. Functional but could be promoted to atoms in a future pass. -- **Streaming cursor** — the blinking orange cursor during text streaming uses an inline CSS class. Could become an atom. +Koan orchestration tools (`koan_yield`, `koan_complete_step`, `koan_set_phase`) are internal to the workflow engine. Their effects are visible through the molecules they trigger (YieldPanel, StepHeader, PhaseMarker). They do not render as ToolCallRows in the content stream. From 24ef62745885794f035b15630b5d06f3460bac72 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 9 Apr 2026 18:55:31 +0700 Subject: [PATCH 361/412] fix: wire yield command palette to projection state --- frontend/src/App.tsx | 2 +- frontend/src/store/index.ts | 19 +++++++++++++++++-- koan/projections.py | 21 ++++++++++++++++++++- 3 files changed, 38 insertions(+), 4 deletions(-) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 283a645..1b99cce 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -219,7 +219,7 @@ function ContentStream() { <FeedbackInput onSend={msg => api.sendChatMessage(msg)} disabled={!!run?.completion} - availableCommands={run?.isYielded ? run.availablePhases : undefined} + availableCommands={run?.activeYield ? run.availablePhases : undefined} onPaletteToggle={setPaletteOpen} /> </> diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 505ff2e..e8efe4b 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -127,17 +127,32 @@ export interface SteeringMessage { content: string } +export interface Suggestion { + id: string + label: string + command: string +} + +export interface ActiveYield { + suggestions: Suggestion[] +} + +export interface PhaseInfo { + id: string + description: string +} + export interface Run { config: RunConfig phase: string workflow: string // active workflow name + availablePhases: PhaseInfo[] // populated on workflow_selected; drives the / command palette agents: Record<string, Agent> focus: Focus | null artifacts: Record<string, ArtifactInfo> completion: CompletionInfo | null steering: SteeringMessage[] - isYielded: boolean - availablePhases: { id: string; description: string }[] + activeYield: ActiveYield | null // non-null while orchestrator is blocked in koan_yield } // -- Store -------------------------------------------------------------------- diff --git a/koan/projections.py b/koan/projections.py index 3d18f49..dd4ca10 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -22,6 +22,8 @@ from pydantic import BaseModel, ConfigDict, Field from pydantic.alias_generators import to_camel +from .lib.workflows import WORKFLOWS + log = logging.getLogger("koan.projections") # --------------------------------------------------------------------------- @@ -336,10 +338,16 @@ class Notification(KoanBaseModel): class SteeringMessage(KoanBaseModel): content: str +class PhaseInfo(KoanBaseModel): + """A phase the user can transition to, as shown in the command palette.""" + id: str # phase key (e.g. "plan-spec") + description: str # one-line description from the workflow + class Run(KoanBaseModel): config: RunConfig phase: str = "" workflow: str = "" # active workflow name + available_phases: list[PhaseInfo] = [] # populated on workflow_selected; drives the / command palette agents: dict[str, Agent] = {} # all agents by ID — queued, running, done, failed focus: Focus | None = None # None before first agent spawns artifacts: dict[str, ArtifactInfo] = {} @@ -467,7 +475,18 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: if projection.run is None: log.warning("fold workflow_selected: run is None, skipping") return projection - new_run = projection.run.model_copy(update={"workflow": payload.get("workflow", "")}) + workflow_name = payload.get("workflow", "") + workflow = WORKFLOWS.get(workflow_name) + available_phases: list[PhaseInfo] = [] + if workflow is not None: + available_phases = [ + PhaseInfo(id=p, description=workflow.phase_descriptions.get(p, "")) + for p in workflow.available_phases + ] + new_run = projection.run.model_copy(update={ + "workflow": workflow_name, + "available_phases": available_phases, + }) return projection.model_copy(update={"run": new_run}) case "phase_started": From 03f345b08099e55720d8bce97160bfb13bad6d5d Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 11:16:05 +0700 Subject: [PATCH 362/412] fix: honor yield suggestion command text --- frontend/src/App.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 1b99cce..8c47af6 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -165,7 +165,7 @@ function renderEntry(entry: ConversationEntry, i: number) { key={i} prompt={entry.prompt || 'What would you like to do next?'} suggestions={entry.suggestions} - onSelect={s => setChatDraft(`/${s.id} `)} + onSelect={s => setChatDraft(s.command ? `/${s.id} ${s.command}` : `/${s.id} `)} /> ) } From 27634766365d4ce11de373ade3de6d7019f0704e Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 11:16:36 +0700 Subject: [PATCH 363/412] feat: add selectable artifacts sidebar state --- frontend/src/App.tsx | 10 ++++++++-- .../src/components/molecules/ArtifactCard.css | 17 +++++++++++++++++ .../src/components/molecules/ArtifactCard.tsx | 10 +++++++--- .../components/organisms/ArtifactsSidebar.tsx | 14 ++++++++++---- frontend/src/store/index.ts | 6 ++++++ 5 files changed, 48 insertions(+), 9 deletions(-) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 8c47af6..06b1d5b 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -82,11 +82,14 @@ function useHeaderData() { function ConnectedSidebar() { const artifacts = useStore(s => s.run?.artifacts ?? {}) + const reviewingArtifact = useStore(s => s.reviewingArtifact) + const setReviewingArtifact = useStore(s => s.setReviewingArtifact) const entries = useMemo(() => { const now = Date.now() const list = Object.values(artifacts).map(a => { const mins = Math.floor((now - a.modifiedAt) / 60000) return { + path: a.path, filename: a.path.split('/').pop() || a.path, modifiedAgo: mins < 1 ? 'just now' : mins < 60 ? `modified ${mins}m ago` : `modified ${Math.floor(mins / 60)}h ago`, variant: mins < 5 ? ('recent' as const) : ('stable' as const), @@ -94,9 +97,12 @@ function ConnectedSidebar() { } }) list.sort((a, b) => b._ts - a._ts) - return list.map(({ filename, modifiedAgo, variant }) => ({ filename, modifiedAgo, variant })) + return list.map(({ path, filename, modifiedAgo, variant }) => ({ path, filename, modifiedAgo, variant })) }, [artifacts]) - return <ArtifactsSidebarOrg artifacts={entries} /> + const handleClick = (path: string) => { + setReviewingArtifact(reviewingArtifact === path ? null : path) + } + return <ArtifactsSidebarOrg artifacts={entries} activePath={reviewingArtifact} onArtifactClick={handleClick} /> } function ConnectedScoutBar() { diff --git a/frontend/src/components/molecules/ArtifactCard.css b/frontend/src/components/molecules/ArtifactCard.css index 1f1c961..0db6fce 100644 --- a/frontend/src/components/molecules/ArtifactCard.css +++ b/frontend/src/components/molecules/ArtifactCard.css @@ -6,6 +6,23 @@ background: var(--bg-card-warm); border-radius: var(--radius-lg); border: 0.5px solid var(--border-divider); + transition: background var(--duration-fast) var(--ease-default), + border-color var(--duration-fast) var(--ease-default), + outline-color var(--duration-fast) var(--ease-default); +} + +.ac--clickable { + cursor: pointer; +} + +.ac--clickable:hover { + background: var(--bg-selected); +} + +.ac--active { + background: var(--bg-selected); + outline: 0.5px solid var(--color-orange); + outline-offset: -0.5px; } /* ---- Icon square ---- */ diff --git a/frontend/src/components/molecules/ArtifactCard.tsx b/frontend/src/components/molecules/ArtifactCard.tsx index c2ee1c6..2a35216 100644 --- a/frontend/src/components/molecules/ArtifactCard.tsx +++ b/frontend/src/components/molecules/ArtifactCard.tsx @@ -3,7 +3,8 @@ * * Shows a colored icon square, filename (truncated), and a * last-modified timestamp. "recent" files get a navy icon, - * "stable" files get a teal icon. + * "stable" files get a teal icon. Clickable when onClick is + * provided; highlights when `active`. * * Used in: artifacts sidebar. */ @@ -14,6 +15,8 @@ interface ArtifactCardProps { filename: string modifiedAgo: string variant?: 'recent' | 'stable' + active?: boolean + onClick?: () => void } const FileIcon = ({ stroke }: { stroke: string }) => ( @@ -23,9 +26,10 @@ const FileIcon = ({ stroke }: { stroke: string }) => ( </svg> ) -export function ArtifactCard({ filename, modifiedAgo, variant = 'recent' }: ArtifactCardProps) { +export function ArtifactCard({ filename, modifiedAgo, variant = 'recent', active, onClick }: ArtifactCardProps) { + const cls = `ac${onClick ? ' ac--clickable' : ''}${active ? ' ac--active' : ''}` return ( - <div className="ac"> + <div className={cls} onClick={onClick} role={onClick ? 'button' : undefined} tabIndex={onClick ? 0 : undefined}> <span className={`ac-icon ac-icon--${variant}`}> <FileIcon stroke={variant === 'recent' ? '#b8b0d0' : '#d0f0e8'} /> </span> diff --git a/frontend/src/components/organisms/ArtifactsSidebar.tsx b/frontend/src/components/organisms/ArtifactsSidebar.tsx index 4b6608b..c9f13f9 100644 --- a/frontend/src/components/organisms/ArtifactsSidebar.tsx +++ b/frontend/src/components/organisms/ArtifactsSidebar.tsx @@ -3,7 +3,8 @@ * * Fixed 240px column beside the main content stream. Shows a section * label, a list of ArtifactCard molecules, or an empty-state message - * when no artifacts exist. + * when no artifacts exist. Cards are clickable when onArtifactClick + * is provided; the entry whose path matches activePath is highlighted. * * Used in: workspace layout, right column. */ @@ -13,6 +14,7 @@ import { ArtifactCard } from '../molecules/ArtifactCard' import './ArtifactsSidebar.css' interface ArtifactEntry { + path: string filename: string modifiedAgo: string variant?: 'recent' | 'stable' @@ -20,9 +22,11 @@ interface ArtifactEntry { interface ArtifactsSidebarProps { artifacts: ArtifactEntry[] + activePath?: string | null + onArtifactClick?: (path: string) => void } -export function ArtifactsSidebar({ artifacts }: ArtifactsSidebarProps) { +export function ArtifactsSidebar({ artifacts, activePath, onArtifactClick }: ArtifactsSidebarProps) { return ( <aside className="asb"> <div className="asb-header"> @@ -32,12 +36,14 @@ export function ArtifactsSidebar({ artifacts }: ArtifactsSidebarProps) { <div className="asb-empty">No artifacts yet</div> ) : ( <div className="asb-list"> - {artifacts.map((a, i) => ( + {artifacts.map(a => ( <ArtifactCard - key={i} + key={a.path} filename={a.filename} modifiedAgo={a.modifiedAgo} variant={a.variant} + active={activePath === a.path} + onClick={onArtifactClick ? () => onArtifactClick(a.path) : undefined} /> ))} </div> diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index e8efe4b..82f4a65 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -173,10 +173,14 @@ interface KoanState { // Local draft for chat input — set by YieldPanel row selections chatDraft: string + // Local UI state: currently open artifact review (path or null) + reviewingArtifact: string | null + // Actions setConnected: (v: boolean) => void setSettingsOpen: (v: boolean) => void setChatDraft: (text: string) => void + setReviewingArtifact: (path: string | null) => void } export const useStore = create<KoanState>((set) => ({ @@ -194,10 +198,12 @@ export const useStore = create<KoanState>((set) => ({ settingsOpen: false, chatDraft: '', + reviewingArtifact: null, setConnected: (v) => set({ connected: v }), setSettingsOpen: (v) => set({ settingsOpen: v }), setChatDraft: (text) => set({ chatDraft: text }), + setReviewingArtifact: (path) => set({ reviewingArtifact: path }), })) export type KoanStore = typeof useStore From 8808e477cbd92133b469c233bd77fbbb59b04ae3 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 11:16:54 +0700 Subject: [PATCH 364/412] feat: define koan_yield review feedback contract --- koan/phases/format_step.py | 11 ++++++++++- koan/web/mcp_endpoint.py | 29 +++++++++++++++++------------ 2 files changed, 27 insertions(+), 13 deletions(-) diff --git a/koan/phases/format_step.py b/koan/phases/format_step.py index 147e352..127f6a2 100644 --- a/koan/phases/format_step.py +++ b/koan/phases/format_step.py @@ -30,7 +30,16 @@ def format_step(g: StepGuidance) -> str: def format_user_messages(messages: list[Any]) -> str: - """Format a list of ChatMessage objects into a readable string block.""" + """Wrap user chat messages in a user-voice envelope for the LLM. + + The envelope is content-agnostic: whether the payload is a review + response, a direct reply, or an open-ended message, the framing only + asserts "the user said this". Behavior-specific instructions live in + the message body (e.g. formatReviewMessage in the frontend names the + review-revise-reyield loop). Do NOT add review-aware branching here: + handoff minimalism requires this layer to stay ignorant of what kind + of user message it is wrapping. + """ parts = [] for msg in messages: ts = datetime.fromtimestamp(msg.timestamp_ms / 1000, tz=timezone.utc) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index c06c274..104c581 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -359,23 +359,28 @@ async def koan_yield( summary: str = "", suggestions: list[dict] | None = None, ) -> str: - """Yield to the user for open-ended conversation. + """Yield to the user and wait for their reply. - Blocks until the user sends a message. The message is returned as - the tool result. Call this in a loop for multi-turn conversation. + Blocks until the user sends a message; returns it as the tool result. + This is the sole human-in-the-loop checkpoint -- call it after finishing + an artifact and whenever you need user direction. Call in a loop for + multi-turn conversation. - Optionally provide suggestions — the UI renders them as clickable - pills that pre-fill the chat input. The user still has to press Send. + REVIEW FEEDBACK LOOP: if the returned message begins with + "I've reviewed `<path>`", treat it as a structured review response. + The user has inspected the artifact you just produced. Revise the file + to address every inline comment and the summary (if present), then call + `koan_yield` again to await confirmation or further feedback. Do NOT + call `koan_complete_step` between review rounds; stay in the yield loop + until the user selects a "done"/"proceed" suggestion or steers elsewhere. - Each dict in suggestions should have: - - id (str): machine key (e.g. "plan-spec", "done") - - label (str): display text shown on the pill (e.g. "Write implementation plan") - - command (str): text pre-filled in chat input when the pill is clicked + Suggestions (optional) render as clickable pills that pre-fill the chat. + Each dict: id (phase name or "done"), label (short display), command + (pre-filled text on click). Args: - summary: Brief context about what the agent is waiting for (unused by - the driver; passed for logging/tooling purposes). - suggestions: Clickable options shown in the UI above the chat input. + summary: Brief context about what the agent is waiting for. + suggestions: Pills shown above the chat input. """ agent = _get_agent() _check_or_raise(agent, "koan_yield", {"summary": summary, "suggestions": suggestions}) From 879e1bc47875105077b0a9a56bf2d7224591659b Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 11:17:29 +0700 Subject: [PATCH 365/412] feat: add inline artifact review panel workflow --- frontend/src/App.tsx | 126 +++++++++++ .../src/components/molecules/ReviewBlock.css | 69 ++++++ .../src/components/molecules/ReviewBlock.tsx | 44 ++++ .../components/molecules/ReviewComment.css | 52 +++++ .../components/molecules/ReviewComment.tsx | 39 ++++ .../molecules/ReviewCommentInput.css | 38 ++++ .../molecules/ReviewCommentInput.tsx | 45 ++++ .../src/components/molecules/ReviewEvent.css | 71 ++++++ .../src/components/molecules/ReviewEvent.tsx | 33 +++ .../src/components/organisms/ReviewPanel.css | 197 +++++++++++++++++ .../src/components/organisms/ReviewPanel.tsx | 205 ++++++++++++++++++ frontend/src/styles/variables.css | 1 + 12 files changed, 920 insertions(+) create mode 100644 frontend/src/components/molecules/ReviewBlock.css create mode 100644 frontend/src/components/molecules/ReviewBlock.tsx create mode 100644 frontend/src/components/molecules/ReviewComment.css create mode 100644 frontend/src/components/molecules/ReviewComment.tsx create mode 100644 frontend/src/components/molecules/ReviewCommentInput.css create mode 100644 frontend/src/components/molecules/ReviewCommentInput.tsx create mode 100644 frontend/src/components/molecules/ReviewEvent.css create mode 100644 frontend/src/components/molecules/ReviewEvent.tsx create mode 100644 frontend/src/components/organisms/ReviewPanel.css create mode 100644 frontend/src/components/organisms/ReviewPanel.tsx diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 06b1d5b..cca62f3 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -48,6 +48,7 @@ import { Notification } from './components/Notification' // SettingsOverlay is no longer rendered — replaced by SettingsPage organism // import { SettingsOverlay } from './components/SettingsOverlay' import { SettingsPage, type Profile as SPProfile, type Installation as SPInstallation } from './components/organisms/SettingsPage' +import { ReviewPanel, type ReviewSubmitPayload } from './components/organisms/ReviewPanel' // --------------------------------------------------------------------------- // Header data @@ -534,6 +535,98 @@ function ConnectedSettingsPage() { ) } +// --------------------------------------------------------------------------- +// Review view — renders ReviewPanel for the currently open artifact +// --------------------------------------------------------------------------- + +// DESIGN NOTE: the opener below deliberately does NOT ask the LLM to verify +// its own revision before re-yielding. Intrinsic self-correction is a +// documented anti-pattern -- the user's next review pass is the verifier, +// not the model. Do not add "double-check your edits", "validate each +// change", or any similar self-verification language. +// +// The opener also pairs with the REVIEW FEEDBACK LOOP contract documented +// in the koan_yield tool docstring (koan/web/mcp_endpoint.py). Both sides +// must stay in sync: the "I've reviewed `<path>`" sentinel is how the LLM +// recognizes the payload as a review response. +function formatReviewMessage(path: string, payload: ReviewSubmitPayload): string { + const out: string[] = [] + out.push( + `I've reviewed \`${path}\`. For each inline comment below, edit the cited section of the file to address it. Preserve everything not called out. When all comments are addressed, call \`koan_yield\` again so I can confirm or give another pass.`, + ) + + // Group comments by blockIndex in document order. + const groups = new Map<number, { preview: string; comments: string[] }>() + for (const c of payload.comments) { + const g = groups.get(c.blockIndex) + if (g) g.comments.push(c.text) + else groups.set(c.blockIndex, { preview: c.blockPreview, comments: [c.text] }) + } + const sorted = [...groups.entries()].sort(([a], [b]) => a - b) + + for (const [, g] of sorted) { + out.push('') + out.push('On the section:') + for (const line of g.preview.split('\n')) out.push(`> ${line}`) + out.push('') + for (const text of g.comments) { + const parts = text.split('\n') + out.push(`- ${parts[0]}`) + for (let i = 1; i < parts.length; i++) out.push(` ${parts[i]}`) + } + } + + const summary = payload.summary.trim() + if (summary) { + out.push('') + out.push(`**Summary:** ${summary}`) + } + + return out.join('\n') +} + +function ReviewView() { + const path = useStore(s => s.reviewingArtifact) + const setReviewing = useStore(s => s.setReviewingArtifact) + const [content, setContent] = useState<string | null>(null) + const [error, setError] = useState<string | null>(null) + + useEffect(() => { + if (!path) return + setContent(null) + setError(null) + let cancelled = false + api.getArtifactContent(path) + .then(res => { if (!cancelled) setContent(res.content) }) + .catch(e => { if (!cancelled) setError(String(e)) }) + return () => { cancelled = true } + }, [path]) + + if (!path) return null + + const handleSubmit = (payload: ReviewSubmitPayload) => { + const message = formatReviewMessage(path, payload) + console.log('[review] submitting:\n' + message) + api.sendChatMessage(message) + setReviewing(null) + } + + return ( + <div className="content-column" style={{ padding: '28px 32px 40px 32px' }}> + {content === null && !error && <div className="loading-center">loading…</div>} + {error && <div className="loading-center">Error: {error}</div>} + {content !== null && ( + <ReviewPanel + path={path} + content={content} + onSubmit={handleSubmit} + onClose={() => setReviewing(null)} + /> + )} + </div> + ) +} + // --------------------------------------------------------------------------- // App // --------------------------------------------------------------------------- @@ -541,9 +634,31 @@ function ConnectedSettingsPage() { export default function App() { const run = useStore(s => s.run) const connected = useStore(s => s.connected) + const reviewingArtifact = useStore(s => s.reviewingArtifact) + const activeYield = useStore(s => s.run?.activeYield ?? null) + const artifactsDict = useStore(s => s.run?.artifacts) const header = useHeaderData() const [page, setPage] = useState<'new-run' | 'sessions' | 'settings'>('new-run') + // Review auto-open: yield-triggered, not write-triggered. Fires when the + // orchestrator parks in koan_yield -- the synchronous checkpoint where a + // review is expected. Picks the newest .md artifact modified since the + // previous yield (or since app mount for the first yield). If no .md was + // modified in that window, no auto-open (the yield is not about an artifact). + // TODO: gate behind settings toggle "Auto-open new or changed artifacts". + const lastYieldAtRef = useRef<number>(Date.now()) + useEffect(() => { + if (activeYield === null) return + const cutoff = lastYieldAtRef.current + lastYieldAtRef.current = Date.now() + const candidates = Object.values(artifactsDict ?? {}) + .filter(a => a.path.endsWith('.md') && a.modifiedAt > cutoff) + if (candidates.length === 0) return + const newest = candidates.reduce((a, b) => (a.modifiedAt >= b.modifiedAt ? a : b)) + useStore.getState().setReviewingArtifact(newest.path) + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [activeYield]) + useEffect(() => { let es: EventSource | null = null let retryDelay = 500 @@ -623,6 +738,17 @@ export default function App() { ) } + if (reviewingArtifact) { + return ( + <div className="app-root"> + <HeaderBar {...header} onSettingsClick={goToSettings} /> + <div className="workflow-grid"><ReviewView /><ConnectedSidebar /></div> + <ConnectedScoutBar /> + <Notification /> + </div> + ) + } + return ( <div className="app-root"> <HeaderBar {...header} onSettingsClick={goToSettings} /> diff --git a/frontend/src/components/molecules/ReviewBlock.css b/frontend/src/components/molecules/ReviewBlock.css new file mode 100644 index 0000000..6983752 --- /dev/null +++ b/frontend/src/components/molecules/ReviewBlock.css @@ -0,0 +1,69 @@ +/* ReviewBlock -- wraps a markdown block; whole-block click target with + a gutter + button as hover hint. Uses flex row layout so the button + naturally aligns with the top of content regardless of element type. */ + +.rb { + display: flex; + align-items: center; + gap: 10px; + padding: 4px 12px; + margin: 0 -12px; + border-radius: var(--radius-lg); + cursor: pointer; + transition: background var(--duration-fast) var(--ease-default); +} + +.rb:hover { + background: var(--bg-selected); +} + +.rb:hover .rb-gutter { + opacity: 1; +} + +.rb-gutter { + flex-shrink: 0; + width: 18px; + height: 18px; + border-radius: var(--radius-circle); + background: var(--color-orange); + color: white; + border: none; + cursor: pointer; + font-size: 12px; + line-height: 1; + display: flex; + align-items: center; + justify-content: center; + opacity: 0; + transition: opacity var(--duration-fast) var(--ease-default), + background var(--duration-fast) var(--ease-default); +} + +.rb-gutter:hover { + background: var(--color-orange-hover); +} + +.rb-content { + flex: 1; + min-width: 0; +} + +/* Kill top margin on first child so content starts flush, + aligning with the gutter button. */ +.rb-content > :first-child { + margin-top: 0; +} + +/* -- Active state (comment input open) -- */ + +.rb--active { + background: var(--bg-selected); + border-left: 3px solid var(--color-orange); + padding-left: 9px; + margin-left: -15px; +} + +.rb--active .rb-gutter { + opacity: 1; +} diff --git a/frontend/src/components/molecules/ReviewBlock.tsx b/frontend/src/components/molecules/ReviewBlock.tsx new file mode 100644 index 0000000..7746437 --- /dev/null +++ b/frontend/src/components/molecules/ReviewBlock.tsx @@ -0,0 +1,44 @@ +/** + * ReviewBlock -- wraps a single rendered markdown block inside the + * ReviewPanel. The whole block is a click target for opening a comment + * input; the gutter "+" button is a visual hint that appears on hover. + * Text selection within the block is preserved (clicks that produce a + * selection do not fire the open handler). + */ + +import type { MouseEvent, ReactNode } from 'react' +import './ReviewBlock.css' + +interface ReviewBlockProps { + hasComments: boolean + isActive: boolean + onClickGutter: () => void + children: ReactNode +} + +export function ReviewBlock({ hasComments: _hasComments, isActive, onClickGutter, children }: ReviewBlockProps) { + const cls = `rb${isActive ? ' rb--active' : ''}` + + const handleClick = (e: MouseEvent) => { + const selection = window.getSelection() + if (selection && selection.toString().length > 0) return + if ((e.target as HTMLElement).closest('.rb-gutter')) return + if ((e.target as HTMLElement).closest('.rci')) return + if ((e.target as HTMLElement).closest('.rc-comment')) return + onClickGutter() + } + + const handleGutterClick = (e: MouseEvent) => { + e.stopPropagation() + onClickGutter() + } + + return ( + <div className={cls} onClick={handleClick}> + <button type="button" className="rb-gutter" onClick={handleGutterClick} aria-label="Add comment">+</button> + <div className="rb-content">{children}</div> + </div> + ) +} + +export default ReviewBlock diff --git a/frontend/src/components/molecules/ReviewComment.css b/frontend/src/components/molecules/ReviewComment.css new file mode 100644 index 0000000..3ea2c1e --- /dev/null +++ b/frontend/src/components/molecules/ReviewComment.css @@ -0,0 +1,52 @@ +/* ReviewComment -- read-only comment card with gray left accent. */ + +.rc-comment { + position: relative; + border-left: 3px solid var(--text-muted); + padding: 6px 12px; + margin-bottom: 4px; +} + +.rc-comment-header { + display: flex; + align-items: center; + justify-content: space-between; +} + +.rc-comment-meta { + font-family: var(--font-body); + font-size: var(--type-badge); + color: var(--text-muted); + text-transform: uppercase; + letter-spacing: 0.5px; + font-weight: 500; + margin-bottom: 2px; +} + +.rc-comment-delete { + background: none; + border: none; + cursor: pointer; + font-size: 14px; + line-height: 1; + color: var(--text-muted); + padding: 0 2px; + opacity: 0; + transition: opacity var(--duration-fast) var(--ease-default), + color var(--duration-fast) var(--ease-default); +} + +.rc-comment:hover .rc-comment-delete { + opacity: 1; +} + +.rc-comment-delete:hover { + color: var(--status-failed); +} + +.rc-comment-text { + font-family: var(--font-body); + font-size: var(--type-breadcrumb); + line-height: 1.5; + color: var(--text-body); +} diff --git a/frontend/src/components/molecules/ReviewComment.tsx b/frontend/src/components/molecules/ReviewComment.tsx new file mode 100644 index 0000000..cc12f96 --- /dev/null +++ b/frontend/src/components/molecules/ReviewComment.tsx @@ -0,0 +1,39 @@ +/** + * ReviewComment -- read-only comment card displayed below an anchor block + * inside a ReviewPanel. Gray left accent on the white parent surface + * (user-content convention). A delete button appears on hover. + */ + +import type { MouseEvent } from 'react' +import './ReviewComment.css' + +interface ReviewCommentProps { + text: string + onDelete?: () => void +} + +export function ReviewComment({ text, onDelete }: ReviewCommentProps) { + const handleDelete = (e: MouseEvent) => { + e.stopPropagation() + onDelete?.() + } + + return ( + <div className="rc-comment"> + <div className="rc-comment-header"> + <span className="rc-comment-meta">You · just now</span> + {onDelete && ( + <button + type="button" + className="rc-comment-delete" + onClick={handleDelete} + aria-label="Delete comment" + >×</button> + )} + </div> + <div className="rc-comment-text">{text}</div> + </div> + ) +} + +export default ReviewComment diff --git a/frontend/src/components/molecules/ReviewCommentInput.css b/frontend/src/components/molecules/ReviewCommentInput.css new file mode 100644 index 0000000..4ea85f2 --- /dev/null +++ b/frontend/src/components/molecules/ReviewCommentInput.css @@ -0,0 +1,38 @@ +/* ReviewCommentInput -- inline comment form with orange border + focus ring. */ + +.rci { + background: var(--bg-card); + border: 1.5px solid var(--color-orange); + border-radius: var(--radius-lg); + padding: 10px 12px; + margin: 6px 0 12px 0; +} + +.rci:focus-within { + box-shadow: 0 0 0 3px var(--focus-ring); +} + +.rci-textarea { + width: 100%; + border: none; + outline: none; + resize: vertical; + font-family: var(--font-body); + font-size: var(--type-breadcrumb); + line-height: 1.5; + background: transparent; + color: var(--text-body); + min-height: 44px; + padding: 0; +} + +.rci-textarea::placeholder { + color: var(--text-placeholder); +} + +.rci-actions { + display: flex; + justify-content: flex-end; + gap: 8px; + margin-top: 6px; +} diff --git a/frontend/src/components/molecules/ReviewCommentInput.tsx b/frontend/src/components/molecules/ReviewCommentInput.tsx new file mode 100644 index 0000000..293fcbb --- /dev/null +++ b/frontend/src/components/molecules/ReviewCommentInput.tsx @@ -0,0 +1,45 @@ +/** + * ReviewCommentInput -- inline comment form rendered below a ReviewBlock + * when the user clicks the gutter "+" button. Auto-focuses on mount. + */ + +import { useEffect, useRef, useState } from 'react' +import { Button } from '../atoms/Button' +import './ReviewCommentInput.css' + +interface ReviewCommentInputProps { + onAdd: (text: string) => void + onCancel: () => void +} + +export function ReviewCommentInput({ onAdd, onCancel }: ReviewCommentInputProps) { + const [text, setText] = useState('') + const textareaRef = useRef<HTMLTextAreaElement>(null) + + useEffect(() => { + textareaRef.current?.focus() + }, []) + + const handleAdd = () => { + onAdd(text) + setText('') + } + + return ( + <div className="rci"> + <textarea + ref={textareaRef} + className="rci-textarea" + value={text} + onChange={e => setText(e.target.value)} + placeholder="Add a comment on this block..." + /> + <div className="rci-actions"> + <Button variant="secondary" size="xs" onClick={onCancel}>Cancel</Button> + <Button variant="primary" size="xs" onClick={handleAdd}>Add comment</Button> + </div> + </div> + ) +} + +export default ReviewCommentInput diff --git a/frontend/src/components/molecules/ReviewEvent.css b/frontend/src/components/molecules/ReviewEvent.css new file mode 100644 index 0000000..3396267 --- /dev/null +++ b/frontend/src/components/molecules/ReviewEvent.css @@ -0,0 +1,71 @@ +/* ReviewEvent -- dot-on-divider event marker for user-submitted reviews. */ + +.re { + padding: 20px 0; + position: relative; +} + +.re-rule { + position: absolute; + left: 0; + right: 0; + top: 50%; + transform: translateY(-50%); + height: 1px; + background: var(--border-divider); +} + +.re-row { + position: relative; + display: inline-flex; + align-items: baseline; + gap: 10px; + background: var(--bg-base); + padding-right: 16px; + max-width: 100%; + min-width: 0; +} + +.re-dot { + width: 10px; + height: 10px; + background: var(--color-orange); + border-radius: var(--radius-circle); + flex-shrink: 0; + align-self: center; +} + +.re-label { + font-family: var(--font-body); + font-size: var(--type-label); + text-transform: uppercase; + letter-spacing: 1px; + font-weight: 500; + color: var(--text-muted); + flex-shrink: 0; +} + +.re-name { + font-family: var(--font-mono); + font-size: var(--type-breadcrumb); + font-weight: 500; + color: var(--color-orange); + flex-shrink: 0; +} + +.re-sep { + font-size: 12px; + color: var(--text-muted); + flex-shrink: 0; +} + +.re-summary { + font-family: var(--font-body); + font-size: var(--type-breadcrumb); + color: var(--text-muted); + line-height: 1.4; + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} diff --git a/frontend/src/components/molecules/ReviewEvent.tsx b/frontend/src/components/molecules/ReviewEvent.tsx new file mode 100644 index 0000000..0823d92 --- /dev/null +++ b/frontend/src/components/molecules/ReviewEvent.tsx @@ -0,0 +1,33 @@ +/** + * ReviewEvent -- event divider rendered in the content stream when the + * user submits an artifact review. + * + * Same dot-on-divider pattern as PhaseMarker, but with an orange dot + * (user action) instead of teal (system event). The file path is shown + * in monospace orange, followed by a comment-count summary. + */ + +import './ReviewEvent.css' + +interface ReviewEventProps { + path: string + commentCount: number +} + +export function ReviewEvent({ path, commentCount }: ReviewEventProps) { + const summary = `${commentCount} comment${commentCount !== 1 ? 's' : ''} submitted` + return ( + <div className="re"> + <div className="re-rule" /> + <div className="re-row"> + <span className="re-dot" /> + <span className="re-label">Review:</span> + <span className="re-name">{path}</span> + <span className="re-sep" aria-hidden="true">·</span> + <span className="re-summary">{summary}</span> + </div> + </div> + ) +} + +export default ReviewEvent diff --git a/frontend/src/components/organisms/ReviewPanel.css b/frontend/src/components/organisms/ReviewPanel.css new file mode 100644 index 0000000..648c462 --- /dev/null +++ b/frontend/src/components/organisms/ReviewPanel.css @@ -0,0 +1,197 @@ +/* ReviewPanel -- full-width artifact review surface. + Card with header / scrollable body / footer. */ + +.rp { + background: var(--bg-card); + border-radius: var(--radius-2xl); + border: 0.5px solid var(--border-card); + border-top: 3px solid var(--color-orange); + display: flex; + flex-direction: column; + max-height: 100%; + min-height: 0; +} + +.rp-spacer { + flex: 1; +} + +/* ---------- Header ---------- */ + +.rp-header { + display: flex; + align-items: center; + gap: 12px; + padding: 16px 24px; + border-bottom: 0.5px solid var(--border-divider-light); + flex-shrink: 0; +} + +.rp-label { + font-family: var(--font-body); + font-size: var(--type-label); + font-weight: 500; + text-transform: uppercase; + letter-spacing: 1px; + color: var(--color-orange); +} + +.rp-path { + font-family: var(--font-mono); + font-size: var(--type-tool-type); + color: var(--text-muted); +} + +.rp-badge { + font-family: var(--font-body); + font-size: var(--type-badge); + color: var(--text-muted); + padding: 2px 10px; + background: var(--bg-tool-row); + border-radius: var(--radius-pill); +} + +.rp-badge-new { + font-family: var(--font-body); + font-size: var(--type-badge); + color: var(--color-orange); + font-weight: 500; + padding: 2px 8px; + background: var(--bg-selected); + border: 0.5px solid var(--color-orange); + border-radius: var(--radius-pill); +} + +/* ---------- Body + markdown typography ---------- */ + +.rp-body { + padding: 20px 24px 12px 24px; + overflow-y: auto; + flex: 1; + min-height: 0; +} + +.rp-body h1 { + font-size: 20px; + font-weight: 500; + margin: 4px 0 12px 0; + letter-spacing: -0.3px; + color: var(--text-primary); +} + +.rp-body h2 { + font-size: var(--type-section-title); + font-weight: 500; + margin: 24px 0 8px 0; + color: var(--text-primary); +} + +.rp-body h3 { + font-size: var(--type-body); + font-weight: 500; + margin: 16px 0 6px 0; + color: var(--text-primary); +} + +.rp-body p { + font-size: var(--type-body); + line-height: 1.65; + margin: 6px 0; + color: var(--text-body); +} + +.rp-body ul, +.rp-body ol { + font-size: var(--type-body); + line-height: 1.65; + margin: 6px 0 6px 20px; + color: var(--text-body); +} + +.rp-body li { + margin: 3px 0; +} + +.rp-body code { + font-family: var(--font-mono); + font-size: var(--type-tool-type); + background: var(--bg-tool-row); + padding: 1px 5px; + border-radius: var(--radius-sm); + color: var(--text-primary); +} + +.rp-body pre { + background: var(--color-navy); + color: var(--text-on-dark); + padding: 14px 18px; + border-radius: var(--radius-lg); + font-family: var(--font-mono); + font-size: var(--type-tool-type); + line-height: 1.6; + margin: 8px 0; + overflow-x: auto; +} + +.rp-body pre code { + background: none; + padding: 0; + border-radius: 0; + color: inherit; +} + +/* ---------- Footer ---------- */ + +.rp-footer { + border-top: 0.5px solid var(--border-divider-light); + padding: 16px 24px; + flex-shrink: 0; +} + +.rp-footer-label { + font-family: var(--font-body); + font-size: var(--type-label); + font-weight: 500; + text-transform: uppercase; + letter-spacing: 0.5px; + color: var(--text-muted); + margin-bottom: 6px; +} + +.rp-footer-ta { + width: 100%; + min-height: 52px; + padding: 10px 14px; + border: 1.5px solid var(--border-input); + border-radius: var(--radius-lg); + font-family: var(--font-body); + font-size: var(--type-breadcrumb); + line-height: 1.5; + color: var(--text-body); + background: var(--bg-card); + resize: vertical; + outline: none; + box-sizing: border-box; +} + +.rp-footer-ta::placeholder { + color: var(--text-placeholder); +} + +.rp-footer-ta:focus { + border-color: var(--color-orange); + box-shadow: 0 0 0 3px var(--focus-ring); +} + +.rp-footer-actions { + display: flex; + align-items: center; + gap: 12px; + margin-top: 12px; +} + +.rp-footer-hint { + font-family: var(--font-body); + font-size: var(--type-label); + color: var(--text-hint); +} diff --git a/frontend/src/components/organisms/ReviewPanel.tsx b/frontend/src/components/organisms/ReviewPanel.tsx new file mode 100644 index 0000000..f3c5532 --- /dev/null +++ b/frontend/src/components/organisms/ReviewPanel.tsx @@ -0,0 +1,205 @@ +/** + * ReviewPanel -- full-width artifact review surface that takes over + * the content column. Renders a markdown document, wraps each top-level + * block in a ReviewBlock, and tracks per-block comments and an optional + * overall summary until the user submits or closes the review. + */ + +import { createContext, useContext, useMemo, useRef, useState } from 'react' +import type { JSX, ReactNode } from 'react' +import ReactMarkdown from 'react-markdown' +import remarkGfm from 'remark-gfm' + +import { Button } from '../atoms/Button' +import { ReviewBlock } from '../molecules/ReviewBlock' +import { ReviewComment } from '../molecules/ReviewComment' +import { ReviewCommentInput } from '../molecules/ReviewCommentInput' + +import './ReviewPanel.css' + +// Published as `true` inside the subtree of any ReviewBlock so that nested +// markdown elements (e.g. a <p> inside an <li> inside a wrapped <ul>) render +// as plain HTML instead of stacking a second gutter button on top. +const NestedCtx = createContext(false) + +export interface ReviewSubmitPayload { + comments: { blockIndex: number; text: string; blockPreview: string }[] + summary: string +} + +interface ReviewPanelProps { + path: string + content: string + isNew?: boolean + onSubmit: (payload: ReviewSubmitPayload) => void + onClose: () => void +} + +// --------------------------------------------------------------------------- + +const countComments = (comments: Record<number, string[]>): number => + Object.values(comments).reduce((n, arr) => n + arr.length, 0) + +const pluralize = (n: number, unit: string): string => + `${n} ${unit}${n !== 1 ? 's' : ''}` + +const hintFor = (n: number): string => + n === 0 + ? 'No comments yet -- click any block above' + : `${pluralize(n, 'inline comment')} will be submitted` + +const badgeLabel = (n: number): string => pluralize(n, 'comment') + +// Collect per-block comments into a flat payload, attaching a preview of +// the anchor block text so the backend can locate the block in source. +const collectSubmit = ( + comments: Record<number, string[]>, + body: HTMLDivElement | null, +): ReviewSubmitPayload['comments'] => { + const blocks = body?.querySelectorAll('.rb') ?? [] + return Object.entries(comments).flatMap(([key, texts]) => { + const idx = Number(key) + const el = blocks[idx] as HTMLElement | undefined + const preview = (el?.querySelector('.rb-content')?.textContent ?? '').slice(0, 200) + return texts.map(text => ({ blockIndex: idx, text, blockPreview: preview })) + }) +} + +// --------------------------------------------------------------------------- + +export function ReviewPanel({ path, content, isNew, onSubmit, onClose }: ReviewPanelProps) { + const [activeBlock, setActiveBlock] = useState<number | null>(null) + const [comments, setComments] = useState<Record<number, string[]>>({}) + const [summary, setSummary] = useState('') + const bodyRef = useRef<HTMLDivElement>(null) + + // Reset the block counter on every render so index assignments stay + // stable across re-renders (state is keyed on index). + const counterRef = useRef(0) + counterRef.current = 0 + + const addComment = (idx: number, text: string) => { + if (!text.trim()) { + setActiveBlock(null) + return + } + setComments(prev => ({ ...prev, [idx]: [...(prev[idx] ?? []), text] })) + setActiveBlock(null) + } + + const deleteComment = (blockIdx: number, commentIdx: number) => { + setComments(prev => { + const blockComments = [...(prev[blockIdx] ?? [])] + blockComments.splice(commentIdx, 1) + const next = { ...prev } + if (blockComments.length === 0) { + delete next[blockIdx] + } else { + next[blockIdx] = blockComments + } + return next + }) + } + + const toggleBlock = (idx: number) => + setActiveBlock(cur => (cur === idx ? null : idx)) + + const wrapBlock = (node: ReactNode): ReactNode => { + const idx = counterRef.current++ + const blockComments = comments[idx] ?? [] + const isActive = activeBlock === idx + return ( + <ReviewBlock + key={idx} + hasComments={blockComments.length > 0} + isActive={isActive} + onClickGutter={() => toggleBlock(idx)} + > + <NestedCtx.Provider value={true}> + {node} + {blockComments.map((text, i) => ( + <ReviewComment key={i} text={text} onDelete={() => deleteComment(idx, i)} /> + ))} + {isActive && ( + <ReviewCommentInput + onAdd={text => addComment(idx, text)} + onCancel={() => setActiveBlock(null)} + /> + )} + </NestedCtx.Provider> + </ReviewBlock> + ) + } + + // One renderer per markdown tag: wraps as a ReviewBlock when it is a + // top-level block, or renders as plain HTML when it is already inside + // another ReviewBlock (the NestedCtx check). Memoized so that parent + // re-renders during SSE streaming don't give react-markdown fresh + // component types -- that would unmount and remount every .rb block and + // cause visible flicker. + const mdComponents = useMemo(() => { + const renderAs = (Tag: keyof JSX.IntrinsicElements) => + function TagRenderer({ children }: { children?: ReactNode }) { + const nested = useContext(NestedCtx) + const el = <Tag>{children}</Tag> + return nested ? el : wrapBlock(el) + } + return { + h1: renderAs('h1'), + h2: renderAs('h2'), + h3: renderAs('h3'), + h4: renderAs('h4'), + p: renderAs('p'), + ul: renderAs('ul'), + ol: renderAs('ol'), + pre: renderAs('pre'), + blockquote: renderAs('blockquote'), + hr: renderAs('hr'), + table: renderAs('table'), + } + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [comments, activeBlock]) + + const total = countComments(comments) + + const handleSubmit = () => { + onSubmit({ comments: collectSubmit(comments, bodyRef.current), summary }) + } + + return ( + <div className="rp"> + <div className="rp-header"> + <span className="rp-label">Review</span> + <span className="rp-path">{path}</span> + <span className="rp-spacer" /> + {isNew + ? <span className="rp-badge-new">new</span> + : <span className="rp-badge">{badgeLabel(total)}</span>} + </div> + + <div className="rp-body" ref={bodyRef}> + <ReactMarkdown remarkPlugins={[remarkGfm]} components={mdComponents}> + {content} + </ReactMarkdown> + </div> + + <div className="rp-footer"> + <div className="rp-footer-label">Overall feedback (optional)</div> + <textarea + className="rp-footer-ta" + value={summary} + onChange={e => setSummary(e.target.value)} + placeholder="Summarize your review -- e.g. 'Looks good, just clarify the channel types and add PagerDuty'" + /> + <div className="rp-footer-actions"> + <span className="rp-footer-hint">{hintFor(total)}</span> + <span className="rp-spacer" /> + <Button variant="secondary" size="sm" onClick={onClose}>Close without submitting</Button> + <Button variant="primary" size="sm" onClick={handleSubmit}>Submit review</Button> + </div> + </div> + </div> + ) +} + +export default ReviewPanel diff --git a/frontend/src/styles/variables.css b/frontend/src/styles/variables.css index 54f55c5..1ed9227 100644 --- a/frontend/src/styles/variables.css +++ b/frontend/src/styles/variables.css @@ -112,6 +112,7 @@ /* ===== Core Colors ===== */ --color-navy: #2e3a5e; --color-orange: #d4775a; + --color-orange-hover: #c06a4f; --color-teal: #5a9a8a; From e3eb1a4e59e55ba3649db5f41039232875ab55dd Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 11:17:40 +0700 Subject: [PATCH 366/412] docs: specify review panel and review event design --- docs/design-system.md | 121 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 120 insertions(+), 1 deletion(-) diff --git a/docs/design-system.md b/docs/design-system.md index b8b6253..2e5cbeb 100644 --- a/docs/design-system.md +++ b/docs/design-system.md @@ -27,6 +27,12 @@ The single source of truth for koan's visual design. `src/styles/variables.css` | `--border-danger` | `#e8c8c8` | Danger button borders, destructive confirmation card borders. | | `--border-teal` | `#b8d8cc` | Teal-accented button borders (Detect, Explore actions). | +### Interactive colors + +| Token | Hex | Usage | +| ---------------------- | --------- | ------------------------------------------------------------------------ | +| `--color-orange-hover` | `#c06a4f` | Hover state for orange interactive elements (ReviewBlock gutter button). | + ### Component gaps | Token | Value | Usage | @@ -218,6 +224,76 @@ Description: `--font-body`, `--type-breadcrumb` (13px), `--text-muted`. Props: `name: string`, `description: string`. +#### ReviewEvent + +An event divider rendered in the content stream when the user submits an artifact review. Uses the same dot-on-divider pattern as PhaseMarker, but with an orange dot (user action) instead of teal (system event). + +Container: `padding: 20px 0`, `position: relative`. Same layout structure as PhaseMarker. + +Horizontal rule: identical to PhaseMarker (`position: absolute`, full width, `1px`, `--border-divider`). + +Content overlay: `position: relative`, `display: flex`, `align-items: center`, `gap: 10px`, `background: var(--bg-base)`, `padding-right: 16px`. + +Orange dot: 10px diameter, `background: var(--color-orange)`, `var(--radius-circle)`, `flex-shrink: 0`. + +"Review:" label: `--type-label` (11px), `text-transform: uppercase`, `letter-spacing: 1px`, font-weight 500, `--text-muted`. + +File name: `--font-mono`, `--type-breadcrumb` (13px), font-weight 500, `--color-orange`. + +Separator: "·" in `--text-muted`. + +Summary: `--font-body`, `--type-breadcrumb` (13px), `--text-muted`. Shows comment count (e.g., "2 comments submitted"). + +Props: `path: string`, `commentCount: number`. + +#### ReviewBlock + +A wrapper around a single rendered markdown block (paragraph, heading, list, code block) inside the ReviewPanel organism. The entire block is a click target for opening a comment input. A small "+" button in the left gutter appears on hover as a visual hint. + +Container: `display: flex`, `align-items: center`, `gap: 10px`, `padding: 4px 12px`, `margin: 0 -12px`, `border-radius: var(--radius-lg)`, `cursor: pointer`. Transition: `background var(--duration-fast) var(--ease-default)`. + +Hover state: `background: var(--bg-selected)`. The gutter button becomes visible. + +Active state (comment input open): `background: var(--bg-selected)`, `border-left: 3px solid --color-orange`, `padding-left: 9px`, `margin-left: -15px`. The gutter button is persistently visible. + +Gutter button: flex child, `flex-shrink: 0`, `width: 18px`, `height: 18px`, `--radius-circle`. Background `--color-orange`, white "+" text, 12px. `opacity: 0` by default, `opacity: 1` on block hover or active state. Transition: `opacity var(--duration-fast) var(--ease-default)`. Hover: `background: var(--color-orange-hover)`. The button occupies its 18px width even when invisible (opacity: 0), keeping content indented consistently with no layout shift on hover. + +Content wrapper: `flex: 1`, `min-width: 0`. First child margin zeroed via `.rb-content > :first-child { margin-top: 0 }` to align content flush with the gutter button. + +Click behavior: clicking anywhere on the block opens the comment input. Text selection is preserved — the click handler checks `window.getSelection()` and skips if text was selected via drag. The gutter button click calls `stopPropagation` to prevent double-firing. + +Props: `hasComments: boolean`, `isActive: boolean`, `onClickGutter: () => void`, `children: ReactNode`. + +#### ReviewComment + +A read-only comment card displayed below its anchor ReviewBlock. Gray left accent on the white card surface (user-content convention, matching UserBubble). A delete button appears on hover. + +Container: `border-left: 3px solid --text-muted`, `padding: 6px 12px`, `margin-bottom: 4px`. No background (inherits `--bg-card` from ReviewPanel). Uses the gray left-border convention for user-authored content, matching UserBubble. + +Header row: `display: flex`, `align-items: center`, `justify-content: space-between`. + +Meta line: `--type-badge` (10px), `--text-muted`, `text-transform: uppercase`, `letter-spacing: 0.5px`, font-weight 500. Shows "You · just now" (timestamps are cosmetic in review context). + +Delete button: `×` character, 14px, `--text-muted`, `opacity: 0` by default. Appears on `.rc-comment:hover` via `opacity: 1`. On button hover: `color: --status-failed` (red). Transition: opacity and color, `--duration-fast`. Click calls `onDelete` and stops propagation to prevent ReviewBlock toggle. + +Comment text: `--type-breadcrumb` (13px), `line-height: 1.5`, `--text-body`. + +Props: `text: string`, `onDelete?: () => void`. + +#### ReviewCommentInput + +An inline comment input form that appears below a ReviewBlock when the user clicks the gutter "+" button. + +Container: `background: var(--bg-card)`, `border: 1.5px solid --color-orange`, `border-radius: var(--radius-lg)`, `padding: 10px 12px`, `margin: 6px 0 12px 0`. Focus ring appears only when the textarea is focused: `:focus-within` adds `box-shadow: 0 0 0 3px var(--focus-ring)`. + +Textarea: `--font-body`, `--type-breadcrumb` (13px), `line-height: 1.5`, `--text-body`. No border, transparent background. `min-height: 44px`, `resize: vertical`. Placeholder: `--text-placeholder`, text "Add a comment on this block...". + +Actions row: `display: flex`, `justify-content: flex-end`, `gap: 8px`, `margin-top: 6px`. Contains Cancel (Button secondary `xs`) and Add comment (Button primary `xs`). + +On "Add comment": the input closes, a ReviewComment card appears in its place, and the block's `hasComment` state becomes true (orange dot indicator visible). + +Props: `onAdd: (text: string) => void`, `onCancel: () => void`. + #### FeedbackInput Text input for sending messages to the orchestrator. Sits at the bottom of the content stream. @@ -337,8 +413,43 @@ Only the active section renders. Side nav controls which section is visible. - **Profiles:** EntityRows + InlineForm for create/edit + Button text trigger. All inside a section card. - **Agents:** TabBar for runner types + EntityRows for installations + InlineForm for create/edit. All inside a section card. - **Runtime:** NumberInput for scout concurrency (with heading above), then SettingRows with Toggle/Select controls. Hairline `0.5px solid --border-card` divider separates the scalar controls from the SettingRow list. All inside a section card. +- **Workflow:** SettingRow with Toggle for "Auto-open new or changed artifacts" (default: on). Description: "Automatically open artifacts for review when they are created or modified." Additional SettingRows for future workflow preferences. Inside a section card. - **Preferences, Debug, About:** future sections using the same patterns. +### ReviewPanel + +Full-width artifact review surface that takes over the content column when an artifact is opened for review. Renders a markdown document with per-block inline commenting. The ArtifactsSidebar remains visible — the user can switch between artifacts during review. + +**Trigger:** auto-opens when a new or modified artifact is detected (gated by the "Auto-open artifacts" setting, default: on). Also opens when the user clicks an artifact in the ArtifactsSidebar. + +**Yield behavior:** opening a ReviewPanel yields the conversation (same mechanism as AskQuestion). The orchestrator is blocked until the user submits or closes the review. The FeedbackInput is not rendered while ReviewPanel is active. + +Card container: `--bg-card`, `--radius-2xl` (12px), `0.5px solid --border-card`, `border-top: 3px solid --color-orange`. Same card treatment as ElicitationPanel decision panel. + +**Header:** `display: flex`, `align-items: center`, `gap: 12px`, `padding: 16px 24px`, `border-bottom: 0.5px solid --border-divider-light`. + +- "REVIEW" label: `--type-label` (11px), font-weight 500, uppercase, `letter-spacing: 1px`, `--color-orange`. Same treatment as SectionLabel with color="orange". +- File path: `--font-mono`, `--type-tool-type` (12px), `--text-muted`. +- Right side: comment count badge — `--type-badge` (10px), `--text-muted`, `padding: 2px 10px`, `background: var(--bg-tool-row)`, `--radius-pill`. Shows "N comments" or "new" badge (`--type-badge`, `--color-orange`, font-weight 500, `padding: 2px 8px`, `background: var(--bg-selected)`, `0.5px solid --color-orange`, `--radius-pill`) when the artifact has not been reviewed yet. + +**Body:** `padding: 20px 24px 12px 24px`. Contains a stack of ReviewBlock elements, each wrapping a rendered markdown AST node (paragraph, heading, list, code block, horizontal rule). The markdown is rendered using the existing Md component. Each top-level AST node is wrapped in a ReviewBlock. + +**Footer:** `border-top: 0.5px solid --border-divider-light`, `padding: 16px 24px`. + +- Top section: "OVERALL FEEDBACK (OPTIONAL)" label (`--type-label`, 11px, font-weight 500, uppercase, `letter-spacing: 0.5px`, `--text-muted`, `margin-bottom: 6px`). Below it, a textarea (`1.5px solid --border-input`, `--radius-lg`, `padding: 10px 14px`, `--font-body`, `--type-breadcrumb` 13px, `--text-body`, `background: var(--bg-card)`, `min-height: 52px`, `resize: vertical`). Focus: `border-color: --color-orange`, `box-shadow: 0 0 0 3px var(--focus-ring)`. Placeholder: "Summarize your review — e.g. 'Looks good, just clarify the channel types and add PagerDuty'". +- Bottom section (`margin-top: 12px`): `display: flex`, `align-items: center`, `gap: 12px`. Left: hint text (`--type-label` 11px, `--text-hint`) showing "N inline comments will be submitted" or "No comments yet — click + on any block above". Right (pushed via flex spacer): "Close without submitting" (Button secondary `sm`) and "Submit review" (Button primary `sm`). + +**Submit payload:** When the user clicks "Submit review", the frontend collects: + +1. Per-block comments: each comment paired with the first 200 characters of its anchor block's text content (for the agent to locate the block in the markdown source). +2. The overall feedback summary text (may be empty). + +These are sent to the backend as a single structured message. A ReviewEvent molecule is inserted into the content stream, and the content column returns to the normal stream view. + +**Close without submitting:** discards all draft comments and closes the review. No ReviewEvent is inserted. The content column returns to the stream. The artifact can be reopened from the sidebar. + +**Switching artifacts:** clicking a different artifact in the ArtifactsSidebar while reviewing swaps the ReviewPanel body to show the new artifact. Draft comments are preserved per-artifact in component-local state — switching back restores them. + --- ## Header Bar @@ -408,7 +519,7 @@ A teal dot sitting on a horizontal rule signals a system event — something str Left-border color on stream cards encodes content origin: - **Orange** — agent prose (ProseCard). -- **Gray (`--text-muted`)** — user messages (UserBubble). +- **Gray (`--text-muted`)** — user content: messages (UserBubble), review comments (ReviewComment). - **Teal** — system events (PhaseMarker label uses teal text rather than a border, but the principle holds). ### Save model @@ -430,3 +541,11 @@ FeedbackInput rewrites `/plan-spec ...` into natural language before sending to ### Internal tool call suppression Koan orchestration tools (`koan_yield`, `koan_complete_step`, `koan_set_phase`) are internal to the workflow engine. Their effects are visible through the molecules they trigger (YieldPanel, StepHeader, PhaseMarker). They do not render as ToolCallRows in the content stream. + +### Orange dot-on-divider = user event + +The dot-on-divider pattern is extended with color semantics. A **teal dot** signals a system event (PhaseMarker — the workflow engine changed phase). An **orange dot** signals a user event (ReviewEvent — the user submitted artifact feedback). Both use identical layout; only the dot color differs. This preserves the "events happen between content" principle while distinguishing system-initiated from user-initiated transitions. + +### Review card pattern + +The ReviewPanel card uses `border-top: 3px solid --color-orange`, the same "panel-level attention" signal as ElicitationPanel's decision panel. Both are organisms that yield the conversation and require user action to proceed. The visual consistency communicates this shared interaction pattern: the workflow is paused, waiting for you. From 9ceb1de97bccf056412cd58a6c425f1318f72c58 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 11:26:59 +0700 Subject: [PATCH 367/412] feat: add sessions list/delete API endpoints --- koan/web/app.py | 57 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/koan/web/app.py b/koan/web/app.py index 72a65fd..15ebdba 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -57,6 +57,7 @@ # without a build step. FRONTEND_DIST = Path(__file__).parent / "static" / "app" +RUNS_DIR = Path.home() / ".koan" / "runs" # -- Helpers ------------------------------------------------------------------ @@ -341,7 +342,12 @@ async def api_start_run(r: Request) -> Response: await atomic_write_json( run_dir / "task.json", - {"task": task, "workflow": workflow_name, "created_at": time.time()}, + { + "task": task, + "workflow": workflow_name, + "created_at": time.time(), + "project_dir": st.project_dir, + }, ) st.task_description = task @@ -984,6 +990,53 @@ async def api_initial_prompt(r: Request) -> Response: return JSONResponse({"prompt": st.initial_prompt, "project_dir": st.project_dir}) +# -- Sessions endpoints ------------------------------------------------------- + +async def api_sessions_list(r: Request) -> Response: + sessions = [] + if RUNS_DIR.is_dir(): + entries = sorted(RUNS_DIR.iterdir(), reverse=True) + for run_path in entries: + if not run_path.is_dir(): + continue + task_file = run_path / "task.json" + try: + data = json.loads(task_file.read_text()) + except (FileNotFoundError, json.JSONDecodeError): + continue + sessions.append({ + "run_id": run_path.name, + "task": data.get("task", ""), + "workflow": data.get("workflow", ""), + "created_at": data.get("created_at", 0), + "project_dir": data.get("project_dir", ""), + }) + return JSONResponse({"sessions": sessions}) + + +async def api_sessions_delete(r: Request) -> Response: + run_id = r.path_params["run_id"] + if not run_id or "/" in run_id or "\\" in run_id or ".." in run_id: + return JSONResponse( + {"error": "invalid", "message": "invalid run_id"}, + status_code=400, + ) + run_path = RUNS_DIR / run_id + if not run_path.is_dir(): + return JSONResponse( + {"error": "not_found", "message": f"session '{run_id}' not found"}, + status_code=404, + ) + st = _app_state(r) + if st.run_dir and Path(st.run_dir).resolve() == run_path.resolve(): + return JSONResponse( + {"error": "active_run", "message": "cannot delete the currently active run"}, + status_code=409, + ) + shutil.rmtree(run_path) + return JSONResponse({"ok": True}) + + # -- App factory -------------------------------------------------------------- def _build_mcp(app_state: AppState): @@ -1070,6 +1123,8 @@ async def _wait_proc(aid: str, proc: asyncio.subprocess.Process) -> None: Route("/api/settings/profile-form", api_settings_profile_form, methods=["GET"]), Route("/api/settings/installation-form", api_settings_installation_form, methods=["GET"]), Route("/api/initial-prompt", api_initial_prompt, methods=["GET"]), + Route("/api/sessions", api_sessions_list, methods=["GET"]), + Route("/api/sessions/{run_id}", api_sessions_delete, methods=["DELETE"]), Route("/events", sse_stream), ] From e460a08d61abb183e9eeeea7d760dd01e847d0a9 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 11:37:40 +0700 Subject: [PATCH 368/412] feat: add sessions page backed by sessions API --- frontend/src/App.tsx | 3 +- frontend/src/api/client.ts | 18 +++ .../src/components/organisms/SessionsPage.css | 47 +++++++ .../src/components/organisms/SessionsPage.tsx | 122 ++++++++++++++++++ 4 files changed, 189 insertions(+), 1 deletion(-) create mode 100644 frontend/src/components/organisms/SessionsPage.css create mode 100644 frontend/src/components/organisms/SessionsPage.tsx diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index cca62f3..955adbe 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -49,6 +49,7 @@ import { Notification } from './components/Notification' // import { SettingsOverlay } from './components/SettingsOverlay' import { SettingsPage, type Profile as SPProfile, type Installation as SPInstallation } from './components/organisms/SettingsPage' import { ReviewPanel, type ReviewSubmitPayload } from './components/organisms/ReviewPanel' +import { SessionsPage } from './components/organisms/SessionsPage' // --------------------------------------------------------------------------- // Header data @@ -705,7 +706,7 @@ export default function App() { {page === 'new-run' && <div className="single-column"><NewRunForm /></div>} {page === 'sessions' && ( <div className="single-column"> - <div className="loading-center">Sessions — coming soon</div> + <SessionsPage /> </div> )} {page === 'settings' && <ConnectedSettingsPage />} diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index a732c85..e5882ef 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -157,3 +157,21 @@ export async function getArtifactContent( ): Promise<{ content: string; displayPath: string }> { return get(`/api/artifacts/${encodeURIComponent(path)}`) } + +// -- Sessions ---------------------------------------------------------------- + +export interface Session { + run_id: string + task: string + workflow: string + created_at: number + project_dir: string +} + +export async function listSessions(): Promise<{ sessions: Session[] }> { + return get('/api/sessions') +} + +export async function deleteSession(run_id: string): Promise<{ ok: boolean; error?: string; message?: string }> { + return del(`/api/sessions/${encodeURIComponent(run_id)}`) +} diff --git a/frontend/src/components/organisms/SessionsPage.css b/frontend/src/components/organisms/SessionsPage.css new file mode 100644 index 0000000..eb5d777 --- /dev/null +++ b/frontend/src/components/organisms/SessionsPage.css @@ -0,0 +1,47 @@ +.sessions-list { + display: flex; + flex-direction: column; + gap: 0.75rem; +} + +.session-row { + background: var(--bg-card); + border: 1px solid var(--border-card); + border-radius: 6px; /* no radius token exists; 6px matches card convention */ + padding: 0.75rem 1rem; + display: flex; + flex-direction: column; + gap: 0.375rem; +} + +.session-row-meta { + color: var(--text-muted); + font-size: 0.75rem; +} + +.session-row-preview { + color: var(--text-primary); + font-size: 0.875rem; +} + +.session-row-actions { + display: flex; + flex-direction: row; + justify-content: flex-end; + align-items: center; + gap: 0.5rem; + margin-top: 0.25rem; +} + +.session-row-confirm-label { + color: var(--text-muted); + font-size: 0.75rem; + margin-right: 0.25rem; +} + +.sessions-empty, +.sessions-error { + color: var(--text-muted); + text-align: center; + padding: 2rem 0; +} diff --git a/frontend/src/components/organisms/SessionsPage.tsx b/frontend/src/components/organisms/SessionsPage.tsx new file mode 100644 index 0000000..38df21d --- /dev/null +++ b/frontend/src/components/organisms/SessionsPage.tsx @@ -0,0 +1,122 @@ +import { useState, useEffect } from 'react' +import * as api from '../../api/client' +import { Button } from '../atoms/Button' +import './SessionsPage.css' + +// -- Helpers ------------------------------------------------------------------ + +function formatDate(ts: number): string { + return new Date(ts * 1000).toLocaleString() +} + +function truncate(s: string, n: number): string { + return s.length > n ? s.slice(0, n) + '...' : s +} + +// -- Component ---------------------------------------------------------------- + +export function SessionsPage() { + const [sessions, setSessions] = useState<api.Session[]>([]) + const [loading, setLoading] = useState(true) + const [error, setError] = useState<string | null>(null) + // run_id of the row currently awaiting delete confirmation, or null + const [confirmingDelete, setConfirmingDelete] = useState<string | null>(null) + + useEffect(() => { + api.listSessions() + .then(r => setSessions(r.sessions)) + .catch(e => setError(String(e))) + .finally(() => setLoading(false)) + }, []) + + function handleDeleteRequest(run_id: string) { + setConfirmingDelete(run_id) + } + + function handleDeleteCancel() { + setConfirmingDelete(null) + } + + async function handleDeleteConfirm(run_id: string) { + // Optimistically remove the row and reset confirmation state. + setSessions(prev => prev.filter(s => s.run_id !== run_id)) + setConfirmingDelete(null) + try { + await api.deleteSession(run_id) + } catch { + // On failure re-fetch to restore accurate list state. + try { + const r = await api.listSessions() + setSessions(r.sessions) + } catch { + // If re-fetch also fails, leave the optimistic state in place. + } + } + } + + if (loading) { + return <div className="loading-center">Loading...</div> + } + + if (error) { + return <div className="sessions-error">{error}</div> + } + + if (sessions.length === 0) { + return <div className="sessions-empty">No previous sessions.</div> + } + + return ( + <div className="sessions-list"> + {sessions.map(s => ( + <div key={s.run_id} className="session-row"> + <div className="session-row-meta"> + {s.project_dir || '-'} · {formatDate(s.created_at)} + </div> + <div className="session-row-preview"> + {truncate(s.task, 120)} + </div> + <div className="session-row-actions"> + {confirmingDelete === s.run_id ? ( + <> + <span className="session-row-confirm-label">Confirm?</span> + <Button + variant="danger" + size="sm" + onClick={() => handleDeleteConfirm(s.run_id)} + > + Yes, delete + </Button> + <Button + variant="secondary" + size="sm" + onClick={handleDeleteCancel} + > + Cancel + </Button> + </> + ) : ( + <> + <Button + variant="secondary" + size="sm" + disabled + title="Not yet implemented" + > + Resume + </Button> + <Button + variant="danger" + size="sm" + onClick={() => handleDeleteRequest(s.run_id)} + > + Delete + </Button> + </> + )} + </div> + </div> + ))} + </div> + ) +} From df9c2760f59240613aa093ce2d65cb2ae9d0a339 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 17:12:45 +0700 Subject: [PATCH 369/412] feat: collapse intake phase into two-step flow --- docs/intake-loop.md | 59 ++++++++++++++++++++++--------------------- koan/phases/intake.py | 55 +++++++++++++++------------------------- 2 files changed, 50 insertions(+), 64 deletions(-) diff --git a/docs/intake-loop.md b/docs/intake-loop.md index 11d94f3..d16e5ff 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -1,6 +1,6 @@ # Intake Phase Design -How the intake phase gathers context in three steps, and the prompt +How the intake phase gathers context in two steps, and the prompt engineering principles that govern it. > Parent doc: [architecture.md](./architecture.md) @@ -10,27 +10,26 @@ engineering principles that govern it. ## Overview -The intake phase is the most consequential subagent in the pipeline. Its -single output -- `landscape.md` -- is the sole input for all downstream phases. -Every story boundary, every implementation plan, and every line of code -produced downstream depends on the completeness and accuracy of that file. -Gaps in `landscape.md` compound: a missed decision becomes a wrong story -boundary becomes a wrong plan becomes wrong code. +The intake phase is the most consequential phase in the pipeline. Its +output -- verified understanding of the task and codebase -- is the foundation +for all downstream phases. Every implementation plan and every line of code +produced downstream depends on the completeness and accuracy of what intake +discovers. Gaps compound: a missed decision becomes a wrong plan becomes +wrong code. -The intake phase runs a focused **three-step workflow**: gather context -(conversation + codebase orientation + scouts), evaluate findings and ask the -user questions, then write `landscape.md`. +The intake phase runs a focused **two-step workflow**: gather context +(conversation + codebase orientation + scouts), then deepen understanding +through dialogue and summarize findings. ### Step structure -| Step | Name | Runs | Purpose | -| ---- | -------- | ---- | --------------------------------------------------------------------------------- | -| 1 | Gather | 1x | Read conversation, open obvious files (≤5), dispatch 3-5 scouts. | -| 2 | Deepen | 1x | Process scout results, verify by reading files, deepen understanding through iterative dialogue. | -| 3 | Write | 1x | Write `landscape.md`. The artifact is available in the artifacts panel. | +| Step | Name | Runs | Purpose | +| ---- | ------ | ---- | -------------------------------------------------------------------------------------------------- | +| 1 | Gather | 1x | Read conversation, open obvious files (<=5), dispatch scouts. | +| 2 | Deepen | 1x | Process scout results, verify by reading files, deepen through iterative dialogue, then summarize. | -All steps advance linearly. The phase boundary after step 3 gives the user a -natural point to review `landscape.md` and discuss next steps. +All steps advance linearly. The phase boundary after step 2 gives the user a +natural point to review the summary and discuss next steps. --- @@ -59,6 +58,7 @@ directly, identifies gaps, and asks the user targeted questions -- then deepens further as each answer reveals new dimensions. Key properties: + - **Scout verification**: Scouts are good at exploration but their output should be confirmed. The Deepen step reads actual files to verify key scout findings that affect scope or story boundaries. @@ -71,24 +71,23 @@ Key properties: - **Default-ask framing**: Question-asking is the default; skipping requires triple justification. This inverts the typical LLM bias toward advancing. -### Step 3: Write - -The Write step produces `landscape.md` with required sections (Task Summary, -Prior Art, Codebase Findings, Project Conventions, Decisions, Constraints, -Open Items). After writing, the phase completes and the orchestrator presents -suggested next phases at the boundary. +The Deepen step concludes by synthesizing a concise summary covering: task +scope, key codebase findings, decisions made, constraints, and open items. +This summary lives in the LLM's context -- downstream phases (plan-spec, +plan-review) trust it as their starting point. See +[phase-trust.md](./phase-trust.md) for the trust model. --- ## Phase Boundary -After step 3 completes, `get_next_step()` returns `None`, which triggers the -phase boundary. The orchestrator summarizes what was accomplished, presents -suggested next phases with descriptions, and asks the user what to do next. +After step 2 completes, `get_next_step()` returns `None`, which triggers the +phase boundary. The orchestrator presents suggested next phases with +descriptions, and asks the user what to do next. ```python def get_next_step(step, ctx): - if step < 3: + if step < TOTAL_STEPS: return step + 1 return None # phase complete ``` @@ -103,10 +102,12 @@ mechanisms that address specific failure modes. ### MARP (Maximizing Operations per Step) -The three-step structure applies the MARP principle: maximize operations +The two-step structure applies the MARP principle: maximize operations per `koan_complete_step` call while minimizing planning or meta-reasoning steps. Each step does real work across multiple activities rather than -artificially separating them into sequential tool calls. +artificially separating them into sequential tool calls. The summary +(previously a separate step) is folded into the Deepen step's conclusion +because a strong model can handle both activities in a single pass. ### Iterative deepening through dialogue diff --git a/koan/phases/intake.py b/koan/phases/intake.py index cb098b1..5f51126 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -1,10 +1,8 @@ -# Intake phase -- 3-step workflow. +# Intake phase -- 2-step workflow. # -# Step 1 (Gather) -- read task description, explore obvious files, dispatch scouts -# Step 2 (Deepen) -- process scout results, verify, deepen through dialogue -# Step 3 (Summarize) -- synthesize findings, present summary, transition +# Step 1 (Gather) -- read task description, explore obvious files, dispatch scouts +# Step 2 (Deepen) -- process scout results, deepen through dialogue, summarize # -# Step 3 completes unconditionally -- no review gate. # Workflow scope framing (phase_instructions) appears at the top of step 1 guidance. from __future__ import annotations @@ -13,12 +11,11 @@ ROLE = "intake" SCOPE = "general" # reusable by any workflow -TOTAL_STEPS = 3 +TOTAL_STEPS = 2 STEP_NAMES: dict[int, str] = { 1: "Gather", 2: "Deepen", - 3: "Summarize", } SYSTEM_PROMPT = ( @@ -246,44 +243,32 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: " plan without hedging.", "- No answer you received left you with a 'I think I know what they mean'", " feeling -- you either confirmed it or asked.", + "", + "## 4. Summarize and transition", + "", + "When deepening is complete, synthesize a concise summary covering:", + "", + "- **Task scope**: What is being built or changed, in the user's framing.", + "- **Key codebase findings**: Entry points, current behavior, integration points.", + "- **Decisions made**: Every question you asked and the user's answer.", + "- **Constraints**: Technical, timeline, or compatibility boundaries.", + "- **Open items**: Anything still unresolved (if any).", + "", + "Describe what IS, not what SHOULD be done. No recommendations, no", + "deliverables, no implementation suggestions.", + "", + "Call `koan_complete_step` to finish intake.", ], ) - if step == 3: - lines = [ - "Synthesize what you learned and present a summary to the user.", - "", - "## What to summarize", - "", - "Present a concise summary covering:", - "", - "- **Task scope**: What is being built or changed, in the user's framing.", - "- **Key codebase findings**: The most important things you discovered about", - " the relevant code — entry points, current behavior, integration points.", - "- **Decisions made**: Every question you asked and the user's answer.", - "- **Constraints**: Technical, timeline, or compatibility boundaries.", - "- **Open items**: Anything still unresolved (if any).", - "", - "Describe what IS, not what SHOULD be done. No recommendations, no", - "deliverables, no implementation suggestions.", - "", - "## After summarizing", - "", - "Call `koan_complete_step`. The phase boundary will provide suggested", - "next phases and their descriptions. Present them to the user and ask", - "which direction they want to go.", - ] - return StepGuidance(title=STEP_NAMES[3], instructions=lines) - return StepGuidance(title=f"Step {step}", instructions=[f"Execute step {step}."]) # -- Lifecycle ----------------------------------------------------------------- def get_next_step(step: int, ctx: PhaseContext) -> int | None: - if step < 3: + if step < TOTAL_STEPS: return step + 1 - # Step 3 (Summarize): terminal — no review gate. return None From 2c753fedbaf0d2a618f6b0fc509e7a75dfc12b23 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 17:12:57 +0700 Subject: [PATCH 370/412] feat: enforce phase trust boundaries in plan workflow --- docs/phase-trust.md | 83 ++++++++++++++++++++++++++++++++++++++ koan/lib/workflows.py | 8 +++- koan/phases/execute.py | 5 ++- koan/phases/plan_review.py | 41 +++++++++++++------ koan/phases/plan_spec.py | 21 ++++++---- 5 files changed, 134 insertions(+), 24 deletions(-) create mode 100644 docs/phase-trust.md diff --git a/docs/phase-trust.md b/docs/phase-trust.md new file mode 100644 index 0000000..bc3be96 --- /dev/null +++ b/docs/phase-trust.md @@ -0,0 +1,83 @@ +# Phase Trust Model + +Design decision document for how phases in the plan workflow relate to each +other's outputs. + +## Principle + +Phases trust each other's outputs. Verification happens _within_ a phase, +not across phases. The user reviews artifacts at phase boundaries. + +The single exception is **plan-review**, whose entire purpose is adversarial +verification of claims made by prior phases. + +## Why + +Re-verification across phases is the "intrinsic self-correction" anti-pattern: +the same LLM re-checking its own prior work without external feedback. Research +shows this typically degrades performance -- the model is more likely to change +correct conclusions to incorrect ones than the reverse. + +The fix is structural: designate one phase (plan-review) as the verification +phase, give it an adversarial posture, and have it use the codebase as an +external verification tool (the CRITIC pattern). All other phases trust the +chain. + +## Phase responsibilities + +### intake (2 steps: Gather, Deepen) + +- Explores the codebase, asks the user targeted questions, resolves ambiguity. +- Owns: uncertainty resolution. Its output is verified understanding. +- Downstream phases trust intake's findings as their starting point. + +### plan-spec (2 steps: Analyze, Write) + +- Reads codebase files to write precise implementation instructions. +- Trusts intake's findings. Reads code to understand structure for planning, + not to re-verify what intake discovered. +- Owns: plan.md -- the implementation artifact. + +### plan-review (2 steps: Read, Evaluate) + +- The designated adversarial verifier. Trusts nobody. +- Opens every file the plan references and checks every claim (paths, function + names, signatures, types) against reality. +- Owns: verification. Uses the codebase as an external tool to validate claims. +- Advisory only -- reports findings, does not modify plan.md. + +### execute (2 steps: Compose, Request) + +- Composes the executor handoff from plan.md and plan-review findings. +- Trusts the plan (it has been reviewed). Does not re-evaluate. +- Owns: clean handoff to the executor agent. + +## Data flow + +``` +task_description + | + v + intake ---- questions/answers ----> user + | + | (trusted context in LLM memory) + v + plan-spec ----> plan.md + | + | (artifact in run_dir) + v + plan-review ----> severity-classified findings (in chat) + | \ + | +---> loop back to plan-spec if critical/major + v + execute ----> koan_request_executor(artifacts, instructions) +``` + +## What this means for prompt design + +- **Do NOT** add "verify against the actual code" directives to phases other + than plan-review. That directive belongs exclusively to the adversarial phase. +- **Do** tell phases to trust prior phase output: "Intake has already explored + the codebase and resolved ambiguities. Trust those findings." +- **Do** tell plan-review it trusts nobody: "You are the only phase that + independently checks claims against reality." diff --git a/koan/lib/workflows.py b/koan/lib/workflows.py index f8bacf4..3662d98 100644 --- a/koan/lib/workflows.py +++ b/koan/lib/workflows.py @@ -6,7 +6,7 @@ # # Design notes: # - frozen=True prevents field reassignment after construction (mutation protection). -# - frozen=True does NOT make Workflow hashable — dict fields are unhashable. +# - frozen=True does NOT make Workflow hashable --dict fields are unhashable. # Do not use Workflow as a dict key or set member. # - Workflows are defined as module-level constants (PLAN_WORKFLOW, etc.). # - Phase transition validation: any phase in available_phases is reachable @@ -31,6 +31,12 @@ class Workflow: phase_descriptions: One-line description of each phase shown at boundaries. phase_guidance: Per-phase scope framing injected at the top of step 1 guidance. Controls investigation depth, question posture, etc. + + Only workflow-agnostic phases (intake, execute) need entries here. + These phases are reused across workflows, so the workflow injects + context they cannot hardcode. Workflow-specific phases (plan-spec, + plan-review) carry their own context -- they do not need injection + because they ARE the workflow. """ name: str description: str diff --git a/koan/phases/execute.py b/koan/phases/execute.py index cf25770..65ab035 100644 --- a/koan/phases/execute.py +++ b/koan/phases/execute.py @@ -21,8 +21,9 @@ } SYSTEM_PROMPT = ( - "You are an execution coordinator. You translate accumulated session knowledge" - " into a structured executor handoff. You do NOT write code.\n" + "You are an execution coordinator. The plan has been written and reviewed.\n" + "Your job is to compose a clean handoff to the executor agent. You do NOT\n" + "write code and you do NOT re-evaluate the plan.\n" "\n" "## Your role\n" "\n" diff --git a/koan/phases/plan_review.py b/koan/phases/plan_review.py index 6a21ec1..1e0a25f 100644 --- a/koan/phases/plan_review.py +++ b/koan/phases/plan_review.py @@ -20,17 +20,25 @@ } SYSTEM_PROMPT = ( - "You are a quality reviewer pressure-testing an implementation plan.\n" + "You are the adversarial reviewer for an implementation plan.\n" "\n" - "You verify all codebase claims against actual source files. You report findings" - " organized by severity. You are advisory -- you do NOT modify plan.md directly.\n" + "You are the ONLY phase in this workflow that independently verifies claims\n" + "against the actual codebase. Intake explored and gathered context. Plan-spec\n" + "structured that context into a plan. Neither was asked to doubt the other.\n" + "Your job is to doubt both.\n" "\n" "## Your role\n" "\n" - "Find problems in the plan before the executor runs. Focus on issues that would" - " cause the executor to fail or produce wrong results. Do NOT flag trivial issues" - " the executor can resolve independently (wrong filenames, syntax errors in" - " snippets, missing imports, minor typos -- executors handle these routinely).\n" + "Find problems that would cause the executor to fail or produce wrong results.\n" + "Verify every codebase claim the plan makes -- file paths, function names,\n" + "interfaces, types -- by reading the actual source files. The plan may reference\n" + "code that was renamed, moved, or never existed. Find out.\n" + "\n" + "Do NOT flag trivial issues the executor can resolve independently (minor typos,\n" + "missing imports, syntax in snippets). Focus on issues that change the approach.\n" + "\n" + "You are advisory -- you do NOT modify plan.md directly. You report findings\n" + "organized by severity.\n" "\n" "## Evaluation dimensions\n" "\n" @@ -45,7 +53,7 @@ "## Strict rules\n" "\n" "- MUST read plan.md before evaluating.\n" - "- MUST read the codebase files the plan references. Verify claims.\n" + "- MUST read the codebase files the plan references. Verify every claim.\n" "- MUST NOT modify plan.md.\n" "- MUST NOT flag issues the executor can trivially resolve.\n" ) @@ -58,13 +66,20 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: lines = [ "Read and comprehend before evaluating. Do NOT write any files in this step.", "", + "## Your verification mandate", + "", + "You are the only phase that independently checks claims against reality.", + "Intake and plan-spec trusted each other. You trust nobody.", + "", "## What to read", "", - "1. Review the intake findings in your context \u2014 requirements, constraints,", - " codebase structure, and user decisions.", - f"2. Read `{ctx.run_dir}/plan.md` -- read every section from start to finish.", - "3. Read the codebase files the plan references. For each claim the plan makes", - " (file path, function name, interface, type), verify it against the actual source.", + "1. Review the intake findings in your context for the requirements and", + " constraints the plan must satisfy.", + f"2. Read `{ctx.run_dir}/plan.md` from start to finish.", + "3. For every codebase claim in the plan (file path, function name,", + " interface, type), open the actual source file and verify. If the plan", + " says 'modify function X in file Y', confirm X exists in Y with the", + " signature the plan assumes.", "", "## Build a mental model", "", diff --git a/koan/phases/plan_spec.py b/koan/phases/plan_spec.py index 0c124ba..d4497c0 100644 --- a/koan/phases/plan_spec.py +++ b/koan/phases/plan_spec.py @@ -47,10 +47,10 @@ "\n" "## Strict rules\n" "\n" - "- MUST read the codebase files the plan references. Verify paths, signatures,\n" - " and types before including them in the plan.\n" + "- MUST read codebase files the plan references to write precise instructions.\n" + " You read to understand structure, not to re-verify intake's findings.\n" "- MUST NOT write code -- write instructions for an executor that will write code.\n" - "- MUST NOT invent file paths or function names without verifying them in the codebase.\n" + "- MUST NOT invent file paths or function names you have not seen in the codebase.\n" ) @@ -63,11 +63,16 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", "## What to read", "", - "1. Review what you learned during intake \u2014 the task scope, codebase", - " findings, decisions, and constraints are in your context.", - "2. Read every file the plan will reference. Open the actual source files", - " to verify function signatures, type names, and integration points.", - " Do not rely on intake memory alone \u2014 verify against the actual code.", + "Intake has already explored the codebase and resolved ambiguities with the", + "user. Trust those findings -- they are your starting point, not something", + "to re-investigate.", + "", + "Read the codebase files you will reference in the plan. Your goal is to", + "understand their structure well enough to write precise, file-level", + "implementation instructions. Focus on:", + "- Function signatures and type names you will reference in plan steps", + "- Integration points between files the plan will touch", + "- Ordering constraints (what depends on what)", "", "## What to analyze", "", From 4f9892765a8a8c75604ed1f9fc1262243fd3fa82 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 17:13:12 +0700 Subject: [PATCH 371/412] docs: refresh architecture links for intake and phase trust --- AGENTS.md | 3 ++- README.md | 2 +- docs/architecture.md | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 15d7e8c..2a5e009 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,8 @@ Spoke documents: - [docs/subagents.md](docs/subagents.md) -- spawn lifecycle, task manifest, step-first workflow, permissions - [docs/ipc.md](docs/ipc.md) -- HTTP MCP tool calls, blocking interactions, scout spawning, koan_yield blocking - [docs/state.md](docs/state.md) -- driver/LLM boundary, run state, orchestrator state -- [docs/intake-loop.md](docs/intake-loop.md) -- three-step intake design, prompt engineering +- [docs/intake-loop.md](docs/intake-loop.md) -- two-step intake design, prompt engineering +- [docs/phase-trust.md](docs/phase-trust.md) -- phase trust model, verification boundaries, adversarial review - [docs/projections.md](docs/projections.md) -- versioned event log, fold function, projection shape, SSE protocol, version-negotiated catch-up - [docs/token-streaming.md](docs/token-streaming.md) -- runner stdout parsing, SSE delta path diff --git a/README.md b/README.md index 14e4a14..76bf366 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ Roles map to tiers: orchestrator → strong, executor → standard, scout → ch - **[docs/ipc.md](./docs/ipc.md)** -- HTTP MCP inter-process communication, blocking tool calls - **[docs/state.md](./docs/state.md)** -- run state, driver state, routing -- **[docs/intake-loop.md](./docs/intake-loop.md)** -- three-step intake design, +- **[docs/intake-loop.md](./docs/intake-loop.md)** -- two-step intake design, prompt engineering principles - **[docs/projections.md](./docs/projections.md)** -- versioned event log, fold function, SSE protocol diff --git a/docs/architecture.md b/docs/architecture.md index dab5c98..cabc7c6 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -15,7 +15,7 @@ principles, and pitfalls that govern the codebase. ownership, run state, orchestrator state - [Projections](./projections.md) -- versioned event log, pure fold, JSON Patch protocol, projection model, camelCase wire format -- [Intake Loop](./intake-loop.md) -- three-step intake design, prompt engineering principles +- [Intake Loop](./intake-loop.md) -- two-step intake design, prompt engineering principles --- From 7642e7a31d2bda8bc578447760a29eeb7962e450 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 17:13:21 +0700 Subject: [PATCH 372/412] fix: support approval and summary-only review responses --- frontend/src/App.tsx | 68 +++++++++++++++++++++++++++------------- koan/web/mcp_endpoint.py | 27 ++++++++++++---- 2 files changed, 67 insertions(+), 28 deletions(-) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 955adbe..12a8bd2 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -550,35 +550,59 @@ function ConnectedSettingsPage() { // in the koan_yield tool docstring (koan/web/mcp_endpoint.py). Both sides // must stay in sync: the "I've reviewed `<path>`" sentinel is how the LLM // recognizes the payload as a review response. +// +// Three response types: +// 1. Approval -- no comments, no summary -> "approve it as-is" +// 2. Structured -- inline comments (+ optional summary) +// 3. Free-form -- summary only, no inline comments function formatReviewMessage(path: string, payload: ReviewSubmitPayload): string { - const out: string[] = [] - out.push( - `I've reviewed \`${path}\`. For each inline comment below, edit the cited section of the file to address it. Preserve everything not called out. When all comments are addressed, call \`koan_yield\` again so I can confirm or give another pass.`, - ) + const summary = payload.summary.trim() + const hasComments = payload.comments.length > 0 + const hasSummary = summary.length > 0 - // Group comments by blockIndex in document order. - const groups = new Map<number, { preview: string; comments: string[] }>() - for (const c of payload.comments) { - const g = groups.get(c.blockIndex) - if (g) g.comments.push(c.text) - else groups.set(c.blockIndex, { preview: c.blockPreview, comments: [c.text] }) + // Approval -- no comments and no summary means the artifact is accepted. + if (!hasComments && !hasSummary) { + return `I've reviewed \`${path}\` and approve it as-is. No changes requested.` } - const sorted = [...groups.entries()].sort(([a], [b]) => a - b) - for (const [, g] of sorted) { - out.push('') - out.push('On the section:') - for (const line of g.preview.split('\n')) out.push(`> ${line}`) - out.push('') - for (const text of g.comments) { - const parts = text.split('\n') - out.push(`- ${parts[0]}`) - for (let i = 1; i < parts.length; i++) out.push(` ${parts[i]}`) + const out: string[] = [] + + // Structured feedback -- inline comments (with optional summary). + if (hasComments) { + out.push( + `I've reviewed \`${path}\`. For each inline comment below, edit the cited section of the file to address it. Preserve everything not called out. When all comments are addressed, call \`koan_yield\` again so I can confirm or give another pass.`, + ) + + // Group comments by blockIndex in document order. + const groups = new Map<number, { preview: string; comments: string[] }>() + for (const c of payload.comments) { + const g = groups.get(c.blockIndex) + if (g) g.comments.push(c.text) + else groups.set(c.blockIndex, { preview: c.blockPreview, comments: [c.text] }) + } + const sorted = [...groups.entries()].sort(([a], [b]) => a - b) + + for (const [, g] of sorted) { + out.push('') + out.push('On the section:') + for (const line of g.preview.split('\n')) out.push(`> ${line}`) + out.push('') + for (const text of g.comments) { + const parts = text.split('\n') + out.push(`- ${parts[0]}`) + for (let i = 1; i < parts.length; i++) out.push(` ${parts[i]}`) + } } } - const summary = payload.summary.trim() - if (summary) { + // Free-form feedback -- summary only, no inline comments. + if (!hasComments && hasSummary) { + out.push( + `I've reviewed \`${path}\`. Apply the feedback below, then call \`koan_yield\` again so I can confirm or give another pass.`, + ) + } + + if (hasSummary) { out.push('') out.push(`**Summary:** ${summary}`) } diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 104c581..e7cbcdb 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -367,12 +367,27 @@ async def koan_yield( multi-turn conversation. REVIEW FEEDBACK LOOP: if the returned message begins with - "I've reviewed `<path>`", treat it as a structured review response. - The user has inspected the artifact you just produced. Revise the file - to address every inline comment and the summary (if present), then call - `koan_yield` again to await confirmation or further feedback. Do NOT - call `koan_complete_step` between review rounds; stay in the yield loop - until the user selects a "done"/"proceed" suggestion or steers elsewhere. + "I've reviewed `<path>`", the user has inspected the artifact you just + produced. There are three response types: + + 1. APPROVAL -- message says "approve it as-is". The artifact is accepted. + Proceed normally (call koan_complete_step or continue the workflow). + 2. STRUCTURED FEEDBACK -- message contains inline comments citing specific + sections. Revise each cited section to address its comments. Preserve + everything not called out. Then call koan_yield again. + 3. FREE-FORM FEEDBACK -- message contains a summary without inline + comments. Understand the requested changes, apply them to the artifact, + then call koan_yield again. + + For types 2 and 3: do NOT call koan_complete_step between review rounds. + Stay in the yield loop until the user approves or steers elsewhere. + + TEMPORAL CONTAMINATION RULE: when revising an artifact after feedback, + rewrite it as though it was correct from the start. Never reference the + previous version, the feedback, or the fact that a revision occurred. + The artifact must read as a clean first draft that incorporates the + requested changes. Do not add labels like "(revised)", "(updated)", + or "(deduplicated)" -- these leak prior state into the output. Suggestions (optional) render as clickable pills that pre-fill the chat. Each dict: id (phase name or "done"), label (short display), command From d6984433cde7689c761b238055cd33b47fbe4169 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 17:13:33 +0700 Subject: [PATCH 373/412] fix: display yield suggestion command text --- frontend/src/components/molecules/YieldPanel.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/components/molecules/YieldPanel.tsx b/frontend/src/components/molecules/YieldPanel.tsx index 7de05be..f4c3cb7 100644 --- a/frontend/src/components/molecules/YieldPanel.tsx +++ b/frontend/src/components/molecules/YieldPanel.tsx @@ -37,7 +37,7 @@ export function YieldPanel({ prompt, suggestions, onSelect }: YieldPanelProps) { <span className={`yp-command${s.recommended ? ' yp-command--recommended' : ''}`}> <span className="yp-slash">/</span>{s.id} </span> - <span className="yp-desc">{s.label}</span> + <span className="yp-desc">{s.command}</span> </div> ))} </div> From be974da1ab542e694b0598a1853e86fdd8225172 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 17:13:49 +0700 Subject: [PATCH 374/412] style: switch guidance text to ascii dash separators --- koan/phases/__init__.py | 2 +- koan/phases/format_step.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index 51066f6..e2bd7dc 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -120,7 +120,7 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> # Plan workflow phases (SCOPE="plan") "plan-spec": plan_spec, "plan-review": plan_review, - # Legacy phases (SCOPE="legacy" — dead code, available for future workflows) + # Legacy phases (SCOPE="legacy" --dead code, available for future workflows) "brief-generation": brief_writer, "core-flows": core_flows, "tech-plan": planner, diff --git a/koan/phases/format_step.py b/koan/phases/format_step.py index 127f6a2..1b2cc8e 100644 --- a/koan/phases/format_step.py +++ b/koan/phases/format_step.py @@ -80,7 +80,7 @@ def format_phase_complete( """Non-blocking response when a phase completes. Tells the orchestrator to summarize its work and call koan_yield with - structured suggestions. Does not block — koan_yield handles blocking. + structured suggestions. Does not block --koan_yield handles blocking. Args: phase: The phase that just completed (e.g. "intake"). @@ -102,7 +102,7 @@ def format_phase_complete( for p in suggested_phases: desc = descs.get(p, "") if desc: - lines.append(f"- **{p}** — {desc}") + lines.append(f"- **{p}** --{desc}") else: lines.append(f"- **{p}**") lines.append("") @@ -121,6 +121,6 @@ def format_phase_complete( lines.append("") lines.append("WHEN DONE: Call koan_yield with your suggestions.") - lines.append("Do NOT call koan_set_phase yet — wait for the user's response.") + lines.append("Do NOT call koan_set_phase yet --wait for the user's response.") return "\n".join(lines) From 27de3f71e1dbdd8f60c955efc42f127d1f269a36 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 20:48:31 +0700 Subject: [PATCH 375/412] chore: add pyyaml dependency for memory frontmatter --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index eedc45d..10f291c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,6 +8,7 @@ dependencies = [ "fastmcp", "aiofiles", "jsonpatch", + "pyyaml", ] [project.scripts] From a24c697754015b02459baaa6543154420db5cfde Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 20:48:41 +0700 Subject: [PATCH 376/412] feat: add file-based memory parsing and storage APIs --- koan/memory/__init__.py | 31 +++++++++ koan/memory/parser.py | 135 ++++++++++++++++++++++++++++++++++++++ koan/memory/store.py | 134 +++++++++++++++++++++++++++++++++++++ koan/memory/types.py | 54 +++++++++++++++ koan/memory/validation.py | 60 +++++++++++++++++ koan/memory/writer.py | 96 +++++++++++++++++++++++++++ 6 files changed, 510 insertions(+) create mode 100644 koan/memory/__init__.py create mode 100644 koan/memory/parser.py create mode 100644 koan/memory/store.py create mode 100644 koan/memory/types.py create mode 100644 koan/memory/validation.py create mode 100644 koan/memory/writer.py diff --git a/koan/memory/__init__.py b/koan/memory/__init__.py new file mode 100644 index 0000000..9667612 --- /dev/null +++ b/koan/memory/__init__.py @@ -0,0 +1,31 @@ +# koan.memory -- file-based project memory system. +# Re-exports the public API from submodules. + +from __future__ import annotations + +from .types import ( + MemoryEntry, + MemoryIndex, + MemorySource, + MemoryStatus, + MemoryType, +) +from .parser import parse_entry, parse_index +from .writer import write_entry, update_entry, write_index +from .store import MemoryStore +from .validation import validate_entry + +__all__ = [ + "MemoryType", + "MemorySource", + "MemoryStatus", + "MemoryEntry", + "MemoryIndex", + "parse_entry", + "parse_index", + "write_entry", + "update_entry", + "write_index", + "MemoryStore", + "validate_entry", +] diff --git a/koan/memory/parser.py b/koan/memory/parser.py new file mode 100644 index 0000000..91740b1 --- /dev/null +++ b/koan/memory/parser.py @@ -0,0 +1,135 @@ +# Parse memory entry markdown files into MemoryEntry / MemoryIndex. + +from __future__ import annotations + +import re +from pathlib import Path + +import yaml + +from .types import MemoryEntry, MemoryIndex + + +class ParseError(Exception): + """Raised when a memory file cannot be parsed.""" + + +def _split_frontmatter(text: str) -> tuple[dict, str]: + """Split a markdown file into YAML frontmatter dict and remaining text. + + Raises ParseError if the file does not start with a ``---`` fence. + """ + stripped = text.lstrip("\n") + if not stripped.startswith("---"): + raise ParseError("missing YAML frontmatter (no opening ---)") + + # Find closing --- + rest = stripped[3:] + m = re.search(r"^---\s*$", rest, re.MULTILINE) + if m is None: + raise ParseError("missing YAML frontmatter (no closing ---)") + + yaml_text = rest[: m.start()] + after = rest[m.end():] + meta = yaml.safe_load(yaml_text) + if not isinstance(meta, dict): + raise ParseError("YAML frontmatter is not a mapping") + return meta, after.lstrip("\n") + + +def _split_intro_body(text: str) -> tuple[str, str]: + """Separate contextual introduction (first paragraph) from body. + + The introduction ends at the first ``## `` heading or the first + blank-line-delimited paragraph break. + """ + # If text starts with a heading, there is no introduction. + if re.match(r"^##\s", text): + return "", text + + # Split at first heading. + heading_match = re.search(r"^##\s", text, re.MULTILINE) + if heading_match: + before = text[: heading_match.start()].rstrip() + after = text[heading_match.start():] + # Introduction is the first paragraph of `before`. + parts = re.split(r"\n\n+", before, maxsplit=1) + intro = parts[0].strip() + remaining = parts[1].strip() if len(parts) > 1 else "" + body = (remaining + "\n\n" + after).strip() if remaining else after.strip() + return intro, body + + # No heading -- split on double newline. + parts = re.split(r"\n\n+", text, maxsplit=1) + intro = parts[0].strip() + body = parts[1].strip() if len(parts) > 1 else "" + return intro, body + + +_REQUIRED_FIELDS = ("title", "type", "date", "source", "status") + + +def parse_entry(path: Path) -> MemoryEntry: + """Parse a memory entry markdown file into a ``MemoryEntry``. + + Raises ``ParseError`` on malformed files or missing required fields. + """ + text = path.read_text("utf-8") + meta, after = _split_frontmatter(text) + + missing = [f for f in _REQUIRED_FIELDS if f not in meta] + if missing: + raise ParseError(f"missing required frontmatter fields: {', '.join(missing)}") + + intro, body = _split_intro_body(after) + if not intro: + raise ParseError("missing contextual introduction") + if not body: + raise ParseError("missing body") + + tags = meta.get("tags") or [] + if not isinstance(tags, list): + tags = [str(tags)] + + supersedes = meta.get("supersedes") + if supersedes is not None: + supersedes = str(supersedes) + if supersedes.lower() == "null": + supersedes = None + + related = meta.get("related") or [] + if not isinstance(related, list): + related = [str(related)] + + return MemoryEntry( + title=str(meta["title"]), + type=meta["type"], + date=str(meta["date"]), + source=meta["source"], + status=meta["status"], + contextual_introduction=intro, + body=body, + tags=[str(t) for t in tags], + supersedes=supersedes, + related=[str(r) for r in related], + file_path=path, + ) + + +def parse_index(path: Path) -> MemoryIndex: + """Parse a ``_index.md`` file into a ``MemoryIndex``.""" + text = path.read_text("utf-8") + meta, after = _split_frontmatter(text) + + covers = meta.get("covers", []) + if not isinstance(covers, list): + covers = [] + covers = [int(c) for c in covers] + + return MemoryIndex( + covers=covers, + token_count=int(meta.get("token_count", 0)), + last_generated=str(meta.get("last_generated", "")), + body=after.strip(), + file_path=path, + ) diff --git a/koan/memory/store.py b/koan/memory/store.py new file mode 100644 index 0000000..fe818ea --- /dev/null +++ b/koan/memory/store.py @@ -0,0 +1,134 @@ +# High-level operations over the .koan/memory/ directory tree. + +from __future__ import annotations + +import re +from pathlib import Path + +from .types import ( + TYPE_DIRS, + MemoryEntry, + MemoryIndex, + MemorySource, + MemoryStatus, + MemoryType, +) +from .parser import parse_entry, parse_index +from .writer import write_entry as _write_entry, update_entry as _update_entry + + +class MemoryStore: + """File-backed store for koan memory entries.""" + + def __init__(self, project_root: str | Path) -> None: + self._root = Path(project_root) + self._memory_dir = self._root / ".koan" / "memory" + self._user_dir = self._root / ".koan" / "user" + + # -- Directory management --------------------------------------------------- + + def init(self) -> None: + """Create the directory structure if it doesn't exist.""" + for dir_name in TYPE_DIRS.values(): + (self._memory_dir / dir_name).mkdir(parents=True, exist_ok=True) + self._user_dir.mkdir(parents=True, exist_ok=True) + + def _type_dir(self, t: MemoryType) -> Path: + return self._memory_dir / TYPE_DIRS[t] + + # -- Query ------------------------------------------------------------------ + + def list_entries(self, type: MemoryType | None = None) -> list[MemoryEntry]: + """List entries, optionally filtered by type. Sorted by sequence number.""" + types = [type] if type is not None else list(TYPE_DIRS.keys()) + entries: list[MemoryEntry] = [] + pattern = re.compile(r"^(\d{4})-.*\.md$") + for t in types: + d = self._type_dir(t) + if not d.is_dir(): + continue + for p in sorted(d.iterdir()): + if pattern.match(p.name): + entries.append(parse_entry(p)) + return entries + + def get_entry(self, type: MemoryType, number: int) -> MemoryEntry | None: + """Find and parse a specific entry by type and sequence number.""" + d = self._type_dir(type) + if not d.is_dir(): + return None + prefix = f"{number:04d}-" + for p in d.iterdir(): + if p.name.startswith(prefix) and p.name.endswith(".md"): + return parse_entry(p) + return None + + def entry_count(self, type: MemoryType | None = None) -> int: + """Count entries, optionally filtered by type.""" + types = [type] if type is not None else list(TYPE_DIRS.keys()) + pattern = re.compile(r"^\d{4}-.*\.md$") + count = 0 + for t in types: + d = self._type_dir(t) + if not d.is_dir(): + continue + count += sum(1 for p in d.iterdir() if pattern.match(p.name)) + return count + + # -- Mutations -------------------------------------------------------------- + + def add_entry( + self, + type: MemoryType, + title: str, + date: str, + source: MemorySource, + contextual_introduction: str, + body: str, + status: MemoryStatus = "active", + tags: list[str] | None = None, + supersedes: str | None = None, + related: list[str] | None = None, + ) -> MemoryEntry: + """Create a new entry, write it to disk, return with file_path set.""" + entry = MemoryEntry( + title=title, + type=type, + date=date, + source=source, + status=status, + contextual_introduction=contextual_introduction, + body=body, + tags=tags or [], + supersedes=supersedes, + related=related or [], + ) + d = self._type_dir(type) + path = _write_entry(entry, d) + entry.file_path = path + return entry + + def update_entry(self, entry: MemoryEntry) -> None: + """Write an entry back to its existing file_path.""" + _update_entry(entry) + + def deprecate_entry(self, entry: MemoryEntry) -> None: + """Set status to 'deprecated' and write back.""" + entry.status = "deprecated" + _update_entry(entry) + + # -- Summaries / indexes ---------------------------------------------------- + + def get_summary(self) -> str | None: + """Return the content of summary.md if it exists.""" + p = self._memory_dir / "summary.md" + if p.is_file(): + return p.read_text("utf-8") + return None + + def get_index(self, type: MemoryType) -> MemoryIndex | None: + """Return the parsed _index.md for the given type, if it exists.""" + p = self._type_dir(type) / "_index.md" + if p.is_file(): + return parse_index(p) + return None diff --git a/koan/memory/types.py b/koan/memory/types.py new file mode 100644 index 0000000..656c0b3 --- /dev/null +++ b/koan/memory/types.py @@ -0,0 +1,54 @@ +# Data model for memory entries and indexes. + +from __future__ import annotations + +from dataclasses import dataclass, field +from pathlib import Path +from typing import Literal + +MemoryType = Literal["decision", "context", "lesson", "procedure", "milestone"] +MemorySource = Literal["user-stated", "llm-inferred", "post-mortem"] +MemoryStatus = Literal["active", "review-needed", "deprecated", "archived"] + +MEMORY_TYPES: tuple[MemoryType, ...] = ( + "decision", "context", "lesson", "procedure", "milestone", +) +MEMORY_SOURCES: tuple[MemorySource, ...] = ( + "user-stated", "llm-inferred", "post-mortem", +) +MEMORY_STATUSES: tuple[MemoryStatus, ...] = ( + "active", "review-needed", "deprecated", "archived", +) + +# Directory name for each memory type. +TYPE_DIRS: dict[MemoryType, str] = { + "decision": "decisions", + "context": "context", + "lesson": "lessons", + "procedure": "procedures", + "milestone": "milestones", +} + + +@dataclass +class MemoryEntry: + title: str + type: MemoryType + date: str + source: MemorySource + status: MemoryStatus + contextual_introduction: str + body: str + tags: list[str] = field(default_factory=list) + supersedes: str | None = None + related: list[str] = field(default_factory=list) + file_path: Path | None = None + + +@dataclass +class MemoryIndex: + covers: list[int] = field(default_factory=list) + token_count: int = 0 + last_generated: str = "" + body: str = "" + file_path: Path | None = None diff --git a/koan/memory/validation.py b/koan/memory/validation.py new file mode 100644 index 0000000..197eef9 --- /dev/null +++ b/koan/memory/validation.py @@ -0,0 +1,60 @@ +# Validate that a MemoryEntry conforms to the spec. + +from __future__ import annotations + +import re + +from .types import MEMORY_SOURCES, MEMORY_STATUSES, MEMORY_TYPES, MemoryEntry + +_ISO_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$") + + +def validate_entry(entry: MemoryEntry) -> list[str]: + """Return a list of validation errors (empty = valid).""" + errors: list[str] = [] + + if not entry.title: + errors.append("title is required") + + if not entry.type: + errors.append("type is required") + elif entry.type not in MEMORY_TYPES: + errors.append(f"invalid type: {entry.type}") + + if not entry.date: + errors.append("date is required") + elif not _ISO_DATE.match(entry.date): + errors.append(f"date is not a valid ISO 8601 date: {entry.date}") + + if not entry.source: + errors.append("source is required") + elif entry.source not in MEMORY_SOURCES: + errors.append(f"invalid source: {entry.source}") + + if not entry.status: + errors.append("status is required") + elif entry.status not in MEMORY_STATUSES: + errors.append(f"invalid status: {entry.status}") + + if not entry.contextual_introduction: + errors.append("contextual_introduction is required") + + if not entry.body: + errors.append("body is required") + + if entry.tags is not None: + if not isinstance(entry.tags, list): + errors.append("tags must be a list of strings") + elif not all(isinstance(t, str) for t in entry.tags): + errors.append("tags must be a list of strings") + + if entry.supersedes is not None and not isinstance(entry.supersedes, str): + errors.append("supersedes must be a string path") + + if entry.related is not None: + if not isinstance(entry.related, list): + errors.append("related must be a list of string paths") + elif not all(isinstance(r, str) for r in entry.related): + errors.append("related must be a list of string paths") + + return errors diff --git a/koan/memory/writer.py b/koan/memory/writer.py new file mode 100644 index 0000000..6515950 --- /dev/null +++ b/koan/memory/writer.py @@ -0,0 +1,96 @@ +# Write memory entries and indexes to disk. + +from __future__ import annotations + +import re +from pathlib import Path + +import yaml + +from .types import MemoryEntry, MemoryIndex + + +def _slugify(title: str, max_len: int = 50) -> str: + """Convert a title to a filename-safe slug.""" + slug = title.lower() + slug = re.sub(r"[^a-z0-9\s-]", "", slug) + slug = re.sub(r"[\s]+", "-", slug).strip("-") + slug = re.sub(r"-+", "-", slug) + return slug[:max_len].rstrip("-") + + +def _next_sequence_number(directory: Path) -> int: + """Scan ``directory`` for ``NNNN-*.md`` files and return max + 1.""" + pattern = re.compile(r"^(\d{4})-.*\.md$") + highest = 0 + if directory.is_dir(): + for p in directory.iterdir(): + m = pattern.match(p.name) + if m: + highest = max(highest, int(m.group(1))) + return highest + 1 + + +def _render_frontmatter(entry: MemoryEntry) -> str: + """Render YAML frontmatter for an entry.""" + meta: dict = { + "title": entry.title, + "type": entry.type, + "date": entry.date, + "source": entry.source, + "status": entry.status, + } + if entry.tags: + meta["tags"] = entry.tags + if entry.supersedes is not None: + meta["supersedes"] = entry.supersedes + else: + meta["supersedes"] = None + if entry.related: + meta["related"] = entry.related + + return yaml.dump(meta, default_flow_style=None, sort_keys=False, allow_unicode=False).rstrip("\n") + + +def _render_entry(entry: MemoryEntry) -> str: + """Render a complete entry file: frontmatter + intro + body.""" + fm = _render_frontmatter(entry) + return f"---\n{fm}\n---\n\n{entry.contextual_introduction}\n\n{entry.body}\n" + + +def write_entry(entry: MemoryEntry, directory: Path) -> Path: + """Write a new memory entry to ``directory``. + + Assigns the next available sequence number, generates a filename + slug from the title, writes the file, and returns its path. + """ + directory.mkdir(parents=True, exist_ok=True) + seq = _next_sequence_number(directory) + slug = _slugify(entry.title) + filename = f"{seq:04d}-{slug}.md" + path = directory / filename + path.write_text(_render_entry(entry), "utf-8") + return path + + +def update_entry(entry: MemoryEntry) -> None: + """Write an entry back to its existing ``file_path``.""" + if entry.file_path is None: + raise ValueError("entry has no file_path; use write_entry for new entries") + entry.file_path.write_text(_render_entry(entry), "utf-8") + + +def write_index(index: MemoryIndex, directory: Path) -> Path: + """Write ``_index.md`` in ``directory``.""" + directory.mkdir(parents=True, exist_ok=True) + meta = { + "type": "index", + "covers": index.covers, + "token_count": index.token_count, + "last_generated": index.last_generated, + } + fm = yaml.dump(meta, default_flow_style=None, sort_keys=False, allow_unicode=False).rstrip("\n") + text = f"---\n{fm}\n---\n\n{index.body}\n" + path = directory / "_index.md" + path.write_text(text, "utf-8") + return path From d64a0a2ce1786b4d55da0f180ba29a873e49e17d Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 20:48:48 +0700 Subject: [PATCH 377/412] test: add coverage for memory parser, writer, store, and validation --- tests/memory/__init__.py | 0 tests/memory/test_parser.py | 117 ++++++++++++++++++++++++++ tests/memory/test_store.py | 141 ++++++++++++++++++++++++++++++++ tests/memory/test_validation.py | 75 +++++++++++++++++ tests/memory/test_writer.py | 118 ++++++++++++++++++++++++++ 5 files changed, 451 insertions(+) create mode 100644 tests/memory/__init__.py create mode 100644 tests/memory/test_parser.py create mode 100644 tests/memory/test_store.py create mode 100644 tests/memory/test_validation.py create mode 100644 tests/memory/test_writer.py diff --git a/tests/memory/__init__.py b/tests/memory/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/memory/test_parser.py b/tests/memory/test_parser.py new file mode 100644 index 0000000..f2bc6fc --- /dev/null +++ b/tests/memory/test_parser.py @@ -0,0 +1,117 @@ +# Tests for koan.memory.parser + +from __future__ import annotations + +import pytest +from pathlib import Path + +from koan.memory.parser import parse_entry, parse_index, ParseError + + +WELL_FORMED = """\ +--- +title: PostgreSQL for Auth Service +type: decision +date: 2026-04-10 +source: user-stated +status: active +tags: [auth, postgresql] +supersedes: null +related: [context/0002-infrastructure.md] +--- + +This entry documents the choice of primary data store. + +On 2026-04-10, user decided to migrate the auth service from SQLite +to PostgreSQL 16.2. Rationale: concurrency. +""" + +WELL_FORMED_HEADING_BODY = """\ +--- +title: Migration Steps +type: procedure +date: 2026-04-11 +source: post-mortem +status: active +--- + +This entry covers migration procedures for the data layer. + +## Steps + +1. Create schema migration file. +2. Run migration. +""" + + +def _write(tmp_path: Path, content: str, name: str = "entry.md") -> Path: + p = tmp_path / name + p.write_text(content, "utf-8") + return p + + +class TestParseEntry: + def test_well_formed(self, tmp_path): + p = _write(tmp_path, WELL_FORMED) + e = parse_entry(p) + assert e.title == "PostgreSQL for Auth Service" + assert e.type == "decision" + assert e.date == "2026-04-10" + assert e.source == "user-stated" + assert e.status == "active" + assert e.tags == ["auth", "postgresql"] + assert e.supersedes is None + assert e.related == ["context/0002-infrastructure.md"] + assert "choice of primary data store" in e.contextual_introduction + assert "PostgreSQL 16.2" in e.body + assert e.file_path == p + + def test_heading_separates_body(self, tmp_path): + p = _write(tmp_path, WELL_FORMED_HEADING_BODY) + e = parse_entry(p) + assert "migration procedures" in e.contextual_introduction + assert e.body.startswith("## Steps") + + def test_missing_frontmatter(self, tmp_path): + p = _write(tmp_path, "Just some text without frontmatter.") + with pytest.raises(ParseError, match="missing YAML frontmatter"): + parse_entry(p) + + def test_missing_required_fields(self, tmp_path): + content = "---\ntitle: Foo\n---\n\nIntro paragraph.\n\nBody text here.\n" + p = _write(tmp_path, content) + with pytest.raises(ParseError, match="missing required frontmatter fields"): + parse_entry(p) + + def test_empty_body(self, tmp_path): + content = "---\ntitle: Foo\ntype: decision\ndate: 2026-01-01\nsource: user-stated\nstatus: active\n---\n\nOnly an intro.\n" + p = _write(tmp_path, content) + with pytest.raises(ParseError, match="missing body"): + parse_entry(p) + + def test_missing_intro(self, tmp_path): + content = "---\ntitle: Foo\ntype: decision\ndate: 2026-01-01\nsource: user-stated\nstatus: active\n---\n\n## Heading\n\nBody only.\n" + p = _write(tmp_path, content) + with pytest.raises(ParseError, match="missing contextual introduction"): + parse_entry(p) + + +class TestParseIndex: + def test_well_formed(self, tmp_path): + content = """\ +--- +type: index +covers: [1, 2, 3] +token_count: 380 +last_generated: 2026-04-15 +--- + +Active decisions cover three areas. +""" + p = _write(tmp_path, content, "_index.md") + idx = parse_index(p) + assert idx.covers == [1, 2, 3] + assert idx.token_count == 380 + assert idx.last_generated == "2026-04-15" + assert "three areas" in idx.body + assert idx.file_path == p diff --git a/tests/memory/test_store.py b/tests/memory/test_store.py new file mode 100644 index 0000000..3f3c274 --- /dev/null +++ b/tests/memory/test_store.py @@ -0,0 +1,141 @@ +# Tests for koan.memory.store + +from __future__ import annotations + +from koan.memory.store import MemoryStore + + +class TestInit: + def test_creates_directories(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + mem = tmp_path / ".koan" / "memory" + assert (mem / "decisions").is_dir() + assert (mem / "context").is_dir() + assert (mem / "lessons").is_dir() + assert (mem / "procedures").is_dir() + assert (mem / "milestones").is_dir() + assert (tmp_path / ".koan" / "user").is_dir() + + def test_idempotent(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + store.init() + assert (tmp_path / ".koan" / "memory" / "decisions").is_dir() + + +class TestAddAndList: + def test_add_and_list_round_trip(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + e = store.add_entry( + type="decision", + title="Use PostgreSQL", + date="2026-04-10", + source="user-stated", + contextual_introduction="Documents the DB choice.", + body="Chose PostgreSQL 16.2 over SQLite.", + ) + assert e.file_path is not None + assert e.file_path.exists() + + entries = store.list_entries(type="decision") + assert len(entries) == 1 + assert entries[0].title == "Use PostgreSQL" + + def test_list_all_types(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + store.add_entry("decision", "D1", "2026-01-01", "user-stated", "Intro.", "Body.") + store.add_entry("lesson", "L1", "2026-01-02", "post-mortem", "Intro.", "Body.") + store.add_entry("context", "C1", "2026-01-03", "user-stated", "Intro.", "Body.") + assert len(store.list_entries()) == 3 + + def test_list_with_type_filter(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + store.add_entry("decision", "D1", "2026-01-01", "user-stated", "Intro.", "Body.") + store.add_entry("lesson", "L1", "2026-01-02", "post-mortem", "Intro.", "Body.") + assert len(store.list_entries(type="decision")) == 1 + assert len(store.list_entries(type="lesson")) == 1 + assert len(store.list_entries(type="milestone")) == 0 + + +class TestGetEntry: + def test_by_type_and_number(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + store.add_entry("decision", "First", "2026-01-01", "user-stated", "Intro.", "Body.") + store.add_entry("decision", "Second", "2026-01-02", "user-stated", "Intro.", "Body.") + e = store.get_entry("decision", 2) + assert e is not None + assert e.title == "Second" + + def test_missing(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + assert store.get_entry("decision", 99) is None + + +class TestEntryCount: + def test_count_all(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + store.add_entry("decision", "D1", "2026-01-01", "user-stated", "Intro.", "Body.") + store.add_entry("lesson", "L1", "2026-01-02", "post-mortem", "Intro.", "Body.") + assert store.entry_count() == 2 + + def test_count_by_type(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + store.add_entry("decision", "D1", "2026-01-01", "user-stated", "Intro.", "Body.") + store.add_entry("decision", "D2", "2026-01-02", "user-stated", "Intro.", "Body.") + store.add_entry("lesson", "L1", "2026-01-03", "post-mortem", "Intro.", "Body.") + assert store.entry_count(type="decision") == 2 + assert store.entry_count(type="lesson") == 1 + + +class TestDeprecateEntry: + def test_changes_status(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + e = store.add_entry("decision", "D1", "2026-01-01", "user-stated", "Intro.", "Body.") + assert e.status == "active" + store.deprecate_entry(e) + assert e.status == "deprecated" + # Re-read from disk to verify persistence + reparsed = store.get_entry("decision", 1) + assert reparsed is not None + assert reparsed.status == "deprecated" + + +class TestSummaryAndIndex: + def test_no_summary(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + assert store.get_summary() is None + + def test_summary_exists(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + summary_path = tmp_path / ".koan" / "memory" / "summary.md" + summary_path.write_text("# Project Summary\n\nOverview here.\n", "utf-8") + assert store.get_summary() is not None + assert "Overview here" in store.get_summary() + + def test_no_index(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + assert store.get_index("decision") is None + + def test_index_exists(self, tmp_path): + from koan.memory.writer import write_index + from koan.memory.types import MemoryIndex + + store = MemoryStore(tmp_path) + store.init() + idx = MemoryIndex(covers=[1, 2], token_count=200, last_generated="2026-04-15", body="Summary.") + write_index(idx, tmp_path / ".koan" / "memory" / "decisions") + result = store.get_index("decision") + assert result is not None + assert result.covers == [1, 2] diff --git a/tests/memory/test_validation.py b/tests/memory/test_validation.py new file mode 100644 index 0000000..272bfc2 --- /dev/null +++ b/tests/memory/test_validation.py @@ -0,0 +1,75 @@ +# Tests for koan.memory.validation + +from __future__ import annotations + +from koan.memory.types import MemoryEntry +from koan.memory.validation import validate_entry + + +def _valid_entry(**overrides) -> MemoryEntry: + defaults = dict( + title="PostgreSQL for Auth", + type="decision", + date="2026-04-10", + source="user-stated", + status="active", + contextual_introduction="Documents the data store choice.", + body="Chose PostgreSQL 16.2 over SQLite.", + ) + defaults.update(overrides) + return MemoryEntry(**defaults) + + +class TestValidEntry: + def test_passes(self): + assert validate_entry(_valid_entry()) == [] + + +class TestMissingRequired: + def test_missing_title(self): + errors = validate_entry(_valid_entry(title="")) + assert any("title" in e for e in errors) + + def test_missing_type(self): + errors = validate_entry(_valid_entry(type="")) + assert any("type" in e for e in errors) + + def test_missing_date(self): + errors = validate_entry(_valid_entry(date="")) + assert any("date" in e for e in errors) + + def test_missing_source(self): + errors = validate_entry(_valid_entry(source="")) + assert any("source" in e for e in errors) + + def test_missing_status(self): + errors = validate_entry(_valid_entry(status="")) + assert any("status" in e for e in errors) + + +class TestInvalidValues: + def test_invalid_type(self): + errors = validate_entry(_valid_entry(type="opinion")) + assert any("invalid type" in e for e in errors) + + def test_invalid_source(self): + errors = validate_entry(_valid_entry(source="guessed")) + assert any("invalid source" in e for e in errors) + + def test_invalid_status(self): + errors = validate_entry(_valid_entry(status="pending")) + assert any("invalid status" in e for e in errors) + + def test_invalid_date_format(self): + errors = validate_entry(_valid_entry(date="April 10")) + assert any("ISO 8601" in e for e in errors) + + +class TestMissingContent: + def test_missing_intro(self): + errors = validate_entry(_valid_entry(contextual_introduction="")) + assert any("contextual_introduction" in e for e in errors) + + def test_missing_body(self): + errors = validate_entry(_valid_entry(body="")) + assert any("body" in e for e in errors) diff --git a/tests/memory/test_writer.py b/tests/memory/test_writer.py new file mode 100644 index 0000000..e02ded1 --- /dev/null +++ b/tests/memory/test_writer.py @@ -0,0 +1,118 @@ +# Tests for koan.memory.writer + +from __future__ import annotations + +from pathlib import Path + +from koan.memory.types import MemoryEntry +from koan.memory.writer import write_entry, update_entry, write_index, _slugify +from koan.memory.parser import parse_entry +from koan.memory.types import MemoryIndex + + +def _entry(**overrides) -> MemoryEntry: + defaults = dict( + title="PostgreSQL for Auth", + type="decision", + date="2026-04-10", + source="user-stated", + status="active", + contextual_introduction="This entry documents the choice of data store.", + body="On 2026-04-10, user chose PostgreSQL 16.2.", + ) + defaults.update(overrides) + return MemoryEntry(**defaults) + + +class TestSlugify: + def test_basic(self): + assert _slugify("PostgreSQL for Auth Service") == "postgresql-for-auth-service" + + def test_special_chars(self): + assert _slugify("What's up? (test!)") == "whats-up-test" + + def test_truncate(self): + long_title = "a" * 100 + slug = _slugify(long_title) + assert len(slug) <= 50 + + def test_trailing_hyphen_after_truncation(self): + # Title that would produce a trailing hyphen at the cut point + title = "a" * 49 + " b" + slug = _slugify(title) + assert not slug.endswith("-") + + +class TestWriteEntry: + def test_first_entry(self, tmp_path): + e = _entry() + p = write_entry(e, tmp_path) + assert p.name == "0001-postgresql-for-auth.md" + assert p.exists() + + def test_second_entry(self, tmp_path): + write_entry(_entry(), tmp_path) + p2 = write_entry(_entry(title="Redis for Sessions"), tmp_path) + assert p2.name == "0002-redis-for-sessions.md" + + def test_no_reuse_after_deletion(self, tmp_path): + """Deleting the highest-numbered file does not reuse its number + when a lower-numbered file still exists -- but the scanner only + sees current files, so max(existing)+1 is the best guarantee + without external state. When 0001 exists and 0002 is deleted, + the next file is 0002 (max(1)+1). When a *middle* file is + deleted, the gap is never filled because the scanner uses max, + not "first available".""" + write_entry(_entry(), tmp_path) # 0001 + write_entry(_entry(title="Second"), tmp_path) # 0002 + p3 = write_entry(_entry(title="Third"), tmp_path) # 0003 + assert p3.name == "0003-third.md" + # Delete the middle file -- gap at 0002 is never filled. + (tmp_path / "0002-second.md").unlink() + p4 = write_entry(_entry(title="Fourth"), tmp_path) + assert p4.name == "0004-fourth.md" + + def test_round_trip(self, tmp_path): + original = _entry( + tags=["auth", "db"], + related=["context/0001-infra.md"], + ) + p = write_entry(original, tmp_path) + parsed = parse_entry(p) + assert parsed.title == original.title + assert parsed.type == original.type + assert parsed.date == original.date + assert parsed.source == original.source + assert parsed.status == original.status + assert parsed.tags == original.tags + assert parsed.related == original.related + assert parsed.contextual_introduction == original.contextual_introduction + assert parsed.body == original.body + + +class TestUpdateEntry: + def test_preserves_filename(self, tmp_path): + e = _entry() + p = write_entry(e, tmp_path) + e.file_path = p + e.status = "deprecated" + update_entry(e) + reparsed = parse_entry(p) + assert reparsed.status == "deprecated" + assert reparsed.file_path == p + + +class TestWriteIndex: + def test_writes_index(self, tmp_path): + idx = MemoryIndex( + covers=[1, 2, 3], + token_count=380, + last_generated="2026-04-15", + body="Summary of decisions.", + ) + p = write_index(idx, tmp_path) + assert p.name == "_index.md" + assert p.exists() + text = p.read_text("utf-8") + assert "covers:" in text + assert "Summary of decisions." in text From 89b94427e233633db599335ae3bbaa2b3ba9e527 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 12 Apr 2026 20:48:58 +0700 Subject: [PATCH 378/412] plan: add memory system specification v3 --- docs/memory-system.md | 789 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 789 insertions(+) create mode 100644 docs/memory-system.md diff --git a/docs/memory-system.md b/docs/memory-system.md new file mode 100644 index 0000000..57ee7af --- /dev/null +++ b/docs/memory-system.md @@ -0,0 +1,789 @@ +# Koan Memory System — Specification v3 + +## Overview + +Koan's memory system captures project knowledge that is not derivable +from code. It prevents LLM agents from repeating mistakes, re-deriving +settled questions, and drifting from established architectural choices +across workflow runs. + +The memory system consists of markdown files stored in `.koan/memory/` +within the project repository. These files are version-controlled +alongside the project's source code, human-readable, and maintained +by koan's LLM agents with explicit user review. A retrieval layer +indexes these files and provides hybrid search (semantic + keyword) +for koan's agents to query during workflows. + +Every memory entry is a single markdown file with YAML frontmatter +carrying structured metadata and a prose body written in event-style. +This design makes each entry independently retrievable, independently +reviewable, and independently trackable via version control. + +--- + +## Entry format + +Each memory entry is a standalone markdown file consisting of three +parts: YAML frontmatter, a contextual introduction, and a prose body. + +### YAML frontmatter + +Structured metadata that enables programmatic operations — staleness +detection, status filtering, cross-referencing, and retrieval +filtering. + +```yaml +--- +title: PostgreSQL for Auth Service +type: decision +date: 2026-04-10 +source: user-stated +status: active +tags: [auth, postgresql, data-storage] +supersedes: null +related: [context/0002-infrastructure.md] +--- +``` + +Required fields: + +- **title**: Short descriptive name, used in listings and summaries +- **type**: One of `decision`, `context`, `lesson`, `procedure`, + `milestone` +- **date**: The date the fact became true or was observed (ISO 8601) +- **source**: How the memory was captured — `user-stated`, + `llm-inferred`, or `post-mortem` +- **status**: `active`, `review-needed`, `deprecated`, or `archived` + +Optional fields: + +- **tags**: Free-form labels for retrieval filtering +- **supersedes**: Path to the entry this one replaces (if any) +- **related**: Paths to related entries + +### Contextual introduction + +A 1–3 sentence paragraph immediately following the frontmatter that +situates the entry within the project. This introduction is written +at capture time and becomes a permanent part of the file. It is not +generated at retrieval or embedding time. + +This follows Anthropic's contextual retrieval technique, which +demonstrated a 35% reduction in retrieval failures when contextual +information is prepended to chunks before embedding. The critical +design choice: the contextual introduction is written once and stored +in the file, rather than generated dynamically at embedding time. + +Rationale for baking it into the file: + +1. **Consistency.** The embedding and the file content are always in + sync. There is no discrepancy between what the retrieval layer + indexed and what the file contains. + +2. **Determinism.** It is possible to check whether an embedding has + already been computed for a file by comparing content hashes. + Dynamic contextual generation would produce slightly different + wordings each time, making hash-based change detection unreliable. + +3. **Transparency.** A human reading the file sees exactly what the + retrieval system sees. Nothing is hidden in an intermediate layer. + +The tradeoff is denormalization. If the project is renamed or a +major structural fact changes, all contextual introductions that +reference it become stale and must be updated. This is acceptable — +such changes are rare, and the memory review workflow can surface +and batch-update affected entries. + +### Prose body + +The main content, written in event-style following the writing +discipline described below. + +### Complete example + +```markdown +--- +title: PostgreSQL for Auth Service +type: decision +date: 2026-04-10 +source: user-stated +status: active +tags: [auth, postgresql, data-storage] +supersedes: null +related: [context/0002-infrastructure.md] +--- + +This entry is a decision record from the TrapperKeeper project, +a distributed data firewall. It documents the choice of primary +data store for the authentication service. + +On 2026-04-10, user decided to migrate the auth service from SQLite +to PostgreSQL 16.2. Rationale: SQLite could not handle concurrent +write loads from the new worker pool (>50 connections). Alternatives +rejected: SQLite WAL mode (single-writer limitation), CockroachDB +(operational complexity too high for a two-person team). Decision +surfaced during intake when user described timeout errors under load. +``` + +--- + +## Writing discipline + +All memories are written as **temporally grounded, absolute facts**. +This quality discipline is validated by SimpleMem (Liu et al., 2026), +whose ablation showed that removing temporal normalization and +coreference resolution reduced Temporal F1 by 56.7%. The EMem paper +(Zhou et al., 2025, "A Simple Yet Strong Baseline for Long-Term +Conversational Memory of LLM Agents") grounds this in neo-Davidsonian +event semantics: treating events as single units with multiple +arguments outperforms decomposing them into relation triples. + +### Rules + +1. **Every statement includes a date.** The date the fact became true + or was observed. If unknown, use the recording date. + +2. **Attribute claims to their source.** "User stated...", "LLM + inferred...", "Post-mortem identified...". + +3. **No forward-looking language.** Not "we will" but "On [date], user + stated the plan was to...". + +4. **Name things concretely.** Not "the database" but "PostgreSQL 16.2" + or "the auth service's primary data store." + +5. **Each entry must stand alone.** Interpretable without any other + file, true regardless of when it is read. + +Source attribution embedded in the prose serves as the primary trust +signal. User-stated facts carry higher trust than LLM-inferred facts. +No external metadata database is needed for trust assessment. + +### Examples + +Bad — relative, will become stale: + +> We use PostgreSQL for the auth service. + +Good — temporally grounded, always true as a historical fact: + +> On 2026-04-10, user decided to use PostgreSQL 16.2 for the auth +> service's data storage, replacing SQLite. + +--- + +## Memory types + +Koan organizes memories into five document types, each corresponding +to a distinct retrieval intent — a kind of question an agent needs +answered. + +### Decisions — *Why is the project the way it is?* + +The most critical memory type. Decisions capture **why** the project +is the way it is — not just what was chosen, but what was rejected +and why. + +Each decision entry should capture, where known: what was decided, +the rationale (constraints that drove the choice), alternatives +considered and rejected, and how the decision surfaced (intake, +mid-workflow correction, post-mortem). + +Decisions include both explicit choices (user-stated) and implicit +choices (LLM-inferred from user behavior). Implicit decisions are +marked as such via the `source` field. + +### Context — *What do I need to know that isn't in the code?* + +Objective facts about the project, team, domain, and infrastructure +that are not derivable from the codebase and are expected to remain +stable across sessions. Team size, deployment setup, external +dependencies, business constraints. + +Context entries are split into project-scoped (in `.koan/memory/ +context/`) and user-scoped (in `.koan/user/context/`). User context +includes background, experience level, coding preferences, and style. +It applies across all projects. + +### Lessons — *What went wrong before?* + +Mistakes made during workflows and the corrections applied. Each +entry captures: what happened, what the user did to correct it, +root cause, and what should change to prevent recurrence. + +A lesson often produces a new decision or procedure, but the lesson +itself is the error record — the ground truth about what went wrong. + +### Procedures — *How should I approach things in this project?* + +Patterns, strategies, and behavioral rules that emerged from +experience. Procedures capture actionable "how-to" knowledge that +tells agents what to do, not just what happened or what was decided. + +The distinction from lessons: a lesson says "executor generated unit +tests despite policy." A procedure says "always verify testing policy +before any code generation task." The lesson is the event record; the +procedure is the actionable rule. + +Procedures emerge from three sources: lessons that generalize into +prevention rules, positive patterns observed after successful +workflows, and the memory review workflow surfacing recurring themes. + +### Milestones — *What work has been done?* + +A running record of completed workflows. Milestones capture *that* +something was done, not the full detail of how. Their primary purpose +is enabling project summary generation and providing future intake +phases a quick history. + +### Project summary (derived) + +A synthesized overview regenerated after each workflow completes. +Unlike memory entries, the summary is produced by reading the other +memory files and synthesizing them into a concise briefing. It lives +at `.koan/memory/summary.md` and does not have the standard entry +format (no sequential number, no contextual introduction). + +The summary is the first thing an LLM reads when starting any +workflow. It is loaded in full at intake (not retrieved via search) +as long as it fits within a budget of ~2000 tokens. This follows the +coarsening–traversal (C–T) coupling principle from "Toward a Theory +of Hierarchical Memory for Language Agents" (ICLR 2026): +self-sufficient representatives can be loaded in full (collapsed +search), but only while they fit the token budget. + +--- + +## File organization + +``` +.koan/ + memory/ + summary.md # tier 1: root summary (whole project) + decisions/ + _index.md # tier 2: condensed summary of all decisions + 0001-postgresql-for-auth.md # tier 3: individual entries + 0002-no-unit-tests.md + 0003-redis-session-management.md + context/ + _index.md + 0001-team-structure.md + 0002-infrastructure.md + 0003-auth0-integration.md + lessons/ + _index.md + 0001-unit-test-generation.md + procedures/ + _index.md + 0001-testing-policy-check.md + 0002-database-migration-steps.md + milestones/ + _index.md + 0042-user-authentication.md + 0048-background-jobs.md + + user/ # user-global (shared across projects) + context/ + _index.md + 0001-background.md + 0002-coding-preferences.md + lessons/ + _index.md + 0001-credential-hardcoding.md + procedures/ + _index.md + 0001-migration-decomposition.md +``` + +### Three-tier summary hierarchy + +The memory system maintains summaries at three levels, following the +RAPTOR recursive abstractive retrieval pattern (Sarthi et al., ICLR +2024). Each level provides a self-sufficient representation that can +answer queries at its resolution without drilling deeper. + +**Tier 1: Root summary** (`summary.md`). A project-wide overview +covering architecture, policies, recent work, and known pitfalls. +Always loaded in full at intake. Budget: ~2000 tokens. + +**Tier 2: Type-level indexes** (`decisions/_index.md`, etc.). Each +type folder contains an `_index.md` that condenses all active entries +in that folder into a single prose summary. An agent needing a broad +view of "all decisions" or "all procedures" can load the relevant +`_index.md` without retrieving individual entries. Budget: ~500 +tokens each. + +**Tier 3: Individual entries** (`0001-postgresql-for-auth.md`). The +full knowledge entries, retrieved via hybrid search when the agent +needs specific detail that the summaries don't provide. + +The root `summary.md` is regenerated from the type-level `_index.md` +files rather than reading every individual entry directly. This is +RAPTOR's recursive summarization: summarize the leaves, then +summarize the summaries. + +Type-level `_index.md` files are generated artifacts, like +`summary.md`. They carry a simple frontmatter block: + +```yaml +--- +type: index +covers: [0001, 0002, 0003] +token_count: 420 +last_generated: 2026-04-15 +--- +``` + +Example `decisions/_index.md`: + +```markdown +--- +type: index +covers: [0001, 0002, 0003] +token_count: 380 +last_generated: 2026-04-15 +--- + +TrapperKeeper's active architectural decisions cover three areas. +Data storage uses PostgreSQL 16.2 for the auth service, chosen over +SQLite (concurrency limits) and CockroachDB (operational complexity) +as of 2026-04-10. Testing policy prohibits unit tests in favor of +integration tests only, established 2026-04-08. Session management +uses Redis 7.x with stateful sessions for compliance requirements, +decided 2026-04-12. +``` + +### Naming convention + +Files are named `NNNN-short-description.md` where `NNNN` is a +zero-padded sequential number within the type folder. The number +provides stable ordering and prevents filename collisions. The +description is a human-readable slug derived from the title. + +New entries are assigned the next available number in their type +folder. Numbers are never reused — if entry `0005` is deleted, the +next entry is still `0006`. + +### Version control + +The `.koan/memory/` directory is checked into version control +alongside the project's source code. This means memory changes +appear in diffs, can be reviewed in pull requests, and have full +git history. The `.koan/user/` directory is stored outside the +project repository (e.g., in `~/.koan/user/`) since it applies +across all projects. + +--- + +## Memory lifecycle + +Memory is created and maintained through a single mechanism — +**curation** — invoked with different sources and directives +depending on the context. All memory modifications require explicit +user review. + +### The curation workflow + +Curation is a unified workflow that reads source material, reflects +on it in the context of existing memory, proposes changes, and +presents them to the user for review. It follows the same pattern +regardless of what triggered it: + +1. **Read source material.** The source varies by invocation: a + workflow transcript, the existing memory corpus, codebase files, + user-provided documents, or a combination. + +2. **Read existing memory.** Load all `_index.md` files for + orientation, plus individual entries relevant to the source + material (via retrieval or full scan). + +3. **Reflect.** The curation agent evaluates the source against + existing memory. Depending on the directive, it may: + - Identify new knowledge to capture + - Find existing entries that need updating + - Detect stale, contradictory, or duplicate entries + - Surface gaps in coverage + - Evaluate lessons for procedure generation + - Assess whether the type-level organization still fits + +4. **Conduct Q&A with the user** (when the directive calls for it). + Ask clarifying questions to fill gaps, verify assumptions, or + resolve ambiguities. + +5. **Propose changes.** Each proposed change is a complete entry + (for creates) or a diff (for updates), organized by operation: + - **Create**: New entry with full frontmatter, contextual + introduction, and prose body + - **Update**: Modified content for an existing entry + - **Merge**: Two or more entries combined into one + - **Deprecate**: Status change to `deprecated` + - **Promote / demote**: Move between project-local and user-global + - **Archive**: Remove from active retrieval + +6. **User reviews each proposed change.** The user approves, edits, + or rejects each change individually. The agent does not modify + memory without explicit user approval. + +7. **Write approved changes to disk.** New entries get the next + available sequence number in their type folder. + +8. **Regenerate summaries.** Type-level `_index.md` files are + regenerated for each type folder that had changes. The root + `summary.md` is regenerated from the updated `_index.md` files. + +9. **Re-index.** The sync layer detects changed files and updates + the retrieval index. + +### Curation directives + +The same workflow serves all memory operations through different +directives: + +**Post-mortem curation** runs at the end of every koan workflow. +Source: the workflow transcript (user messages, agent outputs, +interventions, escalations). Directive: reflect on what went well, +what went wrong, what decisions were made (explicitly or implicitly), +what patterns emerged. Capture decisions, lessons, procedures, +context facts, and a milestone record. + +**Review curation** is triggered on-demand, on a schedule, or at +project initialization. Source: the existing memory corpus (and +optionally the codebase). Directive: assess memory health — identify +stale entries, contradictions, gaps, entries that should be merged, +lessons lacking procedures, deprecated entries to archive. Conduct +Q&A with the user to fill gaps and verify facts. + +**Bootstrap curation** runs when koan is first set up for a project. +Source: the codebase, any existing documentation, and user interview. +Directive: capture baseline project context, team structure, +conventions, constraints, and architectural decisions already in +effect. + +**Document curation** ingests specific source material the user +provides. Source: architecture docs, specs, design documents, or +any other material. Directive: extract relevant knowledge and +organize it into memory entries. + +### Triggering curation + +Curation is triggered: + +- **Automatically** at the end of every koan workflow (post-mortem + directive). +- **On explicit user request** (review, bootstrap, or document + directive). +- **On suggestion** after N completed workflows, koan suggests a + review curation. Configurable, e.g. every 5 workflows. +- **At project initialization** (bootstrap directive). + +### Model tier assignments + +Curation uses **strong-tier models** for reflection and proposal +generation. This is where judgment matters — what to capture, how +to phrase it, whether existing entries need updating. + +Mechanical retrieval at intake uses **no LLM** for the search +itself. Hybrid vector + BM25 search, cross-encoder reranking, and +metadata filtering are all mechanical operations. + +The `koan_reflect` tool uses a **cheap-tier model** for query +generation (decomposing a broad question into multiple search +angles) and synthesis (combining retrieved entries into a coherent +briefing). This does not require the strong model — it is +summarizing existing knowledge, not making new decisions. + +Query rewriting for low-confidence retrievals can also use a +**cheap-tier model** to reformulate queries before retrying. + +### Direct human editing + +Because memory files are plain markdown in version control, humans +can edit them directly at any time — in their editor, via a pull +request, or through any other workflow. The sync layer detects +changes and re-indexes modified files. + +When humans edit files directly, they should maintain the entry +format (frontmatter + contextual introduction + prose body) and +update the `date` field if the content changes substantively. + +--- + +## Retrieval + +Koan builds its own retrieval layer over the memory files rather +than delegating to a conversational memory system. This is because +koan's memory entries are already well-structured, self-contained +documents — running them through a fact extraction pipeline (as +systems like Hindsight do) would be destructive, stripping the +framing and rationale that make entries valuable. + +### Entry grain size + +Each memory entry is 100–500 tokens: large enough to be +self-contained, small enough that retrieving 3–5 entries fits within +a reasonable token budget. This grain size is a deliberate design +choice supported by three converging arguments. + +**Empirical evidence on chunk size.** Mem0's benchmark (Table 2) +shows that for atomic factual queries, small chunks (128–256 tokens) +outperform large chunks (1024–2048 tokens) by ~32% when retrieving +a single result. However, this data comes from conversational memory +where answers are individual facts ("Alice's job is X"). Koan's +knowledge is structurally different — a decision entry bundles a +choice with its rationale, rejected alternatives, and surfacing +context. These elements are not independent facts; they are one +coherent unit of knowledge. + +**The neo-Davidsonian argument (Zhou et al., EMem 2025).** When +knowledge is relational — when the value lies in connections between +elements — atomizing it into independent facts destroys the +structure that makes it useful. If a decision ("chose PostgreSQL +over SQLite due to concurrency, rejecting CockroachDB for +operational complexity") is split into three separate atomic facts, +a query about CockroachDB retrieves the CockroachDB fact but loses +the decision context. The retriever would need to find all three +facts and the LLM would need to reassemble them, requiring +multi-hop reasoning at query time — the operation that degrades +performance most across all benchmarks. + +**Koan's knowledge is inherently relational.** Koan stores +architectural decisions with rationale and alternatives, lessons +with root causes and prevention strategies, procedures with +conditionals and scope boundaries. These are not atomic preferences +("user prefers tabs over spaces") — they are structured arguments +where the rationale, the alternatives, and the context are all +essential to the entry's value. The grain must be large enough to +keep the relations intact within each entry, while small enough +that a few retrieved entries fit the token budget. + +The grain size is therefore not "as small as possible" but "as +small as possible while preserving the coherence of each knowledge +unit." For koan's content type, that is 100–500 tokens per entry. + +### Indexing + +The sync layer watches `.koan/memory/` and indexes each file as a +single chunk. Because entries are written to be self-contained and +are typically 100–500 tokens, most entries can be embedded whole +without further chunking. + +For each entry, the sync layer: + +1. Reads the file content (frontmatter + contextual introduction + + prose body) +2. Parses the YAML frontmatter into structured metadata +3. Computes a content hash for change detection +4. Generates a dense embedding of the full text (including the + contextual introduction) +5. Indexes the text for BM25 keyword search +6. Stores the embedding, BM25 index entry, and metadata + +The `_index.md` summary files and `summary.md` are also indexed +alongside individual entries. Because these summaries are +self-sufficient (following the RAPTOR/C–T coupling principle), they +participate in collapsed search — a broad query may match a +type-level summary directly, while a specific query matches an +individual entry. + +Re-indexing is triggered when a file's content hash changes. Because +the contextual introduction is baked into the file, the hash +reliably indicates whether re-embedding is needed. + +### Two retrieval paths + +Koan provides two distinct retrieval mechanisms: **mechanical context +injection** (automatic, at the start of every intake) and +**agent-invoked tools** (on-demand, during reasoning). + +#### Mechanical context injection + +At the start of every intake phase, before the agent begins +reasoning, koan automatically loads baseline context. The pipeline +has six steps: + +**Step 1: Load project summary.** `summary.md` is loaded in full. +Always present, not retrieved via search. Budget: ~2000 tokens. + +**Step 2: Generate search queries.** From the current task +description, generate 1–3 search queries that cover different +angles of the task. Example: task "implement OAuth2 authentication +via Auth0" produces queries like "authentication architecture +decisions," "Auth0 integration context," "auth service procedures." +These can be generated mechanically (extract key entities, expand +with type-relevant terms) or by a cheap-tier model. + +**Step 3: Per-query hybrid retrieval.** For each query, two +parallel searches run against the index: +- Dense vector search → top N candidates by embedding similarity +- BM25 keyword search → top N candidates by lexical matching +N = 20 per retriever per query (tunable; 20 is sufficient for +knowledge bases of hundreds to low thousands of entries). + +**Step 4: Per-query fusion.** For each query, merge the two result +lists using Reciprocal Rank Fusion: `score = Σ 1/(60 + rank)` +across retrievers. Output: one ranked list per query. + +**Step 5: Cross-query merge and reranking.** Combine the fused +lists from all queries, deduplicate entries. Pass the candidate +pool (typically 30–50 unique entries after dedup) through a +cross-encoder reranker, which scores each (query, entry) pair +with full attention over both texts. + +**Step 6: Take top 3–5 entries.** The highest-scoring entries +after reranking are injected into the agent's context alongside +the summary, with their metadata (type, date, source, status). + +Total mechanical context: summary (~2000 tokens) + 3–5 entries +(~500–2500 tokens) = ~2500–4500 tokens of memory context. The +3–5 budget follows SimpleMem's saturation finding: near-optimal +retrieval performance at k=3, diminishing returns beyond k=5. + +Note: the `_index.md` summary files participate in retrieval +alongside individual entries (collapsed search). A broad query +may match a type-level summary directly; a specific query matches +an individual entry. The reranker decides which level is most +relevant for each query. + +#### Agent-invoked tools + +During reasoning, the intake agent has access to two memory tools. + +**`koan_search(query, filters?)`** is a targeted lookup. The agent +formulates a specific query and gets back raw entries ranked by +relevance. Runs the same hybrid search + reranking pipeline as +mechanical retrieval (steps 3–6 above) but for a single +agent-provided query. Returns the top 3–5 entries as raw markdown +content with metadata. The agent can invoke this as many times as +needed during its reasoning. + +Use case: "what is the testing policy?" → returns the relevant +procedure entry directly. No LLM involved in the retrieval +pipeline. + +**`koan_reflect(question, context?)`** is a synthesized briefing. +The agent poses a broad question and gets back a coherent answer +that draws on multiple entries. This is modeled as a mini-agent +(cheap-tier model) running an evidence-gathering loop, inspired +by Hindsight's CARA reflect architecture. + +The reflect tool runs the following agentic loop: + +**Step 1: Orient.** The reflect agent loads the project summary +and relevant `_index.md` files to understand what knowledge areas +exist. This is a direct file read, not a search. + +**Step 2: Plan queries.** Based on the question and the +orientation context, the agent generates 3–5 search queries from +different angles. Example: question "what constraints and patterns +should guide SDK design?" produces queries like "SDK architecture +decisions," "sensor lifecycle procedures," "testing philosophy +conventions," "fail-safe default requirements," "past SDK-related +lessons." + +**Step 3: Gather evidence.** For each query, run the standard +retrieval pipeline (hybrid search + reranking, steps 3–6 from +mechanical retrieval). Collect the top results across all queries. + +**Step 4: Evaluate sufficiency.** The agent reviews the gathered +entries and assesses whether they adequately answer the question. +If critical gaps remain (the question asks about SDK testing but +no testing-related entries were retrieved), generate 1–2 +additional targeted queries and retrieve more. This loop runs +up to 3 iterations to prevent runaway searches. + +**Step 5: Synthesize.** The agent reads all gathered entries +(typically 8–15 after deduplication) and produces a coherent +300–500 token briefing that answers the original question. The +synthesis connects knowledge across different entry types — +linking a decision about fail-safe defaults to a procedure about +testing to a lesson about SDK initialization failures. Each claim +in the briefing cites the specific entry it draws from (by file +path). + +**Step 6: Return.** The briefing is returned to the calling agent +as the tool's output. + +The key differences from Hindsight's reflect that koan does NOT +adopt: +- **No disposition traits.** Hindsight uses skepticism, literalism, + and empathy parameters to shape how the agent interprets facts. + Koan's reflect produces factual briefings, not opinionated + interpretations. The project's knowledge speaks for itself. +- **No opinion formation.** Hindsight's reflect creates and updates + opinions with confidence scores. Koan's memory system stores + facts, decisions, and procedures — not beliefs. The reflect tool + synthesizes existing knowledge; it does not form new conclusions. +- **No mental models.** Hindsight's reflect checks pre-computed + summary responses first. Koan's `_index.md` files serve a similar + function (compressed type-level overviews) but are loaded during + orientation rather than as a separate retrieval tier. + +What koan DOES adopt from Hindsight's reflect: +- **The agentic loop.** The reflect tool is not a single LLM call + but an iterative evidence-gathering process that can make + multiple searches and evaluate sufficiency. +- **Hierarchical retrieval.** Check summaries for orientation first, + then search individual entries for detail. +- **Evidence-before-synthesis guardrail.** The agent must gather + entries before producing a briefing — it cannot answer from its + parametric knowledge alone. +- **Citation validation.** The briefing can only cite entries that + were actually retrieved during the evidence-gathering loop. + +### Retrieval backend + +The retrieval layer uses an embedded vector database (such as +LanceDB) that provides native hybrid search (dense vectors + BM25) +with metadata filtering. No external server process is required — +the index lives on disk alongside the project. + +The index is a derived artifact, not a source of truth. It can be +rebuilt from scratch at any time by re-reading all memory files in +`.koan/memory/`. It should be excluded from version control (e.g., +added to `.gitignore`). + +--- + +## Appendix: project summary example + +```markdown +# TrapperKeeper — Project Summary + +Last updated: 2026-04-15 + +TrapperKeeper is a distributed data firewall built by a solo +developer with 20 years of data engineering experience. Runs on a +single Hetzner VM (4 cores, 8GB RAM), deploys via docker-compose. + +## Current architecture + +- Data storage: PostgreSQL 16.2 (migrated from SQLite, 2026-04-10) +- Session management: Redis 7.x (stateful sessions for compliance) +- Authentication: Auth0 (OAuth2, Management API v2) +- Background jobs: Bull on Redis +- Deployment: docker-compose, manual SSH, secrets via .env files + +## Key policies + +- No unit tests. Integration tests only. +- No comments except for non-obvious business logic. +- Python: ruff, default config. +- Secrets must never appear in docker-compose.yml; use .env. + +## Key procedures + +- Always verify testing policy before code generation tasks. +- Decompose database migrations into schema + application milestones. +- Check variables.css before adding new CSS styles. + +## Recent work + +- #48 (2026-04-15): Background job processor via Bull/Redis +- #42 (2026-04-10): User authentication via Auth0 + +## Known pitfalls + +- Executor tends to generate unit tests; always verify testing policy. +- Executor tends to hardcode credentials; always check existing secret + management patterns before modifying infrastructure. +``` From f2d7c995243c2e45bab0b95f8ec9edef0fa8d933 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Tue, 14 Apr 2026 15:28:54 +0700 Subject: [PATCH 379/412] feat: redesign memory storage and summary generation --- koan/memory/__init__.py | 24 ++-- koan/memory/llm.py | 48 ++++++++ koan/memory/parser.py | 100 ++++------------ koan/memory/store.py | 110 +++++++----------- koan/memory/summarize.py | 85 ++++++++++++++ koan/memory/types.py | 40 +------ koan/memory/validation.py | 39 +------ koan/memory/writer.py | 61 +++++----- pyproject.toml | 1 + tests/memory/test_parser.py | 86 ++++---------- tests/memory/test_store.py | 124 ++++++++++---------- tests/memory/test_summarize.py | 199 ++++++++++++++++++++++++++++++++ tests/memory/test_validation.py | 42 +------ tests/memory/test_writer.py | 84 ++++++-------- uv.lock | 188 ++++++++++++++++++++++++++++++ 15 files changed, 760 insertions(+), 471 deletions(-) create mode 100644 koan/memory/llm.py create mode 100644 koan/memory/summarize.py create mode 100644 tests/memory/test_summarize.py diff --git a/koan/memory/__init__.py b/koan/memory/__init__.py index 9667612..b8f576b 100644 --- a/koan/memory/__init__.py +++ b/koan/memory/__init__.py @@ -4,28 +4,28 @@ from __future__ import annotations from .types import ( + MEMORY_TYPES, MemoryEntry, - MemoryIndex, - MemorySource, - MemoryStatus, MemoryType, ) -from .parser import parse_entry, parse_index -from .writer import write_entry, update_entry, write_index -from .store import MemoryStore +from .parser import ParseError, parse_entry +from .writer import write_entry, update_entry from .validation import validate_entry +from .store import MemoryStore +from .llm import generate as llm_generate +from .summarize import generate_summary, regenerate_summary __all__ = [ "MemoryType", - "MemorySource", - "MemoryStatus", "MemoryEntry", - "MemoryIndex", + "MEMORY_TYPES", + "ParseError", "parse_entry", - "parse_index", "write_entry", "update_entry", - "write_index", - "MemoryStore", "validate_entry", + "MemoryStore", + "llm_generate", + "generate_summary", + "regenerate_summary", ] diff --git a/koan/memory/llm.py b/koan/memory/llm.py new file mode 100644 index 0000000..33b204e --- /dev/null +++ b/koan/memory/llm.py @@ -0,0 +1,48 @@ +# Lightweight async LLM client for mechanical text generation. +# Used for summaries, query decomposition, synthesis -- not coding agents. + +from __future__ import annotations + +import os + +from google import genai +from google.genai import types + +DEFAULT_MODEL = "gemini-3-flash-lite" + + +def _api_key() -> str: + key = os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY") or "" + if not key: + raise RuntimeError( + "GEMINI_API_KEY or GOOGLE_API_KEY environment variable is required" + ) + return key + + +def _model() -> str: + return os.environ.get("KOAN_LLM_MODEL") or DEFAULT_MODEL + + +async def generate(prompt: str, system: str = "", max_tokens: int = 1024) -> str: + """Call Gemini and return the text response. + + Configuration: + - Model: via env var KOAN_LLM_MODEL (default "gemini-3-flash-lite") + - API key: via env var GEMINI_API_KEY or GOOGLE_API_KEY + - Temperature: 0.0 (deterministic for summaries) + + Raises RuntimeError if the API key is not set or the call fails. + """ + client = genai.Client(api_key=_api_key()) + config = types.GenerateContentConfig( + system_instruction=system or None, + temperature=0.0, + max_output_tokens=max_tokens, + ) + response = await client.aio.models.generate_content( + model=_model(), + contents=prompt, + config=config, + ) + return response.text or "" diff --git a/koan/memory/parser.py b/koan/memory/parser.py index 91740b1..7b4592d 100644 --- a/koan/memory/parser.py +++ b/koan/memory/parser.py @@ -3,11 +3,28 @@ from __future__ import annotations import re +from datetime import date, datetime from pathlib import Path import yaml -from .types import MemoryEntry, MemoryIndex +from .types import MemoryEntry + + +def _stringify_ts(value: object) -> str: + """Normalize a parsed YAML value to an ISO 8601 string. + + pyyaml auto-parses ISO timestamps into datetime/date objects. We need + them back as strings in their original shape. + """ + if value is None: + return "" + if isinstance(value, datetime): + s = value.isoformat() + return s.replace("+00:00", "Z") + if isinstance(value, date): + return value.isoformat() + return str(value) class ParseError(Exception): @@ -15,7 +32,7 @@ class ParseError(Exception): def _split_frontmatter(text: str) -> tuple[dict, str]: - """Split a markdown file into YAML frontmatter dict and remaining text. + """Split a markdown file into YAML frontmatter dict and remaining body. Raises ParseError if the file does not start with a ``---`` fence. """ @@ -23,7 +40,6 @@ def _split_frontmatter(text: str) -> tuple[dict, str]: if not stripped.startswith("---"): raise ParseError("missing YAML frontmatter (no opening ---)") - # Find closing --- rest = stripped[3:] m = re.search(r"^---\s*$", rest, re.MULTILINE) if m is None: @@ -37,36 +53,7 @@ def _split_frontmatter(text: str) -> tuple[dict, str]: return meta, after.lstrip("\n") -def _split_intro_body(text: str) -> tuple[str, str]: - """Separate contextual introduction (first paragraph) from body. - - The introduction ends at the first ``## `` heading or the first - blank-line-delimited paragraph break. - """ - # If text starts with a heading, there is no introduction. - if re.match(r"^##\s", text): - return "", text - - # Split at first heading. - heading_match = re.search(r"^##\s", text, re.MULTILINE) - if heading_match: - before = text[: heading_match.start()].rstrip() - after = text[heading_match.start():] - # Introduction is the first paragraph of `before`. - parts = re.split(r"\n\n+", before, maxsplit=1) - intro = parts[0].strip() - remaining = parts[1].strip() if len(parts) > 1 else "" - body = (remaining + "\n\n" + after).strip() if remaining else after.strip() - return intro, body - - # No heading -- split on double newline. - parts = re.split(r"\n\n+", text, maxsplit=1) - intro = parts[0].strip() - body = parts[1].strip() if len(parts) > 1 else "" - return intro, body - - -_REQUIRED_FIELDS = ("title", "type", "date", "source", "status") +_REQUIRED_FIELDS = ("title", "type") def parse_entry(path: Path) -> MemoryEntry: @@ -75,28 +62,12 @@ def parse_entry(path: Path) -> MemoryEntry: Raises ``ParseError`` on malformed files or missing required fields. """ text = path.read_text("utf-8") - meta, after = _split_frontmatter(text) + meta, body = _split_frontmatter(text) missing = [f for f in _REQUIRED_FIELDS if f not in meta] if missing: raise ParseError(f"missing required frontmatter fields: {', '.join(missing)}") - intro, body = _split_intro_body(after) - if not intro: - raise ParseError("missing contextual introduction") - if not body: - raise ParseError("missing body") - - tags = meta.get("tags") or [] - if not isinstance(tags, list): - tags = [str(tags)] - - supersedes = meta.get("supersedes") - if supersedes is not None: - supersedes = str(supersedes) - if supersedes.lower() == "null": - supersedes = None - related = meta.get("related") or [] if not isinstance(related, list): related = [str(related)] @@ -104,32 +75,9 @@ def parse_entry(path: Path) -> MemoryEntry: return MemoryEntry( title=str(meta["title"]), type=meta["type"], - date=str(meta["date"]), - source=meta["source"], - status=meta["status"], - contextual_introduction=intro, - body=body, - tags=[str(t) for t in tags], - supersedes=supersedes, + body=body.strip(), + created=_stringify_ts(meta.get("created")), + modified=_stringify_ts(meta.get("modified")), related=[str(r) for r in related], file_path=path, ) - - -def parse_index(path: Path) -> MemoryIndex: - """Parse a ``_index.md`` file into a ``MemoryIndex``.""" - text = path.read_text("utf-8") - meta, after = _split_frontmatter(text) - - covers = meta.get("covers", []) - if not isinstance(covers, list): - covers = [] - covers = [int(c) for c in covers] - - return MemoryIndex( - covers=covers, - token_count=int(meta.get("token_count", 0)), - last_generated=str(meta.get("last_generated", "")), - body=after.strip(), - file_path=path, - ) diff --git a/koan/memory/store.py b/koan/memory/store.py index fe818ea..7b39f00 100644 --- a/koan/memory/store.py +++ b/koan/memory/store.py @@ -1,79 +1,64 @@ -# High-level operations over the .koan/memory/ directory tree. +# High-level operations over the flat .koan/memory/ directory. from __future__ import annotations import re from pathlib import Path -from .types import ( - TYPE_DIRS, - MemoryEntry, - MemoryIndex, - MemorySource, - MemoryStatus, - MemoryType, -) -from .parser import parse_entry, parse_index +from .types import MemoryEntry, MemoryType +from .parser import parse_entry from .writer import write_entry as _write_entry, update_entry as _update_entry +_ENTRY_PATTERN = re.compile(r"^(\d{4})-.*\.md$") + class MemoryStore: - """File-backed store for koan memory entries.""" + """File-backed store for koan memory entries in a flat directory.""" def __init__(self, project_root: str | Path) -> None: self._root = Path(project_root) self._memory_dir = self._root / ".koan" / "memory" - self._user_dir = self._root / ".koan" / "user" # -- Directory management --------------------------------------------------- def init(self) -> None: - """Create the directory structure if it doesn't exist.""" - for dir_name in TYPE_DIRS.values(): - (self._memory_dir / dir_name).mkdir(parents=True, exist_ok=True) - self._user_dir.mkdir(parents=True, exist_ok=True) - - def _type_dir(self, t: MemoryType) -> Path: - return self._memory_dir / TYPE_DIRS[t] + """Create the memory directory if it doesn't exist.""" + self._memory_dir.mkdir(parents=True, exist_ok=True) # -- Query ------------------------------------------------------------------ + def _iter_entry_paths(self) -> list[Path]: + """Return all NNNN-*.md paths in the memory directory, sorted by name.""" + if not self._memory_dir.is_dir(): + return [] + return sorted( + p for p in self._memory_dir.iterdir() + if p.is_file() and _ENTRY_PATTERN.match(p.name) + ) + def list_entries(self, type: MemoryType | None = None) -> list[MemoryEntry]: """List entries, optionally filtered by type. Sorted by sequence number.""" - types = [type] if type is not None else list(TYPE_DIRS.keys()) - entries: list[MemoryEntry] = [] - pattern = re.compile(r"^(\d{4})-.*\.md$") - for t in types: - d = self._type_dir(t) - if not d.is_dir(): - continue - for p in sorted(d.iterdir()): - if pattern.match(p.name): - entries.append(parse_entry(p)) + entries = [parse_entry(p) for p in self._iter_entry_paths()] + if type is not None: + entries = [e for e in entries if e.type == type] return entries - def get_entry(self, type: MemoryType, number: int) -> MemoryEntry | None: - """Find and parse a specific entry by type and sequence number.""" - d = self._type_dir(type) - if not d.is_dir(): + def get_entry(self, number: int) -> MemoryEntry | None: + """Find and parse a specific entry by global sequence number.""" + if not self._memory_dir.is_dir(): return None prefix = f"{number:04d}-" - for p in d.iterdir(): - if p.name.startswith(prefix) and p.name.endswith(".md"): + for p in self._memory_dir.iterdir(): + if p.is_file() and p.name.startswith(prefix) and p.name.endswith(".md"): return parse_entry(p) return None def entry_count(self, type: MemoryType | None = None) -> int: """Count entries, optionally filtered by type.""" - types = [type] if type is not None else list(TYPE_DIRS.keys()) - pattern = re.compile(r"^\d{4}-.*\.md$") - count = 0 - for t in types: - d = self._type_dir(t) - if not d.is_dir(): - continue - count += sum(1 for p in d.iterdir() if pattern.match(p.name)) - return count + paths = self._iter_entry_paths() + if type is None: + return len(paths) + return sum(1 for p in paths if parse_entry(p).type == type) # -- Mutations -------------------------------------------------------------- @@ -81,30 +66,17 @@ def add_entry( self, type: MemoryType, title: str, - date: str, - source: MemorySource, - contextual_introduction: str, body: str, - status: MemoryStatus = "active", - tags: list[str] | None = None, - supersedes: str | None = None, related: list[str] | None = None, ) -> MemoryEntry: """Create a new entry, write it to disk, return with file_path set.""" entry = MemoryEntry( title=title, type=type, - date=date, - source=source, - status=status, - contextual_introduction=contextual_introduction, body=body, - tags=tags or [], - supersedes=supersedes, related=related or [], ) - d = self._type_dir(type) - path = _write_entry(entry, d) + path = _write_entry(entry, self._memory_dir) entry.file_path = path return entry @@ -112,12 +84,13 @@ def update_entry(self, entry: MemoryEntry) -> None: """Write an entry back to its existing file_path.""" _update_entry(entry) - def deprecate_entry(self, entry: MemoryEntry) -> None: - """Set status to 'deprecated' and write back.""" - entry.status = "deprecated" - _update_entry(entry) + def forget_entry(self, entry: MemoryEntry) -> None: + """Delete an entry file from disk. Git preserves history.""" + if entry.file_path is None: + raise ValueError("entry has no file_path") + entry.file_path.unlink() - # -- Summaries / indexes ---------------------------------------------------- + # -- Summary ---------------------------------------------------------------- def get_summary(self) -> str | None: """Return the content of summary.md if it exists.""" @@ -126,9 +99,8 @@ def get_summary(self) -> str | None: return p.read_text("utf-8") return None - def get_index(self, type: MemoryType) -> MemoryIndex | None: - """Return the parsed _index.md for the given type, if it exists.""" - p = self._type_dir(type) / "_index.md" - if p.is_file(): - return parse_index(p) - return None + async def regenerate_summary(self, project_name: str = "") -> None: + """Regenerate summary.md from all current entries.""" + from .summarize import regenerate_summary + + await regenerate_summary(self, project_name=project_name) diff --git a/koan/memory/summarize.py b/koan/memory/summarize.py new file mode 100644 index 0000000..1d0149d --- /dev/null +++ b/koan/memory/summarize.py @@ -0,0 +1,85 @@ +# Project summary generation for the flat memory directory. + +from __future__ import annotations + +import logging +import re + +from .llm import generate +from .store import MemoryStore +from .types import MemoryEntry + +log = logging.getLogger("koan.memory.summarize") + + +_SUMMARY_SYSTEM = """\ +You are a technical writer producing a project summary for AI coding +agents. This summary is the first thing an agent reads when starting +any task on this project. It must answer: what is this project, how +is it built, what constraints are in effect, and what mistakes to +avoid. + +Rules: +- Write a briefing document with clear markdown sections +- Preserve concrete details: version numbers, tool names, exact + constraints +- Include a "Known pitfalls" section if lessons exist +- Stay under 2000 tokens +- Do not include information not supported by the provided knowledge""" + + +def _render_entries_for_prompt(entries: list[MemoryEntry]) -> str: + """Concatenate entry titles + bodies for LLM prompt context.""" + parts: list[str] = [] + for e in entries: + parts.append(f"### {e.title} ({e.type}, {e.created})\n\n{e.body}") + return "\n\n---\n\n".join(parts) + + +def _seq_number(entry: MemoryEntry) -> int: + """Extract the NNNN prefix from an entry's filename.""" + if entry.file_path is None: + return 0 + m = re.match(r"^(\d{4})-", entry.file_path.name) + return int(m.group(1)) if m else 0 + + +async def generate_summary( + store: MemoryStore, + project_name: str = "", +) -> str: + """Generate summary.md by reading all entries directly.""" + entries = store.list_entries() + + if not entries: + summary = "No memory entries exist yet." + store._memory_dir.mkdir(parents=True, exist_ok=True) + (store._memory_dir / "summary.md").write_text(summary + "\n", "utf-8") + return summary + + context = _render_entries_for_prompt(entries) + heading = project_name if project_name else "this project" + prompt = ( + f"Below are all active memory entries for {heading}.\n" + f"Write a project summary briefing document.\n\n" + f"{context}" + ) + + try: + summary = await generate(prompt, system=_SUMMARY_SYSTEM, max_tokens=2500) + except Exception: + log.exception("LLM call failed for project summary generation") + summary = "Summary generation failed." + + summary = summary.strip() + store._memory_dir.mkdir(parents=True, exist_ok=True) + (store._memory_dir / "summary.md").write_text(summary + "\n", "utf-8") + return summary + + +async def regenerate_summary( + store: MemoryStore, + project_name: str = "", +) -> None: + """Regenerate the project summary after entries change.""" + await generate_summary(store, project_name=project_name) diff --git a/koan/memory/types.py b/koan/memory/types.py index 656c0b3..5cc7700 100644 --- a/koan/memory/types.py +++ b/koan/memory/types.py @@ -1,4 +1,4 @@ -# Data model for memory entries and indexes. +# Data model for memory entries. from __future__ import annotations @@ -6,49 +6,19 @@ from pathlib import Path from typing import Literal -MemoryType = Literal["decision", "context", "lesson", "procedure", "milestone"] -MemorySource = Literal["user-stated", "llm-inferred", "post-mortem"] -MemoryStatus = Literal["active", "review-needed", "deprecated", "archived"] +MemoryType = Literal["decision", "context", "lesson", "procedure"] MEMORY_TYPES: tuple[MemoryType, ...] = ( - "decision", "context", "lesson", "procedure", "milestone", -) -MEMORY_SOURCES: tuple[MemorySource, ...] = ( - "user-stated", "llm-inferred", "post-mortem", -) -MEMORY_STATUSES: tuple[MemoryStatus, ...] = ( - "active", "review-needed", "deprecated", "archived", + "decision", "context", "lesson", "procedure", ) -# Directory name for each memory type. -TYPE_DIRS: dict[MemoryType, str] = { - "decision": "decisions", - "context": "context", - "lesson": "lessons", - "procedure": "procedures", - "milestone": "milestones", -} - @dataclass class MemoryEntry: title: str type: MemoryType - date: str - source: MemorySource - status: MemoryStatus - contextual_introduction: str body: str - tags: list[str] = field(default_factory=list) - supersedes: str | None = None + created: str = "" # ISO 8601 timestamp; set automatically on write + modified: str = "" # ISO 8601 timestamp; set automatically on write related: list[str] = field(default_factory=list) file_path: Path | None = None - - -@dataclass -class MemoryIndex: - covers: list[int] = field(default_factory=list) - token_count: int = 0 - last_generated: str = "" - body: str = "" - file_path: Path | None = None diff --git a/koan/memory/validation.py b/koan/memory/validation.py index 197eef9..b575b0e 100644 --- a/koan/memory/validation.py +++ b/koan/memory/validation.py @@ -2,11 +2,7 @@ from __future__ import annotations -import re - -from .types import MEMORY_SOURCES, MEMORY_STATUSES, MEMORY_TYPES, MemoryEntry - -_ISO_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$") +from .types import MEMORY_TYPES, MemoryEntry def validate_entry(entry: MemoryEntry) -> list[str]: @@ -21,40 +17,7 @@ def validate_entry(entry: MemoryEntry) -> list[str]: elif entry.type not in MEMORY_TYPES: errors.append(f"invalid type: {entry.type}") - if not entry.date: - errors.append("date is required") - elif not _ISO_DATE.match(entry.date): - errors.append(f"date is not a valid ISO 8601 date: {entry.date}") - - if not entry.source: - errors.append("source is required") - elif entry.source not in MEMORY_SOURCES: - errors.append(f"invalid source: {entry.source}") - - if not entry.status: - errors.append("status is required") - elif entry.status not in MEMORY_STATUSES: - errors.append(f"invalid status: {entry.status}") - - if not entry.contextual_introduction: - errors.append("contextual_introduction is required") - if not entry.body: errors.append("body is required") - if entry.tags is not None: - if not isinstance(entry.tags, list): - errors.append("tags must be a list of strings") - elif not all(isinstance(t, str) for t in entry.tags): - errors.append("tags must be a list of strings") - - if entry.supersedes is not None and not isinstance(entry.supersedes, str): - errors.append("supersedes must be a string path") - - if entry.related is not None: - if not isinstance(entry.related, list): - errors.append("related must be a list of string paths") - elif not all(isinstance(r, str) for r in entry.related): - errors.append("related must be a list of string paths") - return errors diff --git a/koan/memory/writer.py b/koan/memory/writer.py index 6515950..8d65d6d 100644 --- a/koan/memory/writer.py +++ b/koan/memory/writer.py @@ -1,13 +1,18 @@ -# Write memory entries and indexes to disk. +# Write memory entries to disk. from __future__ import annotations import re +from datetime import datetime, timezone from pathlib import Path import yaml -from .types import MemoryEntry, MemoryIndex +from .types import MemoryEntry + + +def _now_iso() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z") def _slugify(title: str, max_len: int = 50) -> str: @@ -36,35 +41,39 @@ def _render_frontmatter(entry: MemoryEntry) -> str: meta: dict = { "title": entry.title, "type": entry.type, - "date": entry.date, - "source": entry.source, - "status": entry.status, + "created": entry.created, + "modified": entry.modified, } - if entry.tags: - meta["tags"] = entry.tags - if entry.supersedes is not None: - meta["supersedes"] = entry.supersedes - else: - meta["supersedes"] = None if entry.related: meta["related"] = entry.related - return yaml.dump(meta, default_flow_style=None, sort_keys=False, allow_unicode=False).rstrip("\n") + return yaml.dump( + meta, + default_flow_style=None, + sort_keys=False, + allow_unicode=False, + ).rstrip("\n") def _render_entry(entry: MemoryEntry) -> str: - """Render a complete entry file: frontmatter + intro + body.""" + """Render a complete entry file: frontmatter + body.""" fm = _render_frontmatter(entry) - return f"---\n{fm}\n---\n\n{entry.contextual_introduction}\n\n{entry.body}\n" + return f"---\n{fm}\n---\n\n{entry.body}\n" def write_entry(entry: MemoryEntry, directory: Path) -> Path: """Write a new memory entry to ``directory``. Assigns the next available sequence number, generates a filename - slug from the title, writes the file, and returns its path. + slug, sets ``created``/``modified`` to the current UTC timestamp + if not already set, and returns the written path. """ directory.mkdir(parents=True, exist_ok=True) + now = _now_iso() + if not entry.created: + entry.created = now + entry.modified = now + seq = _next_sequence_number(directory) slug = _slugify(entry.title) filename = f"{seq:04d}-{slug}.md" @@ -74,23 +83,11 @@ def write_entry(entry: MemoryEntry, directory: Path) -> Path: def update_entry(entry: MemoryEntry) -> None: - """Write an entry back to its existing ``file_path``.""" + """Write an entry back to its existing ``file_path``. + + Preserves ``created``; always refreshes ``modified``. + """ if entry.file_path is None: raise ValueError("entry has no file_path; use write_entry for new entries") + entry.modified = _now_iso() entry.file_path.write_text(_render_entry(entry), "utf-8") - - -def write_index(index: MemoryIndex, directory: Path) -> Path: - """Write ``_index.md`` in ``directory``.""" - directory.mkdir(parents=True, exist_ok=True) - meta = { - "type": "index", - "covers": index.covers, - "token_count": index.token_count, - "last_generated": index.last_generated, - } - fm = yaml.dump(meta, default_flow_style=None, sort_keys=False, allow_unicode=False).rstrip("\n") - text = f"---\n{fm}\n---\n\n{index.body}\n" - path = directory / "_index.md" - path.write_text(text, "utf-8") - return path diff --git a/pyproject.toml b/pyproject.toml index 10f291c..236e0b8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -9,6 +9,7 @@ dependencies = [ "aiofiles", "jsonpatch", "pyyaml", + "google-genai>=1.0", ] [project.scripts] diff --git a/tests/memory/test_parser.py b/tests/memory/test_parser.py index f2bc6fc..5839ea2 100644 --- a/tests/memory/test_parser.py +++ b/tests/memory/test_parser.py @@ -2,22 +2,20 @@ from __future__ import annotations -import pytest from pathlib import Path -from koan.memory.parser import parse_entry, parse_index, ParseError +import pytest + +from koan.memory.parser import ParseError, parse_entry WELL_FORMED = """\ --- title: PostgreSQL for Auth Service type: decision -date: 2026-04-10 -source: user-stated -status: active -tags: [auth, postgresql] -supersedes: null -related: [context/0002-infrastructure.md] +created: 2026-04-10T14:23:00Z +modified: 2026-04-10T14:23:00Z +related: [0002-infrastructure.md] --- This entry documents the choice of primary data store. @@ -26,21 +24,13 @@ to PostgreSQL 16.2. Rationale: concurrency. """ -WELL_FORMED_HEADING_BODY = """\ +WELL_FORMED_MINIMAL = """\ --- title: Migration Steps type: procedure -date: 2026-04-11 -source: post-mortem -status: active --- -This entry covers migration procedures for the data layer. - -## Steps - -1. Create schema migration file. -2. Run migration. +A short-body entry is still valid under the new format. """ @@ -56,21 +46,21 @@ def test_well_formed(self, tmp_path): e = parse_entry(p) assert e.title == "PostgreSQL for Auth Service" assert e.type == "decision" - assert e.date == "2026-04-10" - assert e.source == "user-stated" - assert e.status == "active" - assert e.tags == ["auth", "postgresql"] - assert e.supersedes is None - assert e.related == ["context/0002-infrastructure.md"] - assert "choice of primary data store" in e.contextual_introduction + assert e.created == "2026-04-10T14:23:00Z" + assert e.modified == "2026-04-10T14:23:00Z" + assert e.related == ["0002-infrastructure.md"] + assert "choice of primary data store" in e.body assert "PostgreSQL 16.2" in e.body assert e.file_path == p - def test_heading_separates_body(self, tmp_path): - p = _write(tmp_path, WELL_FORMED_HEADING_BODY) + def test_minimal_entry(self, tmp_path): + p = _write(tmp_path, WELL_FORMED_MINIMAL) e = parse_entry(p) - assert "migration procedures" in e.contextual_introduction - assert e.body.startswith("## Steps") + assert e.title == "Migration Steps" + assert e.type == "procedure" + assert e.created == "" + assert e.modified == "" + assert "still valid" in e.body def test_missing_frontmatter(self, tmp_path): p = _write(tmp_path, "Just some text without frontmatter.") @@ -78,40 +68,14 @@ def test_missing_frontmatter(self, tmp_path): parse_entry(p) def test_missing_required_fields(self, tmp_path): - content = "---\ntitle: Foo\n---\n\nIntro paragraph.\n\nBody text here.\n" + content = "---\ntitle: Foo\n---\n\nBody text.\n" p = _write(tmp_path, content) with pytest.raises(ParseError, match="missing required frontmatter fields"): parse_entry(p) - def test_empty_body(self, tmp_path): - content = "---\ntitle: Foo\ntype: decision\ndate: 2026-01-01\nsource: user-stated\nstatus: active\n---\n\nOnly an intro.\n" + def test_only_title_and_type_required(self, tmp_path): + content = "---\ntitle: Foo\ntype: decision\n---\n\nBody.\n" p = _write(tmp_path, content) - with pytest.raises(ParseError, match="missing body"): - parse_entry(p) - - def test_missing_intro(self, tmp_path): - content = "---\ntitle: Foo\ntype: decision\ndate: 2026-01-01\nsource: user-stated\nstatus: active\n---\n\n## Heading\n\nBody only.\n" - p = _write(tmp_path, content) - with pytest.raises(ParseError, match="missing contextual introduction"): - parse_entry(p) - - -class TestParseIndex: - def test_well_formed(self, tmp_path): - content = """\ ---- -type: index -covers: [1, 2, 3] -token_count: 380 -last_generated: 2026-04-15 ---- - -Active decisions cover three areas. -""" - p = _write(tmp_path, content, "_index.md") - idx = parse_index(p) - assert idx.covers == [1, 2, 3] - assert idx.token_count == 380 - assert idx.last_generated == "2026-04-15" - assert "three areas" in idx.body - assert idx.file_path == p + e = parse_entry(p) + assert e.title == "Foo" + assert e.body == "Body." diff --git a/tests/memory/test_store.py b/tests/memory/test_store.py index 3f3c274..2f2365f 100644 --- a/tests/memory/test_store.py +++ b/tests/memory/test_store.py @@ -6,110 +6,129 @@ class TestInit: - def test_creates_directories(self, tmp_path): + def test_creates_flat_memory_directory(self, tmp_path): store = MemoryStore(tmp_path) store.init() mem = tmp_path / ".koan" / "memory" - assert (mem / "decisions").is_dir() - assert (mem / "context").is_dir() - assert (mem / "lessons").is_dir() - assert (mem / "procedures").is_dir() - assert (mem / "milestones").is_dir() - assert (tmp_path / ".koan" / "user").is_dir() + assert mem.is_dir() + # No type subdirectories + assert not (mem / "decisions").exists() + assert not (mem / "context").exists() + assert not (mem / "lessons").exists() + assert not (mem / "procedures").exists() + # No user dir + assert not (tmp_path / ".koan" / "user").exists() def test_idempotent(self, tmp_path): store = MemoryStore(tmp_path) store.init() store.init() - assert (tmp_path / ".koan" / "memory" / "decisions").is_dir() + assert (tmp_path / ".koan" / "memory").is_dir() class TestAddAndList: - def test_add_and_list_round_trip(self, tmp_path): + def test_add_writes_to_flat_directory(self, tmp_path): store = MemoryStore(tmp_path) store.init() e = store.add_entry( type="decision", title="Use PostgreSQL", - date="2026-04-10", - source="user-stated", - contextual_introduction="Documents the DB choice.", - body="Chose PostgreSQL 16.2 over SQLite.", + body="Documents DB choice. Chose PostgreSQL 16.2 over SQLite.", ) assert e.file_path is not None assert e.file_path.exists() + assert e.file_path.parent == tmp_path / ".koan" / "memory" + assert e.file_path.name == "0001-use-postgresql.md" + assert e.created != "" + assert e.modified != "" - entries = store.list_entries(type="decision") - assert len(entries) == 1 - assert entries[0].title == "Use PostgreSQL" + def test_global_sequence_across_types(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + a = store.add_entry("decision", "D1", "Body.") + b = store.add_entry("lesson", "L1", "Body.") + c = store.add_entry("context", "C1", "Body.") + assert a.file_path.name == "0001-d1.md" + assert b.file_path.name == "0002-l1.md" + assert c.file_path.name == "0003-c1.md" def test_list_all_types(self, tmp_path): store = MemoryStore(tmp_path) store.init() - store.add_entry("decision", "D1", "2026-01-01", "user-stated", "Intro.", "Body.") - store.add_entry("lesson", "L1", "2026-01-02", "post-mortem", "Intro.", "Body.") - store.add_entry("context", "C1", "2026-01-03", "user-stated", "Intro.", "Body.") + store.add_entry("decision", "D1", "Body.") + store.add_entry("lesson", "L1", "Body.") + store.add_entry("context", "C1", "Body.") assert len(store.list_entries()) == 3 def test_list_with_type_filter(self, tmp_path): store = MemoryStore(tmp_path) store.init() - store.add_entry("decision", "D1", "2026-01-01", "user-stated", "Intro.", "Body.") - store.add_entry("lesson", "L1", "2026-01-02", "post-mortem", "Intro.", "Body.") - assert len(store.list_entries(type="decision")) == 1 + store.add_entry("decision", "D1", "Body.") + store.add_entry("decision", "D2", "Body.") + store.add_entry("lesson", "L1", "Body.") + assert len(store.list_entries(type="decision")) == 2 assert len(store.list_entries(type="lesson")) == 1 - assert len(store.list_entries(type="milestone")) == 0 + assert len(store.list_entries(type="procedure")) == 0 + + def test_list_sorted_by_sequence(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + store.add_entry("decision", "First", "Body.") + store.add_entry("lesson", "Second", "Body.") + store.add_entry("decision", "Third", "Body.") + entries = store.list_entries() + assert [e.title for e in entries] == ["First", "Second", "Third"] class TestGetEntry: - def test_by_type_and_number(self, tmp_path): + def test_by_number(self, tmp_path): store = MemoryStore(tmp_path) store.init() - store.add_entry("decision", "First", "2026-01-01", "user-stated", "Intro.", "Body.") - store.add_entry("decision", "Second", "2026-01-02", "user-stated", "Intro.", "Body.") - e = store.get_entry("decision", 2) + store.add_entry("decision", "First", "Body.") + store.add_entry("lesson", "Second", "Body.") + e = store.get_entry(2) assert e is not None assert e.title == "Second" + assert e.type == "lesson" def test_missing(self, tmp_path): store = MemoryStore(tmp_path) store.init() - assert store.get_entry("decision", 99) is None + assert store.get_entry(99) is None class TestEntryCount: def test_count_all(self, tmp_path): store = MemoryStore(tmp_path) store.init() - store.add_entry("decision", "D1", "2026-01-01", "user-stated", "Intro.", "Body.") - store.add_entry("lesson", "L1", "2026-01-02", "post-mortem", "Intro.", "Body.") + store.add_entry("decision", "D1", "Body.") + store.add_entry("lesson", "L1", "Body.") assert store.entry_count() == 2 def test_count_by_type(self, tmp_path): store = MemoryStore(tmp_path) store.init() - store.add_entry("decision", "D1", "2026-01-01", "user-stated", "Intro.", "Body.") - store.add_entry("decision", "D2", "2026-01-02", "user-stated", "Intro.", "Body.") - store.add_entry("lesson", "L1", "2026-01-03", "post-mortem", "Intro.", "Body.") + store.add_entry("decision", "D1", "Body.") + store.add_entry("decision", "D2", "Body.") + store.add_entry("lesson", "L1", "Body.") assert store.entry_count(type="decision") == 2 assert store.entry_count(type="lesson") == 1 + assert store.entry_count(type="procedure") == 0 -class TestDeprecateEntry: - def test_changes_status(self, tmp_path): +class TestForgetEntry: + def test_deletes_file(self, tmp_path): store = MemoryStore(tmp_path) store.init() - e = store.add_entry("decision", "D1", "2026-01-01", "user-stated", "Intro.", "Body.") - assert e.status == "active" - store.deprecate_entry(e) - assert e.status == "deprecated" - # Re-read from disk to verify persistence - reparsed = store.get_entry("decision", 1) - assert reparsed is not None - assert reparsed.status == "deprecated" + e = store.add_entry("decision", "D1", "Body.") + assert e.file_path is not None + assert e.file_path.exists() + store.forget_entry(e) + assert not e.file_path.exists() + assert store.entry_count(type="decision") == 0 -class TestSummaryAndIndex: +class TestSummary: def test_no_summary(self, tmp_path): store = MemoryStore(tmp_path) store.init() @@ -122,20 +141,3 @@ def test_summary_exists(self, tmp_path): summary_path.write_text("# Project Summary\n\nOverview here.\n", "utf-8") assert store.get_summary() is not None assert "Overview here" in store.get_summary() - - def test_no_index(self, tmp_path): - store = MemoryStore(tmp_path) - store.init() - assert store.get_index("decision") is None - - def test_index_exists(self, tmp_path): - from koan.memory.writer import write_index - from koan.memory.types import MemoryIndex - - store = MemoryStore(tmp_path) - store.init() - idx = MemoryIndex(covers=[1, 2], token_count=200, last_generated="2026-04-15", body="Summary.") - write_index(idx, tmp_path / ".koan" / "memory" / "decisions") - result = store.get_index("decision") - assert result is not None - assert result.covers == [1, 2] diff --git a/tests/memory/test_summarize.py b/tests/memory/test_summarize.py new file mode 100644 index 0000000..e97a61b --- /dev/null +++ b/tests/memory/test_summarize.py @@ -0,0 +1,199 @@ +# Tests for koan.memory.summarize +# Unit tests mock the LLM; integration tests require GEMINI_API_KEY. + +from __future__ import annotations + +import os +from unittest.mock import patch + +import pytest + +from koan.memory.store import MemoryStore +from koan.memory.summarize import ( + _render_entries_for_prompt, + generate_summary, + regenerate_summary, +) + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +def _populated_store(tmp_path): + """Create a store with sample entries across types.""" + store = MemoryStore(tmp_path) + store.init() + store.add_entry( + "decision", "PostgreSQL for Auth", + "Documents the choice of primary data store. " + "On 2026-04-10, user chose PostgreSQL 16.2 over SQLite.", + ) + store.add_entry( + "decision", "No Unit Tests", + "Documents the testing policy for TrapperKeeper. " + "On 2026-04-08, user established integration-only testing.", + ) + store.add_entry( + "context", "Team and Infrastructure", + "Captures team and infra context. " + "On 2026-04-01, team documented deployment on a single Hetzner VM.", + ) + store.add_entry( + "lesson", "Executor Generated Unit Tests", + "Records an executor policy violation. " + "On 2026-04-09, executor generated unit tests despite policy.", + ) + store.add_entry( + "procedure", "Check Testing Policy First", + "Rule for any code-generation task. " + "On 2026-04-09, team adopted policy: always read test policy first.", + ) + return store + + +# --------------------------------------------------------------------------- +# Unit tests (mocked LLM) +# --------------------------------------------------------------------------- + +class TestRenderEntries: + def test_includes_title_and_body(self, tmp_path): + store = _populated_store(tmp_path) + text = _render_entries_for_prompt(store.list_entries()) + assert "PostgreSQL for Auth" in text + assert "integration-only testing" in text + assert "Hetzner VM" in text + + +class TestGenerateSummary: + @pytest.mark.anyio + async def test_reads_entries_directly(self, tmp_path): + store = _populated_store(tmp_path) + captured = {} + + async def fake_generate(prompt, system="", max_tokens=1024): + captured["prompt"] = prompt + captured["system"] = system + return "# TrapperKeeper\n\nProject summary here." + + with patch("koan.memory.summarize.generate", side_effect=fake_generate): + summary = await generate_summary(store, project_name="TrapperKeeper") + + prompt = captured["prompt"] + # All entry titles should appear in the prompt (read directly, not indirectly via indexes) + assert "PostgreSQL for Auth" in prompt + assert "No Unit Tests" in prompt + assert "Team and Infrastructure" in prompt + assert "Executor Generated Unit Tests" in prompt + assert "Check Testing Policy First" in prompt + # Project name surfaces in prompt + assert "TrapperKeeper" in prompt + # System prompt should be the summary system prompt + assert "briefing document" in captured["system"] + # Result written to disk + assert summary == "# TrapperKeeper\n\nProject summary here." + assert store.get_summary() is not None + assert "TrapperKeeper" in store.get_summary() + + @pytest.mark.anyio + async def test_no_entries_produces_empty_summary(self, tmp_path): + store = MemoryStore(tmp_path) + store.init() + + summary = await generate_summary(store) + assert "No memory entries" in summary + # Written to disk too + assert store.get_summary() is not None + + @pytest.mark.anyio + async def test_llm_failure_produces_fallback(self, tmp_path): + store = _populated_store(tmp_path) + + async def failing_generate(prompt, system="", max_tokens=1024): + raise RuntimeError("API error") + + with patch("koan.memory.summarize.generate", side_effect=failing_generate): + summary = await generate_summary(store) + + assert "failed" in summary.lower() + + @pytest.mark.anyio + async def test_forgotten_entry_not_in_prompt(self, tmp_path): + store = _populated_store(tmp_path) + # Forget one entry + to_forget = store.list_entries(type="decision")[0] + store.forget_entry(to_forget) + + captured = {} + + async def fake_generate(prompt, system="", max_tokens=1024): + captured["prompt"] = prompt + return "summary" + + with patch("koan.memory.summarize.generate", side_effect=fake_generate): + await generate_summary(store) + + assert "PostgreSQL for Auth" not in captured["prompt"] + + +class TestRegenerateSummary: + @pytest.mark.anyio + async def test_delegates_to_generate_summary(self, tmp_path): + store = _populated_store(tmp_path) + called = {} + + async def fake_generate_summary(s, project_name=""): + called["store"] = s + called["name"] = project_name + return "stub" + + with patch( + "koan.memory.summarize.generate_summary", + side_effect=fake_generate_summary, + ): + await regenerate_summary(store, project_name="Foo") + + assert called["store"] is store + assert called["name"] == "Foo" + + +class TestStoreRegenerateSummary: + @pytest.mark.anyio + async def test_delegates_to_module(self, tmp_path): + store = _populated_store(tmp_path) + called = {} + + async def mock_regen(s, project_name=""): + called["store"] = s + called["name"] = project_name + + with patch("koan.memory.summarize.regenerate_summary", mock_regen): + await store.regenerate_summary(project_name="Foo") + + assert called["store"] is store + assert called["name"] == "Foo" + + +# --------------------------------------------------------------------------- +# Integration tests (require API key) +# --------------------------------------------------------------------------- + +_SKIP_NO_KEY = pytest.mark.skipif( + not os.environ.get("GEMINI_API_KEY"), + reason="GEMINI_API_KEY not set", +) + +# gemini-3-flash-lite is the spec default but may not be available yet; +# fall back to the latest available lite model for integration tests. +_INTEGRATION_MODEL = os.environ.get("KOAN_LLM_MODEL") or "gemini-2.5-flash-lite" + + +@_SKIP_NO_KEY +class TestIntegrationSummary: + @pytest.mark.anyio + async def test_produces_coherent_overview(self, tmp_path, monkeypatch): + monkeypatch.setenv("KOAN_LLM_MODEL", _INTEGRATION_MODEL) + store = _populated_store(tmp_path) + summary = await generate_summary(store, project_name="TrapperKeeper") + assert len(summary) > 50 + assert store.get_summary() is not None diff --git a/tests/memory/test_validation.py b/tests/memory/test_validation.py index 272bfc2..62babde 100644 --- a/tests/memory/test_validation.py +++ b/tests/memory/test_validation.py @@ -10,10 +10,6 @@ def _valid_entry(**overrides) -> MemoryEntry: defaults = dict( title="PostgreSQL for Auth", type="decision", - date="2026-04-10", - source="user-stated", - status="active", - contextual_introduction="Documents the data store choice.", body="Chose PostgreSQL 16.2 over SQLite.", ) defaults.update(overrides) @@ -34,42 +30,12 @@ def test_missing_type(self): errors = validate_entry(_valid_entry(type="")) assert any("type" in e for e in errors) - def test_missing_date(self): - errors = validate_entry(_valid_entry(date="")) - assert any("date" in e for e in errors) - - def test_missing_source(self): - errors = validate_entry(_valid_entry(source="")) - assert any("source" in e for e in errors) - - def test_missing_status(self): - errors = validate_entry(_valid_entry(status="")) - assert any("status" in e for e in errors) + def test_missing_body(self): + errors = validate_entry(_valid_entry(body="")) + assert any("body" in e for e in errors) -class TestInvalidValues: +class TestInvalidType: def test_invalid_type(self): errors = validate_entry(_valid_entry(type="opinion")) assert any("invalid type" in e for e in errors) - - def test_invalid_source(self): - errors = validate_entry(_valid_entry(source="guessed")) - assert any("invalid source" in e for e in errors) - - def test_invalid_status(self): - errors = validate_entry(_valid_entry(status="pending")) - assert any("invalid status" in e for e in errors) - - def test_invalid_date_format(self): - errors = validate_entry(_valid_entry(date="April 10")) - assert any("ISO 8601" in e for e in errors) - - -class TestMissingContent: - def test_missing_intro(self): - errors = validate_entry(_valid_entry(contextual_introduction="")) - assert any("contextual_introduction" in e for e in errors) - - def test_missing_body(self): - errors = validate_entry(_valid_entry(body="")) - assert any("body" in e for e in errors) diff --git a/tests/memory/test_writer.py b/tests/memory/test_writer.py index e02ded1..3684e50 100644 --- a/tests/memory/test_writer.py +++ b/tests/memory/test_writer.py @@ -2,23 +2,21 @@ from __future__ import annotations -from pathlib import Path +import time -from koan.memory.types import MemoryEntry -from koan.memory.writer import write_entry, update_entry, write_index, _slugify from koan.memory.parser import parse_entry -from koan.memory.types import MemoryIndex +from koan.memory.types import MemoryEntry +from koan.memory.writer import _slugify, update_entry, write_entry def _entry(**overrides) -> MemoryEntry: defaults = dict( title="PostgreSQL for Auth", type="decision", - date="2026-04-10", - source="user-stated", - status="active", - contextual_introduction="This entry documents the choice of data store.", - body="On 2026-04-10, user chose PostgreSQL 16.2.", + body=( + "This entry documents the choice of data store.\n\n" + "On 2026-04-10, user chose PostgreSQL 16.2 over SQLite." + ), ) defaults.update(overrides) return MemoryEntry(**defaults) @@ -37,7 +35,6 @@ def test_truncate(self): assert len(slug) <= 50 def test_trailing_hyphen_after_truncation(self): - # Title that would produce a trailing hyphen at the cut point title = "a" * 49 + " b" slug = _slugify(title) assert not slug.endswith("-") @@ -50,69 +47,58 @@ def test_first_entry(self, tmp_path): assert p.name == "0001-postgresql-for-auth.md" assert p.exists() + def test_auto_timestamps(self, tmp_path): + e = _entry() + write_entry(e, tmp_path) + assert e.created != "" + assert e.modified != "" + assert e.created == e.modified # same instant on creation + + def test_preserves_existing_created(self, tmp_path): + e = _entry(created="2026-01-01T00:00:00Z") + write_entry(e, tmp_path) + assert e.created == "2026-01-01T00:00:00Z" + # modified is always set on write + assert e.modified != "" + assert e.modified != e.created + def test_second_entry(self, tmp_path): write_entry(_entry(), tmp_path) p2 = write_entry(_entry(title="Redis for Sessions"), tmp_path) assert p2.name == "0002-redis-for-sessions.md" - def test_no_reuse_after_deletion(self, tmp_path): - """Deleting the highest-numbered file does not reuse its number - when a lower-numbered file still exists -- but the scanner only - sees current files, so max(existing)+1 is the best guarantee - without external state. When 0001 exists and 0002 is deleted, - the next file is 0002 (max(1)+1). When a *middle* file is - deleted, the gap is never filled because the scanner uses max, - not "first available".""" + def test_no_reuse_of_middle_gap(self, tmp_path): write_entry(_entry(), tmp_path) # 0001 write_entry(_entry(title="Second"), tmp_path) # 0002 p3 = write_entry(_entry(title="Third"), tmp_path) # 0003 assert p3.name == "0003-third.md" - # Delete the middle file -- gap at 0002 is never filled. (tmp_path / "0002-second.md").unlink() p4 = write_entry(_entry(title="Fourth"), tmp_path) assert p4.name == "0004-fourth.md" def test_round_trip(self, tmp_path): - original = _entry( - tags=["auth", "db"], - related=["context/0001-infra.md"], - ) + original = _entry(related=["0001-infra.md"]) p = write_entry(original, tmp_path) parsed = parse_entry(p) assert parsed.title == original.title assert parsed.type == original.type - assert parsed.date == original.date - assert parsed.source == original.source - assert parsed.status == original.status - assert parsed.tags == original.tags + assert parsed.body == original.body.strip() assert parsed.related == original.related - assert parsed.contextual_introduction == original.contextual_introduction - assert parsed.body == original.body + assert parsed.created == original.created + assert parsed.modified == original.modified class TestUpdateEntry: - def test_preserves_filename(self, tmp_path): + def test_preserves_filename_and_created(self, tmp_path): e = _entry() p = write_entry(e, tmp_path) e.file_path = p - e.status = "deprecated" + original_created = e.created + # Sleep long enough to guarantee a different second-precision timestamp + time.sleep(1.1) + e.body = "Updated body." update_entry(e) reparsed = parse_entry(p) - assert reparsed.status == "deprecated" - assert reparsed.file_path == p - - -class TestWriteIndex: - def test_writes_index(self, tmp_path): - idx = MemoryIndex( - covers=[1, 2, 3], - token_count=380, - last_generated="2026-04-15", - body="Summary of decisions.", - ) - p = write_index(idx, tmp_path) - assert p.name == "_index.md" - assert p.exists() - text = p.read_text("utf-8") - assert "covers:" in text - assert "Summary of decisions." in text + assert reparsed.body == "Updated body." + assert reparsed.created == original_created + assert reparsed.modified != original_created diff --git a/uv.lock b/uv.lock index 367e259..dea95ec 100644 --- a/uv.lock +++ b/uv.lock @@ -171,6 +171,79 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ae/3a/dbeec9d1ee0844c679f6bb5d6ad4e9f198b1224f4e7a32825f47f6192b0c/cffi-2.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0a1527a803f0a659de1af2e1fd700213caba79377e27e4693648c2923da066f9", size = 184195, upload-time = "2025-09-08T23:23:43.004Z" }, ] +[[package]] +name = "charset-normalizer" +version = "3.4.7" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/e7/a1/67fe25fac3c7642725500a3f6cfe5821ad557c3abb11c9d20d12c7008d3e/charset_normalizer-3.4.7.tar.gz", hash = "sha256:ae89db9e5f98a11a4bf50407d4363e7b09b31e55bc117b4f7d80aab97ba009e5", size = 144271, upload-time = "2026-04-02T09:28:39.342Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/0c/eb/4fc8d0a7110eb5fc9cc161723a34a8a6c200ce3b4fbf681bc86feee22308/charset_normalizer-3.4.7-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:eca9705049ad3c7345d574e3510665cb2cf844c2f2dcfe675332677f081cbd46", size = 311328, upload-time = "2026-04-02T09:26:24.331Z" }, + { url = "https://files.pythonhosted.org/packages/f8/e3/0fadc706008ac9d7b9b5be6dc767c05f9d3e5df51744ce4cc9605de7b9f4/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6178f72c5508bfc5fd446a5905e698c6212932f25bcdd4b47a757a50605a90e2", size = 208061, upload-time = "2026-04-02T09:26:25.568Z" }, + { url = "https://files.pythonhosted.org/packages/42/f0/3dd1045c47f4a4604df85ec18ad093912ae1344ac706993aff91d38773a2/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e1421b502d83040e6d7fb2fb18dff63957f720da3d77b2fbd3187ceb63755d7b", size = 229031, upload-time = "2026-04-02T09:26:26.865Z" }, + { url = "https://files.pythonhosted.org/packages/dc/67/675a46eb016118a2fbde5a277a5d15f4f69d5f3f5f338e5ee2f8948fcf43/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:edac0f1ab77644605be2cbba52e6b7f630731fc42b34cb0f634be1a6eface56a", size = 225239, upload-time = "2026-04-02T09:26:28.044Z" }, + { url = "https://files.pythonhosted.org/packages/4b/f8/d0118a2f5f23b02cd166fa385c60f9b0d4f9194f574e2b31cef350ad7223/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5649fd1c7bade02f320a462fdefd0b4bd3ce036065836d4f42e0de958038e116", size = 216589, upload-time = "2026-04-02T09:26:29.239Z" }, + { url = "https://files.pythonhosted.org/packages/b1/f1/6d2b0b261b6c4ceef0fcb0d17a01cc5bc53586c2d4796fa04b5c540bc13d/charset_normalizer-3.4.7-cp312-cp312-manylinux_2_31_armv7l.whl", hash = "sha256:203104ed3e428044fd943bc4bf45fa73c0730391f9621e37fe39ecf477b128cb", size = 202733, upload-time = "2026-04-02T09:26:30.5Z" }, + { url = "https://files.pythonhosted.org/packages/6f/c0/7b1f943f7e87cc3db9626ba17807d042c38645f0a1d4415c7a14afb5591f/charset_normalizer-3.4.7-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:298930cec56029e05497a76988377cbd7457ba864beeea92ad7e844fe74cd1f1", size = 212652, upload-time = "2026-04-02T09:26:31.709Z" }, + { url = "https://files.pythonhosted.org/packages/38/dd/5a9ab159fe45c6e72079398f277b7d2b523e7f716acc489726115a910097/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:708838739abf24b2ceb208d0e22403dd018faeef86ddac04319a62ae884c4f15", size = 211229, upload-time = "2026-04-02T09:26:33.282Z" }, + { url = "https://files.pythonhosted.org/packages/d5/ff/531a1cad5ca855d1c1a8b69cb71abfd6d85c0291580146fda7c82857caa1/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:0f7eb884681e3938906ed0434f20c63046eacd0111c4ba96f27b76084cd679f5", size = 203552, upload-time = "2026-04-02T09:26:34.845Z" }, + { url = "https://files.pythonhosted.org/packages/c1/4c/a5fb52d528a8ca41f7598cb619409ece30a169fbdf9cdce592e53b46c3a6/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:4dc1e73c36828f982bfe79fadf5919923f8a6f4df2860804db9a98c48824ce8d", size = 230806, upload-time = "2026-04-02T09:26:36.152Z" }, + { url = "https://files.pythonhosted.org/packages/59/7a/071feed8124111a32b316b33ae4de83d36923039ef8cf48120266844285b/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:aed52fea0513bac0ccde438c188c8a471c4e0f457c2dd20cdbf6ea7a450046c7", size = 212316, upload-time = "2026-04-02T09:26:37.672Z" }, + { url = "https://files.pythonhosted.org/packages/fd/35/f7dba3994312d7ba508e041eaac39a36b120f32d4c8662b8814dab876431/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:fea24543955a6a729c45a73fe90e08c743f0b3334bbf3201e6c4bc1b0c7fa464", size = 227274, upload-time = "2026-04-02T09:26:38.93Z" }, + { url = "https://files.pythonhosted.org/packages/8a/2d/a572df5c9204ab7688ec1edc895a73ebded3b023bb07364710b05dd1c9be/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:bb6d88045545b26da47aa879dd4a89a71d1dce0f0e549b1abcb31dfe4a8eac49", size = 218468, upload-time = "2026-04-02T09:26:40.17Z" }, + { url = "https://files.pythonhosted.org/packages/86/eb/890922a8b03a568ca2f336c36585a4713c55d4d67bf0f0c78924be6315ca/charset_normalizer-3.4.7-cp312-cp312-win32.whl", hash = "sha256:2257141f39fe65a3fdf38aeccae4b953e5f3b3324f4ff0daf9f15b8518666a2c", size = 148460, upload-time = "2026-04-02T09:26:41.416Z" }, + { url = "https://files.pythonhosted.org/packages/35/d9/0e7dffa06c5ab081f75b1b786f0aefc88365825dfcd0ac544bdb7b2b6853/charset_normalizer-3.4.7-cp312-cp312-win_amd64.whl", hash = "sha256:5ed6ab538499c8644b8a3e18debabcd7ce684f3fa91cf867521a7a0279cab2d6", size = 159330, upload-time = "2026-04-02T09:26:42.554Z" }, + { url = "https://files.pythonhosted.org/packages/9e/5d/481bcc2a7c88ea6b0878c299547843b2521ccbc40980cb406267088bc701/charset_normalizer-3.4.7-cp312-cp312-win_arm64.whl", hash = "sha256:56be790f86bfb2c98fb742ce566dfb4816e5a83384616ab59c49e0604d49c51d", size = 147828, upload-time = "2026-04-02T09:26:44.075Z" }, + { url = "https://files.pythonhosted.org/packages/c1/3b/66777e39d3ae1ddc77ee606be4ec6d8cbd4c801f65e5a1b6f2b11b8346dd/charset_normalizer-3.4.7-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:f496c9c3cc02230093d8330875c4c3cdfc3b73612a5fd921c65d39cbcef08063", size = 309627, upload-time = "2026-04-02T09:26:45.198Z" }, + { url = "https://files.pythonhosted.org/packages/2e/4e/b7f84e617b4854ade48a1b7915c8ccfadeba444d2a18c291f696e37f0d3b/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ea948db76d31190bf08bd371623927ee1339d5f2a0b4b1b4a4439a65298703c", size = 207008, upload-time = "2026-04-02T09:26:46.824Z" }, + { url = "https://files.pythonhosted.org/packages/c4/bb/ec73c0257c9e11b268f018f068f5d00aa0ef8c8b09f7753ebd5f2880e248/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a277ab8928b9f299723bc1a2dabb1265911b1a76341f90a510368ca44ad9ab66", size = 228303, upload-time = "2026-04-02T09:26:48.397Z" }, + { url = "https://files.pythonhosted.org/packages/85/fb/32d1f5033484494619f701e719429c69b766bfc4dbc61aa9e9c8c166528b/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3bec022aec2c514d9cf199522a802bd007cd588ab17ab2525f20f9c34d067c18", size = 224282, upload-time = "2026-04-02T09:26:49.684Z" }, + { url = "https://files.pythonhosted.org/packages/fa/07/330e3a0dda4c404d6da83b327270906e9654a24f6c546dc886a0eb0ffb23/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e044c39e41b92c845bc815e5ae4230804e8e7bc29e399b0437d64222d92809dd", size = 215595, upload-time = "2026-04-02T09:26:50.915Z" }, + { url = "https://files.pythonhosted.org/packages/e3/7c/fc890655786e423f02556e0216d4b8c6bcb6bdfa890160dc66bf52dee468/charset_normalizer-3.4.7-cp313-cp313-manylinux_2_31_armv7l.whl", hash = "sha256:f495a1652cf3fbab2eb0639776dad966c2fb874d79d87ca07f9d5f059b8bd215", size = 201986, upload-time = "2026-04-02T09:26:52.197Z" }, + { url = "https://files.pythonhosted.org/packages/d8/97/bfb18b3db2aed3b90cf54dc292ad79fdd5ad65c4eae454099475cbeadd0d/charset_normalizer-3.4.7-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e712b419df8ba5e42b226c510472b37bd57b38e897d3eca5e8cfd410a29fa859", size = 211711, upload-time = "2026-04-02T09:26:53.49Z" }, + { url = "https://files.pythonhosted.org/packages/6f/a5/a581c13798546a7fd557c82614a5c65a13df2157e9ad6373166d2a3e645d/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:7804338df6fcc08105c7745f1502ba68d900f45fd770d5bdd5288ddccb8a42d8", size = 210036, upload-time = "2026-04-02T09:26:54.975Z" }, + { url = "https://files.pythonhosted.org/packages/8c/bf/b3ab5bcb478e4193d517644b0fb2bf5497fbceeaa7a1bc0f4d5b50953861/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:481551899c856c704d58119b5025793fa6730adda3571971af568f66d2424bb5", size = 202998, upload-time = "2026-04-02T09:26:56.303Z" }, + { url = "https://files.pythonhosted.org/packages/e7/4e/23efd79b65d314fa320ec6017b4b5834d5c12a58ba4610aa353af2e2f577/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:f59099f9b66f0d7145115e6f80dd8b1d847176df89b234a5a6b3f00437aa0832", size = 230056, upload-time = "2026-04-02T09:26:57.554Z" }, + { url = "https://files.pythonhosted.org/packages/b9/9f/1e1941bc3f0e01df116e68dc37a55c4d249df5e6fa77f008841aef68264f/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:f59ad4c0e8f6bba240a9bb85504faa1ab438237199d4cce5f622761507b8f6a6", size = 211537, upload-time = "2026-04-02T09:26:58.843Z" }, + { url = "https://files.pythonhosted.org/packages/80/0f/088cbb3020d44428964a6c97fe1edfb1b9550396bf6d278330281e8b709c/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:3dedcc22d73ec993f42055eff4fcfed9318d1eeb9a6606c55892a26964964e48", size = 226176, upload-time = "2026-04-02T09:27:00.437Z" }, + { url = "https://files.pythonhosted.org/packages/6a/9f/130394f9bbe06f4f63e22641d32fc9b202b7e251c9aef4db044324dac493/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:64f02c6841d7d83f832cd97ccf8eb8a906d06eb95d5276069175c696b024b60a", size = 217723, upload-time = "2026-04-02T09:27:02.021Z" }, + { url = "https://files.pythonhosted.org/packages/73/55/c469897448a06e49f8fa03f6caae97074fde823f432a98f979cc42b90e69/charset_normalizer-3.4.7-cp313-cp313-win32.whl", hash = "sha256:4042d5c8f957e15221d423ba781e85d553722fc4113f523f2feb7b188cc34c5e", size = 148085, upload-time = "2026-04-02T09:27:03.192Z" }, + { url = "https://files.pythonhosted.org/packages/5d/78/1b74c5bbb3f99b77a1715c91b3e0b5bdb6fe302d95ace4f5b1bec37b0167/charset_normalizer-3.4.7-cp313-cp313-win_amd64.whl", hash = "sha256:3946fa46a0cf3e4c8cb1cc52f56bb536310d34f25f01ca9b6c16afa767dab110", size = 158819, upload-time = "2026-04-02T09:27:04.454Z" }, + { url = "https://files.pythonhosted.org/packages/68/86/46bd42279d323deb8687c4a5a811fd548cb7d1de10cf6535d099877a9a9f/charset_normalizer-3.4.7-cp313-cp313-win_arm64.whl", hash = "sha256:80d04837f55fc81da168b98de4f4b797ef007fc8a79ab71c6ec9bc4dd662b15b", size = 147915, upload-time = "2026-04-02T09:27:05.971Z" }, + { url = "https://files.pythonhosted.org/packages/97/c8/c67cb8c70e19ef1960b97b22ed2a1567711de46c4ddf19799923adc836c2/charset_normalizer-3.4.7-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:c36c333c39be2dbca264d7803333c896ab8fa7d4d6f0ab7edb7dfd7aea6e98c0", size = 309234, upload-time = "2026-04-02T09:27:07.194Z" }, + { url = "https://files.pythonhosted.org/packages/99/85/c091fdee33f20de70d6c8b522743b6f831a2f1cd3ff86de4c6a827c48a76/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1c2aed2e5e41f24ea8ef1590b8e848a79b56f3a5564a65ceec43c9d692dc7d8a", size = 208042, upload-time = "2026-04-02T09:27:08.749Z" }, + { url = "https://files.pythonhosted.org/packages/87/1c/ab2ce611b984d2fd5d86a5a8a19c1ae26acac6bad967da4967562c75114d/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:54523e136b8948060c0fa0bc7b1b50c32c186f2fceee897a495406bb6e311d2b", size = 228706, upload-time = "2026-04-02T09:27:09.951Z" }, + { url = "https://files.pythonhosted.org/packages/a8/29/2b1d2cb00bf085f59d29eb773ce58ec2d325430f8c216804a0a5cd83cbca/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:715479b9a2802ecac752a3b0efa2b0b60285cf962ee38414211abdfccc233b41", size = 224727, upload-time = "2026-04-02T09:27:11.175Z" }, + { url = "https://files.pythonhosted.org/packages/47/5c/032c2d5a07fe4d4855fea851209cca2b6f03ebeb6d4e3afdb3358386a684/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bd6c2a1c7573c64738d716488d2cdd3c00e340e4835707d8fdb8dc1a66ef164e", size = 215882, upload-time = "2026-04-02T09:27:12.446Z" }, + { url = "https://files.pythonhosted.org/packages/2c/c2/356065d5a8b78ed04499cae5f339f091946a6a74f91e03476c33f0ab7100/charset_normalizer-3.4.7-cp314-cp314-manylinux_2_31_armv7l.whl", hash = "sha256:c45e9440fb78f8ddabcf714b68f936737a121355bf59f3907f4e17721b9d1aae", size = 200860, upload-time = "2026-04-02T09:27:13.721Z" }, + { url = "https://files.pythonhosted.org/packages/0c/cd/a32a84217ced5039f53b29f460962abb2d4420def55afabe45b1c3c7483d/charset_normalizer-3.4.7-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3534e7dcbdcf757da6b85a0bbf5b6868786d5982dd959b065e65481644817a18", size = 211564, upload-time = "2026-04-02T09:27:15.272Z" }, + { url = "https://files.pythonhosted.org/packages/44/86/58e6f13ce26cc3b8f4a36b94a0f22ae2f00a72534520f4ae6857c4b81f89/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:e8ac484bf18ce6975760921bb6148041faa8fef0547200386ea0b52b5d27bf7b", size = 211276, upload-time = "2026-04-02T09:27:16.834Z" }, + { url = "https://files.pythonhosted.org/packages/8f/fe/d17c32dc72e17e155e06883efa84514ca375f8a528ba2546bee73fc4df81/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:a5fe03b42827c13cdccd08e6c0247b6a6d4b5e3cdc53fd1749f5896adcdc2356", size = 201238, upload-time = "2026-04-02T09:27:18.229Z" }, + { url = "https://files.pythonhosted.org/packages/6a/29/f33daa50b06525a237451cdb6c69da366c381a3dadcd833fa5676bc468b3/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:2d6eb928e13016cea4f1f21d1e10c1cebd5a421bc57ddf5b1142ae3f86824fab", size = 230189, upload-time = "2026-04-02T09:27:19.445Z" }, + { url = "https://files.pythonhosted.org/packages/b6/6e/52c84015394a6a0bdcd435210a7e944c5f94ea1055f5cc5d56c5fe368e7b/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:e74327fb75de8986940def6e8dee4f127cc9752bee7355bb323cc5b2659b6d46", size = 211352, upload-time = "2026-04-02T09:27:20.79Z" }, + { url = "https://files.pythonhosted.org/packages/8c/d7/4353be581b373033fb9198bf1da3cf8f09c1082561e8e922aa7b39bf9fe8/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:d6038d37043bced98a66e68d3aa2b6a35505dc01328cd65217cefe82f25def44", size = 227024, upload-time = "2026-04-02T09:27:22.063Z" }, + { url = "https://files.pythonhosted.org/packages/30/45/99d18aa925bd1740098ccd3060e238e21115fffbfdcb8f3ece837d0ace6c/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:7579e913a5339fb8fa133f6bbcfd8e6749696206cf05acdbdca71a1b436d8e72", size = 217869, upload-time = "2026-04-02T09:27:23.486Z" }, + { url = "https://files.pythonhosted.org/packages/5c/05/5ee478aa53f4bb7996482153d4bfe1b89e0f087f0ab6b294fcf92d595873/charset_normalizer-3.4.7-cp314-cp314-win32.whl", hash = "sha256:5b77459df20e08151cd6f8b9ef8ef1f961ef73d85c21a555c7eed5b79410ec10", size = 148541, upload-time = "2026-04-02T09:27:25.146Z" }, + { url = "https://files.pythonhosted.org/packages/48/77/72dcb0921b2ce86420b2d79d454c7022bf5be40202a2a07906b9f2a35c97/charset_normalizer-3.4.7-cp314-cp314-win_amd64.whl", hash = "sha256:92a0a01ead5e668468e952e4238cccd7c537364eb7d851ab144ab6627dbbe12f", size = 159634, upload-time = "2026-04-02T09:27:26.642Z" }, + { url = "https://files.pythonhosted.org/packages/c6/a3/c2369911cd72f02386e4e340770f6e158c7980267da16af8f668217abaa0/charset_normalizer-3.4.7-cp314-cp314-win_arm64.whl", hash = "sha256:67f6279d125ca0046a7fd386d01b311c6363844deac3e5b069b514ba3e63c246", size = 148384, upload-time = "2026-04-02T09:27:28.271Z" }, + { url = "https://files.pythonhosted.org/packages/94/09/7e8a7f73d24dba1f0035fbbf014d2c36828fc1bf9c88f84093e57d315935/charset_normalizer-3.4.7-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:effc3f449787117233702311a1b7d8f59cba9ced946ba727bdc329ec69028e24", size = 330133, upload-time = "2026-04-02T09:27:29.474Z" }, + { url = "https://files.pythonhosted.org/packages/8d/da/96975ddb11f8e977f706f45cddd8540fd8242f71ecdb5d18a80723dcf62c/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fbccdc05410c9ee21bbf16a35f4c1d16123dcdeb8a1d38f33654fa21d0234f79", size = 216257, upload-time = "2026-04-02T09:27:30.793Z" }, + { url = "https://files.pythonhosted.org/packages/e5/e8/1d63bf8ef2d388e95c64b2098f45f84758f6d102a087552da1485912637b/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:733784b6d6def852c814bce5f318d25da2ee65dd4839a0718641c696e09a2960", size = 234851, upload-time = "2026-04-02T09:27:32.44Z" }, + { url = "https://files.pythonhosted.org/packages/9b/40/e5ff04233e70da2681fa43969ad6f66ca5611d7e669be0246c4c7aaf6dc8/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a89c23ef8d2c6b27fd200a42aa4ac72786e7c60d40efdc76e6011260b6e949c4", size = 233393, upload-time = "2026-04-02T09:27:34.03Z" }, + { url = "https://files.pythonhosted.org/packages/be/c1/06c6c49d5a5450f76899992f1ee40b41d076aee9279b49cf9974d2f313d5/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6c114670c45346afedc0d947faf3c7f701051d2518b943679c8ff88befe14f8e", size = 223251, upload-time = "2026-04-02T09:27:35.369Z" }, + { url = "https://files.pythonhosted.org/packages/2b/9f/f2ff16fb050946169e3e1f82134d107e5d4ae72647ec8a1b1446c148480f/charset_normalizer-3.4.7-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:a180c5e59792af262bf263b21a3c49353f25945d8d9f70628e73de370d55e1e1", size = 206609, upload-time = "2026-04-02T09:27:36.661Z" }, + { url = "https://files.pythonhosted.org/packages/69/d5/a527c0cd8d64d2eab7459784fb4169a0ac76e5a6fc5237337982fd61347e/charset_normalizer-3.4.7-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3c9a494bc5ec77d43cea229c4f6db1e4d8fe7e1bbffa8b6f0f0032430ff8ab44", size = 220014, upload-time = "2026-04-02T09:27:38.019Z" }, + { url = "https://files.pythonhosted.org/packages/7e/80/8a7b8104a3e203074dc9aa2c613d4b726c0e136bad1cc734594b02867972/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8d828b6667a32a728a1ad1d93957cdf37489c57b97ae6c4de2860fa749b8fc1e", size = 218979, upload-time = "2026-04-02T09:27:39.37Z" }, + { url = "https://files.pythonhosted.org/packages/02/9a/b759b503d507f375b2b5c153e4d2ee0a75aa215b7f2489cf314f4541f2c0/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:cf1493cd8607bec4d8a7b9b004e699fcf8f9103a9284cc94962cb73d20f9d4a3", size = 209238, upload-time = "2026-04-02T09:27:40.722Z" }, + { url = "https://files.pythonhosted.org/packages/c2/4e/0f3f5d47b86bdb79256e7290b26ac847a2832d9a4033f7eb2cd4bcf4bb5b/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:0c96c3b819b5c3e9e165495db84d41914d6894d55181d2d108cc1a69bfc9cce0", size = 236110, upload-time = "2026-04-02T09:27:42.33Z" }, + { url = "https://files.pythonhosted.org/packages/96/23/bce28734eb3ed2c91dcf93abeb8a5cf393a7b2749725030bb630e554fdd8/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:752a45dc4a6934060b3b0dab47e04edc3326575f82be64bc4fc293914566503e", size = 219824, upload-time = "2026-04-02T09:27:43.924Z" }, + { url = "https://files.pythonhosted.org/packages/2c/6f/6e897c6984cc4d41af319b077f2f600fc8214eb2fe2d6bcb79141b882400/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:8778f0c7a52e56f75d12dae53ae320fae900a8b9b4164b981b9c5ce059cd1fcb", size = 233103, upload-time = "2026-04-02T09:27:45.348Z" }, + { url = "https://files.pythonhosted.org/packages/76/22/ef7bd0fe480a0ae9b656189ec00744b60933f68b4f42a7bb06589f6f576a/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:ce3412fbe1e31eb81ea42f4169ed94861c56e643189e1e75f0041f3fe7020abe", size = 225194, upload-time = "2026-04-02T09:27:46.706Z" }, + { url = "https://files.pythonhosted.org/packages/c5/a7/0e0ab3e0b5bc1219bd80a6a0d4d72ca74d9250cb2382b7c699c147e06017/charset_normalizer-3.4.7-cp314-cp314t-win32.whl", hash = "sha256:c03a41a8784091e67a39648f70c5f97b5b6a37f216896d44d2cdcb82615339a0", size = 159827, upload-time = "2026-04-02T09:27:48.053Z" }, + { url = "https://files.pythonhosted.org/packages/7a/1d/29d32e0fb40864b1f878c7f5a0b343ae676c6e2b271a2d55cc3a152391da/charset_normalizer-3.4.7-cp314-cp314t-win_amd64.whl", hash = "sha256:03853ed82eeebbce3c2abfdbc98c96dc205f32a79627688ac9a27370ea61a49c", size = 174168, upload-time = "2026-04-02T09:27:49.795Z" }, + { url = "https://files.pythonhosted.org/packages/de/32/d92444ad05c7a6e41fb2036749777c163baf7a0301a040cb672d6b2b1ae9/charset_normalizer-3.4.7-cp314-cp314t-win_arm64.whl", hash = "sha256:c35abb8bfff0185efac5878da64c45dafd2b37fb0383add1be155a763c1f083d", size = 153018, upload-time = "2026-04-02T09:27:51.116Z" }, + { url = "https://files.pythonhosted.org/packages/db/8f/61959034484a4a7c527811f4721e75d02d653a35afb0b6054474d8185d4c/charset_normalizer-3.4.7-py3-none-any.whl", hash = "sha256:3dce51d0f5e7951f8bb4900c257dad282f49190fdbebecd4ba99bcc41fef404d", size = 61958, upload-time = "2026-04-02T09:28:37.794Z" }, +] + [[package]] name = "click" version = "8.3.1" @@ -260,6 +333,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/8a/0b/2261922126b2e50c601fe22d7ff5194e0a4d50e654836260c0665e24d862/cyclopts-4.10.1-py3-none-any.whl", hash = "sha256:35f37257139380a386d9fe4475e1e7c87ca7795765ef4f31abba579fcfcb6ecd", size = 204331, upload-time = "2026-03-23T14:43:02.625Z" }, ] +[[package]] +name = "distro" +version = "1.9.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/fc/f8/98eea607f65de6527f8a2e8885fc8015d3e6f5775df186e443e0964a11c3/distro-1.9.0.tar.gz", hash = "sha256:2fa77c6fd8940f116ee1d6b94a2f90b13b5ea8d019b98bc8bafdcabcdd9bdbed", size = 60722, upload-time = "2023-12-24T09:54:32.31Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/12/b3/231ffd4ab1fc9d679809f356cebee130ac7daa00d6d6f3206dd4fd137e9e/distro-1.9.0-py3-none-any.whl", hash = "sha256:7bffd925d65168f85027d8da9af6bddab658135b840670a223589bc0c8ef02b2", size = 20277, upload-time = "2023-12-24T09:54:30.421Z" }, +] + [[package]] name = "dnspython" version = "2.8.0" @@ -344,6 +426,45 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/70/ea/570122de7e24f72138d006f799768e14cc1ccf7fcb22b7750b2bd276c711/fastmcp-3.1.1-py3-none-any.whl", hash = "sha256:8132ba069d89f14566b3266919d6d72e2ec23dd45d8944622dca407e9beda7eb", size = 633754, upload-time = "2026-03-14T19:12:22.736Z" }, ] +[[package]] +name = "google-auth" +version = "2.49.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "cryptography" }, + { name = "pyasn1-modules" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/c6/fc/e925290a1ad95c975c459e2df070fac2b90954e13a0370ac505dff78cb99/google_auth-2.49.2.tar.gz", hash = "sha256:c1ae38500e73065dcae57355adb6278cf8b5c8e391994ae9cbadbcb9631ab409", size = 333958, upload-time = "2026-04-10T00:41:21.888Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/73/76/d241a5c927433420507215df6cac1b1fa4ac0ba7a794df42a84326c68da8/google_auth-2.49.2-py3-none-any.whl", hash = "sha256:c2720924dfc82dedb962c9f52cabb2ab16714fd0a6a707e40561d217574ed6d5", size = 240638, upload-time = "2026-04-10T00:41:14.501Z" }, +] + +[package.optional-dependencies] +requests = [ + { name = "requests" }, +] + +[[package]] +name = "google-genai" +version = "1.73.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "anyio" }, + { name = "distro" }, + { name = "google-auth", extra = ["requests"] }, + { name = "httpx" }, + { name = "pydantic" }, + { name = "requests" }, + { name = "sniffio" }, + { name = "tenacity" }, + { name = "typing-extensions" }, + { name = "websockets" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/99/5f/b293b1a78a547b0dd061642a3f6087f0a52c1b723eafa58f94ccdc3e0d2a/google_genai-1.73.0.tar.gz", hash = "sha256:569395b2c225e12bcd8758b8affe1af480e0a1b1c71d652d38c705677057e05f", size = 530812, upload-time = "2026-04-13T20:40:02.642Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5a/73/fb36ced456688c9b95a8ab49a1f408f5b3e69a589788f3eb25016002dd7a/google_genai-1.73.0-py3-none-any.whl", hash = "sha256:dfb0214b834bf977e3841de512cfb651d2fe76309f85064b80c2bc11da99d76b", size = 786072, upload-time = "2026-04-13T20:40:00.365Z" }, +] + [[package]] name = "h11" version = "0.16.0" @@ -586,7 +707,9 @@ source = { editable = "." } dependencies = [ { name = "aiofiles" }, { name = "fastmcp" }, + { name = "google-genai" }, { name = "jsonpatch" }, + { name = "pyyaml" }, { name = "starlette" }, { name = "uvicorn", extra = ["standard"] }, ] @@ -601,7 +724,9 @@ dev = [ requires-dist = [ { name = "aiofiles" }, { name = "fastmcp" }, + { name = "google-genai", specifier = ">=1.0" }, { name = "jsonpatch" }, + { name = "pyyaml" }, { name = "starlette" }, { name = "uvicorn", extras = ["standard"] }, ] @@ -753,6 +878,27 @@ memory = [ { name = "cachetools" }, ] +[[package]] +name = "pyasn1" +version = "0.6.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/5c/5f/6583902b6f79b399c9c40674ac384fd9cd77805f9e6205075f828ef11fb2/pyasn1-0.6.3.tar.gz", hash = "sha256:697a8ecd6d98891189184ca1fa05d1bb00e2f84b5977c481452050549c8a72cf", size = 148685, upload-time = "2026-03-17T01:06:53.382Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5d/a0/7d793dce3fa811fe047d6ae2431c672364b462850c6235ae306c0efd025f/pyasn1-0.6.3-py3-none-any.whl", hash = "sha256:a80184d120f0864a52a073acc6fc642847d0be408e7c7252f31390c0f4eadcde", size = 83997, upload-time = "2026-03-17T01:06:52.036Z" }, +] + +[[package]] +name = "pyasn1-modules" +version = "0.4.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pyasn1" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/e9/e6/78ebbb10a8c8e4b61a59249394a4a594c1a7af95593dc933a349c8d00964/pyasn1_modules-0.4.2.tar.gz", hash = "sha256:677091de870a80aae844b1ca6134f54652fa2c8c5a52aa396440ac3106e941e6", size = 307892, upload-time = "2025-03-28T02:41:22.17Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/47/8d/d529b5d697919ba8c11ad626e835d4039be708a35b0d22de83a269a6682c/pyasn1_modules-0.4.2-py3-none-any.whl", hash = "sha256:29253a9207ce32b64c3ac6600edc75368f98473906e8fd1043bd6b5b1de2c14a", size = 181259, upload-time = "2025-03-28T02:41:19.028Z" }, +] + [[package]] name = "pycparser" version = "3.0" @@ -1018,6 +1164,21 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" }, ] +[[package]] +name = "requests" +version = "2.33.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "certifi" }, + { name = "charset-normalizer" }, + { name = "idna" }, + { name = "urllib3" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/5f/a4/98b9c7c6428a668bf7e42ebb7c79d576a1c3c1e3ae2d47e674b468388871/requests-2.33.1.tar.gz", hash = "sha256:18817f8c57c6263968bc123d237e3b8b08ac046f5456bd1e307ee8f4250d3517", size = 134120, upload-time = "2026-03-30T16:09:15.531Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d7/8e/7540e8a2036f79a125c1d2ebadf69ed7901608859186c856fa0388ef4197/requests-2.33.1-py3-none-any.whl", hash = "sha256:4e6d1ef462f3626a1f0a0a9c42dd93c63bad33f9f1c1937509b8c5c8718ab56a", size = 64947, upload-time = "2026-03-30T16:09:13.83Z" }, +] + [[package]] name = "rich" version = "14.3.3" @@ -1138,6 +1299,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b7/46/f5af3402b579fd5e11573ce652019a67074317e18c1935cc0b4ba9b35552/secretstorage-3.5.0-py3-none-any.whl", hash = "sha256:0ce65888c0725fcb2c5bc0fdb8e5438eece02c523557ea40ce0703c266248137", size = 15554, upload-time = "2025-11-23T19:02:51.545Z" }, ] +[[package]] +name = "sniffio" +version = "1.3.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/a2/87/a6771e1546d97e7e041b6ae58d80074f81b7d5121207425c964ddf5cfdbd/sniffio-1.3.1.tar.gz", hash = "sha256:f4324edc670a0f49750a81b895f35c3adb843cca46f0530f79fc1babb23789dc", size = 20372, upload-time = "2024-02-25T23:20:04.057Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" }, +] + [[package]] name = "sse-starlette" version = "3.3.3" @@ -1164,6 +1334,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/0b/c9/584bc9651441b4ba60cc4d557d8a547b5aff901af35bda3a4ee30c819b82/starlette-1.0.0-py3-none-any.whl", hash = "sha256:d3ec55e0bb321692d275455ddfd3df75fff145d009685eb40dc91fc66b03d38b", size = 72651, upload-time = "2026-03-22T18:29:45.111Z" }, ] +[[package]] +name = "tenacity" +version = "9.1.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/47/c6/ee486fd809e357697ee8a44d3d69222b344920433d3b6666ccd9b374630c/tenacity-9.1.4.tar.gz", hash = "sha256:adb31d4c263f2bd041081ab33b498309a57c77f9acf2db65aadf0898179cf93a", size = 49413, upload-time = "2026-02-07T10:45:33.841Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d7/c1/eb8f9debc45d3b7918a32ab756658a0904732f75e555402972246b0b8e71/tenacity-9.1.4-py3-none-any.whl", hash = "sha256:6095a360c919085f28c6527de529e76a06ad89b23659fa881ae0649b867a9d55", size = 28926, upload-time = "2026-02-07T10:45:32.24Z" }, +] + [[package]] name = "typing-extensions" version = "4.15.0" @@ -1194,6 +1373,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ff/7f/4320d9ce3be404e6310b915c3629fe27bf1e2f438a1a7a3cb0396e32e9a9/uncalled_for-0.2.0-py3-none-any.whl", hash = "sha256:2c0bd338faff5f930918f79e7eb9ff48290df2cb05fcc0b40a7f334e55d4d85f", size = 11351, upload-time = "2026-02-27T17:40:56.804Z" }, ] +[[package]] +name = "urllib3" +version = "2.6.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" }, +] + [[package]] name = "uvicorn" version = "0.42.0" From 048d1eca1aa16106d269bfc1aa24dd939f340104 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Tue, 14 Apr 2026 15:29:26 +0700 Subject: [PATCH 380/412] feat: add MCP tools for memory curation --- koan/lib/permissions.py | 12 ++ koan/web/mcp_endpoint.py | 271 +++++++++++++++++++++++++++++ tests/memory/test_mcp_memory.py | 297 ++++++++++++++++++++++++++++++++ 3 files changed, 580 insertions(+) create mode 100644 tests/memory/test_mcp_memory.py diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index 1614512..1cc71a5 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -53,6 +53,9 @@ "koan_complete_story", "koan_retry_story", "koan_skip_story", + "koan_memorize", + "koan_forget", + "koan_memory_status", "edit", "write", "bash", @@ -100,6 +103,11 @@ "koan_retry_story", "koan_skip_story", }) +# Memory tools are available to the orchestrator in every phase. +_ORCHESTRATOR_MEMORY_TOOLS: frozenset[str] = frozenset({ + "koan_memorize", "koan_forget", "koan_memory_status", +}) + _ORCHESTRATOR_BASH_PHASES: frozenset[str] = frozenset({ "execution", "implementation-validation", }) @@ -136,6 +144,10 @@ def _check_orchestrator_permission( if tool_name in ("koan_complete_step", "koan_set_phase", "koan_yield"): return {"allowed": True, "reason": None} + # Memory tools -- available to the orchestrator in every phase + if tool_name in _ORCHESTRATOR_MEMORY_TOOLS: + return {"allowed": True, "reason": None} + # koan_ask_question — always allowed except brief-generation step 1 if tool_name == "koan_ask_question": if phase == "brief-generation" and current_step == 1: diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index e7cbcdb..09ae73d 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -46,6 +46,7 @@ from ..lib.permissions import check_permission from ..lib.workflows import get_suggested_phases, is_valid_transition as wf_is_valid from ..logger import get_logger +from ..memory import MEMORY_TYPES, MemoryStore from ..phases import PHASE_GUIDANCE_MAP, PhaseContext, StepGuidance from ..phases.format_step import format_phase_complete, format_steering_messages, format_step, format_user_messages from .interactions import activate_next_interaction, enqueue_interaction @@ -61,6 +62,26 @@ # Module-level app_state reference, set by build_mcp_asgi_app(). _app_state: AppState | None = None +# Lazy-initialized per-process memory store, scoped to app_state.project_dir. +_memory_store: MemoryStore | None = None + + +def _get_memory_store() -> MemoryStore: + """Return a MemoryStore bound to the current project directory.""" + global _memory_store + if _memory_store is None: + assert _app_state is not None + store = MemoryStore(_app_state.project_dir or ".") + store.init() + _memory_store = store + return _memory_store + + +def _reset_memory_store() -> None: + """Test hook: clear the cached MemoryStore.""" + global _memory_store + _memory_store = None + # -- fastmcp server ----------------------------------------------------------- mcp = FastMCP(name="koan") @@ -875,6 +896,256 @@ async def koan_skip_story(story_id: str, reason: str = "") -> str: end_tool_call(agent, call_id, "koan_skip_story", result_str) +# -- Memory tools -------------------------------------------------------------- + +def _validate_memory_type(type_str: str) -> None: + if type_str not in MEMORY_TYPES: + raise ToolError(json.dumps({ + "error": "invalid_type", + "message": ( + f"'{type_str}' is not a valid memory type. " + f"Valid types: {list(MEMORY_TYPES)}" + ), + })) + + +def _entry_id_from_path(path_name: str) -> int | None: + """Extract NNNN prefix from 'NNNN-slug.md'.""" + if len(path_name) < 5 or path_name[4] != "-": + return None + try: + return int(path_name[:4]) + except ValueError: + return None + + +@mcp.tool(name="koan_memorize") +async def koan_memorize( + type: str, + title: str, + body: str, + related: list[str] | None = None, + entry_id: int | None = None, +) -> str: + """Write a memory entry. + + Creates a new entry when entry_id is omitted. Updates an existing + entry when entry_id is provided (the NNNN sequence number from + the entry's filename). + + New entries: assigns the next sequence number, generates a filename + slug, sets created/modified timestamps automatically. + + Updates: reads the existing entry, replaces the provided fields, + updates the modified timestamp. Original filename and created + timestamp are preserved. + + The body should begin with 1-3 sentences situating the entry in + the project -- this opening context improves semantic search + matching. The rest is event-style prose: temporally grounded, + attributed, self-contained. + + Args: + type: Memory type (decision, context, lesson, procedure) + title: Short descriptive name + body: Prose content (100-500 tokens). Begin with 1-3 sentences + of project context for search matching. + related: Filenames of related entries (optional) + entry_id: Sequence number for updates (omit for creates) + """ + agent = _get_agent() + _check_or_raise(agent, "koan_memorize", { + "type": type, "title": title, "entry_id": entry_id, + }) + + call_id = begin_tool_call( + agent, "koan_memorize", + {"type": type, "title": title, "entry_id": entry_id}, + f"{type}: {title}", + ) + result_str: str | None = None + try: + _validate_memory_type(type) + + store = _get_memory_store() + + if entry_id is None: + entry = store.add_entry( + type=type, # type: ignore[arg-type] + title=title, + body=body, + related=related or [], + ) + new_id = _entry_id_from_path(entry.file_path.name) if entry.file_path else None + result_str = json.dumps({ + "op": "created", + "type": type, + "entry_id": new_id, + "file_path": str(entry.file_path) if entry.file_path else None, + "created": entry.created, + "modified": entry.modified, + }) + else: + existing = store.get_entry(entry_id) + if existing is None: + raise ToolError(json.dumps({ + "error": "entry_not_found", + "message": f"No entry with id {entry_id}", + })) + if existing.type != type: + raise ToolError(json.dumps({ + "error": "type_mismatch", + "message": ( + f"Entry {entry_id} has type '{existing.type}', " + f"not '{type}'" + ), + })) + existing.title = title + existing.body = body + if related is not None: + existing.related = related + store.update_entry(existing) + result_str = json.dumps({ + "op": "updated", + "type": type, + "entry_id": entry_id, + "file_path": str(existing.file_path) if existing.file_path else None, + "created": existing.created, + "modified": existing.modified, + }) + + result_str = _drain_and_append_steering(result_str, agent) + return result_str + finally: + end_tool_call(agent, call_id, "koan_memorize", result_str) + + +@mcp.tool(name="koan_forget") +async def koan_forget(entry_id: int, type: str | None = None) -> str: + """Remove a memory entry. + + Deletes the entry file from disk. Git preserves history. + + Args: + entry_id: Sequence number (NNNN prefix from filename) + type: Memory type (optional). When provided, the found entry's + type must match or a type_mismatch error is raised. + """ + agent = _get_agent() + _check_or_raise(agent, "koan_forget", {"type": type, "entry_id": entry_id}) + + call_id = begin_tool_call( + agent, "koan_forget", + {"type": type, "entry_id": entry_id}, + f"{type or '*'}/{entry_id}", + ) + result_str: str | None = None + try: + if type is not None: + _validate_memory_type(type) + + store = _get_memory_store() + existing = store.get_entry(entry_id) + if existing is None: + raise ToolError(json.dumps({ + "error": "entry_not_found", + "message": f"No entry with id {entry_id}", + })) + if type is not None and existing.type != type: + raise ToolError(json.dumps({ + "error": "type_mismatch", + "message": ( + f"Entry {entry_id} has type '{existing.type}', " + f"not '{type}'" + ), + })) + path_str = str(existing.file_path) if existing.file_path else None + store.forget_entry(existing) + result_str = json.dumps({ + "op": "forgotten", + "type": existing.type, + "entry_id": entry_id, + "file_path": path_str, + }) + result_str = _drain_and_append_steering(result_str, agent) + return result_str + finally: + end_tool_call(agent, call_id, "koan_forget", result_str) + + +def _summary_is_stale(store: MemoryStore) -> bool: + """Return True if summary.md is missing or older than any entry file.""" + summary_path = store._memory_dir / "summary.md" + if not summary_path.is_file(): + # Only stale if at least one entry exists; otherwise there is + # nothing to summarize and we do not force a regeneration. + return store.entry_count() > 0 + summary_mtime = summary_path.stat().st_mtime + for e in store.list_entries(): + if e.file_path is None: + continue + if e.file_path.stat().st_mtime > summary_mtime: + return True + return False + + +@mcp.tool(name="koan_memory_status") +async def koan_memory_status(type: str | None = None) -> str: + """Get an orientation view of project memory. + + Returns the project summary and a flat listing of all entries. + Checks whether summary.md is stale (older than the most recent + entry) and regenerates it just-in-time before returning. + + Args: + type: Filter listing to a specific memory type (optional). + The summary is always project-wide regardless of filter. + """ + agent = _get_agent() + _check_or_raise(agent, "koan_memory_status", {"type": type}) + + call_id = begin_tool_call( + agent, "koan_memory_status", {"type": type}, type or "all", + ) + result_str: str | None = None + try: + if type is not None: + _validate_memory_type(type) + + store = _get_memory_store() + + regenerated = False + if _summary_is_stale(store): + await store.regenerate_summary() + regenerated = True + + summary = store.get_summary() or "" + entries = store.list_entries(type=type) # type: ignore[arg-type] + out_entries = [ + { + "entry_id": ( + _entry_id_from_path(e.file_path.name) + if e.file_path else None + ), + "title": e.title, + "type": e.type, + "created": e.created, + "modified": e.modified, + } + for e in entries + ] + + result_str = json.dumps({ + "summary": summary, + "entries": out_entries, + "regenerated": regenerated, + }) + result_str = _drain_and_append_steering(result_str, agent) + return result_str + finally: + end_tool_call(agent, call_id, "koan_memory_status", result_str) + + # -- ASGI wrapper -------------------------------------------------------------- def build_mcp_asgi_app(app_state: AppState): diff --git a/tests/memory/test_mcp_memory.py b/tests/memory/test_mcp_memory.py new file mode 100644 index 0000000..0e32434 --- /dev/null +++ b/tests/memory/test_mcp_memory.py @@ -0,0 +1,297 @@ +# Tests for koan_memorize / koan_forget / koan_memory_status MCP tools. +# +# Exercises the raw handler functions (unwrapped from the FastMCP decorator), +# after wiring up a minimal AgentState + AppState + agent context var. + +from __future__ import annotations + +import json +import time +from unittest.mock import patch + +import pytest +from fastmcp.exceptions import ToolError + +from koan.state import AgentState, AppState +from koan.web import mcp_endpoint + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + +def _unwrap(tool): + """Extract the underlying async function from a FastMCP-decorated tool.""" + for attr in ("fn", "func", "_fn", "_func", "__wrapped__", "callback"): + candidate = getattr(tool, attr, None) + if callable(candidate): + return candidate + if callable(tool): + return tool + raise RuntimeError(f"Cannot unwrap FastMCP tool: {tool!r}") + + +memorize = _unwrap(mcp_endpoint.koan_memorize) +forget = _unwrap(mcp_endpoint.koan_forget) +memory_status = _unwrap(mcp_endpoint.koan_memory_status) + + +@pytest.fixture +def mem_env(tmp_path, monkeypatch): + """Set up a minimal MCP environment with a tmp project directory. + + Returns a dict with the agent, app_state, and project_dir. + """ + app_state = AppState() + app_state.project_dir = str(tmp_path) + app_state.phase = "curation" + + agent = AgentState( + agent_id="test-agent-0001", + role="orchestrator", + subagent_dir=str(tmp_path / "sub"), + ) + agent.run_dir = str(tmp_path) + agent.step = 1 + app_state.agents[agent.agent_id] = agent + + # Wire module state + agent context var + monkeypatch.setattr(mcp_endpoint, "_app_state", app_state) + monkeypatch.setattr(mcp_endpoint, "_memory_store", None) + token = mcp_endpoint._agent_ctx.set(agent) + + yield { + "agent": agent, + "app_state": app_state, + "project_dir": tmp_path, + } + + mcp_endpoint._agent_ctx.reset(token) + mcp_endpoint._reset_memory_store() + + +# --------------------------------------------------------------------------- +# koan_memorize +# --------------------------------------------------------------------------- + +class TestMemorize: + @pytest.mark.anyio + async def test_create_writes_to_flat_directory(self, mem_env): + result_str = await memorize( + type="decision", + title="Use PostgreSQL", + body="Documents the DB choice. Chose PostgreSQL 16.2 over SQLite.", + ) + result = json.loads(result_str) + assert result["op"] == "created" + assert result["type"] == "decision" + assert result["entry_id"] == 1 + assert result["created"] != "" + assert result["modified"] != "" + # File should exist in the flat .koan/memory/ directory + project_dir = mem_env["project_dir"] + target = project_dir / ".koan" / "memory" / "0001-use-postgresql.md" + assert target.exists() + + @pytest.mark.anyio + async def test_global_sequence_across_types(self, mem_env): + r1 = json.loads(await memorize(type="decision", title="D1", body="Body.")) + r2 = json.loads(await memorize(type="lesson", title="L1", body="Body.")) + r3 = json.loads(await memorize(type="context", title="C1", body="Body.")) + assert r1["entry_id"] == 1 + assert r2["entry_id"] == 2 + assert r3["entry_id"] == 3 + project_dir = mem_env["project_dir"] + mem = project_dir / ".koan" / "memory" + assert (mem / "0001-d1.md").exists() + assert (mem / "0002-l1.md").exists() + assert (mem / "0003-c1.md").exists() + + @pytest.mark.anyio + async def test_update_preserves_created(self, mem_env): + create_result = json.loads(await memorize( + type="decision", + title="First", + body="Body of first entry documenting a decision.", + )) + original_created = create_result["created"] + + update_result = json.loads(await memorize( + type="decision", + title="First Updated", + body="Body of first entry documenting a decision, now revised.", + entry_id=1, + )) + assert update_result["op"] == "updated" + assert update_result["entry_id"] == 1 + assert update_result["created"] == original_created + + @pytest.mark.anyio + async def test_invalid_type_raises(self, mem_env): + with pytest.raises(ToolError) as exc: + await memorize(type="opinion", title="X", body="Body.") + body = json.loads(str(exc.value)) + assert body["error"] == "invalid_type" + + @pytest.mark.anyio + async def test_update_nonexistent_raises(self, mem_env): + with pytest.raises(ToolError) as exc: + await memorize( + type="decision", + title="Nope", + body="Body.", + entry_id=999, + ) + body = json.loads(str(exc.value)) + assert body["error"] == "entry_not_found" + + @pytest.mark.anyio + async def test_update_type_mismatch_raises(self, mem_env): + await memorize(type="decision", title="D1", body="Body.") + with pytest.raises(ToolError) as exc: + await memorize( + type="lesson", + title="Wrong type", + body="Body.", + entry_id=1, + ) + body = json.loads(str(exc.value)) + assert body["error"] == "type_mismatch" + + +# --------------------------------------------------------------------------- +# koan_forget +# --------------------------------------------------------------------------- + +class TestForget: + @pytest.mark.anyio + async def test_deletes_entry_by_id_without_type(self, mem_env): + await memorize(type="decision", title="D1", body="Body.") + + result = json.loads(await forget(entry_id=1)) + assert result["op"] == "forgotten" + assert result["entry_id"] == 1 + assert result["type"] == "decision" + + project_dir = mem_env["project_dir"] + target = project_dir / ".koan" / "memory" / "0001-d1.md" + assert not target.exists() + + @pytest.mark.anyio + async def test_deletes_with_matching_type(self, mem_env): + await memorize(type="decision", title="D1", body="Body.") + result = json.loads(await forget(entry_id=1, type="decision")) + assert result["op"] == "forgotten" + assert result["entry_id"] == 1 + + @pytest.mark.anyio + async def test_type_mismatch_raises(self, mem_env): + await memorize(type="decision", title="D1", body="Body.") + with pytest.raises(ToolError) as exc: + await forget(entry_id=1, type="lesson") + body = json.loads(str(exc.value)) + assert body["error"] == "type_mismatch" + + @pytest.mark.anyio + async def test_nonexistent_raises(self, mem_env): + with pytest.raises(ToolError) as exc: + await forget(entry_id=42) + body = json.loads(str(exc.value)) + assert body["error"] == "entry_not_found" + + @pytest.mark.anyio + async def test_invalid_type_raises(self, mem_env): + with pytest.raises(ToolError) as exc: + await forget(entry_id=1, type="wrong") + body = json.loads(str(exc.value)) + assert body["error"] == "invalid_type" + + +# --------------------------------------------------------------------------- +# koan_memory_status +# --------------------------------------------------------------------------- + +class TestMemoryStatus: + @pytest.mark.anyio + async def test_returns_summary_and_flat_entries(self, mem_env): + await memorize(type="decision", title="D1", body="Body of decision one.") + await memorize(type="lesson", title="L1", body="Body of lesson one.") + + async def fake_generate(prompt, system="", max_tokens=1024): + return "mocked summary body" + + with patch("koan.memory.summarize.generate", side_effect=fake_generate): + raw = await memory_status() + result = json.loads(raw) + + assert "summary" in result + assert "entries" in result + assert "regenerated" in result + assert "types" not in result # old shape must be gone + assert result["regenerated"] is True + + titles = [e["title"] for e in result["entries"]] + types = [e["type"] for e in result["entries"]] + assert titles == ["D1", "L1"] + assert types == ["decision", "lesson"] + # Each entry exposes id + timestamps + assert result["entries"][0]["entry_id"] == 1 + assert result["entries"][0]["created"] != "" + assert result["entries"][0]["modified"] != "" + + @pytest.mark.anyio + async def test_type_filter(self, mem_env): + await memorize(type="decision", title="D1", body="Decision body.") + await memorize(type="lesson", title="L1", body="Lesson body.") + + async def fake_generate(prompt, system="", max_tokens=1024): + return "mocked" + + with patch("koan.memory.summarize.generate", side_effect=fake_generate): + raw = await memory_status(type="decision") + result = json.loads(raw) + titles = [e["title"] for e in result["entries"]] + assert titles == ["D1"] + # Summary is project-wide regardless of filter + assert "summary" in result + + @pytest.mark.anyio + async def test_staleness_detection(self, mem_env): + async def fake_generate(prompt, system="", max_tokens=1024): + return "mocked" + + # First call: no entries, no summary -> not stale, not regenerated + with patch("koan.memory.summarize.generate", side_effect=fake_generate): + first = json.loads(await memory_status()) + assert first["regenerated"] is False + assert first["entries"] == [] + + # Add an entry -> stale -> regenerate + await memorize(type="decision", title="D1", body="First.") + with patch("koan.memory.summarize.generate", side_effect=fake_generate): + second = json.loads(await memory_status()) + assert second["regenerated"] is True + + # Third call without changes -> summary is fresh -> no regeneration + with patch("koan.memory.summarize.generate", side_effect=fake_generate): + third = json.loads(await memory_status()) + assert third["regenerated"] is False + + # Give filesystem mtime a chance to advance past the summary mtime + time.sleep(0.02) + + # Add another entry -> stale -> regenerate + await memorize(type="decision", title="D2", body="Second.") + with patch("koan.memory.summarize.generate", side_effect=fake_generate): + fourth = json.loads(await memory_status()) + assert fourth["regenerated"] is True + + @pytest.mark.anyio + async def test_empty_memory_no_regeneration(self, mem_env): + # Empty memory should return an empty entries list without calling + # the LLM, so no patch is needed. + raw = await memory_status() + result = json.loads(raw) + assert result["entries"] == [] + assert result["regenerated"] is False + assert result["summary"] == "" From 41178de3b554e9fb70c82b83163a41657093d3c2 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Tue, 14 Apr 2026 15:29:47 +0700 Subject: [PATCH 381/412] feat: add standalone curation workflow and phase --- .../src/components/organisms/NewRunForm.tsx | 12 +- koan/lib/permissions.py | 4 + koan/lib/workflows.py | 144 +++++- koan/phases/__init__.py | 2 + koan/phases/curation.py | 419 ++++++++++++++++++ koan/types.py | 2 + tests/phases/__init__.py | 0 tests/phases/test_curation.py | 234 ++++++++++ tests/test_workflows.py | 38 ++ 9 files changed, 851 insertions(+), 4 deletions(-) create mode 100644 koan/phases/curation.py create mode 100644 tests/phases/__init__.py create mode 100644 tests/phases/test_curation.py diff --git a/frontend/src/components/organisms/NewRunForm.tsx b/frontend/src/components/organisms/NewRunForm.tsx index df8f487..fb7d1dd 100644 --- a/frontend/src/components/organisms/NewRunForm.tsx +++ b/frontend/src/components/organisms/NewRunForm.tsx @@ -21,7 +21,7 @@ export function NewRunForm() { const [loading, setLoading] = useState(false) const [error, setError] = useState<string | null>(null) const [selectedInstallations, setSelectedInstallations] = useState<Record<string, string>>({}) - const [workflow, setWorkflow] = useState<'plan' | 'milestones'>('plan') + const [workflow, setWorkflow] = useState<'plan' | 'milestones' | 'curation'>('plan') const [projectDir, setProjectDir] = useState('') const profilesDict = useStore(s => s.settings.profiles) @@ -121,6 +121,16 @@ export function NewRunForm() { <span className="nrf-wf-desc">Break work into milestones with phased delivery</span> </span> </button> + <button className={`nrf-wf-option${workflow === 'curation' ? ' nrf-wf-option--selected' : ''}`} + onClick={() => setWorkflow('curation')}> + <span className={`nrf-wf-radio${workflow === 'curation' ? ' nrf-wf-radio--selected' : ''}`}> + {workflow === 'curation' && <span className="nrf-wf-radio-inner" />} + </span> + <span className="nrf-wf-info"> + <span className="nrf-wf-name">Memory</span> + <span className="nrf-wf-desc">Review, bootstrap, or maintain project knowledge</span> + </span> + </button> </div> </div> diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index 1cc71a5..007eea1 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -96,6 +96,10 @@ "intake", "core-flows", "tech-plan", "ticket-breakdown", "cross-artifact-validation", "plan-spec", "plan-review", # plan workflow phases + # Curation: standalone directive may need scouts to gather source + # material from the codebase. Postmortem directive forbids them + # in prose. + "curation", }) _ORCHESTRATOR_STORY_TOOLS: frozenset[str] = frozenset({ diff --git a/koan/lib/workflows.py b/koan/lib/workflows.py index 3662d98..5d5bba9 100644 --- a/koan/lib/workflows.py +++ b/koan/lib/workflows.py @@ -47,26 +47,144 @@ class Workflow: phase_guidance: dict[str, str] +# -- Curation directives (injected as phase_instructions) --------------------- +# +# Directives bind the static curation step prompts to a specific entry +# point. They own *what to look for* and *which source-gathering moves +# are authorized*. They must NOT own step mechanics (which belong to +# koan/phases/curation.py) or writing discipline (which belongs to the +# curation system prompt). + +_POSTMORTEM_DIRECTIVE = ( + "## Source: postmortem\n" + "\n" + "The source for this curation is your conversation history with the\n" + "user during the workflow that just completed. The transcript IS the\n" + "task. Ignore the <task> block in step 1 -- it carries the parent\n" + "workflow's task description, which is not your curation source.\n" + "\n" + "## What to harvest\n" + "\n" + "- Decisions made during the workflow, with rationale and rejected\n" + " alternatives.\n" + "- Lessons from mistakes, corrections, or surprises.\n" + "- Procedures that emerged from patterns the user reinforced.\n" + "- Context facts about the project that surfaced during dialogue.\n" + "\n" + "## How to walk the transcript\n" + "\n" + "1. Step back. Identify 2-4 themes from this run -- the major\n" + " decisions, the surprises, the corrections, the reusable patterns.\n" + "2. For each theme, walk the relevant turns and harvest candidates.\n" + " Most impactful first.\n" + "\n" + "## Forbidden moves\n" + "\n" + "- Do NOT call `koan_request_scouts`. The source is bounded by what\n" + " you already discussed in this run.\n" + "- Do NOT read codebase files for new context. Anything you did not\n" + " already touch in the workflow is out of scope.\n" + "- Do NOT call `koan_ask_question`. If clarification is needed,\n" + " surface it inside a batch yield instead.\n" + "\n" + "## What this phase produces\n" + "\n" + "Your output for this phase is `koan_memorize` calls (and `koan_forget`\n" + "where DEPRECATE applies), not analysis. Step 1 is preparation; step 2\n" + "is where the writes happen. A curation phase that ends with zero\n" + "writes -- when the transcript clearly contains harvestable knowledge --\n" + "is a failed phase." +) + +_STANDALONE_DIRECTIVE = ( + "## Source: standalone curation\n" + "\n" + "Your source is determined by the user's task in the <task> block\n" + "above combined with the current state of memory in <existing_memory>.\n" + "Unlike the postmortem entry point, you do NOT have a recent workflow\n" + "transcript to draw from -- context must be gathered.\n" + "\n" + "## Mode pivot (do this in step 1, before gathering)\n" + "\n" + "Decide which mode you are in by walking these four moves:\n" + "\n" + "- **Describe** Paraphrase the user's <task> in one sentence.\n" + "- **Explain** Look at <existing_memory>: empty, sparse, or\n" + " populated? Does the task reference specific source\n" + " material (a doc path, a subsystem name, a file)?\n" + "- **Plan** Pick exactly one mode:\n" + " - **Review** Memory is populated and the task\n" + " is health/maintenance (\"audit my\n" + " memory\", \"check for stale\n" + " entries\", \"find duplicates\").\n" + " - **Document** The task points at specific\n" + " source material -- a doc, a spec,\n" + " a subsystem, a path. Ingest it.\n" + " - **Bootstrap** Memory is empty or near-empty and\n" + " the task is open-ended (\"set up\n" + " memory for this project\").\n" + "- **Select** Commit to the mode. Name it in your end-of-step-1\n" + " orientation summary so the user can correct you\n" + " before you start gathering.\n" + "\n" + "## Source-gathering posture by mode\n" + "\n" + "- **Review**: Read suspect entries directly from `.koan/memory/`.\n" + " Dispatch 1-2 scouts via `koan_request_scouts` to\n" + " verify high-stakes decisions against the current\n" + " codebase. Use `koan_ask_question` only for\n" + " ambiguities the files cannot resolve.\n" + "\n" + "- **Document**: Read the source the user pointed at directly. If\n" + " it spans multiple subsystems, dispatch 2-4 scouts\n" + " in parallel to cover each one. Treat the document\n" + " as authoritative for facts; treat the codebase as\n" + " authoritative for current state.\n" + "\n" + "- **Bootstrap**: Lean heavily on scouts -- 3-5 to cover the major\n" + " subsystems. Read README, AGENTS.md, and CLAUDE.md\n" + " directly if they exist. Interview the user via\n" + " `koan_ask_question` for context the codebase\n" + " cannot reveal: team size, deployment, conventions,\n" + " historical decisions.\n" + "\n" + "In every mode you may always read individual memory entries\n" + "directly from `.koan/memory/NNNN-*.md` -- direct reads are the\n" + "intended duplicate-detection path. Writes still go through\n" + "`koan_memorize` / `koan_forget` only.\n" + "\n" + "## What this phase produces\n" + "\n" + "Your output for this phase is `koan_memorize` calls (and `koan_forget`\n" + "where DEPRECATE applies), not analysis. Step 1 is preparation; step 2\n" + "is where the writes happen. A curation phase that ends with zero\n" + "writes -- when there is genuine novel knowledge to capture -- is a\n" + "failed phase." +) + + # -- Plan workflow ------------------------------------------------------------- -# intake → plan-spec → plan-review → execute +# intake → plan-spec → plan-review → execute → curation # Lightweight focused-change pipeline. Single executor spawn. PLAN_WORKFLOW = Workflow( name="plan", description="Plan an implementation approach, review it, then execute", - available_phases=("intake", "plan-spec", "plan-review", "execute"), + available_phases=("intake", "plan-spec", "plan-review", "execute", "curation"), initial_phase="intake", suggested_transitions={ "intake": ["plan-spec", "execute"], "plan-spec": ["plan-review", "execute"], "plan-review": ["plan-spec", "execute"], - "execute": ["plan-review"], + "execute": ["curation", "plan-review"], + "curation": [], }, phase_descriptions={ "intake": "Explore the codebase and align on requirements through Q&A", "plan-spec": "Write a technical implementation plan grounded in the codebase", "plan-review": "Evaluate the plan for completeness, correctness, and risks", "execute": "Hand off the plan to an executor agent for implementation", + "curation": "Capture lessons, decisions, and context from the completed run", }, phase_guidance={ "intake": ( @@ -111,6 +229,7 @@ class Workflow: "Report the result. If the executor failed or asked questions, relay\n" "the situation to the user and suggest next steps." ), + "curation": _POSTMORTEM_DIRECTIVE, }, ) @@ -160,11 +279,30 @@ class Workflow: ) +# -- Curation workflow -------------------------------------------------------- +# Standalone memory maintenance workflow (review directive). + +CURATION_WORKFLOW = Workflow( + name="curation", + description="Maintain the project memory: review, bootstrap, or ingest documents", + available_phases=("curation",), + initial_phase="curation", + suggested_transitions={"curation": []}, + phase_descriptions={ + "curation": "Review and maintain the project's memory entries", + }, + phase_guidance={ + "curation": _STANDALONE_DIRECTIVE, + }, +) + + # -- Registry ----------------------------------------------------------------- WORKFLOWS: dict[str, Workflow] = { "plan": PLAN_WORKFLOW, "milestones": MILESTONES_WORKFLOW, + "curation": CURATION_WORKFLOW, } diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index e2bd7dc..f57b9cf 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -91,6 +91,7 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> brief_writer, core_flows, cross_artifact_validation, + curation, executor, intake, orchestrator, @@ -117,6 +118,7 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> # General-purpose phases (reusable by any workflow) "intake": intake, "execute": execute_phase, + "curation": curation, # Plan workflow phases (SCOPE="plan") "plan-spec": plan_spec, "plan-review": plan_review, diff --git a/koan/phases/curation.py b/koan/phases/curation.py new file mode 100644 index 0000000..4ebd1d1 --- /dev/null +++ b/koan/phases/curation.py @@ -0,0 +1,419 @@ +# Curation phase -- 2-step workflow. +# +# The curation phase has one job: write project memory. It is invoked from +# two entry points, distinguished only by the directive injected via +# ctx.phase_instructions: +# +# - postmortem: source = the orchestrator's transcript (no scouts, no +# codebase reads, no questions). +# - standalone: source = the user's <task> + existing memory + the +# codebase. May dispatch scouts and ask questions per directive. +# +# The static prompts below are directive-agnostic. They reference "your +# directive" without hardcoding the entry point. Variation lives in the +# directive layer (koan/lib/workflows.py). +# +# Step layout (collapsed from 3 -> 2 because the orchestrator was skipping +# the meaty step entirely; named after their primary tool effect to make +# tool-call elision impossible): +# +# 1 (Inventory) -- koan_memory_status + gather source + classify candidates +# 2 (Memorize) -- yield -> koan_memorize / koan_forget loop, then verify +# +# The screenshots from the previous run showed the orchestrator confusing +# "Survey" with intake-style exploration and reaching "phase complete" +# without ever calling koan_memorize. The fix: give every step a +# <workflow_shape> / <goal> / <tools_this_step> header that names the +# orchestrator's position, the phase-level success criterion, and the +# specific tools to call this step. Re-read at every step so the structure +# is visible at the moment of use. + +from __future__ import annotations + +from . import PhaseContext, StepGuidance + +ROLE = "orchestrator" +SCOPE = "general" +TOTAL_STEPS = 2 + +STEP_NAMES: dict[int, str] = { + 1: "Inventory", + 2: "Memorize", +} + + +# -- System prompt ------------------------------------------------------------- +# Injected at the top of step 1. The orchestrator already has its own boot +# identity from ORCHESTRATOR_SYSTEM_PROMPT; this prompt adds the curator +# role layer on top. It does not redeclare the orchestrator identity. + +SYSTEM_PROMPT = ( + "You are now operating as the project's knowledge curator. Your job is\n" + "to maintain a small, high-quality memory of decisions, context, lessons,\n" + "and procedures that helps AI coding agents work effectively across\n" + "workflow runs.\n" + "\n" + "## Structural invariant\n" + "\n" + "You propose, the user approves, then you write. Every memory mutation\n" + "(create, update, delete) must be presented to the user via `koan_yield`\n" + "and explicitly approved before you call a write tool. There are no\n" + "silent writes.\n" + "\n" + "## Tools\n" + "\n" + "Three MCP tools handle koan memory operations:\n" + "\n" + "- `koan_memory_status` -- orientation. Returns the project summary and\n" + " a flat listing of all entries (id, title, type, dates). Triggers\n" + " just-in-time regeneration of summary.md if entries changed since the\n" + " last summary. Call this first in step 1 and again at the end of\n" + " step 2 to verify your writes.\n" + "- `koan_memorize` -- create or update an entry. Omit `entry_id` to\n" + " create; pass it to update. Sets `created` / `modified` timestamps\n" + " automatically and assigns the next sequence number for new entries.\n" + "- `koan_forget` -- delete an entry by `entry_id`. Git preserves the\n" + " history of removed entries.\n" + "\n" + "## Reads vs. writes -- the asymmetry\n" + "\n" + "Reading and writing memory follow different rules. Both are sanctioned;\n" + "they just use different paths.\n" + "\n" + "**Reading individual entries: native filesystem.**\n" + "Memory entries are plain markdown at `.koan/memory/NNNN-*.md`. Read\n" + "them directly with your standard file-reading tools whenever you need\n" + "to compare a candidate against an existing entry, check for overlap,\n" + "or verify a fact before classifying. This is the intended\n" + "duplicate-detection path -- the listing from `koan_memory_status`\n" + "gives you titles only, so direct reads are how you check bodies.\n" + "\n" + "**Reading the summary or the listing: koan_memory_status.**\n" + "The project summary and the entry listing come from\n" + "`koan_memory_status`, not from parsing files. The tool may regenerate\n" + "summary.md under your feet; do not cache or parse it directly.\n" + "\n" + "**Writes: koan_memorize / koan_forget ONLY.**\n" + "Do NOT write or delete files under `.koan/` directly. The write tools\n" + "manage sequence-number assignment, timestamps, summary staleness\n" + "tracking, and (in the upcoming review-gate feature) human approval.\n" + "Bypassing them desyncs your view of memory from koan's index.\n" + "\n" + "## The coding agent's own memory (separate system)\n" + "\n" + "The coding agent running this orchestration (Claude Code, Cursor,\n" + "Codex, etc.) may have its own memory at paths like CLAUDE.md,\n" + "AGENTS.md, `.claude/projects/*/memory/`, `.cursor/`, etc. Treat these\n" + "as a SEPARATE system from koan memory:\n" + "\n" + "- They are READ-ONLY input. Consult them during step 1 inventory as\n" + " one source of project context, alongside the directive and task.\n" + " They often contain useful prior knowledge.\n" + "- You do NOT write to them. They belong to the coding agent.\n" + "- They are NOT koan memory. The only koan memory is what\n" + " `koan_memory_status` returns and what lives at `.koan/memory/`.\n" + "\n" + "When a fact appears in both the coding agent's memory and koan\n" + "memory, trust the koan version -- it went through curation review.\n" + "\n" + "## Memory types\n" + "\n" + "- **decision** -- architectural choices with rationale and rejected\n" + " alternatives. Why is the project the way it is?\n" + "- **context** -- project facts not derivable from code: team,\n" + " infrastructure, external services, business rules.\n" + "- **lesson** -- things that went wrong and the root cause. Not\n" + " symptoms.\n" + "- **procedure** -- behavioral rules for agents. Checkable conditions\n" + " and concrete actions. Often paired with a lesson.\n" + "\n" + "## Classification schema\n" + "\n" + "Before drafting any candidate, classify it against existing memory:\n" + "\n" + "- **ADD** -- no existing entry covers this. Draft a new entry.\n" + "- **UPDATE** -- an existing entry covers this but needs revision.\n" + " Draft the revision; pass `entry_id` to `koan_memorize`.\n" + "- **NOOP** -- already adequately captured. Skip.\n" + "- **DEPRECATE** -- this knowledge makes an existing entry obsolete.\n" + " Propose removal via `koan_forget`. (The action label\n" + " is DEPRECATE; the tool is `koan_forget` -- they\n" + " refer to the same operation.)\n" + "\n" + "## Writing discipline\n" + "\n" + "Every entry body is 100-500 tokens of event-style prose:\n" + "\n" + "- **Open with context.** The first 1-3 sentences situate the entry in\n" + " the project. They get embedded for semantic search; vague openings\n" + " hurt retrieval.\n" + "- **Temporally ground every claim.** Use absolute dates (\"On 2026-04-10,\n" + " user decided...\") so the entry stays true regardless of when it is\n" + " read.\n" + "- **Attribute the source.** \"User stated\", \"LLM inferred\", \"Post-mortem\n" + " identified\". User-stated facts carry higher trust than inferences.\n" + "- **Name things concretely.** \"PostgreSQL 16.2\", not \"the database\".\n" + "- **Stand alone.** Each entry must be interpretable without reading\n" + " any other entry.\n" + "- **No forward-looking language.** Not \"we will\" but \"On <date>, user\n" + " stated the plan was to...\".\n" + "\n" + "Use the `related` field (filenames like `0002-infrastructure.md`) to\n" + "link a lesson to its derived procedure, or a decision to its\n" + "motivating context.\n" + "\n" + "## What not to capture\n" + "\n" + "- Anything derivable from reading the code.\n" + "- Temporary implementation details that will not matter next week.\n" + "- Opinions without grounding in project experience.\n" + "- Anything already adequately captured (use NOOP, not a duplicate).\n" +) + + +# -- Step header (rendered at the top of every step) -------------------------- +# Re2-inspired structural repetition: every step shows the orchestrator its +# position, the phase-level goal, and the specific tools to call this step. +# This kills the "wait, are we in intake?" confusion seen in the screenshots. + +def _workflow_shape_block(current_step: int) -> list[str]: + you_are_here_1 = "(<-- YOU ARE HERE)" if current_step == 1 else "" + you_are_here_2 = "(<-- YOU ARE HERE)" if current_step == 2 else "" + return [ + "<workflow_shape>", + "The curation workflow has exactly ONE phase: curation.", + "That phase has 2 steps:", + f" step 1 -- Inventory (identify candidates) {you_are_here_1}", + f" step 2 -- Memorize (write entries via koan_memorize) {you_are_here_2}", + "When step 2 completes, the workflow is done. There is no further phase.", + "Do NOT read koan source code to figure this out -- this block is the", + "authoritative answer.", + "</workflow_shape>", + ] + + +def _goal_block() -> list[str]: + return [ + "<goal>", + "By the end of step 2 you will have called `koan_memorize` (and", + "possibly `koan_forget`) one or more times to write user-approved", + "memory entries. That is the only success criterion for this phase.", + "Step 1 is preparation; step 2 is where the writes happen.", + "</goal>", + ] + + +def _tools_this_step_block(current_step: int) -> list[str]: + if current_step == 1: + return [ + "<tools_this_step>", + "1. `koan_memory_status` -- call FIRST. Loads the existing memory view.", + "2. Direct file reads of `.koan/memory/NNNN-*.md` -- compare candidates", + " against existing entries when classifying.", + "3. Source-gathering tools authorized by your directive (scouts, doc", + " reads, `koan_ask_question`, walking your conversation history).", + "4. `koan_complete_step` -- LAST, after you have a candidate list.", + "</tools_this_step>", + ] + if current_step == 2: + return [ + "<tools_this_step>", + "1. `koan_yield` -- present each batch of proposals to the user.", + "2. `koan_memorize` -- write approved ADD / UPDATE entries.", + "3. `koan_forget` -- delete approved DEPRECATE entries.", + "4. `koan_memory_status` -- call ONCE at the end to verify your writes.", + "5. `koan_complete_step` -- LAST, after the anticipatory check passes.", + "</tools_this_step>", + ] + return [] + + +def _header(current_step: int) -> list[str]: + return ( + _workflow_shape_block(current_step) + + [""] + + _goal_block() + + [""] + + _tools_this_step_block(current_step) + + [""] + ) + + +# -- Step 1: Inventory --------------------------------------------------------- + +def _step_1_inventory(ctx: PhaseContext) -> StepGuidance: + directive = ctx.phase_instructions or ( + "No directive provided. Default to the standalone posture: read the\n" + "<task> block, check existing memory, and infer the mode." + ) + + # The <task> block is only meaningful when there is a user task. In the + # postmortem path the task_description is whatever the parent workflow + # was about, not a curation directive -- the postmortem directive tells + # the orchestrator to ignore it and use the transcript instead. + task_block = ( + ctx.task_description.strip() + if ctx.task_description and ctx.task_description.strip() + else "(no user task -- see your directive for where the source lives)" + ) + + instructions = _header(1) + [ + "## Step 1: Inventory", + "", + "Identify the candidates that step 2 will write. By the end of this", + "step you will have a numbered candidate list ready for the memorize", + "loop. Nothing is written in this step.", + "", + "## Input blocks", + "", + "<directive>", + directive, + "</directive>", + "", + "<task>", + task_block, + "</task>", + "", + "## Procedure", + "", + "1. Call `koan_memory_status` FIRST. This is your only sanctioned", + " view of the project summary and entry listing. Read both.", + "", + "2. Read your <directive>. It tells you where the source material", + " lives (transcript / docs / scouts / interview) and what", + " source-gathering moves you are authorized to make.", + "", + "3. If <task> is non-empty, read it. The directive will tell you", + " whether to use it as your primary anchor or to ignore it.", + "", + "4. Gather source material per the directive's posture. Examples:", + " - postmortem -> walk your conversation history above", + " - review -> read suspect entries directly from", + " `.koan/memory/`, dispatch scouts to verify", + " - document -> read the doc the user pointed at, dispatch", + " scouts for broad sources", + " - bootstrap -> dispatch scouts, read README/AGENTS.md/CLAUDE.md,", + " interview the user via `koan_ask_question`", + "", + "5. Consult the coding agent's own memory if it exists", + " (CLAUDE.md, AGENTS.md, `.claude/projects/*/memory/`, etc.).", + " It is useful prior knowledge about the project. It is NOT", + " koan memory -- treat it as read-only input only.", + "", + "6. Build a numbered candidate list. For each candidate note:", + " - type (decision / context / lesson / procedure)", + " - title (one line)", + " - classification (ADD / UPDATE / NOOP / DEPRECATE)", + " - entry_id (only for UPDATE / DEPRECATE)", + " When a candidate is close to an existing topic, read the suspect", + " entries directly from `.koan/memory/` before classifying.", + "", + "## End-of-step output", + "", + "A numbered candidate list. This becomes the input to step 2's", + "memorize loop.", + "", + "Do NOT call `koan_complete_step` until you have at least one", + "candidate with classification ADD, UPDATE, or DEPRECATE.", + "Exception: if the source genuinely contains no novel knowledge,", + "state that explicitly (\"all candidates were NOOPs because X\") and", + "then complete the step.", + ] + return StepGuidance(title=STEP_NAMES[1], instructions=instructions) + + +# -- Step 2: Memorize ---------------------------------------------------------- + +def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: + instructions = _header(2) + [ + "## Step 2: Memorize", + "", + "This is the writing step. Your candidate list from step 1 becomes", + "`koan_memorize` and `koan_forget` calls, gated by user approval", + "via `koan_yield`. The classification schema, writing discipline,", + "and tool semantics live in your role context above -- do not", + "redefine them here.", + "", + "## The loop", + "", + "Repeat for each batch of 3-5 candidates from your step 1 list:", + "", + "1. **Draft** proposals for the batch. Each proposal includes", + " `type`, `title`, `body`, `related`, plus `entry_id` for UPDATE", + " and DEPRECATE.", + "", + "2. **Yield** the batch to the user. Call `koan_yield` with the", + " proposals as markdown plus these structured suggestions:", + ' - {id: "approve", label: "Approve all", command: "Approve all entries in this batch"}', + ' - {id: "skip", label: "Skip all", command: "Skip this batch"}', + ' - {id: "review", label: "Review individually", command: "Let me review each entry"}', + "", + "3. **Apply** approved changes:", + " - ADD -> `koan_memorize` (no `entry_id`)", + " - UPDATE -> `koan_memorize` (with `entry_id`)", + " - DEPRECATE -> `koan_forget` (with `entry_id`)", + " - NOOP -> nothing", + "", + "4. **Cross items off** your candidate list. Loop back to step 1", + " of this loop until the list is empty or the user tells you", + " to stop.", + "", + "## Anticipatory check (BEFORE the wrap-up)", + "", + "Stop and verify:", + "", + "- Did you call `koan_memorize` at least once for the ADD / UPDATE", + " items on your step 1 candidate list?", + "- Did you call `koan_forget` for any DEPRECATE items?", + "", + "If NO and your step 1 list was non-empty: you have not done the", + "work of this phase. Loop back to draft proposals and call", + "`koan_yield`. Do not advance to the wrap-up with zero writes.", + "", + "If your step 1 list was explicitly empty (\"all candidates were", + "NOOPs because X\"), zero writes is correct -- continue to wrap-up.", + "", + "## Wrap-up", + "", + "1. Call `koan_memory_status` once. This triggers just-in-time", + " summary regeneration if any entries changed.", + "", + "2. Report the final counts to the user inline:", + " `{added: N, updated: N, deprecated: N, noop: N}`", + " plus a one-line note on anything deferred for a future run.", + "", + "3. Call `koan_complete_step`. The curation phase ends here and", + " the workflow is complete.", + ] + return StepGuidance(title=STEP_NAMES[2], instructions=instructions) + + +# -- Step dispatch ------------------------------------------------------------- + +_STEPS = { + 1: _step_1_inventory, + 2: _step_2_memorize, +} + + +def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: + fn = _STEPS.get(step) + if fn is None: + return StepGuidance(title=f"Step {step}", instructions=[f"Execute step {step}."]) + return fn(ctx) + + +# -- Lifecycle ----------------------------------------------------------------- + +def get_next_step(step: int, ctx: PhaseContext) -> int | None: + if step < TOTAL_STEPS: + return step + 1 + return None + + +def validate_step_completion(step: int, ctx: PhaseContext) -> str | None: + return None + + +async def on_loop_back(from_step: int, to_step: int, ctx: PhaseContext) -> None: + pass diff --git a/koan/types.py b/koan/types.py index 42c1089..d19c3d7 100644 --- a/koan/types.py +++ b/koan/types.py @@ -19,6 +19,8 @@ "plan-spec", "plan-review", "execute", + # Curation (memory maintenance) -- reusable across workflows + "curation", ] SubagentRole = Literal[ diff --git a/tests/phases/__init__.py b/tests/phases/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/phases/test_curation.py b/tests/phases/test_curation.py new file mode 100644 index 0000000..5be279d --- /dev/null +++ b/tests/phases/test_curation.py @@ -0,0 +1,234 @@ +# Tests for the curation phase module. + +from __future__ import annotations + +from koan.phases import PhaseContext, curation + + +def _ctx(**kw) -> PhaseContext: + defaults = {"run_dir": "/tmp/run", "subagent_dir": "/tmp/sub"} + defaults.update(kw) + return PhaseContext(**defaults) + + +class TestModuleShape: + def test_total_steps_is_2(self): + assert curation.TOTAL_STEPS == 2 + + def test_role_is_orchestrator(self): + assert curation.ROLE == "orchestrator" + + def test_scope_is_general(self): + assert curation.SCOPE == "general" + + def test_step_names(self): + assert curation.STEP_NAMES == {1: "Inventory", 2: "Memorize"} + + def test_system_prompt_is_nonempty(self): + assert isinstance(curation.SYSTEM_PROMPT, str) + assert len(curation.SYSTEM_PROMPT) > 100 + + def test_system_prompt_writing_discipline(self): + # The writing-discipline pillars must be present. + sp = curation.SYSTEM_PROMPT.lower() + for term in ("temporally", "attribut", "stand alone", "concretely"): + assert term in sp, f"missing {term!r} in SYSTEM_PROMPT" + + def test_system_prompt_enumerates_memory_tools(self): + # Tools must be visible at the role layer. + sp = curation.SYSTEM_PROMPT + assert "koan_memorize" in sp + assert "koan_forget" in sp + assert "koan_memory_status" in sp + + def test_system_prompt_declares_classification_schema(self): + sp = curation.SYSTEM_PROMPT + for label in ("ADD", "UPDATE", "NOOP", "DEPRECATE"): + assert label in sp, f"schema label {label!r} missing from SYSTEM_PROMPT" + + def test_system_prompt_declares_structural_invariant(self): + # Propose-then-write must be stated, not buried. + sp = curation.SYSTEM_PROMPT.lower() + assert "propose" in sp and "approve" in sp + + def test_system_prompt_declares_read_write_asymmetry(self): + # Reads of .koan/memory/*.md are allowed; writes are not. + sp = curation.SYSTEM_PROMPT + # Reads explicitly allowed and explained: + assert "Reading individual entries" in sp + assert ".koan/memory/" in sp + # Writes explicitly forbidden: + assert "Do NOT write or delete files under `.koan/`" in sp + + def test_system_prompt_acknowledges_coding_agent_memory(self): + # CLAUDE.md / AGENTS.md / .cursor/ etc. are a separate, read-only system. + sp = curation.SYSTEM_PROMPT + assert "coding agent" in sp.lower() + assert "CLAUDE.md" in sp + assert "READ-ONLY" in sp + + +class TestLifecycle: + def test_get_next_step_linear(self): + ctx = _ctx() + assert curation.get_next_step(1, ctx) == 2 + + def test_get_next_step_terminal(self): + assert curation.get_next_step(2, _ctx()) is None + + def test_validate_all_none(self): + ctx = _ctx() + for s in (1, 2): + assert curation.validate_step_completion(s, ctx) is None + + +class TestStepHeaders: + """Every step must render workflow_shape, goal, and tools_this_step blocks + with a YOU-ARE-HERE marker pointing at the current step.""" + + def test_step_1_renders_workflow_shape(self): + g = curation.step_guidance(1, _ctx()) + text = "\n".join(g.instructions) + assert "<workflow_shape>" in text + assert "</workflow_shape>" in text + # Position marker on step 1. + # Format: `... step 1 -- Inventory ... (<-- YOU ARE HERE)` on the step-1 line. + for line in text.splitlines(): + if "step 1 -- Inventory" in line: + assert "YOU ARE HERE" in line, f"step-1 line missing marker: {line!r}" + break + else: + raise AssertionError("step-1 line not found in workflow_shape block") + for line in text.splitlines(): + if "step 2 -- Memorize" in line: + assert "YOU ARE HERE" not in line, f"step-2 line wrongly marked: {line!r}" + + def test_step_2_renders_workflow_shape(self): + g = curation.step_guidance(2, _ctx()) + text = "\n".join(g.instructions) + assert "<workflow_shape>" in text + for line in text.splitlines(): + if "step 2 -- Memorize" in line: + assert "YOU ARE HERE" in line, f"step-2 line missing marker: {line!r}" + break + else: + raise AssertionError("step-2 line not found in workflow_shape block") + + def test_both_steps_render_goal_block(self): + for step in (1, 2): + text = "\n".join(curation.step_guidance(step, _ctx()).instructions) + assert "<goal>" in text and "</goal>" in text + assert "koan_memorize" in text # the goal names the central tool + + def test_step_1_tools_block_calls_memory_status_first(self): + text = "\n".join(curation.step_guidance(1, _ctx()).instructions) + assert "<tools_this_step>" in text + assert "koan_memory_status" in text + # FIRST is the load-bearing word. + assert "FIRST" in text + + def test_step_2_tools_block_lists_write_tools(self): + text = "\n".join(curation.step_guidance(2, _ctx()).instructions) + assert "<tools_this_step>" in text + assert "koan_yield" in text + assert "koan_memorize" in text + assert "koan_forget" in text + + +class TestStep1Inventory: + def test_title_is_inventory(self): + g = curation.step_guidance(1, _ctx()) + assert g.title == "Inventory" + + def test_renders_directive_block(self): + ctx = _ctx(phase_instructions="## Source: postmortem\n\nWork from transcript.") + g = curation.step_guidance(1, ctx) + text = "\n".join(g.instructions) + assert "<directive>" in text + assert "</directive>" in text + assert "postmortem" in text + assert "transcript" in text + + def test_renders_task_block_when_present(self): + ctx = _ctx(task_description="audit my memory entries for staleness") + g = curation.step_guidance(1, ctx) + text = "\n".join(g.instructions) + assert "<task>" in text + assert "</task>" in text + assert "audit my memory entries for staleness" in text + + def test_renders_task_block_placeholder_when_absent(self): + g = curation.step_guidance(1, _ctx()) + text = "\n".join(g.instructions) + assert "<task>" in text + assert "no user task" in text.lower() + + def test_default_directive_when_missing(self): + g = curation.step_guidance(1, _ctx()) + text = "\n".join(g.instructions) + assert "No directive provided" in text + + def test_calls_out_memory_status(self): + g = curation.step_guidance(1, _ctx()) + text = "\n".join(g.instructions) + assert "koan_memory_status" in text + + def test_acknowledges_coding_agent_memory_as_read_only(self): + text = "\n".join(curation.step_guidance(1, _ctx()).instructions) + assert "CLAUDE.md" in text or "coding agent" in text.lower() + + def test_produces_candidate_list_contract(self): + text = "\n".join(curation.step_guidance(1, _ctx()).instructions) + assert "candidate list" in text.lower() + + +class TestStep2Memorize: + def test_title_is_memorize(self): + g = curation.step_guidance(2, _ctx()) + assert g.title == "Memorize" + + def test_contains_loop_vocabulary(self): + text = "\n".join(curation.step_guidance(2, _ctx()).instructions).lower() + assert "draft" in text + assert "yield" in text + assert "apply" in text + assert "batch" in text + + def test_contains_classification_labels(self): + text = "\n".join(curation.step_guidance(2, _ctx()).instructions) + for label in ("ADD", "UPDATE", "NOOP", "DEPRECATE"): + assert label in text + + def test_references_memory_tools(self): + text = "\n".join(curation.step_guidance(2, _ctx()).instructions) + assert "koan_memorize" in text + assert "koan_forget" in text + assert "koan_yield" in text + + def test_does_not_redefine_writing_discipline(self): + # Writing discipline lives in the system prompt; step 2 should not + # duplicate it. Sentinel: "1-3 sentences" is system-prompt-only. + text = "\n".join(curation.step_guidance(2, _ctx()).instructions) + assert "1-3 sentences" not in text + + def test_includes_anticipatory_check(self): + # The anticipatory check is the central new defense against the + # "phase ended with zero writes" failure. + text = "\n".join(curation.step_guidance(2, _ctx()).instructions) + assert "Anticipatory check" in text + assert "did you call" in text.lower() or "did you call `koan_memorize`" in text.lower() or "Did you call" in text + + def test_wrap_up_calls_memory_status(self): + # Wrap-up (folded in from former step 3) calls koan_memory_status + # for summary regeneration. + text = "\n".join(curation.step_guidance(2, _ctx()).instructions) + assert "Wrap-up" in text + # koan_memory_status appears multiple times; just ensure it's there. + assert "koan_memory_status" in text + + def test_reports_counts_in_schema_terms(self): + text = "\n".join(curation.step_guidance(2, _ctx()).instructions).lower() + assert "added" in text + assert "updated" in text + assert "deprecated" in text + assert "noop" in text diff --git a/tests/test_workflows.py b/tests/test_workflows.py index 7e60fca..86a0fd4 100644 --- a/tests/test_workflows.py +++ b/tests/test_workflows.py @@ -3,6 +3,7 @@ import pytest from koan.lib.workflows import ( + CURATION_WORKFLOW, MILESTONES_WORKFLOW, PLAN_WORKFLOW, WORKFLOWS, @@ -60,6 +61,11 @@ def test_get_suggested_phases_execute(): assert "plan-review" in phases +def test_get_suggested_phases_execute_includes_curation(): + phases = get_suggested_phases(PLAN_WORKFLOW, "execute") + assert "curation" in phases + + def test_get_suggested_phases_milestones_intake_empty(): phases = get_suggested_phases(MILESTONES_WORKFLOW, "intake") assert phases == [] @@ -107,6 +113,7 @@ def test_plan_workflow_structure(): assert "plan-spec" in wf.available_phases assert "plan-review" in wf.available_phases assert "execute" in wf.available_phases + assert "curation" in wf.available_phases assert wf.initial_phase == "intake" @@ -141,6 +148,37 @@ def test_milestones_workflow_has_intake_guidance(): assert len(MILESTONES_WORKFLOW.phase_guidance["intake"]) > 0 +# -- CURATION_WORKFLOW structure ----------------------------------------------- + +def test_curation_workflow_exists(): + assert "curation" in WORKFLOWS + + +def test_curation_workflow_structure(): + wf = CURATION_WORKFLOW + assert wf.name == "curation" + assert wf.initial_phase == "curation" + assert "curation" in wf.available_phases + + +def test_curation_workflow_has_standalone_directive(): + guidance = CURATION_WORKFLOW.phase_guidance.get("curation", "") + # Standalone directive defines the review/document/bootstrap pivot. + assert "standalone curation" in guidance + assert "Review" in guidance + assert "Document" in guidance + assert "Bootstrap" in guidance + + +def test_plan_workflow_curation_uses_postmortem_directive(): + guidance = PLAN_WORKFLOW.phase_guidance.get("curation", "") + # Postmortem directive binds source to the in-context transcript and + # forbids scout dispatch. + assert "postmortem" in guidance + assert "transcript" in guidance + assert "koan_request_scouts" in guidance + + # -- Workflow immutability ----------------------------------------------------- def test_workflow_frozen(): From 30deec7784e3d478f784783bbad8195311f5f00a Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Tue, 14 Apr 2026 15:29:53 +0700 Subject: [PATCH 382/412] docs: update memory system specification to v4 --- docs/memory-system.md | 846 +++++++++++++++++++++++------------------- 1 file changed, 461 insertions(+), 385 deletions(-) diff --git a/docs/memory-system.md b/docs/memory-system.md index 57ee7af..b4e0e88 100644 --- a/docs/memory-system.md +++ b/docs/memory-system.md @@ -1,4 +1,4 @@ -# Koan Memory System — Specification v3 +# Koan Memory System — Specification v4 ## Overview @@ -19,85 +19,93 @@ carrying structured metadata and a prose body written in event-style. This design makes each entry independently retrievable, independently reviewable, and independently trackable via version control. +### What this is not + +This is not conversational memory. Systems like Mem0, SimpleMem, +Hindsight, and A-Mem extract and consolidate facts from dialogue +streams. Their benchmarks (LoCoMo, LongMemEval) test recall of +conversational facts across sessions. + +Koan's memory is fundamentally different: + +- **Deliberate, not extracted.** Entries are proposed by the + orchestrator agent and approved by the human user during a + curation workflow. Every entry is human-reviewed before it enters + memory. + +- **Structured, not atomic.** Each entry is 100–500 tokens of + self-contained prose — an architectural decision with rationale + and alternatives, not an atomic fact like "user prefers coffee." + The grain size is justified by EMem's neo-Davidsonian argument: + relational knowledge must stay bundled (Zhou et al., 2025). + +- **The producer and consumer are LLMs.** The primary reader of + memory entries is the intake agent at the start of the next + workflow. The human oversees (reviews proposals, approves entries) + but does not browse or query memory directly. Design decisions + optimize for LLM consumption, not human browsability. + +- **Write-infrequent, read-frequent.** Memory is written during + curation (end of workflow or on-demand review). It is read at + the start of every workflow. The read path matters more than + the write path. + --- ## Entry format -Each memory entry is a standalone markdown file consisting of three -parts: YAML frontmatter, a contextual introduction, and a prose body. +Each memory entry is a standalone markdown file consisting of two +parts: YAML frontmatter and a prose body. ### YAML frontmatter -Structured metadata that enables programmatic operations — staleness -detection, status filtering, cross-referencing, and retrieval -filtering. +Structured metadata that enables filtering and freshness tracking. ```yaml --- title: PostgreSQL for Auth Service type: decision -date: 2026-04-10 -source: user-stated -status: active -tags: [auth, postgresql, data-storage] -supersedes: null -related: [context/0002-infrastructure.md] +created: 2026-04-10T14:23:00Z +modified: 2026-04-10T14:23:00Z +related: [0002-infrastructure.md] --- ``` Required fields: -- **title**: Short descriptive name, used in listings and summaries -- **type**: One of `decision`, `context`, `lesson`, `procedure`, - `milestone` -- **date**: The date the fact became true or was observed (ISO 8601) -- **source**: How the memory was captured — `user-stated`, - `llm-inferred`, or `post-mortem` -- **status**: `active`, `review-needed`, `deprecated`, or `archived` +- **title**: Short descriptive name, used in listings and the project + summary +- **type**: One of `decision`, `context`, `lesson`, `procedure` +- **created**: ISO 8601 timestamp, set automatically when the entry + is first written. Never modified after creation. +- **modified**: ISO 8601 timestamp, updated automatically on every + write. Enables freshness tracking and staleness detection. Optional fields: -- **tags**: Free-form labels for retrieval filtering -- **supersedes**: Path to the entry this one replaces (if any) -- **related**: Paths to related entries +- **related**: Filenames of related entries (e.g., + `0002-infrastructure.md`). Explicit structural connections — a + lesson linking to its derived procedure, a decision linking to the + context that motivated it. These serve as signals for curation + health checks. + +A file's presence is its status. If a file exists in `.koan/memory/`, +it is active knowledge. The `koan_forget` tool deletes the file. +Git preserves the history of anything removed. -### Contextual introduction +### Prose body -A 1–3 sentence paragraph immediately following the frontmatter that -situates the entry within the project. This introduction is written -at capture time and becomes a permanent part of the file. It is not -generated at retrieval or embedding time. +Everything after the frontmatter is the prose body, written in +event-style following the writing discipline described below. +**The first 1–3 sentences must situate the entry in the project.** This follows Anthropic's contextual retrieval technique, which demonstrated a 35% reduction in retrieval failures when contextual -information is prepended to chunks before embedding. The critical -design choice: the contextual introduction is written once and stored -in the file, rather than generated dynamically at embedding time. - -Rationale for baking it into the file: - -1. **Consistency.** The embedding and the file content are always in - sync. There is no discrepancy between what the retrieval layer - indexed and what the file contains. - -2. **Determinism.** It is possible to check whether an embedding has - already been computed for a file by comparing content hashes. - Dynamic contextual generation would produce slightly different - wordings each time, making hash-based change detection unreliable. - -3. **Transparency.** A human reading the file sees exactly what the - retrieval system sees. Nothing is hidden in an intermediate layer. - -The tradeoff is denormalization. If the project is renamed or a -major structural fact changes, all contextual introductions that -reference it become stale and must be updated. This is acceptable — -such changes are rare, and the memory review workflow can surface -and batch-update affected entries. - -### Prose body - -The main content, written in event-style following the writing -discipline described below. +information is prepended to chunks before embedding. Because the +entire file is embedded as a single chunk for retrieval, these +opening sentences become part of the embedding and improve search +matching. They are not a separate field — they are the natural +opening of the prose, written as part of the body. ### Complete example @@ -105,17 +113,13 @@ discipline described below. --- title: PostgreSQL for Auth Service type: decision -date: 2026-04-10 -source: user-stated -status: active -tags: [auth, postgresql, data-storage] -supersedes: null -related: [context/0002-infrastructure.md] +created: 2026-04-10T14:23:00Z +modified: 2026-04-10T14:23:00Z +related: [0002-infrastructure.md] --- -This entry is a decision record from the TrapperKeeper project, -a distributed data firewall. It documents the choice of primary -data store for the authentication service. +This entry documents the choice of primary data store for the +authentication service in TrapperKeeper, a distributed data firewall. On 2026-04-10, user decided to migrate the auth service from SQLite to PostgreSQL 16.2. Rationale: SQLite could not handle concurrent @@ -141,10 +145,13 @@ arguments outperforms decomposing them into relation triples. ### Rules 1. **Every statement includes a date.** The date the fact became true - or was observed. If unknown, use the recording date. + or was observed. Temporal grounding makes every entry a historical + fact that remains true regardless of when it is read. 2. **Attribute claims to their source.** "User stated...", "LLM - inferred...", "Post-mortem identified...". + inferred...", "Post-mortem identified...". Source attribution lives + in the prose, not in metadata fields. User-stated facts carry + higher trust than LLM-inferred facts. 3. **No forward-looking language.** Not "we will" but "On [date], user stated the plan was to...". @@ -155,10 +162,6 @@ arguments outperforms decomposing them into relation triples. 5. **Each entry must stand alone.** Interpretable without any other file, true regardless of when it is read. -Source attribution embedded in the prose serves as the primary trust -signal. User-stated facts carry higher trust than LLM-inferred facts. -No external metadata database is needed for trust assessment. - ### Examples Bad — relative, will become stale: @@ -174,9 +177,9 @@ Good — temporally grounded, always true as a historical fact: ## Memory types -Koan organizes memories into five document types, each corresponding -to a distinct retrieval intent — a kind of question an agent needs -answered. +Koan classifies memories into four types. The type field is metadata +for filtering and curation heuristics — it does not determine where +the file is stored. All entries live in a single flat directory. ### Decisions — *Why is the project the way it is?* @@ -190,8 +193,8 @@ considered and rejected, and how the decision surfaced (intake, mid-workflow correction, post-mortem). Decisions include both explicit choices (user-stated) and implicit -choices (LLM-inferred from user behavior). Implicit decisions are -marked as such via the `source` field. +choices (LLM-inferred from user behavior). Implicit decisions +should be clearly attributed as inferred in the prose body. ### Context — *What do I need to know that isn't in the code?* @@ -200,11 +203,6 @@ that are not derivable from the codebase and are expected to remain stable across sessions. Team size, deployment setup, external dependencies, business constraints. -Context entries are split into project-scoped (in `.koan/memory/ -context/`) and user-scoped (in `.koan/user/context/`). User context -includes background, experience level, coding preferences, and style. -It applies across all projects. - ### Lessons — *What went wrong before?* Mistakes made during workflows and the corrections applied. Each @@ -229,29 +227,6 @@ Procedures emerge from three sources: lessons that generalize into prevention rules, positive patterns observed after successful workflows, and the memory review workflow surfacing recurring themes. -### Milestones — *What work has been done?* - -A running record of completed workflows. Milestones capture *that* -something was done, not the full detail of how. Their primary purpose -is enabling project summary generation and providing future intake -phases a quick history. - -### Project summary (derived) - -A synthesized overview regenerated after each workflow completes. -Unlike memory entries, the summary is produced by reading the other -memory files and synthesizing them into a concise briefing. It lives -at `.koan/memory/summary.md` and does not have the standard entry -format (no sequential number, no contextual introduction). - -The summary is the first thing an LLM reads when starting any -workflow. It is loaded in full at intake (not retrieved via search) -as long as it fits within a budget of ~2000 tokens. This follows the -coarsening–traversal (C–T) coupling principle from "Toward a Theory -of Hierarchical Memory for Language Agents" (ICLR 2026): -self-sufficient representatives can be loaded in full (collapsed -search), but only while they fit the token budget. - --- ## File organization @@ -259,119 +234,71 @@ search), but only while they fit the token budget. ``` .koan/ memory/ - summary.md # tier 1: root summary (whole project) - decisions/ - _index.md # tier 2: condensed summary of all decisions - 0001-postgresql-for-auth.md # tier 3: individual entries - 0002-no-unit-tests.md - 0003-redis-session-management.md - context/ - _index.md - 0001-team-structure.md - 0002-infrastructure.md - 0003-auth0-integration.md - lessons/ - _index.md - 0001-unit-test-generation.md - procedures/ - _index.md - 0001-testing-policy-check.md - 0002-database-migration-steps.md - milestones/ - _index.md - 0042-user-authentication.md - 0048-background-jobs.md - - user/ # user-global (shared across projects) - context/ - _index.md - 0001-background.md - 0002-coding-preferences.md - lessons/ - _index.md - 0001-credential-hardcoding.md - procedures/ - _index.md - 0001-migration-decomposition.md -``` - -### Three-tier summary hierarchy - -The memory system maintains summaries at three levels, following the -RAPTOR recursive abstractive retrieval pattern (Sarthi et al., ICLR -2024). Each level provides a self-sufficient representation that can -answer queries at its resolution without drilling deeper. - -**Tier 1: Root summary** (`summary.md`). A project-wide overview -covering architecture, policies, recent work, and known pitfalls. -Always loaded in full at intake. Budget: ~2000 tokens. - -**Tier 2: Type-level indexes** (`decisions/_index.md`, etc.). Each -type folder contains an `_index.md` that condenses all active entries -in that folder into a single prose summary. An agent needing a broad -view of "all decisions" or "all procedures" can load the relevant -`_index.md` without retrieving individual entries. Budget: ~500 -tokens each. - -**Tier 3: Individual entries** (`0001-postgresql-for-auth.md`). The -full knowledge entries, retrieved via hybrid search when the agent -needs specific detail that the summaries don't provide. - -The root `summary.md` is regenerated from the type-level `_index.md` -files rather than reading every individual entry directly. This is -RAPTOR's recursive summarization: summarize the leaves, then -summarize the summaries. - -Type-level `_index.md` files are generated artifacts, like -`summary.md`. They carry a simple frontmatter block: - -```yaml ---- -type: index -covers: [0001, 0002, 0003] -token_count: 420 -last_generated: 2026-04-15 ---- + summary.md # project orientation briefing + 0001-postgresql-for-auth.md # individual entries + 0002-infrastructure.md + 0003-no-unit-tests.md + 0004-redis-session-management.md + 0005-unit-test-generation-lesson.md + 0006-testing-policy-check.md + 0007-database-migration-steps.md + 0008-team-structure.md + 0009-auth0-integration.md ``` -Example `decisions/_index.md`: +All entries live in a single flat directory. The type of each entry +is recorded in its YAML frontmatter, not in the directory structure. +This keeps topically related entries together on disk — the decision +about PostgreSQL, the infrastructure context it relates to, and the +lesson about PostgreSQL migrations are all neighbors in the directory, +not scattered across subdirectories. + +Every hierarchical memory system in the literature groups entries by +**semantic/topical similarity**, not by cognitive type (Talebirad et +al., ICLR 2026; Hu et al., 2026; Sun & Zeng, 2025). Type-based +partitioning separates related knowledge that agents need together. +Koan follows this principle: the flat store is the topic-neutral +starting point, and if the knowledge base grows to the point where +flat retrieval degrades, the scaling path is topic-based clustering +(not type-based subdirectories). + +### Project summary + +`summary.md` is a synthesized project orientation briefing, +regenerated after each workflow completes. Unlike memory entries, it +is a derived artifact — produced by reading all entries and +synthesizing them into a concise overview. It does not have the +standard entry format (no sequential number, no frontmatter). -```markdown ---- -type: index -covers: [0001, 0002, 0003] -token_count: 380 -last_generated: 2026-04-15 ---- +The summary is the first thing an LLM reads when starting any +workflow. It is loaded in full at intake (not retrieved via search) +and should stay within ~2000 tokens. -TrapperKeeper's active architectural decisions cover three areas. -Data storage uses PostgreSQL 16.2 for the auth service, chosen over -SQLite (concurrency limits) and CockroachDB (operational complexity) -as of 2026-04-10. Testing policy prohibits unit tests in favor of -integration tests only, established 2026-04-08. Session management -uses Redis 7.x with stateful sessions for compliance requirements, -decided 2026-04-12. -``` +The summary is regenerated by reading all entries directly. At the +current scale (tens to low hundreds of entries), this fits within a +single LLM call. When the knowledge base grows to the point where +all entries no longer fit in a cheap model's context window, that +threshold is the signal to introduce topic-based clustering — +grouping entries by semantic similarity and generating per-topic +summaries. Until then, the flat structure with a single summary is +the simpler and sufficient design. ### Naming convention Files are named `NNNN-short-description.md` where `NNNN` is a -zero-padded sequential number within the type folder. The number -provides stable ordering and prevents filename collisions. The -description is a human-readable slug derived from the title. +zero-padded sequential number. The number provides stable ordering +and prevents filename collisions. The description is a human-readable +slug derived from the title. -New entries are assigned the next available number in their type -folder. Numbers are never reused — if entry `0005` is deleted, the -next entry is still `0006`. +New entries are assigned the next available number. Numbers are never +reused — if entry `0005` is deleted, the next entry is still the +next number after the current highest. ### Version control The `.koan/memory/` directory is checked into version control -alongside the project's source code. This means memory changes -appear in diffs, can be reviewed in pull requests, and have full -git history. The `.koan/user/` directory is stored outside the -project repository (e.g., in `~/.koan/user/`) since it applies -across all projects. +alongside the project's source code. Memory changes appear in diffs, +can be reviewed in pull requests, and have full git history. --- @@ -384,85 +311,114 @@ user review. ### The curation workflow -Curation is a unified workflow that reads source material, reflects -on it in the context of existing memory, proposes changes, and -presents them to the user for review. It follows the same pattern -regardless of what triggered it: - -1. **Read source material.** The source varies by invocation: a - workflow transcript, the existing memory corpus, codebase files, - user-provided documents, or a combination. - -2. **Read existing memory.** Load all `_index.md` files for - orientation, plus individual entries relevant to the source - material (via retrieval or full scan). - -3. **Reflect.** The curation agent evaluates the source against - existing memory. Depending on the directive, it may: - - Identify new knowledge to capture - - Find existing entries that need updating - - Detect stale, contradictory, or duplicate entries - - Surface gaps in coverage - - Evaluate lessons for procedure generation - - Assess whether the type-level organization still fits - -4. **Conduct Q&A with the user** (when the directive calls for it). - Ask clarifying questions to fill gaps, verify assumptions, or - resolve ambiguities. - -5. **Propose changes.** Each proposed change is a complete entry - (for creates) or a diff (for updates), organized by operation: - - **Create**: New entry with full frontmatter, contextual - introduction, and prose body - - **Update**: Modified content for an existing entry - - **Merge**: Two or more entries combined into one - - **Deprecate**: Status change to `deprecated` - - **Promote / demote**: Move between project-local and user-global - - **Archive**: Remove from active retrieval - -6. **User reviews each proposed change.** The user approves, edits, - or rejects each change individually. The agent does not modify - memory without explicit user approval. - -7. **Write approved changes to disk.** New entries get the next - available sequence number in their type folder. - -8. **Regenerate summaries.** Type-level `_index.md` files are - regenerated for each type folder that had changes. The root - `summary.md` is regenerated from the updated `_index.md` files. - -9. **Re-index.** The sync layer detects changed files and updates - the retrieval index. +Curation is an iterative workflow that processes source material +in batches, classifying each candidate against existing memory +before proposing changes. This write-time classification follows +the pattern established by Mem0's memory management algorithm: +every candidate knowledge item is classified (ADD, UPDATE, NOOP, +DEPRECATE) before being committed, preventing duplicate and +redundant entries. + +The curation workflow has three steps: + +**Step 1: Orient.** Quick orientation in existing memory and source +material. Read the project summary to understand what's already +captured. Survey the scope of the source material based on the +directive. Do not produce proposals yet. + +**Step 2: Curate.** The main iterative loop. Process knowledge in +batches of 3–5 candidates. For each batch: + +1. Identify 3–5 candidate knowledge items from the source +2. Classify each candidate against existing memory: + - **ADD**: No existing entry covers this → draft a new entry + - **UPDATE**: An existing entry covers this but needs revision + → draft an update to the existing entry + - **NOOP**: An existing entry already captures this → skip + - **DEPRECATE**: This knowledge makes an existing entry obsolete + → propose deprecation +3. Draft complete entry proposals for ADD and UPDATE candidates +4. Present the batch to the user for review +5. Apply approved changes (via `koan_memorize` and `koan_forget`) +6. Reassess: is there more to extract? After the obvious, look for + implications, connections, conventions, edge cases. Continue + the loop with a new batch if so. + +The loop converges when successive batches produce mostly NOOPs, +the source material is exhausted, or the user says to stop. + +**Step 3: Finalize.** Report what was done. Summary regeneration +happens automatically — the next call to `koan_memory_status` will +detect a stale summary and regenerate it just-in-time. + +### Duplicate detection during curation + +During the curate step, the orchestrator must check whether a +candidate duplicates or overlaps with an existing entry. Without a +retrieval index available during early milestones, the orchestrator +relies on two mechanisms: + +1. **Summary orientation.** The project summary provides a compressed + view of all captured knowledge. If a candidate covers something + already mentioned in the summary, the orchestrator can classify + it as NOOP or UPDATE rather than ADD. + +2. **Direct file reading.** The orchestrator has native filesystem + access and can read any entry in `.koan/memory/`. When a + candidate is close to an existing topic, the orchestrator reads + the potentially overlapping entries and compares before + classifying. + +Once the retrieval index is available (Milestone 3+), the curation +step can use `koan_search` to find related entries before +classifying, making duplicate detection more reliable. + +### MCP tools for memory operations + +The orchestrator interacts with memory through three MCP tools. +Individual entry reading uses the orchestrator's native filesystem +access (the entries are plain markdown). + +**`koan_memorize`** — Write a memory entry. When called without an +entry identifier, creates a new entry with automatic sequence +numbering, filename slug generation, and timestamps. When called +with an entry identifier, updates the existing entry in-place. The +`created` timestamp is set once on creation; `modified` is updated +on every write. Returns the file path and operation performed. + +**`koan_forget`** — Remove an entry from active memory. Deletes the +file from disk. Git preserves the history of removed entries. The +entry disappears from the summary and retrieval immediately. + +**`koan_memory_status`** — Orientation tool. Returns the project +summary and a listing of all entries (title, sequence number, type, +created/modified dates). Before returning, checks whether the +summary is stale (by comparing the summary's generation timestamp +against the most recent entry modification) and regenerates it +just-in-time using a cheap-tier model. ### Curation directives The same workflow serves all memory operations through different directives: -**Post-mortem curation** runs at the end of every koan workflow. -Source: the workflow transcript (user messages, agent outputs, -interventions, escalations). Directive: reflect on what went well, -what went wrong, what decisions were made (explicitly or implicitly), -what patterns emerged. Capture decisions, lessons, procedures, -context facts, and a milestone record. - -**Review curation** is triggered on-demand, on a schedule, or at -project initialization. Source: the existing memory corpus (and -optionally the codebase). Directive: assess memory health — identify -stale entries, contradictions, gaps, entries that should be merged, -lessons lacking procedures, deprecated entries to archive. Conduct -Q&A with the user to fill gaps and verify facts. - -**Bootstrap curation** runs when koan is first set up for a project. -Source: the codebase, any existing documentation, and user interview. -Directive: capture baseline project context, team structure, -conventions, constraints, and architectural decisions already in -effect. - -**Document curation** ingests specific source material the user -provides. Source: architecture docs, specs, design documents, or -any other material. Directive: extract relevant knowledge and -organize it into memory entries. +**Post-mortem** runs at the end of every koan workflow. Source: the +workflow transcript already in the orchestrator's context window. +Focus: decisions made, lessons learned, procedures established, +context surfaced. No scouts — everything is already known. + +**Review** is triggered on-demand. Source: the existing memory +corpus. Focus: assess health — staleness, contradictions, gaps, +entries that should be merged, lessons lacking procedures. May +dispatch scouts to verify decisions against the current codebase. +If memory is empty, pivots to bootstrap (explore codebase, +interview user). If the user's task description references source +material, pivots to document ingestion. + +**Document** ingests specific source material the user provides. +Source: architecture docs, specs, codebase files. May dispatch +scouts for large sources. Bootstrap is document curation at broad +scope — there is no separate bootstrap directive. ### Triggering curation @@ -470,41 +426,32 @@ Curation is triggered: - **Automatically** at the end of every koan workflow (post-mortem directive). -- **On explicit user request** (review, bootstrap, or document - directive). +- **On explicit user request** (review or document directive). - **On suggestion** after N completed workflows, koan suggests a review curation. Configurable, e.g. every 5 workflows. -- **At project initialization** (bootstrap directive). ### Model tier assignments -Curation uses **strong-tier models** for reflection and proposal -generation. This is where judgment matters — what to capture, how -to phrase it, whether existing entries need updating. +Curation runs within the **orchestrator's context** (strong-tier +model). The orchestrator handles all judgment — what to capture, +how to phrase it, whether existing entries need updating. No +separate curation subagent is spawned. -Mechanical retrieval at intake uses **no LLM** for the search -itself. Hybrid vector + BM25 search, cross-encoder reranking, and -metadata filtering are all mechanical operations. +Summary regeneration (inside `koan_memory_status`) uses a +**cheap-tier model**. This is a mechanical operation — condensing +existing entries into a prose overview. The `koan_reflect` tool uses a **cheap-tier model** for query -generation (decomposing a broad question into multiple search -angles) and synthesis (combining retrieved entries into a coherent -briefing). This does not require the strong model — it is -summarizing existing knowledge, not making new decisions. - -Query rewriting for low-confidence retrievals can also use a -**cheap-tier model** to reformulate queries before retrying. +generation and synthesis. ### Direct human editing Because memory files are plain markdown in version control, humans can edit them directly at any time — in their editor, via a pull request, or through any other workflow. The sync layer detects -changes and re-indexes modified files. - -When humans edit files directly, they should maintain the entry -format (frontmatter + contextual introduction + prose body) and -update the `date` field if the content changes substantively. +changes and re-indexes modified files. The `modified` timestamp +in frontmatter should be updated when humans edit entries; the +next `koan_memory_status` call will detect the stale summary. --- @@ -562,55 +509,105 @@ unit." For koan's content type, that is 100–500 tokens per entry. ### Indexing -The sync layer watches `.koan/memory/` and indexes each file as a -single chunk. Because entries are written to be self-contained and -are typically 100–500 tokens, most entries can be embedded whole -without further chunking. +The sync layer watches `.koan/memory/` and indexes each individual +entry file as a single chunk. Because entries are written to be +self-contained and are typically 100–500 tokens, most entries can +be embedded whole without further chunking. For each entry, the sync layer: -1. Reads the file content (frontmatter + contextual introduction + - prose body) +1. Reads the file content (frontmatter + prose body) 2. Parses the YAML frontmatter into structured metadata 3. Computes a content hash for change detection -4. Generates a dense embedding of the full text (including the - contextual introduction) +4. Generates a dense embedding of the full text 5. Indexes the text for BM25 keyword search 6. Stores the embedding, BM25 index entry, and metadata -The `_index.md` summary files and `summary.md` are also indexed -alongside individual entries. Because these summaries are -self-sufficient (following the RAPTOR/C–T coupling principle), they -participate in collapsed search — a broad query may match a -type-level summary directly, while a specific query matches an -individual entry. - -Re-indexing is triggered when a file's content hash changes. Because -the contextual introduction is baked into the file, the hash -reliably indicates whether re-embedding is needed. - -### Two retrieval paths - -Koan provides two distinct retrieval mechanisms: **mechanical context -injection** (automatic, at the start of every intake) and -**agent-invoked tools** (on-demand, during reasoning). +`summary.md` is NOT indexed. It is loaded mechanically at intake +and accessed directly by tools — it does not need search to find. + +Re-indexing is triggered when a file's content hash changes. + +### Two retrieval mechanisms + +Koan provides two retrieval mechanisms that solve fundamentally +different problems: **mechanical context injection** (automatic, +at phase boundaries) and **agent-invoked tools** (on-demand, +during reasoning). The distinction is not about pipeline +mechanics — both use the same hybrid search infrastructure. The +distinction is about what each mechanism can catch. + +The "Memory in the Age of AI Agents" survey (2026) identifies +the core risk of relying on agent-initiated retrieval: "When an +agent overestimates its internal knowledge and fails to initiate +retrieval when needed, the system can fall into a silent failure +mode in which knowledge gaps may lead to hallucinated outputs." +This failure mode defines the boundary between the two mechanisms. + +**Agent-invoked tools handle known unknowns.** The agent is +reasoning, recognizes a gap in its knowledge, and formulates a +targeted query. "What's the session management architecture?" +or "What constraints apply to database migrations?" The agent +is aware of its own gap and goes looking. This works when the +agent has enough context to know *what* it doesn't know. + +**Mechanical injection handles unknown unknowns.** The agent +doesn't know that a testing policy exists. It doesn't know that +a previous executor hardcoded credentials and a lesson was +captured about it. It cannot search for something it doesn't +know to search for. Mechanical injection is the system's +guarantee that relevant knowledge surfaces regardless of +whether the agent thinks to look. It operates without the +agent's involvement, driven by the workflow structure rather +than by agent reasoning. #### Mechanical context injection -At the start of every intake phase, before the agent begins -reasoning, koan automatically loads baseline context. The pipeline -has six steps: +Mechanical injection runs at phase boundaries — points in the +workflow where the problem domain shifts and different knowledge +becomes relevant. Each workflow phase may optionally request +memory injection by providing a **retrieval directive**: a static, +human-authored sentence describing what kind of knowledge is +most likely to matter for the phase. + +The injection pipeline has five steps: **Step 1: Load project summary.** `summary.md` is loaded in full. Always present, not retrieved via search. Budget: ~2000 tokens. - -**Step 2: Generate search queries.** From the current task -description, generate 1–3 search queries that cover different -angles of the task. Example: task "implement OAuth2 authentication -via Auth0" produces queries like "authentication architecture -decisions," "Auth0 integration context," "auth service procedures." -These can be generated mechanically (extract key entities, expand -with type-relevant terms) or by a cheap-tier model. +This step runs only at intake (the first phase); subsequent +phases inherit the summary from the orchestrator's context. + +**Step 2: Generate search queries.** A cheap-tier model receives +two inputs and produces 1–3 search queries: + +The first input is the **retrieval directive** from the phase +definition. This is a static sentence written by the workflow +designer that describes the retrieval intent for the phase — +what kind of knowledge typically matters. For example, an +execution phase might carry the directive "procedures, +conventions, and past lessons related to the subsystem being +modified." A verification phase might carry "quality policies, +testing conventions, and known pitfalls." The directive +provides the *what to look for* dimension. + +The second input is **recent artifacts and context** that provide +the *where to look* dimension — the topical anchor. The preferred +source is the artifacts produced by the preceding phase (the +milestone spec, the technical plan, the decomposition output), +because artifacts are well-structured prose with controlled +format and high information density. When no artifact is +available, the last N messages from the orchestrator's event log +serve the same purpose, though with more noise. The cheap model +combines topic (from the artifacts/context) with intent (from +the directive) to produce well-formed queries. + +Example: the execution phase has directive "procedures, +conventions, and past lessons related to the subsystem being +modified." The preceding planning phase produced a milestone +spec about "token refresh handler for the Auth0 integration." +The cheap model generates queries like "authentication token +refresh procedures," "Auth0 integration lessons," "credential +handling conventions." **Step 3: Per-query hybrid retrieval.** For each query, two parallel searches run against the index: @@ -619,46 +616,57 @@ parallel searches run against the index: N = 20 per retriever per query (tunable; 20 is sufficient for knowledge bases of hundreds to low thousands of entries). -**Step 4: Per-query fusion.** For each query, merge the two result -lists using Reciprocal Rank Fusion: `score = Σ 1/(60 + rank)` -across retrievers. Output: one ranked list per query. - -**Step 5: Cross-query merge and reranking.** Combine the fused +**Step 4: Per-query fusion and cross-query merge.** For each query, +merge the two result lists using Reciprocal Rank Fusion: +`score = Σ 1/(60 + rank)` across retrievers. Combine the fused lists from all queries, deduplicate entries. Pass the candidate pool (typically 30–50 unique entries after dedup) through a cross-encoder reranker, which scores each (query, entry) pair with full attention over both texts. -**Step 6: Take top 3–5 entries.** The highest-scoring entries -after reranking are injected into the agent's context alongside -the summary, with their metadata (type, date, source, status). +**Step 5: Take top 3–5 entries.** The highest-scoring entries +after reranking are injected into the agent's context before +the phase begins, with their metadata (type, created/modified +dates). -Total mechanical context: summary (~2000 tokens) + 3–5 entries -(~500–2500 tokens) = ~2500–4500 tokens of memory context. The -3–5 budget follows SimpleMem's saturation finding: near-optimal -retrieval performance at k=3, diminishing returns beyond k=5. +Total mechanical context per injection: 3–5 entries (~500–2500 +tokens). The 3–5 budget follows SimpleMem's saturation finding: +near-optimal retrieval performance at k=3, diminishing returns +beyond k=5. At intake, the summary adds ~2000 tokens for a +total of ~2500–4500 tokens. -Note: the `_index.md` summary files participate in retrieval -alongside individual entries (collapsed search). A broad query -may match a type-level summary directly; a specific query matches -an individual entry. The reranker decides which level is most -relevant for each query. +Not every phase needs injection. The workflow definition +controls this: a phase either declares a retrieval directive +(and gets injection) or omits it (and relies on inherited +context plus agent-invoked tools). In practice, most phases +that spawn new agents or shift to a different problem domain +should declare a directive. #### Agent-invoked tools -During reasoning, the intake agent has access to two memory tools. +During reasoning, the orchestrator has access to two memory tools. +These complement mechanical injection by handling the agent's +*recognized* information needs — questions that arise during +reasoning that the agent is aware it cannot answer from its +current context. **`koan_search(query, filters?)`** is a targeted lookup. The agent formulates a specific query and gets back raw entries ranked by relevance. Runs the same hybrid search + reranking pipeline as -mechanical retrieval (steps 3–6 above) but for a single +mechanical retrieval (steps 3–5 above) but for a single agent-provided query. Returns the top 3–5 entries as raw markdown content with metadata. The agent can invoke this as many times as -needed during its reasoning. - -Use case: "what is the testing policy?" → returns the relevant -procedure entry directly. No LLM involved in the retrieval -pipeline. +needed during its reasoning. The optional `filters` parameter +supports metadata filtering, e.g. `type=procedure` to narrow +results to a specific memory type. + +Use case: the agent is midway through planning and realizes it +needs to know how the existing secret management works. It calls +`koan_search("secret management pattern .env files")` and gets +the relevant context entry. The mechanical injection surfaced +the lesson about hardcoded credentials (unknown unknown); the +agent tool retrieves the specific implementation pattern it now +knows it needs (known unknown). **`koan_reflect(question, context?)`** is a synthesized briefing. The agent poses a broad question and gets back a coherent answer @@ -668,9 +676,9 @@ by Hindsight's CARA reflect architecture. The reflect tool runs the following agentic loop: -**Step 1: Orient.** The reflect agent loads the project summary -and relevant `_index.md` files to understand what knowledge areas -exist. This is a direct file read, not a search. +**Step 1: Orient.** The reflect agent loads the project summary to +understand what knowledge areas exist. This is a direct file read, +not a search. **Step 2: Plan queries.** Based on the question and the orientation context, the agent generates 3–5 search queries from @@ -681,7 +689,7 @@ conventions," "fail-safe default requirements," "past SDK-related lessons." **Step 3: Gather evidence.** For each query, run the standard -retrieval pipeline (hybrid search + reranking, steps 3–6 from +retrieval pipeline (hybrid search + reranking, steps 3–5 from mechanical retrieval). Collect the top results across all queries. **Step 4: Evaluate sufficiency.** The agent reviews the gathered @@ -704,31 +712,70 @@ path). as the tool's output. The key differences from Hindsight's reflect that koan does NOT -adopt: -- **No disposition traits.** Hindsight uses skepticism, literalism, - and empathy parameters to shape how the agent interprets facts. - Koan's reflect produces factual briefings, not opinionated - interpretations. The project's knowledge speaks for itself. -- **No opinion formation.** Hindsight's reflect creates and updates - opinions with confidence scores. Koan's memory system stores - facts, decisions, and procedures — not beliefs. The reflect tool - synthesizes existing knowledge; it does not form new conclusions. -- **No mental models.** Hindsight's reflect checks pre-computed - summary responses first. Koan's `_index.md` files serve a similar - function (compressed type-level overviews) but are loaded during - orientation rather than as a separate retrieval tier. - -What koan DOES adopt from Hindsight's reflect: -- **The agentic loop.** The reflect tool is not a single LLM call - but an iterative evidence-gathering process that can make - multiple searches and evaluate sufficiency. -- **Hierarchical retrieval.** Check summaries for orientation first, - then search individual entries for detail. -- **Evidence-before-synthesis guardrail.** The agent must gather - entries before producing a briefing — it cannot answer from its - parametric knowledge alone. -- **Citation validation.** The briefing can only cite entries that - were actually retrieved during the evidence-gathering loop. +adopt: no disposition traits (Hindsight uses skepticism, +literalism, and empathy parameters — koan's reflect produces +factual briefings, not opinionated interpretations), and no +opinion formation (Hindsight creates and updates opinions with +confidence scores — koan stores facts and decisions, not +beliefs). + +What koan DOES adopt from Hindsight's reflect: the agentic loop +(iterative evidence gathering, not a single LLM call), the +evidence-before-synthesis guardrail (the agent must gather +entries before producing a briefing — it cannot answer from its +parametric knowledge alone), and citation validation (the briefing +can only cite entries that were actually retrieved). + +#### How the two mechanisms interact + +The two mechanisms are complementary, not redundant. Mechanical +injection casts a wider net guided by structural knowledge about +each phase's typical needs. Agent tools make targeted queries +guided by the agent's evolving reasoning. + +A concrete example: the execution phase's mechanical injection +surfaces a procedure about "always verify testing policy before +code generation" and a lesson about "executor hardcoded +credentials in docker-compose.yml." The agent reads these, +starts working, and midway through realizes it needs to know +specifically how the existing secret management works — so it +calls `koan_search("secret management pattern .env files")` to +get the relevant context entry. The injection caught the unknown +unknowns (the agent didn't know a testing policy existed); the +agent tool handled the known unknown (the agent recognized it +needed implementation details). + +#### Rejected alternative: LLM-generated directives + +An alternative design would have the orchestrator generate the +retrieval directive at runtime — asking the LLM "what memory +should I look for before starting this phase?" This was rejected +because it collapses the two retrieval mechanisms into one. + +If the orchestrator generates the directive, the queries will +reflect what the orchestrator *thinks* it needs — which is +exactly what agent-invoked tools already handle. The +orchestrator can already call `koan_search` for anything it +recognizes as a gap. Generating a directive from the +orchestrator's reasoning produces queries biased toward known +unknowns: topics the orchestrator is already aware of and could +query for itself. + +The value of mechanical injection comes precisely from the fact +that it does *not* depend on the agent's assessment of its own +knowledge gaps. The static directive encodes structural knowledge +that the workflow designer has about what each phase type +typically needs — knowledge that is stable across runs and +independent of any particular agent's reasoning state. An +execution phase needs procedures and lessons about the subsystem +being modified, regardless of whether the orchestrator thinks +to ask for them. A verification phase needs testing policies and +known pitfalls, regardless of whether the verifier knows those +exist. + +Making the directive dynamic would defeat this purpose. The +unknown unknowns would remain unknown, and the injection would +become a redundant copy of what `koan_search` already does. ### Retrieval backend @@ -744,6 +791,35 @@ added to `.gitignore`). --- +## Scaling path: topic-based clustering + +The flat directory structure is the starting point. When the +knowledge base grows to the point where all entries no longer fit +in a cheap model's context window for summary regeneration, that +threshold signals the need for topic-based clustering. + +The scaling path introduces topic clusters derived from entry +content similarity, following the approach validated by xMemory +(Hu et al., 2026) and formalized by the (α, C, τ) framework +(Talebirad et al., ICLR 2026). Topic clusters group entries that +are semantically related — a decision about PostgreSQL, the +infrastructure context it relates to, and a lesson about PostgreSQL +migrations would cluster together regardless of their type fields. + +At that point, each topic cluster gets its own summary, and the +root `summary.md` is regenerated from the topic summaries rather +than from individual entries. This is the recursive summarization +pattern: summarize the leaves, then summarize the summaries. + +The type field remains metadata throughout — it never becomes a +clustering axis. Every hierarchical memory system in the literature +groups by topical similarity, not by cognitive function. + +This scaling transition is a future milestone, not a current +concern. + +--- + ## Appendix: project summary example ```markdown From 47582406bfb126caa738c839503d74b5b5d6d76f Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 16 Apr 2026 14:19:33 +0700 Subject: [PATCH 383/412] fix: improve memory entry slug and frontmatter rendering --- koan/memory/writer.py | 18 ++++++++++--- tests/memory/test_writer.py | 52 ++++++++++++++++++++++++++++++++++++- 2 files changed, 66 insertions(+), 4 deletions(-) diff --git a/koan/memory/writer.py b/koan/memory/writer.py index 8d65d6d..30ca89a 100644 --- a/koan/memory/writer.py +++ b/koan/memory/writer.py @@ -16,12 +16,24 @@ def _now_iso() -> str: def _slugify(title: str, max_len: int = 50) -> str: - """Convert a title to a filename-safe slug.""" + """Convert a title to a filename-safe slug. + + Truncates at the last word boundary (hyphen) within ``max_len`` so the + final filename does not end on a meaningless word fragment like ``-on`` + or ``-sc``. Falls back to hard truncation only when the entire ``max_len`` + window contains no hyphen. + """ slug = title.lower() slug = re.sub(r"[^a-z0-9\s-]", "", slug) slug = re.sub(r"[\s]+", "-", slug).strip("-") slug = re.sub(r"-+", "-", slug) - return slug[:max_len].rstrip("-") + if len(slug) <= max_len: + return slug + cut = slug[:max_len] + last_hyphen = cut.rfind("-") + if last_hyphen > 0: + cut = cut[:last_hyphen] + return cut.rstrip("-") def _next_sequence_number(directory: Path) -> int: @@ -49,7 +61,7 @@ def _render_frontmatter(entry: MemoryEntry) -> str: return yaml.dump( meta, - default_flow_style=None, + default_flow_style=False, sort_keys=False, allow_unicode=False, ).rstrip("\n") diff --git a/tests/memory/test_writer.py b/tests/memory/test_writer.py index 3684e50..6efee66 100644 --- a/tests/memory/test_writer.py +++ b/tests/memory/test_writer.py @@ -6,7 +6,7 @@ from koan.memory.parser import parse_entry from koan.memory.types import MemoryEntry -from koan.memory.writer import _slugify, update_entry, write_entry +from koan.memory.writer import _render_frontmatter, _slugify, update_entry, write_entry def _entry(**overrides) -> MemoryEntry: @@ -39,6 +39,56 @@ def test_trailing_hyphen_after_truncation(self): slug = _slugify(title) assert not slug.endswith("-") + def test_truncates_at_word_boundary_not_mid_word(self): + # Regression: previously truncated to 50 chars unconditionally, + # producing slugs like "...is-one-sentence-on" with a meaningless + # word fragment at the end. + slug = _slugify("Step-first workflow boot prompt is one sentence on call") + assert slug == "step-first-workflow-boot-prompt-is-one-sentence" + # The fragment "on" must not appear as a trailing word. + assert not slug.endswith("-on") + assert not slug.endswith("-sc") + + def test_truncates_cleanly_when_no_hyphen_in_window(self): + # If there's no hyphen at all within max_len, fall back to hard + # truncation rather than returning empty. + slug = _slugify("a" * 100) + assert len(slug) > 0 + assert len(slug) <= 50 + + +class TestRenderFrontmatter: + """Frontmatter must always render in block style, regardless of which + fields are present. Previously the writer used default_flow_style=None + which let PyYAML pick flow-style for entries without a 'related' list, + producing inconsistent files.""" + + def test_block_style_without_related(self): + e = MemoryEntry( + type="context", title="No related field", body="b", + created="2026-01-01T00:00:00Z", modified="2026-01-01T00:00:00Z", + related=[], + ) + fm = _render_frontmatter(e) + # Block style: every key on its own line. Flow style would put the + # whole dict on a single line wrapped in braces. + assert "{" not in fm + assert "}" not in fm + assert "title: No related field" in fm + assert fm.count("\n") >= 3 # at least 4 lines + + def test_block_style_with_related(self): + e = MemoryEntry( + type="decision", title="Has related field", body="b", + created="2026-01-01T00:00:00Z", modified="2026-01-01T00:00:00Z", + related=["0001-foo.md"], + ) + fm = _render_frontmatter(e) + assert "{" not in fm + assert "}" not in fm + assert "related:" in fm + assert "- 0001-foo.md" in fm + class TestWriteEntry: def test_first_entry(self, tmp_path): From f47ff2b8f41927b8ffe06585eff8b438889a9cfb Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 16 Apr 2026 14:20:30 +0700 Subject: [PATCH 384/412] refactor: bind workflows directly to phase modules --- koan/lib/workflows.py | 315 +++++++++++++++++++++++---------------- koan/phases/__init__.py | 50 +------ koan/subagent.py | 13 +- koan/web/mcp_endpoint.py | 11 +- tests/test_workflows.py | 90 ++++++++++- 5 files changed, 300 insertions(+), 179 deletions(-) diff --git a/koan/lib/workflows.py b/koan/lib/workflows.py index 5d5bba9..d11a0f6 100644 --- a/koan/lib/workflows.py +++ b/koan/lib/workflows.py @@ -1,50 +1,101 @@ # Workflow definitions for the koan orchestrator. # -# A Workflow defines the phases available to the orchestrator, their suggested -# transition order, phase descriptions shown at boundaries, and per-phase -# guidance injected into step 1 instructions. +# A Workflow composes its phases directly via a dict[str, PhaseBinding]. +# Each PhaseBinding carries the phase module reference and the per-workflow +# guidance injection. No global registry is needed at runtime -- dispatch +# reads from the workflow's phases dict, making the binding explicit and +# the invariant (module agrees with workflow) structurally enforced. # # Design notes: -# - frozen=True prevents field reassignment after construction (mutation protection). -# - frozen=True does NOT make Workflow hashable --dict fields are unhashable. -# Do not use Workflow as a dict key or set member. +# - frozen=True prevents field reassignment after construction. +# - frozen=True does NOT make Workflow hashable -- dict fields are unhashable. # - Workflows are defined as module-level constants (PLAN_WORKFLOW, etc.). -# - Phase transition validation: any phase in available_phases is reachable -# from any other (user-directed), except self-transitions. +# - Phase transition validation: any phase in phases.keys() is reachable +# from any other (user-directed), except self-transitions. The transitions +# dict guides UI suggestions but does not constrain. from __future__ import annotations from dataclasses import dataclass +from typing import Any + +from ..phases import ( + curation, + execute as execute_phase, + intake, + plan_review, + plan_spec, +) + + +# -- Types -------------------------------------------------------------------- + +@dataclass(frozen=True) +class PhaseBinding: + """Binds a phase module to its per-workflow configuration. + + Each workflow maps phase name strings to PhaseBinding values. + The binding carries the module reference and the guidance + injection, keeping them co-located so dispatch cannot desync. + """ + module: Any # phase module (e.g. intake, curation) + description: str = "" + guidance: str = "" # injected as ctx.phase_instructions at step 1 @dataclass(frozen=True) class Workflow: - """Immutable workflow definition. + """Immutable workflow definition with explicit phase bindings. + + The workflow composes its phases directly: each PhaseBinding + carries the phase module reference, description, and guidance. + Dispatch reads from get_module() / get_binding() instead of a + global registry. Attributes: name: Short identifier (e.g. "plan", "milestones"). description: Human-readable description shown in the UI. - available_phases: All phases the user can transition to in this workflow. - initial_phase: Phase the orchestrator starts in. - suggested_transitions: Per-phase ordered list of suggested next phases. - Guides the orchestrator's boundary response; user can override. - phase_descriptions: One-line description of each phase shown at boundaries. - phase_guidance: Per-phase scope framing injected at the top of step 1 - guidance. Controls investigation depth, question posture, etc. - - Only workflow-agnostic phases (intake, execute) need entries here. - These phases are reused across workflows, so the workflow injects - context they cannot hardcode. Workflow-specific phases (plan-spec, - plan-review) carry their own context -- they do not need injection - because they ARE the workflow. + phases: Ordered dict of phase name -> PhaseBinding. Insertion + order determines UI display order. Each binding carries + the module reference and per-workflow guidance injection. + initial_phase: Phase name the orchestrator starts in. + transitions: Per-phase ordered list of suggested next phase + names. Guides the orchestrator's boundary response; user + can override. Any-to-any within the workflow is valid. """ name: str description: str - available_phases: tuple[str, ...] + phases: dict[str, PhaseBinding] initial_phase: str - suggested_transitions: dict[str, list[str]] - phase_descriptions: dict[str, str] - phase_guidance: dict[str, str] + transitions: dict[str, list[str]] + + # -- Derived accessors (backward compat) ---------------------------------- + + @property + def available_phases(self) -> tuple[str, ...]: + """All phase names in this workflow (insertion-ordered).""" + return tuple(self.phases.keys()) + + @property + def phase_descriptions(self) -> dict[str, str]: + """Phase name -> description mapping.""" + return {k: b.description for k, b in self.phases.items()} + + @property + def phase_guidance(self) -> dict[str, str]: + """Phase name -> guidance text mapping (non-empty entries only).""" + return {k: b.guidance for k, b in self.phases.items() if b.guidance} + + # -- Lookup --------------------------------------------------------------- + + def get_binding(self, name: str) -> PhaseBinding | None: + """Look up a PhaseBinding by phase name.""" + return self.phases.get(name) + + def get_module(self, name: str) -> Any | None: + """Look up the phase module by phase name.""" + b = self.phases.get(name) + return b.module if b else None # -- Curation directives (injected as phase_instructions) --------------------- @@ -164,73 +215,85 @@ class Workflow: # -- Plan workflow ------------------------------------------------------------- -# intake → plan-spec → plan-review → execute → curation +# intake -> plan-spec -> plan-review -> execute -> curation # Lightweight focused-change pipeline. Single executor spawn. PLAN_WORKFLOW = Workflow( name="plan", description="Plan an implementation approach, review it, then execute", - available_phases=("intake", "plan-spec", "plan-review", "execute", "curation"), + phases={ + "intake": PhaseBinding( + module=intake, + description="Explore the codebase and align on requirements through Q&A", + guidance=( + "## Scope\n" + "This is a **plan** workflow -- a focused change touching a bounded\n" + "area of the codebase.\n" + "\n" + "## Downstream\n" + "The understanding you build here feeds into an implementation plan.\n" + "The planner needs enough context to write specific file-level\n" + "instructions, but does not need exhaustive coverage of the entire\n" + "codebase.\n" + "\n" + "## Investigation posture\n" + "- **Prefer direct reading.** For focused changes, reading the referenced\n" + " files yourself is faster and more precise than dispatching scouts.\n" + "- **Dispatch scouts** when the task references subsystems you're unfamiliar\n" + " with, or when dependency tracing would require opening more than ~10 files.\n" + "- If you dispatch scouts, 1-3 is typical for a plan workflow.\n" + "\n" + "## Question posture\n" + "- Always ask at least one round of questions. Even well-specified tasks\n" + " benefit from confirming assumptions and surfacing implicit decisions.\n" + "- A plan workflow needs 2-4 targeted questions covering: approach\n" + " confirmation, constraint verification, and scope boundaries.\n" + "- The user wants to be consulted -- asking questions is a feature, not a\n" + " burden. When in doubt, ask.\n" + "\n" + "## User override\n" + "The user can always ask you to go deeper, dispatch more scouts, or ask\n" + "more questions. Follow their lead over these defaults." + ), + ), + "plan-spec": PhaseBinding( + module=plan_spec, + description="Write a technical implementation plan grounded in the codebase", + ), + "plan-review": PhaseBinding( + module=plan_review, + description="Evaluate the plan for completeness, correctness, and risks", + ), + "execute": PhaseBinding( + module=execute_phase, + description="Hand off the plan to an executor agent for implementation", + guidance=( + "## What to hand off\n" + "Call `koan_request_executor` with:\n" + "- **artifacts**: `[\"plan.md\"]` -- the implementation plan.\n" + "- **instructions**: Key decisions from plan-review, user clarifications,\n" + " or constraints. Do NOT repeat plan.md contents -- the executor reads\n" + " it directly. Instructions are for context that isn't in the files.\n" + "\n" + "## After execution\n" + "Report the result. If the executor failed or asked questions, relay\n" + "the situation to the user and suggest next steps." + ), + ), + "curation": PhaseBinding( + module=curation, + description="Capture lessons, decisions, and context from the completed run", + guidance=_POSTMORTEM_DIRECTIVE, + ), + }, initial_phase="intake", - suggested_transitions={ + transitions={ "intake": ["plan-spec", "execute"], "plan-spec": ["plan-review", "execute"], "plan-review": ["plan-spec", "execute"], "execute": ["curation", "plan-review"], "curation": [], }, - phase_descriptions={ - "intake": "Explore the codebase and align on requirements through Q&A", - "plan-spec": "Write a technical implementation plan grounded in the codebase", - "plan-review": "Evaluate the plan for completeness, correctness, and risks", - "execute": "Hand off the plan to an executor agent for implementation", - "curation": "Capture lessons, decisions, and context from the completed run", - }, - phase_guidance={ - "intake": ( - "## Scope\n" - "This is a **plan** workflow \u2014 a focused change touching a bounded\n" - "area of the codebase.\n" - "\n" - "## Downstream\n" - "The understanding you build here feeds into an implementation plan.\n" - "The planner needs enough context to write specific file-level\n" - "instructions, but does not need exhaustive coverage of the entire\n" - "codebase.\n" - "\n" - "## Investigation posture\n" - "- **Prefer direct reading.** For focused changes, reading the referenced\n" - " files yourself is faster and more precise than dispatching scouts.\n" - "- **Dispatch scouts** when the task references subsystems you're unfamiliar\n" - " with, or when dependency tracing would require opening more than ~10 files.\n" - "- If you dispatch scouts, 1\u20133 is typical for a plan workflow.\n" - "\n" - "## Question posture\n" - "- Always ask at least one round of questions. Even well-specified tasks\n" - " benefit from confirming assumptions and surfacing implicit decisions.\n" - "- A plan workflow needs 2\u20134 targeted questions covering: approach\n" - " confirmation, constraint verification, and scope boundaries.\n" - "- The user wants to be consulted \u2014 asking questions is a feature, not a\n" - " burden. When in doubt, ask.\n" - "\n" - "## User override\n" - "The user can always ask you to go deeper, dispatch more scouts, or ask\n" - "more questions. Follow their lead over these defaults." - ), - "execute": ( - "## What to hand off\n" - "Call `koan_request_executor` with:\n" - "- **artifacts**: `[\"plan.md\"]` \u2014 the implementation plan.\n" - "- **instructions**: Key decisions from plan-review, user clarifications,\n" - " or constraints. Do NOT repeat plan.md contents \u2014 the executor reads\n" - " it directly. Instructions are for context that isn't in the files.\n" - "\n" - "## After execution\n" - "Report the result. If the executor failed or asked questions, relay\n" - "the situation to the user and suggest next steps." - ), - "curation": _POSTMORTEM_DIRECTIVE, - }, ) @@ -240,60 +303,60 @@ class Workflow: MILESTONES_WORKFLOW = Workflow( name="milestones", description="Break work into milestones with phased delivery (coming soon)", - available_phases=("intake",), - initial_phase="intake", - suggested_transitions={"intake": []}, - phase_descriptions={ - "intake": "Explore the codebase and align on requirements through Q&A", - }, - phase_guidance={ - "intake": ( - "## Scope\n" - "This is a **milestones** workflow \u2014 a broad initiative spanning\n" - "multiple subsystems requiring significant codebase exploration.\n" - "\n" - "## Downstream\n" - "The understanding you build here feeds into milestone decomposition\n" - "and multi-phase planning. Downstream phases need comprehensive\n" - "coverage: every affected subsystem, integration point, and constraint\n" - "must be documented.\n" - "\n" - "## Investigation posture\n" - "- **Dispatch scouts broadly.** Explore every subsystem the task touches\n" - " and adjacent areas that might be affected. 3\u20135 scouts is typical.\n" - "- **Also read directly** \u2014 verify key scout findings against the actual\n" - " code, especially integration points and conventions.\n" - "\n" - "## Question posture\n" - "- Ask multiple rounds of questions. For broad initiatives, 2\u20133 rounds\n" - " of 3\u20136 questions is typical.\n" - "- Surface assumptions early. Each answer may reveal new areas to probe.\n" - "- Probe cross-cutting concerns: shared patterns, naming conventions,\n" - " error handling strategies, test coverage expectations.\n" - "\n" - "## User override\n" - "The user can always tell you to narrow scope or skip questions.\n" - "Follow their lead over these defaults." + phases={ + "intake": PhaseBinding( + module=intake, + description="Explore the codebase and align on requirements through Q&A", + guidance=( + "## Scope\n" + "This is a **milestones** workflow -- a broad initiative spanning\n" + "multiple subsystems requiring significant codebase exploration.\n" + "\n" + "## Downstream\n" + "The understanding you build here feeds into milestone decomposition\n" + "and multi-phase planning. Downstream phases need comprehensive\n" + "coverage: every affected subsystem, integration point, and constraint\n" + "must be documented.\n" + "\n" + "## Investigation posture\n" + "- **Dispatch scouts broadly.** Explore every subsystem the task touches\n" + " and adjacent areas that might be affected. 3-5 scouts is typical.\n" + "- **Also read directly** -- verify key scout findings against the actual\n" + " code, especially integration points and conventions.\n" + "\n" + "## Question posture\n" + "- Ask multiple rounds of questions. For broad initiatives, 2-3 rounds\n" + " of 3-6 questions is typical.\n" + "- Surface assumptions early. Each answer may reveal new areas to probe.\n" + "- Probe cross-cutting concerns: shared patterns, naming conventions,\n" + " error handling strategies, test coverage expectations.\n" + "\n" + "## User override\n" + "The user can always tell you to narrow scope or skip questions.\n" + "Follow their lead over these defaults." + ), ), }, + initial_phase="intake", + transitions={"intake": []}, ) # -- Curation workflow -------------------------------------------------------- -# Standalone memory maintenance workflow (review directive). +# Standalone memory maintenance workflow (standalone directive). CURATION_WORKFLOW = Workflow( name="curation", description="Maintain the project memory: review, bootstrap, or ingest documents", - available_phases=("curation",), - initial_phase="curation", - suggested_transitions={"curation": []}, - phase_descriptions={ - "curation": "Review and maintain the project's memory entries", - }, - phase_guidance={ - "curation": _STANDALONE_DIRECTIVE, + phases={ + "curation": PhaseBinding( + module=curation, + description="Review and maintain the project's memory entries", + guidance=_STANDALONE_DIRECTIVE, + ), }, + initial_phase="curation", + transitions={"curation": []}, ) @@ -316,13 +379,13 @@ def get_workflow(name: str) -> Workflow: def get_suggested_phases(workflow: Workflow, phase: str) -> list[str]: """Return the ordered suggested next phases for the current phase.""" - return list(workflow.suggested_transitions.get(phase, [])) + return list(workflow.transitions.get(phase, [])) def is_valid_transition(workflow: Workflow, from_phase: str, to_phase: str) -> bool: """Any phase in the workflow is reachable from any other (except self-transition). - The user drives macro-level progression; suggested_transitions guides defaults + The user drives macro-level progression; transitions guides defaults but does not constrain choices. """ return to_phase in workflow.available_phases and to_phase != from_phase diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index f57b9cf..705bbf2 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -84,50 +84,14 @@ async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> ) -# -- Phase module registry ---------------------------------------------------- -# Maps each SubagentRole string to its phase module (for subagent spawn lookup). - -from . import ( - brief_writer, - core_flows, - cross_artifact_validation, - curation, - executor, - intake, - orchestrator, - scout, - tech_plan as planner, - ticket_breakdown, - execute as execute_phase, - plan_review, - plan_spec, -) +# -- Subagent module registry -------------------------------------------------- +# Maps SubagentRole strings to phase modules for non-orchestrator subagent +# spawns (scouts, executors). Orchestrator phase dispatch uses +# Workflow.get_module() instead -- see koan/lib/workflows.py. + +from . import executor, scout + PHASE_MODULE_MAP: dict[str, Any] = { - "intake": intake, "scout": scout, - "orchestrator": orchestrator, - "planner": planner, "executor": executor, } - -# -- Phase guidance map ------------------------------------------------------- -# Maps WorkflowPhase strings to the phase module that provides step guidance. -# Used by koan_set_phase to load the module for the new phase. - -PHASE_GUIDANCE_MAP: dict[str, Any] = { - # General-purpose phases (reusable by any workflow) - "intake": intake, - "execute": execute_phase, - "curation": curation, - # Plan workflow phases (SCOPE="plan") - "plan-spec": plan_spec, - "plan-review": plan_review, - # Legacy phases (SCOPE="legacy" --dead code, available for future workflows) - "brief-generation": brief_writer, - "core-flows": core_flows, - "tech-plan": planner, - "ticket-breakdown": ticket_breakdown, - "cross-artifact-validation": cross_artifact_validation, - "execution": executor, - "implementation-validation": cross_artifact_validation, -} diff --git a/koan/subagent.py b/koan/subagent.py index a1d5982..e313990 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -29,7 +29,8 @@ build_tool_write, ) from .logger import get_logger -from .phases import ORCHESTRATOR_SYSTEM_PROMPT, PHASE_GUIDANCE_MAP, PHASE_MODULE_MAP, PhaseContext +from .lib.workflows import get_workflow +from .phases import ORCHESTRATOR_SYSTEM_PROMPT, PHASE_MODULE_MAP, PhaseContext from .runners import RunnerDiagnostic, RunnerError from .runners.registry import RunnerRegistry @@ -147,10 +148,14 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None phase_ctx = _build_phase_ctx(task, subagent_dir) # Look up phase module and system prompt. - # Persistent orchestrator: uses intake as initial step-guidance module; - # ORCHESTRATOR_SYSTEM_PROMPT as the spawn-time --system-prompt. + # Persistent orchestrator: uses the workflow's initial_phase to select + # the step-guidance module. This must agree with driver.py which sets + # app_state.phase = workflow.initial_phase. Falls back to "plan" + # workflow when no workflow name is on the task. if role == "orchestrator": - phase_module = PHASE_GUIDANCE_MAP.get("intake") + workflow_name = task.get("workflow", "plan") + workflow = get_workflow(workflow_name) + phase_module = workflow.get_module(workflow.initial_phase) system_prompt = ORCHESTRATOR_SYSTEM_PROMPT else: phase_module = PHASE_MODULE_MAP.get(role) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 09ae73d..b1f9bad 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -47,7 +47,7 @@ from ..lib.workflows import get_suggested_phases, is_valid_transition as wf_is_valid from ..logger import get_logger from ..memory import MEMORY_TYPES, MemoryStore -from ..phases import PHASE_GUIDANCE_MAP, PhaseContext, StepGuidance +from ..phases import PhaseContext, StepGuidance from ..phases.format_step import format_phase_complete, format_steering_messages, format_step, format_user_messages from .interactions import activate_next_interaction, enqueue_interaction @@ -514,12 +514,12 @@ async def koan_set_phase(phase: str) -> str: ), })) - # Look up new phase module - new_module = PHASE_GUIDANCE_MAP.get(phase) + # Look up new phase module from the workflow's bindings + new_module = workflow.get_module(phase) if workflow else None if new_module is None: raise ToolError(json.dumps({ "error": "unknown_phase", - "message": f"Phase '{phase}' has no module implementation", + "message": f"Phase '{phase}' has no module in workflow '{workflow.name if workflow else '?'}'", })) # Update driver state @@ -550,7 +550,8 @@ async def koan_set_phase(phase: str) -> str: ) # Inject per-workflow phase guidance for the new phase - phase_guidance = workflow.phase_guidance.get(phase, "") if workflow else "" + binding = workflow.get_binding(phase) if workflow else None + phase_guidance = binding.guidance if binding else "" # Switch phase module and reset step counter agent.phase_module = new_module diff --git a/tests/test_workflows.py b/tests/test_workflows.py index 86a0fd4..0617b59 100644 --- a/tests/test_workflows.py +++ b/tests/test_workflows.py @@ -7,6 +7,7 @@ MILESTONES_WORKFLOW, PLAN_WORKFLOW, WORKFLOWS, + PhaseBinding, Workflow, get_suggested_phases, get_workflow, @@ -36,6 +37,85 @@ def test_get_workflow_lists_valid_in_error(): get_workflow("bogus") +# -- PhaseBinding and Workflow.get_module / get_binding ------------------------ + +def test_get_module_returns_module(): + mod = PLAN_WORKFLOW.get_module("intake") + assert mod is not None + assert hasattr(mod, "step_guidance") + assert hasattr(mod, "TOTAL_STEPS") + + +def test_get_module_unknown_returns_none(): + assert PLAN_WORKFLOW.get_module("nonexistent") is None + + +def test_get_binding_returns_binding(): + b = PLAN_WORKFLOW.get_binding("intake") + assert isinstance(b, PhaseBinding) + assert b.module is not None + assert len(b.description) > 0 + + +def test_get_binding_unknown_returns_none(): + assert PLAN_WORKFLOW.get_binding("nonexistent") is None + + +def test_curation_workflow_initial_module_is_curation(): + """Regression: the orchestrator's initial phase module must match + the workflow's initial_phase. The previous global-registry design + hardcoded intake for all workflows, causing standalone curation + to receive intake step guidance (Gather/Deepen) instead of + curation step guidance (Inventory/Memorize).""" + from koan.phases import curation + mod = CURATION_WORKFLOW.get_module(CURATION_WORKFLOW.initial_phase) + assert mod is curation + + +def test_plan_workflow_initial_module_is_intake(): + from koan.phases import intake + mod = PLAN_WORKFLOW.get_module(PLAN_WORKFLOW.initial_phase) + assert mod is intake + + +def test_same_module_different_guidance_across_workflows(): + """The same phase module (curation) serves two workflows with + different guidance bindings: postmortem in plan, standalone in + the curation workflow.""" + plan_b = PLAN_WORKFLOW.get_binding("curation") + cur_b = CURATION_WORKFLOW.get_binding("curation") + assert plan_b.module is cur_b.module # same module + assert plan_b.guidance != cur_b.guidance # different guidance + assert "postmortem" in plan_b.guidance + assert "standalone" in cur_b.guidance + + +# -- Backward-compat property accessors --------------------------------------- + +def test_available_phases_is_tuple(): + assert isinstance(PLAN_WORKFLOW.available_phases, tuple) + assert "intake" in PLAN_WORKFLOW.available_phases + assert "curation" in PLAN_WORKFLOW.available_phases + + +def test_phase_descriptions_is_dict(): + descs = PLAN_WORKFLOW.phase_descriptions + assert isinstance(descs, dict) + for phase in PLAN_WORKFLOW.available_phases: + assert phase in descs + assert len(descs[phase]) > 0 + + +def test_phase_guidance_is_dict_non_empty_only(): + guidance = PLAN_WORKFLOW.phase_guidance + assert isinstance(guidance, dict) + # intake and execute have guidance; plan-spec and plan-review do not + assert "intake" in guidance + assert "execute" in guidance + # plan-spec has no guidance (carries its own context) + assert "plan-spec" not in guidance + + # -- get_suggested_phases ----------------------------------------------------- def test_get_suggested_phases_intake(): @@ -140,7 +220,7 @@ def test_milestones_workflow_structure(): assert wf.name == "milestones" assert wf.available_phases == ("intake",) assert wf.initial_phase == "intake" - assert wf.suggested_transitions == {"intake": []} + assert wf.transitions == {"intake": []} def test_milestones_workflow_has_intake_guidance(): @@ -187,11 +267,19 @@ def test_workflow_frozen(): PLAN_WORKFLOW.name = "mutated" +def test_phase_binding_frozen(): + """PhaseBinding instances cannot have fields reassigned (frozen=True).""" + b = PLAN_WORKFLOW.get_binding("intake") + with pytest.raises(Exception): + b.module = None + + # -- WORKFLOWS registry ------------------------------------------------------- def test_workflows_registry_complete(): assert "plan" in WORKFLOWS assert "milestones" in WORKFLOWS + assert "curation" in WORKFLOWS def test_workflows_registry_values_are_workflow_instances(): From d0e9b3adb36f1c5cddab957afa0b17b856c279e5 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 16 Apr 2026 14:20:52 +0700 Subject: [PATCH 385/412] feat: strengthen curation guidance with draft-quality loop --- koan/phases/curation.py | 351 +++++++++++++++++++++++++++++----- tests/phases/test_curation.py | 130 +++++++++++-- 2 files changed, 417 insertions(+), 64 deletions(-) diff --git a/koan/phases/curation.py b/koan/phases/curation.py index 4ebd1d1..a7f66a6 100644 --- a/koan/phases/curation.py +++ b/koan/phases/curation.py @@ -127,6 +127,37 @@ "- **procedure** -- behavioral rules for agents. Checkable conditions\n" " and concrete actions. Often paired with a lesson.\n" "\n" + "## Picking the type for a candidate\n" + "\n" + "The definitions above say what each type IS. This tree says how to\n" + "PICK one for a given candidate. Walk the four questions in order;\n" + "the FIRST match wins.\n" + "\n" + "| # | Question | If YES |\n" + "|---|-------------------------------------------------------|-----------|\n" + "| 1 | Does this entry name a choice between alternatives, | decision |\n" + "| | with rationale (why X over Y)? | |\n" + "| 2 | Did the user correct the agent during this run | lesson |\n" + "| | (agent first thought X, but the right answer was Y), | |\n" + "| | OR does this entry record a thing that went wrong | |\n" + "| | with an identified root cause? | |\n" + "| 3 | Does this entry tell a future agent what to do | procedure |\n" + "| | under condition X (a behavioral rule)? | |\n" + "| 4 | Is this a stable fact about the project (team, | context |\n" + "| | infrastructure, conventions) that does not tell | |\n" + "| | anyone what to do? | |\n" + "\n" + "If none match, the candidate is probably not memory-worthy -- drop\n" + "it. Candidates can match multiple rows; first-match-wins means:\n" + "\n" + "- An actionable rule that came from a specific corrected mistake\n" + " stays as a lesson (question 2 fires before question 3). The\n" + " generalized procedure can be a follow-up entry, linked via\n" + " `related`.\n" + "- An architectural choice with rationale is a decision even when\n" + " it implies a rule for future agents (question 1 fires before\n" + " question 3).\n" + "\n" "## Classification schema\n" "\n" "Before drafting any candidate, classify it against existing memory:\n" @@ -140,31 +171,31 @@ " is DEPRECATE; the tool is `koan_forget` -- they\n" " refer to the same operation.)\n" "\n" - "## Writing discipline\n" - "\n" - "Every entry body is 100-500 tokens of event-style prose:\n" + "## Writing discipline (high-level)\n" "\n" - "- **Open with context.** The first 1-3 sentences situate the entry in\n" - " the project. They get embedded for semantic search; vague openings\n" - " hurt retrieval.\n" - "- **Temporally ground every claim.** Use absolute dates (\"On 2026-04-10,\n" - " user decided...\") so the entry stays true regardless of when it is\n" - " read.\n" - "- **Attribute the source.** \"User stated\", \"LLM inferred\", \"Post-mortem\n" - " identified\". User-stated facts carry higher trust than inferences.\n" - "- **Name things concretely.** \"PostgreSQL 16.2\", not \"the database\".\n" - "- **Stand alone.** Each entry must be interpretable without reading\n" - " any other entry.\n" - "- **No forward-looking language.** Not \"we will\" but \"On <date>, user\n" - " stated the plan was to...\".\n" + "Every entry is 100-500 tokens of **temporally grounded, attributed,\n" + "event-style** prose -- a historical fact that stays true regardless\n" + "of when it is read. The full rules, two contrastive bad/good\n" + "examples, and a 5-item self-validation checklist appear in step 2\n" + "(Memorize), rendered at the drafting moment. Do NOT skim the step 2\n" + "examples -- your default register for technical content is timeless\n" + "documentation prose, and the examples are the only thing that\n" + "overrides that default.\n" "\n" - "Use the `related` field (filenames like `0002-infrastructure.md`) to\n" - "link a lesson to its derived procedure, or a decision to its\n" + "Use the `related` field (filenames like `0002-infrastructure.md`)\n" + "to link a lesson to its derived procedure, or a decision to its\n" "motivating context.\n" "\n" "## What not to capture\n" "\n" - "- Anything derivable from reading the code.\n" + "- Implementation details derivable from reading the code, EXCEPT:\n" + " - The **rationale and rejected alternatives** behind architectural\n" + " decisions. These are NOT in code -- they are in the heads of the\n" + " people who made the choice, and in the conversations that\n" + " surfaced the choice. Capture them.\n" + " - The **lessons from prior workflows** -- corrected mistakes,\n" + " surprises, root causes of failures. These are not in code;\n" + " they are history. Capture them.\n" "- Temporary implementation details that will not matter next week.\n" "- Opinions without grounding in project experience.\n" "- Anything already adequately captured (use NOOP, not a duplicate).\n" @@ -218,6 +249,10 @@ def _tools_this_step_block(current_step: int) -> list[str]: if current_step == 2: return [ "<tools_this_step>", + "Writing discipline, two contrastive examples, and a 5-item", + "draft-quality checklist appear in this step's body below.", + "Read them BEFORE drafting your first candidate.", + "", "1. `koan_yield` -- present each batch of proposals to the user.", "2. `koan_memorize` -- write approved ADD / UPDATE entries.", "3. `koan_forget` -- delete approved DEPRECATE entries.", @@ -301,7 +336,12 @@ def _step_1_inventory(ctx: PhaseContext) -> StepGuidance: " koan memory -- treat it as read-only input only.", "", "6. Build a numbered candidate list. For each candidate note:", - " - type (decision / context / lesson / procedure)", + " - type -- assign using the 4-question discrimination", + " tree in the system prompt above (\"Picking", + " the type for a candidate\"). Walk the four", + " questions in order; first match wins. If", + " none match, drop the candidate as not", + " memory-worthy.", " - title (one line)", " - classification (ADD / UPDATE / NOOP / DEPRECATE)", " - entry_id (only for UPDATE / DEPRECATE)", @@ -330,60 +370,271 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: "", "This is the writing step. Your candidate list from step 1 becomes", "`koan_memorize` and `koan_forget` calls, gated by user approval", - "via `koan_yield`. The classification schema, writing discipline,", - "and tool semantics live in your role context above -- do not", - "redefine them here.", + "via `koan_yield`.", + "", + "Read the writing discipline, contrastive examples, and the", + "draft-quality checklist below BEFORE drafting your first", + "candidate. The rules are rendered here, at the drafting moment,", + "because verbal rules from the system prompt do not survive the", + "distance to this step -- your default register for technical", + "content is timeless documentation prose, which violates every", + "rule. The examples are how you override that default.", + "", + "## Writing discipline (full rules)", + "", + "Every entry body obeys these five rules. Each rule has a", + "corresponding check in the self-critique substep below.", + "", + "**1. Open with a named subsystem.** The first 1-3 sentences", + "situate the entry by naming the specific subsystem, artifact,", + "or decision it is about (examples: \"the session storage for", + "the user-facing web service\", \"the deployment pipeline's cache", + "layer\", \"the configuration loader\"). If the entry is about the", + "project as a whole, the first sentence names the project", + "explicitly. Vague openings (\"This system uses...\", \"The", + "project enforces...\") hurt retrieval because embeddings have", + "no specific anchor.", + "", + "**2. Temporally ground every claim.** Use absolute dates in", + "YYYY-MM-DD form (\"On 2025-09-12, the team decided...\"). A year", + "alone, or relative terms like \"recently\", \"currently\", \"at the", + "moment\" fail. Temporal grounding turns every entry into a", + "historical fact that stays true regardless of when it is read.", + "", + "**3. Attribute every claim to its source.** Name who said or", + "discovered the fact: \"user stated\", \"the team decided\",", + "\"post-mortem identified\", \"LLM inferred\", \"developer", + "confirmed\", \"maintainer agreed\". User-stated facts carry higher", + "trust than inferences; readers need to know which is which.", + "", + "**4. Event-style, past tense.** Describe what happened, not", + "what is. \"We use Redis\" fails; \"On <date>, the team adopted", + "Redis 7.2...\" passes. Forward-looking language (\"we will\",", + "\"should\", \"must\") also fails unless embedded inside a past-", + "tense attribution (\"On <date>, the team decided that the rule", + "is to...\").", + "", + "**5. Name things concretely.** Use specific versions, file", + "paths, tool names, table names, column names, environment", + "variable names. \"The database\" fails; \"PostgreSQL 16.2\"", + "passes. \"Some config\" fails; \"the BUILD_TARGET environment", + "variable in deploy/production.env\" passes.", + "", + "## Contrastive examples", + "", + "These are general-purpose templates, not examples from koan", + "itself. Study each bad/good pair and the explanation of what", + "changed. The GOOD versions are the shape your drafts must", + "take.", + "", + "<example type=\"decision-bad\">", + "We use Redis for session storage because it's fast and reliable.", + "</example>", + "", + "<example type=\"decision-good\">", + "This entry documents the choice of session storage for the", + "user-facing web service. On 2025-09-12, the team decided to", + "adopt Redis 7.2 for session storage, replacing in-process", + "Python dicts. Rationale: horizontal scaling required session", + "state to live outside individual app workers, and the existing", + "operational tooling already supported Redis. Alternatives", + "rejected: Memcached (no built-in persistence, complicating", + "session continuity across restarts), PostgreSQL session table", + "(added 40-80 ms of latency to every request per the team's", + "staging benchmarks). Decision surfaced during a post-mortem on", + "a session-loss incident under load on 2025-09-08.", + "</example>", + "", + "What changed between bad and good:", + "", + "- Bad opens with \"We use\" (timeless present); good opens by", + " naming the subsystem (\"session storage for the user-facing", + " web service\") and follows with a dated event.", + "- Bad has no date; good anchors both the decision (2025-09-12)", + " and the motivating incident (2025-09-08).", + "- Bad has no attribution; good attributes to \"the team\" and", + " names the surfacing context (a post-mortem).", + "- Bad names nothing concretely; good names Redis 7.2, the", + " rejected alternatives, the specific latency numbers, and the", + " incident that drove the decision.", + "- Bad would become stale if Redis is later replaced; good", + " remains true as a historical record forever.", + "", + "<example type=\"lesson-bad\">", + "Don't forget to update the schema migration when adding new columns.", + "</example>", + "", + "<example type=\"lesson-good\">", + "This entry records a deployment failure in the user-management", + "service. On 2025-11-03, a feature branch added a `last_seen_at`", + "column to the users table at the ORM model level but omitted", + "the corresponding Alembic migration file. The change passed", + "local tests because the local test database used SQLite, which", + "auto-creates columns from ORM model definitions. Staging", + "deployment failed when PostgreSQL rejected inserts referencing", + "the missing column. Root cause: the test harness used a", + "different database engine than production, hiding schema drift", + "at merge time. Correction applied on 2025-11-04: the team", + "added a CI step that runs all Alembic migrations against an", + "empty PostgreSQL instance before test suites execute, catching", + "ORM/schema drift before merge.", + "</example>", + "", + "What changed between bad and good:", "", - "## The loop", + "- Bad is a forward-looking instruction (\"don't forget\"); good", + " is an event record of a specific dated failure.", + "- Bad has no root cause; good identifies it (test harness", + " used a different database than production).", + "- Bad has no concrete artifacts; good names Alembic, SQLite,", + " PostgreSQL, `last_seen_at`, the users table, and the new CI", + " step.", + "- Bad would become stale if the team switches migration tools;", + " good stays true as a dated historical record.", "", - "Repeat for each batch of 3-5 candidates from your step 1 list:", + "## The per-batch loop (6 sub-operations, in order)", "", - "1. **Draft** proposals for the batch. Each proposal includes", - " `type`, `title`, `body`, `related`, plus `entry_id` for UPDATE", - " and DEPRECATE.", + "For each batch of 3-5 candidates from your step 1 list, run", + "these sub-operations IN ORDER. Each sub-operation produces a", + "committed, VISIBLE output in your response before the next", + "begins. Do not collapse substeps. Do not skip ahead. The", + "committed-artifact structure is the load-bearing quality gate --", + "collapsing it lets the model sandbag drafts to manufacture", + "obvious improvements at the revise step without actually", + "improving anything.", + "", + "### A. Draft", + "", + "Write each non-NOOP candidate as a complete entry, modeled on", + "the GOOD examples above. Include type, title, body, related,", + "and (for UPDATE / DEPRECATE) entry_id.", + "", + "Output all drafts for this batch as a visible list BEFORE", + "moving to substep B. You must commit to the drafts as-is", + "before self-critiquing them.", + "", + "### B. Self-critique", + "", + "For each draft produced in substep A, run the 5-item draft-", + "quality checklist below. Output the checklist result PER", + "DRAFT in this exact format:", + "", + " Draft 1 ({title}):", + " 1. Opens with named subsystem: PASS / FAIL", + " 2. Contains absolute date: PASS / FAIL", + " 3. Contains attribution: PASS / FAIL", + " 4. Event-style, past tense: PASS / FAIL", + " 5. Concrete naming: PASS / FAIL", + "", + " Draft 2 ({title}):", + " ...", + "", + "Do not skip this substep. Do not merge it into substep A or C.", + "The explicit checklist output is the committed artifact that", + "prevents simulated refinement -- if substep B is absent, the", + "whole quality gate collapses.", + "", + "### C. Revise", + "", + "For every draft with any FAIL in its checklist, rewrite the", + "entry completely. Do not patch in place -- rewrite it, using", + "the GOOD example template as the target form. After each", + "rewrite, re-run the 5-item checklist on the revised draft.", + "Loop until all 5 items PASS for all drafts in the batch.", + "", + "You MAY NOT proceed to substep D (Yield) while any draft in", + "this batch has an outstanding FAIL.", + "", + "### D. Yield", + "", + "Call `koan_yield` with the final (all-PASS) proposals as", + "markdown plus these structured suggestions:", "", - "2. **Yield** the batch to the user. Call `koan_yield` with the", - " proposals as markdown plus these structured suggestions:", ' - {id: "approve", label: "Approve all", command: "Approve all entries in this batch"}', ' - {id: "skip", label: "Skip all", command: "Skip this batch"}', ' - {id: "review", label: "Review individually", command: "Let me review each entry"}', "", - "3. **Apply** approved changes:", - " - ADD -> `koan_memorize` (no `entry_id`)", - " - UPDATE -> `koan_memorize` (with `entry_id`)", - " - DEPRECATE -> `koan_forget` (with `entry_id`)", - " - NOOP -> nothing", + "### E. Apply", + "", + "Apply approved changes:", + "- ADD -> `koan_memorize` (no `entry_id`)", + "- UPDATE -> `koan_memorize` (with `entry_id`)", + "- DEPRECATE -> `koan_forget` (with `entry_id`)", + "- NOOP -> nothing", + "", + "### F. Cross off", + "", + "Cross items off your candidate list and loop back to substep", + "A with the next batch. Continue until the list is empty or", + "the user tells you to stop.", + "", + "## Draft-quality checklist (schema for substep B)", + "", + "For each draft, verify all 5 items. Any FAIL means the draft", + "cannot be yielded -- it must go back through substep C.", + "", + "**1. Opens with a named subsystem.**", + "First sentence names the specific subsystem, decision, or", + "artifact this entry is about. If the entry is about the", + "project as a whole, the first sentence names the project", + "explicitly. Openings like \"This system...\", \"The project...\",", + "or a rule statement with no subject FAIL this check.", + "", + "**2. Contains at least one absolute date.**", + "Body has one or more dates in YYYY-MM-DD form anchoring an", + "event. A year alone, or words like \"recently\", \"currently\",", + "\"at the moment\" FAIL.", + "", + "**3. Contains an attribution phrase.**", + "Body explicitly states who said or discovered each claim:", + "\"user stated\", \"the team decided\", \"post-mortem identified\",", + "\"LLM inferred\", \"developer confirmed\", \"maintainer agreed\".", + "Anonymous declarations (\"it was decided that...\" without a", + "subject) FAIL.", + "", + "**4. Event-style, past tense.**", + "Body describes events that happened (\"On <date>, X did Y\"),", + "not timeless facts (\"We use X\"). Present-tense \"is\"", + "statements about how things currently work FAIL. Forward-", + "looking language (\"we will\", \"should\", \"must\") also FAILS", + "unless embedded inside a past-tense attribution.", "", - "4. **Cross items off** your candidate list. Loop back to step 1", - " of this loop until the list is empty or the user tells you", - " to stop.", + "**5. Concrete naming.**", + "Body names specific entities: versions, file paths, tool", + "names, table names, column names, environment variable names.", + "\"The database\" FAILS; \"PostgreSQL 16.2\" passes. \"Some config\"", + "FAILS; \"the BUILD_TARGET environment variable in", + "deploy/production.env\" passes.", "", - "## Anticipatory check (BEFORE the wrap-up)", + "## Anticipatory tool-call check (BEFORE the wrap-up)", "", - "Stop and verify:", + "After all batches have been processed, before you call", + "`koan_complete_step`, verify:", "", - "- Did you call `koan_memorize` at least once for the ADD / UPDATE", - " items on your step 1 candidate list?", + "- Did you call `koan_memorize` at least once for the ADD /", + " UPDATE items on your step 1 candidate list?", "- Did you call `koan_forget` for any DEPRECATE items?", "", - "If NO and your step 1 list was non-empty: you have not done the", - "work of this phase. Loop back to draft proposals and call", - "`koan_yield`. Do not advance to the wrap-up with zero writes.", + "If NO and your step 1 list was non-empty: you have not done", + "the work of this phase. Loop back to substep A with the", + "remaining candidates. Do not advance to the wrap-up with zero", + "writes.", "", - "If your step 1 list was explicitly empty (\"all candidates were", - "NOOPs because X\"), zero writes is correct -- continue to wrap-up.", + "If your step 1 list was explicitly empty (\"all candidates", + "were NOOPs because X\"), zero writes is correct -- continue", + "to wrap-up.", "", "## Wrap-up", "", - "1. Call `koan_memory_status` once. This triggers just-in-time", + "1. Call `koan_memory_status` once. Triggers just-in-time", " summary regeneration if any entries changed.", "", "2. Report the final counts to the user inline:", " `{added: N, updated: N, deprecated: N, noop: N}`", " plus a one-line note on anything deferred for a future run.", "", - "3. Call `koan_complete_step`. The curation phase ends here and", - " the workflow is complete.", + "3. Call `koan_complete_step`. The curation phase ends here", + " and the workflow is complete.", ] return StepGuidance(title=STEP_NAMES[2], instructions=instructions) diff --git a/tests/phases/test_curation.py b/tests/phases/test_curation.py index 5be279d..023e229 100644 --- a/tests/phases/test_curation.py +++ b/tests/phases/test_curation.py @@ -28,11 +28,39 @@ def test_system_prompt_is_nonempty(self): assert isinstance(curation.SYSTEM_PROMPT, str) assert len(curation.SYSTEM_PROMPT) > 100 - def test_system_prompt_writing_discipline(self): - # The writing-discipline pillars must be present. + def test_system_prompt_writing_discipline_is_high_level_only(self): + # Post-rewrite: writing discipline in the system prompt is a + # one-paragraph high-level summary. The full rules and the + # contrastive examples live in step 2's body, rendered at the + # drafting moment. The system prompt keeps just the pillars + # ("temporally grounded, attributed, event-style") and an + # explicit pointer to step 2. sp = curation.SYSTEM_PROMPT.lower() - for term in ("temporally", "attribut", "stand alone", "concretely"): - assert term in sp, f"missing {term!r} in SYSTEM_PROMPT" + assert "temporally grounded" in sp + assert "attributed" in sp + assert "event-style" in sp + assert "step 2" in sp # points at where the full rules live + + def test_system_prompt_has_type_discrimination_tree(self): + sp = curation.SYSTEM_PROMPT + # The 4-question tree, with first-match-wins semantics, must + # be present as a procedure (not just definitions). + assert "Picking the type for a candidate" in sp + assert "first match wins" in sp.lower() or "FIRST match wins" in sp + # Each of the four types must appear as a tree outcome. + for type_name in ("decision", "lesson", "procedure", "context"): + assert type_name in sp + # Lesson trigger includes the user-correction case. + assert "correct the agent" in sp + + def test_system_prompt_derivable_rule_preserves_decisions(self): + # The "what not to capture" rule must explicitly preserve + # decisions' rationale and prior-workflow lessons, even when + # the resulting implementation is in code. + sp = curation.SYSTEM_PROMPT + assert "EXCEPT" in sp + assert "rationale and rejected alternatives" in sp + assert "lessons from prior workflows" in sp def test_system_prompt_enumerates_memory_tools(self): # Tools must be visible at the role layer. @@ -181,6 +209,18 @@ def test_produces_candidate_list_contract(self): text = "\n".join(curation.step_guidance(1, _ctx()).instructions) assert "candidate list" in text.lower() + def test_points_at_type_discrimination_tree(self): + # Step 1 must reference the system prompt's type discrimination + # tree at the point where types are assigned, so the orchestrator + # applies the tree procedurally rather than picking types from + # the abstract definitions alone. + # Flatten whitespace so the substring match works across line wraps. + import re + text = "\n".join(curation.step_guidance(1, _ctx()).instructions) + flat = re.sub(r"\s+", " ", text).lower() + assert "discrimination tree" in flat + assert "first match wins" in flat + class TestStep2Memorize: def test_title_is_memorize(self): @@ -205,18 +245,80 @@ def test_references_memory_tools(self): assert "koan_forget" in text assert "koan_yield" in text - def test_does_not_redefine_writing_discipline(self): - # Writing discipline lives in the system prompt; step 2 should not - # duplicate it. Sentinel: "1-3 sentences" is system-prompt-only. + def test_renders_writing_discipline_at_drafting_moment(self): + # Post-rewrite: writing discipline is now INTENTIONALLY rendered + # in step 2's body, right at the drafting moment. The previous + # design kept it only in the system prompt, which was too far + # from the drafting turn; 7/10 entries in the audit violated + # rules the system prompt had correctly stated. text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - assert "1-3 sentences" not in text - - def test_includes_anticipatory_check(self): - # The anticipatory check is the central new defense against the - # "phase ended with zero writes" failure. + assert "## Writing discipline" in text + # All 5 rules must be visible inline, not by reference. + assert "Open with a named subsystem" in text + assert "Temporally ground every claim" in text + assert "Attribute every claim" in text + assert "Event-style, past tense" in text + assert "Name things concretely" in text + + def test_renders_contrastive_examples(self): + # Two contrastive bad/good pairs must appear in step 2's body: + # one decision pair (Redis session storage), one lesson pair + # (Alembic migration). Examples are general-purpose, not + # koan-specific. + text = "\n".join(curation.step_guidance(2, _ctx()).instructions) + assert '<example type="decision-bad">' in text + assert '<example type="decision-good">' in text + assert '<example type="lesson-bad">' in text + assert '<example type="lesson-good">' in text + # Decision good-example sentinel: + assert "Redis 7.2" in text + # Lesson good-example sentinel: + assert "Alembic" in text + # Examples must NOT reference koan itself. + assert "koan" not in text.lower() or "koan_" in text # tool names OK + # "What changed between bad and good" explanations must follow each pair. + assert text.count("What changed between bad and good") == 2 + + def test_renders_6_substep_loop(self): + # The per-batch loop has 6 committed sub-operations in order: + # Draft -> Self-critique -> Revise -> Yield -> Apply -> Cross off. + text = "\n".join(curation.step_guidance(2, _ctx()).instructions) + for header in ( + "### A. Draft", + "### B. Self-critique", + "### C. Revise", + "### D. Yield", + "### E. Apply", + "### F. Cross off", + ): + assert header in text, f"missing substep header: {header!r}" + # The critical anti-simulated-refinement guardrails. + assert "Do not collapse substeps" in text + assert "Do not skip this substep" in text + + def test_renders_draft_quality_checklist(self): + # The 5-item checklist must be present as a schema the orchestrator + # can apply per-draft in substep B. + text = "\n".join(curation.step_guidance(2, _ctx()).instructions) + assert "Draft-quality checklist" in text + assert "PASS / FAIL" in text + # The checklist items map 1-to-1 onto the 5 writing discipline rules. + for item in ( + "Opens with named subsystem", + "Contains absolute date", + "Contains attribution", + "Event-style, past tense", + "Concrete naming", + ): + assert item in text, f"missing checklist item: {item!r}" + + def test_includes_anticipatory_tool_call_check(self): + # The tool-call anticipatory check from the previous round is + # preserved (renamed to "Anticipatory tool-call check" to + # distinguish from the new draft-quality gate in substeps B/C). text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - assert "Anticipatory check" in text - assert "did you call" in text.lower() or "did you call `koan_memorize`" in text.lower() or "Did you call" in text + assert "Anticipatory tool-call check" in text + assert "Did you call" in text # the verification question def test_wrap_up_calls_memory_status(self): # Wrap-up (folded in from former step 3) calls koan_memory_status From 8950ca3c2c4da71f70179e0ea2d15c644b354429 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 16 Apr 2026 14:21:09 +0700 Subject: [PATCH 386/412] feat: stream Claude tool-use input deltas --- koan/lib/partial_json.py | 12 +++ koan/runners/base.py | 7 +- koan/runners/claude.py | 77 ++++++++++++++++++- pyproject.toml | 1 + tests/test_runners.py | 157 ++++++++++++++++++++++++++++++++++++--- uv.lock | 11 +++ 6 files changed, 250 insertions(+), 15 deletions(-) create mode 100644 koan/lib/partial_json.py diff --git a/koan/lib/partial_json.py b/koan/lib/partial_json.py new file mode 100644 index 0000000..6744f65 --- /dev/null +++ b/koan/lib/partial_json.py @@ -0,0 +1,12 @@ +from json_repair import repair_json + + +def parse_partial(buffer: str) -> dict | None: + """Lenient parser for truncated JSON from streaming input_json_delta fragments.""" + if not buffer.strip(): + return None + try: + repaired = repair_json(buffer, return_objects=True) + return repaired if isinstance(repaired, dict) else None + except (ValueError, TypeError): + return None diff --git a/koan/runners/base.py b/koan/runners/base.py index db58b5e..61dc817 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -11,12 +11,17 @@ @dataclass(kw_only=True) class StreamEvent: - type: Literal["token_delta", "turn_complete", "tool_call", "thinking", "assistant_text"] + type: Literal[ + "token_delta", "turn_complete", "tool_call", "thinking", "assistant_text", + "tool_start", "tool_input_delta", "tool_stop", + ] content: str | None = None is_thinking: bool = False tool_name: str | None = None tool_args: dict | None = None summary: str | None = None + tool_use_id: str | None = None + block_index: int | None = None @dataclass(kw_only=True) diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 200f796..cc40bb4 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -4,11 +4,22 @@ from __future__ import annotations import json +from dataclasses import dataclass, field from pathlib import Path +from ..lib.partial_json import parse_partial from ..types import AgentInstallation, ModelInfo, ThinkingMode from .base import KOAN_MCP_TOOLS, RunnerDiagnostic, RunnerError, StreamEvent + +@dataclass +class _ToolUseAccumulator: + tool_name: str + raw_name: str + tool_use_id: str + buffer: list[str] = field(default_factory=list) + latest_draft: dict | None = None + # Map internal thinking mode names to Claude CLI --effort values. _EFFORT_MAP: dict[ThinkingMode, str] = { "low": "low", @@ -75,6 +86,7 @@ class ClaudeRunner: def __init__(self, *, subagent_dir: str) -> None: self.subagent_dir = subagent_dir self._saw_stream_events = False + self._tool_accumulators: dict[int, _ToolUseAccumulator] = {} def list_models(self, binary: str) -> list[ModelInfo]: return [ @@ -172,12 +184,33 @@ def _parse_stream_event(self, data: dict) -> list[StreamEvent]: if not isinstance(inner, dict): return [] inner_type = inner.get("type") + if inner_type == "message_start": - # New assistant turn — reset the flag so that if this turn - # doesn't produce content_block_delta events (e.g. after a - # long MCP call), the assistant message fallback kicks in. self._saw_stream_events = False + self._tool_accumulators = {} + return [] + + if inner_type == "content_block_start": + block = inner.get("content_block", {}) + if block.get("type") == "tool_use": + idx = inner.get("index", -1) + raw_name = block.get("name", "") + canonical = _normalize_tool_name(raw_name) + tool_use_id = block.get("id", "") + self._tool_accumulators[idx] = _ToolUseAccumulator( + tool_name=canonical or raw_name, + raw_name=raw_name, + tool_use_id=tool_use_id, + ) + self._saw_stream_events = True + return [StreamEvent( + type="tool_start", + tool_name=canonical, + tool_use_id=tool_use_id, + block_index=idx, + )] return [] + if inner_type == "content_block_delta": self._saw_stream_events = True delta = inner.get("delta", {}) @@ -186,6 +219,41 @@ def _parse_stream_event(self, data: dict) -> list[StreamEvent]: return [StreamEvent(type="thinking", is_thinking=True, content=delta.get("thinking", ""))] if delta_type == "text_delta": return [StreamEvent(type="token_delta", content=delta.get("text", ""))] + if delta_type == "input_json_delta": + idx = inner.get("index", -1) + partial = delta.get("partial_json", "") + acc = self._tool_accumulators.get(idx) + if acc is not None: + acc.buffer.append(partial) + acc.latest_draft = parse_partial("".join(acc.buffer)) + return [StreamEvent( + type="tool_input_delta", + content=partial, + tool_args=acc.latest_draft if acc else None, + block_index=idx, + )] + return [] + + if inner_type == "content_block_stop": + idx = inner.get("index", -1) + acc = self._tool_accumulators.pop(idx, None) + if acc is not None: + full_json = "".join(acc.buffer) + try: + args = json.loads(full_json) if full_json else {} + except json.JSONDecodeError: + args = acc.latest_draft or {} + summary = _extract_tool_summary(acc.tool_name, args) + return [StreamEvent( + type="tool_stop", + tool_name=acc.tool_name, + tool_args=args, + summary=summary, + tool_use_id=acc.tool_use_id, + block_index=idx, + )] + return [] + return [] def _parse_assistant(self, data: dict) -> list[StreamEvent]: @@ -205,9 +273,10 @@ def _parse_assistant(self, data: dict) -> list[StreamEvent]: continue block_type = block.get("type") if block_type == "tool_use": + if self._saw_stream_events: + continue raw_name = block.get("name") canonical = _normalize_tool_name(raw_name) - # Drop koan MCP tool events -- the MCP endpoint is authoritative if canonical in KOAN_MCP_TOOLS: continue args = block.get("input") or {} diff --git a/pyproject.toml b/pyproject.toml index 236e0b8..1a666db 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,6 +10,7 @@ dependencies = [ "jsonpatch", "pyyaml", "google-genai>=1.0", + "json-repair>=0.59.4", ] [project.scripts] diff --git a/tests/test_runners.py b/tests/test_runners.py index 9b7fb90..a16eb0e 100644 --- a/tests/test_runners.py +++ b/tests/test_runners.py @@ -66,27 +66,23 @@ def test_stream_event_text_delta(self): evts = self.runner.parse_stream_event(line) assert evts == [StreamEvent(type="token_delta", content="hello")] - def test_stream_event_suppresses_assistant_text(self): - """Once stream_events are seen, assistant text/thinking blocks are skipped.""" - # First: a stream_event sets the flag + def test_stream_event_suppresses_assistant_text_and_tool_use(self): + """Once stream_events are seen, assistant text/thinking/tool_use blocks are skipped.""" delta_line = json.dumps({ "type": "stream_event", "event": {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "hi"}}, }) self.runner.parse_stream_event(delta_line) - # Then: assistant message with text and tool_use msg_line = self._msg([ {"type": "text", "text": "hi"}, {"type": "tool_use", "name": "bash", "input": {"cmd": "ls"}}, ]) evts = self.runner.parse_stream_event(msg_line) - # text is skipped for streaming (already streamed), but assistant_text still emitted; - # tool_use is preserved - assert len(evts) == 2 - assert evts[0].type == "tool_call" - assert evts[1].type == "assistant_text" - assert evts[1].content == "hi" + # Both text and tool_use are skipped; only assistant_text remains + assert len(evts) == 1 + assert evts[0].type == "assistant_text" + assert evts[0].content == "hi" def test_result_success(self): line = json.dumps({"type": "result", "subtype": "success", "result": "done"}) @@ -143,6 +139,147 @@ def test_multi_block_non_dict_block_skipped(self): assert evts == [StreamEvent(type="token_delta", content="valid"), StreamEvent(type="assistant_text", content="valid")] +# -- ClaudeRunner: streaming tool_use events ----------------------------------- + +class TestClaudeRunnerStreamingToolUse: + def setup_method(self): + self.runner = ClaudeRunner(subagent_dir="/tmp/test") + + def _stream_event(self, inner: dict) -> str: + return json.dumps({"type": "stream_event", "event": inner}) + + def test_content_block_start_tool_use_emits_tool_start(self): + line = self._stream_event({ + "type": "content_block_start", "index": 1, + "content_block": {"type": "tool_use", "id": "toolu_01", "name": "Write", "input": {}}, + }) + evts = self.runner.parse_stream_event(line) + assert len(evts) == 1 + assert evts[0].type == "tool_start" + assert evts[0].tool_name == "write" + assert evts[0].tool_use_id == "toolu_01" + assert evts[0].block_index == 1 + + def test_input_json_delta_emits_tool_input_delta(self): + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_start", "index": 1, + "content_block": {"type": "tool_use", "id": "toolu_01", "name": "Write", "input": {}}, + })) + line = self._stream_event({ + "type": "content_block_delta", "index": 1, + "delta": {"type": "input_json_delta", "partial_json": '{"file_pa'}, + }) + evts = self.runner.parse_stream_event(line) + assert len(evts) == 1 + assert evts[0].type == "tool_input_delta" + assert evts[0].content == '{"file_pa' + assert evts[0].block_index == 1 + + def test_content_block_stop_emits_tool_stop_with_assembled_args(self): + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_start", "index": 1, + "content_block": {"type": "tool_use", "id": "toolu_01", "name": "Bash", "input": {}}, + })) + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_delta", "index": 1, + "delta": {"type": "input_json_delta", "partial_json": '{"command":'}, + })) + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_delta", "index": 1, + "delta": {"type": "input_json_delta", "partial_json": '"ls -la"}'}, + })) + evts = self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_stop", "index": 1, + })) + assert len(evts) == 1 + assert evts[0].type == "tool_stop" + assert evts[0].tool_name == "bash" + assert evts[0].tool_args == {"command": "ls -la"} + assert evts[0].summary == "ls -la" + + def test_streaming_suppresses_assistant_tool_use(self): + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_start", "index": 1, + "content_block": {"type": "tool_use", "id": "toolu_01", "name": "Bash", "input": {}}, + })) + msg_line = json.dumps({ + "type": "assistant", + "message": {"content": [ + {"type": "tool_use", "name": "Bash", "input": {"command": "ls"}}, + {"type": "text", "text": "done"}, + ]}, + }) + evts = self.runner.parse_stream_event(msg_line) + types = [e.type for e in evts] + assert "tool_call" not in types + assert "assistant_text" in types + + def test_message_start_resets_accumulators(self): + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_start", "index": 1, + "content_block": {"type": "tool_use", "id": "toolu_01", "name": "Write", "input": {}}, + })) + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_delta", "index": 1, + "delta": {"type": "input_json_delta", "partial_json": '{"file'}, + })) + self.runner.parse_stream_event(self._stream_event({"type": "message_start"})) + stop_evts = self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_stop", "index": 1, + })) + assert len(stop_evts) == 0 + + def test_koan_tools_not_filtered_in_streaming(self): + line = self._stream_event({ + "type": "content_block_start", "index": 0, + "content_block": {"type": "tool_use", "id": "toolu_02", "name": "koan_yield", "input": {}}, + }) + evts = self.runner.parse_stream_event(line) + assert len(evts) == 1 + assert evts[0].type == "tool_start" + assert evts[0].tool_name == "koan_yield" + + def test_parallel_tool_blocks(self): + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_start", "index": 1, + "content_block": {"type": "tool_use", "id": "toolu_a", "name": "Read", "input": {}}, + })) + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_start", "index": 2, + "content_block": {"type": "tool_use", "id": "toolu_b", "name": "Bash", "input": {}}, + })) + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_delta", "index": 1, + "delta": {"type": "input_json_delta", "partial_json": '{"file_path":"/a.txt"}'}, + })) + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_delta", "index": 2, + "delta": {"type": "input_json_delta", "partial_json": '{"command":"pwd"}'}, + })) + stop1 = self.runner.parse_stream_event(self._stream_event({"type": "content_block_stop", "index": 1})) + stop2 = self.runner.parse_stream_event(self._stream_event({"type": "content_block_stop", "index": 2})) + assert stop1[0].tool_name == "read" + assert stop1[0].tool_args == {"file_path": "/a.txt"} + assert stop2[0].tool_name == "bash" + assert stop2[0].tool_args == {"command": "pwd"} + + def test_malformed_json_uses_lenient_fallback(self): + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_start", "index": 0, + "content_block": {"type": "tool_use", "id": "toolu_x", "name": "Write", "input": {}}, + })) + self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_delta", "index": 0, + "delta": {"type": "input_json_delta", "partial_json": '{"file_path": "/tmp/x.html", "content": "<html'}, + })) + evts = self.runner.parse_stream_event(self._stream_event({ + "type": "content_block_stop", "index": 0, + })) + assert len(evts) == 1 + assert evts[0].type == "tool_stop" + assert evts[0].tool_args.get("file_path") == "/tmp/x.html" + + # -- CodexRunner: parse_stream_event ------------------------------------------- class TestCodexRunnerParseStreamEvent: diff --git a/uv.lock b/uv.lock index dea95ec..a4c9dc0 100644 --- a/uv.lock +++ b/uv.lock @@ -612,6 +612,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b2/a3/e137168c9c44d18eff0376253da9f1e9234d0239e0ee230d2fee6cea8e55/jeepney-0.9.0-py3-none-any.whl", hash = "sha256:97e5714520c16fc0a45695e5365a2e11b81ea79bba796e26f9f1d178cb182683", size = 49010, upload-time = "2025-02-27T18:51:00.104Z" }, ] +[[package]] +name = "json-repair" +version = "0.59.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/32/41/4ae9c6e711647a41b4e0c04bce815113ce9c0286eff6dc6fb86979b2fb9f/json_repair-0.59.4.tar.gz", hash = "sha256:559ca1828f6f566530663cd96d64bee29f8282b9d2ff0e661e05fa87b4171ab3", size = 47624, upload-time = "2026-04-15T06:48:40.776Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/74/c4/ec3068436d2275731539b7a43fbc947f502bc3fe149856a5d00368c7b087/json_repair-0.59.4-py3-none-any.whl", hash = "sha256:46052e646bc0b0c39db672ebbf732f774f3c1a5bde81a54f0b0e19d3af4f45cd", size = 46697, upload-time = "2026-04-15T06:48:39.61Z" }, +] + [[package]] name = "jsonpatch" version = "1.33" @@ -708,6 +717,7 @@ dependencies = [ { name = "aiofiles" }, { name = "fastmcp" }, { name = "google-genai" }, + { name = "json-repair" }, { name = "jsonpatch" }, { name = "pyyaml" }, { name = "starlette" }, @@ -725,6 +735,7 @@ requires-dist = [ { name = "aiofiles" }, { name = "fastmcp" }, { name = "google-genai", specifier = ">=1.0" }, + { name = "json-repair", specifier = ">=0.59.4" }, { name = "jsonpatch" }, { name = "pyyaml" }, { name = "starlette" }, From 7a4ca7f52dbb5cd085cc93e9d4ab71fc8cff5be2 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 16 Apr 2026 14:22:03 +0700 Subject: [PATCH 387/412] feat: surface tool lifecycle events in activity stream --- frontend/src/App.tsx | 22 +++++++++++++--- koan/events.py | 11 ++++++++ koan/projections.py | 51 ++++++++++++++++++++++++++++++++++++ koan/subagent.py | 62 +++++++++++++++++++++++++++++++++++++------- 4 files changed, 133 insertions(+), 13 deletions(-) diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 12a8bd2..123c6d6 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -132,8 +132,19 @@ function ConnectedScoutBar() { // --------------------------------------------------------------------------- // Orchestration tools whose effects are visible through other molecules -// (YieldPanel, StepHeader, PhaseMarker). They should not render as rows. -const SUPPRESSED_TOOLS = new Set(['koan_yield', 'koan_complete_step', 'koan_set_phase']) +// (StepHeader, PhaseMarker). They should not render as rows. +const SUPPRESSED_TOOLS = new Set(['koan_complete_step', 'koan_set_phase']) + +const KOAN_TOOL_LABELS: Record<string, string> = { + koan_request_scouts: 'Dispatching scouts', + koan_ask_question: 'Asking question', + koan_yield: 'Preparing response', + koan_request_executor: 'Starting executor', + koan_select_story: 'Selecting story', + koan_complete_story: 'Completing story', + koan_retry_story: 'Retrying story', + koan_skip_story: 'Skipping story', +} function renderEntry(entry: ConversationEntry, i: number) { switch (entry.type) { @@ -153,9 +164,12 @@ function renderEntry(entry: ConversationEntry, i: number) { return <ToolCallRow key={i} tool="grep" command={entry.pattern} status={entry.inFlight ? 'running' : 'done'} /> case 'tool_ls': return <ToolCallRow key={i} tool="ls" command={entry.path} status={entry.inFlight ? 'running' : 'done'} /> - case 'tool_generic': + case 'tool_generic': { if (SUPPRESSED_TOOLS.has(entry.toolName)) return null - return <ToolCallRow key={i} tool={entry.toolName} command={entry.summary} status={entry.inFlight ? 'running' : 'done'} /> + const label = KOAN_TOOL_LABELS[entry.toolName] ?? entry.toolName + const cmd = entry.toolName in KOAN_TOOL_LABELS ? '' : entry.summary + return <ToolCallRow key={i} tool={label} command={cmd} status={entry.inFlight ? 'running' : 'done'} /> + } case 'step': return <StepHeader key={i} stepNumber={entry.step} totalSteps={entry.totalSteps ?? 0} stepName={entry.stepName} /> case 'debug_step_guidance': diff --git a/koan/events.py b/koan/events.py index 5518827..20ddaf0 100644 --- a/koan/events.py +++ b/koan/events.py @@ -97,6 +97,17 @@ def build_tool_called( } +def build_tool_started(call_id: str, tool: str) -> dict: + return {"call_id": call_id, "tool": tool} + + +def build_tool_stopped(call_id: str, tool: str, summary: str = "") -> dict: + payload: dict = {"call_id": call_id, "tool": tool} + if summary: + payload["summary"] = summary + return payload + + # -- Typed tool event builders (recognized tools with extracted metadata) ----- def build_tool_read(call_id: str, file: str, lines: str = "") -> dict: diff --git a/koan/projections.py b/koan/projections.py index dd4ca10..e422852 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -42,6 +42,8 @@ "workflow_selected", "scout_queued", # Activity + "tool_started", + "tool_stopped", "tool_called", "tool_completed", "tool_read", @@ -704,6 +706,55 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: "run": _update_agent_conversation(projection.run, agent_id, new_conv), }) + case "tool_started": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + tool_name = payload.get("tool", "") + call_id = payload.get("call_id", "") + last_tool = tool_name + new_conv = _flush_conversation(agent.conversation) + new_entry = ToolGenericEntry( + call_id=call_id, + in_flight=True, + tool_name=tool_name, + summary="", + ) + new_conv = new_conv.model_copy(update={ + "entries": [*new_conv.entries, new_entry], + }) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv, + last_tool=last_tool), + }) + + case "tool_stopped": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + call_id = payload.get("call_id", "") + summary = payload.get("summary", "") + tool_name = payload.get("tool", "") + last_tool = f"{tool_name} {summary}".strip() if summary else tool_name + new_entries = [] + for entry in agent.conversation.entries: + if isinstance(entry, BaseToolEntry) and entry.call_id == call_id: + update: dict = {"in_flight": False} + if summary and isinstance(entry, ToolGenericEntry): + update["summary"] = summary + new_entries.append(entry.model_copy(update=update)) + else: + new_entries.append(entry) + new_conv = agent.conversation.model_copy(update={"entries": new_entries}) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv, + last_tool=last_tool), + }) + case "tool_called": if projection.run is None or not agent_id: return projection diff --git a/koan/subagent.py b/koan/subagent.py index e313990..8e5fb74 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -26,6 +26,8 @@ build_tool_grep, build_tool_ls, build_tool_read, + build_tool_started, + build_tool_stopped, build_tool_write, ) from .logger import get_logger @@ -218,11 +220,17 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None # Falls back to subagent_dir if project_dir is unavailable. spawn_cwd = task.get("project_dir") or subagent_dir log.info("spawning %s (agent_id=%s) cwd=%s: %s", role, agent_id, spawn_cwd, " ".join(cmd)) + # limit= raises the asyncio StreamReader per-line buffer above its 64 KB + # default. A single stream-json event from the child CLI (long thinking + # block, fat tool result, large assistant content envelope) routinely + # exceeds 64 KB; readline() then raises LimitOverrunError and the scout's + # output becomes unreadable mid-run. proc = await asyncio.create_subprocess_exec( *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, cwd=spawn_cwd, + limit=4 * 1024 * 1024, ) app_state._active_processes[agent_id] = proc @@ -231,13 +239,14 @@ async def stream_stdout(): assert proc.stdout is not None last_tool_name: str | None = None last_call_id: str | None = None + streaming_call_ids: dict[int, tuple[str, str]] = {} async for raw in proc.stdout: line = raw.decode("utf-8", errors="replace").rstrip("\n") events = runner.parse_stream_event(line) for ev in events: - # Close in-flight tool when the LLM moves on to thinking - # or text output -- those signal the previous tool is done. + # Close implicit in-flight tool (non-streaming path) when + # the LLM moves on to thinking or text output. if ev.type in ("token_delta", "thinking") and last_call_id is not None: store.push_event( "tool_completed", @@ -247,7 +256,38 @@ async def stream_stdout(): last_call_id = None last_tool_name = None - if ev.type == "token_delta": + if ev.type == "tool_start": + if last_call_id is not None and last_tool_name is not None: + store.push_event( + "tool_completed", + build_tool_completed(last_call_id, last_tool_name), + agent_id=agent_id, + ) + last_call_id = None + last_tool_name = None + call_id = str(uuid.uuid4()) + tool_name = ev.tool_name or "tool" + block_idx = ev.block_index if ev.block_index is not None else -1 + streaming_call_ids[block_idx] = (call_id, tool_name) + store.push_event( + "tool_started", + build_tool_started(call_id, tool_name), + agent_id=agent_id, + ) + elif ev.type == "tool_input_delta": + pass + elif ev.type == "tool_stop": + block_idx = ev.block_index if ev.block_index is not None else -1 + pair = streaming_call_ids.pop(block_idx, None) + if pair is not None: + call_id, tool_name = pair + summary = ev.summary or "" + store.push_event( + "tool_stopped", + build_tool_stopped(call_id, tool_name, summary), + agent_id=agent_id, + ) + elif ev.type == "token_delta": agent.token_count["received"] = agent.token_count.get("received", 0) + len(ev.content or "") store.push_event("stream_delta", {"delta": ev.content or ""}, agent_id=agent_id) elif ev.type == "thinking": @@ -256,19 +296,16 @@ async def stream_stdout(): if ev.content: agent.final_response = ev.content elif ev.type == "tool_call": - # Close previous in-flight tool if last_call_id is not None and last_tool_name is not None: store.push_event( "tool_completed", build_tool_completed(last_call_id, last_tool_name), agent_id=agent_id, ) - # Open new tool call — emit typed event for recognized tools call_id = str(uuid.uuid4()) tool_name = ev.tool_name or "tool" summary = ev.summary or "" if tool_name == "read": - # Separate file path from optional line range (e.g. "foo.py:10-20") file_part, lines_part = summary, "" if ":" in summary: head, tail = summary.rsplit(":", 1) @@ -298,11 +335,18 @@ async def stream_stdout(): last_call_id = call_id last_tool_name = tool_name elif ev.type == "turn_complete": - # Dropped -- stream_cleared at stdout EOF covers end-of-stream pass - # All other unrecognized types are silently dropped - # Close any in-flight tool at stdout EOF + # Close any in-flight streaming tools at stdout EOF + for _idx, (cid, tname) in streaming_call_ids.items(): + store.push_event( + "tool_stopped", + build_tool_stopped(cid, tname), + agent_id=agent_id, + ) + streaming_call_ids.clear() + + # Close any implicit in-flight tool at stdout EOF if last_call_id is not None and last_tool_name is not None: store.push_event( "tool_completed", From a1d52124a4e79bd32144dd4295605cc5f33ff94c Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 16 Apr 2026 14:22:16 +0700 Subject: [PATCH 388/412] chore: update default memory model alias --- koan/memory/llm.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/koan/memory/llm.py b/koan/memory/llm.py index 33b204e..6149a59 100644 --- a/koan/memory/llm.py +++ b/koan/memory/llm.py @@ -8,7 +8,7 @@ from google import genai from google.genai import types -DEFAULT_MODEL = "gemini-3-flash-lite" +DEFAULT_MODEL = "gemini-flash-lite-latest" def _api_key() -> str: From 5d5b209345c4105d62b3e8c0fa045629e01b5770 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 16 Apr 2026 15:41:37 +0700 Subject: [PATCH 389/412] chore: add structured logging to memory operations --- koan/memory/llm.py | 14 +++++++++++--- koan/memory/store.py | 28 +++++++++++++++++++++++++--- koan/web/mcp_endpoint.py | 7 +++++++ 3 files changed, 43 insertions(+), 6 deletions(-) diff --git a/koan/memory/llm.py b/koan/memory/llm.py index 6149a59..6fd51e6 100644 --- a/koan/memory/llm.py +++ b/koan/memory/llm.py @@ -8,6 +8,10 @@ from google import genai from google.genai import types +from ..logger import get_logger + +log = get_logger("memory.llm") + DEFAULT_MODEL = "gemini-flash-lite-latest" @@ -28,12 +32,14 @@ async def generate(prompt: str, system: str = "", max_tokens: int = 1024) -> str """Call Gemini and return the text response. Configuration: - - Model: via env var KOAN_LLM_MODEL (default "gemini-3-flash-lite") + - Model: via env var KOAN_LLM_MODEL (default "gemini-flash-lite-latest") - API key: via env var GEMINI_API_KEY or GOOGLE_API_KEY - Temperature: 0.0 (deterministic for summaries) Raises RuntimeError if the API key is not set or the call fails. """ + model = _model() + log.info("generate model=%s prompt_len=%d system_len=%d max_tokens=%d", model, len(prompt), len(system), max_tokens) client = genai.Client(api_key=_api_key()) config = types.GenerateContentConfig( system_instruction=system or None, @@ -41,8 +47,10 @@ async def generate(prompt: str, system: str = "", max_tokens: int = 1024) -> str max_output_tokens=max_tokens, ) response = await client.aio.models.generate_content( - model=_model(), + model=model, contents=prompt, config=config, ) - return response.text or "" + text = response.text or "" + log.info("generate complete response_len=%d", len(text)) + return text diff --git a/koan/memory/store.py b/koan/memory/store.py index 7b39f00..e62805e 100644 --- a/koan/memory/store.py +++ b/koan/memory/store.py @@ -5,10 +5,13 @@ import re from pathlib import Path +from ..logger import get_logger from .types import MemoryEntry, MemoryType from .parser import parse_entry from .writer import write_entry as _write_entry, update_entry as _update_entry +log = get_logger("memory.store") + _ENTRY_PATTERN = re.compile(r"^(\d{4})-.*\.md$") @@ -23,6 +26,7 @@ def __init__(self, project_root: str | Path) -> None: def init(self) -> None: """Create the memory directory if it doesn't exist.""" + log.debug("init memory_dir=%s", self._memory_dir) self._memory_dir.mkdir(parents=True, exist_ok=True) # -- Query ------------------------------------------------------------------ @@ -38,19 +42,26 @@ def _iter_entry_paths(self) -> list[Path]: def list_entries(self, type: MemoryType | None = None) -> list[MemoryEntry]: """List entries, optionally filtered by type. Sorted by sequence number.""" - entries = [parse_entry(p) for p in self._iter_entry_paths()] + paths = self._iter_entry_paths() + log.debug("list_entries type=%s found %d file(s)", type or "*", len(paths)) + entries = [parse_entry(p) for p in paths] if type is not None: entries = [e for e in entries if e.type == type] + log.debug("list_entries filtered to %d entry/entries of type '%s'", len(entries), type) return entries def get_entry(self, number: int) -> MemoryEntry | None: """Find and parse a specific entry by global sequence number.""" if not self._memory_dir.is_dir(): + log.debug("get_entry(%d) memory_dir does not exist", number) return None prefix = f"{number:04d}-" for p in self._memory_dir.iterdir(): if p.is_file() and p.name.startswith(prefix) and p.name.endswith(".md"): - return parse_entry(p) + entry = parse_entry(p) + log.debug("get_entry(%d) found %s type=%s", number, p.name, entry.type) + return entry + log.debug("get_entry(%d) not found", number) return None def entry_count(self, type: MemoryType | None = None) -> int: @@ -70,6 +81,7 @@ def add_entry( related: list[str] | None = None, ) -> MemoryEntry: """Create a new entry, write it to disk, return with file_path set.""" + log.info("add_entry type=%s title=%r body_len=%d related=%s", type, title, len(body), related or []) entry = MemoryEntry( title=title, type=type, @@ -78,17 +90,22 @@ def add_entry( ) path = _write_entry(entry, self._memory_dir) entry.file_path = path + log.info("add_entry written -> %s", path.name) return entry def update_entry(self, entry: MemoryEntry) -> None: """Write an entry back to its existing file_path.""" + log.info("update_entry id=%s type=%s title=%r", entry.file_path.name if entry.file_path else "?", entry.type, entry.title) _update_entry(entry) + log.debug("update_entry written -> %s", entry.file_path) def forget_entry(self, entry: MemoryEntry) -> None: """Delete an entry file from disk. Git preserves history.""" if entry.file_path is None: raise ValueError("entry has no file_path") + log.info("forget_entry %s type=%s title=%r", entry.file_path.name, entry.type, entry.title) entry.file_path.unlink() + log.debug("forget_entry deleted %s", entry.file_path) # -- Summary ---------------------------------------------------------------- @@ -96,11 +113,16 @@ def get_summary(self) -> str | None: """Return the content of summary.md if it exists.""" p = self._memory_dir / "summary.md" if p.is_file(): - return p.read_text("utf-8") + text = p.read_text("utf-8") + log.debug("get_summary loaded %d chars from %s", len(text), p) + return text + log.debug("get_summary no summary.md found") return None async def regenerate_summary(self, project_name: str = "") -> None: """Regenerate summary.md from all current entries.""" + log.info("regenerate_summary starting (project_name=%r, entry_count=%d)", project_name, self.entry_count()) from .summarize import regenerate_summary await regenerate_summary(self, project_name=project_name) + log.info("regenerate_summary complete") diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index b1f9bad..832d99b 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -971,6 +971,7 @@ async def koan_memorize( store = _get_memory_store() if entry_id is None: + log.info("koan_memorize CREATE type=%s title=%r body_len=%d", type, title, len(body)) entry = store.add_entry( type=type, # type: ignore[arg-type] title=title, @@ -978,6 +979,7 @@ async def koan_memorize( related=related or [], ) new_id = _entry_id_from_path(entry.file_path.name) if entry.file_path else None + log.info("koan_memorize CREATED entry_id=%s file=%s", new_id, entry.file_path.name if entry.file_path else "?") result_str = json.dumps({ "op": "created", "type": type, @@ -987,6 +989,7 @@ async def koan_memorize( "modified": entry.modified, }) else: + log.info("koan_memorize UPDATE entry_id=%d type=%s title=%r", entry_id, type, title) existing = store.get_entry(entry_id) if existing is None: raise ToolError(json.dumps({ @@ -1006,6 +1009,7 @@ async def koan_memorize( if related is not None: existing.related = related store.update_entry(existing) + log.info("koan_memorize UPDATED entry_id=%d file=%s", entry_id, existing.file_path.name if existing.file_path else "?") result_str = json.dumps({ "op": "updated", "type": type, @@ -1045,6 +1049,7 @@ async def koan_forget(entry_id: int, type: str | None = None) -> str: if type is not None: _validate_memory_type(type) + log.info("koan_forget entry_id=%d type=%s", entry_id, type or "*") store = _get_memory_store() existing = store.get_entry(entry_id) if existing is None: @@ -1061,7 +1066,9 @@ async def koan_forget(entry_id: int, type: str | None = None) -> str: ), })) path_str = str(existing.file_path) if existing.file_path else None + log.info("koan_forget DELETING %s type=%s title=%r", existing.file_path.name if existing.file_path else "?", existing.type, existing.title) store.forget_entry(existing) + log.info("koan_forget DELETED entry_id=%d", entry_id) result_str = json.dumps({ "op": "forgotten", "type": existing.type, From b6fbf9ed043938fc5f1bd8744058d479e86b60ac Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 16 Apr 2026 15:42:00 +0700 Subject: [PATCH 390/412] fix: surface memory summary regeneration failures --- koan/memory/summarize.py | 6 +++++- koan/web/mcp_endpoint.py | 27 ++++++++++++++++++++++----- tests/memory/test_summarize.py | 8 +++++--- 3 files changed, 32 insertions(+), 9 deletions(-) diff --git a/koan/memory/summarize.py b/koan/memory/summarize.py index 1d0149d..8be35ec 100644 --- a/koan/memory/summarize.py +++ b/koan/memory/summarize.py @@ -52,6 +52,7 @@ async def generate_summary( entries = store.list_entries() if not entries: + log.debug("generate_summary: no entries, writing empty summary") summary = "No memory entries exist yet." store._memory_dir.mkdir(parents=True, exist_ok=True) (store._memory_dir / "summary.md").write_text(summary + "\n", "utf-8") @@ -65,15 +66,18 @@ async def generate_summary( f"{context}" ) + log.info("generate_summary: sending %d entries (%d chars) to LLM", len(entries), len(context)) try: summary = await generate(prompt, system=_SUMMARY_SYSTEM, max_tokens=2500) + log.info("generate_summary: LLM returned %d chars", len(summary)) except Exception: log.exception("LLM call failed for project summary generation") - summary = "Summary generation failed." + raise summary = summary.strip() store._memory_dir.mkdir(parents=True, exist_ok=True) (store._memory_dir / "summary.md").write_text(summary + "\n", "utf-8") + log.debug("generate_summary: wrote summary.md (%d chars)", len(summary)) return summary diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 832d99b..4f89368 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -1120,12 +1120,22 @@ async def koan_memory_status(type: str | None = None) -> str: if type is not None: _validate_memory_type(type) + log.info("koan_memory_status type=%s", type or "*") store = _get_memory_store() regenerated = False - if _summary_is_stale(store): - await store.regenerate_summary() - regenerated = True + regen_error: str | None = None + stale = _summary_is_stale(store) + log.debug("koan_memory_status summary_stale=%s", stale) + if stale: + log.info("koan_memory_status regenerating stale summary") + try: + await store.regenerate_summary() + regenerated = True + log.info("koan_memory_status summary regenerated") + except Exception: + log.exception("koan_memory_status summary regeneration failed") + regen_error = "Summary regeneration failed -- see server logs." summary = store.get_summary() or "" entries = store.list_entries(type=type) # type: ignore[arg-type] @@ -1142,12 +1152,19 @@ async def koan_memory_status(type: str | None = None) -> str: } for e in entries ] + log.info( + "koan_memory_status returning %d entries, summary_len=%d, regenerated=%s", + len(out_entries), len(summary), regenerated, + ) - result_str = json.dumps({ + result: dict = { "summary": summary, "entries": out_entries, "regenerated": regenerated, - }) + } + if regen_error: + result["error"] = regen_error + result_str = json.dumps(result) result_str = _drain_and_append_steering(result_str, agent) return result_str finally: diff --git a/tests/memory/test_summarize.py b/tests/memory/test_summarize.py index e97a61b..481670f 100644 --- a/tests/memory/test_summarize.py +++ b/tests/memory/test_summarize.py @@ -106,16 +106,18 @@ async def test_no_entries_produces_empty_summary(self, tmp_path): assert store.get_summary() is not None @pytest.mark.anyio - async def test_llm_failure_produces_fallback(self, tmp_path): + async def test_llm_failure_propagates(self, tmp_path): store = _populated_store(tmp_path) async def failing_generate(prompt, system="", max_tokens=1024): raise RuntimeError("API error") with patch("koan.memory.summarize.generate", side_effect=failing_generate): - summary = await generate_summary(store) + with pytest.raises(RuntimeError, match="API error"): + await generate_summary(store) - assert "failed" in summary.lower() + # summary.md must not be written on failure + assert not (store._memory_dir / "summary.md").exists() @pytest.mark.anyio async def test_forgotten_entry_not_in_prompt(self, tmp_path): From a329c8eeaba495ebe25b970406a871711c76cc99 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Thu, 16 Apr 2026 16:28:21 +0700 Subject: [PATCH 391/412] fix: tighten curation memory-entry guidance --- koan/phases/curation.py | 69 ++++++++++++++++++++++++++++------- tests/phases/test_curation.py | 15 ++++---- 2 files changed, 64 insertions(+), 20 deletions(-) diff --git a/koan/phases/curation.py b/koan/phases/curation.py index a7f66a6..18cb2ff 100644 --- a/koan/phases/curation.py +++ b/koan/phases/curation.py @@ -176,7 +176,7 @@ "Every entry is 100-500 tokens of **temporally grounded, attributed,\n" "event-style** prose -- a historical fact that stays true regardless\n" "of when it is read. The full rules, two contrastive bad/good\n" - "examples, and a 5-item self-validation checklist appear in step 2\n" + "examples, and a 6-item self-validation checklist appear in step 2\n" "(Memorize), rendered at the drafting moment. Do NOT skim the step 2\n" "examples -- your default register for technical content is timeless\n" "documentation prose, and the examples are the only thing that\n" @@ -188,17 +188,51 @@ "\n" "## What not to capture\n" "\n" - "- Implementation details derivable from reading the code, EXCEPT:\n" - " - The **rationale and rejected alternatives** behind architectural\n" - " decisions. These are NOT in code -- they are in the heads of the\n" - " people who made the choice, and in the conversations that\n" - " surfaced the choice. Capture them.\n" - " - The **lessons from prior workflows** -- corrected mistakes,\n" - " surprises, root causes of failures. These are not in code;\n" - " they are history. Capture them.\n" + "**Structural information** the agent encounters through normal code\n" + "reading should NOT be captured: file layout, API signatures, type\n" + "definitions, import paths, module structure, function names. The\n" + "agent's working context already includes this when it opens the\n" + "relevant files.\n" + "\n" + "**Behavioral knowledge** that needs proactive surfacing MUST be\n" + "captured, even when the knowledge also appears in a project\n" + "document (docs/, AGENTS.md, README.md, etc.). The RAG retrieval\n" + "layer indexes only memory entries -- it does not index project\n" + "files. If a lesson, decision, procedure, or constraint lives only\n" + "in a document, the RAG cannot surface it at the right moment.\n" + "The document is the source; the memory entry is the extraction.\n" + "Examples of behavioral knowledge that must be captured:\n" + "\n" + "- Rationale and rejected alternatives behind architectural\n" + " decisions -- these live in people's heads and conversations.\n" + "- Lessons from prior workflows -- corrected mistakes, surprises,\n" + " root causes of failures.\n" + "- Procedures and constraints for agents -- rules that govern\n" + " behavior but are not obvious from the code itself.\n" + "\n" + "Also do NOT capture:\n" "- Temporary implementation details that will not matter next week.\n" "- Opinions without grounding in project experience.\n" "- Anything already adequately captured (use NOOP, not a duplicate).\n" + "\n" + "## Self-contained entries (critical)\n" + "\n" + "A memory entry must contain the actual knowledge it captures, not\n" + "a reference to where the knowledge is written. Never produce\n" + "entries whose primary content is a pointer to another document.\n" + "\n" + "FAILS: \"docs/architecture.md documents 13 anti-patterns for\n" + "orchestrator prompt design.\"\n" + "\n" + "PASSES: One self-contained entry per anti-pattern, each with its\n" + "own rationale, context, and attribution, readable without opening\n" + "docs/architecture.md.\n" + "\n" + "If a source document contains multiple distinct pieces of\n" + "knowledge, each piece becomes its own independent entry. The RAG\n" + "retrieval layer does not dereference pointers; it only surfaces\n" + "the text of memory entries. Knowledge that is not in the entry's\n" + "body cannot reach the agent.\n" ) @@ -249,7 +283,7 @@ def _tools_this_step_block(current_step: int) -> list[str]: if current_step == 2: return [ "<tools_this_step>", - "Writing discipline, two contrastive examples, and a 5-item", + "Writing discipline, two contrastive examples, and a 6-item", "draft-quality checklist appear in this step's body below.", "Read them BEFORE drafting your first candidate.", "", @@ -515,7 +549,7 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: "", "### B. Self-critique", "", - "For each draft produced in substep A, run the 5-item draft-", + "For each draft produced in substep A, run the 6-item draft-", "quality checklist below. Output the checklist result PER", "DRAFT in this exact format:", "", @@ -525,6 +559,7 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: " 3. Contains attribution: PASS / FAIL", " 4. Event-style, past tense: PASS / FAIL", " 5. Concrete naming: PASS / FAIL", + " 6. Contains knowledge, not pointer: PASS / FAIL", "", " Draft 2 ({title}):", " ...", @@ -539,7 +574,7 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: "For every draft with any FAIL in its checklist, rewrite the", "entry completely. Do not patch in place -- rewrite it, using", "the GOOD example template as the target form. After each", - "rewrite, re-run the 5-item checklist on the revised draft.", + "rewrite, re-run the 6-item checklist on the revised draft.", "Loop until all 5 items PASS for all drafts in the batch.", "", "You MAY NOT proceed to substep D (Yield) while any draft in", @@ -570,7 +605,7 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: "", "## Draft-quality checklist (schema for substep B)", "", - "For each draft, verify all 5 items. Any FAIL means the draft", + "For each draft, verify all 6 items. Any FAIL means the draft", "cannot be yielded -- it must go back through substep C.", "", "**1. Opens with a named subsystem.**", @@ -606,6 +641,14 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: "FAILS; \"the BUILD_TARGET environment variable in", "deploy/production.env\" passes.", "", + "**6. Contains the knowledge, not a pointer.**", + "The entry body contains the actual knowledge -- rationale,", + "lesson, procedure, or context fact -- not a reference to where", + "the knowledge is written. Entries that read \"X documents Y\" or", + "\"X file defines Y\" FAIL. The entry must answer \"what is the", + "knowledge?\" directly in its body, readable without opening any", + "other file.", + "", "## Anticipatory tool-call check (BEFORE the wrap-up)", "", "After all batches have been processed, before you call", diff --git a/tests/phases/test_curation.py b/tests/phases/test_curation.py index 023e229..a925a34 100644 --- a/tests/phases/test_curation.py +++ b/tests/phases/test_curation.py @@ -53,14 +53,15 @@ def test_system_prompt_has_type_discrimination_tree(self): # Lesson trigger includes the user-correction case. assert "correct the agent" in sp - def test_system_prompt_derivable_rule_preserves_decisions(self): - # The "what not to capture" rule must explicitly preserve - # decisions' rationale and prior-workflow lessons, even when - # the resulting implementation is in code. + def test_system_prompt_behavioral_knowledge_must_be_captured(self): + # The "what not to capture" section must require behavioral + # knowledge (decisions, lessons, procedures) to be captured + # even when it also appears in project documents. sp = curation.SYSTEM_PROMPT - assert "EXCEPT" in sp - assert "rationale and rejected alternatives" in sp - assert "lessons from prior workflows" in sp + assert "Behavioral knowledge" in sp + assert "MUST be" in sp + assert "Rationale and rejected alternatives" in sp + assert "Lessons from prior workflows" in sp def test_system_prompt_enumerates_memory_tools(self): # Tools must be visible at the role layer. From 7fd7c51846562cb03536850e081ff45f10405e1c Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 17 Apr 2026 12:45:19 +0700 Subject: [PATCH 392/412] refactor: separate agent prompts from phase role context --- AGENTS.md | 48 ++++--- docs/architecture.md | 48 ++++--- docs/subagents.md | 158 ++++++++++++++++------- koan/phases/__init__.py | 36 +----- koan/phases/brief_writer.py | 2 +- koan/phases/core_flows.py | 2 +- koan/phases/cross_artifact_validation.py | 2 +- koan/phases/curation.py | 56 ++++++-- koan/phases/execute.py | 2 +- koan/phases/executor.py | 41 ++---- koan/phases/intake.py | 23 ++-- koan/phases/orchestrator.py | 2 +- koan/phases/plan_review.py | 2 +- koan/phases/plan_spec.py | 2 +- koan/phases/scout.py | 51 +------- koan/phases/tech_plan.py | 2 +- koan/phases/ticket_breakdown.py | 2 +- koan/prompts/__init__.py | 18 +++ koan/prompts/executor.py | 41 ++++++ koan/prompts/orchestrator.py | 83 ++++++++++++ koan/prompts/scout.py | 60 +++++++++ koan/subagent.py | 37 +++++- koan/web/mcp_endpoint.py | 10 +- tests/phases/test_curation.py | 22 ++-- tests/test_subagent.py | 2 +- 25 files changed, 506 insertions(+), 246 deletions(-) create mode 100644 koan/prompts/__init__.py create mode 100644 koan/prompts/executor.py create mode 100644 koan/prompts/orchestrator.py create mode 100644 koan/prompts/scout.py diff --git a/AGENTS.md b/AGENTS.md index 2a5e009..3a1ebc7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,6 +88,7 @@ Phase routing is driven by the orchestrator via `koan_set_phase` rather than the driver's routing loop. The driver still: + - Validates every phase transition (`is_valid_transition()` in the tool handler) - Updates `run-state.json` atomically - Emits projection events @@ -104,27 +105,40 @@ required successors. ## 4. Default-Deny Permissions -Every tool call passes through a role-based permission fence. Unknown roles -and tools are blocked. The orchestrator role uses **phase-aware permissions**: -available tools vary by `current_phase`. Planning-phase write access is -path-scoped to the run directory. +Two enforcement layers restrict what tools each agent can use: + +1. **CLI tool whitelist** (`CLAUDE_TOOL_WHITELISTS` in `subagent.py`) -- + controls which built-in tools exist in the model's context. Unlisted tools + are not presented to the model; it cannot call them. Agents should not have + access to tools they are never intended to need. +2. **MCP permission fence** (`check_permission()` in `permissions.py`) -- + gates koan MCP tool calls per role and phase. Unknown roles and tools are + blocked. The fence also supports step-level gating: `write` and `edit` are blocked during brief-generation step 1 (the read step). -**Orchestrator tool availability by phase:** - -| Tool | Available phases | -|------|-----------------| -| `koan_complete_step` | All phases | -| `koan_set_phase` | All phases (blocked mid-story during execution); accepts `"done"` as tombstone | -| `koan_yield` | All phases | -| `koan_ask_question` | All phases | -| `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `plan-spec`, `plan-review` | -| `koan_request_executor` | `execution`, `execute` | -| `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | `execution` only | -| `write`, `edit` (run_dir scoped) | All phases except `brief-generation` step 1 | -| `bash` | `execution`, `implementation-validation` | +**CLI tool whitelists (per agent type):** + +| Role | Built-in tools | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------- | +| orchestrator | `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `WebFetch`, `WebSearch` | +| executor | `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`, `TaskStop`, `TaskOutput` | +| scout | `Read`, `Bash`, `Glob`, `Grep` | + +**MCP permission fence -- orchestrator tool availability by phase:** + +| Tool | Available phases | +| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `koan_complete_step` | All phases | +| `koan_set_phase` | All phases (blocked mid-story during execution); accepts `"done"` as tombstone | +| `koan_yield` | All phases | +| `koan_ask_question` | All phases | +| `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `plan-spec`, `plan-review` | +| `koan_request_executor` | `execution`, `execute` | +| `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | `execution` only | +| `write`, `edit` (run_dir scoped) | All phases except `brief-generation` step 1 | +| `bash` | `execution`, `implementation-validation` | ## 5. Need-to-Know Prompts diff --git a/docs/architecture.md b/docs/architecture.md index cabc7c6..b9589ee 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -140,15 +140,28 @@ user can request any available phase. Invalid phase strings raise `ToolError`. ### 4. Default-deny permissions -Every tool call passes through a permission fence (`check_permission()` in -`koan/lib/permissions.py`). Unknown roles are blocked. Unknown tools are -blocked. Planning roles can only write inside the run directory. +Two enforcement layers restrict what tools each agent can use: + +1. **CLI tool whitelist** (`CLAUDE_TOOL_WHITELISTS` in `subagent.py`) -- + controls which Claude Code built-in tools exist in the model's context. + Unlisted tools are not presented to the model; it cannot call them. +2. **MCP permission fence** (`check_permission()` in `permissions.py`) -- + gates koan MCP tool calls per role and phase. Unknown roles and tools are + blocked. Planning roles can only write inside the run directory. + +Agents should not have access to tools they are never intended to need. +Restricting the tool vocabulary prevents the model from drifting toward +irrelevant capabilities (autonomous scheduling, subagent spawning, plan mode) +that compete with koan's step-first workflow. The one accepted limitation: `READ_TOOLS` (bash, read, grep, glob, find, ls) are always allowed because distinguishing "read bash" from "write bash" is intractable at the permission layer. **Prompt engineering constrains intended bash use; enforcement does not.** +See [subagents.md -- Permissions](./subagents.md#permissions) for per-role +whitelists and the full MCP permission matrix. + ### 5. Need-to-know prompts Each subagent receives only the minimum context for its task: @@ -172,13 +185,13 @@ reaches the LLM before it reads task details. The injection contract every `phase_guidance` entry must cover: -| Section | Purpose | -|---------|---------| -| **Scope** | What kind of task this workflow targets | -| **Downstream consumer** | What phase reads the output, what detail level it needs | -| **Investigation posture** | Direct reading vs. scouts, typical scout count | -| **Question posture** | How aggressively to ask, typical round count | -| **User override** | Always present, always last: "follow their lead" | +| Section | Purpose | +| ------------------------- | ------------------------------------------------------- | +| **Scope** | What kind of task this workflow targets | +| **Downstream consumer** | What phase reads the output, what detail level it needs | +| **Investigation posture** | Direct reading vs. scouts, typical scout count | +| **Question posture** | How aggressively to ask, typical round count | +| **User override** | Always present, always last: "follow their lead" | ### 6. Directory-as-contract @@ -227,7 +240,6 @@ disciplinary synchronization. Any divergence produces subtle display bugs that are hard to trace. JSON Patch makes correctness structural: one fold, one source of truth, mechanical application on the client. - --- ## Workflow System @@ -240,12 +252,12 @@ and suggested transitions between phases. Two workflows are defined in **plan** — intake → plan-spec → plan-review → execute -| Phase | Role | Steps | Artifact | -|-------|------|-------|---------| -| `intake` | Requirement gathering | 3 (Gather → Deepen → Summarize) | Chat summary only | -| `plan-spec` | Technical planning | 2 (Analyze → Write) | `plan.md` | -| `plan-review` | Quality review | 2 (Read → Evaluate) | Chat report only | -| `execute` | Implementation handoff | 2 (Compose → Request) | Code changes via executor | +| Phase | Role | Steps | Artifact | +| ------------- | ---------------------- | ------------------------------- | ------------------------- | +| `intake` | Requirement gathering | 3 (Gather → Deepen → Summarize) | Chat summary only | +| `plan-spec` | Technical planning | 2 (Analyze → Write) | `plan.md` | +| `plan-review` | Quality review | 2 (Read → Evaluate) | Chat report only | +| `execute` | Implementation handoff | 2 (Compose → Request) | Code changes via executor | **milestones** — stub workflow; runs intake only, then yields with a single "done" suggestion. @@ -254,6 +266,7 @@ and suggested transitions between phases. Two workflows are defined in The user selects a workflow at run start. The selection is stored in `AppState.workflow` and used throughout the run for: + - Phase transition validation (`is_valid_transition`) - Phase boundary suggestions (`get_suggested_phases`) - Phase guidance injection (`workflow.phase_guidance[phase]`) @@ -324,6 +337,7 @@ Output: a single in-memory `Projection` covering all agents, run state, and UI interactions. Consumed by the browser frontend via SSE. When adding new observable state, decide which system it belongs to: + - State visible only in logs/debugging → audit fold - State visible in the browser UI → projection fold diff --git a/docs/subagents.md b/docs/subagents.md index 6e0eada..9a711e6 100644 --- a/docs/subagents.md +++ b/docs/subagents.md @@ -29,11 +29,11 @@ are nested naturally rather than flattened into a shared namespace. Role-specific fields: -| Role | Additional fields | -| -------------- | ------------------------------------------------- | -| `orchestrator` | `project_dir`, `task_description` | -| `scout` | `question`, `investigator_role` | -| `executor` | `artifacts`, `instructions` | +| Role | Additional fields | +| -------------- | --------------------------------- | +| `orchestrator` | `project_dir`, `task_description` | +| `scout` | `question`, `investigator_role` | +| `executor` | `artifacts`, `instructions` | ### Lifecycle @@ -218,45 +218,86 @@ The driver/parent reads those files after the subagent exits. ## Permissions -Default-deny, role-based, enforced at runtime via `check_permission()` in -`koan/lib/permissions.py`. +Two enforcement layers restrict what tools each agent can use: -### READ_TOOLS (always allowed) +1. **CLI tool whitelist** (`CLAUDE_TOOL_WHITELISTS` in `subagent.py`) -- + controls which Claude Code built-in tools exist in the model's context. + Unlisted tools are not presented to the model at all; it has no awareness + they exist and cannot attempt to call them. +2. **MCP permission fence** (`check_permission()` in `koan/lib/permissions.py`) + -- controls which koan MCP tools are callable per role and phase. + +These layers are complementary. The CLI whitelist gates built-in tools (Read, +Write, Edit, Bash, etc.). The MCP fence gates koan tools (koan_complete_step, +koan_set_phase, etc.). Together they implement defense-in-depth: an agent +never sees tools it should not use, and tools it can see are still validated +per-call. + +### CLI tool whitelists + +Agents should not have access to tools they are never intended to need. A +smaller tool vocabulary reduces misbehavior, token waste, and the chance of +the model drifting toward irrelevant built-in capabilities (plan mode, +autonomous scheduling, subagent spawning) that compete with koan's step-first +workflow. + +| Role | Built-in tools | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| **orchestrator** | `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `WebFetch`, `WebSearch` | +| **executor** | `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`, `TaskStop`, `TaskOutput` | +| **scout** | `Read`, `Bash`, `Glob`, `Grep` | + +All agents also receive `--disable-slash-commands` (no skills) and +`--strict-mcp-config` (only koan's MCP server, no ambient servers). + +Notably excluded from all roles: `Agent` (bypasses spawn lifecycle), +`EnterPlanMode`/`ExitPlanMode` (competes with step-first workflow), +`ScheduleWakeup`/`CronCreate` (autonomous scheduling), `EnterWorktree` +(breaks directory assumptions). + +### MCP permission fence + +Default-deny, role-based, enforced at runtime. + +#### READ_TOOLS (always allowed) `bash`, `read`, `grep`, `glob`, `find`, `ls` -- allowed for all roles. This is an accepted limitation: `bash` can write files, but distinguishing read-bash from write-bash is intractable at the permission layer. -### Role permission matrix +#### Role permission matrix -The orchestrator role uses **phase-aware permissions** — available tools +The orchestrator role uses **phase-aware permissions** -- available tools vary by the current phase. Executor and scout use static permission sets. **Orchestrator phase-aware permissions:** -| Tool | Available phases | -|------|-----------------| -| `koan_complete_step` | All phases | -| `koan_set_phase` | All phases (blocked mid-story during execution) | -| `koan_ask_question` | All phases | -| `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `plan-spec`, `plan-review` | -| `koan_request_executor` | `execution`, `execute` | -| `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | `execution` only | -| `write`, `edit` (run_dir scoped) | All phases except `brief-generation` step 1 | -| `bash` | `execution`, `implementation-validation` | +| Tool | Available phases | +| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `koan_complete_step` | All phases | +| `koan_set_phase` | All phases (blocked mid-story during execution) | +| `koan_ask_question` | All phases | +| `koan_request_scouts` | `intake`, `core-flows`, `tech-plan`, `ticket-breakdown`, `cross-artifact-validation`, `plan-spec`, `plan-review` | +| `koan_request_executor` | `execution`, `execute` | +| `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | `execution` only | +| `write`, `edit` (run_dir scoped) | All phases except `brief-generation` step 1 | +| `bash` | `execution`, `implementation-validation` | **Other role static permissions:** -| Role | koan tools | write/edit | notes | -| -------------- | -------------------------------------------- | ---------------------- | ------------------------------------------- | -| **scout** | `koan_complete_step` | none | No user interaction. No nested scouts. No file writing. | -| **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | +| Role | koan tools | write/edit | notes | +| ------------ | ----------------------------------------- | ---------------- | ------------------------------------------------------- | +| **scout** | `koan_complete_step` | none | No user interaction. No nested scouts. No file writing. | +| **executor** | `koan_complete_step`, `koan_ask_question` | **unrestricted** | Must modify the actual codebase | -### Path scoping +#### Path scoping Planning roles (orchestrator, scout) can only `write`/`edit` files inside the -run directory. The permission check resolves both the tool's `path` argument -and the run directory, then verifies the tool path starts with the run path. +run directory via MCP write/edit tools. The permission check resolves both the +tool's `path` argument and the run directory, then verifies the tool path +starts with the run path. Built-in Write/Edit bypass MCP and are not subject +to this check; path discipline for built-in tools relies on prompt engineering +and the CLI whitelist. --- @@ -266,18 +307,18 @@ The executor is spawned by the orchestrator via `koan_request_executor`. It receives structured inputs via `task.json` and implements code changes in a 3-step workflow: -| Step | Name | What happens | -|------|------|--------------| -| 1 | Comprehend | Read all artifacts listed in `task.json`. Understand the plan and codebase context. | -| 2 | Plan | Identify the specific file edits needed. Do not write code yet. | -| 3 | Implement | Apply changes, verify they match the plan, report what was done. | +| Step | Name | What happens | +| ---- | ---------- | ----------------------------------------------------------------------------------- | +| 1 | Comprehend | Read all artifacts listed in `task.json`. Understand the plan and codebase context. | +| 2 | Plan | Identify the specific file edits needed. Do not write code yet. | +| 3 | Implement | Apply changes, verify they match the plan, report what was done. | `task.json` fields for the executor role: -| Field | Type | Purpose | -|-------|------|---------| -| `artifacts` | `list[str]` | Paths relative to `run_dir` that the executor must read before coding | -| `instructions` | `str` | Free-form context: key decisions, user direction, review findings. Does NOT repeat artifact contents. | +| Field | Type | Purpose | +| -------------- | ----------- | ----------------------------------------------------------------------------------------------------- | +| `artifacts` | `list[str]` | Paths relative to `run_dir` that the executor must read before coding | +| `instructions` | `str` | Free-form context: key decisions, user direction, review findings. Does NOT repeat artifact contents. | The executor has unrestricted `write`/`edit` access — it must be able to modify the actual codebase. It may call `koan_ask_question` if it encounters genuine @@ -294,11 +335,11 @@ receives a success/failure summary and reports it to the user at the execute pha Koan has 6+ roles, but they cluster into 3 capability bands: -| Tier | Roles | Why this tier | -| ------------ | ------------------------------ | ---------------------------------------------------------------- | -| **strong** | orchestrator | Complex multi-step reasoning | -| **standard** | executor | Code implementation: reliable tool use without deepest reasoning | -| **cheap** | scout | Narrow codebase investigation: reading files, writing findings | +| Tier | Roles | Why this tier | +| ------------ | ------------ | ---------------------------------------------------------------- | +| **strong** | orchestrator | Complex multi-step reasoning | +| **standard** | executor | Code implementation: reliable tool use without deepest reasoning | +| **cheap** | scout | Narrow codebase investigation: reading files, writing findings | The role-to-tier mapping is defined in `koan/config.py`. Adding a new role requires updating that map. @@ -313,15 +354,32 @@ to `~/.koan/config.json`: ```json { "agentInstallations": [ - { "alias": "claude-sonnet", "runnerType": "claude", "binary": "claude", "extraArgs": [] } + { + "alias": "claude-sonnet", + "runnerType": "claude", + "binary": "claude", + "extraArgs": [] + } ], "profiles": [ { "name": "balanced", "tiers": { - "strong": { "runnerType": "claude", "model": "claude-sonnet-4-5", "thinking": "disabled" }, - "standard": { "runnerType": "claude", "model": "claude-sonnet-4-5", "thinking": "disabled" }, - "cheap": { "runnerType": "claude", "model": "claude-haiku-4-5", "thinking": "disabled" } + "strong": { + "runnerType": "claude", + "model": "claude-sonnet-4-5", + "thinking": "disabled" + }, + "standard": { + "runnerType": "claude", + "model": "claude-sonnet-4-5", + "thinking": "disabled" + }, + "cheap": { + "runnerType": "claude", + "model": "claude-haiku-4-5", + "thinking": "disabled" + } } } ], @@ -404,8 +462,8 @@ Agent registration and deregistration are tracked in the in-process Intake sub-phase derivation happens server-side based on step number: -| Step | Sub-phase | -| ---- | ------------- | -| 1 | `"gather"` | -| 2 | `"evaluate"` | -| 3 | `"write"` | +| Step | Sub-phase | +| ---- | ------------ | +| 1 | `"gather"` | +| 2 | `"evaluate"` | +| 3 | `"write"` | diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index 705bbf2..b1c5965 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -42,7 +42,7 @@ class PhaseModule(Protocol): ROLE: str SCOPE: str TOTAL_STEPS: int - SYSTEM_PROMPT: str + PHASE_ROLE_CONTEXT: str def step_guidance(self, step: int, ctx: PhaseContext) -> StepGuidance: ... def get_next_step(self, step: int, ctx: PhaseContext) -> int | None: ... @@ -50,40 +50,6 @@ def validate_step_completion(self, step: int, ctx: PhaseContext) -> str | None: async def on_loop_back(self, from_step: int, to_step: int, ctx: PhaseContext) -> None: ... -# -- Orchestrator base system prompt ------------------------------------------ -# Delivered via --system-prompt at spawn time. Phase-specific role context -# is injected via koan_complete_step's step-1 guidance (SYSTEM_PROMPT prepend). - -ORCHESTRATOR_SYSTEM_PROMPT = ( - "You are the koan workflow orchestrator. You run a coding task planning and" - " execution pipeline from start to finish in a single continuous session.\n" - "\n" - "You work through phases in sequence: each phase has numbered steps. Call" - " koan_complete_step to advance through steps.\n" - "\n" - "When a phase ends, koan_complete_step tells you to summarize and yield.\n" - "Call koan_yield with a summary and structured suggestions for the user.\n" - "Each suggestion needs:\n" - "- id: phase name (e.g. \"plan-spec\") or \"done\"\n" - "- label: short action label (e.g. \"Write implementation plan\")\n" - "- command: task-specific sentence pre-filled in the chat input when clicked\n" - "Always include a \"done\" suggestion so the user can end the workflow.\n" - "\n" - "koan_yield blocks until the user sends a message and returns it to you.\n" - "Respond conversationally. Call koan_yield again to continue the conversation.\n" - "When the user confirms a direction, call koan_set_phase with the phase name.\n" - "When the user is done, call koan_set_phase with \"done\".\n" - "\n" - "At the start of each phase, koan_complete_step returns your role context for" - " that phase alongside the first step's instructions.\n" - "\n" - "Rules:\n" - "- Only call koan_set_phase after the user has confirmed the direction.\n" - "- Use koan_yield for all user interaction at phase boundaries.\n" - "- Available tools change depending on the current phase." -) - - # -- Subagent module registry -------------------------------------------------- # Maps SubagentRole strings to phase modules for non-orchestrator subagent # spawns (scouts, executors). Orchestrator phase dispatch uses diff --git a/koan/phases/brief_writer.py b/koan/phases/brief_writer.py index 51e531e..4054acc 100644 --- a/koan/phases/brief_writer.py +++ b/koan/phases/brief_writer.py @@ -18,7 +18,7 @@ 2: "Draft", } -SYSTEM_PROMPT = ( +PHASE_ROLE_CONTEXT = ( "You are a brief writer for a coding task planner. You read intake context and" " produce a compact epic brief -- a product-level document that captures the" " problem, who's affected, goals, and constraints.\n" diff --git a/koan/phases/core_flows.py b/koan/phases/core_flows.py index ef6ffca..0edcfa9 100644 --- a/koan/phases/core_flows.py +++ b/koan/phases/core_flows.py @@ -18,7 +18,7 @@ 2: "Core Flows", } -SYSTEM_PROMPT = ( +PHASE_ROLE_CONTEXT = ( "You are a core-flows analyst for a coding task planner. You read intake" " output and the epic brief, then define the user journeys and interaction" " flows that the implementation must support.\n" diff --git a/koan/phases/cross_artifact_validation.py b/koan/phases/cross_artifact_validation.py index da04a20..7dee08c 100644 --- a/koan/phases/cross_artifact_validation.py +++ b/koan/phases/cross_artifact_validation.py @@ -18,7 +18,7 @@ 2: "Validate", } -SYSTEM_PROMPT = ( +PHASE_ROLE_CONTEXT = ( "You are a cross-artifact validator for a coding task planner. You read all" " spec artifacts produced by upstream phases and validate that they are" " internally consistent and complete.\n" diff --git a/koan/phases/curation.py b/koan/phases/curation.py index 18cb2ff..2cf23e7 100644 --- a/koan/phases/curation.py +++ b/koan/phases/curation.py @@ -42,13 +42,20 @@ } -# -- System prompt ------------------------------------------------------------- -# Injected at the top of step 1. The orchestrator already has its own boot -# identity from ORCHESTRATOR_SYSTEM_PROMPT; this prompt adds the curator -# role layer on top. It does not redeclare the orchestrator identity. - -SYSTEM_PROMPT = ( - "You are now operating as the project's knowledge curator. Your job is\n" +# -- Phase role context -------------------------------------------------------- +# Injected at the top of step 1. The orchestrator's agent-type system prompt +# (koan/prompts/orchestrator.py) provides a high-level memory overview. This +# role context adds the full curation procedure on top -- detailed writing +# discipline, classification schema, quality checklist. + +PHASE_ROLE_CONTEXT = ( + "You are now operating as the project's knowledge curator. Your\n" + "agent-type system prompt gave you a high-level overview of the memory\n" + "system. This phase provides the FULL curation procedure. Read every\n" + "section below -- the writing discipline, classification tree, and\n" + "quality rules here override any assumptions from the overview.\n" + "\n" + "Your job is\n" "to maintain a small, high-quality memory of decisions, context, lessons,\n" "and procedures that helps AI coding agents work effectively across\n" "workflow runs.\n" @@ -170,13 +177,16 @@ " Propose removal via `koan_forget`. (The action label\n" " is DEPRECATE; the tool is `koan_forget` -- they\n" " refer to the same operation.)\n" + "- **COMMENT** -- this knowledge is better expressed as a code comment\n" + " next to the relevant function. Drop from memory\n" + " candidates.\n" "\n" "## Writing discipline (high-level)\n" "\n" "Every entry is 100-500 tokens of **temporally grounded, attributed,\n" "event-style** prose -- a historical fact that stays true regardless\n" "of when it is read. The full rules, two contrastive bad/good\n" - "examples, and a 6-item self-validation checklist appear in step 2\n" + "examples, and a 7-item self-validation checklist appear in step 2\n" "(Memorize), rendered at the drafting moment. Do NOT skim the step 2\n" "examples -- your default register for technical content is timeless\n" "documentation prose, and the examples are the only thing that\n" @@ -194,6 +204,14 @@ "agent's working context already includes this when it opens the\n" "relevant files.\n" "\n" + "**Implementation rationale** scoped to a single function or module\n" + "should be a code comment, not a memory entry. Apply this test:\n" + "\"Would a code comment next to the relevant function give a future\n" + "agent the same benefit?\" If yes, the candidate fails and should be\n" + "classified COMMENT. Examples that fail the test: why a function was\n" + "split a certain way, why a parameter has a specific default value, a\n" + "pattern scoped to one module.\n" + "\n" "**Behavioral knowledge** that needs proactive surfacing MUST be\n" "captured, even when the knowledge also appears in a project\n" "document (docs/, AGENTS.md, README.md, etc.). The RAG retrieval\n" @@ -283,7 +301,7 @@ def _tools_this_step_block(current_step: int) -> list[str]: if current_step == 2: return [ "<tools_this_step>", - "Writing discipline, two contrastive examples, and a 6-item", + "Writing discipline, two contrastive examples, and a 7-item", "draft-quality checklist appear in this step's body below.", "Read them BEFORE drafting your first candidate.", "", @@ -377,7 +395,7 @@ def _step_1_inventory(ctx: PhaseContext) -> StepGuidance: " none match, drop the candidate as not", " memory-worthy.", " - title (one line)", - " - classification (ADD / UPDATE / NOOP / DEPRECATE)", + " - classification (ADD / UPDATE / NOOP / DEPRECATE / COMMENT)", " - entry_id (only for UPDATE / DEPRECATE)", " When a candidate is close to an existing topic, read the suspect", " entries directly from `.koan/memory/` before classifying.", @@ -549,7 +567,7 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: "", "### B. Self-critique", "", - "For each draft produced in substep A, run the 6-item draft-", + "For each draft produced in substep A, run the 7-item draft-", "quality checklist below. Output the checklist result PER", "DRAFT in this exact format:", "", @@ -560,6 +578,7 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: " 4. Event-style, past tense: PASS / FAIL", " 5. Concrete naming: PASS / FAIL", " 6. Contains knowledge, not pointer: PASS / FAIL", + " 7. Passes code-comment test: PASS / FAIL", "", " Draft 2 ({title}):", " ...", @@ -574,8 +593,8 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: "For every draft with any FAIL in its checklist, rewrite the", "entry completely. Do not patch in place -- rewrite it, using", "the GOOD example template as the target form. After each", - "rewrite, re-run the 6-item checklist on the revised draft.", - "Loop until all 5 items PASS for all drafts in the batch.", + "rewrite, re-run the 7-item checklist on the revised draft.", + "Loop until all 7 items PASS for all drafts in the batch.", "", "You MAY NOT proceed to substep D (Yield) while any draft in", "this batch has an outstanding FAIL.", @@ -596,6 +615,7 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: "- UPDATE -> `koan_memorize` (with `entry_id`)", "- DEPRECATE -> `koan_forget` (with `entry_id`)", "- NOOP -> nothing", + "- COMMENT -> skip", "", "### F. Cross off", "", @@ -605,7 +625,7 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: "", "## Draft-quality checklist (schema for substep B)", "", - "For each draft, verify all 6 items. Any FAIL means the draft", + "For each draft, verify all 7 items. Any FAIL means the draft", "cannot be yielded -- it must go back through substep C.", "", "**1. Opens with a named subsystem.**", @@ -649,6 +669,14 @@ def _step_2_memorize(ctx: PhaseContext) -> StepGuidance: "knowledge?\" directly in its body, readable without opening any", "other file.", "", + "**7. Passes the code-comment test.**", + "Candidates that describe why a single function is structured a", + "certain way, why a parameter has a specific value, or a pattern", + "scoped to one module FAIL this check and should be reclassified", + "as COMMENT. Ask: \"Would a code comment next to the relevant", + "function give a future agent the same benefit?\" If yes, classify", + "as COMMENT and skip.", + "", "## Anticipatory tool-call check (BEFORE the wrap-up)", "", "After all batches have been processed, before you call", diff --git a/koan/phases/execute.py b/koan/phases/execute.py index 65ab035..c1ad14f 100644 --- a/koan/phases/execute.py +++ b/koan/phases/execute.py @@ -20,7 +20,7 @@ 2: "Request", } -SYSTEM_PROMPT = ( +PHASE_ROLE_CONTEXT = ( "You are an execution coordinator. The plan has been written and reviewed.\n" "Your job is to compose a clean handoff to the executor agent. You do NOT\n" "write code and you do NOT re-evaluate the plan.\n" diff --git a/koan/phases/executor.py b/koan/phases/executor.py index 6327aaf..8ab3dfb 100644 --- a/koan/phases/executor.py +++ b/koan/phases/executor.py @@ -21,34 +21,10 @@ 3: "Implement", } -SYSTEM_PROMPT = ( - "You are a coding agent. You implement changes to a codebase based on" - " artifacts and instructions provided by the orchestrator.\n" - "\n" - "You receive artifact files to read and free-form instructions. You plan" - " your approach, then implement. You are the only agent that writes source" - " code.\n" - "\n" - "## Resolve trivial issues independently\n" - "\n" - "- Incorrect file paths or function names in artifacts \u2192 find correct ones\n" - "- Syntax errors or typos in plan snippets \u2192 fix them\n" - "- Minor import adjustments \u2192 handle them\n" - "- Obvious missing error handling \u2192 add it\n" - "\n" - "## Call koan_ask_question only when\n" - "\n" - "- The artifacts are genuinely ambiguous about *what* to build\n" - "- You discover a conflict between plan and codebase that isn't trivial\n" - "- A dependency or prerequisite is missing that blocks implementation\n" - "\n" - "## Strict rules\n" - "\n" - "- MUST read all listed artifacts before writing any code.\n" - "- MUST NOT add features the instructions don't mention.\n" - "- MUST NOT refactor code the plan doesn't touch.\n" - "- MUST NOT modify test expectations to make tests pass -- report via koan_ask_question.\n" -) +# Phase role context -- empty for executor. The executor's identity is +# delivered via the agent-type system prompt at spawn time (koan/prompts/executor.py). +# The executor does not switch phases, so there is no role-switching context. +PHASE_ROLE_CONTEXT = "" # -- Step guidance ------------------------------------------------------------- @@ -134,6 +110,15 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "2. Make the change.", "3. Move to the next change.", "", + "## Rationale comments", + "", + "When you make an implementation choice, write a brief comment", + "(1-3 lines) at the code location explaining why. These comments", + "are the primary record of implementation-level decisions. Focus", + "on \"why\", not \"what\". Examples: why a function was split a", + "certain way, why a parameter has a specific default, why one", + "approach was chosen over another.", + "", "## Trivial issues", "", "Resolve independently:", diff --git a/koan/phases/intake.py b/koan/phases/intake.py index 5f51126..93546cd 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -1,7 +1,8 @@ -# Intake phase -- 2-step workflow. +# Intake phase -- 3-step workflow. # -# Step 1 (Gather) -- read task description, explore obvious files, dispatch scouts -# Step 2 (Deepen) -- process scout results, deepen through dialogue, summarize +# Step 1 (Gather) -- read task description, explore obvious files, dispatch scouts +# Step 2 (Deepen) -- process scout results, deepen through dialogue +# Step 3 (Summarize) -- synthesize findings into a handoff summary # # Workflow scope framing (phase_instructions) appears at the top of step 1 guidance. @@ -11,14 +12,15 @@ ROLE = "intake" SCOPE = "general" # reusable by any workflow -TOTAL_STEPS = 2 +TOTAL_STEPS = 3 STEP_NAMES: dict[int, str] = { 1: "Gather", 2: "Deepen", + 3: "Summarize", } -SYSTEM_PROMPT = ( +PHASE_ROLE_CONTEXT = ( "You are an intake analyst for a coding task planner. You read a task" " description, explore the codebase, and ask the user targeted questions" " until you have complete context for planning.\n" @@ -244,9 +246,14 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "- No answer you received left you with a 'I think I know what they mean'", " feeling -- you either confirmed it or asked.", "", - "## 4. Summarize and transition", - "", - "When deepening is complete, synthesize a concise summary covering:", + ], + ) + + if step == 3: + return StepGuidance( + title=STEP_NAMES[3], + instructions=[ + "Synthesize a concise summary covering:", "", "- **Task scope**: What is being built or changed, in the user's framing.", "- **Key codebase findings**: Entry points, current behavior, integration points.", diff --git a/koan/phases/orchestrator.py b/koan/phases/orchestrator.py index 909c89b..a07645b 100644 --- a/koan/phases/orchestrator.py +++ b/koan/phases/orchestrator.py @@ -21,7 +21,7 @@ SCOPE = "legacy" TOTAL_STEPS = 2 # default; actual depends on step_sequence -SYSTEM_PROMPT = ( +PHASE_ROLE_CONTEXT = ( "You are a workflow orchestrator for a multi-story coding epic. You make" " judgment calls at execution boundaries -- before and after each coding story runs.\n" "\n" diff --git a/koan/phases/plan_review.py b/koan/phases/plan_review.py index 1e0a25f..71d3222 100644 --- a/koan/phases/plan_review.py +++ b/koan/phases/plan_review.py @@ -19,7 +19,7 @@ 2: "Evaluate", } -SYSTEM_PROMPT = ( +PHASE_ROLE_CONTEXT = ( "You are the adversarial reviewer for an implementation plan.\n" "\n" "You are the ONLY phase in this workflow that independently verifies claims\n" diff --git a/koan/phases/plan_spec.py b/koan/phases/plan_spec.py index d4497c0..a3ab209 100644 --- a/koan/phases/plan_spec.py +++ b/koan/phases/plan_spec.py @@ -18,7 +18,7 @@ 2: "Write", } -SYSTEM_PROMPT = ( +PHASE_ROLE_CONTEXT = ( "You are a technical architect writing an implementation plan for a coding task.\n" "\n" "You read the codebase thoroughly before planning. Your plans reference actual" diff --git a/koan/phases/scout.py b/koan/phases/scout.py index 3c31b66..0eb19e7 100644 --- a/koan/phases/scout.py +++ b/koan/phases/scout.py @@ -19,53 +19,10 @@ 3: "Report", } -SYSTEM_PROMPT = ( - "You are a codebase investigator. You are assigned one narrow, specific question" - " about a codebase. Your job is to methodically explore the relevant code, verify" - " your findings, and write a grounded report.\n" - "\n" - "## Your role\n" - "\n" - "You find facts. You do NOT interpret, recommend, or opine.\n" - "\n" - "## Speed principles\n" - "\n" - "You are optimized for speed and breadth. Cast a wide net quickly.\n" - "\n" - "- Call MULTIPLE tools simultaneously. Read 3-5 files in one turn, not one at a time.\n" - "- Combine search strategies: run grep, find, and read calls together in a single turn.\n" - "- Use bash for broad sweeps: `grep -rn` across directories, `find` with multiple patterns.\n" - "- Do NOT be overly cautious or sequential. Explore aggressively, discard irrelevant results.\n" - "- Maximize work per turn. Each tool-call turn should accomplish as much as possible.\n" - "\n" - "## Strict rules\n" - "\n" - "- MUST answer only the assigned question. Do not expand scope.\n" - "- MUST write only factual observations: what the code does, what files exist, what patterns are present.\n" - "- MUST NOT produce recommendations or suggestions of any kind.\n" - "- MUST NOT express opinions about code quality.\n" - "- MUST NOT produce implementation plans or design ideas.\n" - "- MUST include file paths and line numbers when referencing code.\n" - "- MUST reference code precisely: file:line, function signature or key line.\n" - " Do NOT copy full function bodies or paste large code blocks.\n" - "- Use compressed notation throughout your report:\n" - " Signatures: `file.go:42 func Compile(*Rule) (*CompiledRule, error)`\n" - " Structs: `CompiledRule{RuleID, Name, Action, SampleRate, OrGroups}`\n" - " Enums: `Action: Observe|Drop|Fail`\n" - " Call chains: `cmd/main.go -> NewService() -> engine.Start()`\n" - "- SHOULD be thorough within the question scope: follow references, check related files.\n" - "- SHOULD note explicitly when something is NOT present (e.g., \"No tests found for this module\").\n" - "\n" - "## Output\n" - "\n" - "Your findings are returned as your final text response. Do not write any files.\n" - "The format is provided in your final step.\n" - "\n" - "## Tools available\n" - "\n" - "- All read tools (read, bash, grep, glob, find, ls) -- for reading the codebase.\n" - "- `koan_complete_step` -- to advance to the next workflow step." -) +# Phase role context -- empty for scout. The scout's identity is +# delivered via the agent-type system prompt at spawn time (koan/prompts/scout.py). +# Scouts do not switch phases, so there is no role-switching context. +PHASE_ROLE_CONTEXT = "" # -- Step guidance ------------------------------------------------------------- diff --git a/koan/phases/tech_plan.py b/koan/phases/tech_plan.py index a8c1dd8..c67898e 100644 --- a/koan/phases/tech_plan.py +++ b/koan/phases/tech_plan.py @@ -20,7 +20,7 @@ 3: "Verification Design", } -SYSTEM_PROMPT = ( +PHASE_ROLE_CONTEXT = ( "You are an implementation planner for a single coding story. You produce a" " detailed, step-by-step plan that a coding agent can execute without making" " judgment calls. You bridge the gap between high-level story intent and" diff --git a/koan/phases/ticket_breakdown.py b/koan/phases/ticket_breakdown.py index ddc7f28..462dd75 100644 --- a/koan/phases/ticket_breakdown.py +++ b/koan/phases/ticket_breakdown.py @@ -18,7 +18,7 @@ 2: "Breakdown", } -SYSTEM_PROMPT = ( +PHASE_ROLE_CONTEXT = ( "You are a ticket-breakdown writer for a coding task planner. You read the" " epic brief, core flows, and technical plan, then split the work into" " independent, story-sized implementation tickets with clear dependency" diff --git a/koan/prompts/__init__.py b/koan/prompts/__init__.py new file mode 100644 index 0000000..9ca7412 --- /dev/null +++ b/koan/prompts/__init__.py @@ -0,0 +1,18 @@ +# Agent-type system prompts -- one per agent role. +# +# These are delivered via --system-prompt at spawn time and persist for +# the entire agent lifetime. They carry identity, persistent knowledge, +# and cross-phase capabilities. +# +# Phase-specific role context (PHASE_ROLE_CONTEXT in each phase module) +# is a separate layer injected at step 1 via koan_complete_step. + +from .orchestrator import SYSTEM_PROMPT as ORCHESTRATOR_SYSTEM_PROMPT +from .executor import SYSTEM_PROMPT as EXECUTOR_SYSTEM_PROMPT +from .scout import SYSTEM_PROMPT as SCOUT_SYSTEM_PROMPT + +AGENT_TYPE_PROMPTS: dict[str, str] = { + "orchestrator": ORCHESTRATOR_SYSTEM_PROMPT, + "executor": EXECUTOR_SYSTEM_PROMPT, + "scout": SCOUT_SYSTEM_PROMPT, +} diff --git a/koan/prompts/executor.py b/koan/prompts/executor.py new file mode 100644 index 0000000..a427b0d --- /dev/null +++ b/koan/prompts/executor.py @@ -0,0 +1,41 @@ +# Executor agent-type system prompt. +# +# Delivered via --system-prompt at spawn time. The executor is a +# subagent that implements code changes -- it does not switch phases. + +SYSTEM_PROMPT = ( + "You are a coding agent. You implement changes to a codebase based on" + " artifacts and instructions provided by the orchestrator.\n" + "\n" + "You receive artifact files to read and free-form instructions. You plan" + " your approach, then implement. You are the only agent that writes source" + " code.\n" + "\n" + "## Resolve trivial issues independently\n" + "\n" + "- Incorrect file paths or function names in artifacts -> find correct ones\n" + "- Syntax errors or typos in plan snippets -> fix them\n" + "- Minor import adjustments -> handle them\n" + "- Obvious missing error handling -> add it\n" + "\n" + "## Call koan_ask_question only when\n" + "\n" + "- The artifacts are genuinely ambiguous about *what* to build\n" + "- You discover a conflict between plan and codebase that isn't trivial\n" + "- A dependency or prerequisite is missing that blocks implementation\n" + "\n" + "## Strict rules\n" + "\n" + "- MUST read all listed artifacts before writing any code.\n" + "- MUST NOT add features the instructions don't mention.\n" + "- MUST NOT refactor code the plan doesn't touch.\n" + "- MUST NOT modify test expectations to make tests pass -- report via koan_ask_question.\n" + "\n" + "## Project memory (read-only)\n" + "\n" + "Project memory entries at `.koan/memory/NNNN-*.md` contain curated\n" + "knowledge about the project -- decisions, context, lessons, and\n" + "procedures. Read them when you need project-level context not\n" + "available in the files you are already reading. You do not write\n" + "memory -- that is the orchestrator's job." +) diff --git a/koan/prompts/orchestrator.py b/koan/prompts/orchestrator.py new file mode 100644 index 0000000..de9b213 --- /dev/null +++ b/koan/prompts/orchestrator.py @@ -0,0 +1,83 @@ +# Orchestrator agent-type system prompt. +# +# Delivered via --system-prompt at spawn time. Covers: +# - Orchestrator identity and workflow mechanics +# - High-level memory system awareness (progressive disclosure: +# detailed curation procedure arrives via PHASE_ROLE_CONTEXT +# when entering the curation phase) + +SYSTEM_PROMPT = ( + "You are the koan workflow orchestrator. You run a coding task planning and" + " execution pipeline from start to finish in a single continuous session.\n" + "\n" + "You work through phases in sequence: each phase has numbered steps. Call" + " koan_complete_step to advance through steps.\n" + "\n" + "When a phase ends, koan_complete_step tells you to summarize and yield.\n" + "Call koan_yield with a summary and structured suggestions for the user.\n" + "Each suggestion needs:\n" + "- id: phase name (e.g. \"plan-spec\") or \"done\"\n" + "- label: short action label (e.g. \"Write implementation plan\")\n" + "- command: task-specific sentence pre-filled in the chat input when clicked\n" + "Always include a \"done\" suggestion so the user can end the workflow.\n" + "\n" + "koan_yield blocks until the user sends a message and returns it to you.\n" + "Respond conversationally. Call koan_yield again to continue the conversation.\n" + "When the user confirms a direction, call koan_set_phase with the phase name.\n" + "When the user is done, call koan_set_phase with \"done\".\n" + "\n" + "At the start of each phase, koan_complete_step returns your role context for" + " that phase alongside the first step's instructions.\n" + "\n" + "Rules:\n" + "- Only call koan_set_phase after the user has confirmed the direction.\n" + "- Use koan_yield for all user interaction at phase boundaries.\n" + "- Available tools change depending on the current phase.\n" + "\n" + "## Project memory\n" + "\n" + "You have access to a project memory system at `.koan/memory/`. Memory\n" + "entries are curated knowledge -- decisions, context, lessons, and\n" + "procedures -- that persists across workflow runs.\n" + "\n" + "### Memory tools\n" + "\n" + "- `koan_memory_status` -- returns the project summary and a listing of\n" + " all entries (id, title, type, dates). Call this to orient yourself.\n" + "- `koan_memorize` -- create or update a memory entry. Omit `entry_id`\n" + " to create; pass it to update.\n" + "- `koan_forget` -- delete a memory entry by `entry_id`.\n" + "\n" + "### Memory types\n" + "\n" + "- **decision** -- architectural choices with rationale and rejected\n" + " alternatives.\n" + "- **context** -- project facts not derivable from code: team,\n" + " infrastructure, business rules.\n" + "- **lesson** -- things that went wrong and the root cause.\n" + "- **procedure** -- behavioral rules for agents: checkable conditions\n" + " and concrete actions.\n" + "\n" + "### Reading vs. writing\n" + "\n" + "Individual entries are plain markdown at `.koan/memory/NNNN-*.md`.\n" + "Read them directly with file-reading tools for context or comparison.\n" + "The project summary comes from `koan_memory_status`. Writes go through\n" + "`koan_memorize` / `koan_forget` only -- do not write files under\n" + "`.koan/` directly.\n" + "\n" + "### Coding agent memory (separate system)\n" + "\n" + "CLAUDE.md, AGENTS.md, `.claude/projects/*/memory/`, etc. belong to\n" + "the coding agent -- they are a separate system from koan memory.\n" + "Treat them as read-only input. When both sources cover the same fact,\n" + "trust koan memory (it went through curation review).\n" + "\n" + "### When memory is curated\n" + "\n" + "Memory is curated at the end of each workflow run during the curation\n" + "phase. That phase provides detailed instructions for the full\n" + "procedure -- writing discipline, classification schema, quality\n" + "checklist. During other phases, be aware that memory exists and may\n" + "contain useful project context, but do not attempt to curate." +) diff --git a/koan/prompts/scout.py b/koan/prompts/scout.py new file mode 100644 index 0000000..798e02f --- /dev/null +++ b/koan/prompts/scout.py @@ -0,0 +1,60 @@ +# Scout agent-type system prompt. +# +# Delivered via --system-prompt at spawn time. Scouts are subagents +# that investigate the codebase -- they do not switch phases. + +SYSTEM_PROMPT = ( + "You are a codebase investigator. You are assigned one narrow, specific question" + " about a codebase. Your job is to methodically explore the relevant code, verify" + " your findings, and write a grounded report.\n" + "\n" + "## Your role\n" + "\n" + "You find facts. You do NOT interpret, recommend, or opine.\n" + "\n" + "## Speed principles\n" + "\n" + "You are optimized for speed and breadth. Cast a wide net quickly.\n" + "\n" + "- Call MULTIPLE tools simultaneously. Read 3-5 files in one turn, not one at a time.\n" + "- Combine search strategies: run grep, find, and read calls together in a single turn.\n" + "- Use bash for broad sweeps: `grep -rn` across directories, `find` with multiple patterns.\n" + "- Do NOT be overly cautious or sequential. Explore aggressively, discard irrelevant results.\n" + "- Maximize work per turn. Each tool-call turn should accomplish as much as possible.\n" + "\n" + "## Strict rules\n" + "\n" + "- MUST answer only the assigned question. Do not expand scope.\n" + "- MUST write only factual observations: what the code does, what files exist, what patterns are present.\n" + "- MUST NOT produce recommendations or suggestions of any kind.\n" + "- MUST NOT express opinions about code quality.\n" + "- MUST NOT produce implementation plans or design ideas.\n" + "- MUST include file paths and line numbers when referencing code.\n" + "- MUST reference code precisely: file:line, function signature or key line.\n" + " Do NOT copy full function bodies or paste large code blocks.\n" + "- Use compressed notation throughout your report:\n" + " Signatures: `file.go:42 func Compile(*Rule) (*CompiledRule, error)`\n" + " Structs: `CompiledRule{RuleID, Name, Action, SampleRate, OrGroups}`\n" + " Enums: `Action: Observe|Drop|Fail`\n" + " Call chains: `cmd/main.go -> NewService() -> engine.Start()`\n" + "- SHOULD be thorough within the question scope: follow references, check related files.\n" + "- SHOULD note explicitly when something is NOT present (e.g., \"No tests found for this module\").\n" + "\n" + "## Output\n" + "\n" + "Your findings are returned as your final text response. Do not write any files.\n" + "The format is provided in your final step.\n" + "\n" + "## Tools available\n" + "\n" + "- All read tools (read, bash, grep, glob, find, ls) -- for reading the codebase.\n" + "- `koan_complete_step` -- to advance to the next workflow step.\n" + "\n" + "## Project memory (read-only)\n" + "\n" + "Project memory entries at `.koan/memory/NNNN-*.md` contain curated\n" + "knowledge about the project -- decisions, context, lessons, and\n" + "procedures. Read them when you need project-level context not\n" + "available in the files you are already reading. You do not write\n" + "memory -- that is the orchestrator's job." +) diff --git a/koan/subagent.py b/koan/subagent.py index 8e5fb74..c01b740 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -32,7 +32,8 @@ ) from .logger import get_logger from .lib.workflows import get_workflow -from .phases import ORCHESTRATOR_SYSTEM_PROMPT, PHASE_MODULE_MAP, PhaseContext +from .phases import PHASE_MODULE_MAP, PhaseContext +from .prompts import AGENT_TYPE_PROMPTS from .runners import RunnerDiagnostic, RunnerError from .runners.registry import RunnerRegistry @@ -42,6 +43,24 @@ log = get_logger("subagent") +# -- Tool whitelists (Claude Code --tools) ------------------------------------- +# +# Agents should not have access to tools they are never intended to need. +# Restricting the tool vocabulary at the CLI level prevents the model from +# even seeing irrelevant tools (EnterPlanMode, Agent, TaskCreate, etc.), +# which reduces misbehavior and token waste. The MCP permission fence +# remains the authority for koan-specific tools; this whitelist controls +# only Claude Code built-in tools. +# +# These are Claude Code PascalCase tool names. Other runners (codex, gemini) +# have their own mechanisms and are not affected by this whitelist. + +CLAUDE_TOOL_WHITELISTS: dict[str, str] = { + "orchestrator": "Read,Write,Edit,Bash,Glob,Grep,WebFetch,WebSearch", + "executor": "Read,Write,Edit,Bash,Glob,Grep,TaskCreate,TaskUpdate,TaskList,TaskGet,TaskStop,TaskOutput", + "scout": "Read,Bash,Glob,Grep", +} + def _now_iso() -> str: from datetime import datetime, timezone @@ -158,10 +177,11 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None workflow_name = task.get("workflow", "plan") workflow = get_workflow(workflow_name) phase_module = workflow.get_module(workflow.initial_phase) - system_prompt = ORCHESTRATOR_SYSTEM_PROMPT else: phase_module = PHASE_MODULE_MAP.get(role) - system_prompt = getattr(phase_module, "SYSTEM_PROMPT", "") or "" if phase_module else "" + + # Agent-type system prompt -- per role, not per phase. + system_prompt = AGENT_TYPE_PROMPTS.get(role, "") if phase_module is None: log.error("no phase module for role %s", role) @@ -184,7 +204,7 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None phase_ctx=phase_ctx, event_log=event_log, model=model, - is_primary=(role != "scout"), + is_primary=(role == "orchestrator"), ) app_state.agents[agent_id] = agent @@ -212,6 +232,15 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None del app_state.agents[agent_id] return SubagentResult(exit_code=1) + # Claude-specific tool restriction: append --tools whitelist, disable skills, + # and isolate MCP sources so the model only sees tools it actually needs. + if runner.name == "claude": + whitelist = CLAUDE_TOOL_WHITELISTS.get(role) + if whitelist is not None: + cmd.extend(["--tools", whitelist]) + cmd.append("--disable-slash-commands") + cmd.append("--strict-mcp-config") + # Emit agent_spawned only after build_command succeeds -- process is about to start store.push_event("agent_spawned", build_agent_spawned(agent), agent_id=agent_id) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 4f89368..a7f239b 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -209,7 +209,7 @@ def _drain_and_append_steering(result: str, agent: AgentState | None = None) -> # -- koan_complete_step private helpers ---------------------------------------- async def _step_phase_handshake(agent: AgentState) -> str: - """Handle step 0 → 1: deliver step 1 guidance prepended with phase SYSTEM_PROMPT.""" + """Handle step 0 -> 1: deliver step 1 guidance prepended with phase role context.""" assert _app_state is not None phase_module = agent.phase_module @@ -233,12 +233,12 @@ async def _step_phase_handshake(agent: AgentState) -> str: agent.step = 1 guidance = phase_module.step_guidance(1, ctx) - # Prepend SYSTEM_PROMPT so the orchestrator receives the phase role context - system_prompt = getattr(phase_module, "SYSTEM_PROMPT", "") or "" - if system_prompt: + # Prepend PHASE_ROLE_CONTEXT so the orchestrator receives the phase role context + role_context = getattr(phase_module, "PHASE_ROLE_CONTEXT", "") or "" + if role_context: guidance = StepGuidance( title=guidance.title, - instructions=[system_prompt, ""] + list(guidance.instructions), + instructions=[role_context, ""] + list(guidance.instructions), invoke_after=guidance.invoke_after, ) diff --git a/tests/phases/test_curation.py b/tests/phases/test_curation.py index a925a34..ed652b5 100644 --- a/tests/phases/test_curation.py +++ b/tests/phases/test_curation.py @@ -25,8 +25,8 @@ def test_step_names(self): assert curation.STEP_NAMES == {1: "Inventory", 2: "Memorize"} def test_system_prompt_is_nonempty(self): - assert isinstance(curation.SYSTEM_PROMPT, str) - assert len(curation.SYSTEM_PROMPT) > 100 + assert isinstance(curation.PHASE_ROLE_CONTEXT, str) + assert len(curation.PHASE_ROLE_CONTEXT) > 100 def test_system_prompt_writing_discipline_is_high_level_only(self): # Post-rewrite: writing discipline in the system prompt is a @@ -35,14 +35,14 @@ def test_system_prompt_writing_discipline_is_high_level_only(self): # drafting moment. The system prompt keeps just the pillars # ("temporally grounded, attributed, event-style") and an # explicit pointer to step 2. - sp = curation.SYSTEM_PROMPT.lower() + sp = curation.PHASE_ROLE_CONTEXT.lower() assert "temporally grounded" in sp assert "attributed" in sp assert "event-style" in sp assert "step 2" in sp # points at where the full rules live def test_system_prompt_has_type_discrimination_tree(self): - sp = curation.SYSTEM_PROMPT + sp = curation.PHASE_ROLE_CONTEXT # The 4-question tree, with first-match-wins semantics, must # be present as a procedure (not just definitions). assert "Picking the type for a candidate" in sp @@ -57,7 +57,7 @@ def test_system_prompt_behavioral_knowledge_must_be_captured(self): # The "what not to capture" section must require behavioral # knowledge (decisions, lessons, procedures) to be captured # even when it also appears in project documents. - sp = curation.SYSTEM_PROMPT + sp = curation.PHASE_ROLE_CONTEXT assert "Behavioral knowledge" in sp assert "MUST be" in sp assert "Rationale and rejected alternatives" in sp @@ -65,24 +65,24 @@ def test_system_prompt_behavioral_knowledge_must_be_captured(self): def test_system_prompt_enumerates_memory_tools(self): # Tools must be visible at the role layer. - sp = curation.SYSTEM_PROMPT + sp = curation.PHASE_ROLE_CONTEXT assert "koan_memorize" in sp assert "koan_forget" in sp assert "koan_memory_status" in sp def test_system_prompt_declares_classification_schema(self): - sp = curation.SYSTEM_PROMPT + sp = curation.PHASE_ROLE_CONTEXT for label in ("ADD", "UPDATE", "NOOP", "DEPRECATE"): - assert label in sp, f"schema label {label!r} missing from SYSTEM_PROMPT" + assert label in sp, f"schema label {label!r} missing from PHASE_ROLE_CONTEXT" def test_system_prompt_declares_structural_invariant(self): # Propose-then-write must be stated, not buried. - sp = curation.SYSTEM_PROMPT.lower() + sp = curation.PHASE_ROLE_CONTEXT.lower() assert "propose" in sp and "approve" in sp def test_system_prompt_declares_read_write_asymmetry(self): # Reads of .koan/memory/*.md are allowed; writes are not. - sp = curation.SYSTEM_PROMPT + sp = curation.PHASE_ROLE_CONTEXT # Reads explicitly allowed and explained: assert "Reading individual entries" in sp assert ".koan/memory/" in sp @@ -91,7 +91,7 @@ def test_system_prompt_declares_read_write_asymmetry(self): def test_system_prompt_acknowledges_coding_agent_memory(self): # CLAUDE.md / AGENTS.md / .cursor/ etc. are a separate, read-only system. - sp = curation.SYSTEM_PROMPT + sp = curation.PHASE_ROLE_CONTEXT assert "coding agent" in sp.lower() assert "CLAUDE.md" in sp assert "READ-ONLY" in sp diff --git a/tests/test_subagent.py b/tests/test_subagent.py index 0b2fedd..a01bc81 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -71,7 +71,7 @@ def _fake_phase_module(): mod = MagicMock() mod.ROLE = "intake" mod.TOTAL_STEPS = 3 - mod.SYSTEM_PROMPT = "test" + mod.PHASE_ROLE_CONTEXT = "test" mod.STEP_NAMES = {1: "Extract", 2: "Scout", 3: "Write"} mod.validate_step_completion = MagicMock(return_value=None) mod.get_next_step = MagicMock(return_value=1) From c5de1e111ca319670ef54dcf1d1adb7497bf47d3 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 17 Apr 2026 12:45:58 +0700 Subject: [PATCH 393/412] feat: add memory CLI and semantic retrieval search --- koan/__main__.py | 186 ++- koan/cli/__init__.py | 0 koan/cli/memory.py | 208 ++++ koan/cli/run.py | 106 ++ koan/lib/permissions.py | 14 +- koan/memory/__init__.py | 2 + koan/memory/ops.py | 180 +++ koan/memory/retrieval/__init__.py | 14 + koan/memory/retrieval/backend.py | 113 ++ koan/memory/retrieval/index.py | 157 +++ koan/memory/retrieval/rag.py | 58 + koan/memory/retrieval/types.py | 12 + koan/memory/store.py | 13 + koan/runners/base.py | 5 + koan/web/mcp_endpoint.py | 256 ++-- pyproject.toml | 2 + tests/memory/test_cli.py | 101 ++ tests/memory/test_cli_search.py | 131 +++ tests/memory/test_integration_retrieval.py | 80 ++ tests/memory/test_mcp_search.py | 141 +++ tests/memory/test_ops.py | 126 ++ tests/memory/test_rag.py | 138 +++ tests/memory/test_retrieval_backend.py | 190 +++ tests/test_permissions.py | 5 + uv.lock | 1217 ++++++++++++++++++++ 25 files changed, 3193 insertions(+), 262 deletions(-) create mode 100644 koan/cli/__init__.py create mode 100644 koan/cli/memory.py create mode 100644 koan/cli/run.py create mode 100644 koan/memory/ops.py create mode 100644 koan/memory/retrieval/__init__.py create mode 100644 koan/memory/retrieval/backend.py create mode 100644 koan/memory/retrieval/index.py create mode 100644 koan/memory/retrieval/rag.py create mode 100644 koan/memory/retrieval/types.py create mode 100644 tests/memory/test_cli.py create mode 100644 tests/memory/test_cli_search.py create mode 100644 tests/memory/test_integration_retrieval.py create mode 100644 tests/memory/test_mcp_search.py create mode 100644 tests/memory/test_ops.py create mode 100644 tests/memory/test_rag.py create mode 100644 tests/memory/test_retrieval_backend.py diff --git a/koan/__main__.py b/koan/__main__.py index 11a01bf..02de2a2 100644 --- a/koan/__main__.py +++ b/koan/__main__.py @@ -1,119 +1,105 @@ # Entry point: `uv run koan` or `python -m koan`. -# Loads config, builds AppState, starts the Starlette server on 127.0.0.1. -# -# In a development checkout (frontend/ directory exists next to the koan -# package), the entry point automatically rebuilds the Vite bundle into -# koan/web/static/app/ when frontend sources are newer than the last build. -# In an installed wheel the frontend/ directory is absent and the check is -# a no-op — the pre-built assets ship inside the wheel. +# Dispatches to subcommands: `koan run` and `koan memory ...`. from __future__ import annotations import argparse -import asyncio -import logging -import socket -import subprocess import sys -from pathlib import Path -import uvicorn - -from .config import load_koan_config from .logger import setup_logging -from .state import AppState -from .web.app import FRONTEND_DIST, create_app - -log = logging.getLogger(__name__) - -# Resolve relative to the *repository root* (one level above the koan package). -# Only present in a development checkout — absent in an installed wheel. -_REPO_ROOT = Path(__file__).resolve().parent.parent -_FRONTEND_SRC = _REPO_ROOT / "frontend" / "src" - - -def _frontend_needs_rebuild() -> bool: - """True when frontend sources are newer than the last Vite build.""" - if not _FRONTEND_SRC.is_dir(): - return False # not a dev checkout - - build_marker = FRONTEND_DIST / "index.html" - if not build_marker.exists(): - return True # never built - - build_mtime = build_marker.stat().st_mtime - return any( - p.stat().st_mtime > build_mtime - for p in _FRONTEND_SRC.rglob("*") - if p.is_file() - ) - - -def _rebuild_frontend() -> None: - """Run ``npm run build`` in the frontend directory.""" - frontend_dir = _FRONTEND_SRC.parent - log.info("Frontend sources changed — rebuilding…") - try: - subprocess.run( - ["npm", "run", "build"], - cwd=str(frontend_dir), - check=True, - capture_output=True, - text=True, - ) - log.info("Frontend build complete.") - except FileNotFoundError: - log.warning("npm not found — skipping frontend rebuild.") - except subprocess.CalledProcessError as exc: - log.error("Frontend build failed:\n%s", exc.stderr) - sys.exit(1) - +from .memory.types import MEMORY_TYPES +from .cli.memory import cmd_memory +from .cli.run import cmd_run -def _find_free_port() -> int: - """Bind to port 0 and let the OS assign a free ephemeral port.""" - with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: - s.bind(("127.0.0.1", 0)) - return s.getsockname()[1] +# Shared flags inherited by every subcommand. +_common = argparse.ArgumentParser(add_help=False) +_common.add_argument("--debug", action="store_true", + help="Enable debug logging") def main() -> None: - parser = argparse.ArgumentParser(prog="koan") - parser.add_argument("--port", type=int, default=None, - help="Port to listen on (default: random free port)") - parser.add_argument("--log-level", type=str, default="INFO") - parser.add_argument("--no-open", action="store_true", help="Don't open browser on startup") - parser.add_argument("--skip-build", action="store_true", help="Skip frontend rebuild check") - parser.add_argument("-p", "--prompt", type=str, default="", - help="Pre-fill the task description") - parser.add_argument("--yolo", action="store_true", - help="Skip all agent permission prompts (dangerous)") - parser.add_argument("--debug", action="store_true", - help="Show step guidance prompts in the UI") - args = parser.parse_args() - - log_level = "DEBUG" if args.debug else args.log_level - setup_logging(log_level) - - if not args.skip_build and _frontend_needs_rebuild(): - _rebuild_frontend() + parser = argparse.ArgumentParser(prog="koan", parents=[_common]) + subs = parser.add_subparsers(dest="subcommand") + + # koan run + run_parser = subs.add_parser("run", help="Start the koan web server", + parents=[_common]) + run_parser.add_argument("--port", type=int, default=None, + help="Port to listen on (default: random free port)") + run_parser.add_argument("--log-level", type=str, default="INFO") + run_parser.add_argument("--no-open", action="store_true", + help="Don't open browser on startup") + run_parser.add_argument("--skip-build", action="store_true", + help="Skip frontend rebuild check") + run_parser.add_argument("-p", "--prompt", type=str, default="", + help="Pre-fill the task description") + run_parser.add_argument("--yolo", action="store_true", + help="Skip all agent permission prompts (dangerous)") + + # koan memory + mem_parser = subs.add_parser("memory", help="Manage project memory", + parents=[_common]) + mem_subs = mem_parser.add_subparsers(dest="memory_command") + + mem_add = mem_subs.add_parser("memorize", help="Create or update a memory entry") + mem_add.add_argument("--type", required=True, choices=list(MEMORY_TYPES)) + mem_add.add_argument("--title", required=True) + mem_add.add_argument("--body", default=None, + help="Entry body (reads stdin if omitted)") + mem_add.add_argument("--related", action="append", default=[]) + mem_add.add_argument("--entry-id", type=int, default=None, dest="entry_id") + + mem_rm = mem_subs.add_parser("forget", help="Delete a memory entry") + mem_rm.add_argument("entry_id", type=int) + mem_rm.add_argument("--type", default=None, choices=list(MEMORY_TYPES)) + + mem_st = mem_subs.add_parser("status", help="Show summary and entry listing") + mem_st.add_argument("--type", default=None, choices=list(MEMORY_TYPES)) + mem_st.add_argument("--json", action="store_true", dest="json_output") + + mem_search = mem_subs.add_parser("search", help="Search memory entries") + mem_search.add_argument("query", help="Search query") + mem_search.add_argument("--type", default=None, choices=list(MEMORY_TYPES), + help="Filter by memory type") + mem_search.add_argument("-k", type=int, default=5, + help="Number of results (default: 5)") + mem_search.add_argument("--json", action="store_true", dest="json_output", + help="Machine-readable JSON output") + + mem_rag = mem_subs.add_parser("rag", help="Run RAG pipeline") + mem_rag.add_argument("--directive", required=True, + help="Retrieval directive (what kind of knowledge to find)") + mem_rag.add_argument("--anchor", required=True, + help="Topical anchor text or @path/to/file") + mem_rag.add_argument("-k", type=int, default=5, + help="Number of final results (default: 5)") + mem_rag.add_argument("--json", action="store_true", dest="json_output", + help="Machine-readable JSON output") + + mem_subs.add_parser("reflect", + help="Reflect on memory entries (not yet implemented)") - port = args.port if args.port is not None else _find_free_port() + args = parser.parse_args() - project_dir = Path.cwd() - if not project_dir.is_dir(): - sys.exit(f"koan: project directory does not exist: {project_dir}") + if args.subcommand is None: + parser.print_help() + sys.exit(1) - config = asyncio.run(load_koan_config()) - app_state = AppState(config=config, port=port, open_browser=not args.no_open, - initial_prompt=args.prompt, yolo=args.yolo, debug=args.debug, - project_dir=str(project_dir)) - app = create_app(app_state) + # Configure logging before any subcommand runs. + if args.debug: + log_level = "DEBUG" + elif args.subcommand == "run": + log_level = args.log_level + else: + log_level = "INFO" + setup_logging(log_level) - host = "127.0.0.1" - # timeout_graceful_shutdown=0: don't wait for HTTP clients to disconnect. - # Agent cleanup happens in the lifespan shutdown handler instead. - uvicorn.run(app, host=host, port=port, log_level=log_level.lower(), - timeout_graceful_shutdown=0) + if args.subcommand == "run": + args.log_level = log_level + cmd_run(args) + elif args.subcommand == "memory": + args._mem_parser = mem_parser + cmd_memory(args) if __name__ == "__main__": diff --git a/koan/cli/__init__.py b/koan/cli/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/koan/cli/memory.py b/koan/cli/memory.py new file mode 100644 index 0000000..d24aa7e --- /dev/null +++ b/koan/cli/memory.py @@ -0,0 +1,208 @@ +# CLI handlers for `koan memory` subcommands. + +from __future__ import annotations + +import argparse +import asyncio +import json +import os +import sys +from pathlib import Path + +from ..memory import ops +from ..memory.retrieval import RetrievalIndex, search as retrieval_search, inject as rag_inject +from ..memory.store import MemoryStore + + +def _make_store() -> MemoryStore: + store = MemoryStore(Path.cwd()) + store.init() + return store + + +def _make_index(store: MemoryStore) -> RetrievalIndex: + return RetrievalIndex(store._memory_dir) + + +def _die(msg: str) -> None: + print(json.dumps({"error": msg}), file=sys.stderr) + sys.exit(1) + + +def _has_api_key() -> bool: + return bool(os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY")) + + +def _print_human_readable(result: dict) -> None: + summary = result.get("summary") or "" + print("# Summary") + print(summary if summary else "(none)") + print() + + entries = result.get("entries") or [] + if not entries: + print("No entries.") + return + + col_id = 8 + col_type = 10 + header = f"{'entry_id':<{col_id}} {'type':<{col_type}} title" + print(header) + print("-" * len(header)) + for e in entries: + entry_id = str(e.get("entry_id", "")) + etype = str(e.get("type", "")) + title = str(e.get("title", "")) + print(f"{entry_id:<{col_id}} {etype:<{col_type}} {title}") + + +def cmd_memorize(args: argparse.Namespace) -> None: + store = _make_store() + body = args.body if args.body is not None else sys.stdin.read() + try: + result = ops.memorize( + store, + args.type, + args.title, + body, + related=args.related or None, + entry_id=args.entry_id, + ) + except ValueError as e: + _die(str(e)) + return + print(json.dumps(result)) + + +def cmd_forget(args: argparse.Namespace) -> None: + store = _make_store() + try: + result = ops.forget(store, args.entry_id, type=args.type) + except ValueError as e: + _die(str(e)) + return + print(json.dumps(result)) + + +def cmd_status(args: argparse.Namespace) -> None: + store = _make_store() + if store.summary_is_stale() and not _has_api_key(): + print( + "koan status: summary is stale but GEMINI_API_KEY is not set" + " -- cannot regenerate", + file=sys.stderr, + ) + sys.exit(1) + result = asyncio.run(ops.status(store, type=getattr(args, "type", None))) + if getattr(args, "json_output", False): + print(json.dumps(result)) + else: + _print_human_readable(result) + if result.get("regenerated"): + print("(summary regenerated)", file=sys.stderr) + + +def cmd_search(args: argparse.Namespace) -> None: + store = _make_store() + index = _make_index(store) + type_filter = getattr(args, "type", None) + k = getattr(args, "k", 5) + json_output = getattr(args, "json_output", False) + try: + results = asyncio.run(retrieval_search(index, args.query, k=k, type_filter=type_filter)) + except RuntimeError as e: + _die(str(e)) + return + if json_output: + out = { + "results": [ + { + "entry_id": r.entry_id, + "title": r.entry.title, + "type": r.entry.type, + "score": r.score, + "created": r.entry.created, + "modified": r.entry.modified, + "body": r.entry.body, + } + for r in results + ] + } + print(json.dumps(out)) + else: + sep = "-" * 60 + for r in results: + print(f"[{r.entry_id:04d}] {r.entry.title} type={r.entry.type} score={r.score:.4f}") + preview = r.entry.body[:200].replace("\n", " ") + print(f" {preview}...") + print(sep) + + +def cmd_rag(args: argparse.Namespace) -> None: + store = _make_store() + index = _make_index(store) + directive = args.directive + anchor_raw = args.anchor + k = getattr(args, "k", 5) + json_output = getattr(args, "json_output", False) + + if anchor_raw.startswith("@"): + anchor_path = Path(anchor_raw[1:]) + if not anchor_path.exists(): + _die(f"anchor file not found: {anchor_path}") + return + anchor = anchor_path.read_text(encoding="utf-8") + else: + anchor = anchor_raw + + try: + results = asyncio.run(rag_inject(index, directive, anchor, k=k)) + except RuntimeError as e: + _die(str(e)) + return + + if json_output: + out = { + "results": [ + { + "entry_id": r.entry_id, + "title": r.entry.title, + "type": r.entry.type, + "score": r.score, + "created": r.entry.created, + "modified": r.entry.modified, + "body": r.entry.body, + } + for r in results + ] + } + print(json.dumps(out)) + else: + sep = "-" * 60 + for r in results: + print(f"[{r.entry_id:04d}] {r.entry.title} type={r.entry.type} score={r.score:.4f}") + preview = r.entry.body[:200].replace("\n", " ") + print(f" {preview}...") + print(sep) + + +def cmd_memory(args: argparse.Namespace) -> None: + cmd = getattr(args, "memory_command", None) + if cmd == "memorize": + cmd_memorize(args) + elif cmd == "forget": + cmd_forget(args) + elif cmd == "status": + cmd_status(args) + elif cmd == "search": + cmd_search(args) + elif cmd == "rag": + cmd_rag(args) + elif cmd == "reflect": + print("koan memory reflect: not yet implemented", file=sys.stderr) + sys.exit(1) + else: + mem_parser = getattr(args, "_mem_parser", None) + if mem_parser is not None: + mem_parser.print_help() + sys.exit(1) diff --git a/koan/cli/run.py b/koan/cli/run.py new file mode 100644 index 0000000..b5aa01a --- /dev/null +++ b/koan/cli/run.py @@ -0,0 +1,106 @@ +# CLI handler for `koan run` -- starts the Starlette/uvicorn server. +# +# In a development checkout (frontend/ directory exists next to the koan +# package), this module automatically rebuilds the Vite bundle into +# koan/web/static/app/ when frontend sources are newer than the last build. +# In an installed wheel the frontend/ directory is absent and the check is +# a no-op -- the pre-built assets ship inside the wheel. + +from __future__ import annotations + +import argparse +import asyncio +import logging +import socket +import subprocess +import sys +from pathlib import Path + +import uvicorn + +from ..config import load_koan_config +from ..state import AppState +from ..web.app import FRONTEND_DIST, create_app + +log = logging.getLogger(__name__) + +# Resolve relative to the *repository root* (one level above the koan package). +# Only present in a development checkout -- absent in an installed wheel. +_REPO_ROOT = Path(__file__).resolve().parent.parent.parent +_FRONTEND_SRC = _REPO_ROOT / "frontend" / "src" + + +def _frontend_needs_rebuild() -> bool: + """True when frontend sources are newer than the last Vite build.""" + if not _FRONTEND_SRC.is_dir(): + return False # not a dev checkout + + build_marker = FRONTEND_DIST / "index.html" + if not build_marker.exists(): + return True # never built + + build_mtime = build_marker.stat().st_mtime + return any( + p.stat().st_mtime > build_mtime + for p in _FRONTEND_SRC.rglob("*") + if p.is_file() + ) + + +def _rebuild_frontend() -> None: + """Run ``npm run build`` in the frontend directory.""" + frontend_dir = _FRONTEND_SRC.parent + log.info("Frontend sources changed -- rebuilding...") + try: + subprocess.run( + ["npm", "run", "build"], + cwd=str(frontend_dir), + check=True, + capture_output=True, + text=True, + ) + log.info("Frontend build complete.") + except FileNotFoundError: + log.warning("npm not found -- skipping frontend rebuild.") + except subprocess.CalledProcessError as exc: + log.error("Frontend build failed:\n%s", exc.stderr) + sys.exit(1) + + +def _find_free_port() -> int: + """Bind to port 0 and let the OS assign a free ephemeral port.""" + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: + s.bind(("127.0.0.1", 0)) + return s.getsockname()[1] + + +def cmd_run(args: argparse.Namespace) -> None: + """Start the koan web server. Expects args from the `koan run` subparser.""" + log_level = args.log_level + + if not args.skip_build and _frontend_needs_rebuild(): + _rebuild_frontend() + + port = args.port if args.port is not None else _find_free_port() + + project_dir = Path.cwd() + if not project_dir.is_dir(): + sys.exit(f"koan: project directory does not exist: {project_dir}") + + config = asyncio.run(load_koan_config()) + app_state = AppState( + config=config, + port=port, + open_browser=not args.no_open, + initial_prompt=args.prompt, + yolo=args.yolo, + debug=args.debug, + project_dir=str(project_dir), + ) + app = create_app(app_state) + + host = "127.0.0.1" + # timeout_graceful_shutdown=0: don't wait for HTTP clients to disconnect. + # Agent cleanup happens in the lifespan shutdown handler instead. + uvicorn.run(app, host=host, port=port, log_level=log_level.lower(), + timeout_graceful_shutdown=0) diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index 007eea1..ec8f7db 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -8,6 +8,17 @@ # Only executor has unrestricted write access. # 5. The orchestrator role uses phase-aware permissions (current_phase parameter). # +# Enforcement layers: +# This fence gates MCP tool calls only. Claude Code built-in tools (Read, +# Write, Edit, Bash, etc.) are restricted at the CLI level via --tools +# whitelists in subagent.py (CLAUDE_TOOL_WHITELISTS). The two layers are +# complementary: --tools controls which built-in tools exist in the model's +# context; this fence controls which MCP tools are callable per role/phase. +# +# Path-scoping for write/edit (below) validates paths when called through +# the MCP endpoint. Built-in Write/Edit bypass MCP entirely, so path +# scoping for those relies on prompt engineering and the --tools whitelist. +# # Pure functions -- no I/O, no mutable state. from __future__ import annotations @@ -56,6 +67,7 @@ "koan_memorize", "koan_forget", "koan_memory_status", + "koan_search", "edit", "write", "bash", @@ -109,7 +121,7 @@ # Memory tools are available to the orchestrator in every phase. _ORCHESTRATOR_MEMORY_TOOLS: frozenset[str] = frozenset({ - "koan_memorize", "koan_forget", "koan_memory_status", + "koan_memorize", "koan_forget", "koan_memory_status", "koan_search", }) _ORCHESTRATOR_BASH_PHASES: frozenset[str] = frozenset({ diff --git a/koan/memory/__init__.py b/koan/memory/__init__.py index b8f576b..69aa313 100644 --- a/koan/memory/__init__.py +++ b/koan/memory/__init__.py @@ -14,6 +14,7 @@ from .store import MemoryStore from .llm import generate as llm_generate from .summarize import generate_summary, regenerate_summary +from . import ops __all__ = [ "MemoryType", @@ -28,4 +29,5 @@ "llm_generate", "generate_summary", "regenerate_summary", + "ops", ] diff --git a/koan/memory/ops.py b/koan/memory/ops.py new file mode 100644 index 0000000..3b31254 --- /dev/null +++ b/koan/memory/ops.py @@ -0,0 +1,180 @@ +# Pure CRUD and validation operations over MemoryStore. +# No MCP or web dependencies -- safe to import from CLI handlers. + +from __future__ import annotations + +import logging + +from .store import MemoryStore +from .types import MEMORY_TYPES + +log = logging.getLogger(__name__) + + +class EntryNotFoundError(ValueError): + """Raised when a requested entry_id does not exist.""" + + +class TypeMismatchError(ValueError): + """Raised when the found entry's type does not match the requested type.""" + + +def validate_memory_type(type_str: str) -> None: + """Raise ValueError if type_str is not a valid memory type.""" + if type_str not in MEMORY_TYPES: + raise ValueError( + f"'{type_str}' is not a valid memory type. " + f"Valid types: {list(MEMORY_TYPES)}" + ) + + +def entry_id_from_path(path_name: str) -> int | None: + """Extract NNNN sequence number from 'NNNN-slug.md'.""" + if len(path_name) < 5 or path_name[4] != "-": + return None + try: + return int(path_name[:4]) + except ValueError: + return None + + +def memorize( + store: MemoryStore, + type: str, + title: str, + body: str, + related: list[str] | None = None, + entry_id: int | None = None, +) -> dict: + """Create or update a memory entry. Raises ValueError on validation errors.""" + validate_memory_type(type) + + if entry_id is None: + log.info("memorize CREATE type=%s title=%r body_len=%d", type, title, len(body)) + entry = store.add_entry( + type=type, # type: ignore[arg-type] + title=title, + body=body, + related=related or [], + ) + new_id = entry_id_from_path(entry.file_path.name) if entry.file_path else None + log.info("memorize CREATED entry_id=%s file=%s", new_id, entry.file_path.name if entry.file_path else "?") + return { + "op": "created", + "type": type, + "entry_id": new_id, + "file_path": str(entry.file_path) if entry.file_path else None, + "created": entry.created, + "modified": entry.modified, + } + else: + log.info("memorize UPDATE entry_id=%d type=%s title=%r", entry_id, type, title) + existing = store.get_entry(entry_id) + if existing is None: + raise EntryNotFoundError(f"No entry with id {entry_id}") + if existing.type != type: + raise TypeMismatchError( + f"Entry {entry_id} has type '{existing.type}', not '{type}'" + ) + existing.title = title + existing.body = body + if related is not None: + existing.related = related + store.update_entry(existing) + log.info("memorize UPDATED entry_id=%d file=%s", entry_id, existing.file_path.name if existing.file_path else "?") + return { + "op": "updated", + "type": type, + "entry_id": entry_id, + "file_path": str(existing.file_path) if existing.file_path else None, + "created": existing.created, + "modified": existing.modified, + } + + +def forget( + store: MemoryStore, + entry_id: int, + type: str | None = None, +) -> dict: + """Delete a memory entry. Raises ValueError on validation or lookup errors.""" + if type is not None: + validate_memory_type(type) + + log.info("forget entry_id=%d type=%s", entry_id, type or "*") + existing = store.get_entry(entry_id) + if existing is None: + raise EntryNotFoundError(f"No entry with id {entry_id}") + if type is not None and existing.type != type: + raise TypeMismatchError( + f"Entry {entry_id} has type '{existing.type}', not '{type}'" + ) + path_str = str(existing.file_path) if existing.file_path else None + log.info( + "forget DELETING %s type=%s title=%r", + existing.file_path.name if existing.file_path else "?", + existing.type, + existing.title, + ) + store.forget_entry(existing) + log.info("forget DELETED entry_id=%d", entry_id) + return { + "op": "forgotten", + "type": existing.type, + "entry_id": entry_id, + "file_path": path_str, + } + + +async def status( + store: MemoryStore, + type: str | None = None, + regenerate: bool = True, +) -> dict: + """Return summary and entry listing. Regenerates stale summary when possible.""" + if type is not None: + validate_memory_type(type) + + log.info("status type=%s", type or "*") + + regenerated = False + regen_error: str | None = None + + if regenerate and store.summary_is_stale(): + log.info("status regenerating stale summary") + try: + await store.regenerate_summary() + regenerated = True + log.info("status summary regenerated") + except Exception: + log.exception("status summary regeneration failed") + regen_error = "Summary regeneration failed -- see server logs." + + summary = store.get_summary() or "" + entries = store.list_entries(type=type) # type: ignore[arg-type] + out_entries = [ + { + "entry_id": ( + entry_id_from_path(e.file_path.name) + if e.file_path else None + ), + "title": e.title, + "type": e.type, + "created": e.created, + "modified": e.modified, + } + for e in entries + ] + log.info( + "status returning %d entries, summary_len=%d, regenerated=%s", + len(out_entries), len(summary), regenerated, + ) + + result: dict = { + "summary": summary, + "entries": out_entries, + "regenerated": regenerated, + } + if regen_error: + result["error"] = regen_error + return result diff --git a/koan/memory/retrieval/__init__.py b/koan/memory/retrieval/__init__.py new file mode 100644 index 0000000..4970491 --- /dev/null +++ b/koan/memory/retrieval/__init__.py @@ -0,0 +1,14 @@ +from .backend import rerank_results, search, search_candidates +from .index import RetrievalIndex +from .rag import generate_queries, inject +from .types import SearchResult + +__all__ = [ + "SearchResult", + "RetrievalIndex", + "search", + "search_candidates", + "rerank_results", + "inject", + "generate_queries", +] diff --git a/koan/memory/retrieval/backend.py b/koan/memory/retrieval/backend.py new file mode 100644 index 0000000..9dadc5e --- /dev/null +++ b/koan/memory/retrieval/backend.py @@ -0,0 +1,113 @@ +from __future__ import annotations + +from pathlib import Path + +import voyageai + +from koan.logger import get_logger + +from ..parser import parse_entry +from .index import RetrievalIndex, _embed_query, _voyage_api_key +from .types import SearchResult + +log = get_logger("memory.retrieval.backend") + + +def _rrf_score(ranks: list[int], k: int = 60) -> float: + return sum(1.0 / (k + r) for r in ranks) + + +def _rrf_merge(dense_hits: list[dict], fts_hits: list[dict]) -> list[dict]: + # Map entry_id -> (row, list of ranks) + rows: dict[int, dict] = {} + ranks: dict[int, list[int]] = {} + + for rank, row in enumerate(dense_hits): + eid = row["entry_id"] + rows[eid] = row + ranks.setdefault(eid, []).append(rank) + + for rank, row in enumerate(fts_hits): + eid = row["entry_id"] + rows[eid] = row + ranks.setdefault(eid, []).append(rank) + + merged = [] + for eid, row in rows.items(): + score = _rrf_score(ranks[eid]) + merged.append({**row, "_rrf_score": score}) + + merged.sort(key=lambda r: r["_rrf_score"], reverse=True) + return merged + + +async def _voyage_rerank( + query: str, candidates: list[dict], k: int +) -> list[dict]: + log.debug("voyage_rerank: %d candidates, k=%d", len(candidates), k) + client = voyageai.AsyncClient(api_key=_voyage_api_key()) + result = await client.rerank( + query=query, + documents=[c["body"] for c in candidates], + model="rerank-2.5", + top_k=k, + ) + reranked = [] + for item in result.results: + row = {**candidates[item.index], "_rerank_score": item.relevance_score} + reranked.append(row) + return reranked + + +# search_candidates and rerank_results are split out from search() so the +# RAG pipeline (rag.py) can call search_candidates per generated query, merge +# candidates across queries, then rerank_results once on the merged pool. +# Without the split, the RAG path would run the Voyage reranker N times +# (once per query) or duplicate the reranker logic. +async def search_candidates( + index: RetrievalIndex, query: str, n: int = 20 +) -> list[dict]: + query_vec = await _embed_query(query) + dense = await index.dense_search(query_vec, n) + fts = await index.fts_search(query, n) + log.debug("search_candidates query=%r dense=%d fts=%d", query, len(dense), len(fts)) + merged = _rrf_merge(dense, fts) + log.debug("rrf_merge produced %d candidates", len(merged)) + return merged + + +async def rerank_results( + query: str, + candidates: list[dict], + k: int, + type_filter: str | None = None, +) -> list[SearchResult]: + if type_filter: + candidates = [c for c in candidates if c["type"] == type_filter] + log.debug("type_filter=%r narrowed to %d candidates", type_filter, len(candidates)) + if not candidates: + return [] + reranked = await _voyage_rerank(query, candidates, k) + log.debug("reranked %d candidates to top %d", len(candidates), len(reranked)) + for c in reranked: + log.debug(" entry_id=%d score=%.4f title=%r", c["entry_id"], c["_rerank_score"], c.get("title", "")) + results = [] + for c in reranked: + entry = parse_entry(Path(c["file_path"])) + results.append(SearchResult( + entry=entry, + entry_id=c["entry_id"], + score=c["_rerank_score"], + )) + return results + + +async def search( + index: RetrievalIndex, + query: str, + k: int = 5, + type_filter: str | None = None, +) -> list[SearchResult]: + await index.ensure_synced() + candidates = await search_candidates(index, query, n=20) + return await rerank_results(query, candidates, k, type_filter) diff --git a/koan/memory/retrieval/index.py b/koan/memory/retrieval/index.py new file mode 100644 index 0000000..5c51f10 --- /dev/null +++ b/koan/memory/retrieval/index.py @@ -0,0 +1,157 @@ +from __future__ import annotations + +import asyncio +import hashlib +import os +import re +from pathlib import Path + +import lancedb +import pyarrow as pa +import voyageai +from lancedb.index import FTS + +from ..parser import parse_entry + +VOYAGE_MODEL = "voyage-4-large" +VOYAGE_DIM = 1024 +TABLE_NAME = "entries" +_ENTRY_PATTERN = re.compile(r"^(\d{4})-.*\.md$") + + +def _content_hash(path: Path) -> str: + return hashlib.sha256(path.read_bytes()).hexdigest() + + +def _entry_id_from_name(name: str) -> int | None: + m = _ENTRY_PATTERN.match(name) + if m is None: + return None + return int(m.group(1)) + + +def _voyage_api_key() -> str: + key = os.environ.get("VOYAGE_API_KEY") or "" + if not key: + raise RuntimeError("VOYAGE_API_KEY environment variable is required") + return key + + +async def _embed_texts(texts: list[str], input_type: str) -> list[list[float]]: + client = voyageai.AsyncClient(api_key=_voyage_api_key()) + result = await client.embed(texts, model=VOYAGE_MODEL, input_type=input_type) + return result.embeddings + + +async def _embed_query(text: str) -> list[float]: + result = await _embed_texts([text], "query") + return result[0] + + +def _lancedb_schema() -> pa.Schema: + return pa.schema([ + pa.field("entry_id", pa.int32()), + pa.field("file_path", pa.utf8()), + pa.field("title", pa.utf8()), + pa.field("type", pa.utf8()), + pa.field("created", pa.utf8()), + pa.field("modified", pa.utf8()), + pa.field("body", pa.utf8()), + pa.field("content_hash", pa.utf8()), + pa.field("vector", pa.list_(pa.float32(), VOYAGE_DIM)), + ]) + + +class RetrievalIndex: + def __init__(self, memory_dir: Path) -> None: + self._memory_dir = memory_dir + self._index_path = memory_dir / ".index" + self._lock: asyncio.Lock = asyncio.Lock() + self._synced: bool = False + + async def ensure_synced(self) -> None: + async with self._lock: + await self._sync() + self._synced = True + + async def _sync(self) -> None: + conn = await lancedb.connect_async(str(self._index_path)) + + # Create-or-open: exist_ok=True returns existing table without overwriting data + table = await conn.create_table(TABLE_NAME, schema=_lancedb_schema(), exist_ok=True) + + # Load existing hashes: entry_id -> content_hash + rows = await table.query().select(["entry_id", "content_hash"]).to_list() + stored: dict[int, str] = {r["entry_id"]: r["content_hash"] for r in rows} + + # Scan memory_dir for NNNN-*.md files (excluding summary.md) + disk: dict[int, Path] = {} + if self._memory_dir.is_dir(): + for p in self._memory_dir.iterdir(): + if p.name == "summary.md": + continue + eid = _entry_id_from_name(p.name) + if eid is not None: + disk[eid] = p + + # Find changed or new files + to_embed: list[tuple[int, Path]] = [] + for eid, path in disk.items(): + h = _content_hash(path) + if stored.get(eid) != h: + to_embed.append((eid, path)) + + if to_embed: + entries = [parse_entry(path) for _, path in to_embed] + texts = [ + f"# {e.title}\ntype: {e.type}\n\n{e.body}" + for e in entries + ] + vectors = await _embed_texts(texts, "document") + + records = [] + for (eid, path), entry, vector in zip(to_embed, entries, vectors): + records.append({ + "entry_id": eid, + "file_path": str(path), + "title": entry.title, + "type": entry.type, + "created": entry.created, + "modified": entry.modified, + "body": entry.body, + "content_hash": _content_hash(path), + "vector": vector, + }) + + # Upsert: delete existing rows for these entry_ids, then add new + existing_eids = [eid for eid, _ in to_embed if eid in stored] + if existing_eids: + ids_str = ", ".join(str(e) for e in existing_eids) + await table.delete(f"entry_id IN ({ids_str})") + + if records: + await table.add(records) + + # Delete rows for files that no longer exist on disk + deleted_eids = [eid for eid in stored if eid not in disk] + if deleted_eids: + ids_str = ", ".join(str(e) for e in deleted_eids) + await table.delete(f"entry_id IN ({ids_str})") + + # Ensure FTS index exists (idempotent) -- only if the table has rows + all_rows = await table.query().select(["entry_id"]).to_list() + if all_rows: + await table.create_index("body", config=FTS(), replace=True) + await table.create_index("title", config=FTS(), replace=True) + + async def dense_search(self, query_vector: list[float], n: int = 20) -> list[dict]: + conn = await lancedb.connect_async(str(self._index_path)) + table = await conn.open_table(TABLE_NAME) + builder = await table.search(query_vector) + return await builder.limit(n).to_list() + + async def fts_search(self, query: str, n: int = 20) -> list[dict]: + conn = await lancedb.connect_async(str(self._index_path)) + table = await conn.open_table(TABLE_NAME) + builder = await table.search(query, query_type="fts") + return await builder.limit(n).to_list() diff --git a/koan/memory/retrieval/rag.py b/koan/memory/retrieval/rag.py new file mode 100644 index 0000000..3b1e07c --- /dev/null +++ b/koan/memory/retrieval/rag.py @@ -0,0 +1,58 @@ +from __future__ import annotations + +from koan.logger import get_logger +from koan.memory.llm import generate as llm_generate + +from .backend import rerank_results, search_candidates +from .index import RetrievalIndex +from .types import SearchResult + +log = get_logger("memory.retrieval.rag") + +_QUERY_GEN_SYSTEM = ( + "You are a search query generator for a project memory system. " + "Given a retrieval directive and anchor context, produce 1-3 concise search " + "queries that will retrieve memory entries relevant to the directive. " + "Output one query per line. No numbering, no bullets, no preamble." +) + + +async def generate_queries(directive: str, anchor: str) -> list[str]: + prompt = f"Directive: {directive}\n\nContext:\n{anchor}" + raw = await llm_generate(prompt, system=_QUERY_GEN_SYSTEM, max_tokens=256) + lines = [line.strip() for line in raw.splitlines()] + queries = [q for q in lines if q][:3] + log.debug("generated %d queries: %s", len(queries), queries) + return queries + + +_generate_queries = generate_queries + + +async def inject( + index: RetrievalIndex, + directive: str, + anchor: str, + k: int = 5, +) -> list[SearchResult]: + await index.ensure_synced() + queries = await _generate_queries(directive, anchor) + + # Gather candidates from each query, merge by entry_id (max RRF score) + merged: dict[int, dict] = {} + for query in queries: + candidates = await search_candidates(index, query, n=20) + log.debug("query=%r returned %d candidates", query, len(candidates)) + for c in candidates: + eid = c["entry_id"] + if eid not in merged or c["_rrf_score"] > merged[eid]["_rrf_score"]: + merged[eid] = c + + merged_list = sorted(merged.values(), key=lambda r: r["_rrf_score"], reverse=True) + log.debug("merged pool: %d unique entries", len(merged_list)) + # Rerank against the directive (the human-authored intent statement), not + # the generated queries. The directive unifies all queries and is what the + # reranker should optimize for -- one API call instead of N. + results = await rerank_results(directive, merged_list, k) + log.debug("reranked to %d results", len(results)) + return results diff --git a/koan/memory/retrieval/types.py b/koan/memory/retrieval/types.py new file mode 100644 index 0000000..02cf4cc --- /dev/null +++ b/koan/memory/retrieval/types.py @@ -0,0 +1,12 @@ +from __future__ import annotations + +from dataclasses import dataclass + +from ..types import MemoryEntry + + +@dataclass +class SearchResult: + entry: MemoryEntry + entry_id: int + score: float diff --git a/koan/memory/store.py b/koan/memory/store.py index e62805e..2781c1b 100644 --- a/koan/memory/store.py +++ b/koan/memory/store.py @@ -119,6 +119,19 @@ def get_summary(self) -> str | None: log.debug("get_summary no summary.md found") return None + def summary_is_stale(self) -> bool: + """True if summary.md is missing or older than any entry file.""" + summary_path = self._memory_dir / "summary.md" + if not summary_path.is_file(): + return self.entry_count() > 0 + summary_mtime = summary_path.stat().st_mtime + for e in self.list_entries(): + if e.file_path is None: + continue + if e.file_path.stat().st_mtime > summary_mtime: + return True + return False + async def regenerate_summary(self, project_name: str = "") -> None: """Regenerate summary.md from all current entries.""" log.info("regenerate_summary starting (project_name=%r, entry_count=%d)", project_name, self.entry_count()) diff --git a/koan/runners/base.py b/koan/runners/base.py index 61dc817..5677ece 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -69,6 +69,7 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: ... KOAN_MCP_TOOLS: frozenset[str] = frozenset({ "koan_complete_step", "koan_set_phase", + "koan_yield", "koan_request_scouts", "koan_ask_question", "koan_request_executor", @@ -76,4 +77,8 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: ... "koan_complete_story", "koan_retry_story", "koan_skip_story", + "koan_memorize", + "koan_forget", + "koan_memory_status", + "koan_search", }) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index a7f239b..7e945ff 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -899,25 +899,28 @@ async def koan_skip_story(story_id: str, reason: str = "") -> str: # -- Memory tools -------------------------------------------------------------- -def _validate_memory_type(type_str: str) -> None: - if type_str not in MEMORY_TYPES: - raise ToolError(json.dumps({ - "error": "invalid_type", - "message": ( - f"'{type_str}' is not a valid memory type. " - f"Valid types: {list(MEMORY_TYPES)}" - ), - })) +from ..memory import ops as memory_ops +from ..memory.ops import EntryNotFoundError, TypeMismatchError +from ..memory.types import MEMORY_TYPES +from ..memory.retrieval import RetrievalIndex, search as retrieval_search +_retrieval_index: RetrievalIndex | None = None + + +def _get_retrieval_index() -> RetrievalIndex: + global _retrieval_index + if _retrieval_index is None: + assert _app_state is not None + project_dir = _app_state.project_dir or "." + memory_dir = Path(project_dir) / ".koan" / "memory" + _retrieval_index = RetrievalIndex(memory_dir) + return _retrieval_index -def _entry_id_from_path(path_name: str) -> int | None: - """Extract NNNN prefix from 'NNNN-slug.md'.""" - if len(path_name) < 5 or path_name[4] != "-": - return None - try: - return int(path_name[:4]) - except ValueError: - return None + +def _reset_retrieval_index() -> None: + """Test hook: clear the cached RetrievalIndex.""" + global _retrieval_index + _retrieval_index = None @mcp.tool(name="koan_memorize") @@ -958,7 +961,6 @@ async def koan_memorize( _check_or_raise(agent, "koan_memorize", { "type": type, "title": title, "entry_id": entry_id, }) - call_id = begin_tool_call( agent, "koan_memorize", {"type": type, "title": title, "entry_id": entry_id}, @@ -966,61 +968,17 @@ async def koan_memorize( ) result_str: str | None = None try: - _validate_memory_type(type) - store = _get_memory_store() - - if entry_id is None: - log.info("koan_memorize CREATE type=%s title=%r body_len=%d", type, title, len(body)) - entry = store.add_entry( - type=type, # type: ignore[arg-type] - title=title, - body=body, - related=related or [], - ) - new_id = _entry_id_from_path(entry.file_path.name) if entry.file_path else None - log.info("koan_memorize CREATED entry_id=%s file=%s", new_id, entry.file_path.name if entry.file_path else "?") - result_str = json.dumps({ - "op": "created", - "type": type, - "entry_id": new_id, - "file_path": str(entry.file_path) if entry.file_path else None, - "created": entry.created, - "modified": entry.modified, - }) - else: - log.info("koan_memorize UPDATE entry_id=%d type=%s title=%r", entry_id, type, title) - existing = store.get_entry(entry_id) - if existing is None: - raise ToolError(json.dumps({ - "error": "entry_not_found", - "message": f"No entry with id {entry_id}", - })) - if existing.type != type: - raise ToolError(json.dumps({ - "error": "type_mismatch", - "message": ( - f"Entry {entry_id} has type '{existing.type}', " - f"not '{type}'" - ), - })) - existing.title = title - existing.body = body - if related is not None: - existing.related = related - store.update_entry(existing) - log.info("koan_memorize UPDATED entry_id=%d file=%s", entry_id, existing.file_path.name if existing.file_path else "?") - result_str = json.dumps({ - "op": "updated", - "type": type, - "entry_id": entry_id, - "file_path": str(existing.file_path) if existing.file_path else None, - "created": existing.created, - "modified": existing.modified, - }) - + result = memory_ops.memorize(store, type, title, body, related, entry_id) + result_str = json.dumps(result) result_str = _drain_and_append_steering(result_str, agent) return result_str + except EntryNotFoundError as e: + raise ToolError(json.dumps({"error": "entry_not_found", "message": str(e)})) + except TypeMismatchError as e: + raise ToolError(json.dumps({"error": "type_mismatch", "message": str(e)})) + except ValueError as e: + raise ToolError(json.dumps({"error": "invalid_type", "message": str(e)})) finally: end_tool_call(agent, call_id, "koan_memorize", result_str) @@ -1038,7 +996,6 @@ async def koan_forget(entry_id: int, type: str | None = None) -> str: """ agent = _get_agent() _check_or_raise(agent, "koan_forget", {"type": type, "entry_id": entry_id}) - call_id = begin_tool_call( agent, "koan_forget", {"type": type, "entry_id": entry_id}, @@ -1046,57 +1003,21 @@ async def koan_forget(entry_id: int, type: str | None = None) -> str: ) result_str: str | None = None try: - if type is not None: - _validate_memory_type(type) - - log.info("koan_forget entry_id=%d type=%s", entry_id, type or "*") store = _get_memory_store() - existing = store.get_entry(entry_id) - if existing is None: - raise ToolError(json.dumps({ - "error": "entry_not_found", - "message": f"No entry with id {entry_id}", - })) - if type is not None and existing.type != type: - raise ToolError(json.dumps({ - "error": "type_mismatch", - "message": ( - f"Entry {entry_id} has type '{existing.type}', " - f"not '{type}'" - ), - })) - path_str = str(existing.file_path) if existing.file_path else None - log.info("koan_forget DELETING %s type=%s title=%r", existing.file_path.name if existing.file_path else "?", existing.type, existing.title) - store.forget_entry(existing) - log.info("koan_forget DELETED entry_id=%d", entry_id) - result_str = json.dumps({ - "op": "forgotten", - "type": existing.type, - "entry_id": entry_id, - "file_path": path_str, - }) + result = memory_ops.forget(store, entry_id, type) + result_str = json.dumps(result) result_str = _drain_and_append_steering(result_str, agent) return result_str + except EntryNotFoundError as e: + raise ToolError(json.dumps({"error": "entry_not_found", "message": str(e)})) + except TypeMismatchError as e: + raise ToolError(json.dumps({"error": "type_mismatch", "message": str(e)})) + except ValueError as e: + raise ToolError(json.dumps({"error": "invalid_type", "message": str(e)})) finally: end_tool_call(agent, call_id, "koan_forget", result_str) -def _summary_is_stale(store: MemoryStore) -> bool: - """Return True if summary.md is missing or older than any entry file.""" - summary_path = store._memory_dir / "summary.md" - if not summary_path.is_file(): - # Only stale if at least one entry exists; otherwise there is - # nothing to summarize and we do not force a regeneration. - return store.entry_count() > 0 - summary_mtime = summary_path.stat().st_mtime - for e in store.list_entries(): - if e.file_path is None: - continue - if e.file_path.stat().st_mtime > summary_mtime: - return True - return False - - @mcp.tool(name="koan_memory_status") async def koan_memory_status(type: str | None = None) -> str: """Get an orientation view of project memory. @@ -1111,64 +1032,77 @@ async def koan_memory_status(type: str | None = None) -> str: """ agent = _get_agent() _check_or_raise(agent, "koan_memory_status", {"type": type}) - call_id = begin_tool_call( agent, "koan_memory_status", {"type": type}, type or "all", ) result_str: str | None = None try: - if type is not None: - _validate_memory_type(type) - - log.info("koan_memory_status type=%s", type or "*") store = _get_memory_store() + result = await memory_ops.status(store, type=type) + result_str = json.dumps(result) + result_str = _drain_and_append_steering(result_str, agent) + return result_str + except ValueError as e: + raise ToolError(json.dumps({ + "error": "invalid_type", + "message": str(e), + })) + finally: + end_tool_call(agent, call_id, "koan_memory_status", result_str) - regenerated = False - regen_error: str | None = None - stale = _summary_is_stale(store) - log.debug("koan_memory_status summary_stale=%s", stale) - if stale: - log.info("koan_memory_status regenerating stale summary") - try: - await store.regenerate_summary() - regenerated = True - log.info("koan_memory_status summary regenerated") - except Exception: - log.exception("koan_memory_status summary regeneration failed") - regen_error = "Summary regeneration failed -- see server logs." - - summary = store.get_summary() or "" - entries = store.list_entries(type=type) # type: ignore[arg-type] - out_entries = [ - { - "entry_id": ( - _entry_id_from_path(e.file_path.name) - if e.file_path else None - ), - "title": e.title, - "type": e.type, - "created": e.created, - "modified": e.modified, - } - for e in entries - ] - log.info( - "koan_memory_status returning %d entries, summary_len=%d, regenerated=%s", - len(out_entries), len(summary), regenerated, - ) - result: dict = { - "summary": summary, - "entries": out_entries, - "regenerated": regenerated, +@mcp.tool(name="koan_search") +async def koan_search( + query: str, + type: str | None = None, + k: int = 5, +) -> str: + """Search memory entries by semantic similarity. + + Runs hybrid dense + BM25 search with cross-encoder reranking. + Returns the top k entries most relevant to the query. + + Args: + query: Search query string + type: Filter results to a specific memory type (optional) + k: Number of results to return (default: 5) + """ + agent = _get_agent() + _check_or_raise(agent, "koan_search", {"type": type}) + call_id = begin_tool_call( + agent, "koan_search", + {"query": query, "type": type, "k": k}, + f"query={query!r} type={type or 'all'} k={k}", + ) + result_str: str | None = None + try: + if type is not None and type not in MEMORY_TYPES: + raise ValueError(f"invalid type: {type!r}") + index = _get_retrieval_index() + results = await retrieval_search(index, query, k=k, type_filter=type) + out = { + "results": [ + { + "entry_id": r.entry_id, + "title": r.entry.title, + "type": r.entry.type, + "score": r.score, + "created": r.entry.created, + "modified": r.entry.modified, + "body": r.entry.body, + } + for r in results + ] } - if regen_error: - result["error"] = regen_error - result_str = json.dumps(result) + result_str = json.dumps(out) result_str = _drain_and_append_steering(result_str, agent) return result_str + except ValueError as e: + raise ToolError(json.dumps({"error": "invalid_type", "message": str(e)})) + except RuntimeError as e: + raise ToolError(json.dumps({"error": "search_failed", "message": str(e)})) finally: - end_tool_call(agent, call_id, "koan_memory_status", result_str) + end_tool_call(agent, call_id, "koan_search", result_str) # -- ASGI wrapper -------------------------------------------------------------- diff --git a/pyproject.toml b/pyproject.toml index 1a666db..cc40879 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,6 +11,8 @@ dependencies = [ "pyyaml", "google-genai>=1.0", "json-repair>=0.59.4", + "voyageai>=0.3", + "lancedb>=0.20", ] [project.scripts] diff --git a/tests/memory/test_cli.py b/tests/memory/test_cli.py new file mode 100644 index 0000000..fd6b543 --- /dev/null +++ b/tests/memory/test_cli.py @@ -0,0 +1,101 @@ +# Tests for koan/cli/memory.py -- CLI-specific behavior only. +# Business logic (create/update/delete/type validation) is covered by +# test_ops.py and test_mcp_memory.py; this file tests only CLI concerns: +# stdin body reading, stdout JSON wiring, stale+no-API-key early exit, +# human-readable table format, and placeholder command exits. + +from __future__ import annotations + +import argparse +import json +import sys +from io import StringIO + +import pytest + +from koan.cli.memory import cmd_memorize, cmd_forget, cmd_status, cmd_memory +from koan.memory import ops +from koan.memory.store import MemoryStore + + +# --------------------------------------------------------------------------- +# Fixtures and helpers +# --------------------------------------------------------------------------- + +@pytest.fixture +def store_env(tmp_path, monkeypatch): + """Create a MemoryStore in tmp_path and monkeypatch _make_store to return it.""" + store = MemoryStore(tmp_path) + store.init() + monkeypatch.setattr("koan.cli.memory._make_store", lambda: store) + return store + + +def ns(**kwargs) -> argparse.Namespace: + return argparse.Namespace(**kwargs) + + +# --------------------------------------------------------------------------- +# Tests +# --------------------------------------------------------------------------- + +def test_memorize_stdin_body(store_env, monkeypatch, capsys): + """Stdin fallback path: body=None reads from sys.stdin.""" + monkeypatch.setattr("sys.stdin", StringIO("body from stdin")) + cmd_memorize(ns(type="context", title="T", body=None, related=[], entry_id=None)) + out = capsys.readouterr().out + result = json.loads(out) + assert result["op"] == "created" + + +def test_forget_prints_json_to_stdout(store_env, capsys): + """Output wiring: cmd_forget prints valid JSON with op=forgotten to stdout.""" + created = ops.memorize(store_env, "decision", "To delete", "Body.") + cmd_forget(ns(entry_id=created["entry_id"], type=None)) + out = capsys.readouterr().out + result = json.loads(out) + assert result["op"] == "forgotten" + + +def test_status_stale_no_api_key_exits(store_env, monkeypatch, capsys): + """Early-exit guard: stale summary without API key exits with code 1.""" + ops.memorize(store_env, "context", "Entry", "Body.") + # summary.md is absent -> summary_is_stale() returns True + monkeypatch.delenv("GEMINI_API_KEY", raising=False) + monkeypatch.delenv("GOOGLE_API_KEY", raising=False) + with pytest.raises(SystemExit) as exc: + cmd_status(ns(type=None, json_output=True)) + assert exc.value.code == 1 + err = capsys.readouterr().err + assert "GEMINI_API_KEY" in err + + +def test_status_human_readable_output(store_env, tmp_path, capsys): + """Human-readable format: table header and entry titles appear in stdout.""" + ops.memorize(store_env, "context", "Alpha entry", "Body.") + ops.memorize(store_env, "decision", "Beta entry", "Body.") + + # Write a fresh summary.md so no regeneration is attempted. + import os, time + summary_path = tmp_path / ".koan" / "memory" / "summary.md" + summary_path.write_text("Dummy summary.", encoding="utf-8") + future = time.time() + 2 + os.utime(summary_path, (future, future)) + + cmd_status(ns(type=None, json_output=False)) + out = capsys.readouterr().out + assert "entry_id" in out + assert "type" in out + assert "title" in out + assert "Alpha entry" in out + assert "Beta entry" in out + + +def test_placeholder_commands_exit(store_env, capsys): + """Placeholder subcommands exit with code 1 and print 'not yet implemented'.""" + for cmd in ("reflect",): + with pytest.raises(SystemExit) as exc: + cmd_memory(ns(memory_command=cmd)) + assert exc.value.code == 1 + err = capsys.readouterr().err + assert "not yet implemented" in err diff --git a/tests/memory/test_cli_search.py b/tests/memory/test_cli_search.py new file mode 100644 index 0000000..e7849fe --- /dev/null +++ b/tests/memory/test_cli_search.py @@ -0,0 +1,131 @@ +from __future__ import annotations + +import argparse +import json +from pathlib import Path +from unittest.mock import AsyncMock, MagicMock, patch + +import pytest + +import koan.cli.memory as cli_memory +from koan.cli.memory import cmd_rag, cmd_search +from koan.memory.retrieval.types import SearchResult +from koan.memory.store import MemoryStore +from koan.memory.types import MemoryEntry + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +def ns(**kwargs) -> argparse.Namespace: + return argparse.Namespace(**kwargs) + + +def _make_entry(n: int = 1, etype: str = "context") -> MemoryEntry: + return MemoryEntry( + title=f"Title {n}", + type=etype, + body=f"Body of entry {n}.", + created="2024-01-01", + modified="2024-01-01", + ) + + +def _make_result(n: int = 1, etype: str = "context") -> SearchResult: + return SearchResult(entry=_make_entry(n, etype), entry_id=n, score=0.85) + + +FIXED_RESULTS = [_make_result(1), _make_result(2)] + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + +@pytest.fixture +def store_env(tmp_path, monkeypatch): + store = MemoryStore(tmp_path) + store.init() + monkeypatch.setattr("koan.cli.memory._make_store", lambda: store) + return store + + +@pytest.fixture +def search_env(store_env, monkeypatch): + mock_index = MagicMock() + monkeypatch.setattr("koan.cli.memory._make_index", lambda _store: mock_index) + monkeypatch.setattr(cli_memory, "retrieval_search", AsyncMock(return_value=FIXED_RESULTS)) + monkeypatch.setattr(cli_memory, "rag_inject", AsyncMock(return_value=FIXED_RESULTS)) + return {"store": store_env, "mock_index": mock_index} + + +# --------------------------------------------------------------------------- +# cmd_search tests +# --------------------------------------------------------------------------- + +def test_cmd_search_human_readable(search_env, capsys) -> None: + cmd_search(ns(query="test", type=None, k=5, json_output=False)) + out = capsys.readouterr().out + assert "0001" in out + assert "Title 1" in out + + +def test_cmd_search_json_output(search_env, capsys) -> None: + cmd_search(ns(query="test", type=None, k=5, json_output=True)) + out = capsys.readouterr().out + result = json.loads(out) + assert "results" in result + assert len(result["results"]) == 2 + + +def test_cmd_search_type_filter_forwarded(search_env, monkeypatch) -> None: + captured = {} + + async def mock_search(index, query, k=5, type_filter=None): + captured["type_filter"] = type_filter + return FIXED_RESULTS + + monkeypatch.setattr(cli_memory, "retrieval_search", mock_search) + cmd_search(ns(query="x", type="decision", k=5, json_output=False)) + assert captured["type_filter"] == "decision" + + +# --------------------------------------------------------------------------- +# cmd_rag tests +# --------------------------------------------------------------------------- + +def test_cmd_rag_json_output(search_env, capsys) -> None: + cmd_rag(ns(directive="find stuff", anchor="some context", k=5, json_output=True)) + out = capsys.readouterr().out + result = json.loads(out) + assert "results" in result + assert len(result["results"]) == 2 + + +def test_cmd_rag_at_file_anchor(search_env, tmp_path, capsys) -> None: + anchor_file = tmp_path / "anchor.txt" + anchor_file.write_text("anchor content from file", encoding="utf-8") + + captured = {} + + async def mock_inject(index, directive, anchor, k=5): + captured["anchor"] = anchor + return FIXED_RESULTS + + import koan.cli.memory as cli_mod + with patch.object(cli_mod, "rag_inject", mock_inject): + cmd_rag(ns( + directive="d", + anchor=f"@{anchor_file}", + k=5, + json_output=False, + )) + + assert captured["anchor"] == "anchor content from file" + + +def test_cmd_rag_missing_anchor_file_exits(search_env, capsys) -> None: + with pytest.raises(SystemExit) as exc: + cmd_rag(ns(directive="d", anchor="@/nonexistent/file.txt", k=5, json_output=False)) + assert exc.value.code == 1 diff --git a/tests/memory/test_integration_retrieval.py b/tests/memory/test_integration_retrieval.py new file mode 100644 index 0000000..4fb3e5c --- /dev/null +++ b/tests/memory/test_integration_retrieval.py @@ -0,0 +1,80 @@ +from __future__ import annotations + +import os +from pathlib import Path + +import pytest + +from koan.memory.retrieval import RetrievalIndex, inject, search + +requires_keys = pytest.mark.skipif( + not os.environ.get("VOYAGE_API_KEY"), + reason="VOYAGE_API_KEY required", +) + + +def _write_entry(mem_dir: Path, n: int, title: str, body: str, etype: str = "context") -> None: + slug = title.lower().replace(" ", "-") + path = mem_dir / f"{n:04d}-{slug}.md" + path.write_text( + f"---\ntitle: {title}\ntype: {etype}\ncreated: 2024-01-01\nmodified: 2024-01-01\n---\n\n{body}\n", + encoding="utf-8", + ) + + +@pytest.fixture +def mem_dir(tmp_path: Path) -> Path: + d = tmp_path / ".koan" / "memory" + d.mkdir(parents=True) + return d + + +@requires_keys +@pytest.mark.anyio +async def test_end_to_end_search(mem_dir: Path) -> None: + _write_entry(mem_dir, 1, "Database choice", "We chose PostgreSQL for its ACID guarantees.", "decision") + _write_entry(mem_dir, 2, "Auth system", "We use JWT tokens for authentication.", "decision") + _write_entry(mem_dir, 3, "Caching layer", "Redis is used for session caching and rate limiting.", "context") + _write_entry(mem_dir, 4, "Deployment", "The service is deployed on Kubernetes in AWS.", "context") + _write_entry(mem_dir, 5, "Testing strategy", "We use pytest for all Python tests.", "procedure") + + index = RetrievalIndex(mem_dir) + results = await search(index, "caching and Redis session management", k=2) + + assert len(results) > 0 + top_ids = [r.entry_id for r in results] + assert 3 in top_ids + + +@requires_keys +@pytest.mark.anyio +async def test_search_type_filter_narrows_results(mem_dir: Path) -> None: + _write_entry(mem_dir, 1, "Decision one", "We chose React for the frontend.", "decision") + _write_entry(mem_dir, 2, "Procedure one", "Run pytest to execute all tests.", "procedure") + _write_entry(mem_dir, 3, "Procedure two", "Use uv run to install dependencies.", "procedure") + + index = RetrievalIndex(mem_dir) + results = await search(index, "running tests and procedures", k=5, type_filter="procedure") + + assert len(results) > 0 + assert all(r.entry.type == "procedure" for r in results) + + +@requires_keys +@pytest.mark.anyio +async def test_rag_inject_returns_relevant_entries(mem_dir: Path) -> None: + _write_entry(mem_dir, 1, "Auth decision", "JWT chosen over sessions for stateless auth.", "decision") + _write_entry(mem_dir, 2, "DB decision", "PostgreSQL for relational data.", "decision") + _write_entry(mem_dir, 3, "Caching lesson", "Redis TTL must match session timeout.", "lesson") + + index = RetrievalIndex(mem_dir) + results = await inject( + index, + directive="authentication and session management decisions", + anchor="implementing the login flow using JWT", + k=3, + ) + + assert len(results) > 0 + for r in results: + assert r.entry_id in {1, 2, 3} diff --git a/tests/memory/test_mcp_search.py b/tests/memory/test_mcp_search.py new file mode 100644 index 0000000..47514be --- /dev/null +++ b/tests/memory/test_mcp_search.py @@ -0,0 +1,141 @@ +from __future__ import annotations + +import json +from pathlib import Path +from unittest.mock import AsyncMock, MagicMock, patch + +import pytest +from fastmcp.exceptions import ToolError + +from koan.memory.retrieval.types import SearchResult +from koan.memory.types import MemoryEntry +from koan.state import AgentState, AppState +from koan.web import mcp_endpoint + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +def _unwrap(tool): + for attr in ("fn", "func", "_fn", "_func", "__wrapped__", "callback"): + candidate = getattr(tool, attr, None) + if callable(candidate): + return candidate + if callable(tool): + return tool + raise RuntimeError(f"Cannot unwrap FastMCP tool: {tool!r}") + + +koan_search = _unwrap(mcp_endpoint.koan_search) + + +def _make_entry(n: int = 1, etype: str = "context") -> MemoryEntry: + return MemoryEntry( + title=f"Entry {n}", + type=etype, + body=f"Body of entry {n}.", + created="2024-01-01", + modified="2024-01-01", + ) + + +def _make_result(n: int = 1, etype: str = "context") -> SearchResult: + return SearchResult(entry=_make_entry(n, etype), entry_id=n, score=0.9) + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + +@pytest.fixture +def mem_env(tmp_path, monkeypatch): + app_state = AppState() + app_state.project_dir = str(tmp_path) + app_state.phase = "curation" + + agent = AgentState( + agent_id="test-search-agent", + role="orchestrator", + subagent_dir=str(tmp_path / "sub"), + ) + agent.run_dir = str(tmp_path) + agent.step = 1 + app_state.agents[agent.agent_id] = agent + + monkeypatch.setattr(mcp_endpoint, "_app_state", app_state) + monkeypatch.setattr(mcp_endpoint, "_memory_store", None) + token = mcp_endpoint._agent_ctx.set(agent) + + yield {"agent": agent, "app_state": app_state, "project_dir": tmp_path} + + mcp_endpoint._agent_ctx.reset(token) + mcp_endpoint._reset_memory_store() + + +@pytest.fixture +def search_env(mem_env, monkeypatch): + fixed_results = [_make_result(1), _make_result(2)] + + mock_index = MagicMock() + mock_search = AsyncMock(return_value=fixed_results) + + monkeypatch.setattr(mcp_endpoint, "_retrieval_index", mock_index) + monkeypatch.setattr(mcp_endpoint, "retrieval_search", mock_search) + + yield {**mem_env, "mock_index": mock_index, "mock_search": mock_search, "fixed_results": fixed_results} + + mcp_endpoint._reset_retrieval_index() + + +# --------------------------------------------------------------------------- +# Tests +# --------------------------------------------------------------------------- + +class TestKoanSearch: + @pytest.mark.anyio + async def test_search_returns_json_with_results(self, search_env): + raw = await koan_search(query="test") + result = json.loads(raw) + assert "results" in result + assert len(result["results"]) == 2 + assert result["results"][0]["entry_id"] == 1 + + @pytest.mark.anyio + async def test_search_type_filter_forwarded(self, search_env): + await koan_search(query="x", type="procedure") + mock_search = search_env["mock_search"] + call_kwargs = mock_search.call_args + assert call_kwargs.kwargs.get("type_filter") == "procedure" + + @pytest.mark.anyio + async def test_search_invalid_type_raises(self, search_env): + with pytest.raises(ToolError) as exc: + await koan_search(query="x", type="nonsense") + body = json.loads(str(exc.value)) + assert body["error"] == "invalid_type" + + @pytest.mark.anyio + async def test_search_api_error_raises_tool_error(self, mem_env, monkeypatch): + mock_index = MagicMock() + monkeypatch.setattr(mcp_endpoint, "_retrieval_index", mock_index) + monkeypatch.setattr( + mcp_endpoint, "retrieval_search", + AsyncMock(side_effect=RuntimeError("API key missing")) + ) + with pytest.raises(ToolError) as exc: + await koan_search(query="x") + body = json.loads(str(exc.value)) + assert body["error"] == "search_failed" + mcp_endpoint._reset_retrieval_index() + + @pytest.mark.anyio + async def test_search_permission_denied_without_agent(self, search_env): + token = mcp_endpoint._agent_ctx.set(None) + try: + with pytest.raises(ToolError) as exc: + await koan_search(query="x") + body = json.loads(str(exc.value)) + assert body["error"] == "permission_denied" + finally: + mcp_endpoint._agent_ctx.reset(token) diff --git a/tests/memory/test_ops.py b/tests/memory/test_ops.py new file mode 100644 index 0000000..75edbad --- /dev/null +++ b/tests/memory/test_ops.py @@ -0,0 +1,126 @@ +# Tests for koan/memory/ops.py -- pure CRUD and validation layer. + +from __future__ import annotations + +import os +import time + +import pytest + +from koan.memory.store import MemoryStore +from koan.memory import ops + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +def make_store(tmp_path) -> MemoryStore: + store = MemoryStore(tmp_path) + store.init() + return store + + +# --------------------------------------------------------------------------- +# memorize +# --------------------------------------------------------------------------- + +def test_memorize_create_returns_correct_shape(tmp_path): + store = make_store(tmp_path) + result = ops.memorize(store, "decision", "My decision", "Body text.") + assert result["op"] == "created" + assert result["type"] == "decision" + assert isinstance(result["entry_id"], int) + assert isinstance(result["file_path"], str) + assert "created" in result + assert "modified" in result + + +def test_memorize_create_file_exists_on_disk(tmp_path): + store = make_store(tmp_path) + result = ops.memorize(store, "context", "Some context", "Body.") + from pathlib import Path + assert Path(result["file_path"]).is_file() + + +def test_memorize_update_returns_correct_shape(tmp_path): + store = make_store(tmp_path) + created = ops.memorize(store, "lesson", "Original", "Body.") + entry_id = created["entry_id"] + result = ops.memorize(store, "lesson", "Updated", "New body.", entry_id=entry_id) + assert result["op"] == "updated" + assert result["entry_id"] == entry_id + + +def test_memorize_update_type_mismatch_raises(tmp_path): + store = make_store(tmp_path) + created = ops.memorize(store, "decision", "Title", "Body.") + with pytest.raises(ValueError, match="type"): + ops.memorize(store, "context", "Title", "Body.", entry_id=created["entry_id"]) + + +def test_memorize_update_missing_entry_raises(tmp_path): + store = make_store(tmp_path) + with pytest.raises(ValueError, match="9999"): + ops.memorize(store, "decision", "Title", "Body.", entry_id=9999) + + +def test_memorize_invalid_type_raises(tmp_path): + store = make_store(tmp_path) + with pytest.raises(ValueError, match="bogus"): + ops.memorize(store, "bogus", "Title", "Body.") + + +# --------------------------------------------------------------------------- +# forget +# --------------------------------------------------------------------------- + +def test_forget_deletes_entry(tmp_path): + from pathlib import Path + store = make_store(tmp_path) + created = ops.memorize(store, "procedure", "To delete", "Body.") + entry_id = created["entry_id"] + result = ops.forget(store, entry_id) + assert result["op"] == "forgotten" + assert not Path(result["file_path"]).exists() + + +def test_forget_type_mismatch_raises(tmp_path): + store = make_store(tmp_path) + created = ops.memorize(store, "decision", "Title", "Body.") + with pytest.raises(ValueError, match="type"): + ops.forget(store, created["entry_id"], type="context") + + +def test_forget_missing_entry_raises(tmp_path): + store = make_store(tmp_path) + with pytest.raises(ValueError, match="9999"): + ops.forget(store, 9999) + + +# --------------------------------------------------------------------------- +# status +# --------------------------------------------------------------------------- + +@pytest.mark.anyio +async def test_status_empty_store(tmp_path): + store = make_store(tmp_path) + result = await ops.status(store) + assert result["summary"] == "" or result["summary"] is None + assert result["entries"] == [] + assert result["regenerated"] is False + + +@pytest.mark.anyio +async def test_status_fresh_summary_no_regen(tmp_path): + store = make_store(tmp_path) + ops.memorize(store, "context", "Entry A", "Body A.") + + # Write summary.md with mtime newer than the entry file. + summary_path = tmp_path / ".koan" / "memory" / "summary.md" + summary_path.write_text("Dummy summary.", encoding="utf-8") + future_mtime = time.time() + 2 + os.utime(summary_path, (future_mtime, future_mtime)) + + result = await ops.status(store) + assert result["regenerated"] is False diff --git a/tests/memory/test_rag.py b/tests/memory/test_rag.py new file mode 100644 index 0000000..a41427d --- /dev/null +++ b/tests/memory/test_rag.py @@ -0,0 +1,138 @@ +from __future__ import annotations + +from pathlib import Path +from unittest.mock import AsyncMock, MagicMock, patch + +import pytest + +from koan.memory.retrieval.rag import generate_queries, inject + + +# --------------------------------------------------------------------------- +# generate_queries +# --------------------------------------------------------------------------- + +@pytest.mark.anyio +async def test_generate_queries_parses_llm_output() -> None: + with patch("koan.memory.retrieval.rag.llm_generate", new=AsyncMock(return_value="query one\nquery two\nquery three\n")): + result = await generate_queries("directive", "anchor") + assert result == ["query one", "query two", "query three"] + + +@pytest.mark.anyio +async def test_generate_queries_truncates_to_three() -> None: + with patch("koan.memory.retrieval.rag.llm_generate", new=AsyncMock(return_value="q1\nq2\nq3\nq4\nq5\n")): + result = await generate_queries("d", "a") + assert result == ["q1", "q2", "q3"] + + +@pytest.mark.anyio +async def test_generate_queries_filters_empty_lines() -> None: + with patch("koan.memory.retrieval.rag.llm_generate", new=AsyncMock(return_value="q1\n\nq2\n")): + result = await generate_queries("d", "a") + assert result == ["q1", "q2"] + + +# --------------------------------------------------------------------------- +# inject +# --------------------------------------------------------------------------- + +def _make_candidate(entry_id: int, rrf_score: float = 0.01) -> dict: + return { + "entry_id": entry_id, + "file_path": "/nonexistent/path.md", + "title": f"Entry {entry_id}", + "type": "context", + "created": "2024-01-01", + "modified": "2024-01-01", + "body": f"Body {entry_id}.", + "_rrf_score": rrf_score, + } + + +@pytest.mark.anyio +async def test_inject_calls_search_candidates_per_query(tmp_path: Path) -> None: + from koan.memory.retrieval.index import RetrievalIndex + index = RetrievalIndex(tmp_path) + index._synced = True # skip actual sync + + fixed_candidates = [_make_candidate(1), _make_candidate(2)] + + mock_sc = AsyncMock(return_value=fixed_candidates) + mock_rr = AsyncMock(return_value=[]) + + with patch("koan.memory.retrieval.rag.llm_generate", new=AsyncMock(return_value="query A\nquery B\n")): + with patch("koan.memory.retrieval.rag.search_candidates", new=mock_sc): + with patch("koan.memory.retrieval.rag.rerank_results", new=mock_rr): + await inject(index, directive="find stuff", anchor="some context") + + # search_candidates called once per query (2 queries) + assert mock_sc.call_count == 2 + # rerank_results called once with directive as query + assert mock_rr.call_count == 1 + call_args = mock_rr.call_args + assert call_args.args[0] == "find stuff" + + +@pytest.mark.anyio +async def test_inject_deduplicates_across_queries(tmp_path: Path) -> None: + from koan.memory.retrieval.index import RetrievalIndex + index = RetrievalIndex(tmp_path) + index._synced = True + + # Query A returns entry 1 with score 0.05, query B returns entry 1 with score 0.1 + def make_sc_side_effect(*args, **kwargs): + call_num = make_sc_side_effect.call_count + make_sc_side_effect.call_count += 1 + if call_num == 0: + return [_make_candidate(1, rrf_score=0.05), _make_candidate(2, rrf_score=0.02)] + else: + return [_make_candidate(1, rrf_score=0.10), _make_candidate(3, rrf_score=0.03)] + make_sc_side_effect.call_count = 0 + + mock_sc = AsyncMock(side_effect=make_sc_side_effect) + captured_candidates: list[list[dict]] = [] + + async def mock_rr(query, candidates, k, *args, **kwargs): + captured_candidates.append(candidates) + return [] + + with patch("koan.memory.retrieval.rag.llm_generate", new=AsyncMock(return_value="q1\nq2\n")): + with patch("koan.memory.retrieval.rag.search_candidates", new=mock_sc): + with patch("koan.memory.retrieval.rag.rerank_results", new=AsyncMock(side_effect=mock_rr)): + await inject(index, directive="d", anchor="a") + + merged = captured_candidates[0] + ids = [c["entry_id"] for c in merged] + # No duplicate entry_ids + assert len(ids) == len(set(ids)) + # Entry 1 score should be max(0.05, 0.10) = 0.10 + e1 = next(c for c in merged if c["entry_id"] == 1) + assert abs(e1["_rrf_score"] - 0.10) < 1e-9 + + +@pytest.mark.anyio +async def test_inject_returns_top_k(tmp_path: Path) -> None: + from koan.memory.retrieval.index import RetrievalIndex + from koan.memory.retrieval.types import SearchResult + from koan.memory.types import MemoryEntry + + index = RetrievalIndex(tmp_path) + index._synced = True + + def make_result(n: int) -> SearchResult: + return SearchResult( + entry=MemoryEntry(title=f"T{n}", type="context", body=f"B{n}."), + entry_id=n, + score=1.0 - n * 0.1, + ) + + mock_sc = AsyncMock(return_value=[_make_candidate(i) for i in range(1, 6)]) + mock_rr = AsyncMock(return_value=[make_result(i) for i in range(1, 4)]) + + with patch("koan.memory.retrieval.rag.llm_generate", new=AsyncMock(return_value="q1\n")): + with patch("koan.memory.retrieval.rag.search_candidates", new=mock_sc): + with patch("koan.memory.retrieval.rag.rerank_results", new=mock_rr): + results = await inject(index, directive="d", anchor="a", k=3) + + assert len(results) <= 3 diff --git a/tests/memory/test_retrieval_backend.py b/tests/memory/test_retrieval_backend.py new file mode 100644 index 0000000..3f4c15a --- /dev/null +++ b/tests/memory/test_retrieval_backend.py @@ -0,0 +1,190 @@ +from __future__ import annotations + +import asyncio +from pathlib import Path +from unittest.mock import AsyncMock, patch + +import pytest + +from koan.memory.retrieval.backend import _rrf_merge, rerank_results +from koan.memory.retrieval.index import RetrievalIndex, _content_hash +from koan.memory.retrieval.types import SearchResult + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + +@pytest.fixture +def mem_dir(tmp_path: Path) -> Path: + d = tmp_path / ".koan" / "memory" + d.mkdir(parents=True) + return d + + +def write_entry(mem_dir: Path, n: int, title: str, body: str, etype: str = "context") -> Path: + slug = title.lower().replace(" ", "-") + path = mem_dir / f"{n:04d}-{slug}.md" + path.write_text( + f"---\ntitle: {title}\ntype: {etype}\ncreated: 2024-01-01\nmodified: 2024-01-01\n---\n\n{body}\n", + encoding="utf-8", + ) + return path + + +# --------------------------------------------------------------------------- +# _content_hash +# --------------------------------------------------------------------------- + +def test_content_hash_changes_on_edit(mem_dir: Path) -> None: + path = write_entry(mem_dir, 1, "Stable entry", "Original body.") + h1 = _content_hash(path) + path.write_text( + "---\ntitle: Stable entry\ntype: context\ncreated: 2024-01-01\nmodified: 2024-01-01\n---\n\nModified body.\n", + encoding="utf-8", + ) + h2 = _content_hash(path) + assert h1 != h2 + + +# --------------------------------------------------------------------------- +# RetrievalIndex sync +# --------------------------------------------------------------------------- + +FAKE_VECTOR = [0.1] * 1024 + + +@pytest.mark.anyio +async def test_sync_indexes_new_files(mem_dir: Path) -> None: + write_entry(mem_dir, 1, "Entry One", "Body of entry one.") + write_entry(mem_dir, 2, "Entry Two", "Body of entry two.") + + index = RetrievalIndex(mem_dir) + + with patch("koan.memory.retrieval.index._embed_texts", new=AsyncMock(return_value=[FAKE_VECTOR, FAKE_VECTOR])): + await index.ensure_synced() + + with patch("koan.memory.retrieval.index._embed_texts", new=AsyncMock(return_value=[])): + rows = await index.dense_search(FAKE_VECTOR, n=10) + + assert len(rows) == 2 + + +@pytest.mark.anyio +async def test_sync_skips_unchanged_files(mem_dir: Path) -> None: + write_entry(mem_dir, 1, "Stable", "Body.") + index = RetrievalIndex(mem_dir) + + mock_embed = AsyncMock(return_value=[FAKE_VECTOR]) + with patch("koan.memory.retrieval.index._embed_texts", new=mock_embed): + await index.ensure_synced() + # Reset synced flag to force a second sync + index._synced = False + await index.ensure_synced() + + # embed called only once (second sync sees matching hash) + assert mock_embed.call_count == 1 + + +@pytest.mark.anyio +async def test_sync_removes_deleted_files(mem_dir: Path) -> None: + p1 = write_entry(mem_dir, 1, "Keep", "Body one.") + p2 = write_entry(mem_dir, 2, "Delete", "Body two.") + index = RetrievalIndex(mem_dir) + + with patch("koan.memory.retrieval.index._embed_texts", new=AsyncMock(return_value=[FAKE_VECTOR, FAKE_VECTOR])): + await index.ensure_synced() + + # Delete second file and re-sync + p2.unlink() + index._synced = False + with patch("koan.memory.retrieval.index._embed_texts", new=AsyncMock(return_value=[])): + await index.ensure_synced() + + rows = await index.dense_search(FAKE_VECTOR, n=10) + assert len(rows) == 1 + assert rows[0]["entry_id"] == 1 + + +# --------------------------------------------------------------------------- +# _rrf_merge +# --------------------------------------------------------------------------- + +def test_rrf_merge_deduplicates() -> None: + dense = [ + {"entry_id": 1, "body": "b1", "title": "t1", "type": "context"}, + {"entry_id": 2, "body": "b2", "title": "t2", "type": "context"}, + ] + fts = [ + {"entry_id": 1, "body": "b1", "title": "t1", "type": "context"}, + {"entry_id": 3, "body": "b3", "title": "t3", "type": "context"}, + ] + merged = _rrf_merge(dense, fts) + ids = [r["entry_id"] for r in merged] + # No duplicates + assert len(ids) == len(set(ids)) + # Entry 1 appears in both lists so has highest score + assert ids[0] == 1 + + +# --------------------------------------------------------------------------- +# rerank_results +# --------------------------------------------------------------------------- + +def _make_candidate(entry_id: int, etype: str = "context") -> dict: + return { + "entry_id": entry_id, + "file_path": "/nonexistent/path.md", + "title": f"Title {entry_id}", + "type": etype, + "created": "2024-01-01", + "modified": "2024-01-01", + "body": f"Body for entry {entry_id}.", + "_rrf_score": 1.0 / (60 + entry_id), + } + + +@pytest.mark.anyio +async def test_search_applies_type_filter(mem_dir: Path) -> None: + write_entry(mem_dir, 1, "Decision A", "Body.", etype="decision") + write_entry(mem_dir, 2, "Context B", "Body.", etype="context") + + candidates = [ + {**_make_candidate(1), "type": "decision", "file_path": str(mem_dir / "0001-decision-a.md")}, + {**_make_candidate(2), "type": "context", "file_path": str(mem_dir / "0002-context-b.md")}, + ] + + mock_rerank_result = type("R", (), { + "results": [type("I", (), {"index": 0, "relevance_score": 0.9})()] + })() + + with patch("koan.memory.retrieval.backend._voyage_api_key", return_value="fake-key"): + with patch("voyageai.AsyncClient.rerank", new=AsyncMock(return_value=mock_rerank_result)): + results = await rerank_results("query", candidates, k=5, type_filter="decision") + + assert all(r.entry.type == "decision" for r in results) + + +@pytest.mark.anyio +async def test_search_returns_top_k(mem_dir: Path) -> None: + # Write 5 entries + for i in range(1, 6): + write_entry(mem_dir, i, f"Entry {i}", f"Body {i}.", etype="context") + + candidates = [ + {**_make_candidate(i), "file_path": str(mem_dir / f"{i:04d}-entry-{i}.md")} + for i in range(1, 6) + ] + + # Mock reranker returns top 3 results + mock_results = [ + type("I", (), {"index": i, "relevance_score": 1.0 - i * 0.1})() + for i in range(3) + ] + mock_rerank_result = type("R", (), {"results": mock_results})() + + with patch("koan.memory.retrieval.backend._voyage_api_key", return_value="fake-key"): + with patch("voyageai.AsyncClient.rerank", new=AsyncMock(return_value=mock_rerank_result)): + results = await rerank_results("query", candidates, k=3) + + assert len(results) <= 3 diff --git a/tests/test_permissions.py b/tests/test_permissions.py index 570dc5b..780e4a0 100644 --- a/tests/test_permissions.py +++ b/tests/test_permissions.py @@ -158,6 +158,11 @@ def test_koan_complete_step_always_allowed(self): r = check_permission("orchestrator", "koan_complete_step", current_phase=phase) assert r["allowed"] + def test_koan_search_allowed_in_every_phase(self): + for phase in ("intake", "brief-generation", "execution", "implementation-validation", "curation"): + r = check_permission("orchestrator", "koan_search", current_phase=phase) + assert r["allowed"], f"koan_search should be allowed in phase '{phase}'" + # -- Exhaustive role x tool matrix --------------------------------------------- diff --git a/uv.lock b/uv.lock index a4c9dc0..51532bb 100644 --- a/uv.lock +++ b/uv.lock @@ -1,6 +1,11 @@ version = 1 revision = 3 requires-python = ">=3.12" +resolution-markers = [ + "python_full_version == '3.13.*'", + "python_full_version < '3.13'", + "python_full_version >= '3.14'", +] [[package]] name = "aiofile" @@ -23,6 +28,131 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/bc/8a/340a1555ae33d7354dbca4faa54948d76d89a27ceef032c8c3bc661d003e/aiofiles-25.1.0-py3-none-any.whl", hash = "sha256:abe311e527c862958650f9438e859c1fa7568a141b22abcd015e120e86a85695", size = 14668, upload-time = "2025-10-09T20:51:03.174Z" }, ] +[[package]] +name = "aiohappyeyeballs" +version = "2.6.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/26/30/f84a107a9c4331c14b2b586036f40965c128aa4fee4dda5d3d51cb14ad54/aiohappyeyeballs-2.6.1.tar.gz", hash = "sha256:c3f9d0113123803ccadfdf3f0faa505bc78e6a72d1cc4806cbd719826e943558", size = 22760, upload-time = "2025-03-12T01:42:48.764Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/0f/15/5bf3b99495fb160b63f95972b81750f18f7f4e02ad051373b669d17d44f2/aiohappyeyeballs-2.6.1-py3-none-any.whl", hash = "sha256:f349ba8f4b75cb25c99c5c2d84e997e485204d2902a9597802b0371f09331fb8", size = 15265, upload-time = "2025-03-12T01:42:47.083Z" }, +] + +[[package]] +name = "aiohttp" +version = "3.13.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "aiohappyeyeballs" }, + { name = "aiosignal" }, + { name = "attrs" }, + { name = "frozenlist" }, + { name = "multidict" }, + { name = "propcache" }, + { name = "yarl" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/77/9a/152096d4808df8e4268befa55fba462f440f14beab85e8ad9bf990516918/aiohttp-3.13.5.tar.gz", hash = "sha256:9d98cc980ecc96be6eb4c1994ce35d28d8b1f5e5208a23b421187d1209dbb7d1", size = 7858271, upload-time = "2026-03-31T22:01:03.343Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/be/6f/353954c29e7dcce7cf00280a02c75f30e133c00793c7a2ed3776d7b2f426/aiohttp-3.13.5-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:023ecba036ddd840b0b19bf195bfae970083fd7024ce1ac22e9bba90464620e9", size = 748876, upload-time = "2026-03-31T21:57:36.319Z" }, + { url = "https://files.pythonhosted.org/packages/f5/1b/428a7c64687b3b2e9cd293186695affc0e1e54a445d0361743b231f11066/aiohttp-3.13.5-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:15c933ad7920b7d9a20de151efcd05a6e38302cbf0e10c9b2acb9a42210a2416", size = 499557, upload-time = "2026-03-31T21:57:38.236Z" }, + { url = "https://files.pythonhosted.org/packages/29/47/7be41556bfbb6917069d6a6634bb7dd5e163ba445b783a90d40f5ac7e3a7/aiohttp-3.13.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:ab2899f9fa2f9f741896ebb6fa07c4c883bfa5c7f2ddd8cf2aafa86fa981b2d2", size = 500258, upload-time = "2026-03-31T21:57:39.923Z" }, + { url = "https://files.pythonhosted.org/packages/67/84/c9ecc5828cb0b3695856c07c0a6817a99d51e2473400f705275a2b3d9239/aiohttp-3.13.5-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a60eaa2d440cd4707696b52e40ed3e2b0f73f65be07fd0ef23b6b539c9c0b0b4", size = 1749199, upload-time = "2026-03-31T21:57:41.938Z" }, + { url = "https://files.pythonhosted.org/packages/f0/d3/3c6d610e66b495657622edb6ae7c7fd31b2e9086b4ec50b47897ad6042a9/aiohttp-3.13.5-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:55b3bdd3292283295774ab585160c4004f4f2f203946997f49aac032c84649e9", size = 1721013, upload-time = "2026-03-31T21:57:43.904Z" }, + { url = "https://files.pythonhosted.org/packages/49/a0/24409c12217456df0bae7babe3b014e460b0b38a8e60753d6cb339f6556d/aiohttp-3.13.5-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c2b2355dc094e5f7d45a7bb262fe7207aa0460b37a0d87027dcf21b5d890e7d5", size = 1781501, upload-time = "2026-03-31T21:57:46.285Z" }, + { url = "https://files.pythonhosted.org/packages/98/9d/b65ec649adc5bccc008b0957a9a9c691070aeac4e41cea18559fef49958b/aiohttp-3.13.5-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b38765950832f7d728297689ad78f5f2cf79ff82487131c4d26fe6ceecdc5f8e", size = 1878981, upload-time = "2026-03-31T21:57:48.734Z" }, + { url = "https://files.pythonhosted.org/packages/57/d8/8d44036d7eb7b6a8ec4c5494ea0c8c8b94fbc0ed3991c1a7adf230df03bf/aiohttp-3.13.5-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b18f31b80d5a33661e08c89e202edabf1986e9b49c42b4504371daeaa11b47c1", size = 1767934, upload-time = "2026-03-31T21:57:51.171Z" }, + { url = "https://files.pythonhosted.org/packages/31/04/d3f8211f273356f158e3464e9e45484d3fb8c4ce5eb2f6fe9405c3273983/aiohttp-3.13.5-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:33add2463dde55c4f2d9635c6ab33ce154e5ecf322bd26d09af95c5f81cfa286", size = 1566671, upload-time = "2026-03-31T21:57:53.326Z" }, + { url = "https://files.pythonhosted.org/packages/41/db/073e4ebe00b78e2dfcacff734291651729a62953b48933d765dc513bf798/aiohttp-3.13.5-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:327cc432fdf1356fb4fbc6fe833ad4e9f6aacb71a8acaa5f1855e4b25910e4a9", size = 1705219, upload-time = "2026-03-31T21:57:55.385Z" }, + { url = "https://files.pythonhosted.org/packages/48/45/7dfba71a2f9fd97b15c95c06819de7eb38113d2cdb6319669195a7d64270/aiohttp-3.13.5-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:7c35b0bf0b48a70b4cb4fc5d7bed9b932532728e124874355de1a0af8ec4bc88", size = 1743049, upload-time = "2026-03-31T21:57:57.341Z" }, + { url = "https://files.pythonhosted.org/packages/18/71/901db0061e0f717d226386a7f471bb59b19566f2cae5f0d93874b017271f/aiohttp-3.13.5-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:df23d57718f24badef8656c49743e11a89fd6f5358fa8a7b96e728fda2abf7d3", size = 1749557, upload-time = "2026-03-31T21:57:59.626Z" }, + { url = "https://files.pythonhosted.org/packages/08/d5/41eebd16066e59cd43728fe74bce953d7402f2b4ddfdfef2c0e9f17ca274/aiohttp-3.13.5-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:02e048037a6501a5ec1f6fc9736135aec6eb8a004ce48838cb951c515f32c80b", size = 1558931, upload-time = "2026-03-31T21:58:01.972Z" }, + { url = "https://files.pythonhosted.org/packages/30/e6/4a799798bf05740e66c3a1161079bda7a3dd8e22ca392481d7a7f9af82a6/aiohttp-3.13.5-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:31cebae8b26f8a615d2b546fee45d5ffb76852ae6450e2a03f42c9102260d6fe", size = 1774125, upload-time = "2026-03-31T21:58:04.007Z" }, + { url = "https://files.pythonhosted.org/packages/84/63/7749337c90f92bc2cb18f9560d67aa6258c7060d1397d21529b8004fcf6f/aiohttp-3.13.5-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:888e78eb5ca55a615d285c3c09a7a91b42e9dd6fc699b166ebd5dee87c9ccf14", size = 1732427, upload-time = "2026-03-31T21:58:06.337Z" }, + { url = "https://files.pythonhosted.org/packages/98/de/cf2f44ff98d307e72fb97d5f5bbae3bfcb442f0ea9790c0bf5c5c2331404/aiohttp-3.13.5-cp312-cp312-win32.whl", hash = "sha256:8bd3ec6376e68a41f9f95f5ed170e2fcf22d4eb27a1f8cb361d0508f6e0557f3", size = 433534, upload-time = "2026-03-31T21:58:08.712Z" }, + { url = "https://files.pythonhosted.org/packages/aa/ca/eadf6f9c8fa5e31d40993e3db153fb5ed0b11008ad5d9de98a95045bed84/aiohttp-3.13.5-cp312-cp312-win_amd64.whl", hash = "sha256:110e448e02c729bcebb18c60b9214a87ba33bac4a9fa5e9a5f139938b56c6cb1", size = 460446, upload-time = "2026-03-31T21:58:10.945Z" }, + { url = "https://files.pythonhosted.org/packages/78/e9/d76bf503005709e390122d34e15256b88f7008e246c4bdbe915cd4f1adce/aiohttp-3.13.5-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a5029cc80718bbd545123cd8fe5d15025eccaaaace5d0eeec6bd556ad6163d61", size = 742930, upload-time = "2026-03-31T21:58:13.155Z" }, + { url = "https://files.pythonhosted.org/packages/57/00/4b7b70223deaebd9bb85984d01a764b0d7bd6526fcdc73cca83bcbe7243e/aiohttp-3.13.5-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:4bb6bf5811620003614076bdc807ef3b5e38244f9d25ca5fe888eaccea2a9832", size = 496927, upload-time = "2026-03-31T21:58:15.073Z" }, + { url = "https://files.pythonhosted.org/packages/9c/f5/0fb20fb49f8efdcdce6cd8127604ad2c503e754a8f139f5e02b01626523f/aiohttp-3.13.5-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a84792f8631bf5a94e52d9cc881c0b824ab42717165a5579c760b830d9392ac9", size = 497141, upload-time = "2026-03-31T21:58:17.009Z" }, + { url = "https://files.pythonhosted.org/packages/3b/86/b7c870053e36a94e8951b803cb5b909bfbc9b90ca941527f5fcafbf6b0fa/aiohttp-3.13.5-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:57653eac22c6a4c13eb22ecf4d673d64a12f266e72785ab1c8b8e5940d0e8090", size = 1732476, upload-time = "2026-03-31T21:58:18.925Z" }, + { url = "https://files.pythonhosted.org/packages/b5/e5/4e161f84f98d80c03a238671b4136e6530453d65262867d989bbe78244d0/aiohttp-3.13.5-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e5e5f7debc7a57af53fdf5c5009f9391d9f4c12867049d509bf7bb164a6e295b", size = 1706507, upload-time = "2026-03-31T21:58:21.094Z" }, + { url = "https://files.pythonhosted.org/packages/d4/56/ea11a9f01518bd5a2a2fcee869d248c4b8a0cfa0bb13401574fa31adf4d4/aiohttp-3.13.5-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c719f65bebcdf6716f10e9eff80d27567f7892d8988c06de12bbbd39307c6e3a", size = 1773465, upload-time = "2026-03-31T21:58:23.159Z" }, + { url = "https://files.pythonhosted.org/packages/eb/40/333ca27fb74b0383f17c90570c748f7582501507307350a79d9f9f3c6eb1/aiohttp-3.13.5-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d97f93fdae594d886c5a866636397e2bcab146fd7a132fd6bb9ce182224452f8", size = 1873523, upload-time = "2026-03-31T21:58:25.59Z" }, + { url = "https://files.pythonhosted.org/packages/f0/d2/e2f77eef1acb7111405433c707dc735e63f67a56e176e72e9e7a2cd3f493/aiohttp-3.13.5-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:3df334e39d4c2f899a914f1dba283c1aadc311790733f705182998c6f7cae665", size = 1754113, upload-time = "2026-03-31T21:58:27.624Z" }, + { url = "https://files.pythonhosted.org/packages/fb/56/3f653d7f53c89669301ec9e42c95233e2a0c0a6dd051269e6e678db4fdb0/aiohttp-3.13.5-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fe6970addfea9e5e081401bcbadf865d2b6da045472f58af08427e108d618540", size = 1562351, upload-time = "2026-03-31T21:58:29.918Z" }, + { url = "https://files.pythonhosted.org/packages/ec/a6/9b3e91eb8ae791cce4ee736da02211c85c6f835f1bdfac0594a8a3b7018c/aiohttp-3.13.5-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:7becdf835feff2f4f335d7477f121af787e3504b48b449ff737afb35869ba7bb", size = 1693205, upload-time = "2026-03-31T21:58:32.214Z" }, + { url = "https://files.pythonhosted.org/packages/98/fc/bfb437a99a2fcebd6b6eaec609571954de2ed424f01c352f4b5504371dd3/aiohttp-3.13.5-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:676e5651705ad5d8a70aeb8eb6936c436d8ebbd56e63436cb7dd9bb36d2a9a46", size = 1730618, upload-time = "2026-03-31T21:58:34.728Z" }, + { url = "https://files.pythonhosted.org/packages/e4/b6/c8534862126191a034f68153194c389addc285a0f1347d85096d349bbc15/aiohttp-3.13.5-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:9b16c653d38eb1a611cc898c41e76859ca27f119d25b53c12875fd0474ae31a8", size = 1745185, upload-time = "2026-03-31T21:58:36.909Z" }, + { url = "https://files.pythonhosted.org/packages/0b/93/4ca8ee2ef5236e2707e0fd5fecb10ce214aee1ff4ab307af9c558bda3b37/aiohttp-3.13.5-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:999802d5fa0389f58decd24b537c54aa63c01c3219ce17d1214cbda3c2b22d2d", size = 1557311, upload-time = "2026-03-31T21:58:39.38Z" }, + { url = "https://files.pythonhosted.org/packages/57/ae/76177b15f18c5f5d094f19901d284025db28eccc5ae374d1d254181d33f4/aiohttp-3.13.5-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:ec707059ee75732b1ba130ed5f9580fe10ff75180c812bc267ded039db5128c6", size = 1773147, upload-time = "2026-03-31T21:58:41.476Z" }, + { url = "https://files.pythonhosted.org/packages/01/a4/62f05a0a98d88af59d93b7fcac564e5f18f513cb7471696ac286db970d6a/aiohttp-3.13.5-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:2d6d44a5b48132053c2f6cd5c8cb14bc67e99a63594e336b0f2af81e94d5530c", size = 1730356, upload-time = "2026-03-31T21:58:44.049Z" }, + { url = "https://files.pythonhosted.org/packages/e4/85/fc8601f59dfa8c9523808281f2da571f8b4699685f9809a228adcc90838d/aiohttp-3.13.5-cp313-cp313-win32.whl", hash = "sha256:329f292ed14d38a6c4c435e465f48bebb47479fd676a0411936cc371643225cc", size = 432637, upload-time = "2026-03-31T21:58:46.167Z" }, + { url = "https://files.pythonhosted.org/packages/c0/1b/ac685a8882896acf0f6b31d689e3792199cfe7aba37969fa91da63a7fa27/aiohttp-3.13.5-cp313-cp313-win_amd64.whl", hash = "sha256:69f571de7500e0557801c0b51f4780482c0ec5fe2ac851af5a92cfce1af1cb83", size = 458896, upload-time = "2026-03-31T21:58:48.119Z" }, + { url = "https://files.pythonhosted.org/packages/5d/ce/46572759afc859e867a5bc8ec3487315869013f59281ce61764f76d879de/aiohttp-3.13.5-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:eb4639f32fd4a9904ab8fb45bf3383ba71137f3d9d4ba25b3b3f3109977c5b8c", size = 745721, upload-time = "2026-03-31T21:58:50.229Z" }, + { url = "https://files.pythonhosted.org/packages/13/fe/8a2efd7626dbe6049b2ef8ace18ffda8a4dfcbe1bcff3ac30c0c7575c20b/aiohttp-3.13.5-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:7e5dc4311bd5ac493886c63cbf76ab579dbe4641268e7c74e48e774c74b6f2be", size = 497663, upload-time = "2026-03-31T21:58:52.232Z" }, + { url = "https://files.pythonhosted.org/packages/9b/91/cc8cc78a111826c54743d88651e1687008133c37e5ee615fee9b57990fac/aiohttp-3.13.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:756c3c304d394977519824449600adaf2be0ccee76d206ee339c5e76b70ded25", size = 499094, upload-time = "2026-03-31T21:58:54.566Z" }, + { url = "https://files.pythonhosted.org/packages/0a/33/a8362cb15cf16a3af7e86ed11962d5cd7d59b449202dc576cdc731310bde/aiohttp-3.13.5-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ecc26751323224cf8186efcf7fbcbc30f4e1d8c7970659daf25ad995e4032a56", size = 1726701, upload-time = "2026-03-31T21:58:56.864Z" }, + { url = "https://files.pythonhosted.org/packages/45/0c/c091ac5c3a17114bd76cbf85d674650969ddf93387876cf67f754204bd77/aiohttp-3.13.5-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:10a75acfcf794edf9d8db50e5a7ec5fc818b2a8d3f591ce93bc7b1210df016d2", size = 1683360, upload-time = "2026-03-31T21:58:59.072Z" }, + { url = "https://files.pythonhosted.org/packages/23/73/bcee1c2b79bc275e964d1446c55c54441a461938e70267c86afaae6fba27/aiohttp-3.13.5-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:0f7a18f258d124cd678c5fe072fe4432a4d5232b0657fca7c1847f599233c83a", size = 1773023, upload-time = "2026-03-31T21:59:01.776Z" }, + { url = "https://files.pythonhosted.org/packages/c7/ef/720e639df03004fee2d869f771799d8c23046dec47d5b81e396c7cda583a/aiohttp-3.13.5-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:df6104c009713d3a89621096f3e3e88cc323fd269dbd7c20afe18535094320be", size = 1853795, upload-time = "2026-03-31T21:59:04.568Z" }, + { url = "https://files.pythonhosted.org/packages/bd/c9/989f4034fb46841208de7aeeac2c6d8300745ab4f28c42f629ba77c2d916/aiohttp-3.13.5-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:241a94f7de7c0c3b616627aaad530fe2cb620084a8b144d3be7b6ecfe95bae3b", size = 1730405, upload-time = "2026-03-31T21:59:07.221Z" }, + { url = "https://files.pythonhosted.org/packages/ce/75/ee1fd286ca7dc599d824b5651dad7b3be7ff8d9a7e7b3fe9820d9180f7db/aiohttp-3.13.5-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c974fb66180e58709b6fc402846f13791240d180b74de81d23913abe48e96d94", size = 1558082, upload-time = "2026-03-31T21:59:09.484Z" }, + { url = "https://files.pythonhosted.org/packages/c3/20/1e9e6650dfc436340116b7aa89ff8cb2bbdf0abc11dfaceaad8f74273a10/aiohttp-3.13.5-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:6e27ea05d184afac78aabbac667450c75e54e35f62238d44463131bd3f96753d", size = 1692346, upload-time = "2026-03-31T21:59:12.068Z" }, + { url = "https://files.pythonhosted.org/packages/d8/40/8ebc6658d48ea630ac7903912fe0dd4e262f0e16825aa4c833c56c9f1f56/aiohttp-3.13.5-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:a79a6d399cef33a11b6f004c67bb07741d91f2be01b8d712d52c75711b1e07c7", size = 1698891, upload-time = "2026-03-31T21:59:14.552Z" }, + { url = "https://files.pythonhosted.org/packages/d8/78/ea0ae5ec8ba7a5c10bdd6e318f1ba5e76fcde17db8275188772afc7917a4/aiohttp-3.13.5-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:c632ce9c0b534fbe25b52c974515ed674937c5b99f549a92127c85f771a78772", size = 1742113, upload-time = "2026-03-31T21:59:17.068Z" }, + { url = "https://files.pythonhosted.org/packages/8a/66/9d308ed71e3f2491be1acb8769d96c6f0c47d92099f3bc9119cada27b357/aiohttp-3.13.5-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:fceedde51fbd67ee2bcc8c0b33d0126cc8b51ef3bbde2f86662bd6d5a6f10ec5", size = 1553088, upload-time = "2026-03-31T21:59:19.541Z" }, + { url = "https://files.pythonhosted.org/packages/da/a6/6cc25ed8dfc6e00c90f5c6d126a98e2cf28957ad06fa1036bd34b6f24a2c/aiohttp-3.13.5-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:f92995dfec9420bb69ae629abf422e516923ba79ba4403bc750d94fb4a6c68c1", size = 1757976, upload-time = "2026-03-31T21:59:22.311Z" }, + { url = "https://files.pythonhosted.org/packages/c1/2b/cce5b0ffe0de99c83e5e36d8f828e4161e415660a9f3e58339d07cce3006/aiohttp-3.13.5-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:20ae0ff08b1f2c8788d6fb85afcb798654ae6ba0b747575f8562de738078457b", size = 1712444, upload-time = "2026-03-31T21:59:24.635Z" }, + { url = "https://files.pythonhosted.org/packages/6c/cf/9e1795b4160c58d29421eafd1a69c6ce351e2f7c8d3c6b7e4ca44aea1a5b/aiohttp-3.13.5-cp314-cp314-win32.whl", hash = "sha256:b20df693de16f42b2472a9c485e1c948ee55524786a0a34345511afdd22246f3", size = 438128, upload-time = "2026-03-31T21:59:27.291Z" }, + { url = "https://files.pythonhosted.org/packages/22/4d/eaedff67fc805aeba4ba746aec891b4b24cebb1a7d078084b6300f79d063/aiohttp-3.13.5-cp314-cp314-win_amd64.whl", hash = "sha256:f85c6f327bf0b8c29da7d93b1cabb6363fb5e4e160a32fa241ed2dce21b73162", size = 464029, upload-time = "2026-03-31T21:59:29.429Z" }, + { url = "https://files.pythonhosted.org/packages/79/11/c27d9332ee20d68dd164dc12a6ecdef2e2e35ecc97ed6cf0d2442844624b/aiohttp-3.13.5-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:1efb06900858bb618ff5cee184ae2de5828896c448403d51fb633f09e109be0a", size = 778758, upload-time = "2026-03-31T21:59:31.547Z" }, + { url = "https://files.pythonhosted.org/packages/04/fb/377aead2e0a3ba5f09b7624f702a964bdf4f08b5b6728a9799830c80041e/aiohttp-3.13.5-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:fee86b7c4bd29bdaf0d53d14739b08a106fdda809ca5fe032a15f52fae5fe254", size = 512883, upload-time = "2026-03-31T21:59:34.098Z" }, + { url = "https://files.pythonhosted.org/packages/bb/a6/aa109a33671f7a5d3bd78b46da9d852797c5e665bfda7d6b373f56bff2ec/aiohttp-3.13.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:20058e23909b9e65f9da62b396b77dfa95965cbe840f8def6e572538b1d32e36", size = 516668, upload-time = "2026-03-31T21:59:36.497Z" }, + { url = "https://files.pythonhosted.org/packages/79/b3/ca078f9f2fa9563c36fb8ef89053ea2bb146d6f792c5104574d49d8acb63/aiohttp-3.13.5-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8cf20a8d6868cb15a73cab329ffc07291ba8c22b1b88176026106ae39aa6df0f", size = 1883461, upload-time = "2026-03-31T21:59:38.723Z" }, + { url = "https://files.pythonhosted.org/packages/b7/e3/a7ad633ca1ca497b852233a3cce6906a56c3225fb6d9217b5e5e60b7419d/aiohttp-3.13.5-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:330f5da04c987f1d5bdb8ae189137c77139f36bd1cb23779ca1a354a4b027800", size = 1747661, upload-time = "2026-03-31T21:59:41.187Z" }, + { url = "https://files.pythonhosted.org/packages/33/b9/cd6fe579bed34a906d3d783fe60f2fa297ef55b27bb4538438ee49d4dc41/aiohttp-3.13.5-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6f1cbf0c7926d315c3c26c2da41fd2b5d2fe01ac0e157b78caefc51a782196cf", size = 1863800, upload-time = "2026-03-31T21:59:43.84Z" }, + { url = "https://files.pythonhosted.org/packages/c0/3f/2c1e2f5144cefa889c8afd5cf431994c32f3b29da9961698ff4e3811b79a/aiohttp-3.13.5-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:53fc049ed6390d05423ba33103ded7281fe897cf97878f369a527070bd95795b", size = 1958382, upload-time = "2026-03-31T21:59:46.187Z" }, + { url = "https://files.pythonhosted.org/packages/66/1d/f31ec3f1013723b3babe3609e7f119c2c2fb6ef33da90061a705ef3e1bc8/aiohttp-3.13.5-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:898703aa2667e3c5ca4c54ca36cd73f58b7a38ef87a5606414799ebce4d3fd3a", size = 1803724, upload-time = "2026-03-31T21:59:48.656Z" }, + { url = "https://files.pythonhosted.org/packages/0e/b4/57712dfc6f1542f067daa81eb61da282fab3e6f1966fca25db06c4fc62d5/aiohttp-3.13.5-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0494a01ca9584eea1e5fbd6d748e61ecff218c51b576ee1999c23db7066417d8", size = 1640027, upload-time = "2026-03-31T21:59:51.284Z" }, + { url = "https://files.pythonhosted.org/packages/25/3c/734c878fb43ec083d8e31bf029daae1beafeae582d1b35da234739e82ee7/aiohttp-3.13.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:6cf81fe010b8c17b09495cbd15c1d35afbc8fb405c0c9cf4738e5ae3af1d65be", size = 1806644, upload-time = "2026-03-31T21:59:53.753Z" }, + { url = "https://files.pythonhosted.org/packages/20/a5/f671e5cbec1c21d044ff3078223f949748f3a7f86b14e34a365d74a5d21f/aiohttp-3.13.5-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:c564dd5f09ddc9d8f2c2d0a301cd30a79a2cc1b46dd1a73bef8f0038863d016b", size = 1791630, upload-time = "2026-03-31T21:59:56.239Z" }, + { url = "https://files.pythonhosted.org/packages/0b/63/fb8d0ad63a0b8a99be97deac8c04dacf0785721c158bdf23d679a87aa99e/aiohttp-3.13.5-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:2994be9f6e51046c4f864598fd9abeb4fba6e88f0b2152422c9666dcd4aea9c6", size = 1809403, upload-time = "2026-03-31T21:59:59.103Z" }, + { url = "https://files.pythonhosted.org/packages/59/0c/bfed7f30662fcf12206481c2aac57dedee43fe1c49275e85b3a1e1742294/aiohttp-3.13.5-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:157826e2fa245d2ef46c83ea8a5faf77ca19355d278d425c29fda0beb3318037", size = 1634924, upload-time = "2026-03-31T22:00:02.116Z" }, + { url = "https://files.pythonhosted.org/packages/17/d6/fd518d668a09fd5a3319ae5e984d4d80b9a4b3df4e21c52f02251ef5a32e/aiohttp-3.13.5-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:a8aca50daa9493e9e13c0f566201a9006f080e7c50e5e90d0b06f53146a54500", size = 1836119, upload-time = "2026-03-31T22:00:04.756Z" }, + { url = "https://files.pythonhosted.org/packages/78/b7/15fb7a9d52e112a25b621c67b69c167805cb1f2ab8f1708a5c490d1b52fe/aiohttp-3.13.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:3b13560160d07e047a93f23aaa30718606493036253d5430887514715b67c9d9", size = 1772072, upload-time = "2026-03-31T22:00:07.494Z" }, + { url = "https://files.pythonhosted.org/packages/7e/df/57ba7f0c4a553fc2bd8b6321df236870ec6fd64a2a473a8a13d4f733214e/aiohttp-3.13.5-cp314-cp314t-win32.whl", hash = "sha256:9a0f4474b6ea6818b41f82172d799e4b3d29e22c2c520ce4357856fced9af2f8", size = 471819, upload-time = "2026-03-31T22:00:10.277Z" }, + { url = "https://files.pythonhosted.org/packages/62/29/2f8418269e46454a26171bfdd6a055d74febf32234e474930f2f60a17145/aiohttp-3.13.5-cp314-cp314t-win_amd64.whl", hash = "sha256:18a2f6c1182c51baa1d28d68fea51513cb2a76612f038853c0ad3c145423d3d9", size = 505441, upload-time = "2026-03-31T22:00:12.791Z" }, +] + +[[package]] +name = "aiolimiter" +version = "1.2.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/f1/23/b52debf471f7a1e42e362d959a3982bdcb4fe13a5d46e63d28868807a79c/aiolimiter-1.2.1.tar.gz", hash = "sha256:e02a37ea1a855d9e832252a105420ad4d15011505512a1a1d814647451b5cca9", size = 7185, upload-time = "2024-12-08T15:31:51.496Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f3/ba/df6e8e1045aebc4778d19b8a3a9bc1808adb1619ba94ca354d9ba17d86c3/aiolimiter-1.2.1-py3-none-any.whl", hash = "sha256:d3f249e9059a20badcb56b61601a83556133655c11d1eb3dd3e04ff069e5f3c7", size = 6711, upload-time = "2024-12-08T15:31:49.874Z" }, +] + +[[package]] +name = "aiosignal" +version = "1.4.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "frozenlist" }, + { name = "typing-extensions", marker = "python_full_version < '3.13'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/61/62/06741b579156360248d1ec624842ad0edf697050bbaf7c3e46394e106ad1/aiosignal-1.4.0.tar.gz", hash = "sha256:f47eecd9468083c2029cc99945502cb7708b082c232f9aca65da147157b251c7", size = 25007, upload-time = "2025-07-03T22:54:43.528Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fb/76/641ae371508676492379f16e2fa48f4e2c11741bd63c48be4b12a6b09cba/aiosignal-1.4.0-py3-none-any.whl", hash = "sha256:053243f8b92b990551949e63930a839ff0cf0b0ebbe0597b0f3fb19e1a0fe82e", size = 7490, upload-time = "2025-07-03T22:54:42.156Z" }, +] + +[[package]] +name = "annotated-doc" +version = "0.0.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/57/ba/046ceea27344560984e26a590f90bc7f4a75b06701f653222458922b558c/annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4", size = 7288, upload-time = "2025-11-10T22:07:42.062Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320", size = 5303, upload-time = "2025-11-10T22:07:40.673Z" }, +] + [[package]] name = "annotated-types" version = "0.7.0" @@ -333,6 +463,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/8a/0b/2261922126b2e50c601fe22d7ff5194e0a4d50e654836260c0665e24d862/cyclopts-4.10.1-py3-none-any.whl", hash = "sha256:35f37257139380a386d9fe4475e1e7c87ca7795765ef4f31abba579fcfcb6ecd", size = 204331, upload-time = "2026-03-23T14:43:02.625Z" }, ] +[[package]] +name = "deprecation" +version = "2.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "packaging" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/5a/d3/8ae2869247df154b64c1884d7346d412fed0c49df84db635aab2d1c40e62/deprecation-2.1.0.tar.gz", hash = "sha256:72b3bde64e5d778694b0cf68178aed03d15e15477116add3fb773e581f9518ff", size = 173788, upload-time = "2020-04-20T14:23:38.738Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/02/c3/253a89ee03fc9b9682f1541728eb66db7db22148cd94f89ab22528cd1e1b/deprecation-2.1.0-py2.py3-none-any.whl", hash = "sha256:a10811591210e1fb0e768a8c25517cabeabcba6f0bf96564f8ff45189f90b14a", size = 11178, upload-time = "2020-04-20T14:23:36.581Z" }, +] + [[package]] name = "distro" version = "1.9.0" @@ -426,6 +568,134 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/70/ea/570122de7e24f72138d006f799768e14cc1ccf7fcb22b7750b2bd276c711/fastmcp-3.1.1-py3-none-any.whl", hash = "sha256:8132ba069d89f14566b3266919d6d72e2ec23dd45d8944622dca407e9beda7eb", size = 633754, upload-time = "2026-03-14T19:12:22.736Z" }, ] +[[package]] +name = "ffmpeg-python" +version = "0.2.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "future" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/dd/5e/d5f9105d59c1325759d838af4e973695081fbbc97182baf73afc78dec266/ffmpeg-python-0.2.0.tar.gz", hash = "sha256:65225db34627c578ef0e11c8b1eb528bb35e024752f6f10b78c011f6f64c4127", size = 21543, upload-time = "2019-07-06T00:19:08.989Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d7/0c/56be52741f75bad4dc6555991fabd2e07b432d333da82c11ad701123888a/ffmpeg_python-0.2.0-py3-none-any.whl", hash = "sha256:ac441a0404e053f8b6a1113a77c0f452f1cfc62f6344a769475ffdc0f56c23c5", size = 25024, upload-time = "2019-07-06T00:19:07.215Z" }, +] + +[[package]] +name = "filelock" +version = "3.28.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d6/17/6e8890271880903e3538660a21d63a6c1fea969ac71d0d6b608b78727fa9/filelock-3.28.0.tar.gz", hash = "sha256:4ed1010aae813c4ee8d9c660e4792475ee60c4a0ba76073ceaf862bd317e3ca6", size = 56474, upload-time = "2026-04-14T22:54:33.625Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/3b/21/2f728888c45033d34a417bfcd248ea2564c9e08ab1bfd301377cf05d5586/filelock-3.28.0-py3-none-any.whl", hash = "sha256:de9af6712788e7171df1b28b15eba2446c69721433fa427a9bee07b17820a9db", size = 39189, upload-time = "2026-04-14T22:54:32.037Z" }, +] + +[[package]] +name = "frozenlist" +version = "1.8.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/2d/f5/c831fac6cc817d26fd54c7eaccd04ef7e0288806943f7cc5bbf69f3ac1f0/frozenlist-1.8.0.tar.gz", hash = "sha256:3ede829ed8d842f6cd48fc7081d7a41001a56f1f38603f9d49bf3020d59a31ad", size = 45875, upload-time = "2025-10-06T05:38:17.865Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/69/29/948b9aa87e75820a38650af445d2ef2b6b8a6fab1a23b6bb9e4ef0be2d59/frozenlist-1.8.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:78f7b9e5d6f2fdb88cdde9440dc147259b62b9d3b019924def9f6478be254ac1", size = 87782, upload-time = "2025-10-06T05:36:06.649Z" }, + { url = "https://files.pythonhosted.org/packages/64/80/4f6e318ee2a7c0750ed724fa33a4bdf1eacdc5a39a7a24e818a773cd91af/frozenlist-1.8.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:229bf37d2e4acdaf808fd3f06e854a4a7a3661e871b10dc1f8f1896a3b05f18b", size = 50594, upload-time = "2025-10-06T05:36:07.69Z" }, + { url = "https://files.pythonhosted.org/packages/2b/94/5c8a2b50a496b11dd519f4a24cb5496cf125681dd99e94c604ccdea9419a/frozenlist-1.8.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f833670942247a14eafbb675458b4e61c82e002a148f49e68257b79296e865c4", size = 50448, upload-time = "2025-10-06T05:36:08.78Z" }, + { url = "https://files.pythonhosted.org/packages/6a/bd/d91c5e39f490a49df14320f4e8c80161cfcce09f1e2cde1edd16a551abb3/frozenlist-1.8.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:494a5952b1c597ba44e0e78113a7266e656b9794eec897b19ead706bd7074383", size = 242411, upload-time = "2025-10-06T05:36:09.801Z" }, + { url = "https://files.pythonhosted.org/packages/8f/83/f61505a05109ef3293dfb1ff594d13d64a2324ac3482be2cedc2be818256/frozenlist-1.8.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:96f423a119f4777a4a056b66ce11527366a8bb92f54e541ade21f2374433f6d4", size = 243014, upload-time = "2025-10-06T05:36:11.394Z" }, + { url = "https://files.pythonhosted.org/packages/d8/cb/cb6c7b0f7d4023ddda30cf56b8b17494eb3a79e3fda666bf735f63118b35/frozenlist-1.8.0-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:3462dd9475af2025c31cc61be6652dfa25cbfb56cbbf52f4ccfe029f38decaf8", size = 234909, upload-time = "2025-10-06T05:36:12.598Z" }, + { url = "https://files.pythonhosted.org/packages/31/c5/cd7a1f3b8b34af009fb17d4123c5a778b44ae2804e3ad6b86204255f9ec5/frozenlist-1.8.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c4c800524c9cd9bac5166cd6f55285957fcfc907db323e193f2afcd4d9abd69b", size = 250049, upload-time = "2025-10-06T05:36:14.065Z" }, + { url = "https://files.pythonhosted.org/packages/c0/01/2f95d3b416c584a1e7f0e1d6d31998c4a795f7544069ee2e0962a4b60740/frozenlist-1.8.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d6a5df73acd3399d893dafc71663ad22534b5aa4f94e8a2fabfe856c3c1b6a52", size = 256485, upload-time = "2025-10-06T05:36:15.39Z" }, + { url = "https://files.pythonhosted.org/packages/ce/03/024bf7720b3abaebcff6d0793d73c154237b85bdf67b7ed55e5e9596dc9a/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:405e8fe955c2280ce66428b3ca55e12b3c4e9c336fb2103a4937e891c69a4a29", size = 237619, upload-time = "2025-10-06T05:36:16.558Z" }, + { url = "https://files.pythonhosted.org/packages/69/fa/f8abdfe7d76b731f5d8bd217827cf6764d4f1d9763407e42717b4bed50a0/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:908bd3f6439f2fef9e85031b59fd4f1297af54415fb60e4254a95f75b3cab3f3", size = 250320, upload-time = "2025-10-06T05:36:17.821Z" }, + { url = "https://files.pythonhosted.org/packages/f5/3c/b051329f718b463b22613e269ad72138cc256c540f78a6de89452803a47d/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:294e487f9ec720bd8ffcebc99d575f7eff3568a08a253d1ee1a0378754b74143", size = 246820, upload-time = "2025-10-06T05:36:19.046Z" }, + { url = "https://files.pythonhosted.org/packages/0f/ae/58282e8f98e444b3f4dd42448ff36fa38bef29e40d40f330b22e7108f565/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:74c51543498289c0c43656701be6b077f4b265868fa7f8a8859c197006efb608", size = 250518, upload-time = "2025-10-06T05:36:20.763Z" }, + { url = "https://files.pythonhosted.org/packages/8f/96/007e5944694d66123183845a106547a15944fbbb7154788cbf7272789536/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:776f352e8329135506a1d6bf16ac3f87bc25b28e765949282dcc627af36123aa", size = 239096, upload-time = "2025-10-06T05:36:22.129Z" }, + { url = "https://files.pythonhosted.org/packages/66/bb/852b9d6db2fa40be96f29c0d1205c306288f0684df8fd26ca1951d461a56/frozenlist-1.8.0-cp312-cp312-win32.whl", hash = "sha256:433403ae80709741ce34038da08511d4a77062aa924baf411ef73d1146e74faf", size = 39985, upload-time = "2025-10-06T05:36:23.661Z" }, + { url = "https://files.pythonhosted.org/packages/b8/af/38e51a553dd66eb064cdf193841f16f077585d4d28394c2fa6235cb41765/frozenlist-1.8.0-cp312-cp312-win_amd64.whl", hash = "sha256:34187385b08f866104f0c0617404c8eb08165ab1272e884abc89c112e9c00746", size = 44591, upload-time = "2025-10-06T05:36:24.958Z" }, + { url = "https://files.pythonhosted.org/packages/a7/06/1dc65480ab147339fecc70797e9c2f69d9cea9cf38934ce08df070fdb9cb/frozenlist-1.8.0-cp312-cp312-win_arm64.whl", hash = "sha256:fe3c58d2f5db5fbd18c2987cba06d51b0529f52bc3a6cdc33d3f4eab725104bd", size = 40102, upload-time = "2025-10-06T05:36:26.333Z" }, + { url = "https://files.pythonhosted.org/packages/2d/40/0832c31a37d60f60ed79e9dfb5a92e1e2af4f40a16a29abcc7992af9edff/frozenlist-1.8.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:8d92f1a84bb12d9e56f818b3a746f3efba93c1b63c8387a73dde655e1e42282a", size = 85717, upload-time = "2025-10-06T05:36:27.341Z" }, + { url = "https://files.pythonhosted.org/packages/30/ba/b0b3de23f40bc55a7057bd38434e25c34fa48e17f20ee273bbde5e0650f3/frozenlist-1.8.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:96153e77a591c8adc2ee805756c61f59fef4cf4073a9275ee86fe8cba41241f7", size = 49651, upload-time = "2025-10-06T05:36:28.855Z" }, + { url = "https://files.pythonhosted.org/packages/0c/ab/6e5080ee374f875296c4243c381bbdef97a9ac39c6e3ce1d5f7d42cb78d6/frozenlist-1.8.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:f21f00a91358803399890ab167098c131ec2ddd5f8f5fd5fe9c9f2c6fcd91e40", size = 49417, upload-time = "2025-10-06T05:36:29.877Z" }, + { url = "https://files.pythonhosted.org/packages/d5/4e/e4691508f9477ce67da2015d8c00acd751e6287739123113a9fca6f1604e/frozenlist-1.8.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:fb30f9626572a76dfe4293c7194a09fb1fe93ba94c7d4f720dfae3b646b45027", size = 234391, upload-time = "2025-10-06T05:36:31.301Z" }, + { url = "https://files.pythonhosted.org/packages/40/76/c202df58e3acdf12969a7895fd6f3bc016c642e6726aa63bd3025e0fc71c/frozenlist-1.8.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:eaa352d7047a31d87dafcacbabe89df0aa506abb5b1b85a2fb91bc3faa02d822", size = 233048, upload-time = "2025-10-06T05:36:32.531Z" }, + { url = "https://files.pythonhosted.org/packages/f9/c0/8746afb90f17b73ca5979c7a3958116e105ff796e718575175319b5bb4ce/frozenlist-1.8.0-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:03ae967b4e297f58f8c774c7eabcce57fe3c2434817d4385c50661845a058121", size = 226549, upload-time = "2025-10-06T05:36:33.706Z" }, + { url = "https://files.pythonhosted.org/packages/7e/eb/4c7eefc718ff72f9b6c4893291abaae5fbc0c82226a32dcd8ef4f7a5dbef/frozenlist-1.8.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f6292f1de555ffcc675941d65fffffb0a5bcd992905015f85d0592201793e0e5", size = 239833, upload-time = "2025-10-06T05:36:34.947Z" }, + { url = "https://files.pythonhosted.org/packages/c2/4e/e5c02187cf704224f8b21bee886f3d713ca379535f16893233b9d672ea71/frozenlist-1.8.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:29548f9b5b5e3460ce7378144c3010363d8035cea44bc0bf02d57f5a685e084e", size = 245363, upload-time = "2025-10-06T05:36:36.534Z" }, + { url = "https://files.pythonhosted.org/packages/1f/96/cb85ec608464472e82ad37a17f844889c36100eed57bea094518bf270692/frozenlist-1.8.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ec3cc8c5d4084591b4237c0a272cc4f50a5b03396a47d9caaf76f5d7b38a4f11", size = 229314, upload-time = "2025-10-06T05:36:38.582Z" }, + { url = "https://files.pythonhosted.org/packages/5d/6f/4ae69c550e4cee66b57887daeebe006fe985917c01d0fff9caab9883f6d0/frozenlist-1.8.0-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:517279f58009d0b1f2e7c1b130b377a349405da3f7621ed6bfae50b10adf20c1", size = 243365, upload-time = "2025-10-06T05:36:40.152Z" }, + { url = "https://files.pythonhosted.org/packages/7a/58/afd56de246cf11780a40a2c28dc7cbabbf06337cc8ddb1c780a2d97e88d8/frozenlist-1.8.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:db1e72ede2d0d7ccb213f218df6a078a9c09a7de257c2fe8fcef16d5925230b1", size = 237763, upload-time = "2025-10-06T05:36:41.355Z" }, + { url = "https://files.pythonhosted.org/packages/cb/36/cdfaf6ed42e2644740d4a10452d8e97fa1c062e2a8006e4b09f1b5fd7d63/frozenlist-1.8.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:b4dec9482a65c54a5044486847b8a66bf10c9cb4926d42927ec4e8fd5db7fed8", size = 240110, upload-time = "2025-10-06T05:36:42.716Z" }, + { url = "https://files.pythonhosted.org/packages/03/a8/9ea226fbefad669f11b52e864c55f0bd57d3c8d7eb07e9f2e9a0b39502e1/frozenlist-1.8.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:21900c48ae04d13d416f0e1e0c4d81f7931f73a9dfa0b7a8746fb2fe7dd970ed", size = 233717, upload-time = "2025-10-06T05:36:44.251Z" }, + { url = "https://files.pythonhosted.org/packages/1e/0b/1b5531611e83ba7d13ccc9988967ea1b51186af64c42b7a7af465dcc9568/frozenlist-1.8.0-cp313-cp313-win32.whl", hash = "sha256:8b7b94a067d1c504ee0b16def57ad5738701e4ba10cec90529f13fa03c833496", size = 39628, upload-time = "2025-10-06T05:36:45.423Z" }, + { url = "https://files.pythonhosted.org/packages/d8/cf/174c91dbc9cc49bc7b7aab74d8b734e974d1faa8f191c74af9b7e80848e6/frozenlist-1.8.0-cp313-cp313-win_amd64.whl", hash = "sha256:878be833caa6a3821caf85eb39c5ba92d28e85df26d57afb06b35b2efd937231", size = 43882, upload-time = "2025-10-06T05:36:46.796Z" }, + { url = "https://files.pythonhosted.org/packages/c1/17/502cd212cbfa96eb1388614fe39a3fc9ab87dbbe042b66f97acb57474834/frozenlist-1.8.0-cp313-cp313-win_arm64.whl", hash = "sha256:44389d135b3ff43ba8cc89ff7f51f5a0bb6b63d829c8300f79a2fe4fe61bcc62", size = 39676, upload-time = "2025-10-06T05:36:47.8Z" }, + { url = "https://files.pythonhosted.org/packages/d2/5c/3bbfaa920dfab09e76946a5d2833a7cbdf7b9b4a91c714666ac4855b88b4/frozenlist-1.8.0-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:e25ac20a2ef37e91c1b39938b591457666a0fa835c7783c3a8f33ea42870db94", size = 89235, upload-time = "2025-10-06T05:36:48.78Z" }, + { url = "https://files.pythonhosted.org/packages/d2/d6/f03961ef72166cec1687e84e8925838442b615bd0b8854b54923ce5b7b8a/frozenlist-1.8.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:07cdca25a91a4386d2e76ad992916a85038a9b97561bf7a3fd12d5d9ce31870c", size = 50742, upload-time = "2025-10-06T05:36:49.837Z" }, + { url = "https://files.pythonhosted.org/packages/1e/bb/a6d12b7ba4c3337667d0e421f7181c82dda448ce4e7ad7ecd249a16fa806/frozenlist-1.8.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:4e0c11f2cc6717e0a741f84a527c52616140741cd812a50422f83dc31749fb52", size = 51725, upload-time = "2025-10-06T05:36:50.851Z" }, + { url = "https://files.pythonhosted.org/packages/bc/71/d1fed0ffe2c2ccd70b43714c6cab0f4188f09f8a67a7914a6b46ee30f274/frozenlist-1.8.0-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:b3210649ee28062ea6099cfda39e147fa1bc039583c8ee4481cb7811e2448c51", size = 284533, upload-time = "2025-10-06T05:36:51.898Z" }, + { url = "https://files.pythonhosted.org/packages/c9/1f/fb1685a7b009d89f9bf78a42d94461bc06581f6e718c39344754a5d9bada/frozenlist-1.8.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:581ef5194c48035a7de2aefc72ac6539823bb71508189e5de01d60c9dcd5fa65", size = 292506, upload-time = "2025-10-06T05:36:53.101Z" }, + { url = "https://files.pythonhosted.org/packages/e6/3b/b991fe1612703f7e0d05c0cf734c1b77aaf7c7d321df4572e8d36e7048c8/frozenlist-1.8.0-cp313-cp313t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:3ef2d026f16a2b1866e1d86fc4e1291e1ed8a387b2c333809419a2f8b3a77b82", size = 274161, upload-time = "2025-10-06T05:36:54.309Z" }, + { url = "https://files.pythonhosted.org/packages/ca/ec/c5c618767bcdf66e88945ec0157d7f6c4a1322f1473392319b7a2501ded7/frozenlist-1.8.0-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:5500ef82073f599ac84d888e3a8c1f77ac831183244bfd7f11eaa0289fb30714", size = 294676, upload-time = "2025-10-06T05:36:55.566Z" }, + { url = "https://files.pythonhosted.org/packages/7c/ce/3934758637d8f8a88d11f0585d6495ef54b2044ed6ec84492a91fa3b27aa/frozenlist-1.8.0-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:50066c3997d0091c411a66e710f4e11752251e6d2d73d70d8d5d4c76442a199d", size = 300638, upload-time = "2025-10-06T05:36:56.758Z" }, + { url = "https://files.pythonhosted.org/packages/fc/4f/a7e4d0d467298f42de4b41cbc7ddaf19d3cfeabaf9ff97c20c6c7ee409f9/frozenlist-1.8.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:5c1c8e78426e59b3f8005e9b19f6ff46e5845895adbde20ece9218319eca6506", size = 283067, upload-time = "2025-10-06T05:36:57.965Z" }, + { url = "https://files.pythonhosted.org/packages/dc/48/c7b163063d55a83772b268e6d1affb960771b0e203b632cfe09522d67ea5/frozenlist-1.8.0-cp313-cp313t-musllinux_1_2_armv7l.whl", hash = "sha256:eefdba20de0d938cec6a89bd4d70f346a03108a19b9df4248d3cf0d88f1b0f51", size = 292101, upload-time = "2025-10-06T05:36:59.237Z" }, + { url = "https://files.pythonhosted.org/packages/9f/d0/2366d3c4ecdc2fd391e0afa6e11500bfba0ea772764d631bbf82f0136c9d/frozenlist-1.8.0-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:cf253e0e1c3ceb4aaff6df637ce033ff6535fb8c70a764a8f46aafd3d6ab798e", size = 289901, upload-time = "2025-10-06T05:37:00.811Z" }, + { url = "https://files.pythonhosted.org/packages/b8/94/daff920e82c1b70e3618a2ac39fbc01ae3e2ff6124e80739ce5d71c9b920/frozenlist-1.8.0-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:032efa2674356903cd0261c4317a561a6850f3ac864a63fc1583147fb05a79b0", size = 289395, upload-time = "2025-10-06T05:37:02.115Z" }, + { url = "https://files.pythonhosted.org/packages/e3/20/bba307ab4235a09fdcd3cc5508dbabd17c4634a1af4b96e0f69bfe551ebd/frozenlist-1.8.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:6da155091429aeba16851ecb10a9104a108bcd32f6c1642867eadaee401c1c41", size = 283659, upload-time = "2025-10-06T05:37:03.711Z" }, + { url = "https://files.pythonhosted.org/packages/fd/00/04ca1c3a7a124b6de4f8a9a17cc2fcad138b4608e7a3fc5877804b8715d7/frozenlist-1.8.0-cp313-cp313t-win32.whl", hash = "sha256:0f96534f8bfebc1a394209427d0f8a63d343c9779cda6fc25e8e121b5fd8555b", size = 43492, upload-time = "2025-10-06T05:37:04.915Z" }, + { url = "https://files.pythonhosted.org/packages/59/5e/c69f733a86a94ab10f68e496dc6b7e8bc078ebb415281d5698313e3af3a1/frozenlist-1.8.0-cp313-cp313t-win_amd64.whl", hash = "sha256:5d63a068f978fc69421fb0e6eb91a9603187527c86b7cd3f534a5b77a592b888", size = 48034, upload-time = "2025-10-06T05:37:06.343Z" }, + { url = "https://files.pythonhosted.org/packages/16/6c/be9d79775d8abe79b05fa6d23da99ad6e7763a1d080fbae7290b286093fd/frozenlist-1.8.0-cp313-cp313t-win_arm64.whl", hash = "sha256:bf0a7e10b077bf5fb9380ad3ae8ce20ef919a6ad93b4552896419ac7e1d8e042", size = 41749, upload-time = "2025-10-06T05:37:07.431Z" }, + { url = "https://files.pythonhosted.org/packages/f1/c8/85da824b7e7b9b6e7f7705b2ecaf9591ba6f79c1177f324c2735e41d36a2/frozenlist-1.8.0-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:cee686f1f4cadeb2136007ddedd0aaf928ab95216e7691c63e50a8ec066336d0", size = 86127, upload-time = "2025-10-06T05:37:08.438Z" }, + { url = "https://files.pythonhosted.org/packages/8e/e8/a1185e236ec66c20afd72399522f142c3724c785789255202d27ae992818/frozenlist-1.8.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:119fb2a1bd47307e899c2fac7f28e85b9a543864df47aa7ec9d3c1b4545f096f", size = 49698, upload-time = "2025-10-06T05:37:09.48Z" }, + { url = "https://files.pythonhosted.org/packages/a1/93/72b1736d68f03fda5fdf0f2180fb6caaae3894f1b854d006ac61ecc727ee/frozenlist-1.8.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:4970ece02dbc8c3a92fcc5228e36a3e933a01a999f7094ff7c23fbd2beeaa67c", size = 49749, upload-time = "2025-10-06T05:37:10.569Z" }, + { url = "https://files.pythonhosted.org/packages/a7/b2/fabede9fafd976b991e9f1b9c8c873ed86f202889b864756f240ce6dd855/frozenlist-1.8.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:cba69cb73723c3f329622e34bdbf5ce1f80c21c290ff04256cff1cd3c2036ed2", size = 231298, upload-time = "2025-10-06T05:37:11.993Z" }, + { url = "https://files.pythonhosted.org/packages/3a/3b/d9b1e0b0eed36e70477ffb8360c49c85c8ca8ef9700a4e6711f39a6e8b45/frozenlist-1.8.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:778a11b15673f6f1df23d9586f83c4846c471a8af693a22e066508b77d201ec8", size = 232015, upload-time = "2025-10-06T05:37:13.194Z" }, + { url = "https://files.pythonhosted.org/packages/dc/94/be719d2766c1138148564a3960fc2c06eb688da592bdc25adcf856101be7/frozenlist-1.8.0-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:0325024fe97f94c41c08872db482cf8ac4800d80e79222c6b0b7b162d5b13686", size = 225038, upload-time = "2025-10-06T05:37:14.577Z" }, + { url = "https://files.pythonhosted.org/packages/e4/09/6712b6c5465f083f52f50cf74167b92d4ea2f50e46a9eea0523d658454ae/frozenlist-1.8.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:97260ff46b207a82a7567b581ab4190bd4dfa09f4db8a8b49d1a958f6aa4940e", size = 240130, upload-time = "2025-10-06T05:37:15.781Z" }, + { url = "https://files.pythonhosted.org/packages/f8/d4/cd065cdcf21550b54f3ce6a22e143ac9e4836ca42a0de1022da8498eac89/frozenlist-1.8.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:54b2077180eb7f83dd52c40b2750d0a9f175e06a42e3213ce047219de902717a", size = 242845, upload-time = "2025-10-06T05:37:17.037Z" }, + { url = "https://files.pythonhosted.org/packages/62/c3/f57a5c8c70cd1ead3d5d5f776f89d33110b1addae0ab010ad774d9a44fb9/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:2f05983daecab868a31e1da44462873306d3cbfd76d1f0b5b69c473d21dbb128", size = 229131, upload-time = "2025-10-06T05:37:18.221Z" }, + { url = "https://files.pythonhosted.org/packages/6c/52/232476fe9cb64f0742f3fde2b7d26c1dac18b6d62071c74d4ded55e0ef94/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:33f48f51a446114bc5d251fb2954ab0164d5be02ad3382abcbfe07e2531d650f", size = 240542, upload-time = "2025-10-06T05:37:19.771Z" }, + { url = "https://files.pythonhosted.org/packages/5f/85/07bf3f5d0fb5414aee5f47d33c6f5c77bfe49aac680bfece33d4fdf6a246/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:154e55ec0655291b5dd1b8731c637ecdb50975a2ae70c606d100750a540082f7", size = 237308, upload-time = "2025-10-06T05:37:20.969Z" }, + { url = "https://files.pythonhosted.org/packages/11/99/ae3a33d5befd41ac0ca2cc7fd3aa707c9c324de2e89db0e0f45db9a64c26/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:4314debad13beb564b708b4a496020e5306c7333fa9a3ab90374169a20ffab30", size = 238210, upload-time = "2025-10-06T05:37:22.252Z" }, + { url = "https://files.pythonhosted.org/packages/b2/60/b1d2da22f4970e7a155f0adde9b1435712ece01b3cd45ba63702aea33938/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:073f8bf8becba60aa931eb3bc420b217bb7d5b8f4750e6f8b3be7f3da85d38b7", size = 231972, upload-time = "2025-10-06T05:37:23.5Z" }, + { url = "https://files.pythonhosted.org/packages/3f/ab/945b2f32de889993b9c9133216c068b7fcf257d8595a0ac420ac8677cab0/frozenlist-1.8.0-cp314-cp314-win32.whl", hash = "sha256:bac9c42ba2ac65ddc115d930c78d24ab8d4f465fd3fc473cdedfccadb9429806", size = 40536, upload-time = "2025-10-06T05:37:25.581Z" }, + { url = "https://files.pythonhosted.org/packages/59/ad/9caa9b9c836d9ad6f067157a531ac48b7d36499f5036d4141ce78c230b1b/frozenlist-1.8.0-cp314-cp314-win_amd64.whl", hash = "sha256:3e0761f4d1a44f1d1a47996511752cf3dcec5bbdd9cc2b4fe595caf97754b7a0", size = 44330, upload-time = "2025-10-06T05:37:26.928Z" }, + { url = "https://files.pythonhosted.org/packages/82/13/e6950121764f2676f43534c555249f57030150260aee9dcf7d64efda11dd/frozenlist-1.8.0-cp314-cp314-win_arm64.whl", hash = "sha256:d1eaff1d00c7751b7c6662e9c5ba6eb2c17a2306ba5e2a37f24ddf3cc953402b", size = 40627, upload-time = "2025-10-06T05:37:28.075Z" }, + { url = "https://files.pythonhosted.org/packages/c0/c7/43200656ecc4e02d3f8bc248df68256cd9572b3f0017f0a0c4e93440ae23/frozenlist-1.8.0-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:d3bb933317c52d7ea5004a1c442eef86f426886fba134ef8cf4226ea6ee1821d", size = 89238, upload-time = "2025-10-06T05:37:29.373Z" }, + { url = "https://files.pythonhosted.org/packages/d1/29/55c5f0689b9c0fb765055629f472c0de484dcaf0acee2f7707266ae3583c/frozenlist-1.8.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:8009897cdef112072f93a0efdce29cd819e717fd2f649ee3016efd3cd885a7ed", size = 50738, upload-time = "2025-10-06T05:37:30.792Z" }, + { url = "https://files.pythonhosted.org/packages/ba/7d/b7282a445956506fa11da8c2db7d276adcbf2b17d8bb8407a47685263f90/frozenlist-1.8.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:2c5dcbbc55383e5883246d11fd179782a9d07a986c40f49abe89ddf865913930", size = 51739, upload-time = "2025-10-06T05:37:32.127Z" }, + { url = "https://files.pythonhosted.org/packages/62/1c/3d8622e60d0b767a5510d1d3cf21065b9db874696a51ea6d7a43180a259c/frozenlist-1.8.0-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:39ecbc32f1390387d2aa4f5a995e465e9e2f79ba3adcac92d68e3e0afae6657c", size = 284186, upload-time = "2025-10-06T05:37:33.21Z" }, + { url = "https://files.pythonhosted.org/packages/2d/14/aa36d5f85a89679a85a1d44cd7a6657e0b1c75f61e7cad987b203d2daca8/frozenlist-1.8.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:92db2bf818d5cc8d9c1f1fc56b897662e24ea5adb36ad1f1d82875bd64e03c24", size = 292196, upload-time = "2025-10-06T05:37:36.107Z" }, + { url = "https://files.pythonhosted.org/packages/05/23/6bde59eb55abd407d34f77d39a5126fb7b4f109a3f611d3929f14b700c66/frozenlist-1.8.0-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:2dc43a022e555de94c3b68a4ef0b11c4f747d12c024a520c7101709a2144fb37", size = 273830, upload-time = "2025-10-06T05:37:37.663Z" }, + { url = "https://files.pythonhosted.org/packages/d2/3f/22cff331bfad7a8afa616289000ba793347fcd7bc275f3b28ecea2a27909/frozenlist-1.8.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:cb89a7f2de3602cfed448095bab3f178399646ab7c61454315089787df07733a", size = 294289, upload-time = "2025-10-06T05:37:39.261Z" }, + { url = "https://files.pythonhosted.org/packages/a4/89/5b057c799de4838b6c69aa82b79705f2027615e01be996d2486a69ca99c4/frozenlist-1.8.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:33139dc858c580ea50e7e60a1b0ea003efa1fd42e6ec7fdbad78fff65fad2fd2", size = 300318, upload-time = "2025-10-06T05:37:43.213Z" }, + { url = "https://files.pythonhosted.org/packages/30/de/2c22ab3eb2a8af6d69dc799e48455813bab3690c760de58e1bf43b36da3e/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:168c0969a329b416119507ba30b9ea13688fafffac1b7822802537569a1cb0ef", size = 282814, upload-time = "2025-10-06T05:37:45.337Z" }, + { url = "https://files.pythonhosted.org/packages/59/f7/970141a6a8dbd7f556d94977858cfb36fa9b66e0892c6dd780d2219d8cd8/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:28bd570e8e189d7f7b001966435f9dac6718324b5be2990ac496cf1ea9ddb7fe", size = 291762, upload-time = "2025-10-06T05:37:46.657Z" }, + { url = "https://files.pythonhosted.org/packages/c1/15/ca1adae83a719f82df9116d66f5bb28bb95557b3951903d39135620ef157/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:b2a095d45c5d46e5e79ba1e5b9cb787f541a8dee0433836cea4b96a2c439dcd8", size = 289470, upload-time = "2025-10-06T05:37:47.946Z" }, + { url = "https://files.pythonhosted.org/packages/ac/83/dca6dc53bf657d371fbc88ddeb21b79891e747189c5de990b9dfff2ccba1/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:eab8145831a0d56ec9c4139b6c3e594c7a83c2c8be25d5bcf2d86136a532287a", size = 289042, upload-time = "2025-10-06T05:37:49.499Z" }, + { url = "https://files.pythonhosted.org/packages/96/52/abddd34ca99be142f354398700536c5bd315880ed0a213812bc491cff5e4/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:974b28cf63cc99dfb2188d8d222bc6843656188164848c4f679e63dae4b0708e", size = 283148, upload-time = "2025-10-06T05:37:50.745Z" }, + { url = "https://files.pythonhosted.org/packages/af/d3/76bd4ed4317e7119c2b7f57c3f6934aba26d277acc6309f873341640e21f/frozenlist-1.8.0-cp314-cp314t-win32.whl", hash = "sha256:342c97bf697ac5480c0a7ec73cd700ecfa5a8a40ac923bd035484616efecc2df", size = 44676, upload-time = "2025-10-06T05:37:52.222Z" }, + { url = "https://files.pythonhosted.org/packages/89/76/c615883b7b521ead2944bb3480398cbb07e12b7b4e4d073d3752eb721558/frozenlist-1.8.0-cp314-cp314t-win_amd64.whl", hash = "sha256:06be8f67f39c8b1dc671f5d83aaefd3358ae5cdcf8314552c57e7ed3e6475bdd", size = 49451, upload-time = "2025-10-06T05:37:53.425Z" }, + { url = "https://files.pythonhosted.org/packages/e0/a3/5982da14e113d07b325230f95060e2169f5311b1017ea8af2a29b374c289/frozenlist-1.8.0-cp314-cp314t-win_arm64.whl", hash = "sha256:102e6314ca4da683dca92e3b1355490fed5f313b768500084fbe6371fddfdb79", size = 42507, upload-time = "2025-10-06T05:37:54.513Z" }, + { url = "https://files.pythonhosted.org/packages/9a/9a/e35b4a917281c0b8419d4207f4334c8e8c5dbf4f3f5f9ada73958d937dcc/frozenlist-1.8.0-py3-none-any.whl", hash = "sha256:0c18a16eab41e82c295618a77502e17b195883241c563b00f0aa5106fc4eaa0d", size = 13409, upload-time = "2025-10-06T05:38:16.721Z" }, +] + +[[package]] +name = "fsspec" +version = "2026.3.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/e1/cf/b50ddf667c15276a9ab15a70ef5f257564de271957933ffea49d2cdbcdfb/fsspec-2026.3.0.tar.gz", hash = "sha256:1ee6a0e28677557f8c2f994e3eea77db6392b4de9cd1f5d7a9e87a0ae9d01b41", size = 313547, upload-time = "2026-03-27T19:11:14.892Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d5/1f/5f4a3cd9e4440e9d9bc78ad0a91a1c8d46b4d429d5239ebe6793c9fe5c41/fsspec-2026.3.0-py3-none-any.whl", hash = "sha256:d2ceafaad1b3457968ed14efa28798162f1638dbb5d2a6868a2db002a5ee39a4", size = 202595, upload-time = "2026-03-27T19:11:13.595Z" }, +] + +[[package]] +name = "future" +version = "1.0.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/a7/b2/4140c69c6a66432916b26158687e821ba631a4c9273c474343badf84d3ba/future-1.0.0.tar.gz", hash = "sha256:bd2968309307861edae1458a4f8a4f3598c03be43b97521076aebf5d94c07b05", size = 1228490, upload-time = "2024-02-21T11:52:38.461Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/da/71/ae30dadffc90b9006d77af76b393cb9dfbfc9629f339fc1574a1c52e6806/future-1.0.0-py3-none-any.whl", hash = "sha256:929292d34f5872e70396626ef385ec22355a1fae8ad29e1a734c3e43f9fbc216", size = 491326, upload-time = "2024-02-21T11:52:35.956Z" }, +] + [[package]] name = "google-auth" version = "2.49.2" @@ -474,6 +744,38 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" }, ] +[[package]] +name = "hf-xet" +version = "1.4.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/53/92/ec9ad04d0b5728dca387a45af7bc98fbb0d73b2118759f5f6038b61a57e8/hf_xet-1.4.3.tar.gz", hash = "sha256:8ddedb73c8c08928c793df2f3401ec26f95be7f7e516a7bee2fbb546f6676113", size = 670477, upload-time = "2026-03-31T22:40:07.874Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/72/43/724d307b34e353da0abd476e02f72f735cdd2bc86082dee1b32ea0bfee1d/hf_xet-1.4.3-cp313-cp313t-macosx_10_12_x86_64.whl", hash = "sha256:7551659ba4f1e1074e9623996f28c3873682530aee0a846b7f2f066239228144", size = 3800935, upload-time = "2026-03-31T22:39:49.618Z" }, + { url = "https://files.pythonhosted.org/packages/2b/d2/8bee5996b699262edb87dbb54118d287c0e1b2fc78af7cdc41857ba5e3c4/hf_xet-1.4.3-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:bee693ada985e7045997f05f081d0e12c4c08bd7626dc397f8a7c487e6c04f7f", size = 3558942, upload-time = "2026-03-31T22:39:47.938Z" }, + { url = "https://files.pythonhosted.org/packages/c3/a1/e993d09cbe251196fb60812b09a58901c468127b7259d2bf0f68bf6088eb/hf_xet-1.4.3-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:21644b404bb0100fe3857892f752c4d09642586fd988e61501c95bbf44b393a3", size = 4207657, upload-time = "2026-03-31T22:39:39.69Z" }, + { url = "https://files.pythonhosted.org/packages/64/44/9eb6d21e5c34c63e5e399803a6932fa983cabdf47c0ecbcfe7ea97684b8c/hf_xet-1.4.3-cp313-cp313t-manylinux_2_28_aarch64.whl", hash = "sha256:987f09cfe418237812896a6736b81b1af02a3a6dcb4b4944425c4c4fca7a7cf8", size = 3986765, upload-time = "2026-03-31T22:39:37.936Z" }, + { url = "https://files.pythonhosted.org/packages/ea/7b/8ad6f16fdb82f5f7284a34b5ec48645bd575bdcd2f6f0d1644775909c486/hf_xet-1.4.3-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:60cf7fc43a99da0a853345cf86d23738c03983ee5249613a6305d3e57a5dca74", size = 4188162, upload-time = "2026-03-31T22:39:58.382Z" }, + { url = "https://files.pythonhosted.org/packages/1b/c4/39d6e136cbeea9ca5a23aad4b33024319222adbdc059ebcda5fc7d9d5ff4/hf_xet-1.4.3-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:2815a49a7a59f3e2edf0cf113ae88e8cb2ca2a221bf353fb60c609584f4884d4", size = 4424525, upload-time = "2026-03-31T22:40:00.225Z" }, + { url = "https://files.pythonhosted.org/packages/46/f2/adc32dae6bdbc367853118b9878139ac869419a4ae7ba07185dc31251b76/hf_xet-1.4.3-cp313-cp313t-win_amd64.whl", hash = "sha256:42ee323265f1e6a81b0e11094564fb7f7e0ec75b5105ffd91ae63f403a11931b", size = 3671610, upload-time = "2026-03-31T22:40:10.42Z" }, + { url = "https://files.pythonhosted.org/packages/e2/19/25d897dcc3f81953e0c2cde9ec186c7a0fee413eb0c9a7a9130d87d94d3a/hf_xet-1.4.3-cp313-cp313t-win_arm64.whl", hash = "sha256:27c976ba60079fb8217f485b9c5c7fcd21c90b0367753805f87cb9f3cdc4418a", size = 3528529, upload-time = "2026-03-31T22:40:09.106Z" }, + { url = "https://files.pythonhosted.org/packages/ec/36/3e8f85ca9fe09b8de2b2e10c63b3b3353d7dda88a0b3d426dffbe7b8313b/hf_xet-1.4.3-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:5251d5ece3a81815bae9abab41cf7ddb7bcb8f56411bce0827f4a3071c92fdc6", size = 3801019, upload-time = "2026-03-31T22:39:56.651Z" }, + { url = "https://files.pythonhosted.org/packages/b5/9c/defb6cb1de28bccb7bd8d95f6e60f72a3d3fa4cb3d0329c26fb9a488bfe7/hf_xet-1.4.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1feb0f3abeacee143367c326a128a2e2b60868ec12a36c225afb1d6c5a05e6d2", size = 3558746, upload-time = "2026-03-31T22:39:54.766Z" }, + { url = "https://files.pythonhosted.org/packages/c1/bd/8d001191893178ff8e826e46ad5299446e62b93cd164e17b0ffea08832ec/hf_xet-1.4.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8b301fc150290ca90b4fccd079829b84bb4786747584ae08b94b4577d82fb791", size = 4207692, upload-time = "2026-03-31T22:39:46.246Z" }, + { url = "https://files.pythonhosted.org/packages/ce/48/6790b402803250e9936435613d3a78b9aaeee7973439f0918848dde58309/hf_xet-1.4.3-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:d972fbe95ddc0d3c0fc49b31a8a69f47db35c1e3699bf316421705741aab6653", size = 3986281, upload-time = "2026-03-31T22:39:44.648Z" }, + { url = "https://files.pythonhosted.org/packages/51/56/ea62552fe53db652a9099eda600b032d75554d0e86c12a73824bfedef88b/hf_xet-1.4.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c5b48db1ee344a805a1b9bd2cda9b6b65fe77ed3787bd6e87ad5521141d317cd", size = 4187414, upload-time = "2026-03-31T22:40:04.951Z" }, + { url = "https://files.pythonhosted.org/packages/7d/f5/bc1456d4638061bea997e6d2db60a1a613d7b200e0755965ec312dc1ef79/hf_xet-1.4.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:22bdc1f5fb8b15bf2831440b91d1c9bbceeb7e10c81a12e8d75889996a5c9da8", size = 4424368, upload-time = "2026-03-31T22:40:06.347Z" }, + { url = "https://files.pythonhosted.org/packages/e4/76/ab597bae87e1f06d18d3ecb8ed7f0d3c9a37037fc32ce76233d369273c64/hf_xet-1.4.3-cp314-cp314t-win_amd64.whl", hash = "sha256:0392c79b7cf48418cd61478c1a925246cf10639f4cd9d94368d8ca1e8df9ea07", size = 3672280, upload-time = "2026-03-31T22:40:16.401Z" }, + { url = "https://files.pythonhosted.org/packages/62/05/2e462d34e23a09a74d73785dbed71cc5dbad82a72eee2ad60a72a554155d/hf_xet-1.4.3-cp314-cp314t-win_arm64.whl", hash = "sha256:681c92a07796325778a79d76c67011764ecc9042a8c3579332b61b63ae512075", size = 3528945, upload-time = "2026-03-31T22:40:14.995Z" }, + { url = "https://files.pythonhosted.org/packages/ac/9f/9c23e4a447b8f83120798f9279d0297a4d1360bdbf59ef49ebec78fe2545/hf_xet-1.4.3-cp37-abi3-macosx_10_12_x86_64.whl", hash = "sha256:d0da85329eaf196e03e90b84c2d0aca53bd4573d097a75f99609e80775f98025", size = 3805048, upload-time = "2026-03-31T22:39:53.105Z" }, + { url = "https://files.pythonhosted.org/packages/0b/f8/7aacb8e5f4a7899d39c787b5984e912e6c18b11be136ef13947d7a66d265/hf_xet-1.4.3-cp37-abi3-macosx_11_0_arm64.whl", hash = "sha256:e23717ce4186b265f69afa66e6f0069fe7efbf331546f5c313d00e123dc84583", size = 3562178, upload-time = "2026-03-31T22:39:51.295Z" }, + { url = "https://files.pythonhosted.org/packages/df/9a/a24b26dc8a65f0ecc0fe5be981a19e61e7ca963b85e062c083f3a9100529/hf_xet-1.4.3-cp37-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fc360b70c815bf340ed56c7b8c63aacf11762a4b099b2fe2c9bd6d6068668c08", size = 4212320, upload-time = "2026-03-31T22:39:42.922Z" }, + { url = "https://files.pythonhosted.org/packages/53/60/46d493db155d2ee2801b71fb1b0fd67696359047fdd8caee2c914cc50c79/hf_xet-1.4.3-cp37-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:39f2d2e9654cd9b4319885733993807aab6de9dfbd34c42f0b78338d6617421f", size = 3991546, upload-time = "2026-03-31T22:39:41.335Z" }, + { url = "https://files.pythonhosted.org/packages/bc/f5/067363e1c96c6b17256910830d1b54099d06287e10f4ec6ec4e7e08371fc/hf_xet-1.4.3-cp37-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:49ad8a8cead2b56051aa84d7fce3e1335efe68df3cf6c058f22a65513885baac", size = 4193200, upload-time = "2026-03-31T22:40:01.936Z" }, + { url = "https://files.pythonhosted.org/packages/42/4b/53951592882d9c23080c7644542fda34a3813104e9e11fa1a7d82d419cb8/hf_xet-1.4.3-cp37-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:7716d62015477a70ea272d2d68cd7cad140f61c52ee452e133e139abfe2c17ba", size = 4429392, upload-time = "2026-03-31T22:40:03.492Z" }, + { url = "https://files.pythonhosted.org/packages/8a/21/75a6c175b4e79662ad8e62f46a40ce341d8d6b206b06b4320d07d55b188c/hf_xet-1.4.3-cp37-abi3-win_amd64.whl", hash = "sha256:6b591fcad34e272a5b02607485e4f2a1334aebf1bc6d16ce8eb1eb8978ac2021", size = 3677359, upload-time = "2026-03-31T22:40:13.619Z" }, + { url = "https://files.pythonhosted.org/packages/8a/7c/44314ecd0e89f8b2b51c9d9e5e7a60a9c1c82024ac471d415860557d3cd8/hf_xet-1.4.3-cp37-abi3-win_arm64.whl", hash = "sha256:7c2c7e20bcfcc946dc67187c203463f5e932e395845d098cc2a93f5b67ca0b47", size = 3533664, upload-time = "2026-03-31T22:40:12.152Z" }, +] + [[package]] name = "httpcore" version = "1.0.9" @@ -540,6 +842,26 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d2/fd/6668e5aec43ab844de6fc74927e155a3b37bf40d7c3790e49fc0406b6578/httpx_sse-0.4.3-py3-none-any.whl", hash = "sha256:0ac1c9fe3c0afad2e0ebb25a934a59f4c7823b60792691f779fad2c5568830fc", size = 8960, upload-time = "2025-10-10T21:48:21.158Z" }, ] +[[package]] +name = "huggingface-hub" +version = "1.10.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "filelock" }, + { name = "fsspec" }, + { name = "hf-xet", marker = "platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'" }, + { name = "httpx" }, + { name = "packaging" }, + { name = "pyyaml" }, + { name = "tqdm" }, + { name = "typer" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/0c/4d/00734890c7fcfe2c7ff04f1c1a167186c42b19e370a2dd8cfd8c34fc92c4/huggingface_hub-1.10.2.tar.gz", hash = "sha256:4b276f820483b709dc86a53bcb8183ea496b8d8447c9f7f88a115a12b498a95f", size = 758428, upload-time = "2026-04-14T10:42:28.498Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5e/c9/4c1e1216b24bcab140c83acdf8bc89a846ea17cd8a06cd18e3fd308a297f/huggingface_hub-1.10.2-py3-none-any.whl", hash = "sha256:c26c908767cc711493978dc0b4f5747ba7841602997cc98bfd628450a28cf9bc", size = 642581, upload-time = "2026-04-14T10:42:26.563Z" }, +] + [[package]] name = "idna" version = "3.11" @@ -719,9 +1041,11 @@ dependencies = [ { name = "google-genai" }, { name = "json-repair" }, { name = "jsonpatch" }, + { name = "lancedb" }, { name = "pyyaml" }, { name = "starlette" }, { name = "uvicorn", extra = ["standard"] }, + { name = "voyageai" }, ] [package.dev-dependencies] @@ -737,9 +1061,11 @@ requires-dist = [ { name = "google-genai", specifier = ">=1.0" }, { name = "json-repair", specifier = ">=0.59.4" }, { name = "jsonpatch" }, + { name = "lancedb", specifier = ">=0.20" }, { name = "pyyaml" }, { name = "starlette" }, { name = "uvicorn", extras = ["standard"] }, + { name = "voyageai", specifier = ">=0.3" }, ] [package.metadata.requires-dev] @@ -748,6 +1074,106 @@ dev = [ { name = "pytest", specifier = ">=8.0" }, ] +[[package]] +name = "lance-namespace" +version = "0.6.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "lance-namespace-urllib3-client" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/28/9f/7906ba4117df8d965510285eaf07264a77de2fd283b9d44ec7fc63a4a57a/lance_namespace-0.6.1.tar.gz", hash = "sha256:f0deea442bd3f1056a8e2fed056ae2778e3356517ec2e680db049058b824d131", size = 10666, upload-time = "2026-03-17T17:55:44.977Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d1/91/aee1c0a04d17f2810173bd304bd444eb78332045df1b0c1b07cebd01f530/lance_namespace-0.6.1-py3-none-any.whl", hash = "sha256:9699c9e3f12236e5e08ea979cc4e036a8e3c67ed2f37ae6f25c5353ab908e1be", size = 12498, upload-time = "2026-03-17T17:55:44.062Z" }, +] + +[[package]] +name = "lance-namespace-urllib3-client" +version = "0.6.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pydantic" }, + { name = "python-dateutil" }, + { name = "typing-extensions" }, + { name = "urllib3" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/63/a1/8706a2be25bd184acccc411e48f1a42a4cbf3b6556cba15b9fcf4c15cfcc/lance_namespace_urllib3_client-0.6.1.tar.gz", hash = "sha256:31fbd058ce1ea0bf49045cdeaa756360ece0bc61e9e10276f41af6d217debe87", size = 182567, upload-time = "2026-03-17T17:55:46.87Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/cd/c7/cb9580602dec25f0fdd6005c1c9ba1d4c8c0c3dc8d543107e5a9f248bba8/lance_namespace_urllib3_client-0.6.1-py3-none-any.whl", hash = "sha256:b9c103e1377ad46d2bd70eec894bfec0b1e2133dae0964d7e4de543c6e16293b", size = 317111, upload-time = "2026-03-17T17:55:45.546Z" }, +] + +[[package]] +name = "lancedb" +version = "0.30.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "deprecation" }, + { name = "lance-namespace" }, + { name = "numpy" }, + { name = "packaging" }, + { name = "pyarrow" }, + { name = "pydantic" }, + { name = "tqdm" }, +] +wheels = [ + { url = "https://files.pythonhosted.org/packages/7f/87/67b23006663be175c396ae8f7c6ac98bfa4728de5b5583016b8b8c54eb14/lancedb-0.30.2-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:3dd8cb9e2e25efb32c088b24b3fbc57f3f24a636f4b8ad4b287b1eb52f6b5075", size = 41720461, upload-time = "2026-03-31T22:42:32.853Z" }, + { url = "https://files.pythonhosted.org/packages/78/68/b3b5f638f8de91de75751414114690cae9c294dc79d9ab2602f4562ed9df/lancedb-0.30.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f083d50b257f645bd5c4b295d693648ffb37640ce1e9d72f55041b1382f0dbd6", size = 43626135, upload-time = "2026-03-31T22:50:28.577Z" }, + { url = "https://files.pythonhosted.org/packages/ef/d1/ea8b74a8b56dd4925cc9cb9cc23c7d9675708a7f6b33d22136dc7bb34dbc/lancedb-0.30.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3aef5538db9cd82af79c90831035b4d67e9aa182ef73095a1b919caddf9bb7a5", size = 46619289, upload-time = "2026-03-31T22:55:02.242Z" }, + { url = "https://files.pythonhosted.org/packages/74/4b/5bfeacf948cfc3452b286a792dcbbfaf04649ef0820e1d3790d47bf5527e/lancedb-0.30.2-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:8b161cb1da04ae6ad45afe10093cfe4107821d93e7712b50200c435d6f4c8a20", size = 43641193, upload-time = "2026-03-31T22:51:13.63Z" }, + { url = "https://files.pythonhosted.org/packages/28/4c/a51af0ce1d18fd86afa3e8538a81abf5523d24632abe7665ce6795b8009d/lancedb-0.30.2-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:7fabc0f57944fd79ddef62ed8cf4df770654b172b1ad1019a999304fed3169f3", size = 46665361, upload-time = "2026-03-31T22:54:20.282Z" }, + { url = "https://files.pythonhosted.org/packages/88/d0/7e44e8143ac2dae8979ba882cc33d4af7b8da4741fb0361497e69b4a4379/lancedb-0.30.2-cp39-abi3-win_amd64.whl", hash = "sha256:531da53002c1c6fda829afccc8ced3056ef58eb036f09ddb2b94a06877ecc66c", size = 50940681, upload-time = "2026-03-31T23:25:52.35Z" }, +] + +[[package]] +name = "langchain-core" +version = "1.2.30" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "jsonpatch" }, + { name = "langsmith" }, + { name = "packaging" }, + { name = "pydantic" }, + { name = "pyyaml" }, + { name = "tenacity" }, + { name = "typing-extensions" }, + { name = "uuid-utils" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/aa/c6/f149313d1536de8fe45619d460a12308b5a87947a37d4958024d79b011b0/langchain_core-1.2.30.tar.gz", hash = "sha256:ee6c6b3476215c4be438231bab7003d880359230b9fdf1f65e0ffa1bde8a58e0", size = 850262, upload-time = "2026-04-15T20:37:13.946Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/79/46/e988e9f024e762750f9f53878316980bdaea2ab1f19600df01a7c39eda89/langchain_core-1.2.30-py3-none-any.whl", hash = "sha256:26fa50894449b29b31b3712fa4975db679d26abe8241a966ea2c5978b68d8394", size = 513005, upload-time = "2026-04-15T20:37:12.396Z" }, +] + +[[package]] +name = "langchain-text-splitters" +version = "1.1.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "langchain-core" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/85/38/14121ead61e0e75f79c3a35e5148ac7c2fe754a55f76eab3eed573269524/langchain_text_splitters-1.1.1.tar.gz", hash = "sha256:34861abe7c07d9e49d4dc852d0129e26b32738b60a74486853ec9b6d6a8e01d2", size = 279352, upload-time = "2026-02-18T23:02:42.798Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/84/66/d9e0c3b83b0ad75ee746c51ba347cacecb8d656b96e1d513f3e334d1ccab/langchain_text_splitters-1.1.1-py3-none-any.whl", hash = "sha256:5ed0d7bf314ba925041e7d7d17cd8b10f688300d5415fb26c29442f061e329dc", size = 35734, upload-time = "2026-02-18T23:02:41.913Z" }, +] + +[[package]] +name = "langsmith" +version = "0.7.32" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "httpx" }, + { name = "orjson", marker = "platform_python_implementation != 'PyPy'" }, + { name = "packaging" }, + { name = "pydantic" }, + { name = "requests" }, + { name = "requests-toolbelt" }, + { name = "uuid-utils" }, + { name = "xxhash" }, + { name = "zstandard" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/2f/b4/a0b4a501bee6b8a741ce29f8c48155b132118483cddc6f9247735ddb38fa/langsmith-0.7.32.tar.gz", hash = "sha256:b59b8e106d0e4c4842e158229296086e2aa7c561e3f602acda73d3ad0062e915", size = 1184518, upload-time = "2026-04-15T23:42:41.885Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/62/bc/148f98ac7dad73ac5e1b1c985290079cfeeb9ba13d760a24f25002beb2c9/langsmith-0.7.32-py3-none-any.whl", hash = "sha256:e1fde928990c4c52f47dc5132708cec674355d9101723d564183e965f383bf5f", size = 378272, upload-time = "2026-04-15T23:42:39.905Z" }, +] + [[package]] name = "markdown-it-py" version = "4.0.0" @@ -803,6 +1229,166 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/a4/8e/469e5a4a2f5855992e425f3cb33804cc07bf18d48f2db061aec61ce50270/more_itertools-10.8.0-py3-none-any.whl", hash = "sha256:52d4362373dcf7c52546bc4af9a86ee7c4579df9a8dc268be0a2f949d376cc9b", size = 69667, upload-time = "2025-09-02T15:23:09.635Z" }, ] +[[package]] +name = "multidict" +version = "6.7.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/1a/c2/c2d94cbe6ac1753f3fc980da97b3d930efe1da3af3c9f5125354436c073d/multidict-6.7.1.tar.gz", hash = "sha256:ec6652a1bee61c53a3e5776b6049172c53b6aaba34f18c9ad04f82712bac623d", size = 102010, upload-time = "2026-01-26T02:46:45.979Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8d/9c/f20e0e2cf80e4b2e4b1c365bf5fe104ee633c751a724246262db8f1a0b13/multidict-6.7.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a90f75c956e32891a4eda3639ce6dd86e87105271f43d43442a3aedf3cddf172", size = 76893, upload-time = "2026-01-26T02:43:52.754Z" }, + { url = "https://files.pythonhosted.org/packages/fe/cf/18ef143a81610136d3da8193da9d80bfe1cb548a1e2d1c775f26b23d024a/multidict-6.7.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:3fccb473e87eaa1382689053e4a4618e7ba7b9b9b8d6adf2027ee474597128cd", size = 45456, upload-time = "2026-01-26T02:43:53.893Z" }, + { url = "https://files.pythonhosted.org/packages/a9/65/1caac9d4cd32e8433908683446eebc953e82d22b03d10d41a5f0fefe991b/multidict-6.7.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:b0fa96985700739c4c7853a43c0b3e169360d6855780021bfc6d0f1ce7c123e7", size = 43872, upload-time = "2026-01-26T02:43:55.041Z" }, + { url = "https://files.pythonhosted.org/packages/cf/3b/d6bd75dc4f3ff7c73766e04e705b00ed6dbbaccf670d9e05a12b006f5a21/multidict-6.7.1-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:cb2a55f408c3043e42b40cc8eecd575afa27b7e0b956dfb190de0f8499a57a53", size = 251018, upload-time = "2026-01-26T02:43:56.198Z" }, + { url = "https://files.pythonhosted.org/packages/fd/80/c959c5933adedb9ac15152e4067c702a808ea183a8b64cf8f31af8ad3155/multidict-6.7.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:eb0ce7b2a32d09892b3dd6cc44877a0d02a33241fafca5f25c8b6b62374f8b75", size = 258883, upload-time = "2026-01-26T02:43:57.499Z" }, + { url = "https://files.pythonhosted.org/packages/86/85/7ed40adafea3d4f1c8b916e3b5cc3a8e07dfcdcb9cd72800f4ed3ca1b387/multidict-6.7.1-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:c3a32d23520ee37bf327d1e1a656fec76a2edd5c038bf43eddfa0572ec49c60b", size = 242413, upload-time = "2026-01-26T02:43:58.755Z" }, + { url = "https://files.pythonhosted.org/packages/d2/57/b8565ff533e48595503c785f8361ff9a4fde4d67de25c207cd0ba3befd03/multidict-6.7.1-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:9c90fed18bffc0189ba814749fdcc102b536e83a9f738a9003e569acd540a733", size = 268404, upload-time = "2026-01-26T02:44:00.216Z" }, + { url = "https://files.pythonhosted.org/packages/e0/50/9810c5c29350f7258180dfdcb2e52783a0632862eb334c4896ac717cebcb/multidict-6.7.1-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:da62917e6076f512daccfbbde27f46fed1c98fee202f0559adec8ee0de67f71a", size = 269456, upload-time = "2026-01-26T02:44:02.202Z" }, + { url = "https://files.pythonhosted.org/packages/f3/8d/5e5be3ced1d12966fefb5c4ea3b2a5b480afcea36406559442c6e31d4a48/multidict-6.7.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bfde23ef6ed9db7eaee6c37dcec08524cb43903c60b285b172b6c094711b3961", size = 256322, upload-time = "2026-01-26T02:44:03.56Z" }, + { url = "https://files.pythonhosted.org/packages/31/6e/d8a26d81ac166a5592782d208dd90dfdc0a7a218adaa52b45a672b46c122/multidict-6.7.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:3758692429e4e32f1ba0df23219cd0b4fc0a52f476726fff9337d1a57676a582", size = 253955, upload-time = "2026-01-26T02:44:04.845Z" }, + { url = "https://files.pythonhosted.org/packages/59/4c/7c672c8aad41534ba619bcd4ade7a0dc87ed6b8b5c06149b85d3dd03f0cd/multidict-6.7.1-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:398c1478926eca669f2fd6a5856b6de9c0acf23a2cb59a14c0ba5844fa38077e", size = 251254, upload-time = "2026-01-26T02:44:06.133Z" }, + { url = "https://files.pythonhosted.org/packages/7b/bd/84c24de512cbafbdbc39439f74e967f19570ce7924e3007174a29c348916/multidict-6.7.1-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:c102791b1c4f3ab36ce4101154549105a53dc828f016356b3e3bcae2e3a039d3", size = 252059, upload-time = "2026-01-26T02:44:07.518Z" }, + { url = "https://files.pythonhosted.org/packages/fa/ba/f5449385510825b73d01c2d4087bf6d2fccc20a2d42ac34df93191d3dd03/multidict-6.7.1-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:a088b62bd733e2ad12c50dad01b7d0166c30287c166e137433d3b410add807a6", size = 263588, upload-time = "2026-01-26T02:44:09.382Z" }, + { url = "https://files.pythonhosted.org/packages/d7/11/afc7c677f68f75c84a69fe37184f0f82fce13ce4b92f49f3db280b7e92b3/multidict-6.7.1-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:3d51ff4785d58d3f6c91bdbffcb5e1f7ddfda557727043aa20d20ec4f65e324a", size = 259642, upload-time = "2026-01-26T02:44:10.73Z" }, + { url = "https://files.pythonhosted.org/packages/2b/17/ebb9644da78c4ab36403739e0e6e0e30ebb135b9caf3440825001a0bddcb/multidict-6.7.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fc5907494fccf3e7d3f94f95c91d6336b092b5fc83811720fae5e2765890dfba", size = 251377, upload-time = "2026-01-26T02:44:12.042Z" }, + { url = "https://files.pythonhosted.org/packages/ca/a4/840f5b97339e27846c46307f2530a2805d9d537d8b8bd416af031cad7fa0/multidict-6.7.1-cp312-cp312-win32.whl", hash = "sha256:28ca5ce2fd9716631133d0e9a9b9a745ad7f60bac2bccafb56aa380fc0b6c511", size = 41887, upload-time = "2026-01-26T02:44:14.245Z" }, + { url = "https://files.pythonhosted.org/packages/80/31/0b2517913687895f5904325c2069d6a3b78f66cc641a86a2baf75a05dcbb/multidict-6.7.1-cp312-cp312-win_amd64.whl", hash = "sha256:fcee94dfbd638784645b066074b338bc9cc155d4b4bffa4adce1615c5a426c19", size = 46053, upload-time = "2026-01-26T02:44:15.371Z" }, + { url = "https://files.pythonhosted.org/packages/0c/5b/aba28e4ee4006ae4c7df8d327d31025d760ffa992ea23812a601d226e682/multidict-6.7.1-cp312-cp312-win_arm64.whl", hash = "sha256:ba0a9fb644d0c1a2194cf7ffb043bd852cea63a57f66fbd33959f7dae18517bf", size = 43307, upload-time = "2026-01-26T02:44:16.852Z" }, + { url = "https://files.pythonhosted.org/packages/f2/22/929c141d6c0dba87d3e1d38fbdf1ba8baba86b7776469f2bc2d3227a1e67/multidict-6.7.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2b41f5fed0ed563624f1c17630cb9941cf2309d4df00e494b551b5f3e3d67a23", size = 76174, upload-time = "2026-01-26T02:44:18.509Z" }, + { url = "https://files.pythonhosted.org/packages/c7/75/bc704ae15fee974f8fccd871305e254754167dce5f9e42d88a2def741a1d/multidict-6.7.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:84e61e3af5463c19b67ced91f6c634effb89ef8bfc5ca0267f954451ed4bb6a2", size = 45116, upload-time = "2026-01-26T02:44:19.745Z" }, + { url = "https://files.pythonhosted.org/packages/79/76/55cd7186f498ed080a18440c9013011eb548f77ae1b297206d030eb1180a/multidict-6.7.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:935434b9853c7c112eee7ac891bc4cb86455aa631269ae35442cb316790c1445", size = 43524, upload-time = "2026-01-26T02:44:21.571Z" }, + { url = "https://files.pythonhosted.org/packages/e9/3c/414842ef8d5a1628d68edee29ba0e5bcf235dbfb3ccd3ea303a7fe8c72ff/multidict-6.7.1-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:432feb25a1cb67fe82a9680b4d65fb542e4635cb3166cd9c01560651ad60f177", size = 249368, upload-time = "2026-01-26T02:44:22.803Z" }, + { url = "https://files.pythonhosted.org/packages/f6/32/befed7f74c458b4a525e60519fe8d87eef72bb1e99924fa2b0f9d97a221e/multidict-6.7.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e82d14e3c948952a1a85503817e038cba5905a3352de76b9a465075d072fba23", size = 256952, upload-time = "2026-01-26T02:44:24.306Z" }, + { url = "https://files.pythonhosted.org/packages/03/d6/c878a44ba877f366630c860fdf74bfb203c33778f12b6ac274936853c451/multidict-6.7.1-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:4cfb48c6ea66c83bcaaf7e4dfa7ec1b6bbcf751b7db85a328902796dfde4c060", size = 240317, upload-time = "2026-01-26T02:44:25.772Z" }, + { url = "https://files.pythonhosted.org/packages/68/49/57421b4d7ad2e9e60e25922b08ceb37e077b90444bde6ead629095327a6f/multidict-6.7.1-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1d540e51b7e8e170174555edecddbd5538105443754539193e3e1061864d444d", size = 267132, upload-time = "2026-01-26T02:44:27.648Z" }, + { url = "https://files.pythonhosted.org/packages/b7/fe/ec0edd52ddbcea2a2e89e174f0206444a61440b40f39704e64dc807a70bd/multidict-6.7.1-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:273d23f4b40f3dce4d6c8a821c741a86dec62cded82e1175ba3d99be128147ed", size = 268140, upload-time = "2026-01-26T02:44:29.588Z" }, + { url = "https://files.pythonhosted.org/packages/b0/73/6e1b01cbeb458807aa0831742232dbdd1fa92bfa33f52a3f176b4ff3dc11/multidict-6.7.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9d624335fd4fa1c08a53f8b4be7676ebde19cd092b3895c421045ca87895b429", size = 254277, upload-time = "2026-01-26T02:44:30.902Z" }, + { url = "https://files.pythonhosted.org/packages/6a/b2/5fb8c124d7561a4974c342bc8c778b471ebbeb3cc17df696f034a7e9afe7/multidict-6.7.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:12fad252f8b267cc75b66e8fc51b3079604e8d43a75428ffe193cd9e2195dfd6", size = 252291, upload-time = "2026-01-26T02:44:32.31Z" }, + { url = "https://files.pythonhosted.org/packages/5a/96/51d4e4e06bcce92577fcd488e22600bd38e4fd59c20cb49434d054903bd2/multidict-6.7.1-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:03ede2a6ffbe8ef936b92cb4529f27f42be7f56afcdab5ab739cd5f27fb1cbf9", size = 250156, upload-time = "2026-01-26T02:44:33.734Z" }, + { url = "https://files.pythonhosted.org/packages/db/6b/420e173eec5fba721a50e2a9f89eda89d9c98fded1124f8d5c675f7a0c0f/multidict-6.7.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:90efbcf47dbe33dcf643a1e400d67d59abeac5db07dc3f27d6bdeae497a2198c", size = 249742, upload-time = "2026-01-26T02:44:35.222Z" }, + { url = "https://files.pythonhosted.org/packages/44/a3/ec5b5bd98f306bc2aa297b8c6f11a46714a56b1e6ef5ebda50a4f5d7c5fb/multidict-6.7.1-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:5c4b9bfc148f5a91be9244d6264c53035c8a0dcd2f51f1c3c6e30e30ebaa1c84", size = 262221, upload-time = "2026-01-26T02:44:36.604Z" }, + { url = "https://files.pythonhosted.org/packages/cd/f7/e8c0d0da0cd1e28d10e624604e1a36bcc3353aaebdfdc3a43c72bc683a12/multidict-6.7.1-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:401c5a650f3add2472d1d288c26deebc540f99e2fb83e9525007a74cd2116f1d", size = 258664, upload-time = "2026-01-26T02:44:38.008Z" }, + { url = "https://files.pythonhosted.org/packages/52/da/151a44e8016dd33feed44f730bd856a66257c1ee7aed4f44b649fb7edeb3/multidict-6.7.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:97891f3b1b3ffbded884e2916cacf3c6fc87b66bb0dde46f7357404750559f33", size = 249490, upload-time = "2026-01-26T02:44:39.386Z" }, + { url = "https://files.pythonhosted.org/packages/87/af/a3b86bf9630b732897f6fc3f4c4714b90aa4361983ccbdcd6c0339b21b0c/multidict-6.7.1-cp313-cp313-win32.whl", hash = "sha256:e1c5988359516095535c4301af38d8a8838534158f649c05dd1050222321bcb3", size = 41695, upload-time = "2026-01-26T02:44:41.318Z" }, + { url = "https://files.pythonhosted.org/packages/b2/35/e994121b0e90e46134673422dd564623f93304614f5d11886b1b3e06f503/multidict-6.7.1-cp313-cp313-win_amd64.whl", hash = "sha256:960c83bf01a95b12b08fd54324a4eb1d5b52c88932b5cba5d6e712bb3ed12eb5", size = 45884, upload-time = "2026-01-26T02:44:42.488Z" }, + { url = "https://files.pythonhosted.org/packages/ca/61/42d3e5dbf661242a69c97ea363f2d7b46c567da8eadef8890022be6e2ab0/multidict-6.7.1-cp313-cp313-win_arm64.whl", hash = "sha256:563fe25c678aaba333d5399408f5ec3c383ca5b663e7f774dd179a520b8144df", size = 43122, upload-time = "2026-01-26T02:44:43.664Z" }, + { url = "https://files.pythonhosted.org/packages/6d/b3/e6b21c6c4f314bb956016b0b3ef2162590a529b84cb831c257519e7fde44/multidict-6.7.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:c76c4bec1538375dad9d452d246ca5368ad6e1c9039dadcf007ae59c70619ea1", size = 83175, upload-time = "2026-01-26T02:44:44.894Z" }, + { url = "https://files.pythonhosted.org/packages/fb/76/23ecd2abfe0957b234f6c960f4ade497f55f2c16aeb684d4ecdbf1c95791/multidict-6.7.1-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:57b46b24b5d5ebcc978da4ec23a819a9402b4228b8a90d9c656422b4bdd8a963", size = 48460, upload-time = "2026-01-26T02:44:46.106Z" }, + { url = "https://files.pythonhosted.org/packages/c4/57/a0ed92b23f3a042c36bc4227b72b97eca803f5f1801c1ab77c8a212d455e/multidict-6.7.1-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:e954b24433c768ce78ab7929e84ccf3422e46deb45a4dc9f93438f8217fa2d34", size = 46930, upload-time = "2026-01-26T02:44:47.278Z" }, + { url = "https://files.pythonhosted.org/packages/b5/66/02ec7ace29162e447f6382c495dc95826bf931d3818799bbef11e8f7df1a/multidict-6.7.1-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:3bd231490fa7217cc832528e1cd8752a96f0125ddd2b5749390f7c3ec8721b65", size = 242582, upload-time = "2026-01-26T02:44:48.604Z" }, + { url = "https://files.pythonhosted.org/packages/58/18/64f5a795e7677670e872673aca234162514696274597b3708b2c0d276cce/multidict-6.7.1-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:253282d70d67885a15c8a7716f3a73edf2d635793ceda8173b9ecc21f2fb8292", size = 250031, upload-time = "2026-01-26T02:44:50.544Z" }, + { url = "https://files.pythonhosted.org/packages/c8/ed/e192291dbbe51a8290c5686f482084d31bcd9d09af24f63358c3d42fd284/multidict-6.7.1-cp313-cp313t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:0b4c48648d7649c9335cf1927a8b87fa692de3dcb15faa676c6a6f1f1aabda43", size = 228596, upload-time = "2026-01-26T02:44:51.951Z" }, + { url = "https://files.pythonhosted.org/packages/1e/7e/3562a15a60cf747397e7f2180b0a11dc0c38d9175a650e75fa1b4d325e15/multidict-6.7.1-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:98bc624954ec4d2c7cb074b8eefc2b5d0ce7d482e410df446414355d158fe4ca", size = 257492, upload-time = "2026-01-26T02:44:53.902Z" }, + { url = "https://files.pythonhosted.org/packages/24/02/7d0f9eae92b5249bb50ac1595b295f10e263dd0078ebb55115c31e0eaccd/multidict-6.7.1-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:1b99af4d9eec0b49927b4402bcbb58dea89d3e0db8806a4086117019939ad3dd", size = 255899, upload-time = "2026-01-26T02:44:55.316Z" }, + { url = "https://files.pythonhosted.org/packages/00/e3/9b60ed9e23e64c73a5cde95269ef1330678e9c6e34dd4eb6b431b85b5a10/multidict-6.7.1-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6aac4f16b472d5b7dc6f66a0d49dd57b0e0902090be16594dc9ebfd3d17c47e7", size = 247970, upload-time = "2026-01-26T02:44:56.783Z" }, + { url = "https://files.pythonhosted.org/packages/3e/06/538e58a63ed5cfb0bd4517e346b91da32fde409d839720f664e9a4ae4f9d/multidict-6.7.1-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:21f830fe223215dffd51f538e78c172ed7c7f60c9b96a2bf05c4848ad49921c3", size = 245060, upload-time = "2026-01-26T02:44:58.195Z" }, + { url = "https://files.pythonhosted.org/packages/b2/2f/d743a3045a97c895d401e9bd29aaa09b94f5cbdf1bd561609e5a6c431c70/multidict-6.7.1-cp313-cp313t-musllinux_1_2_armv7l.whl", hash = "sha256:f5dd81c45b05518b9aa4da4aa74e1c93d715efa234fd3e8a179df611cc85e5f4", size = 235888, upload-time = "2026-01-26T02:44:59.57Z" }, + { url = "https://files.pythonhosted.org/packages/38/83/5a325cac191ab28b63c52f14f1131f3b0a55ba3b9aa65a6d0bf2a9b921a0/multidict-6.7.1-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:eb304767bca2bb92fb9c5bd33cedc95baee5bb5f6c88e63706533a1c06ad08c8", size = 243554, upload-time = "2026-01-26T02:45:01.054Z" }, + { url = "https://files.pythonhosted.org/packages/20/1f/9d2327086bd15da2725ef6aae624208e2ef828ed99892b17f60c344e57ed/multidict-6.7.1-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:c9035dde0f916702850ef66460bc4239d89d08df4d02023a5926e7446724212c", size = 252341, upload-time = "2026-01-26T02:45:02.484Z" }, + { url = "https://files.pythonhosted.org/packages/e8/2c/2a1aa0280cf579d0f6eed8ee5211c4f1730bd7e06c636ba2ee6aafda302e/multidict-6.7.1-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:af959b9beeb66c822380f222f0e0a1889331597e81f1ded7f374f3ecb0fd6c52", size = 246391, upload-time = "2026-01-26T02:45:03.862Z" }, + { url = "https://files.pythonhosted.org/packages/e5/03/7ca022ffc36c5a3f6e03b179a5ceb829be9da5783e6fe395f347c0794680/multidict-6.7.1-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:41f2952231456154ee479651491e94118229844dd7226541788be783be2b5108", size = 243422, upload-time = "2026-01-26T02:45:05.296Z" }, + { url = "https://files.pythonhosted.org/packages/dc/1d/b31650eab6c5778aceed46ba735bd97f7c7d2f54b319fa916c0f96e7805b/multidict-6.7.1-cp313-cp313t-win32.whl", hash = "sha256:df9f19c28adcb40b6aae30bbaa1478c389efd50c28d541d76760199fc1037c32", size = 47770, upload-time = "2026-01-26T02:45:06.754Z" }, + { url = "https://files.pythonhosted.org/packages/ac/5b/2d2d1d522e51285bd61b1e20df8f47ae1a9d80839db0b24ea783b3832832/multidict-6.7.1-cp313-cp313t-win_amd64.whl", hash = "sha256:d54ecf9f301853f2c5e802da559604b3e95bb7a3b01a9c295c6ee591b9882de8", size = 53109, upload-time = "2026-01-26T02:45:08.044Z" }, + { url = "https://files.pythonhosted.org/packages/3d/a3/cc409ba012c83ca024a308516703cf339bdc4b696195644a7215a5164a24/multidict-6.7.1-cp313-cp313t-win_arm64.whl", hash = "sha256:5a37ca18e360377cfda1d62f5f382ff41f2b8c4ccb329ed974cc2e1643440118", size = 45573, upload-time = "2026-01-26T02:45:09.349Z" }, + { url = "https://files.pythonhosted.org/packages/91/cc/db74228a8be41884a567e88a62fd589a913708fcf180d029898c17a9a371/multidict-6.7.1-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:8f333ec9c5eb1b7105e3b84b53141e66ca05a19a605368c55450b6ba208cb9ee", size = 75190, upload-time = "2026-01-26T02:45:10.651Z" }, + { url = "https://files.pythonhosted.org/packages/d5/22/492f2246bb5b534abd44804292e81eeaf835388901f0c574bac4eeec73c5/multidict-6.7.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:a407f13c188f804c759fc6a9f88286a565c242a76b27626594c133b82883b5c2", size = 44486, upload-time = "2026-01-26T02:45:11.938Z" }, + { url = "https://files.pythonhosted.org/packages/f1/4f/733c48f270565d78b4544f2baddc2fb2a245e5a8640254b12c36ac7ac68e/multidict-6.7.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:0e161ddf326db5577c3a4cc2d8648f81456e8a20d40415541587a71620d7a7d1", size = 43219, upload-time = "2026-01-26T02:45:14.346Z" }, + { url = "https://files.pythonhosted.org/packages/24/bb/2c0c2287963f4259c85e8bcbba9182ced8d7fca65c780c38e99e61629d11/multidict-6.7.1-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:1e3a8bb24342a8201d178c3b4984c26ba81a577c80d4d525727427460a50c22d", size = 245132, upload-time = "2026-01-26T02:45:15.712Z" }, + { url = "https://files.pythonhosted.org/packages/a7/f9/44d4b3064c65079d2467888794dea218d1601898ac50222ab8a9a8094460/multidict-6.7.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:97231140a50f5d447d3164f994b86a0bed7cd016e2682f8650d6a9158e14fd31", size = 252420, upload-time = "2026-01-26T02:45:17.293Z" }, + { url = "https://files.pythonhosted.org/packages/8b/13/78f7275e73fa17b24c9a51b0bd9d73ba64bb32d0ed51b02a746eb876abe7/multidict-6.7.1-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:6b10359683bd8806a200fd2909e7c8ca3a7b24ec1d8132e483d58e791d881048", size = 233510, upload-time = "2026-01-26T02:45:19.356Z" }, + { url = "https://files.pythonhosted.org/packages/4b/25/8167187f62ae3cbd52da7893f58cb036b47ea3fb67138787c76800158982/multidict-6.7.1-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:283ddac99f7ac25a4acadbf004cb5ae34480bbeb063520f70ce397b281859362", size = 264094, upload-time = "2026-01-26T02:45:20.834Z" }, + { url = "https://files.pythonhosted.org/packages/a1/e7/69a3a83b7b030cf283fb06ce074a05a02322359783424d7edf0f15fe5022/multidict-6.7.1-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:538cec1e18c067d0e6103aa9a74f9e832904c957adc260e61cd9d8cf0c3b3d37", size = 260786, upload-time = "2026-01-26T02:45:22.818Z" }, + { url = "https://files.pythonhosted.org/packages/fe/3b/8ec5074bcfc450fe84273713b4b0a0dd47c0249358f5d82eb8104ffe2520/multidict-6.7.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7eee46ccb30ff48a1e35bb818cc90846c6be2b68240e42a78599166722cea709", size = 248483, upload-time = "2026-01-26T02:45:24.368Z" }, + { url = "https://files.pythonhosted.org/packages/48/5a/d5a99e3acbca0e29c5d9cba8f92ceb15dce78bab963b308ae692981e3a5d/multidict-6.7.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:fa263a02f4f2dd2d11a7b1bb4362aa7cb1049f84a9235d31adf63f30143469a0", size = 248403, upload-time = "2026-01-26T02:45:25.982Z" }, + { url = "https://files.pythonhosted.org/packages/35/48/e58cd31f6c7d5102f2a4bf89f96b9cf7e00b6c6f3d04ecc44417c00a5a3c/multidict-6.7.1-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:2e1425e2f99ec5bd36c15a01b690a1a2456209c5deed58f95469ffb46039ccbb", size = 240315, upload-time = "2026-01-26T02:45:27.487Z" }, + { url = "https://files.pythonhosted.org/packages/94/33/1cd210229559cb90b6786c30676bb0c58249ff42f942765f88793b41fdce/multidict-6.7.1-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:497394b3239fc6f0e13a78a3e1b61296e72bf1c5f94b4c4eb80b265c37a131cd", size = 245528, upload-time = "2026-01-26T02:45:28.991Z" }, + { url = "https://files.pythonhosted.org/packages/64/f2/6e1107d226278c876c783056b7db43d800bb64c6131cec9c8dfb6903698e/multidict-6.7.1-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:233b398c29d3f1b9676b4b6f75c518a06fcb2ea0b925119fb2c1bc35c05e1601", size = 258784, upload-time = "2026-01-26T02:45:30.503Z" }, + { url = "https://files.pythonhosted.org/packages/4d/c1/11f664f14d525e4a1b5327a82d4de61a1db604ab34c6603bb3c2cc63ad34/multidict-6.7.1-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:93b1818e4a6e0930454f0f2af7dfce69307ca03cdcfb3739bf4d91241967b6c1", size = 251980, upload-time = "2026-01-26T02:45:32.603Z" }, + { url = "https://files.pythonhosted.org/packages/e1/9f/75a9ac888121d0c5bbd4ecf4eead45668b1766f6baabfb3b7f66a410e231/multidict-6.7.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:f33dc2a3abe9249ea5d8360f969ec7f4142e7ac45ee7014d8f8d5acddf178b7b", size = 243602, upload-time = "2026-01-26T02:45:34.043Z" }, + { url = "https://files.pythonhosted.org/packages/9a/e7/50bf7b004cc8525d80dbbbedfdc7aed3e4c323810890be4413e589074032/multidict-6.7.1-cp314-cp314-win32.whl", hash = "sha256:3ab8b9d8b75aef9df299595d5388b14530839f6422333357af1339443cff777d", size = 40930, upload-time = "2026-01-26T02:45:36.278Z" }, + { url = "https://files.pythonhosted.org/packages/e0/bf/52f25716bbe93745595800f36fb17b73711f14da59ed0bb2eba141bc9f0f/multidict-6.7.1-cp314-cp314-win_amd64.whl", hash = "sha256:5e01429a929600e7dab7b166062d9bb54a5eed752384c7384c968c2afab8f50f", size = 45074, upload-time = "2026-01-26T02:45:37.546Z" }, + { url = "https://files.pythonhosted.org/packages/97/ab/22803b03285fa3a525f48217963da3a65ae40f6a1b6f6cf2768879e208f9/multidict-6.7.1-cp314-cp314-win_arm64.whl", hash = "sha256:4885cb0e817aef5d00a2e8451d4665c1808378dc27c2705f1bf4ef8505c0d2e5", size = 42471, upload-time = "2026-01-26T02:45:38.889Z" }, + { url = "https://files.pythonhosted.org/packages/e0/6d/f9293baa6146ba9507e360ea0292b6422b016907c393e2f63fc40ab7b7b5/multidict-6.7.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:0458c978acd8e6ea53c81eefaddbbee9c6c5e591f41b3f5e8e194780fe026581", size = 82401, upload-time = "2026-01-26T02:45:40.254Z" }, + { url = "https://files.pythonhosted.org/packages/7a/68/53b5494738d83558d87c3c71a486504d8373421c3e0dbb6d0db48ad42ee0/multidict-6.7.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:c0abd12629b0af3cf590982c0b413b1e7395cd4ec026f30986818ab95bfaa94a", size = 48143, upload-time = "2026-01-26T02:45:41.635Z" }, + { url = "https://files.pythonhosted.org/packages/37/e8/5284c53310dcdc99ce5d66563f6e5773531a9b9fe9ec7a615e9bc306b05f/multidict-6.7.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:14525a5f61d7d0c94b368a42cff4c9a4e7ba2d52e2672a7b23d84dc86fb02b0c", size = 46507, upload-time = "2026-01-26T02:45:42.99Z" }, + { url = "https://files.pythonhosted.org/packages/e4/fc/6800d0e5b3875568b4083ecf5f310dcf91d86d52573160834fb4bfcf5e4f/multidict-6.7.1-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:17307b22c217b4cf05033dabefe68255a534d637c6c9b0cc8382718f87be4262", size = 239358, upload-time = "2026-01-26T02:45:44.376Z" }, + { url = "https://files.pythonhosted.org/packages/41/75/4ad0973179361cdf3a113905e6e088173198349131be2b390f9fa4da5fc6/multidict-6.7.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7a7e590ff876a3eaf1c02a4dfe0724b6e69a9e9de6d8f556816f29c496046e59", size = 246884, upload-time = "2026-01-26T02:45:47.167Z" }, + { url = "https://files.pythonhosted.org/packages/c3/9c/095bb28b5da139bd41fb9a5d5caff412584f377914bd8787c2aa98717130/multidict-6.7.1-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:5fa6a95dfee63893d80a34758cd0e0c118a30b8dcb46372bf75106c591b77889", size = 225878, upload-time = "2026-01-26T02:45:48.698Z" }, + { url = "https://files.pythonhosted.org/packages/07/d0/c0a72000243756e8f5a277b6b514fa005f2c73d481b7d9e47cd4568aa2e4/multidict-6.7.1-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a0543217a6a017692aa6ae5cc39adb75e587af0f3a82288b1492eb73dd6cc2a4", size = 253542, upload-time = "2026-01-26T02:45:50.164Z" }, + { url = "https://files.pythonhosted.org/packages/c0/6b/f69da15289e384ecf2a68837ec8b5ad8c33e973aa18b266f50fe55f24b8c/multidict-6.7.1-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f99fe611c312b3c1c0ace793f92464d8cd263cc3b26b5721950d977b006b6c4d", size = 252403, upload-time = "2026-01-26T02:45:51.779Z" }, + { url = "https://files.pythonhosted.org/packages/a2/76/b9669547afa5a1a25cd93eaca91c0da1c095b06b6d2d8ec25b713588d3a1/multidict-6.7.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9004d8386d133b7e6135679424c91b0b854d2d164af6ea3f289f8f2761064609", size = 244889, upload-time = "2026-01-26T02:45:53.27Z" }, + { url = "https://files.pythonhosted.org/packages/7e/a9/a50d2669e506dad33cfc45b5d574a205587b7b8a5f426f2fbb2e90882588/multidict-6.7.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e628ef0e6859ffd8273c69412a2465c4be4a9517d07261b33334b5ec6f3c7489", size = 241982, upload-time = "2026-01-26T02:45:54.919Z" }, + { url = "https://files.pythonhosted.org/packages/c5/bb/1609558ad8b456b4827d3c5a5b775c93b87878fd3117ed3db3423dfbce1b/multidict-6.7.1-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:841189848ba629c3552035a6a7f5bf3b02eb304e9fea7492ca220a8eda6b0e5c", size = 232415, upload-time = "2026-01-26T02:45:56.981Z" }, + { url = "https://files.pythonhosted.org/packages/d8/59/6f61039d2aa9261871e03ab9dc058a550d240f25859b05b67fd70f80d4b3/multidict-6.7.1-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:ce1bbd7d780bb5a0da032e095c951f7014d6b0a205f8318308140f1a6aba159e", size = 240337, upload-time = "2026-01-26T02:45:58.698Z" }, + { url = "https://files.pythonhosted.org/packages/a1/29/fdc6a43c203890dc2ae9249971ecd0c41deaedfe00d25cb6564b2edd99eb/multidict-6.7.1-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:b26684587228afed0d50cf804cc71062cc9c1cdf55051c4c6345d372947b268c", size = 248788, upload-time = "2026-01-26T02:46:00.862Z" }, + { url = "https://files.pythonhosted.org/packages/a9/14/a153a06101323e4cf086ecee3faadba52ff71633d471f9685c42e3736163/multidict-6.7.1-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:9f9af11306994335398293f9958071019e3ab95e9a707dc1383a35613f6abcb9", size = 242842, upload-time = "2026-01-26T02:46:02.824Z" }, + { url = "https://files.pythonhosted.org/packages/41/5f/604ae839e64a4a6efc80db94465348d3b328ee955e37acb24badbcd24d83/multidict-6.7.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:b4938326284c4f1224178a560987b6cf8b4d38458b113d9b8c1db1a836e640a2", size = 240237, upload-time = "2026-01-26T02:46:05.898Z" }, + { url = "https://files.pythonhosted.org/packages/5f/60/c3a5187bf66f6fb546ff4ab8fb5a077cbdd832d7b1908d4365c7f74a1917/multidict-6.7.1-cp314-cp314t-win32.whl", hash = "sha256:98655c737850c064a65e006a3df7c997cd3b220be4ec8fe26215760b9697d4d7", size = 48008, upload-time = "2026-01-26T02:46:07.468Z" }, + { url = "https://files.pythonhosted.org/packages/0c/f7/addf1087b860ac60e6f382240f64fb99f8bfb532bb06f7c542b83c29ca61/multidict-6.7.1-cp314-cp314t-win_amd64.whl", hash = "sha256:497bde6223c212ba11d462853cfa4f0ae6ef97465033e7dc9940cdb3ab5b48e5", size = 53542, upload-time = "2026-01-26T02:46:08.809Z" }, + { url = "https://files.pythonhosted.org/packages/4c/81/4629d0aa32302ef7b2ec65c75a728cc5ff4fa410c50096174c1632e70b3e/multidict-6.7.1-cp314-cp314t-win_arm64.whl", hash = "sha256:2bbd113e0d4af5db41d5ebfe9ccaff89de2120578164f86a5d17d5a576d1e5b2", size = 44719, upload-time = "2026-01-26T02:46:11.146Z" }, + { url = "https://files.pythonhosted.org/packages/81/08/7036c080d7117f28a4af526d794aab6a84463126db031b007717c1a6676e/multidict-6.7.1-py3-none-any.whl", hash = "sha256:55d97cc6dae627efa6a6e548885712d4864b81110ac76fa4e534c03819fa4a56", size = 12319, upload-time = "2026-01-26T02:46:44.004Z" }, +] + +[[package]] +name = "numpy" +version = "2.4.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d7/9f/b8cef5bffa569759033adda9481211426f12f53299629b410340795c2514/numpy-2.4.4.tar.gz", hash = "sha256:2d390634c5182175533585cc89f3608a4682ccb173cc9bb940b2881c8d6f8fa0", size = 20731587, upload-time = "2026-03-29T13:22:01.298Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/28/05/32396bec30fb2263770ee910142f49c1476d08e8ad41abf8403806b520ce/numpy-2.4.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:15716cfef24d3a9762e3acdf87e27f58dc823d1348f765bbea6bef8c639bfa1b", size = 16689272, upload-time = "2026-03-29T13:18:49.223Z" }, + { url = "https://files.pythonhosted.org/packages/c5/f3/a983d28637bfcd763a9c7aafdb6d5c0ebf3d487d1e1459ffdb57e2f01117/numpy-2.4.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:23cbfd4c17357c81021f21540da84ee282b9c8fba38a03b7b9d09ba6b951421e", size = 14699573, upload-time = "2026-03-29T13:18:52.629Z" }, + { url = "https://files.pythonhosted.org/packages/9b/fd/e5ecca1e78c05106d98028114f5c00d3eddb41207686b2b7de3e477b0e22/numpy-2.4.4-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:8b3b60bb7cba2c8c81837661c488637eee696f59a877788a396d33150c35d842", size = 5204782, upload-time = "2026-03-29T13:18:55.579Z" }, + { url = "https://files.pythonhosted.org/packages/de/2f/702a4594413c1a8632092beae8aba00f1d67947389369b3777aed783fdca/numpy-2.4.4-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:e4a010c27ff6f210ff4c6ef34394cd61470d01014439b192ec22552ee867f2a8", size = 6552038, upload-time = "2026-03-29T13:18:57.769Z" }, + { url = "https://files.pythonhosted.org/packages/7f/37/eed308a8f56cba4d1fdf467a4fc67ef4ff4bf1c888f5fc980481890104b1/numpy-2.4.4-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f9e75681b59ddaa5e659898085ae0eaea229d054f2ac0c7e563a62205a700121", size = 15670666, upload-time = "2026-03-29T13:19:00.341Z" }, + { url = "https://files.pythonhosted.org/packages/0a/0d/0e3ecece05b7a7e87ab9fb587855548da437a061326fff64a223b6dcb78a/numpy-2.4.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:81f4a14bee47aec54f883e0cad2d73986640c1590eb9bfaaba7ad17394481e6e", size = 16645480, upload-time = "2026-03-29T13:19:03.63Z" }, + { url = "https://files.pythonhosted.org/packages/34/49/f2312c154b82a286758ee2f1743336d50651f8b5195db18cdb63675ff649/numpy-2.4.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:62d6b0f03b694173f9fcb1fb317f7222fd0b0b103e784c6549f5e53a27718c44", size = 17020036, upload-time = "2026-03-29T13:19:07.428Z" }, + { url = "https://files.pythonhosted.org/packages/7b/e9/736d17bd77f1b0ec4f9901aaec129c00d59f5d84d5e79bba540ef12c2330/numpy-2.4.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fbc356aae7adf9e6336d336b9c8111d390a05df88f1805573ebb0807bd06fd1d", size = 18368643, upload-time = "2026-03-29T13:19:10.775Z" }, + { url = "https://files.pythonhosted.org/packages/63/f6/d417977c5f519b17c8a5c3bc9e8304b0908b0e21136fe43bf628a1343914/numpy-2.4.4-cp312-cp312-win32.whl", hash = "sha256:0d35aea54ad1d420c812bfa0385c71cd7cc5bcf7c65fed95fc2cd02fe8c79827", size = 5961117, upload-time = "2026-03-29T13:19:13.464Z" }, + { url = "https://files.pythonhosted.org/packages/2d/5b/e1deebf88ff431b01b7406ca3583ab2bbb90972bbe1c568732e49c844f7e/numpy-2.4.4-cp312-cp312-win_amd64.whl", hash = "sha256:b5f0362dc928a6ecd9db58868fca5e48485205e3855957bdedea308f8672ea4a", size = 12320584, upload-time = "2026-03-29T13:19:16.155Z" }, + { url = "https://files.pythonhosted.org/packages/58/89/e4e856ac82a68c3ed64486a544977d0e7bdd18b8da75b78a577ca31c4395/numpy-2.4.4-cp312-cp312-win_arm64.whl", hash = "sha256:846300f379b5b12cc769334464656bc882e0735d27d9726568bc932fdc49d5ec", size = 10221450, upload-time = "2026-03-29T13:19:18.994Z" }, + { url = "https://files.pythonhosted.org/packages/14/1d/d0a583ce4fefcc3308806a749a536c201ed6b5ad6e1322e227ee4848979d/numpy-2.4.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:08f2e31ed5e6f04b118e49821397f12767934cfdd12a1ce86a058f91e004ee50", size = 16684933, upload-time = "2026-03-29T13:19:22.47Z" }, + { url = "https://files.pythonhosted.org/packages/c1/62/2b7a48fbb745d344742c0277f01286dead15f3f68e4f359fbfcf7b48f70f/numpy-2.4.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e823b8b6edc81e747526f70f71a9c0a07ac4e7ad13020aa736bb7c9d67196115", size = 14694532, upload-time = "2026-03-29T13:19:25.581Z" }, + { url = "https://files.pythonhosted.org/packages/e5/87/499737bfba066b4a3bebff24a8f1c5b2dee410b209bc6668c9be692580f0/numpy-2.4.4-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:4a19d9dba1a76618dd86b164d608566f393f8ec6ac7c44f0cc879011c45e65af", size = 5199661, upload-time = "2026-03-29T13:19:28.31Z" }, + { url = "https://files.pythonhosted.org/packages/cd/da/464d551604320d1491bc345efed99b4b7034143a85787aab78d5691d5a0e/numpy-2.4.4-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:d2a8490669bfe99a233298348acc2d824d496dee0e66e31b66a6022c2ad74a5c", size = 6547539, upload-time = "2026-03-29T13:19:30.97Z" }, + { url = "https://files.pythonhosted.org/packages/7d/90/8d23e3b0dafd024bf31bdec225b3bb5c2dbfa6912f8a53b8659f21216cbf/numpy-2.4.4-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:45dbed2ab436a9e826e302fcdcbe9133f9b0006e5af7168afb8963a6520da103", size = 15668806, upload-time = "2026-03-29T13:19:33.887Z" }, + { url = "https://files.pythonhosted.org/packages/d1/73/a9d864e42a01896bb5974475438f16086be9ba1f0d19d0bb7a07427c4a8b/numpy-2.4.4-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c901b15172510173f5cb310eae652908340f8dede90fff9e3bf6c0d8dfd92f83", size = 16632682, upload-time = "2026-03-29T13:19:37.336Z" }, + { url = "https://files.pythonhosted.org/packages/34/fb/14570d65c3bde4e202a031210475ae9cde9b7686a2e7dc97ee67d2833b35/numpy-2.4.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:99d838547ace2c4aace6c4f76e879ddfe02bb58a80c1549928477862b7a6d6ed", size = 17019810, upload-time = "2026-03-29T13:19:40.963Z" }, + { url = "https://files.pythonhosted.org/packages/8a/77/2ba9d87081fd41f6d640c83f26fb7351e536b7ce6dd9061b6af5904e8e46/numpy-2.4.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:0aec54fd785890ecca25a6003fd9a5aed47ad607bbac5cd64f836ad8666f4959", size = 18357394, upload-time = "2026-03-29T13:19:44.859Z" }, + { url = "https://files.pythonhosted.org/packages/a2/23/52666c9a41708b0853fa3b1a12c90da38c507a3074883823126d4e9d5b30/numpy-2.4.4-cp313-cp313-win32.whl", hash = "sha256:07077278157d02f65c43b1b26a3886bce886f95d20aabd11f87932750dfb14ed", size = 5959556, upload-time = "2026-03-29T13:19:47.661Z" }, + { url = "https://files.pythonhosted.org/packages/57/fb/48649b4971cde70d817cf97a2a2fdc0b4d8308569f1dd2f2611959d2e0cf/numpy-2.4.4-cp313-cp313-win_amd64.whl", hash = "sha256:5c70f1cc1c4efbe316a572e2d8b9b9cc44e89b95f79ca3331553fbb63716e2bf", size = 12317311, upload-time = "2026-03-29T13:19:50.67Z" }, + { url = "https://files.pythonhosted.org/packages/ba/d8/11490cddd564eb4de97b4579ef6bfe6a736cc07e94c1598590ae25415e01/numpy-2.4.4-cp313-cp313-win_arm64.whl", hash = "sha256:ef4059d6e5152fa1a39f888e344c73fdc926e1b2dd58c771d67b0acfbf2aa67d", size = 10222060, upload-time = "2026-03-29T13:19:54.229Z" }, + { url = "https://files.pythonhosted.org/packages/99/5d/dab4339177a905aad3e2221c915b35202f1ec30d750dd2e5e9d9a72b804b/numpy-2.4.4-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:4bbc7f303d125971f60ec0aaad5e12c62d0d2c925f0ab1273debd0e4ba37aba5", size = 14822302, upload-time = "2026-03-29T13:19:57.585Z" }, + { url = "https://files.pythonhosted.org/packages/eb/e4/0564a65e7d3d97562ed6f9b0fd0fb0a6f559ee444092f105938b50043876/numpy-2.4.4-cp313-cp313t-macosx_14_0_arm64.whl", hash = "sha256:4d6d57903571f86180eb98f8f0c839fa9ebbfb031356d87f1361be91e433f5b7", size = 5327407, upload-time = "2026-03-29T13:20:00.601Z" }, + { url = "https://files.pythonhosted.org/packages/29/8d/35a3a6ce5ad371afa58b4700f1c820f8f279948cca32524e0a695b0ded83/numpy-2.4.4-cp313-cp313t-macosx_14_0_x86_64.whl", hash = "sha256:4636de7fd195197b7535f231b5de9e4b36d2c440b6e566d2e4e4746e6af0ca93", size = 6647631, upload-time = "2026-03-29T13:20:02.855Z" }, + { url = "https://files.pythonhosted.org/packages/f4/da/477731acbd5a58a946c736edfdabb2ac5b34c3d08d1ba1a7b437fa0884df/numpy-2.4.4-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ad2e2ef14e0b04e544ea2fa0a36463f847f113d314aa02e5b402fdf910ef309e", size = 15727691, upload-time = "2026-03-29T13:20:06.004Z" }, + { url = "https://files.pythonhosted.org/packages/e6/db/338535d9b152beabeb511579598418ba0212ce77cf9718edd70262cc4370/numpy-2.4.4-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5a285b3b96f951841799528cd1f4f01cd70e7e0204b4abebac9463eecfcf2a40", size = 16681241, upload-time = "2026-03-29T13:20:09.417Z" }, + { url = "https://files.pythonhosted.org/packages/e2/a9/ad248e8f58beb7a0219b413c9c7d8151c5d285f7f946c3e26695bdbbe2df/numpy-2.4.4-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:f8474c4241bc18b750be2abea9d7a9ec84f46ef861dbacf86a4f6e043401f79e", size = 17085767, upload-time = "2026-03-29T13:20:13.126Z" }, + { url = "https://files.pythonhosted.org/packages/b5/1a/3b88ccd3694681356f70da841630e4725a7264d6a885c8d442a697e1146b/numpy-2.4.4-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:4e874c976154687c1f71715b034739b45c7711bec81db01914770373d125e392", size = 18403169, upload-time = "2026-03-29T13:20:17.096Z" }, + { url = "https://files.pythonhosted.org/packages/c2/c9/fcfd5d0639222c6eac7f304829b04892ef51c96a75d479214d77e3ce6e33/numpy-2.4.4-cp313-cp313t-win32.whl", hash = "sha256:9c585a1790d5436a5374bac930dad6ed244c046ed91b2b2a3634eb2971d21008", size = 6083477, upload-time = "2026-03-29T13:20:20.195Z" }, + { url = "https://files.pythonhosted.org/packages/d5/e3/3938a61d1c538aaec8ed6fd6323f57b0c2d2d2219512434c5c878db76553/numpy-2.4.4-cp313-cp313t-win_amd64.whl", hash = "sha256:93e15038125dc1e5345d9b5b68aa7f996ec33b98118d18c6ca0d0b7d6198b7e8", size = 12457487, upload-time = "2026-03-29T13:20:22.946Z" }, + { url = "https://files.pythonhosted.org/packages/97/6a/7e345032cc60501721ef94e0e30b60f6b0bd601f9174ebd36389a2b86d40/numpy-2.4.4-cp313-cp313t-win_arm64.whl", hash = "sha256:0dfd3f9d3adbe2920b68b5cd3d51444e13a10792ec7154cd0a2f6e74d4ab3233", size = 10292002, upload-time = "2026-03-29T13:20:25.909Z" }, + { url = "https://files.pythonhosted.org/packages/6e/06/c54062f85f673dd5c04cbe2f14c3acb8c8b95e3384869bb8cc9bff8cb9df/numpy-2.4.4-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:f169b9a863d34f5d11b8698ead99febeaa17a13ca044961aa8e2662a6c7766a0", size = 16684353, upload-time = "2026-03-29T13:20:29.504Z" }, + { url = "https://files.pythonhosted.org/packages/4c/39/8a320264a84404c74cc7e79715de85d6130fa07a0898f67fb5cd5bd79908/numpy-2.4.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:2483e4584a1cb3092da4470b38866634bafb223cbcd551ee047633fd2584599a", size = 14704914, upload-time = "2026-03-29T13:20:33.547Z" }, + { url = "https://files.pythonhosted.org/packages/91/fb/287076b2614e1d1044235f50f03748f31fa287e3dbe6abeb35cdfa351eca/numpy-2.4.4-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:2d19e6e2095506d1736b7d80595e0f252d76b89f5e715c35e06e937679ea7d7a", size = 5210005, upload-time = "2026-03-29T13:20:36.45Z" }, + { url = "https://files.pythonhosted.org/packages/63/eb/fcc338595309910de6ecabfcef2419a9ce24399680bfb149421fa2df1280/numpy-2.4.4-cp314-cp314-macosx_14_0_x86_64.whl", hash = "sha256:6a246d5914aa1c820c9443ddcee9c02bec3e203b0c080349533fae17727dfd1b", size = 6544974, upload-time = "2026-03-29T13:20:39.014Z" }, + { url = "https://files.pythonhosted.org/packages/44/5d/e7e9044032a716cdfaa3fba27a8e874bf1c5f1912a1ddd4ed071bf8a14a6/numpy-2.4.4-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:989824e9faf85f96ec9c7761cd8d29c531ad857bfa1daa930cba85baaecf1a9a", size = 15684591, upload-time = "2026-03-29T13:20:42.146Z" }, + { url = "https://files.pythonhosted.org/packages/98/7c/21252050676612625449b4807d6b695b9ce8a7c9e1c197ee6216c8a65c7c/numpy-2.4.4-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:27a8d92cd10f1382a67d7cf4db7ce18341b66438bdd9f691d7b0e48d104c2a9d", size = 16637700, upload-time = "2026-03-29T13:20:46.204Z" }, + { url = "https://files.pythonhosted.org/packages/b1/29/56d2bbef9465db24ef25393383d761a1af4f446a1df9b8cded4fe3a5a5d7/numpy-2.4.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:e44319a2953c738205bf3354537979eaa3998ed673395b964c1176083dd46252", size = 17035781, upload-time = "2026-03-29T13:20:50.242Z" }, + { url = "https://files.pythonhosted.org/packages/e3/2b/a35a6d7589d21f44cea7d0a98de5ddcbb3d421b2622a5c96b1edf18707c3/numpy-2.4.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:e892aff75639bbef0d2a2cfd55535510df26ff92f63c92cd84ef8d4ba5a5557f", size = 18362959, upload-time = "2026-03-29T13:20:54.019Z" }, + { url = "https://files.pythonhosted.org/packages/64/c9/d52ec581f2390e0f5f85cbfd80fb83d965fc15e9f0e1aec2195faa142cde/numpy-2.4.4-cp314-cp314-win32.whl", hash = "sha256:1378871da56ca8943c2ba674530924bb8ca40cd228358a3b5f302ad60cf875fc", size = 6008768, upload-time = "2026-03-29T13:20:56.912Z" }, + { url = "https://files.pythonhosted.org/packages/fa/22/4cc31a62a6c7b74a8730e31a4274c5dc80e005751e277a2ce38e675e4923/numpy-2.4.4-cp314-cp314-win_amd64.whl", hash = "sha256:715d1c092715954784bc79e1174fc2a90093dc4dc84ea15eb14dad8abdcdeb74", size = 12449181, upload-time = "2026-03-29T13:20:59.548Z" }, + { url = "https://files.pythonhosted.org/packages/70/2e/14cda6f4d8e396c612d1bf97f22958e92148801d7e4f110cabebdc0eef4b/numpy-2.4.4-cp314-cp314-win_arm64.whl", hash = "sha256:2c194dd721e54ecad9ad387c1d35e63dce5c4450c6dc7dd5611283dda239aabb", size = 10496035, upload-time = "2026-03-29T13:21:02.524Z" }, + { url = "https://files.pythonhosted.org/packages/b1/e8/8fed8c8d848d7ecea092dc3469643f9d10bc3a134a815a3b033da1d2039b/numpy-2.4.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:2aa0613a5177c264ff5921051a5719d20095ea586ca88cc802c5c218d1c67d3e", size = 14824958, upload-time = "2026-03-29T13:21:05.671Z" }, + { url = "https://files.pythonhosted.org/packages/05/1a/d8007a5138c179c2bf33ef44503e83d70434d2642877ee8fbb230e7c0548/numpy-2.4.4-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:42c16925aa5a02362f986765f9ebabf20de75cdefdca827d14315c568dcab113", size = 5330020, upload-time = "2026-03-29T13:21:08.635Z" }, + { url = "https://files.pythonhosted.org/packages/99/64/ffb99ac6ae93faf117bcbd5c7ba48a7f45364a33e8e458545d3633615dda/numpy-2.4.4-cp314-cp314t-macosx_14_0_x86_64.whl", hash = "sha256:874f200b2a981c647340f841730fc3a2b54c9d940566a3c4149099591e2c4c3d", size = 6650758, upload-time = "2026-03-29T13:21:10.949Z" }, + { url = "https://files.pythonhosted.org/packages/6e/6e/795cc078b78a384052e73b2f6281ff7a700e9bf53bcce2ee579d4f6dd879/numpy-2.4.4-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c9b39d38a9bd2ae1becd7eac1303d031c5c110ad31f2b319c6e7d98b135c934d", size = 15729948, upload-time = "2026-03-29T13:21:14.047Z" }, + { url = "https://files.pythonhosted.org/packages/5f/86/2acbda8cc2af5f3d7bfc791192863b9e3e19674da7b5e533fded124d1299/numpy-2.4.4-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b268594bccac7d7cf5844c7732e3f20c50921d94e36d7ec9b79e9857694b1b2f", size = 16679325, upload-time = "2026-03-29T13:21:17.561Z" }, + { url = "https://files.pythonhosted.org/packages/bc/59/cafd83018f4aa55e0ac6fa92aa066c0a1877b77a615ceff1711c260ffae8/numpy-2.4.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:ac6b31e35612a26483e20750126d30d0941f949426974cace8e6b5c58a3657b0", size = 17084883, upload-time = "2026-03-29T13:21:21.106Z" }, + { url = "https://files.pythonhosted.org/packages/f0/85/a42548db84e65ece46ab2caea3d3f78b416a47af387fcbb47ec28e660dc2/numpy-2.4.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:8e3ed142f2728df44263aaf5fb1f5b0b99f4070c553a0d7f033be65338329150", size = 18403474, upload-time = "2026-03-29T13:21:24.828Z" }, + { url = "https://files.pythonhosted.org/packages/ed/ad/483d9e262f4b831000062e5d8a45e342166ec8aaa1195264982bca267e62/numpy-2.4.4-cp314-cp314t-win32.whl", hash = "sha256:dddbbd259598d7240b18c9d87c56a9d2fb3b02fe266f49a7c101532e78c1d871", size = 6155500, upload-time = "2026-03-29T13:21:28.205Z" }, + { url = "https://files.pythonhosted.org/packages/c7/03/2fc4e14c7bd4ff2964b74ba90ecb8552540b6315f201df70f137faa5c589/numpy-2.4.4-cp314-cp314t-win_amd64.whl", hash = "sha256:a7164afb23be6e37ad90b2f10426149fd75aee07ca55653d2aa41e66c4ef697e", size = 12637755, upload-time = "2026-03-29T13:21:31.107Z" }, + { url = "https://files.pythonhosted.org/packages/58/78/548fb8e07b1a341746bfbecb32f2c268470f45fa028aacdbd10d9bc73aab/numpy-2.4.4-cp314-cp314t-win_arm64.whl", hash = "sha256:ba203255017337d39f89bdd58417f03c4426f12beed0440cfd933cb15f8669c7", size = 10566643, upload-time = "2026-03-29T13:21:34.339Z" }, +] + [[package]] name = "openapi-pydantic" version = "0.5.1" @@ -828,6 +1414,59 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/5f/bf/93795954016c522008da367da292adceed71cca6ee1717e1d64c83089099/opentelemetry_api-1.40.0-py3-none-any.whl", hash = "sha256:82dd69331ae74b06f6a874704be0cfaa49a1650e1537d4a813b86ecef7d0ecf9", size = 68676, upload-time = "2026-03-04T14:17:01.24Z" }, ] +[[package]] +name = "orjson" +version = "3.11.8" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/9d/1b/2024d06792d0779f9dbc51531b61c24f76c75b9f4ce05e6f3377a1814cea/orjson-3.11.8.tar.gz", hash = "sha256:96163d9cdc5a202703e9ad1b9ae757d5f0ca62f4fa0cc93d1f27b0e180cc404e", size = 5603832, upload-time = "2026-03-31T16:16:27.878Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/01/f6/8d58b32ab32d9215973a1688aebd098252ee8af1766c0e4e36e7831f0295/orjson-3.11.8-cp312-cp312-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:1cd0b77e77c95758f8e1100139844e99f3ccc87e71e6fc8e1c027e55807c549f", size = 229233, upload-time = "2026-03-31T16:15:12.762Z" }, + { url = "https://files.pythonhosted.org/packages/a9/8b/2ffe35e71f6b92622e8ea4607bf33ecf7dfb51b3619dcfabfd36cbe2d0a5/orjson-3.11.8-cp312-cp312-macosx_15_0_arm64.whl", hash = "sha256:6a3d159d5ffa0e3961f353c4b036540996bf8b9697ccc38261c0eac1fd3347a6", size = 128772, upload-time = "2026-03-31T16:15:14.237Z" }, + { url = "https://files.pythonhosted.org/packages/27/d2/1f8682ae50d5c6897a563cb96bc106da8c9cb5b7b6e81a52e4cc086679b9/orjson-3.11.8-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:76070a76e9c5ae661e2d9848f216980d8d533e0f8143e6ed462807b242e3c5e8", size = 131946, upload-time = "2026-03-31T16:15:15.607Z" }, + { url = "https://files.pythonhosted.org/packages/52/4b/5500f76f0eece84226e0689cb48dcde081104c2fa6e2483d17ca13685ffb/orjson-3.11.8-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:54153d21520a71a4c82a0dbb4523e468941d549d221dc173de0f019678cf3813", size = 130368, upload-time = "2026-03-31T16:15:17.066Z" }, + { url = "https://files.pythonhosted.org/packages/da/4e/58b927e08fbe9840e6c920d9e299b051ea667463b1f39a56e668669f8508/orjson-3.11.8-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:469ac2125611b7c5741a0b3798cd9e5786cbad6345f9f400c77212be89563bec", size = 135540, upload-time = "2026-03-31T16:15:18.404Z" }, + { url = "https://files.pythonhosted.org/packages/56/7c/ba7cb871cba1bcd5cd02ee34f98d894c6cea96353ad87466e5aef2429c60/orjson-3.11.8-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:14778ffd0f6896aa613951a7fbf4690229aa7a543cb2bfbe9f358e08aafa9546", size = 146877, upload-time = "2026-03-31T16:15:19.833Z" }, + { url = "https://files.pythonhosted.org/packages/0b/5d/eb9c25fc1386696c6a342cd361c306452c75e0b55e86ad602dd4827a7fd7/orjson-3.11.8-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ea56a955056a6d6c550cf18b3348656a9d9a4f02e2d0c02cabf3c73f1055d506", size = 132837, upload-time = "2026-03-31T16:15:21.282Z" }, + { url = "https://files.pythonhosted.org/packages/37/87/5ddeb7fc1fbd9004aeccab08426f34c81a5b4c25c7061281862b015fce2b/orjson-3.11.8-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:53a0f57e59a530d18a142f4d4ba6dfc708dc5fdedce45e98ff06b44930a2a48f", size = 133624, upload-time = "2026-03-31T16:15:22.641Z" }, + { url = "https://files.pythonhosted.org/packages/22/09/90048793db94ee4b2fcec4ac8e5ddb077367637d6650be896b3494b79bb7/orjson-3.11.8-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:9b48e274f8824567d74e2158199e269597edf00823a1b12b63d48462bbf5123e", size = 141904, upload-time = "2026-03-31T16:15:24.435Z" }, + { url = "https://files.pythonhosted.org/packages/c0/cf/eb284847487821a5d415e54149a6449ba9bfc5872ce63ab7be41b8ec401c/orjson-3.11.8-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:3f262401086a3960586af06c054609365e98407151f5ea24a62893a40d80dbbb", size = 423742, upload-time = "2026-03-31T16:15:26.155Z" }, + { url = "https://files.pythonhosted.org/packages/44/09/e12423d327071c851c13e76936f144a96adacfc037394dec35ac3fc8d1e8/orjson-3.11.8-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:8e8c6218b614badf8e229b697865df4301afa74b791b6c9ade01d19a9953a942", size = 147806, upload-time = "2026-03-31T16:15:27.909Z" }, + { url = "https://files.pythonhosted.org/packages/b3/6d/37c2589ba864e582ffe7611643314785c6afb1f83c701654ef05daa8fcc7/orjson-3.11.8-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:093d489fa039ddade2db541097dbb484999fcc65fc2b0ff9819141e2ab364f25", size = 136485, upload-time = "2026-03-31T16:15:29.749Z" }, + { url = "https://files.pythonhosted.org/packages/be/c9/135194a02ab76b04ed9a10f68624b7ebd238bbe55548878b11ff15a0f352/orjson-3.11.8-cp312-cp312-win32.whl", hash = "sha256:e0950ed1bcb9893f4293fd5c5a7ee10934fbf82c4101c70be360db23ce24b7d2", size = 131966, upload-time = "2026-03-31T16:15:31.687Z" }, + { url = "https://files.pythonhosted.org/packages/ed/9a/9796f8fbe3cf30ce9cb696748dbb535e5c87be4bf4fe2e9ca498ef1fa8cf/orjson-3.11.8-cp312-cp312-win_amd64.whl", hash = "sha256:3cf17c141617b88ced4536b2135c552490f07799f6ad565948ea07bef0dcb9a6", size = 127441, upload-time = "2026-03-31T16:15:33.333Z" }, + { url = "https://files.pythonhosted.org/packages/cc/47/5aaf54524a7a4a0dd09dd778f3fa65dd2108290615b652e23d944152bc8e/orjson-3.11.8-cp312-cp312-win_arm64.whl", hash = "sha256:48854463b0572cc87dac7d981aa72ed8bf6deedc0511853dc76b8bbd5482d36d", size = 127364, upload-time = "2026-03-31T16:15:34.748Z" }, + { url = "https://files.pythonhosted.org/packages/66/7f/95fba509bb2305fab0073558f1e8c3a2ec4b2afe58ed9fcb7d3b8beafe94/orjson-3.11.8-cp313-cp313-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:3f23426851d98478c8970da5991f84784a76682213cd50eb73a1da56b95239dc", size = 229180, upload-time = "2026-03-31T16:15:36.426Z" }, + { url = "https://files.pythonhosted.org/packages/f6/9d/b237215c743ca073697d759b5503abd2cb8a0d7b9c9e21f524bcf176ab66/orjson-3.11.8-cp313-cp313-macosx_15_0_arm64.whl", hash = "sha256:ebaed4cef74a045b83e23537b52ef19a367c7e3f536751e355a2a394f8648559", size = 128754, upload-time = "2026-03-31T16:15:38.049Z" }, + { url = "https://files.pythonhosted.org/packages/42/3d/27d65b6d11e63f133781425f132807aef793ed25075fec686fc8e46dd528/orjson-3.11.8-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:97c8f5d3b62380b70c36ffacb2a356b7c6becec86099b177f73851ba095ef623", size = 131877, upload-time = "2026-03-31T16:15:39.484Z" }, + { url = "https://files.pythonhosted.org/packages/dd/cc/faee30cd8f00421999e40ef0eba7332e3a625ce91a58200a2f52c7fef235/orjson-3.11.8-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:436c4922968a619fb7fef1ccd4b8b3a76c13b67d607073914d675026e911a65c", size = 130361, upload-time = "2026-03-31T16:15:41.274Z" }, + { url = "https://files.pythonhosted.org/packages/5c/bb/a6c55896197f97b6d4b4e7c7fd77e7235517c34f5d6ad5aadd43c54c6d7c/orjson-3.11.8-cp313-cp313-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1ab359aff0436d80bfe8a23b46b5fea69f1e18aaf1760a709b4787f1318b317f", size = 135521, upload-time = "2026-03-31T16:15:42.758Z" }, + { url = "https://files.pythonhosted.org/packages/9c/7c/ca3a3525aa32ff636ebb1778e77e3587b016ab2edb1b618b36ba96f8f2c0/orjson-3.11.8-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f89b6d0b3a8d81e1929d3ab3d92bbc225688bd80a770c49432543928fe09ac55", size = 146862, upload-time = "2026-03-31T16:15:44.341Z" }, + { url = "https://files.pythonhosted.org/packages/3c/0c/18a9d7f18b5edd37344d1fd5be17e94dc652c67826ab749c6e5948a78112/orjson-3.11.8-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:29c009e7a2ca9ad0ed1376ce20dd692146a5d9fe4310848904b6b4fee5c5c137", size = 132847, upload-time = "2026-03-31T16:15:46.368Z" }, + { url = "https://files.pythonhosted.org/packages/23/91/7e722f352ad67ca573cee44de2a58fb810d0f4eb4e33276c6a557979fd8a/orjson-3.11.8-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:705b895b781b3e395c067129d8551655642dfe9437273211d5404e87ac752b53", size = 133637, upload-time = "2026-03-31T16:15:48.123Z" }, + { url = "https://files.pythonhosted.org/packages/af/04/32845ce13ac5bd1046ddb02ac9432ba856cc35f6d74dde95864fe0ad5523/orjson-3.11.8-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:88006eda83858a9fdf73985ce3804e885c2befb2f506c9a3723cdeb5a2880e3e", size = 141906, upload-time = "2026-03-31T16:15:49.626Z" }, + { url = "https://files.pythonhosted.org/packages/02/5e/c551387ddf2d7106d9039369862245c85738b828844d13b99ccb8d61fd06/orjson-3.11.8-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:55120759e61309af7fcf9e961c6f6af3dde5921cdb3ee863ef63fd9db126cae6", size = 423722, upload-time = "2026-03-31T16:15:51.176Z" }, + { url = "https://files.pythonhosted.org/packages/00/a3/ecfe62434096f8a794d4976728cb59bcfc4a643977f21c2040545d37eb4c/orjson-3.11.8-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:98bdc6cb889d19bed01de46e67574a2eab61f5cc6b768ed50e8ac68e9d6ffab6", size = 147801, upload-time = "2026-03-31T16:15:52.939Z" }, + { url = "https://files.pythonhosted.org/packages/18/6d/0dce10b9f6643fdc59d99333871a38fa5a769d8e2fc34a18e5d2bfdee900/orjson-3.11.8-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:708c95f925a43ab9f34625e45dcdadf09ec8a6e7b664a938f2f8d5650f6c090b", size = 136460, upload-time = "2026-03-31T16:15:54.431Z" }, + { url = "https://files.pythonhosted.org/packages/01/d6/6dde4f31842d87099238f1f07b459d24edc1a774d20687187443ab044191/orjson-3.11.8-cp313-cp313-win32.whl", hash = "sha256:01c4e5a6695dc09098f2e6468a251bc4671c50922d4d745aff1a0a33a0cf5b8d", size = 131956, upload-time = "2026-03-31T16:15:56.081Z" }, + { url = "https://files.pythonhosted.org/packages/c1/f9/4e494a56e013db957fb77186b818b916d4695b8fa2aa612364974160e91b/orjson-3.11.8-cp313-cp313-win_amd64.whl", hash = "sha256:c154a35dd1330707450bb4d4e7dd1f17fa6f42267a40c1e8a1daa5e13719b4b8", size = 127410, upload-time = "2026-03-31T16:15:57.54Z" }, + { url = "https://files.pythonhosted.org/packages/57/7f/803203d00d6edb6e9e7eef421d4e1adbb5ea973e40b3533f3cfd9aeb374e/orjson-3.11.8-cp313-cp313-win_arm64.whl", hash = "sha256:4861bde57f4d253ab041e374f44023460e60e71efaa121f3c5f0ed457c3a701e", size = 127338, upload-time = "2026-03-31T16:15:59.106Z" }, + { url = "https://files.pythonhosted.org/packages/6d/35/b01910c3d6b85dc882442afe5060cbf719c7d1fc85749294beda23d17873/orjson-3.11.8-cp314-cp314-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:ec795530a73c269a55130498842aaa762e4a939f6ce481a7e986eeaa790e9da4", size = 229171, upload-time = "2026-03-31T16:16:00.651Z" }, + { url = "https://files.pythonhosted.org/packages/c2/56/c9ec97bd11240abef39b9e5d99a15462809c45f677420fd148a6c5e6295e/orjson-3.11.8-cp314-cp314-macosx_15_0_arm64.whl", hash = "sha256:c492a0e011c0f9066e9ceaa896fbc5b068c54d365fea5f3444b697ee01bc8625", size = 128746, upload-time = "2026-03-31T16:16:02.673Z" }, + { url = "https://files.pythonhosted.org/packages/3b/e4/66d4f30a90de45e2f0cbd9623588e8ae71eef7679dbe2ae954ed6d66a41f/orjson-3.11.8-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:883206d55b1bd5f5679ad5e6ddd3d1a5e3cac5190482927fdb8c78fb699193b5", size = 131867, upload-time = "2026-03-31T16:16:04.342Z" }, + { url = "https://files.pythonhosted.org/packages/19/30/2a645fc9286b928675e43fa2a3a16fb7b6764aa78cc719dc82141e00f30b/orjson-3.11.8-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:5774c1fdcc98b2259800b683b19599c133baeb11d60033e2095fd9d4667b82db", size = 124664, upload-time = "2026-03-31T16:16:05.837Z" }, + { url = "https://files.pythonhosted.org/packages/db/44/77b9a86d84a28d52ba3316d77737f6514e17118119ade3f91b639e859029/orjson-3.11.8-cp314-cp314-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:8ac7381c83dd3d4a6347e6635950aa448f54e7b8406a27c7ecb4a37e9f1ae08b", size = 129701, upload-time = "2026-03-31T16:16:07.407Z" }, + { url = "https://files.pythonhosted.org/packages/b3/ea/eff3d9bfe47e9bc6969c9181c58d9f71237f923f9c86a2d2f490cd898c82/orjson-3.11.8-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:14439063aebcb92401c11afc68ee4e407258d2752e62d748b6942dad20d2a70d", size = 141202, upload-time = "2026-03-31T16:16:09.48Z" }, + { url = "https://files.pythonhosted.org/packages/52/c8/90d4b4c60c84d62068d0cf9e4d8f0a4e05e76971d133ac0c60d818d4db20/orjson-3.11.8-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:fa72e71977bff96567b0f500fc5bfd2fdf915f34052c782a4c6ebbdaa97aa858", size = 127194, upload-time = "2026-03-31T16:16:11.02Z" }, + { url = "https://files.pythonhosted.org/packages/8d/c7/ea9e08d1f0ba981adffb629811148b44774d935171e7b3d780ae43c4c254/orjson-3.11.8-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7679bc2f01bb0d219758f1a5f87bb7c8a81c0a186824a393b366876b4948e14f", size = 133639, upload-time = "2026-03-31T16:16:13.434Z" }, + { url = "https://files.pythonhosted.org/packages/6c/8c/ddbbfd6ba59453c8fc7fe1d0e5983895864e264c37481b2a791db635f046/orjson-3.11.8-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:14f7b8fcb35ef403b42fa5ecfa4ed032332a91f3dc7368fbce4184d59e1eae0d", size = 141914, upload-time = "2026-03-31T16:16:14.955Z" }, + { url = "https://files.pythonhosted.org/packages/4e/31/dbfbefec9df060d34ef4962cd0afcb6fa7a9ec65884cb78f04a7859526c3/orjson-3.11.8-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:c2bdf7b2facc80b5e34f48a2d557727d5c5c57a8a450de122ae81fa26a81c1bc", size = 423800, upload-time = "2026-03-31T16:16:16.594Z" }, + { url = "https://files.pythonhosted.org/packages/87/cf/f74e9ae9803d4ab46b163494adba636c6d7ea955af5cc23b8aaa94cfd528/orjson-3.11.8-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:ccd7ba1b0605813a0715171d39ec4c314cb97a9c85893c2c5c0c3a3729df38bf", size = 147837, upload-time = "2026-03-31T16:16:18.585Z" }, + { url = "https://files.pythonhosted.org/packages/64/e6/9214f017b5db85e84e68602792f742e5dc5249e963503d1b356bee611e01/orjson-3.11.8-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:cdbc8c9c02463fef4d3c53a9ba3336d05496ec8e1f1c53326a1e4acc11f5c600", size = 136441, upload-time = "2026-03-31T16:16:20.151Z" }, + { url = "https://files.pythonhosted.org/packages/24/dd/3590348818f58f837a75fb969b04cdf187ae197e14d60b5e5a794a38b79d/orjson-3.11.8-cp314-cp314-win32.whl", hash = "sha256:0b57f67710a8cd459e4e54eb96d5f77f3624eba0c661ba19a525807e42eccade", size = 131983, upload-time = "2026-03-31T16:16:21.823Z" }, + { url = "https://files.pythonhosted.org/packages/3f/0f/b6cb692116e05d058f31ceee819c70f097fa9167c82f67fabe7516289abc/orjson-3.11.8-cp314-cp314-win_amd64.whl", hash = "sha256:735e2262363dcbe05c35e3a8869898022af78f89dde9e256924dc02e99fe69ca", size = 127396, upload-time = "2026-03-31T16:16:23.685Z" }, + { url = "https://files.pythonhosted.org/packages/c0/d1/facb5b5051fabb0ef9d26c6544d87ef19a939a9a001198655d0d891062dd/orjson-3.11.8-cp314-cp314-win_arm64.whl", hash = "sha256:6ccdea2c213cf9f3d9490cbd5d427693c870753df41e6cb375bd79bcbafc8817", size = 127330, upload-time = "2026-03-31T16:16:25.496Z" }, +] + [[package]] name = "packaging" version = "26.0" @@ -846,6 +1485,75 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/52/96/5a770e5c461462575474468e5af931cff9de036e7c2b4fea23c1c58d2cbe/pathable-0.5.0-py3-none-any.whl", hash = "sha256:646e3d09491a6351a0c82632a09c02cdf70a252e73196b36d8a15ba0a114f0a6", size = 16867, upload-time = "2026-02-20T08:46:59.536Z" }, ] +[[package]] +name = "pillow" +version = "12.2.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/8c/21/c2bcdd5906101a30244eaffc1b6e6ce71a31bd0742a01eb89e660ebfac2d/pillow-12.2.0.tar.gz", hash = "sha256:a830b1a40919539d07806aa58e1b114df53ddd43213d9c8b75847eee6c0182b5", size = 46987819, upload-time = "2026-04-01T14:46:17.687Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/58/be/7482c8a5ebebbc6470b3eb791812fff7d5e0216c2be3827b30b8bb6603ed/pillow-12.2.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:2d192a155bbcec180f8564f693e6fd9bccff5a7af9b32e2e4bf8c9c69dbad6b5", size = 5308279, upload-time = "2026-04-01T14:43:13.246Z" }, + { url = "https://files.pythonhosted.org/packages/d8/95/0a351b9289c2b5cbde0bacd4a83ebc44023e835490a727b2a3bd60ddc0f4/pillow-12.2.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f3f40b3c5a968281fd507d519e444c35f0ff171237f4fdde090dd60699458421", size = 4695490, upload-time = "2026-04-01T14:43:15.584Z" }, + { url = "https://files.pythonhosted.org/packages/de/af/4e8e6869cbed569d43c416fad3dc4ecb944cb5d9492defaed89ddd6fe871/pillow-12.2.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:03e7e372d5240cc23e9f07deca4d775c0817bffc641b01e9c3af208dbd300987", size = 6284462, upload-time = "2026-04-01T14:43:18.268Z" }, + { url = "https://files.pythonhosted.org/packages/e9/9e/c05e19657fd57841e476be1ab46c4d501bffbadbafdc31a6d665f8b737b6/pillow-12.2.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:b86024e52a1b269467a802258c25521e6d742349d760728092e1bc2d135b4d76", size = 8094744, upload-time = "2026-04-01T14:43:20.716Z" }, + { url = "https://files.pythonhosted.org/packages/2b/54/1789c455ed10176066b6e7e6da1b01e50e36f94ba584dc68d9eebfe9156d/pillow-12.2.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7371b48c4fa448d20d2714c9a1f775a81155050d383333e0a6c15b1123dda005", size = 6398371, upload-time = "2026-04-01T14:43:23.443Z" }, + { url = "https://files.pythonhosted.org/packages/43/e3/fdc657359e919462369869f1c9f0e973f353f9a9ee295a39b1fea8ee1a77/pillow-12.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:62f5409336adb0663b7caa0da5c7d9e7bdbaae9ce761d34669420c2a801b2780", size = 7087215, upload-time = "2026-04-01T14:43:26.758Z" }, + { url = "https://files.pythonhosted.org/packages/8b/f8/2f6825e441d5b1959d2ca5adec984210f1ec086435b0ed5f52c19b3b8a6e/pillow-12.2.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:01afa7cf67f74f09523699b4e88c73fb55c13346d212a59a2db1f86b0a63e8c5", size = 6509783, upload-time = "2026-04-01T14:43:29.56Z" }, + { url = "https://files.pythonhosted.org/packages/67/f9/029a27095ad20f854f9dba026b3ea6428548316e057e6fc3545409e86651/pillow-12.2.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fc3d34d4a8fbec3e88a79b92e5465e0f9b842b628675850d860b8bd300b159f5", size = 7212112, upload-time = "2026-04-01T14:43:32.091Z" }, + { url = "https://files.pythonhosted.org/packages/be/42/025cfe05d1be22dbfdb4f264fe9de1ccda83f66e4fc3aac94748e784af04/pillow-12.2.0-cp312-cp312-win32.whl", hash = "sha256:58f62cc0f00fd29e64b29f4fd923ffdb3859c9f9e6105bfc37ba1d08994e8940", size = 6378489, upload-time = "2026-04-01T14:43:34.601Z" }, + { url = "https://files.pythonhosted.org/packages/5d/7b/25a221d2c761c6a8ae21bfa3874988ff2583e19cf8a27bf2fee358df7942/pillow-12.2.0-cp312-cp312-win_amd64.whl", hash = "sha256:7f84204dee22a783350679a0333981df803dac21a0190d706a50475e361c93f5", size = 7084129, upload-time = "2026-04-01T14:43:37.213Z" }, + { url = "https://files.pythonhosted.org/packages/10/e1/542a474affab20fd4a0f1836cb234e8493519da6b76899e30bcc5d990b8b/pillow-12.2.0-cp312-cp312-win_arm64.whl", hash = "sha256:af73337013e0b3b46f175e79492d96845b16126ddf79c438d7ea7ff27783a414", size = 2463612, upload-time = "2026-04-01T14:43:39.421Z" }, + { url = "https://files.pythonhosted.org/packages/4a/01/53d10cf0dbad820a8db274d259a37ba50b88b24768ddccec07355382d5ad/pillow-12.2.0-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:8297651f5b5679c19968abefd6bb84d95fe30ef712eb1b2d9b2d31ca61267f4c", size = 4100837, upload-time = "2026-04-01T14:43:41.506Z" }, + { url = "https://files.pythonhosted.org/packages/0f/98/f3a6657ecb698c937f6c76ee564882945f29b79bad496abcba0e84659ec5/pillow-12.2.0-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:50d8520da2a6ce0af445fa6d648c4273c3eeefbc32d7ce049f22e8b5c3daecc2", size = 4176528, upload-time = "2026-04-01T14:43:43.773Z" }, + { url = "https://files.pythonhosted.org/packages/69/bc/8986948f05e3ea490b8442ea1c1d4d990b24a7e43d8a51b2c7d8b1dced36/pillow-12.2.0-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:766cef22385fa1091258ad7e6216792b156dc16d8d3fa607e7545b2b72061f1c", size = 3640401, upload-time = "2026-04-01T14:43:45.87Z" }, + { url = "https://files.pythonhosted.org/packages/34/46/6c717baadcd62bc8ed51d238d521ab651eaa74838291bda1f86fe1f864c9/pillow-12.2.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5d2fd0fa6b5d9d1de415060363433f28da8b1526c1c129020435e186794b3795", size = 5308094, upload-time = "2026-04-01T14:43:48.438Z" }, + { url = "https://files.pythonhosted.org/packages/71/43/905a14a8b17fdb1ccb58d282454490662d2cb89a6bfec26af6d3520da5ec/pillow-12.2.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:56b25336f502b6ed02e889f4ece894a72612fe885889a6e8c4c80239ff6e5f5f", size = 4695402, upload-time = "2026-04-01T14:43:51.292Z" }, + { url = "https://files.pythonhosted.org/packages/73/dd/42107efcb777b16fa0393317eac58f5b5cf30e8392e266e76e51cff28c3d/pillow-12.2.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f1c943e96e85df3d3478f7b691f229887e143f81fedab9b20205349ab04d73ed", size = 6280005, upload-time = "2026-04-01T14:43:54.242Z" }, + { url = "https://files.pythonhosted.org/packages/a8/68/b93e09e5e8549019e61acf49f65b1a8530765a7f812c77a7461bca7e4494/pillow-12.2.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:03f6fab9219220f041c74aeaa2939ff0062bd5c364ba9ce037197f4c6d498cd9", size = 8090669, upload-time = "2026-04-01T14:43:57.335Z" }, + { url = "https://files.pythonhosted.org/packages/4b/6e/3ccb54ce8ec4ddd1accd2d89004308b7b0b21c4ac3d20fa70af4760a4330/pillow-12.2.0-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5cdfebd752ec52bf5bb4e35d9c64b40826bc5b40a13df7c3cda20a2c03a0f5ed", size = 6395194, upload-time = "2026-04-01T14:43:59.864Z" }, + { url = "https://files.pythonhosted.org/packages/67/ee/21d4e8536afd1a328f01b359b4d3997b291ffd35a237c877b331c1c3b71c/pillow-12.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:eedf4b74eda2b5a4b2b2fb4c006d6295df3bf29e459e198c90ea48e130dc75c3", size = 7082423, upload-time = "2026-04-01T14:44:02.74Z" }, + { url = "https://files.pythonhosted.org/packages/78/5f/e9f86ab0146464e8c133fe85df987ed9e77e08b29d8d35f9f9f4d6f917ba/pillow-12.2.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:00a2865911330191c0b818c59103b58a5e697cae67042366970a6b6f1b20b7f9", size = 6505667, upload-time = "2026-04-01T14:44:05.381Z" }, + { url = "https://files.pythonhosted.org/packages/ed/1e/409007f56a2fdce61584fd3acbc2bbc259857d555196cedcadc68c015c82/pillow-12.2.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:1e1757442ed87f4912397c6d35a0db6a7b52592156014706f17658ff58bbf795", size = 7208580, upload-time = "2026-04-01T14:44:08.39Z" }, + { url = "https://files.pythonhosted.org/packages/23/c4/7349421080b12fb35414607b8871e9534546c128a11965fd4a7002ccfbee/pillow-12.2.0-cp313-cp313-win32.whl", hash = "sha256:144748b3af2d1b358d41286056d0003f47cb339b8c43a9ea42f5fea4d8c66b6e", size = 6375896, upload-time = "2026-04-01T14:44:11.197Z" }, + { url = "https://files.pythonhosted.org/packages/3f/82/8a3739a5e470b3c6cbb1d21d315800d8e16bff503d1f16b03a4ec3212786/pillow-12.2.0-cp313-cp313-win_amd64.whl", hash = "sha256:390ede346628ccc626e5730107cde16c42d3836b89662a115a921f28440e6a3b", size = 7081266, upload-time = "2026-04-01T14:44:13.947Z" }, + { url = "https://files.pythonhosted.org/packages/c3/25/f968f618a062574294592f668218f8af564830ccebdd1fa6200f598e65c5/pillow-12.2.0-cp313-cp313-win_arm64.whl", hash = "sha256:8023abc91fba39036dbce14a7d6535632f99c0b857807cbbbf21ecc9f4717f06", size = 2463508, upload-time = "2026-04-01T14:44:16.312Z" }, + { url = "https://files.pythonhosted.org/packages/4d/a4/b342930964e3cb4dce5038ae34b0eab4653334995336cd486c5a8c25a00c/pillow-12.2.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:042db20a421b9bafecc4b84a8b6e444686bd9d836c7fd24542db3e7df7baad9b", size = 5309927, upload-time = "2026-04-01T14:44:18.89Z" }, + { url = "https://files.pythonhosted.org/packages/9f/de/23198e0a65a9cf06123f5435a5d95cea62a635697f8f03d134d3f3a96151/pillow-12.2.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:dd025009355c926a84a612fecf58bb315a3f6814b17ead51a8e48d3823d9087f", size = 4698624, upload-time = "2026-04-01T14:44:21.115Z" }, + { url = "https://files.pythonhosted.org/packages/01/a6/1265e977f17d93ea37aa28aa81bad4fa597933879fac2520d24e021c8da3/pillow-12.2.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:88ddbc66737e277852913bd1e07c150cc7bb124539f94c4e2df5344494e0a612", size = 6321252, upload-time = "2026-04-01T14:44:23.663Z" }, + { url = "https://files.pythonhosted.org/packages/3c/83/5982eb4a285967baa70340320be9f88e57665a387e3a53a7f0db8231a0cd/pillow-12.2.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:d362d1878f00c142b7e1a16e6e5e780f02be8195123f164edf7eddd911eefe7c", size = 8126550, upload-time = "2026-04-01T14:44:26.772Z" }, + { url = "https://files.pythonhosted.org/packages/4e/48/6ffc514adce69f6050d0753b1a18fd920fce8cac87620d5a31231b04bfc5/pillow-12.2.0-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2c727a6d53cb0018aadd8018c2b938376af27914a68a492f59dfcaca650d5eea", size = 6433114, upload-time = "2026-04-01T14:44:29.615Z" }, + { url = "https://files.pythonhosted.org/packages/36/a3/f9a77144231fb8d40ee27107b4463e205fa4677e2ca2548e14da5cf18dce/pillow-12.2.0-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:efd8c21c98c5cc60653bcb311bef2ce0401642b7ce9d09e03a7da87c878289d4", size = 7115667, upload-time = "2026-04-01T14:44:32.773Z" }, + { url = "https://files.pythonhosted.org/packages/c1/fc/ac4ee3041e7d5a565e1c4fd72a113f03b6394cc72ab7089d27608f8aaccb/pillow-12.2.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:9f08483a632889536b8139663db60f6724bfcb443c96f1b18855860d7d5c0fd4", size = 6538966, upload-time = "2026-04-01T14:44:35.252Z" }, + { url = "https://files.pythonhosted.org/packages/c0/a8/27fb307055087f3668f6d0a8ccb636e7431d56ed0750e07a60547b1e083e/pillow-12.2.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:dac8d77255a37e81a2efcbd1fc05f1c15ee82200e6c240d7e127e25e365c39ea", size = 7238241, upload-time = "2026-04-01T14:44:37.875Z" }, + { url = "https://files.pythonhosted.org/packages/ad/4b/926ab182c07fccae9fcb120043464e1ff1564775ec8864f21a0ebce6ac25/pillow-12.2.0-cp313-cp313t-win32.whl", hash = "sha256:ee3120ae9dff32f121610bb08e4313be87e03efeadfc6c0d18f89127e24d0c24", size = 6379592, upload-time = "2026-04-01T14:44:40.336Z" }, + { url = "https://files.pythonhosted.org/packages/c2/c4/f9e476451a098181b30050cc4c9a3556b64c02cf6497ea421ac047e89e4b/pillow-12.2.0-cp313-cp313t-win_amd64.whl", hash = "sha256:325ca0528c6788d2a6c3d40e3568639398137346c3d6e66bb61db96b96511c98", size = 7085542, upload-time = "2026-04-01T14:44:43.251Z" }, + { url = "https://files.pythonhosted.org/packages/00/a4/285f12aeacbe2d6dc36c407dfbbe9e96d4a80b0fb710a337f6d2ad978c75/pillow-12.2.0-cp313-cp313t-win_arm64.whl", hash = "sha256:2e5a76d03a6c6dcef67edabda7a52494afa4035021a79c8558e14af25313d453", size = 2465765, upload-time = "2026-04-01T14:44:45.996Z" }, + { url = "https://files.pythonhosted.org/packages/bf/98/4595daa2365416a86cb0d495248a393dfc84e96d62ad080c8546256cb9c0/pillow-12.2.0-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:3adc9215e8be0448ed6e814966ecf3d9952f0ea40eb14e89a102b87f450660d8", size = 4100848, upload-time = "2026-04-01T14:44:48.48Z" }, + { url = "https://files.pythonhosted.org/packages/0b/79/40184d464cf89f6663e18dfcf7ca21aae2491fff1a16127681bf1fa9b8cf/pillow-12.2.0-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:6a9adfc6d24b10f89588096364cc726174118c62130c817c2837c60cf08a392b", size = 4176515, upload-time = "2026-04-01T14:44:51.353Z" }, + { url = "https://files.pythonhosted.org/packages/b0/63/703f86fd4c422a9cf722833670f4f71418fb116b2853ff7da722ea43f184/pillow-12.2.0-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:6a6e67ea2e6feda684ed370f9a1c52e7a243631c025ba42149a2cc5934dec295", size = 3640159, upload-time = "2026-04-01T14:44:53.588Z" }, + { url = "https://files.pythonhosted.org/packages/71/e0/fb22f797187d0be2270f83500aab851536101b254bfa1eae10795709d283/pillow-12.2.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:2bb4a8d594eacdfc59d9e5ad972aa8afdd48d584ffd5f13a937a664c3e7db0ed", size = 5312185, upload-time = "2026-04-01T14:44:56.039Z" }, + { url = "https://files.pythonhosted.org/packages/ba/8c/1a9e46228571de18f8e28f16fabdfc20212a5d019f3e3303452b3f0a580d/pillow-12.2.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:80b2da48193b2f33ed0c32c38140f9d3186583ce7d516526d462645fd98660ae", size = 4695386, upload-time = "2026-04-01T14:44:58.663Z" }, + { url = "https://files.pythonhosted.org/packages/70/62/98f6b7f0c88b9addd0e87c217ded307b36be024d4ff8869a812b241d1345/pillow-12.2.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:22db17c68434de69d8ecfc2fe821569195c0c373b25cccb9cbdacf2c6e53c601", size = 6280384, upload-time = "2026-04-01T14:45:01.5Z" }, + { url = "https://files.pythonhosted.org/packages/5e/03/688747d2e91cfbe0e64f316cd2e8005698f76ada3130d0194664174fa5de/pillow-12.2.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7b14cc0106cd9aecda615dd6903840a058b4700fcb817687d0ee4fc8b6e389be", size = 8091599, upload-time = "2026-04-01T14:45:04.5Z" }, + { url = "https://files.pythonhosted.org/packages/f6/35/577e22b936fcdd66537329b33af0b4ccfefaeabd8aec04b266528cddb33c/pillow-12.2.0-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8cbeb542b2ebc6fcdacabf8aca8c1a97c9b3ad3927d46b8723f9d4f033288a0f", size = 6396021, upload-time = "2026-04-01T14:45:07.117Z" }, + { url = "https://files.pythonhosted.org/packages/11/8d/d2532ad2a603ca2b93ad9f5135732124e57811d0168155852f37fbce2458/pillow-12.2.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4bfd07bc812fbd20395212969e41931001fd59eb55a60658b0e5710872e95286", size = 7083360, upload-time = "2026-04-01T14:45:09.763Z" }, + { url = "https://files.pythonhosted.org/packages/5e/26/d325f9f56c7e039034897e7380e9cc202b1e368bfd04d4cbe6a441f02885/pillow-12.2.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:9aba9a17b623ef750a4d11b742cbafffeb48a869821252b30ee21b5e91392c50", size = 6507628, upload-time = "2026-04-01T14:45:12.378Z" }, + { url = "https://files.pythonhosted.org/packages/5f/f7/769d5632ffb0988f1c5e7660b3e731e30f7f8ec4318e94d0a5d674eb65a4/pillow-12.2.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:deede7c263feb25dba4e82ea23058a235dcc2fe1f6021025dc71f2b618e26104", size = 7209321, upload-time = "2026-04-01T14:45:15.122Z" }, + { url = "https://files.pythonhosted.org/packages/6a/7a/c253e3c645cd47f1aceea6a8bacdba9991bf45bb7dfe927f7c893e89c93c/pillow-12.2.0-cp314-cp314-win32.whl", hash = "sha256:632ff19b2778e43162304d50da0181ce24ac5bb8180122cbe1bf4673428328c7", size = 6479723, upload-time = "2026-04-01T14:45:17.797Z" }, + { url = "https://files.pythonhosted.org/packages/cd/8b/601e6566b957ca50e28725cb6c355c59c2c8609751efbecd980db44e0349/pillow-12.2.0-cp314-cp314-win_amd64.whl", hash = "sha256:4e6c62e9d237e9b65fac06857d511e90d8461a32adcc1b9065ea0c0fa3a28150", size = 7217400, upload-time = "2026-04-01T14:45:20.529Z" }, + { url = "https://files.pythonhosted.org/packages/d6/94/220e46c73065c3e2951bb91c11a1fb636c8c9ad427ac3ce7d7f3359b9b2f/pillow-12.2.0-cp314-cp314-win_arm64.whl", hash = "sha256:b1c1fbd8a5a1af3412a0810d060a78b5136ec0836c8a4ef9aa11807f2a22f4e1", size = 2554835, upload-time = "2026-04-01T14:45:23.162Z" }, + { url = "https://files.pythonhosted.org/packages/b6/ab/1b426a3974cb0e7da5c29ccff4807871d48110933a57207b5a676cccc155/pillow-12.2.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:57850958fe9c751670e49b2cecf6294acc99e562531f4bd317fa5ddee2068463", size = 5314225, upload-time = "2026-04-01T14:45:25.637Z" }, + { url = "https://files.pythonhosted.org/packages/19/1e/dce46f371be2438eecfee2a1960ee2a243bbe5e961890146d2dee1ff0f12/pillow-12.2.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:d5d38f1411c0ed9f97bcb49b7bd59b6b7c314e0e27420e34d99d844b9ce3b6f3", size = 4698541, upload-time = "2026-04-01T14:45:28.355Z" }, + { url = "https://files.pythonhosted.org/packages/55/c3/7fbecf70adb3a0c33b77a300dc52e424dc22ad8cdc06557a2e49523b703d/pillow-12.2.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:5c0a9f29ca8e79f09de89293f82fc9b0270bb4af1d58bc98f540cc4aedf03166", size = 6322251, upload-time = "2026-04-01T14:45:30.924Z" }, + { url = "https://files.pythonhosted.org/packages/1c/3c/7fbc17cfb7e4fe0ef1642e0abc17fc6c94c9f7a16be41498e12e2ba60408/pillow-12.2.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:1610dd6c61621ae1cf811bef44d77e149ce3f7b95afe66a4512f8c59f25d9ebe", size = 8127807, upload-time = "2026-04-01T14:45:33.908Z" }, + { url = "https://files.pythonhosted.org/packages/ff/c3/a8ae14d6defd2e448493ff512fae903b1e9bd40b72efb6ec55ce0048c8ce/pillow-12.2.0-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0a34329707af4f73cf1782a36cd2289c0368880654a2c11f027bcee9052d35dd", size = 6433935, upload-time = "2026-04-01T14:45:36.623Z" }, + { url = "https://files.pythonhosted.org/packages/6e/32/2880fb3a074847ac159d8f902cb43278a61e85f681661e7419e6596803ed/pillow-12.2.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8e9c4f5b3c546fa3458a29ab22646c1c6c787ea8f5ef51300e5a60300736905e", size = 7116720, upload-time = "2026-04-01T14:45:39.258Z" }, + { url = "https://files.pythonhosted.org/packages/46/87/495cc9c30e0129501643f24d320076f4cc54f718341df18cc70ec94c44e1/pillow-12.2.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:fb043ee2f06b41473269765c2feae53fc2e2fbf96e5e22ca94fb5ad677856f06", size = 6540498, upload-time = "2026-04-01T14:45:41.879Z" }, + { url = "https://files.pythonhosted.org/packages/18/53/773f5edca692009d883a72211b60fdaf8871cbef075eaa9d577f0a2f989e/pillow-12.2.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:f278f034eb75b4e8a13a54a876cc4a5ab39173d2cdd93a638e1b467fc545ac43", size = 7239413, upload-time = "2026-04-01T14:45:44.705Z" }, + { url = "https://files.pythonhosted.org/packages/c9/e4/4b64a97d71b2a83158134abbb2f5bd3f8a2ea691361282f010998f339ec7/pillow-12.2.0-cp314-cp314t-win32.whl", hash = "sha256:6bb77b2dcb06b20f9f4b4a8454caa581cd4dd0643a08bacf821216a16d9c8354", size = 6482084, upload-time = "2026-04-01T14:45:47.568Z" }, + { url = "https://files.pythonhosted.org/packages/ba/13/306d275efd3a3453f72114b7431c877d10b1154014c1ebbedd067770d629/pillow-12.2.0-cp314-cp314t-win_amd64.whl", hash = "sha256:6562ace0d3fb5f20ed7290f1f929cae41b25ae29528f2af1722966a0a02e2aa1", size = 7225152, upload-time = "2026-04-01T14:45:50.032Z" }, + { url = "https://files.pythonhosted.org/packages/ff/6e/cf826fae916b8658848d7b9f38d88da6396895c676e8086fc0988073aaf8/pillow-12.2.0-cp314-cp314t-win_arm64.whl", hash = "sha256:aa88ccfe4e32d362816319ed727a004423aab09c5cea43c01a4b435643fa34eb", size = 2556579, upload-time = "2026-04-01T14:45:52.529Z" }, +] + [[package]] name = "platformdirs" version = "4.9.4" @@ -864,6 +1572,90 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" }, ] +[[package]] +name = "propcache" +version = "0.4.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/9e/da/e9fc233cf63743258bff22b3dfa7ea5baef7b5bc324af47a0ad89b8ffc6f/propcache-0.4.1.tar.gz", hash = "sha256:f48107a8c637e80362555f37ecf49abe20370e557cc4ab374f04ec4423c97c3d", size = 46442, upload-time = "2025-10-08T19:49:02.291Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a2/0f/f17b1b2b221d5ca28b4b876e8bb046ac40466513960646bda8e1853cdfa2/propcache-0.4.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:e153e9cd40cc8945138822807139367f256f89c6810c2634a4f6902b52d3b4e2", size = 80061, upload-time = "2025-10-08T19:46:46.075Z" }, + { url = "https://files.pythonhosted.org/packages/76/47/8ccf75935f51448ba9a16a71b783eb7ef6b9ee60f5d14c7f8a8a79fbeed7/propcache-0.4.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:cd547953428f7abb73c5ad82cbb32109566204260d98e41e5dfdc682eb7f8403", size = 46037, upload-time = "2025-10-08T19:46:47.23Z" }, + { url = "https://files.pythonhosted.org/packages/0a/b6/5c9a0e42df4d00bfb4a3cbbe5cf9f54260300c88a0e9af1f47ca5ce17ac0/propcache-0.4.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f048da1b4f243fc44f205dfd320933a951b8d89e0afd4c7cacc762a8b9165207", size = 47324, upload-time = "2025-10-08T19:46:48.384Z" }, + { url = "https://files.pythonhosted.org/packages/9e/d3/6c7ee328b39a81ee877c962469f1e795f9db87f925251efeb0545e0020d0/propcache-0.4.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ec17c65562a827bba85e3872ead335f95405ea1674860d96483a02f5c698fa72", size = 225505, upload-time = "2025-10-08T19:46:50.055Z" }, + { url = "https://files.pythonhosted.org/packages/01/5d/1c53f4563490b1d06a684742cc6076ef944bc6457df6051b7d1a877c057b/propcache-0.4.1-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:405aac25c6394ef275dee4c709be43745d36674b223ba4eb7144bf4d691b7367", size = 230242, upload-time = "2025-10-08T19:46:51.815Z" }, + { url = "https://files.pythonhosted.org/packages/20/e1/ce4620633b0e2422207c3cb774a0ee61cac13abc6217763a7b9e2e3f4a12/propcache-0.4.1-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:0013cb6f8dde4b2a2f66903b8ba740bdfe378c943c4377a200551ceb27f379e4", size = 238474, upload-time = "2025-10-08T19:46:53.208Z" }, + { url = "https://files.pythonhosted.org/packages/46/4b/3aae6835b8e5f44ea6a68348ad90f78134047b503765087be2f9912140ea/propcache-0.4.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:15932ab57837c3368b024473a525e25d316d8353016e7cc0e5ba9eb343fbb1cf", size = 221575, upload-time = "2025-10-08T19:46:54.511Z" }, + { url = "https://files.pythonhosted.org/packages/6e/a5/8a5e8678bcc9d3a1a15b9a29165640d64762d424a16af543f00629c87338/propcache-0.4.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:031dce78b9dc099f4c29785d9cf5577a3faf9ebf74ecbd3c856a7b92768c3df3", size = 216736, upload-time = "2025-10-08T19:46:56.212Z" }, + { url = "https://files.pythonhosted.org/packages/f1/63/b7b215eddeac83ca1c6b934f89d09a625aa9ee4ba158338854c87210cc36/propcache-0.4.1-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:ab08df6c9a035bee56e31af99be621526bd237bea9f32def431c656b29e41778", size = 213019, upload-time = "2025-10-08T19:46:57.595Z" }, + { url = "https://files.pythonhosted.org/packages/57/74/f580099a58c8af587cac7ba19ee7cb418506342fbbe2d4a4401661cca886/propcache-0.4.1-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:4d7af63f9f93fe593afbf104c21b3b15868efb2c21d07d8732c0c4287e66b6a6", size = 220376, upload-time = "2025-10-08T19:46:59.067Z" }, + { url = "https://files.pythonhosted.org/packages/c4/ee/542f1313aff7eaf19c2bb758c5d0560d2683dac001a1c96d0774af799843/propcache-0.4.1-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:cfc27c945f422e8b5071b6e93169679e4eb5bf73bbcbf1ba3ae3a83d2f78ebd9", size = 226988, upload-time = "2025-10-08T19:47:00.544Z" }, + { url = "https://files.pythonhosted.org/packages/8f/18/9c6b015dd9c6930f6ce2229e1f02fb35298b847f2087ea2b436a5bfa7287/propcache-0.4.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:35c3277624a080cc6ec6f847cbbbb5b49affa3598c4535a0a4682a697aaa5c75", size = 215615, upload-time = "2025-10-08T19:47:01.968Z" }, + { url = "https://files.pythonhosted.org/packages/80/9e/e7b85720b98c45a45e1fca6a177024934dc9bc5f4d5dd04207f216fc33ed/propcache-0.4.1-cp312-cp312-win32.whl", hash = "sha256:671538c2262dadb5ba6395e26c1731e1d52534bfe9ae56d0b5573ce539266aa8", size = 38066, upload-time = "2025-10-08T19:47:03.503Z" }, + { url = "https://files.pythonhosted.org/packages/54/09/d19cff2a5aaac632ec8fc03737b223597b1e347416934c1b3a7df079784c/propcache-0.4.1-cp312-cp312-win_amd64.whl", hash = "sha256:cb2d222e72399fcf5890d1d5cc1060857b9b236adff2792ff48ca2dfd46c81db", size = 41655, upload-time = "2025-10-08T19:47:04.973Z" }, + { url = "https://files.pythonhosted.org/packages/68/ab/6b5c191bb5de08036a8c697b265d4ca76148efb10fa162f14af14fb5f076/propcache-0.4.1-cp312-cp312-win_arm64.whl", hash = "sha256:204483131fb222bdaaeeea9f9e6c6ed0cac32731f75dfc1d4a567fc1926477c1", size = 37789, upload-time = "2025-10-08T19:47:06.077Z" }, + { url = "https://files.pythonhosted.org/packages/bf/df/6d9c1b6ac12b003837dde8a10231a7344512186e87b36e855bef32241942/propcache-0.4.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:43eedf29202c08550aac1d14e0ee619b0430aaef78f85864c1a892294fbc28cf", size = 77750, upload-time = "2025-10-08T19:47:07.648Z" }, + { url = "https://files.pythonhosted.org/packages/8b/e8/677a0025e8a2acf07d3418a2e7ba529c9c33caf09d3c1f25513023c1db56/propcache-0.4.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:d62cdfcfd89ccb8de04e0eda998535c406bf5e060ffd56be6c586cbcc05b3311", size = 44780, upload-time = "2025-10-08T19:47:08.851Z" }, + { url = "https://files.pythonhosted.org/packages/89/a4/92380f7ca60f99ebae761936bc48a72a639e8a47b29050615eef757cb2a7/propcache-0.4.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:cae65ad55793da34db5f54e4029b89d3b9b9490d8abe1b4c7ab5d4b8ec7ebf74", size = 46308, upload-time = "2025-10-08T19:47:09.982Z" }, + { url = "https://files.pythonhosted.org/packages/2d/48/c5ac64dee5262044348d1d78a5f85dd1a57464a60d30daee946699963eb3/propcache-0.4.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:333ddb9031d2704a301ee3e506dc46b1fe5f294ec198ed6435ad5b6a085facfe", size = 208182, upload-time = "2025-10-08T19:47:11.319Z" }, + { url = "https://files.pythonhosted.org/packages/c6/0c/cd762dd011a9287389a6a3eb43aa30207bde253610cca06824aeabfe9653/propcache-0.4.1-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:fd0858c20f078a32cf55f7e81473d96dcf3b93fd2ccdb3d40fdf54b8573df3af", size = 211215, upload-time = "2025-10-08T19:47:13.146Z" }, + { url = "https://files.pythonhosted.org/packages/30/3e/49861e90233ba36890ae0ca4c660e95df565b2cd15d4a68556ab5865974e/propcache-0.4.1-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:678ae89ebc632c5c204c794f8dab2837c5f159aeb59e6ed0539500400577298c", size = 218112, upload-time = "2025-10-08T19:47:14.913Z" }, + { url = "https://files.pythonhosted.org/packages/f1/8b/544bc867e24e1bd48f3118cecd3b05c694e160a168478fa28770f22fd094/propcache-0.4.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d472aeb4fbf9865e0c6d622d7f4d54a4e101a89715d8904282bb5f9a2f476c3f", size = 204442, upload-time = "2025-10-08T19:47:16.277Z" }, + { url = "https://files.pythonhosted.org/packages/50/a6/4282772fd016a76d3e5c0df58380a5ea64900afd836cec2c2f662d1b9bb3/propcache-0.4.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:4d3df5fa7e36b3225954fba85589da77a0fe6a53e3976de39caf04a0db4c36f1", size = 199398, upload-time = "2025-10-08T19:47:17.962Z" }, + { url = "https://files.pythonhosted.org/packages/3e/ec/d8a7cd406ee1ddb705db2139f8a10a8a427100347bd698e7014351c7af09/propcache-0.4.1-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:ee17f18d2498f2673e432faaa71698032b0127ebf23ae5974eeaf806c279df24", size = 196920, upload-time = "2025-10-08T19:47:19.355Z" }, + { url = "https://files.pythonhosted.org/packages/f6/6c/f38ab64af3764f431e359f8baf9e0a21013e24329e8b85d2da32e8ed07ca/propcache-0.4.1-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:580e97762b950f993ae618e167e7be9256b8353c2dcd8b99ec100eb50f5286aa", size = 203748, upload-time = "2025-10-08T19:47:21.338Z" }, + { url = "https://files.pythonhosted.org/packages/d6/e3/fa846bd70f6534d647886621388f0a265254d30e3ce47e5c8e6e27dbf153/propcache-0.4.1-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:501d20b891688eb8e7aa903021f0b72d5a55db40ffaab27edefd1027caaafa61", size = 205877, upload-time = "2025-10-08T19:47:23.059Z" }, + { url = "https://files.pythonhosted.org/packages/e2/39/8163fc6f3133fea7b5f2827e8eba2029a0277ab2c5beee6c1db7b10fc23d/propcache-0.4.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9a0bd56e5b100aef69bd8562b74b46254e7c8812918d3baa700c8a8009b0af66", size = 199437, upload-time = "2025-10-08T19:47:24.445Z" }, + { url = "https://files.pythonhosted.org/packages/93/89/caa9089970ca49c7c01662bd0eeedfe85494e863e8043565aeb6472ce8fe/propcache-0.4.1-cp313-cp313-win32.whl", hash = "sha256:bcc9aaa5d80322bc2fb24bb7accb4a30f81e90ab8d6ba187aec0744bc302ad81", size = 37586, upload-time = "2025-10-08T19:47:25.736Z" }, + { url = "https://files.pythonhosted.org/packages/f5/ab/f76ec3c3627c883215b5c8080debb4394ef5a7a29be811f786415fc1e6fd/propcache-0.4.1-cp313-cp313-win_amd64.whl", hash = "sha256:381914df18634f5494334d201e98245c0596067504b9372d8cf93f4bb23e025e", size = 40790, upload-time = "2025-10-08T19:47:26.847Z" }, + { url = "https://files.pythonhosted.org/packages/59/1b/e71ae98235f8e2ba5004d8cb19765a74877abf189bc53fc0c80d799e56c3/propcache-0.4.1-cp313-cp313-win_arm64.whl", hash = "sha256:8873eb4460fd55333ea49b7d189749ecf6e55bf85080f11b1c4530ed3034cba1", size = 37158, upload-time = "2025-10-08T19:47:27.961Z" }, + { url = "https://files.pythonhosted.org/packages/83/ce/a31bbdfc24ee0dcbba458c8175ed26089cf109a55bbe7b7640ed2470cfe9/propcache-0.4.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:92d1935ee1f8d7442da9c0c4fa7ac20d07e94064184811b685f5c4fada64553b", size = 81451, upload-time = "2025-10-08T19:47:29.445Z" }, + { url = "https://files.pythonhosted.org/packages/25/9c/442a45a470a68456e710d96cacd3573ef26a1d0a60067e6a7d5e655621ed/propcache-0.4.1-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:473c61b39e1460d386479b9b2f337da492042447c9b685f28be4f74d3529e566", size = 46374, upload-time = "2025-10-08T19:47:30.579Z" }, + { url = "https://files.pythonhosted.org/packages/f4/bf/b1d5e21dbc3b2e889ea4327044fb16312a736d97640fb8b6aa3f9c7b3b65/propcache-0.4.1-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:c0ef0aaafc66fbd87842a3fe3902fd889825646bc21149eafe47be6072725835", size = 48396, upload-time = "2025-10-08T19:47:31.79Z" }, + { url = "https://files.pythonhosted.org/packages/f4/04/5b4c54a103d480e978d3c8a76073502b18db0c4bc17ab91b3cb5092ad949/propcache-0.4.1-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f95393b4d66bfae908c3ca8d169d5f79cd65636ae15b5e7a4f6e67af675adb0e", size = 275950, upload-time = "2025-10-08T19:47:33.481Z" }, + { url = "https://files.pythonhosted.org/packages/b4/c1/86f846827fb969c4b78b0af79bba1d1ea2156492e1b83dea8b8a6ae27395/propcache-0.4.1-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c07fda85708bc48578467e85099645167a955ba093be0a2dcba962195676e859", size = 273856, upload-time = "2025-10-08T19:47:34.906Z" }, + { url = "https://files.pythonhosted.org/packages/36/1d/fc272a63c8d3bbad6878c336c7a7dea15e8f2d23a544bda43205dfa83ada/propcache-0.4.1-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:af223b406d6d000830c6f65f1e6431783fc3f713ba3e6cc8c024d5ee96170a4b", size = 280420, upload-time = "2025-10-08T19:47:36.338Z" }, + { url = "https://files.pythonhosted.org/packages/07/0c/01f2219d39f7e53d52e5173bcb09c976609ba30209912a0680adfb8c593a/propcache-0.4.1-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a78372c932c90ee474559c5ddfffd718238e8673c340dc21fe45c5b8b54559a0", size = 263254, upload-time = "2025-10-08T19:47:37.692Z" }, + { url = "https://files.pythonhosted.org/packages/2d/18/cd28081658ce597898f0c4d174d4d0f3c5b6d4dc27ffafeef835c95eb359/propcache-0.4.1-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:564d9f0d4d9509e1a870c920a89b2fec951b44bf5ba7d537a9e7c1ccec2c18af", size = 261205, upload-time = "2025-10-08T19:47:39.659Z" }, + { url = "https://files.pythonhosted.org/packages/7a/71/1f9e22eb8b8316701c2a19fa1f388c8a3185082607da8e406a803c9b954e/propcache-0.4.1-cp313-cp313t-musllinux_1_2_armv7l.whl", hash = "sha256:17612831fda0138059cc5546f4d12a2aacfb9e47068c06af35c400ba58ba7393", size = 247873, upload-time = "2025-10-08T19:47:41.084Z" }, + { url = "https://files.pythonhosted.org/packages/4a/65/3d4b61f36af2b4eddba9def857959f1016a51066b4f1ce348e0cf7881f58/propcache-0.4.1-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:41a89040cb10bd345b3c1a873b2bf36413d48da1def52f268a055f7398514874", size = 262739, upload-time = "2025-10-08T19:47:42.51Z" }, + { url = "https://files.pythonhosted.org/packages/2a/42/26746ab087faa77c1c68079b228810436ccd9a5ce9ac85e2b7307195fd06/propcache-0.4.1-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:e35b88984e7fa64aacecea39236cee32dd9bd8c55f57ba8a75cf2399553f9bd7", size = 263514, upload-time = "2025-10-08T19:47:43.927Z" }, + { url = "https://files.pythonhosted.org/packages/94/13/630690fe201f5502d2403dd3cfd451ed8858fe3c738ee88d095ad2ff407b/propcache-0.4.1-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:6f8b465489f927b0df505cbe26ffbeed4d6d8a2bbc61ce90eb074ff129ef0ab1", size = 257781, upload-time = "2025-10-08T19:47:45.448Z" }, + { url = "https://files.pythonhosted.org/packages/92/f7/1d4ec5841505f423469efbfc381d64b7b467438cd5a4bbcbb063f3b73d27/propcache-0.4.1-cp313-cp313t-win32.whl", hash = "sha256:2ad890caa1d928c7c2965b48f3a3815c853180831d0e5503d35cf00c472f4717", size = 41396, upload-time = "2025-10-08T19:47:47.202Z" }, + { url = "https://files.pythonhosted.org/packages/48/f0/615c30622316496d2cbbc29f5985f7777d3ada70f23370608c1d3e081c1f/propcache-0.4.1-cp313-cp313t-win_amd64.whl", hash = "sha256:f7ee0e597f495cf415bcbd3da3caa3bd7e816b74d0d52b8145954c5e6fd3ff37", size = 44897, upload-time = "2025-10-08T19:47:48.336Z" }, + { url = "https://files.pythonhosted.org/packages/fd/ca/6002e46eccbe0e33dcd4069ef32f7f1c9e243736e07adca37ae8c4830ec3/propcache-0.4.1-cp313-cp313t-win_arm64.whl", hash = "sha256:929d7cbe1f01bb7baffb33dc14eb5691c95831450a26354cd210a8155170c93a", size = 39789, upload-time = "2025-10-08T19:47:49.876Z" }, + { url = "https://files.pythonhosted.org/packages/8e/5c/bca52d654a896f831b8256683457ceddd490ec18d9ec50e97dfd8fc726a8/propcache-0.4.1-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:3f7124c9d820ba5548d431afb4632301acf965db49e666aa21c305cbe8c6de12", size = 78152, upload-time = "2025-10-08T19:47:51.051Z" }, + { url = "https://files.pythonhosted.org/packages/65/9b/03b04e7d82a5f54fb16113d839f5ea1ede58a61e90edf515f6577c66fa8f/propcache-0.4.1-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:c0d4b719b7da33599dfe3b22d3db1ef789210a0597bc650b7cee9c77c2be8c5c", size = 44869, upload-time = "2025-10-08T19:47:52.594Z" }, + { url = "https://files.pythonhosted.org/packages/b2/fa/89a8ef0468d5833a23fff277b143d0573897cf75bd56670a6d28126c7d68/propcache-0.4.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9f302f4783709a78240ebc311b793f123328716a60911d667e0c036bc5dcbded", size = 46596, upload-time = "2025-10-08T19:47:54.073Z" }, + { url = "https://files.pythonhosted.org/packages/86/bd/47816020d337f4a746edc42fe8d53669965138f39ee117414c7d7a340cfe/propcache-0.4.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c80ee5802e3fb9ea37938e7eecc307fb984837091d5fd262bb37238b1ae97641", size = 206981, upload-time = "2025-10-08T19:47:55.715Z" }, + { url = "https://files.pythonhosted.org/packages/df/f6/c5fa1357cc9748510ee55f37173eb31bfde6d94e98ccd9e6f033f2fc06e1/propcache-0.4.1-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ed5a841e8bb29a55fb8159ed526b26adc5bdd7e8bd7bf793ce647cb08656cdf4", size = 211490, upload-time = "2025-10-08T19:47:57.499Z" }, + { url = "https://files.pythonhosted.org/packages/80/1e/e5889652a7c4a3846683401a48f0f2e5083ce0ec1a8a5221d8058fbd1adf/propcache-0.4.1-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:55c72fd6ea2da4c318e74ffdf93c4fe4e926051133657459131a95c846d16d44", size = 215371, upload-time = "2025-10-08T19:47:59.317Z" }, + { url = "https://files.pythonhosted.org/packages/b2/f2/889ad4b2408f72fe1a4f6a19491177b30ea7bf1a0fd5f17050ca08cfc882/propcache-0.4.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8326e144341460402713f91df60ade3c999d601e7eb5ff8f6f7862d54de0610d", size = 201424, upload-time = "2025-10-08T19:48:00.67Z" }, + { url = "https://files.pythonhosted.org/packages/27/73/033d63069b57b0812c8bd19f311faebeceb6ba31b8f32b73432d12a0b826/propcache-0.4.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:060b16ae65bc098da7f6d25bf359f1f31f688384858204fe5d652979e0015e5b", size = 197566, upload-time = "2025-10-08T19:48:02.604Z" }, + { url = "https://files.pythonhosted.org/packages/dc/89/ce24f3dc182630b4e07aa6d15f0ff4b14ed4b9955fae95a0b54c58d66c05/propcache-0.4.1-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:89eb3fa9524f7bec9de6e83cf3faed9d79bffa560672c118a96a171a6f55831e", size = 193130, upload-time = "2025-10-08T19:48:04.499Z" }, + { url = "https://files.pythonhosted.org/packages/a9/24/ef0d5fd1a811fb5c609278d0209c9f10c35f20581fcc16f818da959fc5b4/propcache-0.4.1-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:dee69d7015dc235f526fe80a9c90d65eb0039103fe565776250881731f06349f", size = 202625, upload-time = "2025-10-08T19:48:06.213Z" }, + { url = "https://files.pythonhosted.org/packages/f5/02/98ec20ff5546f68d673df2f7a69e8c0d076b5abd05ca882dc7ee3a83653d/propcache-0.4.1-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:5558992a00dfd54ccbc64a32726a3357ec93825a418a401f5cc67df0ac5d9e49", size = 204209, upload-time = "2025-10-08T19:48:08.432Z" }, + { url = "https://files.pythonhosted.org/packages/a0/87/492694f76759b15f0467a2a93ab68d32859672b646aa8a04ce4864e7932d/propcache-0.4.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:c9b822a577f560fbd9554812526831712c1436d2c046cedee4c3796d3543b144", size = 197797, upload-time = "2025-10-08T19:48:09.968Z" }, + { url = "https://files.pythonhosted.org/packages/ee/36/66367de3575db1d2d3f3d177432bd14ee577a39d3f5d1b3d5df8afe3b6e2/propcache-0.4.1-cp314-cp314-win32.whl", hash = "sha256:ab4c29b49d560fe48b696cdcb127dd36e0bc2472548f3bf56cc5cb3da2b2984f", size = 38140, upload-time = "2025-10-08T19:48:11.232Z" }, + { url = "https://files.pythonhosted.org/packages/0c/2a/a758b47de253636e1b8aef181c0b4f4f204bf0dd964914fb2af90a95b49b/propcache-0.4.1-cp314-cp314-win_amd64.whl", hash = "sha256:5a103c3eb905fcea0ab98be99c3a9a5ab2de60228aa5aceedc614c0281cf6153", size = 41257, upload-time = "2025-10-08T19:48:12.707Z" }, + { url = "https://files.pythonhosted.org/packages/34/5e/63bd5896c3fec12edcbd6f12508d4890d23c265df28c74b175e1ef9f4f3b/propcache-0.4.1-cp314-cp314-win_arm64.whl", hash = "sha256:74c1fb26515153e482e00177a1ad654721bf9207da8a494a0c05e797ad27b992", size = 38097, upload-time = "2025-10-08T19:48:13.923Z" }, + { url = "https://files.pythonhosted.org/packages/99/85/9ff785d787ccf9bbb3f3106f79884a130951436f58392000231b4c737c80/propcache-0.4.1-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:824e908bce90fb2743bd6b59db36eb4f45cd350a39637c9f73b1c1ea66f5b75f", size = 81455, upload-time = "2025-10-08T19:48:15.16Z" }, + { url = "https://files.pythonhosted.org/packages/90/85/2431c10c8e7ddb1445c1f7c4b54d886e8ad20e3c6307e7218f05922cad67/propcache-0.4.1-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:c2b5e7db5328427c57c8e8831abda175421b709672f6cfc3d630c3b7e2146393", size = 46372, upload-time = "2025-10-08T19:48:16.424Z" }, + { url = "https://files.pythonhosted.org/packages/01/20/b0972d902472da9bcb683fa595099911f4d2e86e5683bcc45de60dd05dc3/propcache-0.4.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:6f6ff873ed40292cd4969ef5310179afd5db59fdf055897e282485043fc80ad0", size = 48411, upload-time = "2025-10-08T19:48:17.577Z" }, + { url = "https://files.pythonhosted.org/packages/e2/e3/7dc89f4f21e8f99bad3d5ddb3a3389afcf9da4ac69e3deb2dcdc96e74169/propcache-0.4.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:49a2dc67c154db2c1463013594c458881a069fcf98940e61a0569016a583020a", size = 275712, upload-time = "2025-10-08T19:48:18.901Z" }, + { url = "https://files.pythonhosted.org/packages/20/67/89800c8352489b21a8047c773067644e3897f02ecbbd610f4d46b7f08612/propcache-0.4.1-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:005f08e6a0529984491e37d8dbc3dd86f84bd78a8ceb5fa9a021f4c48d4984be", size = 273557, upload-time = "2025-10-08T19:48:20.762Z" }, + { url = "https://files.pythonhosted.org/packages/e2/a1/b52b055c766a54ce6d9c16d9aca0cad8059acd9637cdf8aa0222f4a026ef/propcache-0.4.1-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5c3310452e0d31390da9035c348633b43d7e7feb2e37be252be6da45abd1abcc", size = 280015, upload-time = "2025-10-08T19:48:22.592Z" }, + { url = "https://files.pythonhosted.org/packages/48/c8/33cee30bd890672c63743049f3c9e4be087e6780906bfc3ec58528be59c1/propcache-0.4.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4c3c70630930447f9ef1caac7728c8ad1c56bc5015338b20fed0d08ea2480b3a", size = 262880, upload-time = "2025-10-08T19:48:23.947Z" }, + { url = "https://files.pythonhosted.org/packages/0c/b1/8f08a143b204b418285c88b83d00edbd61afbc2c6415ffafc8905da7038b/propcache-0.4.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8e57061305815dfc910a3634dcf584f08168a8836e6999983569f51a8544cd89", size = 260938, upload-time = "2025-10-08T19:48:25.656Z" }, + { url = "https://files.pythonhosted.org/packages/cf/12/96e4664c82ca2f31e1c8dff86afb867348979eb78d3cb8546a680287a1e9/propcache-0.4.1-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:521a463429ef54143092c11a77e04056dd00636f72e8c45b70aaa3140d639726", size = 247641, upload-time = "2025-10-08T19:48:27.207Z" }, + { url = "https://files.pythonhosted.org/packages/18/ed/e7a9cfca28133386ba52278136d42209d3125db08d0a6395f0cba0c0285c/propcache-0.4.1-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:120c964da3fdc75e3731aa392527136d4ad35868cc556fd09bb6d09172d9a367", size = 262510, upload-time = "2025-10-08T19:48:28.65Z" }, + { url = "https://files.pythonhosted.org/packages/f5/76/16d8bf65e8845dd62b4e2b57444ab81f07f40caa5652b8969b87ddcf2ef6/propcache-0.4.1-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:d8f353eb14ee3441ee844ade4277d560cdd68288838673273b978e3d6d2c8f36", size = 263161, upload-time = "2025-10-08T19:48:30.133Z" }, + { url = "https://files.pythonhosted.org/packages/e7/70/c99e9edb5d91d5ad8a49fa3c1e8285ba64f1476782fed10ab251ff413ba1/propcache-0.4.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:ab2943be7c652f09638800905ee1bab2c544e537edb57d527997a24c13dc1455", size = 257393, upload-time = "2025-10-08T19:48:31.567Z" }, + { url = "https://files.pythonhosted.org/packages/08/02/87b25304249a35c0915d236575bc3574a323f60b47939a2262b77632a3ee/propcache-0.4.1-cp314-cp314t-win32.whl", hash = "sha256:05674a162469f31358c30bcaa8883cb7829fa3110bf9c0991fe27d7896c42d85", size = 42546, upload-time = "2025-10-08T19:48:32.872Z" }, + { url = "https://files.pythonhosted.org/packages/cb/ef/3c6ecf8b317aa982f309835e8f96987466123c6e596646d4e6a1dfcd080f/propcache-0.4.1-cp314-cp314t-win_amd64.whl", hash = "sha256:990f6b3e2a27d683cb7602ed6c86f15ee6b43b1194736f9baaeb93d0016633b1", size = 46259, upload-time = "2025-10-08T19:48:34.226Z" }, + { url = "https://files.pythonhosted.org/packages/c4/2d/346e946d4951f37eca1e4f55be0f0174c52cd70720f84029b02f296f4a38/propcache-0.4.1-cp314-cp314t-win_arm64.whl", hash = "sha256:ecef2343af4cc68e05131e45024ba34f6095821988a9d0a02aa7c73fcc448aa9", size = 40428, upload-time = "2025-10-08T19:48:35.441Z" }, + { url = "https://files.pythonhosted.org/packages/5b/5a/bc7b4a4ef808fa59a816c17b20c4bef6884daebbdf627ff2a161da67da19/propcache-0.4.1-py3-none-any.whl", hash = "sha256:af2a6052aeb6cf17d3e46ee169099044fd8224cbaf75c76a2ef596e8163e2237", size = 13305, upload-time = "2025-10-08T19:49:00.792Z" }, +] + [[package]] name = "py-key-value-aio" version = "0.4.4" @@ -889,6 +1681,49 @@ memory = [ { name = "cachetools" }, ] +[[package]] +name = "pyarrow" +version = "23.0.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/88/22/134986a4cc224d593c1afde5494d18ff629393d74cc2eddb176669f234a4/pyarrow-23.0.1.tar.gz", hash = "sha256:b8c5873e33440b2bc2f4a79d2b47017a89c5a24116c055625e6f2ee50523f019", size = 1167336, upload-time = "2026-02-16T10:14:12.39Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9a/4b/4166bb5abbfe6f750fc60ad337c43ecf61340fa52ab386da6e8dbf9e63c4/pyarrow-23.0.1-cp312-cp312-macosx_12_0_arm64.whl", hash = "sha256:f4b0dbfa124c0bb161f8b5ebb40f1a680b70279aa0c9901d44a2b5a20806039f", size = 34214575, upload-time = "2026-02-16T10:09:56.225Z" }, + { url = "https://files.pythonhosted.org/packages/e1/da/3f941e3734ac8088ea588b53e860baeddac8323ea40ce22e3d0baa865cc9/pyarrow-23.0.1-cp312-cp312-macosx_12_0_x86_64.whl", hash = "sha256:7707d2b6673f7de054e2e83d59f9e805939038eebe1763fe811ee8fa5c0cd1a7", size = 35832540, upload-time = "2026-02-16T10:10:03.428Z" }, + { url = "https://files.pythonhosted.org/packages/88/7c/3d841c366620e906d54430817531b877ba646310296df42ef697308c2705/pyarrow-23.0.1-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:86ff03fb9f1a320266e0de855dee4b17da6794c595d207f89bba40d16b5c78b9", size = 44470940, upload-time = "2026-02-16T10:10:10.704Z" }, + { url = "https://files.pythonhosted.org/packages/2c/a5/da83046273d990f256cb79796a190bbf7ec999269705ddc609403f8c6b06/pyarrow-23.0.1-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:813d99f31275919c383aab17f0f455a04f5a429c261cc411b1e9a8f5e4aaaa05", size = 47586063, upload-time = "2026-02-16T10:10:17.95Z" }, + { url = "https://files.pythonhosted.org/packages/5b/3c/b7d2ebcff47a514f47f9da1e74b7949138c58cfeb108cdd4ee62f43f0cf3/pyarrow-23.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:bf5842f960cddd2ef757d486041d57c96483efc295a8c4a0e20e704cbbf39c67", size = 48173045, upload-time = "2026-02-16T10:10:25.363Z" }, + { url = "https://files.pythonhosted.org/packages/43/b2/b40961262213beaba6acfc88698eb773dfce32ecdf34d19291db94c2bd73/pyarrow-23.0.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:564baf97c858ecc03ec01a41062e8f4698abc3e6e2acd79c01c2e97880a19730", size = 50621741, upload-time = "2026-02-16T10:10:33.477Z" }, + { url = "https://files.pythonhosted.org/packages/f6/70/1fdda42d65b28b078e93d75d371b2185a61da89dda4def8ba6ba41ebdeb4/pyarrow-23.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:07deae7783782ac7250989a7b2ecde9b3c343a643f82e8a4df03d93b633006f0", size = 27620678, upload-time = "2026-02-16T10:10:39.31Z" }, + { url = "https://files.pythonhosted.org/packages/47/10/2cbe4c6f0fb83d2de37249567373d64327a5e4d8db72f486db42875b08f6/pyarrow-23.0.1-cp313-cp313-macosx_12_0_arm64.whl", hash = "sha256:6b8fda694640b00e8af3c824f99f789e836720aa8c9379fb435d4c4953a756b8", size = 34210066, upload-time = "2026-02-16T10:10:45.487Z" }, + { url = "https://files.pythonhosted.org/packages/cb/4f/679fa7e84dadbaca7a65f7cdba8d6c83febbd93ca12fa4adf40ba3b6362b/pyarrow-23.0.1-cp313-cp313-macosx_12_0_x86_64.whl", hash = "sha256:8ff51b1addc469b9444b7c6f3548e19dc931b172ab234e995a60aea9f6e6025f", size = 35825526, upload-time = "2026-02-16T10:10:52.266Z" }, + { url = "https://files.pythonhosted.org/packages/f9/63/d2747d930882c9d661e9398eefc54f15696547b8983aaaf11d4a2e8b5426/pyarrow-23.0.1-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:71c5be5cbf1e1cb6169d2a0980850bccb558ddc9b747b6206435313c47c37677", size = 44473279, upload-time = "2026-02-16T10:11:01.557Z" }, + { url = "https://files.pythonhosted.org/packages/b3/93/10a48b5e238de6d562a411af6467e71e7aedbc9b87f8d3a35f1560ae30fb/pyarrow-23.0.1-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:9b6f4f17b43bc39d56fec96e53fe89d94bac3eb134137964371b45352d40d0c2", size = 47585798, upload-time = "2026-02-16T10:11:09.401Z" }, + { url = "https://files.pythonhosted.org/packages/5c/20/476943001c54ef078dbf9542280e22741219a184a0632862bca4feccd666/pyarrow-23.0.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:9fc13fc6c403d1337acab46a2c4346ca6c9dec5780c3c697cf8abfd5e19b6b37", size = 48179446, upload-time = "2026-02-16T10:11:17.781Z" }, + { url = "https://files.pythonhosted.org/packages/4b/b6/5dd0c47b335fcd8edba9bfab78ad961bd0fd55ebe53468cc393f45e0be60/pyarrow-23.0.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:5c16ed4f53247fa3ffb12a14d236de4213a4415d127fe9cebed33d51671113e2", size = 50623972, upload-time = "2026-02-16T10:11:26.185Z" }, + { url = "https://files.pythonhosted.org/packages/d5/09/a532297c9591a727d67760e2e756b83905dd89adb365a7f6e9c72578bcc1/pyarrow-23.0.1-cp313-cp313-win_amd64.whl", hash = "sha256:cecfb12ef629cf6be0b1887f9f86463b0dd3dc3195ae6224e74006be4736035a", size = 27540749, upload-time = "2026-02-16T10:12:23.297Z" }, + { url = "https://files.pythonhosted.org/packages/a5/8e/38749c4b1303e6ae76b3c80618f84861ae0c55dd3c2273842ea6f8258233/pyarrow-23.0.1-cp313-cp313t-macosx_12_0_arm64.whl", hash = "sha256:29f7f7419a0e30264ea261fdc0e5fe63ce5a6095003db2945d7cd78df391a7e1", size = 34471544, upload-time = "2026-02-16T10:11:32.535Z" }, + { url = "https://files.pythonhosted.org/packages/a3/73/f237b2bc8c669212f842bcfd842b04fc8d936bfc9d471630569132dc920d/pyarrow-23.0.1-cp313-cp313t-macosx_12_0_x86_64.whl", hash = "sha256:33d648dc25b51fd8055c19e4261e813dfc4d2427f068bcecc8b53d01b81b0500", size = 35949911, upload-time = "2026-02-16T10:11:39.813Z" }, + { url = "https://files.pythonhosted.org/packages/0c/86/b912195eee0903b5611bf596833def7d146ab2d301afeb4b722c57ffc966/pyarrow-23.0.1-cp313-cp313t-manylinux_2_28_aarch64.whl", hash = "sha256:cd395abf8f91c673dd3589cadc8cc1ee4e8674fa61b2e923c8dd215d9c7d1f41", size = 44520337, upload-time = "2026-02-16T10:11:47.764Z" }, + { url = "https://files.pythonhosted.org/packages/69/c2/f2a717fb824f62d0be952ea724b4f6f9372a17eed6f704b5c9526f12f2f1/pyarrow-23.0.1-cp313-cp313t-manylinux_2_28_x86_64.whl", hash = "sha256:00be9576d970c31defb5c32eb72ef585bf600ef6d0a82d5eccaae96639cf9d07", size = 47548944, upload-time = "2026-02-16T10:11:56.607Z" }, + { url = "https://files.pythonhosted.org/packages/84/a7/90007d476b9f0dc308e3bc57b832d004f848fd6c0da601375d20d92d1519/pyarrow-23.0.1-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:c2139549494445609f35a5cda4eb94e2c9e4d704ce60a095b342f82460c73a83", size = 48236269, upload-time = "2026-02-16T10:12:04.47Z" }, + { url = "https://files.pythonhosted.org/packages/b0/3f/b16fab3e77709856eb6ac328ce35f57a6d4a18462c7ca5186ef31b45e0e0/pyarrow-23.0.1-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:7044b442f184d84e2351e5084600f0d7343d6117aabcbc1ac78eb1ae11eb4125", size = 50604794, upload-time = "2026-02-16T10:12:11.797Z" }, + { url = "https://files.pythonhosted.org/packages/e9/a1/22df0620a9fac31d68397a75465c344e83c3dfe521f7612aea33e27ab6c0/pyarrow-23.0.1-cp313-cp313t-win_amd64.whl", hash = "sha256:a35581e856a2fafa12f3f54fce4331862b1cfb0bef5758347a858a4aa9d6bae8", size = 27660642, upload-time = "2026-02-16T10:12:17.746Z" }, + { url = "https://files.pythonhosted.org/packages/8d/1b/6da9a89583ce7b23ac611f183ae4843cd3a6cf54f079549b0e8c14031e73/pyarrow-23.0.1-cp314-cp314-macosx_12_0_arm64.whl", hash = "sha256:5df1161da23636a70838099d4aaa65142777185cc0cdba4037a18cee7d8db9ca", size = 34238755, upload-time = "2026-02-16T10:12:32.819Z" }, + { url = "https://files.pythonhosted.org/packages/ae/b5/d58a241fbe324dbaeb8df07be6af8752c846192d78d2272e551098f74e88/pyarrow-23.0.1-cp314-cp314-macosx_12_0_x86_64.whl", hash = "sha256:fa8e51cb04b9f8c9c5ace6bab63af9a1f88d35c0d6cbf53e8c17c098552285e1", size = 35847826, upload-time = "2026-02-16T10:12:38.949Z" }, + { url = "https://files.pythonhosted.org/packages/54/a5/8cbc83f04aba433ca7b331b38f39e000efd9f0c7ce47128670e737542996/pyarrow-23.0.1-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:0b95a3994f015be13c63148fef8832e8a23938128c185ee951c98908a696e0eb", size = 44536859, upload-time = "2026-02-16T10:12:45.467Z" }, + { url = "https://files.pythonhosted.org/packages/36/2e/c0f017c405fcdc252dbccafbe05e36b0d0eb1ea9a958f081e01c6972927f/pyarrow-23.0.1-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:4982d71350b1a6e5cfe1af742c53dfb759b11ce14141870d05d9e540d13bc5d1", size = 47614443, upload-time = "2026-02-16T10:12:55.525Z" }, + { url = "https://files.pythonhosted.org/packages/af/6b/2314a78057912f5627afa13ba43809d9d653e6630859618b0fd81a4e0759/pyarrow-23.0.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c250248f1fe266db627921c89b47b7c06fee0489ad95b04d50353537d74d6886", size = 48232991, upload-time = "2026-02-16T10:13:04.729Z" }, + { url = "https://files.pythonhosted.org/packages/40/f2/1bcb1d3be3460832ef3370d621142216e15a2c7c62602a4ea19ec240dd64/pyarrow-23.0.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5f4763b83c11c16e5f4c15601ba6dfa849e20723b46aa2617cb4bffe8768479f", size = 50645077, upload-time = "2026-02-16T10:13:14.147Z" }, + { url = "https://files.pythonhosted.org/packages/eb/3f/b1da7b61cd66566a4d4c8383d376c606d1c34a906c3f1cb35c479f59d1aa/pyarrow-23.0.1-cp314-cp314-win_amd64.whl", hash = "sha256:3a4c85ef66c134161987c17b147d6bffdca4566f9a4c1d81a0a01cdf08414ea5", size = 28234271, upload-time = "2026-02-16T10:14:09.397Z" }, + { url = "https://files.pythonhosted.org/packages/b5/78/07f67434e910a0f7323269be7bfbf58699bd0c1d080b18a1ab49ba943fe8/pyarrow-23.0.1-cp314-cp314t-macosx_12_0_arm64.whl", hash = "sha256:17cd28e906c18af486a499422740298c52d7c6795344ea5002a7720b4eadf16d", size = 34488692, upload-time = "2026-02-16T10:13:21.541Z" }, + { url = "https://files.pythonhosted.org/packages/50/76/34cf7ae93ece1f740a04910d9f7e80ba166b9b4ab9596a953e9e62b90fe1/pyarrow-23.0.1-cp314-cp314t-macosx_12_0_x86_64.whl", hash = "sha256:76e823d0e86b4fb5e1cf4a58d293036e678b5a4b03539be933d3b31f9406859f", size = 35964383, upload-time = "2026-02-16T10:13:28.63Z" }, + { url = "https://files.pythonhosted.org/packages/46/90/459b827238936d4244214be7c684e1b366a63f8c78c380807ae25ed92199/pyarrow-23.0.1-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:a62e1899e3078bf65943078b3ad2a6ddcacf2373bc06379aac61b1e548a75814", size = 44538119, upload-time = "2026-02-16T10:13:35.506Z" }, + { url = "https://files.pythonhosted.org/packages/28/a1/93a71ae5881e99d1f9de1d4554a87be37da11cd6b152239fb5bd924fdc64/pyarrow-23.0.1-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:df088e8f640c9fae3b1f495b3c64755c4e719091caf250f3a74d095ddf3c836d", size = 47571199, upload-time = "2026-02-16T10:13:42.504Z" }, + { url = "https://files.pythonhosted.org/packages/88/a3/d2c462d4ef313521eaf2eff04d204ac60775263f1fb08c374b543f79f610/pyarrow-23.0.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:46718a220d64677c93bc243af1d44b55998255427588e400677d7192671845c7", size = 48259435, upload-time = "2026-02-16T10:13:49.226Z" }, + { url = "https://files.pythonhosted.org/packages/cc/f1/11a544b8c3d38a759eb3fbb022039117fd633e9a7b19e4841cc3da091915/pyarrow-23.0.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:a09f3876e87f48bc2f13583ab551f0379e5dfb83210391e68ace404181a20690", size = 50629149, upload-time = "2026-02-16T10:13:57.238Z" }, + { url = "https://files.pythonhosted.org/packages/50/f2/c0e76a0b451ffdf0cf788932e182758eb7558953f4f27f1aff8e2518b653/pyarrow-23.0.1-cp314-cp314t-win_amd64.whl", hash = "sha256:527e8d899f14bd15b740cd5a54ad56b7f98044955373a17179d5956ddb93d9ce", size = 28365807, upload-time = "2026-02-16T10:14:03.892Z" }, +] + [[package]] name = "pyasn1" version = "0.6.3" @@ -1072,6 +1907,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" }, ] +[[package]] +name = "python-dateutil" +version = "2.9.0.post0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "six" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" }, +] + [[package]] name = "python-dotenv" version = "1.2.2" @@ -1190,6 +2037,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d7/8e/7540e8a2036f79a125c1d2ebadf69ed7901608859186c856fa0388ef4197/requests-2.33.1-py3-none-any.whl", hash = "sha256:4e6d1ef462f3626a1f0a0a9c42dd93c63bad33f9f1c1937509b8c5c8718ab56a", size = 64947, upload-time = "2026-03-30T16:09:13.83Z" }, ] +[[package]] +name = "requests-toolbelt" +version = "1.0.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "requests" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f3/61/d7545dafb7ac2230c70d38d31cbfe4cc64f7144dc41f6e4e4b78ecd9f5bb/requests-toolbelt-1.0.0.tar.gz", hash = "sha256:7681a0a3d047012b5bdc0ee37d7f8f07ebe76ab08caeccfc3921ce23c88d5bc6", size = 206888, upload-time = "2023-05-01T04:11:33.229Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/3f/51/d4db610ef29373b879047326cbf6fa98b6c1969d6f6dc423279de2b1be2c/requests_toolbelt-1.0.0-py2.py3-none-any.whl", hash = "sha256:cccfdd665f0a24fcf4726e690f65639d272bb0637b9b92dfd91a5568ccf6bd06", size = 54481, upload-time = "2023-05-01T04:11:28.427Z" }, +] + [[package]] name = "rich" version = "14.3.3" @@ -1310,6 +2169,24 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b7/46/f5af3402b579fd5e11573ce652019a67074317e18c1935cc0b4ba9b35552/secretstorage-3.5.0-py3-none-any.whl", hash = "sha256:0ce65888c0725fcb2c5bc0fdb8e5438eece02c523557ea40ce0703c266248137", size = 15554, upload-time = "2025-11-23T19:02:51.545Z" }, ] +[[package]] +name = "shellingham" +version = "1.5.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/58/15/8b3609fd3830ef7b27b655beb4b4e9c62313a4e8da8c676e142cc210d58e/shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de", size = 10310, upload-time = "2023-10-24T04:13:40.426Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" }, +] + +[[package]] +name = "six" +version = "1.17.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" }, +] + [[package]] name = "sniffio" version = "1.3.1" @@ -1354,6 +2231,59 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d7/c1/eb8f9debc45d3b7918a32ab756658a0904732f75e555402972246b0b8e71/tenacity-9.1.4-py3-none-any.whl", hash = "sha256:6095a360c919085f28c6527de529e76a06ad89b23659fa881ae0649b867a9d55", size = 28926, upload-time = "2026-02-07T10:45:32.24Z" }, ] +[[package]] +name = "tokenizers" +version = "0.22.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "huggingface-hub" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/73/6f/f80cfef4a312e1fb34baf7d85c72d4411afde10978d4657f8cdd811d3ccc/tokenizers-0.22.2.tar.gz", hash = "sha256:473b83b915e547aa366d1eee11806deaf419e17be16310ac0a14077f1e28f917", size = 372115, upload-time = "2026-01-05T10:45:15.988Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/92/97/5dbfabf04c7e348e655e907ed27913e03db0923abb5dfdd120d7b25630e1/tokenizers-0.22.2-cp39-abi3-macosx_10_12_x86_64.whl", hash = "sha256:544dd704ae7238755d790de45ba8da072e9af3eea688f698b137915ae959281c", size = 3100275, upload-time = "2026-01-05T10:41:02.158Z" }, + { url = "https://files.pythonhosted.org/packages/2e/47/174dca0502ef88b28f1c9e06b73ce33500eedfac7a7692108aec220464e7/tokenizers-0.22.2-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:1e418a55456beedca4621dbab65a318981467a2b188e982a23e117f115ce5001", size = 2981472, upload-time = "2026-01-05T10:41:00.276Z" }, + { url = "https://files.pythonhosted.org/packages/d6/84/7990e799f1309a8b87af6b948f31edaa12a3ed22d11b352eaf4f4b2e5753/tokenizers-0.22.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2249487018adec45d6e3554c71d46eb39fa8ea67156c640f7513eb26f318cec7", size = 3290736, upload-time = "2026-01-05T10:40:32.165Z" }, + { url = "https://files.pythonhosted.org/packages/78/59/09d0d9ba94dcd5f4f1368d4858d24546b4bdc0231c2354aa31d6199f0399/tokenizers-0.22.2-cp39-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:25b85325d0815e86e0bac263506dd114578953b7b53d7de09a6485e4a160a7dd", size = 3168835, upload-time = "2026-01-05T10:40:38.847Z" }, + { url = "https://files.pythonhosted.org/packages/47/50/b3ebb4243e7160bda8d34b731e54dd8ab8b133e50775872e7a434e524c28/tokenizers-0.22.2-cp39-abi3-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:bfb88f22a209ff7b40a576d5324bf8286b519d7358663db21d6246fb17eea2d5", size = 3521673, upload-time = "2026-01-05T10:40:56.614Z" }, + { url = "https://files.pythonhosted.org/packages/e0/fa/89f4cb9e08df770b57adb96f8cbb7e22695a4cb6c2bd5f0c4f0ebcf33b66/tokenizers-0.22.2-cp39-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1c774b1276f71e1ef716e5486f21e76333464f47bece56bbd554485982a9e03e", size = 3724818, upload-time = "2026-01-05T10:40:44.507Z" }, + { url = "https://files.pythonhosted.org/packages/64/04/ca2363f0bfbe3b3d36e95bf67e56a4c88c8e3362b658e616d1ac185d47f2/tokenizers-0.22.2-cp39-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:df6c4265b289083bf710dff49bc51ef252f9d5be33a45ee2bed151114a56207b", size = 3379195, upload-time = "2026-01-05T10:40:51.139Z" }, + { url = "https://files.pythonhosted.org/packages/2e/76/932be4b50ef6ccedf9d3c6639b056a967a86258c6d9200643f01269211ca/tokenizers-0.22.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:369cc9fc8cc10cb24143873a0d95438bb8ee257bb80c71989e3ee290e8d72c67", size = 3274982, upload-time = "2026-01-05T10:40:58.331Z" }, + { url = "https://files.pythonhosted.org/packages/1d/28/5f9f5a4cc211b69e89420980e483831bcc29dade307955cc9dc858a40f01/tokenizers-0.22.2-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:29c30b83d8dcd061078b05ae0cb94d3c710555fbb44861139f9f83dcca3dc3e4", size = 9478245, upload-time = "2026-01-05T10:41:04.053Z" }, + { url = "https://files.pythonhosted.org/packages/6c/fb/66e2da4704d6aadebf8cb39f1d6d1957df667ab24cff2326b77cda0dcb85/tokenizers-0.22.2-cp39-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:37ae80a28c1d3265bb1f22464c856bd23c02a05bb211e56d0c5301a435be6c1a", size = 9560069, upload-time = "2026-01-05T10:45:10.673Z" }, + { url = "https://files.pythonhosted.org/packages/16/04/fed398b05caa87ce9b1a1bb5166645e38196081b225059a6edaff6440fac/tokenizers-0.22.2-cp39-abi3-musllinux_1_2_i686.whl", hash = "sha256:791135ee325f2336f498590eb2f11dc5c295232f288e75c99a36c5dbce63088a", size = 9899263, upload-time = "2026-01-05T10:45:12.559Z" }, + { url = "https://files.pythonhosted.org/packages/05/a1/d62dfe7376beaaf1394917e0f8e93ee5f67fea8fcf4107501db35996586b/tokenizers-0.22.2-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:38337540fbbddff8e999d59970f3c6f35a82de10053206a7562f1ea02d046fa5", size = 10033429, upload-time = "2026-01-05T10:45:14.333Z" }, + { url = "https://files.pythonhosted.org/packages/fd/18/a545c4ea42af3df6effd7d13d250ba77a0a86fb20393143bbb9a92e434d4/tokenizers-0.22.2-cp39-abi3-win32.whl", hash = "sha256:a6bf3f88c554a2b653af81f3204491c818ae2ac6fbc09e76ef4773351292bc92", size = 2502363, upload-time = "2026-01-05T10:45:20.593Z" }, + { url = "https://files.pythonhosted.org/packages/65/71/0670843133a43d43070abeb1949abfdef12a86d490bea9cd9e18e37c5ff7/tokenizers-0.22.2-cp39-abi3-win_amd64.whl", hash = "sha256:c9ea31edff2968b44a88f97d784c2f16dc0729b8b143ed004699ebca91f05c48", size = 2747786, upload-time = "2026-01-05T10:45:18.411Z" }, + { url = "https://files.pythonhosted.org/packages/72/f4/0de46cfa12cdcbcd464cc59fde36912af405696f687e53a091fb432f694c/tokenizers-0.22.2-cp39-abi3-win_arm64.whl", hash = "sha256:9ce725d22864a1e965217204946f830c37876eee3b2ba6fc6255e8e903d5fcbc", size = 2612133, upload-time = "2026-01-05T10:45:17.232Z" }, +] + +[[package]] +name = "tqdm" +version = "4.67.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "colorama", marker = "sys_platform == 'win32'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/09/a9/6ba95a270c6f1fbcd8dac228323f2777d886cb206987444e4bce66338dd4/tqdm-4.67.3.tar.gz", hash = "sha256:7d825f03f89244ef73f1d4ce193cb1774a8179fd96f31d7e1dcde62092b960bb", size = 169598, upload-time = "2026-02-03T17:35:53.048Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/16/e1/3079a9ff9b8e11b846c6ac5c8b5bfb7ff225eee721825310c91b3b50304f/tqdm-4.67.3-py3-none-any.whl", hash = "sha256:ee1e4c0e59148062281c49d80b25b67771a127c85fc9676d3be5f243206826bf", size = 78374, upload-time = "2026-02-03T17:35:50.982Z" }, +] + +[[package]] +name = "typer" +version = "0.24.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "annotated-doc" }, + { name = "click" }, + { name = "rich" }, + { name = "shellingham" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f5/24/cb09efec5cc954f7f9b930bf8279447d24618bb6758d4f6adf2574c41780/typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45", size = 118613, upload-time = "2026-02-21T16:54:40.609Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/4a/91/48db081e7a63bb37284f9fbcefda7c44c277b18b0e13fbc36ea2335b71e6/typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e", size = 56085, upload-time = "2026-02-21T16:54:41.616Z" }, +] + [[package]] name = "typing-extensions" version = "4.15.0" @@ -1393,6 +2323,28 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" }, ] +[[package]] +name = "uuid-utils" +version = "0.14.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/7b/d1/38a573f0c631c062cf42fa1f5d021d4dd3c31fb23e4376e4b56b0c9fbbed/uuid_utils-0.14.1.tar.gz", hash = "sha256:9bfc95f64af80ccf129c604fb6b8ca66c6f256451e32bc4570f760e4309c9b69", size = 22195, upload-time = "2026-02-20T22:50:38.833Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/43/b7/add4363039a34506a58457d96d4aa2126061df3a143eb4d042aedd6a2e76/uuid_utils-0.14.1-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:93a3b5dc798a54a1feb693f2d1cb4cf08258c32ff05ae4929b5f0a2ca624a4f0", size = 604679, upload-time = "2026-02-20T22:50:27.469Z" }, + { url = "https://files.pythonhosted.org/packages/dd/84/d1d0bef50d9e66d31b2019997c741b42274d53dde2e001b7a83e9511c339/uuid_utils-0.14.1-cp39-abi3-macosx_10_12_x86_64.whl", hash = "sha256:ccd65a4b8e83af23eae5e56d88034b2fe7264f465d3e830845f10d1591b81741", size = 309346, upload-time = "2026-02-20T22:50:31.857Z" }, + { url = "https://files.pythonhosted.org/packages/ef/ed/b6d6fd52a6636d7c3eddf97d68da50910bf17cd5ac221992506fb56cf12e/uuid_utils-0.14.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b56b0cacd81583834820588378e432b0696186683b813058b707aedc1e16c4b1", size = 344714, upload-time = "2026-02-20T22:50:42.642Z" }, + { url = "https://files.pythonhosted.org/packages/a8/a7/a19a1719fb626fe0b31882db36056d44fe904dc0cf15b06fdf56b2679cf7/uuid_utils-0.14.1-cp39-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bb3cf14de789097320a3c56bfdfdd51b1225d11d67298afbedee7e84e3837c96", size = 350914, upload-time = "2026-02-20T22:50:36.487Z" }, + { url = "https://files.pythonhosted.org/packages/1d/fc/f6690e667fdc3bb1a73f57951f97497771c56fe23e3d302d7404be394d4f/uuid_utils-0.14.1-cp39-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:60e0854a90d67f4b0cc6e54773deb8be618f4c9bad98d3326f081423b5d14fae", size = 482609, upload-time = "2026-02-20T22:50:37.511Z" }, + { url = "https://files.pythonhosted.org/packages/54/6e/dcd3fa031320921a12ec7b4672dea3bd1dd90ddffa363a91831ba834d559/uuid_utils-0.14.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ce6743ba194de3910b5feb1a62590cd2587e33a73ab6af8a01b642ceb5055862", size = 345699, upload-time = "2026-02-20T22:50:46.87Z" }, + { url = "https://files.pythonhosted.org/packages/04/28/e5220204b58b44ac0047226a9d016a113fde039280cc8732d9e6da43b39f/uuid_utils-0.14.1-cp39-abi3-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:043fb58fde6cf1620a6c066382f04f87a8e74feb0f95a585e4ed46f5d44af57b", size = 372205, upload-time = "2026-02-20T22:50:28.438Z" }, + { url = "https://files.pythonhosted.org/packages/c7/d9/3d2eb98af94b8dfffc82b6a33b4dfc87b0a5de2c68a28f6dde0db1f8681b/uuid_utils-0.14.1-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:c915d53f22945e55fe0d3d3b0b87fd965a57f5fd15666fd92d6593a73b1dd297", size = 521836, upload-time = "2026-02-20T22:50:23.057Z" }, + { url = "https://files.pythonhosted.org/packages/a8/15/0eb106cc6fe182f7577bc0ab6e2f0a40be247f35c5e297dbf7bbc460bd02/uuid_utils-0.14.1-cp39-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:0972488e3f9b449e83f006ead5a0e0a33ad4a13e4462e865b7c286ab7d7566a3", size = 625260, upload-time = "2026-02-20T22:50:25.949Z" }, + { url = "https://files.pythonhosted.org/packages/3c/17/f539507091334b109e7496830af2f093d9fc8082411eafd3ece58af1f8ba/uuid_utils-0.14.1-cp39-abi3-musllinux_1_2_i686.whl", hash = "sha256:1c238812ae0c8ffe77d8d447a32c6dfd058ea4631246b08b5a71df586ff08531", size = 587824, upload-time = "2026-02-20T22:50:35.225Z" }, + { url = "https://files.pythonhosted.org/packages/2e/c2/d37a7b2e41f153519367d4db01f0526e0d4b06f1a4a87f1c5dfca5d70a8b/uuid_utils-0.14.1-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:bec8f8ef627af86abf8298e7ec50926627e29b34fa907fcfbedb45aaa72bca43", size = 551407, upload-time = "2026-02-20T22:50:44.915Z" }, + { url = "https://files.pythonhosted.org/packages/65/36/2d24b2cbe78547c6532da33fb8613debd3126eccc33a6374ab788f5e46e9/uuid_utils-0.14.1-cp39-abi3-win32.whl", hash = "sha256:b54d6aa6252d96bac1fdbc80d26ba71bad9f220b2724d692ad2f2310c22ef523", size = 183476, upload-time = "2026-02-20T22:50:32.745Z" }, + { url = "https://files.pythonhosted.org/packages/83/92/2d7e90df8b1a69ec4cff33243ce02b7a62f926ef9e2f0eca5a026889cd73/uuid_utils-0.14.1-cp39-abi3-win_amd64.whl", hash = "sha256:fc27638c2ce267a0ce3e06828aff786f91367f093c80625ee21dad0208e0f5ba", size = 187147, upload-time = "2026-02-20T22:50:45.807Z" }, + { url = "https://files.pythonhosted.org/packages/d9/26/529f4beee17e5248e37e0bc17a2761d34c0fa3b1e5729c88adb2065bae6e/uuid_utils-0.14.1-cp39-abi3-win_arm64.whl", hash = "sha256:b04cb49b42afbc4ff8dbc60cf054930afc479d6f4dd7f1ec3bbe5dbfdde06b7a", size = 188132, upload-time = "2026-02-20T22:50:41.718Z" }, +] + [[package]] name = "uvicorn" version = "0.42.0" @@ -1449,6 +2401,27 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/e4/16/c1fd27e9549f3c4baf1dc9c20c456cd2f822dbf8de9f463824b0c0357e06/uvloop-0.22.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6cde23eeda1a25c75b2e07d39970f3374105d5eafbaab2a4482be82f272d5a5e", size = 4296730, upload-time = "2025-10-16T22:17:00.744Z" }, ] +[[package]] +name = "voyageai" +version = "0.3.7" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "aiohttp" }, + { name = "aiolimiter" }, + { name = "ffmpeg-python" }, + { name = "langchain-text-splitters" }, + { name = "numpy", marker = "python_full_version < '3.14'" }, + { name = "pillow" }, + { name = "pydantic" }, + { name = "requests" }, + { name = "tenacity" }, + { name = "tokenizers" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/94/16/1b46b3cd401e1717a68197c1fe336d7bb4e0a1833f8105e1738f5b1add05/voyageai-0.3.7.tar.gz", hash = "sha256:826cd97f97223f42b5babc5c459c9c80f3a8215ce5c0e007b0b276550f790d24", size = 26485, upload-time = "2025-12-16T18:43:05.26Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/60/64/89f6325666d6836979f94ac88b96fefc7527e02e61abc81359843585e088/voyageai-0.3.7-py3-none-any.whl", hash = "sha256:909f6c033001e5a3b3caf970525bf3614a1bfef9003cf3c3b68207dfdb53e86d", size = 34691, upload-time = "2025-12-16T18:43:04.073Z" }, +] + [[package]] name = "watchfiles" version = "1.1.1" @@ -1564,6 +2537,193 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/6f/28/258ebab549c2bf3e64d2b0217b973467394a9cea8c42f70418ca2c5d0d2e/websockets-16.0-py3-none-any.whl", hash = "sha256:1637db62fad1dc833276dded54215f2c7fa46912301a24bd94d45d46a011ceec", size = 171598, upload-time = "2026-01-10T09:23:45.395Z" }, ] +[[package]] +name = "xxhash" +version = "3.6.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/02/84/30869e01909fb37a6cc7e18688ee8bf1e42d57e7e0777636bd47524c43c7/xxhash-3.6.0.tar.gz", hash = "sha256:f0162a78b13a0d7617b2845b90c763339d1f1d82bb04a4b07f4ab535cc5e05d6", size = 85160, upload-time = "2025-10-02T14:37:08.097Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9a/07/d9412f3d7d462347e4511181dea65e47e0d0e16e26fbee2ea86a2aefb657/xxhash-3.6.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:01362c4331775398e7bb34e3ab403bc9ee9f7c497bc7dee6272114055277dd3c", size = 32744, upload-time = "2025-10-02T14:34:34.622Z" }, + { url = "https://files.pythonhosted.org/packages/79/35/0429ee11d035fc33abe32dca1b2b69e8c18d236547b9a9b72c1929189b9a/xxhash-3.6.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:b7b2df81a23f8cb99656378e72501b2cb41b1827c0f5a86f87d6b06b69f9f204", size = 30816, upload-time = "2025-10-02T14:34:36.043Z" }, + { url = "https://files.pythonhosted.org/packages/b7/f2/57eb99aa0f7d98624c0932c5b9a170e1806406cdbcdb510546634a1359e0/xxhash-3.6.0-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:dc94790144e66b14f67b10ac8ed75b39ca47536bf8800eb7c24b50271ea0c490", size = 194035, upload-time = "2025-10-02T14:34:37.354Z" }, + { url = "https://files.pythonhosted.org/packages/4c/ed/6224ba353690d73af7a3f1c7cdb1fc1b002e38f783cb991ae338e1eb3d79/xxhash-3.6.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:93f107c673bccf0d592cdba077dedaf52fe7f42dcd7676eba1f6d6f0c3efffd2", size = 212914, upload-time = "2025-10-02T14:34:38.6Z" }, + { url = "https://files.pythonhosted.org/packages/38/86/fb6b6130d8dd6b8942cc17ab4d90e223653a89aa32ad2776f8af7064ed13/xxhash-3.6.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2aa5ee3444c25b69813663c9f8067dcfaa2e126dc55e8dddf40f4d1c25d7effa", size = 212163, upload-time = "2025-10-02T14:34:39.872Z" }, + { url = "https://files.pythonhosted.org/packages/ee/dc/e84875682b0593e884ad73b2d40767b5790d417bde603cceb6878901d647/xxhash-3.6.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f7f99123f0e1194fa59cc69ad46dbae2e07becec5df50a0509a808f90a0f03f0", size = 445411, upload-time = "2025-10-02T14:34:41.569Z" }, + { url = "https://files.pythonhosted.org/packages/11/4f/426f91b96701ec2f37bb2b8cec664eff4f658a11f3fa9d94f0a887ea6d2b/xxhash-3.6.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:49e03e6fe2cac4a1bc64952dd250cf0dbc5ef4ebb7b8d96bce82e2de163c82a2", size = 193883, upload-time = "2025-10-02T14:34:43.249Z" }, + { url = "https://files.pythonhosted.org/packages/53/5a/ddbb83eee8e28b778eacfc5a85c969673e4023cdeedcfcef61f36731610b/xxhash-3.6.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:bd17fede52a17a4f9a7bc4472a5867cb0b160deeb431795c0e4abe158bc784e9", size = 210392, upload-time = "2025-10-02T14:34:45.042Z" }, + { url = "https://files.pythonhosted.org/packages/1e/c2/ff69efd07c8c074ccdf0a4f36fcdd3d27363665bcdf4ba399abebe643465/xxhash-3.6.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:6fb5f5476bef678f69db04f2bd1efbed3030d2aba305b0fc1773645f187d6a4e", size = 197898, upload-time = "2025-10-02T14:34:46.302Z" }, + { url = "https://files.pythonhosted.org/packages/58/ca/faa05ac19b3b622c7c9317ac3e23954187516298a091eb02c976d0d3dd45/xxhash-3.6.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:843b52f6d88071f87eba1631b684fcb4b2068cd2180a0224122fe4ef011a9374", size = 210655, upload-time = "2025-10-02T14:34:47.571Z" }, + { url = "https://files.pythonhosted.org/packages/d4/7a/06aa7482345480cc0cb597f5c875b11a82c3953f534394f620b0be2f700c/xxhash-3.6.0-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:7d14a6cfaf03b1b6f5f9790f76880601ccc7896aff7ab9cd8978a939c1eb7e0d", size = 414001, upload-time = "2025-10-02T14:34:49.273Z" }, + { url = "https://files.pythonhosted.org/packages/23/07/63ffb386cd47029aa2916b3d2f454e6cc5b9f5c5ada3790377d5430084e7/xxhash-3.6.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:418daf3db71e1413cfe211c2f9a528456936645c17f46b5204705581a45390ae", size = 191431, upload-time = "2025-10-02T14:34:50.798Z" }, + { url = "https://files.pythonhosted.org/packages/0f/93/14fde614cadb4ddf5e7cebf8918b7e8fac5ae7861c1875964f17e678205c/xxhash-3.6.0-cp312-cp312-win32.whl", hash = "sha256:50fc255f39428a27299c20e280d6193d8b63b8ef8028995323bf834a026b4fbb", size = 30617, upload-time = "2025-10-02T14:34:51.954Z" }, + { url = "https://files.pythonhosted.org/packages/13/5d/0d125536cbe7565a83d06e43783389ecae0c0f2ed037b48ede185de477c0/xxhash-3.6.0-cp312-cp312-win_amd64.whl", hash = "sha256:c0f2ab8c715630565ab8991b536ecded9416d615538be8ecddce43ccf26cbc7c", size = 31534, upload-time = "2025-10-02T14:34:53.276Z" }, + { url = "https://files.pythonhosted.org/packages/54/85/6ec269b0952ec7e36ba019125982cf11d91256a778c7c3f98a4c5043d283/xxhash-3.6.0-cp312-cp312-win_arm64.whl", hash = "sha256:eae5c13f3bc455a3bbb68bdc513912dc7356de7e2280363ea235f71f54064829", size = 27876, upload-time = "2025-10-02T14:34:54.371Z" }, + { url = "https://files.pythonhosted.org/packages/33/76/35d05267ac82f53ae9b0e554da7c5e281ee61f3cad44c743f0fcd354f211/xxhash-3.6.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:599e64ba7f67472481ceb6ee80fa3bd828fd61ba59fb11475572cc5ee52b89ec", size = 32738, upload-time = "2025-10-02T14:34:55.839Z" }, + { url = "https://files.pythonhosted.org/packages/31/a8/3fbce1cd96534a95e35d5120637bf29b0d7f5d8fa2f6374e31b4156dd419/xxhash-3.6.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:7d8b8aaa30fca4f16f0c84a5c8d7ddee0e25250ec2796c973775373257dde8f1", size = 30821, upload-time = "2025-10-02T14:34:57.219Z" }, + { url = "https://files.pythonhosted.org/packages/0c/ea/d387530ca7ecfa183cb358027f1833297c6ac6098223fd14f9782cd0015c/xxhash-3.6.0-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:d597acf8506d6e7101a4a44a5e428977a51c0fadbbfd3c39650cca9253f6e5a6", size = 194127, upload-time = "2025-10-02T14:34:59.21Z" }, + { url = "https://files.pythonhosted.org/packages/ba/0c/71435dcb99874b09a43b8d7c54071e600a7481e42b3e3ce1eb5226a5711a/xxhash-3.6.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:858dc935963a33bc33490128edc1c12b0c14d9c7ebaa4e387a7869ecc4f3e263", size = 212975, upload-time = "2025-10-02T14:35:00.816Z" }, + { url = "https://files.pythonhosted.org/packages/84/7a/c2b3d071e4bb4a90b7057228a99b10d51744878f4a8a6dd643c8bd897620/xxhash-3.6.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ba284920194615cb8edf73bf52236ce2e1664ccd4a38fdb543506413529cc546", size = 212241, upload-time = "2025-10-02T14:35:02.207Z" }, + { url = "https://files.pythonhosted.org/packages/81/5f/640b6eac0128e215f177df99eadcd0f1b7c42c274ab6a394a05059694c5a/xxhash-3.6.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:4b54219177f6c6674d5378bd862c6aedf64725f70dd29c472eaae154df1a2e89", size = 445471, upload-time = "2025-10-02T14:35:03.61Z" }, + { url = "https://files.pythonhosted.org/packages/5e/1e/3c3d3ef071b051cc3abbe3721ffb8365033a172613c04af2da89d5548a87/xxhash-3.6.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:42c36dd7dbad2f5238950c377fcbf6811b1cdb1c444fab447960030cea60504d", size = 193936, upload-time = "2025-10-02T14:35:05.013Z" }, + { url = "https://files.pythonhosted.org/packages/2c/bd/4a5f68381939219abfe1c22a9e3a5854a4f6f6f3c4983a87d255f21f2e5d/xxhash-3.6.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f22927652cba98c44639ffdc7aaf35828dccf679b10b31c4ad72a5b530a18eb7", size = 210440, upload-time = "2025-10-02T14:35:06.239Z" }, + { url = "https://files.pythonhosted.org/packages/eb/37/b80fe3d5cfb9faff01a02121a0f4d565eb7237e9e5fc66e73017e74dcd36/xxhash-3.6.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:b45fad44d9c5c119e9c6fbf2e1c656a46dc68e280275007bbfd3d572b21426db", size = 197990, upload-time = "2025-10-02T14:35:07.735Z" }, + { url = "https://files.pythonhosted.org/packages/d7/fd/2c0a00c97b9e18f72e1f240ad4e8f8a90fd9d408289ba9c7c495ed7dc05c/xxhash-3.6.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:6f2580ffab1a8b68ef2b901cde7e55fa8da5e4be0977c68f78fc80f3c143de42", size = 210689, upload-time = "2025-10-02T14:35:09.438Z" }, + { url = "https://files.pythonhosted.org/packages/93/86/5dd8076a926b9a95db3206aba20d89a7fc14dd5aac16e5c4de4b56033140/xxhash-3.6.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:40c391dd3cd041ebc3ffe6f2c862f402e306eb571422e0aa918d8070ba31da11", size = 414068, upload-time = "2025-10-02T14:35:11.162Z" }, + { url = "https://files.pythonhosted.org/packages/af/3c/0bb129170ee8f3650f08e993baee550a09593462a5cddd8e44d0011102b1/xxhash-3.6.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:f205badabde7aafd1a31e8ca2a3e5a763107a71c397c4481d6a804eb5063d8bd", size = 191495, upload-time = "2025-10-02T14:35:12.971Z" }, + { url = "https://files.pythonhosted.org/packages/e9/3a/6797e0114c21d1725e2577508e24006fd7ff1d8c0c502d3b52e45c1771d8/xxhash-3.6.0-cp313-cp313-win32.whl", hash = "sha256:2577b276e060b73b73a53042ea5bd5203d3e6347ce0d09f98500f418a9fcf799", size = 30620, upload-time = "2025-10-02T14:35:14.129Z" }, + { url = "https://files.pythonhosted.org/packages/86/15/9bc32671e9a38b413a76d24722a2bf8784a132c043063a8f5152d390b0f9/xxhash-3.6.0-cp313-cp313-win_amd64.whl", hash = "sha256:757320d45d2fbcce8f30c42a6b2f47862967aea7bf458b9625b4bbe7ee390392", size = 31542, upload-time = "2025-10-02T14:35:15.21Z" }, + { url = "https://files.pythonhosted.org/packages/39/c5/cc01e4f6188656e56112d6a8e0dfe298a16934b8c47a247236549a3f7695/xxhash-3.6.0-cp313-cp313-win_arm64.whl", hash = "sha256:457b8f85dec5825eed7b69c11ae86834a018b8e3df5e77783c999663da2f96d6", size = 27880, upload-time = "2025-10-02T14:35:16.315Z" }, + { url = "https://files.pythonhosted.org/packages/f3/30/25e5321c8732759e930c555176d37e24ab84365482d257c3b16362235212/xxhash-3.6.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:a42e633d75cdad6d625434e3468126c73f13f7584545a9cf34e883aa1710e702", size = 32956, upload-time = "2025-10-02T14:35:17.413Z" }, + { url = "https://files.pythonhosted.org/packages/9f/3c/0573299560d7d9f8ab1838f1efc021a280b5ae5ae2e849034ef3dee18810/xxhash-3.6.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:568a6d743219e717b07b4e03b0a828ce593833e498c3b64752e0f5df6bfe84db", size = 31072, upload-time = "2025-10-02T14:35:18.844Z" }, + { url = "https://files.pythonhosted.org/packages/7a/1c/52d83a06e417cd9d4137722693424885cc9878249beb3a7c829e74bf7ce9/xxhash-3.6.0-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:bec91b562d8012dae276af8025a55811b875baace6af510412a5e58e3121bc54", size = 196409, upload-time = "2025-10-02T14:35:20.31Z" }, + { url = "https://files.pythonhosted.org/packages/e3/8e/c6d158d12a79bbd0b878f8355432075fc82759e356ab5a111463422a239b/xxhash-3.6.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:78e7f2f4c521c30ad5e786fdd6bae89d47a32672a80195467b5de0480aa97b1f", size = 215736, upload-time = "2025-10-02T14:35:21.616Z" }, + { url = "https://files.pythonhosted.org/packages/bc/68/c4c80614716345d55071a396cf03d06e34b5f4917a467faf43083c995155/xxhash-3.6.0-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:3ed0df1b11a79856df5ffcab572cbd6b9627034c1c748c5566fa79df9048a7c5", size = 214833, upload-time = "2025-10-02T14:35:23.32Z" }, + { url = "https://files.pythonhosted.org/packages/7e/e9/ae27c8ffec8b953efa84c7c4a6c6802c263d587b9fc0d6e7cea64e08c3af/xxhash-3.6.0-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:0e4edbfc7d420925b0dd5e792478ed393d6e75ff8fc219a6546fb446b6a417b1", size = 448348, upload-time = "2025-10-02T14:35:25.111Z" }, + { url = "https://files.pythonhosted.org/packages/d7/6b/33e21afb1b5b3f46b74b6bd1913639066af218d704cc0941404ca717fc57/xxhash-3.6.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fba27a198363a7ef87f8c0f6b171ec36b674fe9053742c58dd7e3201c1ab30ee", size = 196070, upload-time = "2025-10-02T14:35:26.586Z" }, + { url = "https://files.pythonhosted.org/packages/96/b6/fcabd337bc5fa624e7203aa0fa7d0c49eed22f72e93229431752bddc83d9/xxhash-3.6.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:794fe9145fe60191c6532fa95063765529770edcdd67b3d537793e8004cabbfd", size = 212907, upload-time = "2025-10-02T14:35:28.087Z" }, + { url = "https://files.pythonhosted.org/packages/4b/d3/9ee6160e644d660fcf176c5825e61411c7f62648728f69c79ba237250143/xxhash-3.6.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:6105ef7e62b5ac73a837778efc331a591d8442f8ef5c7e102376506cb4ae2729", size = 200839, upload-time = "2025-10-02T14:35:29.857Z" }, + { url = "https://files.pythonhosted.org/packages/0d/98/e8de5baa5109394baf5118f5e72ab21a86387c4f89b0e77ef3e2f6b0327b/xxhash-3.6.0-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:f01375c0e55395b814a679b3eea205db7919ac2af213f4a6682e01220e5fe292", size = 213304, upload-time = "2025-10-02T14:35:31.222Z" }, + { url = "https://files.pythonhosted.org/packages/7b/1d/71056535dec5c3177eeb53e38e3d367dd1d16e024e63b1cee208d572a033/xxhash-3.6.0-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:d706dca2d24d834a4661619dcacf51a75c16d65985718d6a7d73c1eeeb903ddf", size = 416930, upload-time = "2025-10-02T14:35:32.517Z" }, + { url = "https://files.pythonhosted.org/packages/dc/6c/5cbde9de2cd967c322e651c65c543700b19e7ae3e0aae8ece3469bf9683d/xxhash-3.6.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:5f059d9faeacd49c0215d66f4056e1326c80503f51a1532ca336a385edadd033", size = 193787, upload-time = "2025-10-02T14:35:33.827Z" }, + { url = "https://files.pythonhosted.org/packages/19/fa/0172e350361d61febcea941b0cc541d6e6c8d65d153e85f850a7b256ff8a/xxhash-3.6.0-cp313-cp313t-win32.whl", hash = "sha256:1244460adc3a9be84731d72b8e80625788e5815b68da3da8b83f78115a40a7ec", size = 30916, upload-time = "2025-10-02T14:35:35.107Z" }, + { url = "https://files.pythonhosted.org/packages/ad/e6/e8cf858a2b19d6d45820f072eff1bea413910592ff17157cabc5f1227a16/xxhash-3.6.0-cp313-cp313t-win_amd64.whl", hash = "sha256:b1e420ef35c503869c4064f4a2f2b08ad6431ab7b229a05cce39d74268bca6b8", size = 31799, upload-time = "2025-10-02T14:35:36.165Z" }, + { url = "https://files.pythonhosted.org/packages/56/15/064b197e855bfb7b343210e82490ae672f8bc7cdf3ddb02e92f64304ee8a/xxhash-3.6.0-cp313-cp313t-win_arm64.whl", hash = "sha256:ec44b73a4220623235f67a996c862049f375df3b1052d9899f40a6382c32d746", size = 28044, upload-time = "2025-10-02T14:35:37.195Z" }, + { url = "https://files.pythonhosted.org/packages/7e/5e/0138bc4484ea9b897864d59fce9be9086030825bc778b76cb5a33a906d37/xxhash-3.6.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:a40a3d35b204b7cc7643cbcf8c9976d818cb47befcfac8bbefec8038ac363f3e", size = 32754, upload-time = "2025-10-02T14:35:38.245Z" }, + { url = "https://files.pythonhosted.org/packages/18/d7/5dac2eb2ec75fd771957a13e5dda560efb2176d5203f39502a5fc571f899/xxhash-3.6.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:a54844be970d3fc22630b32d515e79a90d0a3ddb2644d8d7402e3c4c8da61405", size = 30846, upload-time = "2025-10-02T14:35:39.6Z" }, + { url = "https://files.pythonhosted.org/packages/fe/71/8bc5be2bb00deb5682e92e8da955ebe5fa982da13a69da5a40a4c8db12fb/xxhash-3.6.0-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:016e9190af8f0a4e3741343777710e3d5717427f175adfdc3e72508f59e2a7f3", size = 194343, upload-time = "2025-10-02T14:35:40.69Z" }, + { url = "https://files.pythonhosted.org/packages/e7/3b/52badfb2aecec2c377ddf1ae75f55db3ba2d321c5e164f14461c90837ef3/xxhash-3.6.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4f6f72232f849eb9d0141e2ebe2677ece15adfd0fa599bc058aad83c714bb2c6", size = 213074, upload-time = "2025-10-02T14:35:42.29Z" }, + { url = "https://files.pythonhosted.org/packages/a2/2b/ae46b4e9b92e537fa30d03dbc19cdae57ed407e9c26d163895e968e3de85/xxhash-3.6.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:63275a8aba7865e44b1813d2177e0f5ea7eadad3dd063a21f7cf9afdc7054063", size = 212388, upload-time = "2025-10-02T14:35:43.929Z" }, + { url = "https://files.pythonhosted.org/packages/f5/80/49f88d3afc724b4ac7fbd664c8452d6db51b49915be48c6982659e0e7942/xxhash-3.6.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3cd01fa2aa00d8b017c97eb46b9a794fbdca53fc14f845f5a328c71254b0abb7", size = 445614, upload-time = "2025-10-02T14:35:45.216Z" }, + { url = "https://files.pythonhosted.org/packages/ed/ba/603ce3961e339413543d8cd44f21f2c80e2a7c5cfe692a7b1f2cccf58f3c/xxhash-3.6.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0226aa89035b62b6a86d3c68df4d7c1f47a342b8683da2b60cedcddb46c4d95b", size = 194024, upload-time = "2025-10-02T14:35:46.959Z" }, + { url = "https://files.pythonhosted.org/packages/78/d1/8e225ff7113bf81545cfdcd79eef124a7b7064a0bba53605ff39590b95c2/xxhash-3.6.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c6e193e9f56e4ca4923c61238cdaced324f0feac782544eb4c6d55ad5cc99ddd", size = 210541, upload-time = "2025-10-02T14:35:48.301Z" }, + { url = "https://files.pythonhosted.org/packages/6f/58/0f89d149f0bad89def1a8dd38feb50ccdeb643d9797ec84707091d4cb494/xxhash-3.6.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:9176dcaddf4ca963d4deb93866d739a343c01c969231dbe21680e13a5d1a5bf0", size = 198305, upload-time = "2025-10-02T14:35:49.584Z" }, + { url = "https://files.pythonhosted.org/packages/11/38/5eab81580703c4df93feb5f32ff8fa7fe1e2c51c1f183ee4e48d4bb9d3d7/xxhash-3.6.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:c1ce4009c97a752e682b897aa99aef84191077a9433eb237774689f14f8ec152", size = 210848, upload-time = "2025-10-02T14:35:50.877Z" }, + { url = "https://files.pythonhosted.org/packages/5e/6b/953dc4b05c3ce678abca756416e4c130d2382f877a9c30a20d08ee6a77c0/xxhash-3.6.0-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:8cb2f4f679b01513b7adbb9b1b2f0f9cdc31b70007eaf9d59d0878809f385b11", size = 414142, upload-time = "2025-10-02T14:35:52.15Z" }, + { url = "https://files.pythonhosted.org/packages/08/a9/238ec0d4e81a10eb5026d4a6972677cbc898ba6c8b9dbaec12ae001b1b35/xxhash-3.6.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:653a91d7c2ab54a92c19ccf43508b6a555440b9be1bc8be553376778be7f20b5", size = 191547, upload-time = "2025-10-02T14:35:53.547Z" }, + { url = "https://files.pythonhosted.org/packages/f1/ee/3cf8589e06c2164ac77c3bf0aa127012801128f1feebf2a079272da5737c/xxhash-3.6.0-cp314-cp314-win32.whl", hash = "sha256:a756fe893389483ee8c394d06b5ab765d96e68fbbfe6fde7aa17e11f5720559f", size = 31214, upload-time = "2025-10-02T14:35:54.746Z" }, + { url = "https://files.pythonhosted.org/packages/02/5d/a19552fbc6ad4cb54ff953c3908bbc095f4a921bc569433d791f755186f1/xxhash-3.6.0-cp314-cp314-win_amd64.whl", hash = "sha256:39be8e4e142550ef69629c9cd71b88c90e9a5db703fecbcf265546d9536ca4ad", size = 32290, upload-time = "2025-10-02T14:35:55.791Z" }, + { url = "https://files.pythonhosted.org/packages/b1/11/dafa0643bc30442c887b55baf8e73353a344ee89c1901b5a5c54a6c17d39/xxhash-3.6.0-cp314-cp314-win_arm64.whl", hash = "sha256:25915e6000338999236f1eb68a02a32c3275ac338628a7eaa5a269c401995679", size = 28795, upload-time = "2025-10-02T14:35:57.162Z" }, + { url = "https://files.pythonhosted.org/packages/2c/db/0e99732ed7f64182aef4a6fb145e1a295558deec2a746265dcdec12d191e/xxhash-3.6.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:c5294f596a9017ca5a3e3f8884c00b91ab2ad2933cf288f4923c3fd4346cf3d4", size = 32955, upload-time = "2025-10-02T14:35:58.267Z" }, + { url = "https://files.pythonhosted.org/packages/55/f4/2a7c3c68e564a099becfa44bb3d398810cc0ff6749b0d3cb8ccb93f23c14/xxhash-3.6.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1cf9dcc4ab9cff01dfbba78544297a3a01dafd60f3bde4e2bfd016cf7e4ddc67", size = 31072, upload-time = "2025-10-02T14:35:59.382Z" }, + { url = "https://files.pythonhosted.org/packages/c6/d9/72a29cddc7250e8a5819dad5d466facb5dc4c802ce120645630149127e73/xxhash-3.6.0-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:01262da8798422d0685f7cef03b2bd3f4f46511b02830861df548d7def4402ad", size = 196579, upload-time = "2025-10-02T14:36:00.838Z" }, + { url = "https://files.pythonhosted.org/packages/63/93/b21590e1e381040e2ca305a884d89e1c345b347404f7780f07f2cdd47ef4/xxhash-3.6.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:51a73fb7cb3a3ead9f7a8b583ffd9b8038e277cdb8cb87cf890e88b3456afa0b", size = 215854, upload-time = "2025-10-02T14:36:02.207Z" }, + { url = "https://files.pythonhosted.org/packages/ce/b8/edab8a7d4fa14e924b29be877d54155dcbd8b80be85ea00d2be3413a9ed4/xxhash-3.6.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:b9c6df83594f7df8f7f708ce5ebeacfc69f72c9fbaaababf6cf4758eaada0c9b", size = 214965, upload-time = "2025-10-02T14:36:03.507Z" }, + { url = "https://files.pythonhosted.org/packages/27/67/dfa980ac7f0d509d54ea0d5a486d2bb4b80c3f1bb22b66e6a05d3efaf6c0/xxhash-3.6.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:627f0af069b0ea56f312fd5189001c24578868643203bca1abbc2c52d3a6f3ca", size = 448484, upload-time = "2025-10-02T14:36:04.828Z" }, + { url = "https://files.pythonhosted.org/packages/8c/63/8ffc2cc97e811c0ca5d00ab36604b3ea6f4254f20b7bc658ca825ce6c954/xxhash-3.6.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:aa912c62f842dfd013c5f21a642c9c10cd9f4c4e943e0af83618b4a404d9091a", size = 196162, upload-time = "2025-10-02T14:36:06.182Z" }, + { url = "https://files.pythonhosted.org/packages/4b/77/07f0e7a3edd11a6097e990f6e5b815b6592459cb16dae990d967693e6ea9/xxhash-3.6.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:b465afd7909db30168ab62afe40b2fcf79eedc0b89a6c0ab3123515dc0df8b99", size = 213007, upload-time = "2025-10-02T14:36:07.733Z" }, + { url = "https://files.pythonhosted.org/packages/ae/d8/bc5fa0d152837117eb0bef6f83f956c509332ce133c91c63ce07ee7c4873/xxhash-3.6.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:a881851cf38b0a70e7c4d3ce81fc7afd86fbc2a024f4cfb2a97cf49ce04b75d3", size = 200956, upload-time = "2025-10-02T14:36:09.106Z" }, + { url = "https://files.pythonhosted.org/packages/26/a5/d749334130de9411783873e9b98ecc46688dad5db64ca6e04b02acc8b473/xxhash-3.6.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:9b3222c686a919a0f3253cfc12bb118b8b103506612253b5baeaac10d8027cf6", size = 213401, upload-time = "2025-10-02T14:36:10.585Z" }, + { url = "https://files.pythonhosted.org/packages/89/72/abed959c956a4bfc72b58c0384bb7940663c678127538634d896b1195c10/xxhash-3.6.0-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:c5aa639bc113e9286137cec8fadc20e9cd732b2cc385c0b7fa673b84fc1f2a93", size = 417083, upload-time = "2025-10-02T14:36:12.276Z" }, + { url = "https://files.pythonhosted.org/packages/0c/b3/62fd2b586283b7d7d665fb98e266decadf31f058f1cf6c478741f68af0cb/xxhash-3.6.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5c1343d49ac102799905e115aee590183c3921d475356cb24b4de29a4bc56518", size = 193913, upload-time = "2025-10-02T14:36:14.025Z" }, + { url = "https://files.pythonhosted.org/packages/9a/9a/c19c42c5b3f5a4aad748a6d5b4f23df3bed7ee5445accc65a0fb3ff03953/xxhash-3.6.0-cp314-cp314t-win32.whl", hash = "sha256:5851f033c3030dd95c086b4a36a2683c2ff4a799b23af60977188b057e467119", size = 31586, upload-time = "2025-10-02T14:36:15.603Z" }, + { url = "https://files.pythonhosted.org/packages/03/d6/4cc450345be9924fd5dc8c590ceda1db5b43a0a889587b0ae81a95511360/xxhash-3.6.0-cp314-cp314t-win_amd64.whl", hash = "sha256:0444e7967dac37569052d2409b00a8860c2135cff05502df4da80267d384849f", size = 32526, upload-time = "2025-10-02T14:36:16.708Z" }, + { url = "https://files.pythonhosted.org/packages/0f/c9/7243eb3f9eaabd1a88a5a5acadf06df2d83b100c62684b7425c6a11bcaa8/xxhash-3.6.0-cp314-cp314t-win_arm64.whl", hash = "sha256:bb79b1e63f6fd84ec778a4b1916dfe0a7c3fdb986c06addd5db3a0d413819d95", size = 28898, upload-time = "2025-10-02T14:36:17.843Z" }, +] + +[[package]] +name = "yarl" +version = "1.23.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "idna" }, + { name = "multidict" }, + { name = "propcache" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/23/6e/beb1beec874a72f23815c1434518bfc4ed2175065173fb138c3705f658d4/yarl-1.23.0.tar.gz", hash = "sha256:53b1ea6ca88ebd4420379c330aea57e258408dd0df9af0992e5de2078dc9f5d5", size = 194676, upload-time = "2026-03-01T22:07:53.373Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/88/8a/94615bc31022f711add374097ad4144d569e95ff3c38d39215d07ac153a0/yarl-1.23.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:1932b6b8bba8d0160a9d1078aae5838a66039e8832d41d2992daa9a3a08f7860", size = 124737, upload-time = "2026-03-01T22:05:12.897Z" }, + { url = "https://files.pythonhosted.org/packages/e3/6f/c6554045d59d64052698add01226bc867b52fe4a12373415d7991fdca95d/yarl-1.23.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:411225bae281f114067578891bc75534cfb3d92a3b4dfef7a6ca78ba354e6069", size = 87029, upload-time = "2026-03-01T22:05:14.376Z" }, + { url = "https://files.pythonhosted.org/packages/19/2a/725ecc166d53438bc88f76822ed4b1e3b10756e790bafd7b523fe97c322d/yarl-1.23.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:13a563739ae600a631c36ce096615fe307f131344588b0bc0daec108cdb47b25", size = 86310, upload-time = "2026-03-01T22:05:15.71Z" }, + { url = "https://files.pythonhosted.org/packages/99/30/58260ed98e6ff7f90ba84442c1ddd758c9170d70327394a6227b310cd60f/yarl-1.23.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9cbf44c5cb4a7633d078788e1b56387e3d3cf2b8139a3be38040b22d6c3221c8", size = 97587, upload-time = "2026-03-01T22:05:17.384Z" }, + { url = "https://files.pythonhosted.org/packages/76/0a/8b08aac08b50682e65759f7f8dde98ae8168f72487e7357a5d684c581ef9/yarl-1.23.0-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:53ad387048f6f09a8969631e4de3f1bf70c50e93545d64af4f751b2498755072", size = 92528, upload-time = "2026-03-01T22:05:18.804Z" }, + { url = "https://files.pythonhosted.org/packages/52/07/0b7179101fe5f8385ec6c6bb5d0cb9f76bd9fb4a769591ab6fb5cdbfc69a/yarl-1.23.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:4a59ba56f340334766f3a4442e0efd0af895fae9e2b204741ef885c446b3a1a8", size = 105339, upload-time = "2026-03-01T22:05:20.235Z" }, + { url = "https://files.pythonhosted.org/packages/d3/8a/36d82869ab5ec829ca8574dfcb92b51286fcfb1e9c7a73659616362dc880/yarl-1.23.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:803a3c3ce4acc62eaf01eaca1208dcf0783025ef27572c3336502b9c232005e7", size = 105061, upload-time = "2026-03-01T22:05:22.268Z" }, + { url = "https://files.pythonhosted.org/packages/66/3e/868e5c3364b6cee19ff3e1a122194fa4ce51def02c61023970442162859e/yarl-1.23.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a3d2bff8f37f8d0f96c7ec554d16945050d54462d6e95414babaa18bfafc7f51", size = 100132, upload-time = "2026-03-01T22:05:23.638Z" }, + { url = "https://files.pythonhosted.org/packages/cf/26/9c89acf82f08a52cb52d6d39454f8d18af15f9d386a23795389d1d423823/yarl-1.23.0-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c75eb09e8d55bceb4367e83496ff8ef2bc7ea6960efb38e978e8073ea59ecb67", size = 99289, upload-time = "2026-03-01T22:05:25.749Z" }, + { url = "https://files.pythonhosted.org/packages/6f/54/5b0db00d2cb056922356104468019c0a132e89c8d3ab67d8ede9f4483d2a/yarl-1.23.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:877b0738624280e34c55680d6054a307aa94f7d52fa0e3034a9cc6e790871da7", size = 96950, upload-time = "2026-03-01T22:05:27.318Z" }, + { url = "https://files.pythonhosted.org/packages/f6/40/10fa93811fd439341fad7e0718a86aca0de9548023bbb403668d6555acab/yarl-1.23.0-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:b5405bb8f0e783a988172993cfc627e4d9d00432d6bbac65a923041edacf997d", size = 93960, upload-time = "2026-03-01T22:05:28.738Z" }, + { url = "https://files.pythonhosted.org/packages/bc/d2/8ae2e6cd77d0805f4526e30ec43b6f9a3dfc542d401ac4990d178e4bf0cf/yarl-1.23.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:1c3a3598a832590c5a3ce56ab5576361b5688c12cb1d39429cf5dba30b510760", size = 104703, upload-time = "2026-03-01T22:05:30.438Z" }, + { url = "https://files.pythonhosted.org/packages/2f/0c/b3ceacf82c3fe21183ce35fa2acf5320af003d52bc1fcf5915077681142e/yarl-1.23.0-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:8419ebd326430d1cbb7efb5292330a2cf39114e82df5cc3d83c9a0d5ebeaf2f2", size = 98325, upload-time = "2026-03-01T22:05:31.835Z" }, + { url = "https://files.pythonhosted.org/packages/9d/e0/12900edd28bdab91a69bd2554b85ad7b151f64e8b521fe16f9ad2f56477a/yarl-1.23.0-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:be61f6fff406ca40e3b1d84716fde398fc08bc63dd96d15f3a14230a0973ed86", size = 105067, upload-time = "2026-03-01T22:05:33.358Z" }, + { url = "https://files.pythonhosted.org/packages/15/61/74bb1182cf79c9bbe4eb6b1f14a57a22d7a0be5e9cedf8e2d5c2086474c3/yarl-1.23.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:3ceb13c5c858d01321b5d9bb65e4cf37a92169ea470b70fec6f236b2c9dd7e34", size = 100285, upload-time = "2026-03-01T22:05:35.4Z" }, + { url = "https://files.pythonhosted.org/packages/69/7f/cd5ef733f2550de6241bd8bd8c3febc78158b9d75f197d9c7baa113436af/yarl-1.23.0-cp312-cp312-win32.whl", hash = "sha256:fffc45637bcd6538de8b85f51e3df3223e4ad89bccbfca0481c08c7fc8b7ed7d", size = 82359, upload-time = "2026-03-01T22:05:36.811Z" }, + { url = "https://files.pythonhosted.org/packages/f5/be/25216a49daeeb7af2bec0db22d5e7df08ed1d7c9f65d78b14f3b74fd72fc/yarl-1.23.0-cp312-cp312-win_amd64.whl", hash = "sha256:f69f57305656a4852f2a7203efc661d8c042e6cc67f7acd97d8667fb448a426e", size = 87674, upload-time = "2026-03-01T22:05:38.171Z" }, + { url = "https://files.pythonhosted.org/packages/d2/35/aeab955d6c425b227d5b7247eafb24f2653fedc32f95373a001af5dfeb9e/yarl-1.23.0-cp312-cp312-win_arm64.whl", hash = "sha256:6e87a6e8735b44816e7db0b2fbc9686932df473c826b0d9743148432e10bb9b9", size = 81879, upload-time = "2026-03-01T22:05:40.006Z" }, + { url = "https://files.pythonhosted.org/packages/9a/4b/a0a6e5d0ee8a2f3a373ddef8a4097d74ac901ac363eea1440464ccbe0898/yarl-1.23.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:16c6994ac35c3e74fb0ae93323bf8b9c2a9088d55946109489667c510a7d010e", size = 123796, upload-time = "2026-03-01T22:05:41.412Z" }, + { url = "https://files.pythonhosted.org/packages/67/b6/8925d68af039b835ae876db5838e82e76ec87b9782ecc97e192b809c4831/yarl-1.23.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:4a42e651629dafb64fd5b0286a3580613702b5809ad3f24934ea87595804f2c5", size = 86547, upload-time = "2026-03-01T22:05:42.841Z" }, + { url = "https://files.pythonhosted.org/packages/ae/50/06d511cc4b8e0360d3c94af051a768e84b755c5eb031b12adaaab6dec6e5/yarl-1.23.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:7c6b9461a2a8b47c65eef63bb1c76a4f1c119618ffa99ea79bc5bb1e46c5821b", size = 85854, upload-time = "2026-03-01T22:05:44.85Z" }, + { url = "https://files.pythonhosted.org/packages/c4/f4/4e30b250927ffdab4db70da08b9b8d2194d7c7b400167b8fbeca1e4701ca/yarl-1.23.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2569b67d616eab450d262ca7cb9f9e19d2f718c70a8b88712859359d0ab17035", size = 98351, upload-time = "2026-03-01T22:05:46.836Z" }, + { url = "https://files.pythonhosted.org/packages/86/fc/4118c5671ea948208bdb1492d8b76bdf1453d3e73df051f939f563e7dcc5/yarl-1.23.0-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e9d9a4d06d3481eab79803beb4d9bd6f6a8e781ec078ac70d7ef2dcc29d1bea5", size = 92711, upload-time = "2026-03-01T22:05:48.316Z" }, + { url = "https://files.pythonhosted.org/packages/56/11/1ed91d42bd9e73c13dc9e7eb0dd92298d75e7ac4dd7f046ad0c472e231cd/yarl-1.23.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f514f6474e04179d3d33175ed3f3e31434d3130d42ec153540d5b157deefd735", size = 106014, upload-time = "2026-03-01T22:05:50.028Z" }, + { url = "https://files.pythonhosted.org/packages/ce/c9/74e44e056a23fbc33aca71779ef450ca648a5bc472bdad7a82339918f818/yarl-1.23.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:fda207c815b253e34f7e1909840fd14299567b1c0eb4908f8c2ce01a41265401", size = 105557, upload-time = "2026-03-01T22:05:51.416Z" }, + { url = "https://files.pythonhosted.org/packages/66/fe/b1e10b08d287f518994f1e2ff9b6d26f0adeecd8dd7d533b01bab29a3eda/yarl-1.23.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:34b6cf500e61c90f305094911f9acc9c86da1a05a7a3f5be9f68817043f486e4", size = 101559, upload-time = "2026-03-01T22:05:52.872Z" }, + { url = "https://files.pythonhosted.org/packages/72/59/c5b8d94b14e3d3c2a9c20cb100119fd534ab5a14b93673ab4cc4a4141ea5/yarl-1.23.0-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:d7504f2b476d21653e4d143f44a175f7f751cd41233525312696c76aa3dbb23f", size = 100502, upload-time = "2026-03-01T22:05:54.954Z" }, + { url = "https://files.pythonhosted.org/packages/77/4f/96976cb54cbfc5c9fd73ed4c51804f92f209481d1fb190981c0f8a07a1d7/yarl-1.23.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:578110dd426f0d209d1509244e6d4a3f1a3e9077655d98c5f22583d63252a08a", size = 98027, upload-time = "2026-03-01T22:05:56.409Z" }, + { url = "https://files.pythonhosted.org/packages/63/6e/904c4f476471afdbad6b7e5b70362fb5810e35cd7466529a97322b6f5556/yarl-1.23.0-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:609d3614d78d74ebe35f54953c5bbd2ac647a7ddb9c30a5d877580f5e86b22f2", size = 95369, upload-time = "2026-03-01T22:05:58.141Z" }, + { url = "https://files.pythonhosted.org/packages/9d/40/acfcdb3b5f9d68ef499e39e04d25e141fe90661f9d54114556cf83be8353/yarl-1.23.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:4966242ec68afc74c122f8459abd597afd7d8a60dc93d695c1334c5fd25f762f", size = 105565, upload-time = "2026-03-01T22:06:00.286Z" }, + { url = "https://files.pythonhosted.org/packages/5e/c6/31e28f3a6ba2869c43d124f37ea5260cac9c9281df803c354b31f4dd1f3c/yarl-1.23.0-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:e0fd068364a6759bc794459f0a735ab151d11304346332489c7972bacbe9e72b", size = 99813, upload-time = "2026-03-01T22:06:01.712Z" }, + { url = "https://files.pythonhosted.org/packages/08/1f/6f65f59e72d54aa467119b63fc0b0b1762eff0232db1f4720cd89e2f4a17/yarl-1.23.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:39004f0ad156da43e86aa71f44e033de68a44e5a31fc53507b36dd253970054a", size = 105632, upload-time = "2026-03-01T22:06:03.188Z" }, + { url = "https://files.pythonhosted.org/packages/a3/c4/18b178a69935f9e7a338127d5b77d868fdc0f0e49becd286d51b3a18c61d/yarl-1.23.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e5723c01a56c5028c807c701aa66722916d2747ad737a046853f6c46f4875543", size = 101895, upload-time = "2026-03-01T22:06:04.651Z" }, + { url = "https://files.pythonhosted.org/packages/8f/54/f5b870b5505663911dba950a8e4776a0dbd51c9c54c0ae88e823e4b874a0/yarl-1.23.0-cp313-cp313-win32.whl", hash = "sha256:1b6b572edd95b4fa8df75de10b04bc81acc87c1c7d16bcdd2035b09d30acc957", size = 82356, upload-time = "2026-03-01T22:06:06.04Z" }, + { url = "https://files.pythonhosted.org/packages/7a/84/266e8da36879c6edcd37b02b547e2d9ecdfea776be49598e75696e3316e1/yarl-1.23.0-cp313-cp313-win_amd64.whl", hash = "sha256:baaf55442359053c7d62f6f8413a62adba3205119bcb6f49594894d8be47e5e3", size = 87515, upload-time = "2026-03-01T22:06:08.107Z" }, + { url = "https://files.pythonhosted.org/packages/00/fd/7e1c66efad35e1649114fa13f17485f62881ad58edeeb7f49f8c5e748bf9/yarl-1.23.0-cp313-cp313-win_arm64.whl", hash = "sha256:fb4948814a2a98e3912505f09c9e7493b1506226afb1f881825368d6fb776ee3", size = 81785, upload-time = "2026-03-01T22:06:10.181Z" }, + { url = "https://files.pythonhosted.org/packages/9c/fc/119dd07004f17ea43bb91e3ece6587759edd7519d6b086d16bfbd3319982/yarl-1.23.0-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:aecfed0b41aa72b7881712c65cf764e39ce2ec352324f5e0837c7048d9e6daaa", size = 130719, upload-time = "2026-03-01T22:06:11.708Z" }, + { url = "https://files.pythonhosted.org/packages/e6/0d/9f2348502fbb3af409e8f47730282cd6bc80dec6630c1e06374d882d6eb2/yarl-1.23.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:a41bcf68efd19073376eb8cf948b8d9be0af26256403e512bb18f3966f1f9120", size = 89690, upload-time = "2026-03-01T22:06:13.429Z" }, + { url = "https://files.pythonhosted.org/packages/50/93/e88f3c80971b42cfc83f50a51b9d165a1dbf154b97005f2994a79f212a07/yarl-1.23.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:cde9a2ecd91668bcb7f077c4966d8ceddb60af01b52e6e3e2680e4cf00ad1a59", size = 89851, upload-time = "2026-03-01T22:06:15.53Z" }, + { url = "https://files.pythonhosted.org/packages/1c/07/61c9dd8ba8f86473263b4036f70fb594c09e99c0d9737a799dfd8bc85651/yarl-1.23.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5023346c4ee7992febc0068e7593de5fa2bf611848c08404b35ebbb76b1b0512", size = 95874, upload-time = "2026-03-01T22:06:17.553Z" }, + { url = "https://files.pythonhosted.org/packages/9e/e9/f9ff8ceefba599eac6abddcfb0b3bee9b9e636e96dbf54342a8577252379/yarl-1.23.0-cp313-cp313t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:d1009abedb49ae95b136a8904a3f71b342f849ffeced2d3747bf29caeda218c4", size = 88710, upload-time = "2026-03-01T22:06:19.004Z" }, + { url = "https://files.pythonhosted.org/packages/eb/78/0231bfcc5d4c8eec220bc2f9ef82cb4566192ea867a7c5b4148f44f6cbcd/yarl-1.23.0-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a8d00f29b42f534cc8aa3931cfe773b13b23e561e10d2b26f27a8d309b0e82a1", size = 101033, upload-time = "2026-03-01T22:06:21.203Z" }, + { url = "https://files.pythonhosted.org/packages/cd/9b/30ea5239a61786f18fd25797151a17fbb3be176977187a48d541b5447dd4/yarl-1.23.0-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:95451e6ce06c3e104556d73b559f5da6c34a069b6b62946d3ad66afcd51642ea", size = 100817, upload-time = "2026-03-01T22:06:22.738Z" }, + { url = "https://files.pythonhosted.org/packages/62/e2/a4980481071791bc83bce2b7a1a1f7adcabfa366007518b4b845e92eeee3/yarl-1.23.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:531ef597132086b6cf96faa7c6c1dcd0361dd5f1694e5cc30375907b9b7d3ea9", size = 97482, upload-time = "2026-03-01T22:06:24.21Z" }, + { url = "https://files.pythonhosted.org/packages/e5/1e/304a00cf5f6100414c4b5a01fc7ff9ee724b62158a08df2f8170dfc72a2d/yarl-1.23.0-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:88f9fb0116fbfcefcab70f85cf4b74a2b6ce5d199c41345296f49d974ddb4123", size = 95949, upload-time = "2026-03-01T22:06:25.697Z" }, + { url = "https://files.pythonhosted.org/packages/68/03/093f4055ed4cae649ac53bca3d180bd37102e9e11d048588e9ab0c0108d0/yarl-1.23.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:e7b0460976dc75cb87ad9cc1f9899a4b97751e7d4e77ab840fc9b6d377b8fd24", size = 95839, upload-time = "2026-03-01T22:06:27.309Z" }, + { url = "https://files.pythonhosted.org/packages/b9/28/4c75ebb108f322aa8f917ae10a8ffa4f07cae10a8a627b64e578617df6a0/yarl-1.23.0-cp313-cp313t-musllinux_1_2_armv7l.whl", hash = "sha256:115136c4a426f9da976187d238e84139ff6b51a20839aa6e3720cd1026d768de", size = 90696, upload-time = "2026-03-01T22:06:29.048Z" }, + { url = "https://files.pythonhosted.org/packages/23/9c/42c2e2dd91c1a570402f51bdf066bfdb1241c2240ba001967bad778e77b7/yarl-1.23.0-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:ead11956716a940c1abc816b7df3fa2b84d06eaed8832ca32f5c5e058c65506b", size = 100865, upload-time = "2026-03-01T22:06:30.525Z" }, + { url = "https://files.pythonhosted.org/packages/74/05/1bcd60a8a0a914d462c305137246b6f9d167628d73568505fce3f1cb2e65/yarl-1.23.0-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:fe8f8f5e70e6dbdfca9882cd9deaac058729bcf323cf7a58660901e55c9c94f6", size = 96234, upload-time = "2026-03-01T22:06:32.692Z" }, + { url = "https://files.pythonhosted.org/packages/90/b2/f52381aac396d6778ce516b7bc149c79e65bfc068b5de2857ab69eeea3b7/yarl-1.23.0-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:a0e317df055958a0c1e79e5d2aa5a5eaa4a6d05a20d4b0c9c3f48918139c9fc6", size = 100295, upload-time = "2026-03-01T22:06:34.268Z" }, + { url = "https://files.pythonhosted.org/packages/e5/e8/638bae5bbf1113a659b2435d8895474598afe38b4a837103764f603aba56/yarl-1.23.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:6f0fd84de0c957b2d280143522c4f91a73aada1923caee763e24a2b3fda9f8a5", size = 97784, upload-time = "2026-03-01T22:06:35.864Z" }, + { url = "https://files.pythonhosted.org/packages/80/25/a3892b46182c586c202629fc2159aa13975d3741d52ebd7347fd501d48d5/yarl-1.23.0-cp313-cp313t-win32.whl", hash = "sha256:93a784271881035ab4406a172edb0faecb6e7d00f4b53dc2f55919d6c9688595", size = 88313, upload-time = "2026-03-01T22:06:37.39Z" }, + { url = "https://files.pythonhosted.org/packages/43/68/8c5b36aa5178900b37387937bc2c2fe0e9505537f713495472dcf6f6fccc/yarl-1.23.0-cp313-cp313t-win_amd64.whl", hash = "sha256:dd00607bffbf30250fe108065f07453ec124dbf223420f57f5e749b04295e090", size = 94932, upload-time = "2026-03-01T22:06:39.579Z" }, + { url = "https://files.pythonhosted.org/packages/c6/cc/d79ba8292f51f81f4dc533a8ccfb9fc6992cabf0998ed3245de7589dc07c/yarl-1.23.0-cp313-cp313t-win_arm64.whl", hash = "sha256:ac09d42f48f80c9ee1635b2fcaa819496a44502737660d3c0f2ade7526d29144", size = 84786, upload-time = "2026-03-01T22:06:41.988Z" }, + { url = "https://files.pythonhosted.org/packages/90/98/b85a038d65d1b92c3903ab89444f48d3cee490a883477b716d7a24b1a78c/yarl-1.23.0-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:21d1b7305a71a15b4794b5ff22e8eef96ff4a6d7f9657155e5aa419444b28912", size = 124455, upload-time = "2026-03-01T22:06:43.615Z" }, + { url = "https://files.pythonhosted.org/packages/39/54/bc2b45559f86543d163b6e294417a107bb87557609007c007ad889afec18/yarl-1.23.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:85610b4f27f69984932a7abbe52703688de3724d9f72bceb1cca667deff27474", size = 86752, upload-time = "2026-03-01T22:06:45.425Z" }, + { url = "https://files.pythonhosted.org/packages/24/f9/e8242b68362bffe6fb536c8db5076861466fc780f0f1b479fc4ffbebb128/yarl-1.23.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:23f371bd662cf44a7630d4d113101eafc0cfa7518a2760d20760b26021454719", size = 86291, upload-time = "2026-03-01T22:06:46.974Z" }, + { url = "https://files.pythonhosted.org/packages/ea/d8/d1cb2378c81dd729e98c716582b1ccb08357e8488e4c24714658cc6630e8/yarl-1.23.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c4a80f77dc1acaaa61f0934176fccca7096d9b1ff08c8ba9cddf5ae034a24319", size = 99026, upload-time = "2026-03-01T22:06:48.459Z" }, + { url = "https://files.pythonhosted.org/packages/0a/ff/7196790538f31debe3341283b5b0707e7feb947620fc5e8236ef28d44f72/yarl-1.23.0-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:bd654fad46d8d9e823afbb4f87c79160b5a374ed1ff5bde24e542e6ba8f41434", size = 92355, upload-time = "2026-03-01T22:06:50.306Z" }, + { url = "https://files.pythonhosted.org/packages/c1/56/25d58c3eddde825890a5fe6aa1866228377354a3c39262235234ab5f616b/yarl-1.23.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:682bae25f0a0dd23a056739f23a134db9f52a63e2afd6bfb37ddc76292bbd723", size = 106417, upload-time = "2026-03-01T22:06:52.1Z" }, + { url = "https://files.pythonhosted.org/packages/51/8a/882c0e7bc8277eb895b31bce0138f51a1ba551fc2e1ec6753ffc1e7c1377/yarl-1.23.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a82836cab5f197a0514235aaf7ffccdc886ccdaa2324bc0aafdd4ae898103039", size = 106422, upload-time = "2026-03-01T22:06:54.424Z" }, + { url = "https://files.pythonhosted.org/packages/42/2b/fef67d616931055bf3d6764885990a3ac647d68734a2d6a9e1d13de437a2/yarl-1.23.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1c57676bdedc94cd3bc37724cf6f8cd2779f02f6aba48de45feca073e714fe52", size = 101915, upload-time = "2026-03-01T22:06:55.895Z" }, + { url = "https://files.pythonhosted.org/packages/18/6a/530e16aebce27c5937920f3431c628a29a4b6b430fab3fd1c117b26ff3f6/yarl-1.23.0-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c7f8dc16c498ff06497c015642333219871effba93e4a2e8604a06264aca5c5c", size = 100690, upload-time = "2026-03-01T22:06:58.21Z" }, + { url = "https://files.pythonhosted.org/packages/88/08/93749219179a45e27b036e03260fda05190b911de8e18225c294ac95bbc9/yarl-1.23.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:5ee586fb17ff8f90c91cf73c6108a434b02d69925f44f5f8e0d7f2f260607eae", size = 98750, upload-time = "2026-03-01T22:06:59.794Z" }, + { url = "https://files.pythonhosted.org/packages/d9/cf/ea424a004969f5d81a362110a6ac1496d79efdc6d50c2c4b2e3ea0fc2519/yarl-1.23.0-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:17235362f580149742739cc3828b80e24029d08cbb9c4bda0242c7b5bc610a8e", size = 94685, upload-time = "2026-03-01T22:07:01.375Z" }, + { url = "https://files.pythonhosted.org/packages/e2/b7/14341481fe568e2b0408bcf1484c652accafe06a0ade9387b5d3fd9df446/yarl-1.23.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:0793e2bd0cf14234983bbb371591e6bea9e876ddf6896cdcc93450996b0b5c85", size = 106009, upload-time = "2026-03-01T22:07:03.151Z" }, + { url = "https://files.pythonhosted.org/packages/0a/e6/5c744a9b54f4e8007ad35bce96fbc9218338e84812d36f3390cea616881a/yarl-1.23.0-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:3650dc2480f94f7116c364096bc84b1d602f44224ef7d5c7208425915c0475dd", size = 100033, upload-time = "2026-03-01T22:07:04.701Z" }, + { url = "https://files.pythonhosted.org/packages/0c/23/e3bfc188d0b400f025bc49d99793d02c9abe15752138dcc27e4eaf0c4a9e/yarl-1.23.0-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:f40e782d49630ad384db66d4d8b73ff4f1b8955dc12e26b09a3e3af064b3b9d6", size = 106483, upload-time = "2026-03-01T22:07:06.231Z" }, + { url = "https://files.pythonhosted.org/packages/72/42/f0505f949a90b3f8b7a363d6cbdf398f6e6c58946d85c6d3a3bc70595b26/yarl-1.23.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:94f8575fbdf81749008d980c17796097e645574a3b8c28ee313931068dad14fe", size = 102175, upload-time = "2026-03-01T22:07:08.4Z" }, + { url = "https://files.pythonhosted.org/packages/aa/65/b39290f1d892a9dd671d1c722014ca062a9c35d60885d57e5375db0404b5/yarl-1.23.0-cp314-cp314-win32.whl", hash = "sha256:c8aa34a5c864db1087d911a0b902d60d203ea3607d91f615acd3f3108ac32169", size = 83871, upload-time = "2026-03-01T22:07:09.968Z" }, + { url = "https://files.pythonhosted.org/packages/a9/5b/9b92f54c784c26e2a422e55a8d2607ab15b7ea3349e28359282f84f01d43/yarl-1.23.0-cp314-cp314-win_amd64.whl", hash = "sha256:63e92247f383c85ab00dd0091e8c3fa331a96e865459f5ee80353c70a4a42d70", size = 89093, upload-time = "2026-03-01T22:07:11.501Z" }, + { url = "https://files.pythonhosted.org/packages/e0/7d/8a84dc9381fd4412d5e7ff04926f9865f6372b4c2fd91e10092e65d29eb8/yarl-1.23.0-cp314-cp314-win_arm64.whl", hash = "sha256:70efd20be968c76ece7baa8dafe04c5be06abc57f754d6f36f3741f7aa7a208e", size = 83384, upload-time = "2026-03-01T22:07:13.069Z" }, + { url = "https://files.pythonhosted.org/packages/dd/8d/d2fad34b1c08aa161b74394183daa7d800141aaaee207317e82c790b418d/yarl-1.23.0-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:9a18d6f9359e45722c064c97464ec883eb0e0366d33eda61cb19a244bf222679", size = 131019, upload-time = "2026-03-01T22:07:14.903Z" }, + { url = "https://files.pythonhosted.org/packages/19/ff/33009a39d3ccf4b94d7d7880dfe17fb5816c5a4fe0096d9b56abceea9ac7/yarl-1.23.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:2803ed8b21ca47a43da80a6fd1ed3019d30061f7061daa35ac54f63933409412", size = 89894, upload-time = "2026-03-01T22:07:17.372Z" }, + { url = "https://files.pythonhosted.org/packages/0c/f1/dab7ac5e7306fb79c0190766a3c00b4cb8d09a1f390ded68c85a5934faf5/yarl-1.23.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:394906945aa8b19fc14a61cf69743a868bb8c465efe85eee687109cc540b98f4", size = 89979, upload-time = "2026-03-01T22:07:19.361Z" }, + { url = "https://files.pythonhosted.org/packages/aa/b1/08e95f3caee1fad6e65017b9f26c1d79877b502622d60e517de01e72f95d/yarl-1.23.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:71d006bee8397a4a89f469b8deb22469fe7508132d3c17fa6ed871e79832691c", size = 95943, upload-time = "2026-03-01T22:07:21.266Z" }, + { url = "https://files.pythonhosted.org/packages/c0/cc/6409f9018864a6aa186c61175b977131f373f1988e198e031236916e87e4/yarl-1.23.0-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:62694e275c93d54f7ccedcfef57d42761b2aad5234b6be1f3e3026cae4001cd4", size = 88786, upload-time = "2026-03-01T22:07:23.129Z" }, + { url = "https://files.pythonhosted.org/packages/76/40/cc22d1d7714b717fde2006fad2ced5efe5580606cb059ae42117542122f3/yarl-1.23.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a31de1613658308efdb21ada98cbc86a97c181aa050ba22a808120bb5be3ab94", size = 101307, upload-time = "2026-03-01T22:07:24.689Z" }, + { url = "https://files.pythonhosted.org/packages/8f/0d/476c38e85ddb4c6ec6b20b815bdd779aa386a013f3d8b85516feee55c8dc/yarl-1.23.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:fb1e8b8d66c278b21d13b0a7ca22c41dd757a7c209c6b12c313e445c31dd3b28", size = 100904, upload-time = "2026-03-01T22:07:26.287Z" }, + { url = "https://files.pythonhosted.org/packages/72/32/0abe4a76d59adf2081dcb0397168553ece4616ada1c54d1c49d8936c74f8/yarl-1.23.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:50f9d8d531dfb767c565f348f33dd5139a6c43f5cbdf3f67da40d54241df93f6", size = 97728, upload-time = "2026-03-01T22:07:27.906Z" }, + { url = "https://files.pythonhosted.org/packages/b7/35/7b30f4810fba112f60f5a43237545867504e15b1c7647a785fbaf588fac2/yarl-1.23.0-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:575aa4405a656e61a540f4a80eaa5260f2a38fff7bfdc4b5f611840d76e9e277", size = 95964, upload-time = "2026-03-01T22:07:30.198Z" }, + { url = "https://files.pythonhosted.org/packages/2d/86/ed7a73ab85ef00e8bb70b0cb5421d8a2a625b81a333941a469a6f4022828/yarl-1.23.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:041b1a4cefacf65840b4e295c6985f334ba83c30607441ae3cf206a0eed1a2e4", size = 95882, upload-time = "2026-03-01T22:07:32.132Z" }, + { url = "https://files.pythonhosted.org/packages/19/90/d56967f61a29d8498efb7afb651e0b2b422a1e9b47b0ab5f4e40a19b699b/yarl-1.23.0-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:d38c1e8231722c4ce40d7593f28d92b5fc72f3e9774fe73d7e800ec32299f63a", size = 90797, upload-time = "2026-03-01T22:07:34.404Z" }, + { url = "https://files.pythonhosted.org/packages/72/00/8b8f76909259f56647adb1011d7ed8b321bcf97e464515c65016a47ecdf0/yarl-1.23.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:d53834e23c015ee83a99377db6e5e37d8484f333edb03bd15b4bc312cc7254fb", size = 101023, upload-time = "2026-03-01T22:07:35.953Z" }, + { url = "https://files.pythonhosted.org/packages/ac/e2/cab11b126fb7d440281b7df8e9ddbe4851e70a4dde47a202b6642586b8d9/yarl-1.23.0-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:2e27c8841126e017dd2a054a95771569e6070b9ee1b133366d8b31beb5018a41", size = 96227, upload-time = "2026-03-01T22:07:37.594Z" }, + { url = "https://files.pythonhosted.org/packages/c2/9b/2c893e16bfc50e6b2edf76c1a9eb6cb0c744346197e74c65e99ad8d634d0/yarl-1.23.0-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:76855800ac56f878847a09ce6dba727c93ca2d89c9e9d63002d26b916810b0a2", size = 100302, upload-time = "2026-03-01T22:07:39.334Z" }, + { url = "https://files.pythonhosted.org/packages/28/ec/5498c4e3a6d5f1003beb23405671c2eb9cdbf3067d1c80f15eeafe301010/yarl-1.23.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:e09fd068c2e169a7070d83d3bde728a4d48de0549f975290be3c108c02e499b4", size = 98202, upload-time = "2026-03-01T22:07:41.717Z" }, + { url = "https://files.pythonhosted.org/packages/fe/c3/cd737e2d45e70717907f83e146f6949f20cc23cd4bf7b2688727763aa458/yarl-1.23.0-cp314-cp314t-win32.whl", hash = "sha256:73309162a6a571d4cbd3b6a1dcc703c7311843ae0d1578df6f09be4e98df38d4", size = 90558, upload-time = "2026-03-01T22:07:43.433Z" }, + { url = "https://files.pythonhosted.org/packages/e1/19/3774d162f6732d1cfb0b47b4140a942a35ca82bb19b6db1f80e9e7bdc8f8/yarl-1.23.0-cp314-cp314t-win_amd64.whl", hash = "sha256:4503053d296bc6e4cbd1fad61cf3b6e33b939886c4f249ba7c78b602214fabe2", size = 97610, upload-time = "2026-03-01T22:07:45.773Z" }, + { url = "https://files.pythonhosted.org/packages/51/47/3fa2286c3cb162c71cdb34c4224d5745a1ceceb391b2bd9b19b668a8d724/yarl-1.23.0-cp314-cp314t-win_arm64.whl", hash = "sha256:44bb7bef4ea409384e3f8bc36c063d77ea1b8d4a5b2706956c0d6695f07dcc25", size = 86041, upload-time = "2026-03-01T22:07:49.026Z" }, + { url = "https://files.pythonhosted.org/packages/69/68/c8739671f5699c7dc470580a4f821ef37c32c4cb0b047ce223a7f115757f/yarl-1.23.0-py3-none-any.whl", hash = "sha256:a2df6afe50dea8ae15fa34c9f824a3ee958d785fd5d089063d960bae1daa0a3f", size = 48288, upload-time = "2026-03-01T22:07:51.388Z" }, +] + [[package]] name = "zipp" version = "3.23.0" @@ -1572,3 +2732,60 @@ sdist = { url = "https://files.pythonhosted.org/packages/e3/02/0f2892c661036d50e wheels = [ { url = "https://files.pythonhosted.org/packages/2e/54/647ade08bf0db230bfea292f893923872fd20be6ac6f53b2b936ba839d75/zipp-3.23.0-py3-none-any.whl", hash = "sha256:071652d6115ed432f5ce1d34c336c0adfd6a884660d1e9712a256d3d3bd4b14e", size = 10276, upload-time = "2025-06-08T17:06:38.034Z" }, ] + +[[package]] +name = "zstandard" +version = "0.25.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/fd/aa/3e0508d5a5dd96529cdc5a97011299056e14c6505b678fd58938792794b1/zstandard-0.25.0.tar.gz", hash = "sha256:7713e1179d162cf5c7906da876ec2ccb9c3a9dcbdffef0cc7f70c3667a205f0b", size = 711513, upload-time = "2025-09-14T22:15:54.002Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/82/fc/f26eb6ef91ae723a03e16eddb198abcfce2bc5a42e224d44cc8b6765e57e/zstandard-0.25.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:7b3c3a3ab9daa3eed242d6ecceead93aebbb8f5f84318d82cee643e019c4b73b", size = 795738, upload-time = "2025-09-14T22:16:56.237Z" }, + { url = "https://files.pythonhosted.org/packages/aa/1c/d920d64b22f8dd028a8b90e2d756e431a5d86194caa78e3819c7bf53b4b3/zstandard-0.25.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:913cbd31a400febff93b564a23e17c3ed2d56c064006f54efec210d586171c00", size = 640436, upload-time = "2025-09-14T22:16:57.774Z" }, + { url = "https://files.pythonhosted.org/packages/53/6c/288c3f0bd9fcfe9ca41e2c2fbfd17b2097f6af57b62a81161941f09afa76/zstandard-0.25.0-cp312-cp312-manylinux2010_i686.manylinux2014_i686.manylinux_2_12_i686.manylinux_2_17_i686.whl", hash = "sha256:011d388c76b11a0c165374ce660ce2c8efa8e5d87f34996aa80f9c0816698b64", size = 5343019, upload-time = "2025-09-14T22:16:59.302Z" }, + { url = "https://files.pythonhosted.org/packages/1e/15/efef5a2f204a64bdb5571e6161d49f7ef0fffdbca953a615efbec045f60f/zstandard-0.25.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:6dffecc361d079bb48d7caef5d673c88c8988d3d33fb74ab95b7ee6da42652ea", size = 5063012, upload-time = "2025-09-14T22:17:01.156Z" }, + { url = "https://files.pythonhosted.org/packages/b7/37/a6ce629ffdb43959e92e87ebdaeebb5ac81c944b6a75c9c47e300f85abdf/zstandard-0.25.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:7149623bba7fdf7e7f24312953bcf73cae103db8cae49f8154dd1eadc8a29ecb", size = 5394148, upload-time = "2025-09-14T22:17:03.091Z" }, + { url = "https://files.pythonhosted.org/packages/e3/79/2bf870b3abeb5c070fe2d670a5a8d1057a8270f125ef7676d29ea900f496/zstandard-0.25.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:6a573a35693e03cf1d67799fd01b50ff578515a8aeadd4595d2a7fa9f3ec002a", size = 5451652, upload-time = "2025-09-14T22:17:04.979Z" }, + { url = "https://files.pythonhosted.org/packages/53/60/7be26e610767316c028a2cbedb9a3beabdbe33e2182c373f71a1c0b88f36/zstandard-0.25.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:5a56ba0db2d244117ed744dfa8f6f5b366e14148e00de44723413b2f3938a902", size = 5546993, upload-time = "2025-09-14T22:17:06.781Z" }, + { url = "https://files.pythonhosted.org/packages/85/c7/3483ad9ff0662623f3648479b0380d2de5510abf00990468c286c6b04017/zstandard-0.25.0-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:10ef2a79ab8e2974e2075fb984e5b9806c64134810fac21576f0668e7ea19f8f", size = 5046806, upload-time = "2025-09-14T22:17:08.415Z" }, + { url = "https://files.pythonhosted.org/packages/08/b3/206883dd25b8d1591a1caa44b54c2aad84badccf2f1de9e2d60a446f9a25/zstandard-0.25.0-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:aaf21ba8fb76d102b696781bddaa0954b782536446083ae3fdaa6f16b25a1c4b", size = 5576659, upload-time = "2025-09-14T22:17:10.164Z" }, + { url = "https://files.pythonhosted.org/packages/9d/31/76c0779101453e6c117b0ff22565865c54f48f8bd807df2b00c2c404b8e0/zstandard-0.25.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:1869da9571d5e94a85a5e8d57e4e8807b175c9e4a6294e3b66fa4efb074d90f6", size = 4953933, upload-time = "2025-09-14T22:17:11.857Z" }, + { url = "https://files.pythonhosted.org/packages/18/e1/97680c664a1bf9a247a280a053d98e251424af51f1b196c6d52f117c9720/zstandard-0.25.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:809c5bcb2c67cd0ed81e9229d227d4ca28f82d0f778fc5fea624a9def3963f91", size = 5268008, upload-time = "2025-09-14T22:17:13.627Z" }, + { url = "https://files.pythonhosted.org/packages/1e/73/316e4010de585ac798e154e88fd81bb16afc5c5cb1a72eeb16dd37e8024a/zstandard-0.25.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:f27662e4f7dbf9f9c12391cb37b4c4c3cb90ffbd3b1fb9284dadbbb8935fa708", size = 5433517, upload-time = "2025-09-14T22:17:16.103Z" }, + { url = "https://files.pythonhosted.org/packages/5b/60/dd0f8cfa8129c5a0ce3ea6b7f70be5b33d2618013a161e1ff26c2b39787c/zstandard-0.25.0-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:99c0c846e6e61718715a3c9437ccc625de26593fea60189567f0118dc9db7512", size = 5814292, upload-time = "2025-09-14T22:17:17.827Z" }, + { url = "https://files.pythonhosted.org/packages/fc/5f/75aafd4b9d11b5407b641b8e41a57864097663699f23e9ad4dbb91dc6bfe/zstandard-0.25.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:474d2596a2dbc241a556e965fb76002c1ce655445e4e3bf38e5477d413165ffa", size = 5360237, upload-time = "2025-09-14T22:17:19.954Z" }, + { url = "https://files.pythonhosted.org/packages/ff/8d/0309daffea4fcac7981021dbf21cdb2e3427a9e76bafbcdbdf5392ff99a4/zstandard-0.25.0-cp312-cp312-win32.whl", hash = "sha256:23ebc8f17a03133b4426bcc04aabd68f8236eb78c3760f12783385171b0fd8bd", size = 436922, upload-time = "2025-09-14T22:17:24.398Z" }, + { url = "https://files.pythonhosted.org/packages/79/3b/fa54d9015f945330510cb5d0b0501e8253c127cca7ebe8ba46a965df18c5/zstandard-0.25.0-cp312-cp312-win_amd64.whl", hash = "sha256:ffef5a74088f1e09947aecf91011136665152e0b4b359c42be3373897fb39b01", size = 506276, upload-time = "2025-09-14T22:17:21.429Z" }, + { url = "https://files.pythonhosted.org/packages/ea/6b/8b51697e5319b1f9ac71087b0af9a40d8a6288ff8025c36486e0c12abcc4/zstandard-0.25.0-cp312-cp312-win_arm64.whl", hash = "sha256:181eb40e0b6a29b3cd2849f825e0fa34397f649170673d385f3598ae17cca2e9", size = 462679, upload-time = "2025-09-14T22:17:23.147Z" }, + { url = "https://files.pythonhosted.org/packages/35/0b/8df9c4ad06af91d39e94fa96cc010a24ac4ef1378d3efab9223cc8593d40/zstandard-0.25.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:ec996f12524f88e151c339688c3897194821d7f03081ab35d31d1e12ec975e94", size = 795735, upload-time = "2025-09-14T22:17:26.042Z" }, + { url = "https://files.pythonhosted.org/packages/3f/06/9ae96a3e5dcfd119377ba33d4c42a7d89da1efabd5cb3e366b156c45ff4d/zstandard-0.25.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a1a4ae2dec3993a32247995bdfe367fc3266da832d82f8438c8570f989753de1", size = 640440, upload-time = "2025-09-14T22:17:27.366Z" }, + { url = "https://files.pythonhosted.org/packages/d9/14/933d27204c2bd404229c69f445862454dcc101cd69ef8c6068f15aaec12c/zstandard-0.25.0-cp313-cp313-manylinux2010_i686.manylinux2014_i686.manylinux_2_12_i686.manylinux_2_17_i686.whl", hash = "sha256:e96594a5537722fdfb79951672a2a63aec5ebfb823e7560586f7484819f2a08f", size = 5343070, upload-time = "2025-09-14T22:17:28.896Z" }, + { url = "https://files.pythonhosted.org/packages/6d/db/ddb11011826ed7db9d0e485d13df79b58586bfdec56e5c84a928a9a78c1c/zstandard-0.25.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:bfc4e20784722098822e3eee42b8e576b379ed72cca4a7cb856ae733e62192ea", size = 5063001, upload-time = "2025-09-14T22:17:31.044Z" }, + { url = "https://files.pythonhosted.org/packages/db/00/87466ea3f99599d02a5238498b87bf84a6348290c19571051839ca943777/zstandard-0.25.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:457ed498fc58cdc12fc48f7950e02740d4f7ae9493dd4ab2168a47c93c31298e", size = 5394120, upload-time = "2025-09-14T22:17:32.711Z" }, + { url = "https://files.pythonhosted.org/packages/2b/95/fc5531d9c618a679a20ff6c29e2b3ef1d1f4ad66c5e161ae6ff847d102a9/zstandard-0.25.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:fd7a5004eb1980d3cefe26b2685bcb0b17989901a70a1040d1ac86f1d898c551", size = 5451230, upload-time = "2025-09-14T22:17:34.41Z" }, + { url = "https://files.pythonhosted.org/packages/63/4b/e3678b4e776db00f9f7b2fe58e547e8928ef32727d7a1ff01dea010f3f13/zstandard-0.25.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8e735494da3db08694d26480f1493ad2cf86e99bdd53e8e9771b2752a5c0246a", size = 5547173, upload-time = "2025-09-14T22:17:36.084Z" }, + { url = "https://files.pythonhosted.org/packages/4e/d5/ba05ed95c6b8ec30bd468dfeab20589f2cf709b5c940483e31d991f2ca58/zstandard-0.25.0-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:3a39c94ad7866160a4a46d772e43311a743c316942037671beb264e395bdd611", size = 5046736, upload-time = "2025-09-14T22:17:37.891Z" }, + { url = "https://files.pythonhosted.org/packages/50/d5/870aa06b3a76c73eced65c044b92286a3c4e00554005ff51962deef28e28/zstandard-0.25.0-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:172de1f06947577d3a3005416977cce6168f2261284c02080e7ad0185faeced3", size = 5576368, upload-time = "2025-09-14T22:17:40.206Z" }, + { url = "https://files.pythonhosted.org/packages/5d/35/398dc2ffc89d304d59bc12f0fdd931b4ce455bddf7038a0a67733a25f550/zstandard-0.25.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:3c83b0188c852a47cd13ef3bf9209fb0a77fa5374958b8c53aaa699398c6bd7b", size = 4954022, upload-time = "2025-09-14T22:17:41.879Z" }, + { url = "https://files.pythonhosted.org/packages/9a/5c/36ba1e5507d56d2213202ec2b05e8541734af5f2ce378c5d1ceaf4d88dc4/zstandard-0.25.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:1673b7199bbe763365b81a4f3252b8e80f44c9e323fc42940dc8843bfeaf9851", size = 5267889, upload-time = "2025-09-14T22:17:43.577Z" }, + { url = "https://files.pythonhosted.org/packages/70/e8/2ec6b6fb7358b2ec0113ae202647ca7c0e9d15b61c005ae5225ad0995df5/zstandard-0.25.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:0be7622c37c183406f3dbf0cba104118eb16a4ea7359eeb5752f0794882fc250", size = 5433952, upload-time = "2025-09-14T22:17:45.271Z" }, + { url = "https://files.pythonhosted.org/packages/7b/01/b5f4d4dbc59ef193e870495c6f1275f5b2928e01ff5a81fecb22a06e22fb/zstandard-0.25.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:5f5e4c2a23ca271c218ac025bd7d635597048b366d6f31f420aaeb715239fc98", size = 5814054, upload-time = "2025-09-14T22:17:47.08Z" }, + { url = "https://files.pythonhosted.org/packages/b2/e5/fbd822d5c6f427cf158316d012c5a12f233473c2f9c5fe5ab1ae5d21f3d8/zstandard-0.25.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:4f187a0bb61b35119d1926aee039524d1f93aaf38a9916b8c4b78ac8514a0aaf", size = 5360113, upload-time = "2025-09-14T22:17:48.893Z" }, + { url = "https://files.pythonhosted.org/packages/8e/e0/69a553d2047f9a2c7347caa225bb3a63b6d7704ad74610cb7823baa08ed7/zstandard-0.25.0-cp313-cp313-win32.whl", hash = "sha256:7030defa83eef3e51ff26f0b7bfb229f0204b66fe18e04359ce3474ac33cbc09", size = 436936, upload-time = "2025-09-14T22:17:52.658Z" }, + { url = "https://files.pythonhosted.org/packages/d9/82/b9c06c870f3bd8767c201f1edbdf9e8dc34be5b0fbc5682c4f80fe948475/zstandard-0.25.0-cp313-cp313-win_amd64.whl", hash = "sha256:1f830a0dac88719af0ae43b8b2d6aef487d437036468ef3c2ea59c51f9d55fd5", size = 506232, upload-time = "2025-09-14T22:17:50.402Z" }, + { url = "https://files.pythonhosted.org/packages/d4/57/60c3c01243bb81d381c9916e2a6d9e149ab8627c0c7d7abb2d73384b3c0c/zstandard-0.25.0-cp313-cp313-win_arm64.whl", hash = "sha256:85304a43f4d513f5464ceb938aa02c1e78c2943b29f44a750b48b25ac999a049", size = 462671, upload-time = "2025-09-14T22:17:51.533Z" }, + { url = "https://files.pythonhosted.org/packages/3d/5c/f8923b595b55fe49e30612987ad8bf053aef555c14f05bb659dd5dbe3e8a/zstandard-0.25.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:e29f0cf06974c899b2c188ef7f783607dbef36da4c242eb6c82dcd8b512855e3", size = 795887, upload-time = "2025-09-14T22:17:54.198Z" }, + { url = "https://files.pythonhosted.org/packages/8d/09/d0a2a14fc3439c5f874042dca72a79c70a532090b7ba0003be73fee37ae2/zstandard-0.25.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:05df5136bc5a011f33cd25bc9f506e7426c0c9b3f9954f056831ce68f3b6689f", size = 640658, upload-time = "2025-09-14T22:17:55.423Z" }, + { url = "https://files.pythonhosted.org/packages/5d/7c/8b6b71b1ddd517f68ffb55e10834388d4f793c49c6b83effaaa05785b0b4/zstandard-0.25.0-cp314-cp314-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:f604efd28f239cc21b3adb53eb061e2a205dc164be408e553b41ba2ffe0ca15c", size = 5379849, upload-time = "2025-09-14T22:17:57.372Z" }, + { url = "https://files.pythonhosted.org/packages/a4/86/a48e56320d0a17189ab7a42645387334fba2200e904ee47fc5a26c1fd8ca/zstandard-0.25.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:223415140608d0f0da010499eaa8ccdb9af210a543fac54bce15babbcfc78439", size = 5058095, upload-time = "2025-09-14T22:17:59.498Z" }, + { url = "https://files.pythonhosted.org/packages/f8/ad/eb659984ee2c0a779f9d06dbfe45e2dc39d99ff40a319895df2d3d9a48e5/zstandard-0.25.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2e54296a283f3ab5a26fc9b8b5d4978ea0532f37b231644f367aa588930aa043", size = 5551751, upload-time = "2025-09-14T22:18:01.618Z" }, + { url = "https://files.pythonhosted.org/packages/61/b3/b637faea43677eb7bd42ab204dfb7053bd5c4582bfe6b1baefa80ac0c47b/zstandard-0.25.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:ca54090275939dc8ec5dea2d2afb400e0f83444b2fc24e07df7fdef677110859", size = 6364818, upload-time = "2025-09-14T22:18:03.769Z" }, + { url = "https://files.pythonhosted.org/packages/31/dc/cc50210e11e465c975462439a492516a73300ab8caa8f5e0902544fd748b/zstandard-0.25.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e09bb6252b6476d8d56100e8147b803befa9a12cea144bbe629dd508800d1ad0", size = 5560402, upload-time = "2025-09-14T22:18:05.954Z" }, + { url = "https://files.pythonhosted.org/packages/c9/ae/56523ae9c142f0c08efd5e868a6da613ae76614eca1305259c3bf6a0ed43/zstandard-0.25.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:a9ec8c642d1ec73287ae3e726792dd86c96f5681eb8df274a757bf62b750eae7", size = 4955108, upload-time = "2025-09-14T22:18:07.68Z" }, + { url = "https://files.pythonhosted.org/packages/98/cf/c899f2d6df0840d5e384cf4c4121458c72802e8bda19691f3b16619f51e9/zstandard-0.25.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:a4089a10e598eae6393756b036e0f419e8c1d60f44a831520f9af41c14216cf2", size = 5269248, upload-time = "2025-09-14T22:18:09.753Z" }, + { url = "https://files.pythonhosted.org/packages/1b/c0/59e912a531d91e1c192d3085fc0f6fb2852753c301a812d856d857ea03c6/zstandard-0.25.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:f67e8f1a324a900e75b5e28ffb152bcac9fbed1cc7b43f99cd90f395c4375344", size = 5430330, upload-time = "2025-09-14T22:18:11.966Z" }, + { url = "https://files.pythonhosted.org/packages/a0/1d/7e31db1240de2df22a58e2ea9a93fc6e38cc29353e660c0272b6735d6669/zstandard-0.25.0-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:9654dbc012d8b06fc3d19cc825af3f7bf8ae242226df5f83936cb39f5fdc846c", size = 5811123, upload-time = "2025-09-14T22:18:13.907Z" }, + { url = "https://files.pythonhosted.org/packages/f6/49/fac46df5ad353d50535e118d6983069df68ca5908d4d65b8c466150a4ff1/zstandard-0.25.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:4203ce3b31aec23012d3a4cf4a2ed64d12fea5269c49aed5e4c3611b938e4088", size = 5359591, upload-time = "2025-09-14T22:18:16.465Z" }, + { url = "https://files.pythonhosted.org/packages/c2/38/f249a2050ad1eea0bb364046153942e34abba95dd5520af199aed86fbb49/zstandard-0.25.0-cp314-cp314-win32.whl", hash = "sha256:da469dc041701583e34de852d8634703550348d5822e66a0c827d39b05365b12", size = 444513, upload-time = "2025-09-14T22:18:20.61Z" }, + { url = "https://files.pythonhosted.org/packages/3a/43/241f9615bcf8ba8903b3f0432da069e857fc4fd1783bd26183db53c4804b/zstandard-0.25.0-cp314-cp314-win_amd64.whl", hash = "sha256:c19bcdd826e95671065f8692b5a4aa95c52dc7a02a4c5a0cac46deb879a017a2", size = 516118, upload-time = "2025-09-14T22:18:17.849Z" }, + { url = "https://files.pythonhosted.org/packages/f0/ef/da163ce2450ed4febf6467d77ccb4cd52c4c30ab45624bad26ca0a27260c/zstandard-0.25.0-cp314-cp314-win_arm64.whl", hash = "sha256:d7541afd73985c630bafcd6338d2518ae96060075f9463d7dc14cfb33514383d", size = 476940, upload-time = "2025-09-14T22:18:19.088Z" }, +] From 8cd7552d1f274c34586345a961f4b90205e9b28a Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 17 Apr 2026 12:46:14 +0700 Subject: [PATCH 394/412] fix: hide orchestrator model label when model is unknown --- frontend/src/components/organisms/HeaderBar.tsx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/frontend/src/components/organisms/HeaderBar.tsx b/frontend/src/components/organisms/HeaderBar.tsx index 0a3b905..e0421ba 100644 --- a/frontend/src/components/organisms/HeaderBar.tsx +++ b/frontend/src/components/organisms/HeaderBar.tsx @@ -46,7 +46,7 @@ export function HeaderBar({ step, totalSteps, currentStep, - orchestratorModel = 'opus', + orchestratorModel, elapsed, onSettingsClick, mode = 'workflow', @@ -89,10 +89,12 @@ export function HeaderBar({ {mode === 'workflow' && ( <div className="hb-right"> - <div className="hb-orchestrator"> - <StatusDot status="done" size="sm" /> - <span className="hb-model">{orchestratorModel}</span> - </div> + {orchestratorModel && ( + <div className="hb-orchestrator"> + <StatusDot status="done" size="sm" /> + <span className="hb-model">{orchestratorModel}</span> + </div> + )} {elapsed && <span className="hb-elapsed">{elapsed}</span>} <button className="hb-settings" From 51a962edc0824c84e154d36a1202c0b9f45b3302 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 17 Apr 2026 12:46:30 +0700 Subject: [PATCH 395/412] docs: add curated koan memory entries --- .gitignore | 1 - .koan/memory/.gitignore | 2 ++ ...sistent-orchestrator-over-per-phase-cli.md | 8 +++++++ ...p-first-workflow-pattern-boot-prompt-is.md | 8 +++++++ ...authoritative-projection-via-json-patch.md | 8 +++++++ ...-boundary-invariant-llms-write-markdown.md | 8 +++++++ ...e-trust-model-plan-review-as-designated.md | 10 ++++++++ ...as-contract-taskjson-over-cli-flags-for.md | 10 ++++++++ ...-system-audit-fold-per-subagent-disk-vs.md | 11 +++++++++ ...r-model-system-strongstandardcheap-over.md | 10 ++++++++ ...n-fence-impractical-across-llm-backends.md | 10 ++++++++ ...n-phase-3-step-layout-collapsed-to-2-to.md | 10 ++++++++ ...nfidence-loop-removed-unnecessary-scout.md | 12 ++++++++++ ...-dog-fooded-on-its-own-development-meta.md | 8 +++++++ ...nitive-goal-per-step-prevents-simulated.md | 11 +++++++++ ...e-wire-format-eliminates-renaming-layer.md | 12 ++++++++++ ...e-active-workflows-plan-milestones-stub.md | 10 ++++++++ ...-vs-phase-boundary-message-routing-dual.md | 11 +++++++++ ...parameter-escape-hatch-only-task-output.md | 11 +++++++++ ...ioral-constraints-require-both-a-prompt.md | 10 ++++++++ ...ction-events-record-facts-derived-state.md | 11 +++++++++ ...y-retrieval-static-directive-mechanical.md | 11 +++++++++ ...ory-entry-writing-discipline-temporally.md | 8 +++++++ ...-artifact-review-gate-removed-from-plan.md | 12 ++++++++++ ...ance-workflow-scope-framing-is-injected.md | 12 ++++++++++ ...ep-must-be-a-pure-query-side-effects-of.md | 11 +++++++++ ...-success-is-determined-by-exit-code-and.md | 10 ++++++++ ...e-vs-unrecoverable-error-classification.md | 11 +++++++++ ...l-state-file-writes-use-atomic-tmp-file.md | 11 +++++++++ ...css-token-promotion-hardcode-single-use.md | 9 +++++++ ...erbar-rendered-phantom-opus-model-label.md | 9 +++++++ ...t-use-destructuring-defaults-as-display.md | 11 +++++++++ ...-ai-as-sole-retrieval-provider-voyage-4.md | 11 +++++++++ ...ew-produced-unverified-critical-finding.md | 15 ++++++++++++ ...p-tool-handlers-in-koanwebmcpendpointpy.md | 24 +++++++++++++++++++ ...mory-sync-uses-sha-256-content-hash-not.md | 15 ++++++++++++ ...-comment-vs-memory-entry-filter-comment.md | 9 +++++++ ...rence-repetition-in-prompt-instructions.md | 8 +++++++ ...store-content-policy-rag-serves-unknown.md | 11 +++++++++ ...-memory-captures-persistent-always-true.md | 9 +++++++ 40 files changed, 408 insertions(+), 1 deletion(-) create mode 100644 .koan/memory/.gitignore create mode 100644 .koan/memory/0001-persistent-orchestrator-over-per-phase-cli.md create mode 100644 .koan/memory/0002-step-first-workflow-pattern-boot-prompt-is.md create mode 100644 .koan/memory/0003-server-authoritative-projection-via-json-patch.md create mode 100644 .koan/memory/0004-file-boundary-invariant-llms-write-markdown.md create mode 100644 .koan/memory/0005-phase-trust-model-plan-review-as-designated.md create mode 100644 .koan/memory/0006-directory-as-contract-taskjson-over-cli-flags-for.md create mode 100644 .koan/memory/0007-dual-fold-system-audit-fold-per-subagent-disk-vs.md create mode 100644 .koan/memory/0008-three-tier-model-system-strongstandardcheap-over.md create mode 100644 .koan/memory/0009-permission-fence-impractical-across-llm-backends.md create mode 100644 .koan/memory/0010-curation-phase-3-step-layout-collapsed-to-2-to.md create mode 100644 .koan/memory/0011-intake-confidence-loop-removed-unnecessary-scout.md create mode 100644 .koan/memory/0012-koan-is-dog-fooded-on-its-own-development-meta.md create mode 100644 .koan/memory/0013-single-cognitive-goal-per-step-prevents-simulated.md create mode 100644 .koan/memory/0014-camelcase-wire-format-eliminates-renaming-layer.md create mode 100644 .koan/memory/0015-three-active-workflows-plan-milestones-stub.md create mode 100644 .koan/memory/0016-steering-vs-phase-boundary-message-routing-dual.md create mode 100644 .koan/memory/0017-thoughts-parameter-escape-hatch-only-task-output.md create mode 100644 .koan/memory/0018-behavioral-constraints-require-both-a-prompt.md create mode 100644 .koan/memory/0019-projection-events-record-facts-derived-state.md create mode 100644 .koan/memory/0020-memory-retrieval-static-directive-mechanical.md create mode 100644 .koan/memory/0021-memory-entry-writing-discipline-temporally.md create mode 100644 .koan/memory/0022-blocking-artifact-review-gate-removed-from-plan.md create mode 100644 .koan/memory/0023-phase-guidance-workflow-scope-framing-is-injected.md create mode 100644 .koan/memory/0024-getnextstep-must-be-a-pure-query-side-effects-of.md create mode 100644 .koan/memory/0025-scout-success-is-determined-by-exit-code-and.md create mode 100644 .koan/memory/0026-recoverable-vs-unrecoverable-error-classification.md create mode 100644 .koan/memory/0027-all-state-file-writes-use-atomic-tmp-file.md create mode 100644 .koan/memory/0028-frontend-css-token-promotion-hardcode-single-use.md create mode 100644 .koan/memory/0029-headerbar-rendered-phantom-opus-model-label.md create mode 100644 .koan/memory/0030-do-not-use-destructuring-defaults-as-display.md create mode 100644 .koan/memory/0031-voyage-ai-as-sole-retrieval-provider-voyage-4.md create mode 100644 .koan/memory/0032-plan-review-produced-unverified-critical-finding.md create mode 100644 .koan/memory/0033-new-mcp-tool-handlers-in-koanwebmcpendpointpy.md create mode 100644 .koan/memory/0034-koan-memory-sync-uses-sha-256-content-hash-not.md create mode 100644 .koan/memory/0037-code-comment-vs-memory-entry-filter-comment.md create mode 100644 .koan/memory/0038-cross-reference-repetition-in-prompt-instructions.md create mode 100644 .koan/memory/0039-memory-store-content-policy-rag-serves-unknown.md create mode 100644 .koan/memory/0040-memory-captures-persistent-always-true.md diff --git a/.gitignore b/.gitignore index 7846c4e..804a7d9 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,6 @@ .claude/ plans/ -.koan/ .env .env.* *.log diff --git a/.koan/memory/.gitignore b/.koan/memory/.gitignore new file mode 100644 index 0000000..fc5578b --- /dev/null +++ b/.koan/memory/.gitignore @@ -0,0 +1,2 @@ +.index/ +summary.md diff --git a/.koan/memory/0001-persistent-orchestrator-over-per-phase-cli.md b/.koan/memory/0001-persistent-orchestrator-over-per-phase-cli.md new file mode 100644 index 0000000..510c996 --- /dev/null +++ b/.koan/memory/0001-persistent-orchestrator-over-per-phase-cli.md @@ -0,0 +1,8 @@ +--- +title: Persistent orchestrator over per-phase CLI spawning +type: decision +created: '2026-04-16T07:13:41Z' +modified: '2026-04-16T07:13:41Z' +--- + +This entry documents the orchestrator spawn architecture decision in koan's workflow engine (`koan/driver.py`). On 2026-04-02, Leon redesigned the system to replace per-phase CLI process spawning with a single long-lived orchestrator process running the entire workflow in one continuous session. Previously, each planning phase spawned a fresh `claude`, `codex`, or `gemini` CLI process; a separate `workflow-orchestrator` subagent was then spawned to present the user with a phase-selection decision after each phase completed. Leon's rationale: per-phase spawning caused compounding context loss (each new process re-derived what the previous had explored), and the workflow-orchestrator role was architecturally wasteful -- "a process-boot just to ask a question." Two alternatives were explicitly rejected: (1) API-based conversation (driver calling the LLM API directly) -- would have bypassed the runner abstraction handling model selection, MCP config, output streaming, and thinking mode; (2) context injection into fresh processes per phase -- cheaper but fails to provide a persistent reasoning chain and does not eliminate the workflow-orchestrator overhead. The redesign landed in `koan/driver.py` as a single `spawn_subagent()` call awaiting the orchestrator's exit, and added `koan_set_phase` as the new phase-transition tool replacing the two-tool `koan_propose_workflow` / `koan_set_next_phase` dance. diff --git a/.koan/memory/0002-step-first-workflow-pattern-boot-prompt-is.md b/.koan/memory/0002-step-first-workflow-pattern-boot-prompt-is.md new file mode 100644 index 0000000..9e3a2ea --- /dev/null +++ b/.koan/memory/0002-step-first-workflow-pattern-boot-prompt-is.md @@ -0,0 +1,8 @@ +--- +title: Step-first workflow pattern -- boot prompt is exactly one sentence +type: decision +created: '2026-04-16T07:13:50Z' +modified: '2026-04-16T07:13:50Z' +--- + +The step-first workflow pattern governs how all LLM subagent CLI processes in koan receive task instructions. On 2026-02-10, Leon established this as a load-bearing architectural invariant in the koan initial design (documented in `docs/architecture.md` as Invariant 2 and enforced in `koan/web/mcp_endpoint.py`). The rule: every subagent's boot prompt is exactly one sentence -- role identity plus "Call koan_complete_step to receive your instructions." Task details, phase guidance, and tool lists arrive exclusively as the return value of the first `koan_complete_step` MCP call. The pattern was motivated by a failure mode observed with haiku-class (weaker) models: complex task instructions in the boot prompt caused these models to produce text output on the first turn and exit without ever entering the tool-calling loop. Three reinforcement mechanisms make the pattern robust across model capability levels: primacy (boot prompt is the LLM's very first message), recency (`format_step()` in `koan/phases/format_step.py` always appends "WHEN DONE: Call koan_complete_step..." last), and muscle memory (by step 2 the LLM has called the tool multiple times, locking in the pattern). diff --git a/.koan/memory/0003-server-authoritative-projection-via-json-patch.md b/.koan/memory/0003-server-authoritative-projection-via-json-patch.md new file mode 100644 index 0000000..4c2adec --- /dev/null +++ b/.koan/memory/0003-server-authoritative-projection-via-json-patch.md @@ -0,0 +1,8 @@ +--- +title: Server-authoritative projection via JSON Patch over symmetric dual fold +type: decision +created: '2026-04-16T07:13:57Z' +modified: '2026-04-16T07:13:57Z' +--- + +The koan projection system maintains frontend-visible workflow state for the browser dashboard, served via Server-Sent Events from `koan/projections.py`. On 2026-03-29, Leon decided to replace a dual fold architecture with a server-authoritative JSON Patch model. The prior design maintained two independent fold implementations -- one in Python (`koan/projections.py`) and one in TypeScript (`frontend/src/sse/connect.ts`) -- required to produce identical projections from the same event sequence. Two production bugs traced directly to these folds diverging: fragmented thinking cards in the activity feed, and scout events appearing incorrectly in the primary agent's conversation feed. Leon's decision: Python computes the fold and the RFC 6902 JSON Patch diff after each event; the browser applies patches mechanically via `fast-json-patch` with no fold logic, no event interpretation, and no business rules. Simultaneously, Leon adopted camelCase for all wire-format keys so patches apply directly to the Zustand store without a field-renaming layer. The correctness guarantee is now structural: one fold in one place. diff --git a/.koan/memory/0004-file-boundary-invariant-llms-write-markdown.md b/.koan/memory/0004-file-boundary-invariant-llms-write-markdown.md new file mode 100644 index 0000000..e464edc --- /dev/null +++ b/.koan/memory/0004-file-boundary-invariant-llms-write-markdown.md @@ -0,0 +1,8 @@ +--- +title: File boundary invariant -- LLMs write markdown, driver writes JSON +type: decision +created: '2026-04-16T07:14:03Z' +modified: '2026-04-16T07:14:03Z' +--- + +The file boundary invariant is a load-bearing architectural constraint in koan governing file ownership across the system's actors. On 2026-02-10, Leon established this rule in the koan initial design (documented in `docs/architecture.md` as Invariant 1). The rule: LLM subagents write markdown files only; the koan driver (`koan/driver.py`) reads and writes JSON state files exclusively; tool code in `koan/web/mcp_endpoint.py` bridges both worlds by writing JSON state (for the driver) and templated markdown status files (for LLMs) in the same operation. Leon's stated rationale: if an LLM writes a JSON file, schema drift and parse errors in the payload become runtime failures in the deterministic driver, while markdown is forgiving. The invariant is enforced structurally -- planning-role subagents have write access scoped to the run directory (`~/.koan/runs/<id>/`) but no mechanism to produce JSON state files, and the driver reads JSON state files and exit codes only, never parsing markdown. diff --git a/.koan/memory/0005-phase-trust-model-plan-review-as-designated.md b/.koan/memory/0005-phase-trust-model-plan-review-as-designated.md new file mode 100644 index 0000000..c917708 --- /dev/null +++ b/.koan/memory/0005-phase-trust-model-plan-review-as-designated.md @@ -0,0 +1,10 @@ +--- +title: Phase trust model -- plan-review as designated adversarial verifier +type: decision +created: '2026-04-16T07:35:13Z' +modified: '2026-04-16T07:35:13Z' +related: +- 0001-persistent-orchestrator-over-per-phase-cli.md +--- + +The plan workflow's phase trust architecture in koan (`docs/phase-trust.md`, `koan/lib/workflows.py`) was designed around an asymmetric verification model. On 2026-02-10, Leon formalized this as part of the initial koan design: phases in the plan pipeline (intake, plan-spec, execute) were built to trust each other's outputs without re-verification; only plan-review was designated as the adversarial verifier. Leon documented the rationale in `docs/phase-trust.md`: cross-phase re-verification is the "intrinsic self-correction" anti-pattern -- research shows the same LLM re-checking its own prior work is more likely to change correct conclusions to incorrect ones than the reverse. Leon gave plan-review the CRITIC role: it uses the actual codebase as an external tool to check every file path, function name, signature, and type claim in `plan.md` against reality. Leon also decided that plan-review would be advisory only -- it reports findings with severity classification and may suggest looping back to plan-spec for critical or major issues, but it does not modify `plan.md` itself. diff --git a/.koan/memory/0006-directory-as-contract-taskjson-over-cli-flags-for.md b/.koan/memory/0006-directory-as-contract-taskjson-over-cli-flags-for.md new file mode 100644 index 0000000..f721145 --- /dev/null +++ b/.koan/memory/0006-directory-as-contract-taskjson-over-cli-flags-for.md @@ -0,0 +1,10 @@ +--- +title: Directory-as-contract -- task.json over CLI flags for subagent configuration +type: decision +created: '2026-04-16T07:35:24Z' +modified: '2026-04-16T07:35:24Z' +related: +- 0004-file-boundary-invariant-llms-write-markdown.md +--- + +The subagent configuration mechanism in koan (`koan/subagent.py`, `docs/subagents.md`) was redesigned on 2026-02-10 when Leon replaced a 9-CLI-flag approach with a task.json file convention, later documented as Invariant 6 (Directory-as-contract) in `docs/architecture.md`. The previous design passed task configuration as 9 CLI arguments; Leon replaced it after identifying four problems: (1) the flat flag namespace caused naming collisions (`--koan-role` vs `--koan-scout-role`); (2) role-specific fields mixed with common fields without structure; (3) `--koan-retry-context` needed to carry multi-paragraph summaries exceeding practical CLI limits; (4) after a crash, reconstructing what a subagent had been asked required parsing process arguments from system logs. Leon adopted the convention that the driver would write `task.json` atomically (tmp + `os.rename()`) to the subagent directory before spawn. The subagent discovers its MCP endpoint by reading `mcp_url` from that file. No structured configuration flows through CLI flags, environment variables, or other process-level channels. Leon designated `task.json` as write-once by the parent before spawn and read-once by the parent at agent registration, never modified afterward. diff --git a/.koan/memory/0007-dual-fold-system-audit-fold-per-subagent-disk-vs.md b/.koan/memory/0007-dual-fold-system-audit-fold-per-subagent-disk-vs.md new file mode 100644 index 0000000..964122c --- /dev/null +++ b/.koan/memory/0007-dual-fold-system-audit-fold-per-subagent-disk-vs.md @@ -0,0 +1,11 @@ +--- +title: Dual fold system -- audit fold (per-subagent disk) vs projection fold (workflow + SSE) +type: decision +created: '2026-04-16T07:35:36Z' +modified: '2026-04-16T07:35:36Z' +related: +- 0003-server-authoritative-projection-via-json-patch.md +--- + +The state-management layer of koan (`koan/audit/fold.py`, `koan/projections.py`) was designed around two independent fold systems. On 2026-03-29, Leon documented the distinction in `docs/architecture.md` (section "Two Fold Systems"). Leon designed the audit fold to process per-subagent audit events from each subagent's `events.jsonl`, materialize a per-subagent `Projection` object written to `state.json` on disk after every event, and serve debugging and post-mortem consumers. Leon designed the projection fold to process workflow-level projection events emitted by `ProjectionStore.push_event()`, maintain a single in-memory `Projection` covering all agents and run state for the entire workflow, and serve the browser frontend via SSE. Leon chose to keep the two systems independent rather than merging them: the audit fold needed per-event disk writes for durability, while the projection fold needed to stay in-memory for SSE streaming throughput. Leon established the rule that state visible only in logs belongs to the audit fold, while state visible in the browser UI belongs to the projection fold. diff --git a/.koan/memory/0008-three-tier-model-system-strongstandardcheap-over.md b/.koan/memory/0008-three-tier-model-system-strongstandardcheap-over.md new file mode 100644 index 0000000..f5ac069 --- /dev/null +++ b/.koan/memory/0008-three-tier-model-system-strongstandardcheap-over.md @@ -0,0 +1,10 @@ +--- +title: Three-tier model system (strong/standard/cheap) over per-role model configuration +type: decision +created: '2026-04-16T07:35:45Z' +modified: '2026-04-16T07:35:45Z' +related: +- 0001-persistent-orchestrator-over-per-phase-cli.md +--- + +The model selection system in koan (`koan/config.py`, `docs/subagents.md` -- Model Tiers section) was designed on 2026-02-10 when Leon grouped the 6+ agent roles into three capability tiers rather than mapping each role to an individual model. Leon defined the tiers as: `strong` (orchestrator -- complex multi-step reasoning), `standard` (executor -- reliable tool use for code implementation), and `cheap` (scout -- narrow codebase investigation). Leon encoded the role-to-tier mapping in `koan/config.py`. Leon adopted a profile-based configuration system persisted to `~/.koan/config.json` that binds each tier to a specific runner type and model name; switching profiles changes all three tier bindings at once without touching role definitions. Leon rejected per-role model configuration because, with 6+ roles, each model change would require updating 6+ bindings; the tier system reduces that to 3 bindings per profile switch. diff --git a/.koan/memory/0009-permission-fence-impractical-across-llm-backends.md b/.koan/memory/0009-permission-fence-impractical-across-llm-backends.md new file mode 100644 index 0000000..1552cc9 --- /dev/null +++ b/.koan/memory/0009-permission-fence-impractical-across-llm-backends.md @@ -0,0 +1,10 @@ +--- +title: Permission fence impractical across LLM backends; planned for removal +type: lesson +created: '2026-04-16T08:34:06Z' +modified: '2026-04-16T08:34:06Z' +related: +- 0001-persistent-orchestrator-over-per-phase-cli.md +--- + +The permission fence in koan (`koan/lib/permissions.py`) was initially designed as a load-bearing default-deny gate enforced on every MCP tool call. On 2026-02-10, Leon established it as Invariant 4 in `docs/architecture.md`, describing it as a load-bearing rule that blocked unknown roles and tools. By approximately 2026-04-08, Leon reversed this assessment, stating in a Claude Code project memory note that the fence is "probably not worth maintaining" because many coding agents do not support accurately disabling tool features, making the gate impractical to enforce reliably across different LLM backends. Leon identified the root cause: enforcement does not work reliably across LLM backends, and the maintenance cost outweighs the benefit. Leon directed that no effort should be invested in extending or hardening the permission fence and that it may be completely removed in a future update. The fence still exists in the codebase as of 2026-04-16, but is deprioritized; the architecture documentation was not updated to reflect this direction change and still describes it as load-bearing. diff --git a/.koan/memory/0010-curation-phase-3-step-layout-collapsed-to-2-to.md b/.koan/memory/0010-curation-phase-3-step-layout-collapsed-to-2-to.md new file mode 100644 index 0000000..53f01d4 --- /dev/null +++ b/.koan/memory/0010-curation-phase-3-step-layout-collapsed-to-2-to.md @@ -0,0 +1,10 @@ +--- +title: 'Curation phase: 3-step layout collapsed to 2 to prevent meaty-step skip failure' +type: lesson +created: '2026-04-16T08:34:15Z' +modified: '2026-04-16T08:34:15Z' +related: +- 0002-step-first-workflow-pattern-boot-prompt-is.md +--- + +The curation phase module in koan (`koan/phases/curation.py`) was originally implemented as a 3-step workflow with step names "Survey", "Curate", and "Finalize/Reporting". During a curation run whose output Leon reviewed in screenshots, the orchestrator was observed to confuse "Survey" with intake-style exploration and then reach "phase complete" without ever calling `koan_memorize` -- a failure mode where the curation phase ended with zero memory writes. Leon identified two root causes: (1) the name "Survey" triggered intake-like behavior; (2) there was no per-step structural framing (no workflow_shape, goal, or tools list) visible at the moment the LLM decided whether to advance. On 2026-04-16, Leon approved a redesign that collapsed the 3 steps to 2 (Inventory and Memorize), named after their primary tool effects (`koan_memory_status` and `koan_memorize`) to make step-skipping visible, and added `<workflow_shape>`, `<goal>`, and `<tools_this_step>` XML blocks to every step, re-injected at each `koan_complete_step` call so the phase structure is visible at the moment of use rather than only at step 1. diff --git a/.koan/memory/0011-intake-confidence-loop-removed-unnecessary-scout.md b/.koan/memory/0011-intake-confidence-loop-removed-unnecessary-scout.md new file mode 100644 index 0000000..547f371 --- /dev/null +++ b/.koan/memory/0011-intake-confidence-loop-removed-unnecessary-scout.md @@ -0,0 +1,12 @@ +--- +title: 'Intake confidence loop removed: unnecessary scout batches and intrinsic self-correction + risk' +type: lesson +created: '2026-04-16T08:34:26Z' +modified: '2026-04-16T08:34:26Z' +related: +- 0002-step-first-workflow-pattern-boot-prompt-is.md +- 0005-phase-trust-model-plan-review-as-designated.md +--- + +The intake phase in koan (`koan/phases/intake.py`) previously included a confidence-gated loop where steps 2-4 would repeat based on a structured confidence value. Leon removed this loop in favour of the current 2-step design (Gather + Deepen), as documented in `docs/intake-loop.md` (Pitfalls section -- "Don't add a confidence loop"), confirmed in the codebase as of 2026-04-16. Leon identified three reasons for removal: (a) the loop produced unnecessary second scout batches -- repeating expensive scout runs that a focused single Deepen pass could replace; (b) the self-verification step ("Reflect") risked intrinsic self-correction without external grounding, meaning the same LLM checking its own prior reasoning rather than verifying against actual codebase files; (c) one focused pass through the Deepen step was sufficient when the step was designed to be thorough. Leon replaced the confidence gate with a design that defines phase completion by depth of understanding rather than loop iteration count, and explicitly removed per-round question limits that had previously created an implicit ceiling discouraging iterative deepening. diff --git a/.koan/memory/0012-koan-is-dog-fooded-on-its-own-development-meta.md b/.koan/memory/0012-koan-is-dog-fooded-on-its-own-development-meta.md new file mode 100644 index 0000000..4cff905 --- /dev/null +++ b/.koan/memory/0012-koan-is-dog-fooded-on-its-own-development-meta.md @@ -0,0 +1,8 @@ +--- +title: Koan is dog-fooded on its own development -- meta-context for agents +type: context +created: '2026-04-16T08:34:35Z' +modified: '2026-04-16T08:34:35Z' +--- + +Koan is a solo project maintained by Leon Mergen, as confirmed by Leon in a curation run on 2026-04-16. Since the initial koan design on 2026-02-10, Leon adopted a practice of using koan's own plan workflow to develop koan itself -- dog-fooding the system as its own first user. This creates a meta-context constraint for any agent working on the koan codebase: workflow instructions and phase prompts in `koan/phases/*.py` and `koan/lib/workflows.py` are runtime instructions for koan's orchestrator subagents to execute, not instructions for the agent currently editing the source files. For example, the `SYSTEM_PROMPT` strings in `koan/phases/intake.py` are the intake orchestrator's role instructions; `koan/phases/curation.py` contains the step guidance that koan's curation orchestrator follows. An agent must not conflate "a prompt being analyzed as source material" with "a prompt being given as a direct instruction." Leon named this the "meta use of koan" and stated it explicitly in the task prompt for the 2026-04-16 curation run. diff --git a/.koan/memory/0013-single-cognitive-goal-per-step-prevents-simulated.md b/.koan/memory/0013-single-cognitive-goal-per-step-prevents-simulated.md new file mode 100644 index 0000000..3987abf --- /dev/null +++ b/.koan/memory/0013-single-cognitive-goal-per-step-prevents-simulated.md @@ -0,0 +1,11 @@ +--- +title: Single cognitive goal per step -- prevents simulated refinement +type: decision +created: '2026-04-16T08:37:25Z' +modified: '2026-04-16T08:37:25Z' +related: +- 0002-step-first-workflow-pattern-boot-prompt-is.md +- 0010-curation-phase-3-step-layout-collapsed-to-2-to.md +--- + +The step design constraint for koan phases (`docs/architecture.md` -- Pitfalls section, "Don't give a step multiple cognitive goals") was established on 2026-02-10 when Leon set a rule: each `koan_complete_step` call must correspond to exactly one cognitive goal. Leon identified the failure mode that motivated this rule: when a single step combines multiple goals ("do A, then B, then C"), the LLM can engage in "simulated refinement" -- artificially downgrading its output for A in order to manufacture visible improvement in C, without genuinely improving anything. Leon documented this as a design constraint: when adding a new phase, each step must answer "what is the single thing this step accomplishes?" and if the answer requires "and then," the step must be split. Leon's reference designs in `koan/phases/plan_spec.py` (Analyze + Write), `koan/phases/intake.py` (Gather + Deepen), and `koan/phases/curation.py` (Inventory + Memorize) each place cognitively distinct operations into separate `koan_complete_step` calls. diff --git a/.koan/memory/0014-camelcase-wire-format-eliminates-renaming-layer.md b/.koan/memory/0014-camelcase-wire-format-eliminates-renaming-layer.md new file mode 100644 index 0000000..ff09513 --- /dev/null +++ b/.koan/memory/0014-camelcase-wire-format-eliminates-renaming-layer.md @@ -0,0 +1,12 @@ +--- +title: 'CamelCase wire format: eliminates renaming layer between projection and Zustand + store' +type: decision +created: '2026-04-16T08:37:35Z' +modified: '2026-04-16T08:37:35Z' +related: +- 0003-server-authoritative-projection-via-json-patch.md +- 0007-dual-fold-system-audit-fold-per-subagent-disk-vs.md +--- + +The SSE wire format for koan's projection system (`koan/projections.py`, `frontend/src/sse/connect.ts`) was designed to use camelCase keys for all serialized projection fields. On 2026-03-29, Leon documented this decision in `docs/projections.md` (Design Decisions -- "Why camelCase on the wire"). Leon's rationale: emitting snake_case from the server would require a `mapProjectionToStore()` renaming function in the frontend TypeScript plus a `projectionState` shadow object for patch application (patches must apply to the pre-renamed dict, not the renamed Zustand store); every new projection field would require a rename entry in that mapping. Leon identified this mapping layer as frontend business logic, contradicting his "frontend has zero business logic" principle. By adopting camelCase -- via Pydantic's `alias_generator=to_camel` in `KoanBaseModel` (`koan/projections.py`) -- patches produced by `jsonpatch.make_patch()` apply directly to the Zustand store in `frontend/src/store/`, and snapshot state spreads directly into the store at reconnect with no field renaming. diff --git a/.koan/memory/0015-three-active-workflows-plan-milestones-stub.md b/.koan/memory/0015-three-active-workflows-plan-milestones-stub.md new file mode 100644 index 0000000..99e7720 --- /dev/null +++ b/.koan/memory/0015-three-active-workflows-plan-milestones-stub.md @@ -0,0 +1,10 @@ +--- +title: 'Three active workflows: plan, milestones (stub), curation' +type: context +created: '2026-04-16T08:37:42Z' +modified: '2026-04-16T08:37:42Z' +related: +- 0001-persistent-orchestrator-over-per-phase-cli.md +--- + +The koan workflow registry (`koan/lib/workflows.py`) defined three workflows as of 2026-04-16: `plan` (the primary active pipeline), `milestones` (a stub), and `curation` (standalone memory maintenance). Leon added the `curation` workflow when implementing the koan memory system, giving it its own `Workflow` dataclass in the `WORKFLOWS` dict in `koan/lib/workflows.py`. The `plan` workflow runs: intake -> plan-spec -> plan-review -> execute -> curation (postmortem). The `milestones` workflow ran intake only and was a stub as of 2026-04-16, intended for broad multi-subsystem initiatives but not yet implemented beyond the intake phase. The `curation` workflow runs a single curation phase using the `_STANDALONE_DIRECTIVE` string defined in `koan/lib/workflows.py` and is invoked when the user wants to maintain project memory outside of a development workflow run. Note: an earlier Claude Code project memory entry (written approximately 2026-04-08) listed only two workflows (plan and milestones); the curation workflow was added after that entry was written. diff --git a/.koan/memory/0016-steering-vs-phase-boundary-message-routing-dual.md b/.koan/memory/0016-steering-vs-phase-boundary-message-routing-dual.md new file mode 100644 index 0000000..a12348e --- /dev/null +++ b/.koan/memory/0016-steering-vs-phase-boundary-message-routing-dual.md @@ -0,0 +1,11 @@ +--- +title: 'Steering vs phase-boundary message routing: dual-queue design' +type: decision +created: '2026-04-16T08:37:51Z' +modified: '2026-04-16T08:37:51Z' +related: +- 0001-persistent-orchestrator-over-per-phase-cli.md +- 0002-step-first-workflow-pattern-boot-prompt-is.md +--- + +The user message routing system in koan (`koan/web/mcp_endpoint.py`, `docs/ipc.md` -- Chat Message Delivery section) was designed around two independent message queues. On 2026-03-29, Leon documented the distinction in `docs/ipc.md`. Leon designed phase-boundary messages (sent while `koan_yield` is blocking and `app_state.yield_future` is set) to be routed to `user_message_buffer` and returned directly as the `koan_yield` MCP tool result when the future resolves. Leon designed steering messages (sent while the orchestrator is mid-step and `yield_future` is `None`) to be routed to `steering_queue` and appended to the next outgoing tool response via `_drain_and_append_steering()`, so the LLM integrates them without abandoning the current step. Leon designated both queues as atomically drained and independent to prevent double-delivery: `drain_user_messages()` clears `user_message_buffer` and `drain_steering_messages()` clears `steering_queue`. The `POST /api/chat` endpoint inspects `yield_future` at the moment of message receipt to determine which queue to route to. diff --git a/.koan/memory/0017-thoughts-parameter-escape-hatch-only-task-output.md b/.koan/memory/0017-thoughts-parameter-escape-hatch-only-task-output.md new file mode 100644 index 0000000..57119f8 --- /dev/null +++ b/.koan/memory/0017-thoughts-parameter-escape-hatch-only-task-output.md @@ -0,0 +1,11 @@ +--- +title: '`thoughts` parameter -- escape hatch only; task output goes to files' +type: procedure +created: '2026-04-16T09:00:44Z' +modified: '2026-04-16T09:00:44Z' +related: +- 0004-file-boundary-invariant-llms-write-markdown.md +- 0002-step-first-workflow-pattern-boot-prompt-is.md +--- + +The `koan_complete_step` tool in the koan orchestration system accepts a `thoughts` parameter. On 2026-04-16, the architecture documentation in `docs/subagents.md` established that `thoughts` must never be used to capture task output: the `thoughts` parameter is an escape hatch only. The rationale recorded in that document: some models (particularly weaker ones) cannot produce text output and a tool call in the same response turn; `thoughts` gives those models a way to call the tool without exiting the workflow. Task output -- summaries, reports, structured data, findings -- was established to go exclusively to files such as `findings.md`, `landscape.md`, and `plan.md` in the run directory at `~/.koan/runs/<run_id>/`. The driver, which runs in `koan/driver.py`, reads those files after the subagent exits; it does not read `thoughts` content, and `thoughts` values are not preserved in the audit log (`events.jsonl`). Any subagent that extracts output through `thoughts` rather than file writes creates a silent data loss path. diff --git a/.koan/memory/0018-behavioral-constraints-require-both-a-prompt.md b/.koan/memory/0018-behavioral-constraints-require-both-a-prompt.md new file mode 100644 index 0000000..3dda3d8 --- /dev/null +++ b/.koan/memory/0018-behavioral-constraints-require-both-a-prompt.md @@ -0,0 +1,10 @@ +--- +title: Behavioral constraints require both a prompt instruction and a mechanical gate +type: decision +created: '2026-04-16T09:00:52Z' +modified: '2026-04-16T09:00:52Z' +related: +- 0009-permission-fence-impractical-across-llm-backends.md +--- + +The koan orchestration system uses `koan/web/mcp_endpoint.py` and `koan/lib/permissions.py` to enforce behavioral constraints for subagent roles. On 2026-04-16, the architecture documentation in `docs/architecture.md` established that behavioral constraints require both a prompt instruction and a mechanical gate. The maintainer recorded the rationale: prompt instructions alone were found insufficient because LLMs can ignore them without error; mechanical gates alone were found insufficient because they produce cryptic "blocked" tool errors with no context for the model to self-correct and retry. The document identified three enforcement mechanisms: (1) the permission fence (`check_permission` in `koan/lib/permissions.py`), which blocks disallowed tool calls and returns a rejection message; (2) `validate_step_completion()`, which blocks `koan_complete_step` advancement until required pre-calls have been made; and (3) tool descriptions, which provide soft guidance only and cannot be enforced. The maintainer established the rule that any constraint mattering for correctness requires both a prompt instruction (so the LLM understands the requirement) and a mechanical gate (so non-compliance is caught and corrected rather than silently propagated). diff --git a/.koan/memory/0019-projection-events-record-facts-derived-state.md b/.koan/memory/0019-projection-events-record-facts-derived-state.md new file mode 100644 index 0000000..ed1dc04 --- /dev/null +++ b/.koan/memory/0019-projection-events-record-facts-derived-state.md @@ -0,0 +1,11 @@ +--- +title: Projection events record facts; derived state belongs in the fold function +type: decision +created: '2026-04-16T09:01:03Z' +modified: '2026-04-16T09:01:03Z' +related: +- 0007-dual-fold-system-audit-fold-per-subagent-disk-vs.md +- 0003-server-authoritative-projection-via-json-patch.md +--- + +The koan projection system in `koan/projections.py` uses an event-sourced fold architecture shared with the audit system in `koan/audit/fold.py`. On 2026-04-16, the architecture documentation in `docs/architecture.md` established the invariant that events record facts -- things that happened -- while derived state belongs in the fold function, not in the event log. The maintainer documented a specific anti-pattern to avoid: emitting a `subagent_idle` event to signal "no agent is currently running." The maintainer recorded that "no agent" is derived from the `agent_exited` event, not a fact in itself, and that emitting it as a separate event conflates the audit log with the projection. The documented correct pattern was: emit `agent_exited`, and let the fold function derive `primary_agent = None` from that event. The architecture documentation also established that `fold()` is required to be a pure function -- the maintainer specified that given the same event sequence it must produce the same projection with no I/O, randomness, or side effects, and that this purity guarantee is broken when derived state appears as events. diff --git a/.koan/memory/0020-memory-retrieval-static-directive-mechanical.md b/.koan/memory/0020-memory-retrieval-static-directive-mechanical.md new file mode 100644 index 0000000..c48a6d9 --- /dev/null +++ b/.koan/memory/0020-memory-retrieval-static-directive-mechanical.md @@ -0,0 +1,11 @@ +--- +title: 'Memory retrieval: static-directive mechanical injection handles unknown unknowns; + agent tools handle known unknowns' +type: decision +created: '2026-04-16T09:01:12Z' +modified: '2026-04-16T09:01:12Z' +related: +- 0012-koan-is-dog-fooded-on-its-own-development-meta.md +--- + +The koan memory system, documented in `docs/memory-system.md`, implements two retrieval mechanisms. On 2026-04-16, the memory system specification established an asymmetric design: mechanical context injection (automatic, at phase boundaries) using static retrieval directives authored by the workflow designer, and agent-invoked tools (`koan_search` and `koan_reflect`) called on-demand during reasoning. The maintainer recorded the rationale: the two mechanisms were designed to solve different problems. Mechanical injection was designed to handle unknown unknowns -- knowledge the agent does not know to search for (a procedure about credential handling, a lesson about a past failure); since the agent cannot formulate a query for what it does not know exists, the injection must run without relying on agent reasoning. Agent-invoked tools were designed to handle known unknowns -- gaps the agent recognizes during reasoning and can formulate targeted queries for. The specification explicitly rejected LLM-generated retrieval directives (having the orchestrator generate directives at runtime) because the maintainer established that such directives would produce queries biased toward what the orchestrator already knows, collapsing both mechanisms into one and leaving unknown unknowns uncovered. The static directive was documented as encoding structural knowledge about each phase type's typical needs, independent of any particular agent's reasoning state. diff --git a/.koan/memory/0021-memory-entry-writing-discipline-temporally.md b/.koan/memory/0021-memory-entry-writing-discipline-temporally.md new file mode 100644 index 0000000..79d40f6 --- /dev/null +++ b/.koan/memory/0021-memory-entry-writing-discipline-temporally.md @@ -0,0 +1,8 @@ +--- +title: Memory entry writing discipline -- temporally grounded, event-style prose +type: procedure +created: '2026-04-16T09:02:41Z' +modified: '2026-04-16T09:02:41Z' +--- + +The koan memory system stores entries in `.koan/memory/NNNN-*.md` files within the project repository. On 2026-04-16, the memory system specification in `docs/memory-system.md` established five writing discipline rules for all memory entry bodies. The maintainer recorded the rationale as grounded in SimpleMem's finding (Liu et al., 2026) that removing temporal normalization reduced Temporal F1 by 56.7%. Rule 1: every statement includes a date in YYYY-MM-DD form -- the date the fact became true or was observed. Rule 2: claims are attributed to their source ("user stated", "LLM inferred", "post-mortem identified"); user-stated facts carry higher trust than LLM-inferred facts. Rule 3: no forward-looking language ("we will", "should") -- instead write "On [date], user stated the plan was to..." Rule 4: name things concretely -- not "the database" but "PostgreSQL 16.2" or "the auth service's primary data store." Rule 5: each entry must stand alone, interpretable without any other file, true regardless of when it is read. The specification further established that the first 1-3 sentences situate the entry in the project by naming a specific subsystem, following Anthropic's contextual retrieval technique to reduce retrieval failures by 35%. diff --git a/.koan/memory/0022-blocking-artifact-review-gate-removed-from-plan.md b/.koan/memory/0022-blocking-artifact-review-gate-removed-from-plan.md new file mode 100644 index 0000000..8653d9f --- /dev/null +++ b/.koan/memory/0022-blocking-artifact-review-gate-removed-from-plan.md @@ -0,0 +1,12 @@ +--- +title: Blocking artifact review gate removed from plan workflow; chat-based phase + transitions replace it +type: decision +created: '2026-04-16T09:02:51Z' +modified: '2026-04-16T09:02:51Z' +related: +- 0015-three-active-workflows-plan-milestones-stub.md +- 0016-steering-vs-phase-boundary-message-routing-dual.md +--- + +The koan plan workflow in `koan/lib/workflows.py` includes four phases: intake, plan-spec, plan-review, and execute. On 2026-04-03, the workflow redesign plan (`plans/2026-04-03-workflow-types-and-plan-mode.md`) documented the removal of the blocking `koan_review_artifact` tool and the `POST /api/artifact-review` backend route. The maintainer recorded the rationale (Decision D1): artifact review and "what do I do next?" should be one conversation, not two sequential blocking gates. Under the removed design, the orchestrator wrote an artifact, then a blocking modal required Accept/Reject before phase transition suggestions appeared -- two sequential pauses for what is conceptually one moment: "here's what I did -- what should we do next?" The replacement pattern was established as: the orchestrator writes an artifact, gives a progress update in chat via `koan_yield`, and presents suggested next phases. The user reviews the artifact in the artifacts panel and responds conversationally. The maintainer noted this aligned with Traycer's design (the reverse-engineered origin system), which had no blocking modal -- artifacts appeared in a sidebar and the "what's next?" conversation implicitly covered feedback. diff --git a/.koan/memory/0023-phase-guidance-workflow-scope-framing-is-injected.md b/.koan/memory/0023-phase-guidance-workflow-scope-framing-is-injected.md new file mode 100644 index 0000000..ec42b72 --- /dev/null +++ b/.koan/memory/0023-phase-guidance-workflow-scope-framing-is-injected.md @@ -0,0 +1,12 @@ +--- +title: Phase guidance (workflow scope framing) is injected at the top of step 1, before + procedural instructions +type: decision +created: '2026-04-16T09:03:03Z' +modified: '2026-04-16T09:03:03Z' +related: +- 0002-step-first-workflow-pattern-boot-prompt-is.md +- 0015-three-active-workflows-plan-milestones-stub.md +--- + +The koan orchestration system injects per-workflow scope framing into each phase transition via the `phase_guidance` dict in `koan/lib/workflows.py`. On 2026-04-03, the workflow redesign plan (`plans/2026-04-03-workflow-types-and-plan-mode.md`) established Decision D8: the `phase_guidance` injection must appear at the TOP of step 1 guidance, before procedural instructions, not appended at the bottom. The maintainer recorded the rationale: scope framing is the strongest lever for controlling LLM posture -- "this is a focused change" produces fundamentally different behavior than "this is a broad initiative." If the LLM reads procedural instructions before scope framing, it begins reasoning from the wrong posture and receives the correction too late. The injection contract established by the maintainer specified five required sections per `phase_guidance` entry: Scope, Downstream consumer, Investigation posture, Question posture, and User override (always present, always last). In `koan/web/mcp_endpoint.py`, the `koan_set_phase` handler was designed to store `workflow.phase_guidance.get(phase, "")` in `PhaseContext.phase_instructions`, which step 1 of each phase module renders at the top of the returned guidance string. diff --git a/.koan/memory/0024-getnextstep-must-be-a-pure-query-side-effects-of.md b/.koan/memory/0024-getnextstep-must-be-a-pure-query-side-effects-of.md new file mode 100644 index 0000000..6eafa28 --- /dev/null +++ b/.koan/memory/0024-getnextstep-must-be-a-pure-query-side-effects-of.md @@ -0,0 +1,11 @@ +--- +title: '`get_next_step()` must be a pure query; side effects of loop-backs belong + in `on_loop_back()`' +type: procedure +created: '2026-04-16T09:03:11Z' +modified: '2026-04-16T09:03:11Z' +related: +- 0013-single-cognitive-goal-per-step-prevents-simulated.md +--- + +The koan phase module protocol, defined in `koan/phases/__init__.py`, requires phase modules to implement `get_next_step(step, ctx)` and optionally `on_loop_back(from_step, to_step, ctx)`. On 2026-04-16, the architecture documentation in `docs/architecture.md` established the invariant that `get_next_step()` must be a pure query -- it returns the next step number and nothing else. The maintainer documented the anti-pattern: placing state mutations (counter increments, setting `ctx.confidence = None`), event emissions, or I/O inside `get_next_step()` violates the contract because the function may be called multiple times in a single step transition. The documented correct pattern was: `get_next_step()` returns a step number only; any state changes that must accompany a backward step transition belong in `on_loop_back(from_step, to_step, ctx)`. The maintainer provided a concrete example: `get_next_step(4)` returning `2` for a loop-back is correct; incrementing `self.iteration` inside that call is wrong -- `self.iteration += 1` belongs in `on_loop_back(4, 2, ctx)`. diff --git a/.koan/memory/0025-scout-success-is-determined-by-exit-code-and.md b/.koan/memory/0025-scout-success-is-determined-by-exit-code-and.md new file mode 100644 index 0000000..55571e5 --- /dev/null +++ b/.koan/memory/0025-scout-success-is-determined-by-exit-code-and.md @@ -0,0 +1,10 @@ +--- +title: Scout success is determined by exit code and final_response, not by file existence +type: procedure +created: '2026-04-16T09:25:55Z' +modified: '2026-04-16T09:25:55Z' +related: +- 0006-directory-as-contract-taskjson-over-cli-flags-for.md +--- + +Koan scouts are spawned via `koan_request_scouts` in `koan/web/mcp_endpoint.py` and each produces a `findings.md` output file in their subagent directory under `~/.koan/runs/<run_id>/subagents/`. On 2026-04-16, the architecture documentation in `docs/architecture.md` established that scout success must be derived from the subagent's exit code and final response, not from checking whether `findings.md` exists. The maintainer recorded the rationale: a scout can write a partial `findings.md` and then crash -- file existence is not proof of completion. The documented success check in `koan/web/mcp_endpoint.py` was: `succeeded = result.exit_code == 0; findings = result.final_response or None`. Failed scouts (non-zero exit code) return `None` from the scout runner and are omitted from the concatenated findings returned to the parent orchestrator. The maintainer established that scout failures must be non-fatal -- a failed scout does not abort the parent's workflow; its task ID is reported in the `failures` array and its findings are simply omitted. diff --git a/.koan/memory/0026-recoverable-vs-unrecoverable-error-classification.md b/.koan/memory/0026-recoverable-vs-unrecoverable-error-classification.md new file mode 100644 index 0000000..453c704 --- /dev/null +++ b/.koan/memory/0026-recoverable-vs-unrecoverable-error-classification.md @@ -0,0 +1,11 @@ +--- +title: Recoverable vs unrecoverable error classification for model-output failures + in the MCP endpoint +type: decision +created: '2026-04-16T09:25:58Z' +modified: '2026-04-16T09:25:58Z' +related: +- 0002-step-first-workflow-pattern-boot-prompt-is.md +--- + +The koan MCP endpoint in `koan/web/mcp_endpoint.py` handles tool calls from LLM subagents. On 2026-04-16, the architecture documentation in `docs/architecture.md` established a two-category error classification. The maintainer recorded the rule: fail-fast is scoped to unrecoverable conditions only. Unrecoverable conditions were defined as: invariant/contract violations (e.g., missing or malformed `task.json` at subagent startup), unexpected states where there is no safe deterministic next action, and failures with no simple local recovery path. Recoverable conditions were defined as: malformed tool-call JSON or arguments from the LLM, tool argument schema validation failures, and disallowed or unknown tool calls. The documented handling for recoverable errors was: return a structured tool error so the model can self-correct and retry in the same subagent process. The maintainer noted the rationale: once an LLM subagent process exits due to a parse error, the workflow cannot resume from mid-step -- keeping the process alive for recoverable errors is the only way to maintain continuity. diff --git a/.koan/memory/0027-all-state-file-writes-use-atomic-tmp-file.md b/.koan/memory/0027-all-state-file-writes-use-atomic-tmp-file.md new file mode 100644 index 0000000..6d838f9 --- /dev/null +++ b/.koan/memory/0027-all-state-file-writes-use-atomic-tmp-file.md @@ -0,0 +1,11 @@ +--- +title: All state file writes use atomic tmp-file + os.rename() to prevent partial + reads under concurrent access +type: procedure +created: '2026-04-16T09:26:07Z' +modified: '2026-04-16T09:26:07Z' +related: +- 0004-file-boundary-invariant-llms-write-markdown.md +--- + +The koan driver in `koan/driver.py` and orchestrator tools in `koan/web/mcp_endpoint.py` write state files concurrently with a running web server and SSE subscribers. On 2026-04-16, the architecture documentation in `docs/architecture.md` established the atomic write pattern for all persistent state writes: write to a `.tmp` file, then call `os.rename()` to atomically replace the target. The maintainer recorded the rationale: a partial read of `state.json` caused by a mid-write concurrent access causes silent data corruption or spurious errors. The documented pattern was: `tmp = f"{file_path}.tmp"; json.dump(data, open(tmp, "w")); os.rename(tmp, file_path)`. This pattern was established as mandatory for: `run-state.json` in `~/.koan/runs/<run_id>/`, per-story `state.json` and `status.md` in `stories/{story_id}/`, per-subagent `task.json` written before spawn, and per-subagent `state.json` in the audit projection. The `koan/audit/event_log.py` module was documented as the canonical implementation of this pattern. diff --git a/.koan/memory/0028-frontend-css-token-promotion-hardcode-single-use.md b/.koan/memory/0028-frontend-css-token-promotion-hardcode-single-use.md new file mode 100644 index 0000000..766979d --- /dev/null +++ b/.koan/memory/0028-frontend-css-token-promotion-hardcode-single-use.md @@ -0,0 +1,9 @@ +--- +title: Frontend CSS token promotion -- hardcode single-use values, flag multi-component + values, never modify variables.css unilaterally +type: procedure +created: '2026-04-16T09:26:15Z' +modified: '2026-04-16T09:26:15Z' +--- + +The koan frontend design system uses CSS custom properties defined in `frontend/src/styles/variables.css` as the sole source of design tokens. On 2026-04-16, the component development rules in `frontend/src/components/AGENTS.md` established the token promotion rule for agents implementing frontend components. The maintainer established three tiers of handling for CSS values: (1) values used by exactly one component -- hardcode in that component's colocated `.css` file with a descriptive comment explaining what the value represents; (2) values used by multiple components, or clearly about to be -- flag for token promotion in the response to the user, do not add the token yourself; (3) `variables.css` is a protected file requiring explicit user approval before any modification -- agents must never add, rename, or remove tokens unilaterally. The class naming convention was also established: prefix CSS class names with a short component abbreviation to avoid collisions (e.g., `.tcr-` for ToolCallRow, `.hb-` for HeaderBar, `.ep-` for ElicitationPanel). The maintainer further established that `npx tsc --noEmit` must be run after any TypeScript/TSX changes to verify zero compilation errors before considering frontend work done. diff --git a/.koan/memory/0029-headerbar-rendered-phantom-opus-model-label.md b/.koan/memory/0029-headerbar-rendered-phantom-opus-model-label.md new file mode 100644 index 0000000..991d01d --- /dev/null +++ b/.koan/memory/0029-headerbar-rendered-phantom-opus-model-label.md @@ -0,0 +1,9 @@ +--- +title: HeaderBar rendered phantom 'opus' model label -- destructuring default masked + absent orchestrator state +type: lesson +created: '2026-04-16T11:29:34Z' +modified: '2026-04-16T11:29:34Z' +--- + +The `HeaderBar` organism in `frontend/src/components/organisms/HeaderBar.tsx` was found on 2026-04-16 to display 'opus' in the titlebar whenever no orchestrator was running. The user reported that when no primary agent was active, the model section should be empty. Investigation identified the root cause: the `orchestratorModel` parameter used a destructuring default `= 'opus'` (line 49). `App.tsx` correctly computed `orchestratorModel: primary?.model ?? undefined` -- returning `undefined` when `agents` contained no entry with `isPrimary: true`. However, the destructuring default silently substituted `'opus'` for `undefined`, making the prop appear present in all cases. The prop was already typed `orchestratorModel?: string` in `HeaderBarProps`, making the optionality semantically correct but defeated at the call site. On 2026-04-16, the fix was applied: the `= 'opus'` default was removed from the destructuring parameter, and the `hb-orchestrator` div was wrapped in `{orchestratorModel && (...)}` to suppress the entire section (both the `StatusDot` atom and the `hb-model` span) when no model was known. diff --git a/.koan/memory/0030-do-not-use-destructuring-defaults-as-display.md b/.koan/memory/0030-do-not-use-destructuring-defaults-as-display.md new file mode 100644 index 0000000..54e2151 --- /dev/null +++ b/.koan/memory/0030-do-not-use-destructuring-defaults-as-display.md @@ -0,0 +1,11 @@ +--- +title: Do not use destructuring defaults as display-value fallbacks for potentially + absent React props +type: procedure +created: '2026-04-16T11:29:39Z' +modified: '2026-04-16T11:29:39Z' +related: +- 0029-headerbar-rendered-phantom-opus-model-label.md +--- + +Koan's frontend component conventions, established on 2026-04-16 during the fix of a phantom model label in `frontend/src/components/organisms/HeaderBar.tsx`, include the following rule for handling potentially absent props. When a React component prop is typed `T | undefined` and `undefined` means 'data is genuinely absent' (not just unspecified), using a destructuring default that provides a display-value string -- e.g., `orchestratorModel = 'opus'` -- masks the absence and causes the UI element to render when it should not. The correct pattern, confirmed by the user on 2026-04-16, is: (a) omit the destructuring default so the parameter retains `undefined`; (b) use conditional rendering (`{prop && <Section />}`) to suppress the UI element entirely. This rule applies to any component where an absent prop signals 'nothing to show' rather than 'use a sensible default'. diff --git a/.koan/memory/0031-voyage-ai-as-sole-retrieval-provider-voyage-4.md b/.koan/memory/0031-voyage-ai-as-sole-retrieval-provider-voyage-4.md new file mode 100644 index 0000000..3ec1523 --- /dev/null +++ b/.koan/memory/0031-voyage-ai-as-sole-retrieval-provider-voyage-4.md @@ -0,0 +1,11 @@ +--- +title: Voyage AI as sole retrieval provider -- voyage-4-large embedding + rerank-2.5 + reranking, single VOYAGE_API_KEY +type: decision +created: '2026-04-16T13:30:42Z' +modified: '2026-04-16T13:30:42Z' +--- + +The koan memory retrieval backend (`koan/memory/retrieval/`) chose Voyage AI as its sole external provider for both embedding and reranking. On 2026-04-16, when planning the retrieval backend implementation, the task description had specified Cohere `rerank-v3.5` for reranking (with `COHERE_API_KEY`) alongside Voyage for embedding. The user overrode this during plan-spec and directed consolidation onto Voyage only. Voyage AI's `voyage-4-large` model handles dense embeddings; `rerank-2.5` handles cross-encoder reranking after RRF fusion. Both are accessed via `voyageai.AsyncClient(api_key=VOYAGE_API_KEY)`, requiring only one environment variable. + +The user's rationale: a single provider simplifies credential management (one `VOYAGE_API_KEY` instead of two), reduces the Python dependency count (no `cohere` package required alongside `voyageai`), and keeps the full retrieval pipeline within one vendor relationship. The `voyageai` package provides both `AsyncClient.embed()` and `AsyncClient.rerank()` under the same API key. diff --git a/.koan/memory/0032-plan-review-produced-unverified-critical-finding.md b/.koan/memory/0032-plan-review-produced-unverified-critical-finding.md new file mode 100644 index 0000000..1f62fc6 --- /dev/null +++ b/.koan/memory/0032-plan-review-produced-unverified-critical-finding.md @@ -0,0 +1,15 @@ +--- +title: Plan-review produced unverified Critical finding about voyage-4-large; unverified + bold claims during review cause unnecessary work +type: lesson +created: '2026-04-16T13:30:54Z' +modified: '2026-04-16T13:30:54Z' +--- + +The plan-review phase for the koan retrieval backend (`koan/memory/retrieval/`) produced an incorrect critical finding on 2026-04-16. The review agent flagged `VOYAGE_DIM = 1024` in `koan/memory/retrieval/index.py` as "Critical," asserting that `voyage-4-large` outputs 2048 dimensions and would cause PyArrow schema mismatches on first index write. The assertion was based on inference from the model name ("large" suggesting larger output size), with no documentation check performed. + +The user verified against the Voyage AI documentation and confirmed the constant was correct: `voyage-4-large` supports 256, 512, 1024 (default), and 2048 output dimensions. The plan proceeded unchanged. + +Root cause: the reviewer treated an assumption as a verified fact and labeled it "Critical." Unverified bold claims during adversarial review are particularly harmful because high-severity labels override the planner's judgment, create unnecessary revision cycles, and erode trust in the review phase itself. The cascade effect: if the planner had accepted the finding without checking, the schema would have been changed to 2048 dims, breaking compatibility with the voyage-4-large default output. + +A review agent should cite the specific documentation, test result, or source code reference that grounds a critical claim. An unverified inference stated at high confidence is worse than a verified minor finding. diff --git a/.koan/memory/0033-new-mcp-tool-handlers-in-koanwebmcpendpointpy.md b/.koan/memory/0033-new-mcp-tool-handlers-in-koanwebmcpendpointpy.md new file mode 100644 index 0000000..fb517ee --- /dev/null +++ b/.koan/memory/0033-new-mcp-tool-handlers-in-koanwebmcpendpointpy.md @@ -0,0 +1,24 @@ +--- +title: 'New MCP tool handlers in koan/web/mcp_endpoint.py must use try/finally with + result_str: str | None = None' +type: procedure +created: '2026-04-16T13:31:07Z' +modified: '2026-04-16T13:31:07Z' +--- + +When adding any new `@mcp.tool(name="...")` handler to `koan/web/mcp_endpoint.py`, follow the established lifecycle pattern. On 2026-04-16, the plan-review phase caught a deviation in the initial `koan_search` draft: the draft called `end_tool_call` inside both the except block and after the try/except, and placed `_drain_and_append_steering` outside the try block. The user-approved correction, verified against `koan_memorize` at line 906, `koan_forget` at line 966, and `koan_memory_status` at line 1001, uses this structure: + +``` +result_str: str | None = None +try: + # ... do work ... + result_str = json.dumps(...) + result_str = _drain_and_append_steering(result_str, agent) + return result_str +except SpecificError as e: + raise ToolError(json.dumps({"error": "...", "message": str(e)})) +finally: + end_tool_call(agent, call_id, tool_name, result_str) +``` + +`result_str` initialized to `None` before the try block ensures `end_tool_call` receives `None` when an exception occurs before the result is assembled. `_drain_and_append_steering` executes inside the try block, not after it. The decorator uses `@mcp.tool(name="koan_...")` with an explicit name string, not the bare `@mcp.tool()` form. diff --git a/.koan/memory/0034-koan-memory-sync-uses-sha-256-content-hash-not.md b/.koan/memory/0034-koan-memory-sync-uses-sha-256-content-hash-not.md new file mode 100644 index 0000000..8bdcd5c --- /dev/null +++ b/.koan/memory/0034-koan-memory-sync-uses-sha-256-content-hash-not.md @@ -0,0 +1,15 @@ +--- +title: koan memory sync uses SHA-256 content hash, not mtime, as change-detection + invariant +type: decision +created: '2026-04-16T13:32:18Z' +modified: '2026-04-16T13:32:18Z' +--- + +The sync layer in `koan/memory/retrieval/index.py` was designed on 2026-04-16, with the user confirming the design in plan-review, to detect changes to `.koan/memory/NNNN-*.md` entry files using SHA-256 content hashes stored as a `content_hash` column in the LanceDB table, rather than file modification timestamps (mtime). + +Two alternatives were considered and rejected by the plan author: +- **mtime**: git operations (branch checkout, `git pull`, `git stash`) update file mtimes without changing content; `touch` changes mtime without changing content. An mtime-based sync would spuriously re-embed files after routine git operations, wasting Voyage AI embedding API calls. +- **A separate metadata sidecar file** (e.g., a JSON file tracking hashes alongside the index): rejected in favor of storing hashes as a LanceDB column, keeping the index fully self-contained with no external tracking file. + +The hash computation uses `hashlib.sha256(path.read_bytes()).hexdigest()` stored in the `content_hash` column of the LanceDB `entries` table. diff --git a/.koan/memory/0037-code-comment-vs-memory-entry-filter-comment.md b/.koan/memory/0037-code-comment-vs-memory-entry-filter-comment.md new file mode 100644 index 0000000..b46f6ce --- /dev/null +++ b/.koan/memory/0037-code-comment-vs-memory-entry-filter-comment.md @@ -0,0 +1,9 @@ +--- +title: Code-comment vs memory-entry filter -- COMMENT classification and executor + rationale comments +type: decision +created: '2026-04-17T04:22:11Z' +modified: '2026-04-17T04:22:11Z' +--- + +The curation phase's COMMENT classification in `koan/phases/curation.py` was added on 2026-04-17 to filter implementation-specific knowledge out of the koan memory store. The user identified that entries like "backend.py exposes search_candidates and rerank_results separately" recorded knowledge that would serve agents better as code comments next to the relevant functions. The design introduced a two-part strategy: (1) a COMMENT classification in the curation phase's `PHASE_ROLE_CONTEXT` that applies a test question -- "Would a code comment next to the relevant function give a future agent the same benefit?" -- to filter candidates that describe single-function rationale, parameter defaults, or single-module patterns; (2) a "Rationale comments" directive in `koan/phases/executor.py` step 3 instructing executors to write brief 1-3 line "why" comments at code locations when making implementation choices. Alternative considered: relying solely on the existing "What not to capture" guidance without a formal classification -- rejected because it lacked a mechanical discrimination test and did not redirect the knowledge to code comments. diff --git a/.koan/memory/0038-cross-reference-repetition-in-prompt-instructions.md b/.koan/memory/0038-cross-reference-repetition-in-prompt-instructions.md new file mode 100644 index 0000000..1dec09b --- /dev/null +++ b/.koan/memory/0038-cross-reference-repetition-in-prompt-instructions.md @@ -0,0 +1,8 @@ +--- +title: Cross-reference repetition in prompt instructions aids LLM instruction following +type: procedure +created: '2026-04-17T04:22:19Z' +modified: '2026-04-17T04:22:19Z' +--- + +The koan phase prompt system (`koan/phases/*.py`) was confirmed on 2026-04-17 to follow a cross-reference repetition principle for LLM instruction following. When the plan proposed adding the COMMENT classification to step 2 substep E's "Apply" list (even though COMMENT was already defined in the classification schema earlier in the prompt), the user confirmed this was correct, stating "these type of cross-references and repetitions work well" for optimizing instruction following. The user described this as fitting koan's existing conventions. The rule: when writing phase prompt instructions, repeat classifications, rules, and categories at each point of use rather than referencing earlier definitions once. The model recognizes the repeated information from earlier context, and the repetition reinforces the expected behavior at the moment of action. diff --git a/.koan/memory/0039-memory-store-content-policy-rag-serves-unknown.md b/.koan/memory/0039-memory-store-content-policy-rag-serves-unknown.md new file mode 100644 index 0000000..ae7bffe --- /dev/null +++ b/.koan/memory/0039-memory-store-content-policy-rag-serves-unknown.md @@ -0,0 +1,11 @@ +--- +title: Memory store content policy -- RAG serves "unknown unknowns," implementation + details go near code +type: decision +created: '2026-04-17T04:33:46Z' +modified: '2026-04-17T04:33:46Z' +related: +- 0037-code-comment-vs-memory-entry-filter-comment.md +--- + +The koan memory store's content policy was clarified by the user on 2026-04-17. The RAG system is intended for "unknown unknown" knowledge -- cross-cutting architecture decisions and constraints that do not have a coherent single location in the codebase. When an LLM is extremely likely to open a file anyway, implementation details should be placed as comments in close proximity to the actual implementation; this approach works well for both humans and LLMs. The memory store should not contain knowledge that an agent would encounter through normal file reading. This principle motivated the COMMENT classification added to koan/phases/curation.py on the same date, which filters single-function and single-module rationale out of memory candidates and into code comments. diff --git a/.koan/memory/0040-memory-captures-persistent-always-true.md b/.koan/memory/0040-memory-captures-persistent-always-true.md new file mode 100644 index 0000000..a5e93a0 --- /dev/null +++ b/.koan/memory/0040-memory-captures-persistent-always-true.md @@ -0,0 +1,9 @@ +--- +title: Memory captures persistent "always true" information, not future plans or speculative + principles +type: lesson +created: '2026-04-17T04:33:48Z' +modified: '2026-04-17T04:33:48Z' +--- + +The koan memory system's scope boundary was corrected by the user on 2026-04-17. During the curation phase of a workflow run, the curation agent attempted to elicit prompt engineering principles by asking speculative questions about future design patterns. The user identified this as a non-goal: the memory system is intended to contain persistent, "always true" information -- facts that have already been established through project experience. Speculative knowledge, future plans, and principles not yet grounded in concrete decisions or incidents do not belong in memory. Root cause: the curation agent conflated "potentially useful knowledge" with "established project knowledge." The memory store's value comes from capturing what HAS happened, not what MIGHT be useful. From 71b0b1549ddf89158949aa0f26b438e1c500b0c3 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 17 Apr 2026 13:28:38 +0700 Subject: [PATCH 396/412] fix: coerce read range args to ints in Claude summaries --- koan/runners/claude.py | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/koan/runners/claude.py b/koan/runners/claude.py index cc40bb4..4741da0 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -51,18 +51,33 @@ def _normalize_tool_name(name: str | None) -> str | None: return _TOOL_NAME_MAP.get(name, name.lower()) +def _coerce_int(value: object) -> int | None: + # Models occasionally emit numeric tool arguments as strings; Read itself + # accepts both, so we coerce here to match that lenience for display. + if isinstance(value, bool): + return None + if isinstance(value, int): + return value + if isinstance(value, str): + try: + return int(value) + except ValueError: + return None + return None + + def _extract_tool_summary(tool: str, args: dict) -> str: """Extract human-readable detail from Claude tool arguments.""" if tool == "read": path = args.get("file_path", "") - offset = args.get("offset") - limit = args.get("limit") + offset = _coerce_int(args.get("offset")) + limit = _coerce_int(args.get("limit")) if offset is not None and limit is not None: return f"{path}:{offset}-{offset + limit}" if offset is not None: return f"{path}:{offset}+" - start = args.get("start_line") - end = args.get("end_line") + start = _coerce_int(args.get("start_line")) + end = _coerce_int(args.get("end_line")) if start is not None and end is not None: return f"{path}:{start}-{end}" return path From b973f6c2db045f90c43180ee8cc6a7df8c399988 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Fri, 17 Apr 2026 13:28:46 +0700 Subject: [PATCH 397/412] fix: recover subagent stream after parse errors --- koan/subagent.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/koan/subagent.py b/koan/subagent.py index c01b740..a0db0d2 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -272,7 +272,21 @@ async def stream_stdout(): async for raw in proc.stdout: line = raw.decode("utf-8", errors="replace").rstrip("\n") - events = runner.parse_stream_event(line) + try: + events = runner.parse_stream_event(line) + except Exception as exc: + log.warning( + "parse_stream_event failed for %s (agent_id=%s): %s", + role, agent_id, exc, + ) + for _idx, (cid, tname) in streaming_call_ids.items(): + store.push_event( + "tool_stopped", + build_tool_stopped(cid, tname), + agent_id=agent_id, + ) + streaming_call_ids.clear() + continue for ev in events: # Close implicit in-flight tool (non-streaming path) when # the LLM moves on to thinking or text output. From 822bb06008853ece995583f65f480969ac051000 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 18 Apr 2026 11:14:23 +0700 Subject: [PATCH 398/412] feat: add per-phase memory injection at phase handshakes --- ...-summary-capture-rides-on-orchestrators.md | 9 + ...ries-dict-stored-on-run-projection-wire.md | 11 ++ ...nical-rag-injection-anchor-task-run-dir.md | 12 ++ ...anical-rag-injection-scope-orchestrator.md | 10 ++ ...se-summary-must-be-a-dense-paragraph-it.md | 12 ++ ...-rag-injection-is-fail-soft-log-warning.md | 10 ++ ...ory-systemmd-described-an-unimplemented.md | 11 ++ AGENTS.md | 4 + docs/architecture.md | 8 + docs/memory-system.md | 109 +++++++----- koan/events.py | 9 + koan/lib/workflows.py | 36 ++++ koan/memory/retrieval/rag.py | 26 +++ koan/phases/__init__.py | 4 + koan/phases/execute.py | 3 + koan/phases/intake.py | 3 + koan/phases/plan_review.py | 7 +- koan/phases/plan_spec.py | 7 +- koan/projections.py | 18 ++ koan/prompts/orchestrator.py | 31 +++- koan/web/mcp_endpoint.py | 161 ++++++++++++++++++ 21 files changed, 455 insertions(+), 46 deletions(-) create mode 100644 .koan/memory/0041-per-phase-summary-capture-rides-on-orchestrators.md create mode 100644 .koan/memory/0042-phasesummaries-dict-stored-on-run-projection-wire.md create mode 100644 .koan/memory/0043-mechanical-rag-injection-anchor-task-run-dir.md create mode 100644 .koan/memory/0044-mechanical-rag-injection-scope-orchestrator.md create mode 100644 .koan/memory/0045-end-of-phase-summary-must-be-a-dense-paragraph-it.md create mode 100644 .koan/memory/0046-mechanical-rag-injection-is-fail-soft-log-warning.md create mode 100644 .koan/memory/0047-docsmemory-systemmd-described-an-unimplemented.md diff --git a/.koan/memory/0041-per-phase-summary-capture-rides-on-orchestrators.md b/.koan/memory/0041-per-phase-summary-capture-rides-on-orchestrators.md new file mode 100644 index 0000000..67def66 --- /dev/null +++ b/.koan/memory/0041-per-phase-summary-capture-rides-on-orchestrators.md @@ -0,0 +1,9 @@ +--- +title: Per-phase summary capture rides on orchestrator's last prose turn before first + koan_yield +type: decision +created: '2026-04-17T09:37:08Z' +modified: '2026-04-17T09:37:08Z' +--- + +This entry documents the per-phase summary capture mechanism for koan's mechanical RAG injection pipeline. On 2026-04-17, user decided that the orchestrator's last assistant text immediately preceding the first `koan_yield` of each phase is captured as that phase's summary, written into `Run.phase_summaries[phase]` via the `phase_summary_captured` event. Subsequent yields within the same phase do not overwrite. Rationale: the orchestrator already writes prose summaries informally before yielding at phase boundaries, so the contract piggybacks on existing behavior with zero new tool calls. Alternative rejected: a dedicated `koan_phase_summary` MCP tool that would have produced cleaner audit artifacts but would have forced the summary to render BOTH as a tool call and as chat text, duplicating the rendering surface and complicating the conversation entry types. Known limitation: runner buffering may deliver the tool call before the final text deltas have been folded into the projection; user accepted this risk and post-mortem identified that captures shorter than 50 characters are logged as warnings via `_extract_last_orchestrator_text` in `koan/web/mcp_endpoint.py`. Implementation surfaced during the 2026-04-17 plan workflow that wired RAG injection into phase transitions. diff --git a/.koan/memory/0042-phasesummaries-dict-stored-on-run-projection-wire.md b/.koan/memory/0042-phasesummaries-dict-stored-on-run-projection-wire.md new file mode 100644 index 0000000..500c587 --- /dev/null +++ b/.koan/memory/0042-phasesummaries-dict-stored-on-run-projection-wire.md @@ -0,0 +1,11 @@ +--- +title: phase_summaries dict stored on Run projection, wire-visible +type: decision +created: '2026-04-17T09:37:19Z' +modified: '2026-04-17T09:37:19Z' +related: +- 0007-dual-fold-system-audit-fold-per-subagent-disk-vs-projection-fold-workflow-sse.md +- 0041-per-phase-summary-capture-rides-on-orchestrators.md +--- + +This entry documents the storage location for koan's per-phase summary state used by mechanical RAG injection. On 2026-04-17, user decided that `phase_summaries: dict[str, str]` lives on the `Run` projection model in `koan/projections.py` and is serialized to the SSE wire alongside every other Run field. Frontend ignores the field for now; future UI work may surface it. Alternatives rejected: storing on `AppState` only (would lose event-log restorability -- the projection is reconstructable from events but AppState is not), or storing on the projection but excluding from `to_wire()` (would break the invariant that the projection IS what the frontend sees, regressing the symmetric fold design captured in entry 7). User stated the wire-visibility "is not a secret, it's just not necessary right now" -- the field is data-only and exposing it carries no risk. Decision surfaced during intake of the RAG-wiring workflow on 2026-04-17. diff --git a/.koan/memory/0043-mechanical-rag-injection-anchor-task-run-dir.md b/.koan/memory/0043-mechanical-rag-injection-anchor-task-run-dir.md new file mode 100644 index 0000000..9fc9088 --- /dev/null +++ b/.koan/memory/0043-mechanical-rag-injection-anchor-task-run-dir.md @@ -0,0 +1,12 @@ +--- +title: 'Mechanical RAG injection anchor: task + run-dir markdown (mtime asc) + immediate + prior phase summary' +type: decision +created: '2026-04-17T09:37:31Z' +modified: '2026-04-17T09:37:31Z' +related: +- 0020-memory-retrieval-static-directive-mechanical-injection.md +- 0041-per-phase-summary-capture-rides-on-orchestrators.md +--- + +This entry documents the anchor composition rule for koan's mechanical RAG injection pipeline. On 2026-04-17, user decided that `_compose_rag_anchor` in `koan/web/mcp_endpoint.py` produces a single anchor string from three sources concatenated in a fixed order: (1) the workflow task description, (2) every `*.md` file in the run directory sorted by mtime ascending (oldest first), (3) the immediate prior phase's summary read from `Run.phase_summaries[completed_phase]`. The cheap query-generation LLM receives this single anchor plus the per-phase `retrieval_directive` and produces 1-3 search queries combined and reranked against the directive. Alternatives rejected: separate RAG queries per source (more LLM calls, harder reranking -- user noted "it's more common to do a single context and guide the cheap LLM into writing useful queries based on all provided context"), and including all prior phase summaries (would dilute anchor topics -- relies on summary-chain compaction: if intake facts still matter in plan-review, plan-spec's summary repeats them). Chronological mtime ordering puts the most recent artifact closest to the prior summary, placing the most directly relevant content where attention is strongest. Decision surfaced during 2026-04-17 intake when user clarified the anchor should be "first task description, then all artifacts in chronological order, then summary of previous phase". diff --git a/.koan/memory/0044-mechanical-rag-injection-scope-orchestrator.md b/.koan/memory/0044-mechanical-rag-injection-scope-orchestrator.md new file mode 100644 index 0000000..3a743b8 --- /dev/null +++ b/.koan/memory/0044-mechanical-rag-injection-scope-orchestrator.md @@ -0,0 +1,10 @@ +--- +title: 'Mechanical RAG injection scope: orchestrator phases only; curation excluded' +type: decision +created: '2026-04-17T09:37:43Z' +modified: '2026-04-17T09:37:43Z' +related: +- 0020-memory-retrieval-static-directive-mechanical-injection.md +--- + +This entry documents the agent-type scope for koan's mechanical RAG memory injection. On 2026-04-17, user decided that mechanical injection runs ONLY for orchestrator phases that declare a non-empty `retrieval_directive` on their `PhaseBinding` in `koan/lib/workflows.py`. Scouts and executors are excluded from injection. The curation phase's binding sets `retrieval_directive=""` explicitly, disabling injection. Rationale: scouts receive a narrow single-shot prompt where memory entries would be noise; executors have richer artifacts to read and benefit less from cross-cutting memory; curation already calls `koan_memory_status` which surfaces the full project summary and entry listing, making mechanical injection redundant for it. Alternatives rejected: include executors with a directive keyed to artifact subsystems (deferred to a future workflow because executors don't yet have a clear directive vocabulary), and emit a non-empty curation directive (rejected because `koan_memory_status` already covers the duplicate-detection use case). Scope surfaced during 2026-04-17 intake when user explicitly answered "orchestrator_only" to the agent-scope question. diff --git a/.koan/memory/0045-end-of-phase-summary-must-be-a-dense-paragraph-it.md b/.koan/memory/0045-end-of-phase-summary-must-be-a-dense-paragraph-it.md new file mode 100644 index 0000000..4b1447e --- /dev/null +++ b/.koan/memory/0045-end-of-phase-summary-must-be-a-dense-paragraph-it.md @@ -0,0 +1,12 @@ +--- +title: End-of-phase summary must be a dense paragraph -- it becomes the next phase's + RAG anchor +type: procedure +created: '2026-04-17T09:37:55Z' +modified: '2026-04-17T09:37:55Z' +related: +- 0041-per-phase-summary-capture-rides-on-orchestrators.md +- 0043-mechanical-rag-injection-anchor-task-run-dir.md +--- + +This entry records a behavioral rule for koan orchestrator agents at phase boundaries. On 2026-04-17, the team established the procedure: when the orchestrator is about to call its first `koan_yield` of a phase boundary (the `Phase Complete` boundary that follows the final `koan_complete_step` of a phase), the assistant text immediately preceding that yield must be a standalone, dense, information-rich paragraph that names the decisions made, constraints discovered, artifacts produced, and any unresolved items of the just-finished phase. The rule exists because that text is automatically captured into `Run.phase_summaries[phase]` and fed as the prior-phase summary anchor for the next phase's mechanical RAG injection (see `_extract_last_orchestrator_text` in `koan/web/mcp_endpoint.py`). A terse "done" or single-sentence acknowledgement degrades the next phase's RAG retrieval quality and degrades the user-facing brief. Procedure derived during the 2026-04-17 RAG-wiring workflow. Mechanical reinforcement: an `IMPORTANT:` paragraph in the orchestrator system prompt (`koan/prompts/orchestrator.py`) instructs the orchestrator about the contract; future drift is observable via warning logs when `len(summary_text) < 50` chars or when no text is captured at all. diff --git a/.koan/memory/0046-mechanical-rag-injection-is-fail-soft-log-warning.md b/.koan/memory/0046-mechanical-rag-injection-is-fail-soft-log-warning.md new file mode 100644 index 0000000..fdca347 --- /dev/null +++ b/.koan/memory/0046-mechanical-rag-injection-is-fail-soft-log-warning.md @@ -0,0 +1,10 @@ +--- +title: 'Mechanical RAG injection is fail-soft: log warning, never block phase handshake' +type: procedure +created: '2026-04-17T09:38:05Z' +modified: '2026-04-17T09:38:05Z' +related: +- 0041-per-phase-summary-capture-rides-on-orchestrators.md +--- + +This entry records a behavioral rule for koan's mechanical memory injection pipeline at the orchestrator's phase handshake. On 2026-04-17, the team established the procedure: when `_compute_memory_injection` in `koan/web/mcp_endpoint.py` raises any exception (missing `VOYAGE_API_KEY`, empty `.koan/memory/`, LanceDB I/O error, embedding API failure, etc.), the helper catches the exception, logs it at `warning` level via `log.warning("mechanical memory injection failed for phase %r ...", exc_info=True)`, and returns an empty injection block. The phase handshake proceeds without the `## Relevant memory` section. The rule exists because retrieval quality is best-effort and never load-bearing -- the orchestrator can complete its phase from the directive + task + artifacts alone. A blocking handshake on retrieval failure would couple workflow correctness to optional infrastructure. Same posture is applied in `koan_yield`: short or missing summary captures emit warnings but never block the yield. Procedure surfaced during 2026-04-17 plan-spec when the user accepted the fail-soft design decision and the executor wired warning log lines per the plan. diff --git a/.koan/memory/0047-docsmemory-systemmd-described-an-unimplemented.md b/.koan/memory/0047-docsmemory-systemmd-described-an-unimplemented.md new file mode 100644 index 0000000..818f68a --- /dev/null +++ b/.koan/memory/0047-docsmemory-systemmd-described-an-unimplemented.md @@ -0,0 +1,11 @@ +--- +title: docs/memory-system.md described an unimplemented summary.md load step in the + injection pipeline +type: lesson +created: '2026-04-17T09:38:19Z' +modified: '2026-04-17T09:38:19Z' +related: +- 0032-plan-review-produced-unverified-critical-finding.md +--- + +This entry records a documentation-versus-code drift in koan's memory system. On 2026-04-17, plan-review discovered that `docs/memory-system.md` described a 5-step mechanical injection pipeline whose first step was "Load project summary -- summary.md is loaded in full ... runs only at intake" -- a step that was never wired into the orchestrator's phase handshake. The `_step_phase_handshake` code path in `koan/web/mcp_endpoint.py` had no summary.md load at any point; the injection helper composed the anchor from task + artifacts + prior phase summary alone. Root cause: the design spec was authored aspirationally during the memory system design phase and never reconciled when the partial wiring landed. Plan-review caught the drift only because the reviewer cross-checked the doc claim against the actual code path, which is not a routine review move. Correction applied during the 2026-04-17 RAG-wiring workflow: the doc was rewritten to describe a 4-step pipeline (drop the summary.md load) and an "Implementation mapping" subsection was appended pinning the doc to specific file/function names. Adding the summary.md load is left to a future workflow if the user wants it. diff --git a/AGENTS.md b/AGENTS.md index 3a1ebc7..001d038 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -139,6 +139,10 @@ during brief-generation step 1 (the read step). | `koan_select_story`, `koan_complete_story`, `koan_retry_story`, `koan_skip_story` | `execution` only | | `write`, `edit` (run_dir scoped) | All phases except `brief-generation` step 1 | | `bash` | `execution`, `implementation-validation` | +| `koan_memorize` | All phases | +| `koan_forget` | All phases | +| `koan_memory_status` | All phases | +| `koan_search` | All phases | ## 5. Need-to-Know Prompts diff --git a/docs/architecture.md b/docs/architecture.md index b9589ee..392a7dd 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -16,6 +16,7 @@ principles, and pitfalls that govern the codebase. - [Projections](./projections.md) -- versioned event log, pure fold, JSON Patch protocol, projection model, camelCase wire format - [Intake Loop](./intake-loop.md) -- two-step intake design, prompt engineering principles +- [Memory System](./memory-system.md) -- project memory, curation, and the RAG injection wired into phase transitions --- @@ -193,6 +194,13 @@ The injection contract every `phase_guidance` entry must cover: | **Question posture** | How aggressively to ask, typical round count | | **User override** | Always present, always last: "follow their lead" | +**Memory injection.** At step 1 of every orchestrator phase, the +`_step_phase_handshake` response may include a `## Relevant memory` +block of top-5 memory entries retrieved by a per-phase static directive. +The mechanism is described in [memory-system.md](./memory-system.md); +the directive for each phase lives on its `PhaseBinding.retrieval_directive` +in `koan/lib/workflows.py`. + ### 6. Directory-as-contract The subagent directory is the **sole interface** between parent and child. diff --git a/docs/memory-system.md b/docs/memory-system.md index b4e0e88..7d43174 100644 --- a/docs/memory-system.md +++ b/docs/memory-system.md @@ -181,7 +181,7 @@ Koan classifies memories into four types. The type field is metadata for filtering and curation heuristics — it does not determine where the file is stored. All entries live in a single flat directory. -### Decisions — *Why is the project the way it is?* +### Decisions — _Why is the project the way it is?_ The most critical memory type. Decisions capture **why** the project is the way it is — not just what was chosen, but what was rejected @@ -196,14 +196,14 @@ Decisions include both explicit choices (user-stated) and implicit choices (LLM-inferred from user behavior). Implicit decisions should be clearly attributed as inferred in the prose body. -### Context — *What do I need to know that isn't in the code?* +### Context — _What do I need to know that isn't in the code?_ Objective facts about the project, team, domain, and infrastructure that are not derivable from the codebase and are expected to remain stable across sessions. Team size, deployment setup, external dependencies, business constraints. -### Lessons — *What went wrong before?* +### Lessons — _What went wrong before?_ Mistakes made during workflows and the corrections applied. Each entry captures: what happened, what the user did to correct it, @@ -212,7 +212,7 @@ root cause, and what should change to prevent recurrence. A lesson often produces a new decision or procedure, but the lesson itself is the error record — the ground truth about what went wrong. -### Procedures — *How should I approach things in this project?* +### Procedures — _How should I approach things in this project?_ Patterns, strategies, and behavioral rules that emerged from experience. Procedures capture actionable "how-to" knowledge that @@ -549,7 +549,7 @@ reasoning, recognizes a gap in its knowledge, and formulates a targeted query. "What's the session management architecture?" or "What constraints apply to database migrations?" The agent is aware of its own gap and goes looking. This works when the -agent has enough context to know *what* it doesn't know. +agent has enough context to know _what_ it doesn't know. **Mechanical injection handles unknown unknowns.** The agent doesn't know that a testing policy exists. It doesn't know that @@ -570,36 +570,29 @@ memory injection by providing a **retrieval directive**: a static, human-authored sentence describing what kind of knowledge is most likely to matter for the phase. -The injection pipeline has five steps: +The injection pipeline has four steps: -**Step 1: Load project summary.** `summary.md` is loaded in full. -Always present, not retrieved via search. Budget: ~2000 tokens. -This step runs only at intake (the first phase); subsequent -phases inherit the summary from the orchestrator's context. - -**Step 2: Generate search queries.** A cheap-tier model receives -two inputs and produces 1–3 search queries: +**Step 1: Generate search queries.** A cheap-tier model receives +two inputs and produces 1-3 search queries: The first input is the **retrieval directive** from the phase definition. This is a static sentence written by the workflow -designer that describes the retrieval intent for the phase — +designer that describes the retrieval intent for the phase -- what kind of knowledge typically matters. For example, an execution phase might carry the directive "procedures, conventions, and past lessons related to the subsystem being modified." A verification phase might carry "quality policies, testing conventions, and known pitfalls." The directive -provides the *what to look for* dimension. +provides the _what to look for_ dimension. The second input is **recent artifacts and context** that provide -the *where to look* dimension — the topical anchor. The preferred -source is the artifacts produced by the preceding phase (the -milestone spec, the technical plan, the decomposition output), -because artifacts are well-structured prose with controlled -format and high information density. When no artifact is -available, the last N messages from the orchestrator's event log -serve the same purpose, though with more noise. The cheap model -combines topic (from the artifacts/context) with intent (from -the directive) to produce well-formed queries. +the _where to look_ dimension -- the topical anchor. The anchor +is composed from: the task description, all `.md` files in the +run directory sorted by mtime ascending, and the prior phase's +summary (captured automatically on the first `koan_yield` of +each phase). The cheap model combines topic (from the +artifacts/context) with intent (from the directive) to produce +well-formed queries. Example: the execution phase has directive "procedures, conventions, and past lessons related to the subsystem being @@ -609,31 +602,32 @@ The cheap model generates queries like "authentication token refresh procedures," "Auth0 integration lessons," "credential handling conventions." -**Step 3: Per-query hybrid retrieval.** For each query, two +**Step 2: Per-query hybrid retrieval.** For each query, two parallel searches run against the index: -- Dense vector search → top N candidates by embedding similarity -- BM25 keyword search → top N candidates by lexical matching + +- Dense vector search -> top N candidates by embedding similarity +- BM25 keyword search -> top N candidates by lexical matching + N = 20 per retriever per query (tunable; 20 is sufficient for knowledge bases of hundreds to low thousands of entries). -**Step 4: Per-query fusion and cross-query merge.** For each query, +**Step 3: Per-query fusion and cross-query merge.** For each query, merge the two result lists using Reciprocal Rank Fusion: -`score = Σ 1/(60 + rank)` across retrievers. Combine the fused -lists from all queries, deduplicate entries. Pass the candidate -pool (typically 30–50 unique entries after dedup) through a -cross-encoder reranker, which scores each (query, entry) pair -with full attention over both texts. +`score = sum(1/(60 + rank))` across retrievers. Combine the +fused lists from all queries, deduplicate entries. Pass the +candidate pool (typically 30-50 unique entries after dedup) +through a cross-encoder reranker, which scores each +(query, entry) pair with full attention over both texts. -**Step 5: Take top 3–5 entries.** The highest-scoring entries +**Step 4: Take top 3-5 entries.** The highest-scoring entries after reranking are injected into the agent's context before the phase begins, with their metadata (type, created/modified dates). -Total mechanical context per injection: 3–5 entries (~500–2500 -tokens). The 3–5 budget follows SimpleMem's saturation finding: +Total mechanical context per injection: 3-5 entries (~500-2500 +tokens). The 3-5 budget follows SimpleMem's saturation finding: near-optimal retrieval performance at k=3, diminishing returns -beyond k=5. At intake, the summary adds ~2000 tokens for a -total of ~2500–4500 tokens. +beyond k=5. Not every phase needs injection. The workflow definition controls this: a phase either declares a retrieval directive @@ -642,11 +636,44 @@ context plus agent-invoked tools). In practice, most phases that spawn new agents or shift to a different problem domain should declare a directive. +#### Implementation mapping + +The design above maps to the following code locations: + +- **Attachment point**: `_step_phase_handshake` in + `koan/web/mcp_endpoint.py`, executed on the step 0 -> 1 transition of + every orchestrator phase. +- **Directive location**: `PhaseBinding.retrieval_directive` in + `koan/lib/workflows.py`. The directive is a static, human-authored + string set per workflow binding. An empty string disables injection + for that phase (the curation phase uses an empty string because + `koan_memory_status` already surfaces the full entry listing). +- **Anchor composition**: `_compose_rag_anchor()` in + `koan/web/mcp_endpoint.py`. Order is task description, then all + `*.md` files in the run directory sorted by mtime ascending, then + `Run.phase_summaries[prior_phase]`. +- **Summary capture**: The orchestrator's last assistant text preceding + the first `koan_yield` of a phase is captured into + `Run.phase_summaries[phase]` via the `phase_summary_captured` event. + Subsequent yields in the same phase do not overwrite. Projection + code: `_extract_last_orchestrator_text()` in + `koan/web/mcp_endpoint.py`. +- **Rendering**: `render_injection_block()` in + `koan/memory/retrieval/rag.py` produces a `## Relevant memory` + markdown block. Phase modules (intake, plan-spec, plan-review, + execute) prepend this block to their step 1 guidance via + `ctx.memory_injection`. +- **Failure mode**: Retrieval errors (missing `VOYAGE_API_KEY`, empty + memory, LanceDB errors) are logged at `warning` and the phase + proceeds without the injection block. +- **Agent scope**: Orchestrator phases only. Scouts and executors are + excluded from mechanical injection. + #### Agent-invoked tools During reasoning, the orchestrator has access to two memory tools. These complement mechanical injection by handling the agent's -*recognized* information needs — questions that arise during +_recognized_ information needs — questions that arise during reasoning that the agent is aware it cannot answer from its current context. @@ -753,7 +780,7 @@ should I look for before starting this phase?" This was rejected because it collapses the two retrieval mechanisms into one. If the orchestrator generates the directive, the queries will -reflect what the orchestrator *thinks* it needs — which is +reflect what the orchestrator _thinks_ it needs — which is exactly what agent-invoked tools already handle. The orchestrator can already call `koan_search` for anything it recognizes as a gap. Generating a directive from the @@ -762,7 +789,7 @@ unknowns: topics the orchestrator is already aware of and could query for itself. The value of mechanical injection comes precisely from the fact -that it does *not* depend on the agent's assessment of its own +that it does _not_ depend on the agent's assessment of its own knowledge gaps. The static directive encodes structural knowledge that the workflow designer has about what each phase type typically needs — knowledge that is stable across runs and diff --git a/koan/events.py b/koan/events.py index 20ddaf0..09a49bc 100644 --- a/koan/events.py +++ b/koan/events.py @@ -209,6 +209,15 @@ def build_yield_started(suggestions: list[dict]) -> dict: return {"suggestions": suggestions} +def build_phase_summary_captured(phase: str, summary: str) -> dict: + """Build phase_summary_captured event payload. + + Carries only phase + summary. agent_id is passed separately at push_event + time for audit; the fold reads only phase and summary (run-scoped state). + """ + return {"phase": phase, "summary": summary} + + # -- Configuration event builders --------------------------------------------- def build_probe_completed(results: dict[str, bool]) -> dict: diff --git a/koan/lib/workflows.py b/koan/lib/workflows.py index d11a0f6..7af0dd6 100644 --- a/koan/lib/workflows.py +++ b/koan/lib/workflows.py @@ -41,6 +41,11 @@ class PhaseBinding: module: Any # phase module (e.g. intake, curation) description: str = "" guidance: str = "" # injected as ctx.phase_instructions at step 1 + # Static retrieval directive for mechanical RAG injection at step 1. + # Empty string disables injection for this phase. The directive belongs + # here (not in the phase module) so the same module can be reused across + # workflows with different retrieval intent. + retrieval_directive: str = "" @dataclass(frozen=True) @@ -255,14 +260,31 @@ def get_module(self, name: str) -> Any | None: "The user can always ask you to go deeper, dispatch more scouts, or ask\n" "more questions. Follow their lead over these defaults." ), + retrieval_directive=( + "Architectural decisions, constraints, and context entries that shape" + " how this codebase is organized. Entries about subsystems the task" + " may touch, team conventions, and deployment invariants." + ), ), "plan-spec": PhaseBinding( module=plan_spec, description="Write a technical implementation plan grounded in the codebase", + retrieval_directive=( + "Implementation decisions, procedures, and conventions that constrain" + " how changes are made in this codebase. Entries about coding patterns," + " module layout rules, and past lessons from similar changes." + ), ), "plan-review": PhaseBinding( module=plan_review, description="Evaluate the plan for completeness, correctness, and risks", + # Same directive as plan-spec: review evaluates against the same + # implementation-level knowledge that spec used to write the plan. + retrieval_directive=( + "Implementation decisions, procedures, and conventions that constrain" + " how changes are made in this codebase. Entries about coding patterns," + " module layout rules, and past lessons from similar changes." + ), ), "execute": PhaseBinding( module=execute_phase, @@ -279,11 +301,19 @@ def get_module(self, name: str) -> Any | None: "Report the result. If the executor failed or asked questions, relay\n" "the situation to the user and suggest next steps." ), + retrieval_directive=( + "Procedures, conventions, and past lessons related to the subsystems" + " being modified. Executor-facing rules about testing policy, secret" + " handling, file placement, and other coding-time constraints." + ), ), "curation": PhaseBinding( module=curation, description="Capture lessons, decisions, and context from the completed run", guidance=_POSTMORTEM_DIRECTIVE, + # Curation already calls koan_memory_status which surfaces the full + # entry listing. Mechanical injection would be redundant and noisy. + retrieval_directive="", ), }, initial_phase="intake", @@ -335,6 +365,11 @@ def get_module(self, name: str) -> Any | None: "The user can always tell you to narrow scope or skip questions.\n" "Follow their lead over these defaults." ), + retrieval_directive=( + "Architectural decisions, constraints, and context entries that shape" + " how this codebase is organized. Entries about subsystems the task" + " may touch, team conventions, and deployment invariants." + ), ), }, initial_phase="intake", @@ -353,6 +388,7 @@ def get_module(self, name: str) -> Any | None: module=curation, description="Review and maintain the project's memory entries", guidance=_STANDALONE_DIRECTIVE, + retrieval_directive="", # explicit: curation uses koan_memory_status instead ), }, initial_phase="curation", diff --git a/koan/memory/retrieval/rag.py b/koan/memory/retrieval/rag.py index 3b1e07c..1b96a26 100644 --- a/koan/memory/retrieval/rag.py +++ b/koan/memory/retrieval/rag.py @@ -56,3 +56,29 @@ async def inject( results = await rerank_results(directive, merged_list, k) log.debug("reranked to %d results", len(results)) return results + + +def render_injection_block(results: list[SearchResult]) -> str: + """Render SearchResult list as a markdown block for step-1 injection. + + Returns "" when results is empty so the caller can omit the block + without branching on truthiness elsewhere. + """ + if not results: + return "" + lines: list[str] = [ + "## Relevant memory", + "", + "The following memory entries were retrieved based on the retrieval", + "directive for this phase and the current workflow context. Treat", + "them as prior knowledge -- decisions, procedures, lessons, and", + "context from past workflow runs that are likely to matter here.", + "", + ] + for r in results: + lines.append(f"### {r.entry.title}") + lines.append(f"*type: {r.entry.type} | modified: {r.entry.modified}*") + lines.append("") + lines.append(r.entry.body.strip()) + lines.append("") + return "\n".join(lines).rstrip() + "\n" diff --git a/koan/phases/__init__.py b/koan/phases/__init__.py index b1c5965..caa71ff 100644 --- a/koan/phases/__init__.py +++ b/koan/phases/__init__.py @@ -35,6 +35,10 @@ class PhaseContext: available_phases: list[str] = field(default_factory=list) scout_question: str | None = None scout_investigator_role: str | None = None + # Pre-rendered markdown block set by _step_phase_handshake. Phase modules + # prepend this to step 1 guidance. Empty string means no injection (either + # no directive on the binding or retrieval failed gracefully). + memory_injection: str = "" @runtime_checkable diff --git a/koan/phases/execute.py b/koan/phases/execute.py index c1ad14f..e2dd0e4 100644 --- a/koan/phases/execute.py +++ b/koan/phases/execute.py @@ -55,6 +55,9 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "", ] + if ctx.memory_injection: + lines.extend([ctx.memory_injection, ""]) + if ctx.phase_instructions: lines.extend([ "## Workflow guidance", diff --git a/koan/phases/intake.py b/koan/phases/intake.py index 93546cd..99b6d56 100644 --- a/koan/phases/intake.py +++ b/koan/phases/intake.py @@ -89,6 +89,9 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: lines.insert(0, f"Active workflow: **{ctx.workflow_name}**") lines.insert(1, "") + if ctx.memory_injection: + lines.extend([ctx.memory_injection, ""]) + lines.extend([ "Read the task description, orient yourself in the codebase, and plan your investigation.", "", diff --git a/koan/phases/plan_review.py b/koan/phases/plan_review.py index 71d3222..f039265 100644 --- a/koan/phases/plan_review.py +++ b/koan/phases/plan_review.py @@ -63,7 +63,10 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: if step == 1: - lines = [ + lines: list[str] = [] + if ctx.memory_injection: + lines.extend([ctx.memory_injection, ""]) + lines.extend([ "Read and comprehend before evaluating. Do NOT write any files in this step.", "", "## Your verification mandate", @@ -90,7 +93,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "- Are the implementation steps in the right order?", "", "Do NOT write an evaluation yet. Comprehend first.", - ] + ]) if ctx.phase_instructions: lines.extend(["", "## Additional Context from Workflow Orchestrator", "", ctx.phase_instructions]) return StepGuidance(title=STEP_NAMES[1], instructions=lines) diff --git a/koan/phases/plan_spec.py b/koan/phases/plan_spec.py index a3ab209..2441e83 100644 --- a/koan/phases/plan_spec.py +++ b/koan/phases/plan_spec.py @@ -58,7 +58,10 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: if step == 1: - lines = [ + lines: list[str] = [] + if ctx.memory_injection: + lines.extend([ctx.memory_injection, ""]) + lines.extend([ "Read and analyze before writing the plan. Do NOT write any files in this step.", "", "## What to read", @@ -87,7 +90,7 @@ def step_guidance(step: int, ctx: PhaseContext) -> StepGuidance: "- Files that will be modified", "- Key decisions and rationale", "- Any ambiguities or risks spotted", - ] + ]) if ctx.phase_instructions: lines.extend(["", "## Additional Context from Workflow Orchestrator", "", ctx.phase_instructions]) return StepGuidance(title=STEP_NAMES[1], instructions=lines) diff --git a/koan/projections.py b/koan/projections.py index e422852..015b783 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -62,6 +62,7 @@ # Yield — orchestrator hands control back to the user "yield_started", "yield_cleared", + "phase_summary_captured", # Steering "steering_queued", "steering_delivered", @@ -356,6 +357,10 @@ class Run(KoanBaseModel): completion: CompletionInfo | None = None steering: list[SteeringMessage] = [] # pending steering messages shown above chat active_yield: ActiveYield | None = None # non-None while orchestrator is in koan_yield + # Keyed by phase name. Populated on the first koan_yield of each phase + # from the orchestrator's last assistant text. Used as context anchor for + # the next phase's mechanical RAG injection. Wire-visible; frontend ignores. + phase_summaries: dict[str, str] = {} class Projection(KoanBaseModel): settings: Settings = Field(default_factory=Settings) @@ -1247,6 +1252,19 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: new_run = projection.run.model_copy(update={"active_yield": None}) return projection.model_copy(update={"run": new_run}) + case "phase_summary_captured": + # agent_id is carried for audit only; phase_summaries is run-scoped. + if projection.run is None: + return projection + phase = payload.get("phase", "") + summary = payload.get("summary", "") + if not phase: + return projection + new_summaries = dict(projection.run.phase_summaries) + new_summaries[phase] = summary + new_run = projection.run.model_copy(update={"phase_summaries": new_summaries}) + return projection.model_copy(update={"run": new_run}) + case _: log.warning("fold: unknown event_type=%r", event_type) return projection diff --git a/koan/prompts/orchestrator.py b/koan/prompts/orchestrator.py index de9b213..deb7cf1 100644 --- a/koan/prompts/orchestrator.py +++ b/koan/prompts/orchestrator.py @@ -26,6 +26,12 @@ "When the user confirms a direction, call koan_set_phase with the phase name.\n" "When the user is done, call koan_set_phase with \"done\".\n" "\n" + "IMPORTANT: The last assistant text you write *before* calling\n" + "koan_yield at the end of each phase is captured automatically as\n" + "that phase's summary. Downstream phases use it to retrieve relevant\n" + "memory and to brief the user. Make each end-of-phase summary a\n" + "standalone, dense, information-rich paragraph -- not a terse 'done'.\n" + "\n" "At the start of each phase, koan_complete_step returns your role context for" " that phase alongside the first step's instructions.\n" "\n" @@ -47,6 +53,11 @@ "- `koan_memorize` -- create or update a memory entry. Omit `entry_id`\n" " to create; pass it to update.\n" "- `koan_forget` -- delete a memory entry by `entry_id`.\n" + "- `koan_search` -- hybrid dense + BM25 + reranked search over memory\n" + " entries. Returns top-k entries most relevant to a targeted query.\n" + " Use this when you recognize a specific knowledge gap during reasoning\n" + " -- e.g. 'how does the existing session management work?' or\n" + " 'are there past lessons about modifying the auth service?'.\n" "\n" "### Memory types\n" "\n" @@ -79,5 +90,23 @@ "phase. That phase provides detailed instructions for the full\n" "procedure -- writing discipline, classification schema, quality\n" "checklist. During other phases, be aware that memory exists and may\n" - "contain useful project context, but do not attempt to curate." + "contain useful project context, but do not attempt to curate.\n" + "\n" + "### Mechanical memory injection vs. agent-invoked search\n" + "\n" + "Koan surfaces memory to you through two distinct mechanisms:\n" + "\n" + "1. **Mechanical injection.** At the start of each orchestrator phase,\n" + " the step 1 guidance may include a `## Relevant memory` block with\n" + " the top 5 entries retrieved from a static per-phase directive plus\n" + " the task description, prior artifacts, and the previous phase's\n" + " summary. You do NOT trigger this -- it arrives automatically.\n" + " Treat entries in the block as prior knowledge for the phase.\n" + "\n" + "2. **Agent-invoked search.** At any point during reasoning, if you\n" + " recognize a specific information need that your current context\n" + " cannot answer (e.g. 'is there a past lesson about this pattern?'),\n" + " call `koan_search` with a targeted query. Use it when you know\n" + " WHAT to ask. The mechanical injection catches things you don't\n" + " know to ask about.\n" ) diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index 7e945ff..a60f7e1 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -50,6 +50,7 @@ from ..phases import PhaseContext, StepGuidance from ..phases.format_step import format_phase_complete, format_steering_messages, format_step, format_user_messages from .interactions import activate_next_interaction, enqueue_interaction +from ..projections import TextEntry if TYPE_CHECKING: from ..state import AgentState, AppState @@ -206,6 +207,92 @@ def _drain_and_append_steering(result: str, agent: AgentState | None = None) -> return result +# -- RAG injection helpers ---------------------------------------------------- + +def _compose_rag_anchor( + task_description: str, + run_dir: str | None, + prior_phase: str | None, + phase_summaries: dict[str, str], +) -> str: + """Compose the anchor string fed to rag.generate_queries(). + + Order: task -> artifacts (mtime ascending) -> immediate prior-phase summary. + Chronological artifact ordering puts the most recent artifact closest to + the summary, placing the most directly relevant content last (where + attention is strongest). + """ + sections: list[str] = [] + if task_description: + sections.append(f"# Task description\n\n{task_description}") + + if run_dir: + run_dir_path = Path(run_dir) + if run_dir_path.is_dir(): + md_files = sorted( + (p for p in run_dir_path.glob("*.md") if p.is_file()), + key=lambda p: p.stat().st_mtime, + ) + for p in md_files: + try: + body = p.read_text(encoding="utf-8") + except OSError: + continue + sections.append(f"# Artifact: {p.name}\n\n{body}") + + if prior_phase: + summary = phase_summaries.get(prior_phase, "") + if summary: + sections.append(f"# Prior phase summary ({prior_phase})\n\n{summary}") + + return "\n\n".join(sections) + + +async def _compute_memory_injection(agent: AgentState) -> str: + """Run the mechanical RAG injection pipeline for the current phase. + + Returns a rendered markdown block, or "" if the phase has no retrieval + directive, memory is unavailable, or retrieval fails. Retrieval is + best-effort: failure must never block the phase handshake. + """ + assert _app_state is not None + workflow = _app_state.workflow + if workflow is None: + return "" + binding = workflow.get_binding(_app_state.phase) + if binding is None or not binding.retrieval_directive: + return "" + + run = _app_state.projection_store.projection.run + prior_phase = agent.phase_ctx.completed_phase + phase_summaries = dict(run.phase_summaries) if run else {} + + anchor = _compose_rag_anchor( + task_description=_app_state.task_description or "", + run_dir=agent.phase_ctx.run_dir or _app_state.run_dir, + prior_phase=prior_phase, + phase_summaries=phase_summaries, + ) + + try: + from ..memory.retrieval.rag import inject, render_injection_block + index = _get_retrieval_index() + results = await inject( + index=index, + directive=binding.retrieval_directive, + anchor=anchor, + k=5, + ) + return render_injection_block(results) + except Exception: + log.warning( + "mechanical memory injection failed for phase %r; continuing without injection", + _app_state.phase, + exc_info=True, + ) + return "" + + # -- koan_complete_step private helpers ---------------------------------------- async def _step_phase_handshake(agent: AgentState) -> str: @@ -230,6 +317,11 @@ async def _step_phase_handshake(agent: AgentState) -> str: agent_id=agent.agent_id, ) + # Mechanical memory injection runs once per phase, at the step 0 -> 1 + # handshake. The rendered block is stashed on ctx.memory_injection and + # phase modules prepend it to their step 1 instructions. + ctx.memory_injection = await _compute_memory_injection(agent) + agent.step = 1 guidance = phase_module.step_guidance(1, ctx) @@ -373,6 +465,39 @@ async def koan_complete_step(thoughts: str = "") -> str: end_tool_call(agent, call_id, "koan_complete_step", result_str) +# -- Summary extraction ------------------------------------------------------- + +def _extract_last_orchestrator_text(agent: AgentState) -> str: + """Return the most recent textual turn from the primary agent. + + Concatenates any completed TextEntry at the tail of conversation.entries + with the current pending_text (which has not yet been flushed by a + subsequent tool call). Returns "" if neither is present. + + Runner buffering may deliver the tool call before the final text deltas + are folded into the projection. This is observable: suspiciously short + captures are logged as warnings by the caller. + """ + assert _app_state is not None + run = _app_state.projection_store.projection.run + if run is None: + return "" + proj_agent = run.agents.get(agent.agent_id) + if proj_agent is None: + return "" + conv = proj_agent.conversation + # Walk entries backward to find the tail TextEntry chain (same turn). + tail: list[str] = [] + for entry in reversed(conv.entries): + if isinstance(entry, TextEntry): + tail.insert(0, entry.text) + else: + break + pending = conv.pending_text or "" + combined = "\n".join([*tail, pending]).strip() + return combined + + # -- koan_yield --------------------------------------------------------------- @mcp.tool(name="koan_yield") @@ -430,6 +555,42 @@ async def koan_yield( assert _app_state is not None from ..state import drain_user_messages, drain_steering_messages + # Capture phase summary on the FIRST yield of each phase. + # Contract: the orchestrator's assistant text immediately preceding + # koan_yield is treated as the phase summary. Subsequent yields in the + # same phase do not overwrite. + # + # Ordering note: stream_delta events and tool calls both flow through the + # same asyncio event loop, but runner buffering may deliver the tool call + # before the final text deltas have been folded into the projection. When + # the captured summary is suspiciously short we log a warning so the + # failure is observable; we do NOT block the yield on it. + if agent.is_primary and _app_state.phase: + run = _app_state.projection_store.projection.run + already_captured = bool(run and run.phase_summaries.get(_app_state.phase)) + if not already_captured: + summary_text = _extract_last_orchestrator_text(agent) + if summary_text: + if len(summary_text) < 50: + log.warning( + "phase summary for %r is suspiciously short (%d chars);" + " text deltas may not have been fully flushed before" + " koan_yield fired", + _app_state.phase, len(summary_text), + ) + from ..events import build_phase_summary_captured + _app_state.projection_store.push_event( + "phase_summary_captured", + build_phase_summary_captured(_app_state.phase, summary_text), + agent_id=agent.agent_id, + ) + else: + log.warning( + "phase summary for %r not captured: no assistant text found" + " before koan_yield", + _app_state.phase, + ) + # Emit yield_started — renders YieldEntry in the conversation stream and # sets run.active_yield so the UI pins pills above the chat input. from ..events import build_yield_started From d27ecb916c392ebbb861f80308c848b5c4082762 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 18 Apr 2026 11:14:36 +0700 Subject: [PATCH 399/412] fix: surface subagent failure details in phase logs --- koan/subagent.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/koan/subagent.py b/koan/subagent.py index a0db0d2..cb6cba4 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -430,6 +430,15 @@ async def drain_stderr(): await event_log.emit_runner_diagnostic(diag) error_str = "bootstrap_failure" exit_code = 1 + elif exit_code != 0: + final = (agent.final_response or "").strip() + stderr_lines = [l.strip() for l in stderr_output.splitlines() if l.strip()] + stderr_tail = stderr_lines[-1] if stderr_lines else "" + error_str = final or stderr_tail or f"exit_code={exit_code}" + log.error( + "%s (agent_id=%s) exited unexpectedly (exit_code=%d): %s", + role, agent_id, exit_code, error_str, + ) # Cleanup: remove from active processes, resolve pending interactions app_state._active_processes.pop(agent_id, None) @@ -437,7 +446,7 @@ async def drain_stderr(): # Finalize audit log outcome = "completed" if exit_code == 0 else "failed" - await event_log.emit_phase_end(outcome) + await event_log.emit_phase_end(outcome, detail=error_str) await event_log.close() final_response = agent.final_response @@ -454,7 +463,8 @@ async def drain_stderr(): agent_id=agent_id, ) - log.info("%s (agent_id=%s) exited with code %d", role, agent_id, exit_code) + log_fn = log.info if exit_code == 0 else log.warning + log_fn("%s (agent_id=%s) exited with code %d", role, agent_id, exit_code) return SubagentResult(exit_code=exit_code, final_response=final_response) From fd2a79bb58f7f2065560993bfad4050aed23c995 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 18 Apr 2026 11:14:42 +0700 Subject: [PATCH 400/412] fix: use opus[1m] alias in built-in Claude profiles --- koan/runners/claude.py | 2 +- koan/runners/registry.py | 2 +- tests/test_runners.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 4741da0..f75033f 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -106,7 +106,7 @@ def __init__(self, *, subagent_dir: str) -> None: def list_models(self, binary: str) -> list[ModelInfo]: return [ ModelInfo( - alias="opus", display_name="Opus", + alias="opus[1m]", display_name="Opus", thinking_modes=frozenset({"disabled", "low", "medium", "high", "xhigh"}), tier_hint="strong", ), diff --git a/koan/runners/registry.py b/koan/runners/registry.py index 6c5ccb5..579bac9 100644 --- a/koan/runners/registry.py +++ b/koan/runners/registry.py @@ -51,7 +51,7 @@ # Fixed built-in profiles: (runner_type, model) per tier, no fallback logic _FIXED_PROFILE_SPECS: dict[str, dict[ModelTier, tuple[str, str]]] = { "frontier": { - "strong": ("claude", "opus"), + "strong": ("claude", "opus[1m]"), "standard": ("claude", "sonnet"), "cheap": ("claude", "haiku"), }, diff --git a/tests/test_runners.py b/tests/test_runners.py index a16eb0e..88a989e 100644 --- a/tests/test_runners.py +++ b/tests/test_runners.py @@ -529,7 +529,7 @@ def test_haiku_limited_thinking(self): def test_opus_all_thinking_modes(self): runner = ClaudeRunner(subagent_dir="/tmp/x") models = runner.list_models("claude") - opus = [m for m in models if m.alias == "opus"][0] + opus = [m for m in models if m.alias == "opus[1m]"][0] assert opus.thinking_modes == frozenset({"disabled", "low", "medium", "high", "xhigh"}) def test_sonnet_all_thinking_modes(self): From 0e4bd7195f8f9df269c9f94780802a0c1177f70b Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 18 Apr 2026 11:14:52 +0700 Subject: [PATCH 401/412] test: remove brittle prompt-structure test suite --- ...ts-asserting-llm-prompt-content-deleted.md | 8 + tests/phases/test_curation.py | 337 ------------------ tests/test_driver.py | 17 - tests/test_phases.py | 286 --------------- tests/test_web_flows.py | 84 ----- tests/test_workflows.py | 288 --------------- 6 files changed, 8 insertions(+), 1012 deletions(-) create mode 100644 .koan/memory/0051-unit-tests-asserting-llm-prompt-content-deleted.md delete mode 100644 tests/phases/test_curation.py delete mode 100644 tests/test_driver.py delete mode 100644 tests/test_phases.py delete mode 100644 tests/test_workflows.py diff --git a/.koan/memory/0051-unit-tests-asserting-llm-prompt-content-deleted.md b/.koan/memory/0051-unit-tests-asserting-llm-prompt-content-deleted.md new file mode 100644 index 0000000..7c7b598 --- /dev/null +++ b/.koan/memory/0051-unit-tests-asserting-llm-prompt-content-deleted.md @@ -0,0 +1,8 @@ +--- +title: Unit tests asserting LLM prompt content deleted; pure-logic tests retained +type: decision +created: '2026-04-17T12:14:23Z' +modified: '2026-04-17T12:14:23Z' +--- + +The koan test suite retention policy was established on 2026-04-17 during the test suite overhaul planning session. Leon stated that tests asserting on LLM prompt content (hardcoded strings in step guidance text, workflow dataclass structure, phase shape) are low-value because they break whenever prompt engineering changes and provide no signal about actual LLM behavior. Leon decided to delete the following test files entirely: `tests/test_phases.py` (286 lines of step-progression and prompt-text content tests), `tests/test_workflows.py` (288 lines of workflow dataclass structure tests), `tests/phases/test_curation.py` (phase shape and SYSTEM_PROMPT content checks), and `tests/test_driver.py` (17-line import smoke test). Leon decided to retain tests that cover deterministic pure-logic algorithms: `tests/test_permissions.py` (permission gate logic), `tests/test_projections.py` (projection fold), `tests/test_audit_fold.py` (audit fold), `tests/test_runners.py` (stream event parsing), `tests/test_probe.py` (runner probing), `tests/test_mcp_check_or_raise.py` (permission check), `tests/test_interactions.py` (interaction queue FIFO logic), `tests/test_subagent.py`, and all twelve files under `tests/memory/`. diff --git a/tests/phases/test_curation.py b/tests/phases/test_curation.py deleted file mode 100644 index ed652b5..0000000 --- a/tests/phases/test_curation.py +++ /dev/null @@ -1,337 +0,0 @@ -# Tests for the curation phase module. - -from __future__ import annotations - -from koan.phases import PhaseContext, curation - - -def _ctx(**kw) -> PhaseContext: - defaults = {"run_dir": "/tmp/run", "subagent_dir": "/tmp/sub"} - defaults.update(kw) - return PhaseContext(**defaults) - - -class TestModuleShape: - def test_total_steps_is_2(self): - assert curation.TOTAL_STEPS == 2 - - def test_role_is_orchestrator(self): - assert curation.ROLE == "orchestrator" - - def test_scope_is_general(self): - assert curation.SCOPE == "general" - - def test_step_names(self): - assert curation.STEP_NAMES == {1: "Inventory", 2: "Memorize"} - - def test_system_prompt_is_nonempty(self): - assert isinstance(curation.PHASE_ROLE_CONTEXT, str) - assert len(curation.PHASE_ROLE_CONTEXT) > 100 - - def test_system_prompt_writing_discipline_is_high_level_only(self): - # Post-rewrite: writing discipline in the system prompt is a - # one-paragraph high-level summary. The full rules and the - # contrastive examples live in step 2's body, rendered at the - # drafting moment. The system prompt keeps just the pillars - # ("temporally grounded, attributed, event-style") and an - # explicit pointer to step 2. - sp = curation.PHASE_ROLE_CONTEXT.lower() - assert "temporally grounded" in sp - assert "attributed" in sp - assert "event-style" in sp - assert "step 2" in sp # points at where the full rules live - - def test_system_prompt_has_type_discrimination_tree(self): - sp = curation.PHASE_ROLE_CONTEXT - # The 4-question tree, with first-match-wins semantics, must - # be present as a procedure (not just definitions). - assert "Picking the type for a candidate" in sp - assert "first match wins" in sp.lower() or "FIRST match wins" in sp - # Each of the four types must appear as a tree outcome. - for type_name in ("decision", "lesson", "procedure", "context"): - assert type_name in sp - # Lesson trigger includes the user-correction case. - assert "correct the agent" in sp - - def test_system_prompt_behavioral_knowledge_must_be_captured(self): - # The "what not to capture" section must require behavioral - # knowledge (decisions, lessons, procedures) to be captured - # even when it also appears in project documents. - sp = curation.PHASE_ROLE_CONTEXT - assert "Behavioral knowledge" in sp - assert "MUST be" in sp - assert "Rationale and rejected alternatives" in sp - assert "Lessons from prior workflows" in sp - - def test_system_prompt_enumerates_memory_tools(self): - # Tools must be visible at the role layer. - sp = curation.PHASE_ROLE_CONTEXT - assert "koan_memorize" in sp - assert "koan_forget" in sp - assert "koan_memory_status" in sp - - def test_system_prompt_declares_classification_schema(self): - sp = curation.PHASE_ROLE_CONTEXT - for label in ("ADD", "UPDATE", "NOOP", "DEPRECATE"): - assert label in sp, f"schema label {label!r} missing from PHASE_ROLE_CONTEXT" - - def test_system_prompt_declares_structural_invariant(self): - # Propose-then-write must be stated, not buried. - sp = curation.PHASE_ROLE_CONTEXT.lower() - assert "propose" in sp and "approve" in sp - - def test_system_prompt_declares_read_write_asymmetry(self): - # Reads of .koan/memory/*.md are allowed; writes are not. - sp = curation.PHASE_ROLE_CONTEXT - # Reads explicitly allowed and explained: - assert "Reading individual entries" in sp - assert ".koan/memory/" in sp - # Writes explicitly forbidden: - assert "Do NOT write or delete files under `.koan/`" in sp - - def test_system_prompt_acknowledges_coding_agent_memory(self): - # CLAUDE.md / AGENTS.md / .cursor/ etc. are a separate, read-only system. - sp = curation.PHASE_ROLE_CONTEXT - assert "coding agent" in sp.lower() - assert "CLAUDE.md" in sp - assert "READ-ONLY" in sp - - -class TestLifecycle: - def test_get_next_step_linear(self): - ctx = _ctx() - assert curation.get_next_step(1, ctx) == 2 - - def test_get_next_step_terminal(self): - assert curation.get_next_step(2, _ctx()) is None - - def test_validate_all_none(self): - ctx = _ctx() - for s in (1, 2): - assert curation.validate_step_completion(s, ctx) is None - - -class TestStepHeaders: - """Every step must render workflow_shape, goal, and tools_this_step blocks - with a YOU-ARE-HERE marker pointing at the current step.""" - - def test_step_1_renders_workflow_shape(self): - g = curation.step_guidance(1, _ctx()) - text = "\n".join(g.instructions) - assert "<workflow_shape>" in text - assert "</workflow_shape>" in text - # Position marker on step 1. - # Format: `... step 1 -- Inventory ... (<-- YOU ARE HERE)` on the step-1 line. - for line in text.splitlines(): - if "step 1 -- Inventory" in line: - assert "YOU ARE HERE" in line, f"step-1 line missing marker: {line!r}" - break - else: - raise AssertionError("step-1 line not found in workflow_shape block") - for line in text.splitlines(): - if "step 2 -- Memorize" in line: - assert "YOU ARE HERE" not in line, f"step-2 line wrongly marked: {line!r}" - - def test_step_2_renders_workflow_shape(self): - g = curation.step_guidance(2, _ctx()) - text = "\n".join(g.instructions) - assert "<workflow_shape>" in text - for line in text.splitlines(): - if "step 2 -- Memorize" in line: - assert "YOU ARE HERE" in line, f"step-2 line missing marker: {line!r}" - break - else: - raise AssertionError("step-2 line not found in workflow_shape block") - - def test_both_steps_render_goal_block(self): - for step in (1, 2): - text = "\n".join(curation.step_guidance(step, _ctx()).instructions) - assert "<goal>" in text and "</goal>" in text - assert "koan_memorize" in text # the goal names the central tool - - def test_step_1_tools_block_calls_memory_status_first(self): - text = "\n".join(curation.step_guidance(1, _ctx()).instructions) - assert "<tools_this_step>" in text - assert "koan_memory_status" in text - # FIRST is the load-bearing word. - assert "FIRST" in text - - def test_step_2_tools_block_lists_write_tools(self): - text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - assert "<tools_this_step>" in text - assert "koan_yield" in text - assert "koan_memorize" in text - assert "koan_forget" in text - - -class TestStep1Inventory: - def test_title_is_inventory(self): - g = curation.step_guidance(1, _ctx()) - assert g.title == "Inventory" - - def test_renders_directive_block(self): - ctx = _ctx(phase_instructions="## Source: postmortem\n\nWork from transcript.") - g = curation.step_guidance(1, ctx) - text = "\n".join(g.instructions) - assert "<directive>" in text - assert "</directive>" in text - assert "postmortem" in text - assert "transcript" in text - - def test_renders_task_block_when_present(self): - ctx = _ctx(task_description="audit my memory entries for staleness") - g = curation.step_guidance(1, ctx) - text = "\n".join(g.instructions) - assert "<task>" in text - assert "</task>" in text - assert "audit my memory entries for staleness" in text - - def test_renders_task_block_placeholder_when_absent(self): - g = curation.step_guidance(1, _ctx()) - text = "\n".join(g.instructions) - assert "<task>" in text - assert "no user task" in text.lower() - - def test_default_directive_when_missing(self): - g = curation.step_guidance(1, _ctx()) - text = "\n".join(g.instructions) - assert "No directive provided" in text - - def test_calls_out_memory_status(self): - g = curation.step_guidance(1, _ctx()) - text = "\n".join(g.instructions) - assert "koan_memory_status" in text - - def test_acknowledges_coding_agent_memory_as_read_only(self): - text = "\n".join(curation.step_guidance(1, _ctx()).instructions) - assert "CLAUDE.md" in text or "coding agent" in text.lower() - - def test_produces_candidate_list_contract(self): - text = "\n".join(curation.step_guidance(1, _ctx()).instructions) - assert "candidate list" in text.lower() - - def test_points_at_type_discrimination_tree(self): - # Step 1 must reference the system prompt's type discrimination - # tree at the point where types are assigned, so the orchestrator - # applies the tree procedurally rather than picking types from - # the abstract definitions alone. - # Flatten whitespace so the substring match works across line wraps. - import re - text = "\n".join(curation.step_guidance(1, _ctx()).instructions) - flat = re.sub(r"\s+", " ", text).lower() - assert "discrimination tree" in flat - assert "first match wins" in flat - - -class TestStep2Memorize: - def test_title_is_memorize(self): - g = curation.step_guidance(2, _ctx()) - assert g.title == "Memorize" - - def test_contains_loop_vocabulary(self): - text = "\n".join(curation.step_guidance(2, _ctx()).instructions).lower() - assert "draft" in text - assert "yield" in text - assert "apply" in text - assert "batch" in text - - def test_contains_classification_labels(self): - text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - for label in ("ADD", "UPDATE", "NOOP", "DEPRECATE"): - assert label in text - - def test_references_memory_tools(self): - text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - assert "koan_memorize" in text - assert "koan_forget" in text - assert "koan_yield" in text - - def test_renders_writing_discipline_at_drafting_moment(self): - # Post-rewrite: writing discipline is now INTENTIONALLY rendered - # in step 2's body, right at the drafting moment. The previous - # design kept it only in the system prompt, which was too far - # from the drafting turn; 7/10 entries in the audit violated - # rules the system prompt had correctly stated. - text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - assert "## Writing discipline" in text - # All 5 rules must be visible inline, not by reference. - assert "Open with a named subsystem" in text - assert "Temporally ground every claim" in text - assert "Attribute every claim" in text - assert "Event-style, past tense" in text - assert "Name things concretely" in text - - def test_renders_contrastive_examples(self): - # Two contrastive bad/good pairs must appear in step 2's body: - # one decision pair (Redis session storage), one lesson pair - # (Alembic migration). Examples are general-purpose, not - # koan-specific. - text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - assert '<example type="decision-bad">' in text - assert '<example type="decision-good">' in text - assert '<example type="lesson-bad">' in text - assert '<example type="lesson-good">' in text - # Decision good-example sentinel: - assert "Redis 7.2" in text - # Lesson good-example sentinel: - assert "Alembic" in text - # Examples must NOT reference koan itself. - assert "koan" not in text.lower() or "koan_" in text # tool names OK - # "What changed between bad and good" explanations must follow each pair. - assert text.count("What changed between bad and good") == 2 - - def test_renders_6_substep_loop(self): - # The per-batch loop has 6 committed sub-operations in order: - # Draft -> Self-critique -> Revise -> Yield -> Apply -> Cross off. - text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - for header in ( - "### A. Draft", - "### B. Self-critique", - "### C. Revise", - "### D. Yield", - "### E. Apply", - "### F. Cross off", - ): - assert header in text, f"missing substep header: {header!r}" - # The critical anti-simulated-refinement guardrails. - assert "Do not collapse substeps" in text - assert "Do not skip this substep" in text - - def test_renders_draft_quality_checklist(self): - # The 5-item checklist must be present as a schema the orchestrator - # can apply per-draft in substep B. - text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - assert "Draft-quality checklist" in text - assert "PASS / FAIL" in text - # The checklist items map 1-to-1 onto the 5 writing discipline rules. - for item in ( - "Opens with named subsystem", - "Contains absolute date", - "Contains attribution", - "Event-style, past tense", - "Concrete naming", - ): - assert item in text, f"missing checklist item: {item!r}" - - def test_includes_anticipatory_tool_call_check(self): - # The tool-call anticipatory check from the previous round is - # preserved (renamed to "Anticipatory tool-call check" to - # distinguish from the new draft-quality gate in substeps B/C). - text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - assert "Anticipatory tool-call check" in text - assert "Did you call" in text # the verification question - - def test_wrap_up_calls_memory_status(self): - # Wrap-up (folded in from former step 3) calls koan_memory_status - # for summary regeneration. - text = "\n".join(curation.step_guidance(2, _ctx()).instructions) - assert "Wrap-up" in text - # koan_memory_status appears multiple times; just ensure it's there. - assert "koan_memory_status" in text - - def test_reports_counts_in_schema_terms(self): - text = "\n".join(curation.step_guidance(2, _ctx()).instructions).lower() - assert "added" in text - assert "updated" in text - assert "deprecated" in text - assert "noop" in text diff --git a/tests/test_driver.py b/tests/test_driver.py deleted file mode 100644 index 31fba03..0000000 --- a/tests/test_driver.py +++ /dev/null @@ -1,17 +0,0 @@ -# Tests for driver -- the persistent orchestrator driver. -# route_from_state has been removed as part of the persistent orchestrator refactor. -# Driver now manages a single long-lived orchestrator process for the entire run. - -import pytest - -from koan.driver import driver_main, _push_artifact_diff - - -class TestDriverImports: - """Smoke test: driver module imports cleanly after refactor.""" - - def test_driver_main_importable(self): - assert callable(driver_main) - - def test_push_artifact_diff_importable(self): - assert callable(_push_artifact_diff) diff --git a/tests/test_phases.py b/tests/test_phases.py deleted file mode 100644 index 6843183..0000000 --- a/tests/test_phases.py +++ /dev/null @@ -1,286 +0,0 @@ -# Tests for phase module get_next_step, validate_step_completion, and purity. - -import copy - -import pytest - -from koan.phases import PhaseContext -from koan.phases import intake -from koan.phases import brief_writer -from koan.phases import core_flows -from koan.phases import tech_plan -from koan.phases import ticket_breakdown -from koan.phases import cross_artifact_validation -from koan.phases import executor -from koan.phases import orchestrator -from koan.phases import scout -from koan.phases import plan_spec -from koan.phases import plan_review -from koan.phases import execute as execute_phase - - -def _ctx(**kw) -> PhaseContext: - defaults = {"run_dir": "/tmp/run", "subagent_dir": "/tmp/sub"} - defaults.update(kw) - return PhaseContext(**defaults) - - -# -- Intake -------------------------------------------------------------------- - -class TestIntake: - # -- Linear progression (steps 1-3) ---------------------------------------- - - @pytest.mark.parametrize("step", [1, 2]) - def test_linear_steps(self, step): - assert intake.get_next_step(step, _ctx()) == step + 1 - - def test_step_3_completes(self): - """Step 3 (Write) completes unconditionally — no review gate.""" - assert intake.get_next_step(3, _ctx()) is None - - # -- No validation gates --------------------------------------------------- - - def test_validate_all_steps_none(self): - ctx = _ctx() - for s in range(1, 4): - assert intake.validate_step_completion(s, ctx) is None - - # -- Step guidance contains workflow context injection ---------------------- - - def test_step_1_guidance_with_phase_instructions(self): - ctx = _ctx(phase_instructions="## Scope\nThis is a plan workflow.") - g = intake.step_guidance(1, ctx) - text = "\n".join(g.instructions) - assert "Workflow Context" in text - assert "plan workflow" in text - - def test_step_1_guidance_with_workflow_name(self): - ctx = _ctx(workflow_name="plan") - g = intake.step_guidance(1, ctx) - text = "\n".join(g.instructions) - assert "plan" in text - - def test_step_3_guidance_is_summarize(self): - ctx = _ctx(run_dir="/tmp/myrun") - g = intake.step_guidance(3, ctx) - assert g.title == "Summarize" - text = "\n".join(g.instructions) - assert "summary" in text.lower() - - -# -- Brief Writer -------------------------------------------------------------- - -class TestBriefWriter: - def test_step_1_to_2(self): - assert brief_writer.get_next_step(1, _ctx()) == 2 - - def test_step_2_completes(self): - """Step 2 is terminal — no review gate.""" - assert brief_writer.get_next_step(2, _ctx()) is None - - def test_validate_all_none(self): - ctx = _ctx() - for s in (1, 2): - assert brief_writer.validate_step_completion(s, ctx) is None - - def test_total_steps_is_2(self): - assert brief_writer.TOTAL_STEPS == 2 - - -# -- Plan Spec ----------------------------------------------------------------- - -class TestPlanSpec: - def test_step_1_to_2(self): - assert plan_spec.get_next_step(1, _ctx()) == 2 - - def test_step_2_completes(self): - assert plan_spec.get_next_step(2, _ctx()) is None - - def test_validate_always_none(self): - ctx = _ctx() - for s in (1, 2): - assert plan_spec.validate_step_completion(s, ctx) is None - - def test_total_steps_is_2(self): - assert plan_spec.TOTAL_STEPS == 2 - - def test_scope_is_plan(self): - assert plan_spec.SCOPE == "plan" - - def test_step_1_guidance_references_intake_context(self): - ctx = _ctx(run_dir="/tmp/myrun") - g = plan_spec.step_guidance(1, ctx) - text = "\n".join(g.instructions) - assert "intake" in text.lower() - - def test_step_2_guidance_references_plan_md(self): - ctx = _ctx(run_dir="/tmp/myrun") - g = plan_spec.step_guidance(2, ctx) - text = "\n".join(g.instructions) - assert "plan.md" in text - - -# -- Plan Review --------------------------------------------------------------- - -class TestPlanReview: - def test_step_1_to_2(self): - assert plan_review.get_next_step(1, _ctx()) == 2 - - def test_step_2_completes(self): - assert plan_review.get_next_step(2, _ctx()) is None - - def test_validate_always_none(self): - ctx = _ctx() - for s in (1, 2): - assert plan_review.validate_step_completion(s, ctx) is None - - def test_total_steps_is_2(self): - assert plan_review.TOTAL_STEPS == 2 - - def test_scope_is_plan(self): - assert plan_review.SCOPE == "plan" - - def test_step_1_guidance_references_intake_and_plan(self): - ctx = _ctx(run_dir="/tmp/myrun") - g = plan_review.step_guidance(1, ctx) - text = "\n".join(g.instructions) - assert "intake" in text.lower() - assert "plan.md" in text - - -# -- Execute Phase ------------------------------------------------------------- - -class TestExecutePhase: - def test_step_1_to_2(self): - assert execute_phase.get_next_step(1, _ctx()) == 2 - - def test_step_2_completes(self): - assert execute_phase.get_next_step(2, _ctx()) is None - - def test_validate_always_none(self): - ctx = _ctx() - for s in (1, 2): - assert execute_phase.validate_step_completion(s, ctx) is None - - def test_total_steps_is_2(self): - assert execute_phase.TOTAL_STEPS == 2 - - def test_scope_is_general(self): - assert execute_phase.SCOPE == "general" - - def test_step_1_guidance_with_phase_instructions(self): - ctx = _ctx(phase_instructions="## What to hand off\nCall koan_request_executor.") - g = execute_phase.step_guidance(1, ctx) - text = "\n".join(g.instructions) - assert "koan_request_executor" in text - - -# -- Orchestrator -------------------------------------------------------------- - -class TestOrchestrator: - def test_pre_execution_step_2_completes(self): - ctx = _ctx(step_sequence="pre-execution") - assert orchestrator.get_next_step(2, ctx) is None - - def test_post_execution_step_2_advances(self): - ctx = _ctx(step_sequence="post-execution") - assert orchestrator.get_next_step(2, ctx) == 3 - - def test_post_execution_step_4_completes(self): - ctx = _ctx(step_sequence="post-execution") - assert orchestrator.get_next_step(4, ctx) is None - - def test_pre_execution_step_1_advances(self): - ctx = _ctx(step_sequence="pre-execution") - assert orchestrator.get_next_step(1, ctx) == 2 - - -# -- Executor (rewritten: 3-step) ---------------------------------------------- - -class TestExecutor: - def test_step_1_to_2(self): - assert executor.get_next_step(1, _ctx()) == 2 - - def test_step_2_to_3(self): - assert executor.get_next_step(2, _ctx()) == 3 - - def test_step_3_completes(self): - assert executor.get_next_step(3, _ctx()) is None - - def test_validate_always_none(self): - ctx = _ctx() - for s in (1, 2, 3): - assert executor.validate_step_completion(s, ctx) is None - - def test_total_steps_is_3(self): - assert executor.TOTAL_STEPS == 3 - - def test_scope_is_general(self): - assert executor.SCOPE == "general" - - def test_step_1_guidance_with_artifacts(self): - ctx = _ctx(run_dir="/tmp/myrun", executor_artifacts=["plan.md"]) - g = executor.step_guidance(1, ctx) - text = "\n".join(g.instructions) - assert "/tmp/myrun/plan.md" in text - - def test_step_1_guidance_with_phase_instructions(self): - ctx = _ctx(phase_instructions="Key constraint: don't touch auth module.") - g = executor.step_guidance(1, ctx) - text = "\n".join(g.instructions) - assert "Key constraint" in text - - def test_step_1_guidance_with_retry_context(self): - ctx = _ctx(retry_context="Previous run failed at step 3 due to import error.") - g = executor.step_guidance(1, ctx) - text = "\n".join(g.instructions) - assert "import error" in text - - -# -- Linear modules (all steps linear, no validation gates) -------------------- - -LINEAR_MODULES = [ - (core_flows, 2), - (tech_plan, 3), - (ticket_breakdown, 2), - (cross_artifact_validation, 2), - (scout, 3), -] - - -@pytest.mark.parametrize("mod,total", LINEAR_MODULES, ids=lambda x: x.ROLE if hasattr(x, "ROLE") else str(x)) -class TestLinearModules: - def test_steps_advance(self, mod, total): - ctx = _ctx() - for s in range(1, total): - assert mod.get_next_step(s, ctx) == s + 1 - - def test_last_step_completes(self, mod, total): - assert mod.get_next_step(total, _ctx()) is None - - def test_validate_always_none(self, mod, total): - ctx = _ctx() - for s in range(1, total + 1): - assert mod.validate_step_completion(s, ctx) is None - - -# -- Purity invariant ---------------------------------------------------------- - -class TestPurity: - def test_intake_step_3_pure(self): - """Intake step 3 always returns None (no review gate).""" - ctx = _ctx() - ctx_copy = copy.deepcopy(ctx) - r1 = intake.get_next_step(3, ctx) - r2 = intake.get_next_step(3, ctx) - assert r1 == r2 == None - assert ctx == ctx_copy - - def test_brief_writer_step_2_pure(self): - """Brief writer step 2 always returns None (no review gate).""" - ctx = _ctx() - ctx_copy = copy.deepcopy(ctx) - r1 = brief_writer.get_next_step(2, ctx) - r2 = brief_writer.get_next_step(2, ctx) - assert r1 == r2 == None - assert ctx == ctx_copy diff --git a/tests/test_web_flows.py b/tests/test_web_flows.py index e0484e7..372382f 100644 --- a/tests/test_web_flows.py +++ b/tests/test_web_flows.py @@ -69,19 +69,6 @@ def test_landing_page_renders(client, app_state): # -- Start run ---------------------------------------------------------------- -def test_start_run_sets_event(client, app_state): - app_state.probe_results = _make_probe_results() - resp = client.post( - "/api/start-run", - json={"task": "build something", "profile": "balanced"}, - ) - assert resp.status_code == 200 - data = resp.json() - assert data["ok"] is True - assert app_state.start_event.is_set() - assert app_state.run_dir is not None - - def test_start_run_requires_task(client, app_state): resp = client.post("/api/start-run", json={"task": ""}) assert resp.status_code == 422 @@ -115,16 +102,6 @@ def test_start_run_blocked_no_runners(client, app_state): assert data["error"] == "no_runners" -def test_start_run_persists_profile(client, app_state): - app_state.probe_results = _make_probe_results() - resp = client.post( - "/api/start-run", - json={"task": "build something", "profile": "balanced"}, - ) - assert resp.status_code == 200 - assert app_state.config.active_profile == "balanced" - - # -- Start-run preflight ------------------------------------------------------- def test_preflight_returns_required_types(client, app_state): @@ -164,24 +141,6 @@ def test_preflight_missing_profile(client, app_state): # -- Start-run installation validation ----------------------------------------- -def test_start_run_accepts_installation_selection(client, app_state, tmp_path): - from koan.runners.registry import compute_builtin_profiles - app_state.probe_results = _make_probe_results() - app_state.builtin_profiles = compute_builtin_profiles(app_state.probe_results) - binary = tmp_path / "claude" - binary.touch() - app_state.config.agent_installations = [ - AgentInstallation(alias="my-claude", runner_type="claude", binary=str(binary)), - ] - resp = client.post("/api/start-run", json={ - "task": "build something", - "profile": "balanced", - "installations": {"claude": "my-claude"}, - }) - assert resp.status_code == 200 - assert app_state.run_installations["claude"] == "my-claude" - - def test_start_run_rejects_missing_binary(client, app_state): from koan.runners.registry import compute_builtin_profiles app_state.probe_results = _make_probe_results() @@ -254,51 +213,8 @@ def test_path_traversal_blocked(client, app_state): assert resp.status_code in (400, 404) -# -- Probe endpoint ----------------------------------------------------------- - -def test_probe_endpoint(client, app_state): - app_state.probe_results = _make_probe_results() - app_state.builtin_profiles = {"balanced": Profile(name="balanced", tiers={ - "strong": ProfileTier(runner_type="claude", model="opus", thinking="high"), - })} - - resp = client.get("/api/probe") - assert resp.status_code == 200 - data = resp.json() - assert "runners" in data - assert "balanced_profile" in data - assert len(data["runners"]) == 3 - assert data["runners"][0]["runner_type"] == "claude" - assert len(data["runners"][0]["models"]) == 2 - - # -- Profile endpoints -------------------------------------------------------- -def test_profiles_list_includes_balanced(client, app_state): - app_state.builtin_profiles = {"balanced": Profile(name="balanced", tiers={ - "strong": ProfileTier(runner_type="claude", model="opus", thinking="high"), - })} - - resp = client.get("/api/profiles") - assert resp.status_code == 200 - data = resp.json() - assert any(p["name"] == "balanced" and p["read_only"] is True for p in data["profiles"]) - - -def test_profiles_create_valid(client, app_state): - app_state.probe_results = _make_probe_results() - - resp = client.post("/api/profiles", json={ - "name": "myprofile", - "tiers": { - "strong": {"runner_type": "claude", "model": "opus", "thinking": "high"}, - }, - }) - assert resp.status_code == 200 - assert resp.json()["ok"] is True - assert any(p.name == "myprofile" for p in app_state.config.profiles) - - def test_profiles_create_invalid_runner(client, app_state): app_state.probe_results = _make_probe_results() diff --git a/tests/test_workflows.py b/tests/test_workflows.py deleted file mode 100644 index 0617b59..0000000 --- a/tests/test_workflows.py +++ /dev/null @@ -1,288 +0,0 @@ -# Tests for koan/lib/workflows.py -- workflow type system. - -import pytest - -from koan.lib.workflows import ( - CURATION_WORKFLOW, - MILESTONES_WORKFLOW, - PLAN_WORKFLOW, - WORKFLOWS, - PhaseBinding, - Workflow, - get_suggested_phases, - get_workflow, - is_valid_transition, -) - - -# -- get_workflow -------------------------------------------------------------- - -def test_get_workflow_valid_plan(): - wf = get_workflow("plan") - assert wf.name == "plan" - - -def test_get_workflow_valid_milestones(): - wf = get_workflow("milestones") - assert wf.name == "milestones" - - -def test_get_workflow_invalid_raises(): - with pytest.raises(ValueError, match="Unknown workflow"): - get_workflow("nonexistent") - - -def test_get_workflow_lists_valid_in_error(): - with pytest.raises(ValueError, match="plan"): - get_workflow("bogus") - - -# -- PhaseBinding and Workflow.get_module / get_binding ------------------------ - -def test_get_module_returns_module(): - mod = PLAN_WORKFLOW.get_module("intake") - assert mod is not None - assert hasattr(mod, "step_guidance") - assert hasattr(mod, "TOTAL_STEPS") - - -def test_get_module_unknown_returns_none(): - assert PLAN_WORKFLOW.get_module("nonexistent") is None - - -def test_get_binding_returns_binding(): - b = PLAN_WORKFLOW.get_binding("intake") - assert isinstance(b, PhaseBinding) - assert b.module is not None - assert len(b.description) > 0 - - -def test_get_binding_unknown_returns_none(): - assert PLAN_WORKFLOW.get_binding("nonexistent") is None - - -def test_curation_workflow_initial_module_is_curation(): - """Regression: the orchestrator's initial phase module must match - the workflow's initial_phase. The previous global-registry design - hardcoded intake for all workflows, causing standalone curation - to receive intake step guidance (Gather/Deepen) instead of - curation step guidance (Inventory/Memorize).""" - from koan.phases import curation - mod = CURATION_WORKFLOW.get_module(CURATION_WORKFLOW.initial_phase) - assert mod is curation - - -def test_plan_workflow_initial_module_is_intake(): - from koan.phases import intake - mod = PLAN_WORKFLOW.get_module(PLAN_WORKFLOW.initial_phase) - assert mod is intake - - -def test_same_module_different_guidance_across_workflows(): - """The same phase module (curation) serves two workflows with - different guidance bindings: postmortem in plan, standalone in - the curation workflow.""" - plan_b = PLAN_WORKFLOW.get_binding("curation") - cur_b = CURATION_WORKFLOW.get_binding("curation") - assert plan_b.module is cur_b.module # same module - assert plan_b.guidance != cur_b.guidance # different guidance - assert "postmortem" in plan_b.guidance - assert "standalone" in cur_b.guidance - - -# -- Backward-compat property accessors --------------------------------------- - -def test_available_phases_is_tuple(): - assert isinstance(PLAN_WORKFLOW.available_phases, tuple) - assert "intake" in PLAN_WORKFLOW.available_phases - assert "curation" in PLAN_WORKFLOW.available_phases - - -def test_phase_descriptions_is_dict(): - descs = PLAN_WORKFLOW.phase_descriptions - assert isinstance(descs, dict) - for phase in PLAN_WORKFLOW.available_phases: - assert phase in descs - assert len(descs[phase]) > 0 - - -def test_phase_guidance_is_dict_non_empty_only(): - guidance = PLAN_WORKFLOW.phase_guidance - assert isinstance(guidance, dict) - # intake and execute have guidance; plan-spec and plan-review do not - assert "intake" in guidance - assert "execute" in guidance - # plan-spec has no guidance (carries its own context) - assert "plan-spec" not in guidance - - -# -- get_suggested_phases ----------------------------------------------------- - -def test_get_suggested_phases_intake(): - phases = get_suggested_phases(PLAN_WORKFLOW, "intake") - assert "plan-spec" in phases - assert "execute" in phases - - -def test_get_suggested_phases_plan_spec(): - phases = get_suggested_phases(PLAN_WORKFLOW, "plan-spec") - assert "plan-review" in phases - assert "execute" in phases - - -def test_get_suggested_phases_plan_review(): - phases = get_suggested_phases(PLAN_WORKFLOW, "plan-review") - assert "plan-spec" in phases - assert "execute" in phases - - -def test_get_suggested_phases_execute(): - phases = get_suggested_phases(PLAN_WORKFLOW, "execute") - assert "plan-review" in phases - - -def test_get_suggested_phases_execute_includes_curation(): - phases = get_suggested_phases(PLAN_WORKFLOW, "execute") - assert "curation" in phases - - -def test_get_suggested_phases_milestones_intake_empty(): - phases = get_suggested_phases(MILESTONES_WORKFLOW, "intake") - assert phases == [] - - -def test_get_suggested_phases_unknown_phase(): - phases = get_suggested_phases(PLAN_WORKFLOW, "nonexistent") - assert phases == [] - - -# -- is_valid_transition ------------------------------------------------------- - -def test_is_valid_transition_available_phase(): - assert is_valid_transition(PLAN_WORKFLOW, "intake", "plan-spec") is True - - -def test_is_valid_transition_self_blocked(): - assert is_valid_transition(PLAN_WORKFLOW, "intake", "intake") is False - - -def test_is_valid_transition_unavailable_phase(): - assert is_valid_transition(PLAN_WORKFLOW, "intake", "execution") is False - - -def test_is_valid_transition_any_to_any_within_workflow(): - """Any phase can transition to any other phase in the workflow (user-directed).""" - phases = list(PLAN_WORKFLOW.available_phases) - for from_p in phases: - for to_p in phases: - if from_p != to_p: - assert is_valid_transition(PLAN_WORKFLOW, from_p, to_p) is True, \ - f"{from_p} -> {to_p} should be valid" - - -def test_is_valid_transition_milestones_to_plan_spec_denied(): - assert is_valid_transition(MILESTONES_WORKFLOW, "intake", "plan-spec") is False - - -# -- PLAN_WORKFLOW structure --------------------------------------------------- - -def test_plan_workflow_structure(): - wf = PLAN_WORKFLOW - assert wf.name == "plan" - assert "intake" in wf.available_phases - assert "plan-spec" in wf.available_phases - assert "plan-review" in wf.available_phases - assert "execute" in wf.available_phases - assert "curation" in wf.available_phases - assert wf.initial_phase == "intake" - - -def test_plan_workflow_has_phase_descriptions(): - for phase in PLAN_WORKFLOW.available_phases: - assert phase in PLAN_WORKFLOW.phase_descriptions - assert len(PLAN_WORKFLOW.phase_descriptions[phase]) > 0 - - -def test_plan_workflow_has_guidance_for_intake(): - assert "intake" in PLAN_WORKFLOW.phase_guidance - assert len(PLAN_WORKFLOW.phase_guidance["intake"]) > 0 - - -def test_plan_workflow_has_guidance_for_execute(): - assert "execute" in PLAN_WORKFLOW.phase_guidance - assert len(PLAN_WORKFLOW.phase_guidance["execute"]) > 0 - - -# -- MILESTONES_WORKFLOW structure --------------------------------------------- - -def test_milestones_workflow_structure(): - wf = MILESTONES_WORKFLOW - assert wf.name == "milestones" - assert wf.available_phases == ("intake",) - assert wf.initial_phase == "intake" - assert wf.transitions == {"intake": []} - - -def test_milestones_workflow_has_intake_guidance(): - assert "intake" in MILESTONES_WORKFLOW.phase_guidance - assert len(MILESTONES_WORKFLOW.phase_guidance["intake"]) > 0 - - -# -- CURATION_WORKFLOW structure ----------------------------------------------- - -def test_curation_workflow_exists(): - assert "curation" in WORKFLOWS - - -def test_curation_workflow_structure(): - wf = CURATION_WORKFLOW - assert wf.name == "curation" - assert wf.initial_phase == "curation" - assert "curation" in wf.available_phases - - -def test_curation_workflow_has_standalone_directive(): - guidance = CURATION_WORKFLOW.phase_guidance.get("curation", "") - # Standalone directive defines the review/document/bootstrap pivot. - assert "standalone curation" in guidance - assert "Review" in guidance - assert "Document" in guidance - assert "Bootstrap" in guidance - - -def test_plan_workflow_curation_uses_postmortem_directive(): - guidance = PLAN_WORKFLOW.phase_guidance.get("curation", "") - # Postmortem directive binds source to the in-context transcript and - # forbids scout dispatch. - assert "postmortem" in guidance - assert "transcript" in guidance - assert "koan_request_scouts" in guidance - - -# -- Workflow immutability ----------------------------------------------------- - -def test_workflow_frozen(): - """Workflow instances cannot have fields reassigned (frozen=True).""" - with pytest.raises(Exception): # FrozenInstanceError or AttributeError - PLAN_WORKFLOW.name = "mutated" - - -def test_phase_binding_frozen(): - """PhaseBinding instances cannot have fields reassigned (frozen=True).""" - b = PLAN_WORKFLOW.get_binding("intake") - with pytest.raises(Exception): - b.module = None - - -# -- WORKFLOWS registry ------------------------------------------------------- - -def test_workflows_registry_complete(): - assert "plan" in WORKFLOWS - assert "milestones" in WORKFLOWS - assert "curation" in WORKFLOWS - - -def test_workflows_registry_values_are_workflow_instances(): - for name, wf in WORKFLOWS.items(): - assert isinstance(wf, Workflow) - assert wf.name == name From 1fb7bf362eb0c6c46a8e840881e4667db8f95e30 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sat, 18 Apr 2026 11:15:06 +0700 Subject: [PATCH 402/412] feat: add inspect-ai eval harness for full koan runs --- .gitignore | 5 + ...nspect-ai-uk-aisi-selected-as-koan-eval.md | 8 + ...lver-answers-all-koan-interactive-gates.md | 9 + ...hmark-fixtures-are-manual-git-snapshots.md | 8 + ...ataset-uses-full-run-fixtures-first-per.md | 8 + evals/__init__.py | 0 evals/dataset.py | 35 + evals/fixtures/README.md | 18 + evals/scorers.py | 83 ++ evals/solver.py | 263 ++++++ evals/tasks.py | 18 + pyproject.toml | 2 +- uv.lock | 845 ++++++++++++++++-- 13 files changed, 1229 insertions(+), 73 deletions(-) create mode 100644 .koan/memory/0048-inspect-ai-uk-aisi-selected-as-koan-eval.md create mode 100644 .koan/memory/0049-eval-solver-answers-all-koan-interactive-gates.md create mode 100644 .koan/memory/0050-eval-benchmark-fixtures-are-manual-git-snapshots.md create mode 100644 .koan/memory/0052-eval-dataset-uses-full-run-fixtures-first-per.md create mode 100644 evals/__init__.py create mode 100644 evals/dataset.py create mode 100644 evals/fixtures/README.md create mode 100644 evals/scorers.py create mode 100644 evals/solver.py create mode 100644 evals/tasks.py diff --git a/.gitignore b/.gitignore index 804a7d9..f2426ff 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,8 @@ koan/web/static/app/ frontend/node_modules/ frontend/dist/ __pycache__/ + +# Eval fixture snapshots are large binaries captured manually by Leon. +# Only README.md and task.md are committed; snapshot.tar.gz and memory/ are local. +evals/fixtures/*/snapshot.tar.gz +evals/fixtures/*/memory/ diff --git a/.koan/memory/0048-inspect-ai-uk-aisi-selected-as-koan-eval.md b/.koan/memory/0048-inspect-ai-uk-aisi-selected-as-koan-eval.md new file mode 100644 index 0000000..31342ba --- /dev/null +++ b/.koan/memory/0048-inspect-ai-uk-aisi-selected-as-koan-eval.md @@ -0,0 +1,8 @@ +--- +title: Inspect AI (UK AISI) selected as koan eval framework over deepeval +type: decision +created: '2026-04-17T12:06:09Z' +modified: '2026-04-17T12:06:09Z' +--- + +The koan eval framework selection covers the choice of evaluation tooling for the test suite overhaul. On 2026-04-17, Leon evaluated Inspect AI (UK AISI) and deepeval as candidate frameworks and selected Inspect AI. Leon's stated rationale: Inspect AI supports black-box subprocess testing as a first-class concept and provides four clean primitives -- Dataset (frozen fixture collection), Task (spec combining Dataset + Solver + Scorers), Solver (a function that transforms TaskState; koan runs as a subprocess here), and Scorer (grades output; LLM-as-judge supported natively via `model_graded_qa`). deepeval was rejected: it lacks the black-box subprocess model that koan's eval approach requires. The eval framework lives under `evals/` in the koan repository root. The four primitives map to koan as follows: Dataset = frozen koan project snapshots, Solver = subprocess runner against a frozen snapshot, Scorer = LLM-as-judge grading plan artifacts. diff --git a/.koan/memory/0049-eval-solver-answers-all-koan-interactive-gates.md b/.koan/memory/0049-eval-solver-answers-all-koan-interactive-gates.md new file mode 100644 index 0000000..3f942d1 --- /dev/null +++ b/.koan/memory/0049-eval-solver-answers-all-koan-interactive-gates.md @@ -0,0 +1,9 @@ +--- +title: Eval Solver answers all koan interactive gates with a fixed message, not a + surrogate LLM +type: decision +created: '2026-04-17T12:06:18Z' +modified: '2026-04-17T12:06:18Z' +--- + +The koan eval Solver's approach to interactive phase handling was established on 2026-04-17 during the test suite overhaul planning session. During a live koan workflow run, the orchestrator calls `koan_yield` (which blocks until a user message arrives via `POST /api/chat`) and `koan_ask_question` (which blocks until answers arrive via `POST /api/answer`). In the eval context these gates would block indefinitely. Leon decided that the Solver in `evals/solver.py` answers every interactive gate with a fixed message: "Please use your best judgment and pick whichever option you think is best." The orchestrator self-selects from available options. Leon rejected the alternative of a surrogate-user LLM -- a second LLM impersonating the user and answering questions on the fly -- because it would add LLM API cost and non-determinism to the eval without proportional signal gain at this early stage of the framework. diff --git a/.koan/memory/0050-eval-benchmark-fixtures-are-manual-git-snapshots.md b/.koan/memory/0050-eval-benchmark-fixtures-are-manual-git-snapshots.md new file mode 100644 index 0000000..39faeee --- /dev/null +++ b/.koan/memory/0050-eval-benchmark-fixtures-are-manual-git-snapshots.md @@ -0,0 +1,8 @@ +--- +title: Eval benchmark fixtures are manual git snapshots of koan at specific commits +type: decision +created: '2026-04-17T12:06:26Z' +modified: '2026-04-17T12:06:26Z' +--- + +The koan eval benchmark fixture format was established on 2026-04-17 during the test suite overhaul planning session. Leon decided that the reference benchmark corpus would be the koan project itself, captured manually at specific git commits. Each fixture directory under `evals/fixtures/` contains three artifacts: `task.md` (the task description as UTF-8 plain text), `snapshot.tar.gz` (a `git archive HEAD --format=tar.gz` of the target project at a specific commit), and `memory/` (a copy of `.koan/memory/` at that commit). Leon's rationale: using koan itself as the reference corpus captures real-world complexity; re-capture is simple (take a new snapshot at a new commit). Leon rejected two alternatives: fully synthetic task descriptions against a fictional codebase (risk: synthetic inputs may not expose real failure modes) and live session capture from actual koan runs (concern: fragile and labor-intensive to re-capture). diff --git a/.koan/memory/0052-eval-dataset-uses-full-run-fixtures-first-per.md b/.koan/memory/0052-eval-dataset-uses-full-run-fixtures-first-per.md new file mode 100644 index 0000000..32f9cc2 --- /dev/null +++ b/.koan/memory/0052-eval-dataset-uses-full-run-fixtures-first-per.md @@ -0,0 +1,8 @@ +--- +title: Eval dataset uses full-run fixtures first; per-phase checkpoint freeze deferred +type: decision +created: '2026-04-17T12:14:31Z' +modified: '2026-04-17T12:14:31Z' +--- + +The koan eval dataset granularity decision was made on 2026-04-17 during the test suite overhaul planning session. Leon decided that the first iteration of the `evals/` framework would use full-run fixtures only: each `Sample` in the Inspect AI Dataset corresponds to one complete koan workflow run from task description to final artifact set. Leon explicitly deferred per-phase and per-step fixture checkpointing. Leon's stated reason: mid-run resume requires the `--resume` flag on the orchestrator CLI, which Leon described as fragile and not ready to instrument. The design direction (per-phase and per-step freeze points) was documented in the plan at `plan.md` for a future iteration but excluded from the initial implementation scope. diff --git a/evals/__init__.py b/evals/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/evals/dataset.py b/evals/dataset.py new file mode 100644 index 0000000..f3ab4b2 --- /dev/null +++ b/evals/dataset.py @@ -0,0 +1,35 @@ +# evals/dataset.py +# Loads benchmark fixtures as an Inspect AI MemoryDataset. +# +# Each fixture directory must contain task.md (the task description). +# snapshot.tar.gz and memory/ are optional at load time (the solver checks +# for them at run time). Directories without task.md are skipped silently. + +from pathlib import Path + +# Dataset is an abstract protocol in inspect_ai 0.3+; MemoryDataset is the +# concrete in-memory implementation. +from inspect_ai.dataset import MemoryDataset, Sample + + +FIXTURES_DIR = Path(__file__).parent / "fixtures" + + +def load_dataset(fixtures_dir: Path = FIXTURES_DIR) -> MemoryDataset: + """Return an Inspect AI MemoryDataset from all fixture directories.""" + samples = [] + for fixture_dir in sorted(fixtures_dir.iterdir()): + task_file = fixture_dir / "task.md" + if not fixture_dir.is_dir() or not task_file.exists(): + continue + task_description = task_file.read_text(encoding="utf-8").strip() + samples.append(Sample( + input=task_description, + metadata={ + "fixture_dir": str(fixture_dir), + "fixture_name": fixture_dir.name, + "snapshot_path": str(fixture_dir / "snapshot.tar.gz"), + "memory_path": str(fixture_dir / "memory"), + }, + )) + return MemoryDataset(samples, name="koan-bench") diff --git a/evals/fixtures/README.md b/evals/fixtures/README.md new file mode 100644 index 0000000..129bdbe --- /dev/null +++ b/evals/fixtures/README.md @@ -0,0 +1,18 @@ +# Eval Fixtures + +Each subdirectory is one benchmark fixture. Structure: + + <fixture-name>/ + task.md -- task description (UTF-8 plain text) + snapshot.tar.gz -- git archive of the target project at a specific commit + memory/ -- copy of .koan/memory/ at that point + +`snapshot.tar.gz` and `memory/` are gitignored -- they are large and must be +captured manually by Leon. Only `task.md` is committed. + +To capture a new fixture from the koan project itself: + + mkdir -p evals/fixtures/<name>/memory + git archive HEAD --format=tar.gz -o evals/fixtures/<name>/snapshot.tar.gz + cp .koan/memory/*.md evals/fixtures/<name>/memory/ + echo "Your task description" > evals/fixtures/<name>/task.md diff --git a/evals/scorers.py b/evals/scorers.py new file mode 100644 index 0000000..c96f97c --- /dev/null +++ b/evals/scorers.py @@ -0,0 +1,83 @@ +# evals/scorers.py +# LLM-as-judge scorers for koan eval tasks. +# +# All three scorers use model_graded_qa, which takes a template string +# embedding the question/rubric. The "answer" field is the concatenated +# artifact content from state.output. PASS/FAIL is extracted from the +# model's response via the default grade_pattern ("PASS" / "FAIL"). + +from inspect_ai.scorer import Scorer, model_graded_qa + + +_PLAN_SPECIFICITY_TEMPLATE = """ +You are evaluating a software engineering plan produced by an AI orchestrator. + +Plan artifacts: +{answer} + +Rubric: +Grade whether the plan references specific file paths and function names from +the actual codebase rather than vague descriptions. + +Score PASS if the plan cites at least 5 specific file paths and at least 3 +specific function names that would be found in the codebase. +Score FAIL if the plan uses only vague descriptions, generic module names, +or fewer than the required specific references. + +Respond with exactly one word on the last line: PASS or FAIL. +""" + + +_QUESTION_QUALITY_TEMPLATE = """ +You are evaluating the intake questions posed by an AI orchestrator during +a software planning session. + +Session artifacts (look for any intake questions section): +{answer} + +Rubric: +Grade whether the orchestrator surfaced targeted, non-obvious questions. + +Score PASS if at least 2 questions address genuine ambiguities that are not +directly answerable from the task description alone -- for example: scope +boundaries, approach trade-offs, constraint verification, or integration risks. +Score FAIL if the questions are generic (e.g. "what is the deadline?"), redundant +with information already in the task, or derivable mechanically from the task text. + +Respond with exactly one word on the last line: PASS or FAIL. +""" + + +_MEMORY_RELEVANCE_TEMPLATE = """ +You are evaluating the memory entries captured by an AI orchestrator after +completing a software planning session. + +Memory / curation artifacts: +{answer} + +Rubric: +Grade whether the captured memory entries are substantive and task-specific. + +Score PASS if at least one entry has type=decision or type=lesson and a body +that is specific to this particular task (not a restatement of general +engineering boilerplate or a copy of an existing invariant). +Score FAIL if all entries are structural or procedural repetitions of +pre-existing invariants, or if no decision/lesson entries were captured. + +Respond with exactly one word on the last line: PASS or FAIL. +""" + + +def plan_specificity() -> Scorer: + """Grade whether the plan cites specific file paths and function names.""" + return model_graded_qa(template=_PLAN_SPECIFICITY_TEMPLATE) + + +def question_quality() -> Scorer: + """Grade whether the orchestrator asked targeted, non-obvious questions.""" + return model_graded_qa(template=_QUESTION_QUALITY_TEMPLATE) + + +def memory_relevance() -> Scorer: + """Grade whether captured memory entries are specific to the task.""" + return model_graded_qa(template=_MEMORY_RELEVANCE_TEMPLATE) diff --git a/evals/solver.py b/evals/solver.py new file mode 100644 index 0000000..2db5db6 --- /dev/null +++ b/evals/solver.py @@ -0,0 +1,263 @@ +# evals/solver.py +# Inspect AI Solver: runs koan as an in-process black-box. +# +# The solver starts koan's HTTP server via uvicorn, POSTs a start-run +# request, then monitors the /events SSE stream to detect interactive +# gates and respond with a fixed "use your best judgment" message. +# +# SSE protocol note: koan's SSE stream emits only "snapshot" and "patch" +# event types (RFC 6902 JSON Patch on the camelCase projection). The +# event names yield_started / questions_asked / workflow_completed are +# internal projection events that change projection state, not SSE event +# types. Gates are detected by inspecting patch operations on: +# /run/activeYield -> orchestrator blocked in koan_yield +# /run/focus -> orchestrator waiting for koan_ask_question answers +# /run/completion -> workflow finished +# +# Per-phase and per-step resume via --resume are explicitly deferred. +# Design direction: each phase boundary could be treated as a fixture +# checkpoint, using the projection version + run-state.json as the resume +# anchor. Not implemented until the full-run eval is proven stable. + +from __future__ import annotations + +import asyncio +import json +import socket +import tarfile +import tempfile +from pathlib import Path +from typing import Any + +import httpx +from inspect_ai.model import ModelOutput +from inspect_ai.solver import Solver, TaskState, solver + + +GATE_RESPONSE = ( + "Please use your best judgment and pick whichever option you think is best." +) +DEFAULT_TIMEOUT = 1800 + + +def _find_free_port() -> int: + """Bind to port 0 to get an OS-assigned free port, then release it.""" + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: + s.bind(("127.0.0.1", 0)) + return s.getsockname()[1] + + +async def _wait_for_server(base_url: str, poll_interval: float = 0.1, max_wait: float = 30.0) -> None: + """Poll /api/probe until the server responds or max_wait is exceeded.""" + deadline = asyncio.get_event_loop().time() + max_wait + async with httpx.AsyncClient() as client: + while asyncio.get_event_loop().time() < deadline: + try: + r = await client.get(f"{base_url}/api/probe", timeout=2.0) + if r.status_code < 500: + return + except httpx.TransportError: + pass + await asyncio.sleep(poll_interval) + raise TimeoutError(f"koan server at {base_url} did not start within {max_wait}s") + + +def _active_yield_from_patch(ops: list[dict]) -> bool: + """Return True if any patch op sets /run/activeYield to a non-null value.""" + for op in ops: + path = op.get("path", "") + if path == "/run/activeYield" or path.startswith("/run/activeYield/"): + if op.get("op") in ("add", "replace") and op.get("value") is not None: + return True + return False + + +def _question_focus_from_patch(ops: list[dict]) -> dict | None: + """Return the QuestionFocus value if a patch op sets /run/focus to type=question.""" + for op in ops: + path = op.get("path", "") + if path == "/run/focus" and op.get("op") in ("add", "replace"): + value = op.get("value") + if isinstance(value, dict) and value.get("type") == "question": + return value + return None + + +def _completion_from_patch(ops: list[dict]) -> bool: + """Return True if any patch op sets /run/completion to a non-null value.""" + for op in ops: + path = op.get("path", "") + if path == "/run/completion" or path.startswith("/run/completion/"): + if op.get("op") in ("add", "replace") and op.get("value") is not None: + return True + return False + + +def _active_yield_from_snapshot(state: dict) -> bool: + run = state.get("run") or {} + return run.get("activeYield") is not None + + +def _question_focus_from_snapshot(state: dict) -> dict | None: + run = state.get("run") or {} + focus = run.get("focus") + if isinstance(focus, dict) and focus.get("type") == "question": + return focus + return None + + +def _completion_from_snapshot(state: dict) -> bool: + run = state.get("run") or {} + return run.get("completion") is not None + + +async def _post_chat(base_url: str) -> None: + async with httpx.AsyncClient(timeout=30.0) as client: + await client.post(f"{base_url}/api/chat", json={"message": GATE_RESPONSE}) + + +async def _post_answer(base_url: str, token: str, questions: list) -> None: + answers = [ + { + "question_index": i, + "value": "other", + "free_text": GATE_RESPONSE, + } + for i in range(len(questions)) + ] + async with httpx.AsyncClient(timeout=30.0) as client: + await client.post( + f"{base_url}/api/answer", + json={"token": token, "answers": answers}, + ) + + +async def _sse_drive_loop(base_url: str) -> None: + """Subscribe to the SSE stream and respond to interactive gates until workflow completes.""" + # httpx stream() keeps the connection open; we parse SSE lines manually. + # Timeout=None on the outer client since the run may take 30+ minutes. + async with httpx.AsyncClient(timeout=httpx.Timeout(None)) as client: + async with client.stream("GET", f"{base_url}/events") as resp: + current_event: str | None = None + async for raw_line in resp.aiter_lines(): + line = raw_line.rstrip("\r") + if line.startswith("event:"): + current_event = line[6:].strip() + elif line.startswith("data:") and current_event is not None: + try: + data: Any = json.loads(line[5:].strip()) + except json.JSONDecodeError: + continue + + if current_event == "snapshot": + state = data.get("state", {}) + if _completion_from_snapshot(state): + return + if _active_yield_from_snapshot(state): + await _post_chat(base_url) + else: + focus = _question_focus_from_snapshot(state) + if focus is not None: + await _post_answer( + base_url, + focus.get("token", ""), + focus.get("questions", []), + ) + + elif current_event == "patch": + ops: list[dict] = data.get("patch", []) + if _completion_from_patch(ops): + return + if _active_yield_from_patch(ops): + await _post_chat(base_url) + else: + focus = _question_focus_from_patch(ops) + if focus is not None: + await _post_answer( + base_url, + focus.get("token", ""), + focus.get("questions", []), + ) + elif line == "": + current_event = None + + +def _collect_artifacts(run_dir: Path) -> dict[str, str]: + """Read all .md files from the run directory, keyed by filename.""" + result = {} + for p in sorted(run_dir.glob("*.md")): + try: + result[p.name] = p.read_text(encoding="utf-8") + except OSError: + pass + return result + + +@solver +def koan_solver(timeout: int = DEFAULT_TIMEOUT) -> Solver: + """Black-box koan eval solver. + + Starts koan's HTTP server in-process, submits the task description, + responds to all interactive gates with a fixed "use your best judgment" + message, and harvests the final run artifacts as the task output. + """ + + async def solve(state: TaskState, generate) -> TaskState: + import uvicorn + from koan.config import KoanConfig + from koan.state import AppState + from koan.web.app import create_app + + snapshot_path = Path(state.metadata["snapshot_path"]) + + with tempfile.TemporaryDirectory() as project_tmp: + # Extract the project snapshot so the orchestrator can inspect it. + # If no snapshot exists yet (no fixtures committed), skip silently. + if snapshot_path.exists(): + with tarfile.open(snapshot_path, "r:gz") as tar: + tar.extractall(project_tmp) + + app_state = AppState() + app_state.config = KoanConfig() + app = create_app(app_state) + + port = _find_free_port() + uv_config = uvicorn.Config( + app, + host="127.0.0.1", + port=port, + log_level="warning", + ) + server = uvicorn.Server(uv_config) + # Run uvicorn in a background asyncio task so we can drive it + # concurrently with the SSE loop. + server_task = asyncio.create_task(server.serve()) + + base_url = f"http://127.0.0.1:{port}" + await _wait_for_server(base_url) + + try: + async with httpx.AsyncClient(timeout=30.0) as client: + await client.post( + f"{base_url}/api/start-run", + json={"task": state.input, "profile": "balanced"}, + ) + + await asyncio.wait_for(_sse_drive_loop(base_url), timeout=timeout) + + except asyncio.TimeoutError: + pass # harvest whatever artifacts exist after timeout + finally: + server.should_exit = True + await server_task + + run_dir = app_state.run_dir + artifacts = _collect_artifacts(Path(run_dir)) if run_dir else {} + + content = "\n\n---\n\n".join(artifacts.values()) if artifacts else "" + # Use ModelOutput (TaskOutput does not exist in inspect_ai 0.3+). + state.output = ModelOutput.from_content("koan-solver", content) + state.metadata["artifacts"] = artifacts + return state + + return solve diff --git a/evals/tasks.py b/evals/tasks.py new file mode 100644 index 0000000..ad1a380 --- /dev/null +++ b/evals/tasks.py @@ -0,0 +1,18 @@ +# evals/tasks.py +# Inspect AI Task definitions for koan evals. + +from inspect_ai import Task, task + +from .dataset import load_dataset +from .scorers import memory_relevance, plan_specificity, question_quality +from .solver import koan_solver + + +@task +def koan_plan_eval() -> Task: + """Full-run koan plan workflow eval.""" + return Task( + dataset=load_dataset(), + solver=koan_solver(), + scorer=[plan_specificity(), question_quality(), memory_relevance()], + ) diff --git a/pyproject.toml b/pyproject.toml index cc40879..dc33681 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,7 @@ dependencies = [ koan = "koan.__main__:main" [dependency-groups] -dev = ["pytest>=8.0", "anyio>=4.0"] +dev = ["pytest>=8.0", "anyio>=4.0", "inspect-ai", "httpx"] [build-system] requires = ["hatchling"] diff --git a/uv.lock b/uv.lock index 51532bb..0e61259 100644 --- a/uv.lock +++ b/uv.lock @@ -7,6 +7,42 @@ resolution-markers = [ "python_full_version >= '3.14'", ] +[[package]] +name = "aioboto3" +version = "15.5.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "aiobotocore", extra = ["boto3"] }, + { name = "aiofiles" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/a2/01/92e9ab00f36e2899315f49eefcd5b4685fbb19016c7f19a9edf06da80bb0/aioboto3-15.5.0.tar.gz", hash = "sha256:ea8d8787d315594842fbfcf2c4dce3bac2ad61be275bc8584b2ce9a3402a6979", size = 255069, upload-time = "2025-10-30T13:37:16.122Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e5/3e/e8f5b665bca646d43b916763c901e00a07e40f7746c9128bdc912a089424/aioboto3-15.5.0-py3-none-any.whl", hash = "sha256:cc880c4d6a8481dd7e05da89f41c384dbd841454fc1998ae25ca9c39201437a6", size = 35913, upload-time = "2025-10-30T13:37:14.549Z" }, +] + +[[package]] +name = "aiobotocore" +version = "2.25.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "aiohttp" }, + { name = "aioitertools" }, + { name = "botocore" }, + { name = "jmespath" }, + { name = "multidict" }, + { name = "python-dateutil" }, + { name = "wrapt" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/62/94/2e4ec48cf1abb89971cb2612d86f979a6240520f0a659b53a43116d344dc/aiobotocore-2.25.1.tar.gz", hash = "sha256:ea9be739bfd7ece8864f072ec99bb9ed5c7e78ebb2b0b15f29781fbe02daedbc", size = 120560, upload-time = "2025-10-28T22:33:21.787Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/95/2a/d275ec4ce5cd0096665043995a7d76f5d0524853c76a3d04656de49f8808/aiobotocore-2.25.1-py3-none-any.whl", hash = "sha256:eb6daebe3cbef5b39a0bb2a97cffbe9c7cb46b2fcc399ad141f369f3c2134b1f", size = 86039, upload-time = "2025-10-28T22:33:19.949Z" }, +] + +[package.optional-dependencies] +boto3 = [ + { name = "boto3" }, +] + [[package]] name = "aiofile" version = "3.9.0" @@ -122,6 +158,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/62/29/2f8418269e46454a26171bfdd6a055d74febf32234e474930f2f60a17145/aiohttp-3.13.5-cp314-cp314t-win_amd64.whl", hash = "sha256:18a2f6c1182c51baa1d28d68fea51513cb2a76612f038853c0ad3c145423d3d9", size = 505441, upload-time = "2026-03-31T22:00:12.791Z" }, ] +[[package]] +name = "aioitertools" +version = "0.13.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/fd/3c/53c4a17a05fb9ea2313ee1777ff53f5e001aefd5cc85aa2f4c2d982e1e38/aioitertools-0.13.0.tar.gz", hash = "sha256:620bd241acc0bbb9ec819f1ab215866871b4bbd1f73836a55f799200ee86950c", size = 19322, upload-time = "2025-11-06T22:17:07.609Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/10/a1/510b0a7fadc6f43a6ce50152e69dbd86415240835868bb0bd9b5b88b1e06/aioitertools-0.13.0-py3-none-any.whl", hash = "sha256:0be0292b856f08dfac90e31f4739432f4cb6d7520ab9eb73e143f4f2fa5259be", size = 24182, upload-time = "2025-11-06T22:17:06.502Z" }, +] + [[package]] name = "aiolimiter" version = "1.2.1" @@ -205,6 +250,47 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/71/cc/18245721fa7747065ab478316c7fea7c74777d07f37ae60db2e84f8172e8/beartype-0.22.9-py3-none-any.whl", hash = "sha256:d16c9bbc61ea14637596c5f6fbff2ee99cbe3573e46a716401734ef50c3060c2", size = 1333658, upload-time = "2025-12-13T06:50:28.266Z" }, ] +[[package]] +name = "beautifulsoup4" +version = "4.14.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "soupsieve" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/c3/b0/1c6a16426d389813b48d95e26898aff79abbde42ad353958ad95cc8c9b21/beautifulsoup4-4.14.3.tar.gz", hash = "sha256:6292b1c5186d356bba669ef9f7f051757099565ad9ada5dd630bd9de5fa7fb86", size = 627737, upload-time = "2025-11-30T15:08:26.084Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1a/39/47f9197bdd44df24d67ac8893641e16f386c984a0619ef2ee4c51fbbc019/beautifulsoup4-4.14.3-py3-none-any.whl", hash = "sha256:0918bfe44902e6ad8d57732ba310582e98da931428d231a5ecb9e7c703a735bb", size = 107721, upload-time = "2025-11-30T15:08:24.087Z" }, +] + +[[package]] +name = "boto3" +version = "1.40.61" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "botocore" }, + { name = "jmespath" }, + { name = "s3transfer" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/ed/f9/6ef8feb52c3cce5ec3967a535a6114b57ac7949fd166b0f3090c2b06e4e5/boto3-1.40.61.tar.gz", hash = "sha256:d6c56277251adf6c2bdd25249feae625abe4966831676689ff23b4694dea5b12", size = 111535, upload-time = "2025-10-28T19:26:57.247Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/61/24/3bf865b07d15fea85b63504856e137029b6acbc73762496064219cdb265d/boto3-1.40.61-py3-none-any.whl", hash = "sha256:6b9c57b2a922b5d8c17766e29ed792586a818098efe84def27c8f582b33f898c", size = 139321, upload-time = "2025-10-28T19:26:55.007Z" }, +] + +[[package]] +name = "botocore" +version = "1.40.61" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "jmespath" }, + { name = "python-dateutil" }, + { name = "urllib3" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/28/a3/81d3a47c2dbfd76f185d3b894f2ad01a75096c006a2dd91f237dca182188/botocore-1.40.61.tar.gz", hash = "sha256:a2487ad69b090f9cccd64cf07c7021cd80ee9c0655ad974f87045b02f3ef52cd", size = 14393956, upload-time = "2025-10-28T19:26:46.108Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/38/c5/f6ce561004db45f0b847c2cd9b19c67c6bf348a82018a48cb718be6b58b0/botocore-1.40.61-py3-none-any.whl", hash = "sha256:17ebae412692fd4824f99cde0f08d50126dc97954008e5ba2b522eb049238aa7", size = 14055973, upload-time = "2025-10-28T19:26:42.15Z" }, +] + [[package]] name = "cachetools" version = "7.0.5" @@ -376,14 +462,14 @@ wheels = [ [[package]] name = "click" -version = "8.3.1" +version = "8.2.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "colorama", marker = "sys_platform == 'win32'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz", hash = "sha256:12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a", size = 295065, upload-time = "2025-11-15T20:45:42.706Z" } +sdist = { url = "https://files.pythonhosted.org/packages/60/6c/8ca2efa64cf75a977a0d7fac081354553ebe483345c734fb6b6515d96bbc/click-8.2.1.tar.gz", hash = "sha256:27c491cc05d968d271d5a1db13e3b5a184636d9d930f148c50b038f0d0646202", size = 286342, upload-time = "2025-05-20T23:19:49.832Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/98/78/01c019cdb5d6498122777c1a43056ebb3ebfeef2076d9d026bfe15583b2b/click-8.3.1-py3-none-any.whl", hash = "sha256:981153a64e25f12d547d3426c367a4857371575ee7ad18df2a6183ab0545b2a6", size = 108274, upload-time = "2025-11-15T20:45:41.139Z" }, + { url = "https://files.pythonhosted.org/packages/85/32/10bb5764d90a8eee674e9dc6f4db6a0ab47c8c4d0d83c27f7c39ac415a4d/click-8.2.1-py3-none-any.whl", hash = "sha256:61a3265b914e850b85317d0b3109c7f8cd35a670f963866005d6ef1d5175a12b", size = 102215, upload-time = "2025-05-20T23:19:47.796Z" }, ] [[package]] @@ -463,6 +549,27 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/8a/0b/2261922126b2e50c601fe22d7ff5194e0a4d50e654836260c0665e24d862/cyclopts-4.10.1-py3-none-any.whl", hash = "sha256:35f37257139380a386d9fe4475e1e7c87ca7795765ef4f31abba579fcfcb6ecd", size = 204331, upload-time = "2026-03-23T14:43:02.625Z" }, ] +[[package]] +name = "debugpy" +version = "1.8.20" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/e0/b7/cd8080344452e4874aae67c40d8940e2b4d47b01601a8fd9f44786c757c7/debugpy-1.8.20.tar.gz", hash = "sha256:55bc8701714969f1ab89a6d5f2f3d40c36f91b2cbe2f65d98bf8196f6a6a2c33", size = 1645207, upload-time = "2026-01-29T23:03:28.199Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/14/57/7f34f4736bfb6e00f2e4c96351b07805d83c9a7b33d28580ae01374430f7/debugpy-1.8.20-cp312-cp312-macosx_15_0_universal2.whl", hash = "sha256:4ae3135e2089905a916909ef31922b2d733d756f66d87345b3e5e52b7a55f13d", size = 2550686, upload-time = "2026-01-29T23:03:42.023Z" }, + { url = "https://files.pythonhosted.org/packages/ab/78/b193a3975ca34458f6f0e24aaf5c3e3da72f5401f6054c0dfd004b41726f/debugpy-1.8.20-cp312-cp312-manylinux_2_34_x86_64.whl", hash = "sha256:88f47850a4284b88bd2bfee1f26132147d5d504e4e86c22485dfa44b97e19b4b", size = 4310588, upload-time = "2026-01-29T23:03:43.314Z" }, + { url = "https://files.pythonhosted.org/packages/c1/55/f14deb95eaf4f30f07ef4b90a8590fc05d9e04df85ee379712f6fb6736d7/debugpy-1.8.20-cp312-cp312-win32.whl", hash = "sha256:4057ac68f892064e5f98209ab582abfee3b543fb55d2e87610ddc133a954d390", size = 5331372, upload-time = "2026-01-29T23:03:45.526Z" }, + { url = "https://files.pythonhosted.org/packages/a1/39/2bef246368bd42f9bd7cba99844542b74b84dacbdbea0833e610f384fee8/debugpy-1.8.20-cp312-cp312-win_amd64.whl", hash = "sha256:a1a8f851e7cf171330679ef6997e9c579ef6dd33c9098458bd9986a0f4ca52e3", size = 5372835, upload-time = "2026-01-29T23:03:47.245Z" }, + { url = "https://files.pythonhosted.org/packages/15/e2/fc500524cc6f104a9d049abc85a0a8b3f0d14c0a39b9c140511c61e5b40b/debugpy-1.8.20-cp313-cp313-macosx_15_0_universal2.whl", hash = "sha256:5dff4bb27027821fdfcc9e8f87309a28988231165147c31730128b1c983e282a", size = 2539560, upload-time = "2026-01-29T23:03:48.738Z" }, + { url = "https://files.pythonhosted.org/packages/90/83/fb33dcea789ed6018f8da20c5a9bc9d82adc65c0c990faed43f7c955da46/debugpy-1.8.20-cp313-cp313-manylinux_2_34_x86_64.whl", hash = "sha256:84562982dd7cf5ebebfdea667ca20a064e096099997b175fe204e86817f64eaf", size = 4293272, upload-time = "2026-01-29T23:03:50.169Z" }, + { url = "https://files.pythonhosted.org/packages/a6/25/b1e4a01bfb824d79a6af24b99ef291e24189080c93576dfd9b1a2815cd0f/debugpy-1.8.20-cp313-cp313-win32.whl", hash = "sha256:da11dea6447b2cadbf8ce2bec59ecea87cc18d2c574980f643f2d2dfe4862393", size = 5331208, upload-time = "2026-01-29T23:03:51.547Z" }, + { url = "https://files.pythonhosted.org/packages/13/f7/a0b368ce54ffff9e9028c098bd2d28cfc5b54f9f6c186929083d4c60ba58/debugpy-1.8.20-cp313-cp313-win_amd64.whl", hash = "sha256:eb506e45943cab2efb7c6eafdd65b842f3ae779f020c82221f55aca9de135ed7", size = 5372930, upload-time = "2026-01-29T23:03:53.585Z" }, + { url = "https://files.pythonhosted.org/packages/33/2e/f6cb9a8a13f5058f0a20fe09711a7b726232cd5a78c6a7c05b2ec726cff9/debugpy-1.8.20-cp314-cp314-macosx_15_0_universal2.whl", hash = "sha256:9c74df62fc064cd5e5eaca1353a3ef5a5d50da5eb8058fcef63106f7bebe6173", size = 2538066, upload-time = "2026-01-29T23:03:54.999Z" }, + { url = "https://files.pythonhosted.org/packages/c5/56/6ddca50b53624e1ca3ce1d1e49ff22db46c47ea5fb4c0cc5c9b90a616364/debugpy-1.8.20-cp314-cp314-manylinux_2_34_x86_64.whl", hash = "sha256:077a7447589ee9bc1ff0cdf443566d0ecf540ac8aa7333b775ebcb8ce9f4ecad", size = 4269425, upload-time = "2026-01-29T23:03:56.518Z" }, + { url = "https://files.pythonhosted.org/packages/c5/d9/d64199c14a0d4c476df46c82470a3ce45c8d183a6796cfb5e66533b3663c/debugpy-1.8.20-cp314-cp314-win32.whl", hash = "sha256:352036a99dd35053b37b7803f748efc456076f929c6a895556932eaf2d23b07f", size = 5331407, upload-time = "2026-01-29T23:03:58.481Z" }, + { url = "https://files.pythonhosted.org/packages/e0/d9/1f07395b54413432624d61524dfd98c1a7c7827d2abfdb8829ac92638205/debugpy-1.8.20-cp314-cp314-win_amd64.whl", hash = "sha256:a98eec61135465b062846112e5ecf2eebb855305acc1dfbae43b72903b8ab5be", size = 5372521, upload-time = "2026-01-29T23:03:59.864Z" }, + { url = "https://files.pythonhosted.org/packages/e0/c3/7f67dea8ccf8fdcb9c99033bbe3e90b9e7395415843accb81428c441be2d/debugpy-1.8.20-py2.py3-none-any.whl", hash = "sha256:5be9bed9ae3be00665a06acaa48f8329d2b9632f15fd09f6a9a8c8d9907e54d7", size = 5337658, upload-time = "2026-01-29T23:04:17.404Z" }, +] + [[package]] name = "deprecation" version = "2.1.0" @@ -680,11 +787,11 @@ wheels = [ [[package]] name = "fsspec" -version = "2026.3.0" +version = "2025.9.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/e1/cf/b50ddf667c15276a9ab15a70ef5f257564de271957933ffea49d2cdbcdfb/fsspec-2026.3.0.tar.gz", hash = "sha256:1ee6a0e28677557f8c2f994e3eea77db6392b4de9cd1f5d7a9e87a0ae9d01b41", size = 313547, upload-time = "2026-03-27T19:11:14.892Z" } +sdist = { url = "https://files.pythonhosted.org/packages/de/e0/bab50af11c2d75c9c4a2a26a5254573c0bd97cea152254401510950486fa/fsspec-2025.9.0.tar.gz", hash = "sha256:19fd429483d25d28b65ec68f9f4adc16c17ea2c7c7bf54ec61360d478fb19c19", size = 304847, upload-time = "2025-09-02T19:10:49.215Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/d5/1f/5f4a3cd9e4440e9d9bc78ad0a91a1c8d46b4d429d5239ebe6793c9fe5c41/fsspec-2026.3.0-py3-none-any.whl", hash = "sha256:d2ceafaad1b3457968ed14efa28798162f1638dbb5d2a6868a2db002a5ee39a4", size = 202595, upload-time = "2026-03-27T19:11:13.595Z" }, + { url = "https://files.pythonhosted.org/packages/47/71/70db47e4f6ce3e5c37a607355f80da8860a33226be640226ac52cb05ef2e/fsspec-2025.9.0-py3-none-any.whl", hash = "sha256:530dc2a2af60a414a832059574df4a6e10cce927f6f4a78209390fe38955cfb7", size = 199289, upload-time = "2025-09-02T19:10:47.708Z" }, ] [[package]] @@ -871,6 +978,69 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" }, ] +[[package]] +name = "ijson" +version = "3.5.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/f4/57/60d1a6a512f2f0508d0bc8b4f1cc5616fd3196619b66bd6a01f9155a1292/ijson-3.5.0.tar.gz", hash = "sha256:94688760720e3f5212731b3cb8d30267f9a045fb38fb3870254e7b9504246f31", size = 68658, upload-time = "2026-02-24T03:58:30.974Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/aa/17/9c63c7688025f3a8c47ea717b8306649c8c7244e49e20a2be4e3515dc75c/ijson-3.5.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:1ebefbe149a6106cc848a3eaf536af51a9b5ccc9082de801389f152dba6ab755", size = 88536, upload-time = "2026-02-24T03:57:06.809Z" }, + { url = "https://files.pythonhosted.org/packages/6f/dd/e15c2400244c117b06585452ebc63ae254f5a6964f712306afd1422daae0/ijson-3.5.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:19e30d9f00f82e64de689c0b8651b9cfed879c184b139d7e1ea5030cec401c21", size = 60499, upload-time = "2026-02-24T03:57:09.155Z" }, + { url = "https://files.pythonhosted.org/packages/77/a9/bf4fe3538a0c965f16b406f180a06105b875da83f0743e36246be64ef550/ijson-3.5.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:a04a33ee78a6f27b9b8528c1ca3c207b1df3b8b867a4cf2fcc4109986f35c227", size = 60330, upload-time = "2026-02-24T03:57:10.574Z" }, + { url = "https://files.pythonhosted.org/packages/31/76/6f91bdb019dd978fce1bc5ea1cd620cfc096d258126c91db2c03a20a7f34/ijson-3.5.0-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:7d48dc2984af02eb3c56edfb3f13b3f62f2f3e4fe36f058c8cfc75d93adf4fed", size = 138977, upload-time = "2026-02-24T03:57:11.932Z" }, + { url = "https://files.pythonhosted.org/packages/11/be/bbc983059e48a54b0121ee60042979faed7674490bbe7b2c41560db3f436/ijson-3.5.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f1e73a44844d9adbca9cf2c4132cd875933e83f3d4b23881fcaf82be83644c7d", size = 149785, upload-time = "2026-02-24T03:57:13.255Z" }, + { url = "https://files.pythonhosted.org/packages/6d/81/2fee58f9024a3449aee83edfa7167fb5ccd7e1af2557300e28531bb68e16/ijson-3.5.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7389a56b8562a19948bdf1d7bae3a2edc8c7f86fb59834dcb1c4c722818e645a", size = 149729, upload-time = "2026-02-24T03:57:14.191Z" }, + { url = "https://files.pythonhosted.org/packages/c7/56/f1706761fcc096c9d414b3dcd000b1e6e5c24364c21cfba429837f98ee8d/ijson-3.5.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:3176f23f8ebec83f374ed0c3b4e5a0c4db7ede54c005864efebbed46da123608", size = 150697, upload-time = "2026-02-24T03:57:15.855Z" }, + { url = "https://files.pythonhosted.org/packages/d9/6e/ee0d9c875a0193b632b3e9ccd1b22a50685fb510256ad57ba483b6529f77/ijson-3.5.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:6babd88e508630c6ef86c9bebaaf13bb2fb8ec1d8f8868773a03c20253f599bc", size = 142873, upload-time = "2026-02-24T03:57:16.831Z" }, + { url = "https://files.pythonhosted.org/packages/d2/bf/f9d4399d0e6e3fd615035290a71e97c843f17f329b43638c0a01cf112d73/ijson-3.5.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:dc1b3836b174b6db2fa8319f1926fb5445abd195dc963368092103f8579cb8ed", size = 151583, upload-time = "2026-02-24T03:57:17.757Z" }, + { url = "https://files.pythonhosted.org/packages/b2/71/a7254a065933c0e2ffd3586f46187d84830d3d7b6f41cfa5901820a4f87d/ijson-3.5.0-cp312-cp312-win32.whl", hash = "sha256:6673de9395fb9893c1c79a43becd8c8fbee0a250be6ea324bfd1487bb5e9ee4c", size = 53079, upload-time = "2026-02-24T03:57:18.703Z" }, + { url = "https://files.pythonhosted.org/packages/8f/7b/2edca79b359fc9f95d774616867a03ecccdf333797baf5b3eea79733918c/ijson-3.5.0-cp312-cp312-win_amd64.whl", hash = "sha256:f4f7fabd653459dcb004175235f310435959b1bb5dfa8878578391c6cc9ad944", size = 55500, upload-time = "2026-02-24T03:57:20.428Z" }, + { url = "https://files.pythonhosted.org/packages/a2/71/d67e764a712c3590627480643a3b51efcc3afa4ef3cb54ee4c989073c97e/ijson-3.5.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:e9cedc10e40dd6023c351ed8bfc7dcfce58204f15c321c3c1546b9c7b12562a4", size = 88544, upload-time = "2026-02-24T03:57:21.293Z" }, + { url = "https://files.pythonhosted.org/packages/1a/39/f1c299371686153fa3cf5c0736b96247a87a1bee1b7145e6d21f359c505a/ijson-3.5.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:3647649f782ee06c97490b43680371186651f3f69bebe64c6083ee7615d185e5", size = 60495, upload-time = "2026-02-24T03:57:22.501Z" }, + { url = "https://files.pythonhosted.org/packages/16/94/b1438e204d75e01541bebe3e668fe3e68612d210e9931ae1611062dd0a56/ijson-3.5.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:90e74be1dce05fce73451c62d1118671f78f47c9f6be3991c82b91063bf01fc9", size = 60325, upload-time = "2026-02-24T03:57:23.332Z" }, + { url = "https://files.pythonhosted.org/packages/30/e2/4aa9c116fa86cc8b0f574f3c3a47409edc1cd4face05d0e589a5a176b05d/ijson-3.5.0-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:78e9ad73e7be2dd80627504bd5cbf512348c55ce2c06e362ed7683b5220e8568", size = 138774, upload-time = "2026-02-24T03:57:24.683Z" }, + { url = "https://files.pythonhosted.org/packages/d2/d2/738b88752a70c3be1505faa4dcd7110668c2712e582a6a36488ed1e295d4/ijson-3.5.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9577449313cc94be89a4fe4b3e716c65f09cc19636d5a6b2861c4e80dddebd58", size = 149820, upload-time = "2026-02-24T03:57:26.062Z" }, + { url = "https://files.pythonhosted.org/packages/ed/df/0b3ab9f393ca8f72ea03bc896ba9fdc987e90ae08cdb51c32a4ee0c14d5e/ijson-3.5.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:3e4c1178fb50aff5f5701a30a5152ead82a14e189ce0f6102fa1b5f10b2f54ff", size = 149747, upload-time = "2026-02-24T03:57:27.308Z" }, + { url = "https://files.pythonhosted.org/packages/cc/a3/b0037119f75131b78cb00acc2657b1a9d0435475f1f2c5f8f5a170b66b9c/ijson-3.5.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:0eb402ab026ffb37a918d75af2b7260fe6cfbce13232cc83728a714dd30bd81d", size = 151027, upload-time = "2026-02-24T03:57:28.522Z" }, + { url = "https://files.pythonhosted.org/packages/22/a0/cb344de1862bf09d8f769c9d25c944078c87dd59a1b496feec5ad96309a4/ijson-3.5.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:5b08ee08355f9f729612a8eb9bf69cc14f9310c3b2a487c6f1c3c65d85216ec4", size = 142996, upload-time = "2026-02-24T03:57:29.774Z" }, + { url = "https://files.pythonhosted.org/packages/ca/32/a8ffd67182e02ea61f70f62daf43ded4fa8a830a2520a851d2782460aba8/ijson-3.5.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:bda62b6d48442903e7bf56152108afb7f0f1293c2b9bef2f2c369defea76ab18", size = 152068, upload-time = "2026-02-24T03:57:30.969Z" }, + { url = "https://files.pythonhosted.org/packages/3c/d1/3578df8e75d446aab0ae92e27f641341f586b85e1988536adebc65300cb4/ijson-3.5.0-cp313-cp313-win32.whl", hash = "sha256:8d073d9b13574cfa11083cc7267c238b7a6ed563c2661e79192da4a25f09c82c", size = 53065, upload-time = "2026-02-24T03:57:31.93Z" }, + { url = "https://files.pythonhosted.org/packages/fb/a2/f7cdaf5896710da3e69e982e44f015a83d168aa0f3a89b6f074b5426779d/ijson-3.5.0-cp313-cp313-win_amd64.whl", hash = "sha256:2419f9e32e0968a876b04d8f26aeac042abd16f582810b576936bbc4c6015069", size = 55499, upload-time = "2026-02-24T03:57:32.773Z" }, + { url = "https://files.pythonhosted.org/packages/42/65/13e2492d17e19a2084523e18716dc2809159f2287fd2700c735f311e76c4/ijson-3.5.0-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:4d4b0cd676b8c842f7648c1a783448fac5cd3b98289abd83711b3e275e143524", size = 93019, upload-time = "2026-02-24T03:57:33.976Z" }, + { url = "https://files.pythonhosted.org/packages/33/92/483fc97ece0c3f1cecabf48f6a7a36e89d19369eec462faaeaa34c788992/ijson-3.5.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:252dec3680a48bb82d475e36b4ae1b3a9d7eb690b951bb98a76c5fe519e30188", size = 62714, upload-time = "2026-02-24T03:57:34.819Z" }, + { url = "https://files.pythonhosted.org/packages/4b/88/793fe020a0fe9d9eed4c285cf4a5cfdb0a935708b3bde0d72f35c794b513/ijson-3.5.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:aa1b5dca97d323931fde2501172337384c958914d81a9dac7f00f0d4bfc76bc7", size = 62460, upload-time = "2026-02-24T03:57:35.874Z" }, + { url = "https://files.pythonhosted.org/packages/51/69/f1a2690aa8d4df1f4e262b385e65a933ffdc250b091531bac9a449c19e16/ijson-3.5.0-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:7a5ec7fd86d606094bba6f6f8f87494897102fa4584ef653f3005c51a784c320", size = 199273, upload-time = "2026-02-24T03:57:37.07Z" }, + { url = "https://files.pythonhosted.org/packages/ea/a2/f1346d5299e79b988ab472dc773d5381ec2d57c23cb2f1af3ede4a810e62/ijson-3.5.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:009f41443e1521847701c6d87fa3923c0b1961be3c7e7de90947c8cb92ea7c44", size = 216884, upload-time = "2026-02-24T03:57:38.346Z" }, + { url = "https://files.pythonhosted.org/packages/28/3c/8b637e869be87799e6c2c3c275a30a546f086b1aed77e2b7f11512168c5a/ijson-3.5.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e4c3651d1f9fe2839a93fdf8fd1d5ca3a54975349894249f3b1b572bcc4bd577", size = 207306, upload-time = "2026-02-24T03:57:39.718Z" }, + { url = "https://files.pythonhosted.org/packages/7f/7c/18b1c1df6951ca056782d7580ec40cea4ff9a27a0947d92640d1cc8c4ae3/ijson-3.5.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:945b7abcfcfeae2cde17d8d900870f03536494245dda7ad4f8d056faa303256c", size = 211364, upload-time = "2026-02-24T03:57:40.953Z" }, + { url = "https://files.pythonhosted.org/packages/f3/55/e795812e82851574a9dba8a53fde045378f531ef14110c6fb55dbd23b443/ijson-3.5.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:0574b0a841ff97495c13e9d7260fbf3d85358b061f540c52a123db9dbbaa2ed6", size = 200608, upload-time = "2026-02-24T03:57:42.272Z" }, + { url = "https://files.pythonhosted.org/packages/5c/cd/013c85b4749b57a4cb4c2670014d1b32b8db4ab1a7be92ea7aeb5d7fe7b5/ijson-3.5.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:f969ffb2b89c5cdf686652d7fb66252bc72126fa54d416317411497276056a18", size = 205127, upload-time = "2026-02-24T03:57:43.286Z" }, + { url = "https://files.pythonhosted.org/packages/0e/7c/faf643733e3ab677f180018f6a855c4ef70b7c46540987424c563c959e42/ijson-3.5.0-cp313-cp313t-win32.whl", hash = "sha256:59d3f9f46deed1332ad669518b8099920512a78bda64c1f021fcd2aff2b36693", size = 55282, upload-time = "2026-02-24T03:57:44.353Z" }, + { url = "https://files.pythonhosted.org/packages/69/22/94ddb47c24b491377aca06cd8fc9202cad6ab50619842457d2beefde21ea/ijson-3.5.0-cp313-cp313t-win_amd64.whl", hash = "sha256:5c2839fa233746d8aad3b8cd2354e441613f5df66d721d59da4a09394bd1db2b", size = 58016, upload-time = "2026-02-24T03:57:45.237Z" }, + { url = "https://files.pythonhosted.org/packages/7a/93/0868efe753dc1df80cc405cf0c1f2527a6991643607c741bff8dcb899b3b/ijson-3.5.0-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:25a5a6b2045c90bb83061df27cfa43572afa43ba9408611d7bfe237c20a731a9", size = 89094, upload-time = "2026-02-24T03:57:46.115Z" }, + { url = "https://files.pythonhosted.org/packages/24/94/fd5a832a0df52ef5e4e740f14ac8640725d61034a1b0c561e8b5fb424706/ijson-3.5.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:8976c54c0b864bc82b951bae06567566ac77ef63b90a773a69cd73aab47f4f4f", size = 60715, upload-time = "2026-02-24T03:57:47.552Z" }, + { url = "https://files.pythonhosted.org/packages/70/79/1b9a90af5732491f9eec751ee211b86b11011e1158c555c06576d52c3919/ijson-3.5.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:859eb2038f7f1b0664df4241957694cc35e6295992d71c98659b22c69b3cbc10", size = 60638, upload-time = "2026-02-24T03:57:48.428Z" }, + { url = "https://files.pythonhosted.org/packages/23/6f/2c551ea980fe56f68710a8d5389cfbd015fc45aaafd17c3c52c346db6aa1/ijson-3.5.0-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:c911aa02991c7c0d3639b6619b93a93210ff1e7f58bf7225d613abea10adc78e", size = 140667, upload-time = "2026-02-24T03:57:49.314Z" }, + { url = "https://files.pythonhosted.org/packages/25/0e/27b887879ba6a5bc29766e3c5af4942638c952220fd63e1e442674f7883a/ijson-3.5.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:903cbdc350173605220edc19796fbea9b2203c8b3951fb7335abfa8ed37afda8", size = 149850, upload-time = "2026-02-24T03:57:50.329Z" }, + { url = "https://files.pythonhosted.org/packages/da/1e/23e10e1bc04bf31193b21e2960dce14b17dbd5d0c62204e8401c59d62c08/ijson-3.5.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a4549d96ded5b8efa71639b2160235415f6bdb8c83367615e2dbabcb72755c33", size = 149206, upload-time = "2026-02-24T03:57:51.261Z" }, + { url = "https://files.pythonhosted.org/packages/8e/90/e552f6495063b235cf7fa2c592f6597c057077195e517b842a0374fd470c/ijson-3.5.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:6b2dcf6349e6042d83f3f8c39ce84823cf7577eba25bac5aae5e39bbbbbe9c1c", size = 150438, upload-time = "2026-02-24T03:57:52.198Z" }, + { url = "https://files.pythonhosted.org/packages/5c/18/45bf8f297c41b42a1c231d261141097babd953d2c28a07be57ae4c3a1a02/ijson-3.5.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:e44af39e6f8a17e5627dcd89715d8279bf3474153ff99aae031a936e5c5572e5", size = 144369, upload-time = "2026-02-24T03:57:53.22Z" }, + { url = "https://files.pythonhosted.org/packages/9b/3a/deb9772bb2c0cead7ad64f00c3598eec9072bdf511818e70e2c512eeabbe/ijson-3.5.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:9260332304b7e7828db56d43f08fc970a3ab741bf84ff10189361ea1b60c395b", size = 151352, upload-time = "2026-02-24T03:57:54.375Z" }, + { url = "https://files.pythonhosted.org/packages/e4/51/67f4d80cd58ad7eab0cd1af5fe28b961886338956b2f88c0979e21914346/ijson-3.5.0-cp314-cp314-win32.whl", hash = "sha256:63bc8121bb422f6969ced270173a3fa692c29d4ae30c860a2309941abd81012a", size = 53610, upload-time = "2026-02-24T03:57:55.655Z" }, + { url = "https://files.pythonhosted.org/packages/70/d3/263672ea22983ba3940f1534316dbc9200952c1c2a2332d7a664e4eaa7ae/ijson-3.5.0-cp314-cp314-win_amd64.whl", hash = "sha256:01b6dad72b7b7df225ef970d334556dfad46c696a2c6767fb5d9ed8889728bca", size = 56301, upload-time = "2026-02-24T03:57:56.584Z" }, + { url = "https://files.pythonhosted.org/packages/9f/d9/86f7fac35e0835faa188085ae0579e813493d5261ce056484015ad533445/ijson-3.5.0-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:2ea4b676ec98e374c1df400a47929859e4fa1239274339024df4716e802aa7e4", size = 93069, upload-time = "2026-02-24T03:57:57.849Z" }, + { url = "https://files.pythonhosted.org/packages/33/d2/e7366ed9c6e60228d35baf4404bac01a126e7775ea8ce57f560125ed190a/ijson-3.5.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:014586eec043e23c80be9a923c56c3a0920a0f1f7d17478ce7bc20ba443968ef", size = 62767, upload-time = "2026-02-24T03:57:58.758Z" }, + { url = "https://files.pythonhosted.org/packages/35/8b/3e703e8cc4b3ada79f13b28070b51d9550c578f76d1968657905857b2ddd/ijson-3.5.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:d5b8b886b0248652d437f66e7c5ac318bbdcb2c7137a7e5327a68ca00b286f5f", size = 62467, upload-time = "2026-02-24T03:58:00.261Z" }, + { url = "https://files.pythonhosted.org/packages/21/42/0c91af32c1ee8a957fdac2e051b5780756d05fd34e4b60d94a08d51bac1d/ijson-3.5.0-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:498fd46ae2349297e43acf97cdc421e711dbd7198418677259393d2acdc62d78", size = 200447, upload-time = "2026-02-24T03:58:01.591Z" }, + { url = "https://files.pythonhosted.org/packages/f9/80/796ea0e391b7e2d45c5b1b451734bba03f81c2984cf955ea5eaa6c4920ad/ijson-3.5.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:22a51b4f9b81f12793731cf226266d1de2112c3c04ba4a04117ad4e466897e05", size = 217820, upload-time = "2026-02-24T03:58:02.598Z" }, + { url = "https://files.pythonhosted.org/packages/38/14/52b6613fdda4078c62eb5b4fe3efc724ddc55a4ad524c93de51830107aa3/ijson-3.5.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9636c710dc4ac4a281baa266a64f323b4cc165cec26836af702c44328b59a515", size = 208310, upload-time = "2026-02-24T03:58:04.759Z" }, + { url = "https://files.pythonhosted.org/packages/6a/ad/8b3105a78774fd4a65e534a21d975ef3a77e189489fe3029ebcaeba5e243/ijson-3.5.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:f7168a39e8211107666d71b25693fd1b2bac0b33735ef744114c403c6cac21e1", size = 211843, upload-time = "2026-02-24T03:58:05.836Z" }, + { url = "https://files.pythonhosted.org/packages/36/ab/a2739f6072d6e1160581bc3ed32da614c8cced023dcd519d9c5fa66e0425/ijson-3.5.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:8696454245415bc617ab03b0dc3ae4c86987df5dc6a90bad378fe72c5409d89e", size = 200906, upload-time = "2026-02-24T03:58:07.788Z" }, + { url = "https://files.pythonhosted.org/packages/6d/5e/e06c2de3c3d4a9cfb655c1ad08a68fb72838d271072cdd3196576ac4431a/ijson-3.5.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:c21bfb61f71f191565885bf1bc29e0a186292d866b4880637b833848360bdc1b", size = 205495, upload-time = "2026-02-24T03:58:09.163Z" }, + { url = "https://files.pythonhosted.org/packages/7c/11/778201eb2e202ddd76b36b0fb29bf3d8e3c167389d8aa883c62524e49f47/ijson-3.5.0-cp314-cp314t-win32.whl", hash = "sha256:a2619460d6795b70d0155e5bf016200ac8a63ab5397aa33588bb02b6c21759e6", size = 56280, upload-time = "2026-02-24T03:58:10.116Z" }, + { url = "https://files.pythonhosted.org/packages/23/28/96711503245339084c8086b892c47415895eba49782d6cc52d9f4ee50301/ijson-3.5.0-cp314-cp314t-win_amd64.whl", hash = "sha256:4f24b78d4ef028d17eb57ad1b16c0aed4a17bdd9badbf232dc5d9305b7e13854", size = 58965, upload-time = "2026-02-24T03:58:11.278Z" }, +] + [[package]] name = "importlib-metadata" version = "8.7.1" @@ -892,6 +1062,54 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" }, ] +[[package]] +name = "inspect-ai" +version = "0.3.207" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "aioboto3" }, + { name = "aiohttp" }, + { name = "anyio" }, + { name = "beautifulsoup4" }, + { name = "boto3" }, + { name = "click" }, + { name = "debugpy" }, + { name = "docstring-parser" }, + { name = "fsspec" }, + { name = "httpx" }, + { name = "ijson" }, + { name = "jsonlines" }, + { name = "jsonpatch" }, + { name = "jsonpath-ng" }, + { name = "jsonref" }, + { name = "jsonschema" }, + { name = "mmh3" }, + { name = "nest-asyncio2" }, + { name = "numpy" }, + { name = "platformdirs" }, + { name = "psutil" }, + { name = "pydantic" }, + { name = "python-dotenv" }, + { name = "pyyaml" }, + { name = "rich" }, + { name = "s3fs" }, + { name = "semver" }, + { name = "shortuuid" }, + { name = "sniffio" }, + { name = "tenacity" }, + { name = "textual" }, + { name = "tiktoken" }, + { name = "typing-extensions" }, + { name = "universal-pathlib" }, + { name = "zipfile-zstd", marker = "python_full_version < '3.14'" }, + { name = "zipp" }, + { name = "zstandard" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/7c/8a/4adb0fdd3a77c80904f9fbdda609719a8c38ea966e851c2be466f4b8ca14/inspect_ai-0.3.207.tar.gz", hash = "sha256:20047d95e8f276fc0218aa0249be701ad56e2260edafa6104ed6e100ff8c45c9", size = 45272813, upload-time = "2026-04-16T21:33:38.371Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c9/b8/d809f7134d965b93e012df1d502fd3d66fa133d7e02fdb7671ca1d1b5ecc/inspect_ai-0.3.207-py3-none-any.whl", hash = "sha256:6ff80d17528153e011772c9c5cd4b80f32736e2752abcf4872518c88916793e3", size = 35998474, upload-time = "2026-04-16T21:33:31.948Z" }, +] + [[package]] name = "jaraco-classes" version = "3.4.0" @@ -934,6 +1152,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b2/a3/e137168c9c44d18eff0376253da9f1e9234d0239e0ee230d2fee6cea8e55/jeepney-0.9.0-py3-none-any.whl", hash = "sha256:97e5714520c16fc0a45695e5365a2e11b81ea79bba796e26f9f1d178cb182683", size = 49010, upload-time = "2025-02-27T18:51:00.104Z" }, ] +[[package]] +name = "jmespath" +version = "1.1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d3/59/322338183ecda247fb5d1763a6cbe46eff7222eaeebafd9fa65d4bf5cb11/jmespath-1.1.0.tar.gz", hash = "sha256:472c87d80f36026ae83c6ddd0f1d05d4e510134ed462851fd5f754c8c3cbb88d", size = 27377, upload-time = "2026-01-22T16:35:26.279Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/14/2f/967ba146e6d58cf6a652da73885f52fc68001525b4197effc174321d70b4/jmespath-1.1.0-py3-none-any.whl", hash = "sha256:a5663118de4908c91729bea0acadca56526eb2698e83de10cd116ae0f4e97c64", size = 20419, upload-time = "2026-01-22T16:35:24.919Z" }, +] + [[package]] name = "json-repair" version = "0.59.4" @@ -943,6 +1170,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/74/c4/ec3068436d2275731539b7a43fbc947f502bc3fe149856a5d00368c7b087/json_repair-0.59.4-py3-none-any.whl", hash = "sha256:46052e646bc0b0c39db672ebbf732f774f3c1a5bde81a54f0b0e19d3af4f45cd", size = 46697, upload-time = "2026-04-15T06:48:39.61Z" }, ] +[[package]] +name = "jsonlines" +version = "4.0.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "attrs" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/35/87/bcda8e46c88d0e34cad2f09ee2d0c7f5957bccdb9791b0b934ec84d84be4/jsonlines-4.0.0.tar.gz", hash = "sha256:0c6d2c09117550c089995247f605ae4cf77dd1533041d366351f6f298822ea74", size = 11359, upload-time = "2023-09-01T12:34:44.187Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f8/62/d9ba6323b9202dd2fe166beab8a86d29465c41a0288cbe229fac60c1ab8d/jsonlines-4.0.0-py3-none-any.whl", hash = "sha256:185b334ff2ca5a91362993f42e83588a360cf95ce4b71a73548502bda52a7c55", size = 8701, upload-time = "2023-09-01T12:34:42.563Z" }, +] + [[package]] name = "jsonpatch" version = "1.33" @@ -955,6 +1194,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/73/07/02e16ed01e04a374e644b575638ec7987ae846d25ad97bcc9945a3ee4b0e/jsonpatch-1.33-py2.py3-none-any.whl", hash = "sha256:0ae28c0cd062bbd8b8ecc26d7d164fbbea9652a1a3693f3b956c1eae5145dade", size = 12898, upload-time = "2023-06-16T21:01:28.466Z" }, ] +[[package]] +name = "jsonpath-ng" +version = "1.8.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/32/58/250751940d75c8019659e15482d548a4aa3b6ce122c515102a4bfdac50e3/jsonpath_ng-1.8.0.tar.gz", hash = "sha256:54252968134b5e549ea5b872f1df1168bd7defe1a52fed5a358c194e1943ddc3", size = 74513, upload-time = "2026-02-24T14:42:06.182Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/03/99/33c7d78a3fb70d545fd5411ac67a651c81602cc09c9cf0df383733f068c5/jsonpath_ng-1.8.0-py3-none-any.whl", hash = "sha256:b8dde192f8af58d646fc031fac9c99fe4d00326afc4148f1f043c601a8cfe138", size = 67844, upload-time = "2026-02-28T00:53:19.637Z" }, +] + [[package]] name = "jsonpointer" version = "3.1.1" @@ -1051,6 +1299,8 @@ dependencies = [ [package.dev-dependencies] dev = [ { name = "anyio" }, + { name = "httpx" }, + { name = "inspect-ai" }, { name = "pytest" }, ] @@ -1071,6 +1321,8 @@ requires-dist = [ [package.metadata.requires-dev] dev = [ { name = "anyio", specifier = ">=4.0" }, + { name = "httpx" }, + { name = "inspect-ai" }, { name = "pytest", specifier = ">=8.0" }, ] @@ -1174,6 +1426,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/62/bc/148f98ac7dad73ac5e1b1c985290079cfeeb9ba13d760a24f25002beb2c9/langsmith-0.7.32-py3-none-any.whl", hash = "sha256:e1fde928990c4c52f47dc5132708cec674355d9101723d564183e965f383bf5f", size = 378272, upload-time = "2026-04-15T23:42:39.905Z" }, ] +[[package]] +name = "linkify-it-py" +version = "2.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "uc-micro-py" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/2e/c9/06ea13676ef354f0af6169587ae292d3e2406e212876a413bf9eece4eb23/linkify_it_py-2.1.0.tar.gz", hash = "sha256:43360231720999c10e9328dc3691160e27a718e280673d444c38d7d3aaa3b98b", size = 29158, upload-time = "2026-03-01T07:48:47.683Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b4/de/88b3be5c31b22333b3ca2f6ff1de4e863d8fe45aaea7485f591970ec1d3e/linkify_it_py-2.1.0-py3-none-any.whl", hash = "sha256:0d252c1594ecba2ecedc444053db5d3a9b7ec1b0dd929c8f1d74dce89f86c05e", size = 19878, upload-time = "2026-03-01T07:48:46.098Z" }, +] + [[package]] name = "markdown-it-py" version = "4.0.0" @@ -1186,6 +1450,11 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321, upload-time = "2025-08-11T12:57:51.923Z" }, ] +[package.optional-dependencies] +linkify = [ + { name = "linkify-it-py" }, +] + [[package]] name = "mcp" version = "1.26.0" @@ -1211,6 +1480,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/fd/d9/eaa1f80170d2b7c5ba23f3b59f766f3a0bb41155fbc32a69adfa1adaaef9/mcp-1.26.0-py3-none-any.whl", hash = "sha256:904a21c33c25aa98ddbeb47273033c435e595bbacfdb177f4bd87f6dceebe1ca", size = 233615, upload-time = "2026-01-24T19:40:30.652Z" }, ] +[[package]] +name = "mdit-py-plugins" +version = "0.5.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markdown-it-py" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/b2/fd/a756d36c0bfba5f6e39a1cdbdbfdd448dc02692467d83816dff4592a1ebc/mdit_py_plugins-0.5.0.tar.gz", hash = "sha256:f4918cb50119f50446560513a8e311d574ff6aaed72606ddae6d35716fe809c6", size = 44655, upload-time = "2025-08-11T07:25:49.083Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fb/86/dd6e5db36df29e76c7a7699123569a4a18c1623ce68d826ed96c62643cae/mdit_py_plugins-0.5.0-py3-none-any.whl", hash = "sha256:07a08422fc1936a5d26d146759e9155ea466e842f5ab2f7d2266dd084c8dab1f", size = 57205, upload-time = "2025-08-11T07:25:47.597Z" }, +] + [[package]] name = "mdurl" version = "0.1.2" @@ -1220,6 +1501,88 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" }, ] +[[package]] +name = "mmh3" +version = "5.2.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/91/1a/edb23803a168f070ded7a3014c6d706f63b90c84ccc024f89d794a3b7a6d/mmh3-5.2.1.tar.gz", hash = "sha256:bbea5b775f0ac84945191fb83f845a6fd9a21a03ea7f2e187defac7e401616ad", size = 33775, upload-time = "2026-03-05T15:55:57.716Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/92/94/bc5c3b573b40a328c4d141c20e399039ada95e5e2a661df3425c5165fd84/mmh3-5.2.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0cc21533878e5586b80d74c281d7f8da7932bc8ace50b8d5f6dbf7e3935f63f1", size = 56087, upload-time = "2026-03-05T15:54:21.92Z" }, + { url = "https://files.pythonhosted.org/packages/f6/80/64a02cc3e95c3af0aaa2590849d9ed24a9f14bb93537addde688e039b7c3/mmh3-5.2.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:4eda76074cfca2787c8cf1bec603eaebdddd8b061ad5502f85cddae998d54f00", size = 40500, upload-time = "2026-03-05T15:54:22.953Z" }, + { url = "https://files.pythonhosted.org/packages/8b/72/e6d6602ce18adf4ddcd0e48f2e13590cc92a536199e52109f46f259d3c46/mmh3-5.2.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:eee884572b06bbe8a2b54f424dbd996139442cf83c76478e1ec162512e0dd2c7", size = 40034, upload-time = "2026-03-05T15:54:23.943Z" }, + { url = "https://files.pythonhosted.org/packages/59/c2/bf4537a8e58e21886ef16477041238cab5095c836496e19fafc34b7445d2/mmh3-5.2.1-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:0d0b7e803191db5f714d264044e06189c8ccd3219e936cc184f07106bd17fd7b", size = 97292, upload-time = "2026-03-05T15:54:25.335Z" }, + { url = "https://files.pythonhosted.org/packages/e5/e2/51ed62063b44d10b06d975ac87af287729eeb5e3ed9772f7584a17983e90/mmh3-5.2.1-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8e6c219e375f6341d0959af814296372d265a8ca1af63825f65e2e87c618f006", size = 103274, upload-time = "2026-03-05T15:54:26.44Z" }, + { url = "https://files.pythonhosted.org/packages/75/ce/12a7524dca59eec92e5b31fdb13ede1e98eda277cf2b786cf73bfbc24e81/mmh3-5.2.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:26fb5b9c3946bf7f1daed7b37e0c03898a6f062149127570f8ede346390a0825", size = 106158, upload-time = "2026-03-05T15:54:28.578Z" }, + { url = "https://files.pythonhosted.org/packages/86/1f/d3ba6dd322d01ab5d44c46c8f0c38ab6bbbf9b5e20e666dfc05bf4a23604/mmh3-5.2.1-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:3c38d142c706201db5b2345166eeef1e7740e3e2422b470b8ba5c8727a9b4c7a", size = 113005, upload-time = "2026-03-05T15:54:29.767Z" }, + { url = "https://files.pythonhosted.org/packages/b6/a9/15d6b6f913294ea41b44d901741298e3718e1cb89ee626b3694625826a43/mmh3-5.2.1-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:50885073e2909251d4718634a191c49ae5f527e5e1736d738e365c3e8be8f22b", size = 120744, upload-time = "2026-03-05T15:54:30.931Z" }, + { url = "https://files.pythonhosted.org/packages/76/b3/70b73923fd0284c439860ff5c871b20210dfdbe9a6b9dd0ee6496d77f174/mmh3-5.2.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:b3f99e1756fc48ad507b95e5d86f2fb21b3d495012ff13e6592ebac14033f166", size = 99111, upload-time = "2026-03-05T15:54:32.353Z" }, + { url = "https://files.pythonhosted.org/packages/dd/38/99f7f75cd27d10d8b899a1caafb9d531f3903e4d54d572220e3d8ac35e89/mmh3-5.2.1-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:62815d2c67f2dd1be76a253d88af4e1da19aeaa1820146dec52cf8bee2958b16", size = 98623, upload-time = "2026-03-05T15:54:33.801Z" }, + { url = "https://files.pythonhosted.org/packages/fd/68/6e292c0853e204c44d2f03ea5f090be3317a0e2d9417ecb62c9eb27687df/mmh3-5.2.1-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:8f767ba0911602ddef289404e33835a61168314ebd3c729833db2ed685824211", size = 106437, upload-time = "2026-03-05T15:54:35.177Z" }, + { url = "https://files.pythonhosted.org/packages/dd/c6/fedd7284c459cfb58721d461fcf5607a4c1f5d9ab195d113d51d10164d16/mmh3-5.2.1-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:67e41a497bac88cc1de96eeba56eeb933c39d54bc227352f8455aa87c4ca4000", size = 110002, upload-time = "2026-03-05T15:54:36.673Z" }, + { url = "https://files.pythonhosted.org/packages/3b/ac/ca8e0c19a34f5b71390171d2ff0b9f7f187550d66801a731bb68925126a4/mmh3-5.2.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:3d74a03fb57757ece25aa4b3c1c60157a1cece37a020542785f942e2f827eed5", size = 97507, upload-time = "2026-03-05T15:54:37.804Z" }, + { url = "https://files.pythonhosted.org/packages/df/94/6ebb9094cfc7ac5e7950776b9d13a66bb4a34f83814f32ba2abc9494fc68/mmh3-5.2.1-cp312-cp312-win32.whl", hash = "sha256:7374d6e3ef72afe49697ecd683f3da12f4fc06af2d75433d0580c6746d2fa025", size = 40773, upload-time = "2026-03-05T15:54:40.077Z" }, + { url = "https://files.pythonhosted.org/packages/5b/3c/cd3527198cf159495966551c84a5f36805a10ac17b294f41f67b83f6a4d6/mmh3-5.2.1-cp312-cp312-win_amd64.whl", hash = "sha256:3a9fed49c6ce4ed7e73f13182760c65c816da006debe67f37635580dfb0fae00", size = 41560, upload-time = "2026-03-05T15:54:41.148Z" }, + { url = "https://files.pythonhosted.org/packages/15/96/6fe5ebd0f970a076e3ed5512871ce7569447b962e96c125528a2f9724470/mmh3-5.2.1-cp312-cp312-win_arm64.whl", hash = "sha256:bbfcb95d9a744e6e2827dfc66ad10e1020e0cac255eb7f85652832d5a264c2fc", size = 39313, upload-time = "2026-03-05T15:54:42.171Z" }, + { url = "https://files.pythonhosted.org/packages/25/a5/9daa0508a1569a54130f6198d5462a92deda870043624aa3ea72721aa765/mmh3-5.2.1-cp313-cp313-android_21_arm64_v8a.whl", hash = "sha256:723b2681ed4cc07d3401bbea9c201ad4f2a4ca6ba8cddaff6789f715dd2b391e", size = 40832, upload-time = "2026-03-05T15:54:43.212Z" }, + { url = "https://files.pythonhosted.org/packages/0a/6b/3230c6d80c1f4b766dedf280a92c2241e99f87c1504ff74205ec8cebe451/mmh3-5.2.1-cp313-cp313-android_21_x86_64.whl", hash = "sha256:3619473a0e0d329fd4aec8075628f8f616be2da41605300696206d6f36920c3d", size = 41964, upload-time = "2026-03-05T15:54:44.204Z" }, + { url = "https://files.pythonhosted.org/packages/62/fb/648bfddb74a872004b6ee751551bfdda783fe6d70d2e9723bad84dbe5311/mmh3-5.2.1-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:e48d4dbe0f88e53081da605ae68644e5182752803bbc2beb228cca7f1c4454d6", size = 39114, upload-time = "2026-03-05T15:54:45.205Z" }, + { url = "https://files.pythonhosted.org/packages/95/c2/ab7901f87af438468b496728d11264cb397b3574d41506e71b92128e0373/mmh3-5.2.1-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:a482ac121de6973897c92c2f31defc6bafb11c83825109275cffce54bb64933f", size = 39819, upload-time = "2026-03-05T15:54:46.509Z" }, + { url = "https://files.pythonhosted.org/packages/2f/ed/6f88dda0df67de1612f2e130ffea34cf84aaee5bff5b0aff4dbff2babe34/mmh3-5.2.1-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:17fbb47f0885ace8327ce1235d0416dc86a211dcd8cc1e703f41523be32cfec8", size = 40330, upload-time = "2026-03-05T15:54:47.864Z" }, + { url = "https://files.pythonhosted.org/packages/3d/66/7516d23f53cdf90f43fce24ab80c28f45e6851d78b46bef8c02084edf583/mmh3-5.2.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:d51fde50a77f81330523562e3c2734ffdca9c4c9e9d355478117905e1cfe16c6", size = 56078, upload-time = "2026-03-05T15:54:48.9Z" }, + { url = "https://files.pythonhosted.org/packages/bc/34/4d152fdf4a91a132cb226b671f11c6b796eada9ab78080fb5ce1e95adaab/mmh3-5.2.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:19bbd3b841174ae6ed588536ab5e1b1fe83d046e668602c20266547298d939a9", size = 40498, upload-time = "2026-03-05T15:54:49.942Z" }, + { url = "https://files.pythonhosted.org/packages/d4/4c/8e3af1b6d85a299767ec97bd923f12b06267089c1472c27c1696870d1175/mmh3-5.2.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:be77c402d5e882b6fbacfd90823f13da8e0a69658405a39a569c6b58fdb17b03", size = 40033, upload-time = "2026-03-05T15:54:50.994Z" }, + { url = "https://files.pythonhosted.org/packages/8b/f2/966ea560e32578d453c9e9db53d602cbb1d0da27317e232afa7c38ceba11/mmh3-5.2.1-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:fd96476f04db5ceba1cfa0f21228f67c1f7402296f0e73fee3513aa680ad237b", size = 97320, upload-time = "2026-03-05T15:54:52.072Z" }, + { url = "https://files.pythonhosted.org/packages/bb/0d/2c5f9893b38aeb6b034d1a44ecd55a010148054f6a516abe53b5e4057297/mmh3-5.2.1-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:707151644085dd0f20fe4f4b573d28e5130c4aaa5f587e95b60989c5926653b5", size = 103299, upload-time = "2026-03-05T15:54:53.569Z" }, + { url = "https://files.pythonhosted.org/packages/1c/fc/2ebaef4a4d4376f89761274dc274035ffd96006ab496b4ee5af9b08f21a9/mmh3-5.2.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3737303ca9ea0f7cb83028781148fcda4f1dac7821db0c47672971dabcf63593", size = 106222, upload-time = "2026-03-05T15:54:55.092Z" }, + { url = "https://files.pythonhosted.org/packages/57/09/ea7ffe126d0ba0406622602a2d05e1e1a6841cc92fc322eb576c95b27fad/mmh3-5.2.1-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2778fed822d7db23ac5008b181441af0c869455b2e7d001f4019636ac31b6fe4", size = 113048, upload-time = "2026-03-05T15:54:56.305Z" }, + { url = "https://files.pythonhosted.org/packages/85/57/9447032edf93a64aa9bef4d9aa596400b1756f40411890f77a284f6293ca/mmh3-5.2.1-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d57dea657357230cc780e13920d7fa7db059d58fe721c80020f94476da4ca0a1", size = 120742, upload-time = "2026-03-05T15:54:57.453Z" }, + { url = "https://files.pythonhosted.org/packages/53/82/a86cc87cc88c92e9e1a598fee509f0409435b57879a6129bf3b3e40513c7/mmh3-5.2.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:169e0d178cb59314456ab30772429a802b25d13227088085b0d49b9fe1533104", size = 99132, upload-time = "2026-03-05T15:54:58.583Z" }, + { url = "https://files.pythonhosted.org/packages/54/f7/6b16eb1b40ee89bb740698735574536bc20d6cdafc65ae702ea235578e05/mmh3-5.2.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:7e4e1f580033335c6f76d1e0d6b56baf009d1a64d6a4816347e4271ba951f46d", size = 98686, upload-time = "2026-03-05T15:55:00.078Z" }, + { url = "https://files.pythonhosted.org/packages/e8/88/a601e9f32ad1410f438a6d0544298ea621f989bd34a0731a7190f7dec799/mmh3-5.2.1-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:2bd9f19f7f1fcebd74e830f4af0f28adad4975d40d80620be19ffb2b2af56c9f", size = 106479, upload-time = "2026-03-05T15:55:01.532Z" }, + { url = "https://files.pythonhosted.org/packages/d6/5c/ce29ae3dfc4feec4007a437a1b7435fb9507532a25147602cd5b52be86db/mmh3-5.2.1-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:c88653877aeb514c089d1b3d473451677b8b9a6d1497dbddf1ae7934518b06d2", size = 110030, upload-time = "2026-03-05T15:55:02.934Z" }, + { url = "https://files.pythonhosted.org/packages/13/30/ae444ef2ff87c805d525da4fa63d27cda4fe8a48e77003a036b8461cfd5c/mmh3-5.2.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:fceef7fe67c81e1585198215e42ad3fdba3a25644beda8fbdaf85f4d7b93175a", size = 97536, upload-time = "2026-03-05T15:55:04.135Z" }, + { url = "https://files.pythonhosted.org/packages/4b/f9/dc3787ee5c813cc27fe79f45ad4500d9b5437f23a7402435cc34e07c7718/mmh3-5.2.1-cp313-cp313-win32.whl", hash = "sha256:54b64fb2433bc71488e7a449603bf8bd31fbcf9cb56fbe1eb6d459e90b86c37b", size = 40769, upload-time = "2026-03-05T15:55:05.277Z" }, + { url = "https://files.pythonhosted.org/packages/43/67/850e0b5a1e97799822ebfc4ca0e8c6ece3ed8baf7dcdf64de817dfdda2ca/mmh3-5.2.1-cp313-cp313-win_amd64.whl", hash = "sha256:cae6383181f1e345317742d2ddd88f9e7d2682fa4c9432e3a74e47d92dce0229", size = 41563, upload-time = "2026-03-05T15:55:06.283Z" }, + { url = "https://files.pythonhosted.org/packages/c0/cc/98c90b28e1da5458e19fbfaf4adb5289208d3bfccd45dd14eab216a2f0bb/mmh3-5.2.1-cp313-cp313-win_arm64.whl", hash = "sha256:022aa1a528604e6c83d0a7705fdef0b5355d897a9e0fa3a8d26709ceaa06965d", size = 39310, upload-time = "2026-03-05T15:55:07.323Z" }, + { url = "https://files.pythonhosted.org/packages/63/b4/65bc1fb2bb7f83e91c30865023b1847cf89a5f237165575e8c83aa536584/mmh3-5.2.1-cp314-cp314-android_24_arm64_v8a.whl", hash = "sha256:d771f085fcdf4035786adfb1d8db026df1eb4b41dac1c3d070d1e49512843227", size = 40794, upload-time = "2026-03-05T15:55:09.773Z" }, + { url = "https://files.pythonhosted.org/packages/c4/86/7168b3d83be8eb553897b1fac9da8bbb06568e5cfe555ffc329ebb46f59d/mmh3-5.2.1-cp314-cp314-android_24_x86_64.whl", hash = "sha256:7f196cd7910d71e9d9860da0ff7a77f64d22c1ad931f1dd18559a06e03109fc0", size = 41923, upload-time = "2026-03-05T15:55:10.924Z" }, + { url = "https://files.pythonhosted.org/packages/bf/9b/b653ab611c9060ce8ff0ba25c0226757755725e789292f3ca138a58082cd/mmh3-5.2.1-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:b1f12bd684887a0a5d55e6363ca87056f361e45451105012d329b86ec19dbe0b", size = 39131, upload-time = "2026-03-05T15:55:11.961Z" }, + { url = "https://files.pythonhosted.org/packages/9b/b4/5a2e0d34ab4d33543f01121e832395ea510132ea8e52cdf63926d9d81754/mmh3-5.2.1-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:d106493a60dcb4aef35a0fac85105e150a11cf8bc2b0d388f5a33272d756c966", size = 39825, upload-time = "2026-03-05T15:55:13.013Z" }, + { url = "https://files.pythonhosted.org/packages/bd/69/81699a8f39a3f8d368bec6443435c0c392df0d200ad915bf0d222b588e03/mmh3-5.2.1-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:44983e45310ee5b9f73397350251cdf6e63a466406a105f1d16cb5baa659270b", size = 40344, upload-time = "2026-03-05T15:55:14.026Z" }, + { url = "https://files.pythonhosted.org/packages/0c/b3/71c8c775807606e8fd8acc5c69016e1caf3200d50b50b6dd4b40ce10b76c/mmh3-5.2.1-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:368625fb01666655985391dbad3860dc0ba7c0d6b9125819f3121ee7292b4ac8", size = 56291, upload-time = "2026-03-05T15:55:15.137Z" }, + { url = "https://files.pythonhosted.org/packages/6f/75/2c24517d4b2ce9e4917362d24f274d3d541346af764430249ddcc4cb3a08/mmh3-5.2.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:72d1cc63bcc91e14933f77d51b3df899d6a07d184ec515ea7f56bff659e124d7", size = 40575, upload-time = "2026-03-05T15:55:16.518Z" }, + { url = "https://files.pythonhosted.org/packages/bf/b9/e4a360164365ac9f07a25f0f7928e3a66eb9ecc989384060747aa170e6aa/mmh3-5.2.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:e8b4b5580280b9265af3e0409974fb79c64cf7523632d03fbf11df18f8b0181e", size = 40052, upload-time = "2026-03-05T15:55:17.735Z" }, + { url = "https://files.pythonhosted.org/packages/97/ca/120d92223a7546131bbbc31c9174168ee7a73b1366f5463ffe69d9e691fe/mmh3-5.2.1-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:4cbbde66f1183db040daede83dd86c06d663c5bb2af6de1142b7c8c37923dd74", size = 97311, upload-time = "2026-03-05T15:55:18.959Z" }, + { url = "https://files.pythonhosted.org/packages/b6/71/c1a60c1652b8813ef9de6d289784847355417ee0f2980bca002fe87f4ae5/mmh3-5.2.1-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8ff038d52ef6aa0f309feeba00c5095c9118d0abf787e8e8454d6048db2037fc", size = 103279, upload-time = "2026-03-05T15:55:20.448Z" }, + { url = "https://files.pythonhosted.org/packages/48/29/ad97f4be1509cdcb28ae32c15593ce7c415db47ace37f8fad35b493faa9a/mmh3-5.2.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a4130d0b9ce5fad6af07421b1aecc7e079519f70d6c05729ab871794eded8617", size = 106290, upload-time = "2026-03-05T15:55:21.6Z" }, + { url = "https://files.pythonhosted.org/packages/77/29/1f86d22e281bd8827ba373600a4a8b0c0eae5ca6aa55b9a8c26d2a34decc/mmh3-5.2.1-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f6e0bfe77d238308839699944164b96a2eeccaf55f2af400f54dc20669d8d5f2", size = 113116, upload-time = "2026-03-05T15:55:22.826Z" }, + { url = "https://files.pythonhosted.org/packages/a7/7c/339971ea7ed4c12d98f421f13db3ea576a9114082ccb59d2d1a0f00ccac1/mmh3-5.2.1-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f963eafc0a77a6c0562397da004f5876a9bcf7265a7bcc3205e29636bc4a1312", size = 120740, upload-time = "2026-03-05T15:55:24.3Z" }, + { url = "https://files.pythonhosted.org/packages/e4/92/3c7c4bdb8e926bb3c972d1e2907d77960c1c4b250b41e8366cf20c6e4373/mmh3-5.2.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:92883836caf50d5255be03d988d75bc93e3f86ba247b7ca137347c323f731deb", size = 99143, upload-time = "2026-03-05T15:55:25.456Z" }, + { url = "https://files.pythonhosted.org/packages/df/0a/33dd8706e732458c8375eae63c981292de07a406bad4ec03e5269654aa2c/mmh3-5.2.1-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:57b52603e89355ff318025dd55158f6e71396c0f1f609d548e9ea9c94cc6ce0a", size = 98703, upload-time = "2026-03-05T15:55:26.723Z" }, + { url = "https://files.pythonhosted.org/packages/51/04/76bbce05df76cbc3d396f13b2ea5b1578ef02b6a5187e132c6c33f99d596/mmh3-5.2.1-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:f40a95186a72fa0b67d15fef0f157bfcda00b4f59c8a07cbe5530d41ac35d105", size = 106484, upload-time = "2026-03-05T15:55:28.214Z" }, + { url = "https://files.pythonhosted.org/packages/d3/8f/c6e204a2c70b719c1f62ffd9da27aef2dddcba875ea9c31ca0e87b975a46/mmh3-5.2.1-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:58370d05d033ee97224c81263af123dea3d931025030fd34b61227a768a8858a", size = 110012, upload-time = "2026-03-05T15:55:29.532Z" }, + { url = "https://files.pythonhosted.org/packages/e3/37/7181efd8e39db386c1ebc3e6b7d1f702a09d7c1197a6f2742ed6b5c16597/mmh3-5.2.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:7be6dfb49e48fd0a7d91ff758a2b51336f1cd21f9d44b20f6801f072bd080cdd", size = 97508, upload-time = "2026-03-05T15:55:31.01Z" }, + { url = "https://files.pythonhosted.org/packages/42/0f/afa7ca2615fd85e1469474bb860e381443d0b868c083b62b41cb1d7ca32f/mmh3-5.2.1-cp314-cp314-win32.whl", hash = "sha256:54fe8518abe06a4c3852754bfd498b30cc58e667f376c513eac89a244ce781a4", size = 41387, upload-time = "2026-03-05T15:55:32.403Z" }, + { url = "https://files.pythonhosted.org/packages/71/0d/46d42a260ee1357db3d486e6c7a692e303c017968e14865e00efa10d09fc/mmh3-5.2.1-cp314-cp314-win_amd64.whl", hash = "sha256:3f796b535008708846044c43302719c6956f39ca2d93f2edda5319e79a29efbb", size = 42101, upload-time = "2026-03-05T15:55:33.646Z" }, + { url = "https://files.pythonhosted.org/packages/a4/7b/848a8378059d96501a41159fca90d6a99e89736b0afbe8e8edffeac8c74b/mmh3-5.2.1-cp314-cp314-win_arm64.whl", hash = "sha256:cd471ede0d802dd936b6fab28188302b2d497f68436025857ca72cd3810423fe", size = 39836, upload-time = "2026-03-05T15:55:35.026Z" }, + { url = "https://files.pythonhosted.org/packages/27/61/1dabea76c011ba8547c25d30c91c0ec22544487a8750997a27a0c9e1180b/mmh3-5.2.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:5174a697ce042fa77c407e05efe41e03aa56dae9ec67388055820fb48cf4c3ba", size = 57727, upload-time = "2026-03-05T15:55:36.162Z" }, + { url = "https://files.pythonhosted.org/packages/b7/32/731185950d1cf2d5e28979cc8593016ba1619a295faba10dda664a4931b5/mmh3-5.2.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:0a3984146e414684a6be2862d84fcb1035f4984851cb81b26d933bab6119bf00", size = 41308, upload-time = "2026-03-05T15:55:37.254Z" }, + { url = "https://files.pythonhosted.org/packages/76/aa/66c76801c24b8c9418b4edde9b5e57c75e72c94e29c48f707e3962534f18/mmh3-5.2.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:bd6e7d363aa93bd3421b30b6af97064daf47bc96005bddba67c5ffbc6df426b8", size = 40758, upload-time = "2026-03-05T15:55:38.61Z" }, + { url = "https://files.pythonhosted.org/packages/9e/bb/79a1f638a02f0ae389f706d13891e2fbf7d8c0a22ecde67ba828951bb60a/mmh3-5.2.1-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:113f78e7463a36dbbcea05bfe688efd7fa759d0f0c56e73c974d60dcfec3dfcc", size = 109670, upload-time = "2026-03-05T15:55:40.13Z" }, + { url = "https://files.pythonhosted.org/packages/26/94/8cd0e187a288985bcfc79bf5144d1d712df9dee74365f59d26e3a1865be6/mmh3-5.2.1-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:7e8ec5f606e0809426d2440e0683509fb605a8820a21ebd120dcdba61b74ef7f", size = 117399, upload-time = "2026-03-05T15:55:42.076Z" }, + { url = "https://files.pythonhosted.org/packages/42/94/dfea6059bd5c5beda565f58a4096e43f4858fb6d2862806b8bbd12cbb284/mmh3-5.2.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:22b0f9971ec4e07e8223f2beebe96a6cfc779d940b6f27d26604040dd74d3a44", size = 120386, upload-time = "2026-03-05T15:55:43.481Z" }, + { url = "https://files.pythonhosted.org/packages/47/cb/f9c45e62aaa67220179f487772461d891bb582bb2f9783c944832c60efd9/mmh3-5.2.1-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:85ffc9920ffc39c5eee1e3ac9100c913a0973996fbad5111f939bbda49204bb7", size = 125924, upload-time = "2026-03-05T15:55:44.638Z" }, + { url = "https://files.pythonhosted.org/packages/a5/83/fe54a4a7c11bc9f623dfc1707decd034245602b076dfc1dcc771a4163170/mmh3-5.2.1-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:7aec798c2b01aaa65a55f1124f3405804184373abb318a3091325aece235f67c", size = 135280, upload-time = "2026-03-05T15:55:45.866Z" }, + { url = "https://files.pythonhosted.org/packages/97/67/fe7e9e9c143daddd210cd22aef89cbc425d58ecf238d2b7d9eb0da974105/mmh3-5.2.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:55dbbd8ffbc40d1697d5e2d0375b08599dae8746b0b08dea05eee4ce81648fac", size = 110050, upload-time = "2026-03-05T15:55:47.074Z" }, + { url = "https://files.pythonhosted.org/packages/43/c4/6d4b09fcbef80794de447c9378e39eefc047156b290fa3dd2d5257ca8227/mmh3-5.2.1-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:6c85c38a279ca9295a69b9b088a2e48aa49737bb1b34e6a9dc6297c110e8d912", size = 111158, upload-time = "2026-03-05T15:55:48.239Z" }, + { url = "https://files.pythonhosted.org/packages/81/a6/ca51c864bdb30524beb055a6d8826db3906af0834ec8c41d097a6e8573d5/mmh3-5.2.1-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:6290289fa5fb4c70fd7f72016e03633d60388185483ff3b162912c81205ae2cf", size = 116890, upload-time = "2026-03-05T15:55:49.405Z" }, + { url = "https://files.pythonhosted.org/packages/cc/04/5a1fe2e2ad843d03e89af25238cbc4f6840a8bb6c4329a98ab694c71deda/mmh3-5.2.1-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:4fc6cd65dc4d2fdb2625e288939a3566e36127a84811a4913f02f3d5931da52d", size = 123121, upload-time = "2026-03-05T15:55:50.61Z" }, + { url = "https://files.pythonhosted.org/packages/af/4d/3c820c6f4897afd25905270a9f2330a23f77a207ea7356f7aadace7273c0/mmh3-5.2.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:623f938f6a039536cc02b7582a07a080f13fdfd48f87e63201d92d7e34d09a18", size = 110187, upload-time = "2026-03-05T15:55:52.143Z" }, + { url = "https://files.pythonhosted.org/packages/21/54/1d71cd143752361c0aebef16ad3f55926a6faf7b112d355745c1f8a25f7f/mmh3-5.2.1-cp314-cp314t-win32.whl", hash = "sha256:29bc3973676ae334412efdd367fcd11d036b7be3efc1ce2407ef8676dabfeb82", size = 41934, upload-time = "2026-03-05T15:55:53.564Z" }, + { url = "https://files.pythonhosted.org/packages/9d/e4/63a2a88f31d93dea03947cccc2a076946857e799ea4f7acdecbf43b324aa/mmh3-5.2.1-cp314-cp314t-win_amd64.whl", hash = "sha256:28cfab66577000b9505a0d068c731aee7ca85cd26d4d63881fab17857e0fe1fb", size = 43036, upload-time = "2026-03-05T15:55:55.252Z" }, + { url = "https://files.pythonhosted.org/packages/a0/0f/59204bf136d1201f8d7884cfbaf7498c5b4674e87a4c693f9bde63741ce1/mmh3-5.2.1-cp314-cp314t-win_arm64.whl", hash = "sha256:dfd51b4c56b673dfbc43d7d27ef857dd91124801e2806c69bb45585ce0fa019b", size = 40391, upload-time = "2026-03-05T15:55:56.697Z" }, +] + [[package]] name = "more-itertools" version = "10.8.0" @@ -1328,6 +1691,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/81/08/7036c080d7117f28a4af526d794aab6a84463126db031b007717c1a6676e/multidict-6.7.1-py3-none-any.whl", hash = "sha256:55d97cc6dae627efa6a6e548885712d4864b81110ac76fa4e534c03819fa4a56", size = 12319, upload-time = "2026-01-26T02:46:44.004Z" }, ] +[[package]] +name = "nest-asyncio2" +version = "1.7.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/b4/73/731debf26e27e0a0323d7bda270dc2f634b398e38f040a09da1f4351d0aa/nest_asyncio2-1.7.2.tar.gz", hash = "sha256:1921d70b92cc4612c374928d081552efb59b83d91b2b789d935c665fa01729a8", size = 14743, upload-time = "2026-02-13T00:34:04.386Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c5/3c/3179b85b0e1c3659f0369940200cd6d0fa900e6cefcc7ea0bc6dd0e29ffb/nest_asyncio2-1.7.2-py3-none-any.whl", hash = "sha256:f5dfa702f3f81f6a03857e9a19e2ba578c0946a4ad417b4c50a24d7ba641fe01", size = 7843, upload-time = "2026-02-13T00:34:02.691Z" }, +] + [[package]] name = "numpy" version = "2.4.4" @@ -1485,6 +1857,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/52/96/5a770e5c461462575474468e5af931cff9de036e7c2b4fea23c1c58d2cbe/pathable-0.5.0-py3-none-any.whl", hash = "sha256:646e3d09491a6351a0c82632a09c02cdf70a252e73196b36d8a15ba0a114f0a6", size = 16867, upload-time = "2026-02-20T08:46:59.536Z" }, ] +[[package]] +name = "pathlib-abc" +version = "0.5.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d6/cb/448649d7f25d228bf0be3a04590ab7afa77f15e056f8fa976ed05ec9a78f/pathlib_abc-0.5.2.tar.gz", hash = "sha256:fcd56f147234645e2c59c7ae22808b34c364bb231f685ddd9f96885aed78a94c", size = 33342, upload-time = "2025-10-10T18:37:20.524Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b1/29/c028a0731e202035f0e2e0bfbf1a3e46ad6c628cbb17f6f1cc9eea5d9ff1/pathlib_abc-0.5.2-py3-none-any.whl", hash = "sha256:4c9d94cf1b23af417ce7c0417b43333b06a106c01000b286c99de230d95eefbb", size = 19070, upload-time = "2025-10-10T18:37:19.437Z" }, +] + [[package]] name = "pillow" version = "12.2.0" @@ -1656,6 +2037,34 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/5b/5a/bc7b4a4ef808fa59a816c17b20c4bef6884daebbdf627ff2a161da67da19/propcache-0.4.1-py3-none-any.whl", hash = "sha256:af2a6052aeb6cf17d3e46ee169099044fd8224cbaf75c76a2ef596e8163e2237", size = 13305, upload-time = "2025-10-08T19:49:00.792Z" }, ] +[[package]] +name = "psutil" +version = "7.2.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/aa/c6/d1ddf4abb55e93cebc4f2ed8b5d6dbad109ecb8d63748dd2b20ab5e57ebe/psutil-7.2.2.tar.gz", hash = "sha256:0746f5f8d406af344fd547f1c8daa5f5c33dbc293bb8d6a16d80b4bb88f59372", size = 493740, upload-time = "2026-01-28T18:14:54.428Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/51/08/510cbdb69c25a96f4ae523f733cdc963ae654904e8db864c07585ef99875/psutil-7.2.2-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:2edccc433cbfa046b980b0df0171cd25bcaeb3a68fe9022db0979e7aa74a826b", size = 130595, upload-time = "2026-01-28T18:14:57.293Z" }, + { url = "https://files.pythonhosted.org/packages/d6/f5/97baea3fe7a5a9af7436301f85490905379b1c6f2dd51fe3ecf24b4c5fbf/psutil-7.2.2-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:e78c8603dcd9a04c7364f1a3e670cea95d51ee865e4efb3556a3a63adef958ea", size = 131082, upload-time = "2026-01-28T18:14:59.732Z" }, + { url = "https://files.pythonhosted.org/packages/37/d6/246513fbf9fa174af531f28412297dd05241d97a75911ac8febefa1a53c6/psutil-7.2.2-cp313-cp313t-manylinux2010_x86_64.manylinux_2_12_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1a571f2330c966c62aeda00dd24620425d4b0cc86881c89861fbc04549e5dc63", size = 181476, upload-time = "2026-01-28T18:15:01.884Z" }, + { url = "https://files.pythonhosted.org/packages/b8/b5/9182c9af3836cca61696dabe4fd1304e17bc56cb62f17439e1154f225dd3/psutil-7.2.2-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:917e891983ca3c1887b4ef36447b1e0873e70c933afc831c6b6da078ba474312", size = 184062, upload-time = "2026-01-28T18:15:04.436Z" }, + { url = "https://files.pythonhosted.org/packages/16/ba/0756dca669f5a9300d0cbcbfae9a4c30e446dfc7440ffe43ded5724bfd93/psutil-7.2.2-cp313-cp313t-win_amd64.whl", hash = "sha256:ab486563df44c17f5173621c7b198955bd6b613fb87c71c161f827d3fb149a9b", size = 139893, upload-time = "2026-01-28T18:15:06.378Z" }, + { url = "https://files.pythonhosted.org/packages/1c/61/8fa0e26f33623b49949346de05ec1ddaad02ed8ba64af45f40a147dbfa97/psutil-7.2.2-cp313-cp313t-win_arm64.whl", hash = "sha256:ae0aefdd8796a7737eccea863f80f81e468a1e4cf14d926bd9b6f5f2d5f90ca9", size = 135589, upload-time = "2026-01-28T18:15:08.03Z" }, + { url = "https://files.pythonhosted.org/packages/81/69/ef179ab5ca24f32acc1dac0c247fd6a13b501fd5534dbae0e05a1c48b66d/psutil-7.2.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:eed63d3b4d62449571547b60578c5b2c4bcccc5387148db46e0c2313dad0ee00", size = 130664, upload-time = "2026-01-28T18:15:09.469Z" }, + { url = "https://files.pythonhosted.org/packages/7b/64/665248b557a236d3fa9efc378d60d95ef56dd0a490c2cd37dafc7660d4a9/psutil-7.2.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7b6d09433a10592ce39b13d7be5a54fbac1d1228ed29abc880fb23df7cb694c9", size = 131087, upload-time = "2026-01-28T18:15:11.724Z" }, + { url = "https://files.pythonhosted.org/packages/d5/2e/e6782744700d6759ebce3043dcfa661fb61e2fb752b91cdeae9af12c2178/psutil-7.2.2-cp314-cp314t-manylinux2010_x86_64.manylinux_2_12_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1fa4ecf83bcdf6e6c8f4449aff98eefb5d0604bf88cb883d7da3d8d2d909546a", size = 182383, upload-time = "2026-01-28T18:15:13.445Z" }, + { url = "https://files.pythonhosted.org/packages/57/49/0a41cefd10cb7505cdc04dab3eacf24c0c2cb158a998b8c7b1d27ee2c1f5/psutil-7.2.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e452c464a02e7dc7822a05d25db4cde564444a67e58539a00f929c51eddda0cf", size = 185210, upload-time = "2026-01-28T18:15:16.002Z" }, + { url = "https://files.pythonhosted.org/packages/dd/2c/ff9bfb544f283ba5f83ba725a3c5fec6d6b10b8f27ac1dc641c473dc390d/psutil-7.2.2-cp314-cp314t-win_amd64.whl", hash = "sha256:c7663d4e37f13e884d13994247449e9f8f574bc4655d509c3b95e9ec9e2b9dc1", size = 141228, upload-time = "2026-01-28T18:15:18.385Z" }, + { url = "https://files.pythonhosted.org/packages/f2/fc/f8d9c31db14fcec13748d373e668bc3bed94d9077dbc17fb0eebc073233c/psutil-7.2.2-cp314-cp314t-win_arm64.whl", hash = "sha256:11fe5a4f613759764e79c65cf11ebdf26e33d6dd34336f8a337aa2996d71c841", size = 136284, upload-time = "2026-01-28T18:15:19.912Z" }, + { url = "https://files.pythonhosted.org/packages/e7/36/5ee6e05c9bd427237b11b3937ad82bb8ad2752d72c6969314590dd0c2f6e/psutil-7.2.2-cp36-abi3-macosx_10_9_x86_64.whl", hash = "sha256:ed0cace939114f62738d808fdcecd4c869222507e266e574799e9c0faa17d486", size = 129090, upload-time = "2026-01-28T18:15:22.168Z" }, + { url = "https://files.pythonhosted.org/packages/80/c4/f5af4c1ca8c1eeb2e92ccca14ce8effdeec651d5ab6053c589b074eda6e1/psutil-7.2.2-cp36-abi3-macosx_11_0_arm64.whl", hash = "sha256:1a7b04c10f32cc88ab39cbf606e117fd74721c831c98a27dc04578deb0c16979", size = 129859, upload-time = "2026-01-28T18:15:23.795Z" }, + { url = "https://files.pythonhosted.org/packages/b5/70/5d8df3b09e25bce090399cf48e452d25c935ab72dad19406c77f4e828045/psutil-7.2.2-cp36-abi3-manylinux2010_x86_64.manylinux_2_12_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:076a2d2f923fd4821644f5ba89f059523da90dc9014e85f8e45a5774ca5bc6f9", size = 155560, upload-time = "2026-01-28T18:15:25.976Z" }, + { url = "https://files.pythonhosted.org/packages/63/65/37648c0c158dc222aba51c089eb3bdfa238e621674dc42d48706e639204f/psutil-7.2.2-cp36-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b0726cecd84f9474419d67252add4ac0cd9811b04d61123054b9fb6f57df6e9e", size = 156997, upload-time = "2026-01-28T18:15:27.794Z" }, + { url = "https://files.pythonhosted.org/packages/8e/13/125093eadae863ce03c6ffdbae9929430d116a246ef69866dad94da3bfbc/psutil-7.2.2-cp36-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:fd04ef36b4a6d599bbdb225dd1d3f51e00105f6d48a28f006da7f9822f2606d8", size = 148972, upload-time = "2026-01-28T18:15:29.342Z" }, + { url = "https://files.pythonhosted.org/packages/04/78/0acd37ca84ce3ddffaa92ef0f571e073faa6d8ff1f0559ab1272188ea2be/psutil-7.2.2-cp36-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:b58fabe35e80b264a4e3bb23e6b96f9e45a3df7fb7eed419ac0e5947c61e47cc", size = 148266, upload-time = "2026-01-28T18:15:31.597Z" }, + { url = "https://files.pythonhosted.org/packages/b4/90/e2159492b5426be0c1fef7acba807a03511f97c5f86b3caeda6ad92351a7/psutil-7.2.2-cp37-abi3-win_amd64.whl", hash = "sha256:eb7e81434c8d223ec4a219b5fc1c47d0417b12be7ea866e24fb5ad6e84b3d988", size = 137737, upload-time = "2026-01-28T18:15:33.849Z" }, + { url = "https://files.pythonhosted.org/packages/8c/c7/7bb2e321574b10df20cbde462a94e2b71d05f9bbda251ef27d104668306a/psutil-7.2.2-cp37-abi3-win_arm64.whl", hash = "sha256:8c233660f575a5a89e6d4cb65d9f938126312bca76d8fe087b947b3a1aaac9ee", size = 134617, upload-time = "2026-01-28T18:15:36.514Z" }, +] + [[package]] name = "py-key-value-aio" version = "0.4.4" @@ -1756,7 +2165,7 @@ wheels = [ [[package]] name = "pydantic" -version = "2.12.5" +version = "2.13.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "annotated-types" }, @@ -1764,9 +2173,9 @@ dependencies = [ { name = "typing-extensions" }, { name = "typing-inspection" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/69/44/36f1a6e523abc58ae5f928898e4aca2e0ea509b5aa6f6f392a5d882be928/pydantic-2.12.5.tar.gz", hash = "sha256:4d351024c75c0f085a9febbb665ce8c0c6ec5d30e903bdb6394b7ede26aebb49", size = 821591, upload-time = "2025-11-26T15:11:46.471Z" } +sdist = { url = "https://files.pythonhosted.org/packages/09/e5/06d23afac9973109d1e3c8ad38e1547a12e860610e327c05ee686827dc37/pydantic-2.13.2.tar.gz", hash = "sha256:b418196607e61081c3226dcd4f0672f2a194828abb9109e9cfb84026564df2d1", size = 843836, upload-time = "2026-04-17T09:31:59.636Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/5a/87/b70ad306ebb6f9b585f114d0ac2137d792b48be34d732d60e597c2f8465a/pydantic-2.12.5-py3-none-any.whl", hash = "sha256:e561593fccf61e8a20fc46dfc2dfe075b8be7d0188df33f221ad1f0139180f9d", size = 463580, upload-time = "2025-11-26T15:11:44.605Z" }, + { url = "https://files.pythonhosted.org/packages/77/ca/b45c378e6e8d0b90577288b533e04e95b7afd61bb1d51b6c263176435489/pydantic-2.13.2-py3-none-any.whl", hash = "sha256:a525087f4c03d7e7456a3de89b64cd693d2229933bb1068b9af6befd5563694e", size = 471947, upload-time = "2026-04-17T09:31:57.541Z" }, ] [package.optional-dependencies] @@ -1776,73 +2185,77 @@ email = [ [[package]] name = "pydantic-core" -version = "2.41.5" +version = "2.46.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/71/70/23b021c950c2addd24ec408e9ab05d59b035b39d97cdc1130e1bce647bb6/pydantic_core-2.41.5.tar.gz", hash = "sha256:08daa51ea16ad373ffd5e7606252cc32f07bc72b28284b6bc9c6df804816476e", size = 460952, upload-time = "2025-11-04T13:43:49.098Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/5f/5d/5f6c63eebb5afee93bcaae4ce9a898f3373ca23df3ccaef086d0233a35a7/pydantic_core-2.41.5-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:f41a7489d32336dbf2199c8c0a215390a751c5b014c2c1c5366e817202e9cdf7", size = 2110990, upload-time = "2025-11-04T13:39:58.079Z" }, - { url = "https://files.pythonhosted.org/packages/aa/32/9c2e8ccb57c01111e0fd091f236c7b371c1bccea0fa85247ac55b1e2b6b6/pydantic_core-2.41.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:070259a8818988b9a84a449a2a7337c7f430a22acc0859c6b110aa7212a6d9c0", size = 1896003, upload-time = "2025-11-04T13:39:59.956Z" }, - { url = "https://files.pythonhosted.org/packages/68/b8/a01b53cb0e59139fbc9e4fda3e9724ede8de279097179be4ff31f1abb65a/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e96cea19e34778f8d59fe40775a7a574d95816eb150850a85a7a4c8f4b94ac69", size = 1919200, upload-time = "2025-11-04T13:40:02.241Z" }, - { url = "https://files.pythonhosted.org/packages/38/de/8c36b5198a29bdaade07b5985e80a233a5ac27137846f3bc2d3b40a47360/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ed2e99c456e3fadd05c991f8f437ef902e00eedf34320ba2b0842bd1c3ca3a75", size = 2052578, upload-time = "2025-11-04T13:40:04.401Z" }, - { url = "https://files.pythonhosted.org/packages/00/b5/0e8e4b5b081eac6cb3dbb7e60a65907549a1ce035a724368c330112adfdd/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:65840751b72fbfd82c3c640cff9284545342a4f1eb1586ad0636955b261b0b05", size = 2208504, upload-time = "2025-11-04T13:40:06.072Z" }, - { url = "https://files.pythonhosted.org/packages/77/56/87a61aad59c7c5b9dc8caad5a41a5545cba3810c3e828708b3d7404f6cef/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e536c98a7626a98feb2d3eaf75944ef6f3dbee447e1f841eae16f2f0a72d8ddc", size = 2335816, upload-time = "2025-11-04T13:40:07.835Z" }, - { url = "https://files.pythonhosted.org/packages/0d/76/941cc9f73529988688a665a5c0ecff1112b3d95ab48f81db5f7606f522d3/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:eceb81a8d74f9267ef4081e246ffd6d129da5d87e37a77c9bde550cb04870c1c", size = 2075366, upload-time = "2025-11-04T13:40:09.804Z" }, - { url = "https://files.pythonhosted.org/packages/d3/43/ebef01f69baa07a482844faaa0a591bad1ef129253ffd0cdaa9d8a7f72d3/pydantic_core-2.41.5-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d38548150c39b74aeeb0ce8ee1d8e82696f4a4e16ddc6de7b1d8823f7de4b9b5", size = 2171698, upload-time = "2025-11-04T13:40:12.004Z" }, - { url = "https://files.pythonhosted.org/packages/b1/87/41f3202e4193e3bacfc2c065fab7706ebe81af46a83d3e27605029c1f5a6/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:c23e27686783f60290e36827f9c626e63154b82b116d7fe9adba1fda36da706c", size = 2132603, upload-time = "2025-11-04T13:40:13.868Z" }, - { url = "https://files.pythonhosted.org/packages/49/7d/4c00df99cb12070b6bccdef4a195255e6020a550d572768d92cc54dba91a/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_armv7l.whl", hash = "sha256:482c982f814460eabe1d3bb0adfdc583387bd4691ef00b90575ca0d2b6fe2294", size = 2329591, upload-time = "2025-11-04T13:40:15.672Z" }, - { url = "https://files.pythonhosted.org/packages/cc/6a/ebf4b1d65d458f3cda6a7335d141305dfa19bdc61140a884d165a8a1bbc7/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:bfea2a5f0b4d8d43adf9d7b8bf019fb46fdd10a2e5cde477fbcb9d1fa08c68e1", size = 2319068, upload-time = "2025-11-04T13:40:17.532Z" }, - { url = "https://files.pythonhosted.org/packages/49/3b/774f2b5cd4192d5ab75870ce4381fd89cf218af999515baf07e7206753f0/pydantic_core-2.41.5-cp312-cp312-win32.whl", hash = "sha256:b74557b16e390ec12dca509bce9264c3bbd128f8a2c376eaa68003d7f327276d", size = 1985908, upload-time = "2025-11-04T13:40:19.309Z" }, - { url = "https://files.pythonhosted.org/packages/86/45/00173a033c801cacf67c190fef088789394feaf88a98a7035b0e40d53dc9/pydantic_core-2.41.5-cp312-cp312-win_amd64.whl", hash = "sha256:1962293292865bca8e54702b08a4f26da73adc83dd1fcf26fbc875b35d81c815", size = 2020145, upload-time = "2025-11-04T13:40:21.548Z" }, - { url = "https://files.pythonhosted.org/packages/f9/22/91fbc821fa6d261b376a3f73809f907cec5ca6025642c463d3488aad22fb/pydantic_core-2.41.5-cp312-cp312-win_arm64.whl", hash = "sha256:1746d4a3d9a794cacae06a5eaaccb4b8643a131d45fbc9af23e353dc0a5ba5c3", size = 1976179, upload-time = "2025-11-04T13:40:23.393Z" }, - { url = "https://files.pythonhosted.org/packages/87/06/8806241ff1f70d9939f9af039c6c35f2360cf16e93c2ca76f184e76b1564/pydantic_core-2.41.5-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:941103c9be18ac8daf7b7adca8228f8ed6bb7a1849020f643b3a14d15b1924d9", size = 2120403, upload-time = "2025-11-04T13:40:25.248Z" }, - { url = "https://files.pythonhosted.org/packages/94/02/abfa0e0bda67faa65fef1c84971c7e45928e108fe24333c81f3bfe35d5f5/pydantic_core-2.41.5-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:112e305c3314f40c93998e567879e887a3160bb8689ef3d2c04b6cc62c33ac34", size = 1896206, upload-time = "2025-11-04T13:40:27.099Z" }, - { url = "https://files.pythonhosted.org/packages/15/df/a4c740c0943e93e6500f9eb23f4ca7ec9bf71b19e608ae5b579678c8d02f/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0cbaad15cb0c90aa221d43c00e77bb33c93e8d36e0bf74760cd00e732d10a6a0", size = 1919307, upload-time = "2025-11-04T13:40:29.806Z" }, - { url = "https://files.pythonhosted.org/packages/9a/e3/6324802931ae1d123528988e0e86587c2072ac2e5394b4bc2bc34b61ff6e/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:03ca43e12fab6023fc79d28ca6b39b05f794ad08ec2feccc59a339b02f2b3d33", size = 2063258, upload-time = "2025-11-04T13:40:33.544Z" }, - { url = "https://files.pythonhosted.org/packages/c9/d4/2230d7151d4957dd79c3044ea26346c148c98fbf0ee6ebd41056f2d62ab5/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:dc799088c08fa04e43144b164feb0c13f9a0bc40503f8df3e9fde58a3c0c101e", size = 2214917, upload-time = "2025-11-04T13:40:35.479Z" }, - { url = "https://files.pythonhosted.org/packages/e6/9f/eaac5df17a3672fef0081b6c1bb0b82b33ee89aa5cec0d7b05f52fd4a1fa/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:97aeba56665b4c3235a0e52b2c2f5ae9cd071b8a8310ad27bddb3f7fb30e9aa2", size = 2332186, upload-time = "2025-11-04T13:40:37.436Z" }, - { url = "https://files.pythonhosted.org/packages/cf/4e/35a80cae583a37cf15604b44240e45c05e04e86f9cfd766623149297e971/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:406bf18d345822d6c21366031003612b9c77b3e29ffdb0f612367352aab7d586", size = 2073164, upload-time = "2025-11-04T13:40:40.289Z" }, - { url = "https://files.pythonhosted.org/packages/bf/e3/f6e262673c6140dd3305d144d032f7bd5f7497d3871c1428521f19f9efa2/pydantic_core-2.41.5-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:b93590ae81f7010dbe380cdeab6f515902ebcbefe0b9327cc4804d74e93ae69d", size = 2179146, upload-time = "2025-11-04T13:40:42.809Z" }, - { url = "https://files.pythonhosted.org/packages/75/c7/20bd7fc05f0c6ea2056a4565c6f36f8968c0924f19b7d97bbfea55780e73/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:01a3d0ab748ee531f4ea6c3e48ad9dac84ddba4b0d82291f87248f2f9de8d740", size = 2137788, upload-time = "2025-11-04T13:40:44.752Z" }, - { url = "https://files.pythonhosted.org/packages/3a/8d/34318ef985c45196e004bc46c6eab2eda437e744c124ef0dbe1ff2c9d06b/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_armv7l.whl", hash = "sha256:6561e94ba9dacc9c61bce40e2d6bdc3bfaa0259d3ff36ace3b1e6901936d2e3e", size = 2340133, upload-time = "2025-11-04T13:40:46.66Z" }, - { url = "https://files.pythonhosted.org/packages/9c/59/013626bf8c78a5a5d9350d12e7697d3d4de951a75565496abd40ccd46bee/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:915c3d10f81bec3a74fbd4faebe8391013ba61e5a1a8d48c4455b923bdda7858", size = 2324852, upload-time = "2025-11-04T13:40:48.575Z" }, - { url = "https://files.pythonhosted.org/packages/1a/d9/c248c103856f807ef70c18a4f986693a46a8ffe1602e5d361485da502d20/pydantic_core-2.41.5-cp313-cp313-win32.whl", hash = "sha256:650ae77860b45cfa6e2cdafc42618ceafab3a2d9a3811fcfbd3bbf8ac3c40d36", size = 1994679, upload-time = "2025-11-04T13:40:50.619Z" }, - { url = "https://files.pythonhosted.org/packages/9e/8b/341991b158ddab181cff136acd2552c9f35bd30380422a639c0671e99a91/pydantic_core-2.41.5-cp313-cp313-win_amd64.whl", hash = "sha256:79ec52ec461e99e13791ec6508c722742ad745571f234ea6255bed38c6480f11", size = 2019766, upload-time = "2025-11-04T13:40:52.631Z" }, - { url = "https://files.pythonhosted.org/packages/73/7d/f2f9db34af103bea3e09735bb40b021788a5e834c81eedb541991badf8f5/pydantic_core-2.41.5-cp313-cp313-win_arm64.whl", hash = "sha256:3f84d5c1b4ab906093bdc1ff10484838aca54ef08de4afa9de0f5f14d69639cd", size = 1981005, upload-time = "2025-11-04T13:40:54.734Z" }, - { url = "https://files.pythonhosted.org/packages/ea/28/46b7c5c9635ae96ea0fbb779e271a38129df2550f763937659ee6c5dbc65/pydantic_core-2.41.5-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:3f37a19d7ebcdd20b96485056ba9e8b304e27d9904d233d7b1015db320e51f0a", size = 2119622, upload-time = "2025-11-04T13:40:56.68Z" }, - { url = "https://files.pythonhosted.org/packages/74/1a/145646e5687e8d9a1e8d09acb278c8535ebe9e972e1f162ed338a622f193/pydantic_core-2.41.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1d1d9764366c73f996edd17abb6d9d7649a7eb690006ab6adbda117717099b14", size = 1891725, upload-time = "2025-11-04T13:40:58.807Z" }, - { url = "https://files.pythonhosted.org/packages/23/04/e89c29e267b8060b40dca97bfc64a19b2a3cf99018167ea1677d96368273/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:25e1c2af0fce638d5f1988b686f3b3ea8cd7de5f244ca147c777769e798a9cd1", size = 1915040, upload-time = "2025-11-04T13:41:00.853Z" }, - { url = "https://files.pythonhosted.org/packages/84/a3/15a82ac7bd97992a82257f777b3583d3e84bdb06ba6858f745daa2ec8a85/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:506d766a8727beef16b7adaeb8ee6217c64fc813646b424d0804d67c16eddb66", size = 2063691, upload-time = "2025-11-04T13:41:03.504Z" }, - { url = "https://files.pythonhosted.org/packages/74/9b/0046701313c6ef08c0c1cf0e028c67c770a4e1275ca73131563c5f2a310a/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4819fa52133c9aa3c387b3328f25c1facc356491e6135b459f1de698ff64d869", size = 2213897, upload-time = "2025-11-04T13:41:05.804Z" }, - { url = "https://files.pythonhosted.org/packages/8a/cd/6bac76ecd1b27e75a95ca3a9a559c643b3afcd2dd62086d4b7a32a18b169/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2b761d210c9ea91feda40d25b4efe82a1707da2ef62901466a42492c028553a2", size = 2333302, upload-time = "2025-11-04T13:41:07.809Z" }, - { url = "https://files.pythonhosted.org/packages/4c/d2/ef2074dc020dd6e109611a8be4449b98cd25e1b9b8a303c2f0fca2f2bcf7/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:22f0fb8c1c583a3b6f24df2470833b40207e907b90c928cc8d3594b76f874375", size = 2064877, upload-time = "2025-11-04T13:41:09.827Z" }, - { url = "https://files.pythonhosted.org/packages/18/66/e9db17a9a763d72f03de903883c057b2592c09509ccfe468187f2a2eef29/pydantic_core-2.41.5-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2782c870e99878c634505236d81e5443092fba820f0373997ff75f90f68cd553", size = 2180680, upload-time = "2025-11-04T13:41:12.379Z" }, - { url = "https://files.pythonhosted.org/packages/d3/9e/3ce66cebb929f3ced22be85d4c2399b8e85b622db77dad36b73c5387f8f8/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:0177272f88ab8312479336e1d777f6b124537d47f2123f89cb37e0accea97f90", size = 2138960, upload-time = "2025-11-04T13:41:14.627Z" }, - { url = "https://files.pythonhosted.org/packages/a6/62/205a998f4327d2079326b01abee48e502ea739d174f0a89295c481a2272e/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:63510af5e38f8955b8ee5687740d6ebf7c2a0886d15a6d65c32814613681bc07", size = 2339102, upload-time = "2025-11-04T13:41:16.868Z" }, - { url = "https://files.pythonhosted.org/packages/3c/0d/f05e79471e889d74d3d88f5bd20d0ed189ad94c2423d81ff8d0000aab4ff/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:e56ba91f47764cc14f1daacd723e3e82d1a89d783f0f5afe9c364b8bb491ccdb", size = 2326039, upload-time = "2025-11-04T13:41:18.934Z" }, - { url = "https://files.pythonhosted.org/packages/ec/e1/e08a6208bb100da7e0c4b288eed624a703f4d129bde2da475721a80cab32/pydantic_core-2.41.5-cp314-cp314-win32.whl", hash = "sha256:aec5cf2fd867b4ff45b9959f8b20ea3993fc93e63c7363fe6851424c8a7e7c23", size = 1995126, upload-time = "2025-11-04T13:41:21.418Z" }, - { url = "https://files.pythonhosted.org/packages/48/5d/56ba7b24e9557f99c9237e29f5c09913c81eeb2f3217e40e922353668092/pydantic_core-2.41.5-cp314-cp314-win_amd64.whl", hash = "sha256:8e7c86f27c585ef37c35e56a96363ab8de4e549a95512445b85c96d3e2f7c1bf", size = 2015489, upload-time = "2025-11-04T13:41:24.076Z" }, - { url = "https://files.pythonhosted.org/packages/4e/bb/f7a190991ec9e3e0ba22e4993d8755bbc4a32925c0b5b42775c03e8148f9/pydantic_core-2.41.5-cp314-cp314-win_arm64.whl", hash = "sha256:e672ba74fbc2dc8eea59fb6d4aed6845e6905fc2a8afe93175d94a83ba2a01a0", size = 1977288, upload-time = "2025-11-04T13:41:26.33Z" }, - { url = "https://files.pythonhosted.org/packages/92/ed/77542d0c51538e32e15afe7899d79efce4b81eee631d99850edc2f5e9349/pydantic_core-2.41.5-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:8566def80554c3faa0e65ac30ab0932b9e3a5cd7f8323764303d468e5c37595a", size = 2120255, upload-time = "2025-11-04T13:41:28.569Z" }, - { url = "https://files.pythonhosted.org/packages/bb/3d/6913dde84d5be21e284439676168b28d8bbba5600d838b9dca99de0fad71/pydantic_core-2.41.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b80aa5095cd3109962a298ce14110ae16b8c1aece8b72f9dafe81cf597ad80b3", size = 1863760, upload-time = "2025-11-04T13:41:31.055Z" }, - { url = "https://files.pythonhosted.org/packages/5a/f0/e5e6b99d4191da102f2b0eb9687aaa7f5bea5d9964071a84effc3e40f997/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3006c3dd9ba34b0c094c544c6006cc79e87d8612999f1a5d43b769b89181f23c", size = 1878092, upload-time = "2025-11-04T13:41:33.21Z" }, - { url = "https://files.pythonhosted.org/packages/71/48/36fb760642d568925953bcc8116455513d6e34c4beaa37544118c36aba6d/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:72f6c8b11857a856bcfa48c86f5368439f74453563f951e473514579d44aa612", size = 2053385, upload-time = "2025-11-04T13:41:35.508Z" }, - { url = "https://files.pythonhosted.org/packages/20/25/92dc684dd8eb75a234bc1c764b4210cf2646479d54b47bf46061657292a8/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5cb1b2f9742240e4bb26b652a5aeb840aa4b417c7748b6f8387927bc6e45e40d", size = 2218832, upload-time = "2025-11-04T13:41:37.732Z" }, - { url = "https://files.pythonhosted.org/packages/e2/09/f53e0b05023d3e30357d82eb35835d0f6340ca344720a4599cd663dca599/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bd3d54f38609ff308209bd43acea66061494157703364ae40c951f83ba99a1a9", size = 2327585, upload-time = "2025-11-04T13:41:40Z" }, - { url = "https://files.pythonhosted.org/packages/aa/4e/2ae1aa85d6af35a39b236b1b1641de73f5a6ac4d5a7509f77b814885760c/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2ff4321e56e879ee8d2a879501c8e469414d948f4aba74a2d4593184eb326660", size = 2041078, upload-time = "2025-11-04T13:41:42.323Z" }, - { url = "https://files.pythonhosted.org/packages/cd/13/2e215f17f0ef326fc72afe94776edb77525142c693767fc347ed6288728d/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d0d2568a8c11bf8225044aa94409e21da0cb09dcdafe9ecd10250b2baad531a9", size = 2173914, upload-time = "2025-11-04T13:41:45.221Z" }, - { url = "https://files.pythonhosted.org/packages/02/7a/f999a6dcbcd0e5660bc348a3991c8915ce6599f4f2c6ac22f01d7a10816c/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:a39455728aabd58ceabb03c90e12f71fd30fa69615760a075b9fec596456ccc3", size = 2129560, upload-time = "2025-11-04T13:41:47.474Z" }, - { url = "https://files.pythonhosted.org/packages/3a/b1/6c990ac65e3b4c079a4fb9f5b05f5b013afa0f4ed6780a3dd236d2cbdc64/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:239edca560d05757817c13dc17c50766136d21f7cd0fac50295499ae24f90fdf", size = 2329244, upload-time = "2025-11-04T13:41:49.992Z" }, - { url = "https://files.pythonhosted.org/packages/d9/02/3c562f3a51afd4d88fff8dffb1771b30cfdfd79befd9883ee094f5b6c0d8/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:2a5e06546e19f24c6a96a129142a75cee553cc018ffee48a460059b1185f4470", size = 2331955, upload-time = "2025-11-04T13:41:54.079Z" }, - { url = "https://files.pythonhosted.org/packages/5c/96/5fb7d8c3c17bc8c62fdb031c47d77a1af698f1d7a406b0f79aaa1338f9ad/pydantic_core-2.41.5-cp314-cp314t-win32.whl", hash = "sha256:b4ececa40ac28afa90871c2cc2b9ffd2ff0bf749380fbdf57d165fd23da353aa", size = 1988906, upload-time = "2025-11-04T13:41:56.606Z" }, - { url = "https://files.pythonhosted.org/packages/22/ed/182129d83032702912c2e2d8bbe33c036f342cc735737064668585dac28f/pydantic_core-2.41.5-cp314-cp314t-win_amd64.whl", hash = "sha256:80aa89cad80b32a912a65332f64a4450ed00966111b6615ca6816153d3585a8c", size = 1981607, upload-time = "2025-11-04T13:41:58.889Z" }, - { url = "https://files.pythonhosted.org/packages/9f/ed/068e41660b832bb0b1aa5b58011dea2a3fe0ba7861ff38c4d4904c1c1a99/pydantic_core-2.41.5-cp314-cp314t-win_arm64.whl", hash = "sha256:35b44f37a3199f771c3eaa53051bc8a70cd7b54f333531c59e29fd4db5d15008", size = 1974769, upload-time = "2025-11-04T13:42:01.186Z" }, - { url = "https://files.pythonhosted.org/packages/09/32/59b0c7e63e277fa7911c2fc70ccfb45ce4b98991e7ef37110663437005af/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:7da7087d756b19037bc2c06edc6c170eeef3c3bafcb8f532ff17d64dc427adfd", size = 2110495, upload-time = "2025-11-04T13:42:49.689Z" }, - { url = "https://files.pythonhosted.org/packages/aa/81/05e400037eaf55ad400bcd318c05bb345b57e708887f07ddb2d20e3f0e98/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:aabf5777b5c8ca26f7824cb4a120a740c9588ed58df9b2d196ce92fba42ff8dc", size = 1915388, upload-time = "2025-11-04T13:42:52.215Z" }, - { url = "https://files.pythonhosted.org/packages/6e/0d/e3549b2399f71d56476b77dbf3cf8937cec5cd70536bdc0e374a421d0599/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c007fe8a43d43b3969e8469004e9845944f1a80e6acd47c150856bb87f230c56", size = 1942879, upload-time = "2025-11-04T13:42:56.483Z" }, - { url = "https://files.pythonhosted.org/packages/f7/07/34573da085946b6a313d7c42f82f16e8920bfd730665de2d11c0c37a74b5/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:76d0819de158cd855d1cbb8fcafdf6f5cf1eb8e470abe056d5d161106e38062b", size = 2139017, upload-time = "2025-11-04T13:42:59.471Z" }, +sdist = { url = "https://files.pythonhosted.org/packages/43/bb/4742f05b739b2478459bb16fa8470549518c802e06ddcf3f106c5081315e/pydantic_core-2.46.2.tar.gz", hash = "sha256:37bb079f9ee3f1a519392b73fda2a96379b31f2013c6b467fe693e7f2987f596", size = 471269, upload-time = "2026-04-17T09:10:07.017Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/97/ec/2fafa4c86f5d2a69372c7cddef30925fd0e370b1efaf556609c1a0196d8a/pydantic_core-2.46.2-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:ea1ad8c89da31512fe2d249cf0638fb666925bda341901541bc5f3311c6fcc9e", size = 2101729, upload-time = "2026-04-17T09:12:30.042Z" }, + { url = "https://files.pythonhosted.org/packages/cf/55/be5386c2c4b49af346e8a26b748194ff25757bbb6cf544130854e997af7a/pydantic_core-2.46.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:b308da17b92481e0587244631c5529e5d91d04cb2b08194825627b1eca28e21e", size = 1951546, upload-time = "2026-04-17T09:10:10.585Z" }, + { url = "https://files.pythonhosted.org/packages/29/92/89e273a055ce440e6636c756379af35ad86da9d336a560049c3ba5e41c80/pydantic_core-2.46.2-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d333a50bdd814a917d8d6a7ee35ba2395d53ddaa882613bc24e54a9d8b129095", size = 1976178, upload-time = "2026-04-17T09:11:49.619Z" }, + { url = "https://files.pythonhosted.org/packages/91/b3/e4664469cf70c0cb0f7b2f5719d64e5968bb6f38217042c2afa3d3c4ba17/pydantic_core-2.46.2-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:1d00b99590c5bd1fabbc5d28b170923e32c1b1071b1f1de1851a4d14d89eb192", size = 2051697, upload-time = "2026-04-17T09:12:04.917Z" }, + { url = "https://files.pythonhosted.org/packages/98/58/dbf68213ee06ce51cdd6d8c95f97980e646858c45bd96bd2dfb40433be73/pydantic_core-2.46.2-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9f0e686960ffe9e65066395af856ac2d52c159043144433602c50c221d81c1ba", size = 2233160, upload-time = "2026-04-17T09:12:00.956Z" }, + { url = "https://files.pythonhosted.org/packages/f5/d3/68092aa0ee6c60ff4de4740eb82db3d4ce338ec89b3cecb978c532472f12/pydantic_core-2.46.2-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2d1128da41c9cb474e0a4701f9c363ec645c9d1a02229904c76bf4e0a194fde2", size = 2298398, upload-time = "2026-04-17T09:10:29.694Z" }, + { url = "https://files.pythonhosted.org/packages/e4/51/5d6155eb737db55b0ad354ca5f333ef009f75feb67df2d79a84bace45af6/pydantic_core-2.46.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:48649cf2d8c358d79586e9fb2f8235902fcaa2d969ec1c5301f2d1873b2f8321", size = 2094058, upload-time = "2026-04-17T09:12:10.995Z" }, + { url = "https://files.pythonhosted.org/packages/6b/f3/eb4a986197d71319430464ff181226c95adc8f06d932189b158bae5a82f5/pydantic_core-2.46.2-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:b902f0fc7c2cf503865a05718b68147c6cd5d0a3867af38c527be574a9fa6e9d", size = 2130388, upload-time = "2026-04-17T09:12:41.159Z" }, + { url = "https://files.pythonhosted.org/packages/56/00/44a9c4fe6d0f64b5786d6a8c649d6f0e34ba6c89b3663add1066e54451a2/pydantic_core-2.46.2-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:e80011f808b03d1d87a8f1e76ae3da19a18eb706c823e17981dcf1fae43744fc", size = 2184245, upload-time = "2026-04-17T09:12:36.532Z" }, + { url = "https://files.pythonhosted.org/packages/78/6b/685b98a834d5e3d1c34a1bde1627525559dd223b75075bc7490cdb24eb33/pydantic_core-2.46.2-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:b839d5c802e31348b949b6473f8190cddbf7d47475856d8ac995a373ee16ec59", size = 2186842, upload-time = "2026-04-17T09:13:04.054Z" }, + { url = "https://files.pythonhosted.org/packages/22/64/caa2f5a2ac8b6113adaa410ccdf31ba7f54897a6e54cd0d726fc7e780c88/pydantic_core-2.46.2-cp312-cp312-musllinux_1_1_armv7l.whl", hash = "sha256:c6b1064f3f9cf9072e1d59dd2936f9f3b668bec1c37039708c9222db703c0d5b", size = 2336066, upload-time = "2026-04-17T09:12:13.006Z" }, + { url = "https://files.pythonhosted.org/packages/ee/f9/7d2701bf82945b5b9e7df8347be97ef6a36da2846bfe5b4afec299ffe27b/pydantic_core-2.46.2-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:37a68e6f2ac95578ce3c0564802404b27b24988649616e556c07e77111ed3f1d", size = 2363691, upload-time = "2026-04-17T09:13:42.972Z" }, + { url = "https://files.pythonhosted.org/packages/3b/65/0dab11574101522941055109419db3cc09db871643dc3fc74e2413215e5b/pydantic_core-2.46.2-cp312-cp312-win32.whl", hash = "sha256:d9ffa75a7ef4b97d6e5e205fabd4304ef01fec09e6f1bdde04b9ad1b07d20289", size = 1958801, upload-time = "2026-04-17T09:11:31.981Z" }, + { url = "https://files.pythonhosted.org/packages/13/2b/df84baa609c676f6450b8ecad44ea59146c805e3371b7b52443c0899f989/pydantic_core-2.46.2-cp312-cp312-win_amd64.whl", hash = "sha256:0551f2d2ddb68af5a00e26497f8025c538f73ef3cb698f8e5a487042cd2792a8", size = 2072634, upload-time = "2026-04-17T09:11:02.407Z" }, + { url = "https://files.pythonhosted.org/packages/d1/4e/e1ce8029fc438086a946739bf9d596f70ff470aad4a8345555920618cabe/pydantic_core-2.46.2-cp312-cp312-win_arm64.whl", hash = "sha256:83aef30f106edcc21a6a4cc44b82d3169a1dbe255508db788e778f3c804d3583", size = 2026188, upload-time = "2026-04-17T09:13:11.083Z" }, + { url = "https://files.pythonhosted.org/packages/07/2b/662e48254479a2d3450ba24b1e25061108b64339794232f503990c519144/pydantic_core-2.46.2-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:d26e9eea3715008a09a74585fe9becd0c67fbb145dc4df9756d597d7230a652c", size = 2101762, upload-time = "2026-04-17T09:10:13.87Z" }, + { url = "https://files.pythonhosted.org/packages/73/ab/bafd7c7503757ccc8ec4d1911e106fe474c629443648c51a88f08b0fe91a/pydantic_core-2.46.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:48b36e3235140510dc7861f0cd58b714b1cdd3d48f75e10ce52e69866b746f10", size = 1951814, upload-time = "2026-04-17T09:12:25.934Z" }, + { url = "https://files.pythonhosted.org/packages/92/cc/7549c2d57ba2e9a42caa5861a2d398dbe31c02c6aca783253ace59ce84f8/pydantic_core-2.46.2-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:36b1f99dc451f1a3981f236151465bcf995bbe712d0727c9f7b236fe228a8133", size = 1977329, upload-time = "2026-04-17T09:13:37.605Z" }, + { url = "https://files.pythonhosted.org/packages/18/50/7ed4a8a0d478a4dca8f0134a5efa7193f03cc8520dd4c9509339fb2e5002/pydantic_core-2.46.2-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8641c8d535c2d95b45c2e19b646ecd23ebba35d461e0ae48a3498277006250ab", size = 2051832, upload-time = "2026-04-17T09:12:49.771Z" }, + { url = "https://files.pythonhosted.org/packages/dc/16/bb35b193741c0298ddc5f5e4234269efdc0c65e2bcd198aa0de9b68845e4/pydantic_core-2.46.2-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:20fb194788a0a50993e87013e693494ba183a2af5b44e99cf060bbae10912b11", size = 2233127, upload-time = "2026-04-17T09:11:04.449Z" }, + { url = "https://files.pythonhosted.org/packages/91/a5/98f4b637149185addea19e1785ea20c373cca31b202f589111d8209d9873/pydantic_core-2.46.2-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9262d11d0cd11ee3303a95156939402bed6cedfe5ed0e331b95a283a4da6eb8b", size = 2297418, upload-time = "2026-04-17T09:11:25.929Z" }, + { url = "https://files.pythonhosted.org/packages/36/90/93a5d21990b152da7b7507b7fddb0b935f6a0984d57ac3ec45a6e17777a2/pydantic_core-2.46.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ac204542736aa295fa25f713b7fad6fc50b46ab7764d16087575c85f085174f3", size = 2093735, upload-time = "2026-04-17T09:12:06.908Z" }, + { url = "https://files.pythonhosted.org/packages/14/22/b8b1ffdddf08b4e84380bcb67f41dbbf4c171377c1d36fc6290794bb2094/pydantic_core-2.46.2-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:9a7c43a0584742dface3ca0daf6f719d46c1ac2f87cf080050f9ae052c75e1b2", size = 2127570, upload-time = "2026-04-17T09:11:53.906Z" }, + { url = "https://files.pythonhosted.org/packages/c6/26/e60d72b4e2d0ce1fa811044a974412ac1c567fe067d97b3e6b290530786e/pydantic_core-2.46.2-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:fd05e1edb6a90ad446fa268ab09e59202766b837597b714b2492db11ee87fab9", size = 2183524, upload-time = "2026-04-17T09:11:30.092Z" }, + { url = "https://files.pythonhosted.org/packages/35/32/36bec7584a1eefb17dec4dfa1c946d3fe4440f466c5705b8adfda69c9a9f/pydantic_core-2.46.2-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:91155b110788b5501abc7ea954f1d08606219e4e28e3c73a94124307c06efb80", size = 2185408, upload-time = "2026-04-17T09:10:57.228Z" }, + { url = "https://files.pythonhosted.org/packages/fc/d6/1a5689d873620efd67d6b163db0c444c056adb0849b5bc33e2b9f09665a6/pydantic_core-2.46.2-cp313-cp313-musllinux_1_1_armv7l.whl", hash = "sha256:e4e2c72a529fa03ff228be1d2b76944013f428220b764e03cc50ada67e17a42c", size = 2335171, upload-time = "2026-04-17T09:11:43.369Z" }, + { url = "https://files.pythonhosted.org/packages/3e/8e/675104802abe8ef502b072050ee5f2e915251aa1a3af87e1015ce31ec42d/pydantic_core-2.46.2-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:56291ec1a11c3499890c99a8fd9053b47e60fe837a77ec72c0671b1b8b3dce24", size = 2362743, upload-time = "2026-04-17T09:10:18.333Z" }, + { url = "https://files.pythonhosted.org/packages/8d/bc/86c5dde4fa6e24467680eef5047da3c1a19be0a527d0d8e14aa76b39307c/pydantic_core-2.46.2-cp313-cp313-win32.whl", hash = "sha256:b50f9c5f826ddca1246f055148df939f5f3f2d0d96db73de28e2233f22210d4c", size = 1958074, upload-time = "2026-04-17T09:12:38.622Z" }, + { url = "https://files.pythonhosted.org/packages/2a/97/2537e8c1282b2c4eb062580c0d7a4339e10b072b803d1ee0b7f1f0a5c22c/pydantic_core-2.46.2-cp313-cp313-win_amd64.whl", hash = "sha256:251a57788823230ca8cbc99e6245d1a2ed6e180ec4864f251c94182c580c7f2e", size = 2071741, upload-time = "2026-04-17T09:13:32.405Z" }, + { url = "https://files.pythonhosted.org/packages/da/aa/2ee75798706f9dbc4e76dbe59e41a396c5c311e3d6223b9cf6a5fa7780be/pydantic_core-2.46.2-cp313-cp313-win_arm64.whl", hash = "sha256:315d32d1a71494d6b4e1e14a9fa7a4329597b4c4340088ad7e1a9dafbeed92a9", size = 2025955, upload-time = "2026-04-17T09:10:15.567Z" }, + { url = "https://files.pythonhosted.org/packages/d0/96/a50ccb6b539ae780f73cea74905468777680e30c6c3bdf714b9d4c116ea0/pydantic_core-2.46.2-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:4f59b45f3ef8650c0c736a57f59031d47ed9df4c0a64e83796849d7d14863a2d", size = 2097111, upload-time = "2026-04-17T09:10:49.617Z" }, + { url = "https://files.pythonhosted.org/packages/34/5f/fdead7b3afa822ab6e5a18ee0ecffd54937de1877c01ed13a342e0fb3f07/pydantic_core-2.46.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:3a075a29ebef752784a91532a1a85be6b234ccffec0a9d7978a92696387c3da6", size = 1951904, upload-time = "2026-04-17T09:12:32.062Z" }, + { url = "https://files.pythonhosted.org/packages/95/e0/1c5d547e550cdab1bec737492aa08865337af6fe7fc9b96f7f45f17d9519/pydantic_core-2.46.2-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0d12d786e30c04a9d307c5d7080bf720d9bac7f1668191d8e37633a9562749e2", size = 1978667, upload-time = "2026-04-17T09:11:35.589Z" }, + { url = "https://files.pythonhosted.org/packages/0e/cb/665ce629e218c8228302cb94beff4f6531082a2c87d3ecc3d5e63a26f392/pydantic_core-2.46.2-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:0d5e6d6343b0b5dcacb3503b5de90022968da8ed0ab9ab39d3eda71c20cbf84e", size = 2046721, upload-time = "2026-04-17T09:11:47.725Z" }, + { url = "https://files.pythonhosted.org/packages/77/e9/6cb2cf60f54c1472bbdfce19d957553b43dbba79d1d7b2930a195c594785/pydantic_core-2.46.2-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:233eebac0999b6b9ba76eb56f3ec8fce13164aa16b6d2225a36a79e0f95b5973", size = 2228483, upload-time = "2026-04-17T09:12:08.837Z" }, + { url = "https://files.pythonhosted.org/packages/0d/2a/93e018dd5571f781ebaeda8c0cf65398489d5bee9b1f484df0b6149b43b9/pydantic_core-2.46.2-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9cc0eee720dd2f14f3b7c349469402b99ad81a174ab49d3533974529e9d93992", size = 2294663, upload-time = "2026-04-17T09:12:52.053Z" }, + { url = "https://files.pythonhosted.org/packages/5e/4f/49e57ca55c770c93d9bb046666a54949b42e3c9099a0c5fe94557873fe30/pydantic_core-2.46.2-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:83ee76bf2c9910513dbc19e7d82367131fa7508dedd6186a462393071cc11059", size = 2098742, upload-time = "2026-04-17T09:13:45.472Z" }, + { url = "https://files.pythonhosted.org/packages/c6/b0/6e46b5cd3332af665f794b8cdeea206618a8630bd9e7bcc36864518fce81/pydantic_core-2.46.2-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:d61db38eb4ee5192f0c261b7f2d38e420b554df8912245e3546aee5c45e2fd78", size = 2125922, upload-time = "2026-04-17T09:12:54.304Z" }, + { url = "https://files.pythonhosted.org/packages/06/d1/40850c81585be443a2abfdf7f795f8fae831baf8e2f9b2133c8246ac671c/pydantic_core-2.46.2-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:8f09a713d17bcd55da8ab02ebd9110c5246a49c44182af213b5212800af8bc83", size = 2183000, upload-time = "2026-04-17T09:10:59.027Z" }, + { url = "https://files.pythonhosted.org/packages/04/af/8493d7dfa03ebb7866909e577c6aa65ea0de7377b86023cc51d0c8e11db3/pydantic_core-2.46.2-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:30cacc5fb696e64b8ef6fd31d9549d394dd7d52760db072eecb98e37e3af1677", size = 2180335, upload-time = "2026-04-17T09:12:57.01Z" }, + { url = "https://files.pythonhosted.org/packages/72/5b/1f6a344c4ffdf284da41c6067b82d5ebcbd11ce1b515ae4b662d4adb6f61/pydantic_core-2.46.2-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:7ccfb105fcfe91a22bbb5563ad3dc124bc1aa75bfd2e53a780ab05f78cdf6108", size = 2330002, upload-time = "2026-04-17T09:12:02.958Z" }, + { url = "https://files.pythonhosted.org/packages/25/ff/9a694126c12d6d2f48a0cafa6f8eef88ef0d8825600e18d03ff2e896c3b2/pydantic_core-2.46.2-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:13ffef637dc8370c249e5b26bd18e9a80a4fca3d809618c44e18ec834a7ca7a8", size = 2359920, upload-time = "2026-04-17T09:10:27.764Z" }, + { url = "https://files.pythonhosted.org/packages/51/c8/3a35c763d68a9cb2675eb10ef242cf66c5d4701b28ae12e688d67d2c180e/pydantic_core-2.46.2-cp314-cp314-win32.whl", hash = "sha256:1b0ab6d756ca2704a938e6c31b53f290c2f9c10d3914235410302a149de1a83e", size = 1953701, upload-time = "2026-04-17T09:13:30.021Z" }, + { url = "https://files.pythonhosted.org/packages/1a/6a/f2726a780365f7dfd89d62036f984f7acb99978c60c5e1fa7c0cb898ed11/pydantic_core-2.46.2-cp314-cp314-win_amd64.whl", hash = "sha256:99ebade8c9ada4df975372d8dd25883daa0e379a05f1cd0c99aa0c04368d01a6", size = 2071867, upload-time = "2026-04-17T09:10:39.205Z" }, + { url = "https://files.pythonhosted.org/packages/e1/79/76baacb9feba3d7c399b245ca1a29c74ea0db04ea693811374827eec2290/pydantic_core-2.46.2-cp314-cp314-win_arm64.whl", hash = "sha256:de87422197cf7f83db91d89c86a21660d749b3cd76cd8a45d115b8e675670f02", size = 2017252, upload-time = "2026-04-17T09:10:26.175Z" }, + { url = "https://files.pythonhosted.org/packages/f1/3b/77c26938f817668d9ad9bab1a905cb23f11d9a3d4bf724d429b3e55a8eaf/pydantic_core-2.46.2-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:236f22b4a206b5b61db955396b7cf9e2e1ff77f372efe9570128ccfcd6a525eb", size = 2094545, upload-time = "2026-04-17T09:12:19.339Z" }, + { url = "https://files.pythonhosted.org/packages/fe/de/42c13f590e3c260966aa49bcdb1674774f975467c49abd51191e502bea28/pydantic_core-2.46.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c2012f64d2cd7cca50f49f22445aa5a88691ac2b4498ee0a9a977f8ca4f7289f", size = 1933953, upload-time = "2026-04-17T09:09:55.889Z" }, + { url = "https://files.pythonhosted.org/packages/4e/84/ebe3ebb3e2d8db656937cfa6f97f544cb7132f2307a4a7dfdcd0ea102a12/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d07d6c63106d3a9c9a333e2636f9c82c703b1a9e3b079299e58747964e4fdb72", size = 1974435, upload-time = "2026-04-17T09:10:12.371Z" }, + { url = "https://files.pythonhosted.org/packages/b9/15/0bf51ca6709477cd4ef86148b6d7844f3308f029eac361dd0383f1e17b1a/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:c326a2b4b85e959d9a1fc3a11f32f84611b6ec07c053e1828a860edf8d068208", size = 2031113, upload-time = "2026-04-17T09:10:00.752Z" }, + { url = "https://files.pythonhosted.org/packages/02/ae/b7b5af9b79db036d9e61a44c481c17a213dc8fc4b8b71fe6875a72fc778b/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ac8a65e798f2462552c00d2e013d532c94d646729dda98458beaf51f9ec7b120", size = 2236325, upload-time = "2026-04-17T09:10:33.227Z" }, + { url = "https://files.pythonhosted.org/packages/a6/ae/ecef7477b5a03d4a499708f7e75d2836452ebb70b776c2d64612b334f57a/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:5a3c2bc1cc8164bedbc160b7bb1e8cc1e8b9c27f69ae4f9ae2b976cdae02b2dd", size = 2278135, upload-time = "2026-04-17T09:10:23.287Z" }, + { url = "https://files.pythonhosted.org/packages/db/e4/2f9d82faa47af6c39fc3f120145fd915971e1e0cb6b55b494fad9fdf8275/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e69aa5e10b7e8b1bb4a6888650fd12fcbf11d396ca11d4a44de1450875702830", size = 2109071, upload-time = "2026-04-17T09:11:06.149Z" }, + { url = "https://files.pythonhosted.org/packages/f1/9c/677cf10873fbd0b116575ab7b97c90482b21564f8a8040beb18edef7a577/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:4e6df5c3301e65fb42bc5338bf9a1027a02b0a31dc7f54c33775229af474daf0", size = 2106028, upload-time = "2026-04-17T09:10:51.525Z" }, + { url = "https://files.pythonhosted.org/packages/d6/53/6a06183544daba51c059123a2064a99039df25f115a06bdb26f2ea177038/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2c2f6e32548ac8d559b47944effcf8ae4d81c161f6b6c885edc53bc08b8f192d", size = 2164816, upload-time = "2026-04-17T09:11:56.187Z" }, + { url = "https://files.pythonhosted.org/packages/57/6f/10fcdd9e3eca66fc828eef0f6f5850f2dd3bca2c59e6e041fb8bc3da39be/pydantic_core-2.46.2-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:b089a81c58e6ea0485562bbbbbca4f65c0549521606d5ef27fba217aac9b665a", size = 2166130, upload-time = "2026-04-17T09:10:03.804Z" }, + { url = "https://files.pythonhosted.org/packages/29/83/92d3fd0e0156cad2e3cb5c26de73794af78ac9fa0c22ab666e566dd67061/pydantic_core-2.46.2-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:7f700a6d6f64112ae9193709b84303bbab84424ad4b47d0253301aabce9dfc70", size = 2316605, upload-time = "2026-04-17T09:12:45.249Z" }, + { url = "https://files.pythonhosted.org/packages/97/f1/facffdb970981068219582e499b8d0871ed163ffcc6b347de5c412669e4c/pydantic_core-2.46.2-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:67db6814beaa5fefe91101ec7eb9efda613795767be96f7cf58b1ca8c9ca9972", size = 2358385, upload-time = "2026-04-17T09:09:54.657Z" }, + { url = "https://files.pythonhosted.org/packages/8b/a1/b8160b2f22b2199467bc68581a4ed380643c16b348a27d6165c6c242d694/pydantic_core-2.46.2-cp314-cp314t-win32.whl", hash = "sha256:32fbc7447be8e3be99bf7869f7066308f16be55b61f9882c2cefc7931f5c7664", size = 1942373, upload-time = "2026-04-17T09:12:59.594Z" }, + { url = "https://files.pythonhosted.org/packages/0d/90/db89acabe5b150e11d1b59fe3d947dda2ef6abbfef5c82f056ff63802f5d/pydantic_core-2.46.2-cp314-cp314t-win_amd64.whl", hash = "sha256:b317a2b97019c0b95ce99f4f901ae383f40132da6706cdf1731066a73394c25c", size = 2052078, upload-time = "2026-04-17T09:10:19.96Z" }, + { url = "https://files.pythonhosted.org/packages/97/32/e19b83ceb07a3f1bb21798407790bbc9a31740158fd132b94139cb84e16c/pydantic_core-2.46.2-cp314-cp314t-win_arm64.whl", hash = "sha256:7dcb9d40930dfad7ab6b20bcc6ca9d2b030b0f347a0cd9909b54bd53ead521b1", size = 2016941, upload-time = "2026-04-17T09:12:34.447Z" }, + { url = "https://files.pythonhosted.org/packages/f3/d2/66c146f421178641bda880b0267c0d57dd84f5fec9ecc8e46be17b480742/pydantic_core-2.46.2-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:e9fcabd1857492b5bf16f90258babde50f618f55d046b1309972da2396321ff9", size = 2091621, upload-time = "2026-04-17T09:12:47.501Z" }, + { url = "https://files.pythonhosted.org/packages/ee/b2/c28419aa9fc8055f4ac8e801d1d11c6357351bfa4321ed9bafab3eb98087/pydantic_core-2.46.2-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:fb3ec2c7f54c07b30d89983ce78dc32c37dd06a972448b8716d609493802d628", size = 1937059, upload-time = "2026-04-17T09:10:53.554Z" }, + { url = "https://files.pythonhosted.org/packages/30/ce/cd0824a2db213dc17113291b7a09b9b0ccd9fbf97daa4b81548703341baf/pydantic_core-2.46.2-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:130a6c837d819ef33e8c2bf702ed2c3429237ea69807f1140943d6f4bdaf52fa", size = 1997278, upload-time = "2026-04-17T09:12:23.784Z" }, + { url = "https://files.pythonhosted.org/packages/c9/69/47283fe3c0c967d3e9e9cd6c42b70907610c8a6f8d6e8381f1bb55f8006c/pydantic_core-2.46.2-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c2e25417cec5cd9bddb151e33cb08c50160f317479ecc02b22a95ec18f8fe004", size = 2147096, upload-time = "2026-04-17T09:12:43.124Z" }, ] [[package]] @@ -2022,6 +2435,94 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" }, ] +[[package]] +name = "regex" +version = "2026.4.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/cb/0e/3a246dbf05666918bd3664d9d787f84a9108f6f43cc953a077e4a7dfdb7e/regex-2026.4.4.tar.gz", hash = "sha256:e08270659717f6973523ce3afbafa53515c4dc5dcad637dc215b6fd50f689423", size = 416000, upload-time = "2026-04-03T20:56:28.155Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e5/28/b972a4d3df61e1d7bcf1b59fdb3cddef22f88b6be43f161bb41ebc0e4081/regex-2026.4.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:c07ab8794fa929e58d97a0e1796b8b76f70943fa39df225ac9964615cf1f9d52", size = 490434, upload-time = "2026-04-03T20:53:40.219Z" }, + { url = "https://files.pythonhosted.org/packages/84/20/30041446cf6dc3e0eab344fc62770e84c23b6b68a3b657821f9f80cb69b4/regex-2026.4.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:2c785939dc023a1ce4ec09599c032cc9933d258a998d16ca6f2b596c010940eb", size = 292061, upload-time = "2026-04-03T20:53:41.862Z" }, + { url = "https://files.pythonhosted.org/packages/62/c8/3baa06d75c98c46d4cc4262b71fd2edb9062b5665e868bca57859dadf93a/regex-2026.4.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:1b1ce5c81c9114f1ce2f9288a51a8fd3aeea33a0cc440c415bf02da323aa0a76", size = 289628, upload-time = "2026-04-03T20:53:43.701Z" }, + { url = "https://files.pythonhosted.org/packages/31/87/3accf55634caad8c0acab23f5135ef7d4a21c39f28c55c816ae012931408/regex-2026.4.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:760ef21c17d8e6a4fe8cf406a97cf2806a4df93416ccc82fc98d25b1c20425be", size = 796651, upload-time = "2026-04-03T20:53:45.379Z" }, + { url = "https://files.pythonhosted.org/packages/f6/0c/aaa2c83f34efedbf06f61cb1942c25f6cf1ee3b200f832c4d05f28306c2e/regex-2026.4.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7088fcdcb604a4417c208e2169715800d28838fefd7455fbe40416231d1d47c1", size = 865916, upload-time = "2026-04-03T20:53:47.064Z" }, + { url = "https://files.pythonhosted.org/packages/d9/f6/8c6924c865124643e8f37823eca845dc27ac509b2ee58123685e71cd0279/regex-2026.4.4-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:07edca1ba687998968f7db5bc355288d0c6505caa7374f013d27356d93976d13", size = 912287, upload-time = "2026-04-03T20:53:49.422Z" }, + { url = "https://files.pythonhosted.org/packages/11/0e/a9f6f81013e0deaf559b25711623864970fe6a098314e374ccb1540a4152/regex-2026.4.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:993f657a7c1c6ec51b5e0ba97c9817d06b84ea5fa8d82e43b9405de0defdc2b9", size = 801126, upload-time = "2026-04-03T20:53:51.096Z" }, + { url = "https://files.pythonhosted.org/packages/71/61/3a0cc8af2dc0c8deb48e644dd2521f173f7e6513c6e195aad9aa8dd77ac5/regex-2026.4.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:2b69102a743e7569ebee67e634a69c4cb7e59d6fa2e1aa7d3bdbf3f61435f62d", size = 776788, upload-time = "2026-04-03T20:53:52.889Z" }, + { url = "https://files.pythonhosted.org/packages/64/0b/8bb9cbf21ef7dee58e49b0fdb066a7aded146c823202e16494a36777594f/regex-2026.4.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:6dac006c8b6dda72d86ea3d1333d45147de79a3a3f26f10c1cf9287ca4ca0ac3", size = 785184, upload-time = "2026-04-03T20:53:55.627Z" }, + { url = "https://files.pythonhosted.org/packages/99/c2/d3e80e8137b25ee06c92627de4e4d98b94830e02b3e6f81f3d2e3f504cf5/regex-2026.4.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:50a766ee2010d504554bfb5f578ed2e066898aa26411d57e6296230627cdefa0", size = 859913, upload-time = "2026-04-03T20:53:57.249Z" }, + { url = "https://files.pythonhosted.org/packages/bc/e6/9d5d876157d969c804622456ef250017ac7a8f83e0e14f903b9e6df5ce95/regex-2026.4.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:9e2f5217648f68e3028c823df58663587c1507a5ba8419f4fdfc8a461be76043", size = 765732, upload-time = "2026-04-03T20:53:59.428Z" }, + { url = "https://files.pythonhosted.org/packages/82/80/b568935b4421388561c8ed42aff77247285d3ae3bb2a6ca22af63bae805e/regex-2026.4.4-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:39d8de85a08e32632974151ba59c6e9140646dcc36c80423962b1c5c0a92e244", size = 852152, upload-time = "2026-04-03T20:54:01.505Z" }, + { url = "https://files.pythonhosted.org/packages/39/29/f0f81217e21cd998245da047405366385d5c6072048038a3d33b37a79dc0/regex-2026.4.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:55d9304e0e7178dfb1e106c33edf834097ddf4a890e2f676f6c5118f84390f73", size = 789076, upload-time = "2026-04-03T20:54:03.323Z" }, + { url = "https://files.pythonhosted.org/packages/49/1d/1d957a61976ab9d4e767dd4f9d04b66cc0c41c5e36cf40e2d43688b5ae6f/regex-2026.4.4-cp312-cp312-win32.whl", hash = "sha256:04bb679bc0bde8a7bfb71e991493d47314e7b98380b083df2447cda4b6edb60f", size = 266700, upload-time = "2026-04-03T20:54:05.639Z" }, + { url = "https://files.pythonhosted.org/packages/c5/5c/bf575d396aeb58ea13b06ef2adf624f65b70fafef6950a80fc3da9cae3bc/regex-2026.4.4-cp312-cp312-win_amd64.whl", hash = "sha256:db0ac18435a40a2543dbb3d21e161a6c78e33e8159bd2e009343d224bb03bb1b", size = 277768, upload-time = "2026-04-03T20:54:07.312Z" }, + { url = "https://files.pythonhosted.org/packages/c9/27/049df16ec6a6828ccd72add3c7f54b4df029669bea8e9817df6fff58be90/regex-2026.4.4-cp312-cp312-win_arm64.whl", hash = "sha256:4ce255cc05c1947a12989c6db801c96461947adb7a59990f1360b5983fab4983", size = 270568, upload-time = "2026-04-03T20:54:09.484Z" }, + { url = "https://files.pythonhosted.org/packages/9d/83/c4373bc5f31f2cf4b66f9b7c31005bd87fe66f0dce17701f7db4ee79ee29/regex-2026.4.4-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:62f5519042c101762509b1d717b45a69c0139d60414b3c604b81328c01bd1943", size = 490273, upload-time = "2026-04-03T20:54:11.202Z" }, + { url = "https://files.pythonhosted.org/packages/46/f8/fe62afbcc3cf4ad4ac9adeaafd98aa747869ae12d3e8e2ac293d0593c435/regex-2026.4.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:3790ba9fb5dd76715a7afe34dbe603ba03f8820764b1dc929dd08106214ed031", size = 291954, upload-time = "2026-04-03T20:54:13.412Z" }, + { url = "https://files.pythonhosted.org/packages/5a/92/4712b9fe6a33d232eeb1c189484b80c6c4b8422b90e766e1195d6e758207/regex-2026.4.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:8fae3c6e795d7678963f2170152b0d892cf6aee9ee8afc8c45e6be38d5107fe7", size = 289487, upload-time = "2026-04-03T20:54:15.824Z" }, + { url = "https://files.pythonhosted.org/packages/88/2c/f83b93f85e01168f1070f045a42d4c937b69fdb8dd7ae82d307253f7e36e/regex-2026.4.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:298c3ec2d53225b3bf91142eb9691025bab610e0c0c51592dde149db679b3d17", size = 796646, upload-time = "2026-04-03T20:54:18.229Z" }, + { url = "https://files.pythonhosted.org/packages/df/55/61a2e17bf0c4dc57e11caf8dd11771280d8aaa361785f9e3bc40d653f4a7/regex-2026.4.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e9638791082eaf5b3ac112c587518ee78e083a11c4b28012d8fe2a0f536dfb17", size = 865904, upload-time = "2026-04-03T20:54:20.019Z" }, + { url = "https://files.pythonhosted.org/packages/45/32/1ac8ed1b5a346b5993a3d256abe0a0f03b0b73c8cc88d928537368ac65b6/regex-2026.4.4-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:ae3e764bd4c5ff55035dc82a8d49acceb42a5298edf6eb2fc4d328ee5dd7afae", size = 912304, upload-time = "2026-04-03T20:54:22.403Z" }, + { url = "https://files.pythonhosted.org/packages/26/47/2ee5c613ab546f0eddebf9905d23e07beb933416b1246c2d8791d01979b4/regex-2026.4.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ffa81f81b80047ba89a3c69ae6a0f78d06f4a42ce5126b0eb2a0a10ad44e0b2e", size = 801126, upload-time = "2026-04-03T20:54:24.308Z" }, + { url = "https://files.pythonhosted.org/packages/75/cd/41dacd129ca9fd20bd7d02f83e0fad83e034ac8a084ec369c90f55ef37e2/regex-2026.4.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f56ebf9d70305307a707911b88469213630aba821e77de7d603f9d2f0730687d", size = 776772, upload-time = "2026-04-03T20:54:26.319Z" }, + { url = "https://files.pythonhosted.org/packages/89/6d/5af0b588174cb5f46041fa7dd64d3fd5cd2fe51f18766703d1edc387f324/regex-2026.4.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:773d1dfd652bbffb09336abf890bfd64785c7463716bf766d0eb3bc19c8b7f27", size = 785228, upload-time = "2026-04-03T20:54:28.387Z" }, + { url = "https://files.pythonhosted.org/packages/b7/3b/f5a72b7045bd59575fc33bf1345f156fcfd5a8484aea6ad84b12c5a82114/regex-2026.4.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:d51d20befd5275d092cdffba57ded05f3c436317ee56466c8928ac32d960edaf", size = 860032, upload-time = "2026-04-03T20:54:30.641Z" }, + { url = "https://files.pythonhosted.org/packages/39/a4/72a317003d6fcd7a573584a85f59f525dfe8f67e355ca74eb6b53d66a5e2/regex-2026.4.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:0a51cdb3c1e9161154f976cb2bef9894bc063ac82f31b733087ffb8e880137d0", size = 765714, upload-time = "2026-04-03T20:54:32.789Z" }, + { url = "https://files.pythonhosted.org/packages/25/1e/5672e16f34dbbcb2560cc7e6a2fbb26dfa8b270711e730101da4423d3973/regex-2026.4.4-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:ae5266a82596114e41fb5302140e9630204c1b5f325c770bec654b95dd54b0aa", size = 852078, upload-time = "2026-04-03T20:54:34.546Z" }, + { url = "https://files.pythonhosted.org/packages/f7/0d/c813f0af7c6cc7ed7b9558bac2e5120b60ad0fa48f813e4d4bd55446f214/regex-2026.4.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:c882cd92ec68585e9c1cf36c447ec846c0d94edd706fe59e0c198e65822fd23b", size = 789181, upload-time = "2026-04-03T20:54:36.642Z" }, + { url = "https://files.pythonhosted.org/packages/ea/6d/a344608d1adbd2a95090ddd906cec09a11be0e6517e878d02a5123e0917f/regex-2026.4.4-cp313-cp313-win32.whl", hash = "sha256:05568c4fbf3cb4fa9e28e3af198c40d3237cf6041608a9022285fe567ec3ad62", size = 266690, upload-time = "2026-04-03T20:54:38.343Z" }, + { url = "https://files.pythonhosted.org/packages/31/07/54049f89b46235ca6f45cd6c88668a7050e77d4a15555e47dd40fde75263/regex-2026.4.4-cp313-cp313-win_amd64.whl", hash = "sha256:3384df51ed52db0bea967e21458ab0a414f67cdddfd94401688274e55147bb81", size = 277733, upload-time = "2026-04-03T20:54:40.11Z" }, + { url = "https://files.pythonhosted.org/packages/0e/21/61366a8e20f4d43fb597708cac7f0e2baadb491ecc9549b4980b2be27d16/regex-2026.4.4-cp313-cp313-win_arm64.whl", hash = "sha256:acd38177bd2c8e69a411d6521760806042e244d0ef94e2dd03ecdaa8a3c99427", size = 270565, upload-time = "2026-04-03T20:54:41.883Z" }, + { url = "https://files.pythonhosted.org/packages/f1/1e/3a2b9672433bef02f5d39aa1143ca2c08f311c1d041c464a42be9ae648dc/regex-2026.4.4-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:f94a11a9d05afcfcfa640e096319720a19cc0c9f7768e1a61fceee6a3afc6c7c", size = 494126, upload-time = "2026-04-03T20:54:43.602Z" }, + { url = "https://files.pythonhosted.org/packages/4e/4b/c132a4f4fe18ad3340d89fcb56235132b69559136036b845be3c073142ed/regex-2026.4.4-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:36bcb9d6d1307ab629edc553775baada2aefa5c50ccc0215fbfd2afcfff43141", size = 293882, upload-time = "2026-04-03T20:54:45.41Z" }, + { url = "https://files.pythonhosted.org/packages/f4/5f/eaa38092ce7a023656280f2341dbbd4ad5f05d780a70abba7bb4f4bea54c/regex-2026.4.4-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:261c015b3e2ed0919157046d768774ecde57f03d8fa4ba78d29793447f70e717", size = 292334, upload-time = "2026-04-03T20:54:47.051Z" }, + { url = "https://files.pythonhosted.org/packages/5f/f6/dd38146af1392dac33db7074ab331cec23cced3759167735c42c5460a243/regex-2026.4.4-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c228cf65b4a54583763645dcd73819b3b381ca8b4bb1b349dee1c135f4112c07", size = 811691, upload-time = "2026-04-03T20:54:49.074Z" }, + { url = "https://files.pythonhosted.org/packages/7a/f0/dc54c2e69f5eeec50601054998ec3690d5344277e782bd717e49867c1d29/regex-2026.4.4-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:dd2630faeb6876fb0c287f664d93ddce4d50cd46c6e88e60378c05c9047e08ca", size = 871227, upload-time = "2026-04-03T20:54:51.035Z" }, + { url = "https://files.pythonhosted.org/packages/a1/af/cb16bd5dc61621e27df919a4449bbb7e5a1034c34d307e0a706e9cc0f3e3/regex-2026.4.4-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:6a50ab11b7779b849472337191f3a043e27e17f71555f98d0092fa6d73364520", size = 917435, upload-time = "2026-04-03T20:54:52.994Z" }, + { url = "https://files.pythonhosted.org/packages/5c/71/8b260897f22996b666edd9402861668f45a2ca259f665ac029e6104a2d7d/regex-2026.4.4-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0734f63afe785138549fbe822a8cfeaccd1bae814c5057cc0ed5b9f2de4fc883", size = 816358, upload-time = "2026-04-03T20:54:54.884Z" }, + { url = "https://files.pythonhosted.org/packages/1c/60/775f7f72a510ef238254906c2f3d737fc80b16ca85f07d20e318d2eea894/regex-2026.4.4-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c4ee50606cb1967db7e523224e05f32089101945f859928e65657a2cbb3d278b", size = 785549, upload-time = "2026-04-03T20:54:57.01Z" }, + { url = "https://files.pythonhosted.org/packages/58/42/34d289b3627c03cf381e44da534a0021664188fa49ba41513da0b4ec6776/regex-2026.4.4-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:6c1818f37be3ca02dcb76d63f2c7aaba4b0dc171b579796c6fbe00148dfec6b1", size = 801364, upload-time = "2026-04-03T20:54:58.981Z" }, + { url = "https://files.pythonhosted.org/packages/fc/20/f6ecf319b382a8f1ab529e898b222c3f30600fcede7834733c26279e7465/regex-2026.4.4-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:f5bfc2741d150d0be3e4a0401a5c22b06e60acb9aa4daa46d9e79a6dcd0f135b", size = 866221, upload-time = "2026-04-03T20:55:00.88Z" }, + { url = "https://files.pythonhosted.org/packages/92/6a/9f16d3609d549bd96d7a0b2aee1625d7512ba6a03efc01652149ef88e74d/regex-2026.4.4-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:504ffa8a03609a087cad81277a629b6ce884b51a24bd388a7980ad61748618ff", size = 772530, upload-time = "2026-04-03T20:55:03.213Z" }, + { url = "https://files.pythonhosted.org/packages/fa/f6/aa9768bc96a4c361ac96419fbaf2dcdc33970bb813df3ba9b09d5d7b6d96/regex-2026.4.4-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:70aadc6ff12e4b444586e57fc30771f86253f9f0045b29016b9605b4be5f7dfb", size = 856989, upload-time = "2026-04-03T20:55:05.087Z" }, + { url = "https://files.pythonhosted.org/packages/4d/b4/c671db3556be2473ae3e4bb7a297c518d281452871501221251ea4ecba57/regex-2026.4.4-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:f4f83781191007b6ef43b03debc35435f10cad9b96e16d147efe84a1d48bdde4", size = 803241, upload-time = "2026-04-03T20:55:07.162Z" }, + { url = "https://files.pythonhosted.org/packages/2a/5c/83e3b1d89fa4f6e5a1bc97b4abd4a9a97b3c1ac7854164f694f5f0ba98a0/regex-2026.4.4-cp313-cp313t-win32.whl", hash = "sha256:e014a797de43d1847df957c0a2a8e861d1c17547ee08467d1db2c370b7568baa", size = 269921, upload-time = "2026-04-03T20:55:09.62Z" }, + { url = "https://files.pythonhosted.org/packages/28/07/077c387121f42cdb4d92b1301133c0d93b5709d096d1669ab847dda9fe2e/regex-2026.4.4-cp313-cp313t-win_amd64.whl", hash = "sha256:b15b88b0d52b179712632832c1d6e58e5774f93717849a41096880442da41ab0", size = 281240, upload-time = "2026-04-03T20:55:11.521Z" }, + { url = "https://files.pythonhosted.org/packages/9d/22/ead4a4abc7c59a4d882662aa292ca02c8b617f30b6e163bc1728879e9353/regex-2026.4.4-cp313-cp313t-win_arm64.whl", hash = "sha256:586b89cdadf7d67bf86ae3342a4dcd2b8d70a832d90c18a0ae955105caf34dbe", size = 272440, upload-time = "2026-04-03T20:55:13.365Z" }, + { url = "https://files.pythonhosted.org/packages/f0/f5/ed97c2dc47b5fbd4b73c0d7d75f9ebc8eca139f2bbef476bba35f28c0a77/regex-2026.4.4-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:2da82d643fa698e5e5210e54af90181603d5853cf469f5eedf9bfc8f59b4b8c7", size = 490343, upload-time = "2026-04-03T20:55:15.241Z" }, + { url = "https://files.pythonhosted.org/packages/80/e9/de4828a7385ec166d673a5790ad06ac48cdaa98bc0960108dd4b9cc1aef7/regex-2026.4.4-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:54a1189ad9d9357760557c91103d5e421f0a2dabe68a5cdf9103d0dcf4e00752", size = 291909, upload-time = "2026-04-03T20:55:17.558Z" }, + { url = "https://files.pythonhosted.org/packages/b4/d6/5cfbfc97f3201a4d24b596a77957e092030dcc4205894bc035cedcfce62f/regex-2026.4.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:76d67d5afb1fe402d10a6403bae668d000441e2ab115191a804287d53b772951", size = 289692, upload-time = "2026-04-03T20:55:20.561Z" }, + { url = "https://files.pythonhosted.org/packages/8e/ac/f2212d9fd56fe897e36d0110ba30ba2d247bd6410c5bd98499c7e5a1e1f2/regex-2026.4.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e7cd3e4ee8d80447a83bbc9ab0c8459781fa77087f856c3e740d7763be0df27f", size = 796979, upload-time = "2026-04-03T20:55:22.56Z" }, + { url = "https://files.pythonhosted.org/packages/c9/e3/a016c12675fbac988a60c7e1c16e67823ff0bc016beb27bd7a001dbdabc6/regex-2026.4.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2e19e18c568d2866d8b6a6dfad823db86193503f90823a8f66689315ba28fbe8", size = 866744, upload-time = "2026-04-03T20:55:24.646Z" }, + { url = "https://files.pythonhosted.org/packages/af/a4/0b90ca4cf17adc3cb43de80ec71018c37c88ad64987e8d0d481a95ca60b5/regex-2026.4.4-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:7698a6f38730fd1385d390d1ed07bb13dce39aa616aca6a6d89bea178464b9a4", size = 911613, upload-time = "2026-04-03T20:55:27.033Z" }, + { url = "https://files.pythonhosted.org/packages/8e/3b/2b3dac0b82d41ab43aa87c6ecde63d71189d03fe8854b8ca455a315edac3/regex-2026.4.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:173a66f3651cdb761018078e2d9487f4cf971232c990035ec0eb1cdc6bf929a9", size = 800551, upload-time = "2026-04-03T20:55:29.532Z" }, + { url = "https://files.pythonhosted.org/packages/25/fe/5365eb7aa0e753c4b5957815c321519ecab033c279c60e1b1ae2367fa810/regex-2026.4.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fa7922bbb2cc84fa062d37723f199d4c0cd200245ce269c05db82d904db66b83", size = 776911, upload-time = "2026-04-03T20:55:31.526Z" }, + { url = "https://files.pythonhosted.org/packages/aa/b3/7fb0072156bba065e3b778a7bc7b0a6328212be5dd6a86fd207e0c4f2dab/regex-2026.4.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:59f67cd0a0acaf0e564c20bbd7f767286f23e91e2572c5703bf3e56ea7557edb", size = 785751, upload-time = "2026-04-03T20:55:33.797Z" }, + { url = "https://files.pythonhosted.org/packages/02/1a/9f83677eb699273e56e858f7bd95acdbee376d42f59e8bfca2fd80d79df3/regex-2026.4.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:475e50f3f73f73614f7cba5524d6de49dee269df00272a1b85e3d19f6d498465", size = 860484, upload-time = "2026-04-03T20:55:35.745Z" }, + { url = "https://files.pythonhosted.org/packages/3b/7a/93937507b61cfcff8b4c5857f1b452852b09f741daa9acae15c971d8554e/regex-2026.4.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:a1c0c7d67b64d85ac2e1879923bad2f08a08f3004055f2f406ef73c850114bd4", size = 765939, upload-time = "2026-04-03T20:55:37.972Z" }, + { url = "https://files.pythonhosted.org/packages/86/ea/81a7f968a351c6552b1670ead861e2a385be730ee28402233020c67f9e0f/regex-2026.4.4-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:1371c2ccbb744d66ee63631cc9ca12aa233d5749972626b68fe1a649dd98e566", size = 851417, upload-time = "2026-04-03T20:55:39.92Z" }, + { url = "https://files.pythonhosted.org/packages/4c/7e/323c18ce4b5b8f44517a36342961a0306e931e499febbd876bb149d900f0/regex-2026.4.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:59968142787042db793348a3f5b918cf24ced1f23247328530e063f89c128a95", size = 789056, upload-time = "2026-04-03T20:55:42.303Z" }, + { url = "https://files.pythonhosted.org/packages/c0/af/e7510f9b11b1913b0cd44eddb784b2d650b2af6515bfce4cffcc5bfd1d38/regex-2026.4.4-cp314-cp314-win32.whl", hash = "sha256:59efe72d37fd5a91e373e5146f187f921f365f4abc1249a5ab446a60f30dd5f8", size = 272130, upload-time = "2026-04-03T20:55:44.995Z" }, + { url = "https://files.pythonhosted.org/packages/9a/51/57dae534c915e2d3a21490e88836fa2ae79dde3b66255ecc0c0a155d2c10/regex-2026.4.4-cp314-cp314-win_amd64.whl", hash = "sha256:e0aab3ff447845049d676827d2ff714aab4f73f340e155b7de7458cf53baa5a4", size = 280992, upload-time = "2026-04-03T20:55:47.316Z" }, + { url = "https://files.pythonhosted.org/packages/0a/5e/abaf9f4c3792e34edb1434f06717fae2b07888d85cb5cec29f9204931bf8/regex-2026.4.4-cp314-cp314-win_arm64.whl", hash = "sha256:a7a5bb6aa0cf62208bb4fa079b0c756734f8ad0e333b425732e8609bd51ee22f", size = 273563, upload-time = "2026-04-03T20:55:49.273Z" }, + { url = "https://files.pythonhosted.org/packages/ff/06/35da85f9f217b9538b99cbb170738993bcc3b23784322decb77619f11502/regex-2026.4.4-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:97850d0638391bdc7d35dc1c1039974dcb921eaafa8cc935ae4d7f272b1d60b3", size = 494191, upload-time = "2026-04-03T20:55:51.258Z" }, + { url = "https://files.pythonhosted.org/packages/54/5b/1bc35f479eef8285c4baf88d8c002023efdeebb7b44a8735b36195486ae7/regex-2026.4.4-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:ee7337f88f2a580679f7bbfe69dc86c043954f9f9c541012f49abc554a962f2e", size = 293877, upload-time = "2026-04-03T20:55:53.214Z" }, + { url = "https://files.pythonhosted.org/packages/39/5b/f53b9ad17480b3ddd14c90da04bfb55ac6894b129e5dea87bcaf7d00e336/regex-2026.4.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7429f4e6192c11d659900c0648ba8776243bf396ab95558b8c51a345afeddde6", size = 292410, upload-time = "2026-04-03T20:55:55.736Z" }, + { url = "https://files.pythonhosted.org/packages/bb/56/52377f59f60a7c51aa4161eecf0b6032c20b461805aca051250da435ffc9/regex-2026.4.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dc4f10fbd5dd13dcf4265b4cc07d69ca70280742870c97ae10093e3d66000359", size = 811831, upload-time = "2026-04-03T20:55:57.802Z" }, + { url = "https://files.pythonhosted.org/packages/dd/63/8026310bf066f702a9c361f83a8c9658f3fe4edb349f9c1e5d5273b7c40c/regex-2026.4.4-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a152560af4f9742b96f3827090f866eeec5becd4765c8e0d3473d9d280e76a5a", size = 871199, upload-time = "2026-04-03T20:56:00.333Z" }, + { url = "https://files.pythonhosted.org/packages/20/9f/a514bbb00a466dbb506d43f187a04047f7be1505f10a9a15615ead5080ee/regex-2026.4.4-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:54170b3e95339f415d54651f97df3bff7434a663912f9358237941bbf9143f55", size = 917649, upload-time = "2026-04-03T20:56:02.445Z" }, + { url = "https://files.pythonhosted.org/packages/cb/6b/8399f68dd41a2030218839b9b18360d79b86d22b9fab5ef477c7f23ca67c/regex-2026.4.4-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:07f190d65f5a72dcb9cf7106bfc3d21e7a49dd2879eda2207b683f32165e4d99", size = 816388, upload-time = "2026-04-03T20:56:04.595Z" }, + { url = "https://files.pythonhosted.org/packages/1e/9c/103963f47c24339a483b05edd568594c2be486188f688c0170fd504b2948/regex-2026.4.4-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:9a2741ce5a29d3c84b0b94261ba630ab459a1b847a0d6beca7d62d188175c790", size = 785746, upload-time = "2026-04-03T20:56:07.13Z" }, + { url = "https://files.pythonhosted.org/packages/fa/ee/7f6054c0dec0cee3463c304405e4ff42e27cff05bf36fcb34be549ab17bd/regex-2026.4.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:b26c30df3a28fd9793113dac7385a4deb7294a06c0f760dd2b008bd49a9139bc", size = 801483, upload-time = "2026-04-03T20:56:09.365Z" }, + { url = "https://files.pythonhosted.org/packages/30/c2/51d3d941cf6070dc00c3338ecf138615fc3cce0421c3df6abe97a08af61a/regex-2026.4.4-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:421439d1bee44b19f4583ccf42670ca464ffb90e9fdc38d37f39d1ddd1e44f1f", size = 866331, upload-time = "2026-04-03T20:56:12.039Z" }, + { url = "https://files.pythonhosted.org/packages/16/e8/76d50dcc122ac33927d939f350eebcfe3dbcbda96913e03433fc36de5e63/regex-2026.4.4-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:b40379b53ecbc747fd9bdf4a0ea14eb8188ca1bd0f54f78893a39024b28f4863", size = 772673, upload-time = "2026-04-03T20:56:14.558Z" }, + { url = "https://files.pythonhosted.org/packages/a5/6e/5f6bf75e20ea6873d05ba4ec78378c375cbe08cdec571c83fbb01606e563/regex-2026.4.4-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:08c55c13d2eef54f73eeadc33146fb0baaa49e7335eb1aff6ae1324bf0ddbe4a", size = 857146, upload-time = "2026-04-03T20:56:16.663Z" }, + { url = "https://files.pythonhosted.org/packages/0b/33/3c76d9962949e487ebba353a18e89399f292287204ac8f2f4cfc3a51c233/regex-2026.4.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:9776b85f510062f5a75ef112afe5f494ef1635607bf1cc220c1391e9ac2f5e81", size = 803463, upload-time = "2026-04-03T20:56:18.923Z" }, + { url = "https://files.pythonhosted.org/packages/19/eb/ef32dcd2cb69b69bc0c3e55205bce94a7def48d495358946bc42186dcccc/regex-2026.4.4-cp314-cp314t-win32.whl", hash = "sha256:385edaebde5db5be103577afc8699fea73a0e36a734ba24870be7ffa61119d74", size = 275709, upload-time = "2026-04-03T20:56:20.996Z" }, + { url = "https://files.pythonhosted.org/packages/a0/86/c291bf740945acbf35ed7dbebf8e2eea2f3f78041f6bd7cdab80cb274dc0/regex-2026.4.4-cp314-cp314t-win_amd64.whl", hash = "sha256:5d354b18839328927832e2fa5f7c95b7a3ccc39e7a681529e1685898e6436d45", size = 285622, upload-time = "2026-04-03T20:56:23.641Z" }, + { url = "https://files.pythonhosted.org/packages/d5/e7/ec846d560ae6a597115153c02ca6138a7877a1748b2072d9521c10a93e58/regex-2026.4.4-cp314-cp314t-win_arm64.whl", hash = "sha256:af0384cb01a33600c49505c27c6c57ab0b27bf84a74e28524c92ca897ebdac9d", size = 275773, upload-time = "2026-04-03T20:56:26.07Z" }, +] + [[package]] name = "requests" version = "2.33.1" @@ -2156,6 +2657,32 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d0/02/fa464cdfbe6b26e0600b62c528b72d8608f5cc49f96b8d6e38c95d60c676/rpds_py-0.30.0-cp314-cp314t-win_amd64.whl", hash = "sha256:27f4b0e92de5bfbc6f86e43959e6edd1425c33b5e69aab0984a72047f2bcf1e3", size = 226532, upload-time = "2025-11-30T20:24:14.634Z" }, ] +[[package]] +name = "s3fs" +version = "2025.9.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "aiobotocore" }, + { name = "aiohttp" }, + { name = "fsspec" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/ee/f3/8e6371436666aedfd16e63ff68a51b8a8fcf5f33a0eee33c35e0b2476b27/s3fs-2025.9.0.tar.gz", hash = "sha256:6d44257ef19ea64968d0720744c4af7a063a05f5c1be0e17ce943bef7302bc30", size = 77823, upload-time = "2025-09-02T19:18:21.781Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/37/b3/ca7d58ca25b1bb6df57e6cbd0ca8d6437a4b9ce1cd35adc8a6b2949c113b/s3fs-2025.9.0-py3-none-any.whl", hash = "sha256:c33c93d48f66ed440dbaf6600be149cdf8beae4b6f8f0201a209c5801aeb7e30", size = 30319, upload-time = "2025-09-02T19:18:20.563Z" }, +] + +[[package]] +name = "s3transfer" +version = "0.14.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "botocore" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/62/74/8d69dcb7a9efe8baa2046891735e5dfe433ad558ae23d9e3c14c633d1d58/s3transfer-0.14.0.tar.gz", hash = "sha256:eff12264e7c8b4985074ccce27a3b38a485bb7f7422cc8046fee9be4983e4125", size = 151547, upload-time = "2025-09-09T19:23:31.089Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/48/f0/ae7ca09223a81a1d890b2557186ea015f6e0502e9b8cb8e1813f1d8cfa4e/s3transfer-0.14.0-py3-none-any.whl", hash = "sha256:ea3b790c7077558ed1f02a3072fb3cb992bbbd253392f4b6e9e8976941c7d456", size = 85712, upload-time = "2025-09-09T19:23:30.041Z" }, +] + [[package]] name = "secretstorage" version = "3.5.0" @@ -2169,6 +2696,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b7/46/f5af3402b579fd5e11573ce652019a67074317e18c1935cc0b4ba9b35552/secretstorage-3.5.0-py3-none-any.whl", hash = "sha256:0ce65888c0725fcb2c5bc0fdb8e5438eece02c523557ea40ce0703c266248137", size = 15554, upload-time = "2025-11-23T19:02:51.545Z" }, ] +[[package]] +name = "semver" +version = "3.0.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/72/d1/d3159231aec234a59dd7d601e9dd9fe96f3afff15efd33c1070019b26132/semver-3.0.4.tar.gz", hash = "sha256:afc7d8c584a5ed0a11033af086e8af226a9c0b206f313e0301f8dd7b6b589602", size = 269730, upload-time = "2025-01-24T13:19:27.617Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a6/24/4d91e05817e92e3a61c8a21e08fd0f390f5301f1c448b137c57c4bc6e543/semver-3.0.4-py3-none-any.whl", hash = "sha256:9c824d87ba7f7ab4a1890799cec8596f15c1241cb473404ea1cb0c55e4b04746", size = 17912, upload-time = "2025-01-24T13:19:24.949Z" }, +] + [[package]] name = "shellingham" version = "1.5.4" @@ -2178,6 +2714,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" }, ] +[[package]] +name = "shortuuid" +version = "1.0.13" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/8c/e2/bcf761f3bff95856203f9559baf3741c416071dd200c0fc19fad7f078f86/shortuuid-1.0.13.tar.gz", hash = "sha256:3bb9cf07f606260584b1df46399c0b87dd84773e7b25912b7e391e30797c5e72", size = 9662, upload-time = "2024-03-11T20:11:06.879Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c0/44/21d6bf170bf40b41396480d8d49ad640bca3f2b02139cd52aa1e272830a5/shortuuid-1.0.13-py3-none-any.whl", hash = "sha256:a482a497300b49b4953e15108a7913244e1bb0d41f9d332f5e9925dba33a3c5a", size = 10529, upload-time = "2024-03-11T20:11:04.807Z" }, +] + [[package]] name = "six" version = "1.17.0" @@ -2196,6 +2741,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" }, ] +[[package]] +name = "soupsieve" +version = "2.8.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/7b/ae/2d9c981590ed9999a0d91755b47fc74f74de286b0f5cee14c9269041e6c4/soupsieve-2.8.3.tar.gz", hash = "sha256:3267f1eeea4251fb42728b6dfb746edc9acaffc4a45b27e19450b676586e8349", size = 118627, upload-time = "2026-01-20T04:27:02.457Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/46/2c/1462b1d0a634697ae9e55b3cecdcb64788e8b7d63f54d923fcd0bb140aed/soupsieve-2.8.3-py3-none-any.whl", hash = "sha256:ed64f2ba4eebeab06cc4962affce381647455978ffc1e36bb79a545b91f45a95", size = 37016, upload-time = "2026-01-20T04:27:01.012Z" }, +] + [[package]] name = "sse-starlette" version = "3.3.3" @@ -2231,6 +2785,70 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d7/c1/eb8f9debc45d3b7918a32ab756658a0904732f75e555402972246b0b8e71/tenacity-9.1.4-py3-none-any.whl", hash = "sha256:6095a360c919085f28c6527de529e76a06ad89b23659fa881ae0649b867a9d55", size = 28926, upload-time = "2026-02-07T10:45:32.24Z" }, ] +[[package]] +name = "textual" +version = "8.2.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markdown-it-py", extra = ["linkify"] }, + { name = "mdit-py-plugins" }, + { name = "platformdirs" }, + { name = "pygments" }, + { name = "rich" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/cf/2f/d44f0f12b3ddb1f0b88f7775652e99c6b5a43fd733badf4ce064bdbfef4a/textual-8.2.3.tar.gz", hash = "sha256:beea7b86b03b03558a2224f0cc35252e60ef8b0c4353b117b2f40972902d976a", size = 1848738, upload-time = "2026-04-05T09:12:45.338Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/0e/28/a81d6ce9f4804818bd1231a9a6e4d56ea84ebbe8385c49591444f0234fa2/textual-8.2.3-py3-none-any.whl", hash = "sha256:5008ac581bebf1f6fa0520404261844a231e5715fdbddd10ca73916a3af48ca2", size = 724231, upload-time = "2026-04-05T09:12:48.747Z" }, +] + +[[package]] +name = "tiktoken" +version = "0.12.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "regex" }, + { name = "requests" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/7d/ab/4d017d0f76ec3171d469d80fc03dfbb4e48a4bcaddaa831b31d526f05edc/tiktoken-0.12.0.tar.gz", hash = "sha256:b18ba7ee2b093863978fcb14f74b3707cdc8d4d4d3836853ce7ec60772139931", size = 37806, upload-time = "2025-10-06T20:22:45.419Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a4/85/be65d39d6b647c79800fd9d29241d081d4eeb06271f383bb87200d74cf76/tiktoken-0.12.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:b97f74aca0d78a1ff21b8cd9e9925714c15a9236d6ceacf5c7327c117e6e21e8", size = 1050728, upload-time = "2025-10-06T20:21:52.756Z" }, + { url = "https://files.pythonhosted.org/packages/4a/42/6573e9129bc55c9bf7300b3a35bef2c6b9117018acca0dc760ac2d93dffe/tiktoken-0.12.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:2b90f5ad190a4bb7c3eb30c5fa32e1e182ca1ca79f05e49b448438c3e225a49b", size = 994049, upload-time = "2025-10-06T20:21:53.782Z" }, + { url = "https://files.pythonhosted.org/packages/66/c5/ed88504d2f4a5fd6856990b230b56d85a777feab84e6129af0822f5d0f70/tiktoken-0.12.0-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:65b26c7a780e2139e73acc193e5c63ac754021f160df919add909c1492c0fb37", size = 1129008, upload-time = "2025-10-06T20:21:54.832Z" }, + { url = "https://files.pythonhosted.org/packages/f4/90/3dae6cc5436137ebd38944d396b5849e167896fc2073da643a49f372dc4f/tiktoken-0.12.0-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:edde1ec917dfd21c1f2f8046b86348b0f54a2c0547f68149d8600859598769ad", size = 1152665, upload-time = "2025-10-06T20:21:56.129Z" }, + { url = "https://files.pythonhosted.org/packages/a3/fe/26df24ce53ffde419a42f5f53d755b995c9318908288c17ec3f3448313a3/tiktoken-0.12.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:35a2f8ddd3824608b3d650a000c1ef71f730d0c56486845705a8248da00f9fe5", size = 1194230, upload-time = "2025-10-06T20:21:57.546Z" }, + { url = "https://files.pythonhosted.org/packages/20/cc/b064cae1a0e9fac84b0d2c46b89f4e57051a5f41324e385d10225a984c24/tiktoken-0.12.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:83d16643edb7fa2c99eff2ab7733508aae1eebb03d5dfc46f5565862810f24e3", size = 1254688, upload-time = "2025-10-06T20:21:58.619Z" }, + { url = "https://files.pythonhosted.org/packages/81/10/b8523105c590c5b8349f2587e2fdfe51a69544bd5a76295fc20f2374f470/tiktoken-0.12.0-cp312-cp312-win_amd64.whl", hash = "sha256:ffc5288f34a8bc02e1ea7047b8d041104791d2ddbf42d1e5fa07822cbffe16bd", size = 878694, upload-time = "2025-10-06T20:21:59.876Z" }, + { url = "https://files.pythonhosted.org/packages/00/61/441588ee21e6b5cdf59d6870f86beb9789e532ee9718c251b391b70c68d6/tiktoken-0.12.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:775c2c55de2310cc1bc9a3ad8826761cbdc87770e586fd7b6da7d4589e13dab3", size = 1050802, upload-time = "2025-10-06T20:22:00.96Z" }, + { url = "https://files.pythonhosted.org/packages/1f/05/dcf94486d5c5c8d34496abe271ac76c5b785507c8eae71b3708f1ad9b45a/tiktoken-0.12.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a01b12f69052fbe4b080a2cfb867c4de12c704b56178edf1d1d7b273561db160", size = 993995, upload-time = "2025-10-06T20:22:02.788Z" }, + { url = "https://files.pythonhosted.org/packages/a0/70/5163fe5359b943f8db9946b62f19be2305de8c3d78a16f629d4165e2f40e/tiktoken-0.12.0-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:01d99484dc93b129cd0964f9d34eee953f2737301f18b3c7257bf368d7615baa", size = 1128948, upload-time = "2025-10-06T20:22:03.814Z" }, + { url = "https://files.pythonhosted.org/packages/0c/da/c028aa0babf77315e1cef357d4d768800c5f8a6de04d0eac0f377cb619fa/tiktoken-0.12.0-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:4a1a4fcd021f022bfc81904a911d3df0f6543b9e7627b51411da75ff2fe7a1be", size = 1151986, upload-time = "2025-10-06T20:22:05.173Z" }, + { url = "https://files.pythonhosted.org/packages/a0/5a/886b108b766aa53e295f7216b509be95eb7d60b166049ce2c58416b25f2a/tiktoken-0.12.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:981a81e39812d57031efdc9ec59fa32b2a5a5524d20d4776574c4b4bd2e9014a", size = 1194222, upload-time = "2025-10-06T20:22:06.265Z" }, + { url = "https://files.pythonhosted.org/packages/f4/f8/4db272048397636ac7a078d22773dd2795b1becee7bc4922fe6207288d57/tiktoken-0.12.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9baf52f84a3f42eef3ff4e754a0db79a13a27921b457ca9832cf944c6be4f8f3", size = 1255097, upload-time = "2025-10-06T20:22:07.403Z" }, + { url = "https://files.pythonhosted.org/packages/8e/32/45d02e2e0ea2be3a9ed22afc47d93741247e75018aac967b713b2941f8ea/tiktoken-0.12.0-cp313-cp313-win_amd64.whl", hash = "sha256:b8a0cd0c789a61f31bf44851defbd609e8dd1e2c8589c614cc1060940ef1f697", size = 879117, upload-time = "2025-10-06T20:22:08.418Z" }, + { url = "https://files.pythonhosted.org/packages/ce/76/994fc868f88e016e6d05b0da5ac24582a14c47893f4474c3e9744283f1d5/tiktoken-0.12.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:d5f89ea5680066b68bcb797ae85219c72916c922ef0fcdd3480c7d2315ffff16", size = 1050309, upload-time = "2025-10-06T20:22:10.939Z" }, + { url = "https://files.pythonhosted.org/packages/f6/b8/57ef1456504c43a849821920d582a738a461b76a047f352f18c0b26c6516/tiktoken-0.12.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:b4e7ed1c6a7a8a60a3230965bdedba8cc58f68926b835e519341413370e0399a", size = 993712, upload-time = "2025-10-06T20:22:12.115Z" }, + { url = "https://files.pythonhosted.org/packages/72/90/13da56f664286ffbae9dbcfadcc625439142675845baa62715e49b87b68b/tiktoken-0.12.0-cp313-cp313t-manylinux_2_28_aarch64.whl", hash = "sha256:fc530a28591a2d74bce821d10b418b26a094bf33839e69042a6e86ddb7a7fb27", size = 1128725, upload-time = "2025-10-06T20:22:13.541Z" }, + { url = "https://files.pythonhosted.org/packages/05/df/4f80030d44682235bdaecd7346c90f67ae87ec8f3df4a3442cb53834f7e4/tiktoken-0.12.0-cp313-cp313t-manylinux_2_28_x86_64.whl", hash = "sha256:06a9f4f49884139013b138920a4c393aa6556b2f8f536345f11819389c703ebb", size = 1151875, upload-time = "2025-10-06T20:22:14.559Z" }, + { url = "https://files.pythonhosted.org/packages/22/1f/ae535223a8c4ef4c0c1192e3f9b82da660be9eb66b9279e95c99288e9dab/tiktoken-0.12.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:04f0e6a985d95913cabc96a741c5ffec525a2c72e9df086ff17ebe35985c800e", size = 1194451, upload-time = "2025-10-06T20:22:15.545Z" }, + { url = "https://files.pythonhosted.org/packages/78/a7/f8ead382fce0243cb625c4f266e66c27f65ae65ee9e77f59ea1653b6d730/tiktoken-0.12.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:0ee8f9ae00c41770b5f9b0bb1235474768884ae157de3beb5439ca0fd70f3e25", size = 1253794, upload-time = "2025-10-06T20:22:16.624Z" }, + { url = "https://files.pythonhosted.org/packages/93/e0/6cc82a562bc6365785a3ff0af27a2a092d57c47d7a81d9e2295d8c36f011/tiktoken-0.12.0-cp313-cp313t-win_amd64.whl", hash = "sha256:dc2dd125a62cb2b3d858484d6c614d136b5b848976794edfb63688d539b8b93f", size = 878777, upload-time = "2025-10-06T20:22:18.036Z" }, + { url = "https://files.pythonhosted.org/packages/72/05/3abc1db5d2c9aadc4d2c76fa5640134e475e58d9fbb82b5c535dc0de9b01/tiktoken-0.12.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:a90388128df3b3abeb2bfd1895b0681412a8d7dc644142519e6f0a97c2111646", size = 1050188, upload-time = "2025-10-06T20:22:19.563Z" }, + { url = "https://files.pythonhosted.org/packages/e3/7b/50c2f060412202d6c95f32b20755c7a6273543b125c0985d6fa9465105af/tiktoken-0.12.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:da900aa0ad52247d8794e307d6446bd3cdea8e192769b56276695d34d2c9aa88", size = 993978, upload-time = "2025-10-06T20:22:20.702Z" }, + { url = "https://files.pythonhosted.org/packages/14/27/bf795595a2b897e271771cd31cb847d479073497344c637966bdf2853da1/tiktoken-0.12.0-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:285ba9d73ea0d6171e7f9407039a290ca77efcdb026be7769dccc01d2c8d7fff", size = 1129271, upload-time = "2025-10-06T20:22:22.06Z" }, + { url = "https://files.pythonhosted.org/packages/f5/de/9341a6d7a8f1b448573bbf3425fa57669ac58258a667eb48a25dfe916d70/tiktoken-0.12.0-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:d186a5c60c6a0213f04a7a802264083dea1bbde92a2d4c7069e1a56630aef830", size = 1151216, upload-time = "2025-10-06T20:22:23.085Z" }, + { url = "https://files.pythonhosted.org/packages/75/0d/881866647b8d1be4d67cb24e50d0c26f9f807f994aa1510cb9ba2fe5f612/tiktoken-0.12.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:604831189bd05480f2b885ecd2d1986dc7686f609de48208ebbbddeea071fc0b", size = 1194860, upload-time = "2025-10-06T20:22:24.602Z" }, + { url = "https://files.pythonhosted.org/packages/b3/1e/b651ec3059474dab649b8d5b69f5c65cd8fcd8918568c1935bd4136c9392/tiktoken-0.12.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:8f317e8530bb3a222547b85a58583238c8f74fd7a7408305f9f63246d1a0958b", size = 1254567, upload-time = "2025-10-06T20:22:25.671Z" }, + { url = "https://files.pythonhosted.org/packages/80/57/ce64fd16ac390fafde001268c364d559447ba09b509181b2808622420eec/tiktoken-0.12.0-cp314-cp314-win_amd64.whl", hash = "sha256:399c3dd672a6406719d84442299a490420b458c44d3ae65516302a99675888f3", size = 921067, upload-time = "2025-10-06T20:22:26.753Z" }, + { url = "https://files.pythonhosted.org/packages/ac/a4/72eed53e8976a099539cdd5eb36f241987212c29629d0a52c305173e0a68/tiktoken-0.12.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:c2c714c72bc00a38ca969dae79e8266ddec999c7ceccd603cc4f0d04ccd76365", size = 1050473, upload-time = "2025-10-06T20:22:27.775Z" }, + { url = "https://files.pythonhosted.org/packages/e6/d7/0110b8f54c008466b19672c615f2168896b83706a6611ba6e47313dbc6e9/tiktoken-0.12.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:cbb9a3ba275165a2cb0f9a83f5d7025afe6b9d0ab01a22b50f0e74fee2ad253e", size = 993855, upload-time = "2025-10-06T20:22:28.799Z" }, + { url = "https://files.pythonhosted.org/packages/5f/77/4f268c41a3957c418b084dd576ea2fad2e95da0d8e1ab705372892c2ca22/tiktoken-0.12.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:dfdfaa5ffff8993a3af94d1125870b1d27aed7cb97aa7eb8c1cefdbc87dbee63", size = 1129022, upload-time = "2025-10-06T20:22:29.981Z" }, + { url = "https://files.pythonhosted.org/packages/4e/2b/fc46c90fe5028bd094cd6ee25a7db321cb91d45dc87531e2bdbb26b4867a/tiktoken-0.12.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:584c3ad3d0c74f5269906eb8a659c8bfc6144a52895d9261cdaf90a0ae5f4de0", size = 1150736, upload-time = "2025-10-06T20:22:30.996Z" }, + { url = "https://files.pythonhosted.org/packages/28/c0/3c7a39ff68022ddfd7d93f3337ad90389a342f761c4d71de99a3ccc57857/tiktoken-0.12.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:54c891b416a0e36b8e2045b12b33dd66fb34a4fe7965565f1b482da50da3e86a", size = 1194908, upload-time = "2025-10-06T20:22:32.073Z" }, + { url = "https://files.pythonhosted.org/packages/ab/0d/c1ad6f4016a3968c048545f5d9b8ffebf577774b2ede3e2e352553b685fe/tiktoken-0.12.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5edb8743b88d5be814b1a8a8854494719080c28faaa1ccbef02e87354fe71ef0", size = 1253706, upload-time = "2025-10-06T20:22:33.385Z" }, + { url = "https://files.pythonhosted.org/packages/af/df/c7891ef9d2712ad774777271d39fdef63941ffba0a9d59b7ad1fd2765e57/tiktoken-0.12.0-cp314-cp314t-win_amd64.whl", hash = "sha256:f61c0aea5565ac82e2ec50a05e02a6c44734e91b51c10510b084ea1b8e633a71", size = 920667, upload-time = "2025-10-06T20:22:34.444Z" }, +] + [[package]] name = "tokenizers" version = "0.22.2" @@ -2305,6 +2923,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" }, ] +[[package]] +name = "uc-micro-py" +version = "2.0.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/78/67/9a363818028526e2d4579334460df777115bdec1bb77c08f9db88f6389f2/uc_micro_py-2.0.0.tar.gz", hash = "sha256:c53691e495c8db60e16ffc4861a35469b0ba0821fe409a8a7a0a71864d33a811", size = 6611, upload-time = "2026-03-01T06:31:27.526Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/61/73/d21edf5b204d1467e06500080a50f79d49ef2b997c79123a536d4a17d97c/uc_micro_py-2.0.0-py3-none-any.whl", hash = "sha256:3603a3859af53e5a39bc7677713c78ea6589ff188d70f4fee165db88e22b242c", size = 6383, upload-time = "2026-03-01T06:31:26.257Z" }, +] + [[package]] name = "uncalled-for" version = "0.2.0" @@ -2314,6 +2941,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ff/7f/4320d9ce3be404e6310b915c3629fe27bf1e2f438a1a7a3cb0396e32e9a9/uncalled_for-0.2.0-py3-none-any.whl", hash = "sha256:2c0bd338faff5f930918f79e7eb9ff48290df2cb05fcc0b40a7f334e55d4d85f", size = 11351, upload-time = "2026-02-27T17:40:56.804Z" }, ] +[[package]] +name = "universal-pathlib" +version = "0.3.10" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "fsspec" }, + { name = "pathlib-abc" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/3d/6e/d997a70ee8f4c61f9a7e2f4f8af721cf072a3326848fc881b05187e52558/universal_pathlib-0.3.10.tar.gz", hash = "sha256:4487cbc90730a48cfb64f811d99e14b6faed6d738420cd5f93f59f48e6930bfb", size = 261110, upload-time = "2026-02-22T14:40:58.87Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/dd/1a/5d9a402b39ec892d856bbdd9db502ff73ce28cdf4aff72eb1ce1d6843506/universal_pathlib-0.3.10-py3-none-any.whl", hash = "sha256:dfaf2fb35683d2eb1287a3ed7b215e4d6016aa6eaf339c607023d22f90821c66", size = 83528, upload-time = "2026-02-22T14:40:57.316Z" }, +] + [[package]] name = "urllib3" version = "2.6.3" @@ -2537,6 +3177,55 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/6f/28/258ebab549c2bf3e64d2b0217b973467394a9cea8c42f70418ca2c5d0d2e/websockets-16.0-py3-none-any.whl", hash = "sha256:1637db62fad1dc833276dded54215f2c7fa46912301a24bd94d45d46a011ceec", size = 171598, upload-time = "2026-01-10T09:23:45.395Z" }, ] +[[package]] +name = "wrapt" +version = "1.17.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/95/8f/aeb76c5b46e273670962298c23e7ddde79916cb74db802131d49a85e4b7d/wrapt-1.17.3.tar.gz", hash = "sha256:f66eb08feaa410fe4eebd17f2a2c8e2e46d3476e9f8c783daa8e09e0faa666d0", size = 55547, upload-time = "2025-08-12T05:53:21.714Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9f/41/cad1aba93e752f1f9268c77270da3c469883d56e2798e7df6240dcb2287b/wrapt-1.17.3-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ab232e7fdb44cdfbf55fc3afa31bcdb0d8980b9b95c38b6405df2acb672af0e0", size = 53998, upload-time = "2025-08-12T05:51:47.138Z" }, + { url = "https://files.pythonhosted.org/packages/60/f8/096a7cc13097a1869fe44efe68dace40d2a16ecb853141394047f0780b96/wrapt-1.17.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:9baa544e6acc91130e926e8c802a17f3b16fbea0fd441b5a60f5cf2cc5c3deba", size = 39020, upload-time = "2025-08-12T05:51:35.906Z" }, + { url = "https://files.pythonhosted.org/packages/33/df/bdf864b8997aab4febb96a9ae5c124f700a5abd9b5e13d2a3214ec4be705/wrapt-1.17.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6b538e31eca1a7ea4605e44f81a48aa24c4632a277431a6ed3f328835901f4fd", size = 39098, upload-time = "2025-08-12T05:51:57.474Z" }, + { url = "https://files.pythonhosted.org/packages/9f/81/5d931d78d0eb732b95dc3ddaeeb71c8bb572fb01356e9133916cd729ecdd/wrapt-1.17.3-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:042ec3bb8f319c147b1301f2393bc19dba6e176b7da446853406d041c36c7828", size = 88036, upload-time = "2025-08-12T05:52:34.784Z" }, + { url = "https://files.pythonhosted.org/packages/ca/38/2e1785df03b3d72d34fc6252d91d9d12dc27a5c89caef3335a1bbb8908ca/wrapt-1.17.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3af60380ba0b7b5aeb329bc4e402acd25bd877e98b3727b0135cb5c2efdaefe9", size = 88156, upload-time = "2025-08-12T05:52:13.599Z" }, + { url = "https://files.pythonhosted.org/packages/b3/8b/48cdb60fe0603e34e05cffda0b2a4adab81fd43718e11111a4b0100fd7c1/wrapt-1.17.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:0b02e424deef65c9f7326d8c19220a2c9040c51dc165cddb732f16198c168396", size = 87102, upload-time = "2025-08-12T05:52:14.56Z" }, + { url = "https://files.pythonhosted.org/packages/3c/51/d81abca783b58f40a154f1b2c56db1d2d9e0d04fa2d4224e357529f57a57/wrapt-1.17.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:74afa28374a3c3a11b3b5e5fca0ae03bef8450d6aa3ab3a1e2c30e3a75d023dc", size = 87732, upload-time = "2025-08-12T05:52:36.165Z" }, + { url = "https://files.pythonhosted.org/packages/9e/b1/43b286ca1392a006d5336412d41663eeef1ad57485f3e52c767376ba7e5a/wrapt-1.17.3-cp312-cp312-win32.whl", hash = "sha256:4da9f45279fff3543c371d5ababc57a0384f70be244de7759c85a7f989cb4ebe", size = 36705, upload-time = "2025-08-12T05:53:07.123Z" }, + { url = "https://files.pythonhosted.org/packages/28/de/49493f962bd3c586ab4b88066e967aa2e0703d6ef2c43aa28cb83bf7b507/wrapt-1.17.3-cp312-cp312-win_amd64.whl", hash = "sha256:e71d5c6ebac14875668a1e90baf2ea0ef5b7ac7918355850c0908ae82bcb297c", size = 38877, upload-time = "2025-08-12T05:53:05.436Z" }, + { url = "https://files.pythonhosted.org/packages/f1/48/0f7102fe9cb1e8a5a77f80d4f0956d62d97034bbe88d33e94699f99d181d/wrapt-1.17.3-cp312-cp312-win_arm64.whl", hash = "sha256:604d076c55e2fdd4c1c03d06dc1a31b95130010517b5019db15365ec4a405fc6", size = 36885, upload-time = "2025-08-12T05:52:54.367Z" }, + { url = "https://files.pythonhosted.org/packages/fc/f6/759ece88472157acb55fc195e5b116e06730f1b651b5b314c66291729193/wrapt-1.17.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a47681378a0439215912ef542c45a783484d4dd82bac412b71e59cf9c0e1cea0", size = 54003, upload-time = "2025-08-12T05:51:48.627Z" }, + { url = "https://files.pythonhosted.org/packages/4f/a9/49940b9dc6d47027dc850c116d79b4155f15c08547d04db0f07121499347/wrapt-1.17.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:54a30837587c6ee3cd1a4d1c2ec5d24e77984d44e2f34547e2323ddb4e22eb77", size = 39025, upload-time = "2025-08-12T05:51:37.156Z" }, + { url = "https://files.pythonhosted.org/packages/45/35/6a08de0f2c96dcdd7fe464d7420ddb9a7655a6561150e5fc4da9356aeaab/wrapt-1.17.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:16ecf15d6af39246fe33e507105d67e4b81d8f8d2c6598ff7e3ca1b8a37213f7", size = 39108, upload-time = "2025-08-12T05:51:58.425Z" }, + { url = "https://files.pythonhosted.org/packages/0c/37/6faf15cfa41bf1f3dba80cd3f5ccc6622dfccb660ab26ed79f0178c7497f/wrapt-1.17.3-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6fd1ad24dc235e4ab88cda009e19bf347aabb975e44fd5c2fb22a3f6e4141277", size = 88072, upload-time = "2025-08-12T05:52:37.53Z" }, + { url = "https://files.pythonhosted.org/packages/78/f2/efe19ada4a38e4e15b6dff39c3e3f3f73f5decf901f66e6f72fe79623a06/wrapt-1.17.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ed61b7c2d49cee3c027372df5809a59d60cf1b6c2f81ee980a091f3afed6a2d", size = 88214, upload-time = "2025-08-12T05:52:15.886Z" }, + { url = "https://files.pythonhosted.org/packages/40/90/ca86701e9de1622b16e09689fc24b76f69b06bb0150990f6f4e8b0eeb576/wrapt-1.17.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:423ed5420ad5f5529db9ce89eac09c8a2f97da18eb1c870237e84c5a5c2d60aa", size = 87105, upload-time = "2025-08-12T05:52:17.914Z" }, + { url = "https://files.pythonhosted.org/packages/fd/e0/d10bd257c9a3e15cbf5523025252cc14d77468e8ed644aafb2d6f54cb95d/wrapt-1.17.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e01375f275f010fcbf7f643b4279896d04e571889b8a5b3f848423d91bf07050", size = 87766, upload-time = "2025-08-12T05:52:39.243Z" }, + { url = "https://files.pythonhosted.org/packages/e8/cf/7d848740203c7b4b27eb55dbfede11aca974a51c3d894f6cc4b865f42f58/wrapt-1.17.3-cp313-cp313-win32.whl", hash = "sha256:53e5e39ff71b3fc484df8a522c933ea2b7cdd0d5d15ae82e5b23fde87d44cbd8", size = 36711, upload-time = "2025-08-12T05:53:10.074Z" }, + { url = "https://files.pythonhosted.org/packages/57/54/35a84d0a4d23ea675994104e667ceff49227ce473ba6a59ba2c84f250b74/wrapt-1.17.3-cp313-cp313-win_amd64.whl", hash = "sha256:1f0b2f40cf341ee8cc1a97d51ff50dddb9fcc73241b9143ec74b30fc4f44f6cb", size = 38885, upload-time = "2025-08-12T05:53:08.695Z" }, + { url = "https://files.pythonhosted.org/packages/01/77/66e54407c59d7b02a3c4e0af3783168fff8e5d61def52cda8728439d86bc/wrapt-1.17.3-cp313-cp313-win_arm64.whl", hash = "sha256:7425ac3c54430f5fc5e7b6f41d41e704db073309acfc09305816bc6a0b26bb16", size = 36896, upload-time = "2025-08-12T05:52:55.34Z" }, + { url = "https://files.pythonhosted.org/packages/02/a2/cd864b2a14f20d14f4c496fab97802001560f9f41554eef6df201cd7f76c/wrapt-1.17.3-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:cf30f6e3c077c8e6a9a7809c94551203c8843e74ba0c960f4a98cd80d4665d39", size = 54132, upload-time = "2025-08-12T05:51:49.864Z" }, + { url = "https://files.pythonhosted.org/packages/d5/46/d011725b0c89e853dc44cceb738a307cde5d240d023d6d40a82d1b4e1182/wrapt-1.17.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:e228514a06843cae89621384cfe3a80418f3c04aadf8a3b14e46a7be704e4235", size = 39091, upload-time = "2025-08-12T05:51:38.935Z" }, + { url = "https://files.pythonhosted.org/packages/2e/9e/3ad852d77c35aae7ddebdbc3b6d35ec8013af7d7dddad0ad911f3d891dae/wrapt-1.17.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:5ea5eb3c0c071862997d6f3e02af1d055f381b1d25b286b9d6644b79db77657c", size = 39172, upload-time = "2025-08-12T05:51:59.365Z" }, + { url = "https://files.pythonhosted.org/packages/c3/f7/c983d2762bcce2326c317c26a6a1e7016f7eb039c27cdf5c4e30f4160f31/wrapt-1.17.3-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:281262213373b6d5e4bb4353bc36d1ba4084e6d6b5d242863721ef2bf2c2930b", size = 87163, upload-time = "2025-08-12T05:52:40.965Z" }, + { url = "https://files.pythonhosted.org/packages/e4/0f/f673f75d489c7f22d17fe0193e84b41540d962f75fce579cf6873167c29b/wrapt-1.17.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dc4a8d2b25efb6681ecacad42fca8859f88092d8732b170de6a5dddd80a1c8fa", size = 87963, upload-time = "2025-08-12T05:52:20.326Z" }, + { url = "https://files.pythonhosted.org/packages/df/61/515ad6caca68995da2fac7a6af97faab8f78ebe3bf4f761e1b77efbc47b5/wrapt-1.17.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:373342dd05b1d07d752cecbec0c41817231f29f3a89aa8b8843f7b95992ed0c7", size = 86945, upload-time = "2025-08-12T05:52:21.581Z" }, + { url = "https://files.pythonhosted.org/packages/d3/bd/4e70162ce398462a467bc09e768bee112f1412e563620adc353de9055d33/wrapt-1.17.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:d40770d7c0fd5cbed9d84b2c3f2e156431a12c9a37dc6284060fb4bec0b7ffd4", size = 86857, upload-time = "2025-08-12T05:52:43.043Z" }, + { url = "https://files.pythonhosted.org/packages/2b/b8/da8560695e9284810b8d3df8a19396a6e40e7518059584a1a394a2b35e0a/wrapt-1.17.3-cp314-cp314-win32.whl", hash = "sha256:fbd3c8319de8e1dc79d346929cd71d523622da527cca14e0c1d257e31c2b8b10", size = 37178, upload-time = "2025-08-12T05:53:12.605Z" }, + { url = "https://files.pythonhosted.org/packages/db/c8/b71eeb192c440d67a5a0449aaee2310a1a1e8eca41676046f99ed2487e9f/wrapt-1.17.3-cp314-cp314-win_amd64.whl", hash = "sha256:e1a4120ae5705f673727d3253de3ed0e016f7cd78dc463db1b31e2463e1f3cf6", size = 39310, upload-time = "2025-08-12T05:53:11.106Z" }, + { url = "https://files.pythonhosted.org/packages/45/20/2cda20fd4865fa40f86f6c46ed37a2a8356a7a2fde0773269311f2af56c7/wrapt-1.17.3-cp314-cp314-win_arm64.whl", hash = "sha256:507553480670cab08a800b9463bdb881b2edeed77dc677b0a5915e6106e91a58", size = 37266, upload-time = "2025-08-12T05:52:56.531Z" }, + { url = "https://files.pythonhosted.org/packages/77/ed/dd5cf21aec36c80443c6f900449260b80e2a65cf963668eaef3b9accce36/wrapt-1.17.3-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:ed7c635ae45cfbc1a7371f708727bf74690daedc49b4dba310590ca0bd28aa8a", size = 56544, upload-time = "2025-08-12T05:51:51.109Z" }, + { url = "https://files.pythonhosted.org/packages/8d/96/450c651cc753877ad100c7949ab4d2e2ecc4d97157e00fa8f45df682456a/wrapt-1.17.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:249f88ed15503f6492a71f01442abddd73856a0032ae860de6d75ca62eed8067", size = 40283, upload-time = "2025-08-12T05:51:39.912Z" }, + { url = "https://files.pythonhosted.org/packages/d1/86/2fcad95994d9b572db57632acb6f900695a648c3e063f2cd344b3f5c5a37/wrapt-1.17.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:5a03a38adec8066d5a37bea22f2ba6bbf39fcdefbe2d91419ab864c3fb515454", size = 40366, upload-time = "2025-08-12T05:52:00.693Z" }, + { url = "https://files.pythonhosted.org/packages/64/0e/f4472f2fdde2d4617975144311f8800ef73677a159be7fe61fa50997d6c0/wrapt-1.17.3-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:5d4478d72eb61c36e5b446e375bbc49ed002430d17cdec3cecb36993398e1a9e", size = 108571, upload-time = "2025-08-12T05:52:44.521Z" }, + { url = "https://files.pythonhosted.org/packages/cc/01/9b85a99996b0a97c8a17484684f206cbb6ba73c1ce6890ac668bcf3838fb/wrapt-1.17.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:223db574bb38637e8230eb14b185565023ab624474df94d2af18f1cdb625216f", size = 113094, upload-time = "2025-08-12T05:52:22.618Z" }, + { url = "https://files.pythonhosted.org/packages/25/02/78926c1efddcc7b3aa0bc3d6b33a822f7d898059f7cd9ace8c8318e559ef/wrapt-1.17.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e405adefb53a435f01efa7ccdec012c016b5a1d3f35459990afc39b6be4d5056", size = 110659, upload-time = "2025-08-12T05:52:24.057Z" }, + { url = "https://files.pythonhosted.org/packages/dc/ee/c414501ad518ac3e6fe184753632fe5e5ecacdcf0effc23f31c1e4f7bfcf/wrapt-1.17.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:88547535b787a6c9ce4086917b6e1d291aa8ed914fdd3a838b3539dc95c12804", size = 106946, upload-time = "2025-08-12T05:52:45.976Z" }, + { url = "https://files.pythonhosted.org/packages/be/44/a1bd64b723d13bb151d6cc91b986146a1952385e0392a78567e12149c7b4/wrapt-1.17.3-cp314-cp314t-win32.whl", hash = "sha256:41b1d2bc74c2cac6f9074df52b2efbef2b30bdfe5f40cb78f8ca22963bc62977", size = 38717, upload-time = "2025-08-12T05:53:15.214Z" }, + { url = "https://files.pythonhosted.org/packages/79/d9/7cfd5a312760ac4dd8bf0184a6ee9e43c33e47f3dadc303032ce012b8fa3/wrapt-1.17.3-cp314-cp314t-win_amd64.whl", hash = "sha256:73d496de46cd2cdbdbcce4ae4bcdb4afb6a11234a1df9c085249d55166b95116", size = 41334, upload-time = "2025-08-12T05:53:14.178Z" }, + { url = "https://files.pythonhosted.org/packages/46/78/10ad9781128ed2f99dbc474f43283b13fea8ba58723e98844367531c18e9/wrapt-1.17.3-cp314-cp314t-win_arm64.whl", hash = "sha256:f38e60678850c42461d4202739f9bf1e3a737c7ad283638251e79cc49effb6b6", size = 38471, upload-time = "2025-08-12T05:52:57.784Z" }, + { url = "https://files.pythonhosted.org/packages/1f/f6/a933bd70f98e9cf3e08167fc5cd7aaaca49147e48411c0bd5ae701bb2194/wrapt-1.17.3-py3-none-any.whl", hash = "sha256:7171ae35d2c33d326ac19dd8facb1e82e5fd04ef8c6c0e394d7af55a55051c22", size = 23591, upload-time = "2025-08-12T05:53:20.674Z" }, +] + [[package]] name = "xxhash" version = "3.6.0" @@ -2724,6 +3413,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/69/68/c8739671f5699c7dc470580a4f821ef37c32c4cb0b047ce223a7f115757f/yarl-1.23.0-py3-none-any.whl", hash = "sha256:a2df6afe50dea8ae15fa34c9f824a3ee958d785fd5d089063d960bae1daa0a3f", size = 48288, upload-time = "2026-03-01T22:07:51.388Z" }, ] +[[package]] +name = "zipfile-zstd" +version = "0.0.4" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "zstandard", marker = "python_full_version < '3.14'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f7/2a/2e0941bc0058d10ab37d8c578b94a19f611f6ae54f124140f2fb451f0932/zipfile-zstd-0.0.4.tar.gz", hash = "sha256:c1498e15b7922a3d1af0ea55df8b11b2af4e8f7e0e80e414e25d66899f7def89", size = 4603, upload-time = "2021-12-08T07:38:16.245Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b1/3a/bc3011d26bbb490741f58c28a2df559445c59e8524cbbb71ecf33db23bb7/zipfile_zstd-0.0.4-py3-none-any.whl", hash = "sha256:c8e07be35765c072eb7b1be715c89ecb248a1127b014e12a9b8ac7db2600c166", size = 4058, upload-time = "2021-12-08T07:38:14.715Z" }, +] + [[package]] name = "zipp" version = "3.23.0" From 79e08341de3bcb07b1b792f49f00b6fe7835320f Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 19 Apr 2026 11:53:20 +0700 Subject: [PATCH 403/412] fix: allow all roles to call read-only memory tools --- koan/lib/permissions.py | 14 ++++++++++++++ koan/prompts/scout.py | 12 ++++++++++++ koan/web/mcp_endpoint.py | 13 +++++++++---- tests/test_permissions.py | 4 +++- 4 files changed, 38 insertions(+), 5 deletions(-) diff --git a/koan/lib/permissions.py b/koan/lib/permissions.py index ec8f7db..5b76fb7 100644 --- a/koan/lib/permissions.py +++ b/koan/lib/permissions.py @@ -102,6 +102,14 @@ "edit", }) +# Memory query tools -- always allowed for all roles in every phase. +# A single canonical fast-path is simpler and safer than adding these +# to every role's ROLE_PERMISSIONS entry (which would diverge over time). +_UNIVERSAL_MEMORY_TOOLS: frozenset[str] = frozenset({ + "koan_memory_status", + "koan_search", +}) + # -- Orchestrator phase-specific constants ------------------------------------ _ORCHESTRATOR_SCOUT_PHASES: frozenset[str] = frozenset({ @@ -238,6 +246,12 @@ def check_permission( if tool_name in _NON_BASH_READ_TOOLS: return {"allowed": True, "reason": None} + # Memory query tools -- always allowed for all roles (scouts and executors + # need read-only memory access; placing this before the orchestrator branch + # avoids duplicating it in _check_orchestrator_permission). + if tool_name in _UNIVERSAL_MEMORY_TOOLS: + return {"allowed": True, "reason": None} + # Orchestrator uses phase-aware permission logic (handles bash phase-gating). if role == "orchestrator": return _check_orchestrator_permission(tool_name, current_phase, current_step, run_dir, tool_args) diff --git a/koan/prompts/scout.py b/koan/prompts/scout.py index 798e02f..48a6e92 100644 --- a/koan/prompts/scout.py +++ b/koan/prompts/scout.py @@ -49,6 +49,18 @@ "\n" "- All read tools (read, bash, grep, glob, find, ls) -- for reading the codebase.\n" "- `koan_complete_step` -- to advance to the next workflow step.\n" + "- `koan_memory_status`, `koan_search` -- read-only project memory queries.\n" + "\n" + "## Forbidden tools\n" + "\n" + "Your MCP tool list may advertise additional `koan_*` tools (yield,\n" + "set_phase, ask_question, request_scouts, request_executor, story\n" + "management, memorize, forget). These belong to the orchestrator.\n" + "Scouts MUST NOT call any of them -- they will be denied and the\n" + "failure will pollute your investigation. The ONLY koan tool you\n" + "call to drive the workflow is `koan_complete_step`. You do not\n" + "yield, you do not ask questions, you do not converse with the\n" + "user. Your final text response IS your handoff.\n" "\n" "## Project memory (read-only)\n" "\n" diff --git a/koan/web/mcp_endpoint.py b/koan/web/mcp_endpoint.py index a60f7e1..a6a9266 100644 --- a/koan/web/mcp_endpoint.py +++ b/koan/web/mcp_endpoint.py @@ -505,12 +505,17 @@ async def koan_yield( summary: str = "", suggestions: list[dict] | None = None, ) -> str: - """Yield to the user and wait for their reply. + """Yield to the user and wait for their reply. ORCHESTRATOR-ONLY. + + This tool is reserved for the persistent orchestrator agent. Scouts and + executors are denied by the permission fence -- if you are a subagent, + do not call this, return your findings as your final text response + instead. Blocks until the user sends a message; returns it as the tool result. - This is the sole human-in-the-loop checkpoint -- call it after finishing - an artifact and whenever you need user direction. Call in a loop for - multi-turn conversation. + For the orchestrator, this is the sole human-in-the-loop checkpoint -- + call it after finishing an artifact and whenever you need user + direction. Call in a loop for multi-turn conversation. REVIEW FEEDBACK LOOP: if the returned message begins with "I've reviewed `<path>`", the user has inspected the artifact you just diff --git a/tests/test_permissions.py b/tests/test_permissions.py index 780e4a0..f9c14e8 100644 --- a/tests/test_permissions.py +++ b/tests/test_permissions.py @@ -8,6 +8,7 @@ ROLE_PERMISSIONS, STEP_1_BLOCKED_TOOLS, WRITE_TOOLS, + _UNIVERSAL_MEMORY_TOOLS, check_permission, ) @@ -177,7 +178,8 @@ def _build_matrix(): for role in ALL_ROLES: if role == "orchestrator": continue # orchestrator uses phase-aware checks, tested separately - allowed_set = ROLE_PERMISSIONS[role] | READ_TOOLS + # _UNIVERSAL_MEMORY_TOOLS are allowed for all roles via fast-path. + allowed_set = ROLE_PERMISSIONS[role] | READ_TOOLS | _UNIVERSAL_MEMORY_TOOLS for tool in sorted(ALL_KOAN_TOOLS): expected = tool in allowed_set cases.append((role, tool, expected)) From 3da8d08b84be8be66343e2cc84cc744130274229 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 19 Apr 2026 11:53:32 +0700 Subject: [PATCH 404/412] docs: update memory notes for permission and retrieval behavior --- .../0018-behavioral-constraints-require-both-a-prompt.md | 4 ++-- .../0020-memory-retrieval-static-directive-mechanical.md | 4 ++-- .../0053-new-read-only-memory-tools-must-be-added-to.md | 8 ++++++++ 3 files changed, 12 insertions(+), 4 deletions(-) create mode 100644 .koan/memory/0053-new-read-only-memory-tools-must-be-added-to.md diff --git a/.koan/memory/0018-behavioral-constraints-require-both-a-prompt.md b/.koan/memory/0018-behavioral-constraints-require-both-a-prompt.md index 3dda3d8..8a08505 100644 --- a/.koan/memory/0018-behavioral-constraints-require-both-a-prompt.md +++ b/.koan/memory/0018-behavioral-constraints-require-both-a-prompt.md @@ -2,9 +2,9 @@ title: Behavioral constraints require both a prompt instruction and a mechanical gate type: decision created: '2026-04-16T09:00:52Z' -modified: '2026-04-16T09:00:52Z' +modified: '2026-04-18T05:06:44Z' related: - 0009-permission-fence-impractical-across-llm-backends.md --- -The koan orchestration system uses `koan/web/mcp_endpoint.py` and `koan/lib/permissions.py` to enforce behavioral constraints for subagent roles. On 2026-04-16, the architecture documentation in `docs/architecture.md` established that behavioral constraints require both a prompt instruction and a mechanical gate. The maintainer recorded the rationale: prompt instructions alone were found insufficient because LLMs can ignore them without error; mechanical gates alone were found insufficient because they produce cryptic "blocked" tool errors with no context for the model to self-correct and retry. The document identified three enforcement mechanisms: (1) the permission fence (`check_permission` in `koan/lib/permissions.py`), which blocks disallowed tool calls and returns a rejection message; (2) `validate_step_completion()`, which blocks `koan_complete_step` advancement until required pre-calls have been made; and (3) tool descriptions, which provide soft guidance only and cannot be enforced. The maintainer established the rule that any constraint mattering for correctness requires both a prompt instruction (so the LLM understands the requirement) and a mechanical gate (so non-compliance is caught and corrected rather than silently propagated). +The koan orchestration system uses `koan/web/mcp_endpoint.py` and `koan/lib/permissions.py` to enforce behavioral constraints for subagent roles. On 2026-04-16, the architecture documentation in `docs/architecture.md` established that behavioral constraints require both a prompt instruction and a mechanical gate. The maintainer recorded the rationale: prompt instructions alone were found insufficient because LLMs can ignore them without error; mechanical gates alone were found insufficient because they produce cryptic "blocked" tool errors with no context for the model to self-correct and retry. The document identified three enforcement mechanisms: (1) the permission fence (`check_permission` in `koan/lib/permissions.py`), which blocks disallowed tool calls and returns a rejection message; (2) `validate_step_completion()`, which blocks `koan_complete_step` advancement until required pre-calls have been made; and (3) tool descriptions, which provide soft guidance only and cannot be enforced. The maintainer established the rule that any constraint mattering for correctness requires both a prompt instruction (so the LLM understands the requirement) and a mechanical gate (so non-compliance is caught and corrected rather than silently propagated). Caveat recorded on 2026-04-17: the permission-fence exemplar's future is under active consideration. As documented in entry 0009, Leon found the call-level fence impractical to enforce reliably across LLM backends; Leon stated on 2026-04-17 that a final decision has not been made and that an alternative worth considering is simply not exposing the tool to the model at all (tool-vocabulary control at the MCP layer) rather than blocking calls at the handler. The underlying principle (prompt + gate) remains in force via `validate_step_completion` and similar handshake-level gates; only the permission-fence example is unsettled. diff --git a/.koan/memory/0020-memory-retrieval-static-directive-mechanical.md b/.koan/memory/0020-memory-retrieval-static-directive-mechanical.md index c48a6d9..58ce1a0 100644 --- a/.koan/memory/0020-memory-retrieval-static-directive-mechanical.md +++ b/.koan/memory/0020-memory-retrieval-static-directive-mechanical.md @@ -3,9 +3,9 @@ title: 'Memory retrieval: static-directive mechanical injection handles unknown agent tools handle known unknowns' type: decision created: '2026-04-16T09:01:12Z' -modified: '2026-04-16T09:01:12Z' +modified: '2026-04-18T05:06:31Z' related: - 0012-koan-is-dog-fooded-on-its-own-development-meta.md --- -The koan memory system, documented in `docs/memory-system.md`, implements two retrieval mechanisms. On 2026-04-16, the memory system specification established an asymmetric design: mechanical context injection (automatic, at phase boundaries) using static retrieval directives authored by the workflow designer, and agent-invoked tools (`koan_search` and `koan_reflect`) called on-demand during reasoning. The maintainer recorded the rationale: the two mechanisms were designed to solve different problems. Mechanical injection was designed to handle unknown unknowns -- knowledge the agent does not know to search for (a procedure about credential handling, a lesson about a past failure); since the agent cannot formulate a query for what it does not know exists, the injection must run without relying on agent reasoning. Agent-invoked tools were designed to handle known unknowns -- gaps the agent recognizes during reasoning and can formulate targeted queries for. The specification explicitly rejected LLM-generated retrieval directives (having the orchestrator generate directives at runtime) because the maintainer established that such directives would produce queries biased toward what the orchestrator already knows, collapsing both mechanisms into one and leaving unknown unknowns uncovered. The static directive was documented as encoding structural knowledge about each phase type's typical needs, independent of any particular agent's reasoning state. +The koan memory system, documented in `docs/memory-system.md`, implements two retrieval mechanisms. On 2026-04-16, the memory system specification established an asymmetric design: mechanical context injection (automatic, at phase boundaries) using static retrieval directives authored by the workflow designer, and agent-invoked tools called on-demand during reasoning. The maintainer recorded the rationale: the two mechanisms were designed to solve different problems. Mechanical injection was designed to handle unknown unknowns -- knowledge the agent does not know to search for (a procedure about credential handling, a lesson about a past failure); since the agent cannot formulate a query for what it does not know exists, the injection must run without relying on agent reasoning. Agent-invoked tools were designed to handle known unknowns -- gaps the agent recognizes during reasoning and can formulate targeted queries for. The specification explicitly rejected LLM-generated retrieval directives (having the orchestrator generate directives at runtime) because the maintainer established that such directives would produce queries biased toward what the orchestrator already knows, collapsing both mechanisms into one and leaving unknown unknowns uncovered. The static directive was documented as encoding structural knowledge about each phase type's typical needs, independent of any particular agent's reasoning state. Implementation status as of 2026-04-17: the mechanical injection path is wired in `koan/web/mcp_endpoint.py`, and the agent-invoked side exposes one MCP tool, `koan_search` (registered at line 1215 of that file). A second agent-invoked tool `koan_reflect` was specified in the original design -- a CLI stub exists at `koan/cli/memory.py:201` printing "not yet implemented" -- but has not been wired as an MCP tool; it remains a planned surface for reflection-style queries over the memory store. diff --git a/.koan/memory/0053-new-read-only-memory-tools-must-be-added-to.md b/.koan/memory/0053-new-read-only-memory-tools-must-be-added-to.md new file mode 100644 index 0000000..9ed6020 --- /dev/null +++ b/.koan/memory/0053-new-read-only-memory-tools-must-be-added-to.md @@ -0,0 +1,8 @@ +--- +title: New read-only memory tools must be added to _UNIVERSAL_MEMORY_TOOLS in koan/lib/permissions.py +type: procedure +created: '2026-04-18T14:36:10Z' +modified: '2026-04-18T14:36:10Z' +--- + +The permission gate in `koan/lib/permissions.py` provides a universal fast-path for read-only memory query tools via the `_UNIVERSAL_MEMORY_TOOLS` frozenset. On 2026-04-18, Leon identified that `koan_memory_status` and `koan_search` had been accidentally scoped to the orchestrator role only -- they appeared in `_ORCHESTRATOR_MEMORY_TOOLS` but were absent from the non-orchestrator `ROLE_PERMISSIONS` dicts (`scout`, `executor`, `intake`, `planner`), causing scouts and executors to be silently blocked from querying memory. Leon directed the fix: add both tools to a new `_UNIVERSAL_MEMORY_TOOLS` frozenset placed between the `_NON_BASH_READ_TOOLS` fast-path and the orchestrator branch in `check_permission()`. The resulting behavioral rule: any new read-only memory tool added to the koan MCP endpoint must also be registered in `_UNIVERSAL_MEMORY_TOOLS` to be available for all agent roles. Placing a new memory read tool only in `_ORCHESTRATOR_MEMORY_TOOLS` will silently restrict it to the orchestrator with no error. From 8f0542f56f1bb38c20562f34cde9a28c84ed1664 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 19 Apr 2026 11:53:42 +0700 Subject: [PATCH 405/412] docs: document intake step-3 summarize flow --- ...nfidence-loop-removed-unnecessary-scout.md | 7 ++- ...marize-step-step-3-extracted-to-provide.md | 16 +++++++ docs/intake-loop.md | 46 +++++++++++++------ 3 files changed, 52 insertions(+), 17 deletions(-) create mode 100644 .koan/memory/0054-intake-summarize-step-step-3-extracted-to-provide.md diff --git a/.koan/memory/0011-intake-confidence-loop-removed-unnecessary-scout.md b/.koan/memory/0011-intake-confidence-loop-removed-unnecessary-scout.md index 547f371..795e4f7 100644 --- a/.koan/memory/0011-intake-confidence-loop-removed-unnecessary-scout.md +++ b/.koan/memory/0011-intake-confidence-loop-removed-unnecessary-scout.md @@ -3,10 +3,13 @@ title: 'Intake confidence loop removed: unnecessary scout batches and intrinsic risk' type: lesson created: '2026-04-16T08:34:26Z' -modified: '2026-04-16T08:34:26Z' +modified: '2026-04-18T16:21:49Z' related: - 0002-step-first-workflow-pattern-boot-prompt-is.md - 0005-phase-trust-model-plan-review-as-designated.md +- 0013-single-cognitive-goal-per-step-prevents-simulated.md --- -The intake phase in koan (`koan/phases/intake.py`) previously included a confidence-gated loop where steps 2-4 would repeat based on a structured confidence value. Leon removed this loop in favour of the current 2-step design (Gather + Deepen), as documented in `docs/intake-loop.md` (Pitfalls section -- "Don't add a confidence loop"), confirmed in the codebase as of 2026-04-16. Leon identified three reasons for removal: (a) the loop produced unnecessary second scout batches -- repeating expensive scout runs that a focused single Deepen pass could replace; (b) the self-verification step ("Reflect") risked intrinsic self-correction without external grounding, meaning the same LLM checking its own prior reasoning rather than verifying against actual codebase files; (c) one focused pass through the Deepen step was sufficient when the step was designed to be thorough. Leon replaced the confidence gate with a design that defines phase completion by depth of understanding rather than loop iteration count, and explicitly removed per-round question limits that had previously created an implicit ceiling discouraging iterative deepening. +The intake phase in koan (koan/phases/intake.py) previously included a confidence-gated loop where steps 2-4 would repeat based on a structured confidence value. On 2026-04-12, Leon collapsed intake to a focused 2-step design (Gather + Deepen), removing the loop for three reasons: (a) it produced unnecessary second scout batches; (b) the Reflect step risked intrinsic self-correction -- the same LLM verifying its own prior reasoning rather than checking against actual codebase files; (c) a single thorough Deepen pass was sufficient when that step was well-scoped. Phase completion was redefined by depth of understanding, not iteration count. + +On 2026-04-17, Leon extracted a dedicated Summarize step from Deepen's conclusion, bringing intake to 3 steps total: Gather, Deepen, Summarize. The split applies the single-cognitive-goal-per-step principle (entry 0013): Deepen stays focused on dialogue and codebase verification; Summarize is a distinct step for synthesizing findings into a planning handoff. The confidence-loop removal rationale is unchanged -- the step count change only separates concerns that were already happening at the end of step 2. Note: docs/intake-loop.md still describes the older 2-step design as of 2026-04-18 and requires a separate update. diff --git a/.koan/memory/0054-intake-summarize-step-step-3-extracted-to-provide.md b/.koan/memory/0054-intake-summarize-step-step-3-extracted-to-provide.md new file mode 100644 index 0000000..e5cfb61 --- /dev/null +++ b/.koan/memory/0054-intake-summarize-step-step-3-extracted-to-provide.md @@ -0,0 +1,16 @@ +--- +title: Intake Summarize step (step 3) extracted to provide a clean RAG-injection anchor + at phase boundary +type: decision +created: '2026-04-18T16:28:03Z' +modified: '2026-04-18T16:28:03Z' +related: +- 0011-intake-confidence-loop-removed-unnecessary-scout.md +- 0013-single-cognitive-goal-per-step-prevents-simulated.md +- 0041-per-phase-summary-capture-rides-on-orchestrators.md +- 0045-end-of-phase-summary-must-be-a-dense-paragraph-it.md +--- + +The intake phase in koan (koan/phases/intake.py) has a dedicated step 3 (Summarize, TOTAL_STEPS = 3) that was extracted from the end of the Deepen step on 2026-04-17. On 2026-04-18, Leon confirmed the primary rationale: the RAG injection pipeline (entries 0041, 0045) captures the orchestrator's last prose turn before the first koan_yield of each phase as the phase summary. When the synthesis was embedded at the end of step 2 (Deepen), any koan_complete_step call for remaining Deepen work would follow the synthesis text, potentially displacing it as the final text before yield and leaving the RAG capture with noisy or incomplete content. + +The dedicated Summarize step forces synthesis to happen as its own distinct act immediately before the phase boundary, so the prose written between the phase-complete koan_complete_step response and the first koan_yield is an unambiguous summary -- the form the RAG pipeline expects. Secondary rationale: the single-cognitive-goal-per-step principle (entry 0013) -- Deepen stays focused on dialogue and verification; Summarize is a distinct cognitive act. Alternative rejected: embedding the summary at the end of step 2 and relying on step discipline alone, because the RAG capture mechanism has no way to enforce which portion of step 2's output is the synthesis. diff --git a/docs/intake-loop.md b/docs/intake-loop.md index d16e5ff..5e70023 100644 --- a/docs/intake-loop.md +++ b/docs/intake-loop.md @@ -1,6 +1,6 @@ # Intake Phase Design -How the intake phase gathers context in two steps, and the prompt +How the intake phase gathers context in three steps, and the prompt engineering principles that govern it. > Parent doc: [architecture.md](./architecture.md) @@ -17,18 +17,20 @@ produced downstream depends on the completeness and accuracy of what intake discovers. Gaps compound: a missed decision becomes a wrong plan becomes wrong code. -The intake phase runs a focused **two-step workflow**: gather context -(conversation + codebase orientation + scouts), then deepen understanding -through dialogue and summarize findings. +The intake phase runs a focused **three-step workflow**: gather context +(conversation + codebase orientation + scouts), deepen understanding through +dialogue and codebase verification, then synthesize findings into a handoff +summary. ### Step structure -| Step | Name | Runs | Purpose | -| ---- | ------ | ---- | -------------------------------------------------------------------------------------------------- | -| 1 | Gather | 1x | Read conversation, open obvious files (<=5), dispatch scouts. | -| 2 | Deepen | 1x | Process scout results, verify by reading files, deepen through iterative dialogue, then summarize. | +| Step | Name | Runs | Purpose | +| ---- | --------- | ---- | ------------------------------------------------------------------------ | +| 1 | Gather | 1x | Read conversation, open obvious files (<=5), dispatch scouts. | +| 2 | Deepen | 1x | Process scout results, verify by reading files, deepen through dialogue. | +| 3 | Summarize | 1x | Synthesize findings into a concise handoff summary. | -All steps advance linearly. The phase boundary after step 2 gives the user a +All steps advance linearly. The phase boundary after step 3 gives the user a natural point to review the summary and discuss next steps. --- @@ -71,17 +73,28 @@ Key properties: - **Default-ask framing**: Question-asking is the default; skipping requires triple justification. This inverts the typical LLM bias toward advancing. -The Deepen step concludes by synthesizing a concise summary covering: task +### Step 3: Summarize + +The Summarize step synthesizes findings into a concise summary covering: task scope, key codebase findings, decisions made, constraints, and open items. This summary lives in the LLM's context -- downstream phases (plan-spec, plan-review) trust it as their starting point. See [phase-trust.md](./phase-trust.md) for the trust model. +The Summarize step exists as a distinct step (rather than being folded into the +end of Deepen) for a structural reason: the RAG injection pipeline captures the +orchestrator's last prose turn before `koan_yield` at each phase boundary as +that phase's summary. Embedding the synthesis inside Deepen means subsequent +`koan_complete_step` calls could follow the synthesis text, displacing it as the +final captured turn and degrading the RAG anchor for the next phase. A dedicated +step ensures the synthesis is the last cognitive act before the phase boundary, +making the captured summary clean and unambiguous. + --- ## Phase Boundary -After step 2 completes, `get_next_step()` returns `None`, which triggers the +After step 3 completes, `get_next_step()` returns `None`, which triggers the phase boundary. The orchestrator presents suggested next phases with descriptions, and asks the user what to do next. @@ -102,12 +115,15 @@ mechanisms that address specific failure modes. ### MARP (Maximizing Operations per Step) -The two-step structure applies the MARP principle: maximize operations +The three-step structure applies the MARP principle: maximize operations per `koan_complete_step` call while minimizing planning or meta-reasoning steps. Each step does real work across multiple activities rather than -artificially separating them into sequential tool calls. The summary -(previously a separate step) is folded into the Deepen step's conclusion -because a strong model can handle both activities in a single pass. +artificially separating them into sequential tool calls. Gather combines +reading, orientation, and scout dispatch in a single step. Deepen combines +scout result processing, direct file verification, and iterative dialogue. +Summarize is a distinct step rather than being folded into Deepen because +it serves a structural role in the RAG injection pipeline (see +[Step 3: Summarize](#step-3-summarize) above). ### Iterative deepening through dialogue From 4f2e7cc408df9b632086fae46d5e5149b9c024d3 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 19 Apr 2026 11:53:56 +0700 Subject: [PATCH 406/412] feat: aggregate exploration tool calls with parsed metrics --- koan/events.py | 43 ++++- koan/projections.py | 223 ++++++++++++++++++---- koan/runners/base.py | 7 +- koan/runners/claude.py | 245 ++++++++++++++++++++++++ koan/subagent.py | 142 ++++++++++++-- tests/test_projections.py | 181 +++++++++++++++--- tests/test_streaming_aggregation.py | 276 ++++++++++++++++++++++++++++ tests/test_tool_result_parsers.py | 236 ++++++++++++++++++++++++ 8 files changed, 1271 insertions(+), 82 deletions(-) create mode 100644 tests/test_streaming_aggregation.py create mode 100644 tests/test_tool_result_parsers.py diff --git a/koan/events.py b/koan/events.py index 09a49bc..731093d 100644 --- a/koan/events.py +++ b/koan/events.py @@ -110,8 +110,11 @@ def build_tool_stopped(call_id: str, tool: str, summary: str = "") -> dict: # -- Typed tool event builders (recognized tools with extracted metadata) ----- -def build_tool_read(call_id: str, file: str, lines: str = "") -> dict: - return {"call_id": call_id, "tool": "read", "file": file, "lines": lines} +def build_tool_read(call_id: str, file: str, lines: str = "", ts_ms: int = 0) -> dict: + return { + "call_id": call_id, "tool": "read", "file": file, "lines": lines, + "ts_ms": ts_ms, + } def build_tool_write(call_id: str, file: str) -> dict: @@ -126,25 +129,51 @@ def build_tool_bash(call_id: str, command: str) -> dict: return {"call_id": call_id, "tool": "bash", "command": command} -def build_tool_grep(call_id: str, pattern: str) -> dict: - return {"call_id": call_id, "tool": "grep", "pattern": pattern} +def build_tool_grep(call_id: str, pattern: str, ts_ms: int = 0) -> dict: + return { + "call_id": call_id, "tool": "grep", "pattern": pattern, + "ts_ms": ts_ms, + } -def build_tool_ls(call_id: str, path: str) -> dict: - return {"call_id": call_id, "tool": "ls", "path": path} +def build_tool_ls(call_id: str, path: str, ts_ms: int = 0) -> dict: + return { + "call_id": call_id, "tool": "ls", "path": path, + "ts_ms": ts_ms, + } def build_tool_completed( call_id: str, tool: str, result: str | None = None, + ts_ms: int = 0, ) -> dict: - payload: dict = {"call_id": call_id, "tool": tool} + payload: dict = {"call_id": call_id, "tool": tool, "ts_ms": ts_ms} if result is not None: payload["result"] = result return payload +def build_tool_result_captured( + call_id: str, + tool: str, + metrics: dict | None = None, +) -> dict: + """Build a tool_result_captured event. + + Emitted by the runner layer after it has parsed a tool_result block from + a user message in the model's stream. `metrics` is a tool-family-specific + dict that the fold attaches to the matching aggregate child. When the + runner parser could not interpret the result, metrics is None and the + fold leaves the child's metric fields unchanged. + """ + payload: dict = {"call_id": call_id, "tool": tool} + if metrics is not None: + payload["metrics"] = metrics + return payload + + def build_artifact_diff( old: dict[str, dict], new_artifacts: list[dict], diff --git a/koan/projections.py b/koan/projections.py index 015b783..00d5e9f 100644 --- a/koan/projections.py +++ b/koan/projections.py @@ -52,6 +52,7 @@ "tool_bash", "tool_grep", "tool_ls", + "tool_result_captured", "thinking", "stream_delta", "stream_cleared", @@ -148,15 +149,10 @@ class UserMessageEntry(KoanBaseModel): timestamp_ms: int class BaseToolEntry(KoanBaseModel): - """Shared fields for all tool entries.""" + """Shared fields for all tool entries and aggregate children.""" call_id: str # unique per tool invocation in_flight: bool # True until tool_completed -class ToolReadEntry(BaseToolEntry): - type: Literal["tool_read"] = "tool_read" - file: str # path that was read - lines: str = "" # line range, e.g. "1-50" - class ToolWriteEntry(BaseToolEntry): type: Literal["tool_write"] = "tool_write" file: str # path that was created or overwritten @@ -169,20 +165,61 @@ class ToolBashEntry(BaseToolEntry): type: Literal["tool_bash"] = "tool_bash" command: str # shell command executed -class ToolGrepEntry(BaseToolEntry): - type: Literal["tool_grep"] = "tool_grep" - pattern: str # search pattern - -class ToolLsEntry(BaseToolEntry): - type: Literal["tool_ls"] = "tool_ls" - path: str # directory listed - class ToolGenericEntry(BaseToolEntry): """Catch-all for tools without a typed variant (e.g. custom MCP tools).""" type: Literal["tool_generic"] = "tool_generic" tool_name: str # original tool name from the LLM summary: str = "" # human-readable one-liner from the runner parser +# --------------------------------------------------------------------------- +# Aggregate children — exploration tools (read, grep, ls) never appear as +# top-level ConversationEntry values. They live only inside a ToolAggregateEntry. +# --------------------------------------------------------------------------- + +class AggregateReadChild(BaseToolEntry): + tool: Literal["read"] = "read" + file: str # path that was read + lines: str = "" # line range, e.g. "1-50" + started_at_ms: int = 0 # creation timestamp + completed_at_ms: int | None = None # set by tool_completed + lines_read: int | None = None # attached by tool_result_captured + bytes_read: int | None = None # attached by tool_result_captured + +class AggregateGrepChild(BaseToolEntry): + tool: Literal["grep"] = "grep" + pattern: str # search pattern + started_at_ms: int = 0 + completed_at_ms: int | None = None + matches: int | None = None # attached by tool_result_captured + files_matched: int | None = None # attached by tool_result_captured + +class AggregateLsChild(BaseToolEntry): + tool: Literal["ls"] = "ls" + path: str # directory listed + started_at_ms: int = 0 + completed_at_ms: int | None = None + entries: int | None = None # attached by tool_result_captured + directories: int | None = None # attached by tool_result_captured + +AggregateChild = Annotated[ + AggregateReadChild | AggregateGrepChild | AggregateLsChild, + Field(discriminator="tool"), +] + +class ToolAggregateEntry(KoanBaseModel): + """A run of consecutive exploration tool calls (read, grep, ls). + + Created when the first exploration tool in a run arrives; grown as + subsequent consecutive exploration tools arrive; left alone once any + other entry type intervenes. Single-child aggregates are normal — the + frontend renders one child as a ToolCallRow and 2+ children as a + ToolAggregateCard. Active/elapsed state is derived from children at + render time, not stored here. + """ + type: Literal["tool_aggregate"] = "tool_aggregate" + children: list[AggregateChild] = [] + started_at_ms: int = 0 # timestamp of the first child's creation + class DebugStepGuidanceEntry(KoanBaseModel): """Step guidance prompt shown in --debug mode.""" type: Literal["debug_step_guidance"] = "debug_step_guidance" @@ -214,8 +251,8 @@ class ActiveYield(KoanBaseModel): ConversationEntry = Annotated[ ThinkingEntry | TextEntry | StepEntry | UserMessageEntry | - ToolReadEntry | ToolWriteEntry | ToolEditEntry | - ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry | + ToolWriteEntry | ToolEditEntry | ToolBashEntry | ToolGenericEntry | + ToolAggregateEntry | DebugStepGuidanceEntry | PhaseBoundaryEntry | YieldEntry, Field(discriminator="type"), ] @@ -417,6 +454,35 @@ def _flush_pending_thinking(conv: Conversation) -> Conversation: }) +def _append_exploration_child( + conv: Conversation, + child: AggregateChild, + ts_ms: int, +) -> Conversation: + """Append an exploration-tool child to the trailing aggregate, or start a new one. + + Always flushes pending text/thinking first — exploration tools appear in the + same stream as prose, so any in-progress prose must close out before a tool + entry lands. After the flush, if the last entry is a ToolAggregateEntry the + child is appended to it; otherwise a new ToolAggregateEntry is created. The + existing aggregate's started_at_ms is preserved; only the children list grows. + """ + flushed = _flush_conversation(conv) + entries = list(flushed.entries) + if entries and isinstance(entries[-1], ToolAggregateEntry): + aggregate = entries[-1] + grown = aggregate.model_copy(update={ + "children": [*aggregate.children, child], + }) + entries[-1] = grown + else: + entries.append(ToolAggregateEntry( + children=[child], + started_at_ms=ts_ms, + )) + return flushed.model_copy(update={"entries": entries}) + + def _get_agent(run: Run, agent_id: str | None) -> Agent | None: if not agent_id or run is None: return None @@ -797,16 +863,15 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: file = payload.get("file", "") lines = payload.get("lines", "") last_tool = f"read {file}:{lines}" if lines else f"read {file}" - new_conv = _flush_conversation(agent.conversation) - new_entry = ToolReadEntry( + ts_ms = payload.get("ts_ms", 0) + child = AggregateReadChild( call_id=payload.get("call_id", ""), in_flight=True, file=file, lines=lines, + started_at_ms=ts_ms, ) - new_conv = new_conv.model_copy(update={ - "entries": [*new_conv.entries, new_entry], - }) + new_conv = _append_exploration_child(agent.conversation, child, ts_ms) return projection.model_copy(update={ "run": _update_agent_conversation(projection.run, agent_id, new_conv, last_tool=last_tool), @@ -882,15 +947,14 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: if agent is None: return projection pattern = payload.get("pattern", "") - new_conv = _flush_conversation(agent.conversation) - new_entry = ToolGrepEntry( + ts_ms = payload.get("ts_ms", 0) + child = AggregateGrepChild( call_id=payload.get("call_id", ""), in_flight=True, pattern=pattern, + started_at_ms=ts_ms, ) - new_conv = new_conv.model_copy(update={ - "entries": [*new_conv.entries, new_entry], - }) + new_conv = _append_exploration_child(agent.conversation, child, ts_ms) return projection.model_copy(update={ "run": _update_agent_conversation(projection.run, agent_id, new_conv, last_tool=f"grep {pattern}"), @@ -903,15 +967,14 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: if agent is None: return projection path = payload.get("path", "") - new_conv = _flush_conversation(agent.conversation) - new_entry = ToolLsEntry( + ts_ms = payload.get("ts_ms", 0) + child = AggregateLsChild( call_id=payload.get("call_id", ""), in_flight=True, path=path, + started_at_ms=ts_ms, ) - new_conv = new_conv.model_copy(update={ - "entries": [*new_conv.entries, new_entry], - }) + new_conv = _append_exploration_child(agent.conversation, child, ts_ms) return projection.model_copy(update={ "run": _update_agent_conversation(projection.run, agent_id, new_conv, last_tool=f"ls {path}"), @@ -924,13 +987,107 @@ def fold(projection: Projection, event: VersionedEvent) -> Projection: if agent is None: return projection call_id = payload.get("call_id", "") - # Scan entries for the matching in-flight tool entry and mark it done + ts_ms = payload.get("ts_ms", 0) + # Scan two levels: top-level tool entries (bash/write/edit/generic) + # and aggregate children (read/grep/ls). A single tool_completed + # event may target either — the runner does not know which. new_entries = [] + found = False for entry in agent.conversation.entries: - if isinstance(entry, BaseToolEntry) and entry.call_id == call_id: + if ( + isinstance(entry, BaseToolEntry) + and entry.call_id == call_id + and not isinstance(entry, ToolAggregateEntry) + ): new_entries.append(entry.model_copy(update={"in_flight": False})) + found = True + elif isinstance(entry, ToolAggregateEntry): + new_children = [] + child_found = False + for child in entry.children: + if child.call_id == call_id: + new_children.append(child.model_copy(update={ + "in_flight": False, + "completed_at_ms": ts_ms or None, + })) + child_found = True + else: + new_children.append(child) + if child_found: + found = True + new_entries.append(entry.model_copy(update={"children": new_children})) + else: + new_entries.append(entry) + else: + new_entries.append(entry) + if not found: + log.warning( + "fold: tool_completed for unknown call_id=%r agent=%r", + call_id, agent_id, + ) + return projection + new_conv = agent.conversation.model_copy(update={"entries": new_entries}) + return projection.model_copy(update={ + "run": _update_agent_conversation(projection.run, agent_id, new_conv), + }) + + case "tool_result_captured": + if projection.run is None or not agent_id: + return projection + agent = projection.run.agents.get(agent_id) + if agent is None: + return projection + call_id = payload.get("call_id", "") + metrics = payload.get("metrics") + if not metrics or not isinstance(metrics, dict): + # No parsed metrics to attach; fold is a no-op. Runner emits + # these even when parsing failed so the event trail stays + # symmetric, but there is nothing for the projection to do. + return projection + new_entries = [] + found = False + for entry in agent.conversation.entries: + if not isinstance(entry, ToolAggregateEntry): + new_entries.append(entry) + continue + new_children = [] + child_found = False + for child in entry.children: + if child.call_id != call_id: + new_children.append(child) + continue + update: dict = {} + if isinstance(child, AggregateReadChild): + if "lines_read" in metrics: + update["lines_read"] = metrics["lines_read"] + if "bytes_read" in metrics: + update["bytes_read"] = metrics["bytes_read"] + elif isinstance(child, AggregateGrepChild): + if "matches" in metrics: + update["matches"] = metrics["matches"] + if "files_matched" in metrics: + update["files_matched"] = metrics["files_matched"] + elif isinstance(child, AggregateLsChild): + if "entries" in metrics: + update["entries"] = metrics["entries"] + if "directories" in metrics: + update["directories"] = metrics["directories"] + if update: + new_children.append(child.model_copy(update=update)) + else: + new_children.append(child) + child_found = True + if child_found: + found = True + new_entries.append(entry.model_copy(update={"children": new_children})) else: new_entries.append(entry) + if not found: + log.warning( + "fold: tool_result_captured for unknown call_id=%r agent=%r", + call_id, agent_id, + ) + return projection new_conv = agent.conversation.model_copy(update={"entries": new_entries}) return projection.model_copy(update={ "run": _update_agent_conversation(projection.run, agent_id, new_conv), diff --git a/koan/runners/base.py b/koan/runners/base.py index 5677ece..2c0c358 100644 --- a/koan/runners/base.py +++ b/koan/runners/base.py @@ -13,7 +13,7 @@ class StreamEvent: type: Literal[ "token_delta", "turn_complete", "tool_call", "thinking", "assistant_text", - "tool_start", "tool_input_delta", "tool_stop", + "tool_start", "tool_input_delta", "tool_stop", "tool_result", ] content: str | None = None is_thinking: bool = False @@ -22,6 +22,11 @@ class StreamEvent: summary: str | None = None tool_use_id: str | None = None block_index: int | None = None + # Populated for tool_result events: tool-family-specific metrics parsed + # from the model's tool_result block content. None when the runner could + # not interpret the result; the consumer treats this as "no metrics" and + # leaves projection state unchanged for that call_id. + metrics: dict | None = None @dataclass(kw_only=True) diff --git a/koan/runners/claude.py b/koan/runners/claude.py index f75033f..058f5f5 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -102,6 +102,11 @@ def __init__(self, *, subagent_dir: str) -> None: self.subagent_dir = subagent_dir self._saw_stream_events = False self._tool_accumulators: dict[int, _ToolUseAccumulator] = {} + # Map tool_use_id -> canonical tool_name for exploration tools (read, + # grep, ls). Populated when a tool_use block is emitted; drained when + # the matching tool_result block arrives. Only these three tools are + # tracked because only they have result parsers in this scope. + self._exploration_tool_by_id: dict[str, str] = {} def list_models(self, binary: str) -> list[ModelInfo]: return [ @@ -186,6 +191,8 @@ def parse_stream_event(self, line: str) -> list[StreamEvent]: return self._parse_stream_event(data) if evt_type == "assistant": return self._parse_assistant(data) + if evt_type == "user": + return self._parse_user(data) if evt_type == "result": evt = self._parse_result(data) return [evt] if evt is not None else [] @@ -217,6 +224,8 @@ def _parse_stream_event(self, data: dict) -> list[StreamEvent]: raw_name=raw_name, tool_use_id=tool_use_id, ) + if tool_use_id and canonical in ("read", "grep", "ls"): + self._exploration_tool_by_id[tool_use_id] = canonical self._saw_stream_events = True return [StreamEvent( type="tool_start", @@ -295,11 +304,15 @@ def _parse_assistant(self, data: dict) -> list[StreamEvent]: if canonical in KOAN_MCP_TOOLS: continue args = block.get("input") or {} + tool_use_id = block.get("id") or None + if tool_use_id and canonical in ("read", "grep", "ls"): + self._exploration_tool_by_id[tool_use_id] = canonical events.append(StreamEvent( type="tool_call", tool_name=canonical, tool_args=args, summary=_extract_tool_summary(canonical or "", args), + tool_use_id=tool_use_id, )) # text and thinking blocks are streamed incrementally via # stream_event deltas (--include-partial-messages). Only @@ -325,3 +338,235 @@ def _parse_result(self, data: dict) -> StreamEvent | None: if subtype == "success": return StreamEvent(type="turn_complete", content=data.get("result")) return StreamEvent(type="turn_complete") + + def _parse_user(self, data: dict) -> list[StreamEvent]: + """Extract tool_result blocks from a user message. + + Emits one StreamEvent(type='tool_result', ...) per tool_result block + whose originating tool was a tracked exploration tool (read/grep/ls). + Non-exploration tool_results are ignored — the existing tool_completed + event flow is enough for them, and we have no metrics parser. + """ + msg = data.get("message") + if isinstance(msg, dict): + blocks = msg.get("content") + else: + blocks = data.get("content") + if not isinstance(blocks, list): + return [] + + events: list[StreamEvent] = [] + for block in blocks: + if not isinstance(block, dict): + continue + if block.get("type") != "tool_result": + continue + tool_use_id = block.get("tool_use_id") or "" + tool_name = self._exploration_tool_by_id.pop(tool_use_id, None) + if tool_name is None: + continue + text = _tool_result_text(block.get("content")) + metrics: dict | None + if tool_name == "read": + metrics = _parse_read_result(text) + elif tool_name == "grep": + metrics = _parse_grep_result(text) + elif tool_name == "ls": + metrics = _parse_ls_result(text) + else: + metrics = None + events.append(StreamEvent( + type="tool_result", + tool_name=tool_name, + tool_use_id=tool_use_id, + metrics=metrics, + )) + return events + + +# --------------------------------------------------------------------------- +# Tool-result parsers +# --------------------------------------------------------------------------- + +def _tool_result_text(content: object) -> str: + """Extract text payload from a tool_result block's `content` field. + + content is usually a string, but Anthropic's API occasionally sends a list + of content blocks (e.g. [{"type":"text","text":"..."}]). Handle both. + """ + if isinstance(content, str): + return content + if isinstance(content, list): + parts: list[str] = [] + for item in content: + if isinstance(item, dict) and item.get("type") == "text": + parts.append(item.get("text") or "") + elif isinstance(item, str): + parts.append(item) + return "".join(parts) + return "" + + +def _parse_read_result(text: str) -> dict | None: + """Parse Claude's Read tool output. + + Format is numbered-line, e.g.: + + 1\tfirst line\n2\tsecond line\n... + + There may also be a system-reminder trailer ('<system-reminder>...') that + is not part of the file content and should be excluded from byte counts. + Line count is the number of numbered lines; byte count is the sum of the + raw content after the tab separator on each line. + """ + if not text: + return None + # Strip trailing system-reminder block if present. + sr_idx = text.find("<system-reminder>") + if sr_idx != -1: + text = text[:sr_idx] + lines = 0 + byte_total = 0 + any_numbered = False + for raw_line in text.splitlines(): + # Numbered-line format: optional whitespace + digits + tab + content. + # Lines that don't match this shape (e.g. a truncation notice) are + # skipped rather than counted. + stripped = raw_line.lstrip() + tab_idx = stripped.find("\t") + if tab_idx == -1: + continue + prefix = stripped[:tab_idx] + if not prefix.isdigit(): + continue + any_numbered = True + content = stripped[tab_idx + 1:] + lines += 1 + byte_total += len(content.encode("utf-8")) + if not any_numbered: + return None + return {"lines_read": lines, "bytes_read": byte_total} + + +def _parse_grep_result(text: str) -> dict | None: + """Parse Claude's Grep tool output, across its several output modes. + + Common shapes: + - files_with_matches mode: `path\npath\n...` + - content mode: `path:lineno:match` (possibly with `-` context) + - count mode: `path:count\npath:count\n...` + - summary line: `Found N matches in M files` + + Returns None when the shape is unrecognized — we would rather emit no + metrics than a wrong count. + """ + if not text: + return None + text = text.strip() + if not text: + return None + + # Strip trailing system-reminder block if present (defensive). + sr_idx = text.find("<system-reminder>") + if sr_idx != -1: + text = text[:sr_idx].rstrip() + if not text: + return None + + # Summary shape first — Claude sometimes emits "Found N matches..." or + # "Found N files..." at the top of content-mode output. + first_line = text.splitlines()[0] if text else "" + if first_line.lower().startswith("found "): + # "Found 42 matches in 6 files" or similar. + import re + m = re.search(r"found\s+(\d+)\s+matches?(?:\s+in\s+(\d+)\s+files?)?", first_line, re.IGNORECASE) + if m: + matches = int(m.group(1)) + files = int(m.group(2)) if m.group(2) else None + result: dict = {"matches": matches} + if files is not None: + result["files_matched"] = files + return result + m = re.search(r"found\s+(\d+)\s+files?", first_line, re.IGNORECASE) + if m: + return {"matches": int(m.group(1)), "files_matched": int(m.group(1))} + + lines = [ln for ln in text.splitlines() if ln.strip()] + if not lines: + return None + + # count mode: every line looks like "path:<digits>" + if all(":" in ln and ln.rsplit(":", 1)[-1].strip().isdigit() for ln in lines): + total = sum(int(ln.rsplit(":", 1)[-1].strip()) for ln in lines) + return {"matches": total, "files_matched": len(lines)} + + # content mode heuristic: lines shaped path:lineno:... (lineno is digits) + content_mode = True + files_seen: set[str] = set() + match_count = 0 + for ln in lines: + parts = ln.split(":", 2) + if len(parts) >= 3 and parts[1].strip().isdigit(): + files_seen.add(parts[0]) + match_count += 1 + else: + content_mode = False + break + if content_mode and match_count > 0: + return {"matches": match_count, "files_matched": len(files_seen)} + + # files_with_matches mode: each non-blank line is a distinct path. + # Skip obvious non-path shapes (lines containing colons where the second + # segment isn't a digit we couldn't parse) — treat as unknown. + if all(":" not in ln or not ln.split(":", 1)[-1][:1].isdigit() for ln in lines): + n = len(lines) + return {"matches": n, "files_matched": n} + + return None + + +def _parse_ls_result(text: str) -> dict | None: + """Parse Claude's LS tool output. + + Format is a tree-like listing with 2-space indentation and trailing '/' + on directories: + + - /path/to/dir/ + - file1.py + - subdir/ + - nested.py + + The first line (the un-indented parent path) is the header and is not + counted. Indented '- NAME' lines are counted as entries; entries ending + in '/' additionally count as directories. + """ + if not text: + return None + # Strip trailing system-reminder block if present. + sr_idx = text.find("<system-reminder>") + if sr_idx != -1: + text = text[:sr_idx] + entries = 0 + directories = 0 + for raw_line in text.splitlines(): + line = raw_line.rstrip() + if not line: + continue + # Count the number of leading spaces to distinguish indented leaves + # (entries) from the un-indented header (parent path). + stripped = line.lstrip(" ") + indent = len(line) - len(stripped) + if not stripped.startswith("- "): + continue + if indent == 0: + # Header line (parent path) — not an entry. + continue + name = stripped[2:].strip() + if not name: + continue + entries += 1 + if name.endswith("/"): + directories += 1 + if entries == 0: + return None + return {"entries": entries, "directories": directories} diff --git a/koan/subagent.py b/koan/subagent.py index cb6cba4..c3bffcb 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -5,6 +5,7 @@ import asyncio import json import os +import time import uuid from dataclasses import dataclass from pathlib import Path @@ -26,6 +27,7 @@ build_tool_grep, build_tool_ls, build_tool_read, + build_tool_result_captured, build_tool_started, build_tool_stopped, build_tool_write, @@ -43,6 +45,52 @@ log = get_logger("subagent") + +def _emit_exploration_tool_completion( + store, + agent_id: str, + call_id: str, + tool_name: str, + summary: str, + now_ms: int, +) -> None: + """Emit the typed projection event + tool_completed for a streaming read/grep/ls. + + Called from stream_stdout's tool_stop handler when Claude's streaming path + finishes an exploration tool. The args are finalized at tool_stop, so this + helper can create the aggregate child and close it in one step. Child + metric fields stay None until a matching tool_result_captured arrives + from a later user message. + """ + if tool_name == "read": + file_part, lines_part = summary, "" + if ":" in summary: + head, tail = summary.rsplit(":", 1) + if tail and (tail[0].isdigit() or "-" in tail): + file_part, lines_part = head, tail + store.push_event( + "tool_read", + build_tool_read(call_id, file_part, lines_part, ts_ms=now_ms), + agent_id=agent_id, + ) + elif tool_name == "grep": + store.push_event( + "tool_grep", + build_tool_grep(call_id, summary, ts_ms=now_ms), + agent_id=agent_id, + ) + else: # ls + store.push_event( + "tool_ls", + build_tool_ls(call_id, summary, ts_ms=now_ms), + agent_id=agent_id, + ) + store.push_event( + "tool_completed", + build_tool_completed(call_id, tool_name, ts_ms=now_ms), + agent_id=agent_id, + ) + # -- Tool whitelists (Claude Code --tools) ------------------------------------- # # Agents should not have access to tools they are never intended to need. @@ -269,6 +317,9 @@ async def stream_stdout(): last_tool_name: str | None = None last_call_id: str | None = None streaming_call_ids: dict[int, tuple[str, str]] = {} + # Map Claude's tool_use_id -> our local call_id so that later + # tool_result events can be attributed to the correct projection entry. + call_id_by_tool_use_id: dict[str, str] = {} async for raw in proc.stdout: line = raw.decode("utf-8", errors="replace").rstrip("\n") @@ -293,7 +344,10 @@ async def stream_stdout(): if ev.type in ("token_delta", "thinking") and last_call_id is not None: store.push_event( "tool_completed", - build_tool_completed(last_call_id, last_tool_name), + build_tool_completed( + last_call_id, last_tool_name, + ts_ms=int(time.time() * 1000), + ), agent_id=agent_id, ) last_call_id = None @@ -303,7 +357,10 @@ async def stream_stdout(): if last_call_id is not None and last_tool_name is not None: store.push_event( "tool_completed", - build_tool_completed(last_call_id, last_tool_name), + build_tool_completed( + last_call_id, last_tool_name, + ts_ms=int(time.time() * 1000), + ), agent_id=agent_id, ) last_call_id = None @@ -312,11 +369,22 @@ async def stream_stdout(): tool_name = ev.tool_name or "tool" block_idx = ev.block_index if ev.block_index is not None else -1 streaming_call_ids[block_idx] = (call_id, tool_name) - store.push_event( - "tool_started", - build_tool_started(call_id, tool_name), - agent_id=agent_id, - ) + if tool_name in ("read", "grep", "ls"): + # Exploration tools defer their projection emission to + # tool_stop, where the full args are available. Capture + # the tool_use_id → call_id mapping now so a later + # tool_result block can find its aggregate child. + if ev.tool_use_id: + call_id_by_tool_use_id[ev.tool_use_id] = call_id + else: + # Non-exploration tools (bash/write/edit/custom) keep + # the ToolGenericEntry flow — tool_started creates the + # entry, tool_stopped attaches the summary. + store.push_event( + "tool_started", + build_tool_started(call_id, tool_name), + agent_id=agent_id, + ) elif ev.type == "tool_input_delta": pass elif ev.type == "tool_stop": @@ -325,11 +393,17 @@ async def stream_stdout(): if pair is not None: call_id, tool_name = pair summary = ev.summary or "" - store.push_event( - "tool_stopped", - build_tool_stopped(call_id, tool_name, summary), - agent_id=agent_id, - ) + if tool_name in ("read", "grep", "ls"): + _emit_exploration_tool_completion( + store, agent_id, call_id, tool_name, summary, + now_ms=int(time.time() * 1000), + ) + else: + store.push_event( + "tool_stopped", + build_tool_stopped(call_id, tool_name, summary), + agent_id=agent_id, + ) elif ev.type == "token_delta": agent.token_count["received"] = agent.token_count.get("received", 0) + len(ev.content or "") store.push_event("stream_delta", {"delta": ev.content or ""}, agent_id=agent_id) @@ -342,21 +416,29 @@ async def stream_stdout(): if last_call_id is not None and last_tool_name is not None: store.push_event( "tool_completed", - build_tool_completed(last_call_id, last_tool_name), + build_tool_completed( + last_call_id, last_tool_name, + ts_ms=int(time.time() * 1000), + ), agent_id=agent_id, ) call_id = str(uuid.uuid4()) tool_name = ev.tool_name or "tool" summary = ev.summary or "" + now_ms = int(time.time() * 1000) if tool_name == "read": file_part, lines_part = summary, "" if ":" in summary: head, tail = summary.rsplit(":", 1) if tail and (tail[0].isdigit() or "-" in tail): file_part, lines_part = head, tail + # tool_use_id lets tool_result_captured match this call + # later even though the call_id we assigned is local. + if ev.tool_use_id: + call_id_by_tool_use_id[ev.tool_use_id] = call_id store.push_event( "tool_read", - build_tool_read(call_id, file_part, lines_part), + build_tool_read(call_id, file_part, lines_part, ts_ms=now_ms), agent_id=agent_id, ) elif tool_name == "write": @@ -366,9 +448,21 @@ async def stream_stdout(): elif tool_name == "bash": store.push_event("tool_bash", build_tool_bash(call_id, summary), agent_id=agent_id) elif tool_name == "grep": - store.push_event("tool_grep", build_tool_grep(call_id, summary), agent_id=agent_id) + if ev.tool_use_id: + call_id_by_tool_use_id[ev.tool_use_id] = call_id + store.push_event( + "tool_grep", + build_tool_grep(call_id, summary, ts_ms=now_ms), + agent_id=agent_id, + ) elif tool_name == "ls": - store.push_event("tool_ls", build_tool_ls(call_id, summary), agent_id=agent_id) + if ev.tool_use_id: + call_id_by_tool_use_id[ev.tool_use_id] = call_id + store.push_event( + "tool_ls", + build_tool_ls(call_id, summary, ts_ms=now_ms), + agent_id=agent_id, + ) else: store.push_event( "tool_called", @@ -377,6 +471,22 @@ async def stream_stdout(): ) last_call_id = call_id last_tool_name = tool_name + elif ev.type == "tool_result": + # Runner parsed a tool_result block from a user message. + # Map the LLM's tool_use_id back to our local call_id and + # emit a projection event carrying the parsed metrics. + tool_use_id = ev.tool_use_id or "" + cid = call_id_by_tool_use_id.get(tool_use_id) + if cid is not None: + store.push_event( + "tool_result_captured", + build_tool_result_captured( + cid, + ev.tool_name or "", + metrics=ev.metrics, + ), + agent_id=agent_id, + ) elif ev.type == "turn_complete": pass diff --git a/tests/test_projections.py b/tests/test_projections.py index bb57b8b..ae77906 100644 --- a/tests/test_projections.py +++ b/tests/test_projections.py @@ -10,6 +10,9 @@ from koan.projections import ( Agent, + AggregateGrepChild, + AggregateLsChild, + AggregateReadChild, ArtifactInfo, BaseToolEntry, Conversation, @@ -23,12 +26,10 @@ StepEntry, TextEntry, ThinkingEntry, + ToolAggregateEntry, ToolBashEntry, ToolEditEntry, ToolGenericEntry, - ToolGrepEntry, - ToolLsEntry, - ToolReadEntry, ToolWriteEntry, VersionedEvent, fold, @@ -352,18 +353,62 @@ def test_agent_step_advanced_unknown_agent_noop(self): class TestFoldTools: - def test_tool_read_appends_entry(self): + def test_tool_read_creates_aggregate_with_one_child(self): p = _proj_with_primary("a1") - r = fold(p, _e("tool_read", {"call_id": "c1", "file": "/foo.py", "lines": "1-10"}, agent_id="a1")) + r = fold(p, _e("tool_read", { + "call_id": "c1", "file": "/foo.py", "lines": "1-10", "ts_ms": 1000, + }, agent_id="a1")) conv = r.run.agents["a1"].conversation assert len(conv.entries) == 1 - entry = conv.entries[0] - assert isinstance(entry, ToolReadEntry) - assert entry.file == "/foo.py" - assert entry.lines == "1-10" - assert entry.in_flight is True + agg = conv.entries[0] + assert isinstance(agg, ToolAggregateEntry) + assert agg.started_at_ms == 1000 + assert len(agg.children) == 1 + child = agg.children[0] + assert isinstance(child, AggregateReadChild) + assert child.file == "/foo.py" + assert child.lines == "1-10" + assert child.in_flight is True + assert child.started_at_ms == 1000 assert r.run.agents["a1"].last_tool == "read /foo.py:1-10" + def test_two_consecutive_reads_form_one_aggregate(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/a", "lines": "", "ts_ms": 1}, agent_id="a1")) + r = fold(p, _e("tool_read", {"call_id": "c2", "file": "/b", "lines": "", "ts_ms": 2}, agent_id="a1")) + entries = r.run.agents["a1"].conversation.entries + assert len(entries) == 1 + assert isinstance(entries[0], ToolAggregateEntry) + assert entries[0].started_at_ms == 1 # aggregate's started_at_ms is the first child's + assert [c.call_id for c in entries[0].children] == ["c1", "c2"] + + def test_read_grep_ls_form_one_aggregate_three_children(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/a", "lines": "", "ts_ms": 1}, agent_id="a1")) + p = fold(p, _e("tool_grep", {"call_id": "c2", "pattern": "foo", "ts_ms": 2}, agent_id="a1")) + r = fold(p, _e("tool_ls", {"call_id": "c3", "path": "/d", "ts_ms": 3}, agent_id="a1")) + entries = r.run.agents["a1"].conversation.entries + assert len(entries) == 1 + agg = entries[0] + assert isinstance(agg, ToolAggregateEntry) + assert isinstance(agg.children[0], AggregateReadChild) + assert isinstance(agg.children[1], AggregateGrepChild) + assert isinstance(agg.children[2], AggregateLsChild) + + def test_read_bash_read_produces_three_top_level_entries(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/a", "lines": "", "ts_ms": 1}, agent_id="a1")) + p = fold(p, _e("tool_bash", {"call_id": "c2", "command": "ls"}, agent_id="a1")) + r = fold(p, _e("tool_read", {"call_id": "c3", "file": "/b", "lines": "", "ts_ms": 3}, agent_id="a1")) + entries = r.run.agents["a1"].conversation.entries + assert len(entries) == 3 + assert isinstance(entries[0], ToolAggregateEntry) + assert len(entries[0].children) == 1 + assert isinstance(entries[1], ToolBashEntry) + assert isinstance(entries[2], ToolAggregateEntry) + assert len(entries[2].children) == 1 + assert entries[2].children[0].call_id == "c3" + def test_tool_write_appends_entry(self): p = _proj_with_primary("a1") r = fold(p, _e("tool_write", {"call_id": "c1", "file": "/out.py"}, agent_id="a1")) @@ -382,19 +427,21 @@ def test_tool_bash_appends_entry(self): assert isinstance(entry, ToolBashEntry) assert entry.command == "ls -la" - def test_tool_grep_appends_entry(self): + def test_tool_grep_single_event_wraps_in_aggregate(self): p = _proj_with_primary("a1") - r = fold(p, _e("tool_grep", {"call_id": "c1", "pattern": "def foo"}, agent_id="a1")) - entry = r.run.agents["a1"].conversation.entries[0] - assert isinstance(entry, ToolGrepEntry) - assert entry.pattern == "def foo" + r = fold(p, _e("tool_grep", {"call_id": "c1", "pattern": "def foo", "ts_ms": 5}, agent_id="a1")) + agg = r.run.agents["a1"].conversation.entries[0] + assert isinstance(agg, ToolAggregateEntry) + assert isinstance(agg.children[0], AggregateGrepChild) + assert agg.children[0].pattern == "def foo" - def test_tool_ls_appends_entry(self): + def test_tool_ls_single_event_wraps_in_aggregate(self): p = _proj_with_primary("a1") - r = fold(p, _e("tool_ls", {"call_id": "c1", "path": "/src"}, agent_id="a1")) - entry = r.run.agents["a1"].conversation.entries[0] - assert isinstance(entry, ToolLsEntry) - assert entry.path == "/src" + r = fold(p, _e("tool_ls", {"call_id": "c1", "path": "/src", "ts_ms": 9}, agent_id="a1")) + agg = r.run.agents["a1"].conversation.entries[0] + assert isinstance(agg, ToolAggregateEntry) + assert isinstance(agg.children[0], AggregateLsChild) + assert agg.children[0].path == "/src" def test_tool_called_appends_generic_entry(self): p = _proj_with_primary("a1") @@ -416,13 +463,35 @@ def test_tool_called_mcp_koan_prefix_skipped(self): r = fold(p, _e("tool_called", {"call_id": "c1", "tool": "mcp__koan__step", "args": {}}, agent_id="a1")) assert r.run.agents["a1"].conversation.entries == [] - def test_tool_completed_clears_in_flight(self): + def test_tool_completed_marks_aggregate_child_done(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/a", "lines": "", "ts_ms": 1}, agent_id="a1")) + p = fold(p, _e("tool_read", {"call_id": "c2", "file": "/b", "lines": "", "ts_ms": 2}, agent_id="a1")) + r = fold(p, _e("tool_completed", {"call_id": "c1", "tool": "read", "ts_ms": 5}, agent_id="a1")) + agg = r.run.agents["a1"].conversation.entries[0] + assert isinstance(agg, ToolAggregateEntry) + # c1 completed, c2 still in-flight — sibling untouched + by_id = {c.call_id: c for c in agg.children} + assert by_id["c1"].in_flight is False + assert by_id["c1"].completed_at_ms == 5 + assert by_id["c2"].in_flight is True + assert by_id["c2"].completed_at_ms is None + + def test_tool_completed_for_top_level_tool_still_works(self): p = _proj_with_primary("a1") - p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/f", "lines": ""}, agent_id="a1")) + p = fold(p, _e("tool_bash", {"call_id": "c1", "command": "ls"}, agent_id="a1")) assert p.run.agents["a1"].conversation.entries[0].in_flight is True - r = fold(p, _e("tool_completed", {"call_id": "c1", "tool": "read"}, agent_id="a1")) + r = fold(p, _e("tool_completed", {"call_id": "c1", "tool": "bash"}, agent_id="a1")) assert r.run.agents["a1"].conversation.entries[0].in_flight is False + def test_tool_completed_unknown_call_id_is_noop(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/a", "lines": ""}, agent_id="a1")) + r = fold(p, _e("tool_completed", {"call_id": "missing", "tool": "read"}, agent_id="a1")) + # Projection shape unchanged; c1 still in-flight. + agg = r.run.agents["a1"].conversation.entries[0] + assert agg.children[0].in_flight is True + def test_tool_flushes_pending_fields(self): p = _proj_with_primary("a1") p = fold(p, _e("stream_delta", {"delta": "output"}, agent_id="a1")) @@ -430,7 +499,7 @@ def test_tool_flushes_pending_fields(self): conv = r.run.agents["a1"].conversation assert len(conv.entries) == 2 assert isinstance(conv.entries[0], TextEntry) # flushed - assert isinstance(conv.entries[1], ToolReadEntry) + assert isinstance(conv.entries[1], ToolAggregateEntry) assert conv.pending_text == "" def test_tool_events_per_agent_not_primary_only(self): @@ -440,7 +509,69 @@ def test_tool_events_per_agent_not_primary_only(self): p = fold(p, _e("agent_spawned", {"agent_id": "s1", "role": "scout", "is_primary": False, "started_at_ms": 0}, agent_id="s1")) r = fold(p, _e("tool_read", {"call_id": "c1", "file": "/f", "lines": ""}, agent_id="s1")) assert len(r.run.agents["s1"].conversation.entries) == 1 - assert isinstance(r.run.agents["s1"].conversation.entries[0], ToolReadEntry) + assert isinstance(r.run.agents["s1"].conversation.entries[0], ToolAggregateEntry) + + # --- tool_result_captured ----------------------------------------------- + + def test_tool_result_captured_attaches_read_metrics(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/a", "lines": "", "ts_ms": 1}, agent_id="a1")) + r = fold(p, _e("tool_result_captured", { + "call_id": "c1", "tool": "read", + "metrics": {"lines_read": 42, "bytes_read": 1024}, + }, agent_id="a1")) + child = r.run.agents["a1"].conversation.entries[0].children[0] + assert isinstance(child, AggregateReadChild) + assert child.lines_read == 42 + assert child.bytes_read == 1024 + + def test_tool_result_captured_grep_leaves_read_siblings_alone(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/a", "lines": "", "ts_ms": 1}, agent_id="a1")) + p = fold(p, _e("tool_grep", {"call_id": "c2", "pattern": "x", "ts_ms": 2}, agent_id="a1")) + r = fold(p, _e("tool_result_captured", { + "call_id": "c2", "tool": "grep", + "metrics": {"matches": 7, "files_matched": 3}, + }, agent_id="a1")) + agg = r.run.agents["a1"].conversation.entries[0] + read_child = agg.children[0] + grep_child = agg.children[1] + assert isinstance(read_child, AggregateReadChild) + assert read_child.lines_read is None # untouched + assert isinstance(grep_child, AggregateGrepChild) + assert grep_child.matches == 7 + assert grep_child.files_matched == 3 + + def test_tool_result_captured_unknown_call_id_is_noop(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/a", "lines": ""}, agent_id="a1")) + before = p.run.agents["a1"].conversation.entries[0] + r = fold(p, _e("tool_result_captured", { + "call_id": "missing", "tool": "read", + "metrics": {"lines_read": 1}, + }, agent_id="a1")) + # Projection shape unchanged — returns same projection reference semantics + assert r.run.agents["a1"].conversation.entries[0] == before + + def test_tool_result_captured_no_metrics_is_noop(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_read", {"call_id": "c1", "file": "/a", "lines": ""}, agent_id="a1")) + r = fold(p, _e("tool_result_captured", {"call_id": "c1", "tool": "read"}, agent_id="a1")) + child = r.run.agents["a1"].conversation.entries[0].children[0] + assert child.lines_read is None + assert child.bytes_read is None + + def test_tool_result_captured_ls_metrics(self): + p = _proj_with_primary("a1") + p = fold(p, _e("tool_ls", {"call_id": "c1", "path": "/d", "ts_ms": 1}, agent_id="a1")) + r = fold(p, _e("tool_result_captured", { + "call_id": "c1", "tool": "ls", + "metrics": {"entries": 12, "directories": 3}, + }, agent_id="a1")) + child = r.run.agents["a1"].conversation.entries[0].children[0] + assert isinstance(child, AggregateLsChild) + assert child.entries == 12 + assert child.directories == 3 # --------------------------------------------------------------------------- diff --git a/tests/test_streaming_aggregation.py b/tests/test_streaming_aggregation.py new file mode 100644 index 0000000..4f319b8 --- /dev/null +++ b/tests/test_streaming_aggregation.py @@ -0,0 +1,276 @@ +"""End-to-end streaming test for tool aggregation. + +Covers the pipeline from raw Claude CLI stream-json JSONL lines through +ClaudeRunner.parse_stream_event, the subagent's streaming event-handling +branches, and the projection fold. Regression guard for the bug where +exploration tools (read/grep/ls) were emitted as ToolGenericEntry because +the streaming path routed them through tool_started/tool_stopped instead +of the typed tool_read/tool_grep/tool_ls events. +""" +from __future__ import annotations + +import json +import uuid + +from koan.events import ( + build_tool_completed, + build_tool_grep, + build_tool_ls, + build_tool_read, + build_tool_result_captured, + build_tool_started, + build_tool_stopped, +) +from koan.projections import ( + AggregateReadChild, + ProjectionStore, + ToolAggregateEntry, + VersionedEvent, + fold, +) +from koan.runners.base import StreamEvent +from koan.runners.claude import ClaudeRunner + + +# --------------------------------------------------------------------------- +# Streaming event-handling harness — replicates the relevant branches of +# stream_stdout()'s loop. This intentionally mirrors the production code so +# the test would have caught the original bug; if the subagent ever grows +# extra streaming logic for these tools, this harness must grow with it. +# --------------------------------------------------------------------------- + +class _StreamingHarness: + def __init__(self, store: ProjectionStore, agent_id: str) -> None: + self.store = store + self.agent_id = agent_id + self.streaming_call_ids: dict[int, tuple[str, str]] = {} + self.call_id_by_tool_use_id: dict[str, str] = {} + # Deterministic call_id generator so assertions are stable. + self._next_id = 0 + + def _new_call_id(self) -> str: + self._next_id += 1 + return f"call-{self._next_id}" + + def dispatch(self, ev: StreamEvent, now_ms: int = 1000) -> None: + if ev.type == "tool_start": + call_id = self._new_call_id() + tool_name = ev.tool_name or "tool" + block_idx = ev.block_index if ev.block_index is not None else -1 + self.streaming_call_ids[block_idx] = (call_id, tool_name) + if tool_name in ("read", "grep", "ls"): + if ev.tool_use_id: + self.call_id_by_tool_use_id[ev.tool_use_id] = call_id + else: + self.store.push_event( + "tool_started", + build_tool_started(call_id, tool_name), + agent_id=self.agent_id, + ) + elif ev.type == "tool_stop": + block_idx = ev.block_index if ev.block_index is not None else -1 + pair = self.streaming_call_ids.pop(block_idx, None) + if pair is None: + return + call_id, tool_name = pair + summary = ev.summary or "" + if tool_name in ("read", "grep", "ls"): + if tool_name == "read": + file_part, lines_part = summary, "" + if ":" in summary: + head, tail = summary.rsplit(":", 1) + if tail and (tail[0].isdigit() or "-" in tail): + file_part, lines_part = head, tail + self.store.push_event( + "tool_read", + build_tool_read(call_id, file_part, lines_part, ts_ms=now_ms), + agent_id=self.agent_id, + ) + elif tool_name == "grep": + self.store.push_event( + "tool_grep", + build_tool_grep(call_id, summary, ts_ms=now_ms), + agent_id=self.agent_id, + ) + else: # ls + self.store.push_event( + "tool_ls", + build_tool_ls(call_id, summary, ts_ms=now_ms), + agent_id=self.agent_id, + ) + self.store.push_event( + "tool_completed", + build_tool_completed(call_id, tool_name, ts_ms=now_ms), + agent_id=self.agent_id, + ) + else: + self.store.push_event( + "tool_stopped", + build_tool_stopped(call_id, tool_name, summary), + agent_id=self.agent_id, + ) + elif ev.type == "tool_result": + tool_use_id = ev.tool_use_id or "" + cid = self.call_id_by_tool_use_id.get(tool_use_id) + if cid is not None: + self.store.push_event( + "tool_result_captured", + build_tool_result_captured(cid, ev.tool_name or "", metrics=ev.metrics), + agent_id=self.agent_id, + ) + + +# --------------------------------------------------------------------------- +# Fixture helpers +# --------------------------------------------------------------------------- + +def _wrap_stream_event(inner: dict) -> str: + return json.dumps({"type": "stream_event", "event": inner}) + + +def _read_block_lines(block_idx: int, tool_use_id: str, file_path: str) -> list[str]: + """Produce the raw JSONL lines for one streaming Read tool use.""" + return [ + _wrap_stream_event({ + "type": "content_block_start", + "index": block_idx, + "content_block": { + "type": "tool_use", + "id": tool_use_id, + "name": "Read", + "input": {}, + }, + }), + _wrap_stream_event({ + "type": "content_block_delta", + "index": block_idx, + "delta": { + "type": "input_json_delta", + "partial_json": json.dumps({"file_path": file_path}), + }, + }), + _wrap_stream_event({ + "type": "content_block_stop", + "index": block_idx, + }), + ] + + +def _user_tool_result(tool_use_id: str, content: str) -> str: + return json.dumps({ + "type": "user", + "message": { + "content": [ + { + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": content, + } + ] + }, + }) + + +def _seed_store() -> tuple[ProjectionStore, str]: + store = ProjectionStore() + agent_id = "a1" + store.push_event("run_started", { + "profile": "balanced", + "installations": {}, + "scout_concurrency": 8, + }) + store.push_event( + "agent_spawned", + { + "agent_id": agent_id, + "role": "intake", + "label": "", + "model": "opus", + "is_primary": True, + "started_at_ms": 1, + }, + agent_id=agent_id, + ) + return store, agent_id + + +# --------------------------------------------------------------------------- +# The actual tests +# --------------------------------------------------------------------------- + +def test_two_streaming_reads_form_one_aggregate_with_two_children(): + """Regression guard: consecutive streaming reads must aggregate. + + Before the fix, the subagent routed every tool_start/tool_stop through + tool_started/tool_stopped → ToolGenericEntry, so two reads landed as two + separate generic entries with no aggregate wrapper. The fix routes + exploration tools through the typed tool_read/tool_grep/tool_ls + + tool_completed events so the aggregate fold creates a ToolAggregateEntry + whose children are AggregateReadChild instances. + """ + store, agent_id = _seed_store() + runner = ClaudeRunner(subagent_dir="/tmp/does-not-matter") + harness = _StreamingHarness(store, agent_id) + + raw_lines: list[str] = [] + raw_lines.extend(_read_block_lines(block_idx=1, tool_use_id="toolu_1", file_path="/repo/a.py")) + raw_lines.extend(_read_block_lines(block_idx=2, tool_use_id="toolu_2", file_path="/repo/b.py")) + + for i, line in enumerate(raw_lines): + for ev in runner.parse_stream_event(line): + harness.dispatch(ev, now_ms=100 + i) + + entries = store.projection.run.agents[agent_id].conversation.entries + assert len(entries) == 1, f"expected exactly one top-level entry, got {[e.type for e in entries]}" + agg = entries[0] + assert isinstance(agg, ToolAggregateEntry) + assert len(agg.children) == 2 + assert all(isinstance(c, AggregateReadChild) for c in agg.children) + # Both children completed — the streaming path fires tool_completed + # immediately after the typed tool_read event. + assert all(c.in_flight is False for c in agg.children) + assert all(c.completed_at_ms is not None for c in agg.children) + # Paths preserved through the full pipeline. + paths = [c.file for c in agg.children if isinstance(c, AggregateReadChild)] + assert paths == ["/repo/a.py", "/repo/b.py"] + # tool_use_id mapping populated for both — verifies the streaming path's + # tool_result_captured correlation is wired. + assert set(harness.call_id_by_tool_use_id.keys()) == {"toolu_1", "toolu_2"} + + +def test_streaming_read_then_tool_result_attaches_metrics(): + """After a streaming read, a matching tool_result user message must populate + the aggregate child's lines_read and bytes_read metrics. + + This exercises the tool_use_id → call_id mapping captured at tool_start + in the streaming path; if that wiring is missing, tool_result_captured + would be emitted with the wrong call_id (or not at all) and the child's + metric fields would stay None. + """ + store, agent_id = _seed_store() + runner = ClaudeRunner(subagent_dir="/tmp/does-not-matter") + harness = _StreamingHarness(store, agent_id) + + # 1. Stream the Read tool_use block. + for line in _read_block_lines(block_idx=1, tool_use_id="toolu_abc", file_path="/r/x.py"): + for ev in runner.parse_stream_event(line): + harness.dispatch(ev, now_ms=200) + + # 2. Deliver a matching tool_result in the user message. + result_body = " 1\talpha\n 2\tbeta\n 3\tgamma\n" + user_line = _user_tool_result("toolu_abc", result_body) + for ev in runner.parse_stream_event(user_line): + harness.dispatch(ev, now_ms=300) + + entries = store.projection.run.agents[agent_id].conversation.entries + assert len(entries) == 1 + agg = entries[0] + assert isinstance(agg, ToolAggregateEntry) + assert len(agg.children) == 1 + child = agg.children[0] + assert isinstance(child, AggregateReadChild) + assert child.file == "/r/x.py" + assert child.in_flight is False + assert child.lines_read == 3 + # The numbered-line payload has three rows of pure lowercase ASCII. + assert child.bytes_read == len(b"alphabetagamma") diff --git a/tests/test_tool_result_parsers.py b/tests/test_tool_result_parsers.py new file mode 100644 index 0000000..71a6ea8 --- /dev/null +++ b/tests/test_tool_result_parsers.py @@ -0,0 +1,236 @@ +"""Tests for the tool-result parsers in ClaudeRunner. + +Covers the three exploration tool parsers (read, grep, ls), the content-shape +helper that normalizes string vs. list content, and one integration test that +exercises the full parse_stream_event path with a synthetic user message. +""" +from __future__ import annotations + +import json + +from koan.runners.claude import ( + ClaudeRunner, + _parse_grep_result, + _parse_ls_result, + _parse_read_result, + _tool_result_text, +) + + +# --------------------------------------------------------------------------- +# _tool_result_text +# --------------------------------------------------------------------------- + +class TestToolResultText: + def test_string_content_returned_as_is(self): + assert _tool_result_text("hello") == "hello" + + def test_list_of_text_blocks_joined(self): + content = [ + {"type": "text", "text": "one\n"}, + {"type": "text", "text": "two"}, + ] + assert _tool_result_text(content) == "one\ntwo" + + def test_list_with_non_text_blocks_skipped(self): + content = [ + {"type": "image", "data": "..."}, + {"type": "text", "text": "only this"}, + ] + assert _tool_result_text(content) == "only this" + + def test_unknown_shape_returns_empty(self): + assert _tool_result_text(None) == "" + assert _tool_result_text(42) == "" + + +# --------------------------------------------------------------------------- +# Read parser +# --------------------------------------------------------------------------- + +class TestReadParser: + def test_basic_numbered_lines(self): + text = " 1\tfirst line\n 2\tsecond line\n 3\tthird\n" + metrics = _parse_read_result(text) + assert metrics == { + "lines_read": 3, + "bytes_read": len(b"first linesecond linethird"), + } + + def test_strips_trailing_system_reminder(self): + text = ( + "1\tabc\n" + "2\tdef\n" + "<system-reminder>\nDo not touch.\n</system-reminder>" + ) + metrics = _parse_read_result(text) + assert metrics == {"lines_read": 2, "bytes_read": len(b"abcdef")} + + def test_empty_result_returns_none(self): + assert _parse_read_result("") is None + + def test_non_numbered_output_returns_none(self): + assert _parse_read_result("just some text\nwithout tabs\n") is None + + def test_utf8_byte_counting(self): + # Three "hello" with a multibyte char. + text = "1\théllo\n" + metrics = _parse_read_result(text) + assert metrics is not None + assert metrics["lines_read"] == 1 + assert metrics["bytes_read"] == len("héllo".encode("utf-8")) + + +# --------------------------------------------------------------------------- +# Grep parser +# --------------------------------------------------------------------------- + +class TestGrepParser: + def test_files_with_matches_mode(self): + text = "src/a.py\nsrc/b.py\nsrc/c.py\n" + assert _parse_grep_result(text) == {"matches": 3, "files_matched": 3} + + def test_content_mode_path_line_match(self): + text = ( + "src/a.py:10:def foo():\n" + "src/a.py:42:def bar():\n" + "src/b.py:5:def baz():\n" + ) + assert _parse_grep_result(text) == {"matches": 3, "files_matched": 2} + + def test_count_mode(self): + text = "src/a.py:4\nsrc/b.py:2\nsrc/c.py:1\n" + assert _parse_grep_result(text) == {"matches": 7, "files_matched": 3} + + def test_summary_line_with_files(self): + text = "Found 42 matches in 6 files\nsome context line\n" + assert _parse_grep_result(text) == {"matches": 42, "files_matched": 6} + + def test_summary_line_without_files(self): + text = "Found 12 matches\n" + metrics = _parse_grep_result(text) + assert metrics is not None + assert metrics["matches"] == 12 + + def test_empty_result_returns_none(self): + assert _parse_grep_result("") is None + assert _parse_grep_result(" \n\n") is None + + +# --------------------------------------------------------------------------- +# Ls parser +# --------------------------------------------------------------------------- + +class TestLsParser: + def test_tree_listing_counts_entries_and_dirs(self): + text = ( + "- /path/to/root/\n" + " - file1.py\n" + " - file2.py\n" + " - subdir/\n" + " - nested.py\n" + " - another_dir/\n" + ) + metrics = _parse_ls_result(text) + # 5 entries (file1, file2, subdir, nested, another_dir); 2 dirs (subdir, another_dir). + assert metrics == {"entries": 5, "directories": 2} + + def test_header_not_counted(self): + text = "- /home/user/\n - a\n" + assert _parse_ls_result(text) == {"entries": 1, "directories": 0} + + def test_empty_result_returns_none(self): + assert _parse_ls_result("") is None + assert _parse_ls_result("nothing relevant\n") is None + + +# --------------------------------------------------------------------------- +# parse_stream_event integration +# --------------------------------------------------------------------------- + +class TestParseStreamEventUser: + def _runner(self) -> ClaudeRunner: + return ClaudeRunner(subagent_dir="/tmp/does-not-matter") + + def test_user_message_with_read_tool_result_emits_event(self): + r = self._runner() + # Prime the tracker as if a Read tool_use block had been seen earlier. + r._exploration_tool_by_id["toolu_123"] = "read" + payload = { + "type": "user", + "message": { + "content": [ + { + "type": "tool_result", + "tool_use_id": "toolu_123", + "content": "1\talpha\n2\tbeta\n", + } + ] + }, + } + events = r.parse_stream_event(json.dumps(payload)) + assert len(events) == 1 + ev = events[0] + assert ev.type == "tool_result" + assert ev.tool_name == "read" + assert ev.tool_use_id == "toolu_123" + assert ev.metrics == {"lines_read": 2, "bytes_read": len(b"alphabeta")} + # Tracker drained. + assert "toolu_123" not in r._exploration_tool_by_id + + def test_user_message_with_untracked_tool_result_is_ignored(self): + r = self._runner() + payload = { + "type": "user", + "message": { + "content": [ + { + "type": "tool_result", + "tool_use_id": "toolu_unknown", + "content": "anything", + } + ] + }, + } + assert r.parse_stream_event(json.dumps(payload)) == [] + + def test_user_message_with_list_content_handled(self): + r = self._runner() + r._exploration_tool_by_id["toolu_456"] = "grep" + payload = { + "type": "user", + "message": { + "content": [ + { + "type": "tool_result", + "tool_use_id": "toolu_456", + "content": [ + {"type": "text", "text": "src/a.py:10:hit\n"}, + {"type": "text", "text": "src/b.py:20:hit\n"}, + ], + } + ] + }, + } + events = r.parse_stream_event(json.dumps(payload)) + assert len(events) == 1 + assert events[0].metrics == {"matches": 2, "files_matched": 2} + + def test_user_message_with_unparseable_content_emits_none_metrics(self): + r = self._runner() + r._exploration_tool_by_id["toolu_789"] = "read" + payload = { + "type": "user", + "message": { + "content": [ + { + "type": "tool_result", + "tool_use_id": "toolu_789", + "content": "not numbered lines\n", + } + ] + }, + } + events = r.parse_stream_event(json.dumps(payload)) + assert len(events) == 1 + assert events[0].metrics is None From 5017ecf95bed36438e2d3de47a68e860ea4cf48b Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 19 Apr 2026 11:54:13 +0700 Subject: [PATCH 407/412] feat: render aggregated exploration tool cards in UI --- frontend/src/App.tsx | 237 +++++++++++++++++- frontend/src/components/atoms/StatusDot.css | 7 +- frontend/src/components/atoms/StatusDot.tsx | 16 +- .../molecules/ToolAggregateCard.css | 90 +++++++ .../molecules/ToolAggregateCard.tsx | 88 +++++++ .../src/components/molecules/ToolCallRow.css | 13 + .../src/components/molecules/ToolCallRow.tsx | 6 +- .../src/components/molecules/ToolLogRow.css | 51 ++++ .../src/components/molecules/ToolLogRow.tsx | 47 ++++ .../components/molecules/ToolStatBlock.css | 45 ++++ .../components/molecules/ToolStatBlock.tsx | 71 ++++++ frontend/src/store/index.ts | 43 +++- frontend/src/styles/variables.css | 6 + 13 files changed, 703 insertions(+), 17 deletions(-) create mode 100644 frontend/src/components/molecules/ToolAggregateCard.css create mode 100644 frontend/src/components/molecules/ToolAggregateCard.tsx create mode 100644 frontend/src/components/molecules/ToolLogRow.css create mode 100644 frontend/src/components/molecules/ToolLogRow.tsx create mode 100644 frontend/src/components/molecules/ToolStatBlock.css create mode 100644 frontend/src/components/molecules/ToolStatBlock.tsx diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 123c6d6..a3e3c76 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -34,6 +34,9 @@ import { NewRunForm } from './components/organisms/NewRunForm' import { ThinkingBlock } from './components/molecules/ThinkingBlock' import { ProseCard } from './components/molecules/ProseCard' import { ToolCallRow } from './components/molecules/ToolCallRow' +import { ToolLogRow } from './components/molecules/ToolLogRow' +import { ToolStatBlock } from './components/molecules/ToolStatBlock' +import { ToolAggregateCard } from './components/molecules/ToolAggregateCard' import { StepGuidancePill } from './components/molecules/StepGuidancePill' import { FeedbackInput } from './components/molecules/FeedbackInput' import { UserBubble } from './components/molecules/UserBubble' @@ -51,6 +54,8 @@ import { SettingsPage, type Profile as SPProfile, type Installation as SPInstall import { ReviewPanel, type ReviewSubmitPayload } from './components/organisms/ReviewPanel' import { SessionsPage } from './components/organisms/SessionsPage' +import type { AggregateChild, AggregateReadChild, AggregateGrepChild, AggregateLsChild, ToolAggregateEntry } from './store/index' + // --------------------------------------------------------------------------- // Header data // --------------------------------------------------------------------------- @@ -146,24 +151,244 @@ const KOAN_TOOL_LABELS: Record<string, string> = { koan_skip_story: 'Skipping story', } +// --------------------------------------------------------------------------- +// Aggregate rendering helpers — pure functions, next to renderEntry so the +// data flow stays readable. Each maps AggregateChild state to display strings +// or further structured pieces consumed by the card / row components. +// --------------------------------------------------------------------------- + +function pluralizeOps(n: number): string { + return n === 1 ? '1 op' : `${n} ops` +} + +function formatBytes(n: number): string { + if (n < 1024) return `${n} B` + const kb = n / 1024 + if (kb < 1024) return `${kb.toFixed(1)} KB` + return `${(kb / 1024).toFixed(1)} MB` +} + +function childCommand(child: AggregateChild): string { + switch (child.tool) { + case 'read': return child.lines ? `${child.file}:${child.lines}` : child.file + case 'grep': return child.pattern + case 'ls': return child.path + } +} + +function childMetric(child: AggregateChild): string | undefined { + switch (child.tool) { + case 'read': { + if (child.linesRead != null && child.bytesRead != null) { + return `${child.linesRead} lines · ${formatBytes(child.bytesRead)}` + } + if (child.linesRead != null) return `${child.linesRead} lines` + return undefined + } + case 'grep': { + if (child.matches != null && child.filesMatched != null) { + return `${child.matches} matches · ${child.filesMatched} files` + } + if (child.matches != null) return `${child.matches} matches` + return undefined + } + case 'ls': { + if (child.entries != null) return `${child.entries} entries` + return undefined + } + } +} + +function shortBasename(path: string): string { + const slash = path.lastIndexOf('/') + return slash >= 0 ? path.slice(slash + 1) : path +} + +function runningLabelFor(child: AggregateChild): string { + switch (child.tool) { + case 'read': return `reading ${shortBasename(child.file)}` + case 'grep': return 'grepping' + case 'ls': return `listing ${shortBasename(child.path)}` + } +} + +function findRunningChild(children: AggregateChild[]): AggregateChild | undefined { + return children.find(c => c.inFlight) +} + +function groupChildrenByTool(children: AggregateChild[]): { + read: AggregateReadChild[]; grep: AggregateGrepChild[]; ls: AggregateLsChild[] +} { + const read: AggregateReadChild[] = [] + const grep: AggregateGrepChild[] = [] + const ls: AggregateLsChild[] = [] + for (const c of children) { + if (c.tool === 'read') read.push(c) + else if (c.tool === 'grep') grep.push(c) + else ls.push(c) + } + return { read, grep, ls } +} + +function readMetaLines(children: AggregateReadChild[]): string[] { + let totalLines = 0 + let totalBytes = 0 + let anyLineMetric = false + const files = new Set<string>() + for (const c of children) { + if (c.linesRead != null) { totalLines += c.linesRead; anyLineMetric = true } + if (c.bytesRead != null) { totalBytes += c.bytesRead } + files.add(c.file) + } + const lines: string[] = [] + if (anyLineMetric) { + lines.push(totalBytes > 0 + ? `${totalLines} lines · ${formatBytes(totalBytes)}` + : `${totalLines} lines`) + } + if (files.size !== children.length) { + // More than one read hit the same file — worth mentioning file count. + lines.push(`${files.size} ${files.size === 1 ? 'file' : 'files'} touched`) + } + return lines +} + +function grepMetaLines(children: AggregateGrepChild[]): string[] { + let totalMatches = 0 + let totalFiles = 0 + let anyMetric = false + for (const c of children) { + if (c.matches != null) { totalMatches += c.matches; anyMetric = true } + if (c.filesMatched != null) { totalFiles += c.filesMatched } + } + const lines: string[] = [] + if (anyMetric) lines.push(`${totalMatches} matches`) + if (totalFiles > 0) lines.push(`${totalFiles} ${totalFiles === 1 ? 'file' : 'files'} searched`) + return lines +} + +function lsMetaLines(children: AggregateLsChild[]): string[] { + let totalEntries = 0 + let totalDirs = 0 + let anyMetric = false + for (const c of children) { + if (c.entries != null) { totalEntries += c.entries; anyMetric = true } + if (c.directories != null) totalDirs += c.directories + } + const lines: string[] = [] + if (anyMetric) lines.push(`${totalEntries} entries`) + if (totalDirs > 0) lines.push(`${totalDirs} ${totalDirs === 1 ? 'directory' : 'directories'}`) + return lines +} + +function aggregateElapsedMs(agg: ToolAggregateEntry, nowMs: number): number { + const running = findRunningChild(agg.children) + if (running) { + return Math.max(0, nowMs - agg.startedAtMs) + } + let latest = agg.startedAtMs + for (const c of agg.children) { + if (c.completedAtMs != null && c.completedAtMs > latest) latest = c.completedAtMs + } + return Math.max(0, latest - agg.startedAtMs) +} + +function renderAggregate(entry: ToolAggregateEntry, i: number) { + const children = entry.children + if (children.length === 0) return null + + // Single-child aggregates render as a standalone ToolCallRow, matching the + // pre-aggregation visual for the common case where no grouping has happened + // yet. The row upgrades to a card on the next consecutive exploration tool. + if (children.length === 1) { + const c = children[0] + return ( + <ToolCallRow + key={i} + tool={c.tool} + command={childCommand(c)} + status={c.inFlight ? 'running' : 'done'} + metric={childMetric(c)} + /> + ) + } + + // Two or more children: render the full two-pane aggregate card. + const groups = groupChildrenByTool(children) + const running = findRunningChild(children) + const runningLabel = running ? runningLabelFor(running) : undefined + const elapsedMs = aggregateElapsedMs(entry, Date.now()) + + const stats = [ + groups.read.length > 0 && ( + <ToolStatBlock + key="read" + type="read" + name="read" + opCount={pluralizeOps(groups.read.length)} + metaLines={readMetaLines(groups.read)} + active={running?.tool === 'read'} + /> + ), + groups.grep.length > 0 && ( + <ToolStatBlock + key="grep" + type="grep" + name="grep" + opCount={pluralizeOps(groups.grep.length)} + metaLines={grepMetaLines(groups.grep)} + active={running?.tool === 'grep'} + /> + ), + groups.ls.length > 0 && ( + <ToolStatBlock + key="ls" + type="ls" + name="ls" + opCount={pluralizeOps(groups.ls.length)} + metaLines={lsMetaLines(groups.ls)} + active={running?.tool === 'ls'} + /> + ), + ].filter(Boolean) + + const logRows = children.map((c, j) => ( + <ToolLogRow + key={j} + status={c.inFlight ? 'running' : c.tool} + command={childCommand(c)} + metric={c.inFlight + ? (c.tool === 'read' ? 'reading…' : c.tool === 'grep' ? 'grepping…' : 'listing…') + : childMetric(c)} + /> + )) + + return ( + <ToolAggregateCard + key={i} + operationCount={children.length} + runningLabel={runningLabel} + elapsed={elapsedMs > 0 ? formatElapsed(elapsedMs) : undefined} + statsPane={stats} + logPane={logRows} + /> + ) +} + function renderEntry(entry: ConversationEntry, i: number) { switch (entry.type) { case 'thinking': return <ThinkingBlock key={i}><Md>{entry.content}</Md></ThinkingBlock> case 'text': return <ProseCard key={i}><Md>{entry.text}</Md></ProseCard> - case 'tool_read': - return <ToolCallRow key={i} tool="read" command={entry.lines ? `${entry.file}:${entry.lines}` : entry.file} status={entry.inFlight ? 'running' : 'done'} /> + case 'tool_aggregate': + return renderAggregate(entry, i) case 'tool_write': return <ToolCallRow key={i} tool="write" command={entry.file} status={entry.inFlight ? 'running' : 'done'} /> case 'tool_edit': return <ToolCallRow key={i} tool="edit" command={entry.file} status={entry.inFlight ? 'running' : 'done'} /> case 'tool_bash': return <ToolCallRow key={i} tool="bash" command={entry.command} status={entry.inFlight ? 'running' : 'done'} /> - case 'tool_grep': - return <ToolCallRow key={i} tool="grep" command={entry.pattern} status={entry.inFlight ? 'running' : 'done'} /> - case 'tool_ls': - return <ToolCallRow key={i} tool="ls" command={entry.path} status={entry.inFlight ? 'running' : 'done'} /> case 'tool_generic': { if (SUPPRESSED_TOOLS.has(entry.toolName)) return null const label = KOAN_TOOL_LABELS[entry.toolName] ?? entry.toolName diff --git a/frontend/src/components/atoms/StatusDot.css b/frontend/src/components/atoms/StatusDot.css index 120fac0..4b5c0cd 100644 --- a/frontend/src/components/atoms/StatusDot.css +++ b/frontend/src/components/atoms/StatusDot.css @@ -8,8 +8,13 @@ .status-dot--sm { width: 6px; height: 6px; } .status-dot--md { width: 8px; height: 8px; } -/* Status colors */ +/* Status colors — operational state */ .status-dot--running { background: var(--status-running); } .status-dot--done { background: var(--status-done); } .status-dot--queued { background: var(--status-queued); } .status-dot--failed { background: var(--status-failed); } + +/* Status colors — tool family */ +.status-dot--read { background: var(--dot-read); } +.status-dot--grep { background: var(--dot-grep); } +.status-dot--ls { background: var(--dot-ls); } diff --git a/frontend/src/components/atoms/StatusDot.tsx b/frontend/src/components/atoms/StatusDot.tsx index 7e5f528..eb02b77 100644 --- a/frontend/src/components/atoms/StatusDot.tsx +++ b/frontend/src/components/atoms/StatusDot.tsx @@ -1,13 +1,21 @@ /** - * StatusDot — a small colored circle indicating operational state. + * StatusDot — a small colored circle indicating either an operational + * state or a tool family. * - * Used in: header orchestrator indicator, scout table rows, - * artifact cards, step guidance pill. + * All variants are static — no animation. In-flight activity indicators + * in consuming molecules are implemented inline (see ToolCallRow's + * `.tcr-running-dot` pattern) rather than through StatusDot, so that + * StatusDot stays a pure visual primitive and adjacent features using + * StatusDot (e.g. ScoutRow) are unaffected when new variants are added. + * + * Used in: header orchestrator indicator, scout table rows, artifact + * cards, step guidance pill (operational state variants); ToolLogRow and + * ToolStatBlock (tool-family variants — read, grep, ls). */ import './StatusDot.css' -type Status = 'running' | 'done' | 'queued' | 'failed' +type Status = 'running' | 'done' | 'queued' | 'failed' | 'read' | 'grep' | 'ls' type Size = 'sm' | 'md' interface StatusDotProps { diff --git a/frontend/src/components/molecules/ToolAggregateCard.css b/frontend/src/components/molecules/ToolAggregateCard.css new file mode 100644 index 0000000..4423277 --- /dev/null +++ b/frontend/src/components/molecules/ToolAggregateCard.css @@ -0,0 +1,90 @@ +.tac { + background: var(--bg-card); + border: 0.5px solid var(--border-card); + border-left: 3px solid var(--color-orange); + border-radius: var(--radius-xl); + overflow: hidden; +} + +/* ---- Header ---- */ +.tac-header { + display: flex; + align-items: baseline; + gap: 10px; + padding: 10px 18px 9px 18px; + border-bottom: 1px solid var(--border-divider-light); +} + +.tac-label { + font-size: var(--type-tool-type); + color: var(--text-muted); + letter-spacing: 0.3px; +} + +.tac-count { + font-size: var(--type-body); + color: var(--text-primary); + font-weight: 500; +} + +.tac-spacer { + flex: 1; +} + +/* ---- Running indicator (header, when runningLabel is set) ---- */ +.tac-running { + display: inline-flex; + align-items: center; + gap: 5px; +} + +.tac-running-dot { + width: 6px; + height: 6px; + border-radius: var(--radius-circle); + background: var(--status-running); + animation: tac-pulse 1.5s ease-in-out infinite; + flex-shrink: 0; +} + +.tac-running-label { + font-family: var(--font-mono); + font-size: 11px; + color: var(--color-orange); +} + +/* ---- Elapsed (header, optional) ---- */ +.tac-elapsed { + font-family: var(--font-mono); + font-size: 11px; + color: var(--text-hint); + padding-left: 8px; +} + +/* ---- Body (two-pane grid) ---- */ +.tac-body { + display: grid; + grid-template-columns: 240px 1fr; +} + +.tac-stats-pane { + background: var(--bg-card-warm); + border-right: 1px solid var(--border-divider-light); + padding: 14px 16px; + display: flex; + flex-direction: column; + gap: 12px; +} + +.tac-log-pane { + padding: 11px 18px 11px 16px; + display: flex; + flex-direction: column; + gap: 0; + min-width: 0; +} + +@keyframes tac-pulse { + 0%, 100% { opacity: 0.3; } + 50% { opacity: 1; } +} diff --git a/frontend/src/components/molecules/ToolAggregateCard.tsx b/frontend/src/components/molecules/ToolAggregateCard.tsx new file mode 100644 index 0000000..0fe5113 --- /dev/null +++ b/frontend/src/components/molecules/ToolAggregateCard.tsx @@ -0,0 +1,88 @@ +/** + * ToolAggregateCard — a two-pane card that groups consecutive exploration + * tool calls (read, grep, ls) into a single visual unit. + * + * Structure: a header with an "explore" label, a formatted operation + * count, an optional running indicator, and an optional elapsed duration; + * below the header, a two-column grid body with a 240px stats pane on + * the left and a flexible log pane on the right. The panes are slot + * props (statsPane, logPane) — the caller composes ToolStatBlock and + * ToolLogRow children directly into these slots. + * + * Source accent: the card has a 3px orange left border at all times, + * following the "left border = content source" convention — tool calls + * are agent output, so the card inherits the same source accent as + * ProseCard. The border color does NOT change when the card is active. + * + * Active state: when the card's aggregate contains an in-flight + * operation, the caller passes runningLabel (a short human-readable + * string like "reading projections.py") and the card renders a + * pulsing orange dot plus the label in its header. The caller is also + * responsible for marking the appropriate ToolStatBlock as active and + * the in-flight ToolLogRow as status="running" inside the slot props — + * the card does not reach into its slots to do this. The three + * activation signals (header indicator, active stat block, running log + * row) together tell the user something is happening; no outer-border + * change participates. + * + * Used in: the content stream, replacing runs of consecutive + * ToolCallRow molecules. The grouping logic that decides when to render + * a card (vs. individual rows) lives in a utility function (prompt 8). + */ + +import type { ReactNode } from 'react' +import './ToolAggregateCard.css' + +interface ToolAggregateCardProps { + /** Number of operations in this aggregate. Formatted by the card as + * "N operation" or "N operations". The card handles pluralization. */ + operationCount: number + /** When set, the card is in its active state: the header renders the + * pulsing dot plus this label. Typical values: "reading projections.py", + * "grepping for phase context", "listing koan/phases". When undefined, + * the header's running indicator is not rendered. */ + runningLabel?: string + /** Pre-formatted wall-clock duration for the aggregate, e.g. "1m 12s", + * "3m 24s". Shown in the header for both completed and active cards. + * The caller handles formatting. */ + elapsed?: string + /** The left pane content. Typically a stack of ToolStatBlock elements, + * one per tool family present in the aggregate. */ + statsPane: ReactNode + /** The right pane content. Typically a stack of ToolLogRow elements + * in chronological order. */ + logPane: ReactNode +} + +export function ToolAggregateCard({ + operationCount, + runningLabel, + elapsed, + statsPane, + logPane, +}: ToolAggregateCardProps) { + const countText = `${operationCount} operation${operationCount === 1 ? '' : 's'}` + return ( + <div className="tac"> + <div className="tac-header"> + <span className="tac-label">explore</span> + <span className="tac-count">{countText}</span> + <span className="tac-spacer" /> + {runningLabel && ( + <span className="tac-running"> + {/* Inline pulsing dot — intentionally NOT StatusDot. See file header. */} + <span className="tac-running-dot" aria-label="running" /> + <span className="tac-running-label">{runningLabel}</span> + </span> + )} + {elapsed && <span className="tac-elapsed">{elapsed}</span>} + </div> + <div className="tac-body"> + <div className="tac-stats-pane">{statsPane}</div> + <div className="tac-log-pane">{logPane}</div> + </div> + </div> + ) +} + +export default ToolAggregateCard diff --git a/frontend/src/components/molecules/ToolCallRow.css b/frontend/src/components/molecules/ToolCallRow.css index f4a1510..4765d28 100644 --- a/frontend/src/components/molecules/ToolCallRow.css +++ b/frontend/src/components/molecules/ToolCallRow.css @@ -54,6 +54,15 @@ min-width: 0; } +/* ---- Metric (optional) ---- */ +.tcr-metric { + font-family: var(--font-mono); + font-size: var(--type-tool-path); + color: var(--text-muted); + flex-shrink: 0; + padding-left: 12px; +} + /* ---- Status variants ---- */ .tcr--running { opacity: 0.8; @@ -67,6 +76,10 @@ color: var(--status-failed); } +.tcr--error .tcr-metric { + color: var(--status-failed); +} + @keyframes tcr-pulse { 0%, 100% { opacity: 0.3; } 50% { opacity: 1; } diff --git a/frontend/src/components/molecules/ToolCallRow.tsx b/frontend/src/components/molecules/ToolCallRow.tsx index edf0320..d4219d2 100644 --- a/frontend/src/components/molecules/ToolCallRow.tsx +++ b/frontend/src/components/molecules/ToolCallRow.tsx @@ -14,6 +14,9 @@ interface ToolCallRowProps { tool: string command: string status?: 'done' | 'running' | 'error' + /** Optional right-aligned metric text. Examples: "22.8 KB · new", + * "2.4s · 140 B out", "3 hunks · ±24 lines". */ + metric?: string } const CheckSvg = () => ( @@ -22,7 +25,7 @@ const CheckSvg = () => ( </svg> ) -export function ToolCallRow({ tool, command, status = 'done' }: ToolCallRowProps) { +export function ToolCallRow({ tool, command, status = 'done', metric }: ToolCallRowProps) { return ( <div className={`tcr tcr--${status}`}> <span className="tcr-indicator"> @@ -32,6 +35,7 @@ export function ToolCallRow({ tool, command, status = 'done' }: ToolCallRowProps </span> <span className="tcr-type">{tool}</span> <span className="tcr-command">{command}</span> + {metric && <span className="tcr-metric">{metric}</span>} </div> ) } diff --git a/frontend/src/components/molecules/ToolLogRow.css b/frontend/src/components/molecules/ToolLogRow.css new file mode 100644 index 0000000..87eaf53 --- /dev/null +++ b/frontend/src/components/molecules/ToolLogRow.css @@ -0,0 +1,51 @@ +.tlr { + display: flex; + align-items: center; + gap: 10px; + padding: 3px 0; + font-family: var(--font-mono); + font-size: 12px; + line-height: 1.5; +} + +/* ---- Running dot (inline, intentionally not StatusDot) ---- */ +.tlr-running-dot { + width: 6px; + height: 6px; + border-radius: var(--radius-circle); + background: var(--status-running); + animation: tlr-pulse 1.5s ease-in-out infinite; + flex-shrink: 0; +} + +/* ---- Command / path ---- */ +.tlr-command { + color: var(--text-body); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; + min-width: 0; + flex: 1; +} + +/* ---- Metric (optional) ---- */ +.tlr-metric { + font-size: 11px; + color: var(--text-muted); + flex-shrink: 0; + padding-left: 12px; +} + +/* ---- Running-state text treatment ---- */ +.tlr--running .tlr-command { + color: var(--text-subtle); +} + +.tlr--running .tlr-metric { + color: var(--color-orange); +} + +@keyframes tlr-pulse { + 0%, 100% { opacity: 0.3; } + 50% { opacity: 1; } +} diff --git a/frontend/src/components/molecules/ToolLogRow.tsx b/frontend/src/components/molecules/ToolLogRow.tsx new file mode 100644 index 0000000..57e447a --- /dev/null +++ b/frontend/src/components/molecules/ToolLogRow.tsx @@ -0,0 +1,47 @@ +/** + * ToolLogRow — a compact log row for the right pane of ToolAggregateCard. + * + * Visually lighter than ToolCallRow — no background fill, no text type + * label. The leading dot encodes the tool family via color: + * read/grep/ls each get their tool-family hue from StatusDot; the + * in-flight `running` variant uses an inline pulsing orange dot (not + * StatusDot, because StatusDot stays static for consistency with + * ScoutRow — see design-system.md § StatusDot). + * + * Used in: ToolAggregateCard right pane (not yet built — this molecule + * is delivered ahead of the card). + */ + +import { StatusDot } from '../atoms/StatusDot' +import './ToolLogRow.css' + +interface ToolLogRowProps { + /** Tool family for completed ops (drives dot color), or 'running' for + * the in-flight op (drives both the pulsing dot and the muted-text + * styling). Completed and in-flight states always move together, so + * one prop controls both. */ + status: 'read' | 'grep' | 'ls' | 'running' + command: string + /** Optional right-aligned metric text. Examples: "400 lines · 16.1 KB", + * "46 matches · 6 files", "7 entries". When status is 'running', the + * metric typically reads like "reading…" or "grepping…". */ + metric?: string +} + +export function ToolLogRow({ status, command, metric }: ToolLogRowProps) { + const isRunning = status === 'running' + return ( + <div className={`tlr tlr--${status}`}> + {isRunning ? ( + // Inline pulsing dot — intentionally NOT StatusDot. See file header. + <span className="tlr-running-dot" aria-label="running" /> + ) : ( + <StatusDot status={status} size="sm" /> + )} + <span className="tlr-command">{command}</span> + {metric && <span className="tlr-metric">{metric}</span>} + </div> + ) +} + +export default ToolLogRow diff --git a/frontend/src/components/molecules/ToolStatBlock.css b/frontend/src/components/molecules/ToolStatBlock.css new file mode 100644 index 0000000..c95ba9c --- /dev/null +++ b/frontend/src/components/molecules/ToolStatBlock.css @@ -0,0 +1,45 @@ +.tsb { + display: flex; + flex-direction: column; + gap: 3px; +} + +/* ---- Header row (dot + name + op count) ---- */ +.tsb-header { + display: flex; + align-items: center; + gap: 8px; +} + +.tsb-name { + font-family: var(--font-mono); + font-size: 12px; + color: var(--text-primary); + font-weight: 500; +} + +.tsb-opcount { + font-family: var(--font-mono); + font-size: 11px; + color: var(--text-muted); + margin-left: auto; +} + +/* ---- Meta lines (aligned under the tool name, past the dot) ---- */ +.tsb-meta { + display: flex; + flex-direction: column; + padding-left: 16px; +} + +.tsb-meta-line { + font-family: var(--font-mono); + font-size: 11px; + color: var(--text-muted); + line-height: 1.4; +} + +/* ---- Active variant ---- */ +.tsb--active .tsb-name { + color: var(--color-orange); +} diff --git a/frontend/src/components/molecules/ToolStatBlock.tsx b/frontend/src/components/molecules/ToolStatBlock.tsx new file mode 100644 index 0000000..2b6c19c --- /dev/null +++ b/frontend/src/components/molecules/ToolStatBlock.tsx @@ -0,0 +1,71 @@ +/** + * ToolStatBlock — per-tool-family statistics block for the left pane of + * ToolAggregateCard. + * + * Displays aggregated scope information for one tool family (read, grep, + * or ls): operation count in the header, then free-form meta lines below + * aligned under the tool name. Each block represents one tool family's + * presence inside a single ToolAggregateCard; the card renders one block + * per family that has at least one operation. + * + * Active state: when the currently-running operation in the enclosing + * ToolAggregateCard belongs to this block's tool family, the caller + * passes active={true} and the tool name renders in orange. The dot and + * op count are not affected. Only one block within a card can be active + * at a time — enforcement is the caller's responsibility. + * + * Used in: ToolAggregateCard left pane (not yet built — this molecule + * is delivered ahead of the card). + */ + +import { StatusDot } from '../atoms/StatusDot' +import './ToolStatBlock.css' + +interface ToolStatBlockProps { + /** Tool family. Drives the StatusDot color. */ + type: 'read' | 'grep' | 'ls' + /** Display name shown next to the dot. Currently mirrors `type` in all + * call sites — the two are kept separate per the design-system spec + * to allow future alternative display names without an API break. */ + name: string + /** Pre-formatted operation count, e.g. "4 ops", "1 op". The caller + * handles pluralization and number-to-string formatting. */ + opCount: string + /** One or more meta lines describing aggregate scope. Each line is + * a pre-formatted string, e.g. "612 lines · 24.7 KB", + * "3 files touched", "76 matches". Empty array is allowed; the + * block then renders with only its header row. */ + metaLines: string[] + /** When true, the tool name renders in orange. Set by the parent + * ToolAggregateCard when the in-flight operation belongs to this + * tool family. */ + active?: boolean +} + +export function ToolStatBlock({ + type, + name, + opCount, + metaLines, + active = false, +}: ToolStatBlockProps) { + const cls = `tsb${active ? ' tsb--active' : ''}` + return ( + <div className={cls}> + <div className="tsb-header"> + <StatusDot status={type} size="md" /> + <span className="tsb-name">{name}</span> + <span className="tsb-opcount">{opCount}</span> + </div> + {metaLines.length > 0 && ( + <div className="tsb-meta"> + {metaLines.map((line, i) => ( + <div key={i} className="tsb-meta-line">{line}</div> + ))} + </div> + )} + </div> + ) +} + +export default ToolStatBlock diff --git a/frontend/src/store/index.ts b/frontend/src/store/index.ts index 82f4a65..e4e05fd 100644 --- a/frontend/src/store/index.ts +++ b/frontend/src/store/index.ts @@ -37,13 +37,46 @@ export interface StepEntry { type: 'step'; step: number; stepName: string; total export interface UserMessageEntry { type: 'user_message'; content: string; timestampMs: number } interface BaseToolEntry { callId: string; inFlight: boolean } -export interface ToolReadEntry extends BaseToolEntry { type: 'tool_read'; file: string; lines: string } export interface ToolWriteEntry extends BaseToolEntry { type: 'tool_write'; file: string } export interface ToolEditEntry extends BaseToolEntry { type: 'tool_edit'; file: string } export interface ToolBashEntry extends BaseToolEntry { type: 'tool_bash'; command: string } -export interface ToolGrepEntry extends BaseToolEntry { type: 'tool_grep'; pattern: string } -export interface ToolLsEntry extends BaseToolEntry { type: 'tool_ls'; path: string } export interface ToolGenericEntry extends BaseToolEntry { type: 'tool_generic'; toolName: string; summary: string } + +// Aggregate children — exploration tools (read/grep/ls) never appear as +// top-level ConversationEntry values. They live only inside ToolAggregateEntry. +export interface AggregateReadChild extends BaseToolEntry { + tool: 'read' + file: string + lines: string + startedAtMs: number + completedAtMs: number | null + linesRead: number | null + bytesRead: number | null +} +export interface AggregateGrepChild extends BaseToolEntry { + tool: 'grep' + pattern: string + startedAtMs: number + completedAtMs: number | null + matches: number | null + filesMatched: number | null +} +export interface AggregateLsChild extends BaseToolEntry { + tool: 'ls' + path: string + startedAtMs: number + completedAtMs: number | null + entries: number | null + directories: number | null +} +export type AggregateChild = AggregateReadChild | AggregateGrepChild | AggregateLsChild + +export interface ToolAggregateEntry { + type: 'tool_aggregate' + children: AggregateChild[] + startedAtMs: number +} + export interface DebugStepGuidanceEntry { type: 'debug_step_guidance'; content: string } export interface PhaseBoundaryEntry { type: 'phase_boundary'; phase: string; message: string; description: string } @@ -52,8 +85,8 @@ export interface YieldEntry { type: 'yield'; prompt: string; suggestions: Sugges export type ConversationEntry = | ThinkingEntry | TextEntry | StepEntry | UserMessageEntry - | ToolReadEntry | ToolWriteEntry | ToolEditEntry - | ToolBashEntry | ToolGrepEntry | ToolLsEntry | ToolGenericEntry + | ToolWriteEntry | ToolEditEntry | ToolBashEntry | ToolGenericEntry + | ToolAggregateEntry | DebugStepGuidanceEntry | PhaseBoundaryEntry | YieldEntry export interface Conversation { diff --git a/frontend/src/styles/variables.css b/frontend/src/styles/variables.css index 1ed9227..b3e286e 100644 --- a/frontend/src/styles/variables.css +++ b/frontend/src/styles/variables.css @@ -169,6 +169,12 @@ --status-failed: #c44; + /* ===== Tool Family Indicator Colors ===== */ + --dot-read: #5a9a8a; + --dot-grep: #7ab0a0; + --dot-ls: #4a8878; + + /* ===== Font Families ===== */ --font-display: Georgia, "Times New Roman", serif; --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; From ffd20385f1b16bf2046593d4303d0f96b9bd0429 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 19 Apr 2026 11:54:19 +0700 Subject: [PATCH 408/412] docs: specify tool aggregation UI in design system --- docs/design-system.md | 312 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 312 insertions(+) diff --git a/docs/design-system.md b/docs/design-system.md index 2e5cbeb..93ad956 100644 --- a/docs/design-system.md +++ b/docs/design-system.md @@ -56,10 +56,62 @@ The single source of truth for koan's visual design. `src/styles/variables.css` | `--settings-nav-width` | 152px | Side navigation column width on the Settings page. | | `--settings-max-width` | 960px | Max width for the Settings page layout container (nav + content). | +### Tool family indicator colors + +| Token | Hex | Usage | +| ------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--dot-read` | `#5a9a8a` | `StatusDot` `status="read"`. Identifies `read` operations in tool aggregate cards. Aliases `--color-teal`; the alias pattern matches `--status-done`. | +| `--dot-grep` | `#7ab0a0` | `StatusDot` `status="grep"`. Identifies `grep` operations. Slightly lighter teal than `--dot-read`; distinguishable from `--dot-read` at 8px stat-block size, secondary to the command text at 6px log-row size. | +| `--dot-ls` | `#4a8878` | `StatusDot` `status="ls"`. Identifies `ls` operations. Slightly darker teal than `--dot-read`. | + +All three tokens belong to the teal family because all three tools are +read-only exploration operations. Orange is reserved for active state +(`--color-orange`) and must not appear in tool-family indicator colors. + --- ## Atoms +### StatusDot + +A small colored circle indicating either an operational state or a tool family. + +Container: `display: inline-block`, `border-radius: var(--radius-circle)`, +`flex-shrink: 0`. All variants are static — no animation. In-flight activity +indicators in consuming molecules are implemented inline (see `ToolCallRow`'s +`.tcr-running-dot` pattern) rather than through `StatusDot`, so that +`StatusDot` stays a pure visual primitive and adjacent features that already +use `StatusDot` (e.g., `ScoutRow`) are not affected by changes in this area. + +**Sizes:** + +- `sm`: 6px × 6px. Used inside `ToolLogRow` log rows where vertical density + matters. +- `md`: 8px × 8px. Default. Used in `ToolStatBlock` stat blocks, scout tables, + artifact cards, and the header orchestrator indicator. + +**Status variants — operational state:** + +- `running`: `background: var(--status-running)` (orange). Static. +- `done`: `background: var(--status-done)` (teal). Static. +- `queued`: `background: var(--status-queued)` (neutral warm gray). Static. +- `failed`: `background: var(--status-failed)` (red). Static. + +**Status variants — tool family:** + +- `read`: `background: var(--dot-read)`. Static. +- `grep`: `background: var(--dot-grep)`. Static. +- `ls`: `background: var(--dot-ls)`. Static. + +The tool-family variants share the `status` prop with the operational variants +intentionally — the geometry and usage pattern are identical, and a single +`status` prop keeps consumers' call sites readable. + +Type: `Status = 'running' | 'done' | 'queued' | 'failed' | 'read' | 'grep' | 'ls'`, +`Size = 'sm' | 'md'`. + +Props: `status: Status`, `size?: Size` (default `'md'`). + ### TextInput Shared text input used in settings forms, NewRunForm textarea, NewRunForm concurrency input, RadioOption/CheckboxOption custom text input, and FeedbackInput textarea. @@ -313,6 +365,206 @@ Footer: flex row. Left: hint text in `--type-label` (11px), `--text-hint`. Defau Props: `placeholder?: string`, `onSend?: (text: string) => void`, `disabled?: boolean`, `availableCommands?: PhaseCommand[]`, `onPaletteToggle?: (open: boolean) => void`. +#### ToolCallRow + +A single horizontal row representing a standalone tool call. Used for +non-exploration tools (`bash`, `write`, `edit`) that keep their individual +visual weight outside aggregate cards. + +Container: `display: flex`, `align-items: center`, `gap: 10px`, +`background: var(--bg-tool-row)`, `border-radius: var(--radius-md)`, +`padding: var(--padding-tool-row)` (7px 14px). + +Status indicator column (`width: 13px`, `flex-shrink: 0`) — existing markup, +not routed through `StatusDot`: + +- `done`: teal check SVG (`stroke: var(--color-teal)`, 13×13, 2.5 stroke + width). +- `running`: 6px orange dot rendered as an inline `span.tcr-running-dot`, + animated by the local `@keyframes tcr-pulse` at 1.5s ease-in-out infinite. +- `error`: `✕` character, `color: var(--status-failed)`, 11px. + +Type label (`min-width: 36px`, `flex-shrink: 0`): +`--type-tool-type` (12px), `--text-muted`. Examples: "bash", "write", "edit". + +Command / path (`flex: 1`, `min-width: 0`): +`--font-mono`, `--type-tool-path` (12px), `--text-body`, `white-space: nowrap`, +`overflow: hidden`, `text-overflow: ellipsis`. The actual path or shell +command. + +Metric (optional, `flex-shrink: 0`, `padding-left: 12px`): +`--font-mono`, `--type-tool-path` (12px), `--text-muted`. Right-aligned. +Added in this spec; absent in the original `ToolCallRow`. Examples: +`"22.8 KB · new"`, `"2.4s · 140 B out"`, `"3 hunks · ±24 lines"`. + +Error state: container background `#f6e8e8` (hardcoded, candidate for +`--bg-tool-row-error` in a future token pass), command and metric text +`color: var(--text-danger-body)`. + +Running state: container `opacity: 0.8`. + +Props: `tool: string`, `command: string`, `status?: 'done' | 'running' | 'error'` +(default `'done'`), `metric?: string`. + +#### ToolLogRow + +A compact, no-background log row used inside the right pane of +`ToolAggregateCard`. Visually lighter than `ToolCallRow` — no background fill, +no explicit type label (the colored dot encodes the tool family instead). + +Container: `display: flex`, `align-items: center`, `gap: 10px`, +`padding: 3px 0`, `font-family: var(--font-mono)`, `font-size: 12px`, +`line-height: 1.5`. + +Status indicator: one of + +- `StatusDot size="sm" status={type}` where `type` is `read`, `grep`, or `ls`, + for completed operations. Static teal-family dot. +- An inline pulsing orange dot (6px, same pattern as `ToolCallRow`'s + `.tcr-running-dot` — local `@keyframes` on the molecule, independent of + `StatusDot`) for the in-flight operation. + +Command (`flex: 1`, `min-width: 0`): `--font-mono`, `font-size: 12px`, +`--text-body`, `white-space: nowrap`, `overflow: hidden`, +`text-overflow: ellipsis`. Typically a compact path or pattern +(e.g., `"plan.md:160-560"`, `"^from|^import"`). + +Metric (optional, `flex-shrink: 0`, `padding-left: 12px`): +`font-size: 11px`, `--text-muted`. Right-aligned. Examples: +`"400 lines · 16.1 KB"`, `"46 matches · 6 files"`. + +Running state: command text color becomes `--text-subtle`, metric text color +becomes `--color-orange`. This muted-text + orange-metric treatment fires +whenever the row is in its `running` status — there is no separate boolean +prop for it. A completed read renders with a `--dot-read` StatusDot, normal +command text, and a `--text-muted` metric; an in-flight read renders with a +pulsing orange dot, `--text-subtle` command text, and a `--color-orange` +metric text like "reading…". + +Props: `status: 'read' | 'grep' | 'ls' | 'running'`, `command: string`, +`metric?: string`. + +The single `status` prop covers both the dot's visual and the row's running- +state styling. For an in-flight operation, callers pass `status="running"` +and get both the pulsing orange dot and the dimmed text; for a completed +operation, callers pass the tool-family variant and get both the static +teal-family dot and normal text. The two states always move together, so +collapsing them into one prop keeps the API honest. + +#### ToolStatBlock + +A single per-tool-type statistics block in the left pane of +`ToolAggregateCard`. Presents aggregated scope information — operation count, +bytes, lines, matches, files touched — for one tool family. + +Container: `display: flex`, `flex-direction: column`, `gap: 3px`. Multiple +blocks within a pane are separated by `gap: 12px` via the parent. + +Header row: `display: flex`, `align-items: center`, `gap: 8px`. Contains: + +- `StatusDot size="md" status={type}` where `type` is `read`, `grep`, or `ls`. +- Tool name: `--font-mono`, `font-size: 12px`, `--text-primary`, + `font-weight: 500`. E.g., "read", "grep", "ls". +- Op count: `--font-mono`, `font-size: 11px`, `--text-muted`, + `margin-left: auto` (right-aligned). E.g., "4 ops". + +Meta lines (`padding-left: 16px` to align under the tool name, past the dot): +`--font-mono`, `font-size: 11px`, `--text-muted`, `line-height: 1.4`. +Multiple lines rendered via `<br>` or separate elements. Examples: +`"612 lines · 24.7 KB"`, `"3 files touched"`, `"76 matches"`. + +Active variant: when the currently-running operation in the aggregate belongs +to this tool type, the tool name becomes `color: var(--color-orange)`, +font-weight 500. The StatusDot and op count are unchanged. Only one +`ToolStatBlock` in a card can be active at a time. + +Props: `type: 'read' | 'grep' | 'ls'`, `name: string`, `opCount: string` +(formatted, e.g., `"4 ops"`), `metaLines: string[]`, `active?: boolean`. + +#### ToolAggregateCard + +A card that groups consecutive exploration tool calls (`read`, `grep`, `ls`) +into a single two-pane visual unit. Always rendered fully expanded — there is +no collapsed state. Replaces the run of individual `ToolCallRow` rows that +would otherwise wall the content stream. + +Container: `--bg-card`, `0.5px solid var(--border-card)`, +`border-left: 3px solid var(--color-orange)`, `--radius-xl` (10px), +`overflow: hidden`. The 3px orange left border follows the existing +"left border = content source" convention — tool calls are agent output, so +the card inherits the same source accent as `ProseCard`. The border color +does NOT change when the card is in its active state. + +Active state — signaled only in the header and in the inner components, not +in the outer border. When any child operation is in-flight: + +1. The header renders a pulsing orange dot plus a short label + (e.g., "reading projections.py"). This is the primary signal — visible + at a glance, persistent through the entire active period. +2. The `ToolStatBlock` for the tool type that owns the in-flight operation + renders with `active={true}`, turning its tool name orange. +3. The in-flight `ToolLogRow` in the right pane renders with + `status="running"`, replacing its dot with a pulsing orange dot and + dimming its command text. + +When no child operation is in-flight, the header does not render the running +indicator and no stat block or log row is in the active/running state. + +Header: `display: flex`, `align-items: baseline`, `gap: 10px`, +`padding: 10px 18px 9px 18px`, `border-bottom: 1px solid var(--border-divider-light)`. +Contains, in order: + +1. Aggregate label: `--type-tool-type` (12px), `--text-muted`, + `letter-spacing: 0.3px`. Always the literal string "explore". +2. Operation count: `--type-body` (14px), `--text-primary`, `font-weight: 500`. + E.g., "8 operations". +3. Spacer (`flex: 1`). +4. Running indicator (only when `runningLabel` prop is set): inline-flex + group — a 6px orange pulsing dot (inline span with local `@keyframes`, + same pattern as `ToolCallRow`'s `.tcr-running-dot`, not `StatusDot`) + plus a short label in `--font-mono`, `font-size: 11px`, `--color-orange`. + The label is a human-readable fragment like "reading projections.py" or + "grepping" — supplied by the caller; the card does not compute it. + Padding: gap 5px between dot and label. +5. Elapsed (optional): `--font-mono`, `font-size: 11px`, `--text-hint`, + `padding-left: 8px`. A formatted duration string like "3m 24s". Shown for + both completed and active cards. This is the aggregate's total wall-clock + duration — per-operation durations are intentionally NOT shown anywhere, + because exploration tools return near-instantly and per-op duration is + noise. See the design rationale section on duration vs scope metrics. + +Body: `display: grid`, `grid-template-columns: 240px 1fr`. Two panes with a +vertical divider between them. + +Left pane (stats): `background: var(--bg-card-warm)`, +`border-right: 1px solid var(--border-divider-light)`, `padding: 14px 16px`, +`display: flex`, `flex-direction: column`, `gap: 12px`. Contains a stack of +`ToolStatBlock` molecules, one per tool family present in the aggregate. Tool +families with zero operations are not rendered. Ordering: `read`, `grep`, +`ls` (alphabetical-by-convention; the caller orders). + +Right pane (log): `padding: 11px 18px 11px 16px`, `display: flex`, +`flex-direction: column`, `gap: 0`. Contains a stack of `ToolLogRow` +molecules in strict chronological order. The currently-running row, if any, +is rendered last. + +The two panes carry orthogonal information. The left pane is enduring +summary — operations fold into their type's totals. The right pane is the +chronological event stream. The left pane is meant to land the eye; the +right pane is meant to scroll past. + +Props: `operationCount: number`, `runningLabel?: string` +(when set, card is in active state and the running indicator renders), +`elapsed?: string`, `statsPane: ReactNode` (typically a list of +`ToolStatBlock` elements), `logPane: ReactNode` (typically a list of +`ToolLogRow` elements). + +The card uses slot-based composition rather than prescribed data arrays, +because the grouping logic that produces the stats and log rows lives +outside the card (in a utility function consumed by `App.tsx`). Keeping +the card slot-based keeps it pure layout and lets the molecules it contains +stay independently usable. + ### Settings Molecules #### FormRow @@ -549,3 +801,63 @@ The dot-on-divider pattern is extended with color semantics. A **teal dot** sign ### Review card pattern The ReviewPanel card uses `border-top: 3px solid --color-orange`, the same "panel-level attention" signal as ElicitationPanel's decision panel. Both are organisms that yield the conversation and require user action to proceed. The visual consistency communicates this shared interaction pattern: the workflow is paused, waiting for you. + +### Tool aggregation scope + +Exploration tools (`read`, `grep`, `ls`) are aggregated into +`ToolAggregateCard` when two or more appear consecutively in the conversation +stream without any other entry type between them (prose, thinking, user +message, step boundary, phase marker, `bash`, `write`, `edit`, or any other +tool). A lone `read` renders as a standalone `ToolCallRow`. A run of two or +more consecutive reads/greps/ls's collapses into one card. + +`bash`, `write`, and `edit` are never aggregated. `bash` has too much +semantic variance — it can be a one-line formatter, a heavy test run, or an +arbitrary script — and compressing disparate bash calls into a summary +obscures rather than clarifies. `write` and `edit` are mutations; each is +individually significant. All three render as standalone `ToolCallRow`s. + +### Tool aggregation active state + +Active state on `ToolAggregateCard` is communicated through three in-card +signals, not through a border color change. When an operation inside the +card is in-flight: + +1. The card header renders a pulsing orange dot plus a short label + (e.g., "reading projections.py"). +2. The stat block for the tool type that owns the in-flight operation + renders with `active={true}`, turning its tool name orange. +3. The in-flight log row in the right pane renders with `status="running"`, + replacing its dot with a pulsing orange dot and dimming its command + text. + +The card's left border stays orange throughout (see "Left border = content +source"). Not changing the border preserves the content-source convention +without conflating "this is agent content" with "this is happening right +now." The three in-card signals are enough: the user always has a clear +"something is still happening" indicator without ambiguity in the outer +chrome. + +The signal is qualitative and textual (label + pulsing dot) rather than +quantitative and spatial (a progress bar), because the total number of +operations is not known in advance. A horizontal progress bar would falsely +imply a completion endpoint; a pulsing dot next to a label does not. + +### Duration vs scope metrics + +`ToolAggregateCard` and `ToolLogRow` show per-operation scope metrics — +bytes read, lines read, matches found, files touched, hunks edited — and +deliberately omit per-operation duration. Exploration tools return in +milliseconds in practice, so per-op duration is noise that competes for +attention with the signal. + +Per-aggregate duration is shown once, in the card header, because the +total wall-clock time across a run of exploration ops is legitimately +useful — it tells the user whether the agent is thinking slowly, spawning +many ops, or encountering a tool that happened to be genuinely slow. The +distinction is scale: individual ops are fast, aggregates are not. + +`ToolCallRow` (standalone) does show a metric that may include duration for +`bash` specifically, because bash duration is frequently meaningful. +`ToolCallRow` for `write` and `edit` shows size/line-count metrics without +duration. From 61b63aa5711b9c1393da6c72c538ec780249b034 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 19 Apr 2026 11:54:38 +0700 Subject: [PATCH 409/412] chore: align eval fixtures with LFS snapshot archives --- .gitignore | 5 ----- evals/dataset.py | 7 ++++--- evals/fixtures/.gitattributes | 1 + evals/fixtures/README.md | 15 +++++++++------ evals/solver.py | 17 +++++++++++++---- 5 files changed, 27 insertions(+), 18 deletions(-) create mode 100644 evals/fixtures/.gitattributes diff --git a/.gitignore b/.gitignore index f2426ff..804a7d9 100644 --- a/.gitignore +++ b/.gitignore @@ -12,8 +12,3 @@ koan/web/static/app/ frontend/node_modules/ frontend/dist/ __pycache__/ - -# Eval fixture snapshots are large binaries captured manually by Leon. -# Only README.md and task.md are committed; snapshot.tar.gz and memory/ are local. -evals/fixtures/*/snapshot.tar.gz -evals/fixtures/*/memory/ diff --git a/evals/dataset.py b/evals/dataset.py index f3ab4b2..13e23c0 100644 --- a/evals/dataset.py +++ b/evals/dataset.py @@ -2,8 +2,10 @@ # Loads benchmark fixtures as an Inspect AI MemoryDataset. # # Each fixture directory must contain task.md (the task description). -# snapshot.tar.gz and memory/ are optional at load time (the solver checks -# for them at run time). Directories without task.md are skipped silently. +# snapshot.tar.gz is optional at load time (the solver checks at run time). +# The snapshot is a `git archive` of the project, so .koan/memory/*.md rides +# along inside it -- no separate memory/ directory. Directories without +# task.md are skipped silently. from pathlib import Path @@ -29,7 +31,6 @@ def load_dataset(fixtures_dir: Path = FIXTURES_DIR) -> MemoryDataset: "fixture_dir": str(fixture_dir), "fixture_name": fixture_dir.name, "snapshot_path": str(fixture_dir / "snapshot.tar.gz"), - "memory_path": str(fixture_dir / "memory"), }, )) return MemoryDataset(samples, name="koan-bench") diff --git a/evals/fixtures/.gitattributes b/evals/fixtures/.gitattributes new file mode 100644 index 0000000..f087b42 --- /dev/null +++ b/evals/fixtures/.gitattributes @@ -0,0 +1 @@ +*.tar.gz filter=lfs diff=lfs merge=lfs -text diff --git a/evals/fixtures/README.md b/evals/fixtures/README.md index 129bdbe..9c3b2c8 100644 --- a/evals/fixtures/README.md +++ b/evals/fixtures/README.md @@ -5,14 +5,17 @@ Each subdirectory is one benchmark fixture. Structure: <fixture-name>/ task.md -- task description (UTF-8 plain text) snapshot.tar.gz -- git archive of the target project at a specific commit - memory/ -- copy of .koan/memory/ at that point -`snapshot.tar.gz` and `memory/` are gitignored -- they are large and must be -captured manually by Leon. Only `task.md` is committed. +`task.md` is a small text file and is committed normally. +`snapshot.tar.gz` is stored via git-lfs (see `.gitattributes`). Contributors +need `git lfs install` + `git lfs pull` to hydrate the tarballs; otherwise +the solver will fail with a "not a gzip file" error because the checkout +contains LFS pointer files instead of the real blobs. + +The snapshot is a `git archive` of the project, so `.koan/memory/*.md` rides +along inside it. No separate memory copy is needed. To capture a new fixture from the koan project itself: - mkdir -p evals/fixtures/<name>/memory git archive HEAD --format=tar.gz -o evals/fixtures/<name>/snapshot.tar.gz - cp .koan/memory/*.md evals/fixtures/<name>/memory/ - echo "Your task description" > evals/fixtures/<name>/task.md + printf 'Your task description\n' > evals/fixtures/<name>/task.md diff --git a/evals/solver.py b/evals/solver.py index 2db5db6..c583aaf 100644 --- a/evals/solver.py +++ b/evals/solver.py @@ -204,21 +204,30 @@ def koan_solver(timeout: int = DEFAULT_TIMEOUT) -> Solver: async def solve(state: TaskState, generate) -> TaskState: import uvicorn - from koan.config import KoanConfig + from koan.config import load_koan_config from koan.state import AppState from koan.web.app import create_app snapshot_path = Path(state.metadata["snapshot_path"]) with tempfile.TemporaryDirectory() as project_tmp: - # Extract the project snapshot so the orchestrator can inspect it. - # If no snapshot exists yet (no fixtures committed), skip silently. + # Extract the project snapshot so the orchestrator sees it as the + # project root. If no snapshot exists yet (no fixtures committed), + # leave project_tmp empty and koan will operate on an empty dir. if snapshot_path.exists(): with tarfile.open(snapshot_path, "r:gz") as tar: tar.extractall(project_tmp) app_state = AppState() - app_state.config = KoanConfig() + # Load the user's real config so probe_results finds installed + # agents. Without this, /api/start-run fails with no_runners. + app_state.config = await load_koan_config() + # Point koan at the extracted snapshot rather than the solver's + # CWD. AppState.project_dir flows through task.json to every + # spawned subagent as its spawn cwd. + app_state.project_dir = project_tmp + # Don't try to open a browser during headless evals. + app_state.open_browser = False app = create_app(app_state) port = _find_free_port() From 67471d328720df0d3a34f1daead1e5582d8d357b Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 19 Apr 2026 14:13:55 +0700 Subject: [PATCH 410/412] fix: restore thinking display for opus claude models --- ...requires-thinking-display-summarized-to.md | 9 ++++ koan/runners/claude.py | 4 ++ tests/test_runners.py | 45 +++++++++++++++++++ 3 files changed, 58 insertions(+) create mode 100644 .koan/memory/0055-opus-47-requires-thinking-display-summarized-to.md diff --git a/.koan/memory/0055-opus-47-requires-thinking-display-summarized-to.md b/.koan/memory/0055-opus-47-requires-thinking-display-summarized-to.md new file mode 100644 index 0000000..742d7d2 --- /dev/null +++ b/.koan/memory/0055-opus-47-requires-thinking-display-summarized-to.md @@ -0,0 +1,9 @@ +--- +title: Opus 4.7+ requires --thinking-display summarized to restore thinking tokens + in Claude CLI stream-json +type: context +created: '2026-04-19T06:21:20Z' +modified: '2026-04-19T06:21:20Z' +--- + +This entry records the addition of `--thinking-display summarized` to Claude launch arguments in koan. On 2026-04-19, Leon reported that Anthropic's Opus 4.7 release changed Claude Code CLI behavior: the default thinking-display mode changed to "off", omitting thinking tokens from the stream-json output entirely unless the consumer opts in via the undocumented `--thinking-display` flag. In response, Leon directed that the Claude runner in `koan/runners/claude.py` append `--thinking-display summarized` to the command whenever the selected model alias contained "opus" (case-insensitive substring match, inserted between `--model X` and the `installation.extra_args` spread). The `summarized` value produced condensed reasoning summaries suitable for the projection store's thinking-block rendering path, while the Opus 4.7+ default produced no thinking content at all. Leon chose substring matching over exact or prefix matching on the rationale that users were assumed to run the latest Opus model; earlier Opus releases (4.6 and prior) accepted the flag as a no-op, so the substring match was safe across versions. The flag was not present in Claude Code's published CLI reference at that date; Leon discovered it empirically after the 4.7 upgrade broke thinking-block visibility in the koan frontend. diff --git a/koan/runners/claude.py b/koan/runners/claude.py index 058f5f5..d1fd947 100644 --- a/koan/runners/claude.py +++ b/koan/runners/claude.py @@ -173,6 +173,10 @@ def build_command( if thinking != "disabled": cmd.extend(["--effort", _EFFORT_MAP[thinking]]) cmd.extend(["--model", model]) + # Opus 4.7+ suppresses thinking tokens by default; summarized mode + # preserves visibility without overwhelming the stream. + if "opus" in model.lower(): + cmd.extend(["--thinking-display", "summarized"]) cmd.extend(installation.extra_args) return cmd diff --git a/tests/test_runners.py b/tests/test_runners.py index 88a989e..5e7f950 100644 --- a/tests/test_runners.py +++ b/tests/test_runners.py @@ -512,6 +512,51 @@ def test_effort_max_opus(self, tmp_path): assert cmd[idx + 1] == "max" +# -- ClaudeRunner: opus thinking-display -------------------------------------- + +class TestClaudeRunnerOpusThinkingDisplay: + def test_opus_alias_injects_thinking_display(self, tmp_path): + runner = ClaudeRunner(subagent_dir=str(tmp_path)) + cmd = runner.build_command("p", "http://x/mcp", _install("claude"), "opus", "disabled") + assert "--thinking-display" in cmd + idx = cmd.index("--thinking-display") + assert cmd[idx + 1] == "summarized" + + def test_opus_with_suffix_still_matches(self, tmp_path): + runner = ClaudeRunner(subagent_dir=str(tmp_path)) + cmd = runner.build_command("p", "http://x/mcp", _install("claude"), "opus[1m]", "disabled") + assert "--thinking-display" in cmd + idx = cmd.index("--thinking-display") + assert cmd[idx + 1] == "summarized" + + def test_case_insensitive_match(self, tmp_path): + runner = ClaudeRunner(subagent_dir=str(tmp_path)) + cmd = runner.build_command("p", "http://x/mcp", _install("claude"), "OPUS", "disabled") + assert "--thinking-display" in cmd + + def test_non_opus_model_has_no_thinking_display(self, tmp_path): + runner = ClaudeRunner(subagent_dir=str(tmp_path)) + for model in ("sonnet", "haiku"): + cmd = runner.build_command("p", "http://x/mcp", _install("claude"), model, "disabled") + assert "--thinking-display" not in cmd + + def test_thinking_display_before_extra_args(self, tmp_path): + runner = ClaudeRunner(subagent_dir=str(tmp_path)) + inst = AgentInstallation( + alias="claude", runner_type="claude", binary="claude", + extra_args=["--verbose"], + ) + cmd = runner.build_command("p", "http://x/mcp", inst, "opus", "disabled") + # extra_args must remain last + assert cmd[-1] == "--verbose" + assert "--thinking-display" in cmd + td_idx = cmd.index("--thinking-display") + # Compare against the LAST --verbose (from extra_args), not the + # built-in --verbose that the runner hardcodes earlier in the command. + verbose_idx = len(cmd) - 1 - cmd[::-1].index("--verbose") + assert td_idx < verbose_idx + + # -- ClaudeRunner: list_models ------------------------------------------------- class TestClaudeRunnerListModels: From f1d6de7d5e51c7a888602afa95ee89b412fee27e Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 19 Apr 2026 14:14:04 +0700 Subject: [PATCH 411/412] fix: compose claude permission and dir flags at spawn time --- ...-mode-acceptedits-auto-approves-a-fixed.md | 9 +++ ...e-permissiondirectory-flags-composed-at.md | 9 +++ koan/subagent.py | 43 +++++++++-- koan/web/app.py | 5 +- tests/test_subagent.py | 76 +++++++++++++++++++ 5 files changed, 133 insertions(+), 9 deletions(-) create mode 100644 .koan/memory/0056-permission-mode-acceptedits-auto-approves-a-fixed.md create mode 100644 .koan/memory/0057-claude-permissiondirectory-flags-composed-at.md diff --git a/.koan/memory/0056-permission-mode-acceptedits-auto-approves-a-fixed.md b/.koan/memory/0056-permission-mode-acceptedits-auto-approves-a-fixed.md new file mode 100644 index 0000000..75c1114 --- /dev/null +++ b/.koan/memory/0056-permission-mode-acceptedits-auto-approves-a-fixed.md @@ -0,0 +1,9 @@ +--- +title: --permission-mode acceptEdits auto-approves a fixed Bash subset inside --add-dir + scope +type: context +created: '2026-04-19T06:21:23Z' +modified: '2026-04-19T06:21:23Z' +--- + +This entry documents permission-mode behavior for Claude subagents in koan. On 2026-04-19, during the plan-workflow Claude-CLI-flags change, Leon cited Anthropic's documentation establishing that `--permission-mode acceptEdits` auto-approves two categories of Claude Code tool calls: (1) all Write and Edit tool calls, and (2) a fixed set of filesystem Bash commands -- `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`, optionally prefixed with safe environment variables (`LANG=C`, `NO_COLOR=1`) or wrapped in process wrappers (`timeout`, `nice`, `nohup`). Auto-approval applied only to paths inside the CLI's working directory and any directories added via `--add-dir`. Koan's Claude subagents ran in headless mode (`-p` + `--output-format stream-json`), which could not respond to interactive permission prompts, so Bash commands outside this safe subset would hang indefinitely when invoked. Leon accepted this tradeoff for the change, and the koan design chose `acceptEdits` as the unconditional permission mode for every Claude subagent (orchestrator, executor, scout). Leon also stated an intent to repurpose the `--yolo` flag into a separate non-interactive mode at a later date, at which point workflows requiring broader Bash execution could bypass the safe-subset restriction. diff --git a/.koan/memory/0057-claude-permissiondirectory-flags-composed-at.md b/.koan/memory/0057-claude-permissiondirectory-flags-composed-at.md new file mode 100644 index 0000000..797928e --- /dev/null +++ b/.koan/memory/0057-claude-permissiondirectory-flags-composed-at.md @@ -0,0 +1,9 @@ +--- +title: Claude permission/directory flags composed at spawn time in subagent.py, not + in build_command or extra_args +type: decision +created: '2026-04-19T06:21:28Z' +modified: '2026-04-19T06:21:28Z' +--- + +This entry records the argv-composition split for Claude subagents in koan. On 2026-04-19, during the plan-workflow Claude-CLI-flags change, Leon decided that Claude-specific flags split across two sites: `ClaudeRunner.build_command` in `koan/runners/claude.py` produced a stable command skeleton (model-only-dependent flags like `--thinking-display summarized` lived here, gated by `"opus" in model.lower()`), and `spawn_subagent` in `koan/subagent.py` appended Claude-specific argv extensions afterward via the new `_claude_post_build_args(role, run_dir, project_dir)` helper (run-context-dependent flags: `--add-dir <project_dir>`, `--add-dir <run_dir>`, `--permission-mode acceptEdits`, alongside the previously-existing `--tools`, `--disable-slash-commands`, `--strict-mcp-config`). Two alternatives were explicitly rejected during the intake phase that preceded the decision. First, extending the `Runner.build_command` protocol with `run_dir` and `project_dir` parameters: rejected because it forced signature churn on `CodexRunner` and `GeminiRunner` for flags they did not need, violating the "codex and gemini untouched" scope constraint. Second, writing the flags into `AgentInstallation.extra_args` as done for the old `--dangerously-skip-permissions`: rejected because `run_dir` is per-run and `AgentInstallation.extra_args` was serialized to `KoanConfig` on disk, so run-specific paths could not persist there. The spawn-time helper read `task["run_dir"]` and `task["project_dir"]`, both already populated by every spawn site (`koan/driver.py` for the orchestrator, scout and executor spawners in `koan/web/mcp_endpoint.py`). Leon also removed the `"claude"` entry from `_YOLO_ARGS` in `koan/web/app.py` in the same change, making the `--yolo` flag a no-op for Claude while leaving codex and gemini yolo entries unchanged. diff --git a/koan/subagent.py b/koan/subagent.py index c3bffcb..24aa925 100644 --- a/koan/subagent.py +++ b/koan/subagent.py @@ -110,6 +110,35 @@ def _emit_exploration_tool_completion( } +def _claude_post_build_args(role: str, run_dir: str, project_dir: str) -> list[str]: + """Compose claude-only post-build args: tool whitelist, slash-command disable, + strict MCP config, additional directories, and permission mode. + + Returns a list of argv entries to append to a claude command. Pure function -- + no I/O, no globals beyond the CLAUDE_TOOL_WHITELISTS module constant. + + project_dir is listed before run_dir so the project is searched first. + Empty dir strings are skipped to avoid passing --add-dir "" to the CLI. + """ + args: list[str] = [] + whitelist = CLAUDE_TOOL_WHITELISTS.get(role) + if whitelist is not None: + args.extend(["--tools", whitelist]) + args.append("--disable-slash-commands") + args.append("--strict-mcp-config") + # Add project and run directories so the CLI can read/edit files in both + # locations without prompting; acceptEdits gates writes at the tool level. + if project_dir: + args.extend(["--add-dir", project_dir]) + if run_dir: + args.extend(["--add-dir", run_dir]) + # acceptEdits is safe for all roles: the CLAUDE_TOOL_WHITELISTS already + # restrict which roles receive Write/Edit in their tool vocabulary, so + # scouts cannot write even though the permission mode is permissive. + args.extend(["--permission-mode", "acceptEdits"]) + return args + + def _now_iso() -> str: from datetime import datetime, timezone return datetime.now(timezone.utc).isoformat() @@ -280,14 +309,14 @@ async def spawn_subagent(task: dict, app_state: AppState, runner: Runner | None del app_state.agents[agent_id] return SubagentResult(exit_code=1) - # Claude-specific tool restriction: append --tools whitelist, disable skills, - # and isolate MCP sources so the model only sees tools it actually needs. + # Claude-specific post-build: tool whitelist, slash-command disable, + # strict MCP config, additional working directories, and permission mode. if runner.name == "claude": - whitelist = CLAUDE_TOOL_WHITELISTS.get(role) - if whitelist is not None: - cmd.extend(["--tools", whitelist]) - cmd.append("--disable-slash-commands") - cmd.append("--strict-mcp-config") + cmd.extend(_claude_post_build_args( + role=role, + run_dir=task.get("run_dir", ""), + project_dir=task.get("project_dir", ""), + )) # Emit agent_spawned only after build_command succeeds -- process is about to start store.push_event("agent_spawned", build_agent_spawned(agent), agent_id=agent_id) diff --git a/koan/web/app.py b/koan/web/app.py index 15ebdba..13f44e3 100644 --- a/koan/web/app.py +++ b/koan/web/app.py @@ -510,9 +510,10 @@ async def _refresh_probe_state(st: AppState, broadcast: bool = True) -> None: st.probe_results = await probe_all_runners() st.builtin_profiles = compute_builtin_profiles(st.probe_results) - # --yolo: per-runner permission-skipping flags for default installations + # --yolo: per-runner permission-skipping flags for default installations. + # Claude is excluded: new default installations receive --permission-mode + # acceptEdits unconditionally via _claude_post_build_args at spawn time. _YOLO_ARGS: dict[str, list[str]] = { - "claude": ["--dangerously-skip-permissions"], "codex": ["--dangerously-bypass-approvals-and-sandbox"], "gemini": ["--yolo"], } diff --git a/tests/test_subagent.py b/tests/test_subagent.py index a01bc81..887e1e2 100644 --- a/tests/test_subagent.py +++ b/tests/test_subagent.py @@ -656,3 +656,79 @@ async def test_missing_binary_returns_controlled_failure(self, tmp_path): diag_events = [json.loads(l) for l in lines if "runner_diagnostic" in l] assert len(diag_events) >= 1 assert diag_events[0]["code"] == "binary_not_found" + + +# -- _claude_post_build_args -------------------------------------------------- + +class TestClaudePostBuildArgs: + """Unit tests for the pure _claude_post_build_args helper. + + The helper composes claude-only argv entries without I/O. Tests exercise + the full whitelist/dir/permission_mode combinations directly. + """ + + from koan.subagent import CLAUDE_TOOL_WHITELISTS as _WHITELISTS + + def test_orchestrator_full_args(self): + from koan.subagent import _claude_post_build_args, CLAUDE_TOOL_WHITELISTS + args = _claude_post_build_args("orchestrator", "/run", "/proj") + assert "--tools" in args + tools_idx = args.index("--tools") + assert args[tools_idx + 1] == CLAUDE_TOOL_WHITELISTS["orchestrator"] + assert "--disable-slash-commands" in args + assert "--strict-mcp-config" in args + assert "--add-dir" in args + # Both dirs present + add_dir_indices = [i for i, a in enumerate(args) if a == "--add-dir"] + add_dirs = [args[i + 1] for i in add_dir_indices] + assert "/proj" in add_dirs + assert "/run" in add_dirs + assert "--permission-mode" in args + pm_idx = args.index("--permission-mode") + assert args[pm_idx + 1] == "acceptEdits" + + def test_executor_gets_executor_whitelist(self): + from koan.subagent import _claude_post_build_args, CLAUDE_TOOL_WHITELISTS + args = _claude_post_build_args("executor", "/run", "/proj") + tools_idx = args.index("--tools") + assert args[tools_idx + 1] == CLAUDE_TOOL_WHITELISTS["executor"] + + def test_scout_gets_scout_whitelist(self): + from koan.subagent import _claude_post_build_args, CLAUDE_TOOL_WHITELISTS + args = _claude_post_build_args("scout", "/run", "/proj") + tools_idx = args.index("--tools") + assert args[tools_idx + 1] == CLAUDE_TOOL_WHITELISTS["scout"] + + def test_unknown_role_omits_tools_flag(self): + from koan.subagent import _claude_post_build_args + args = _claude_post_build_args("bogus", "/run", "/proj") + assert "--tools" not in args + + def test_empty_run_dir_skipped(self): + from koan.subagent import _claude_post_build_args + args = _claude_post_build_args("orchestrator", "", "/proj") + add_dir_indices = [i for i, a in enumerate(args) if a == "--add-dir"] + add_dirs = [args[i + 1] for i in add_dir_indices] + assert "/proj" in add_dirs + assert "" not in add_dirs + + def test_empty_project_dir_skipped(self): + from koan.subagent import _claude_post_build_args + args = _claude_post_build_args("orchestrator", "/run", "") + add_dir_indices = [i for i, a in enumerate(args) if a == "--add-dir"] + add_dirs = [args[i + 1] for i in add_dir_indices] + assert "/run" in add_dirs + assert "" not in add_dirs + + def test_both_dirs_empty(self): + from koan.subagent import _claude_post_build_args + args = _claude_post_build_args("orchestrator", "", "") + assert "--add-dir" not in args + + def test_permission_mode_always_present(self): + from koan.subagent import _claude_post_build_args + # Even with empty dirs and unknown role, permission mode is always set. + args = _claude_post_build_args("bogus", "", "") + assert "--permission-mode" in args + pm_idx = args.index("--permission-mode") + assert args[pm_idx + 1] == "acceptEdits" From 4e4415e0eaef9431e03a83cb5cf2bf6b13142493 Mon Sep 17 00:00:00 2001 From: Leon Mergen <leon@solatis.com> Date: Sun, 19 Apr 2026 14:14:09 +0700 Subject: [PATCH 412/412] docs: rewrite README around workflows and memory --- README.md | 187 +++++++++++++++++++----------------------------------- 1 file changed, 67 insertions(+), 120 deletions(-) diff --git a/README.md b/README.md index 76bf366..eb4fde4 100644 --- a/README.md +++ b/README.md @@ -1,134 +1,81 @@ # Koan -Koan is a workflow system for coding tasks. A single Python process hosts a web -dashboard and MCP tool endpoint; the user selects a workflow type, describes a -task, and the system runs a sequence of LLM subagents to plan and implement it. +Koan runs opinionated multi-turn workflows for LLM-assisted engineering. A local Python process hosts a web dashboard and an MCP endpoint; subagents are invocations of the vendor CLIs (`claude`, `codex`, or `gemini`) that connect back over HTTP MCP and advance through a fixed sequence of phases under user direction. Decisions are written to markdown artifacts during the run, and a per-project memory is carried across runs. -## Setup +Koan invokes the vendor CLIs as subprocesses and uses whatever authentication they already have on your machine. It does not call provider APIs directly, does not touch OAuth credentials, and does not proxy traffic, so it runs under your existing CLI subscription and within each CLI's terms of service. + +Koan is alpha. Interfaces, phase names, state files, and the memory schema will change without migration. + +## The Problem + +Long-lived LLM-assisted projects accumulate what I call knowledge debt. The developer no longer knows what is in the code, and the LLM never knew to begin with. Utilities get reimplemented, conventions diverge, and architecture drifts. + +LLMs are good at retrieval, synthesis, and presentation. They are bad at reasoning under uncertainty and at noticing drift. Larger context windows do not help -- attention is finite and uneven regardless of window size. What helps is giving the model a narrower slice of the right information at each step, and writing the decisions down so the next run does not re-derive them. + +## What It Does + +### Workflows + +A workflow is a fixed sequence of phases with narrow roles. The plan workflow runs intake, plan-spec, plan-review, execute. The orchestrator is a long-lived LLM process that advances by calling typed tools; it cannot skip phases or improvise structure. Each phase ends with a summary and a pause for user direction. + +### Decision capture + +Agents write markdown artifacts during the run: landscape.md, plan.md, scout findings, review notes. These are the durable record of what was considered and why. + +### Memory + +A per-project memory lives under `.koan/memory/`. Each entry is a short markdown file with YAML frontmatter, typed as decision, context, lesson, or procedure. Entries are proposed by the orchestrator at the end of a workflow and approved by the user before being committed. + +Three read modes are exposed to agents: + +- `status`: a broad project summary, injected at workflow start +- `query`: hybrid semantic + keyword retrieval +- `reflect`: the agent poses a question and receives a synthesized briefing drawn from multiple entries + +Phase entry also retrieves a contextual slice of memory, scoped to the role and phase. + +### Machine-readable code + +Function docstrings are written for LLM consumption. They include usage examples and explicit "use when..." triggers, so an agent reading the docstring can decide whether the function applies without reading the body. + +### Docs in code + +Architecture decisions and invariants live next to the code they constrain. Workflows read and update these during execution rather than deferring to a cleanup pass. + +### Conventions + +Project conventions are declared, not inferred. Agents check against them during review. + +## Quick Start ```bash uv sync uv run koan ``` -## How it works +Open the dashboard, select a workflow, and describe the task. -At startup, the user selects a workflow type and describes the task. Koan spawns -a long-lived orchestrator LLM process that runs the entire workflow via MCP tool -calls. At each phase boundary, the orchestrator pauses, summarizes progress, and -asks the user where to go next. +## How a Run Looks -### Plan workflow +The plan workflow phases: -``` -intake — explore codebase, ask clarifying questions, write landscape.md -plan-spec — read landscape.md, write plan.md (technical implementation plan) -plan-review — read landscape.md + plan.md, evaluate quality, report findings -execute — spawn executor agent with plan.md; implements the changes -``` +- `intake`: explore the codebase, ask clarifying questions, produce landscape.md +- `plan-spec`: produce plan.md +- `plan-review`: adversarial review of plan.md against landscape.md +- `execute`: spawn an executor with plan.md -### Milestones workflow - -Stub — runs intake only, then reports the workflow is not yet fully implemented. - ---- - -A single Python process (`koan/driver.py`) runs a Starlette HTTP server that -hosts both the web dashboard and an MCP tool endpoint. Subagents are CLI -processes (`claude`, `codex`, or `gemini`) that connect to -`http://localhost:{port}/mcp?agent_id={id}` to receive step guidance and call -koan tools. The driver reads JSON state and exit codes; it never parses LLM -output. - -## Roles - -| Role | What it does | -|------|-------------| -| **orchestrator** | Runs the entire workflow in one long-lived process. Calls `koan_set_phase` to advance phases. | -| **scout** | Narrow codebase investigator. Spawned in parallel via `koan_request_scouts`. Writes `findings.md`. | -| **executor** | Reads artifacts and instructions from `task.json`, implements code changes in one pass. | - -## Web Dashboard - -Koan serves a local web dashboard at `http://localhost:{port}` during pipeline -execution. The dashboard provides: - -- **Activity feed** -- real-time tool calls, scout dispatches, thinking traces -- **Agent monitor** -- status, token counts, and recent actions for each - running subagent -- **Artifacts panel** -- markdown files written during the run (landscape.md, plan.md) -- **User interaction** -- question forms (clarifications), chat for phase-boundary direction - -The dashboard uses Server-Sent Events for real-time updates. SSE events are -pushed directly from in-process state transitions and tool handlers. - -## Key Concepts - -**Step-first workflow.** Every subagent's first action is calling -`koan_complete_step`. This forces a tool call before any text output. Task -instructions are delivered as the return value of that first call. - -**Directory-as-contract.** Each subagent gets a directory with `task.json` -(input), `state.json` (live projection), and `events.jsonl` (audit log). The -spawn command carries the directory path and the MCP endpoint URL. - -**Default-deny permissions.** Every tool call passes through a permission -fence. Roles cannot use tools outside their scope. Planning roles can only -write inside the run directory. - -**Driver determinism.** The driver reads JSON and exit codes, validates phase -transitions against the active workflow, and spawns subagents. It never parses -markdown or adapts to LLM behavior. Routing decisions are deterministic. - -**HTTP MCP.** Subagents connect to the driver's MCP endpoint at -`/mcp?agent_id={id}`. Tool calls arrive as HTTP requests; the driver looks up -the agent's state by `agent_id` in an in-process registry and handles the call -directly. No separate MCP server processes, no file-based IPC polling. - -**Workflow-based phase transitions.** Phase transitions are validated against -the active workflow's `available_phases`. Any phase in the workflow is reachable -from any other. Suggested transitions guide the orchestrator's boundary response -but do not restrict the user. - -## Configuration - -Model tiers and scout concurrency are configured via the web UI at pipeline -start, then saved to `~/.koan/config.json`: - -```json -{ - "agentInstallations": [ - { "alias": "claude-sonnet", "runnerType": "claude", "binary": "claude", "extraArgs": [] } - ], - "profiles": [ - { - "name": "balanced", - "tiers": { - "strong": { "runnerType": "claude", "model": "claude-sonnet-4-5", "thinking": "disabled" }, - "standard": { "runnerType": "claude", "model": "claude-sonnet-4-5", "thinking": "disabled" }, - "cheap": { "runnerType": "claude", "model": "claude-haiku-4-5", "thinking": "disabled" } - } - } - ], - "activeProfile": "balanced", - "scoutConcurrency": 8 -} -``` +Memory is consulted at intake and at each phase boundary. At the end of the run, curation proposes memory additions for user approval. + +## Design Notes + +A single Python process (`koan/driver.py`) hosts the dashboard and the MCP endpoint. Subagents are CLI processes speaking HTTP MCP. The driver validates phase transitions, enforces a default-deny permission fence, and maintains run state. It does not parse LLM output. Agents write markdown; the driver writes JSON. + +Three roles: + +- `orchestrator`: runs the workflow and delegates +- `scout`: parallel, read-only investigator +- `executor`: implements from an approved plan + +## Status -Roles map to tiers: orchestrator → strong, executor → standard, scout → cheap. - -## Architecture Documentation - -- **[docs/architecture.md](./docs/architecture.md)** -- core invariants, - design principles, workflow system, pitfalls -- **[docs/subagents.md](./docs/subagents.md)** -- spawn lifecycle, step-first - workflow, permissions, model tiers -- **[docs/ipc.md](./docs/ipc.md)** -- HTTP MCP inter-process communication, - blocking tool calls -- **[docs/state.md](./docs/state.md)** -- run state, driver state, routing -- **[docs/intake-loop.md](./docs/intake-loop.md)** -- two-step intake design, - prompt engineering principles -- **[docs/projections.md](./docs/projections.md)** -- versioned event log, - fold function, SSE protocol -- **[docs/token-streaming.md](./docs/token-streaming.md)** -- runner stdout - parsing, SSE delta path +Alpha. I use it daily across several projects. Interfaces will change.